@ecoma-io/archkeep 0.23.0 → 0.24.1

package/src/commands/check.mjs

@@ -12,6 +12,7 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
 
+import { foldMarkdownTrack } from "../analysis/markdown.mjs";
 import {
   blindSpotRows,
   fileFailure,
@@ -28,10 +29,13 @@ 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 } from "../rules/edge-constraints.mjs";
+import { declaredEdgeViolationsForCheck, judgeEdge } from "../rules/edge-constraints.mjs";
 import { customRulesForCheck, declaresCustomRules } from "./custom-rules.mjs";
 import { driftForCheck } from "./drift.mjs";
 import { fitnessForCheck } from "./fitness.mjs";
@@ -40,14 +44,16 @@ import { resolvePolicy } from "./policy.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { compareGoWork, parseGoWorkUse } from "../go-work.mjs";
+import { mergeDeclaredEdges } from "../providers/native/graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatSarif } from "../report/sarif.mjs";
 import { formatReport } from "../report/text.mjs";
 import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
-import { evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { applySuppressionTable, evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { buildReachability } from "../rules/reachability.mjs";
 import { orphanedNotDependOnTags, unmatchedConstraintRows } from "../rules/tags.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
-import { verdictFor } from "../verdict.mjs";
+import { coverageComplete, verdictFor } from "../verdict.mjs";
 import { listTrackedFiles, listUntrackedFiles } from "../workspace.mjs";
 
 /**
@@ -220,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
@@ -305,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
@@ -453,6 +458,41 @@ export async function check(
     }
   }
 
+  // The markdown document track, keyed by presence like every fold above it:
+  // a policy that declares no `markdown` block reaches nothing here and hears
+  // nothing anywhere — no edges, no failures, no envelope key — so a
+  // config-absent run is byte-identical to one this fold never existed for
+  // (`../../../../AGENTS.md`, "a change to what is reported on an unchanged
+  // workspace is a breaking change"). A policy that DOES declare one has its
+  // documents read (`../analysis/markdown.mjs`'s `foldMarkdownTrack`), the
+  // resolved pairings folded into the graph the way the declared manifest
+  // track's edges already are (`mergeDeclaredEdges`, the same dedup key), and
+  // every whole-file failure the read earned pushed into the same `failures`
+  // funnel the analysis uses — an unresolvable marker is an `unchecked` file,
+  // never a clean one.
+  //
+  // The fold runs BEFORE the walk below on purpose: a document pairing is a
+  // project-to-project dependency claim, and from here on this run's graph
+  // carries it exactly as it carries a csproj's `ProjectReference` — the tag
+  // rows, the circularity walk and the reachability behind them all read one
+  // graph, so a pairing cannot be legal here and violating in `context`.
+  // What it does not join is the twelve non-tag import-site rules: those need
+  // a specifier, a file and a resolution, and a document marker has none of
+  // them — it is judged as the EDGE it drew, the same 3-of-15 limit
+  // `declaredEdgeViolationsForCheck` documents for `implicit` edges.
+  let markdownTrack = null;
+  if (config !== null && config.markdown !== undefined) {
+    markdownTrack = foldMarkdownTrack({
+      tracked,
+      owned: commandContext.owned,
+      readFile: (file) => workspace.readFile(file),
+      workspace,
+      markdown: config.markdown,
+    });
+    mergeDeclaredEdges(graph, markdownTrack.edges);
+    failures.push(...markdownTrack.failures);
+  }
+
   // Both faces of one walk: the run's verdict, and the raw superset it was
   // picked from — every candidate up to each site's surviving group, including
   // the verdicts the suppression table removed to get there. `evaluate` alone
@@ -462,8 +502,66 @@ export async function check(
   // the gate's waiver-expiry judgement below and the engine's are the same
   // judgement, not two reads of the clock a boundary instant could split.
   const now = referenceTime();
-  const { violations: judged, rawViolations } = evaluateRun(imports, graph, { ...config, now });
-  const violations = sortViolations(judged);
+  const { violations: judged, rawViolations: judgedRaw } = evaluateRun(imports, graph, {
+    ...config,
+    now,
+  });
+
+  // The document pairings' own verdicts, judged by the machinery that already
+  // existed: `judgeEdge` — the same function `declaredEdgeViolationsForCheck`
+  // runs `implicit` edges through, so a doc pairing and a declared manifest
+  // edge can never disagree about the same boundary — over the graph the fold
+  // above already joined, with reachability built once for the whole claim
+  // list. The same empty-table exit `declaredEdgeViolationsForCheck` takes: a
+  // workspace declaring no `depConstraints` has opted out of tag enforcement
+  // entirely, and folding `projectWithoutTagsCannotHaveDependencies` onto
+  // every marker anyway would flag an opted-out workspace for a reason its
+  // import sites are never flagged for. Each verdict is then reshaped into the
+  // exact `Violation` record `violationOf` builds — position and specifier
+  // from the MARKER (the line a reader edits is the document's), project and
+  // constraint from the edge — so suppression, waiver annotation, sorting and
+  // the SARIF face all treat it as the ordinary violation it is.
+  /** @type {object[]} */
+  const markdownRaw = [];
+  if (config !== null && markdownTrack !== null && config.depConstraints.length > 0) {
+    const reachability = buildReachability(graph);
+    for (const claim of markdownTrack.claims) {
+      for (const verdict of judgeEdge(
+        { source: claim.source, target: claim.target },
+        graph.nodes,
+        graph.dependencies,
+        config.depConstraints,
+        reachability,
+      )) {
+        markdownRaw.push({
+          sourceFile: claim.file,
+          line: claim.line,
+          column: claim.column,
+          specifier: claim.name,
+          kind: claim.type,
+          messageId: verdict.messageId,
+          message: verdict.message,
+          sourceProject: verdict.source,
+          targetProject: verdict.target,
+          constraint: verdict.constraint,
+          data: verdict.data,
+        });
+      }
+    }
+  }
+  // The same table, the same behaviour: a suppression row whose glob covers a
+  // document removes that document's verdict (or waives it, with the same
+  // expiry evidence an import-site waiver carries), and the RAW records join
+  // `rawViolations` below so a row covering only document verdicts still
+  // counts as alive — a table that is doing its job must not read as dead
+  // because the violations it removes live in a different fold.
+  const markdownViolations =
+    config !== null && markdownTrack !== null
+      ? applySuppressionTable(config.suppressions, markdownRaw, now)
+      : [];
+
+  const rawViolations = [...judgedRaw, ...markdownRaw];
+  const violations = sortViolations([...judged, ...markdownViolations]);
   // An ACTIVE waiver keeps the violation it accepts in the findings list,
   // marked `waivedBy` — the run is still non-zero (waiving does not flip
   // exit 1 → 0), and this count is the additive "accepted violations" number
@@ -704,7 +802,10 @@ export async function check(
     config !== null &&
     options.paths.length === 0 &&
     failures.length === 0 &&
-    (config.suppressions.length > 0 || config.depConstraints.length > 0 || coverageRows.length > 0)
+    (config.suppressions.length > 0 ||
+      config.depConstraints.length > 0 ||
+      coverageRows.length > 0 ||
+      config.markdown !== undefined)
   ) {
     const deadRows = [];
     // The third dead table: a `coverage.unowned` row matching no unowned file
@@ -755,6 +856,34 @@ export async function check(
         );
       }
     }
+    // The document track's two dead tables, measured against what the fold
+    // actually selected (`markdownTrack.includeCounts`/`rowMatches` — the
+    // same counts the fold's own selection is built from, not a re-derivation
+    // that could disagree): an include glob matching no tracked document, and
+    // a marker row matching no line in any included document, both govern
+    // nothing while reading as enforced — every pairing the workspace meant
+    // to declare goes unjudged and the run stays green. A whole-file failure
+    // above already disabled this gate, so reaching here with a row that
+    // matched nothing means the tree genuinely has no such line.
+    if (markdownTrack !== null && config.markdown !== undefined) {
+      markdownTrack.includeCounts.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.include[${index}]: '${config.markdown.include[index]}' matches no tracked ` +
+            `document — the document track reads nothing, so every marker row below it governs ` +
+            `nothing while reading as enforced. Either the path was never right, or the ` +
+            `documents are not tracked`,
+        );
+      });
+      markdownTrack.rowMatches.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.markers[${index}]: the pattern matches no line in any included document — ` +
+            `this row extracts no pairing, so it enforces nothing while reading as enforced. ` +
+            `Either the documents do not carry the marker, or the pattern was never right`,
+        );
+      });
+    }
     if (deadRows.length > 0) {
       throw new Error(
         `archkeep: ${policySource ?? "the boundary config"} describes a workspace that does not ` +
@@ -977,8 +1106,14 @@ export async function check(
               // Complete means the run judged everything in scope: no
               // whole-file failure (unchecked), no unresolvable site (#595),
               // and at least one file analyzed (#599 — a run that judged
-              // nothing has no verdict to claim).
-              complete: unchecked === 0 && blindSpotCount === 0 && analyzed > 0,
+              // nothing has no verdict to claim). Read from the one predicate
+              // `verdictFor`'s decision face reads, so this field and the
+              // envelope's `decision.coverageComplete` are one derivation —
+              // the counts are this command's (the go.work/tsconfig failures
+              // pushed above and the accepted files withdrawn above make the
+              // universe wider than `commandContext.analysis`), the law is
+              // not.
+              complete: coverageComplete({ unchecked, blindSpotCount, analyzed }),
               projects: Object.keys(graph.nodes).length,
               analyzedFiles: analyzed,
               imports: imports.length,
@@ -1029,6 +1164,31 @@ export async function check(
                       judged: declaredEdges.judged,
                       findings: declaredEdges.findings,
                     },
+              // The document track is a policy DECLARATION, so it takes the
+              // same omitted-key-not-null discipline the intent/fitness/
+              // customRules blocks below state: a workspace whose policy
+              // declares no `markdown` block gets no key at all, and its
+              // envelope is byte-identical to the one it got before this
+              // section existed. The findings themselves are NOT restated
+              // here — they are members of `violations` above (sorted with,
+              // suppressible by, and counted into the verdict exactly like
+              // every import-site violation), so an array here would be one
+              // fact counted in two places; the block states what the track
+              // DID: how many documents the globs selected, how many markers
+              // they carried, where each resolution went.
+              ...(markdownTrack === null
+                ? {}
+                : {
+                    markdown: {
+                      checked: true,
+                      documents: markdownTrack.documents,
+                      judged: markdownTrack.judged,
+                      resolved: markdownTrack.resolved,
+                      ...(markdownTrack.selfPaired > 0
+                        ? { selfPaired: markdownTrack.selfPaired }
+                        : {}),
+                    },
+                  }),
               // Intent is a governance DECLARATION, absent when the workspace
               // chose not to make one: the key is omitted, never written as
               // null — the design contract `docs/reference/json-output.md` will

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/context-command.mjs

@@ -32,16 +32,12 @@
  * than explaining constraints from a graph whose edges silently under-represent
  * the real architecture.
  */
-import {
-  blindSpotRows,
-  isWholeFileFailure,
-  unresolvableLiteralCount,
-} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { judgeEdge } from "../rules/edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatContextReport } from "../report/context-text.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
@@ -150,27 +146,23 @@ export function contextCommand(projectName, commandContext, config) {
     );
   }
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // The same completeness `check` claims (#595, #599): unjudged sites and
-  // a zero-analyzed run defeat it here exactly as they do there, so a
-  // context report cannot look complete over a tree the run could not
-  // fully read.
-  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
-  const complete =
-    notAnalyzed.length === 0 && blindSpotCount === 0 && commandContext.analysis.analyzed > 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The completeness verdict is the shared constructor's, not this file's —
+  // the same law `graph`/`discover` run (#595, #599): unjudged sites and a
+  // zero-analyzed run defeat it here exactly as they do there, so a context
+  // report cannot look complete over a tree the run could not fully read
+  // while the faces beside it refuse the same tree. The restatement this
+  // replaces carried all three axes, so composing it moves no byte on any
+  // input.
+  const verdict = coverageVerdict(commandContext);
+  const { complete, status, exitCode } = verdict;
 
   const coverage = {
     complete,
     projects: Object.keys(graph.nodes).length,
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
-    notAnalyzed,
-    blindSpots: blindSpotRows(commandContext.analysis.failures),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependency with no violations here may still violate npm-ban, circular-dependency, " +

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/coverage-verdict.mjs

@@ -49,7 +49,7 @@ import {
   isWholeFileFailure,
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
-import { EXIT, coverageIncompleteReasons } from "../verdict.mjs";
+import { EXIT, coverageComplete, coverageIncompleteReasons } from "../verdict.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatCoverageIncomplete } from "../report/text.mjs";
@@ -96,7 +96,17 @@ export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
   const blindSpots = blindSpotRows(analysis.failures);
   const blindSpotCount = unresolvableLiteralCount(analysis.failures);
-  const complete = notAnalyzed.length === 0 && blindSpotCount === 0 && analysis.analyzed > 0;
+  // The conjunction is `../verdict.mjs`'s `coverageComplete` — the same
+  // predicate `verdictFor`'s decision face reads, so `check`'s envelope
+  // cannot carry a `coverage.complete` and a `decision.coverageComplete`
+  // that disagree about one run. The predicate is defined there, not here,
+  // because `verdictFor` needs it and this module already imports from that
+  // one: the reverse import would be a cycle.
+  const complete = coverageComplete({
+    unchecked: notAnalyzed.length,
+    blindSpotCount,
+    analyzed: analysis.analyzed,
+  });
   return {
     notAnalyzed,
     blindSpots,

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

@@ -48,10 +48,11 @@
 import { readFileSync } from "node:fs";
 
 import { canonicalJsonReplacer } from "../canonical.mjs";
+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.
@@ -337,6 +338,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);
@@ -518,11 +520,6 @@ export function providerMismatch(baselineProvider, currentProvider) {
   );
 }
 
-/** Non-empty plain-object guard used across validation. */
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /** Describes a value for error messages without dumping it. */
 function describe(value) {
   if (value === null) return "null";

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,
@@ -161,6 +162,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 +273,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 +301,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 +396,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";
@@ -810,26 +834,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

package/src/commands/drift.mjs

@@ -250,7 +250,7 @@ export async function driftForCheck(commandContext, io = {}) {
  * @param {object} intent The normalized intent model.
  * @returns {{kind: string, row: object}[]}
  */
-export function intentDecisionRefRows(intent) {
+function intentDecisionRefRows(intent) {
   return governanceIntentRows(intent).filter(
     ({ row }) => typeof row?.decisionRef === "string" && row.decisionRef.trim() !== "",
   );