@ecoma-io/archkeep 0.23.0 → 0.24.1

package/src/errors.mjs

@@ -23,7 +23,10 @@
  * (`../AGENTS.md`, check's four exit codes).
  *
  * One class, nothing else exported: a second class needs a catch site that
- * treats two of these mistakes differently, and none does.
+ * treats two of these mistakes differently, and none does. Beside it sits the
+ * one error-SHAPE predicate the engine shares (`isEnoent` below) — a test of
+ * what a caught value looks like, not a decision about what one means, which
+ * is why it lives with the error primitives rather than at any catch site.
  */
 export class UsageError extends Error {
   /**
@@ -34,3 +37,22 @@ export class UsageError extends Error {
     this.name = "UsageError";
   }
 }
+
+/**
+ * Is this caught value the filesystem's "no such file or directory"?
+ *
+ * Node's `fs` throws the raw error with `code: "ENOENT"` set directly;
+ * `./process.mjs`'s `runProcess` wraps its child's failure and carries the
+ * original on `cause` — so the shape arrives both ways, and every site that
+ * distinguishes "absent" from "could not read" was spelling the test by hand
+ * (`#652`). The two legs together are the one definition; a catch site adds
+ * its own meaning on top (absent store, absent registry, install Moon), which
+ * is exactly the logic this predicate does not own.
+ *
+ * @param {unknown} error The caught value, of any shape.
+ * @returns {boolean}
+ */
+export function isEnoent(error) {
+  const thrown = /** @type {{code?: unknown, cause?: {code?: unknown}}|null|undefined} */ (error);
+  return thrown?.code === "ENOENT" || thrown?.cause?.code === "ENOENT";
+}

package/src/eslint-config.mjs

@@ -71,6 +71,8 @@
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
+import { isPlainObject } from "./values.mjs";
+
 /** The severities ESLint itself recognises for a rule entry. */
 const KNOWN_SEVERITIES = new Set(["off", "warn", "error", 0, 1, 2]);
 const OFF_SEVERITIES = new Set(["off", 0]);
@@ -94,11 +96,6 @@ const OFF_SEVERITIES = new Set(["off", 0]);
 // one — a stricter refusal than strictly necessary, not a silent guess.
 const BARE_EXTENSION_GLOB = /^\*\*\/\*\.[A-Za-z0-9]+$/u;
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** A rule entry's severity — the bare value itself, or the `[severity, …]` pair's first element. */
 function severityOf(value) {
   return Array.isArray(value) ? value[0] : value;
@@ -238,6 +235,7 @@ function parseRuleValue(value, index) {
  *   severity-only fallback has been applied.
  */
 export function extractBoundaryRule(flatConfig, readerOptions = {}) {
+  // used by its own test
   const pathScopedMode = readerOptions.pathScoped ?? "refuse";
   if (pathScopedMode !== "refuse" && pathScopedMode !== "bind-tree-wide") {
     throw new Error(

package/src/fixtures/evolution-lifecycle/workspace.mjs

@@ -36,6 +36,7 @@ const IDENTITY = ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpg
  * than blocking the worker thread forever.
  */
 export function git(cwd, ...args) {
+  // used by its own test
   return execFileSync("git", args, {
     cwd,
     env: environmentForTree(),
@@ -47,12 +48,14 @@ export function git(cwd, ...args) {
 
 /** Writes `text` to `root/relativePath`, creating parent directories. */
 export function writeIn(root, relativePath, text) {
+  // used by its own test
   mkdirSync(join(root, relativePath, ".."), { recursive: true });
   writeFileSync(join(root, relativePath), text);
 }
 
 /** Stages every change and commits with the fixture identity; returns the SHA. */
 export function commit(root, message) {
+  // used by its own test
   git(root, ...IDENTITY, "add", "-A");
   git(root, ...IDENTITY, "commit", "-q", "-m", message);
   return git(root, "rev-parse", "HEAD").trim();
@@ -109,12 +112,12 @@ const OPTIONS = `export const moduleBoundaryOptions = {
 };
 `;
 
-export const ALPHA_CLEAN = `package alpha
+export const ALPHA_CLEAN = `package alpha // used by its own test
 
 func Name() string { return "alpha" }
 `;
 
-export const ALPHA_REACHING = `package alpha
+export const ALPHA_REACHING = `package alpha // used by its own test
 
 import (
 	"example.com/beta"
@@ -123,7 +126,7 @@ import (
 func Name() string { return "alpha" + beta.Suffix() }
 `;
 
-export const BETA = `package beta
+export const BETA = `package beta // used by its own test
 
 func Suffix() string { return "-beta" }
 `;
@@ -136,6 +139,7 @@ func Suffix() string { return "-beta" }
  * @param {{rows?: string, fitness?: string}} [law]
  */
 export function writeLaw(root, { rows = "", fitness } = {}) {
+  // used by its own test
   writeIn(
     root,
     "module-boundaries.config.mjs",
@@ -149,7 +153,7 @@ export function writeLaw(root, { rows = "", fitness } = {}) {
  * evolution CLI integration fixtures use, so an allowed alpha→beta edge never
  * trips a boundary rule.
  */
-export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags: ["layer:b"] },`;
+export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags: ["layer:b"] },`; // used by its own test
 
 /**
  * Writes `architecture-intent.json` at `root`. `sections` carries the top-level
@@ -157,6 +161,7 @@ export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags:
  * `dependencies`, …); `version` defaults to "1".
  */
 export function writeIntent(root, sections) {
+  // used by its own test
   writeIn(root, "architecture-intent.json", `${JSON.stringify(sections, null, 2)}\n`);
 }
 
@@ -165,6 +170,7 @@ export function writeIntent(root, sections) {
  * `record` is the frontmatter map (`{id, status, supersedes?, bindings?}`).
  */
 export function writeAdr(root, filename, record) {
+  // used by its own test
   const lines = ["---", `id: ${record.id}`, `status: ${record.status}`];
   if (record.supersedes?.length) {
     lines.push("supersedes:");
@@ -184,6 +190,7 @@ export function writeAdr(root, filename, record) {
  * (`../cli.mjs`), never a shell-out to a binary named `archkeep`.
  */
 export async function runEvolution(cwd, argv) {
+  // used by its own test
   const out = [];
   const err = [];
   const exitCode = await runCli(argv, {
@@ -201,6 +208,7 @@ export async function runEvolution(cwd, argv) {
  * @param {{head?: string, eventOut?: string, format?: string}} [options]
  */
 export function evolutionArgs(base, { head, eventOut, format = "json" } = {}) {
+  // used by its own test
   const args = ["evolution", "--base", base];
   if (head) args.push("--head", head);
   if (eventOut) args.push("--event-out", eventOut);
@@ -212,6 +220,7 @@ export function evolutionArgs(base, { head, eventOut, format = "json" } = {}) {
  * Parses the `--format json` envelope out of a successful evolution run.
  */
 export function parseEnvelope(run) {
+  // used by its own test
   if (run.exitCode !== EXIT.ok) throw new Error(`evolution exited ${run.exitCode}: ${run.err}`);
   return JSON.parse(run.out);
 }
@@ -226,6 +235,7 @@ export function readEvents(dir) {
 
 /** The event store's file names in `dir`, in filename order. */
 export function eventFiles(dir) {
+  // used by its own test
   return readdirSync(dir)
     .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
     .sort();
@@ -233,5 +243,6 @@ export function eventFiles(dir) {
 
 /** Removes a throwaway workspace. */
 export function dispose(root) {
+  // used by its own test
   rmSync(root, { recursive: true, force: true });
 }

package/src/go-work.mjs

@@ -113,7 +113,7 @@ const IDENTIFIER_BOUNDARY = new Set([" ", "\t", "\r", '"', "`", "(", ")"]);
  * @throws {Error} on an unterminated string — a string left open would
  *   otherwise swallow the rest of the line silently.
  */
-export function tokenizeGoWorkLine(line, lineNumber) {
+function tokenizeGoWorkLine(line, lineNumber) {
   const tokens = [];
   let at = 0;
   while (at < line.length) {

package/src/governance/adr-registry.mjs

@@ -91,6 +91,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "
 import { join } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 import { describe } from "../values.mjs";
 
 /** The directory, relative to a workspace root, where ADR files live. */
@@ -123,7 +124,7 @@ export function hasAuthority(status) {
  * format outgrows 999 records without breaking; the slug is dash-separated
  * lowercase words.
  */
-export const ADR_FILE_PATTERN = /^(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/u;
+const ADR_FILE_PATTERN = /^(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/u;
 
 /** An ADR id — `NNN-slug` — must match the filename it lives in. */
 export const ADR_ID_PATTERN = /^\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -235,6 +236,7 @@ function parseProseFields(body) {
  *   that already appears earlier in the same block.
  */
 export function parseFrontmatterFields(text, at) {
+  // used by its own test
   /** @type {Record<string, string|string[]|undefined>} */
   const fields = {};
   let currentList = null;
@@ -306,6 +308,7 @@ function toList(value) {
  * @throws {Error} naming every violation at once.
  */
 export function validateRecord({ id, frontmatter, body = "" }) {
+  // used by its own test
   const fields = frontmatter === null ? {} : parseFrontmatterFields(frontmatter, id);
   const violations = [];
 
@@ -399,6 +402,7 @@ export function validateRecord({ id, frontmatter, body = "" }) {
  * @throws {Error} naming every lineage violation at once.
  */
 export function validateLineage(records) {
+  // used by its own test
   const byId = new Map(records.map((record) => [record.id, record]));
   /** @type {Map<string, string[]>} */
   const supersededBy = new Map(records.map((record) => [record.id, []]));
@@ -538,7 +542,7 @@ export function loadAdrRegistry(root, io = {}) {
     // deliberately silent, for the reason this module's header states.
     names = readDir(dir);
   } catch (cause) {
-    if (cause?.code === "ENOENT") return { records: [], byId: new Map() };
+    if (isEnoent(cause)) return { records: [], byId: new Map() };
     throw new Error(`archkeep: cannot read ${ADR_DIR}: ${cause?.message ?? cause}`, { cause });
   }
   names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));

package/src/governance/debt-ledger.mjs

@@ -143,7 +143,7 @@ function owningProjectForPath(path, byName) {
  * @param {string} source The entry's `source` (its keying field).
  * @returns {string} The stable hex id.
  */
-export function entryId(kind, source) {
+function entryId(kind, source) {
   const semanticKind = kind === "expired-waiver" ? "waiver" : kind;
   return createHash("sha256")
     .update(canonicalizeJson({ kind: semanticKind, source }))

package/src/governance/decision-fitness.mjs

@@ -61,6 +61,7 @@ import { hasAuthority } from "./adr-registry.mjs";
 
 /** The closed set of per-decision fitness levels `computeDecisionFitness` emits. */
 export const DECISION_FITNESS_LEVELS = Object.freeze([
+  // used by its own test
   "enforced",
   "partially-enforced",
   "violated",
@@ -70,6 +71,7 @@ export const DECISION_FITNESS_LEVELS = Object.freeze([
 
 /** Whether a level names a red (never-healthy) direction. */
 export function isRedDirection(level) {
+  // used by its own test
   return level === "violated" || level === "unverifiable";
 }
 

package/src/governance/decision-graph.mjs

@@ -382,6 +382,7 @@ export function forwardDecision(decisionId, ctx) {
  * @returns {GraphWalk}
  */
 export function reverseRow(rowRef, ctx) {
+  // used by its own test
   const g = newWalk();
 
   const row = ctx.rows.find((candidate) => candidate.id === rowRef);

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/evolution-store.mjs

@@ -51,6 +51,7 @@ import {
 import { join, resolve } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 import {
   eventDedupeKey,
   eventId,
@@ -222,7 +223,7 @@ export function writeEvent(dir, event, io = {}) {
   try {
     names = readDir(dirAbs);
   } catch (cause) {
-    if (cause?.code === "ENOENT") {
+    if (isEnoent(cause)) {
       // An absent optional store is an empty store: the caller's first event.
       makeDir(dirAbs, { recursive: true });
       names = readDir(dirAbs);
@@ -325,7 +326,7 @@ export function readEvents(dir, io = {}) {
   try {
     names = readDir(dirAbs);
   } catch (cause) {
-    if (cause?.code === "ENOENT") return [];
+    if (isEnoent(cause)) return [];
     throw new Error(
       `archkeep: cannot read the event store '${dirAbs}': ${cause?.message ?? cause}`,
       { cause },

package/src/governance/fitness-registry.mjs

@@ -63,11 +63,9 @@ import {
   tagConformance,
 } from "./fitness-rules.mjs";
 
-/** The one `fitness` list key in the boundary config. */
-export const FITNESS_KEY = "fitness";
-
 /** The condition types the registry can evaluate. */
 export const CONDITION_TYPES = Object.freeze([
+  // used by its own test
   "cycle-free",
   "layer-dependency",
   "tag-conformance",
@@ -330,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({

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

@@ -59,9 +59,6 @@
 import { originViolations } from "./provenance-record.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 
-/** The shape of any `origin.on` producer. Re-exported for a row owner's own docs. */
-export { clockViolations as clockValidation } from "./clock.mjs";
-
 /** The four governance keys a row may carry, in the order reports list them. */
 export const GOVERNANCE_ROW_KEYS = Object.freeze([
   "origin",
@@ -97,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

@@ -48,6 +48,7 @@ export const VERDICTS = Object.freeze(["pass", "fail", "unknown", "not_applicabl
 
 /** 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",

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));
 }