@ecoma-io/archkeep 0.22.2 → 0.23.0

package/src/commands/impact-reachability.mjs

@@ -0,0 +1,104 @@
+/**
+ * Reverse reachability over the project graph — the impact *computation*.
+ *
+ * Given a project name, `computeImpact` lists every project that transitively
+ * depends on it — the set a developer needs to consider before changing that
+ * project. It is descriptive: it never exits anything, because a description
+ * of what depends on a project is never a finding.
+ *
+ * The result separates **direct** dependents (projects whose edges point
+ * straight at the target) from **transitive** ones (reachable only through
+ * another project), and the union of both is `dependents`. An empty
+ * `dependents` list is a claim — "nothing depends on this project" — not a
+ * shrug, and the reports built on it are worded that way so a reader never
+ * mistakes it for silence.
+ *
+ * This is a plain module rather than part of `./impact.mjs` on purpose: the
+ * canonical evaluator (`./evaluation-primitives.mjs`) needs the same
+ * reachability walk the `impact` command reports, and `./impact.mjs` drives
+ * `./impact-statement.mjs`, which drives that evaluator. Holding the walk in
+ * `./impact.mjs` made `evaluation-primitives → impact → impact-statement →
+ * evaluation-primitives` the engine's only import cycle (#644) — three
+ * modules forced to load together, with no dependency order left to reason
+ * about. Both sides import the walk from here instead:
+ * `impact → impact-reachability`, `evaluation-primitives →
+ * impact-reachability`, and the trio's remaining direction stays one-way.
+ * `./impact.mjs` re-exports `computeImpact` so its existing importers keep
+ * resolving.
+ *
+ * Like `./edge-constraints.mjs`, this is a shared computation layer: it holds
+ * no argv, prints nothing, and decides no exit code (`./README.md`).
+ */
+import { UsageError } from "../errors.mjs";
+
+/**
+ * Computes the impact set: every project that transitively depends on
+ * `projectName`.
+ *
+ * Builds a reverse adjacency map from the graph's `dependencies`, then walks
+ * it breadth-first starting from the target project. The walk does NOT include
+ * the target project itself in the dependent set — a project does not depend
+ * on itself — but the returned `dependents` array is the union of `direct`
+ * and `transitive`, and the report header names the target separately.
+ *
+ * @param {string} projectName The project whose impact is being queried.
+ * @param {object} graph The project graph: `{nodes, dependencies}`.
+ * @returns {{project: string, direct: string[], transitive: string[], dependents: string[]}}
+ * @throws {UsageError} when `projectName` is not in the graph.
+ */
+export function computeImpact(projectName, graph) {
+  const nodes = graph.nodes;
+  const deps = graph.dependencies;
+
+  if (!Object.hasOwn(nodes, projectName)) {
+    throw new UsageError(
+      `archkeep: no project named '${projectName}' in the graph — ` +
+        `available projects: ${Object.keys(nodes)
+          .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+          .join(", ")}`,
+    );
+  }
+
+  // Build reverse adjacency: target → [sources that depend on it]
+  const reverseAdj = Object.create(null);
+  for (const source of Object.keys(deps)) {
+    if (!Object.hasOwn(deps, source)) continue;
+    const targets = deps[source];
+    for (const edge of targets) {
+      if (!Object.hasOwn(reverseAdj, edge.target)) {
+        reverseAdj[edge.target] = [];
+      }
+      reverseAdj[edge.target].push(source);
+    }
+  }
+
+  // Direct dependents: projects whose edges point straight at the target.
+  // Deduplicate (multiple edges between same pair are possible) and sort.
+  const directSet = new Set(reverseAdj[projectName] ?? []);
+  const direct = [...directSet].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  // BFS through reverse edges to find transitive dependents.
+  const visited = new Set(directSet);
+  const queue = [...directSet];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const parents = reverseAdj[current];
+    if (parents === undefined) continue;
+    for (const parent of parents) {
+      if (!visited.has(parent)) {
+        visited.add(parent);
+        queue.push(parent);
+      }
+    }
+  }
+
+  // Transitive dependents: reachable through another project, but not direct.
+  const transitive = [...visited]
+    .filter((name) => !directSet.has(name))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  // All dependents: direct + transitive, sorted.
+  const dependents = [...visited].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  return { project: projectName, direct, transitive, dependents };
+}

