@ecoma-io/archkeep 0.24.0 → 0.24.1

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

@@ -124,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;
@@ -236,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;
@@ -307,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 = [];
 
@@ -400,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, []]));

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/fitness-registry.mjs

@@ -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({

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

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

package/src/intent/intent-manifest.json

@@ -104,13 +104,13 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
+          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
+          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
         }
       ],
       "status": "proven"
@@ -286,7 +286,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 —