@intentius/chant 0.86.0 → 0.88.0

package/src/workspace/records-write.ts

@@ -14,11 +14,17 @@
  *
  * Every command writes one file or none, never commits, and prints one JSON
  * document with a closed error code on refusal. `--dry-run` prints the
- * document and the text it would write, and writes nothing.
+ * document and the text it would write, and writes nothing. The exception is
+ * `review --session` (#2693), which appends the verdict to the open session
+ * as well, after checking both files, so the two lists never differ.
+ * `records close` is in `records-close.ts`.
+ *
+ * `new --sign` and `amend --sign` seal the record's author (#2688), and
+ * `review --sign` seals a verdict (#2687): see `trust/seal.ts`.
  */
 
 import { readFileSync, statSync, writeFileSync } from "node:fs";
-import { join, posix, relative, resolve } from "node:path";
+import { dirname, join, posix, relative, resolve } from "node:path";
 import type { CommandContext } from "../cli/registry";
 import type { ReasonCode } from "./reason-codes";
 import { gitRoot, workingTreeSource, type RecordSource } from "./record-source";
@@ -28,6 +34,8 @@ import {
   readRecords,
   RECORD_REASON_CODES,
   RecordReadError,
+  RECORD_SEAL_FIELD,
+  digestFields,
   recordTextDigest,
   type LoadedRecordKind,
   type RecordEntry,
@@ -35,6 +43,7 @@ import {
 } from "./records";
 import { declaredKindFiles, pinRoot, realpathOr } from "./records-cli";
 import { WorkspaceReadError } from "./declaration";
+import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
 import { workingTree } from "./tree";
 
 // ── Contract ─────────────────────────────────────────────────────────────────
@@ -47,7 +56,7 @@ export const RECORDS_AMEND_SCHEMA_ID = "https://intentius.io/chant/schemas/works
 export const RECORDS_REVIEW_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json";
 
 /** Loading the kind and reading its records, as `records` reads them. */
-const LOAD_ERROR_CODES = ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing"] as const;
+export const LOAD_ERROR_CODES = ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing"] as const;
 
 /** Why `records new` wrote nothing. Closed: a reader may switch on it. */
 export const NEW_ERROR_CODES = [
@@ -57,6 +66,7 @@ export const NEW_ERROR_CODES = [
   "record-id-taken",
   "record-id-unallocatable",
   "record-path-unmatched",
+  "record-sign-failed",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -69,6 +79,7 @@ export const AMEND_ERROR_CODES = [
   "amend-id-immutable",
   "record-closed",
   "amend-supersede-instead",
+  "record-sign-failed",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -80,18 +91,21 @@ export const REVIEW_ERROR_CODES = [
   "review-unsupported",
   "record-closed",
   "review-note-required",
+  "review-sign-failed",
+  "session-unknown",
+  "session-not-open",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
 export type NewErrorCode = (typeof NEW_ERROR_CODES)[number];
 export type AmendErrorCode = (typeof AMEND_ERROR_CODES)[number];
 export type ReviewErrorCode = (typeof REVIEW_ERROR_CODES)[number];
-type WriteErrorCode = NewErrorCode | AmendErrorCode | ReviewErrorCode;
+type WriteErrorCode = NewErrorCode | AmendErrorCode | ReviewErrorCode | import("./records-close").CloseErrorCode;
 
 export const VERDICTS = ["agree", "dissent", "abstain"] as const;
 export type Verdict = (typeof VERDICTS)[number];
 
-class RecordWriteError extends Error {
+export class RecordWriteError extends Error {
   constructor(
     readonly code: WriteErrorCode,
     message: string,
@@ -101,14 +115,14 @@ class RecordWriteError extends Error {
   }
 }
 
-interface KindView {
+export interface KindView {
   name: string;
   schema: string;
   file: string;
 }
 
 /** What every write result carries. */
-interface WriteResult {
+export interface WriteResult {
   $schema: string;
   contract: number;
   kind: KindView;
@@ -123,15 +137,32 @@ interface WriteResult {
   text?: string;
 }
 
-interface WriteFailure<C> {
+export interface WriteFailure<C> {
   $schema: string;
   contract: number;
   error: { code: C; message: string };
 }
 
-export type NewDocument = WriteResult | WriteFailure<NewErrorCode>;
-export type AmendDocument = (WriteResult & { changed: string[] }) | WriteFailure<AmendErrorCode>;
-export type ReviewDocument = (WriteResult & { review: Record<string, unknown> }) | WriteFailure<ReviewErrorCode>;
+/** A record's author seal as `new` and `amend` write it with `--sign` (#2688). */
+export interface AuthorSeal {
+  signer: string;
+  key: string;
+  signature: string;
+}
+
+export type NewDocument = (WriteResult & { seal?: AuthorSeal }) | WriteFailure<NewErrorCode>;
+export type AmendDocument = (WriteResult & { changed: string[]; seal?: AuthorSeal; sealDropped?: string }) | WriteFailure<AmendErrorCode>;
+/** With --session (#2693): the session the verdict was also appended to. */
+export interface ReviewSession {
+  id: string;
+  path: string;
+  /** The entry appended to the session's verdicts list. */
+  verdict: Record<string, unknown>;
+  /** With --dry-run, the whole text the session file would hold. */
+  text?: string;
+}
+
+export type ReviewDocument = (WriteResult & { review: Record<string, unknown>; session?: ReviewSession }) | WriteFailure<ReviewErrorCode>;
 
 // ── Rendering ────────────────────────────────────────────────────────────────
 
@@ -195,7 +226,7 @@ function bodyOf(text: string): string {
 }
 
 /** JSON with object keys sorted, for comparing two values whatever their key order. */
-function stableJson(value: unknown): string {
+export function stableJson(value: unknown): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
   const obj = value as Record<string, unknown>;
@@ -241,6 +272,31 @@ export function replaceFields(text: string, set: Record<string, unknown>, expect
   return back.ok && stableJson(back.value) === stableJson(expected) ? out : undefined;
 }
 
+/**
+ * `text` with the top-level field `key` removed: its key line and the lines
+ * after it that {@link replaceFields} counts as its block, less the blank
+ * lines ending it, which stay. Returns undefined when the result does not
+ * read back as `expected`.
+ */
+export function removeField(text: string, key: string, expected: Record<string, unknown>): string | undefined {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  if (lines[0] !== "---") return undefined;
+  const close = lines.indexOf("---", 1);
+  if (close < 0) return undefined;
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const starts = new RegExp(`^(?:${k}|"${k}"|'${k}')[ \\t]*:(?:[ \\t]|$)`);
+  const at = lines.findIndex((l, i) => i > 0 && i < close && starts.test(l));
+  if (at >= 0) {
+    let end = at;
+    while (end + 1 < close && /^(?:$|[ \t#-])/.test(lines[end + 1])) end++;
+    while (end > at && lines[end] === "") end--;
+    lines.splice(at, end - at + 1);
+  }
+  const out = lines.join("\n");
+  const back = parseFrontMatter(out);
+  return back.ok && stableJson(back.value) === stableJson(expected) ? out : undefined;
+}
+
 /** A file-name slug from a title, as `scripts/import-decisions.mjs` makes one. */
 export function slug(title: string): string {
   return title
@@ -254,7 +310,7 @@ export function slug(title: string): string {
 
 // ── Shared steps ─────────────────────────────────────────────────────────────
 
-interface Opened {
+export interface Opened {
   loaded: LoadedRecordKind;
   root: string;
   /** Where pinned paths resolve, from `root`. */
@@ -265,7 +321,7 @@ interface Opened {
   dirRel: string;
 }
 
-async function open(kind: string, cwd: string): Promise<Opened> {
+export async function open(kind: string, cwd: string): Promise<Opened> {
   const real = realpathOr(cwd);
   const root = gitRoot(real) ?? real;
   const loaded = await loadRecordKind(kind, real);
@@ -286,13 +342,23 @@ async function open(kind: string, cwd: string): Promise<Opened> {
   };
 }
 
-async function readAll(o: Opened, source: RecordSource): Promise<RecordEntry[]> {
+/**
+ * The kind's records as `records` reads them from `source`. A session kind's
+ * subject records are read from the same source (#2693), so a write is
+ * refused for a verdict naming a record that does not exist.
+ */
+export async function readAll(o: Opened, source: RecordSource): Promise<RecordEntry[]> {
   const assets = workingTree(o.workspaceRoot === "." ? o.root : join(o.root, ...o.workspaceRoot.split("/")));
-  return (await readRecords(o.loaded, { root: o.root, source, assets })).records;
+  let subjects: { records: RecordEntry[]; reviews: string } | undefined;
+  if (o.loaded.kind.session) {
+    const subjectKind = await loadRecordKind(resolve(dirname(o.loaded.file), o.loaded.kind.session.subjects.kind), o.root);
+    subjects = { records: (await readRecords(subjectKind, { root: o.root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" };
+  }
+  return (await readRecords(o.loaded, { root: o.root, source, assets, ...(subjects ? { subjects } : {}) })).records;
 }
 
 /** `base` with the file at `path` holding `text`, added to its directory when new. */
-function overlay(base: RecordSource, path: string, text: string): RecordSource {
+export function overlay(base: RecordSource, path: string, text: string): RecordSource {
   const dir = posix.dirname(path);
   const name = posix.basename(path);
   return {
@@ -312,12 +378,13 @@ function overlay(base: RecordSource, path: string, text: string): RecordSource {
 }
 
 /**
- * Read the records again with `text` at `path`. The written record must come
+ * Read the records again with `text` at `path`, over `base` (the working
+ * tree unless another write goes with this one). The written record must come
  * back with no reason, and no other record may gain one. Returns the written
  * record's warnings.
  */
-async function validateWrite(o: Opened, before: RecordEntry[], path: string, text: string): Promise<RecordWarning[]> {
-  const after = await readAll(o, overlay(o.source, path, text));
+export async function validateWrite(o: Opened, before: RecordEntry[], path: string, text: string, base: RecordSource = o.source): Promise<RecordWarning[]> {
+  const after = await readAll(o, overlay(base, path, text));
   const written = after.find((e) => e.path === path);
   if (!written) throw new RecordWriteError("record-path-unmatched", `${path} is not a file the kind ${o.view.name} reads`);
   if (written.reasons.length > 0) {
@@ -332,7 +399,7 @@ async function validateWrite(o: Opened, before: RecordEntry[], path: string, tex
   return written.warnings;
 }
 
-function findRecord(entries: RecordEntry[], id: string, kind: string): RecordEntry & { data: Record<string, unknown> } {
+export function findRecord(entries: RecordEntry[], id: string, kind: string): RecordEntry & { data: Record<string, unknown> } {
   const hits = entries.filter((e) => e.id === id);
   if (hits.length === 0) throw new RecordWriteError("record-not-found", `no ${kind} record has id ${id}`);
   if (hits.length > 1) {
@@ -354,8 +421,97 @@ function parseFields(text: string, flag: string): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
+/** Refuse fields that set the author seal by hand: only --sign writes it (#2688). */
+function refuseSealField(o: Opened, fields: Record<string, unknown>, flag: string): void {
+  if (o.loaded.kind.reviews && RECORD_SEAL_FIELD in fields) {
+    throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${RECORD_SEAL_FIELD}, and only --sign writes a record's seal`);
+  }
+}
+
+/**
+ * Refuse fields that set a session's opening or closing revision by hand
+ * (#2693): `new` writes the first from HEAD and `close` the second. A field
+ * given with the value the record already holds is not a change, so an
+ * amendment that sends the whole record back is taken.
+ */
+function refuseRevisionFields(kind: LoadedRecordKind["kind"], fields: Record<string, unknown>, old: Record<string, unknown>, flag: string): void {
+  for (const f of [kind.session?.openedRev, kind.session?.closedRev]) {
+    if (f === undefined || !(f in fields) || (f in old && stableJson(old[f]) === stableJson(fields[f]))) continue;
+    throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f}, and chant writes it: records new writes the commit a session opened at, and records close the one it closed at`);
+  }
+}
+
+/**
+ * `text`, the record `data` holds, with its author sealed (#2688): an ssh
+ * signature by the key `sign` names over the record id, the digest of
+ * `text`, the author (the kind's `reviews.decider` field) and the state, in
+ * the `chant-record` namespace. The seal goes in the top-level `seal` field,
+ * replacing one already there, or added at the end of the front matter. The
+ * digest leaves that field out, so it is the same before and after.
+ */
+async function sealAuthor(o: Opened, text: string, data: Record<string, unknown>, id: string, sign: string | true, cwd: string): Promise<{ text: string; seal: AuthorSeal }> {
+  const { kind } = o.loaded;
+  if (!kind.reviews) {
+    throw new RecordWriteError(
+      "write-usage-invalid",
+      `--sign seals a record's author, named by the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`,
+    );
+  }
+  const field = kind.reviews.decider;
+  const author = data[field];
+  if (typeof author !== "string" || author.trim() === "") {
+    throw new RecordWriteError("record-sign-failed", `${id} names no ${field}, so there is no author to seal: set ${field}, then seal it with records amend ${id} --sign`);
+  }
+  const state = kind.stateField !== undefined && typeof data[kind.stateField] === "string" ? (data[kind.stateField] as string) : null;
+  const digest = recordTextDigest(text, digestFields(kind), kind.format);
+  const { resolveSigningKey, sealRecord, SealError } = await import("./trust/seal");
+  let seal: AuthorSeal;
+  try {
+    const key = resolveSigningKey(sign, cwd);
+    try {
+      seal = { ...sealRecord(key.file, { record: id, digest, author, state }) };
+    } finally {
+      key.cleanup();
+    }
+  } catch (err) {
+    if (err instanceof SealError) throw new RecordWriteError("record-sign-failed", err.message);
+    throw err;
+  }
+  const sealed = replaceFields(text, { [RECORD_SEAL_FIELD]: seal }, { ...data, [RECORD_SEAL_FIELD]: seal });
+  if (sealed === undefined) throw new RecordWriteError("record-unparseable", `the ${RECORD_SEAL_FIELD} field can't be written into ${id} without changing the rest of the file`);
+  if (recordTextDigest(sealed, digestFields(kind), kind.format) !== digest) {
+    throw new Error(`sealing ${id} moved its digest; the seal block and the digest rule disagree`);
+  }
+  return { text: sealed, seal };
+}
+
+/**
+ * What to do instead of changing a closed record. A supersedes link is
+ * advice only when the kind's schema has the field: the session schema has
+ * none, so a closed session is followed by a new session (#2693).
+ */
+function closedAdvice(o: Opened, id: string, supersede: string): string {
+  const { kind, schema } = o.loaded;
+  if (kind.session) return `A closed session is sealed and stays as it is: open a new session for what follows, with chant workspace records new ${o.view.file}`;
+  const props = schema.properties !== null && typeof schema.properties === "object" ? (schema.properties as Record<string, unknown>) : {};
+  if (kind.supersedes && (schema.additionalProperties !== false || kind.supersedes.field in props)) return `Write a new record that supersedes it: ${supersede}`;
+  return `Write a new record in its place with chant workspace records new ${o.view.file}; the ${kind.name} schema has no field that links it to ${id}`;
+}
+
+/**
+ * The opening revision a session lacks (#2693): when the kind names one and
+ * the record holds null there, HEAD, once the repository has a commit.
+ * Every write to the session fills it.
+ */
+export function openedRevFill(kind: LoadedRecordKind["kind"], data: Record<string, unknown>, root: string): Record<string, unknown> {
+  const f = kind.session?.openedRev;
+  if (f === undefined || data[f] !== null) return {};
+  const head = headCommit(root);
+  return head === null ? {} : { [f]: head };
+}
+
 /** Keys in the schema's `required` order, then its `properties` order, then the rest as given. */
-function schemaOrder(data: Record<string, unknown>, schema: Record<string, unknown>): string[] {
+export function schemaOrder(data: Record<string, unknown>, schema: Record<string, unknown>): string[] {
   const required = Array.isArray(schema.required) ? (schema.required as unknown[]).filter((k): k is string => typeof k === "string") : [];
   const props = schema.properties !== null && typeof schema.properties === "object" ? Object.keys(schema.properties as object) : [];
   const order = [...new Set([...required, ...props])];
@@ -363,11 +519,11 @@ function schemaOrder(data: Record<string, unknown>, schema: Record<string, unkno
   return [...order.filter((k) => keys.includes(k)), ...keys.filter((k) => !order.includes(k))];
 }
 
-function pick(data: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+export function pick(data: Record<string, unknown>, keys: string[]): Record<string, unknown> {
   return Object.fromEntries(keys.map((k) => [k, data[k]]));
 }
 
-function abs(o: Opened, path: string): string {
+export function abs(o: Opened, path: string): string {
   return join(o.root, ...path.split("/"));
 }
 
@@ -375,7 +531,7 @@ function today(): string {
   return new Date().toISOString().slice(0, 10);
 }
 
-function failure<C>(schema: string, err: unknown): WriteFailure<C> {
+export function failure<C>(schema: string, err: unknown): WriteFailure<C> {
   if (err instanceof RecordWriteError || err instanceof RecordReadError) {
     return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code as C, message: err.message } };
   }
@@ -430,9 +586,15 @@ export interface NewRecordOptions {
   prefix?: string;
   dryRun?: boolean;
   cwd: string;
+  /**
+   * Seal the record's author (#2688): a key file, resolved against `cwd`, or
+   * true for git's `user.signingkey`. The author is the kind's
+   * `reviews.decider` field, which the fields must set.
+   */
+  sign?: string | true;
 }
 
-/** `records new`: write one new record from validated fields. */
+/** `records new`: write one new record from validated fields, sealed by its author with `sign`. */
 export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
   try {
     if (opts.prefix !== undefined && !/^[A-Za-z][A-Za-z0-9]*$/.test(opts.prefix)) {
@@ -441,6 +603,8 @@ export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
     const fields = parseFields(opts.fields, "--from");
     const o = await open(opts.kind, opts.cwd);
     const { kind, schema } = o.loaded;
+    refuseSealField(o, fields, "--from");
+    refuseRevisionFields(kind, fields, {}, "--from");
     const idField = kind.idField!;
     const before = await readAll(o, o.source);
     const given = fields[idField];
@@ -453,7 +617,10 @@ export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
       if (taken) throw new RecordWriteError("record-id-taken", `id ${given} is already used by ${taken.path}; ids are never reused, so leave ${idField} out to have the next one allocated`);
       id = given;
     }
-    const data = pick({ ...fields, [idField]: id }, schemaOrder({ ...fields, [idField]: id }, schema));
+    // A session records the commit it opened at (#2693): HEAD now, or null before the first commit.
+    const opened = kind.session?.openedRev ? { [kind.session.openedRev]: headCommit(o.root) } : {};
+    const full = { ...fields, ...opened, [idField]: id };
+    const data = pick(full, schemaOrder(full, schema));
     const title = typeof data.title === "string" ? data.title : "";
     const match = new RegExp(kind.location.match);
     const names = [slug(title) ? `${id}-${slug(title)}.md` : null, `${id}.md`].filter((n): n is string => n !== null);
@@ -461,7 +628,9 @@ export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
     if (!name) throw new RecordWriteError("record-path-unmatched", `the kind's location.match ${kind.location.match} matches none of ${names.join(", ")}`);
     const path = o.dirRel === "." ? name : `${o.dirRel}/${name}`;
     if (o.source.list(o.dirRel)?.includes(name)) throw new RecordWriteError("record-id-taken", `${path} already exists`);
-    const text = renderRecord(data, title ? `\n# ${title}\n` : "");
+    let text = renderRecord(data, title ? `\n# ${title}\n` : "");
+    let seal: AuthorSeal | undefined;
+    if (opts.sign !== undefined) ({ text, seal } = await sealAuthor(o, text, data, id, opts.sign, opts.cwd));
     const warnings = await validateWrite(o, before, path, text);
     if (!opts.dryRun) writeFileSync(abs(o, path), text, { flag: "wx" });
     return {
@@ -470,6 +639,7 @@ export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
       kind: o.view,
       path,
       id,
+      ...(seal ? { seal } : {}),
       dryRun: !!opts.dryRun,
       warnings,
       ...(opts.dryRun ? { text } : {}),
@@ -488,6 +658,8 @@ export interface AmendRecordOptions {
   fields: string;
   dryRun?: boolean;
   cwd: string;
+  /** Seal the amended record's author, as `records new` does (#2688). */
+  sign?: string | true;
 }
 
 /**
@@ -496,15 +668,26 @@ export interface AmendRecordOptions {
  * a decided decision) changes in place only in its state, to one ranked at
  * least as high, its pins field and its reviews: anything else is a new
  * decision, written as a record that supersedes it (#2524 D4).
+ *
+ * An amendment moves the record's digest, so an author seal no longer holds
+ * (#2688). With `sign` the record is sealed again over the new text; without
+ * it, an amendment that moves the digest removes the seal and says so in
+ * `sealDropped`, so a record never carries a seal that fails. One that
+ * changes only the reviews leaves the digest, and the seal, as they were.
+ * `--sign` with nothing to change seals the record as it is.
  */
 export async function amendRecord(opts: AmendRecordOptions): Promise<AmendDocument> {
   try {
-    const patch = parseFields(opts.fields, "--set");
+    const given = parseFields(opts.fields, "--set");
     const o = await open(opts.kind, opts.cwd);
     const { kind } = o.loaded;
+    refuseSealField(o, given, "--set");
     const before = await readAll(o, o.source);
     const target = findRecord(before, opts.id, kind.name);
     const old = target.data;
+    refuseRevisionFields(kind, given, old, "--set");
+    const isClosed = target.state !== null && (kind.closedStates ?? []).includes(target.state);
+    const patch = { ...(isClosed ? {} : openedRevFill(kind, old, o.root)), ...given };
     const added = Object.keys(patch).filter((k) => !(k in old));
     const merged = pick({ ...old, ...patch }, [...Object.keys(old), ...schemaOrder(pick(patch, added), o.loaded.schema)]);
     const changed = Object.keys(merged).filter((k) => stableJson(old[k]) !== stableJson(merged[k]));
@@ -514,8 +697,8 @@ export async function amendRecord(opts: AmendRecordOptions): Promise<AmendDocume
     const state = target.state;
     const link = kind.supersedes?.key === undefined ? JSON.stringify(opts.id) : `[{"${kind.supersedes.key}": "${opts.id}"}]`;
     const supersede = kind.supersedes ? `chant workspace records new with ${kind.supersedes.field}: ${link}` : `chant workspace records new`;
-    if (changed.length > 0 && state !== null && (kind.closedStates ?? []).includes(state)) {
-      throw new RecordWriteError("record-closed", `${opts.id} is ${state}, a closed state, so nothing in it changes. Write a new record that supersedes it: ${supersede}`);
+    if ((changed.length > 0 || opts.sign !== undefined) && state !== null && (kind.closedStates ?? []).includes(state)) {
+      throw new RecordWriteError("record-closed", `${opts.id} is ${state}, a closed state, so nothing in it changes. ${closedAdvice(o, opts.id, supersede)}`);
     }
     const rank = (s: unknown): number => (typeof s === "string" ? (kind.approval?.[s] ?? 0) : 0);
     if (changed.length > 0 && kind.approval && rank(state) > 0) {
@@ -537,7 +720,23 @@ export async function amendRecord(opts: AmendRecordOptions): Promise<AmendDocume
     }
     // Only the changed fields' blocks are rewritten, so the rest of the file keeps its bytes.
     const current = o.source.read(target.path);
-    const text = replaceFields(current, pick(merged, changed), merged) ?? renderRecord(merged, bodyOf(current));
+    let text = changed.length === 0 ? current : (replaceFields(current, pick(merged, changed), merged) ?? renderRecord(merged, bodyOf(current)));
+    // The author seal (#2688): signed again over the new text, or dropped once the text moves.
+    let seal: AuthorSeal | undefined;
+    let sealDropped: string | undefined;
+    const sealable = kind.reviews !== undefined && RECORD_SEAL_FIELD in old;
+    if (opts.sign !== undefined) {
+      ({ text, seal } = await sealAuthor(o, text, merged, opts.id, opts.sign, opts.cwd));
+      merged[RECORD_SEAL_FIELD] = seal;
+    } else if (sealable && recordTextDigest(text, digestFields(kind), kind.format) !== recordTextDigest(current, digestFields(kind), kind.format)) {
+      const signer = (old[RECORD_SEAL_FIELD] as { signer?: unknown } | null)?.signer;
+      delete merged[RECORD_SEAL_FIELD];
+      const dropped = removeField(text, RECORD_SEAL_FIELD, merged);
+      if (dropped === undefined) throw new RecordWriteError("record-unparseable", `${target.path}: the ${RECORD_SEAL_FIELD} block can't be removed without changing the rest of the file`);
+      text = dropped;
+      sealDropped = `${opts.id} was sealed${typeof signer === "string" ? ` by ${signer}` : ""}, and the amendment moves its digest, so the seal was removed: seal it again with records amend ${opts.id} --sign`;
+    }
+    if (stableJson(old[RECORD_SEAL_FIELD]) !== stableJson(merged[RECORD_SEAL_FIELD])) changed.push(RECORD_SEAL_FIELD);
     const warnings = changed.length === 0 ? target.warnings : await validateWrite(o, before, target.path, text);
     if (!opts.dryRun && changed.length > 0) writeFileSync(abs(o, target.path), text);
     return {
@@ -547,6 +746,8 @@ export async function amendRecord(opts: AmendRecordOptions): Promise<AmendDocume
       path: target.path,
       id: opts.id,
       changed,
+      ...(seal ? { seal } : {}),
+      ...(sealDropped ? { sealDropped } : {}),
       dryRun: !!opts.dryRun,
       warnings,
       ...(opts.dryRun ? { text } : {}),
@@ -562,7 +763,7 @@ export interface ReviewRecordOptions {
   kind: string;
   id: string;
   verdict: string;
-  /** The reviewer, as the caller names them. chant does not check who it is; attestation does (#2547). */
+  /** The reviewer, as the caller names them. chant does not check who it is; a seal does, on read (#2687). */
   by: string;
   note?: string;
   /** The review session the verdict was given in. */
@@ -571,11 +772,18 @@ export interface ReviewRecordOptions {
   cwd: string;
   /** The date written as `on`, YYYY-MM-DD. Defaults to today, in UTC. */
   on?: string;
+  /**
+   * Seal the verdict (#2687): a key file, resolved against `cwd`, or true for
+   * git's `user.signingkey`. Without it the verdict is written unsealed.
+   */
+  sign?: string | true;
 }
 
 /**
  * `records review`: append one verdict to a record's reviews, with the date
  * and the digest of the record text it judged ({@link recordTextDigest}).
+ * With `sign`, the verdict carries a seal: an ssh signature over the record
+ * id, the digest, the verdict, the reviewer and the date (`trust/seal.ts`).
  */
 export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDocument> {
   try {
@@ -598,6 +806,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
     if (opts.verdict === "dissent" && !(opts.note ?? "").trim()) {
       throw new RecordWriteError("review-note-required", `a dissent needs a reason: pass --note <text> with the concern`);
     }
+    const inSession = opts.session !== undefined ? await openSession(o, opts.session, opts.cwd) : undefined;
     const reviews = target.data[field] ?? [];
     if (!Array.isArray(reviews)) throw new RecordWriteError("record-schema-invalid", `${target.path}: ${field} is not a list`);
     const current = o.source.read(target.path);
@@ -606,15 +815,34 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       verdict: opts.verdict,
       ...(opts.note !== undefined ? { note: opts.note } : {}),
       on: opts.on ?? today(),
-      digest: recordTextDigest(current, field),
+      digest: recordTextDigest(current, digestFields(kind), kind.format),
       ...(opts.session !== undefined ? { session: opts.session } : {}),
     };
-    // Only the reviews block changes, so the digest the verdict names stays the record's digest (#2672).
+    if (opts.sign !== undefined) review.seal = await seal(opts.sign, opts.cwd, { record: opts.id, digest: review.digest as string, verdict: opts.verdict, reviewer: opts.by, on: review.on as string });
+    // Only the reviews block changes, so the digest the verdict names stays the record's digest (#2672),
+    // and a record's author seal, which the digest leaves out too, still holds (#2688).
     const list = [...reviews, review];
     const text = replaceFields(current, { [field]: list }, { ...target.data, [field]: list });
     if (text === undefined) throw new RecordWriteError("record-unparseable", `${target.path}: the ${field} block can't be rewritten in place without changing the rest of the file`);
     const warnings = await validateWrite(o, before, target.path, text);
-    if (!opts.dryRun) writeFileSync(abs(o, target.path), text);
+    // The same verdict on the session's own list (#2693), validated with the review in place, so the two lists never differ.
+    let session: { path: string; text: string; out: ReviewSession } | undefined;
+    if (inSession) {
+      const { so, before: sessions, target: st } = inSession;
+      const decl = so.loaded.kind.session!;
+      const verdicts = st.data[decl.verdicts] ?? [];
+      if (!Array.isArray(verdicts)) throw new RecordWriteError("record-schema-invalid", `${st.path}: ${decl.verdicts} is not a list`);
+      const verdict = { record: opts.id, principal: opts.by, verdict: opts.verdict, digest: review.digest };
+      const set = { ...openedRevFill(so.loaded.kind, st.data, so.root), [decl.verdicts]: [...verdicts, verdict] };
+      const sText = replaceFields(so.source.read(st.path), set, { ...st.data, ...set });
+      if (sText === undefined) throw new RecordWriteError("record-unparseable", `${st.path}: the ${decl.verdicts} block can't be rewritten in place without changing the rest of the file`);
+      await validateWrite(so, sessions, st.path, sText, overlay(o.source, target.path, text));
+      session = { path: st.path, text: sText, out: { id: opts.session!, path: st.path, verdict, ...(opts.dryRun ? { text: sText } : {}) } };
+    }
+    if (!opts.dryRun) {
+      writeFileSync(abs(o, target.path), text);
+      if (session) writeFileSync(abs(o, session.path), session.text);
+    }
     return {
       $schema: RECORDS_REVIEW_SCHEMA_ID,
       contract: RECORDS_WRITE_CONTRACT_VERSION,
@@ -622,6 +850,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       path: target.path,
       id: opts.id,
       review,
+      ...(session ? { session: session.out } : {}),
       dryRun: !!opts.dryRun,
       warnings,
       ...(opts.dryRun ? { text } : {}),
@@ -631,12 +860,56 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
   }
 }
 
+/**
+ * The open session `id` of a session kind whose subjects are the kind `o`
+ * writes (#2693), found through the workspace declaration. Refused with
+ * session-unknown when no such session exists, and session-not-open when it
+ * is in a closed state.
+ */
+async function openSession(o: Opened, id: string, cwd: string): Promise<{ so: Opened; before: RecordEntry[]; target: RecordEntry & { data: Record<string, unknown> } }> {
+  const kinds = await sessionKindsFor(o.loaded.file, cwd);
+  for (const k of kinds) {
+    const so = await open(k.file, cwd);
+    const before = await readAll(so, so.source);
+    if (!before.some((e) => e.id === id)) continue;
+    const target = findRecord(before, id, so.view.name);
+    if (target.data === null) throw new RecordWriteError("record-unparseable", `session ${id} (${target.path}) can't be read, so the verdict can't be added to it`);
+    if (target.state !== null && (so.loaded.kind.closedStates ?? []).includes(target.state)) {
+      throw new RecordWriteError("session-not-open", `session ${id} is ${target.state}, so it takes no more verdicts: give the verdict in an open session, or without --session`);
+    }
+    return { so, before, target };
+  }
+  throw new RecordWriteError(
+    "session-unknown",
+    kinds.length === 0
+      ? `no session kind the workspace declaration names has ${o.view.file} as its subjects, so there is no session ${id} to give the verdict in`
+      : `no ${kinds.map((k) => k.kind.name).join(" or ")} record has id ${id}`,
+  );
+}
+
+/** A seal over one verdict, or a refusal with review-sign-failed. Loaded only when --sign is given. */
+async function seal(sign: string | true, cwd: string, v: { record: string; digest: string; verdict: string; reviewer: string; on: string }): Promise<Record<string, unknown>> {
+  const { resolveSigningKey, sealVerdict, SealError } = await import("./trust/seal");
+  try {
+    const key = resolveSigningKey(sign, cwd);
+    try {
+      return { ...sealVerdict(key.file, v) };
+    } finally {
+      key.cleanup();
+    }
+  } catch (err) {
+    if (err instanceof SealError) throw new RecordWriteError("review-sign-failed", err.message);
+    throw err;
+  }
+}
+
 // ── The command ──────────────────────────────────────────────────────────────
 
 export const WRITE_USAGE = [
-  "chant workspace records new [<kind file or declared kind>] --from <file|-> [--prefix <prefix>] [--dry-run]",
-  "chant workspace records amend <id> [--kind <kind file>] --set <file|-> [--dry-run]",
-  "chant workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--dry-run]",
+  "chant workspace records new [<kind file or declared kind>] --from <file|-> [--prefix <prefix>] [--sign [<key file>]] [--dry-run]",
+  "chant workspace records amend <id> [--kind <kind file>] --set <file|-> [--sign [<key file>]] [--dry-run]",
+  "chant workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]",
+  "chant workspace records close <session id> [--kind <session kind file>] [--dry-run]",
 ].join("\n");
 
 function usage(schema: string, message: string): WriteFailure<"write-usage-invalid"> {
@@ -701,7 +974,18 @@ function readInput(schema: string, flag: string, value: string | undefined, cwd:
   }
 }
 
-/** `chant workspace records new|amend|review`. Prints one JSON document; exits 0 when it wrote, or would have with --dry-run. */
+/**
+ * The session kind `records close` goes through when none is named (#2693):
+ * the one session kind the declaration names.
+ */
+async function declaredSessionKind(schema: string, cwd: string): Promise<string | WriteFailure<"write-usage-invalid">> {
+  const kinds = (await findSessionKinds(cwd)).map((k) => k.file);
+  if (kinds.length === 1) return kinds[0];
+  if (kinds.length === 0) return usage(schema, "--kind <session kind file> is required: the declaration names no session kind");
+  return usage(schema, `the declaration names ${kinds.length} session kinds (${kinds.join(", ")}), so name the one to close with --kind`);
+}
+
+/** `chant workspace records new|amend|review|close`. Prints one JSON document; exits 0 when it wrote, or would have with --dry-run. */
 export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
@@ -710,13 +994,22 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;
   };
+  if (verb === "close") {
+    const { closeRecord, RECORDS_CLOSE_SCHEMA_ID } = await import("./records-close");
+    if (args.sign !== undefined) return print(usage(RECORDS_CLOSE_SCHEMA_ID, "--sign is not taken by close: the seal close writes is the digest of the session text"));
+    const id = args.extraPositional2;
+    if (!id) return print(usage(RECORDS_CLOSE_SCHEMA_ID, "close needs the session's id"));
+    const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : await declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
+    if (typeof kind !== "string") return print(kind);
+    return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd }));
+  }
   if (verb === "new") {
     const named = args.extraPositional2 ?? args.kind;
     const kind = named !== undefined ? resolveWriteKind(named, cwd) : declaredWriteKind(RECORDS_NEW_SCHEMA_ID, cwd, "new needs the kind file");
     if (typeof kind !== "string") return print(kind);
     const input = readInput(RECORDS_NEW_SCHEMA_ID, "--from", args.migrateFrom, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await newRecord({ kind, fields: input, prefix: args.prefix, dryRun: args.dryRun, cwd }));
+    return print(await newRecord({ kind, fields: input, prefix: args.prefix, sign: args.sign, dryRun: args.dryRun, cwd }));
   }
   const schema = verb === "amend" ? RECORDS_AMEND_SCHEMA_ID : RECORDS_REVIEW_SCHEMA_ID;
   const id = args.extraPositional2;
@@ -726,11 +1019,11 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
   if (verb === "amend") {
     const input = readInput(schema, "--set", args.set, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await amendRecord({ kind, id, fields: input, dryRun: args.dryRun, cwd }));
+    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd }));
   }
   if (args.verdict === undefined) return print(usage(schema, "--verdict agree|dissent|abstain is required"));
   if (args.by === undefined) return print(usage(schema, "--by <principal> is required"));
   return print(
-    await reviewRecord({ kind, id, verdict: args.verdict, by: args.by, note: args.note, session: args.session, dryRun: args.dryRun, cwd }),
+    await reviewRecord({ kind, id, verdict: args.verdict, by: args.by, note: args.note, session: args.session, sign: args.sign, dryRun: args.dryRun, cwd }),
   );
 }