@intentius/chant 0.86.0 → 0.88.0

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

@@ -2,7 +2,7 @@
   "$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.",
+  "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, or with --session the record and the session (#2693), 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"
@@ -75,7 +75,7 @@
             "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)."
+              "description": "The principal given with --by, as given. The write does not check who it is. With --sign, the seal lets chant workspace records check it against the signers file at base (#2687)."
             },
             "verdict": {
               "enum": [
@@ -101,7 +101,31 @@
             "session": {
               "type": "string",
               "minLength": 1,
-              "description": "The session given with --session. Absent when none was given."
+              "description": "The session given with --session. Absent when none was given. Since #2693 it names an open session of a session kind whose subjects are this kind, found through the workspace declaration (session-unknown, session-not-open)."
+            },
+            "seal": {
+              "type": "object",
+              "description": "Added in contract 1 by #2687. With --sign only: an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<verdict>\\n<reviewer>\\n<on>, in the ssh-keygen namespace chant-review. The write does not check the key against the signers file; chant workspace records reports whether the seal counts.",
+              "required": [
+                "signer",
+                "key",
+                "signature"
+              ],
+              "properties": {
+                "signer": {
+                  "type": "string",
+                  "description": "The reviewer given with --by."
+                },
+                "key": {
+                  "type": "string",
+                  "pattern": "^SHA256:[A-Za-z0-9+/]+=*$",
+                  "description": "The fingerprint of the key that signed, read back from the signature."
+                },
+                "signature": {
+                  "type": "string",
+                  "description": "The armored ssh signature."
+                }
+              }
             }
           }
         },
@@ -120,6 +144,57 @@
           "type": "string",
           "description": "With --dry-run only: the whole text of the file the command would write."
         },
+        "session": {
+          "type": "object",
+          "description": "Added in contract 1 by #2693, with --session only: the session record the verdict was also appended to, in the same command, so the session's verdicts list and the reviews that name the session never differ. Both files are validated before either is written.",
+          "required": [
+            "id",
+            "path",
+            "verdict"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The session file, relative to the repository root, with / separators."
+            },
+            "verdict": {
+              "type": "object",
+              "description": "The entry appended to the session's verdicts list (the field the session kind's session.verdicts names): the record's id, the principal given with --by, the verdict and the same digest as the review.",
+              "required": [
+                "record",
+                "principal",
+                "verdict",
+                "digest"
+              ],
+              "properties": {
+                "record": {
+                  "type": "string"
+                },
+                "principal": {
+                  "type": "string"
+                },
+                "verdict": {
+                  "enum": [
+                    "agree",
+                    "dissent",
+                    "abstain"
+                  ]
+                },
+                "digest": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            },
+            "text": {
+              "type": "string",
+              "description": "With --dry-run only: the whole text the session file would hold."
+            }
+          }
+        },
         "error": false
       }
     },
@@ -180,6 +255,9 @@
                 "review-unsupported",
                 "record-closed",
                 "review-note-required",
+                "review-sign-failed",
+                "session-unknown",
+                "session-not-open",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

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

