@intentius/chant 0.84.0 → 0.86.0

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

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json",
+  "title": "chant workspace records new output",
+  "description": "What `chant workspace records new <kind file> --from <file|->` prints (#2670): the path and id of the record it wrote, or would write with --dry-run, or the reason it wrote nothing. Version 1 of the write contract for records. The command writes one file or none and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.86.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"decision\"."
+            },
+            "schema": {
+              "type": "string",
+              "description": "The `$id` of the schema the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "record-id-taken",
+                "record-id-unallocatable",
+                "record-path-unmatched",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something, such as writing a new record that supersedes this one."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

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

@@ -0,0 +1,196 @@
+/**
+ * A record's digest and its quorum (#2671, #2672).
+ *
+ * `recordTextDigest` hashes a record's text without its reviews block, so a
+ * verdict can name the text it judged and stop counting after an amendment.
+ * `computeQuorum` lists which verdicts count toward the quorum and why the
+ * others don't. The end-to-end reads through `records --json` are in
+ * records-contract.test.ts.
+ */
+
+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 { workingTreeSource } from "./record-source";
+import { computeQuorum, DEFAULT_QUORUM, loadRecordKind, normalisePrincipal, readRecords, recordTextDigest, type QuorumOptions, type RecordEntry } 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");
+
+/** ws-003 with its reviews list replaced. `reviews` is the YAML under `reviews:`, or null for `reviews: []`. */
+function withReviews(reviews: string | null, text = SAMPLE): string {
+  return text.replace(/^reviews: \[\]$/m, reviews === null ? "reviews: []" : `reviews:\n${reviews.replace(/\n$/, "")}`);
+}
+
+/** One review entry as YAML. */
+function review(reviewer: string, verdict: string, extra: Record<string, string> = {}): string {
+  const note = verdict === "dissent" && !extra.note ? { note: "it misses a case" } : {};
+  const fields = { reviewer, verdict, on: "2026-09-24", ...note, ...extra };
+  return Object.entries(fields)
+    .map(([k, v], i) => `${i === 0 ? "  - " : "    "}${k}: ${JSON.stringify(v)}`)
+    .join("\n");
+}
+
+const BARE = recordTextDigest(SAMPLE);
+
+describe("recordTextDigest", () => {
+  test("is the sha256 hex of the text with the reviews block taken out", () => {
+    expect(BARE).toMatch(/^[0-9a-f]{64}$/);
+    const lines = SAMPLE.split("\n");
+    const without = lines.filter((l) => l !== "reviews: []").join("\n");
+    expect(recordTextDigest(SAMPLE)).toBe(recordTextDigest(without, null));
+  });
+
+  test("does not move when a verdict is added, changed or removed", () => {
+    const one = withReviews(review("alice", "agree"));
+    const two = withReviews(`${review("alice", "agree", { digest: BARE })}\n${review("bob", "dissent", { note: "no" })}`);
+    expect(recordTextDigest(one)).toBe(BARE);
+    expect(recordTextDigest(two)).toBe(BARE);
+    // The compact form, with the list at column 0, and comments and blank lines inside the block.
+    const compact = SAMPLE.replace(/^reviews: \[\]$/m, `reviews:\n# first review\n- reviewer: "alice"\n  verdict: "agree"\n\n  on: "2026-09-24"`);
+    expect(recordTextDigest(compact)).toBe(BARE);
+    // A quoted key is the same key.
+    expect(recordTextDigest(SAMPLE.replace(/^reviews: \[\]$/m, `"reviews": []`))).toBe(BARE);
+  });
+
+  test("moves with any other edit, in the front matter or the body", () => {
+    expect(recordTextDigest(SAMPLE.replace(/^title: .*$/m, 'title: "Seal scope, amended"'))).not.toBe(BARE);
+    expect(recordTextDigest(`${SAMPLE}\nOne more line.\n`)).not.toBe(BARE);
+    // The line after the block is kept: removal stops at the next key.
+    expect(recordTextDigest(SAMPLE.replace(/^constrains:$/m, "constrains: # the scope"))).not.toBe(BARE);
+  });
+
+  test("reads CRLF and LF alike", () => {
+    expect(recordTextDigest(SAMPLE.replace(/\n/g, "\r\n"))).toBe(BARE);
+  });
+
+  test("hashes text with no front matter as it is", () => {
+    expect(recordTextDigest("reviews: []\nbody\n")).toBe(recordTextDigest("reviews: []\nbody\n", null));
+    expect(recordTextDigest("---\nreviews: []\nno closing line\n")).toBe(recordTextDigest("---\nreviews: []\nno closing line\n", null));
+  });
+
+  test("a hand-editor gets the same digest with awk and sha256sum", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-digest-")));
+    try {
+      const file = join(dir, "ws-003.md");
+      writeFileSync(file, withReviews(`${review("alice", "agree")}\n${review("bob", "dissent")}`));
+      // The recipe in docs/src/content/docs/cli/workspace-records.mdx.
+      const awk = `awk 'NR==1&&$0=="---"{fm=1;print;next} fm&&$0=="---"{fm=0;skip=0;print;next} fm&&/^reviews[ \\t]*:/{skip=1;next} fm&&skip&&/^([ \\t#-]|$)/{next} {skip=0;print}' "${file}" | shasum -a 256`;
+      const out = execFileSync("sh", ["-c", awk], { encoding: "utf-8" });
+      expect(out.split(" ")[0]).toBe(BARE);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("normalisePrincipal", () => {
+  test("trims and case-folds", () => {
+    expect(normalisePrincipal("Alice ")).toBe("alice");
+    expect(normalisePrincipal(" ALICE")).toBe(normalisePrincipal("alice"));
+    expect(normalisePrincipal("ａｌｉｃｅ")).toBe("alice");
+  });
+});
+
+describe("computeQuorum", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-quorum-")));
+    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 }));
+
+  const OPTIONS: QuorumOptions = { need: DEFAULT_QUORUM, needFrom: "default", agents: new Set(), attestation: false };
+
+  async function quorumOf(text: string, options: Partial<QuorumOptions> = {}) {
+    writeFileSync(join(dir, "decisions", "ws-003-seal-scope.md"), text);
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const { records } = await readRecords(loaded, { root: dir, source: workingTreeSource(dir) });
+    const record = records[0] as RecordEntry;
+    expect(record.reasons).toEqual([]);
+    return { record, quorum: computeQuorum(loaded.kind, record, { ...OPTIONS, ...options })! };
+  }
+
+  const principals = (list: Array<{ principal: string; reason?: { code: string } }>) => list.map((v) => (v.reason ? `${v.principal}:${v.reason.code}` : v.principal));
+
+  test("alice and 'Alice ' count once: the later verdict stands, the earlier is a duplicate", async () => {
+    const { quorum } = await quorumOf(withReviews(`${review("alice", "agree", { digest: BARE })}\n${review("Alice ", "agree", { digest: BARE })}`));
+    expect(principals(quorum.counted)).toEqual(["alice"]);
+    expect(quorum.counted[0].reviewer).toBe("Alice ");
+    expect(principals(quorum.notCounted)).toEqual(["alice:review-duplicate"]);
+    expect(quorum).toMatchObject({ need: 2, agreed: 1, met: false, metWithObjections: false });
+  });
+
+  test("a review by the decider is listed as not counted", async () => {
+    const { quorum } = await quorumOf(withReviews(`${review("Lex00", "agree", { digest: BARE })}\n${review("bob", "agree", { digest: BARE })}`));
+    expect(principals(quorum.notCounted)).toEqual(["lex00:review-decider"]);
+    expect(principals(quorum.counted)).toEqual(["bob"]);
+  });
+
+  test("amending the record after one agree drops the count from 1 to 0, with review-older-digest", async () => {
+    const reviewed = withReviews(review("alice", "agree", { digest: BARE }));
+    const before = await quorumOf(reviewed);
+    expect(before.quorum.agreed).toBe(1);
+    const after = await quorumOf(reviewed.replace(/^question: .*$/m, 'question: "What does a seal cover, now?"'));
+    expect(after.record.digest).not.toBe(BARE);
+    expect(after.quorum.counted).toEqual([]);
+    expect(after.quorum.agreed).toBe(0);
+    expect(principals(after.quorum.notCounted)).toEqual(["alice:review-older-digest"]);
+    expect(after.quorum.notCounted[0].reason!.message).toContain(BARE.slice(0, 12));
+  });
+
+  test("a verdict with no digest counts, and the record carries review-undigested", async () => {
+    const { record, quorum } = await quorumOf(withReviews(`${review("alice", "agree")}\n${review("bob", "agree", { digest: BARE })}`));
+    expect(principals(quorum.counted)).toEqual(["alice", "bob"]);
+    expect(quorum.counted[0].digest).toBeNull();
+    expect(quorum).toMatchObject({ agreed: 2, met: true, metWithObjections: false });
+    expect(record.warnings.map((w) => w.code)).toEqual(["review-undigested"]);
+    expect(record.warnings[0].message).toContain("alice");
+    expect(record.warnings[0].message).not.toContain("bob");
+  });
+
+  test("a met count with an open concern is met with objections, never consensus", async () => {
+    const reviews = [review("alice", "agree", { digest: BARE }), review("bob", "agree", { digest: BARE }), review("carol", "dissent", { digest: BARE, proposes: "ws-900" })];
+    const { quorum } = await quorumOf(withReviews(reviews.join("\n")));
+    expect(quorum).toMatchObject({ agreed: 2, met: true, metWithObjections: true });
+    expect(quorum.openConcerns).toEqual([{ index: 2, principal: "carol", reviewer: "carol", note: "it misses a case", proposes: "ws-900" }]);
+  });
+
+  test("an addressed or withdrawn dissent is no open concern", async () => {
+    const reviews = [
+      review("alice", "agree", { digest: BARE }),
+      review("bob", "agree", { digest: BARE }),
+      review("carol", "dissent", { digest: BARE, addressed_by: "ws-001" }),
+      review("dan", "dissent", { digest: BARE, withdrawn_on: "2026-09-25" }),
+    ];
+    const { quorum } = await quorumOf(withReviews(reviews.join("\n")));
+    expect(quorum.openConcerns).toEqual([]);
+    expect(quorum).toMatchObject({ met: true, metWithObjections: false });
+  });
+
+  test("an agent's verdict is not counted, and under an attestation policy an unsealed one is not either", async () => {
+    const text = withReviews(`${review("Bot-1", "agree", { digest: BARE })}\n${review("alice", "agree", { digest: BARE })}`);
+    const agents = await quorumOf(text, { agents: new Set(["bot-1"]) });
+    expect(principals(agents.quorum.notCounted)).toEqual(["bot-1:review-agent"]);
+    const attested = await quorumOf(text, { attestation: true });
+    expect(principals(attested.quorum.notCounted)).toEqual(["bot-1:review-unattested", "alice:review-unattested"]);
+    expect(attested.quorum.counted).toEqual([]);
+  });
+
+  test("the declared need applies, and a need of 0 is met with no verdict", async () => {
+    const { quorum } = await quorumOf(SAMPLE, { need: 0, needFrom: "declaration" });
+    expect(quorum).toMatchObject({ need: 0, needFrom: "declaration", agreed: 0, met: true, counted: [], notCounted: [], openConcerns: [] });
+  });
+
+  test("a kind with no reviews list has no quorum", async () => {
+    const loaded = await loadRecordKind(join(DECISIONS, "decision.kind.mjs"));
+    const { reviews: _drop, ...kind } = loaded.kind;
+    expect(computeQuorum(kind, { data: {}, digest: BARE }, OPTIONS)).toBeNull();
+    expect(computeQuorum(loaded.kind, { data: null, digest: BARE }, OPTIONS)).toBeNull();
+  });
+});

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

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json",
+  "title": "chant workspace records review output",
+  "description": "What `chant workspace records review <id> --kind <kind file> --verdict <verdict> --by <principal>` prints (#2670): the record's path and id and the review entry appended, or the reason it wrote nothing. Version 1 of the write contract for records. The command writes one file or none and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.86.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "review",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"decision\"."
+            },
+            "schema": {
+              "type": "string",
+              "description": "The `$id` of the schema the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "review": {
+          "type": "object",
+          "description": "The entry appended to the record's reviews, as written.",
+          "required": [
+            "reviewer",
+            "verdict",
+            "on",
+            "digest"
+          ],
+          "properties": {
+            "reviewer": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The principal given with --by, as given. chant does not check who it is; attestation of the commit that carries the review does (#2547)."
+            },
+            "verdict": {
+              "enum": [
+                "agree",
+                "dissent",
+                "abstain"
+              ]
+            },
+            "note": {
+              "type": "string",
+              "description": "The note given with --note. Absent when none was given; a dissent always has one."
+            },
+            "on": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+              "description": "The date of the verdict, in UTC."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The digest of the record text the verdict judged: the lowercase hex SHA-256 of the file with LF line endings and without its reviews block (#2672), as records prints it for the record. The command changes only the reviews block, so the record keeps this digest."
+            },
+            "session": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The session given with --session. Absent when none was given."
+            }
+          }
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "record-not-found",
+                "review-unsupported",
+                "record-closed",
+                "review-note-required",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something, such as writing a new record that supersedes this one."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Review sessions as a record kind (#2673, #2650 C10), read through the
+ * reference workspace's session kind: a closed session's seal is checked on
+ * read, each verdict names a decision that exists, and each session lists the
+ * decision reviews that cite it.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, REPO } from "./__fixtures__/contract-repo";
+import { reviewed, sessionText, SESSIONS_KIND as SESSIONS, sessionsRepo as fixture } from "./__fixtures__/sessions";
+import { sessionSeal } from "./record-sessions";
+import { queryRecords, type RecordsDocument } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(recordsSchema);
+
+async function read(root: string, at?: string): Promise<Extract<RecordsDocument, { records: unknown }>> {
+  const doc = await queryRecords({ kind: SESSIONS, cwd: root, ...(at ? { at } : {}) });
+  expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("the session kind (#2673)", () => {
+  test("the reference workspace's session is closed, sealed and valid, and cited by nothing", async () => {
+    const doc = await read(join(REPO, "reference-workspace"));
+    expect(doc.kind.name).toBe("session");
+    expect(doc.records.map((r) => [r.id, r.state, r.valid])).toEqual([["S-0001", "closed", true]]);
+    expect(doc.records[0].citedBy).toEqual([]);
+  });
+
+  test("the seal is the awk recipe the docs give", () => {
+    const file = join(REPO, "reference-workspace", "design", "sessions", "S-0001-first-walk-of-the-reference-decisions.md");
+    const awk = execFileSync("sh", ["-c", `awk 'NR==1&&/^---$/{f=1;print;next} f&&/^---$/{f=0} f&&/^closed_digest:/{next} {print}' "$1" | shasum -a 256`, "sh", file], { encoding: "utf-8" });
+    const text = readFileSync(file, "utf-8");
+    expect(awk.split(" ")[0]).toBe(sessionSeal(text, "closed_digest"));
+    expect(text).toContain(`closed_digest: "${sessionSeal(text, "closed_digest")}"`);
+    // CRLF line endings hash as LF.
+    expect(sessionSeal(text.replace(/\n/g, "\r\n"), "closed_digest")).toBe(sessionSeal(text, "closed_digest"));
+  });
+
+  test("a closed session edited after it closed is session-seal-mismatch", async () => {
+    const root = fixture();
+    const file = join(root, "design", "sessions", "S-0001-first-walk-of-the-reference-decisions.md");
+    writeFileSync(file, readFileSync(file, "utf-8").replace("First walk", "Second walk"));
+    const s1 = (await read(root)).records[0];
+    expect(s1.valid).toBe(false);
+    expect(s1.reasons.map((r) => r.code)).toEqual(["session-seal-mismatch"]);
+  });
+
+  test("an open session with a seal, or a closed one without, is schema-invalid", async () => {
+    const root = fixture();
+    const dir = join(root, "design", "sessions");
+    writeFileSync(join(dir, "S-0002-open.md"), sessionText({ id: "S-0002", state: "open" }).replace("verdicts: []", 'verdicts: []\nclosed_digest: "' + "0".repeat(64) + '"'));
+    writeFileSync(join(dir, "S-0003-closed.md"), sessionText({ id: "S-0003", state: "closed" }).replace(/^closed_digest: .*\n/m, ""));
+    const doc = await read(root);
+    expect(doc.records.filter((r) => r.id !== "S-0001").map((r) => [r.id, r.reasons.map((x) => x.code)])).toEqual([
+      ["S-0002", ["record-schema-invalid"]],
+      ["S-0003", ["record-schema-invalid"]],
+    ]);
+  });
+
+  test("a verdict naming a record no decision has is session-verdict-unknown-record", async () => {
+    const root = fixture();
+    writeFileSync(
+      join(root, "design", "sessions", "S-0002-walk.md"),
+      sessionText({ id: "S-0002", state: "closed", verdicts: [{ record: "ref-001", principal: "alice", verdict: "agree" }, { record: "ref-999", principal: "alice", verdict: "agree" }] }),
+    );
+    const s2 = (await read(root)).records.find((r) => r.id === "S-0002")!;
+    expect(s2.valid).toBe(false);
+    expect(s2.reasons).toEqual([{ code: "session-verdict-unknown-record", message: expect.stringContaining("verdicts[1] names ref-999") }]);
+  });
+
+  test("each session lists the decision reviews that name it, and --at reads both kinds at the revision", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "design", "sessions", "S-0002-walk.md"), sessionText({ id: "S-0002", state: "open" }));
+    const open = commitAll(root, "open S-0002");
+    reviewed(root, ["alice", "bob"], "S-0002");
+    writeFileSync(
+      join(root, "design", "sessions", "S-0002-walk.md"),
+      sessionText({ id: "S-0002", state: "closed", verdicts: [{ record: "ref-001", principal: "alice", verdict: "agree" }, { record: "ref-001", principal: "bob", verdict: "agree" }] }),
+    );
+    const doc = await read(root);
+    expect(doc.summary.invalid).toBe(0);
+    const s2 = doc.records.find((r) => r.id === "S-0002")!;
+    expect(s2.citedBy).toEqual([
+      { id: "ref-001", path: "decisions/ref-001-how-the-app-is-deployed.md", index: 0, reviewer: "alice", verdict: "agree" },
+      { id: "ref-001", path: "decisions/ref-001-how-the-app-is-deployed.md", index: 1, reviewer: "bob", verdict: "agree" },
+    ]);
+    expect(doc.records.find((r) => r.id === "S-0001")!.citedBy).toEqual([]);
+    const then = await read(root, open);
+    expect(then.records.find((r) => r.id === "S-0002")).toMatchObject({ state: "open", valid: true, citedBy: [] });
+  });
+
+  test("the decision kind accepts a review entry naming its session", async () => {
+    const root = fixture();
+    reviewed(root, ["alice"], "S-0001");
+    const doc = await queryRecords({ kind: "decisions/decision.kind.mjs", cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records.find((r) => r.id === "ref-001")).toMatchObject({ valid: true });
+    expect((await read(root)).records[0].citedBy).toEqual([expect.objectContaining({ id: "ref-001", reviewer: "alice" })]);
+  });
+});