@starci/skills 1.1.0

package/operators/backend-source-apply/self-test.mjs

@@ -0,0 +1,257 @@
+// Proves validate.mjs on a synthetic session branch: one conforming implementation of a frozen
+// contract committed once on the session branch, with its change record, one conformance file per
+// facet and one proof file per proof kind, one dry run that plans the same write set and commits,
+// measures and writes nothing, one branch blocked on a terminate code, and one mutation per law,
+// each of which must fail with a line that names the defect.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { validateBackendStep } from './validate.mjs';
+
+const BASE = 'f'.repeat(40);
+const COMMIT = 'a1b2'.repeat(10);
+const BRANCH = 'session/s-test';
+const hash = (c) => `sha256:${c.repeat(64)}`;
+const CONTRACT_FP = hash('a');
+const OP = 'enrol-course';
+const WRITER = 'src/features/api/core/graphql/mutations/enrol-course.handler.ts';
+const SPEC = 'src/features/api/core/graphql/mutations/enrol-course.handler.spec.ts';
+const FACETS = ['transport', 'writer', 'transaction', 'idempotency', 'exception-identity', 'authorization'];
+const PROOF_KINDS = ['unit', 'integration'];
+
+const operation = (overrides = {}) => ({
+  operationId: OP, name: 'enrolCourse', transport: 'graphql-mutation', writerRef: WRITER,
+  storeRefs: ['enrollments'], transactionBoundary: 'single-transaction', idempotencyKind: 'request-token',
+  migrationRefs: [], authorityDecisionIds: ['BA-1'], facets: FACETS, proofKinds: PROOF_KINDS,
+  ...overrides,
+});
+const CHANGES = [
+  { path: WRITER, change: 'added', operationId: OP, beforeHash: null, afterHash: hash('1') },
+  { path: SPEC, change: 'added', operationId: OP, beforeHash: null, afterHash: hash('2') },
+];
+const DRY_CHANGES = CHANGES.map((c) => ({ ...c, afterHash: null }));
+const mutationsJson = ({ operations = [operation()], changes = CHANGES, commit = COMMIT, base = BASE, branch = BRANCH, mode = 'apply' } = {}) => ({
+  mode, contractFingerprint: CONTRACT_FP, base, branch, commit, operations, changes,
+});
+const conformanceRecord = (facet, overrides = {}) => ({ operationId: OP, facet, verdict: 'conforms', evidenceRef: `${SPEC}:40`, statement: `the ${facet} of the operation matches the contract`, contractFingerprint: CONTRACT_FP, ...overrides });
+const proofRecord = (proofKind, overrides = {}) => ({ operationId: OP, proofKind, commandRef: `npm run test:${proofKind}`, exitCode: 0, result: 'passed', output: `${proofKind} suite: 12 passed`, statement: `the ${proofKind} proof ran and passed`, contractFingerprint: CONTRACT_FP, ...overrides });
+const conformancePath = (operationId, facet) => `response/data/conformance/${operationId}.${facet}.json`;
+const proofPath = (operationId, proofKind) => `response/data/proofs/${operationId}.${proofKind}.json`;
+
+function responseMd({ operations = null, changes = null, findings = null, contractFingerprint = CONTRACT_FP, commit = COMMIT, base = BASE, branch = BRANCH, mode = 'apply' } = {}) {
+  const operationRows = (operations ?? [[OP, 'graphql-mutation', WRITER, 'single-transaction', 'request-token', 'BA-1']]).map((r) => `| \`${r[0]}\` | ${r[1]} | \`${r[2]}\` | ${r[3]} | ${r[4]} | ${r[5]} |`).join('\n');
+  const changeRows = (changes ?? [[WRITER, 'added', OP, '—', hash('1')], [SPEC, 'added', OP, '—', hash('2')]]).map((r) => `| \`${r[0]}\` | ${r[1]} | \`${r[2]}\` | ${r[3]} | ${r[4]} |`).join('\n');
+  const findingRows = (findings ?? [['PATTERN_BOUND', OP, WRITER, 'the mutation handler mirrors the published command family']]).map(([code, op, file, statement]) => `| \`${code}\` | ${op === null ? '—' : `\`${op}\``} | ${file === null ? '—' : `\`${file}\``} | ${statement} |`).join('\n');
+  return `# backend-source-application — enrol-course
+
+The enrolment mutation, filled inside the frozen contract and measured on every declared facet.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Outcome | one enrolment mutation behind the paid access promise |
+| Feature | paid-access |
+| Mode | ${mode} |
+| Contract fingerprint | ${contractFingerprint} |
+| Base | ${base} |
+| Branch | ${branch} |
+| Commit | ${commit} |
+
+## Operations
+
+| Operation | Transport | Writer | Transaction | Idempotency | Decisions |
+| --- | --- | --- | --- | --- | --- |
+${operationRows}
+
+## Changes
+
+| Path | Change | Operation | Before | After |
+| --- | --- | --- | --- | --- |
+${changeRows}
+
+## Findings
+
+| Code | Operation | File | Statement |
+| --- | --- | --- | --- |
+${findingRows}
+`;
+}
+
+const changesMd = ({ files = null, checkout = `\`@workspaces/be\` at \`${BASE}\` → \`${COMMIT}\` on \`${BRANCH}\`` } = {}) => {
+  const rows = (files ?? [[WRITER, 'created'], [SPEC, 'created']]).map(([p, kind, why]) => `| \`${p}\` | ${kind} | ${why ?? 'the decision this file carries'} | BE-1 |`).join('\n');
+  return `# changes — backend.source.apply step-1/parallel-1
+
+The enrolment mutation and its unit spec were written into the session branch of the routed backend
+checkout and committed once.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`backend.source.apply\` |
+| Step | \`step-1/parallel-1\` |
+| Checkout | ${checkout} |
+| Predecessor | \`step-1/parallel-2/response/response.md\` |
+
+## Files
+
+| Path | Change | Why | Claims |
+| --- | --- | --- | --- |
+${rows}
+
+## What the next step must know
+
+- Gates to run: the backend lint, type and test gates the checkout pins for these paths.
+- Surfaces to observe: the enrolment mutation of the api.
+- Not changed on purpose: the legacy checkout path, which the contract does not carry.
+`;
+};
+
+const requestJson = ({ extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'backend.source.apply', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/be', head: BASE }, { alias: '@worktrees/businesses/paid-access', head: null }, { alias: '@knowledge/patterns/be', head: null }],
+  requirements: {
+    featureId: 'paid-access', outcome: 'one enrolment mutation behind the paid access promise',
+    mutableFileRefs: [WRITER, SPEC], resume: null, ...extra,
+  },
+  inputs: { 'architecture-decision': 'step-1/parallel-2/response/response.md' }, resume: null,
+});
+function responseJson({ status = 'done', stop, fallbacks = [], fields = null, commits = [COMMIT], next = ['quality.verify'] } = {}) {
+  return {
+    schemaVersion: 9, operatorId: 'backend.source.apply', step: 1, parallel: 1, status, ...(stop ? { stop } : {}), fallbacks,
+    fields: fields ?? {
+      'backend-source-application': 'response/response.md',
+      changes: 'response/changes.md',
+      mutations: 'response/data/mutations.json',
+      conformance: FACETS.map((facet) => conformancePath(OP, facet)),
+      proof: PROOF_KINDS.map((kind) => proofPath(OP, kind)),
+    },
+    commits, next,
+  };
+}
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'backend-session-'));
+  const branch = path.join(session, 'step-1', 'parallel-1');
+  for (const d of ['request', 'response/data/conformance', 'response/data/proofs', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  mkdirSync(path.join(session, 'step-1', 'parallel-2', 'response'), { recursive: true });
+  writeFileSync(path.join(session, 'step-1', 'parallel-2', 'response', 'response.md'), '# architecture-decision — enrol-course\n');
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'backend.source.apply' }, current: '1/1', status: 'running' }));
+  for (const [name, content] of Object.entries(files)) {
+    if (content === null) continue;
+    writeFileSync(path.join(branch, name), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+  return { branch, session };
+}
+const records = (conformance = null, proofs = null) => ({
+  ...Object.fromEntries((conformance ?? FACETS.map((f) => conformanceRecord(f))).map((r) => [conformancePath(r.operationId, r.facet), r])),
+  ...Object.fromEntries((proofs ?? PROOF_KINDS.map((k) => proofRecord(k))).map((r) => [proofPath(r.operationId, r.proofKind), r])),
+});
+const baseline = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/changes.md': changesMd(),
+  'response/data/mutations.json': mutationsJson(),
+  ...records(),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateBackendStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateBackendStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.ok(errors.some((e) => e.includes(needle)), `${label}: expected an error containing "${needle}", got:\n${errors.join('\n') || '(none)'}`);
+}
+// A dry run: the same plan, with nothing committed, nothing measured and nothing moved in the tree.
+const dryFiles = () => ({
+  'request/request.json': requestJson({ extra: { mode: 'dry' } }),
+  'response/response.json': responseJson({
+    commits: [],
+    fields: { 'backend-source-application': 'response/response.md', changes: 'response/changes.md', mutations: 'response/data/mutations.json' },
+  }),
+  'response/response.md': responseMd({ mode: 'dry', commit: '—', changes: [[WRITER, 'added', OP, '—', '—'], [SPEC, 'added', OP, '—', '—']] }),
+  'response/changes.md': changesMd({
+    files: [[WRITER, 'unchanged', 'the mutation handler this run would add'], [SPEC, 'unchanged', 'the unit spec this run would add']],
+    checkout: `\`@workspaces/be\` at \`${BASE}\` on \`${BRANCH}\`, nothing written`,
+  }),
+  'response/data/mutations.json': mutationsJson({ mode: 'dry', commit: null, changes: DRY_CHANGES }),
+});
+const blockedFiles = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'CONTRACT_WIDENED', fields: {}, commits: [], next: [] }),
+});
+// One mutation of the frozen contract, with the receipt and the records that must follow it.
+const withOperation = (patch) => {
+  const op = operation(patch);
+  return {
+    ...baseline(),
+    'response/data/mutations.json': mutationsJson({ operations: [op] }),
+    ...records(op.facets.map((f) => conformanceRecord(f)), op.proofKinds.map((k) => proofRecord(k))),
+    'response/response.json': responseJson({
+      fields: {
+        'backend-source-application': 'response/response.md', changes: 'response/changes.md', mutations: 'response/data/mutations.json',
+        conformance: op.facets.map((f) => conformancePath(OP, f)), proof: op.proofKinds.map((k) => proofPath(OP, k)),
+      },
+    }),
+    'response/response.md': responseMd({ operations: [[OP, op.transport, op.writerRef, op.transactionBoundary, op.idempotencyKind, op.authorityDecisionIds.join(', ')]] }),
+  };
+};
+
+await expectValid(baseline(), 'one operation filled inside the frozen contract and committed once');
+await expectValid(dryFiles(), 'a dry run that plans the write set and commits, measures and writes nothing');
+await expectValid(blockedFiles(), 'blocked on a contract the outcome would widen');
+
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), stop: 'CONTRACT_WIDENED' } }, 'only a blocked response carries a stop', 'done with a stop');
+await expectError({ ...blockedFiles(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', fields: {}, commits: [], next: [] }) }, 'not a registered code', 'unknown stop code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['PROOF_UNAVAILABLE'] }) }, 'has disposition terminate under these requirements; it cannot be taken as a fallback', 'fallback on a terminate code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'PROOF_UNAVAILABLE', commits: [], next: [] }) }, 'a blocked branch cannot carry an implementation', 'blocked while reporting an implementation');
+await expectError({ ...blockedFiles(), 'response/response.json': responseJson({ status: 'blocked', stop: 'CONTRACT_WIDENED', fields: {}, next: [] }) }, 'a blocked branch commits nothing', 'blocked with a commit');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ commits: [] }) }, 'commits its whole write set once, found 0 commits', 'a done branch that never committed');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ commits: [COMMIT, hash('9').slice(7, 47)] }) }, 'commits its whole write set once, found 2 commits', 'a done branch with two commits');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ commit: 'b'.repeat(40) }) }, 'differs from response.json commits[0]', 'the mutation record names another commit');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ commit: BASE }), 'response/response.json': responseJson({ commits: [BASE] }), 'response/response.md': responseMd({ commit: BASE }), 'response/changes.md': changesMd({ checkout: `\`@workspaces/be\` at \`${BASE}\` → \`${BASE}\` on \`${BRANCH}\`` }) }, 'nothing was written on the session branch', 'a commit equal to the base');
+await expectError({ ...baseline(), 'response/changes.md': changesMd({ checkout: `\`@workspaces/be\` at \`${BASE}\` → uncommitted` }) }, 'so the next request can pin exactly what was written', 'a change record that pins no commit');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { mystery: 1 } }) }, 'requirements.mystery is not a field', 'undeclared requirement');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { outcome: '' } }) }, 'required field outcome has no value', 'missing required outcome');
+await expectError(withOperation({ writerRef: 'src/other/handler.ts' }), 'outside the mutable ceiling', 'a writer outside the mutable ceiling');
+await expectError(withOperation({ migrationRefs: ['1700000000000-AddEnrolment.ts'], facets: [...FACETS, 'migration'] }), 'ships a migration without declaring the migration-replay proof', 'a migration with no replay proof');
+await expectError(withOperation({ migrationRefs: ['1700000000000-AddEnrolment.ts'], proofKinds: [...PROOF_KINDS, 'migration-replay'] }), 'ships a migration without declaring the migration facet', 'a migration with no migration facet');
+await expectError(withOperation({ transactionBoundary: 'read-only', migrationRefs: ['m.ts'], facets: [...FACETS, 'migration'], proofKinds: [...PROOF_KINDS, 'migration-replay'] }), 'is read-only but ships a migration', 'a read-only operation shipping a migration');
+await expectError(withOperation({ transport: 'event-consumer', idempotencyKind: 'none' }), 'will apply twice on redelivery', 'an event consumer with no idempotency');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fields: { ...responseJson().fields, conformance: FACETS.slice(0, 5).map((f) => conformancePath(OP, f)) } }) }, 'the operation declares the authorization facet and no record proves it', 'a declared facet with no record');
+await expectError({ ...baseline(), [conformancePath(OP, 'writer')]: conformanceRecord('writer', { verdict: 'widened' }) }, 'reports widened writer conformance in a done branch', 'a widened facet in a done branch');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fields: { ...responseJson().fields, conformance: [...FACETS.map((f) => conformancePath(OP, f)), conformancePath(OP, 'store')] } }), [conformancePath(OP, 'store')]: conformanceRecord('store') }, 'proves undeclared facet store', 'a facet the contract never declared');
+await expectError({ ...baseline(), [conformancePath(OP, 'writer')]: conformanceRecord('transport') }, 'must be filed as response/data/conformance/enrol-course.transport.json', 'a conformance record filed under another name');
+await expectError({ ...baseline(), [conformancePath(OP, 'writer')]: conformanceRecord('writer', { contractFingerprint: hash('9') }) }, 'measured against another contract fingerprint', 'a facet measured against another contract');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fields: { ...responseJson().fields, proof: [proofPath(OP, 'unit')] } }) }, 'declares the integration proof and never ran it', 'a declared proof that never ran');
+await expectError({ ...baseline(), [proofPath(OP, 'unit')]: proofRecord('unit', { result: 'failed', exitCode: 1 }) }, 'reports a failed unit proof in a done branch', 'a failed proof in a done branch');
+await expectError({ ...baseline(), [proofPath(OP, 'unit')]: proofRecord('unit', { exitCode: 1 }) }, 'contradicts the passed verdict', 'a passing verdict over a non-zero exit code');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ changes: [{ ...CHANGES[0], change: 'modified', beforeHash: hash('1'), afterHash: hash('1') }, CHANGES[1]] }), 'response/response.md': responseMd({ changes: [[WRITER, 'modified', OP, hash('1'), hash('1')], [SPEC, 'added', OP, '—', hash('2')]] }) }, 'records a modification whose hashes are identical', 'a modification that never happened');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ changes: [{ ...CHANGES[0], beforeHash: hash('1') }, CHANGES[1]] }) }, 'is added with the wrong before hash', 'an added file carrying a before hash');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ changes: [CHANGES[0], { ...CHANGES[1], path: WRITER, afterHash: hash('2') }] }) }, 'carries more than one change record', 'one file changed twice');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ changes: [CHANGES[0], { ...CHANGES[1], operationId: 'ghost-op' }] }) }, 'names undeclared operation ghost-op', 'a change owned by no operation');
+await expectError({ ...baseline(), 'response/data/mutations.json': mutationsJson({ changes: [CHANGES[0], { ...CHANGES[1], path: 'src/other/thing.ts' }] }) }, 'lies outside the mutable ceiling', 'a change outside the ceiling');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ operations: [[OP, 'rest', WRITER, 'single-transaction', 'request-token', 'BA-1']] }) }, 'reports transport rest, the contract froze graphql-mutation', 'a transport the contract did not freeze');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ operations: [[OP, 'graphql-mutation', WRITER, 'single-transaction', 'request-token', 'BA-9']] }) }, 'cites decision BA-9, which the contract does not bind', 'an unapproved business decision');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['BUSINESS_QUESTION_RAISED', OP, null, 'the voucher rule on a foreign gateway was never decided']] }) }, 'cannot raise an unresolved business question', 'shipping with an open business question');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ contractFingerprint: hash('9') }) }, 'differs from the fingerprint the mutations were measured against', 'a receipt measured against another contract');
+await expectError({ ...baseline(), 'response/changes.md': changesMd({ files: [[WRITER, 'created']] }) }, 'which the change record omits', 'a changed file missing from the change record');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Changes', '## Change set') }, 'missing section ^## Changes$', 'response section renamed');
+await expectError({ ...baseline(), 'response/response.json': (() => { const o = responseJson(); delete o.fields.mutations; return o; })() }, 'required output mutations is not in fields', 'missing required output');
+await expectError({ ...baseline(), 'response/response.json': (() => { const o = responseJson(); delete o.fields.conformance; return o; })() }, 'required output conformance is not in fields', 'an applied branch that measured no facet');
+await expectError({ ...dryFiles(), 'response/data/mutations.json': mutationsJson({ mode: 'dry', commit: COMMIT, changes: DRY_CHANGES }) }, 'a dry run commits nothing, so commit must be null', 'a dry plan carrying a commit');
+await expectError({ ...dryFiles(), 'response/response.json': responseJson({ commits: [COMMIT], fields: { 'backend-source-application': 'response/response.md', changes: 'response/changes.md', mutations: 'response/data/mutations.json' } }) }, 'a dry run records no commit', 'a dry run that committed');
+await expectError({ ...dryFiles(), 'response/data/mutations.json': mutationsJson({ mode: 'dry', commit: null }) }, 'reports an after hash under a dry run', 'a dry plan carrying an after hash');
+await expectError({ ...dryFiles(), ...records(), 'response/response.json': responseJson({ commits: [], fields: { ...responseJson().fields } }) }, 'a dry run measures nothing', 'a dry run carrying conformance and proof records');
+await expectError({ ...dryFiles(), 'response/changes.md': changesMd({ files: [[WRITER, 'created'], [SPEC, 'created']], checkout: `\`@workspaces/be\` at \`${BASE}\` on \`${BRANCH}\`, nothing written` }) }, 'under a dry run, which leaves every path unchanged', 'a dry change record reporting a move');
+await expectError({ ...dryFiles(), 'response/data/mutations.json': mutationsJson({ commit: null, changes: DRY_CHANGES }) }, "mode apply differs from the request's dry", 'a plan that re-decides the mode');
+
+process.stdout.write('backend.source.apply self-test: 3 valid branches, 43 rejected mutations\n');