@@ -0,0 +1,274 @@
+/**
+ * Sessions from a UI (#2693): `records new` on a session kind records the
+ * commit it opened at, `records close` closes and seals a session in one
+ * write, `records review --session` refuses a session that does not exist or
+ * is not open and appends the verdict to the session too, and
+ * `records --since <session id>` compares the session's own revisions. The
+ * fixture is a copy of the reference workspace's decisions and design
+ * member with a declaration naming both kinds.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, readFileSync, 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 } from "./__fixtures__/contract-repo";
+import { declareSessions, DECISIONS_KIND, newSessionFields, sessionsRepo, SESSIONS_KIND } from "./__fixtures__/sessions";
+import { sessionSeal } from "./record-sessions";
+import { parseFrontMatter, recordTextDigest } from "./records";
+import { queryRecords } from "./records-cli";
+import { closeRecord } from "./records-close";
+import closeSchema from "./records-close.schema.json";
+import { queryRecordsSince, type RecordsSinceDocument } from "./records-since";
+import sinceSchema from "./records-since.schema.json";
+import { amendRecord, newRecord, reviewRecord } from "./records-write";
+import newSchema from "./records-new.schema.json";
+import reviewSchema from "./records-review.schema.json";
+
+afterAll(cleanScratch);
+
+const close = contract(closeSchema);
+const since = contract(sinceSchema);
+const review = contract(reviewSchema);
+const created = contract(newSchema);
+
+const code = (doc: object) => ("error" in doc ? (doc as { error: { code: string } }).error.code : "ok");
+const HEX = /^[0-9a-f]{40}$/;
+
+/** The reference fixture with a declaration, committed. */
+function declared(): string {
+  const root = sessionsRepo();
+  declareSessions(root);
+  commitAll(root, "declare");
+  return root;
+}
+
+function front(root: string, path: string): Record<string, unknown> {
+  const fm = parseFrontMatter(readFileSync(join(root, path), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+}
+
+/** Open S-0002 through records new, and commit it. */
+async function opened(root: string): Promise<{ path: string; head: string }> {
+  const head = git(root, "rev-parse", "HEAD");
+  const doc = await newRecord({ kind: SESSIONS_KIND, fields: newSessionFields(), cwd: root });
+  created.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  expect(doc.id).toBe("S-0002");
+  commitAll(root, "open S-0002");
+  return { path: doc.path, head };
+}
+
+async function sessions(root: string) {
+  const doc = await queryRecords({ kind: SESSIONS_KIND, cwd: root });
+  if ("error" in doc) throw new Error(doc.error.message);
+  return doc;
+}
+
+describe("opening revisions (#2693)", () => {
+  test("records new on a session kind writes opened_rev, the commit HEAD names", async () => {
+    const root = declared();
+    const { path, head } = await opened(root);
+    expect(front(root, path).opened_rev).toBe(head);
+    expect((await sessions(root)).records.find((r) => r.id === "S-0002")).toMatchObject({ state: "open", valid: true });
+  });
+
+  test("before the first commit it is null, and the next amend fills it", async () => {
+    const root = scratchDir("chant-sessions-nocommit-");
+    for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
+    declareSessions(root);
+    git(root, "init", "-q");
+    const doc = await newRecord({ kind: SESSIONS_KIND, fields: newSessionFields(), cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(front(root, doc.path).opened_rev).toBeNull();
+    const head = commitAll(root, "first");
+    const amended = await amendRecord({ kind: SESSIONS_KIND, id: "S-0002", fields: "{}", cwd: root });
+    expect(amended).toMatchObject({ changed: ["opened_rev"] });
+    expect(front(root, doc.path).opened_rev).toBe(head);
+  });
+
+  test("a caller can't set the opening or closing revision", async () => {
+    const root = declared();
+    expect(code(await newRecord({ kind: SESSIONS_KIND, fields: newSessionFields({ opened_rev: "a".repeat(40) }), cwd: root }))).toBe("write-input-invalid");
+    await opened(root);
+    expect(code(await amendRecord({ kind: SESSIONS_KIND, id: "S-0002", fields: JSON.stringify({ opened_rev: "b".repeat(40) }), cwd: root }))).toBe("write-input-invalid");
+    expect(code(await amendRecord({ kind: SESSIONS_KIND, id: "S-0002", fields: JSON.stringify({ closed_rev: "b".repeat(40) }), cwd: root }))).toBe("write-input-invalid");
+  });
+});
+
+describe("records close (#2693)", () => {
+  test("sets the state, the close time, the closing revision and the seal in one write, and the session reads back sealed", async () => {
+    const root = declared();
+    const { path } = await opened(root);
+    const head = git(root, "rev-parse", "HEAD");
+    const dry = await closeRecord({ kind: SESSIONS_KIND, id: "S-0002", dryRun: true, cwd: root, now: new Date("2026-09-25T10:30:00.123Z") });
+    close.expectValid(dry);
+    expect(dry).toMatchObject({ dryRun: true, closedRev: head, text: expect.stringContaining('state: "closed"') });
+    expect(front(root, path).state).toBe("open");
+
+    const doc = await closeRecord({ kind: SESSIONS_KIND, id: "S-0002", cwd: root, now: new Date("2026-09-25T10:30:00.123Z") });
+    close.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.changed.sort()).toEqual(["closed", "closed_digest", "closed_rev", "state"]);
+    const fm = front(root, path);
+    expect(fm).toMatchObject({ state: "closed", closed: "2026-09-25T10:30:00Z", closed_rev: head, opened_rev: expect.stringMatching(HEX) });
+    const text = readFileSync(join(root, path), "utf-8");
+    expect(fm.closed_digest).toBe(sessionSeal(text, "closed_digest"));
+    expect(doc.seal).toEqual({ field: "closed_digest", digest: fm.closed_digest });
+    expect((await sessions(root)).records.find((r) => r.id === "S-0002")).toMatchObject({ state: "closed", valid: true, reasons: [] });
+  });
+
+  test("refuses a closed session, an unknown id and a verdict naming a record the subjects lack", async () => {
+    const root = declared();
+    const s1 = await closeRecord({ kind: SESSIONS_KIND, id: "S-0001", cwd: root });
+    close.expectValid(s1);
+    expect(code(s1)).toBe("record-closed");
+    expect(code(await closeRecord({ kind: SESSIONS_KIND, id: "S-0404", cwd: root }))).toBe("record-not-found");
+    expect(code(await closeRecord({ kind: DECISIONS_KIND, id: "ref-001", cwd: root }))).toBe("write-usage-invalid");
+    await opened(root);
+    const file = join(root, "design", "sessions", "S-0002-second-walk.md");
+    writeFileSync(file, readFileSync(file, "utf-8").replace("verdicts: []", 'verdicts:\n  - record: "ref-999"\n    principal: "alice"\n    verdict: "agree"'));
+    const before = readFileSync(file, "utf-8");
+    const bad = await closeRecord({ kind: SESSIONS_KIND, id: "S-0002", cwd: root });
+    close.expectValid(bad);
+    expect(code(bad)).toBe("session-verdict-unknown-record");
+    expect(readFileSync(file, "utf-8")).toBe(before);
+  });
+
+  test("amend's refusal on a closed session does not advise a supersedes field the session schema lacks", async () => {
+    const root = declared();
+    const doc = await amendRecord({ kind: SESSIONS_KIND, id: "S-0001", fields: JSON.stringify({ title: "x" }), cwd: root });
+    expect(code(doc)).toBe("record-closed");
+    const message = "error" in doc ? doc.error.message : "";
+    expect(message).not.toContain("supersedes");
+    expect(message).toContain("open a new session");
+  });
+});
+
+describe("records review --session (#2693)", () => {
+  test("refuses a session that does not exist and one that is closed, writing nothing", async () => {
+    const root = declared();
+    const decision = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
+    const before = readFileSync(decision, "utf-8");
+    const unknown = await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-9999", cwd: root });
+    review.expectValid(unknown);
+    expect(code(unknown)).toBe("session-unknown");
+    const closed = await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-0001", cwd: root });
+    review.expectValid(closed);
+    expect(code(closed)).toBe("session-not-open");
+    expect(readFileSync(decision, "utf-8")).toBe(before);
+  });
+
+  test("a verdict given in a session shows on both the decision and the session, with the same digest", async () => {
+    const root = declared();
+    const { path } = await opened(root);
+    const decision = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
+    const digest = recordTextDigest(readFileSync(decision, "utf-8"));
+
+    const dry = await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-0002", dryRun: true, cwd: root });
+    review.expectValid(dry);
+    expect(dry).toMatchObject({ session: { id: "S-0002", path, text: expect.stringContaining('principal: "alice"') } });
+    expect(front(root, path).verdicts).toEqual([]);
+
+    const doc = await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-0002", on: "2026-09-25", cwd: root });
+    review.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const verdict = { record: "ref-001", principal: "alice", verdict: "agree", digest };
+    expect(doc.session).toEqual({ id: "S-0002", path, verdict });
+    expect(front(root, "decisions/ref-001-how-the-app-is-deployed.md").reviews).toEqual([{ reviewer: "alice", verdict: "agree", on: "2026-09-25", digest, session: "S-0002" }]);
+    expect(front(root, path).verdicts).toEqual([verdict]);
+
+    const s2 = (await sessions(root)).records.find((r) => r.id === "S-0002")!;
+    expect(s2).toMatchObject({ valid: true, citedBy: [{ id: "ref-001", index: 0, reviewer: "alice", verdict: "agree" }] });
+    expect(s2.data?.verdicts).toEqual([verdict]);
+
+    // The session closes over the verdict, and a later one is refused.
+    close.expectValid(await closeRecord({ kind: SESSIONS_KIND, id: "S-0002", cwd: root }));
+    expect(code(await reviewRecord({ kind: DECISIONS_KIND, id: "ref-002", verdict: "agree", by: "bob", session: "S-0002", cwd: root }))).toBe("session-not-open");
+  });
+});
+
+describe("records --since <session id> (#2693)", () => {
+  async function sinceDoc(q: { kind: string; since: string; at?: string; cwd: string }): Promise<Extract<RecordsSinceDocument, { changes: unknown }>> {
+    const doc = await queryRecordsSince(q);
+    since.expectValid(doc);
+    if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+    return doc;
+  }
+
+  test("an open session compares its opening revision with the working tree, and a closed one its opening and closing revisions", async () => {
+    const root = declared();
+    const { head } = await opened(root);
+    await reviewRecord({ kind: DECISIONS_KIND, id: "ref-001", verdict: "agree", by: "alice", session: "S-0002", on: "2026-09-25", cwd: root });
+
+    const open = await sinceDoc({ kind: DECISIONS_KIND, since: "S-0002", cwd: root });
+    expect(open.since).toBe(head);
+    expect(open.at).toBeNull();
+    expect(open.session).toMatchObject({ id: "S-0002", state: "open", sinceFrom: "opened-rev", atFrom: "working-tree", reasons: [{ code: "since-session-open" }] });
+    expect(open.changes).toEqual([{ change: "verdict", id: "ref-001", principal: "alice", verdict: "agree", index: 0, session: "S-0002" }]);
+
+    // Closed but not committed: closed_rev is HEAD before the close, and the close is only in the working tree.
+    const closing = await closeRecord({ kind: SESSIONS_KIND, id: "S-0002", cwd: root });
+    expect(closing).toMatchObject({ closedRev: git(root, "rev-parse", "HEAD") });
+    expect((await sinceDoc({ kind: DECISIONS_KIND, since: "S-0002", cwd: root })).session).toMatchObject({ state: "closed", atFrom: "working-tree", reasons: [] });
+    const closeCommit = commitAll(root, "the verdict and the close");
+    await reviewRecord({ kind: DECISIONS_KIND, id: "ref-002", verdict: "agree", by: "bob", cwd: root });
+
+    const done = await sinceDoc({ kind: DECISIONS_KIND, since: "S-0002", cwd: root });
+    expect(done).toMatchObject({ since: head, at: closeCommit, session: { state: "closed", sinceFrom: "opened-rev", atFrom: "close-commit", reasons: [] } });
+    // The later review of ref-002 came after the session closed, so it is not listed.
+    expect(done.changes).toEqual([{ change: "verdict", id: "ref-001", principal: "alice", verdict: "agree", index: 0, session: "S-0002" }]);
+    // The session was written after its opening commit, so it is new, with the verdict it produced.
+    const own = await sinceDoc({ kind: SESSIONS_KIND, since: "S-0002", cwd: root });
+    expect(own.changes).toEqual([
+      { change: "new", id: "S-0002", path: "design/sessions/S-0002-second-walk.md", state: "closed" },
+      { change: "verdict", id: "S-0002", principal: "alice", verdict: "agree", index: 0, record: "ref-001" },
+    ]);
+  });
+
+  test("a session without revision fields falls back to its file's history, and an unknown id is since-session-unknown", async () => {
+    const root = declared();
+    const added = git(root, "log", "--diff-filter=A", "--format=%H", "--", "design/sessions/S-0001-first-walk-of-the-reference-decisions.md");
+    const s1 = await sinceDoc({ kind: SESSIONS_KIND, since: "S-0001", cwd: root });
+    expect(s1).toMatchObject({ since: added, at: added, session: { sinceFrom: "history", atFrom: "history" }, changes: [] });
+    const unknown = await queryRecordsSince({ kind: DECISIONS_KIND, since: "S-9999", cwd: root });
+    since.expectValid(unknown);
+    expect(code(unknown)).toBe("since-session-unknown");
+    // An id-shaped value that names a commit, such as a tag, is still read as the commit.
+    git(root, "tag", "v-1");
+    expect((await sinceDoc({ kind: DECISIONS_KIND, since: "v-1", cwd: root })).session).toBeUndefined();
+  });
+
+  test(
+    "through the CLI: close with the declared session kind, and --since <session id> without --kind",
+    async () => {
+      const root = declared();
+      await opened(root);
+      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: root,
+          encoding: "utf-8",
+          env: { ...process.env, NO_COLOR: "1" },
+          timeout: 60_000,
+        });
+      const closed = run("close", "S-0002");
+      expect(closed.status, closed.stderr).toBe(0);
+      close.expectValid(JSON.parse(closed.stdout));
+      const again = run("close", "S-0002");
+      expect(again.status).toBe(1);
+      expect(JSON.parse(again.stdout).error.code).toBe("record-closed");
+      commitAll(root, "close");
+      const set = run("--since", "S-0002", "--json");
+      expect(set.status, set.stderr).toBe(0);
+      const kinds = JSON.parse(set.stdout).kinds as RecordsSinceDocument[];
+      for (const k of kinds) since.expectValid(k);
+      expect(kinds.map((k) => ("session" in k ? k.session?.id : null))).toEqual(["S-0002", "S-0002"]);
+      const text = run("--kind", SESSIONS_KIND, "--since", "S-0002");
+      expect(text.stdout).toContain("session S-0002 (closed)");
+      expect(text.stdout).toContain("S-0002  new, closed");
+    },
+    120_000,
+  );
+});

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

@@ -2,7 +2,7 @@
   "$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`.",
+  "description": "What `chant workspace records --kind <kind file> --since <rev|session id> --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": {
@@ -59,6 +59,7 @@
         },
         "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." },
