@ecoma-io/archkeep 0.28.0 → 0.29.0

package/package.json

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

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.28.0"
+    "version": "0.29.0"
   },
   "command": "adr",
   "workspace": {

package/src/corpus/goldens/change.json

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

package/src/corpus/goldens/check.json

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

package/src/corpus/goldens/context.json

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

package/src/corpus/goldens/debt.json

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

package/src/corpus/goldens/decisions.json

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

package/src/corpus/goldens/delta.json

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

package/src/corpus/goldens/diff.json

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

package/src/corpus/goldens/discover.json

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

package/src/corpus/goldens/drift.json

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

package/src/corpus/goldens/evolution.json

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

package/src/corpus/goldens/explain.json

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

package/src/corpus/goldens/fitness.json

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

package/src/corpus/goldens/graph.json

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

package/src/corpus/goldens/health.json

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

package/src/corpus/goldens/history.json

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

package/src/corpus/goldens/impact.json

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

package/src/corpus/goldens/provenance.json

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

package/src/corpus/goldens/reconcile.json

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

package/src/corpus/goldens/report.json

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

package/src/corpus/goldens/scenario.json

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

package/src/corpus/goldens/trajectory.json

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

package/src/corpus/goldens/waivers.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.28.0"
+    "version": "0.29.0"
   },
   "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/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`).
  *