@intentius/chant 0.82.0 → 0.83.0

package/src/workspace/record-assets.ts

@@ -0,0 +1,207 @@
+/**
+ * Asset pins and record links (#2549; #2524 D4, D6, D18).
+ *
+ * Artifact relationships are derived from decisions. A decision record pins
+ * the workspace files it rests on in `evidence`, each as `{title, path,
+ * sha256}`, and names what it governs in `constrains`, as `member:<name>` or
+ * `path:<path>`. There is no direct link from a design artifact to code or to
+ * another artifact: a reader walks from a file to the decisions whose
+ * `constrains` cover it, and from them to their pinned assets.
+ *
+ * A pin is checked against the tree a read looks at (the working tree, or a
+ * revision's git objects). A file whose bytes hash differently is `drifted`,
+ * and one that is gone is `missing`. Neither makes the record invalid: the
+ * record is still what was decided, and the drift is reported beside it.
+ *
+ * Which front-matter fields hold pins and links is the kind's data
+ * (`pins.field`, `constrains.field`), so this module never names `evidence`.
+ */
+
+import { sha256Hex } from "../content-digest";
+import type { RecordWarning } from "./records";
+import type { WorkspaceTree } from "./tree";
+
+/**
+ * A path from the workspace root: `/` separators, no leading `/`, no `.` or
+ * `..` segment, no empty segment, no backslash or control character and no
+ * trailing `/`. The decision schema holds the same pattern.
+ */
+export const WORKSPACE_PATH_PATTERN = String.raw`(?!/)(?!(?:[^/]*/)*\.{1,2}(?:/|$))(?!.*//)[^\\\u0000-\u001f]*[^/\\\u0000-\u001f]`;
+const WORKSPACE_PATH = new RegExp(`^${WORKSPACE_PATH_PATTERN}$`, "u");
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export function isWorkspacePath(value: unknown): value is string {
+  return typeof value === "string" && WORKSPACE_PATH.test(value);
+}
+
+/**
+ * `pinned`: the file hashes to the pin. `drifted`: it doesn't. `missing`: it
+ * isn't there. `stale`: it hashes to the pin, which a record this one
+ * supersedes pinned too, so the decision changed and the artifact did not.
+ */
+export type PinState = "pinned" | "drifted" | "missing" | "stale";
+
+/** One pinned file, as the tree read has it. */
+export interface AssetPin {
+  /** From the workspace root. */
+  path: string;
+  /** The hash the record pins. */
+  sha256: string;
+  /** The hash of the file in the tree read, or null when it is missing. */
+  actual: string | null;
+  state: PinState;
+}
+
+/** The well-formed pins in a record's `field` list: entries with a workspace path and a hex sha256. */
+export function pinEntries(data: Record<string, unknown> | null, field: string): { path: string; sha256: string }[] {
+  const list = data?.[field];
+  if (!Array.isArray(list)) return [];
+  const out: { path: string; sha256: string }[] = [];
+  for (const e of list) {
+    if (e === null || typeof e !== "object" || Array.isArray(e)) continue;
+    const { path, sha256 } = e as Record<string, unknown>;
+    if (isWorkspacePath(path) && typeof sha256 === "string" && SHA256.test(sha256)) out.push({ path, sha256 });
+  }
+  return out;
+}
+
+/** The hex SHA-256 of the file at `path` in `tree`, or undefined when it is not a file there. */
+export function fileDigest(tree: WorkspaceTree, path: string): string | undefined {
+  if (tree.stat(path) !== "file") return undefined;
+  const bytes = tree.bytes ? tree.bytes(path) : Buffer.from(tree.read(path), "utf-8");
+  return sha256Hex(bytes);
+}
+
+/** Check each pin against `tree`, rooted at the workspace root. */
+export function checkPins(pins: { path: string; sha256: string }[], tree: WorkspaceTree): { assets: AssetPin[]; warnings: RecordWarning[] } {
+  const assets: AssetPin[] = [];
+  const warnings: RecordWarning[] = [];
+  for (const pin of pins) {
+    const actual = fileDigest(tree, pin.path) ?? null;
+    const state: PinState = actual === null ? "missing" : actual === pin.sha256 ? "pinned" : "drifted";
+    assets.push({ ...pin, actual, state });
+    if (state === "missing") {
+      warnings.push({ code: "asset-missing", message: `evidence pins ${pin.path}, which does not exist${tree.label}` });
+    } else if (state === "drifted") {
+      warnings.push({
+        code: "asset-drift",
+        message: `${pin.path} changed since it was pinned: sha256 ${pin.sha256.slice(0, 12)} is pinned, the file${tree.label} hashes to ${actual!.slice(0, 12)}`,
+      });
+    }
+  }
+  return { assets, warnings };
+}
+
+// ── Record links ─────────────────────────────────────────────────────────────
+
+/** The kinds of link a record has in `chant workspace graph`. Closed. */
+export const RECORD_LINK_KINDS = ["asset", "constrains"] as const;
+
+/** A link from a record to a workspace path or member, a row of the graph's `links`. */
+export interface RecordLinkRow {
+  kind: (typeof RECORD_LINK_KINDS)[number];
+  origin: "declared";
+  resolves: "source";
+  /** The record's kind, such as `decision`. */
+  recordKind: string;
+  /** The record's id. */
+  record: string;
+  /** The record file, from the repository root. */
+  recordPath: string;
+  /** For `asset`, the pinned path; for `constrains`, the entry as written (`member:<name>` or `path:<path>`). */
+  target: string;
+  /** The member the target is, or holds it; null when no member does. */
+  member: string | null;
+  /** `pinned`, `drifted`, `missing` or `stale` for an asset; `resolved` or `missing` for constrains. */
+  status: PinState | "resolved";
+  reason: string | null;
+  /** For an asset: the pinned hash and the hash in the tree read. */
+  sha256?: string;
+  actual?: string | null;
+}
+
+/** The member whose directory holds `path` (the deepest one), or null. */
+export function memberHolding(path: string, members: readonly { name: string; dir: string }[]): string | null {
+  let best: { name: string; dir: string } | null = null;
+  for (const m of members) {
+    const inside = m.dir === "." || path === m.dir || path.startsWith(`${m.dir}/`);
+    if (inside && (!best || best.dir === "." || m.dir.length > best.dir.length)) best = m;
+  }
+  return best?.name ?? null;
+}
+
+/** Whether a `path:` constraint covers `file`: the same path, or a directory above it. */
+export function constraintCovers(constraint: string, file: string): boolean {
+  return file === constraint || file.startsWith(`${constraint}/`);
+}
+
+/** A record as the link rows read it. */
+export interface LinkedRecord {
+  id: string | null;
+  path: string;
+  supersededBy: string | null;
+  data: Record<string, unknown> | null;
+  assets: AssetPin[];
+}
+
+/**
+ * The link rows of the records of one kind: an `asset` row per pin and a
+ * `constrains` row per `member:` or `path:` entry. Superseded records and
+ * records with no id have none, since their links no longer hold. Paths
+ * resolve in `tree` (the workspace root), members in `members`.
+ */
+export function recordLinkRows(
+  kindName: string,
+  records: readonly LinkedRecord[],
+  constrainsField: string | undefined,
+  tree: WorkspaceTree,
+  members: readonly { name: string; dir: string }[],
+): RecordLinkRow[] {
+  const rows: RecordLinkRow[] = [];
+  for (const r of records) {
+    if (r.id === null || r.supersededBy !== null) continue;
+    const base = { origin: "declared" as const, resolves: "source" as const, recordKind: kindName, record: r.id, recordPath: r.path };
+    for (const a of r.assets) {
+      rows.push({
+        kind: "asset",
+        ...base,
+        target: a.path,
+        member: memberHolding(a.path, members),
+        status: a.state,
+        reason:
+          a.state === "missing"
+            ? `${a.path} does not exist${tree.label}`
+            : a.state === "drifted"
+              ? `${a.path} changed since ${r.id} pinned it`
+              : a.state === "stale"
+                ? `${a.path} has not changed since a record ${r.id} supersedes pinned it`
+                : null,
+        sha256: a.sha256,
+        actual: a.actual,
+      });
+    }
+    const list = constrainsField ? r.data?.[constrainsField] : undefined;
+    if (!Array.isArray(list)) continue;
+    for (const entry of list) {
+      if (typeof entry !== "string") continue;
+      if (entry.startsWith("member:")) {
+        const name = entry.slice("member:".length);
+        const known = members.some((m) => m.name === name);
+        rows.push({ kind: "constrains", ...base, target: entry, member: known ? name : null, status: known ? "resolved" : "missing", reason: known ? null : `${name} is not a member of this workspace` });
+      } else if (entry.startsWith("path:")) {
+        const path = entry.slice("path:".length);
+        if (!isWorkspacePath(path)) continue;
+        const exists = tree.stat(path) !== undefined;
+        rows.push({
+          kind: "constrains",
+          ...base,
+          target: entry,
+          member: memberHolding(path, members),
+          status: exists ? "resolved" : "missing",
+          reason: exists ? null : `${path} does not exist${tree.label}`,
+        });
+      }
+    }
+  }
+  return rows;
+}

