@ecoma-io/archkeep 0.24.0 → 0.25.0

package/src/commands/change.mjs

@@ -103,15 +103,18 @@ import { providerMismatch, readEvidenceSnapshot } from "./delta-snapshot.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { blindSpotRows } from "../analysis/source-util.mjs";
 import { cyclicProjects } from "../governance/fitness-rules.mjs";
-import { fitnessVerdict } from "../governance/verdict.mjs";
+import { eventSnapshotSide } from "./history.mjs";
+import { VERDICTS, fitnessVerdict, isVerdict } from "../governance/verdict.mjs";
+import { describe } from "../values.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatChangeReport } from "../report/change-text.mjs";
 import { evaluateRun } from "../rules/index.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
+  assertReproducibleEventIdentity,
   classifyEvolution,
   declarationDigest,
   escapeIdentityField,
@@ -170,6 +173,7 @@ function cmpFacts(a, b) {
  * @returns {string}
  */
 export function violationFindingId(entry) {
+  // used by its own test
   const sourceProject =
     entry.sourceProject == null ? "-" : escapeIdentityField(entry.sourceProject);
   return `${escapeIdentityField(entry.messageId)}:${sourceProject}:${escapeIdentityField(entry.target)}`;
@@ -250,6 +254,7 @@ function observedFrom(structural, meta) {
  * @returns {{matched: object[], unexpected: object[], missingExpected: object[]}}
  */
 export function reconcileMaterialDelta(intent, delta) {
+  // used by its own test
   const addedProjectNames = new Set(intent.projects.add);
   const removedProjectNames = new Set(intent.projects.remove);
   // The declared row's identity is `./change-intent.mjs`'s `edgePairKey` — the
@@ -358,13 +363,16 @@ export function reconcileMaterialDelta(intent, delta) {
  * @param {string[]} unprovenReasons Why the base identity could not be proven.
  * @returns {"matched"|"undeclared"|"unfulfilled"|"unproven"}
  */
-export function reconciliationVerdict(lists, unprovenReasons) {
+function reconciliationVerdict(lists, unprovenReasons) {
   if (unprovenReasons.length > 0) return "unproven";
   if (lists.unexpected.length > 0) return "undeclared";
   if (lists.missingExpected.length > 0) return "unfulfilled";
   return "matched";
 }
 
+/** The verdict axis `reconcileDisposition` maps — the four `reconciliationVerdict` answers. */
+const RECONCILE_VERDICTS = Object.freeze(["matched", "undeclared", "unfulfilled", "unproven"]);
+
 /**
  * The reconcile DISPOSITION mapping (wave 3, design §5) — the verdict axis
  * first, then the declared constraints' verdicts. Pure and exported so the
@@ -387,8 +395,34 @@ export function reconciliationVerdict(lists, unprovenReasons) {
  *   this run — empty when none were declared or when the base identity was
  *   unproven (constraints are left unevaluated then).
  * @returns {"accepted"|"rejected"|"no-verdict"}
+ * @throws {Error} on an axis value outside the four, or a constraint row
+ *   whose verdict is outside the canonical vocabulary — a stranger would fold
+ *   to `accepted`, and a fabricated acceptance is the one answer this mapping
+ *   never hands out.
  */
 export function reconcileDisposition(verdict, constraints = []) {
+  // The mapping owns its input latch — it is exported and pure, the one place
+  // the precedence is stated, and a stranger axis value would match no named
+  // arm and land on `accepted`: a fabricated acceptance, the one answer this
+  // function must never hand out over input it did not understand.
+  if (!RECONCILE_VERDICTS.includes(verdict)) {
+    throw new Error(
+      `archkeep: refusing to map a reconcile verdict ${describe(verdict)} — ` +
+        `expected one of ${RECONCILE_VERDICTS.join(", ")}. This is a bug in the ` +
+        `reconciliation that produced it.`,
+    );
+  }
+  // Same latch one axis down: a constraint row verdict outside the four states
+  // matches neither `unknown` nor `fail`, and the mapping reads it as consent.
+  for (const row of constraints) {
+    if (!isVerdict(row.verdict)) {
+      throw new Error(
+        `archkeep: refusing to map a constraint row whose verdict is ${describe(row.verdict)} — ` +
+          `expected one of ${VERDICTS.join(", ")}. This is a bug in the judge that built the row.`,
+      );
+    }
+  }
+  // used by its own test
   if (verdict === "unproven") return "no-verdict";
   if (verdict === "undeclared" || verdict === "unfulfilled") return "rejected";
   if (constraints.some((row) => row.verdict === "unknown")) return "no-verdict";
@@ -644,6 +678,28 @@ export async function changeCommand(
     dependencies: buildDependencies(graph.dependencies),
   };
   const structural = computeDiff(baseGraphForDiff, headGraphForDiff);
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything between this
+  // line and the event assembly (constraint re-judgement, custom rules,
+  // classification, debt) reads the graphs too; the engine's purity is what
+  // keeps them honest today, but the WS-I adversarial audit named the seam:
+  // identity and diff agreeing must not rest on purity conventions alone when
+  // one structural line closes it.
+  const baseCommit = baseline.provenance?.commit;
+  const headCommit = headProvenance?.commit;
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseGraphForDiff.projects,
+    dependencies: baseGraphForDiff.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraphForDiff.projects,
+    dependencies: headGraphForDiff.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const reconciliation = reconcileMaterialDelta(intent, structural);
 
   // Constraints and the law axis are computed over both sides re-judged under
@@ -732,16 +788,10 @@ export async function changeCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit the contract pins",
-    );
+    notes.push(dirtyBaselineNote(true));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
   if (meta.provenanceOneSided) {
     notes.push(
@@ -851,23 +901,24 @@ export async function changeCommand(
     }
   }
 
-  const baseCommit = baseline.provenance?.commit;
-  const headCommit = headProvenance?.commit;
   /** @type {object} */
   const event = {
     schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
     kind: "reconcile",
     source: "change",
-    base: {
-      ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-      // The caller's own evidence ref — the baseline file this run consumed,
-      // spelled as the run received it (the same convention `declaration.file`
-      // uses for the intent path).
-      evidence: baselinePath,
-    },
-    head: {
-      ...(typeof headCommit === "string" ? { revision: headCommit } : {}),
-    },
+    // Both sides were frozen through the ONE identity spelling
+    // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a revision
+    // when one is known, plus the snapshot identity of the graph the diff
+    // compared — never the baseline's storage path, which is machine-local
+    // and must not make the identity a per-machine property.
+    base: eventBase,
+    head: eventHead,
+    // The caller's own evidence ref — the baseline file this run consumed,
+    // spelled as the run received it (the same convention `declaration.file`
+    // uses for the intent path). Disclosed OUTSIDE the identity: the tuple
+    // above names the state itself, so a relocated baseline is still the
+    // same event.
+    evidence: baselinePath,
     declaration: { file: intentPath, digest: declarationDigest(intent) },
     observed,
     affected: evolution.affected,
@@ -898,6 +949,18 @@ export async function changeCommand(
   /** @type {{dir: string, id: string, duplicate: boolean}|null} */
   let eventWritten = null;
   if (eventOut !== undefined && eventOut !== null && eventOut !== "") {
+    // F-delta-event-id on the reconcile event: the event's identity names
+    // base and head revisions, so a commitless head or a dirty tree collapses
+    // distinct evidence states onto one event id — a later transition is
+    // silently lost or aliased, the silent direction. `delta` holds the same
+    // gate; the shared law and its frozen wording live in
+    // `../governance/evolution-event.mjs`.
+    assertReproducibleEventIdentity({
+      label: "change",
+      headCommit,
+      baseDirty: baseline.provenance?.dirty === true,
+      headDirty: headProvenance?.dirty === true,
+    });
     // The store's io.root is the workspace root: the write must be provable
     // to stay inside the workspace (the same containment `--output` obeys).
     // A write failure throws — exit 3 upstream, the could-not-look lane —

package/src/commands/check.mjs

@@ -29,7 +29,10 @@ import {
   unownedGapWithoutRunConfiguration,
   untrackedOwnedFiles,
 } from "./context.mjs";
-import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
+import {
+  partitionUnownedCoverage,
+  withdrawAcceptedUnclaimedFailures,
+} from "./coverage-acceptance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
 import { declaredEdgeViolationsForCheck, judgeEdge } from "../rules/edge-constraints.mjs";
@@ -223,7 +226,7 @@ export async function check(
   );
   const { root, graph, workspace, tracked } = commandContext;
   const { imports, exemptedFiles, unsupportedLanguageFiles } = commandContext.analysis;
-  const failures = [...commandContext.analysis.failures];
+  let failures = [...commandContext.analysis.failures];
   const analyzed = commandContext.analysis.analyzed;
 
   // The config's location is a separate fact from the workspace root, which is
@@ -308,17 +311,16 @@ export async function check(
   // acceptance now — stated below as the `"accepted-unowned-files"` coverage
   // gap, never silently — rather than the exit-3 refusal an unanswered
   // orphan earns. Uncovered unclaimed files keep their failures, and with
-  // them the exit code, byte-identical to before the channel existed. An
-  // unclaimed file carries exactly one failure (it is unowned, so no
-  // analyzer ever read it), so filtering by file cannot drop an unrelated
-  // read failure.
+  // them the exit code, byte-identical to before the channel existed. The
+  // one-failure-per-file assumption the withdrawal rests on is enforced where
+  // it is spent (`./coverage-acceptance.mjs`), not stated here: an accepted
+  // file carrying a second failure refuses the run instead of losing both
+  // rows to a by-file splice.
   const acceptedUnclaimed = new Set(
     commandContext.unclaimedGap.files.filter((file) => unownedCoverage.acceptedFiles.has(file)),
   );
   if (acceptedUnclaimed.size > 0) {
-    for (let at = failures.length - 1; at >= 0; at -= 1) {
-      if (acceptedUnclaimed.has(failures[at].sourceFile)) failures.splice(at, 1);
-    }
+    failures = withdrawAcceptedUnclaimedFailures(failures, acceptedUnclaimed);
   }
 
   // The go.work drift check, keyed off the manifest's presence the way every

package/src/commands/completeness.mjs

@@ -40,10 +40,10 @@ export const EVALUATION_STATUS = Object.freeze({
   REFUSED: "refused",
 });
 export const EVALUATED = EVALUATION_STATUS.EVALUATED;
-export const PARTIAL = EVALUATION_STATUS.PARTIAL;
+export const PARTIAL = EVALUATION_STATUS.PARTIAL; // used by its own test
 export const NOT_EVALUATED = EVALUATION_STATUS.NOT_EVALUATED;
-export const UNSUPPORTED = EVALUATION_STATUS.UNSUPPORTED;
-export const REFUSED = EVALUATION_STATUS.REFUSED;
+export const UNSUPPORTED = EVALUATION_STATUS.UNSUPPORTED; // used by its own test
+export const REFUSED = EVALUATION_STATUS.REFUSED; // used by its own test
 
 // ---------------------------------------------------------------------------
 // Evaluation contract types — which gates are required per evaluation type
@@ -71,7 +71,7 @@ export const EVALUATION_CONTRACT_TYPES = Object.freeze({
  *
  * @type {Readonly<Object<string, ReadonlySet<string>>>}
  */
-export const REQUIRED_GATES_FOR_CONTRACT = Object.freeze({
+const REQUIRED_GATES_FOR_CONTRACT = Object.freeze({
   [EVALUATION_CONTRACT_TYPES.CANONICAL]: Object.freeze(
     new Set([
       "domainCoverage",
@@ -107,7 +107,7 @@ export const REQUIRED_GATES_FOR_CONTRACT = Object.freeze({
  *   Defaults to SCENARIO (most restrictive).
  * @returns {boolean}
  */
-export function isGateRequired(gateKey, contractType = EVALUATION_CONTRACT_TYPES.SCENARIO) {
+function isGateRequired(gateKey, contractType = EVALUATION_CONTRACT_TYPES.SCENARIO) {
   const required = REQUIRED_GATES_FOR_CONTRACT[contractType];
   return required ? required.has(gateKey) : true;
 }
@@ -121,6 +121,7 @@ export function isGateRequired(gateKey, contractType = EVALUATION_CONTRACT_TYPES
  * @type {Readonly<{key: string, label: string, type: string}[]>}
  */
 export const EVIDENCE_COMPLETE_GATES = Object.freeze([
+  // used by its own test
   { key: "domainCoverage", label: "Domain coverage", type: "ratio" },
   { key: "claimEvidenceCoverage", label: "Claim evidence coverage", type: "ratio" },
   { key: "causalCoverage", label: "Causal coverage", type: "ratio" },
@@ -265,7 +266,7 @@ export const REQUIRED_DOMAINS = Object.freeze([
  * @param {string} status EVALUATION_STATUS value
  * @returns {boolean}
  */
-export function isDomainEvaluated(status) {
+function isDomainEvaluated(status) {
   return status === EVALUATION_STATUS.EVALUATED;
 }
 

package/src/commands/coverage-acceptance.mjs

@@ -111,3 +111,49 @@ export function partitionUnownedCoverage({ rows, unownedGap, unclaimedFiles, tra
     },
   };
 }
+
+/**
+ * Withdraws each accepted unclaimed file's failure from the run's failure
+ * list — the acceptance channel's effect on it, kept beside the matching so
+ * the channel's contract (accept the file ⇒ withdraw its refusal) is one
+ * module's. `./check.mjs` holds the list and narrows `acceptedFiles` to the
+ * unclaimed half; `./waivers.mjs` has no failure list and only reports rows.
+ *
+ * An accepted unclaimed file carries exactly one failure — its unowned-file
+ * refusal, the only row any producer appends for a file no analyzer ever
+ * read. The withdrawal does not TRUST that assumption, it ENFORCES it: an
+ * accepted file carrying more than one failure means some producer appended a
+ * second row for it, and a splice by `sourceFile` would take the second one
+ * down with the first — the failure count falls, `coverage.notAnalyzed` loses
+ * a row, and a could-not-look run tips toward a clean one, the silent
+ * direction (`../../../../AGENTS.md`). The run refuses instead, naming the
+ * file and the count it found.
+ *
+ * @param {{sourceFile: string}[]} failures The run's failure list, in order.
+ * @param {Set<string>} acceptedFiles The accepted subset of the unclaimed
+ *   list — `partitionUnownedCoverage`'s `acceptedFiles` narrowed to that list
+ *   by the caller.
+ * @returns {{sourceFile: string}[]} A new array without the accepted files'
+ *   single failures; the input is not mutated.
+ * @throws {Error} when an accepted file carries more than one failure.
+ */
+export function withdrawAcceptedUnclaimedFailures(failures, acceptedFiles) {
+  const carried = new Map();
+  for (const failure of failures) {
+    if (!acceptedFiles.has(failure.sourceFile)) continue;
+    carried.set(failure.sourceFile, (carried.get(failure.sourceFile) ?? 0) + 1);
+  }
+  const overloaded = [...carried.entries()].filter(([, count]) => count > 1);
+  if (overloaded.length > 0) {
+    const named = overloaded
+      .map(([file, count]) => `'${file}' (carries ${count} failures)`)
+      .join(", ");
+    throw new Error(
+      `archkeep: the coverage.unowned acceptance channel cannot withdraw ${named} — ` +
+        `acceptance withdraws exactly one failure per file (the unowned-file refusal), and ` +
+        `withdrawing by file would drop the second one with it, understating what this run ` +
+        `could not read`,
+    );
+  }
+  return failures.filter((failure) => !acceptedFiles.has(failure.sourceFile));
+}

package/src/commands/custom-rules.mjs

@@ -140,6 +140,7 @@ export function declaresCustomRules(config) {
  * @returns {(artifact: string) => Uint8Array|null}
  */
 export function readArtifactBytes(root) {
+  // used by its own test
   return (artifact) => {
     const abs = join(root, artifact);
     if (containmentViolation(root, abs) !== null) return null;

package/src/commands/delta-classify.mjs

@@ -79,6 +79,7 @@ import { namespacedId } from "./custom-rules.mjs";
  *   constraint: object|null}}|{ok: false, reason: string}}
  */
 export function violationIdentity(violation) {
+  // used by its own test
   if (violation === null || typeof violation !== "object" || Array.isArray(violation)) {
     return { ok: false, reason: `violation is ${describe(violation)}, not an object` };
   }
@@ -148,6 +149,7 @@ export function violationIdentity(violation) {
  *   original violation plus the `reason` its identity could not be stated.
  */
 export function classifyViolations({ base, head, suppressions = [], now = referenceTime() }) {
+  // used by its own test
   const baseIdentified = base.map(identityOf);
   const headIdentified = head.map(identityOf);
 
@@ -237,6 +239,7 @@ export function classifyViolations({ base, head, suppressions = [], now = refere
  *   unknown: object[]}}
  */
 export function classifyUnresolvableRecords({ base, head, sourceProjectOf }) {
+  // used by its own test
   const attribute = sourceProjectOf ?? (() => null);
   const baseIdentified = base
     .filter(isUnresolvable)

package/src/commands/delta-snapshot.mjs

@@ -52,7 +52,7 @@ import { isPlainObject } from "../values.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 
 /** The only snapshot schemaVersion this module writes and reads. */
-export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1; // used by its own test
 
 /**
  * Builds the snapshot object from already-captured evidence.
@@ -274,7 +274,9 @@ export function buildEvidenceSnapshot({
  * order is the only order the format keeps, and `buildEvidenceSnapshot` sorts
  * every array whose source does not guarantee it. Two captures over one
  * unchanged tree produce byte-identical files, which is what makes a plain
- * `diff` of two baselines meaningful.
+ * `diff` of two baselines meaningful. That determinism is also why this
+ * family carries no identity field, by decision: the bytes are the identity
+ * (`../../../../docs/adr/0008-snapshot-identity-per-family.md`).
  *
  * @param {object} snapshot From `buildEvidenceSnapshot`.
  * @returns {string} The JSON text, newline-terminated.
@@ -330,7 +332,11 @@ export function readEvidenceSnapshot(path, io = {}) {
  * What is deliberately NOT a refusal: dirty base provenance. A baseline from
  * an uncommitted tree is weaker evidence, not unreadable evidence — the parsed
  * snapshot exposes `provenance.dirty` so the renderer can say so loudly, and
- * classification itself proceeds.
+ * classification itself proceeds. A dirty BIT that is not a boolean is a
+ * different thing — malformed, not weaker: the gates read `dirty === true`
+ * while the renderers interpolate truthiness, so any other type would read
+ * clean to some consumers and dirty to others. The provenance block below
+ * refuses it by name.
  *
  * @param {string} text The file contents.
  * @param {string} path The path the text came from, for error messages.
@@ -338,6 +344,7 @@ export function readEvidenceSnapshot(path, io = {}) {
  * @throws {Error} on every condition above.
  */
 export function parseEvidenceSnapshot(text, path) {
+  // used by its own test
   let parsed;
   try {
     parsed = JSON.parse(text);
@@ -391,8 +398,23 @@ export function parseEvidenceSnapshot(text, path) {
 
   if (parsed.provenance !== null && !isPlainObject(parsed.provenance)) {
     problems.push("provenance: must be an object ({commit, remote, dirty}) or null");
-  } else if (isPlainObject(parsed.provenance) && typeof parsed.provenance.commit !== "string") {
-    problems.push("provenance.commit: must be a string when provenance is present");
+  } else if (isPlainObject(parsed.provenance)) {
+    if (typeof parsed.provenance.commit !== "string") {
+      problems.push("provenance.commit: must be a string when provenance is present");
+    }
+    if (parsed.provenance.remote !== null && typeof parsed.provenance.remote !== "string") {
+      problems.push("provenance.remote: must be a string or null when provenance is present");
+    }
+    if (typeof parsed.provenance.dirty !== "boolean") {
+      // Malformed, not weaker: the gates read `dirty === true` while the
+      // renderers interpolate truthiness, so a value of any other type reads
+      // clean to some consumers and dirty to others — the one disagreement
+      // this record must never carry.
+      problems.push(
+        "provenance.dirty: must be a boolean when provenance is present — the gates decide " +
+          "between committed and uncommitted evidence on this bit",
+      );
+    }
   }
 
   if (typeof parsed.policyFingerprint !== "string" || parsed.policyFingerprint === "") {

package/src/commands/delta.mjs

@@ -74,6 +74,7 @@ import {
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
+  assertReproducibleEventIdentity,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -105,9 +106,10 @@ import {
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { eventSnapshotSide } from "./history.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 
 const require = createRequire(import.meta.url);
 /** @type {{name: string, version: string}} */
@@ -161,6 +163,7 @@ export function refusePluginGapHead(commandContext, activity) {
  * @throws {Error} on either condition.
  */
 export function refuseUnjudgeableHead(commandContext, activity) {
+  // used by its own test
   refusePluginGapHead(commandContext, activity);
   const notAnalyzed = commandContext.analysis.failures.filter(isWholeFileFailure);
 
@@ -271,6 +274,8 @@ export function captureDelta(commandContext, { config }) {
  *   type: string}[], workspaceLayout?: object, exemptedFiles?: string[]}} storedGraph
  *   A validated snapshot's `graph` section (`parseEvidenceSnapshot`).
  * @returns {object} A graph `evaluate()` consumes.
+ * @throws {Error} when an `exemptedFiles` entry is not a string — the engine's
+ *   own filter would drop it in silence (the refusal beside the copy below).
  */
 export function evidenceGraphToProjectGraph(storedGraph) {
   /** @type {Record<string, object>} */
@@ -297,7 +302,26 @@ export function evidenceGraphToProjectGraph(storedGraph) {
   const graph = { nodes, dependencies };
   if (storedGraph.workspaceLayout !== undefined)
     graph.workspaceLayout = storedGraph.workspaceLayout;
-  if (Array.isArray(storedGraph.exemptedFiles)) graph.exemptedFiles = storedGraph.exemptedFiles;
+  if (Array.isArray(storedGraph.exemptedFiles)) {
+    // An entry that is not a string is refused here rather than carried:
+    // `../rules/index.mjs`'s `createContext` filters `graph.exemptedFiles`
+    // with `typeof file === "string"`, so a corrupted snapshot's entry would
+    // ride through this conversion and vanish there — the exemption set the
+    // snapshot recorded silently shrinking by one file, the under-count
+    // disclosed nowhere.
+    const malformed = storedGraph.exemptedFiles
+      .map((entry, at) => ({ entry, at }))
+      .filter(({ entry }) => typeof entry !== "string");
+    if (malformed.length > 0) {
+      const { entry, at } = malformed[0];
+      throw new Error(
+        `archkeep: the snapshot's graph.exemptedFiles[${at}] is ${JSON.stringify(entry)}, ` +
+          `not a string — the rule engine drops such entries in silence, which would shrink ` +
+          `the exemption set the snapshot recorded; re-capture the baseline or correct the file`,
+      );
+    }
+    graph.exemptedFiles = storedGraph.exemptedFiles;
+  }
   return graph;
 }
 
@@ -373,6 +397,7 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  * @returns {"accepted"|"rejected"|"no-verdict"}
  */
 export function deltaDisposition({ status }) {
+  // used by its own test
   if (status === "no-verdict") return "no-verdict";
   if (status === "findings") return "rejected";
   return "accepted";
@@ -545,16 +570,10 @@ export async function deltaCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
 
   // The event's structural signal: what moved between the two graphs the
@@ -564,10 +583,11 @@ export async function deltaCommand(
   // a second spelling of "changed". The head side is rebuilt by the same
   // `buildProjects`/`buildDependencies` the snapshot stores
   // (`./delta-snapshot.mjs`), which is what makes the two sides comparable.
-  const structuralDiff = computeDiff(baseline.graph, {
+  const headGraph = {
     projects: buildProjects(graph.nodes),
     dependencies: buildDependencies(graph.dependencies),
-  });
+  };
+  const structuralDiff = computeDiff(baseline.graph, headGraph);
   const structural = {
     projects: {
       added: structuralDiff.addedProjects.map((project) => project.name),
@@ -594,6 +614,25 @@ export async function deltaCommand(
   // same", and a policy change is disclosed, not folded into drift.
   const baseCommit = baseline.provenance?.commit;
   const headCommit = headProvenance?.commit;
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything below this line
+  // (custom rules, classification, intent, debt) reads the graphs too; the
+  // engine's purity is what keeps them honest today, but the WS-I adversarial
+  // audit named the seam: identity and diff agreeing must not rest on purity
+  // conventions alone when one structural line closes it.
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseline.graph.projects,
+    dependencies: baseline.graph.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraph.projects,
+    dependencies: headGraph.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const provenanceAdvanced =
     typeof baseCommit === "string" &&
     typeof headCommit === "string" &&
@@ -810,26 +849,16 @@ export async function deltaCommand(
   let eventWrite = null;
   if (eventOut !== null && eventOut !== undefined) {
     // F-delta-event-id: an evolution event is only written from a reproducible
-    // identity — a committed, clean head and a clean base. A commitless head
-    // has no revision to name, and a dirty tree names a commit its evidence
-    // does not back; either way TWO distinct evidence states collapse onto ONE
-    // event id, so a later transition is silently lost or aliased (the silent
-    // direction). Refuse loudly instead. The same run without `--event-out`
-    // stays a byte-identical in-memory delta.
-    if (typeof headCommit !== "string") {
-      throw new Error(
-        "archkeep: refusing to write a delta event without a committed head — a commitless " +
-          "head has no reproducible event identity, and every distinct head state would " +
-          "collide on one event id. Commit the head, or capture without --event-out.",
-      );
-    }
-    if (baseline.provenance?.dirty === true || headProvenance?.dirty === true) {
-      throw new Error(
-        "archkeep: refusing to write a delta event from a dirty working tree — the event " +
-          "would name a commit whose evidence is uncommitted, and distinct uncommitted " +
-          "states would collide on one event id. Commit both sides first.",
-      );
-    }
+    // identity — a committed, clean head and a clean base, by the shared law
+    // `assertReproducibleEventIdentity` owns. The wording is frozen there; the
+    // messages consumers match on are byte-identical to the inline refusals
+    // this call replaces.
+    assertReproducibleEventIdentity({
+      label: "delta",
+      headCommit,
+      baseDirty: baseline.provenance?.dirty === true,
+      headDirty: headProvenance?.dirty === true,
+    });
     // The architecture-debt sub-ledger (design §8): judged by re-running the
     // current intent over this run's base and head graphs — a drift finding
     // present at head but not base is introduced; one gone is resolved. Both
@@ -864,13 +893,18 @@ export async function deltaCommand(
       schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
       kind: "transition",
       source: "delta",
-      base: {
-        ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-        // The evidence ref is the baseline file this run actually compared
-        // against — a pointer into the evidence, never a graph.
-        evidence: baselinePath,
-      },
-      head: typeof headCommit === "string" ? { revision: headCommit } : {},
+      // Both sides were frozen through the ONE identity spelling
+      // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a
+      // revision when one is known, plus the snapshot identity of the graph
+      // the diff compared — never the baseline's storage path, which is
+      // machine-local and must not make the identity a per-machine property.
+      base: eventBase,
+      head: eventHead,
+      // The evidence ref is the baseline file this run actually compared
+      // against — a pointer into the evidence, never a graph, and disclosed
+      // OUTSIDE the identity: the tuple above names the state itself, so a
+      // relocated baseline is still the same event.
+      evidence: baselinePath,
       recordedAt: recordOrigin({
         by: "cli",
         tool: `archkeep:v${TOOL_VERSION}`,

package/src/commands/diff.mjs

@@ -46,7 +46,7 @@ import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 
 /**
@@ -475,16 +475,10 @@ export function diffCommand(
   }
 
   if (meta.dirtyBaseline) {
-    coverage.notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    coverage.notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    coverage.notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    coverage.notes.push(dirtyHeadNote());
   }
 
   if (meta.policyChanged === true) {