@ecoma-io/archkeep 0.27.0 → 0.28.0

package/src/governance/provenance-record.mjs

@@ -147,8 +147,9 @@ export function validateOrigin(raw, io = {}, at = "origin") {
  *   clock that supplies `on`. `clock` is required — an `on` produced without a
  *   clock is the non-determinism this module exists to exclude, so the absence
  *   is a loud Error, never a default.
- * @returns {OriginRecord} `{by, tool, on: clock.now()}`, and ONLY those three
- *   keys — a fresh object, so nothing from untrusted input rides along.
+ * @returns {OriginRecord} `{by, tool, on}`, where `on` is the clock's one
+ *   sampled answer, and ONLY those three keys — a fresh object, so nothing from
+ *   untrusted input rides along.
  * @throws {Error} on an invalid author, an unusable clock, or a
  *   non-string/empty clock answer.
  */
@@ -158,11 +159,24 @@ export function recordOrigin({ by, tool, clock }) {
   if (shape.length > 0) {
     throw new Error(shape.join("; "));
   }
-  const clockProblems = clockViolations(clock);
-  if (clockProblems.length > 0) {
-    throw new Error(`origin.on: ${clockProblems.join("; ")}`);
+  // The clock is read exactly once and the read is what ships: sample it, judge
+  // the sample, emit it. `clockViolations` cannot render this verdict — it
+  // samples the clock itself, so delegating to it here would read the clock a
+  // second time, and that second read let a stateful clock answer validation
+  // with one instant and the record with another. The checks below restate its
+  // messages so a misused clock is still named in the shared vocabulary,
+  // read-free until the one sample exists.
+  if (clock === null || typeof clock !== "object") {
+    throw new Error(
+      `origin.on: clock must be an object with a now() function, got ${describe(clock)}`,
+    );
+  }
+  if (typeof clock.now !== "function") {
+    throw new Error("origin.on: clock.now must be a function returning a non-empty string");
+  }
+  const on = clock.now();
+  if (typeof on !== "string" || on.length === 0) {
+    throw new Error("origin.on: clock.now() must return a non-empty string");
   }
-  // The clock is the single door, and it is called exactly once for this
-  // record, so two calls with the same clock are byte-identical.
-  return { by, tool, on: clock.now() };
+  return { by, tool, on };
 }

package/src/governance/reconcile-score.mjs

@@ -268,8 +268,13 @@ export function scoreEdge(edge, keys, intentForbiddenPairs, tagForbiddenPairs) {
  * Boundary `allowed`/`forbidden` rows are scored from the canonical judge's
  * findings (matched exactly by `from`/`to`): a `forbidden` row with an
  * `intentForbiddenEdge` finding is `unexpected`, an `allowed` row with an
- * `intentAllowedMissing` finding is `absent`. Project and dependency rows are
- * scored directly against the observed names and edges. A
+ * `intentAllowedMissing` finding is `absent`. Project rows are scored against
+ * the observed names, and the two forbidden drift planes are scored from the
+ * judge's findings as well — `dependencies.forbidden` through its
+ * `dependencyForbidden` findings, `forbiddenTags` through its
+ * `tagDependencyForbidden` witnesses attributed via `tagsByProject` — so a
+ * row's verdict IS the verdict `check` and `drift` render, including the
+ * transitive closure a direct-edge re-derivation would read as "match". A
  * `dependencies.allowed` row is an allowlist entry, not an existence claim —
  * its absence in the graph is not divergence, so it scores `match` either
  * way (the divergent direction is the observed edge outside the list, scored
@@ -285,7 +290,29 @@ 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}`));
+  // The judge has already judged every forbidden plane on the any-path
+  // closure (`../architecture-intent/judge.mjs` emits `dependencyForbidden`
+  // and `tagDependencyForbidden` for direct AND transitive paths, as concrete
+  // `source`/`target` project names with `boundaryFrom: null`). These two
+  // projections score the drift rows from those findings — projecting the
+  // canonical verdict, never re-deriving reachability here: a re-walk of the
+  // direct-edge list would score a transitive violation the judge reported
+  // as a row "match", the divergence `check` and `drift` do report. The
+  // judge's pairless findings (`intentUnknownProject`, `intentUnknownTag`)
+  // carry no witness pair; the rows they belong to are scored below from the
+  // observed names and tags themselves — the same existence predicate the
+  // judge used to emit them: a row whose endpoint can never resolve is
+  // unknown/unverifiable, never a silent "match".
+  const dependencyForbiddenPairs = new Set();
+  const tagForbiddenWitnesses = [];
+  for (const finding of judgeVerdict.findings) {
+    if (finding.source === null || finding.target === null) continue;
+    if (finding.rule === "dependencyForbidden") {
+      dependencyForbiddenPairs.add(`${finding.source} → ${finding.target}`);
+    } else if (finding.rule === "tagDependencyForbidden") {
+      tagForbiddenWitnesses.push([finding.source, finding.target]);
+    }
+  }
 
   const boundaryFinding = new Map();
   for (const finding of judgeVerdict.findings) {
@@ -341,22 +368,45 @@ export function scoreIntentRows(intent, judgeVerdict, observed, tagsByProject) {
   }
   for (const forbidden of dependencies.forbidden ?? []) {
     const key = `${forbidden.source} → ${forbidden.target}`;
+    // A row naming a project the observed architecture does not have can
+    // never fire — the judge reports it as `intentUnknownProject` with no
+    // witness pair, so the projection above stays empty for it. Reading
+    // that as "match — the ban holds" would be the silent direction; score
+    // it unknown, mirroring the boundary plane (`reconcileScores`).
+    if (!observedNames.has(forbidden.source) || !observedNames.has(forbidden.target)) {
+      row("edge", key, "unknown", "intentUnknownProject", "forbidden", key);
+      continue;
+    }
+    const violated = dependencyForbiddenPairs.has(key);
     row(
       "edge",
       key,
-      observedEdgeKeys.has(key) ? "unexpected" : "match",
-      observedEdgeKeys.has(key) ? "dependencyForbidden" : "match",
+      violated ? "unexpected" : "match",
+      violated ? "dependencyForbidden" : "match",
       "forbidden",
       key,
     );
   }
 
+  // Every tag any observed project carries — the existence side of a
+  // `forbiddenTags` row, the same vocabulary the judge checks when it emits
+  // `intentUnknownTag`.
+  const allTags = new Set();
+  for (const tags of tagsByProject.values()) {
+    for (const tag of tags) allTags.add(tag);
+  }
   for (const tagRow of intent.forbiddenTags ?? []) {
     const key = `${tagRow.from} → ${tagRow.to}`;
-    const violated = observed.edges.some((e) => {
-      if (e.source === e.target) return false;
-      const sourceTags = tagsByProject.get(e.source) ?? [];
-      const targetTags = tagsByProject.get(e.target) ?? [];
+    // A row naming a tag no observed project carries can never fire — the
+    // judge reports it as `intentUnknownTag` with no witness pair. Score it
+    // unknown, never a silent "match".
+    if (!allTags.has(tagRow.from) || !allTags.has(tagRow.to)) {
+      row("tag", key, "unknown", "intentUnknownTag", "tag-forbidden", key);
+      continue;
+    }
+    const violated = tagForbiddenWitnesses.some(([source, target]) => {
+      const sourceTags = tagsByProject.get(source) ?? [];
+      const targetTags = tagsByProject.get(target) ?? [];
       return sourceTags.includes(tagRow.from) && targetTags.includes(tagRow.to);
     });
     row(

package/src/graph/create-dependencies.mjs

@@ -42,6 +42,20 @@
  * the rule; its malformed-TOML tolerance stays the documented exception its
  * own header pins (`../analysis/python.mjs`).
  *
+ * ## The hook's context contract (#843)
+ *
+ * `context.fileMap.projectFileMap` is validated before any resolver runs: a
+ * missing map, or a declared project with no key in it, throws. nx 23.x
+ * seeds a key for EVERY declared project before attributing a single file —
+ * `createFileMap` writes `projectFileMap[name] ??= []` (measured, nx 23.2.0
+ * `dist/src/project-graph/file-map-utils.js`) — so a legitimate zero-file or
+ * target-only project reads as an EMPTY ARRAY, never as an absent key. The
+ * refusal therefore has no legitimate shape to catch, and the state it
+ * replaces was the silent direction: a project whose manifests were never
+ * read contributes no edges, byte-for-byte identical to a workspace with
+ * nothing to find, while a project whose manifest was read and could not be
+ * parsed throws (#364). "Never looked" now fails like "looked and failed".
+ *
  * Resolver contract (see `../analysis/*.mjs`): every resolver returns raw Nx
  * edges — { source, target, sourceFile, type } and nothing else. Go, Rust and
  * Python take `resolve(projects, filesOf, readFile)`; the C# and JVM halves
@@ -188,12 +202,31 @@ export function resolveDeclaredManifestFailures(workspace) {
  */
 export const createDependencies = (options, context) => {
   resolveOptions(options);
-  const projects = Object.entries(context.projects).map(([projectName, config]) => ({
-    name: projectName,
-    root: config.root,
-  }));
-  const filesOf = (projectName) =>
-    (context.fileMap?.projectFileMap?.[projectName] ?? []).map((f) => f.file);
+  const projectFileMap = context.fileMap?.projectFileMap;
+  if (projectFileMap === null || typeof projectFileMap !== "object") {
+    throw new Error(
+      "archkeep: the Nx plugin context carries no fileMap.projectFileMap — no " +
+        "project's file universe is known, so no polyglot manifest can be read and " +
+        "no edge can be trusted. Refusing rather than computing a silently empty " +
+        "graph: nx 23.x seeds a projectFileMap key for every declared project, so a " +
+        "missing map is context-shape drift. Upgrade @ecoma-io/archkeep if a newer " +
+        "Nx moved the field.",
+    );
+  }
+  const projects = Object.entries(context.projects).map(([projectName, config]) => {
+    if (!Object.hasOwn(projectFileMap, projectName)) {
+      throw new Error(
+        `archkeep: project "${projectName}" (root "${config.root}") is declared in the ` +
+          `Nx plugin context but has no key in fileMap.projectFileMap — its manifests ` +
+          `would go unread and its edges undrawn, the under-selection this plugin ` +
+          `exists to close. nx 23.x maps every declared project, including projects ` +
+          `with no files (an empty array), so a missing key is context-shape drift. ` +
+          `Upgrade @ecoma-io/archkeep if a newer Nx moved the field.`,
+      );
+    }
+    return { name: projectName, root: config.root };
+  });
+  const filesOf = (projectName) => projectFileMap[projectName].map((f) => f.file);
   const readFile = (workspaceRelativePath) => {
     const abs = join(context.workspaceRoot, workspaceRelativePath);
     // Every value this reader is handed comes from the tree's own `fileMap` —

package/src/intent/intent-manifest.json

@@ -201,8 +201,8 @@
         {
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
-          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap",
-          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
+          "assertion": "Section 'What `context` and `impact` do not check' warns agents about the semantic gap",
+          "sha256": "81b1b57e19f3f5b4894f8273d33d731f80e6f8e80a513bd64208135852ed3bb8"
         }
       ],
       "status": "proven"
@@ -272,7 +272,7 @@
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
           "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations",
-          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
+          "sha256": "81b1b57e19f3f5b4894f8273d33d731f80e6f8e80a513bd64208135852ed3bb8"
         }
       ],
       "status": "proven"

package/src/providers/nx-static.mjs

@@ -37,6 +37,12 @@
  * not blank the index — where `readProjectGraph` throws the identical refusal;
  * the two policies are the recorded difference between an acquisition that
  * still has a tree to index and one that does not.
+ *
+ * One refusal THROWS rather than skipping: a `package.json` beside a
+ * `project.json` that exists but cannot be read or parsed (#846). Falling
+ * through to the directory basename there would put the project in the graph
+ * under a name no constraint row names — a silently wrong identity. Absent
+ * (null) stays the legitimate basename fallback per Nx's own precedence.
  */
 
 import { readWorkspaceLayout, requireCompleteWorkspaceLayout } from "../options.mjs";
@@ -103,15 +109,30 @@ export function discoverProjects({ files, readFile }) {
     // Nx's own precedence: the name a project states, then the one its
     // `package.json` states, then the directory it lives in.
     const packageName = (() => {
-      const manifest = readFile(root === "" ? "package.json" : `${root}/package.json`);
+      const pkgPath = root === "" ? "package.json" : `${root}/package.json`;
+      let manifest;
+      try {
+        manifest = readFile(pkgPath);
+      } catch (cause) {
+        throw new Error(
+          `package.json '${pkgPath}' beside project '${root || "."}' could not be read: ${cause?.message ?? cause}`,
+          { cause },
+        );
+      }
       if (manifest === null) return undefined;
       try {
         // The same parser, because Nx reads this file with the same
         // `readJsonFile` — a `package.json` Nx can name a project from must
         // not become a project named after its directory here.
         return parseProjectJson(manifest).name;
-      } catch {
-        return undefined;
+      } catch (cause) {
+        // An unreadable package.json that was READ must not fall through to
+        // the directory basename (#846) — that is a project the graph knows
+        // under one name and every constraint row names under another.
+        throw new Error(
+          `package.json '${pkgPath}' beside project '${root || "."}' could not be read: ${cause?.message ?? cause}`,
+          { cause },
+        );
       }
     })();
     const name =

package/src/providers/nx.mjs

@@ -34,6 +34,17 @@
  *   afterwards (`../../cli.mjs`, via `annotateMFERemotes` and
  *   `annotatePackageFacts`), read from disk the way upstream reads them — a
  *   provider that filled them in would only be overwritten.
+ *
+ * The nodes that graph carries are validated at this seam, not trusted. Nx's
+ * own contract is narrow — `type` exactly one of `app`/`e2e`/`lib`, `data` an
+ * object with a string `root` and, when present, a `tags` array of non-empty
+ * strings — and every one of those fields is read verbatim by the rules layer
+ * (`../rules/specifiers.mjs`'s root mappings, `../rules/index.mjs`'s node-kind
+ * filter, `../rules/tags.mjs`'s constraint matching), so a drifted node is
+ * refused here by project name rather than judged into a wrong analysis: a
+ * rootless project silently drops out of every path lookup, a wrong kind
+ * silently skips its checks, a scalar `tags` silently matches or misses every
+ * tag row. See `readProjectGraph` below for the refusal itself.
  */
 
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -105,6 +116,81 @@ function nxCli({ resolveNx = () => require.resolve("nx/package.json") } = {}) {
   return join(dirname(manifest), typeof bin === "string" ? bin : bin.nx);
 }
 
+/**
+ * Refuses any project node whose shape drifted from what Nx emits, by name.
+ *
+ * The command's output reaches `evaluate()` with no shape work in between, and
+ * every node field is read verbatim downstream: `data.root` by
+ * `../rules/specifiers.mjs`'s `createProjectRootMappings` (a missing root maps
+ * the project to `undefined`, and it silently drops out of every
+ * path-to-project lookup), `type` by `../rules/index.mjs`'s
+ * `isProjectGraphProjectNode` (anything outside `app`/`e2e`/`lib` is judged as
+ * an external node, silently skipping its boundary checks), `data.tags` by
+ * `../rules/tags.mjs` (a scalar silently matches or misses every constraint
+ * row). All four shapes are states `nx graph` does not emit — Nx 23.2.0's own
+ * `ProjectGraphProjectNode` carries exactly `type: "app"|"e2e"|"lib"` and a
+ * `data` configuration with a string `root` — so one here can only mean an Nx
+ * version drift or a defective producer, and it is refused, not guessed at:
+ * an unreadable entry refuses, it does not skip.
+ *
+ * @param {Record<string, object>} nodes The `graph.nodes` map as parsed.
+ * @throws {Error} when a node is not an object, its `type` is not one of
+ *   `app`/`e2e`/`lib`, its `data` is not an object, its `data.root` is not a
+ *   string, or its `data.tags` is present but not an array of non-empty
+ *   strings. The error names the project and the offending field.
+ */
+function validateProjectNodes(nodes) {
+  for (const [name, node] of Object.entries(nodes)) {
+    if (typeof node !== "object" || node === null) {
+      throw new Error(
+        `archkeep: \`nx graph\` node '${name}' is not an object — expected a project node ` +
+          `with type, name and data as Nx emits it.`,
+      );
+    }
+    if (node.type !== "app" && node.type !== "e2e" && node.type !== "lib") {
+      throw new Error(
+        `archkeep: \`nx graph\` node '${name}' has type "${node.type}" — expected one of ` +
+          `"app", "e2e", "lib". Anything else is judged as an external node and its boundary ` +
+          `checks are silently skipped.`,
+      );
+    }
+    if (typeof node.data !== "object" || node.data === null) {
+      throw new Error(
+        `archkeep: \`nx graph\` node '${name}' has no data object — expected data with a ` +
+          `workspace-relative root, and tags when the project carries any.`,
+      );
+    }
+    if (typeof node.data.root !== "string") {
+      throw new Error(
+        `archkeep: \`nx graph\` node '${name}' has no string data.root — expected the ` +
+          `workspace-relative project root as a string ("" is the workspace root). A rootless ` +
+          `project silently drops out of every path-to-project lookup and its imports are ` +
+          `judged with no owning project.`,
+      );
+    }
+    if (node.data.tags !== undefined) {
+      if (!Array.isArray(node.data.tags)) {
+        const got = node.data.tags === null ? "null" : typeof node.data.tags;
+        throw new Error(
+          `archkeep: \`nx graph\` node '${name}' has data.tags of type ${got} — expected an ` +
+            `array of non-empty strings. Tag rows are matched against this list verbatim, so a ` +
+            `scalar silently matches or misses every row.`,
+        );
+      }
+      for (const [index, tag] of node.data.tags.entries()) {
+        if (typeof tag !== "string" || tag === "") {
+          const got = tag === "" ? "an empty string" : `a ${typeof tag}`;
+          throw new Error(
+            `archkeep: \`nx graph\` node '${name}' has data.tags[${index}] that is not a ` +
+              `non-empty string (got ${got}) — expected an array of non-empty strings. A ` +
+              `non-string entry silently matches or misses every tag row it is compared with.`,
+          );
+        }
+      }
+    }
+  }
+}
+
 /**
  * The Nx project graph for `workspaceRoot`, in the shape `evaluate()` consumes.
  *
@@ -133,6 +219,12 @@ function nxCli({ resolveNx = () => require.resolve("nx/package.json") } = {}) {
  * agree on the same declared object rather than one merging onto a default
  * the other would have refused.
  *
+ * Each node in that graph is also validated against Nx's own contract —
+ * `type` one of `app`/`e2e`/`lib`, `data` an object, `data.root` a string,
+ * `data.tags` (when present) an array of non-empty strings — and a drifted
+ * node is refused by project name (`validateProjectNodes` below) rather than
+ * forwarded to rules that read it verbatim and would silently misjudge it.
+ *
  * @param {string} workspaceRoot
  * @param {{ run?: typeof runProcess, resolveNx?: () => string,
  *   readLayout?: typeof readWorkspaceLayout }} [io]
@@ -140,6 +232,9 @@ function nxCli({ resolveNx = () => require.resolve("nx/package.json") } = {}) {
  *   `workspaceLayout` read (see `../options.mjs`).
  * @returns {object} `{ nodes, dependencies }`, plus `workspaceLayout` when
  *   `nx.json` declares a complete one.
+ * @throws {Error} when the emitted graph carries no `graph.nodes` map, or any
+ *   node drifted from Nx's own shape — the error names the project and the
+ *   field that refused it.
  */
 export function readProjectGraph(
   workspaceRoot,
@@ -150,12 +245,13 @@ export function readProjectGraph(
   try {
     run(process.execPath, [nxCli({ resolveNx }), "graph", `--file=${file}`], workspaceRoot);
     const { graph } = JSON.parse(readFileSync(file, "utf8"));
-    if (!graph?.nodes) {
+    if (!graph?.nodes || typeof graph.nodes !== "object" || Array.isArray(graph.nodes)) {
       throw new Error(
-        `archkeep: \`nx graph\` produced no \`graph.nodes\` in ${file} — ` +
+        `archkeep: \`nx graph\` produced no \`graph.nodes\` object in ${file} — ` +
           `nothing can be judged against a graph with no projects in it`,
       );
     }
+    validateProjectNodes(graph.nodes);
     const workspaceLayout = requireCompleteWorkspaceLayout(readLayout(workspaceRoot));
     return workspaceLayout === null ? graph : { ...graph, workspaceLayout };
   } finally {

package/src/report/text.mjs

@@ -774,7 +774,7 @@ function formatUntrackedFilesGap(gap) {
     `⚠ ${count} project-owned file${count === 1 ? "" : "s"} ${count === 1 ? "is" : "are"} ` +
     `not tracked by git — never read by this run, so no boundary verdict here covers ${them}\n` +
     `${lines.join("\n")}\n` +
-    `${DETAIL}git add ${them} so the next run reads ${them}, or let git ignore ${them}`
+    `${DETAIL}git add ${them} so the next run reads ${them}`
   );
 }
 

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

@@ -1,248 +0,0 @@
-/**
- * Fixture scaffolding for the Wave 3 W8 evolution-lifecycle conformance suite
- * (`../evolution-lifecycle.integration.test.mjs`). This module is the ONE home
- * for the real-git workspace builders that suite uses — a throwaway native Go
- * workspace per case, materialized through real `git`, driven through the real
- * `archkeep evolution` entry point.
- *
- * It deliberately reuses the native-workspace recipe already proven by
- * `../commands/evolution.cli.integration.test.mjs` (an `archkeep.json` model,
- * a `module-boundaries.config.mjs` law, and Go sources) rather than inventing
- * a second convention, and threads the same environment guard (`../process.mjs`).
- *
- * Nothing here decides a verdict. It builds trees and drives the CLI; the
- * assertions live in the suite. Keeping the builders here (and only here) is
- * what the W8 task boundary requires: fixture scaffolding lives in
- * `./fixtures/evolution-lifecycle/`, nowhere else.
- */
-
-import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { EXIT, runCli } from "../../../cli.mjs";
-import { SPAWN_BUDGET_MS, SPAWN_TEST_BUDGET_MS } from "../../../spawn-budget.mjs";
-import { environmentForTree } from "../../workspace.mjs";
-
-export { SPAWN_TEST_BUDGET_MS, EXIT };
-
-/** Identity flags keeping every fixture commit independent of the machine. */
-const IDENTITY = ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false"];
-
-/**
- * Runs git in `cwd` through the same environment guard production uses, with
- * the single-spawn budget on every child so a wedged git fails the test rather
- * than blocking the worker thread forever.
- */
-export function git(cwd, ...args) {
-  // used by its own test
-  return execFileSync("git", args, {
-    cwd,
-    env: environmentForTree(),
-    encoding: "utf8",
-    timeout: SPAWN_BUDGET_MS,
-    killSignal: "SIGKILL",
-  });
-}
-
-/** 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();
-}
-
-/**
- * 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
- * MODEL `../commands/evolution.cli.integration.test.mjs` uses, so a case can
- * lay an edge between them and the native provider draws it.
- *
- * @returns {{root: string}}
- */
-export function createWorkspace() {
-  const root = mkdtempSync(join(tmpdir(), "archkeep-lifecycle-"));
-  git(root, "init", "-q", "-b", "main");
-  writeIn(root, "archkeep.json", `${MODEL()}\n`);
-  writeIn(root, "libs/alpha/go.mod", "module example.com/alpha\n\ngo 1.22\n");
-  writeIn(root, "libs/beta/go.mod", "module example.com/beta\n\ngo 1.22\n");
-  return { root };
-}
-
-/**
- * The native workspace model: two Go projects on two layers (alpha is
- * `layer:a`, beta is `layer:b`), the law file exempted from coverage.
- */
-const MODEL = () =>
-  JSON.stringify(
-    {
-      projects: {
-        declared: [
-          { root: "libs/alpha", name: "alpha", tags: ["layer:a"] },
-          { root: "libs/beta", name: "beta", tags: ["layer:b"] },
-        ],
-      },
-      coverage: {
-        exempt: [{ path: "module-boundaries.config.mjs", reason: "the workspace's own law" }],
-      },
-    },
-    null,
-    2,
-  );
-
-/** The eight options a valid boundary law must carry, per `policyFrom`. */
-const OPTIONS = `export const moduleBoundaryOptions = {
-  allow: [],
-  buildTargets: ["build"],
-  enforceBuildableLibDependency: false,
-  allowCircularSelfDependency: false,
-  checkDynamicDependenciesExceptions: [],
-  ignoredCircularDependencies: [],
-  banTransitiveDependencies: false,
-  checkNestedExternalImports: false,
-};
-`;
-
-export const ALPHA_CLEAN = `package alpha // used by its own test
-
-func Name() string { return "alpha" }
-`;
-
-export const ALPHA_REACHING = `package alpha // used by its own test
-
-import (
-	"example.com/beta"
-)
-
-func Name() string { return "alpha" + beta.Suffix() }
-`;
-
-export const BETA = `package beta // used by its own test
-
-func Suffix() string { return "-beta" }
-`;
-
-/**
- * Writes a `module-boundaries.config.mjs` law at `root` with the given
- * `depConstraints` rows and optional `fitness` array.
- *
- * @param {string} root
- * @param {{rows?: string, fitness?: string}} [law]
- */
-export function writeLaw(root, { rows = "", fitness } = {}) {
-  // used by its own test
-  writeIn(
-    root,
-    "module-boundaries.config.mjs",
-    `export const depConstraints = [\n${rows}\n];\n${OPTIONS}` +
-      (fitness === undefined ? "" : `\nexport const fitness = ${fitness};\n`),
-  );
-}
-
-/**
- * A single permitted layer rule (a may reach b). The same ONE_ROW the
- * 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"] },`; // used by its own test
-
-/**
- * Writes `architecture-intent.json` at `root`. `sections` carries the top-level
- * keys directly (`version`, `boundaries`, `allowed`, `forbidden`,
- * `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`);
-}
-
-/**
- * Writes one ADR record under `docs/adr/`, the shape `adr-registry.mjs` reads.
- * `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:");
-    for (const target of record.supersedes) lines.push(`  - ${target}`);
-  }
-  if (record.bindings?.length) {
-    lines.push("bindings:");
-    for (const binding of record.bindings) lines.push(`  - ${binding}`);
-  }
-  lines.push("---", "", `# ${record.id}`, "");
-  writeIn(root, join("docs/adr", filename), `${lines.join("\n")}\n`);
-}
-
-/**
- * Drives the CLI in-process over `cwd`, capturing streams. Returns the exit
- * code and joined `out`/`err`. `runCli` is the real entry point
- * (`../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, {
-    out: (text) => out.push(text),
-    err: (text) => err.push(text),
-    cwd,
-  });
-  return { exitCode, out: out.join("\n"), err: err.join("\n") };
-}
-
-/**
- * Invokes `evolution --base <base> [--head <head>] [--event-out <dir>] [--format json]`.
- *
- * @param {string} base The base revision (full SHA).
- * @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);
-  if (format) args.push("--format", format);
-  return args;
-}
-
-/**
- * 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);
-}
-
-/** The parsed event files in `dir`, in filename order. */
-export function readEvents(dir) {
-  return readdirSync(dir)
-    .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
-    .sort()
-    .map((name) => JSON.parse(readFileSync(join(dir, name), "utf8")));
-}
-
-/** 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();
-}
-
-/** Removes a throwaway workspace. */
-export function dispose(root) {
-  // used by its own test
-  rmSync(root, { recursive: true, force: true });
-}