@ecoma-io/archkeep 0.22.2 → 0.24.0

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
@@ -646,6 +639,155 @@ function findCoverageViolations(value) {
   return violations;
 }
 
+/**
+ * The one edge kind a markdown marker row can declare. The name is the claim
+ * the row makes about the graph: the captured symbol is resolved to the project
+ * that exports it, and the edge runs from the document's own project to that
+ * project. Kept as data rather than inlined at the check site so a second kind
+ * (`docs/reference/policy-schema.md`, "markdown") extends this list and nothing
+ * else — and so a row naming a kind this reader cannot draw is refused at load,
+ * where a law that would silently never run belongs.
+ *
+ * @type {Readonly<string[]>}
+ */
+export const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
+
+/**
+ * One markdown marker row's problems, prefixed with its index.
+ *
+ * `pattern` is a regular-expression SOURCE matched against one line of a
+ * matched document at a time — never a glob, and never a whole-document
+ * match — because the position a violation reports must be a real
+ * `file:line:column` a developer can open. Its FIRST capture group must name
+ * the exported symbol the marker claims; a pattern with no capture group can
+ * match every line it is aimed at and still resolve nothing, which is a law
+ * that reads as enforced while testing nothing — refused here for the reason
+ * every dead shape in this file is refused.
+ *
+ * @param {object} row
+ * @param {number} index
+ * @returns {string[]}
+ */
+function markdownMarkerRowViolations(row, index) {
+  const at = `markdown.markers[${index}]`;
+  if (!isPlainObject(row)) return [`${at}: must be an object, got ${describe(row)}`];
+
+  const violations = [];
+  if (typeof row.pattern !== "string" || row.pattern === "") {
+    violations.push(
+      `${at}.pattern: must be a non-empty regular-expression source matched against one line of ` +
+        `a matched document, got ${describe(row.pattern)}`,
+    );
+  } else {
+    let compiled = null;
+    try {
+      compiled = new RegExp(row.pattern, "u");
+    } catch (cause) {
+      violations.push(
+        `${at}.pattern: '${row.pattern}' is not a valid regular expression under the 'u' flag ` +
+          `(${cause?.message ?? cause})`,
+      );
+    }
+    if (compiled !== null) {
+      // The capture count, read off the standard `pattern|` trick: matching the
+      // empty string yields one element per capture group plus the whole match,
+      // so a pattern that cannot capture anything reports `length === 1` here.
+      // Compiled in its own try, because the appended `|` can fail on a source
+      // the pattern alone accepted; the compile violation above is already
+      // reported in that case, and a second one would name the same row twice.
+      let captures;
+      try {
+        captures = (new RegExp(`${row.pattern}|`, "u").exec("")?.length ?? 1) - 1;
+      } catch {
+        captures = 1; // already refused above by the pattern's own compile check
+      }
+      if (captures < 1) {
+        violations.push(
+          `${at}.pattern: '${row.pattern}' has no capture group — the first capture group must ` +
+            `name the exported symbol the marker claims, and a pattern that captures nothing ` +
+            `resolves nothing while reading as enforced`,
+        );
+      }
+    }
+  }
+  if (!MARKDOWN_EDGE_KINDS.includes(row.edge)) {
+    violations.push(
+      `${at}.edge: ${describe(row.edge)} is not an edge kind this reader can draw — expected ` +
+        `${MARKDOWN_EDGE_KINDS.map((kind) => `"${kind}"`).join(", ")} (the captured symbol is ` +
+        `resolved to the project exporting it, and the edge runs there from the document's own ` +
+        `project)`,
+    );
+  }
+  for (const key of Object.keys(row)) {
+    if (key !== "pattern" && key !== "edge") {
+      violations.push(`${at}.${key}: not a markdown marker field — expected 'pattern' and 'edge'`);
+    }
+  }
+  return violations;
+}
+
+/**
+ * The markdown document track's problems, as messages; empty when it is
+ * well-formed. Pure, so a test drives it without a file on disk.
+ *
+ * `include` names the documents the track reads, by workspace-relative glob —
+ * the same glob machinery `boundarySuppressions` rows and `coverage.unowned`
+ * rows match with (`./rules/match.mjs`'s `safeMatchesGlob`), complexity-checked
+ * here at load for the reason a suppression's `path` is. An ABSOLUTE pattern is
+ * refused rather than left to match nothing forever: it can never match a
+ * workspace-relative document path, so declaring one is a law aimed outside
+ * the tree it governs (the family test is `ABSOLUTE_ARTIFACT_PATH`'s — the same
+ * "absolute in either path family" question, asked of a glob instead of a file).
+ *
+ * @param {unknown} value The parsed `markdown` value.
+ * @returns {string[]}
+ */
+function findMarkdownViolations(value) {
+  if (!isPlainObject(value)) {
+    return [`markdown: must be an object carrying 'include' and 'markers', got ${describe(value)}`];
+  }
+  const violations = [];
+  if (!Array.isArray(value.include) || value.include.length === 0) {
+    violations.push(
+      `markdown.include: must be a non-empty array of workspace-relative glob patterns naming ` +
+        `the documents the track reads, got ${describe(value.include)}`,
+    );
+  } else {
+    value.include.forEach((pattern, index) => {
+      const at = `markdown.include[${index}]`;
+      if (typeof pattern !== "string" || pattern === "") {
+        violations.push(
+          `${at}: must be a non-empty workspace-relative glob, got ${describe(pattern)}`,
+        );
+      } else if (ABSOLUTE_ARTIFACT_PATH.test(pattern)) {
+        violations.push(
+          `${at}: '${pattern}' is an absolute path — an include glob is matched against ` +
+            `workspace-relative document paths, so an absolute one can never match`,
+        );
+      } else {
+        const problem = globComplexityError(pattern);
+        if (problem) violations.push(`${at}: '${pattern}' ${problem}`);
+      }
+    });
+  }
+  if (!Array.isArray(value.markers) || value.markers.length === 0) {
+    violations.push(
+      `markdown.markers: must be a non-empty array of {pattern, edge} rows, got ` +
+        `${describe(value.markers)}`,
+    );
+  } else {
+    value.markers.forEach((row, index) =>
+      violations.push(...markdownMarkerRowViolations(row, index)),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "include" && key !== "markers") {
+      violations.push(`markdown.${key}: not a markdown field — expected 'include' and 'markers'`);
+    }
+  }
+  return violations;
+}
+
 /**
  * The grammar a custom rule's `name` is written in: lowercase letters and
  * digits, single `-` separators, nothing else.
@@ -934,13 +1076,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.
@@ -959,6 +1094,7 @@ export function findBoundaryConfigViolations(module, io = {}) {
     fitness,
     customRules,
     coverage,
+    markdown,
   } = module;
   // F05: the resolution half of the governance block (`row-schema.mjs`'s
   // `io.resolve`) was validator-only until now — no production caller passed
@@ -1014,6 +1150,19 @@ export function findBoundaryConfigViolations(module, io = {}) {
     violations.push(...findCoverageViolations(coverage));
   }
 
+  // The markdown document track — the seventh top-level law, declared here and
+  // executed at graph level (`../analysis/markdown.mjs`): machine-readable
+  // markers inside tracked markdown documents, each resolved to an edge from
+  // the document's own project to the project that exports the named symbol.
+  // Absent means "no document track" — the workspace decision this key exists
+  // to state, and the state every config-absent run must stay byte-identical
+  // to. Present and malformed is refused here, loudly, for the reason the two
+  // blocks above state: a row this reader cannot understand is a document law
+  // that would not run while the policy still says it does.
+  if (markdown !== undefined) {
+    violations.push(...findMarkdownViolations(markdown));
+  }
+
   // Absent means "nothing is suppressed", which is the only default that fails
   // toward reporting — unlike the eight options above, where a missing value
   // would be a second copy of something ESLint also reads and this module has
@@ -1109,7 +1258,10 @@ export function findBoundaryConfigViolations(module, io = {}) {
  * `coverage.exempt` is that provider's one channel for the same decision —
  * and the refusal lives in `./commands/policy.mjs`'s `resolvePolicy` and
  * `./providers/native/model.mjs`'s inline-policy check, because only they
- * know which provider is reading.
+ * know which provider is reading. `markdown` is the seventh: the document
+ * track (`findMarkdownViolations` above owns the shape), read into the graph
+ * by `../analysis/markdown.mjs` on every provider, because documents belong
+ * to projects under all three.
  *
  * The name says `.json` and the list binds both file dialects: `loadModulePolicy`
  * runs the same check over an ES module's exports, which is what makes a
@@ -1123,6 +1275,7 @@ const JSON_POLICY_KEYS = [
   "fitness",
   "customRules",
   "coverage",
+  "markdown",
 ];
 
 /**
@@ -1199,7 +1352,7 @@ export function policyKeyViolations(parsed, { allowSchema }) {
  *   inline one.
  * @param {string[]} [extraViolations] Violations the caller already found that
  *   `findBoundaryConfigViolations` does not check on its own.
- * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }}
+ * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: object }}
  *   `fitness` and `customRules` are present only when the config declares
  *   them — a workspace without one carries no key, the same "absent is a
  *   decision" posture `cli.mjs`'s `check` uses for a missing
@@ -1223,6 +1376,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
     ...(parsed.fitness === undefined ? {} : { fitness: parsed.fitness }),
     ...(parsed.customRules === undefined ? {} : { customRules: parsed.customRules }),
     ...(parsed.coverage === undefined ? {} : { coverage: parsed.coverage }),
+    ...(parsed.markdown === undefined ? {} : { markdown: parsed.markdown }),
   };
 }
 

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

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,8 @@ 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. */
 export const ADR_DIR = "docs/adr";
@@ -137,13 +139,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 +489,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 +512,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[]} */
@@ -538,7 +539,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));
@@ -581,7 +582,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 +775,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,17 +40,18 @@
  */
 
 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";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 import {
   eventDedupeKey,
   eventId,
@@ -205,13 +206,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
@@ -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);
@@ -316,8 +317,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);
 
@@ -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 },
@@ -360,3 +361,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 {
@@ -62,9 +63,6 @@ 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([
   "cycle-free",
@@ -87,17 +85,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));
 }