@intentius/chant 0.87.0 → 0.88.0

package/src/workspace/records-close.ts

@@ -0,0 +1,129 @@
+/**
+ * `chant workspace records close <session id>` (#2693): close a review
+ * session in one write. It sets the session's state to its kind's closed
+ * state, the time it closed and the commit it closed at (the fields the
+ * kind's `session` block names in `closedOn` and `closedRev`), and then the
+ * seal by chant's rule ({@link sessionSeal}), so a UI never computes a seal.
+ *
+ * Like `new`, `amend` and `review`, it reads the records again with the file
+ * in place and writes only when the session comes back valid: a verdict
+ * naming a record the subjects lack is refused with
+ * `session-verdict-unknown-record`. A session already closed is
+ * `record-closed`. It writes one file or none and never commits.
+ */
+
+import { writeFileSync } from "node:fs";
+import type { ReasonCode } from "./reason-codes";
+import { sessionSeal } from "./record-sessions";
+import { RECORD_REASON_CODES } from "./records";
+import {
+  abs,
+  failure,
+  findRecord,
+  LOAD_ERROR_CODES,
+  open,
+  openedRevFill,
+  readAll,
+  RECORDS_WRITE_CONTRACT_VERSION,
+  RecordWriteError,
+  replaceFields,
+  stableJson,
+  validateWrite,
+  type WriteFailure,
+  type WriteResult,
+} from "./records-write";
+import { headCommit } from "./session-kinds";
+
+export const RECORDS_CLOSE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json";
+
+/** Why `records close` wrote nothing. Closed. */
+export const CLOSE_ERROR_CODES = [
+  ...LOAD_ERROR_CODES,
+  "write-usage-invalid",
+  "record-not-found",
+  "record-closed",
+  ...RECORD_REASON_CODES,
+] as const satisfies readonly ReasonCode[];
+export type CloseErrorCode = (typeof CLOSE_ERROR_CODES)[number];
+
+export type CloseDocument =
+  | (WriteResult & {
+      /** The top-level fields the close set, in the order written. */
+      changed: string[];
+      /** The seal field and the digest written in it. */
+      seal: { field: string; digest: string };
+      /** The commit HEAD named at the close, or null outside git or before the first commit. */
+      closedRev: string | null;
+    })
+  | WriteFailure<CloseErrorCode>;
+
+export interface CloseRecordOptions {
+  /** The session kind file, resolved against `cwd`. */
+  kind: string;
+  id: string;
+  dryRun?: boolean;
+  cwd: string;
+  /** The close time. Defaults to now. */
+  now?: Date;
+}
+
+/** An ISO 8601 time in UTC to the second, as the reference session schema's dateTime takes it. */
+function isoSeconds(d: Date): string {
+  return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** `records close`: close one open session and seal it. */
+export async function closeRecord(opts: CloseRecordOptions): Promise<CloseDocument> {
+  try {
+    const o = await open(opts.kind, opts.cwd);
+    const { kind } = o.loaded;
+    const decl = kind.session;
+    if (!decl || kind.stateField === undefined) {
+      throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind has no session block, and records close closes a review session; amend sets the state of other records`);
+    }
+    const closedState = (kind.closedStates ?? [])[0];
+    if (closedState === undefined) throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind lists no closed state, so a session of it can't close`);
+    const before = await readAll(o, o.source);
+    const target = findRecord(before, opts.id, kind.name);
+    if (target.state !== null && (kind.closedStates ?? []).includes(target.state)) {
+      throw new RecordWriteError("record-closed", `${opts.id} is already ${target.state}, and a closed session is sealed and stays as it is`);
+    }
+    if (target.data === null) throw new RecordWriteError("record-unparseable", `${target.path} can't be read, so it can't be closed`);
+    const old = target.data;
+    const closedRev = headCommit(o.root);
+    const set: Record<string, unknown> = {
+      ...openedRevFill(kind, old, o.root),
+      [kind.stateField]: closedState,
+      ...(decl.closedOn ? { [decl.closedOn]: isoSeconds(opts.now ?? new Date()) } : {}),
+      ...(decl.closedRev ? { [decl.closedRev]: closedRev } : {}),
+    };
+    // The seal line is written last, into text that already holds everything else, so the seal is the digest of the file without it.
+    const merged = { ...old, ...set };
+    delete merged[decl.seal];
+    const unsealed = replaceFields(o.source.read(target.path), set, merged);
+    if (unsealed === undefined) throw new RecordWriteError("record-unparseable", `${target.path}: its fields can't be rewritten in place without changing the rest of the file`);
+    const digest = sessionSeal(unsealed, decl.seal, kind.format);
+    const text = replaceFields(unsealed, { [decl.seal]: digest }, { ...merged, [decl.seal]: digest });
+    if (text === undefined || sessionSeal(text, decl.seal, kind.format) !== digest) {
+      throw new RecordWriteError("record-unparseable", `${target.path}: the ${decl.seal} line can't be added without changing the text it seals`);
+    }
+    const warnings = await validateWrite(o, before, target.path, text);
+    if (!opts.dryRun) writeFileSync(abs(o, target.path), text);
+    const written = { ...merged, [decl.seal]: digest };
+    return {
+      $schema: RECORDS_CLOSE_SCHEMA_ID,
+      contract: RECORDS_WRITE_CONTRACT_VERSION,
+      kind: o.view,
+      path: target.path,
+      id: opts.id,
+      changed: Object.keys(written).filter((k) => stableJson(old[k]) !== stableJson(written[k])),
+      seal: { field: decl.seal, digest },
+      closedRev,
+      dryRun: !!opts.dryRun,
+      warnings,
+      ...(opts.dryRun ? { text } : {}),
+    };
+  } catch (err) {
+    return failure<CloseErrorCode>(RECORDS_CLOSE_SCHEMA_ID, err);
+  }
+}

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

@@ -11,7 +11,7 @@ import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import { afterAll, describe, expect, test } from "vitest";
 import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
-import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, recordTextDigest, REVIEW_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, recordTextDigest, REVIEW_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
@@ -148,8 +148,9 @@ describe("records output schema", () => {
   });
 
   test("lists exactly the warning codes the code can return", () => {
-    // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES]);
+    // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
+    // and records adds record-unattested for an author seal under a signers file at base (#2688).
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...SEAL_WARNING_CODES]);
   });
 
   test("every failure validates with its code", async () => {

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

@@ -61,6 +61,30 @@
           "type": "string",
           "description": "The record's id."
         },
+        "seal": {
+          "type": "object",
+          "description": "Added in contract 1 by #2688. With --sign only: the author seal written into the record's top-level seal field, an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<author>\\n<state>, in the ssh-keygen namespace chant-record. The author is the kind's reviews.decider field (decided_by for decisions), and the digest is the record's digest by the digest rule, which leaves the seal field out. The write does not check the key against the signers file; chant workspace records reports whether the seal verifies.",
+          "required": [
+            "signer",
+            "key",
+            "signature"
+          ],
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "The record's author, as its reviews.decider field names them."
+            },
+            "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."
+            }
+          }
+        },
         "dryRun": {
           "type": "boolean",
           "description": "True when --dry-run was given and nothing was written."
@@ -136,6 +160,7 @@
                 "record-id-taken",
                 "record-id-unallocatable",
                 "record-path-unmatched",
+                "record-sign-failed",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

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"
@@ -101,7 +101,7 @@
             "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",
@@ -144,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
       }
     },
@@ -205,6 +256,8 @@
                 "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" }