@ecoma-io/archkeep 0.24.0 → 0.25.0

package/src/governance/discovery-proposal.mjs

@@ -61,7 +61,7 @@
  * The uncertainty marker vocabulary — three values, the bound the "bounded
  * uncertainty markers" test asserts.
  */
-export const CONFIDENCE = Object.freeze(["high", "medium", "low"]);
+export const CONFIDENCE = Object.freeze(["high", "medium", "low"]); // used by its own test
 
 /**
  * The component model: every project's root's first path segment (`""` at the
@@ -73,6 +73,7 @@ export const CONFIDENCE = Object.freeze(["high", "medium", "low"]);
  * @returns {Map<string, {name: string, root: string, tags: string[]}[]>}
  */
 export function componentsByDirectory(projects) {
+  // used by its own test
   const buckets = new Map();
   for (const project of projects) {
     const component = project.root === "" ? "" : project.root.split("/")[0];
@@ -101,6 +102,7 @@ export function componentsByDirectory(projects) {
  * @returns {{tag: string, component: string, members: string[]}[]} Sorted.
  */
 export function dominantTags(components) {
+  // used by its own test
   const tags = [];
   for (const [component, members] of components) {
     if (members.length < 2) continue;
@@ -136,6 +138,7 @@ export function dominantTags(components) {
  * @returns {{axis: string, values: string[]}[]} Sorted by axis.
  */
 export function tagAxes(projects) {
+  // used by its own test
   const byAxis = new Map();
   for (const project of projects) {
     for (const tag of project.tags) {
@@ -169,7 +172,7 @@ export function tagAxes(projects) {
  * @param {string} target
  * @returns {boolean}
  */
-export function sameComponent(components, source, target) {
+function sameComponent(components, source, target) {
   for (const members of components.values()) {
     if (members.some((m) => m.name === source) && members.some((m) => m.name === target)) {
       return true;
@@ -198,6 +201,7 @@ export function sameComponent(components, source, target) {
  *   component?: string, evidence: object[], confidence: string}[]} Sorted.
  */
 export function boundaryAssertions({ projects, edges }) {
+  // used by its own test
   const components = componentsByDirectory(projects);
   const projectNames = new Set(projects.map((p) => p.name));
   /** @type {{kind: "edge"|"component", source: string|undefined, target: string|undefined,
@@ -256,6 +260,7 @@ export function boundaryAssertions({ projects, edges }) {
  *   evidence: object[], confidence: string}[]} Sorted.
  */
 export function tagVocabulary(projects) {
+  // used by its own test
   const components = componentsByDirectory(projects);
   /** @type {{kind: "observed"|"suggested", tag: string|undefined, axis: string|undefined,
    *   component: string|undefined, members: string[]|undefined, values: string[]|undefined,
@@ -308,6 +313,7 @@ export function tagVocabulary(projects) {
  *   component?: string, evidence: object[], confidence: string}[]} Sorted.
  */
 export function candidateRules(assertions) {
+  // used by its own test
   /** @type {{kind: "noDependency"|"boundary", source: string|undefined, target: string|undefined,
    *   component: string|undefined, evidence: object[], confidence: "medium"}[]} */
   const rules = [];

package/src/governance/evolution-event.mjs

@@ -80,6 +80,48 @@ export function eventId(event) {
   return createHash("sha256").update(eventDedupeKey(event)).digest("hex");
 }
 
+/**
+ * The refusal law every command that writes an evolution event holds: the
+ * write happens only from a reproducible identity — a committed, clean head
+ * and a clean base. A commitless head has no revision to name (the event
+ * would serialize its `head` as `{}`, and every run over that workspace
+ * would collide on one event id); a dirty tree names a commit its evidence
+ * does not back, so two distinct uncommitted states collapse onto one event
+ * id — a later transition is silently lost or aliased. That is the silent
+ * direction this repository refuses, so the write is refused loudly instead.
+ * The same run without `--event-out` stays a byte-identical in-memory run —
+ * the gate is the event write, never the verdict.
+ *
+ * The messages are the `delta` command's original wording, parameterized by
+ * the writing command's label. Consumers match on these strings (a refusal
+ * is part of a run's observable contract), so the wording is frozen here —
+ * one home, one copy, no per-command drift.
+ *
+ * @param {{label: "delta"|"change", headCommit: string|undefined,
+ *   baseDirty: boolean, headDirty: boolean}} input `label` names the writing
+ *   command in the refusal message; `headCommit` is the head revision the
+ *   event would carry (`undefined` when provenance could not resolve one);
+ *   `baseDirty`/`headDirty` are the two sides' provenance dirty bits.
+ * @returns {void} Throws on every state that cannot produce a reproducible
+ *   event identity.
+ */
+export function assertReproducibleEventIdentity({ label, headCommit, baseDirty, headDirty }) {
+  if (typeof headCommit !== "string") {
+    throw new Error(
+      `archkeep: refusing to write a ${label} 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 (baseDirty === true || headDirty === true) {
+    throw new Error(
+      `archkeep: refusing to write a ${label} 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.",
+    );
+  }
+}
+
 /**
  * The digest of a normalized change-intent's DECLARATIVE parts only:
  * `{version, base, projects, edges, constraints}`. The prose `summary` is

package/src/governance/fitness-registry.mjs

@@ -52,7 +52,7 @@ import { languageOf } from "../analysis/registry.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "./row-schema.mjs";
-import { fitnessVerdict, isVerdict } from "./verdict.mjs";
+import { VERDICTS, fitnessVerdict, isVerdict } from "./verdict.mjs";
 import {
   coverageMinimum,
   cycleFree,
@@ -65,6 +65,7 @@ import {
 
 /** The condition types the registry can evaluate. */
 export const CONDITION_TYPES = Object.freeze([
+  // used by its own test
   "cycle-free",
   "layer-dependency",
   "tag-conformance",
@@ -327,6 +328,7 @@ function tagAxisIsolationViolations(condition, at) {
  * @returns {object} A verdict record from `fitnessVerdict`.
  */
 export function judgeFitnessRow(row, graph, analysis, intent, suppressions) {
+  // used by its own test
   const names = resolveMembers(row.match, graph.nodes);
   if (names.length === 0) {
     return fitnessVerdict({
@@ -479,6 +481,19 @@ export function evaluateFitness(rows, snapshot) {
  * @returns {{verdict: "pass"|"fail"|"unknown"|"not_applicable", decisions: object[]}}
  */
 export function fitnessVerdictFor(decisions) {
+  // The fold is an overall-verdict constructor, so it owns the same vocabulary
+  // latch `buildDecision` does rather than trusting every caller to have
+  // latched its rows first: a stranger verdict matches none of the checks
+  // below and falls through to `pass` — the loudest clean state a governance
+  // run can emit, fabricated from a row nobody judged.
+  for (const decision of decisions) {
+    if (!isVerdict(decision.verdict)) {
+      throw new Error(
+        `archkeep: refusing to fold a fitness row whose verdict is ${describe(decision.verdict)} — ` +
+          `expected one of ${VERDICTS.join(", ")}. This is a bug in the rule that judged the row.`,
+      );
+    }
+  }
   if (decisions.some((d) => d.verdict === "fail")) return { verdict: "fail", decisions };
   if (decisions.some((d) => d.verdict === "unknown")) return { verdict: "unknown", decisions };
   if (decisions.length === 0 || decisions.every((d) => d.verdict === "not_applicable")) {

package/src/governance/preset-fingerprints.json

@@ -1,16 +1,16 @@
 {
-  "clean-architecture#clean-architecture": "28e4dc572cf278e69f05c01bed020cda425ebd7b11bfe04804f21d2f1bbdcb69",
-  "clean-architecture#clean-architecture-pure-core": "85e7d5a36759169190dab1d871acc1d2c733b145306ef33f7b161e641c9f78e4",
-  "ddd-bounded-contexts#ddd-bounded-contexts": "8ec7feb0e6dbf64373e1aaf5bfc9d53d6299de3c11fb38955a5a3857fac04f09",
-  "ddd-bounded-contexts#ddd-bounded-contexts-isolated": "8ac4183559010abf01e20ae50bffd7611b78417b4af531af6c7a15fbcdc443da",
-  "ddd-bounded-contexts#ddd-bounded-contexts-partitioned": "982f90d0718c2bdd6874411964ef9baa379ee5f9c849404cb9cde2ab7aaccc19",
-  "hexagonal#hexagonal": "08e57312c449a79ce32c4248931e7d9488441fa47f8638fb780fd02602442003",
-  "hexagonal#hexagonal-pure-domain": "3a43406883c6e182592ff1f47347c6f9a04f04690300ea5b9260877dea2f134f",
-  "layered#layered-relaxed": "ad2912594d26a270b6139c6561454ef01e2bf6e2214d2d8ec57afcc8fee11467",
-  "layered#layered-strict": "26af569cb6c352a223e09e18e3e7c9817d5c1cb53575be46ffad950bd2f84be2",
-  "modular-monolith#modular-monolith": "4b3517e4d4ae1357e675b947d7e4845260fa6d75122f40d8e75ad202d910606a",
-  "modular-monolith#modular-monolith-sealed-kernel": "124a7bafd43abbd87e5218146219d57af6010e9374d80f0c3c1d2ac13a8e2677",
-  "modular-monolith#modular-monolith-sealed-modules": "772d74fd8bbdb85ea39c5e38bdb8193a4f069ace8b458bff96943d5a243f5d25",
-  "vertical-slice#vertical-slice": "5a4a17b041bb57046ba0f42a28032afb933c1f28ee3ecaa1262c706786c14dc7",
-  "vertical-slice#vertical-slice-sealed-kernel": "efbcd5617f3c96f43b02f622cd79c4b27e49af907329ec9dcd9ee77549eb49fa"
+  "clean-architecture#clean-architecture": "5f32ab7e98b5e49ed832bbb4dd97d6757abdf607ca85dbe70a3fc9515493fcb4",
+  "clean-architecture#clean-architecture-pure-core": "9728201a3f57fc7db38747e58cd277fdff54277a34d3997b6ae67827dc547404",
+  "ddd-bounded-contexts#ddd-bounded-contexts": "6d9f733c915e3ab33932d5150d0651a4603a7869625a7ec55afc7bb3a0328871",
+  "ddd-bounded-contexts#ddd-bounded-contexts-isolated": "6dd7e4360b8d8fb0359148af1360bc8986526b2be51c6b7a647f7fb414e5a0a3",
+  "ddd-bounded-contexts#ddd-bounded-contexts-partitioned": "93b15523dda77be5aca06806d0235eefa32a504e411d4fcf6962a7c1bec9e719",
+  "hexagonal#hexagonal": "86321ee12d3e304567c988a5fb04ef17d040763c45f021a9b1f64c3852ea7c12",
+  "hexagonal#hexagonal-pure-domain": "2aa8efe7d71a4c731aee61c46961d6bba8d239af68909a71595488374c5de80a",
+  "layered#layered-relaxed": "ffc0f268d37b88c97eb8c783283adbf9779850750b3e21c780c7851d936fb6b4",
+  "layered#layered-strict": "4c90afb7cfe1e273fedce2a85e2403a1f354a4a038f1c872ad103f1c2f1d7df1",
+  "modular-monolith#modular-monolith": "634ef3e706d06780bfd72a57c1a4a3c0be2d4163b0728fc734f4bd4e5da8cbe1",
+  "modular-monolith#modular-monolith-sealed-kernel": "372cabc2d618aea8a0aa8b284e8be93a062dd5ebe22f64af52bc1fa785826a97",
+  "modular-monolith#modular-monolith-sealed-modules": "0ff0b39328d50fb3622dc84fb4d7b26fd567a5110437536aaa586e29ad4b8c92",
+  "vertical-slice#vertical-slice": "4df057e4ec1f92dae8aada8203d18869c6e283764f66a9f96f1c425304436f34",
+  "vertical-slice#vertical-slice-sealed-kernel": "1d1fbaf268a7afc851e6e4a126bd586dd0ca9547cf9d654e44dcf0dd99537f78"
 }

package/src/governance/profile-registry.mjs

@@ -74,7 +74,7 @@ import { describe, isPlainObject } from "../values.mjs";
 const REGISTRY_KEYS = ["profiles", "version", "$schema"];
 
 /** A version a reader that predates it must refuse, per `docs/reference/profiles.md`. */
-export const PROFILE_REGISTRY_SCHEMA_VERSION = 1;
+const PROFILE_REGISTRY_SCHEMA_VERSION = 1;
 
 /** The registry's schema version: stated, or schema 1 when absent. */
 function registrySchemaVersion(raw) {
@@ -112,6 +112,7 @@ const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/u;
 
 /** A profile's declared block, kept ONLY for this command's own data. */
 export function listNames(registry) {
+  // used by its own test
   return registry.profiles.map((profile) => profile.name);
 }
 
@@ -126,6 +127,7 @@ export function listNames(registry) {
  * @returns {string[]}
  */
 export function profileRegistryViolations(raw) {
+  // used by its own test
   if (!isPlainObject(raw)) {
     return [`profiles: expected a JSON object, got ${describe(raw)}`];
   }
@@ -201,6 +203,7 @@ export function profileRegistryViolations(raw) {
  * @returns {string[]}
  */
 export function profileReferenceViolations(profiles) {
+  // used by its own test
   const violations = [];
   const byName = new Map(profiles.map((profile) => [profile.name, profile]));
   for (const profile of profiles) {
@@ -250,6 +253,7 @@ export function profileReferenceViolations(profiles) {
  *   silently resolved as "no profile".
  */
 export function resolveProfile(profiles, name, seen = new Set()) {
+  // used by its own test
   const profile = profiles.find((candidate) => candidate.name === name);
   if (profile === undefined) {
     throw new Error(
@@ -302,6 +306,7 @@ export function resolveProfile(profiles, name, seen = new Set()) {
  *   profile-registry or reference-graph defect.
  */
 export function loadProfileRegistry(path, { readFile = defaultProfileIo.readFile } = {}) {
+  // used by its own test
   const text = readFile(path);
   if (text === null) {
     throw new Error(`archkeep: cannot read profiles file ${path}`);
@@ -336,13 +341,27 @@ export function loadProfileRegistry(path, { readFile = defaultProfileIo.readFile
  * @param {string} profileName The profile to resolve.
  * @param {string} sourceLabel What failed, named in the thrown message.
  * @param {{readFile?: (path: string) => string|null}} [io]
- * @returns {{depConstraints: object[], options: object, suppressions: object[], fitness?: object[]}}
+ * @returns {{depConstraints: object[], options: object, suppressions: object[], fitness?: object[],
+ *   profile: string}} `profile` is the selection the policy was resolved by,
+ *   carried on the policy itself so the law's identity travels with it —
+ *   `../commands/graph.mjs`'s `computePolicyFingerprint` reads it, and the
+ *   fingerprint is the one policy fact that travels between captures
+ *   (`delta`, `diff`, `history`).
  * @throws {Error} when the registry or the named profile is defective.
  */
 export function profilePolicy(registryPath, profileName, sourceLabel, io = {}) {
   const registry = loadProfileRegistry(registryPath, io);
   const effective = resolveProfile(registry.profiles, profileName);
-  return policyFrom(effective, `${sourceLabel} (profile "${profileName}")`);
+  return {
+    ...policyFrom(effective, `${sourceLabel} (profile "${profileName}")`),
+    // The selection rides on the policy it produced: two profiles whose
+    // blocks converge resolve to the same fields, so without this key a
+    // switch between them resolves to the same fingerprint and a `delta`
+    // across the switch classifies as no law change. The NAME, never
+    // `registryPath` — a path is machine-local, and a fingerprint that
+    // differs between a laptop and CI reports a change nobody made.
+    profile: profileName,
+  };
 }
 
 /**

package/src/governance/provenance-record.mjs

@@ -52,7 +52,7 @@ import { clockViolations } from "./clock.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 
 /** The only keys a validated `origin` may carry. */
-export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]);
+export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]); // used by its own test
 
 /**
  * @typedef {object} OriginRecord
@@ -135,6 +135,7 @@ export function originViolations(raw, io = {}) {
  * @throws {Error} naming every violation at once, prefixed by `at`.
  */
 export function validateOrigin(raw, io = {}, at = "origin") {
+  // used by its own test
   const violations = originViolations(raw, io).map((message) =>
     message.startsWith("origin.")
       ? `${at}.${message.slice("origin.".length)}`
@@ -181,6 +182,7 @@ export function recordOrigin({ by, tool, clock }) {
  * change, supersession, and bindings change is recorded as one of these.
  */
 export const DECISION_LIFECYCLE_KINDS = Object.freeze([
+  // used by its own test
   "status-transition",
   "supersession",
   "bindings-change",
@@ -234,6 +236,7 @@ export const DECISION_LIFECYCLE_KINDS = Object.freeze([
  *   the registry's `ADR_STATUSES`, a no-op event, or an invalid origin/clock.
  */
 export function recordDecisionLifecycle({
+  // used by its own test
   kind,
   decisionId,
   from = null,

package/src/governance/reconcile-score.mjs

@@ -70,6 +70,7 @@ function boundaryKey(from, to) {
 
 /** The severity a state earns — the sort key a ranked proposal list uses. */
 export const SEVERITY_ORDER = Object.freeze({
+  // used by its own test
   unexpected: 4,
   absent: 3,
   match: 0,
@@ -133,6 +134,7 @@ function intentKeys(intent) {
  * @returns {{project: ScoredElement, tags: ScoredElement[]}}
  */
 export function scoreProject(project, keys, requiredTagsByProject) {
+  // used by its own test
   const tags = project.data?.tags ?? project.tags ?? [];
   const requiredTags = requiredTagsByProject.get(project.name) ?? [];
   const element = { plane: "project", name: project.name };
@@ -209,6 +211,7 @@ export function scoreProject(project, keys, requiredTagsByProject) {
  * @returns {ScoredElement}
  */
 export function scoreEdge(edge, keys, intentForbiddenPairs, tagForbiddenPairs) {
+  // used by its own test
   const key = `${edge.source} → ${edge.target}`;
   const element = { plane: "edge", name: key, intentRow: null };
 
@@ -279,6 +282,7 @@ export function scoreEdge(edge, keys, intentForbiddenPairs, tagForbiddenPairs) {
  * @returns {ScoredElement[]}
  */
 export function scoreIntentRows(intent, judgeVerdict, observed, tagsByProject) {
+  // used by its own test
   const rows = [];
   const observedNames = new Set(observed.projects.map((p) => p.name));
   const observedEdgeKeys = new Set(observed.edges.map((e) => `${e.source} → ${e.target}`));

package/src/governance/row-schema.mjs

@@ -94,6 +94,7 @@ export const GOVERNANCE_ROW_KEYS = Object.freeze([
  * @returns {string[]}
  */
 export function governanceBlockViolations(raw, at) {
+  // used by its own test
   if (!isPlainObject(raw)) return [];
   const violations = [];
 

package/src/governance/verdict.mjs

@@ -43,11 +43,14 @@
  * path — a path, never a second implementation.
  */
 
+import { describe, isNonEmptyString } from "../values.mjs";
+
 /** The four canonical verdict values. */
 export const VERDICTS = Object.freeze(["pass", "fail", "unknown", "not_applicable"]);
 
 /** The single mapping from an envelope status to a verdict. */
 export const VERDICT_FOR_STATUS = Object.freeze({
+  // used by its own test
   ok: "pass",
   findings: "fail",
   "no-verdict": "unknown",
@@ -112,7 +115,7 @@ export function fitnessVerdict({ verdict, name, evidence, message, rows, notAppl
         `expected one of ${VERDICTS.join(", ")}.`,
     );
   }
-  if (verdict === "not_applicable" && notApplicableReason === undefined) {
+  if (verdict === "not_applicable" && !isNonEmptyString(notApplicableReason)) {
     throw new Error(
       `archkeep: fitness function "${name}" returned "not_applicable" without ` +
         `notApplicableReason — invariant I4: the reader must be told why the ` +
@@ -205,6 +208,21 @@ export function buildDecision(run) {
     throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
   }
   const verdict = run.verdict ?? verdictForStatus(run.status);
+  // The vocabulary latch. `verdictForStatus` cannot produce a stranger, so
+  // this refuses exactly the explicitly-passed verdicts — and it must run
+  // BEFORE the status-conflict check below, so a malformed verdict reports
+  // the vocabulary it violated rather than a conflict it never had. Without
+  // this latch, "perhaps", "PASS", `42` and `{}` fell through the
+  // pass/fail/unknown arms into the not_applicable one and SHIPPED whenever
+  // `notApplicableReason` happened to be truthy — a byte-legal decision
+  // about a workspace nobody judged.
+  if (!isVerdict(verdict)) {
+    throw new Error(
+      `archkeep: refusing to build a decision with verdict ${describe(run.verdict)} — ` +
+        `expected one of ${VERDICTS.join(", ")}. This is a bug in the command that ` +
+        `built the decision.`,
+    );
+  }
   if (
     run.verdict !== undefined &&
     run.status !== undefined &&
@@ -259,17 +277,32 @@ export function buildDecision(run) {
   }
 
   if (verdict === "unknown") {
+    // An absent reason (undefined/null) still defaults to the generic one —
+    // absence is not emptiness. A SUPPLIED reason must actually say
+    // something: "" and "   " are byte-present but semantically absent, and
+    // a non-string reason would ship a `typeof` artifact where the reader
+    // was promised a sentence (I3).
     const reason =
       run.reason ??
       (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
+    if (!isNonEmptyString(reason)) {
+      throw new Error(
+        `archkeep: refusing to emit an "unknown" decision with a ${describe(run.reason)} reason — ` +
+          `I3 requires a non-empty reason naming why no verdict was reached. ` +
+          `This is a bug in the command that built the decision.`,
+      );
+    }
     return withSampleTime({ verdict, reason }, run.sampleTime);
   }
 
-  // verdict === "not_applicable" (I4).
-  if (!run.notApplicableReason) {
+  // verdict === "not_applicable" (I4). The reason must be a string a reader
+  // could act on — the falsy check this replaces refused "" but SHIPPED
+  // "   " and non-strings, the same byte-present-semantically-absent hole.
+  if (!isNonEmptyString(run.notApplicableReason)) {
     throw new Error(
       `archkeep: refusing to emit a "not_applicable" decision without notApplicableReason — ` +
-        `"did not apply" and "did not run" must never be indistinguishable. ` +
+        `"did not apply" and "did not run" must never be indistinguishable, and a reason of ` +
+        `${describe(run.notApplicableReason)} tells the reader nothing. ` +
         `This is a bug in the command that built the decision.`,
     );
   }

package/src/governance/waiver.mjs

@@ -55,6 +55,7 @@ export function isWaiver(row) {
  * @returns {number}
  */
 export function expiresAtMs(row) {
+  // used by its own test
   return Date.parse(String(row.expiresAt));
 }
 

package/src/intent/intent-manifest.json

@@ -25,7 +25,7 @@
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
-          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
+          "assertion": "commands/context.mjs imports providers — the designated orchestration path",
           "sha256": "b505e3a7476c64af4b2daeb106e2f9cb05be82e314604229d508dda04b629a98"
         }
       ],
@@ -40,7 +40,7 @@
           "type": "behavioral-test",
           "path": "src/report/json.test.mjs",
           "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement",
-          "sha256": "a371d36b89b10c5a4bda4d9e9a2e3bde114256c1377eb95699c9f0f195aabc4a"
+          "sha256": "8f587d3bd3f06519b90f760e7eafc091ca4e4cf26b67929ab180abe35c36c8f0"
         },
         {
           "type": "source-evidence",
@@ -66,13 +66,13 @@
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes (three workspaces differing only in project tag fields compared byte-for-byte)",
-          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "type": "architecture-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "the gate walks every production analysis module and fails when judging vocabulary (judge/forbid/permit/allow/ban) appears in code",
-          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "type": "source-evidence",
@@ -103,14 +103,20 @@
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
+          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped",
+          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/report/json.mjs",
+          "assertion": "SCHEMA_VERSION = 2 — the envelope's schemaVersion constant",
+          "sha256": "090418f6f60dec51638976dff658c55f8a932012bfc7c8bc59952b0f03543340"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
+          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
         }
       ],
       "status": "proven"
@@ -130,7 +136,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         }
       ],
       "status": "proven"
@@ -150,7 +156,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         }
       ],
       "status": "proven"
@@ -230,7 +236,7 @@
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "depConstraints verdicts from judgeEdge agree with evaluate in both directions (violating edge found by both, legal edge reported by neither); explain includes the same violations as evaluate at a given site",
-          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "type": "behavioral-test",
@@ -260,7 +266,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         },
         {
           "type": "documentation",
@@ -286,7 +292,7 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison throughout; never localeCompare",
-          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
+          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
         }
       ],
       "status": "proven"

package/src/intent/mask-non-code.mjs

@@ -536,6 +536,7 @@ function scanTemplate(src, i) {
  *   same line structure.
  */
 export function maskNonCode(src) {
+  // used by its own test
   /**
    * Chunks of the result, joined once at the end. Code is copied through in
    * RUNS rather than a token at a time — `plainFrom` is where the current

package/src/lsp/diagnostics.mjs

@@ -38,7 +38,7 @@ import { DIAGNOSTIC_SEVERITY, SERVER_INFO } from "./protocol.mjs";
  * prints beside the message to say which tool spoke. Taken from the server's
  * own identity so the two can never disagree.
  */
-export const DIAGNOSTIC_SOURCE = SERVER_INFO.name;
+export const DIAGNOSTIC_SOURCE = SERVER_INFO.name; // used by its own test
 
 /**
  * The `code` on a diagnostic that reports the ABSENCE of a verdict rather than
@@ -46,7 +46,7 @@ export const DIAGNOSTIC_SOURCE = SERVER_INFO.name;
  * against `MESSAGE_IDS` at load so a future upstream id cannot silently collide
  * with it.
  */
-export const ANALYSIS_FAILURE_CODE = "analysisFailure";
+export const ANALYSIS_FAILURE_CODE = "analysisFailure"; // used by its own test
 
 if (MESSAGE_IDS.includes(ANALYSIS_FAILURE_CODE)) {
   throw new Error(
@@ -100,6 +100,7 @@ const QUOTES = new Set(['"', "'", "`"]);
  * @returns {{start: {line: number, character: number}, end: {line: number, character: number}}}
  */
 export function rangeAt(at, lines) {
+  // used by its own test
   // A failure about the file as a whole carries no position (`contract.md`
   // fixes it as an explicit `null`). It gets the first line, whole: a
   // zero-width range at the origin renders as an invisible caret in most

package/src/lsp/protocol.mjs

@@ -95,7 +95,7 @@ export const DIAGNOSTIC_SEVERITY = Object.freeze({
  * more is not a supported conversation, and saying so beats waiting for bytes
  * that will never arrive.
  */
-export const MAX_CONTENT_LENGTH = 64 * 1024 * 1024;
+export const MAX_CONTENT_LENGTH = 64 * 1024 * 1024; // used by its own test
 
 /**
  * LSP `MessageType`, as `window/showMessage` reports it.
@@ -211,5 +211,6 @@ export function uriToPath(uri) {
  * @returns {string}
  */
 export function pathToUri(path) {
+  // used by its own test
   return pathToFileURL(path).href;
 }

package/src/lsp/server.mjs

@@ -292,6 +292,7 @@ const POLYGLOT_GRAPH_MANIFESTS = Object.freeze([
  * @returns {readonly string[]}
  */
 export function watchedFilesFor(options, { unresolved = false } = {}) {
+  // used by its own test
   return Object.freeze([
     ...(typeof options.boundaryConfig === "string" ? [options.boundaryConfig] : []),
     ...(unresolved
@@ -376,6 +377,7 @@ function markersAt(root) {
  *   convention chain can find while carrying files that need one.
  */
 export function readWorkspaceOptions(root) {
+  // used by its own test
   const { hasNx, hasNative } = markersAt(root);
   if (hasNx && hasNative) {
     throw new Error(
@@ -450,6 +452,7 @@ const WATCHER_REGISTRATION_ID = "archkeep/watched-files";
  * text than the one on screen.
  */
 export const SERVER_CAPABILITIES = Object.freeze({
+  // used by its own test
   textDocumentSync: Object.freeze({
     openClose: true,
     change: TEXT_DOCUMENT_SYNC_KIND.full,

package/src/lsp/workspace-index.mjs

@@ -156,7 +156,7 @@ export { PROJECT_CONFIG_FILE, nodeTypeOf, buildDependencies };
  * @returns {object} Whatever the JSON describes.
  * @throws {Error} when neither parser can read it.
  */
-export const parseProjectJson = parseNxJson;
+const parseProjectJson = parseNxJson;
 
 /**
  * Every file git considers part of the working tree, workspace-relative and
@@ -205,6 +205,7 @@ const directoryOf = (file) => {
  * @returns {{projects: {name: string, root: string, config: object}[], skipped: {file: string, reason: string}[]}}
  */
 export function discoverProjects({ files, readFile }) {
+  // used by its own test
   const projects = [];
   const skipped = [];
   for (const file of files) {
@@ -263,6 +264,7 @@ export function discoverProjects({ files, readFile }) {
  *   publishes the collision through `indexGaps`.
  */
 export function buildNodes(projects) {
+  // used by its own test
   // Null-prototype for the same reason `../providers/native/graph.mjs` and
   // `../providers/moon.mjs` use them: every key here is a project NAME, and
   // project names come from a `project.json`'s own `name` field —