@intentius/chant 0.84.0 → 0.86.0

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

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.schema.json",
+  "title": "chant workspace records --since output",
+  "description": "What `chant workspace records --kind <kind file> --since <rev> --json` prints (#2673, #2650 C11): what changed in a kind's records between the commit --since names and the tree --at names, or the working tree without it. Records are matched by id; a record whose id could not be read is not compared. Between a review session's open and close commits, the changes are what the session did. Readers ignore fields they do not know; a field is only ever added within a version. The change kinds and the error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2673; a chant without --since on records refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }, { "$ref": "#/$defs/set" }],
+  "$defs": {
+    "set": {
+      "description": "Added in contract 1 by #2680. What records --since prints without --kind when the workspace declaration names record kinds: one result or failure per declared kind, in the declaration's order (the workspace's own kinds, then each member's in member order). Exit code 1 when any kind's read failed; the others are still compared and listed.",
+      "type": "object",
+      "required": ["$schema", "contract", "kinds"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.schema.json" },
+        "contract": { "const": 1 },
+        "kinds": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              { "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }] },
+              {
+                "type": "object",
+                "required": ["declared"],
+                "properties": {
+                  "declared": {
+                    "description": "The declaration's entry for the kind, as in the records set.",
+                    "type": "object",
+                    "required": ["member", "path", "name"],
+                    "properties": {
+                      "member": { "type": ["string", "null"] },
+                      "path": { "type": "string" },
+                      "name": { "type": ["string", "null"] }
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "kind": false,
+        "changes": false,
+        "error": false
+      }
+    },
+    "result": {
+      "description": "Both revisions were read. Exit code 0, whatever changed.",
+      "type": "object",
+      "required": ["$schema", "contract", "kind", "since", "at", "changes", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.schema.json" },
+        "contract": { "const": 1 },
+        "kind": {
+          "type": "object",
+          "required": ["name", "schema", "file"],
+          "properties": {
+            "name": { "type": "string", "description": "The kind's name, such as \"decision\" or \"session\"." },
+            "schema": { "type": "string", "description": "The `$id` of the kind's record schema." },
+            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators. It is read from the working tree for both revisions." }
+          }
+        },
+        "since": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id --since names." },
+        "at": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id --at names, or null for the working tree." },
+        "error": false,
+        "changes": {
+          "description": "In the order new, removed, state, verdict, supersession, pin, and by id within each.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/change" }
+        },
+        "summary": {
+          "description": "How many changes of each kind.",
+          "type": "object",
+          "required": ["new", "removed", "state", "verdict", "supersession", "pin"],
+          "properties": {
+            "new": { "type": "integer", "minimum": 0 },
+            "removed": { "type": "integer", "minimum": 0 },
+            "state": { "type": "integer", "minimum": 0 },
+            "verdict": { "type": "integer", "minimum": 0 },
+            "supersession": { "type": "integer", "minimum": 0 },
+            "pin": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "change": {
+      "oneOf": [
+        { "$ref": "#/$defs/new" },
+        { "$ref": "#/$defs/removed" },
+        { "$ref": "#/$defs/state" },
+        { "$ref": "#/$defs/verdict" },
+        { "$ref": "#/$defs/supersession" },
+        { "$ref": "#/$defs/pin" }
+      ]
+    },
+    "new": {
+      "description": "A record with an id no record had at --since. A directory that did not exist at --since held no records, so every record in it is new.",
+      "type": "object",
+      "required": ["change", "id", "path", "state"],
+      "properties": {
+        "change": { "const": "new" },
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "From the repository root, with / separators." },
+        "state": { "type": ["string", "null"] }
+      }
+    },
+    "removed": {
+      "description": "A record whose id no record has any more.",
+      "type": "object",
+      "required": ["change", "id", "path", "state"],
+      "properties": {
+        "change": { "const": "removed" },
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "Where it was at --since." },
+        "state": { "type": ["string", "null"], "description": "Its state at --since." }
+      }
+    },
+    "state": {
+      "description": "A state transition, such as decided to ratified, or a session open to closed.",
+      "type": "object",
+      "required": ["change", "id", "from", "to"],
+      "properties": {
+        "change": { "const": "state" },
+        "id": { "type": "string" },
+        "from": { "type": ["string", "null"] },
+        "to": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "description": "A verdict the record did not have at --since, including every verdict on a new record. On a session it is an entry of the session's verdict list, with the record it judged in record; on any other record, an entry of its reviews list, with the session it was given in when it names one. Two entries are the same verdict when they name the same principal, verdict, date, session and record, so a dissent that later gains addressed_by is not a new one.",
+      "type": "object",
+      "required": ["change", "id", "principal", "verdict", "index"],
+      "properties": {
+        "change": { "const": "verdict" },
+        "id": { "type": "string", "description": "The record holding the verdict." },
+        "principal": { "type": ["string", "null"], "description": "Who gave it, as written: a review's reviewer, or a session verdict's principal." },
+        "verdict": { "type": ["string", "null"], "description": "agree, dissent or abstain, as written." },
+        "index": { "type": "integer", "minimum": 0, "description": "Its position in the list, from 0." },
+        "record": { "type": "string", "description": "On a session's verdict, the record it judged." },
+        "session": { "type": "string", "description": "On a review entry, the session it names." }
+      }
+    },
+    "supersession": {
+      "description": "A supersession that took effect since --since, derived by the same rule as records' supersededBy, so a pending link that is now approved counts.",
+      "type": "object",
+      "required": ["change", "id", "supersedes"],
+      "properties": {
+        "change": { "const": "supersession" },
+        "id": { "type": "string", "description": "The superseding record." },
+        "supersedes": { "type": "string", "description": "The record it now supersedes." }
+      }
+    },
+    "pin": {
+      "description": "A pinned file whose pinned sha256 changed on a record that exists at both revisions: from is null for a pin added, and to is null for a pin removed.",
+      "type": "object",
+      "required": ["change", "id", "path", "from", "to"],
+      "properties": {
+        "change": { "const": "pin" },
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "From the workspace root, as the pin writes it." },
+        "from": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
+        "to": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "failure": {
+      "description": "A revision or the kind could not be read. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.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",
+                "not-a-git-repository",
+                "revision-unknown",
+                "since-rev-unknown"
+              ]
+            },
+            "message": { "type": "string" }
+          }
+        },
+        "changes": false
+      }
+    }
+  }
+}

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

@@ -0,0 +1,174 @@
+/**
+ * `chant workspace records --since <rev>` (#2673, #2650 C11), the contract
+ * and the comparison. The fixture is a repository with commits for a review
+ * session's open and close: between them the session closes with two
+ * verdicts, ref-001 gains the two reviews that name it and is ratified,
+ * a new decision supersedes ref-002, and ref-002's pin moves. Every document
+ * validates against records-since.schema.json.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, git, REPO, scratchDir, validSchema } from "./__fixtures__/contract-repo";
+import { DECISIONS_KIND, reviewed, sessionText, SESSIONS_KIND, sessionsRepo } from "./__fixtures__/sessions";
+import { queryRecordsSince, RECORDS_SINCE_ERROR_CODES, RECORDS_SINCE_OUTPUT_SCHEMA_ID, SINCE_CHANGE_KINDS, type RecordsSinceDocument } from "./records-since";
+import schema from "./records-since.schema.json";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+async function since(q: { kind: string; since: string; at?: string; cwd: string }): Promise<RecordsSinceDocument> {
+  const doc = await queryRecordsSince(q);
+  expectValid(doc);
+  return doc;
+}
+
+function ok(doc: RecordsSinceDocument): Extract<RecordsSinceDocument, { changes: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+/** The session fixture: returns the repository and its commits. */
+function sessionHistory(): { root: string; before: string; open: string; close: string } {
+  const root = sessionsRepo();
+  const before = git(root, "rev-parse", "HEAD");
+  writeFileSync(join(root, "design", "sessions", "S-0002-walk.md"), sessionText({ id: "S-0002", state: "open", agenda: ["ref-001", "ref-002"] }));
+  const open = commitAll(root, "open S-0002");
+
+  reviewed(root, ["alice", "bob"], "S-0002", "ratified");
+  writeFileSync(
+    join(root, "design", "sessions", "S-0002-walk.md"),
+    sessionText({
+      id: "S-0002",
+      state: "closed",
+      agenda: ["ref-001", "ref-002"],
+      verdicts: [
+        { record: "ref-001", principal: "alice", verdict: "agree" },
+        { record: "ref-001", principal: "bob", verdict: "agree" },
+      ],
+    }),
+  );
+  const ref002 = join(root, "decisions", "ref-002-where-the-screen-design-lives.md");
+  const text = readFileSync(ref002, "utf-8");
+  writeFileSync(ref002, text.replace(/sha256: "[0-9a-f]{64}"/, `sha256: "${"a".repeat(64)}"`));
+  writeFileSync(
+    join(root, "decisions", "ref-003-a-successor.md"),
+    text.replace(/^id: .*$/m, 'id: "ref-003"').replace(/^supersedes: \[\]$/m, 'supersedes:\n  - decision: "ref-002"'),
+  );
+  const close = commitAll(root, "close S-0002");
+  return { root, before, open, close };
+}
+
+describe("records-since output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(RECORDS_SINCE_OUTPUT_SCHEMA_ID);
+  });
+
+  test("lists exactly the error codes and change kinds the code can return", () => {
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...RECORDS_SINCE_ERROR_CODES]);
+    expect(schema.$defs.change.oneOf.map((r) => (schema.$defs as unknown as Record<string, { properties: { change: { const: string } } }>)[r.$ref.replace("#/$defs/", "")].properties.change.const)).toEqual([...SINCE_CHANGE_KINDS]);
+    expect(Object.keys(schema.$defs.result.properties.summary.properties)).toEqual([...SINCE_CHANGE_KINDS]);
+  });
+});
+
+describe("records --since (#2673)", () => {
+  const h = sessionHistory();
+
+  test("between a session's open and close commits, the decisions show every verdict, state change, supersession and pin", async () => {
+    const doc = ok(await since({ kind: DECISIONS_KIND, since: h.open, at: h.close, cwd: h.root }));
+    expect(doc.since).toBe(h.open);
+    expect(doc.at).toBe(h.close);
+    expect(doc.kind).toEqual({ name: "decision", schema: "urn:intentius:chant:decision:1", file: "decisions/decision.kind.mjs" });
+    expect(doc.changes).toEqual([
+      { change: "new", id: "ref-003", path: "decisions/ref-003-a-successor.md", state: "decided" },
+      { change: "state", id: "ref-001", from: "decided", to: "ratified" },
+      { change: "verdict", id: "ref-001", principal: "alice", verdict: "agree", index: 0, session: "S-0002" },
+      { change: "verdict", id: "ref-001", principal: "bob", verdict: "agree", index: 1, session: "S-0002" },
+      { change: "supersession", id: "ref-003", supersedes: "ref-002" },
+      { change: "pin", id: "ref-002", path: "design/screens/home.json", from: expect.stringMatching(/^[0-9a-f]{64}$/), to: "a".repeat(64) },
+    ]);
+    expect(doc.summary).toEqual({ new: 1, removed: 0, state: 1, verdict: 2, supersession: 1, pin: 1 });
+  });
+
+  test("the session kind shows the session closing and the verdicts it produced", async () => {
+    const doc = ok(await since({ kind: SESSIONS_KIND, since: h.open, at: h.close, cwd: h.root }));
+    expect(doc.changes).toEqual([
+      { change: "state", id: "S-0002", from: "open", to: "closed" },
+      { change: "verdict", id: "S-0002", principal: "alice", verdict: "agree", index: 0, record: "ref-001" },
+      { change: "verdict", id: "S-0002", principal: "bob", verdict: "agree", index: 1, record: "ref-001" },
+    ]);
+  });
+
+  test("without --at it compares with the working tree, and a record deleted there is removed", async () => {
+    rmSync(join(h.root, "decisions", "ref-003-a-successor.md"));
+    try {
+      const doc = ok(await since({ kind: DECISIONS_KIND, since: h.close, cwd: h.root }));
+      expect(doc.at).toBeNull();
+      expect(doc.changes).toEqual([{ change: "removed", id: "ref-003", path: "decisions/ref-003-a-successor.md", state: "decided" }]);
+    } finally {
+      git(h.root, "checkout", "--", "decisions");
+    }
+  });
+
+  test("a directory that did not exist at --since held no records, so every record in it is new", async () => {
+    const root = scratchDir("chant-since-empty-");
+    git(root, "init", "-q");
+    writeFileSync(join(root, "README.md"), "empty\n");
+    const first = commitAll(root, "empty");
+    const copy = sessionsRepo();
+    for (const d of ["decisions", "design"]) cpSync(join(copy, d), join(root, d), { recursive: true });
+    const doc = ok(await since({ kind: SESSIONS_KIND, since: first, cwd: root }));
+    expect(doc.changes).toEqual([{ change: "new", id: "S-0001", path: "design/sessions/S-0001-first-walk-of-the-reference-decisions.md", state: "closed" }]);
+  });
+
+  test("nothing changed is an empty list", async () => {
+    const doc = ok(await since({ kind: DECISIONS_KIND, since: h.close, at: "HEAD", cwd: h.root }));
+    expect(doc.changes).toEqual([]);
+  });
+
+  test("a --since that names no commit is since-rev-unknown, and a bad --at is revision-unknown", async () => {
+    const docs = [
+      await since({ kind: DECISIONS_KIND, since: "no-such-rev", cwd: h.root }),
+      await since({ kind: DECISIONS_KIND, since: "--all", cwd: h.root }),
+      await since({ kind: DECISIONS_KIND, since: h.open, at: "no-such-rev", cwd: h.root }),
+      await since({ kind: "missing.kind.mjs", since: h.open, cwd: h.root }),
+    ];
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual(["since-rev-unknown", "since-rev-unknown", "revision-unknown", "kind-unreadable"]);
+  });
+
+  test("outside a git repository it is not-a-git-repository", async () => {
+    const root = scratchDir("chant-since-nogit-");
+    const doc = await since({ kind: DECISIONS_KIND, since: "HEAD", cwd: root });
+    expect("error" in doc && doc.error.code).toBe("not-a-git-repository");
+  });
+
+  test(
+    "through the CLI: --json prints the document, the text form a line per change, and a bad --since exits 1",
+    () => {
+      const run = (...args: string[]) =>
+        spawnSync(process.execPath, ["--import", pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href, join(REPO, "packages/core/src/cli/main.ts"), "workspace", "records", ...args], {
+          cwd: h.root,
+          encoding: "utf-8",
+          env: { ...process.env, NO_COLOR: "1" },
+          timeout: 60_000,
+        });
+      const json = run("--kind", SESSIONS_KIND, "--since", h.open, "--at", h.close, "--json");
+      expect(json.status, json.stderr).toBe(0);
+      expectValid(JSON.parse(json.stdout));
+      const text = run("--kind", SESSIONS_KIND, "--since", h.open, "--at", h.close);
+      expect(text.stdout).toContain("S-0002  state open to closed");
+      expect(text.stdout).toContain("S-0002  verdict agree by alice on ref-001");
+      const bad = run("--kind", SESSIONS_KIND, "--since", "nope", "--json");
+      expect(bad.status).toBe(1);
+      expect(JSON.parse(bad.stdout).error.code).toBe("since-rev-unknown");
+      const mixed = run("--kind", SESSIONS_KIND, "--since", h.open, "--current");
+      expect(mixed.status).toBe(1);
+    },
+    120_000,
+  );
+});