package/src/workspace/records-cli.ts

@@ -12,12 +12,16 @@
  * nothing is inferred (#2525 rule 1).
  */
 
+import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
+import { findWorkspaceRoot } from "../project-root";
+import { fileDigest, isWorkspacePath } from "./record-assets";
 import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
-import { loadRecordKind, readRecords, RecordReadError, type ReadErrorCode, type RecordEntry } from "./records";
+import { loadRecordKind, readRecords, RecordReadError, type LoadedRecordKind, type ReadErrorCode, type ReadRecordsResult, type RecordEntry, type RecordHistory } from "./records";
+import { gitTree, workingTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
 
@@ -27,7 +31,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 /** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
-const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]";
+const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records pin <path>";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -63,6 +67,8 @@ export type RecordsDocument =
       contract: number;
       kind: { name: string; schema: string; file: string };
       at: string | null;
+      /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
+      workspaceRoot: string;
       current: boolean;
       trust: TrustView;
       records: RecordView[];
@@ -70,23 +76,84 @@ export type RecordsDocument =
     }
   | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
 
-/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
-export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
+/** A records read, before provenance. */
+export interface RecordsRead {
+  loaded: LoadedRecordKind;
+  /** The repository root, or the working directory outside git. Record paths are relative to it. */
+  root: string;
+  /** The git top, or undefined outside git. */
+  top: string | undefined;
+  at: string | null;
+  /** Where pinned paths resolve, relative to `root` ("." for the root itself). */
+  workspaceRoot: string;
+  result: ReadRecordsResult;
+}
+
+/**
+ * Where a kind's pinned paths resolve: the workspace whose declaration sits
+ * nearest above the kind file, when it is inside the repository, or else the
+ * repository root. Relative to `root`, with / separators.
+ */
+function pinRoot(kindFile: string, root: string): string {
+  const found = findWorkspaceRoot(dirname(kindFile));
+  if (!found) return ".";
+  const rel = relative(root, realpathOr(found.dir)).split(sep).join("/");
+  return rel === "" || rel.startsWith("..") ? "." : rel;
+}
+
+/**
+ * Commit times from the history of `rev` in the repository at `top`, asked
+ * only for a pin that might be stale. `prefix` is the workspace root from the
+ * repository root.
+ */
+function gitHistory(top: string, rev: string, prefix: string): RecordHistory {
+  const times = (args: string[]): number[] => {
+    try {
+      const out = execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+      return out.split("\n").filter(Boolean).map(Number);
+    } catch {
+      // No commits yet, or a path git doesn't know.
+      return [];
+    }
+  };
+  return {
+    fileChanged: (path) => times(["log", "-1", "--format=%ct", rev, "--", prefix === "." ? path : `${prefix}/${path}`])[0] ?? null,
+    // The latest commit that added the file: a record deleted and written again counts from the second time.
+    recorded: (path) => times(["log", "--diff-filter=A", "--format=%ct", rev, "--", path])[0] ?? null,
+  };
+}
+
+/**
+ * Load the kind and read its records, in the working tree or at `query.at`,
+ * with each pin checked in the same tree. Throws a {@link RecordReadError}.
+ * `chant workspace graph` and `check` read records through this too.
+ */
+export async function readRecordsFor(query: Omit<RecordsQuery, "base">): Promise<RecordsRead> {
   // git reports its top through symlinks resolved (/var is /private/var on
   // macOS), so the directory has to be too, or record paths leave the repository.
   const cwd = realpathOr(query.cwd);
   const top = gitRoot(cwd);
   const root = top ?? cwd;
+  const loaded = await loadRecordKind(query.kind, cwd);
+  const workspaceRoot = pinRoot(loaded.file, root);
+  let at: string | null = null;
+  let source = workingTreeSource(root);
+  let assets = workingTree(workspaceRoot === "." ? root : join(root, ...workspaceRoot.split("/")));
+  if (query.at !== undefined) {
+    if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+    at = resolveRevision(top, query.at);
+    source = gitRevisionSource(top, at);
+    assets = gitTree(top, at, workspaceRoot === "." ? "" : workspaceRoot);
+  }
+  const history = top ? gitHistory(top, at ?? "HEAD", workspaceRoot) : undefined;
+  const result = await readRecords(loaded, { root, source, current: !!query.current, assets, ...(history ? { history } : {}) });
+  return { loaded, root, top, at, workspaceRoot, result };
+}
+
+/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
+export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
   try {
-    const loaded = await loadRecordKind(query.kind, cwd);
-    let at: string | null = null;
-    let source = workingTreeSource(root);
-    if (query.at !== undefined) {
-      if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
-      at = resolveRevision(top, query.at);
-      source = gitRevisionSource(top, at);
-    }
-    const result = await readRecords(loaded, { root, source, current: !!query.current });
+    const { loaded, root, top, at, workspaceRoot, result } = await readRecordsFor(query);
     // Provenance, judged by the policy at base and never by the tree read (#2547).
     const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
     const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
@@ -106,6 +173,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
         file: relative(root, loaded.file).split("\\").join("/"),
       },
       at,
+      workspaceRoot,
       current: !!query.current,
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
       records: result.records.map((r) => ({ ...r, provenance: provenance.get(r.path)! })),
@@ -117,8 +185,42 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   }
 }
 
