@ecoma-io/archkeep 0.16.1 → 0.18.0

package/src/governance/evolution-store.mjs

@@ -0,0 +1,362 @@
+/**
+ * The append-only evolution event store (design §3): one event per file,
+ * `<NNNN>-<id8>.json`, written atomically and idempotently. `docs/concepts/evolution.md`
+ * states the store semantics; this module implements them.
+ *
+ * Four properties, each with a mechanism:
+ *
+ * - **Append-only.** There is no update and no delete in this module, by
+ *   construction — the only write path creates a new file. State change is a
+ *   new event; rewriting history is impossible.
+ * - **Idempotent.** `writeEvent` scans the directory for an existing event
+ *   with the same `dedupeKey` BEFORE writing. The key is the canonical
+ *   `{base, head, declarationDigest}` tuple `evolution-event.mjs` defines — the
+ *   same tuple the id hashes — so a rerun over the same transition finds the
+ *   earlier event and returns `{duplicate: true}` writing nothing, the
+ *   always-present `duplicate` sibling `commands/history.mjs`'s capture uses so
+ *   the envelope shape never depends on directory state. A file that cannot be
+ *   parsed during the scan throws: a corrupt store must never silently
+ *   manufacture a duplicate of the record it could not read.
+ * - **Atomic.** The write goes to `<path>.json.tmp` opened with `{flag: "wx"}`
+ *   (refusing rather than following a symlink already sitting there), then
+ *   `rename` over the final name — the same mechanism as history's
+ *   `writeSnapshotFile` (`../commands/history.mjs`). Reads filter `.json.tmp`
+ *   out, so an interrupted write leaves a partial file the store will never
+ *   read. The final-name rule from containment still applies: the `.tmp` name
+ *   is not walked by the containment probe, and `wx` is what refuses a planted
+ *   symlink at it.
+ * - **Contained.** A write is checked against the workspace root the same way
+ *   `--output` is (`../containment.mjs`): `io.root` is REQUIRED, and a path
+ *   whose intermediate components are workspace-controlled symlinks is refused
+ *   loudly rather than silently landing outside the tree. A directory the
+ *   caller names outside the root string is the caller's explicit choice and
+ *   proceeds, exactly like `--output /tmp`.
+ *
+ * Sequence numbers are zero-based (`0000`, `0001`, …) and widen from a
+ * four-digit minimum rather than overflowing — the same mechanism as history's
+ * `nextSequence` (`../commands/history.mjs`), offset by one because a capture
+ * sequence is an ordinal while an event log is an index. `shortId` is history's
+ * `shortId` (first 8 hex chars of the id).
+ */
+
+import {
+  mkdirSync as defaultMkdir,
+  readdirSync as defaultReaddir,
+  readFileSync as defaultReadFile,
+  renameSync as defaultRename,
+  writeFileSync as defaultWriteFile,
+  lstatSync as defaultLstat,
+  realpathSync as defaultRealpath,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+import { containmentViolation } from "../containment.mjs";
+import {
+  eventDedupeKey,
+  eventId,
+  EVOLUTION_EVENT_SCHEMA_VERSION,
+  EVENT_CLASSIFICATIONS,
+  EVENT_DISPOSITIONS,
+} from "./evolution-event.mjs";
+
+/**
+ * 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.
+ *
+ * @param {string[]} names Event filenames from the directory read.
+ * @returns {string} Zero-padded sequence, at least four digits.
+ */
+function nextSequence(names) {
+  // `max` starts at -1 so a fresh directory sequences from 0000.
+  let max = -1;
+  for (const name of names) {
+    const match = /^(\d+)-/.exec(name);
+    if (match) max = Math.max(max, Number.parseInt(match[1], 10));
+  }
+  const width = Math.max(4, String(max + 1).length);
+  return String(max + 1).padStart(width, "0");
+}
+/**
+ * The short filename suffix for an event id — history's `shortId` (`../commands/history.mjs`):
+ * first 8 hex characters.
+ *
+ * @param {string} id Full hex SHA-256 from `eventId`.
+ * @returns {string} First 8 hex characters.
+ */
+function shortId(id) {
+  return id.slice(0, 8);
+}
+
+/**
+ * Refuses an event whose identity does not match its content. `id` and
+ * `dedupeKey` are derived, never free-form: a record whose fields disagree
+ * with the canonical tuple would dedupe against the wrong key on rerun and
+ * silently manufacture duplicates — the failure shape this store exists to
+ * rule out.
+ *
+ * @param {object} event The event to write.
+ * @throws {Error} naming the mismatch.
+ */
+function validateEventForWrite(event) {
+  if (typeof event !== "object" || event === null || Array.isArray(event)) {
+    throw new Error("archkeep: writeEvent requires an EvolutionEvent object");
+  }
+  const expectedId = eventId(event);
+  const expectedKey = eventDedupeKey(event);
+  if (typeof event.id !== "string") {
+    throw new Error("archkeep: refusing to write the evolution event: the record carries no 'id'");
+  }
+  if (event.id !== expectedId) {
+    throw new Error(
+      "archkeep: refusing to write the evolution event: its 'id' does not match the canonical " +
+        "tuple {base, head, declarationDigest}",
+    );
+  }
+  if (typeof event.dedupeKey !== "string") {
+    throw new Error(
+      "archkeep: refusing to write the evolution event: the record carries no 'dedupeKey'",
+    );
+  }
+  if (event.dedupeKey !== expectedKey) {
+    throw new Error(
+      "archkeep: refusing to write the evolution event: its 'dedupeKey' does not match the canonical " +
+        "tuple {base, head, declarationDigest}",
+    );
+  }
+}
+
+/**
+ * The three validations every stored event must pass: the schema version, the
+ * classification subset, and the disposition. Any other shape is a malformed
+ * store — thrown, never read as an event.
+ *
+ * @param {object} parsed The parsed record.
+ * @param {string} path The file it came from, for the error message.
+ * @throws {Error} naming the file and the violated check.
+ */
+function validateEventRecord(parsed, path) {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `archkeep: malformed evolution event '${path}': the record is not a JSON object`,
+    );
+  }
+  if (parsed.schemaVersion !== EVOLUTION_EVENT_SCHEMA_VERSION) {
+    throw new Error(
+      `archkeep: malformed evolution event '${path}': schemaVersion ${JSON.stringify(
+        parsed.schemaVersion,
+      )} is not ${EVOLUTION_EVENT_SCHEMA_VERSION}`,
+    );
+  }
+  if (
+    !Array.isArray(parsed.classifications) ||
+    parsed.classifications.some((entry) => !EVENT_CLASSIFICATIONS.includes(entry))
+  ) {
+    throw new Error(
+      `archkeep: malformed evolution event '${path}': classifications must be a subset of ` +
+        `[${EVENT_CLASSIFICATIONS.join(", ")}]`,
+    );
+  }
+  if (!EVENT_DISPOSITIONS.includes(parsed.disposition)) {
+    throw new Error(
+      `archkeep: malformed evolution event '${path}': disposition ${JSON.stringify(
+        parsed.disposition,
+      )} is not one of [${EVENT_DISPOSITIONS.join(", ")}]`,
+    );
+  }
+}
+
+/**
+ * Appends one event to the store at `dir`.
+ *
+ * Idempotency first: the directory is scanned for an event whose `dedupeKey`
+ * matches BEFORE anything is written; a match returns `{id, duplicate: true}`
+ * and writes nothing. Then the event is written atomically
+ * (`<path>.json.tmp` + rename, `{flag: "wx"}`) under a containment check
+ * against `io.root`. A missing directory is an empty store: it is created
+ * before the scan, so the first event in a fresh store lands at `0000`.
+ *
+ * The event's `id`/`dedupeKey` must match the canonical tuple (see
+ * `validateEventForWrite`) — a caller cannot persist a record whose identity
+ * lies about its content.
+ *
+ * @param {string} dir Absolute or relative path to the event store directory.
+ * @param {object} event The EvolutionEvent to append.
+ * @param {{root?: string, readdirSync?: (path: string) => string[],
+ *   readFileSync?: (path: string, encoding: "utf8") => string,
+ *   writeFileSync?: (path: string, text: string, options: object) => void,
+ *   renameSync?: (from: string, to: string) => void,
+ *   mkdirSync?: (path: string, options: {recursive: boolean}) => void,
+ *   lstatSync?: (path: string) => {isSymbolicLink: () => boolean},
+ *   realpathSync?: (path: string) => string}} [io]
+ *   Injectable filesystem seams, defaulting to the sync `node:fs` calls this
+ *   module uses; `root` is the workspace root the containment check is made
+ *   against and is REQUIRED for a write.
+ * @returns {{id: string, duplicate: boolean}} The event id, and whether this
+ *   call wrote nothing because the event already existed.
+ * @throws {Error} on a mismatched event identity, an unreadable or malformed
+ *   store, a containment violation, or a `wx` refusal.
+ */
+export function writeEvent(dir, event, io = {}) {
+  validateEventForWrite(event);
+
+  const readDir = io.readdirSync ?? defaultReaddir;
+  const readFile = io.readFileSync ?? defaultReadFile;
+  const writeFile = io.writeFileSync ?? defaultWriteFile;
+  const rename = io.renameSync ?? defaultRename;
+  const makeDir = io.mkdirSync ?? defaultMkdir;
+  const lstat = io.lstatSync ?? defaultLstat;
+  const realpath = io.realpathSync ?? defaultRealpath;
+
+  // Resolved once: the identical string feeds the containment check and the
+  // actual write (`../containment.mjs`, "One contract binds the WRITE call
+  // sites"). `resolve` also collapses any `..`, which containment refuses raw.
+  const dirAbs = resolve(dir);
+
+  let names;
+  try {
+    names = readDir(dirAbs);
+  } catch (cause) {
+    if (cause?.code === "ENOENT") {
+      // An absent optional store is an empty store: the caller's first event.
+      makeDir(dirAbs, { recursive: true });
+      names = readDir(dirAbs);
+    } else {
+      throw new Error(
+        `archkeep: cannot read the event store '${dirAbs}': ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
+  }
+
+  const eventNames = names.filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"));
+  eventNames.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  // The dedupe scan. A file that cannot be parsed, or that parses to a record
+  // without a string dedupeKey, throws: a store this module cannot read must
+  // not be silently appended to — the unreadable file may BE the duplicate.
+  for (const name of eventNames) {
+    const existingPath = join(dirAbs, name);
+    let text;
+    try {
+      text = readFile(existingPath, "utf8");
+    } catch (cause) {
+      throw new Error(
+        `archkeep: cannot read the evolution event '${existingPath}': ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (cause) {
+      throw new Error(
+        `archkeep: malformed evolution event '${existingPath}': ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
+    if (typeof parsed?.dedupeKey !== "string") {
+      throw new Error(
+        `archkeep: malformed evolution event '${existingPath}': the record carries no string 'dedupeKey'`,
+      );
+    }
+    if (parsed.dedupeKey === event.dedupeKey) {
+      return { id: event.id, duplicate: true };
+    }
+  }
+
+  const sequence = nextSequence(eventNames);
+  const name = `${sequence}-${shortId(event.id)}.json`;
+  const path = join(dirAbs, name);
+
+  if (io.root === undefined) {
+    throw new Error(
+      "archkeep: writing an evolution event requires io.root — the workspace root — so the " +
+        "write can be proven to stay inside the workspace",
+    );
+  }
+  const violation = containmentViolation(io.root, path, {
+    forWrite: true,
+    lstatSync: lstat,
+    realpathSync: realpath,
+  });
+  if (violation !== null) {
+    throw new Error(`archkeep: refusing to write the evolution event '${path}': ${violation}`);
+  }
+
+  const tmp = `${path}.tmp`;
+  writeFile(tmp, `${JSON.stringify(event, null, 2)}\n`, { flag: "wx" });
+  rename(tmp, path);
+
+  return { id: event.id, duplicate: false };
+}
+
+/**
+ * Reads and validates every event in the store at `dir`, in filename order
+ * (the append order). A malformed file — JSON that does not parse, a
+ * non-object record, a wrong `schemaVersion`, a classification outside the
+ * vocabulary, a disposition outside the vocabulary — THROWS; the command layer
+ * maps that to exit 3, and "could not read the store" never reads as "no
+ * events recorded" (the invariant: an empty result is a claim, not a shrug).
+ * A missing directory is `[]` — an absent OPTIONAL store is not an error, and
+ * the caller states "no events recorded" itself when that matters.
+ *
+ * `.json.tmp` files are filtered out: an interrupted write leaves one behind,
+ * and it must never count as an event.
+ *
+ * @param {string} dir Path to the event store directory.
+ * @param {{readdirSync?: (path: string) => string[],
+ *   readFileSync?: (path: string, encoding: "utf8") => string}} [io]
+ * @returns {object[]} The validated events, in append order.
+ * @throws {Error} on the first unreadable or malformed event file.
+ */
+export function readEvents(dir, io = {}) {
+  const readDir = io.readdirSync ?? defaultReaddir;
+  const readFile = io.readFileSync ?? defaultReadFile;
+
+  const dirAbs = resolve(dir);
+
+  let names;
+  try {
+    names = readDir(dirAbs);
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return [];
+    throw new Error(
+      `archkeep: cannot read the event store '${dirAbs}': ${cause?.message ?? cause}`,
+      { cause },
+    );
+  }
+
+  const eventNames = names.filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"));
+  eventNames.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  const events = [];
+  for (const name of eventNames) {
+    const path = join(dirAbs, name);
+    let text;
+    try {
+      text = readFile(path, "utf8");
+    } catch (cause) {
+      throw new Error(
+        `archkeep: cannot read the evolution event '${path}': ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (cause) {
+      throw new Error(`archkeep: malformed evolution event '${path}': ${cause?.message ?? cause}`, {
+        cause,
+      });
+    }
+    validateEventRecord(parsed, path);
+    events.push(parsed);
+  }
+  return events;
+}

package/src/governance/provenance-record.mjs

@@ -37,8 +37,17 @@
  * or a polluted prototype cannot smuggle keys into a validated origin. This
  * module builds nothing from untrusted keys; it validates and, at write time,
  * builds a fresh object with only the three permitted keys.
+ * ## The decision-lifecycle record
+ *
+ * The same discipline extends from a row to a DECISION (an ADR id — the
+ * stable handle later waves reference). `recordDecisionLifecycle` records one
+ * lifecycle event — a status transition, a supersession, or a bindings
+ * change — attributed by the same `origin` shape and the same clock door:
+ * `by`/`tool` are required, and `on` comes from `recordOrigin` and nowhere
+ * else. A record that records nothing (a no-op transition) is refused loudly.
  */
 
+import { ADR_STATUSES } from "./adr-registry.mjs";
 import { clockViolations } from "./clock.mjs";
 
 /** The only keys a validated `origin` may carry. */
@@ -175,3 +184,144 @@ export function recordOrigin({ by, tool, clock }) {
   // record, so two calls with the same clock are byte-identical.
   return { by, tool, on: clock.now() };
 }
+/**
+ * The decision-lifecycle events one record can hold, each a single fact about
+ * ONE decision (an ADR id — `docs/adr/NNN-slug.md` — the stable handle the
+ * registry's `byId` map keys on). A decision's creation and every status
+ * change, supersession, and bindings change is recorded as one of these.
+ */
+export const DECISION_LIFECYCLE_KINDS = Object.freeze([
+  "status-transition",
+  "supersession",
+  "bindings-change",
+]);
+
+/**
+ * @typedef {object} DecisionLifecycleRecord
+ * @property {"status-transition"|"supersession"|"bindings-change"} kind
+ *   One recorded lifecycle event on one decision.
+ * @property {string} decisionId The ADR id the event happened to — the stable
+ *   handle the ADR registry keys on (`docs/adr/NNN-slug.md`).
+ * @property {string|null} [from] status-transition: the status the decision
+ *   left, or null when the event is the decision's creation (its proposed
+ *   entry).
+ * @property {string} [to] status-transition: the status the decision entered.
+ * @property {string[]} [superseded] supersession: the ADR id(s) this decision
+ *   replaced — `decisionId` is the RECORDING record, the successor.
+ * @property {string[]} [added] bindings-change: constraint ids made
+ *   enforceable.
+ * @property {string[]} [removed] bindings-change: constraint ids unbound.
+ * @property {OriginRecord} origin WHO recorded the event and with what tool —
+ *   `on` produced by `recordOrigin`, the only door.
+ */
+
+/**
+ * Records one decision-lifecycle event, attributed by the same `origin`
+ * discipline as a row: `by` and `tool` are required, and `on` comes from the
+ * injected clock through `recordOrigin` — the only producer of an `on`, and
+ * the refusal to run without one is its own, inherited here.
+ *
+ * The record carries ONLY the kind's own keys and the origin, built fresh, so
+ * nothing from untrusted input rides along. A no-op event — a status
+ * transition that changes nothing, a supersession naming no target, a
+ * bindings change that adds and removes nothing — is refused loudly: a record
+ * that records nothing would read as a transition that happened, the silent
+ * direction this module exists to exclude.
+ *
+ * Statuses are validated against `ADR_STATUSES` (`./adr-registry.mjs`), the
+ * single status vocabulary — a record can never attest a status the registry
+ * could not hold.
+ *
+ * @param {{kind: "status-transition"|"supersession"|"bindings-change",
+ *   decisionId: string,
+ *   from?: string|null, to?: string,
+ *   superseded?: string[],
+ *   added?: string[], removed?: string[],
+ *   origin: {by: string, tool: string},
+ *   clock: import("./clock.mjs").Clock}} event
+ * @returns {DecisionLifecycleRecord}
+ * @throws {Error} on an unknown kind, a missing decisionId, a status outside
+ *   the registry's `ADR_STATUSES`, a no-op event, or an invalid origin/clock.
+ */
+export function recordDecisionLifecycle({
+  kind,
+  decisionId,
+  from = null,
+  to,
+  superseded,
+  added,
+  removed,
+  origin,
+  clock,
+}) {
+  const violations = [];
+  if (!DECISION_LIFECYCLE_KINDS.includes(kind)) {
+    violations.push(
+      `kind: must be one of ${DECISION_LIFECYCLE_KINDS.join(", ")}, got ${describe(kind)}`,
+    );
+  }
+  if (typeof decisionId !== "string" || decisionId.trim() === "") {
+    violations.push(
+      `decisionId: must be a non-empty string naming the ADR, got ${describe(decisionId)}`,
+    );
+  }
+  if (kind === "status-transition") {
+    if (from !== null && !ADR_STATUSES.includes(from)) {
+      violations.push(
+        `from: must be null or one of ${ADR_STATUSES.join(", ")}, got ${describe(from)}`,
+      );
+    }
+    if (!ADR_STATUSES.includes(to)) {
+      violations.push(`to: must be one of ${ADR_STATUSES.join(", ")}, got ${describe(to)}`);
+    }
+    if (from !== null && from === to) {
+      violations.push(
+        `to: equals from (${JSON.stringify(from)}) — a status transition that changes nothing is not a recordable event`,
+      );
+    }
+  } else if (kind === "supersession") {
+    if (
+      !Array.isArray(superseded) ||
+      superseded.length === 0 ||
+      superseded.some((ref) => typeof ref !== "string" || ref.trim() === "")
+    ) {
+      violations.push("superseded: must be a non-empty array of ADR ids this decision replaced");
+    }
+  } else if (kind === "bindings-change") {
+    for (const [name, value] of [
+      ["added", added],
+      ["removed", removed],
+    ]) {
+      if (value !== undefined && !Array.isArray(value)) {
+        violations.push(`${name}: must be an array of constraint ids, got ${describe(value)}`);
+      } else if (
+        Array.isArray(value) &&
+        value.some((id) => typeof id !== "string" || id.trim() === "")
+      ) {
+        violations.push(`${name}: every entry must be a non-empty constraint id`);
+      }
+    }
+    const addedList = Array.isArray(added) ? added : [];
+    const removedList = Array.isArray(removed) ? removed : [];
+    if (addedList.length === 0 && removedList.length === 0) {
+      violations.push(
+        "added/removed: a bindings change that adds nothing and removes nothing is not a recordable event",
+      );
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`decisionLifecycle: ${violations.join("; ")}`);
+  }
+  const eventFields =
+    kind === "status-transition"
+      ? { from, to }
+      : kind === "supersession"
+        ? { superseded }
+        : { added: added ?? [], removed: removed ?? [] };
+  return {
+    kind,
+    decisionId,
+    ...eventFields,
+    origin: recordOrigin({ by: origin?.by, tool: origin?.tool, clock }),
+  };
+}

package/src/providers/native/model.mjs

@@ -246,6 +246,10 @@ const PROJECT_TYPES = ["app", "lib", "e2e"];
  * An explicit `exclude` list REPLACES this default (the `tsc` convention for
  * the same field): a workspace that names its own list takes over the whole
  * decision, `exclude: []` included — that spelling is the documented opt-out.
+ * `excludeBeyondDefaults` extends the effective set — the defaults when
+ * `exclude` is absent, an explicit list when it is present — without restating
+ * it, so a workspace with `testdata/` or `golden/` directories does not copy
+ * these three patterns by hand (issue #389).
  *
  * @see DEFAULT_MANIFEST_NAMES
  */
@@ -375,7 +379,7 @@ function declaredProjectViolations(row, index) {
   return violations;
 }
 
-const INFER_KEYS = ["manifests", "include", "exclude"];
+const INFER_KEYS = ["manifests", "include", "exclude", "excludeBeyondDefaults"];
 
 /** `projects.infer`'s problems, or `[]` when the key is absent — absent means "use the defaults", not "malformed". */
 function inferViolations(value) {
@@ -385,6 +389,11 @@ function inferViolations(value) {
     ...stringListViolations(value.manifests, "projects.infer.manifests"),
     ...stringListViolations(value.include, "projects.infer.include", globComplexityError),
     ...stringListViolations(value.exclude, "projects.infer.exclude", globComplexityError),
+    ...stringListViolations(
+      value.excludeBeyondDefaults,
+      "projects.infer.excludeBeyondDefaults",
+      globComplexityError,
+    ),
   ];
   // `[]` and "omit the key" both validate against `stringListViolations` above
   // — a list is still a list at length zero — but they must not mean the same
@@ -758,9 +767,14 @@ export function normalizeNativeModel(raw) {
           : {
               manifests: rawInfer.manifests ?? DEFAULT_MANIFEST_NAMES,
               include: rawInfer.include ?? ["**"],
-              // Replaces, never merges: an explicit list takes over the whole
-              // decision — `DEFAULT_INFER_EXCLUDE`'s doc comment owns the why.
-              exclude: rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE,
+              // `exclude` replaces the defaults (`DEFAULT_INFER_EXCLUDE`'s doc
+              // comment owns the why); `excludeBeyondDefaults` then extends the
+              // effective set — the defaults when `exclude` is absent, the
+              // explicit list when it is present — without restating it.
+              exclude: [
+                .../** @type {string[]|undefined} */ (rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE),
+                .../** @type {string[]|undefined} */ (rawInfer.excludeBeyondDefaults ?? []),
+              ],
             },
     },
     projectRules: /** @type {unknown[]} */ (raw.projectRules ?? []).map((row) => {