@starci/skills 1.1.0 → 1.2.0

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

@@ -1,240 +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');
-}
+// 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.authorityDimensionIds).size !== operation.authorityDimensionIds.length) errors.push(`${at} repeats a business dimension 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 dimensionId of cited) if (!operation.authorityDimensionIds.includes(dimensionId)) errors.push(`response/response.md: operation ${operationId} cites dimension ${dimensionId}, which the contract does not bind`);
+      for (const dimensionId of operation.authorityDimensionIds) if (!cited.includes(dimensionId)) errors.push(`response/response.md: operation ${operationId} does not restate approved dimension ${dimensionId}`);
+    }
+    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/self-test.mjs

@@ -142,7 +142,7 @@ function writeBranch(files) {
   for (const d of ['request', 'response/data', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
   mkdirSync(path.join(session, 'step-1', 'parallel-2', 'response'), { recursive: true });
   writeFileSync(path.join(session, DELIVERED), '# backend-source-application — delivered source\n');
-  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'business.decide' }, current: '1/1', status: 'running' }));
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', project: 'starci-academy', startedAt: '2026-09-03T00:00:00Z', requestHashes: {}, chain: [['1/1']], steps: { '1/1': 'business.decide' }, 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));
@@ -217,6 +217,7 @@ await expectError({ ...baseline(), 'request/request.json': requestJson({ extra:
 await expectError({ ...baseline(), 'response/response.md': responseMd({ dispositions: DISPOSITIONS.map(([d, p]) => (d === 'legacy-read' ? [d, 'defer'] : [d, p])) }) }, 'is defer here and preserve in the matrix', 'the response and the matrix disagree on a disposition');
 await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Coverage', '## Coverage matrix') }, 'missing section ^## Coverage$', 'response section renamed');
 await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['LEGACY_COEXISTENCE', 'error', 'legacy-create', 'the legacy sale path still creates rights']] }) }, 'is still an open error, so the promise cannot be published', 'published with an open error finding');
+await expectError({ ...baseline(), 'response/data/claims.json': claimsDoc({ fingerprint: `sha256:${'b'.repeat(64)}` }) }, 'claimsFingerprint must equal the frozen claims fingerprint', 'a head naming another claims fingerprint');
 await expectError({ ...baseline(), 'response/data/claims.json': claimsDoc({ claims: [CLAIMS[0], { ...CLAIMS[0], kind: 'intent' }] }) }, 'is declared more than once', 'a duplicated claim');
 await expectError({ ...baseline(), 'response/data/claims.json': claimsDoc({ claims: [{ ...CLAIMS[0], sourceHead: null }, CLAIMS[1]] }) }, 'must bind the observed source head', 'a fact claim with no head');
 await expectError({ ...baseline(), 'response/response.md': responseMd({ claims: [['c-fact', 'fact']] }) }, 'which Cited claims omits', 'a claim the response never cites');

package/operators/business-decide/validate.mjs