package/operators/backend-source-apply/validate.mjs

@@ -0,0 +1,240 @@
+// backend.source.apply's own law over one branch, on top of the shared step check: the write set arrives
+// as exactly one commit on the session branch, and the mutation record, response.json.commits and the
+// change record name that same sha; every operation the frozen contract carries is restated once and
+// applied; every change lies inside the mutable ceiling, names a declared operation, appears once, and
+// carries the hash pair its kind demands; a dry run commits nothing, writes no after hash, measures no
+// facet and runs no proof, and reports every planned path as unchanged in the change record; every
+// declared facet of an applied run has its own conformance file, named for
+// the operation and facet it measures, with evidence, and every verdict in a done branch conforms;
+// every declared proof ran exactly once in its own file, with a command, an exit code that agrees with
+// its result, and a pass; the change record and the receipt describe the same files; no finding names
+// an undeclared operation, and a done branch raises no business question.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// A change record is the only durable trace that a file was mutated, so the hash pair has to agree with
+// the kind. A modified record whose before and after hashes are equal describes a mutation that never
+// happened.
+const HASH_SHAPE = { added: { before: 'null', after: 'set' }, modified: { before: 'set', after: 'set' }, deleted: { before: 'set', after: 'null' } };
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const fields = (rows) => Object.fromEntries((rows ?? []).map(([k, v]) => [k, v]));
+const listed = (value) => (value === undefined ? [] : Array.isArray(value) ? value : [value]);
+
+export async function validateBackendStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'backend.source.apply') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const readJson = async (f) => { try { return JSON.parse(await read(f)); } catch { return null; } };
+  const mutable = new Set(Array.isArray(requirements.mutableFileRefs) ? requirements.mutableFileRefs : []);
+  // `mode` decides whether this branch touched the checkout at all; everything below reads differently under dry.
+  const mode = requirements.mode ?? 'apply';
+
+  // A blocked branch has no implementation at all, and nothing it may have written is committed.
+  if (response.status === 'blocked' && (present.has('backend-source-application') || present.has('mutations') || present.has('conformance') || present.has('proof'))) {
+    errors.push('response/response.json: a blocked branch cannot carry an implementation');
+  }
+  if (response.status === 'blocked' && (response.commits ?? []).length) {
+    errors.push('response/response.json: a blocked branch commits nothing');
+  }
+
+  const mutations = present.has('mutations') && has('response/data/mutations.json') ? await readJson('response/data/mutations.json') : null;
+  const declared = mutations ? mutations.operations : [];
+  const declaredById = new Map(declared.map((o) => [o.operationId, o]));
+
+  // The plan cannot re-decide the mode the request asked for.
+  if (mutations && mutations.mode !== mode) errors.push(`response/data/mutations.json: mode ${mutations.mode} differs from the request's ${mode}`);
+
+  // A dry run answers with the plan alone: nothing committed, nothing measured, nothing hashed after.
+  if (mode === 'dry') {
+    if (mutations && mutations.commit !== null) errors.push('response/data/mutations.json: a dry run commits nothing, so commit must be null');
+    if ((response.commits ?? []).length) errors.push('response/response.json: a dry run records no commit');
+    if (present.has('conformance') || present.has('proof')) errors.push('response/response.json: a dry run measures nothing, so it carries no conformance or proof record');
+  }
+
+  // One commit on the session branch, named the same way in three places.
+  if (response.status === 'done' && mode === 'apply') {
+    const commits = response.commits ?? [];
+    if (commits.length !== 1) errors.push(`response/response.json: a done branch commits its whole write set once, found ${commits.length} commits`);
+    if (mutations && commits.length === 1 && mutations.commit !== commits[0]) errors.push(`response/data/mutations.json: commit ${mutations.commit} differs from response.json commits[0] ${commits[0]}`);
+    // Required of an applied branch only: a dry run has no source to measure, and the Outputs table can only say yes or no.
+    for (const kind of ['conformance', 'proof']) if (!present.has(kind)) errors.push(`response/response.json: required output ${kind} is not in fields`);
+  }
+  if (mutations) {
+    if (mode === 'apply' && mutations.commit === mutations.base) errors.push('response/data/mutations.json: the commit equals the base, so nothing was written on the session branch');
+    for (const operation of declared) {
+      const at = `response/data/mutations.json: operation ${operation.operationId}`;
+      if (mutable.size && !mutable.has(operation.writerRef)) errors.push(`${at} names writer ${operation.writerRef} outside the mutable ceiling`);
+      const shipsMigration = (operation.migrationRefs ?? []).length > 0;
+      // A migration without a replay proof is a schema change nobody re-ran.
+      if (shipsMigration && !operation.proofKinds.includes('migration-replay')) errors.push(`${at} ships a migration without declaring the migration-replay proof`);
+      if (shipsMigration && !operation.facets.includes('migration')) errors.push(`${at} ships a migration without declaring the migration facet`);
+      if (!shipsMigration && operation.proofKinds.includes('migration-replay')) errors.push(`${at} declares a migration-replay proof but ships no migration`);
+      // A mutation arriving through a boundary declared not to mutate.
+      if (operation.transactionBoundary === 'read-only' && shipsMigration) errors.push(`${at} is read-only but ships a migration`);
+      // A redelivered event applies twice unless something makes the write idempotent.
+      if (operation.transport === 'event-consumer' && operation.idempotencyKind === 'none') errors.push(`${at} consumes events with no idempotency and will apply twice on redelivery`);
+      if (new Set(operation.facets).size !== operation.facets.length) errors.push(`${at} repeats a contract facet`);
+      if (new Set(operation.proofKinds).size !== operation.proofKinds.length) errors.push(`${at} repeats a proof kind`);
+      if (new Set(operation.authorityDecisionIds).size !== operation.authorityDecisionIds.length) errors.push(`${at} repeats a business decision identifier`);
+    }
+    if (declared.length && declaredById.size !== declared.length) errors.push('response/data/mutations.json: the contract repeats an operationId');
+
+    const changedPaths = new Set();
+    for (const change of mutations.changes) {
+      if (changedPaths.has(change.path)) errors.push(`response/data/mutations.json: file ${change.path} carries more than one change record`);
+      changedPaths.add(change.path);
+      if (declaredById.size && !declaredById.has(change.operationId)) errors.push(`response/data/mutations.json: change on ${change.path} names undeclared operation ${change.operationId}`);
+      if (mutable.size && !mutable.has(change.path)) errors.push(`response/data/mutations.json: change on ${change.path} lies outside the mutable ceiling`);
+      const shape = HASH_SHAPE[change.change];
+      if ((shape.before === 'set') !== (change.beforeHash !== null)) errors.push(`response/data/mutations.json: change on ${change.path} is ${change.change} with the wrong before hash`);
+      if (mode === 'dry') {
+        // A planned path has no new content yet, so an after hash could only have been invented.
+        if (change.afterHash !== null) errors.push(`response/data/mutations.json: change on ${change.path} reports an after hash under a dry run, which writes nothing`);
+      } else {
+        if ((shape.after === 'set') !== (change.afterHash !== null)) errors.push(`response/data/mutations.json: change on ${change.path} is ${change.change} with the wrong after hash`);
+        if (change.change === 'modified' && change.beforeHash === change.afterHash) errors.push(`response/data/mutations.json: change on ${change.path} records a modification whose hashes are identical`);
+      }
+    }
+  }
+
+  // One conformance file per declared facet, named for what it measures.
+  const conformanceKeys = new Set();
+  for (const file of listed(response.fields?.conformance)) {
+    const record = has(file) ? await readJson(file) : null;
+    if (!record) continue;
+    const expected = `response/data/conformance/${record.operationId}.${record.facet}.json`;
+    if (file !== expected) errors.push(`${file}: a conformance record of ${record.operationId} ${record.facet} must be filed as ${expected}`);
+    const key = `${record.operationId}|${record.facet}`;
+    if (conformanceKeys.has(key)) errors.push(`${file}: operation ${record.operationId} records ${record.facet} conformance twice`);
+    conformanceKeys.add(key);
+    const operation = declaredById.get(record.operationId);
+    if (declaredById.size && !operation) { errors.push(`${file}: conformance names undeclared operation ${record.operationId}`); continue; }
+    if (operation && !operation.facets.includes(record.facet)) errors.push(`${file}: operation ${record.operationId} proves undeclared facet ${record.facet}`);
+    if (mutations && record.contractFingerprint !== mutations.contractFingerprint) errors.push(`${file}: measured against another contract fingerprint than the one filled`);
+    // A widened or narrowed facet means the frozen contract was not filled as written.
+    if (response.status === 'done' && record.verdict !== 'conforms') errors.push(`${file}: operation ${record.operationId} reports ${record.verdict} ${record.facet} conformance in a done branch`);
+    if (empty(record.evidenceRef)) errors.push(`${file}: operation ${record.operationId} asserts ${record.facet} conformance with no evidence`);
+  }
+
+  const proofKeys = new Set();
+  for (const file of listed(response.fields?.proof)) {
+    const record = has(file) ? await readJson(file) : null;
+    if (!record) continue;
+    const expected = `response/data/proofs/${record.operationId}.${record.proofKind}.json`;
+    if (file !== expected) errors.push(`${file}: a proof of ${record.operationId} ${record.proofKind} must be filed as ${expected}`);
+    const key = `${record.operationId}|${record.proofKind}`;
+    if (proofKeys.has(key)) errors.push(`${file}: operation ${record.operationId} records the ${record.proofKind} proof twice`);
+    proofKeys.add(key);
+    const operation = declaredById.get(record.operationId);
+    if (declaredById.size && !operation) { errors.push(`${file}: proof names undeclared operation ${record.operationId}`); continue; }
+    if (operation && !operation.proofKinds.includes(record.proofKind)) errors.push(`${file}: operation ${record.operationId} runs undeclared proof ${record.proofKind}`);
+    if (mutations && record.contractFingerprint !== mutations.contractFingerprint) errors.push(`${file}: run against another contract fingerprint than the one filled`);
+    // The exit code is what was actually read; the verdict is a reading of it.
+    if ((record.exitCode === 0) !== (record.result === 'passed')) errors.push(`${file}: exit code ${record.exitCode} contradicts the ${record.result} verdict`);
+    if (response.status === 'done' && record.result !== 'passed') errors.push(`${file}: operation ${record.operationId} reports a failed ${record.proofKind} proof in a done branch`);
+  }
+
+  if (response.status === 'done' && mode === 'apply') {
+    for (const operation of declared) {
+      // Silence about a facet reads exactly like a pass.
+      for (const facet of operation.facets) if (!conformanceKeys.has(`${operation.operationId}|${facet}`)) errors.push(`response/data/conformance/${operation.operationId}.${facet}.json: the operation declares the ${facet} facet and no record proves it`);
+      for (const proofKind of operation.proofKinds) if (!proofKeys.has(`${operation.operationId}|${proofKind}`)) errors.push(`response/data/proofs/${operation.operationId}.${proofKind}.json: the operation declares the ${proofKind} proof and never ran it`);
+    }
+  }
+
+  let receiptFiles = null;
+  if (present.has('backend-source-application') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const binding = fields(tableUnder(text, '## Binding'));
+    if (!empty(requirements.outcome) && binding.Outcome !== requirements.outcome) errors.push('response/response.md: Outcome differs from the request');
+    if (!empty(requirements.featureId) && binding.Feature !== requirements.featureId) errors.push('response/response.md: Feature differs from the request');
+    if (binding.Mode !== undefined && binding.Mode !== mode) errors.push(`response/response.md: Mode ${binding.Mode} differs from the request's ${mode}`);
+    if (mutations) {
+      if (binding['Contract fingerprint'] !== mutations.contractFingerprint) errors.push('response/response.md: Contract fingerprint differs from the fingerprint the mutations were measured against');
+      if (binding.Base !== mutations.base) errors.push('response/response.md: Base differs from the base the session branch was cut from');
+      if (binding.Branch !== mutations.branch) errors.push('response/response.md: Branch differs from the session branch the write set lives on');
+      if (binding.Commit !== (mutations.commit ?? '—')) errors.push('response/response.md: Commit differs from the one commit the write set arrived as');
+    }
+
+    const applied = new Set();
+    for (const [operationId, transport, writer, transaction, idempotency, decisions] of tableUnder(text, '## Operations') ?? []) {
+      if (applied.has(operationId)) errors.push(`response/response.md: operation ${operationId} is declared more than once`);
+      applied.add(operationId);
+      const operation = declaredById.get(operationId);
+      if (declaredById.size && !operation) { errors.push(`response/response.md: operation ${operationId} is not in the frozen contract`); continue; }
+      if (!operation) continue;
+      if (transport !== operation.transport) errors.push(`response/response.md: operation ${operationId} reports transport ${transport}, the contract froze ${operation.transport}`);
+      if (writer !== operation.writerRef) errors.push(`response/response.md: operation ${operationId} reports writer ${writer}, the contract froze ${operation.writerRef}`);
+      if (transaction !== operation.transactionBoundary) errors.push(`response/response.md: operation ${operationId} reports transaction ${transaction}, the contract froze ${operation.transactionBoundary}`);
+      if (idempotency !== operation.idempotencyKind) errors.push(`response/response.md: operation ${operationId} reports idempotency ${idempotency}, the contract froze ${operation.idempotencyKind}`);
+      const cited = String(decisions).split(',').map((s) => s.trim()).filter(Boolean);
+      for (const decisionId of cited) if (!operation.authorityDecisionIds.includes(decisionId)) errors.push(`response/response.md: operation ${operationId} cites decision ${decisionId}, which the contract does not bind`);
+      for (const decisionId of operation.authorityDecisionIds) if (!cited.includes(decisionId)) errors.push(`response/response.md: operation ${operationId} does not restate approved decision ${decisionId}`);
+    }
+    if (response.status === 'done') for (const operationId of declaredById.keys()) if (!applied.has(operationId)) errors.push(`response/response.md: operation ${operationId} was declared but never applied`);
+
+    const seenFiles = new Set();
+    const changeById = new Map((mutations?.changes ?? []).map((c) => [c.path, c]));
+    for (const [file, changeKind, operationId, before, after] of tableUnder(text, '## Changes') ?? []) {
+      if (seenFiles.has(file)) errors.push(`response/response.md: file ${file} carries more than one change record`);
+      seenFiles.add(file);
+      const record = changeById.get(file);
+      if (mutations && !record) { errors.push(`response/response.md: change on ${file} is absent from the mutation record`); continue; }
+      if (!record) continue;
+      if (changeKind !== record.change) errors.push(`response/response.md: change on ${file} is ${changeKind} here and ${record.change} in the mutation record`);
+      if (operationId !== record.operationId) errors.push(`response/response.md: change on ${file} names operation ${operationId}, the mutation record names ${record.operationId}`);
+      if ((empty(before) ? null : before) !== record.beforeHash) errors.push(`response/response.md: change on ${file} disagrees with the mutation record on the before hash`);
+      if ((empty(after) ? null : after) !== record.afterHash) errors.push(`response/response.md: change on ${file} disagrees with the mutation record on the after hash`);
+    }
+    if (mutations) for (const p of changeById.keys()) if (!seenFiles.has(p)) errors.push(`response/response.md: the mutation record changed ${p}, which the receipt omits`);
+    receiptFiles = seenFiles;
+
+    for (const [code, operationId] of tableUnder(text, '## Findings') ?? []) {
+      if (!empty(operationId) && declaredById.size && !declaredById.has(operationId)) errors.push(`response/response.md: finding ${code} names undeclared operation ${operationId}`);
+      // Raising the business question and shipping anyway is the exact contradiction to catch.
+      if (code === 'BUSINESS_QUESTION_RAISED' && response.status === 'done') errors.push('response/response.md: a done branch cannot raise an unresolved business question');
+    }
+  }
+
+  // The change record the next step reads must describe the same files and pin the same commit.
+  if (present.has('changes') && has('response/changes.md')) {
+    const text = await read('response/changes.md');
+    if (mutations) {
+      const checkout = fields(tableUnder(text, '## Binding')).Checkout ?? '';
+      // A dry run wrote nothing, so the next request can only pin the base it read.
+      const expected = mode === 'dry'
+        ? `@workspaces/be at ${mutations.base} on ${mutations.branch}, nothing written`
+        : `@workspaces/be at ${mutations.base} → ${mutations.commit} on ${mutations.branch}`;
+      const seen = checkout.replaceAll('`', '').replace(/\s+/g, ' ').trim();
+      if (seen !== expected) errors.push(`response/changes.md: Checkout must read ${expected}, so the next request can pin exactly what was written; it reads ${seen}`);
+    }
+    if (mode === 'dry') {
+      // The Change column reports the working tree, and a dry run left every path in it alone.
+      for (const [file, kind] of tableUnder(text, '## Files') ?? []) {
+        if (kind !== 'unchanged') errors.push(`response/changes.md: ${file} is reported ${kind} under a dry run, which leaves every path unchanged in the working tree`);
+      }
+    }
+    if (receiptFiles) {
+      const changed = new Set((tableUnder(text, '## Files') ?? []).map(([p]) => p));
+      for (const file of changed) if (!receiptFiles.has(file)) errors.push(`response/changes.md: ${file} is not in the receipt's change records`);
+      for (const file of receiptFiles) if (!changed.has(file)) errors.push(`response/changes.md: the receipt changed ${file}, which the change record omits`);
+    }
+  }
+  return { errors };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node validate.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateBackendStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid backend.source.apply branch\n');
+}