+/**
+ * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
+ * evidence entry holds for a file, with the path from the workspace root
+ * (the nearest declaration above the file, or the repository root).
+ */
+export function pinFile(file: string, cwd: string): { path: string; sha256: string } | { error: string } {
+  const abs = realpathOr(resolve(cwd, file));
+  const top = gitRoot(dirname(abs));
+  const ws = findWorkspaceRoot(dirname(abs));
+  const base = ws ? realpathOr(ws.dir) : top ? realpathOr(top) : realpathOr(cwd);
+  const path = relative(base, abs).split(sep).join("/");
+  if (path.startsWith("..") || !isWorkspacePath(path)) return { error: `${file} is not a file path inside the workspace at ${base}` };
+  const sha256 = fileDigest(workingTree(base), path);
+  if (sha256 === undefined) return { error: `${file} is not a file` };
+  return { path, sha256 };
+}
+
 export async function runWorkspaceRecords(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (args.extraPositional === "pin") {
+    if (!args.extraPositional2) {
+      console.error(formatError({ message: "pin needs the path of a file", hint: USAGE }));
+      return 1;
+    }
+    const pin = pinFile(args.extraPositional2, process.cwd());
+    if ("error" in pin) {
+      console.error(formatError({ message: pin.error, hint: USAGE }));
+      return 1;
+    }
+    console.log(JSON.stringify(pin, null, 2));
+    return 0;
+  }
+  if (args.extraPositional) {
+    console.error(formatError({ message: `chant workspace records takes no argument but pin (got ${args.extraPositional})`, hint: USAGE }));
+    return 1;
+  }
   if (!args.kind) {
     console.error(formatError({ message: "--kind <kind file> is required", hint: USAGE }));
     return 1;
@@ -178,6 +280,7 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${flag}`);
     for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
+    for (const warning of r.warnings) lines.push(`${" ".repeat(idWidth + 2)}warning ${warning.code}: ${warning.message} (${r.path})`);
   }
   lines.push(
     `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,

package/src/workspace/records.schema.json

@@ -26,6 +26,10 @@
           "type": ["string", "null"],
           "pattern": "^[0-9a-f]{40,64}$"
         },
+        "workspaceRoot": {
+          "type": "string",
+          "description": "Added in contract 1 by #2549. The directory a record's pinned paths resolve in, from the repository root with / separators: the workspace whose declaration sits nearest above the kind file, or \".\" for the repository root."
+        },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
         "trust": { "$ref": "#/$defs/trust" },
@@ -63,7 +67,17 @@
           "type": ["object", "null"],
           "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
         },