@@ -71,10 +71,12 @@ export async function validateBusinessStep(branchDir, root = ROOT) {
   const declaredDimensions = Array.isArray(requirements.dimensions) ? requirements.dimensions : [];
 
   let claims = new Map();
+  let claimsDoc = null;
   if (present.has('claims') && has('response/data/claims.json')) {
     let doc = null;
     try { doc = JSON.parse(await read('response/data/claims.json')); } catch { doc = null; }
     if (doc) {
+      claimsDoc = doc;
       if (!empty(requirements.featureId) && doc.featureId !== requirements.featureId) errors.push(`response/data/claims.json: featureId ${doc.featureId} differs from the request's ${requirements.featureId}`);
       for (const claim of doc.claims ?? []) {
         if (claims.has(claim.claimId)) errors.push(`response/data/claims.json: claim ${claim.claimId} is declared more than once`);
@@ -197,6 +199,7 @@ export async function validateBusinessStep(branchDir, root = ROOT) {
     if (model.lineage.previousState !== null && model.lineage.previousHeadRef === null) errors.push('response/data/model.json: a transition from an existing state must name the previous head, because rejection preserves lineage');
 
     if (matrix && model.coverageFingerprint !== matrix.fingerprint) errors.push('response/data/model.json: coverageFingerprint must equal the frozen matrix fingerprint, or backend and UAT cannot correlate the same matrix');
+    if (claimsDoc && model.claimsFingerprint !== claimsDoc.fingerprint) errors.push('response/data/model.json: claimsFingerprint must equal the frozen claims fingerprint, or the head names claims nobody froze');
     if (mode === 'model' && model.reconciliation !== null) errors.push('response/data/model.json: mode model reconciles nothing, so reconciliation must be null');
     if (mode === 'reconcile') {
       if (model.reconciliation === null) errors.push('response/data/model.json: mode reconcile must carry the reconciliation it performed');

package/operators/content-generate/self-test.mjs

@@ -176,7 +176,7 @@ function writeBranch(files) {
   const session = mkdtempSync(path.join(tmpdir(), 'content-session-'));
   const branch = path.join(session, 'step-1', 'parallel-1');
   for (const d of ['request', 'response/data', 'response/artifacts', 'review/request', 'review/response']) mkdirSync(path.join(branch, d), { recursive: true });
-  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'content.generate' }, current: '1/1', status: 'running' }));
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', project: 'starci-academy', startedAt: '2026-09-03T00:00:00Z', requestHashes: {}, chain: [['1/1']], steps: { '1/1': 'content.generate' }, 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));

package/operators/frontend-direction-decide/self-test.mjs

@@ -146,7 +146,7 @@ function writeBranch(files) {
   for (const d of ['request', 'response/data', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
   mkdirSync(path.join(session, 'step-1', 'parallel-1', 'response'), { recursive: true });
   writeFileSync(path.join(session, 'step-1', 'parallel-1', 'response', 'response.md'), '# business-promise-authority — plans\n');
-  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1'], ['2/1']], steps: { '1/1': 'business.decide', '2/1': 'frontend.direction.decide' }, current: '2/1', status: 'running' }));
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', project: 'starci-academy', startedAt: '2026-09-03T00:00:00Z', requestHashes: {}, chain: [['1/1'], ['2/1']], steps: { '1/1': 'business.decide', '2/1': 'frontend.direction.decide' }, current: '2/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));

package/operators/frontend-presentation-resolve/operator.md

@@ -108,6 +108,12 @@ write product source, or record a verdict, score or pass claim on any node.
 | 8 | Emit the contract claims onto the application-owned nodes | `contractEmission` | @knowledge/ui/presentation (the frozen rule inventory) | — | `UNKNOWN_RULE` |
 | 9 | Emit | — | everything above | `response/artifacts/<target>.resolved.tsx`, `response/data/inventory.json`, `response/response.md`, `response/response.json` | — |
 
+Step 8 claims only what a node can carry: a property the application owns on a Grammar component's
+`className` carries no attribute, because the component forwards `className` and publishes no prop for
+the relationship, so its rule is recorded under `## Gaps` instead of being emitted. Forwarding
+`data-contract` from every Common component that accepts `className` is a Grammar change and belongs
+to the family owner, not to this operator.
+
 The walk visits every node in document order and records a stable node path; a node outside the
 ceiling the direction carries is observed and never mutated. Steps 4 to 8 run per node, so a single
 tree yields one decision per node and property. The receipt authorizes a later audit to measure the

package/operators/frontend-presentation-resolve/operator.vi.md

@@ -106,6 +106,12 @@ source sản phẩm, và không ghi phán quyết, điểm số hay tuyên bố
 | 8 | Phát lời khai contract lên các node do ứng dụng sở hữu | `contractEmission` | @knowledge/ui/presentation (kho luật đã đóng băng) | — | `UNKNOWN_RULE` |
 | 9 | Phát | — | mọi thứ ở trên | `response/artifacts/<target>.resolved.tsx`, `response/data/inventory.json`, `response/response.md`, `response/response.json` | — |
 
+Bước 8 chỉ khai thứ mà một node mang nổi: một thuộc tính do ứng dụng sở hữu nằm trên `className` của
+một component Grammar thì không mang thuộc tính nào, bởi component ấy chuyển tiếp `className` và không
+công bố prop nào cho quan hệ đó, nên luật của nó được ghi dưới `## Gaps` thay vì được phát ra. Chuyển
+tiếp `data-contract` từ mọi component Common có nhận `className` là một thay đổi của Grammar và thuộc
+về chủ họ ấy, không thuộc về operator này.
+
 Lượt đi thăm mọi node theo thứ tự tài liệu và ghi một node path ổn định; node nằm ngoài trần mà hướng
 mang theo thì chỉ quan sát chứ không bao giờ bị sửa. Bước 4 đến 8 chạy theo từng node, nên một cây cho
 đúng một quyết định cho mỗi cặp node và thuộc tính. Biên nhận uỷ quyền cho một lượt audit sau đo kết