+        "session": { "$ref": "#/$defs/session" },
         "error": false,
         "changes": {
           "description": "In the order new, removed, state, verdict, supersession, pin, and by id within each.",
@@ -80,6 +81,29 @@
         }
       }
     },
+    "session": {
+      "description": "Added in contract 1 by #2693, with --since <session id> only: the session named, and where since and at came from. since is the commit the session opened at: its opening revision field (the kind's session.openedRev), or, for a session without one, the latest commit that added its file (history). at is the commit that carries the close: the first commit after its closing revision field (session.closedRev, HEAD when records close wrote the close) that changed the session file (close-commit), or, for a session without that field, the last commit that changed its file (history); --at overrides it (at). An open session, or one whose close is not committed yet, is compared with the working tree (working-tree), and an open one carries since-session-open.",
+      "type": "object",
+      "required": ["id", "path", "state", "sinceFrom", "atFrom", "reasons"],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "The session file, from the repository root, with / separators." },
+        "state": { "type": ["string", "null"] },
+        "sinceFrom": { "enum": ["opened-rev", "history"] },
+        "atFrom": { "enum": ["close-commit", "history", "at", "working-tree"] },
+        "reasons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code", "message"],
+            "properties": {
+              "code": { "enum": ["since-session-open"] },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "change": {
       "oneOf": [
         { "$ref": "#/$defs/new" },
@@ -180,7 +204,8 @@
                 "location-missing",
                 "not-a-git-repository",
                 "revision-unknown",
-                "since-rev-unknown"
+                "since-rev-unknown",
+                "since-session-unknown"
               ]
             },
             "message": { "type": "string" }

package/src/workspace/records-since.ts

@@ -9,6 +9,18 @@
  *
  * 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.
+ *
+ * `--since <session id>` (#2693) compares the commit a review session
+ * opened at with the commit that carries its close. The first is the
+ * record's opening revision (the kind's `session.openedRev` field). The
+ * record's closing revision (`session.closedRev`) is HEAD when `records
+ * close` wrote the close, before the caller committed it, so the close and
+ * the verdicts committed with it are in the first commit after it that
+ * changed the session file. A session written before chant wrote these
+ * fields falls back to its file's history: the commit that added it and the
+ * last commit that changed it. An open session, or one whose close is not
+ * committed yet, is compared with the working tree, and an open one says so
+ * with `since-session-open`.
  */
 
 import { realpathSync } from "node:fs";
@@ -16,8 +28,9 @@ 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 { readRecordsFor, realpathOr, RECORDS_CONTRACT_VERSION } from "./records-cli";
 import type { ReasonCode } from "./reason-codes";
+import { commitsTouching, findSessionKinds, SESSION_ID } from "./session-kinds";
 
 /** `$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";
@@ -27,9 +40,38 @@ export const RECORDS_SINCE_ERROR_CODES = [
   ...READ_ERROR_CODES,
   /** `--since` names no commit. */
   "since-rev-unknown",
+  /** `--since` has a session id's shape, names no commit, and no session has the id (#2693). */
+  "since-session-unknown",
 ] as const satisfies readonly ReasonCode[];
 export type RecordsSinceErrorCode = (typeof RECORDS_SINCE_ERROR_CODES)[number];
 
+/** Why a session's comparison is not the one between its open and close commits (#2693). Closed. */
+export const RECORDS_SINCE_REASON_CODES = [
+  /** The session is open, so the comparison runs to the working tree. */
+  "since-session-open",
+] as const satisfies readonly ReasonCode[];
+
+/**
+ * The session `--since` named (#2693), and where the two revisions came
+ * from: the record's own fields, or git's history of its file for a session
+ * written before chant wrote them.
+ */
+export interface SinceSession {
+  id: string;
+  /** The session file, from the repository root, with / separators. */
+  path: string;
+  state: string | null;
+  /** Where `since` came from: the session's opening revision field, or the last commit that added its file. */
+  sinceFrom: "opened-rev" | "history";
+  /**
+   * Where `at` came from: the first commit after the closing revision that
+   * changed the session file (the commit carrying the close), the last
+   * commit that changed the file, --at, or the working tree.
+   */
+  atFrom: "close-commit" | "history" | "at" | "working-tree";
+  reasons: { code: (typeof RECORDS_SINCE_REASON_CODES)[number]; message: string }[];
+}
+
 /** 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];
@@ -52,6 +94,8 @@ export type RecordsSinceDocument =
       kind: { name: string; schema: string; file: string };
       since: string;
       at: string | null;
+      /** With `--since <session id>` only. */
+      session?: SinceSession;
       changes: SinceChange[];
       summary: Record<SinceChangeKind, number>;
     }
