@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/records-concurrent.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Concurrent writers in one working tree (#3173, ws-089): two people and an
+ * agent amend one record at once, each from the digest they read. Exactly one
+ * write wins per digest; the others are refused with record-conflict, naming
+ * the digest the record has now and who wrote it, and win when they retry
+ * from it. Nothing anyone wrote is lost. The same through the command line,
+ * in separate processes, is in records-concurrent.e2e.test.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { parseFrontMatter } from "./records";
+import { queryRecords } from "./records-cli";
+import { amendRecord, newRecord, renderRecord, reviewRecord, type AmendDocument } from "./records-write";
+import amendSchema from "./records-amend.schema.json";
+import recordsSchema from "./records.schema.json";
+
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const KIND = "decisions/decision.kind.mjs";
+type Data = Record<string, unknown>;
+
+const SAMPLE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+const proposal = (over: Data): Data => ({ ...structuredClone(SAMPLE), state: "proposed", choice: null, decided_by: null, decided_on: null, ...over });
+const record = (d: Data) => renderRecord(d, `\n# ${String(d.title)}\n`);
+
+const amendDoc = contract(amendSchema);
+const recordsDoc = contract(recordsSchema);
+
+let root: string;
+beforeAll(() => {
+  root = repo(
+    {
+      "chant.workspace.json": JSON.stringify({
+        name: "box",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+        records: [{ kind: KIND }],
+        writeScope: { agent: { records: { decision: ["new", "amend", "review"] } } },
+        agents: [{ name: "app-agent", member: "app" }],
+      }),
+      [KIND]: readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8"),
+      "decisions/decision.schema.json": readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"),
+      "decisions/ws-001-one.md": record(proposal({ id: "ws-001", title: "One" })),
+      "app/server.mjs": "export const port = 8080;\n",
+    },
+    true,
+  );
+  git(root, "branch", "-M", "main");
+});
+afterAll(cleanScratch);
+
+async function read(id: string): Promise<{ digest: string; lastWrite: unknown; data: Data }> {
+  const doc = await queryRecords({ kind: KIND, cwd: root });
+  recordsDoc.expectValid(doc);
+  const r = (doc as { records: { id: string; digest: string; lastWrite: unknown; data: Data }[] }).records.find((x) => x.id === id)!;
+  return { digest: r.digest, lastWrite: r.lastWrite, data: r.data };
+}
+
+const failed = (d: AmendDocument) => ("error" in d ? d : null);
+
+describe("two people and an agent amend one record at once (#3173)", () => {
+  test("exactly one wins per digest, and the others get a conflict they can retry", async () => {
+    const start = await read("ws-001");
+    expect(start.lastWrite).toBeNull();
+
+    const writes = {
+      alice: { fields: { title: "One, as alice has it" } },
+      bob: { fields: { question: "What does bob ask?" } },
+      agent: { fields: { constrains: ["member:app"] }, agent: "app-agent" },
+    } as const;
+    const amend = (who: keyof typeof writes, expect: string) =>
+      amendRecord({ kind: KIND, id: "ws-001", fields: JSON.stringify(writes[who].fields), cwd: root, expect, agent: who === "agent" ? "app-agent" : undefined });
+
+    // All three from the digest they read, at once.
+    const first = await Promise.all((["alice", "bob", "agent"] as const).map(async (who) => [who, await amend(who, start.digest)] as const));
+    for (const [, doc] of first) amendDoc.expectValid(doc);
+    const won = first.filter(([, d]) => !failed(d));
+    const lost = first.filter(([, d]) => failed(d));
+    expect(won).toHaveLength(1);
+    expect(lost).toHaveLength(2);
+    const [winner, winDoc] = won[0];
+    const d1 = (winDoc as { digest: string }).digest;
+    expect(d1).not.toBe(start.digest);
+    for (const [, doc] of lost) {
+      const f = failed(doc)!;
+      expect(f.error.code).toBe("record-conflict");
+      expect(f.error.message).toContain(d1);
+      expect(f.conflict).toMatchObject({ id: "ws-001", path: "decisions/ws-001-one.md", expected: start.digest, digest: d1 });
+      expect(f.conflict!.lastWrite).toMatchObject({ verb: "records amend", agent: winner === "agent" ? "app-agent" : null });
+    }
+
+    // The read contract shows the same digest and who wrote it.
+    const after = await read("ws-001");
+    expect(after.digest).toBe(d1);
+    expect(after.lastWrite).toMatchObject({ verb: "records amend" });
+
+    // Each loser retries from the digest its conflict named; the first retry wins, the second conflicts again, then wins.
+    const [[l1], [l2]] = lost;
+    const r1 = await amend(l1, d1);
+    expect(failed(r1)).toBeNull();
+    const d2 = (r1 as { digest: string }).digest;
+    const r2 = await amend(l2, d1);
+    expect(failed(r2)?.conflict?.digest).toBe(d2);
+    const r3 = await amend(l2, d2);
+    expect(failed(r3)).toBeNull();
+
+    // Nothing anyone wrote was lost.
+    const end = await read("ws-001");
+    expect(end.data).toMatchObject({ title: "One, as alice has it", question: "What does bob ask?", constrains: ["member:app"] });
+    expect(end.digest).toBe((r3 as { digest: string }).digest);
+  });
+
+  test("a verdict on a text the reviewer did not see is refused, and one on the current text is taken", async () => {
+    const now = await read("ws-001");
+    const stale = await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by: "carol", cwd: root, expect: "0".repeat(64) });
+    expect(stale).toMatchObject({ error: { code: "record-conflict" }, conflict: { digest: now.digest } });
+    const fresh = await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by: "carol", cwd: root, expect: now.digest });
+    expect(fresh).toMatchObject({ digest: now.digest, review: { reviewer: "carol", digest: now.digest } });
+    expect((await read("ws-001")).lastWrite).toMatchObject({ verb: "records review", by: "carol" });
+  });
+
+  test("writes without --expect are serialised, so none is lost and no id is handed out twice", async () => {
+    const titles = ["Two", "Three", "Four"];
+    const made = await Promise.all(titles.map((title) => newRecord({ kind: KIND, fields: JSON.stringify(proposal({ id: undefined, title })), cwd: root })));
+    const ids = made.map((d) => ("error" in d ? d.error.code : d.id));
+    expect(new Set(ids).size).toBe(3);
+    for (const id of ids) expect(id).toMatch(/^ws-00[2-4]$/);
+    const amended = await Promise.all([
+      amendRecord({ kind: KIND, id: "ws-002", fields: JSON.stringify({ title: "Two, retitled" }), cwd: root }),
+      amendRecord({ kind: KIND, id: "ws-002", fields: JSON.stringify({ question: "Asked again?" }), cwd: root }),
+    ]);
+    expect(amended.every((d) => !("error" in d))).toBe(true);
+    expect((await read("ws-002")).data).toMatchObject({ title: "Two, retitled", question: "Asked again?" });
+  });
+
+  test("--expect that is not a digest is a usage error, and nothing is read", async () => {
+    expect(await amendRecord({ kind: KIND, id: "ws-001", fields: "{}", cwd: root, expect: "abc" })).toMatchObject({ error: { code: "write-usage-invalid" } });
+  });
+});

