@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/records.test.ts

@@ -0,0 +1,243 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { lexiconModulePath } from "../lexicon-module";
+import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
+import { loadRecordKind, parseFrontMatter, readRecords, RecordReadError, type LoadedRecordKind } from "./records";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const SAMPLE = readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8");
+
+/** A copy of a real decision with its id, state and supersedes links replaced. */
+function decision(id: string, state = "decided", supersedes: string[] = []): string {
+  const links = supersedes.length === 0 ? "supersedes: []" : `supersedes:\n${supersedes.map((d) => `  - decision: "${d}"`).join("\n")}`;
+  return SAMPLE.replace(/^id: .*$/m, `id: "${id}"`)
+    .replace(/^state: .*$/m, `state: "${state}"`)
+    .replace(/^supersedes:(?: \[\])?\n(?:  .*\n)*/m, `${links}\n`);
+}
+
+let dir: string;
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-")));
+  mkdirSync(join(dir, "decisions"));
+  cpSync(join(DECISIONS, "decision.kind.mjs"), join(dir, "decisions", "decision.kind.mjs"));
+  cpSync(join(DECISIONS, "decision.schema.json"), join(dir, "decisions", "decision.schema.json"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function write(name: string, text: string): void {
+  writeFileSync(join(dir, "decisions", name), text);
+}
+
+async function read(options: { current?: boolean } = {}) {
+  const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+  return readRecords(loaded, { root: dir, source: workingTreeSource(dir), ...options });
+}
+
+const codes = (r: { reasons: Array<{ code: string }> }) => r.reasons.map((x) => x.code);
+
+describe("parseFrontMatter", () => {
+  test("reads the JSON subset of YAML, whatever the line endings", () => {
+    const fm = parseFrontMatter('---\r\nid: "a-001"\r\nn: 2\r\nok: true\r\nlist: []\r\n---\r\n# A\r\n');
+    expect(fm).toEqual({ ok: true, value: { id: "a-001", n: 2, ok: true, list: [] } });
+  });
+
+  test("an unquoted date stays a string", () => {
+    expect(parseFrontMatter("---\non: 2026-09-23\n---\n")).toEqual({ ok: true, value: { on: "2026-09-23" } });
+  });
+
+  test.each([
+    ["no front matter", "# Just a heading\n", /no front matter/],
+    ["an unclosed block", "---\nid: x\n", /no front matter/],
+    ["invalid YAML", "---\nid: [unclosed\n---\n", /not valid YAML/],
+    ["a duplicate key", "---\nid: a\nid: b\n---\n", /not valid YAML/],
+    ["a list at the top", "---\n- a\n---\n", /must be a mapping/],
+    ["an alias", "---\na: &x {k: 1}\nb: *x\n---\n", /aliases/],
+  ])("refuses %s", (_label, text, why) => {
+    const fm = parseFrontMatter(text);
+    expect(fm.ok).toBe(false);
+    if (!fm.ok) expect(fm.message).toMatch(why);
+  });
+});
+
+describe("readRecords", () => {
+  test("every well-formed decision is valid, in path order", async () => {
+    write("ws-002-b.md", decision("ws-002"));
+    write("ws-001-a.md", decision("ws-001"));
+    write("README.md", "# not a record\n");
+    const result = await read();
+    expect(result.records.map((r) => [r.id, r.path, r.valid, r.state])).toEqual([
+      ["ws-001", "decisions/ws-001-a.md", true, "decided"],
+      ["ws-002", "decisions/ws-002-b.md", true, "decided"],
+    ]);
+    expect(result.summary).toEqual({ total: 2, valid: 2, invalid: 0, superseded: 0 });
+    expect(result.records[0].data?.title).toBe("Seal scope");
+  });
+
+  test("a malformed file is returned with record-unparseable", async () => {
+    write("ws-001-a.md", "no front matter here\n");
+    const [r] = (await read()).records;
+    expect(r).toMatchObject({ id: null, state: null, valid: false, data: null });
+    expect(codes(r)).toEqual(["record-unparseable"]);
+  });
+
+  test("a schema violation is returned with record-schema-invalid, and keeps its data", async () => {
+    write("ws-001-a.md", decision("ws-001").replace(/^state: .*$/m, 'state: "maybe"'));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-schema-invalid"]);
+    expect(r.reasons[0].message).toMatch(/\/state/);
+    expect(r.id).toBe("ws-001");
+    expect(r.data).not.toBeNull();
+  });
+
+  test("a supersedes link to a missing id is record-supersedes-unknown", async () => {
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-404"]));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-supersedes-unknown"]);
+  });
+
+  test("a repeated id is flagged on the later file only", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    write("ws-001-b.md", decision("ws-001"));
+    const records = (await read()).records;
+    expect(records.map(codes)).toEqual([[], ["record-id-duplicate"]]);
+  });
+
+  test("supersession comes from a closed record's link, never from the old record's own state", async () => {
+    write("ws-001-a.md", decision("ws-001", "superseded"));
+    write("ws-002-b.md", decision("ws-002", "ratified"));
+    write("ws-003-c.md", decision("ws-003", "ratified"));
+    write("ws-004-d.md", decision("ws-004", "ratified", ["ws-003"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy])).toEqual([
+      ["ws-001", null],
+      ["ws-002", null],
+      ["ws-003", "ws-004"],
+      ["ws-004", null],
+    ]);
+    expect(all.summary.superseded).toBe(1);
+    const current = await read({ current: true });
+    expect(current.records.map((r) => r.id)).toEqual(["ws-001", "ws-002", "ws-004"]);
+  });
+
+  test("a link from a decided record does not supersede yet", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const current = await read({ current: true });
+    expect(current.records.map((r) => [r.id, r.valid])).toEqual([
+      ["ws-001", true],
+      ["ws-002", true],
+    ]);
+  });
+
+  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"]));
+    write("ws-003-c.md", decision("ws-003", "ratified", ["ws-001"]));
+    const records = (await read()).records;
+    expect(records[0].supersededBy).toBe("ws-002");
+    expect(codes(records[2])).toEqual(["record-supersedes-conflict"]);
+  });
+
+  test("a missing records directory is location-missing", async () => {
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const moved: LoadedRecordKind = { ...loaded, dir: join(dir, "nowhere") };
+    await expect(readRecords(moved, { root: dir, source: workingTreeSource(dir) })).rejects.toMatchObject({ code: "location-missing" });
+  });
+});
+
+describe("loadRecordKind", () => {
+  const load = () => loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+
+  test("the chant repo's decision kind loads with its schema", async () => {
+    const loaded = await loadRecordKind(join(DECISIONS, "decision.kind.mjs"));
+    expect(loaded.kind.name).toBe("decision");
+    expect(loaded.schema.$id).toBe("urn:intentius:chant:decision:1");
+    expect(loaded.dir).toBe(DECISIONS);
+  });
+
+  test("loads through the #2520 path loader and leaves nothing registered", async () => {
+    const file = join(DECISIONS, "decision.kind.mjs");
+    await loadRecordKind(file);
+    expect(lexiconModulePath(`record-kind:${file}`)).toBeUndefined();
+  });
+
+  test("a missing file is kind-unreadable", async () => {
+    await expect(loadRecordKind(join(dir, "none.kind.ts"))).rejects.toMatchObject({ code: "kind-unreadable" });
+  });
+
+  test("a module with no recordKind is kind-invalid", async () => {
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), "export const other = 1;\n");
+    await expect(load()).rejects.toMatchObject({ code: "kind-invalid" });
+  });
+
+  test("an unknown field or a closed state outside states is kind-invalid", async () => {
+    const text = readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8");
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), text.replace('closedStates: ["ratified", "superseded"]', 'closedStates: ["sealed"]'));
+    await expect(load()).rejects.toMatchObject({ code: "kind-invalid" });
+  });
+
+  test("a schema whose $id differs is schema-id-mismatch", async () => {
+    const schema = JSON.parse(readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"));
+    writeFileSync(join(dir, "decisions", "decision.schema.json"), JSON.stringify({ ...schema, $id: "urn:other" }));
+    await expect(load()).rejects.toMatchObject({ code: "schema-id-mismatch" });
+  });
+
+  test("an unreadable schema is schema-unreadable", async () => {
+    writeFileSync(join(dir, "decisions", "decision.schema.json"), "{ not json");
+    await expect(load()).rejects.toBeInstanceOf(RecordReadError);
+    await expect(load()).rejects.toMatchObject({ code: "schema-unreadable" });
+  });
+});
+
+describe("reading at a revision", () => {
+  const git = (...args: string[]) =>
+    execFileSync("git", args, {
+      cwd: dir,
+      encoding: "utf-8",
+      env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" },
+    }).trim();
+
+  test("reads the committed files, not the working tree", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    git("init", "-q", "-b", "main");
+    git("add", "-A");
+    git("commit", "-q", "-m", "one");
+    const first = git("rev-parse", "HEAD");
+    write("ws-002-b.md", decision("ws-002"));
+    write("ws-001-a.md", "broken now\n");
+
+    expect(gitRoot(join(dir, "decisions"))).toBe(dir);
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const at = await readRecords(loaded, { root: dir, source: gitRevisionSource(dir, resolveRevision(dir, "main")) });
+    expect(at.records.map((r) => [r.id, r.valid])).toEqual([["ws-001", true]]);
+    expect(resolveRevision(dir, first.slice(0, 8))).toBe(first);
+
+    const tree = await readRecords(loaded, { root: dir, source: workingTreeSource(dir) });
+    expect(tree.records.map((r) => [r.path, r.valid])).toEqual([
+      ["decisions/ws-001-a.md", false],
+      ["decisions/ws-002-b.md", true],
+    ]);
+  });
+
+  test("an unknown revision is revision-unknown, and a directory missing at the revision is location-missing", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    writeFileSync(join(dir, "other.txt"), "x\n");
+    git("init", "-q", "-b", "main");
+    git("add", "other.txt");
+    git("commit", "-q", "-m", "no records yet");
+    expect(() => resolveRevision(dir, "no-such-ref")).toThrow(expect.objectContaining({ code: "revision-unknown" }));
+    expect(() => resolveRevision(dir, "--all")).toThrow(expect.objectContaining({ code: "revision-unknown" }));
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    await expect(
+      readRecords(loaded, { root: dir, source: gitRevisionSource(dir, resolveRevision(dir, "HEAD")) }),
+    ).rejects.toMatchObject({ code: "location-missing" });
+  });
+
+  test("outside a repository there is no git root", () => {
+    expect(gitRoot(dir)).toBeUndefined();
+  });
+});