@@ -81,8 +125,10 @@ export async function queryRecordsSince(query: RecordsSinceQuery): Promise<Recor
     error: { code, message },
   });
   try {
-    const since = resolveSince(query.cwd, query.since);
-    const after = await readRecordsFor({ kind: query.kind, at: query.at, cwd: query.cwd });
+    const found = await findSinceSession(query);
+    const since = resolveSince(query.cwd, found ? found.since : query.since, found?.session.id);
+    const at = found ? (found.at ?? undefined) : query.at;
+    const after = await readRecordsFor({ kind: query.kind, at, cwd: query.cwd });
     let before: RecordEntry[];
     try {
       before = (await readRecordsFor({ kind: query.kind, at: since, cwd: query.cwd })).result.records;
@@ -99,6 +145,7 @@ export async function queryRecordsSince(query: RecordsSinceQuery): Promise<Recor
       kind: kindView(after.loaded, after.root),
       since,
       at: after.at,
+      ...(found ? { session: found.session } : {}),
       changes,
       summary,
     };
@@ -113,8 +160,71 @@ function kindView(loaded: LoadedRecordKind, root: string): { name: string; schem
   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 {
+/**
+ * The session `query.since` names, with the revisions to compare, or null
+ * when it names none and is to be read as a revision. It is looked up only
+ * in a git repository, when it has a session id's shape, in the kind read
+ * when that is a session kind and in the session kinds the declaration
+ * names. An id-shaped value that is neither a session nor a commit is
+ * `since-session-unknown`.
+ */
+async function findSinceSession(query: RecordsSinceQuery): Promise<{ since: string; at: string | null; session: SinceSession } | null> {
+  const top = gitRoot(realpathOr(query.cwd));
+  if (!top || !SESSION_ID.test(query.since)) return null;
+  const kinds = await findSessionKinds(query.cwd, [query.kind]);
+  for (const k of kinds) {
+    let records: RecordEntry[];
+    try {
+      records = (await readRecordsFor({ kind: k.file, cwd: query.cwd })).result.records;
+    } catch (err) {
+      if (err instanceof RecordReadError) continue;
+      throw err;
+    }
+    const s = records.find((r) => r.id === query.since);
+    if (!s) continue;
+    const decl = k.kind.session!;
+    const field = (f: string | undefined): string | null => (f !== undefined && typeof s.data?.[f] === "string" ? (s.data[f] as string) : null);
+    const closed = s.state !== null && (k.kind.closedStates ?? []).includes(s.state);
+    const session: SinceSession = { id: s.id!, path: s.path, state: s.state, sinceFrom: "opened-rev", atFrom: "working-tree", reasons: [] };
+    let since = field(decl.openedRev);
+    if (since === null) {
+      since = commitsTouching(top, s.path, ["--diff-filter=A"])[0] ?? null;
+      session.sinceFrom = "history";
+      if (since === null) {
+        throw new SinceError("since-rev-unknown", `session ${s.id} (${s.path}) names no commit it opened at${decl.openedRev ? ` in ${decl.openedRev}` : ""}, and no commit added its file`);
+      }
+    }
+    let at: string | null = null;
+    if (query.at !== undefined) {
+      at = query.at;
+      session.atFrom = "at";
+    } else if (closed) {
+      const closedRev = field(decl.closedRev);
+      if (closedRev !== null && /^[0-9a-f]{40,64}$/.test(closedRev)) {
+        // The oldest of these is the commit that carried the close. None yet means the close is only in the working tree.
+        at = commitsTouching(top, s.path, [`${closedRev}..HEAD`]).slice(-1)[0] ?? null;
+        session.atFrom = at === null ? "working-tree" : "close-commit";
+      } else {
+        at = commitsTouching(top, s.path, ["-1"])[0] ?? null;
+        session.atFrom = at === null ? "working-tree" : "history";
+      }
+    } else {
+      session.reasons.push({ code: "since-session-open", message: `session ${s.id} is ${s.state ?? "not closed"}, so it has no closing revision, and the comparison runs to the working tree` });
+    }
+    return { since, at, session };
+  }
+  try {
+    resolveRevision(top, query.since);
+    return null;
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+  }
+  if (kinds.length === 0) return null;
+  throw new SinceError("since-session-unknown", `--since ${query.since} names no commit, and no ${[...new Set(kinds.map((k) => k.kind.name))].join(" or ")} record has that id`);
+}
+
+/** The full commit id `rev` names, from the repository holding `cwd`; `session` names the session it came from. */
+function resolveSince(cwd: string, rev: string, session?: string): string {
   let dir = cwd;
   try {
     dir = realpathSync(cwd);
@@ -127,7 +237,7 @@ function resolveSince(cwd: string, rev: string): string {
     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 new SinceError("since-rev-unknown", session ? `session ${session} names ${rev}, which is no commit in this repository` : `--since ${rev} names no commit in this repository`);
     }
     throw err;
   }
@@ -252,6 +362,10 @@ export function formatSince(doc: Extract<RecordsSinceDocument, { changes: SinceC
     }
   });
   const s = doc.summary;
+  if (doc.session) {
+    const x = doc.session;
+    lines.unshift(`session ${x.id} (${x.state ?? "no state"}): opened at ${doc.since.slice(0, 8)} (${x.sinceFrom}), compared to ${doc.at ? `${doc.at.slice(0, 8)} (${x.atFrom})` : "the working tree"}`);
+  }
   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`,
   );