package/src/workspace/records-formats.test.ts

@@ -12,7 +12,7 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -22,9 +22,11 @@ import { queryRecords, type RecordsDocument } from "./records-cli";
 import { newRecord, runRecordsWrite } from "./records-write";
 import { loadRecordKind, parseJsonRecord, RECORD_FORMATS, recordTextDigest } from "./records";
 import schema from "./records.schema.json";
+import newSchema from "./records-new.schema.json";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 const validateOutput = new Ajv2020({ strict: true, allErrors: true }).compile(schema);
+const validateNew = new Ajv2020({ strict: true, allErrors: true }).compile(newSchema);
 
 let root: string;
 beforeEach(() => {
@@ -398,19 +400,51 @@ describe("a JSON session kind (#2673)", () => {
 });
 
 describe("the write commands", () => {
-  test("refuse a JSON kind and a content-addressed one, which they cannot write", async () => {
-    for (const kind of ["unit", "evidence"]) {
-      const doc = await newRecord({ kind: `design/${kind}.kind.mjs`, fields: "{}", cwd: root, dryRun: true });
-      expect("error" in doc && doc.error.code).toBe("write-usage-invalid");
-      expect("error" in doc && doc.error.message).toMatch(/write only Markdown front matter records with an idField/);
-    }
+  test("refuse a JSON kind with an id field, which they cannot write", async () => {
+    const doc = await newRecord({ kind: "design/unit.kind.mjs", fields: "{}", cwd: root, dryRun: true });
+    expect("error" in doc && doc.error.code).toBe("write-usage-invalid");
+    expect("error" in doc && doc.error.message).toMatch(/write only Markdown front matter records with an idField/);
+  });
+
+  test("records new writes a content-addressed record as JSON named for its bytes, and reads it back valid (ws-082)", async () => {
+    // The fields in another order: the file holds them in the schema's.
+    const fields = JSON.stringify(Object.fromEntries(Object.entries(EVIDENCE).reverse()));
+    const dry = await newRecord({ kind: "design/evidence.kind.mjs", fields, cwd: root, dryRun: true });
+    if ("error" in dry) throw new Error(dry.error.message);
+    const h = sha256(json(EVIDENCE));
+    expect(dry).toMatchObject({ id: h, path: `design/evidence/${h}.json`, dryRun: true, text: json(EVIDENCE), warnings: [] });
+    expect(validateNew(dry), JSON.stringify(validateNew.errors)).toBe(true);
+    expect(readdirSync(join(root, "design", "evidence"))).toEqual([]);
+
+    const doc = await newRecord({ kind: "design/evidence.kind.mjs", fields, cwd: root });
+    expect(doc).toMatchObject({ id: h, path: `design/evidence/${h}.json`, dryRun: false });
+    expect(readFileSync(join(root, "design", "evidence", `${h}.json`), "utf-8")).toBe(json(EVIDENCE));
+    const [read] = (await query("evidence")).records;
+    expect([read.id, read.valid, warned(read)]).toEqual([h, true, []]);
+
+    // The same bytes again are the same record, already written.
+    const again = await newRecord({ kind: "design/evidence.kind.mjs", fields, cwd: root });
+    expect("error" in again && again.error.code).toBe("record-id-taken");
+  });
+
+  test("records new refuses content-addressed fields the schema refuses, an id prefix and a seal", async () => {
+    const bad = await newRecord({ kind: "design/evidence.kind.mjs", fields: JSON.stringify({ ...EVIDENCE, tree: "not-a-tree" }), cwd: root });
+    expect("error" in bad && bad.error.code).toBe("record-schema-invalid");
+    const prefixed = await newRecord({ kind: "design/evidence.kind.mjs", fields: JSON.stringify(EVIDENCE), prefix: "ev", cwd: root });
+    expect("error" in prefixed && prefixed.error.message).toMatch(/--prefix allocates nothing/);
+    const signed = await newRecord({ kind: "design/evidence.kind.mjs", fields: JSON.stringify(EVIDENCE), sign: true, cwd: root });
+    expect("error" in signed && signed.error.message).toMatch(/names no author to seal/);
+    expect(readdirSync(join(root, "design", "evidence"))).toEqual([]);
   });
 });
 
 describe("the write commands through a declared kind (#2680)", () => {
   afterEach(() => vi.restoreAllMocks());
 
-  test.each(["unit", "evidence"])("refuse the declared %s kind with write-usage-invalid", async (kind) => {
+  test.each([
+    ["unit", ["new", "amend", "review"], /write only Markdown front matter records with an idField/],
+    ["evidence", ["amend", "review"], /a content-addressed record never changes once records new writes it/],
+  ] as const)("refuse the declared %s kind with write-usage-invalid", async (kind, verbs, why) => {
     write(
       "chant.workspace.json",
       json({ name: "acme", schema: 1, members: [{ name: "design", dir: "design", kind: "other", because: "acme's records" }], records: [{ kind: `design/${kind}.kind.mjs` }] }),
@@ -425,13 +459,13 @@ describe("the write commands through a declared kind (#2680)", () => {
       ["amend", "U-0001", "--set", join(root, "fields.json"), "--dry-run"],
       ["review", "U-0001", "--verdict", "agree", "--by", "bo", "--dry-run"],
     ];
-    for (const argv of runs) {
+    for (const argv of runs.filter((r) => (verbs as readonly string[]).includes(r[0]))) {
       out.length = 0;
       const status = await runRecordsWrite({ args: parseArgs(["workspace", "records", ...argv]), plugins: [] } as never);
       const doc = JSON.parse(out.join("\n")) as { error?: { code: string; message: string } };
       expect(status, argv[0]).toBe(1);
       expect(doc.error?.code, argv[0]).toBe("write-usage-invalid");
-      expect(doc.error?.message, argv[0]).toMatch(/write only Markdown front matter records with an idField/);
+      expect(doc.error?.message, argv[0]).toMatch(why);
     }
   });
 });
@@ -554,6 +588,8 @@ describe("kinds without a lifecycle", () => {
     ["an unknown format", { ...KINDS.closure, format: "yaml" }, /format/],
     ["a session block without states", { ...KINDS.closure, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs" } } }, /session: a session kind must have states/],
     ["a seal without states (#2546)", { ...KINDS.closure, seal: { field: "seal" } }, /seal: a kind without states cannot have seal/],
+    ["session subjects listing a kind twice (ws-082)", { ...KINDS.session, session: { verdicts: "approvals", seal: "seal", subjects: { kinds: ["contract.kind.mjs", "contract.kind.mjs"] } } }, /lists each kind file once/],
+    ["session subjects with both kind and kinds (ws-082)", { ...KINDS.session, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs", kinds: ["contract.kind.mjs"] } } }, /subjects/],
     ["a seal naming another field than session.seal (#2546)", { ...KINDS.session, session: { verdicts: "approvals", seal: "seal", subjects: { kind: "contract.kind.mjs" } }, seal: { field: "closed_digest" } }, /seal: seal.field and session.seal name the field/],
   ])("a kind with %s is kind-invalid, naming the field", async (_label, kind, why) => {
     write("design/closure.kind.mjs", kindFile(kind));

package/src/workspace/records-new.schema.json

@@ -96,6 +96,11 @@
             "$ref": "#/$defs/warning"
           }
         },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
         "text": {
           "type": "string",
           "description": "With --dry-run only: the whole text of the file the command would write."
@@ -165,6 +170,8 @@
                 "source-harvest-not-proposed",
                 "record-state-not-initial",
                 "ratify-quorum-not-met",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "write-scope-member",
                 "write-scope-kind",
                 "write-scope-class-unknown",

package/src/workspace/records-review.schema.json

@@ -140,6 +140,11 @@
             "$ref": "#/$defs/warning"
           }
         },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
         "text": {
           "type": "string",
           "description": "With --dry-run only: the whole text of the file the command would write."
@@ -259,6 +264,9 @@
                 "review-sign-failed",
                 "session-unknown",
                 "session-not-open",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "write-scope-member",
                 "write-scope-kind",
                 "write-scope-class-unknown",
@@ -282,6 +290,76 @@
             }
           }
         },
+        "conflict": {
+          "type": "object",
+          "description": "Added in contract 1 by #3173. With record-conflict only: the record as it is now. Re-read it, and write again with --expect set to digest if the change still stands.",
+          "required": [
+            "id",
+            "path",
+            "expected",
+            "digest",
+            "lastWrite"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "expected": {
+              "type": "string",
+              "description": "The digest given with --expect."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The record's digest now."
+            },
+            "lastWrite": {
+              "description": "The last chant write of the record file, from the write journal in the git directory, while the file still holds the text it left; null when the journal does not know it.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "verb",
+                    "by",
+                    "agent",
+                    "at"
+                  ],
+                  "properties": {
+                    "verb": {
+                      "type": "string",
+                      "description": "The write command, such as records amend or points answer."
+                    },
+                    "by": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The principal the write named, or null when it named none."
+                    },
+                    "agent": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The agent session it was made in (CHANT_AGENT), or null."
+                    },
+                    "at": {
+                      "type": "string",
+                      "description": "When, as an ISO 8601 time."
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
         "path": false
       }
     }

package/src/workspace/records-sessions-write.test.ts

@@ -241,3 +241,72 @@ describe("records --since <session id> (#2693)", () => {
     expect((await sinceDoc({ kind: DECISIONS_KIND, since: "v-1", cwd: root })).session).toBeUndefined();
   });
 });
+
+describe("a UI review batch as a session (#3350, ws-083)", () => {
+  const anchor = { route: "/notes?page=2#top", elements: [{ selector: "[data-hud-id=status]", tag: "p", text: "Running.", state: "anchored", basis: "authored" }] };
+
+  test("a batch is written through records new, answered and replied to through amend, and closed with each comment's exit", async () => {
+    const root = declared();
+    const sent = await newRecord({
+      kind: SESSIONS_KIND,
+      fields: newSessionFields({
+        title: "Review of /notes",
+        agenda: [{ text: "Comment-mode review of /notes" }],
+        attendance: [{ principal: "alice", class: "person", roles: ["reviewer"] }, { principal: "hud-chat", class: "agent" }],
+        comments: [
+          { text: "Say which build is running.", by: "alice", anchor },
+          { text: "", anchor: { route: "/notes?page=2#top", elements: [{ selector: "main > ul", state: "ambiguous" }] } },
+        ],
+        rounds: [{ round: 0, note: "The list's second page, mostly.", by: "alice", at: "2026-09-25T09:00:00Z", ended: null }],
+      }),
+      cwd: root,
+    });
+    created.expectValid(sent);
+    if ("error" in sent) throw new Error(`${sent.error.code}: ${sent.error.message}`);
+
+    const answered = (round: number, extra: Record<string, unknown>[]) => [
+      { text: "Say which build is running.", by: "alice", anchor, answers: [{ round: 0, disposition: "needs-discussion", note: "The commit, or the release tag?", by: "hud-chat", at: "2026-09-25T09:02:00Z" }, ...extra] },
+      { text: "", anchor: { route: "/notes?page=2#top", elements: [{ selector: "main > ul", state: "ambiguous" }] }, answers: [{ round, disposition: "handled", note: "Paged the list by 20.", at: "2026-09-25T09:03:00Z" }] },
+    ];
+    const first = await amendRecord({
+      kind: SESSIONS_KIND,
+      id: sent.id,
+      fields: JSON.stringify({ comments: answered(0, []), rounds: [{ round: 0, note: "The list's second page, mostly.", by: "alice", at: "2026-09-25T09:00:00Z", ended: "2026-09-25T09:04:00Z" }] }),
+      cwd: root,
+    });
+    expect(code(first)).toBe("ok");
+
+    const comments = answered(0, [{ round: 1, disposition: "handled", note: "Shows the release tag now.", by: "hud-chat", at: "2026-09-25T09:11:00Z" }]);
+    (comments[0] as Record<string, unknown>).replies = [{ round: 1, text: "The release tag.", by: "alice", at: "2026-09-25T09:10:00Z" }];
+    (comments[0] as Record<string, unknown>).exit = "kept";
+    (comments[0] as Record<string, unknown>).follow_ups = ["work:W-007"];
+    (comments[1] as Record<string, unknown>).exit = "sent";
+    const rounds = [
+      { round: 0, note: "The list's second page, mostly.", by: "alice", at: "2026-09-25T09:00:00Z", ended: "2026-09-25T09:04:00Z" },
+      { round: 1, note: null, by: "alice", at: "2026-09-25T09:10:00Z", ended: "2026-09-25T09:12:00Z" },
+    ];
+    expect(code(await amendRecord({ kind: SESSIONS_KIND, id: sent.id, fields: JSON.stringify({ comments, rounds, closed_by: "alice" }), cwd: root }))).toBe("ok");
+    const closed = await closeRecord({ kind: SESSIONS_KIND, id: sent.id, cwd: root, now: new Date("2026-09-25T09:15:00Z") });
+    close.expectValid(closed);
+    expect(code(closed)).toBe("ok");
+
+    const doc = await queryRecords({ kind: SESSIONS_KIND, cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const s2 = doc.records.find((r) => r.id === sent.id)!;
+    expect([s2.state, s2.valid, s2.reasons]).toEqual(["closed", true, []]);
+    expect((s2.data!.comments as { exit?: string }[]).map((c) => c.exit)).toEqual(["kept", "sent"]);
+  });
+
+  test.each([
+    ["an answer with another disposition", { text: "x", answers: [{ round: 0, disposition: "kept", note: "n" }] }],
+    ["an answer with no note", { text: "x", answers: [{ round: 0, disposition: "skipped", note: " " }] }],
+    ["a reply in round 0", { text: "x", replies: [{ round: 0, text: "r" }] }],
+    ["an anchor with no element", { text: "x", anchor: { route: "/", elements: [] } }],
+    ["an element in an unknown state", { text: "x", anchor: { route: "/", elements: [{ selector: "p", state: "moved" }] } }],
+    ["an exit that is not kept, sent or dismissed", { text: "x", exit: "handled" }],
+  ])("records new refuses %s", async (_label, comment) => {
+    const root = declared();
+    const doc = await newRecord({ kind: SESSIONS_KIND, fields: newSessionFields({ comments: [comment] }), cwd: root, dryRun: true });
+    expect(code(doc)).toBe("record-schema-invalid");
+  });
+});

package/src/workspace/records-sessions.test.ts

@@ -114,6 +114,28 @@ describe("the session kind (#2673)", () => {
     expect(then.records.find((r) => r.id === "S-0002")).toMatchObject({ state: "open", valid: true, citedBy: [] });
   });
 
+  test("a verdict may name a contract or a driver, the session kind's other subjects, and a contract review cites the session (#3148, ws-082)", async () => {
+    const root = fixture();
+    const contractFile = join(root, "design", "contracts", "C-001-the-home-page-follows-its-screen-spec.md");
+    writeFileSync(contractFile, readFileSync(contractFile, "utf-8").replace("reviews: []", 'reviews:\n  - reviewer: "alice"\n    verdict: "agree"\n    on: "2026-09-24"\n    session: "S-0002"'));
+    writeFileSync(
+      join(root, "design", "sessions", "S-0002-walk.md"),
+      sessionText({
+        id: "S-0002",
+        state: "closed",
+        agenda: ["C-001", "D-001"],
+        verdicts: [
+          { record: "C-001", principal: "alice", verdict: "agree" },
+          { record: "D-001", principal: "alice", verdict: "agree" },
+          { record: "C-999", principal: "alice", verdict: "agree" },
+        ],
+      }),
+    );
+    const s2 = (await read(root)).records.find((r) => r.id === "S-0002")!;
+    expect(s2.reasons).toEqual([{ code: "session-verdict-unknown-record", message: expect.stringMatching(/verdicts\[2\] names C-999, which no .*decision\.kind\.mjs or .*contract\.kind\.mjs or .*driver\.kind\.mjs record has/) }]);
+    expect(s2.citedBy).toEqual([{ id: "C-001", path: "design/contracts/C-001-the-home-page-follows-its-screen-spec.md", index: 0, reviewer: "alice", verdict: "agree" }]);
+  });
+
   test("the decision kind accepts a review entry naming its session", async () => {
     const root = fixture();
     reviewed(root, ["alice"], "S-0001");