@ecoma-io/archkeep 0.24.0 → 0.24.1

package/src/commands/check.mjs

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

package/src/commands/completeness.mjs

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

package/src/commands/coverage-acceptance.mjs

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

package/src/commands/custom-rules.mjs

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

package/src/commands/delta-classify.mjs

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

package/src/commands/delta-snapshot.mjs

@@ -52,7 +52,7 @@ import { isPlainObject } from "../values.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 
 /** The only snapshot schemaVersion this module writes and reads. */
-export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1; // used by its own test
 
 /**
  * Builds the snapshot object from already-captured evidence.
@@ -338,6 +338,7 @@ export function readEvidenceSnapshot(path, io = {}) {
  * @throws {Error} on every condition above.
  */
 export function parseEvidenceSnapshot(text, path) {
+  // used by its own test
   let parsed;
   try {
     parsed = JSON.parse(text);

package/src/commands/delta.mjs

@@ -74,6 +74,7 @@ import {
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
+  assertReproducibleEventIdentity,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -161,6 +162,7 @@ export function refusePluginGapHead(commandContext, activity) {
  * @throws {Error} on either condition.
  */
 export function refuseUnjudgeableHead(commandContext, activity) {
+  // used by its own test
   refusePluginGapHead(commandContext, activity);
   const notAnalyzed = commandContext.analysis.failures.filter(isWholeFileFailure);
 
@@ -271,6 +273,8 @@ export function captureDelta(commandContext, { config }) {
  *   type: string}[], workspaceLayout?: object, exemptedFiles?: string[]}} storedGraph
  *   A validated snapshot's `graph` section (`parseEvidenceSnapshot`).
  * @returns {object} A graph `evaluate()` consumes.
+ * @throws {Error} when an `exemptedFiles` entry is not a string — the engine's
+ *   own filter would drop it in silence (the refusal beside the copy below).
  */
 export function evidenceGraphToProjectGraph(storedGraph) {
   /** @type {Record<string, object>} */
@@ -297,7 +301,26 @@ export function evidenceGraphToProjectGraph(storedGraph) {
   const graph = { nodes, dependencies };
   if (storedGraph.workspaceLayout !== undefined)
     graph.workspaceLayout = storedGraph.workspaceLayout;
-  if (Array.isArray(storedGraph.exemptedFiles)) graph.exemptedFiles = storedGraph.exemptedFiles;
+  if (Array.isArray(storedGraph.exemptedFiles)) {
+    // An entry that is not a string is refused here rather than carried:
+    // `../rules/index.mjs`'s `createContext` filters `graph.exemptedFiles`
+    // with `typeof file === "string"`, so a corrupted snapshot's entry would
+    // ride through this conversion and vanish there — the exemption set the
+    // snapshot recorded silently shrinking by one file, the under-count
+    // disclosed nowhere.
+    const malformed = storedGraph.exemptedFiles
+      .map((entry, at) => ({ entry, at }))
+      .filter(({ entry }) => typeof entry !== "string");
+    if (malformed.length > 0) {
+      const { entry, at } = malformed[0];
+      throw new Error(
+        `archkeep: the snapshot's graph.exemptedFiles[${at}] is ${JSON.stringify(entry)}, ` +
+          `not a string — the rule engine drops such entries in silence, which would shrink ` +
+          `the exemption set the snapshot recorded; re-capture the baseline or correct the file`,
+      );
+    }
+    graph.exemptedFiles = storedGraph.exemptedFiles;
+  }
   return graph;
 }
 
@@ -373,6 +396,7 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  * @returns {"accepted"|"rejected"|"no-verdict"}
  */
 export function deltaDisposition({ status }) {
+  // used by its own test
   if (status === "no-verdict") return "no-verdict";
   if (status === "findings") return "rejected";
   return "accepted";
@@ -810,26 +834,16 @@ export async function deltaCommand(
   let eventWrite = null;
   if (eventOut !== null && eventOut !== undefined) {
     // F-delta-event-id: an evolution event is only written from a reproducible
-    // identity — a committed, clean head and a clean base. A commitless head
-    // has no revision to name, and a dirty tree names a commit its evidence
-    // does not back; either way TWO distinct evidence states collapse onto ONE
-    // event id, so a later transition is silently lost or aliased (the silent
-    // direction). Refuse loudly instead. The same run without `--event-out`
-    // stays a byte-identical in-memory delta.
-    if (typeof headCommit !== "string") {
-      throw new Error(
-        "archkeep: refusing to write a delta event without a committed head — a commitless " +
-          "head has no reproducible event identity, and every distinct head state would " +
-          "collide on one event id. Commit the head, or capture without --event-out.",
-      );
-    }
-    if (baseline.provenance?.dirty === true || headProvenance?.dirty === true) {
-      throw new Error(
-        "archkeep: refusing to write a delta event from a dirty working tree — the event " +
-          "would name a commit whose evidence is uncommitted, and distinct uncommitted " +
-          "states would collide on one event id. Commit both sides first.",
-      );
-    }
+    // identity — a committed, clean head and a clean base, by the shared law
+    // `assertReproducibleEventIdentity` owns. The wording is frozen there; the
+    // messages consumers match on are byte-identical to the inline refusals
+    // this call replaces.
+    assertReproducibleEventIdentity({
+      label: "delta",
+      headCommit,
+      baseDirty: baseline.provenance?.dirty === true,
+      headDirty: headProvenance?.dirty === true,
+    });
     // The architecture-debt sub-ledger (design §8): judged by re-running the
     // current intent over this run's base and head graphs — a drift finding
     // present at head but not base is introduced; one gone is resolved. Both

package/src/commands/drift.mjs

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

package/src/commands/evaluation-primitives.mjs

@@ -195,7 +195,7 @@ export function buildDecisionImpact(root, constraintImpact, config) {
  *   not available.
  * @returns {{evaluated: boolean, findings: object[], count: number}}
  */
-export function evaluateFindingsImpact(affectedProjects, availableFindings) {
+function evaluateFindingsImpact(affectedProjects, availableFindings) {
   if (!availableFindings || availableFindings.length === 0) {
     return { evaluated: false, findings: [], count: 0 };
   }
@@ -221,7 +221,7 @@ export function evaluateFindingsImpact(affectedProjects, availableFindings) {
  *   entry's associated project.
  * @returns {{evaluated: boolean, debt: object[], count: number}}
  */
-export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
+function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
   if (!availableDebt || availableDebt.length === 0) {
     return { evaluated: false, debt: [], count: 0 };
   }
@@ -247,7 +247,7 @@ export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProje
  * @param {string} targetProject The target of the impact analysis.
  * @returns {{boundaries: object[], evaluated: boolean}}
  */
-export function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
+function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
   if (!constraintImpact || constraintImpact.length === 0) {
     return { boundaries: [], evaluated: false };
   }
@@ -339,7 +339,7 @@ export function decisionProvenanceCoverage(decisions) {
  * @param {object} evaluation.evolutionAlignment Evolution alignment.
  * @returns {object} Evidence gate values for buildEvidenceComplete.
  */
-export function deriveEvidenceGates(evaluation) {
+function deriveEvidenceGates(evaluation) {
   const { completeness, constraintImpact, decisionImpact } = evaluation;
 
   // domainCoverage: ratio of evaluated required domains

package/src/commands/evolution.mjs

@@ -138,6 +138,7 @@ function shortSha(sha) {
  *   and a shallow clone whose cut-off sits below the requested revision.
  */
 export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
+  // used by its own test
   if (typeof rev !== "string" || rev.length === 0) {
     throw new Error(`archkeep: ${flag} needs a revision — a commit, branch, tag, or HEAD~n.`);
   }
@@ -190,6 +191,7 @@ export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
  *   head's ancestry, or a merge commit inside the range.
  */
 export function selectLinearRange(root, { base, head }, { run = runProcess } = {}) {
+  // used by its own test
   const baseSha = resolveRevision(root, base, "--base", { run });
   const headSha = resolveRevision(root, head ?? "HEAD", "--head", { run });
 

package/src/commands/explain.mjs

@@ -111,6 +111,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
  * @throws {UsageError} when the site string is malformed.
  */
 export function parseSite(site) {
+  // used by its own test
   const lastColon = site.lastIndexOf(":");
   if (lastColon === -1 || lastColon === 0) {
     throw new UsageError(
@@ -157,6 +158,7 @@ export function parseSite(site) {
  * @returns {object|null} The matching record, or `null`.
  */
 export function findSite(parsed, imports) {
+  // used by its own test
   return (
     imports.find(
       (site) =>

package/src/commands/graph.mjs

@@ -151,24 +151,26 @@ export function buildDependencies(dependencies) {
  * config comparison logic.
  *
  * The fingerprint is SHA-256 of the canonicalized JSON for `depConstraints`,
- * `options`, `suppressions` and — when the policy declares them — `fitness`
- * and `customRules`. Those are every field of a loaded policy that states
- * law: the first three decide which violations `evaluate` produces, the
- * fourth decides which fitness functions `check` folds into the same exit
- * code (`../governance/fitness-registry.mjs`), and the fifth names the rule
+ * `options`, `suppressions` and — when the policy declares them — the
+ * `fitness`, `customRules`, `coverage` and `markdown` blocks, plus the
+ * selected profile's NAME when the law was selected by name. Those are every
+ * field of a loaded policy that states law: the first three decide which
+ * violations `evaluate` produces, the fourth decides which fitness functions
+ * `check` folds into the same exit code
+ * (`../governance/fitness-registry.mjs`), and the fifth names the rule
  * artifacts a workspace declared, each pinned to the bytes its `sha256` claims
  * (`../config.mjs`'s `customRuleRowViolations`) — swap one row's hash or its
- * `params` and the policy says something different. A field that can fail a
- * build and is not in the hash is a law that can be rewritten while `diff`
- * reports the policy unchanged — the silent direction, and the reason the list
- * here and `policyFrom`'s return shape (`../config.mjs`) are revisited
- * together.
+ * `params` and the policy says something different. The three after those are
+ * argued at their keys below. A field that can fail a build and is not in the
+ * hash is a law that can be rewritten while `diff` reports the policy
+ * unchanged — the silent direction, and the reason the list here and
+ * `policyFrom`'s return shape (`../config.mjs`) are revisited together.
  *
- * `fitness` and `customRules` are included only when they are DECLARED, and
- * the absent case contributes no key rather than an empty array. A policy that
- * declares neither therefore fingerprints exactly as it did before those
- * fields were covered, so extending the hash did not move every existing
- * snapshot's value — only those whose law it was failing to describe.
+ * The conditional fields are included only when they are DECLARED, and the
+ * absent case contributes no key rather than an empty array. A policy that
+ * declares none therefore fingerprints exactly as it did before those fields
+ * were covered, so extending the hash did not move every existing snapshot's
+ * value — only those whose law it was failing to describe.
  *
  * @param {object} config The loaded boundary config.
  * @returns {string} A hex-encoded SHA-256 fingerprint.
@@ -180,13 +182,33 @@ export function computePolicyFingerprint(config) {
     suppressions: config.suppressions ?? [],
     ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
     ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
-    // The document track is law the same way the two blocks above are: it
+    // The acceptance channel is law the same way the blocks above are: a
+    // `coverage.unowned` row withdraws an unclaimed file's whole-file failure
+    // as a recorded acceptance (`../config.mjs`'s `findCoverageViolations`
+    // owns the shape, `../commands/coverage-acceptance.mjs` matches it), so a
+    // policy that records or removes an acceptance must not share a
+    // fingerprint with one that does not — `diff`'s policy-changed warning
+    // reads this hash (#709: the one block `policyFrom` sets that the hash
+    // skipped). Conditional, like the three above, so a policy recording no
+    // acceptance hashes exactly as it did before this key existed.
+    ...(config.coverage === undefined ? {} : { coverage: config.coverage }),
+    // The document track is law the same way the blocks above are: it
     // decides what this run judges, so a policy that adds or edits a
     // `markdown` block must not share a fingerprint with one that does not —
     // `diff`'s policy-changed warning reads this hash. Conditional, like the
-    // two above, so a policy declaring no block hashes exactly as it did
+    // three above, so a policy declaring no block hashes exactly as it did
     // before this key existed.
     ...(config.markdown === undefined ? {} : { markdown: config.markdown }),
+    // The named selection is law identity the same way the blocks above are:
+    // `profilePolicy` (`../governance/profile-registry.mjs`) sets this key
+    // when the workspace selects a profile by name, and two profiles whose
+    // resolved blocks converge are still two different named laws. Only
+    // `check`'s report names the selection, so a hash blind to it would let a
+    // `delta` across a switch report the law unchanged with nothing anywhere
+    // saying it moved. Conditional, like the four above, so a policy
+    // selected by file or inline — no `profile` key at all — hashes exactly
+    // as it did before the selection was covered.
+    ...(config.profile === undefined ? {} : { profile: config.profile }),
   };
   // Canonicalise: sort object keys at every depth so insertion order does not
   // affect the hash. Semantic equality, not construction order, is the claim —

package/src/commands/history.mjs

@@ -229,6 +229,7 @@ export function readSnapshots(dir, root) {
  * @returns {string} First 8 hex characters.
  */
 export function shortId(id) {
+  // used by its own test
   return id.slice(0, 8);
 }
 
@@ -248,6 +249,7 @@ export function shortId(id) {
  * @returns {string} Zero-padded sequence, at least four digits.
  */
 export function nextSequence(read) {
+  // used by its own test
   let max = 0;
   for (const file of read.files) {
     const match = /^(\d+)-/.exec(file.name);

package/src/commands/plan-context-command.mjs

@@ -87,7 +87,7 @@ import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/a
 import { formatPlanContextReport } from "../report/plan-context-text.mjs";
 
 /** How many dependents are listed before an explicit overflow note. */
-export const DEPENDENT_CAP = 10;
+export const DEPENDENT_CAP = 10; // used by its own test
 
 /**
  * The projects a change touches: the target project, plus every project whose
@@ -100,6 +100,7 @@ export const DEPENDENT_CAP = 10;
  * @returns {string[]} Distinct affected project names, sorted.
  */
 export function collectAffectedProjects(commandContext, paths) {
+  // used by its own test
   const affected = new Set();
   for (const { file, project } of commandContext.owned ?? []) {
     for (const p of paths) {
@@ -124,6 +125,7 @@ export function collectAffectedProjects(commandContext, paths) {
  * @returns {object[]}
  */
 export function collectImpact(projectName, affected, graph) {
+  // used by its own test
   const targets = [...new Set([projectName, ...affected])].sort((a, b) =>
     a < b ? -1 : a > b ? 1 : 0,
   );
@@ -172,6 +174,7 @@ function scopedFiles(commandContext, affected) {
  * @returns {{goWork: object|null, tsconfigPaths: object|null, failures: object[]}}
  */
 export function collectDrift(commandContext) {
+  // used by its own test
   const { root, tracked, workspace } = commandContext;
   const failures = [];
 

package/src/commands/policy.mjs

@@ -26,7 +26,7 @@ import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
  * @param {object} options The resolved options from `resolveCommandContext`.
  * @returns {boolean}
  */
-export function hasProfiles(options) {
+function hasProfiles(options) {
   return typeof options?.profiles === "string" && options.profiles !== "";
 }
 
@@ -86,10 +86,13 @@ export function hasProfiles(options) {
  * @param {string} cwd The process's working directory a relative `--config`
  *   resolves against — kept separate from the workspace root for the reason
  *   above.
- * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[]}|null, profile: string|null, source: string|null}>}
+ * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[], profile?: string}|null, profile: string|null, source: string|null}>}
  *   `fitness`, `customRules` and `markdown` are present only when the resolved
  *   policy declares them — an absent key is the workspace's decision not to
  *   declare that law, never an empty one (`../config.mjs`'s `policyFrom`).
+ *   `profile` is present only when the law was selected by name, set by the
+ *   profiles arm (`../governance/profile-registry.mjs`'s `profilePolicy`) so
+ *   the selection the policy was resolved by travels with it.
  * @throws {Error} when a named profile, a `--config` file, or an inline
  *   policy cannot be resolved or is malformed — every arm's existing failure
  *   mode, unchanged by the extraction.

package/src/commands/scenario-evaluation.mjs

@@ -55,7 +55,7 @@ import {
 // ---------------------------------------------------------------------------
 
 /** The supported scenario change types. */
-export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]);
+export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]); // used by its own test
 
 // ---------------------------------------------------------------------------
 // Input schema types

package/src/commands/trajectory.mjs

@@ -107,7 +107,7 @@ const OBSERVATION_BASIS = "graph_snapshots";
  * constant in the envelope, so a consumer branches on a documented value
  * rather than on prose.
  */
-export const INSUFFICIENT_HISTORY = "insufficient_history";
+export const INSUFFICIENT_HISTORY = "insufficient_history"; // used by its own test
 
 /**
  * The derived-number block for one structural axis (projects keyed by name,
@@ -187,6 +187,7 @@ export const INSUFFICIENT_HISTORY = "insufficient_history";
  *   trends: TrajectoryTrends|null}}
  */
 export function computeTrajectory(files) {
+  // used by its own test
   const n = files.length;
   const available = n >= 2;
 

package/src/config.mjs

@@ -650,7 +650,7 @@ function findCoverageViolations(value) {
  *
  * @type {Readonly<string[]>}
  */
-export const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
+const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
 
 /**
  * One markdown marker row's problems, prefixed with its index.

package/src/custom-rules/host.mjs

@@ -124,17 +124,17 @@ export const CUSTOM_RULE_TIMEOUT_MS = 10_000;
  * bundle for a large workspace is smaller — and it is what stops a claimed
  * length from being an allocation instruction.
  */
-export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024;
+export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024; // used by its own test
 
 /**
  * The most linear memory a rule may hold at the two boundaries the worker
  * measures. 256 MiB is far past what reading an evidence bundle needs and far
  * short of what a workspace's CI runner can absorb without noticing.
  */
-export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024;
+export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024; // used by its own test
 
 /** The four ABI symbols a rule module must export, and the kind each must be. */
-export const REQUIRED_EXPORTS = Object.freeze({
+const REQUIRED_EXPORTS = Object.freeze({
   memory: "memory",
   archkeep_alloc: "function",
   archkeep_describe: "function",

package/src/eslint-config.mjs

@@ -235,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(