package/src/workspace/records-since.ts

@@ -0,0 +1,259 @@
+/**
+ * `chant workspace records --kind <kind file> --since <rev> [--at <rev>]
+ * [--json]` (#2673, #2650 C11): what changed in a kind's records between two
+ * revisions. It reads the records at `<rev>` and at `--at` (the working tree
+ * without it), through the same reader as `records`, and lists new and
+ * removed records, state transitions, new verdicts, new supersessions and
+ * changed pins. Between a review session's open and close commits, that is
+ * what the session did.
+ *
+ * Records are matched by id. A record whose id could not be read is left
+ * out of the comparison, since nothing says which record it was before.
+ */
+
+import { realpathSync } from "node:fs";
+import { relative } from "node:path";
+import { pinEntries } from "./record-assets";
+import { gitRoot, resolveRevision } from "./record-source";
+import { READ_ERROR_CODES, RecordReadError, type LoadedRecordKind, type ReadErrorCode, type RecordEntry, type RecordKind } from "./records";
+import { readRecordsFor, RECORDS_CONTRACT_VERSION } from "./records-cli";
+import type { ReasonCode } from "./reason-codes";
+
+/** `$id` of the JSON Schema for `records --since --json`, shipped beside this file. */
+export const RECORDS_SINCE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-since/v1/records-since.schema.json";
+
+/** Why a `--since` read failed: any records read error, or a `--since` that names no commit. Closed. */
+export const RECORDS_SINCE_ERROR_CODES = [
+  ...READ_ERROR_CODES,
+  /** `--since` names no commit. */
+  "since-rev-unknown",
+] as const satisfies readonly ReasonCode[];
+export type RecordsSinceErrorCode = (typeof RECORDS_SINCE_ERROR_CODES)[number];
+
+/** The kinds of change, in the order the output lists them. */
+export const SINCE_CHANGE_KINDS = ["new", "removed", "state", "verdict", "supersession", "pin"] as const;
+export type SinceChangeKind = (typeof SINCE_CHANGE_KINDS)[number];
+
+/** The review list on a record that is not a session, when its kind declares none (#2670, #2671). */
+const REVIEWS_FIELD = "reviews";
+
+export type SinceChange =
+  | { change: "new"; id: string; path: string; state: string | null }
+  | { change: "removed"; id: string; path: string; state: string | null }
+  | { change: "state"; id: string; from: string | null; to: string | null }
+  | { change: "verdict"; id: string; principal: string | null; verdict: string | null; index: number; record?: string; session?: string }
+  | { change: "supersession"; id: string; supersedes: string }
+  | { change: "pin"; id: string; path: string; from: string | null; to: string | null };
+
+export type RecordsSinceDocument =
+  | {
+      $schema: string;
+      contract: number;
+      kind: { name: string; schema: string; file: string };
+      since: string;
+      at: string | null;
+      changes: SinceChange[];
+      summary: Record<SinceChangeKind, number>;
+    }
+  | { $schema: string; contract: number; error: { code: RecordsSinceErrorCode; message: string } };
+
+export interface RecordsSinceQuery {
+  kind: string;
+  since: string;
+  at?: string;
+  cwd: string;
+}
+
+class SinceError extends Error {
+  constructor(
+    readonly code: RecordsSinceErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Run the comparison and build the document `--json` prints. Never throws a read error. */
+export async function queryRecordsSince(query: RecordsSinceQuery): Promise<RecordsSinceDocument> {
+  const failure = (code: RecordsSinceErrorCode, message: string): RecordsSinceDocument => ({
+    $schema: RECORDS_SINCE_OUTPUT_SCHEMA_ID,
+    contract: RECORDS_CONTRACT_VERSION,
+    error: { code, message },
+  });
+  try {
+    const since = resolveSince(query.cwd, query.since);
+    const after = await readRecordsFor({ kind: query.kind, at: query.at, cwd: query.cwd });
+    let before: RecordEntry[];
+    try {
+      before = (await readRecordsFor({ kind: query.kind, at: since, cwd: query.cwd })).result.records;
+    } catch (err) {
+      // A directory that did not exist yet held no records.
+      if (!(err instanceof RecordReadError) || err.code !== "location-missing") throw err;
+      before = [];
+    }
+    const changes = compareRecords(after.loaded.kind, before, after.result.records);
+    const summary = Object.fromEntries(SINCE_CHANGE_KINDS.map((k) => [k, changes.filter((c) => c.change === k).length])) as Record<SinceChangeKind, number>;
+    return {
+      $schema: RECORDS_SINCE_OUTPUT_SCHEMA_ID,
+      contract: RECORDS_CONTRACT_VERSION,
+      kind: kindView(after.loaded, after.root),
+      since,
+      at: after.at,
+      changes,
+      summary,
+    };
+  } catch (err) {
+    if (err instanceof SinceError) return failure(err.code, err.message);
+    if (err instanceof RecordReadError) return failure(err.code satisfies ReadErrorCode, err.message);
+    throw err;
+  }
+}
+
+function kindView(loaded: LoadedRecordKind, root: string): { name: string; schema: string; file: string } {
+  return { name: loaded.kind.name, schema: loaded.kind.schema.id, file: relative(root, loaded.file).split("\\").join("/") };
+}
+
+/** The full commit id `rev` names, from the repository holding `cwd`. */
+function resolveSince(cwd: string, rev: string): string {
+  let dir = cwd;
+  try {
+    dir = realpathSync(cwd);
+  } catch {
+    // Reported by the read that follows, if at all.
+  }
+  const top = gitRoot(dir);
+  if (!top) throw new RecordReadError("not-a-git-repository", "--since reads git objects, and this directory is not in a git repository");
+  try {
+    return resolveRevision(top, rev);
+  } catch (err) {
+    if (err instanceof RecordReadError && err.code === "revision-unknown") {
+      throw new SinceError("since-rev-unknown", `--since ${rev} names no commit in this repository`);
+    }
+    throw err;
+  }
+}
+
+/** The first record with each id, in path order; records with no id are left out. */
+function byId(records: RecordEntry[]): Map<string, RecordEntry> {
+  const out = new Map<string, RecordEntry>();
+  for (const r of records) if (r.id !== null && !out.has(r.id)) out.set(r.id, r);
+  return out;
+}
+
+interface Verdict {
+  key: string;
+  index: number;
+  principal: string | null;
+  verdict: string | null;
+  record?: string;
+  session?: string;
+}
+
+/**
+ * A record's verdicts: a session's own verdict list, or the review list on
+ * any other record. Two entries are the same verdict when they name the same
+ * principal, verdict, date, session and record, so a dissent that later gains
+ * `addressed_by` is not a new verdict.
+ */
+function verdicts(kind: RecordKind, r: RecordEntry): Verdict[] {
+  const field = kind.session ? kind.session.verdicts : (kind.reviews?.field ?? REVIEWS_FIELD);
+  const list = r.data?.[field];
+  if (!Array.isArray(list)) return [];
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  const out: Verdict[] = [];
+  list.forEach((e, index) => {
+    if (e === null || typeof e !== "object" || Array.isArray(e)) return;
+    const o = e as Record<string, unknown>;
+    const principal = str(kind.session ? o.principal : o.reviewer) ?? null;
+    const verdict = str(o.verdict) ?? null;
+    const record = str(o.record);
+    const session = str(o.session);
+    out.push({
+      key: JSON.stringify([principal, verdict, str(o.on) ?? null, session ?? null, record ?? null]),
+      index,
+      principal,
+      verdict,
+      ...(record !== undefined ? { record } : {}),
+      ...(session !== undefined ? { session } : {}),
+    });
+  });
+  return out;
+}
+
+/** What changed from `before` to `after`, in the order of {@link SINCE_CHANGE_KINDS} and then by id. */
+export function compareRecords(kind: RecordKind, before: RecordEntry[], after: RecordEntry[]): SinceChange[] {
+  const old = byId(before);
+  const now = byId(after);
+  const ids = [...new Set([...old.keys(), ...now.keys()])].sort();
+  const out: Record<SinceChangeKind, SinceChange[]> = { new: [], removed: [], state: [], verdict: [], supersession: [], pin: [] };
+  for (const id of ids) {
+    const a = old.get(id);
+    const b = now.get(id);
+    if (!a && b) out.new.push({ change: "new", id, path: b.path, state: b.state });
+    if (a && !b) out.removed.push({ change: "removed", id, path: a.path, state: a.state });
+    if (!b) continue;
+    if (a && a.state !== b.state) out.state.push({ change: "state", id, from: a.state, to: b.state });
+
+    // Verdicts in b beyond the ones a already had, compared as multisets.
+    const seen = new Map<string, number>();
+    for (const v of a ? verdicts(kind, a) : []) seen.set(v.key, (seen.get(v.key) ?? 0) + 1);
+    for (const v of verdicts(kind, b)) {
+      const left = seen.get(v.key) ?? 0;
+      if (left > 0) {
+        seen.set(v.key, left - 1);
+        continue;
+      }
+      out.verdict.push({
+        change: "verdict",
+        id,
+        principal: v.principal,
+        verdict: v.verdict,
+        index: v.index,
+        ...(v.record !== undefined ? { record: v.record } : {}),
+        ...(v.session !== undefined ? { session: v.session } : {}),
+      });
+    }
+
+    // Supersession as derived, so a link that only now takes effect counts.
+    if (b.supersededBy !== null && (!a || a.supersededBy !== b.supersededBy)) {
+      out.supersession.push({ change: "supersession", id: b.supersededBy, supersedes: id });
+    }
+
+    if (a && kind.pins) {
+      const from = new Map(pinEntries(a.data, kind.pins.field).map((p) => [p.path, p.sha256]));
+      const to = new Map(pinEntries(b.data, kind.pins.field).map((p) => [p.path, p.sha256]));
+      for (const path of [...new Set([...from.keys(), ...to.keys()])].sort()) {
+        const x = from.get(path) ?? null;
+        const y = to.get(path) ?? null;
+        if (x !== y) out.pin.push({ change: "pin", id, path, from: x, to: y });
+      }
+    }
+  }
+  out.supersession.sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+  return SINCE_CHANGE_KINDS.flatMap((k) => out[k]);
+}
+
+/** The text form: one line per change and a summary. */
+export function formatSince(doc: Extract<RecordsSinceDocument, { changes: SinceChange[] }>): string {
+  const lines = doc.changes.map((c) => {
+    switch (c.change) {
+      case "new":
+        return `${c.id}  new, ${c.state ?? "no state"}  (${c.path})`;
+      case "removed":
+        return `${c.id}  removed, was ${c.state ?? "no state"}  (${c.path})`;
+      case "state":
+        return `${c.id}  state ${c.from ?? "none"} to ${c.to ?? "none"}`;
+      case "verdict":
+        return `${c.id}  verdict ${c.verdict ?? "-"} by ${c.principal ?? "-"}${c.record ? ` on ${c.record}` : ""}${c.session ? ` in ${c.session}` : ""}`;
+      case "supersession":
+        return `${c.id}  supersedes ${c.supersedes}`;
+      case "pin":
+        return `${c.id}  pin ${c.path} ${c.from ? c.from.slice(0, 12) : "none"} to ${c.to ? c.to.slice(0, 12) : "none"}`;
+    }
+  });
+  const s = doc.summary;
+  lines.push(
+    `${doc.changes.length} changes since ${doc.since.slice(0, 8)}${doc.at ? ` to ${doc.at.slice(0, 8)}` : " to the working tree"}: ${s.new} new, ${s.removed} removed, ${s.state} state, ${s.verdict} verdicts, ${s.supersession} supersessions, ${s.pin} pins`,
+  );
+  return lines.join("\n");
+}