-        "provenance": { "$ref": "#/$defs/provenance" }
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "assets": {
+          "description": "Added in contract 1 by #2549. Each workspace file the record pins by hash, checked against the tree read: the working tree, or the revision under --at. Empty for a kind that pins nothing.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/asset" }
+        },
+        "warnings": {
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, or a supersedes link that has no effect yet. valid and --current do not look at them.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/warning" }
+        }
       },
       "allOf": [
         {
@@ -73,6 +87,24 @@
         }
       ]
     },
+    "asset": {
+      "type": "object",
+      "required": ["path", "sha256", "actual", "state"],
+      "properties": {
+        "path": { "type": "string", "description": "From the workspace root (workspaceRoot), with / separators." },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The hash the record pins." },
+        "actual": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "The hash of the file's bytes in the tree read, or null when the file is missing." },
+        "state": { "enum": ["pinned", "drifted", "missing", "stale"], "description": "pinned when the hashes match; drifted when they differ (a warning asset-drift); missing when the file is not there (a warning asset-missing); stale when the hashes match and a record this one supersedes pinned the same hash, with the file unchanged since this record was recorded (a warning asset-stale)." }
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"] },
+        "message": { "type": "string" }
+      }
+    },
     "trust": {
       "description": "Added in contract 1 by #2547. Where provenance was judged from: the policy read at the base revision, never the tree read.",
       "type": "object",

package/src/workspace/records.test.ts

@@ -133,6 +133,56 @@ describe("readRecords", () => {
     ]);
   });
 