package/src/workspace/records.ts

@@ -0,0 +1,384 @@
+/**
+ * Records read through a record kind (#2524 D4), first-test slice (#2546).
+ *
+ * A record kind is data. It says where its records live, which JSON Schema
+ * they follow and which of their states are closed. This module reads every
+ * record a kind locates, parses its front matter as the JSON subset of YAML,
+ * validates it against the kind's schema and derives supersession from the
+ * records' own `supersedes` links. It never writes a record.
+ *
+ * A record that fails any of that is still returned, with reason codes, and the
+ * read succeeds. Only a failure to read the kind, its schema or the revision is
+ * an error. Seals, attestation and the workspace declaration come later (#2546,
+ * #2534); nothing here needs a `chant.workspace.json`.
+ *
+ * Everything under `workspace/` loads only when a `chant workspace` command
+ * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { dirname, posix, relative, resolve, sep } from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+import { importLexiconModule, registerLexiconDeclarations } from "../lexicon-module";
+import type { ReasonCode } from "./reason-codes";
+import type { RecordSource } from "./record-source";
+
+// ── Reason codes ─────────────────────────────────────────────────────────────
+
+/**
+ * Why one record is not valid. The list is closed: a reader may switch on it,
+ * and a new code is a contract change (#2536).
+ */
+export const RECORD_REASON_CODES = [
+  /** No front matter, a YAML error, or a value outside the JSON subset of YAML. */
+  "record-unparseable",
+  /** The front matter does not match the kind's schema. */
+  "record-schema-invalid",
+  /** Another record earlier in path order has the same id. */
+  "record-id-duplicate",
+  /** A `supersedes` link names an id no record has. */
+  "record-supersedes-unknown",
+  /** A second closed record supersedes a record another one already superseded. */
+  "record-supersedes-conflict",
+] as const satisfies readonly ReasonCode[];
+export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
+
+/**
+ * Why the read as a whole failed. Also closed. The command exits 1 with one of
+ * these and returns no records.
+ */
+export const READ_ERROR_CODES = [
+  /** The kind file is missing or could not be imported. */
+  "kind-unreadable",
+  /** The kind file exports no `recordKind`, or its shape is wrong. */
+  "kind-invalid",
+  /** The schema file the kind names is missing or is not JSON. */
+  "schema-unreadable",
+  /** The schema's `$id` differs from the id the kind names. */
+  "schema-id-mismatch",
+  /** The schema itself does not compile. */
+  "schema-invalid",
+  /** The records directory does not exist, in the tree or at the revision. */
+  "location-missing",
+  /** `--at` was given outside a git repository. */
+  "not-a-git-repository",
+  /** `--at` names no commit. */
+  "revision-unknown",
+] as const satisfies readonly ReasonCode[];
+export type ReadErrorCode = (typeof READ_ERROR_CODES)[number];
+
+export class RecordReadError extends Error {
+  constructor(
+    readonly code: ReadErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "RecordReadError";
+  }
+}
+
+// ── The kind ─────────────────────────────────────────────────────────────────
+
+const idPattern = /^[a-z][a-z0-9-]*$/;
+
+/** The data a kind file exports as `recordKind`. */
+export const recordKindSchema = z
+  .object({
+    /** The kind's name, such as `decision`. */
+    name: z.string().regex(idPattern),
+    /** Where the records are, relative to the kind file's directory. */
+    location: z
+      .object({
+        dir: z.string().min(1),
+        /** A regular expression the file name must match. Only that directory is read; subdirectories are not. */
+        match: z.string().min(1),
+      })
+      .strict(),
+    /** Only Markdown with YAML front matter for now. */
+    format: z.literal("markdown-front-matter"),
+    schema: z
+      .object({
+        /** The schema's `$id`. A schema file with a different `$id` is refused. */
+        id: z.string().min(1),
+        /** The schema file, relative to the kind file's directory. */
+        path: z.string().min(1),
+      })
+      .strict(),
+    /** The front-matter field holding the record's id. */
+    idField: z.string().min(1),
+    /** The front-matter field holding the record's state. */
+    stateField: z.string().min(1),
+    states: z.array(z.string().min(1)).min(1),
+    /** States whose records are final. A `supersedes` link takes effect only from a record in one of them. */
+    closedStates: z.array(z.string().min(1)),
+    /** The front-matter list of links to superseded records, and the key in each entry that holds the target id. */
+    supersedes: z.object({ field: z.string().min(1), key: z.string().min(1) }).strict(),
+  })
+  .strict()
+  .refine((k) => k.closedStates.every((s) => k.states.includes(s)), {
+    message: "every closed state must be listed in states",
+    path: ["closedStates"],
+  });
+
+export type RecordKind = z.infer<typeof recordKindSchema>;
+
+/** A kind as loaded: its data, where it came from, and its schema. */
+export interface LoadedRecordKind {
+  kind: RecordKind;
+  /** Absolute path of the kind file. */
+  file: string;
+  /** Absolute path of the records directory in the working tree. */
+  dir: string;
+  schema: Record<string, unknown>;
+}
+
+/**
+ * Import the kind file at `path` through the path loader lexicons use (#2520).
+ * The kind is registered under a name no lexicon package can have (npm names
+ * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
+ */
+async function importKindModule(path: string): Promise<Record<string, unknown>> {
+  const name = `record-kind:${path}`;
+  registerLexiconDeclarations([{ name, module: path }], dirname(path));
+  try {
+    const mod = await importLexiconModule(name);
+    if (!mod) throw new Error(`${path} was not registered`);
+    return mod;
+  } finally {
+    registerLexiconDeclarations([name], dirname(path));
+  }
+}
+
+/** Load a kind file and the schema it names. `path` is resolved against `cwd`. */
+export async function loadRecordKind(path: string, cwd: string = process.cwd()): Promise<LoadedRecordKind> {
+  const file = resolve(cwd, path);
+  let mod: Record<string, unknown>;
+  try {
+    statSync(file);
+    mod = await importKindModule(file);
+  } catch (err) {
+    throw new RecordReadError("kind-unreadable", `kind file ${path} could not be loaded: ${message(err)}`);
+  }
+  const parsed = recordKindSchema.safeParse(mod.recordKind);
+  if (!parsed.success) {
+    const detail =
+      mod.recordKind === undefined
+        ? "it has no recordKind export"
+        : parsed.error.issues.map((i) => `${i.path.join(".") || "recordKind"}: ${i.message}`).join("; ");
+    throw new RecordReadError("kind-invalid", `kind file ${path} is not a record kind: ${detail}`);
+  }
+  const kind = parsed.data;
+  const base = dirname(file);
+  const schemaFile = resolve(base, kind.schema.path);
+  let schema: Record<string, unknown>;
+  try {
+    schema = JSON.parse(readFileSync(schemaFile, "utf-8")) as Record<string, unknown>;
+  } catch (err) {
+    throw new RecordReadError("schema-unreadable", `schema ${kind.schema.path} named by ${path} could not be read: ${message(err)}`);
+  }
+  if (schema.$id !== kind.schema.id) {
+    throw new RecordReadError(
+      "schema-id-mismatch",
+      `kind ${kind.name} names schema ${kind.schema.id}, but ${kind.schema.path} has $id ${JSON.stringify(schema.$id)}`,
+    );
+  }
+  return { kind, file, dir: resolve(base, kind.location.dir), schema };
+}
+
+// ── Front matter ─────────────────────────────────────────────────────────────
+
+export type FrontMatter = { ok: true; value: Record<string, unknown> } | { ok: false; message: string };
+
+/**
+ * The front matter of a Markdown file, limited to what YAML and JSON share
+ * (#2524 D4). Line endings are normalised first. Aliases, and any value JSON
+ * cannot hold, are refused, so the same text always reads as the same JSON.
+ */
+export function parseFrontMatter(text: string): FrontMatter {
+  const normalised = text.replace(/\r\n?/g, "\n");
+  const m = normalised.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!m) return { ok: false, message: "no front matter: the file must start with a --- line and close it with another" };
+  let value: unknown;
+  try {
+    value = yaml.load(m[1], { schema: yaml.JSON_SCHEMA });
+  } catch (err) {
+    return { ok: false, message: `front matter is not valid YAML: ${message(err).split("\n")[0]}` };
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, message: "front matter must be a mapping" };
+  }
+  const problem = nonJson(value, "", new Set());
+  if (problem) return { ok: false, message: problem };
+  return { ok: true, value: value as Record<string, unknown> };
+}
+
+/** The first thing in `v` that JSON cannot say, or that only an alias can produce. */
+function nonJson(v: unknown, at: string, seen: Set<object>): string | undefined {
+  if (v === null || typeof v === "string" || typeof v === "boolean") return undefined;
+  if (typeof v === "number") return Number.isFinite(v) ? undefined : `${at || "/"}: ${v} is not a JSON number`;
+  if (typeof v !== "object") return `${at || "/"}: a ${typeof v} is not a JSON value`;
+  if (seen.has(v)) return `${at || "/"}: YAML aliases are not allowed`;
+  seen.add(v);
+  if (Array.isArray(v)) {
+    for (let i = 0; i < v.length; i++) {
+      const p = nonJson(v[i], `${at}/${i}`, seen);
+      if (p) return p;
+    }
+    return undefined;
+  }
+  if (Object.getPrototypeOf(v) !== Object.prototype) return `${at || "/"}: not a plain mapping`;
+  for (const [k, x] of Object.entries(v)) {
+    const p = nonJson(x, `${at}/${k}`, seen);
+    if (p) return p;
+  }
+  return undefined;
+}
+
+// ── Reading ──────────────────────────────────────────────────────────────────
+
+export interface RecordReason {
+  code: RecordReasonCode;
+  message: string;
+}
+
+export interface RecordEntry {
+  /** The record's id, or null when it could not be read. */
+  id: string | null;
+  /** Path from the repository root (or the working directory outside git), with `/` separators. */
+  path: string;
+  /** The record's state as written, or null when it could not be read. */
+  state: string | null;
+  valid: boolean;
+  reasons: RecordReason[];
+  /** The id of the closed record whose `supersedes` link replaces this one, or null. */
+  supersededBy: string | null;
+  /** The front matter as JSON, or null when it could not be parsed. */
+  data: Record<string, unknown> | null;
+}
+
+export interface ReadRecordsOptions {
+  /** Where record paths are reported from, and what `source` reads relative to. */
+  root: string;
+  source: RecordSource;
+  /** Leave out records a closed record supersedes. */
+  current?: boolean;
+}
+
+export interface ReadRecordsResult {
+  records: RecordEntry[];
+  summary: { total: number; valid: number; invalid: number; superseded: number };
+}
+
+type Validator = (data: unknown) => { ok: true } | { ok: false; errors: string[] };
+
+async function compileSchema(schema: Record<string, unknown>): Promise<Validator> {
+  const mod = (await import("ajv")) as unknown as { default: unknown };
+  // ajv is CommonJS; its class is the default export, or that export's own default.
+  const Ajv = ((mod.default as { default?: unknown }).default ?? mod.default) as new (opts: object) => {
+    compile(s: object): ((d: unknown) => boolean) & { errors?: Array<{ instancePath: string; message?: string }> | null };
+  };
+  let validate: ReturnType<InstanceType<typeof Ajv>["compile"]>;
+  try {
+    validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+  } catch (err) {
+    throw new RecordReadError("schema-invalid", `the kind's schema does not compile: ${message(err)}`);
+  }
+  return (data) =>
+    validate(data)
+      ? { ok: true }
+      : { ok: false, errors: (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`) };
+}
+
+/** Read every record `loaded` locates, through `options.source`. */
+export async function readRecords(loaded: LoadedRecordKind, options: ReadRecordsOptions): Promise<ReadRecordsResult> {
+  const { kind } = loaded;
+  const dirRel = toPosix(relative(options.root, loaded.dir)) || ".";
+  const names = options.source.list(dirRel);
+  if (names === undefined) {
+    throw new RecordReadError("location-missing", `records directory ${dirRel} does not exist${options.source.label}`);
+  }
+  const match = new RegExp(kind.location.match);
+  const validate = await compileSchema(loaded.schema);
+
+  const entries: RecordEntry[] = [];
+  for (const name of names.filter((n) => match.test(n)).sort()) {
+    const path = dirRel === "." ? name : `${dirRel}/${name}`;
+    const entry: RecordEntry = { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null };
+    entries.push(entry);
+    const fm = parseFrontMatter(options.source.read(path));
+    if (!fm.ok) {
+      entry.reasons.push({ code: "record-unparseable", message: fm.message });
+      continue;
+    }
+    entry.data = fm.value;
+    const id = fm.value[kind.idField];
+    const state = fm.value[kind.stateField];
+    if (typeof id === "string") entry.id = id;
+    if (typeof state === "string") entry.state = state;
+    const result = validate(fm.value);
+    if (!result.ok) {
+      entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
+    }
+  }
+
+  // Ids: the first file in path order keeps an id; later ones are flagged.
+  const byId = new Map<string, RecordEntry>();
+  for (const e of entries) {
+    if (e.id === null) continue;
+    const first = byId.get(e.id);
+    if (first) e.reasons.push({ code: "record-id-duplicate", message: `id ${e.id} is already used by ${first.path}` });
+    else byId.set(e.id, e);
+  }
+
+  // Supersession comes from the new record's links, never from the old record.
+  // A link takes effect only from a closed record (#2555: a later ratified
+  // decision replaces an earlier one), and a record is superseded at most once
+  // (#2524 D4).
+  const closed = new Set(kind.closedStates);
+  for (const e of entries) {
+    const links = e.data?.[kind.supersedes.field];
+    if (!Array.isArray(links)) continue;
+    for (const link of links) {
+      if (link === null || typeof link !== "object") continue;
+      const target = (link as Record<string, unknown>)[kind.supersedes.key];
+      if (typeof target !== "string") continue;
+      const old = byId.get(target);
+      if (!old) {
+        e.reasons.push({ code: "record-supersedes-unknown", message: `supersedes ${target}, which no record has` });
+        continue;
+      }
+      if (e.state === null || !closed.has(e.state) || old === e) continue;
+      if (old.supersededBy !== null && old.supersededBy !== e.id) {
+        e.reasons.push({
+          code: "record-supersedes-conflict",
+          message: `supersedes ${target}, which ${old.supersededBy} already supersedes`,
+        });
+        continue;
+      }
+      old.supersededBy = e.id;
+    }
+  }
+
+  for (const e of entries) e.valid = e.reasons.length === 0;
+  const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;
+  return {
+    records,
+    summary: {
+      total: records.length,
+      valid: records.filter((e) => e.valid).length,
+      invalid: records.filter((e) => !e.valid).length,
+      superseded: entries.filter((e) => e.supersededBy !== null).length,
+    },
+  };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join(posix.sep);
+}