package/operators/business-decide/errors.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only business.decide emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS, EVIDENCE_MISSING) come from operators/errors.json, and APPROVAL_REQUIRED is not defined here because more than one operator emits it: a code two operators emit belongs in operators/errors.json with both ids in scope. Every domain here is the routing domain the old package's owningDomain enum published for this operator: business, backend, frontend, architecture, workspace, caller.",
+  "codes": {
+    "CONTRADICTION_UNRESOLVED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Two claims about the same behaviour disagree and nothing resolves them.",
+        "vi": "Hai claim về cùng một hành vi mâu thuẫn và không có gì giải quyết chúng."
+      },
+      "resume": {
+        "en": "The owner resolves the contradiction.",
+        "vi": "Người chủ giải quyết mâu thuẫn."
+      }
+    },
+    "COVERAGE_INCOMPLETE": {
+      "domain": "business",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared coverage dimension carries no disposition.",
+        "vi": "Một chiều phủ đã khai không mang disposition nào."
+      },
+      "resume": {
+        "en": "Add the missing disposition.",
+        "vi": "Bổ sung disposition còn thiếu."
+      }
+    },
+    "CONSUMER_UNPROVEN": {
+      "domain": "business",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A discovered enforcement consumer has no disposition or no proof.",
+        "vi": "Một consumer thực thi đã phát hiện không có disposition hoặc không có bằng chứng."
+      },
+      "resume": {
+        "en": "Dispose the consumer with positive and negative proof, then publish the promise again.",
+        "vi": "Xử lý consumer đó kèm positive và negative proof, rồi publish lại lời hứa."
+      }
+    },
+    "LIFECYCLE_TRANSITION_INVALID": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The requested target state is unreachable from the observed head.",
+        "vi": "Trạng thái đích được yêu cầu không tới được từ head đã quan sát."
+      },
+      "resume": {
+        "en": "Ask for a legal transition, or publish the intermediate state first.",
+        "vi": "Yêu cầu một chuyển trạng thái hợp lệ, hoặc publish trạng thái trung gian trước."
+      }
+    },
+    "AUTHORITY_CONFLICT": {
+      "domain": "workspace",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The head or the businesses root contradicts published authority.",
+        "vi": "Head hoặc gốc businesses mâu thuẫn với thẩm quyền đã publish."
+      },
+      "resume": {
+        "en": "Correct the authority binding.",
+        "vi": "Sửa binding thẩm quyền."
+      }
+    },
+    "RECONCILIATION_DISCREPANCY": {
+      "domain": "backend",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "Delivered source differs from the frozen coverage matrix.",
+        "vi": "Source đã giao khác với ma trận phủ đã đóng băng."
+      },
+      "resume": {
+        "en": "Correct the source, or revise the matrix.",
+        "vi": "Sửa source, hoặc sửa lại ma trận."
+      }
+    }
+  }
+}

package/operators/business-decide/operator.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 9,
+  "id": "business.decide",
+  "domain": "business",
+  "job": "Decide and publish one evidence-backed business promise as durable backend-owned authority, frozen behind a complete promise-to-enforcement coverage matrix.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "sol-fresh",
+    "grammarBound": false,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/sourcewrite": "declared-write-set",
+      "@tools/git": "read",
+      "@tools/websearch": "bounded"
+    }
+  }
+}