@ecoma-io/archkeep 0.27.1 → 0.28.1

package/README.md

@@ -3,7 +3,7 @@
 **Architecture governance for polyglot repositories** — a deterministic
 authority that keeps the architecture your team declared aligned with the code
 your team keeps changing. Dependency graphs and module boundaries for Go, Rust,
-Python, TypeScript, JavaScript, Vue, Java, Kotlin and C#, with Nx and Moon as first-class
+Python, TypeScript and JavaScript, Vue, Java, Kotlin and C#, with Nx and Moon as first-class
 integrations. Coding agents read the same verdicts, machine-readably, through
 the `arch-*` skills. The system boundary — what Archkeep is and what it is not —
 is owned by [architecture-authority.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/architecture-authority.md).
@@ -166,8 +166,10 @@ a file it cannot edit ([overview.md](https://github.com/ecoma-io/archkeep/blob/m
   mismatch, undeclared imports) refuses the run — never a silent skip
   ([custom-rules.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/custom-rules.md),
   [writing one](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/custom-rules.md)).
-- **Shipped policy packs** — Clean Architecture, hexagonal, layered modular
-  monolith and DDD bounded contexts, as ready-made profile registries under
+- **Shipped policy packs** — six shipped packs: Clean Architecture, hexagonal,
+  traditional layering, layered modular monolith, vertical slices and DDD
+  bounded contexts, as
+  ready-made profile registries under
   this package's `presets/` directory. Copy one into your workspace, or point
   the `profiles` option straight at it; either way it is enforced by the same
   path a registry you wrote yourself is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "description": "Architecture authority for human and agentic software development — deterministic, evidence-backed enforcement of declared architecture.",
   "keywords": [
     "architecture",

package/src/analysis/jvm/gradle.mjs

@@ -69,6 +69,12 @@
  * below THROWS on the same list (#364's posture, `../source-util.mjs`'s
  * `refuseUnreadTree`), so `nx affected` fails loudly instead of
  * under-selecting on it.
+ *
+ * A settings file that cannot be READ at all — one `readFile` throws on, an
+ * unreadable include file — is refused with a thrown Error naming the file
+ * path, not an empty include list (#847): a missing settings file is fine
+ * (a root may have no reactor), but a settings file whose read fails must
+ * not collapse the reactor to "no includes" silently.
  */
 
 import { normalizePath } from "../manifest-util.mjs";
@@ -380,12 +386,27 @@ function buildGradleModel(workspace) {
   for (const dir of candidateDirs) {
     for (const name of SETTINGS_FILENAMES) {
       const path = normalizePath(dir, name);
-      if (readFile(path) !== null && readFile(path) !== undefined) settingsFiles.push(path);
+      try {
+        if (readFile(path) !== null && readFile(path) !== undefined) settingsFiles.push(path);
+      } catch (cause) {
+        throw new Error(
+          `Gradle settings file '${path}' could not be read: ${cause?.message ?? cause}`,
+          { cause },
+        );
+      }
     }
   }
   for (const settingsPath of settingsFiles) {
     const settingsDir = dirnameOf(settingsPath);
-    const settingsText = readFile(settingsPath);
+    let settingsText;
+    try {
+      settingsText = readFile(settingsPath);
+    } catch (cause) {
+      throw new Error(
+        `Gradle settings file '${settingsPath}' could not be read: ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
     const settingsParsed = parseGradleSettings(settingsText ?? "");
     if (settingsParsed.reason !== undefined) {
       failures.push({

package/src/commands/README.md

@@ -134,7 +134,8 @@ the resolution order.
 - **`history`** (`./history.mjs`'s `historyCommand`) — the architecture's
   evolution across a consumer-managed directory of `graph --format json`
   snapshots. Reads every snapshot (the directory is the sole source of truth —
-  no index, no database), in filename byte-sort (history) order, and classifies
+  no index, no database), in capture-sequence order (each filename's leading
+  numeric sequence, not byte order), and classifies
   each transition by what the snapshots carry: graph diff (architecture),
   `policy.fingerprint` (policy/intent), `workspace.provider` (provider), and
   provenance advance with neither changed (code drift). One-sided or cross-repo

package/src/commands/history.mjs

@@ -10,7 +10,8 @@
  *
  * `--capture` appends a snapshot of the current workspace first — writing
  * `<seq>-<sha8>.json` (a zero-padded monotonic sequence and the snapshot's
- * architecture identity, so filename byte-sort IS history order) — then
+ * architecture identity; `readSnapshots` parses the leading sequence, so
+ * capture-sequence order IS history order) — then
  * produces the record that includes it. Capture deduplicates: when the
  * current architecture identity matches the last snapshot, no new file is
  * written and no empty transition is manufactured. The capture answer — was
@@ -34,9 +35,11 @@
  * An index file would be a second copy of facts the snapshot files already
  * hold, and two copies drift — the same reason `scripts/check-packages.mjs`
  * derives its target list from `ci.yml` rather than holding a copy
- * (`../../../../AGENTS.md`). The directory is ordered by filename byte-sort;
- * a snapshot is replaced or deleted by moving its file; a `history` that
- * cannot make sense of the directory says so instead of guessing.
+ * (`../../../../AGENTS.md`). The directory is ordered by capture sequence —
+ * `readSnapshots` parses each filename's leading numeric sequence, never
+ * byte order, which a sequence widened past 9999 would rewind; a snapshot
+ * is replaced or deleted by moving its file; a `history` that cannot make
+ * sense of the directory says so instead of guessing.
  *
  * ## What a transition can and cannot assert
  *
@@ -71,8 +74,16 @@
  * owns those (`./README.md`).
  */
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import {
   blindSpotRows,
@@ -80,7 +91,7 @@ import {
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
-import { containmentViolation } from "../containment.mjs";
+import { containmentViolation, deepestExistingAncestor } from "../containment.mjs";
 import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
@@ -183,6 +194,14 @@ export function eventSnapshotSide({ revision, projects, dependencies, policyFing
  * may share an architecture identity at non-adjacent positions (an A → B → A
  * evolution is real history); only capture dedups, against the last file.
  *
+ * The files are returned in capture-sequence order: the leading numeric
+ * sequence parsed from each filename, never filename byte order — at the
+ * 9999→10000 boundary byte order places a five-digit `10000-…` before
+ * `1001-…`, rewinding the record. Byte order is only the deterministic
+ * tiebreak for equal sequences; a name with no numeric prefix sorts after
+ * every numbered snapshot, byte-ordered among themselves, so a foreign file
+ * never interleaves with (and silently rewrites) the record.
+ *
  * @param {string} dir Absolute path to the history directory.
  * @param {string} [root] The workspace root, when the caller has one. A
  *   directory whose STRING lies inside the workspace but whose realpath
@@ -221,7 +240,24 @@ export function readSnapshots(dir, root) {
     );
   }
   names = names.filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"));
-  names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  // History order is the capture SEQUENCE, not filename bytes: the sequence
+  // widens past 9999 (`nextSequence`), where byte-sort would order
+  // `10000-…` between `1000-…` and `1001-…` and rewind the record. Parse
+  // each leading `\d+` once and sort numerically; byte order is the
+  // deterministic tiebreak for equal sequences. A name with no numeric
+  // prefix cannot be sequenced — it sorts after every numbered snapshot
+  // (`Infinity`), byte-ordered among itself, never displacing the record.
+  const sequenced = names.map((name) => {
+    const match = /^(\d+)-/.exec(name);
+    return {
+      name,
+      sequence: match === null ? Number.POSITIVE_INFINITY : Number.parseInt(match[1], 10),
+    };
+  });
+  sequenced.sort(
+    (a, b) => a.sequence - b.sequence || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  );
+  names = sequenced.map((entry) => entry.name);
 
   const files = [];
   for (const name of names) {
@@ -273,13 +309,14 @@ export function shortId(id) {
  * The zero-padded sequence number for `--capture`, taken from the highest
  * existing snapshot filename. `0001` for a fresh directory.
  *
- * The width widens from a four-digit minimum rather than overflowing: a
- * `10000` that padded to four digits would byte-sort *before* `9999-…` and
- * silently rewind history order, and the sequence regex would stop seeing the
- * 5-digit name so repeated captures would clobber the same file. Fresh
- * directories start at `0001`; each subsequent capture pads to at least the
- * width the next number needs, so the sequence always advances and no two
- * captures ever target the same file.
+ * The width is a stable filename shape, not an ordering mechanism:
+ * `readSnapshots` parses the leading sequence numerically, so a five-digit
+ * `10000-…` follows `9999-…` and history order can never rewind at the
+ * width boundary. The four-digit minimum keeps a young history's filenames
+ * uniformly shaped, and the width only ever grows to what the next number
+ * needs — which is what actually keeps two captures from ever targeting
+ * the same filename: the sequence advances past every existing name, so no
+ * produced name repeats one that exists, on any width.
  *
  * @param {{files: {name: string}[]}} read From `readSnapshots`.
  * @returns {string} Zero-padded sequence, at least four digits.
@@ -781,6 +818,39 @@ function historyDirFrom(options, cwd) {
   return isAbsolute(options.paths[0]) ? resolve(options.paths[0]) : resolve(cwd, options.paths[0]);
 }
 
+/**
+ * The physical location `path` names, resolved through every intermediate
+ * symlink. When a component does not exist yet (`ENOENT`/`ENOTDIR` — the
+ * only errors that mean "missing"), `realpathSync` fails and the fallback
+ * walks up to the deepest existing ancestor (`deepestExistingAncestor` — the
+ * same primitive the containment probe in `../containment.mjs` walks),
+ * resolves THAT physically, and appends the not-yet-existing remainder
+ * lexically: a component that does not exist cannot be a symlink, so its
+ * lexical spelling is its only spelling. When no component exists at all,
+ * nothing is provable and the answer is `null`.
+ *
+ * @param {string} path An absolute, already-`resolve`d path.
+ * @returns {string|null} The physical destination, the lexical form when the
+ *   path is missing, or `null` when the destination cannot be resolved at
+ *   all (a symlink loop, an unreadable component) — a no-verdict signal the
+ *   caller must refuse on, never guess from.
+ */
+function physicalDestination(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return null;
+    const ancestor = deepestExistingAncestor(path, lstatSync);
+    if (ancestor === null) return null;
+    try {
+      return resolve(realpathSync(ancestor), relative(ancestor, path));
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return null;
+      return resolve(path);
+    }
+  }
+}
+
 /**
  * `history`'s self-footgun guard: writing the history report back into the
  * very directory `history` reads would poison every later run (the report
@@ -788,6 +858,23 @@ function historyDirFrom(options, cwd) {
  * non-`graph` snapshot). Declared by the command that owns the law and
  * enforced by the driver's write door; `null` means no refusal.
  *
+ * The decision is made on the PHYSICAL destination, not the string spelling:
+ * `resolve()` normalizes `..` segments but never resolves symlinks, so an
+ * alias of the history directory (`hist-alias -> hist`) makes `dirname` of
+ * the output differ from the directory argument while the write would land
+ * in the SAME directory. The read side of this command family already
+ * decides on the physical path — `readSnapshots`'s containment resolves the
+ * history directory through symlinks rather than comparing strings — and
+ * this guard now matches it: the realpath of the output's parent against the
+ * realpath of the history directory, falling back to the lexical `resolve()`
+ * result for components that do not exist yet. A destination that cannot be
+ * resolved at all (a symlink loop, an unreadable component) is refused: it
+ * cannot be PROVEN outside the history directory, and answering from the
+ * spelling would be the silent direction. Refusal is EQUALITY only: a
+ * report in a SUBDIRECTORY of the history directory is not read back
+ * (`readSnapshots` is non-recursive) and stays allowed. The resolved-string
+ * comparison runs first, unchanged.
+ *
  * @param {{output: string|null, paths: string[]}} options This run's parsed
  *   flags.
  * @param {string} cwd The run's working directory, for relative flag
@@ -805,13 +892,30 @@ export function historyOutputRefusal(options, cwd) {
     ? resolve(options.output)
     : resolve(cwd, options.output);
   const dir = historyDirFrom(options, cwd);
-  if (dirname(outputAbs) === dir) {
+  const refusal =
+    `archkeep: --output '${options.output}' is inside the history directory '${dir}' — ` +
+    `writing the report there would be read back as a snapshot on the next run. ` +
+    `Write it somewhere else.`;
+  // Fast path: the resolved string already names the history directory.
+  if (dirname(outputAbs) === dir) return refusal;
+  // Physical path: the spelling differs but the write would land in the
+  // history directory all the same — a symlink alias of it, for example. A
+  // `null` destination means the physical answer is unprovable (a symlink
+  // loop, an unreadable component): refusing IS the claim there, because a
+  // destination that cannot be resolved also cannot be proven outside the
+  // history directory.
+  const outputPhysical = physicalDestination(dirname(outputAbs));
+  const dirPhysical = physicalDestination(dir);
+  if (outputPhysical === null || dirPhysical === null) {
     return (
-      `archkeep: --output '${options.output}' is inside the history directory '${dir}' — ` +
-      `writing the report there would be read back as a snapshot on the next run. ` +
-      `Write it somewhere else.`
+      `archkeep: --output '${options.output}' could not be resolved to a ` +
+      `physical destination, so it cannot be proven outside the history ` +
+      `directory '${dir}' — refusing rather than guessing from the spelling. ` +
+      `Check the path for symlink loops or unreadable components, and write ` +
+      `somewhere resolvable.`
     );
   }
+  if (outputPhysical === dirPhysical) return refusal;
   return null;
 }
 

package/src/containment.mjs

@@ -129,7 +129,7 @@ function within(root, absPath) {
  * @param {(path: string) => {isSymbolicLink: () => boolean}} lstat
  * @returns {string|null}
  */
-function deepestExistingAncestor(absPath, lstat) {
+export function deepestExistingAncestor(absPath, lstat) {
   let probe = absPath;
   for (;;) {
     try {

package/src/corpus/goldens/adr.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "adr",
   "workspace": {

package/src/corpus/goldens/change.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "change",
   "workspace": {
@@ -45,7 +45,7 @@
       "path": "<fixture-root>/.archkeep-delta.json",
       "tool": {
         "name": "@ecoma-io/archkeep",
-        "version": "0.27.1"
+        "version": "0.28.1"
       },
       "provider": "native",
       "provenance": {

package/src/corpus/goldens/check.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "check",
   "workspace": {

package/src/corpus/goldens/context.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "context",
   "workspace": {

package/src/corpus/goldens/debt.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "debt",
   "workspace": {

package/src/corpus/goldens/decisions.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "decisions",
   "workspace": {

package/src/corpus/goldens/delta.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "delta",
   "workspace": {
@@ -31,7 +31,7 @@
       "path": "<fixture-root>/.archkeep-delta.json",
       "tool": {
         "name": "@ecoma-io/archkeep",
-        "version": "0.27.1"
+        "version": "0.28.1"
       },
       "provider": "native",
       "provenance": {

package/src/corpus/goldens/diff.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "diff",
   "workspace": {
@@ -33,7 +33,7 @@
       "path": "<fixture-root>/.archkeep-graph.json",
       "projects": 3,
       "edges": 2,
-      "toolVersion": "0.27.1",
+      "toolVersion": "0.28.1",
       "provenance": {
         "commit": "1fd51709c377d99a6139891e1200291cf08aede9",
         "remote": null,

package/src/corpus/goldens/discover.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "discover",
   "workspace": {

package/src/corpus/goldens/drift.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "drift",
   "workspace": {

package/src/corpus/goldens/evolution.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "evolution",
   "workspace": {

package/src/corpus/goldens/explain.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "explain",
   "workspace": {

package/src/corpus/goldens/fitness.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "fitness",
   "workspace": {

package/src/corpus/goldens/graph.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "graph",
   "workspace": {

package/src/corpus/goldens/health.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "health",
   "workspace": {

package/src/corpus/goldens/history.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "history",
   "workspace": {

package/src/corpus/goldens/impact.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "impact",
   "workspace": {

package/src/corpus/goldens/provenance.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "provenance",
   "workspace": {

package/src/corpus/goldens/reconcile.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "reconcile",
   "workspace": {

package/src/corpus/goldens/report.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "report",
   "workspace": {

package/src/corpus/goldens/scenario.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "scenario",
   "workspace": {

package/src/corpus/goldens/trajectory.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "trajectory",
   "workspace": {

package/src/corpus/goldens/waivers.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.1"
+    "version": "0.28.1"
   },
   "command": "waivers",
   "workspace": {

package/src/governance/evolution-store.mjs

@@ -64,11 +64,12 @@ import {
  * The zero-padded sequence number for the next event, taken from the highest
  * existing event filename: `0000` for a fresh directory. An event log is
  * zero-based — the first event is index 0 — unlike history's capture
- * ordinals, which start at `0001`. The width widens from a four-digit minimum
- * rather than overflowing, for the same reason history's `nextSequence`
- * documents: a `10000` padded to four digits would byte-sort before `9999-…`
- * and silently rewind the log, and the sequence regex would stop seeing the
- * 5-digit name so repeated writes would clobber one file.
+ * ordinals, which start at `0001`. The width widens from a four-digit
+ * minimum rather than being pinned to it: the sequence regex reads any
+ * width, so the parsed maximum keeps advancing past `9999`, and the width
+ * growing to exactly what the next number needs is what keeps repeated
+ * writes from clobbering one file — the sequence advances past every
+ * existing name, so no produced name repeats one that exists, on any width.
  *
  * @param {string[]} names Event filenames from the directory read.
  * @returns {string} Zero-padded sequence, at least four digits.

package/src/governance/provenance-graph.mjs

@@ -5,9 +5,10 @@
  * to `{attested, attribution}`. When `fileAttribution` cannot answer (returns
  * null), every decision is unattested.
  *
- * This is the shared helper both `buildProvenanceGraph` and the impact/scenario
- * evaluation callers use, so decision provenance is computed identically
- * everywhere — "via the same graph helper, never re-derived" (PR4).
+ * This is the shared helper the impact and scenario evaluation callers use, so
+ * decision provenance is computed identically everywhere — "via the same graph
+ * helper, never re-derived" (PR4). `buildProvenanceGraph` is not a caller: it
+ * reads attestation from its `decisionLifecycle` input directly (#882).
  *
  * @param {{id: string}[]} records ADR records
  * @param {(path: string) => {createdBy: object|null,
@@ -92,9 +93,6 @@ import { resolveDecisionRef, stripRuleFitnessPrefix, stripAdrPrefix } from "./ad
  *   Decision record lookup map.
  * @property {Set<string>} knownFitness
  *   Fitness record names for resolution.
- * @property {(path: string) => object|null} [fileAttribution]
- *   Resolves git attribution for a decision record file. Passed through to
- *   `computeDecisionProvenance`. Defaults to a function that always returns null.
  * @property {{id: string, attested: boolean, attribution: object|null}[]}
  *   decisionLifecycle
  * @typedef {object} ProvenanceGraphNode
@@ -172,7 +170,6 @@ export function buildProvenanceGraph({
   records = [],
   byId = new Map(),
   knownFitness = new Set(),
-  fileAttribution: _fileAttribution = () => null,
   decisionLifecycle = [],
 }) {
   const nodes = [];
@@ -408,7 +405,12 @@ export function buildProvenanceGraph({
       for (const nextId of sortedArray(record.supersedes)) {
         if (!visited.has(nextId)) {
           queue.push(nextId);
-          parentMap.set(nextId, currentId);
+          // First queued parent wins: when a second supersession path reaches
+          // a decision already queued, overwriting its parent would drop the
+          // first path's hop from the chain while `edges` keeps both relations.
+          if (!parentMap.has(nextId)) {
+            parentMap.set(nextId, currentId);
+          }
         }
       }
 
@@ -457,7 +459,9 @@ export function buildProvenanceGraph({
       causalChains.push({
         id: chainId,
         startNode: rowId,
-        endNode: `decision:${chainNodes[chainNodes.length - 1]}`,
+        // `chainNodes` entries are node ids already (`decision:<id>`); wrapping
+        // them a second time emitted the dangling `decision:decision:<id>`.
+        endNode: chainNodes[chainNodes.length - 1],
         hops: chainEdges,
       });
     }

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/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/health-text.mjs

@@ -13,7 +13,7 @@
  * silent gap.
  *
  * Determinism: the metric order is fixed, and the trend rows are the snapshots
- * in byte-sort order (`../commands/history.mjs` orders them). This module
+ * in history order (`../commands/history.mjs` orders them). This module
  * decides nothing — a formatter that filtered would be a rule wearing a
  * formatter's name (`../README.md`).
  *