package/src/commands/impact.mjs

@@ -35,85 +35,23 @@
  * under project roots, `impact` refuses loudly rather than returning a result
  * whose dependents silently under-represent the real architecture.
  */
-import { UsageError } from "../errors.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatImpactReport } from "../report/impact-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { composeImpactStatement } from "./impact-statement.mjs";
+import { computeImpact } from "./impact-reachability.mjs";
 
 /**
- * Computes the impact set: every project that transitively depends on
- * `projectName`.
- *
- * Builds a reverse adjacency map from the graph's `dependencies`, then walks
- * it breadth-first starting from the target project. The walk does NOT include
- * the target project itself in the dependent set — a project does not depend
- * on itself — but the returned `dependents` array is the union of `direct`
- * and `transitive`, and the report header names the target separately.
- *
- * @param {string} projectName The project whose impact is being queried.
- * @param {object} graph The project graph: `{nodes, dependencies}`.
- * @returns {{project: string, direct: string[], transitive: string[], dependents: string[]}}
- * @throws {UsageError} when `projectName` is not in the graph.
+ * The reachability walk this command reports, shared with the canonical
+ * evaluator through `./impact-reachability.mjs` — held there, not here,
+ * because this module also drives `./impact-statement.mjs`, which drives that
+ * evaluator, and keeping the walk here is what closed the engine's only
+ * import cycle (#644). Re-exported so every importer of this module keeps
+ * resolving `computeImpact` from where it always has.
  */
-export function computeImpact(projectName, graph) {
-  const nodes = graph.nodes;
-  const deps = graph.dependencies;
-
-  if (!Object.hasOwn(nodes, projectName)) {
-    throw new UsageError(
-      `archkeep: no project named '${projectName}' in the graph — ` +
-        `available projects: ${Object.keys(nodes)
-          .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
-          .join(", ")}`,
-    );
-  }
-
-  // Build reverse adjacency: target → [sources that depend on it]
-  const reverseAdj = Object.create(null);
-  for (const source of Object.keys(deps)) {
-    if (!Object.hasOwn(deps, source)) continue;
-    const targets = deps[source];
-    for (const edge of targets) {
-      if (!Object.hasOwn(reverseAdj, edge.target)) {
-        reverseAdj[edge.target] = [];
-      }
-      reverseAdj[edge.target].push(source);
-    }
-  }
-
-  // Direct dependents: projects whose edges point straight at the target.
-  // Deduplicate (multiple edges between same pair are possible) and sort.
-  const directSet = new Set(reverseAdj[projectName] ?? []);
-  const direct = [...directSet].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  // BFS through reverse edges to find transitive dependents.
-  const visited = new Set(directSet);
-  const queue = [...directSet];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    const parents = reverseAdj[current];
-    if (parents === undefined) continue;
-    for (const parent of parents) {
-      if (!visited.has(parent)) {
-        visited.add(parent);
-        queue.push(parent);
-      }
-    }
-  }
-
-  // Transitive dependents: reachable through another project, but not direct.
-  const transitive = [...visited]
-    .filter((name) => !directSet.has(name))
-    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  // All dependents: direct + transitive, sorted.
-  const dependents = [...visited].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  return { project: projectName, direct, transitive, dependents };
-}
+export { computeImpact };
 
 /**
  * Runs the `impact` command: resolves the command context, checks the

package/src/commands/scenario-evaluation.mjs

@@ -32,7 +32,7 @@
  * @module
  */
 import { computeImpact } from "./impact.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 import {
   buildDecisionImpact,
   buildEvolutionAlignment,

package/src/config.mjs

@@ -125,6 +125,7 @@ import { pathToFileURL } from "node:url";
 import { containmentViolation, pathEscapes } from "./containment.mjs";
 
 import { loadEslintBoundaryConfig } from "./eslint-config.mjs";
