From ddf4f895cd0e41fb9d6110c7ea2cbd4ddc860029 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 10 Nov 2026 19:42:36 -0600 Subject: [PATCH] fix(rails): close review guidance and coverage gaps (#1873) --- packages/bus/src/refusals.mjs | 83 ++++++++++++++++++++++++++- packages/bus/tests/rails.test.mjs | 33 ++++++++++- packages/harness/tests/rails.test.mjs | 8 +++ packages/organization/src/rails.mjs | 5 +- 4 files changed, 122 insertions(+), 7 deletions(-) diff --git a/packages/bus/src/refusals.mjs b/packages/bus/src/refusals.mjs index c93290b4d..0844f1c5f 100644 --- a/packages/bus/src/refusals.mjs +++ b/packages/bus/src/refusals.mjs @@ -49,9 +49,14 @@ group( "Ask the owner to inspect the scoped access and binding state through the supported access controls; do not supply credentials in a call or widen your own grants." ); group( - "confirm-required outcome-unknown outcome-unknown-revoked revision-conflict revision-conflict-revoked", + "outcome-unknown outcome-unknown-revoked revision-conflict revision-conflict-revoked", "R2/R3: current revision and verified effect", - "Read the latest status, revision and receipts before retrying. Obtain the required confirmation through the supported human path." + "Read the latest status, revision and receipts before retrying. Verify whether an uncertain effect already happened, and use the current revision for any new attempt." +); +group( + "confirm-required", + "R2/R3: explicit confirmation of the current operation", + "Read the current status and obtain the required confirmation through the supported human path." ); group( "decision-closed decision-consumed decision-mismatch decision-not-approved decision-not-eligible decision-not-found decision-not-held decision-stale supersede-refused", @@ -79,10 +84,15 @@ group( "Read the permitted configuration/status and ask the owner or configured chief to repair it through the supported path. Do not edit policy to bypass the refusal." ); group( - "field-writer task-already-archived task-archived task-conflict task-create-conflict task-create-uncertain task-not-archived task-not-found task-position-full task-project-refused task-required task-scope-required task-subject-required", + "field-writer task-already-archived task-archived task-conflict task-create-conflict task-create-uncertain task-not-archived task-not-found task-position-full task-project-refused task-scope-required task-subject-required", "Role task ownership, allowed fields and current task state", "Read the current task and assigned role. Use the permitted task operation with current evidence; ask the PM for scope or assignment changes through the decision path." ); +group( + "task-required", + "Role decisions: a blocking decision belongs to a task", + "Supply the task_ref for this work, or raise with blocking false when there is no task." +); group( "fork-foreign gitea-admin-unavailable gitea-failed gitea-not-configured gitea-not-declared host-busy host-changed host-creative-role host-enrolled host-failed host-in-use host-key-mismatch host-line-left host-not-configured host-not-declared host-not-enrolled host-not-granted host-not-ready host-remove-failed host-unknown publish-busy publish-unknown", "Role access: declared service, host or remote and verified outcome", @@ -158,6 +168,73 @@ group( "R3/role tools: bounded protocol and available capacity", "Check the tool schema and narrow oversized requests. For a timeout, inspect status and receipts before retrying; never assume an uncertain operation did not happen." ); +// Finite error vocabularies forwarded by the project's, library's and request's +// typed adapters are part of the same table, not an unhelpful unknown-code path. +group( + "project-busy library-sync-busy", + "Role storage: exclusive write or sync already in progress", + "Wait for the current operation to finish, read its status, then retry once the lock is clear." +); +group( + "stale-base library-accept-stale", + "R2/R3: current file or served revision", + "Read the latest file or library status and its current revision. Reconcile the intended change before retrying with that base; never overwrite a newer change blindly." +); +group( + "citation-cross-universe citation-invalid citation-missing citation-unavailable citation-unfetched citations-over-limit playground-cited-as-canon reply-invalid", + "Role replies: validated citations, provenance and scope", + "Use permitted library, spec or web reads and supply a valid reply with current citations in the allowed universe and scope. Narrow oversized citation lists; never invent provenance." +); +group( + "invalid-request-admission invalid-request-effect invalid-request-event invalid-request-plan invalid-request-projects artifact-path-invalid artifact-type-refused", + "R3: typed request plan, delivery and evidence schema", + "Check the current request's tool schema and correct the plan, artifact path or evidence. Delivery requires the supported self-contained HTML artifact and matching verification evidence." +); +group( + "prd-admission-revoked prd-author-invalid prd-candidate-invalid prd-candidate-required prd-candidate-size prd-candidate-stale prd-requirement-invalid", + "Role PRD workflow: current candidate, authors and admission", + "Read the current request, candidate, requirements, mode and approval. Ask the PM to correct or submit the current candidate through the supported workflow; never approve your own authorship." +); +group( + "request-question-open request-question-closed request-question-mismatch request-phase-refused request-attachment-mismatch request-delivery-required request-document-refused", + "Role request workflow: current phase, question and selected attachment", + "Read intake_status and follow its current question, wait or delivery step. A pending question needs its answer before another question; use only the operation and attachment valid for the current phase." +); +group( + "request-effect-conflict request-effect-unprepared request-mode-revision-conflict request-operation-conflict request-plan-binding-refused request-plan-path-collision request-plan-path-refused request-project-collision", + "R2/R3: current request revision and bound operation", + "Read the current request status, plan and operation receipts. Recover an existing operation before retrying; use a new operation ID only for a new intended operation, and never bypass a path or project collision." +); +group( + "request-notification-unavailable request-services-unavailable library-credential-missing library-human-missing library-mapping-invalid library-problem-code library-remote-invalid library-state-invalid library-diverged library-accept-invalid", + "R1/R3: owner-configured service, mapping and accepted library state", + "Read the supported service or library status and ask the owner to repair the missing binding, mapping or accepted state. Check existing operation receipts before retrying an uncertain effect." +); +group( + "library-commit library-git library-push-failed project-commit-uncertain project-init-cleanup", + "R2/R3: verified repository effect and recovery", + "Read current repository status and receipts to determine what already happened. Report an uncertain commit, push or cleanup to the owner before any new write; do not retry an uncertain effect blindly." +); +group( + "project-author project-dirty project-git project-id project-invalid project-no-commit project-not-declared project-not-empty project-path project-read-commit project-read-content project-read-missing project-read-path project-record-path project-records-conflict project-records-missing project-remote project-repository tester-project-area", + "Role project scope: declared repository, clean state and allowed paths", + "Read the permitted project status and file metadata. Correct the declared project or allowed path when possible; ask the owner to repair repository state or identity. Preserve existing changes and never bypass repository or path checks." +); +group( + "project-record-unchanged", + "R2: no new record effect for unchanged content", + "Read the current record and its existing commit receipt. If it already matches the intended content, use that evidence instead of retrying the same write." +); +group( + "library-write-story-path library-revert-not-agent", + "Role library writes: supporting paths and permitted agent-owned commits", + "Use only the supporting paths and agent-owned commit reversals permitted by the library tool. Preserve story and canon files; ask the owner when the requested edit is outside that scope." +); +group( + "query-argument-invalid query-chapter-ambiguous query-item-too-large query-universe-unknown", + "Role library reads: known universe, unambiguous selection and bounded result", + "Read the permitted library index, choose a known universe and an unambiguous book or chapter, and narrow the query or requested range before retrying." +); export const REFUSALS = Object.freeze(Object.fromEntries(entries)); const UNKNOWN = Object.freeze({ rail: "R3: fail closed", nextStep: "Report the refusal code to the responsible owner and inspect supported status; do not bypass the refusal." }); export const refusalGuidance = code => Object.hasOwn(REFUSALS, code) ? REFUSALS[code] : UNKNOWN; diff --git a/packages/bus/tests/rails.test.mjs b/packages/bus/tests/rails.test.mjs index b28333048..f416c66be 100644 --- a/packages/bus/tests/rails.test.mjs +++ b/packages/bus/tests/rails.test.mjs @@ -1,6 +1,6 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs'; +import { mkdtempSync, rmSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'; import { join } from 'node:path'; import { tmpdir } from 'node:os'; import { connect } from 'node:net'; @@ -14,6 +14,7 @@ import { Client } from '../src/client.mjs'; import { resolveInstance, validateBusinessDocument } from '../../organization/src/index.mjs'; import { businessDoc, REPO_ROLES, systemFor } from '../../organization/tests/helpers.mjs'; import { railsText } from '../../organization/src/rails.mjs'; +import { GUARD_CODES } from '../../library/src/reply-protocol.mjs'; const SECRET = 'sk-test-NOT-A-SECRET-1234'; function fixture(t) { const root = mkdtempSync(join(tmpdir(), 'rails-')); @@ -80,6 +81,16 @@ test('cross-role refusal envelope names its rail and next step without changing const cross = await raw(path, { cap: f.cap, verb: 'decision.resolve', args: { id: decision.id, choice: 'yes' } }); assert.equal(cross.error, 'not-resolver'); assert.match(cross.rail, /resolve right/); assert.match(cross.nextStep, /routed resolver/); assert.equal(f.store.get('SELECT count(*) n FROM decision_events WHERE decision=?', decision.id).n, 0); + // Exercise an actual cross-role action without its required decision, not just resolve. + const live = busOrganization(f.business, f.resolved); + live.roles.coder.authority.crossRole.push('role.end'); + f.broker.reloadBusiness('acme', live); + const decisions = f.store.get('SELECT count(*) n FROM decisions').n; + const required = await raw(path, { cap: f.cap, verb: 'role.revoke', args: { role: 'reviewer', reason: SECRET } }); + assert.equal(required.ok, false); assert.equal(required.error, 'decision-required'); + assert.deepEqual({ rail: required.rail, nextStep: required.nextStep }, REFUSALS['decision-required']); + assert.ok(!JSON.stringify(required).includes(SECRET)); + assert.equal(f.store.get('SELECT count(*) n FROM decisions').n, decisions); }); test('every literal fail branch in broker has static guidance; guidance never contains payload values', () => { @@ -105,7 +116,7 @@ test('every literal fail branch in broker has static guidance; guidance never co assert.equal(depth, 0, 'balanced fail call'); } // Finite delegated fail(code) sources must be covered as well as literal branches. - for (const code of [...PROXY_PAGE_CODES, 'remote-host-mismatch', 'remote-not-fork', + for (const code of [...PROXY_PAGE_CODES, ...GUARD_CODES, 'project-busy', 'remote-host-mismatch', 'remote-not-fork', 'processing-control-unsafe', 'processing-uninitialized', 'processing-generation-changed']) { assert.ok(Object.hasOwn(REFUSALS, code), code); } @@ -116,3 +127,21 @@ test('every literal fail branch in broker has static guidance; guidance never co } assert.deepEqual(refusalGuidance(SECRET), refusalGuidance('unknown-external-code')); }); + +test('finite forwarded project, library and request errors have static next steps', () => { + const modules = [ + ...['index', 'git', 'paths'].map(name => new URL(`../../project/src/${name}.mjs`, import.meta.url)), + ...readdirSync(new URL('../../library/src/', import.meta.url)).filter(f => f.endsWith('.mjs')) + .map(name => new URL(`../../library/src/${name}`, import.meta.url)), + ...['request-store', 'request-lifecycle'].map(name => new URL(`../src/${name}.mjs`, import.meta.url)), + ]; + for (const file of modules) { + const source = readFileSync(file, 'utf8'); + for (const match of source.matchAll(/\b(?:new\s+(?:ProjectError|LibraryError|RequestError|GuardError)|raise|refuse|fail)\s*\(\s*['"]([a-z][a-z0-9-]*)['"]/g)) { + assert.ok(Object.hasOwn(REFUSALS, match[1]), `${file.pathname}: ${match[1]}`); + } + } + assert.doesNotMatch(REFUSALS['outcome-unknown'].nextStep, /confirmation|human/); + assert.doesNotMatch(REFUSALS['revision-conflict'].nextStep, /confirmation|human/); + assert.match(REFUSALS['task-required'].nextStep, /task_ref.*blocking false/); +}); diff --git a/packages/harness/tests/rails.test.mjs b/packages/harness/tests/rails.test.mjs index bac6f586c..67d521048 100644 --- a/packages/harness/tests/rails.test.mjs +++ b/packages/harness/tests/rails.test.mjs @@ -52,3 +52,11 @@ test('fixed domains, arbiter self-raises and hard waits describe existing routes { action: 'policy.change', routes: [{ domain: 'delivery', to: 'pm' }] }, ]); }); + +test('hire and fire are unavailable to a chief that is not the configured launcher', t => { + const { rails } = resolvedFor(t, 'chief', doc => { delete doc.launch; }); + for (const action of ['role.hire', 'role.fire']) { + assert.deepEqual(rails.actions.find(a => a.action === action).routes, [{ to: 'unavailable' }]); + } + assert.match(railsText(rails), /role.hire: unavailable here; only the configured chief can hire or fire/); +}); diff --git a/packages/organization/src/rails.mjs b/packages/organization/src/rails.mjs index 3ef68619a..db7cfd409 100644 --- a/packages/organization/src/rails.mjs +++ b/packages/organization/src/rails.mjs @@ -13,9 +13,10 @@ export function ownRails({ instance, authority, network, credentials = [], messa const actions = []; for (const [kind, held] of Object.entries(authority ?? {})) { for (const action of held) { + const chiefOnly = ['role.hire', 'role.fire'].includes(action) && launcher !== instance; const hard = GATED_ONLY.includes(action) || (action === 'role.launch' && launcher !== instance); const domains = DOMAINS[action] ? [DOMAINS[action]] : ['delivery', 'technical']; - const routes = hard ? [{ to: 'human' }] : kind === 'withinRole' ? [{ to: 'alone' }] + const routes = chiefOnly ? [{ to: 'unavailable' }] : hard ? [{ to: 'human' }] : kind === 'withinRole' ? [{ to: 'alone' }] : domains.map(domain => ({ domain, to: arbiters[domain] === instance ? 'human' : arbiters[domain] ?? 'unconfigured' })); actions.push({ action, routes }); } @@ -36,7 +37,7 @@ export function ownRails({ instance, authority, network, credentials = [], messa export function railsText(rails) { const lines = ['## Your rails', '', 'These are your resolved rails. Call my_rails for the current rails after a narrowing.']; for (const { action, routes } of rails.actions) { - const route = routes.map(({ domain, to }) => `${domain ? `${domain}${domain === 'delivery' && routes.length > 1 ? ' (default)' : ''}: ` : ''}${to === 'human' ? 'a person' : to === 'alone' ? 'alone' : to === 'unconfigured' ? 'unconfigured; report missing arbiter' : `arbiter instance ${JSON.stringify(to)}`}`).join('; '); + const route = routes.map(({ domain, to }) => `${domain ? `${domain}${domain === 'delivery' && routes.length > 1 ? ' (default)' : ''}: ` : ''}${to === 'human' ? 'a person' : to === 'alone' ? 'alone' : to === 'unavailable' ? 'unavailable here; only the configured chief can hire or fire' : to === 'unconfigured' ? 'unconfigured; report missing arbiter' : `arbiter instance ${JSON.stringify(to)}`}`).join('; '); lines.push(`- ${action}: ${route}.`); } if (!rails.actions.length) lines.push('- Held actions: none.');