+  test("a decided record supersedes a decided one, under an equal approval rule (#2524 D4)", async () => {
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.valid, r.warnings])).toEqual([
+      ["ws-001", "ws-002", true, []],
+      ["ws-002", null, true, []],
+    ]);
+    const current = await read({ current: true });
+    expect(current.records.map((r) => r.id)).toEqual(["ws-002"]);
+  });
+
+  test("a proposed record supersedes nothing: the link is pending, as a warning on the new record", async () => {
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "proposed", ["ws-001"]).replace(/^choice:\n  option: .*\n  reason: .*\n/m, "choice: null\n"));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.valid])).toEqual([
+      ["ws-001", null, true],
+      ["ws-002", null, true],
+    ]);
+    expect(all.records[1].warnings.map((w) => w.code)).toEqual(["record-supersedes-pending"]);
+    expect((await read({ current: true })).records.map((r) => r.id)).toEqual(["ws-001", "ws-002"]);
+  });
+
+  test("a decided record can't supersede a ratified one; a ratified record supersedes any", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    write("ws-003-c.md", decision("ws-003", "decided"));
+    write("ws-004-d.md", decision("ws-004", "ratified", ["ws-003"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-001", null, []],
+      ["ws-002", null, ["record-supersedes-pending"]],
+      ["ws-003", "ws-004", []],
+      ["ws-004", null, []],
+    ]);
+  });
+
+  test("a kind without approval ranks keeps the closed-state rule", async () => {
+    const kind = readFileSync(join(dir, "decisions", "decision.kind.mjs"), "utf-8").replace(/^  approval: .*\n/m, "");
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), kind);
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.warnings])).toEqual([
+      ["ws-001", null, []],
+      ["ws-002", null, []],
+    ]);
+  });
+
   test("a record superseded twice keeps the first and flags the second", async () => {
     write("ws-001-a.md", decision("ws-001", "ratified"));
     write("ws-002-b.md", decision("ws-002", "ratified", ["ws-001"]));