+import { describe, isPlainObject, isStringArray } from "./values.mjs";
 import { findFitnessViolations } from "./governance/fitness-registry.mjs";
 import { declaredFitnessNames, stripRuleFitnessPrefix } from "./governance/adr-registry.mjs";
 import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "./governance/row-schema.mjs";
@@ -258,18 +259,10 @@ const ROW_LIST_MATCHERS = {
 
 const ROW_LIST_KEYS = Object.keys(ROW_LIST_MATCHERS);
 
-/** @type {(value: unknown) => value is string[]} */
-const isStringArray = (value) =>
-  Array.isArray(value) && value.every((item) => typeof item === "string");
-
 /** @type {(value: unknown) => value is [string, string][]} */
 const isTagPairArray = (value) =>
   Array.isArray(value) && value.every((pair) => isStringArray(pair) && pair.length === 2);
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 /**
  * What is wrong with the entries of one string list, each message naming the
  * entry's own index so a long list points at the offender rather than at
@@ -934,13 +927,6 @@ function findCustomRuleViolations(list, io) {
   return violations;
 }
 
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /**
  * Everything wrong with a loaded boundary config, as messages; empty when it
  * is well-formed. Pure, so a test drives it without a file on disk.

package/src/custom-rules/evidence.mjs

@@ -21,7 +21,7 @@
  * from "the pipeline never collected any", so it answers `pass` for a reason
  * nobody earned. A throw is a bug in the caller that composed the bundle, not
  * a fact about the workspace, which is why it is an exception rather than a
- * violation list — the same posture `../report/evidence.mjs`'s `buildDecision`
+ * violation list — the same posture `../governance/verdict.mjs`'s `buildDecision`
  * takes when a verdict and its counts disagree.
  *
  * ## Byte-determinism, and the two orders that are NOT normalized here

package/src/custom-rules/host.mjs

@@ -725,8 +725,8 @@ export async function evaluateCustomRule({
  * What is wrong with a verdict, or `null`.
  *
  * The obligations are the four-state vocabulary's, not this host's invention
- * (`../governance/verdict.mjs` states I1–I5 and `../report/evidence.mjs`
- * enforces the same ones for a command's own decision): `fail` names what
+ * (`../governance/verdict.mjs` states I1–I5 and enforces them for a command's
+ * own decision through `buildDecision`): `fail` names what
  * failed, `pass` names nothing, `unknown` names why it could not tell,
  * `not_applicable` names why it did not apply. A rule that breaks one of them
  * has returned a shape, not a judgment — hence "hollow", and hence a refusal

package/src/custom-rules/values.mjs

@@ -16,11 +16,16 @@
  *
  * The rendering is fixed here and nowhere else: `an array of N`, `null`,
  * `undefined`, and otherwise the value's type followed by its JSON.
+ *
+ * The plain-object guard is defined one floor down, in `../values.mjs` — the
+ * package-wide vocabulary every layer's validators share — and re-exported
+ * here so this layer's importers keep their spelling. It cannot be defined
+ * here: `./host.mjs` imports `../config.mjs` and `../governance/verdict.mjs`,
+ * so a guard defined in this directory would sit above the modules that need
+ * to reach it.
  */
 
-/** @type {(value: unknown) => value is Record<string, any>} */
-export const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
+export { isPlainObject } from "../values.mjs";
 
 /** @type {(value: unknown) => boolean} */
 export const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";

package/src/errors.mjs

@@ -12,7 +12,7 @@
  *
  * `UsageError` covers exactly the refusals those regexes matched: a path
  * outside the workspace or matching no tracked file (`./workspace.mjs`'s
- * `selectFiles`), an unknown project name (`./commands/impact.mjs`'s
+ * `selectFiles`), an unknown project name (`./commands/impact-reachability.mjs`'s
  * `computeImpact`, `./commands/context-command.mjs`'s
  * `collectProjectContext`), and a malformed `file:line:column` site string
  * (`./commands/explain.mjs`'s `parseSite`). They are one mistake in four

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

@@ -58,11 +58,6 @@ export function commit(root, message) {
   return git(root, "rev-parse", "HEAD").trim();
 }
 
-/** Resolves the current HEAD of the fixture. */
-export function headOf(root) {
-  return git(root, "rev-parse", "HEAD").trim();
-}
-
 /**
  * Opens a brand-new throwaway native git workspace (never the repository's own
  * tree). `archkeep.json` declares two Go projects on two layers, exactly the

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 { describe } from "../values.mjs";
 
 /** The directory, relative to a workspace root, where ADR files live. */
 export const ADR_DIR = "docs/adr";
@@ -137,13 +138,6 @@ const FRONTMATTER_KEYS = Object.freeze([
   "updated",
 ]);
 
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /** The `---`-delimited frontmatter block's text, or null when the file has none. */
 function frontmatterBlock(text) {
   if (!text.startsWith("---")) return null;
@@ -494,12 +488,17 @@ export function validateLineage(records) {
  * throws; the caller maps that to exit 3, never to an empty list.
  *
  * @param {string} root Absolute workspace root.
- * @param {{readdirSync?: (path: string) => string[], readFileSync?: (path: string, encoding: "utf8") => string,
+ * @param {{existsSync?: (path: string) => boolean, readdirSync?: (path: string) => string[],
+ *   readFileSync?: (path: string, encoding: "utf8") => string,
  *   lstatSync?: (path: string) => {isSymbolicLink: () => boolean}, realpathSync?: (path: string) => string,
  *   tracked?: string[]}} [io]
- *   Injectable filesystem seams, defaulting to the sync `node:fs` calls this
- *   module uses so the CLI stays event-loop-simple. Tests inject an in-memory
- *   tree. `tracked` is the `git ls-files` list (`../workspace.mjs`'s
+ *   Injectable filesystem seams, defaulting to `defaultAdrIo` (the sync
+ *   `node:fs` calls this module uses) so the CLI stays event-loop-simple.
+ *   Tests inject an in-memory tree.
+ *   `existsSync` gates the containment probe below: an in-memory root does not
+ *   exist on disk, and probing a nonexistent path's ancestry would walk up to
+ *   a real parent and misread it as an escape.
+ *   `tracked` is the `git ls-files` list (`../workspace.mjs`'s
  *   `listTrackedFiles`); when provided, a directory entry whose `docs/adr/<name>`
  *   path is not in it is excluded before it is ever validated — see this
  *   module's header for why, and `../architecture-intent/model.mjs`'s
@@ -512,10 +511,11 @@ export function validateLineage(records) {
  * @throws {Error} on an unreadable registry.
  */
 export function loadAdrRegistry(root, io = {}) {
-  const readDir = io.readdirSync ?? readdirSync;
-  const readFile = io.readFileSync ?? readFileSync;
-  const lstat = io.lstatSync ?? lstatSync;
-  const realpath = io.realpathSync ?? realpathSync;
+  const dirExists = io.existsSync ?? defaultAdrIo.existsSync;
+  const readDir = io.readdirSync ?? defaultAdrIo.readdirSync;
+  const readFile = io.readFileSync ?? defaultAdrIo.readFileSync;
+  const lstat = io.lstatSync ?? defaultAdrIo.lstatSync;
+  const realpath = io.realpathSync ?? defaultAdrIo.realpathSync;
   const dir = join(root, ADR_DIR);
 
   /** @type {string[]} */
@@ -581,7 +581,7 @@ export function loadAdrRegistry(root, io = {}) {
       // drives is keyed by a fixture path that does not exist on disk, and
       // probing a nonexistent root's ancestry would walk up to a real parent
       // directory and misread it as an escape. Real roots only.
-      existsSync(root) &&
+      dirExists(root) &&
       containmentViolation(root, filePath, { lstatSync: lstat, realpathSync: realpath }) !== null
     ) {
       continue;
@@ -774,3 +774,18 @@ export function unresolvedDecisionRefRows(rows, byId, knownFitness) {
   }
   return unresolved;
 }
+
+/**
+ * The default io: the sync `node:fs` calls `loadAdrRegistry` makes. This is
+ * the only place in this module the filesystem is named directly — every
+ * function reads through an injected `io` whose missing seams fall back here,
+ * so a test drives an in-memory tree without mocking the fs module and the
+ * module body never touches the disk on its own.
+ */
+const defaultAdrIo = Object.freeze({
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+});

package/src/governance/decision-graph.mjs

@@ -12,7 +12,7 @@
  * ## Descriptive by contract (Wave 2 scope)
  *
  * This module NEVER gates. It decides nothing about whether a finding IS one
- * (the rule that produced it owns that, `../report/evidence.mjs`'), never
+ * (the rule that produced it owns that, `./verdict.mjs`), never
  * changes `check`'s exit code, and never turns green or red on its own. It
  * reports the graph the registry and the caller's row/finding facts describe
  * — or, where a reference cannot resolve, names the gap. The `adr`/`report`

package/src/governance/evolution-store.mjs

@@ -40,13 +40,13 @@
  */
 
 import {
-  mkdirSync as defaultMkdir,
-  readdirSync as defaultReaddir,
-  readFileSync as defaultReadFile,
-  renameSync as defaultRename,
-  writeFileSync as defaultWriteFile,
-  lstatSync as defaultLstat,
-  realpathSync as defaultRealpath,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
 } from "node:fs";
 import { join, resolve } from "node:path";
 
@@ -205,13 +205,13 @@ function validateEventRecord(parsed, path) {
 export function writeEvent(dir, event, io = {}) {
   validateEventForWrite(event);
 
-  const readDir = io.readdirSync ?? defaultReaddir;
-  const readFile = io.readFileSync ?? defaultReadFile;
-  const writeFile = io.writeFileSync ?? defaultWriteFile;
-  const rename = io.renameSync ?? defaultRename;
-  const makeDir = io.mkdirSync ?? defaultMkdir;
-  const lstat = io.lstatSync ?? defaultLstat;
-  const realpath = io.realpathSync ?? defaultRealpath;
+  const readDir = io.readdirSync ?? defaultEvolutionIo.readdirSync;
+  const readFile = io.readFileSync ?? defaultEvolutionIo.readFileSync;
+  const writeFile = io.writeFileSync ?? defaultEvolutionIo.writeFileSync;
+  const rename = io.renameSync ?? defaultEvolutionIo.renameSync;
+  const makeDir = io.mkdirSync ?? defaultEvolutionIo.mkdirSync;
+  const lstat = io.lstatSync ?? defaultEvolutionIo.lstatSync;
+  const realpath = io.realpathSync ?? defaultEvolutionIo.realpathSync;
 
   // Resolved once: the identical string feeds the containment check and the
   // actual write (`../containment.mjs`, "One contract binds the WRITE call
@@ -316,8 +316,8 @@ export function writeEvent(dir, event, io = {}) {
  * @throws {Error} on the first unreadable or malformed event file.
  */
 export function readEvents(dir, io = {}) {
-  const readDir = io.readdirSync ?? defaultReaddir;
-  const readFile = io.readFileSync ?? defaultReadFile;
+  const readDir = io.readdirSync ?? defaultEvolutionIo.readdirSync;
+  const readFile = io.readFileSync ?? defaultEvolutionIo.readFileSync;
 
   const dirAbs = resolve(dir);
 
@@ -360,3 +360,20 @@ export function readEvents(dir, io = {}) {
   }
   return events;
 }
+
+/**
+ * The default io: the sync `node:fs` calls `writeEvent` and `readEvents` make.
+ * This is the only place in this module the filesystem is named directly —
+ * every store operation reads and writes through an injected `io` whose
+ * missing seams fall back here, so a test drives an in-memory store without
+ * mocking the fs module and the module body never touches the disk on its own.
+ */
+const defaultEvolutionIo = Object.freeze({
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+});

package/src/governance/fitness-registry.mjs

@@ -50,6 +50,7 @@
 import { isValidSelector, resolveMembers } from "../architecture-intent/selectors.mjs";
 import { languageOf } from "../analysis/registry.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "./row-schema.mjs";
 import { fitnessVerdict, isVerdict } from "./verdict.mjs";
 import {
@@ -87,17 +88,6 @@ const LAYER_DIRECTIONS = Object.freeze(["forbidden", "required"]);
 /** The one `toDependents` a `tag-conformance` row may carry. */
 const TAG_DEPENDENT_DIRECTIONS = Object.freeze(["only", "never"]);
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 function unknownKeys(obj, allowed) {
   return Object.keys(obj).filter((key) => !allowed.includes(key));
 }

package/src/governance/profile-registry.mjs

@@ -61,6 +61,7 @@
 import { readFileSync } from "node:fs";
 
 import { policyFrom } from "../config.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 
 /**
  * The top-level keys a profiles file may carry. `version` is checked AFTER
@@ -109,16 +110,6 @@ const BLOCK_KEYS = ["depConstraints", "moduleBoundaryOptions", "boundarySuppress
  */
 const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/u;
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /** A profile's declared block, kept ONLY for this command's own data. */
 export function listNames(registry) {
   return registry.profiles.map((profile) => profile.name);
@@ -304,23 +295,13 @@ export function resolveProfile(profiles, name, seen = new Set()) {
  * @param {string} path Absolute path of the profiles file.
  * @param {{readFile?: (path: string) => string|null}} [io] Injectable read,
  *   the same seam `../../options.mjs`'s readers take; answers `null` when the
- *   file is not there.
+ *   file is not there. Defaults to `defaultProfileIo.readFile` — the sync
+ *   `node:fs` read this module makes, the only place it touches the disk.
  * @returns {{profiles: object[]}}
  * @throws {Error} on a missing/unreadable/unparseable file, or on any
  *   profile-registry or reference-graph defect.
  */
-export function loadProfileRegistry(
-  path,
-  {
-    readFile = (p) => {
-      try {
-        return readFileSync(p, "utf8");
-      } catch {
-        return null;
-      }
-    },
-  } = {},
-) {
+export function loadProfileRegistry(path, { readFile = defaultProfileIo.readFile } = {}) {
   const text = readFile(path);
   if (text === null) {
     throw new Error(`archkeep: cannot read profiles file ${path}`);
@@ -363,3 +344,19 @@ export function profilePolicy(registryPath, profileName, sourceLabel, io = {}) {
   const effective = resolveProfile(registry.profiles, profileName);
   return policyFrom(effective, `${sourceLabel} (profile "${profileName}")`);
 }
+
+/**
+ * The default io: the sync `node:fs` read `loadProfileRegistry` makes, wrapped
+ * in the null-on-missing contract `../../options.mjs`'s readers share. This is
+ * the only place in this module the filesystem is named directly — a test
+ * injects a `readFile` and the module body never touches the disk on its own.
+ */
+const defaultProfileIo = Object.freeze({
+  readFile: (p) => {
+    try {
+      return readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
+});

package/src/governance/provenance-record.mjs

@@ -49,6 +49,7 @@
 
 import { ADR_STATUSES } from "./adr-registry.mjs";
 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"]);
@@ -63,17 +64,6 @@ export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]);
  *   `recordOrigin` produced it through the shared clock.
  */
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /**
  * Everything wrong with a raw `origin` record at READ time, as messages; empty
  * when it is well-formed. Shape only — an `on` committed in a declaration file

package/src/governance/reconcile-score.mjs

@@ -76,9 +76,6 @@ export const SEVERITY_ORDER = Object.freeze({
   unknown: Infinity,
 });
 
-/** A scored element's state, in the vocabulary the text and JSON reports share. */
-export const ELEMENT_STATES = Object.freeze(["match", "absent", "unexpected", "unknown"]);
-
 /**
  * A scored element.
  *

package/src/governance/row-schema.mjs

@@ -57,6 +57,7 @@
  */
 
 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";
@@ -85,17 +86,6 @@ export const GOVERNANCE_ROW_KEYS = Object.freeze([
  * @property {string[]} [fitnessBindings] Fitness ids this row is bound to.
  */
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /**
  * Everything wrong with a row's `rationale`, `decisionRef`, or
  * `fitnessBindings` — the three string-shaped governance keys. `origin` has