@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/records-write.ts

@@ -20,7 +20,9 @@
  * `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`.
+ * `review --sign` seals a verdict (#2687): see `trust/seal.ts`. A record of
+ * a kind that declares `seal` gets its whole-file seal when `new` or `amend`
+ * writes it into a closed state (#2546, ws-063).
  */
 
 import { readFileSync, statSync, writeFileSync } from "node:fs";
@@ -37,6 +39,7 @@ import {
   RecordReadError,
   RECORD_SEAL_FIELD,
   digestFields,
+  recordSeal,
   recordTextDigest,
   type LoadedRecordKind,
   type RecordEntry,
@@ -47,6 +50,8 @@ import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
 import { workingTree } from "./tree";
+import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError } from "./write-scope";
+import type { WriteVerb } from "./declaration";
 
 // ── Contract ─────────────────────────────────────────────────────────────────
 
@@ -72,6 +77,7 @@ export const NEW_ERROR_CODES = [
   "source-harvest-not-proposed",
   "record-state-not-initial",
   "ratify-quorum-not-met",
+  ...WRITE_SCOPE_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -86,6 +92,7 @@ export const AMEND_ERROR_CODES = [
   "amend-supersede-instead",
   "record-sign-failed",
   "ratify-quorum-not-met",
+  ...WRITE_SCOPE_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -100,6 +107,7 @@ export const REVIEW_ERROR_CODES = [
   "review-sign-failed",
   "session-unknown",
   "session-not-open",
+  ...WRITE_SCOPE_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -348,6 +356,15 @@ export async function open(kind: string, cwd: string): Promise<Opened> {
   };
 }
 
+/**
+ * Refuse a write outside the writer's scope (#2548): the kind `o` opened,
+ * written with `verb`, by the session `agent` names (`CHANT_AGENT`) or the
+ * principal `by` names. Throws a {@link WriteScopeError}.
+ */
+export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): void {
+  refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+}
+
 /**
  * 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
@@ -460,6 +477,33 @@ function refuseSealField(o: Opened, fields: Record<string, unknown>, flag: strin
   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`);
   }
+  const closed = o.loaded.kind.seal?.field;
+  if (closed !== undefined && !o.loaded.kind.session && closed in fields) {
+    throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${closed}, and chant writes it when the record closes`);
+  }
+}
+
+/**
+ * `text`, the record `data` holds, with its whole-file seal written into the
+ * kind's `seal.field` when the record is in a closed state (#2546, ws-063).
+ * The seal goes last, after the author seal, so it covers every other value
+ * and the body. `text` is returned as it is for a kind without `seal`, a
+ * session kind (whose seal `records close` writes), or an open record.
+ */
+function sealClosed(o: Opened, text: string, data: Record<string, unknown>, id: string): { text: string; data: Record<string, unknown> } {
+  const { kind } = o.loaded;
+  if (!kind.seal || kind.session || kind.stateField === undefined) return { text, data };
+  const state = data[kind.stateField];
+  if (typeof state !== "string" || !(kind.closedStates ?? []).includes(state)) return { text, data };
+  const field = kind.seal.field;
+  const seal = recordSeal(text, field, kind.format);
+  if (seal === null) throw new RecordWriteError("record-unparseable", `${id} can't be read, so it can't be sealed`);
+  const sealedData = { ...data, [field]: seal };
+  const sealed = replaceFields(text, { [field]: seal }, sealedData);
+  if (sealed === undefined || recordSeal(sealed, field, kind.format) !== seal) {
+    throw new RecordWriteError("record-unparseable", `the ${field} field can't be written into ${id} without changing the text it seals`);
+  }
+  return { text: sealed, data: sealedData };
 }
 
 /**
@@ -584,7 +628,7 @@ function today(): string {
 }
 
 export function failure<C>(schema: string, err: unknown): WriteFailure<C> {
-  if (err instanceof RecordWriteError || err instanceof RecordReadError) {
+  if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError) {
     return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code as C, message: err.message } };
   }
   throw err;
@@ -644,6 +688,8 @@ export interface NewRecordOptions {
    * `reviews.decider` field, which the fields must set.
    */
   sign?: string | true;
+  /** The agent session the write is made in (`CHANT_AGENT`, #2548), which its write scope binds. */
+  agent?: string;
 }
 
 /**
@@ -727,6 +773,7 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
       throw new RecordWriteError("write-usage-invalid", `--prefix takes letters and digits, starting with a letter, not ${JSON.stringify(opts.prefix)}`);
     }
     const o = await open(opts.kind, opts.cwd);
+    refuseOutOfScope(o, "new", opts.cwd, opts);
     const fields = applyChannel(o, parseFields(opts.fields, "--from"), opts, true, "--from");
     const { kind, schema } = o.loaded;
     refuseSealField(o, fields, "--from");
@@ -758,6 +805,7 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
     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));
+    ({ text } = sealClosed(o, text, seal ? { ...data, [RECORD_SEAL_FIELD]: seal } : data, id));
     const written = await validatedEntry(o, before, path, text);
     await refuseRatifyBelowQuorum(o, written, id);
     const warnings = written.warnings;
@@ -789,6 +837,8 @@ export interface AmendRecordOptions {
   cwd: string;
   /** Seal the amended record's author, as `records new` does (#2688). */
   sign?: string | true;
+  /** The agent session the write is made in (#2548). */
+  agent?: string;
 }
 
 /**
@@ -808,6 +858,7 @@ export interface AmendRecordOptions {
 export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
+    refuseOutOfScope(o, "amend", opts.cwd, opts);
     const given = applyChannel(o, parseFields(opts.fields, "--set"), opts, false, "--set");
     const { kind } = o.loaded;
     refuseSealField(o, given, "--set");
@@ -871,6 +922,12 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
       sealDropped = `${opts.id} was sealed${typeof signer === "string" ? ` by ${signer}` : ""}, and the amendment moves its digest or its state, 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);
+    // Entering a closed state seals the whole record, last (#2546, ws-063).
+    if (changed.length > 0 && kind.seal && !kind.session) {
+      const closedSeal = sealClosed(o, text, merged, opts.id);
+      text = closedSeal.text;
+      if (stableJson(old[kind.seal.field]) !== stableJson(closedSeal.data[kind.seal.field])) changed.push(kind.seal.field);
+    }
     let warnings = target.warnings;
     if (changed.length > 0) {
       const written = await validatedEntry(o, before, target.path, text);
@@ -916,6 +973,8 @@ export interface ReviewRecordOptions {
    * git's `user.signingkey`. Without it the verdict is written unsealed.
    */
   sign?: string | true;
+  /** The agent session the write is made in (#2548). */
+  agent?: string;
 }
 
 /**
@@ -932,6 +991,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
     if (opts.by.trim() === "") throw new RecordWriteError("write-usage-invalid", "--by needs the reviewer's name");
     if (opts.session !== undefined && opts.session === "") throw new RecordWriteError("write-usage-invalid", "--session needs a session id");
     const o = await open(opts.kind, opts.cwd);
+    refuseOutOfScope(o, "review", opts.cwd, opts);
     const { kind } = o.loaded;
     if (!kind.reviews) {
       throw new RecordWriteError("review-unsupported", `the ${kind.name} kind declares no reviews field, so its records take no review`);
@@ -946,6 +1006,8 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       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;
+    // The verdict is appended to the session too, so the session's kind must be in scope as well.
+    if (inSession) refuseOutOfScope(inSession.so, "review", opts.cwd, opts);
     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);
@@ -1129,6 +1191,8 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
   const verb = args.extraPositional;
+  // The agent session the write is made in (#2548): set by the harness that runs the agent.
+  const agent = process.env[AGENT_ENV] || undefined;
   const print = (doc: object): number => {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;
@@ -1140,7 +1204,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     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 }));
+    return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd, agent }));
   }
   if (verb === "new") {
     const named = args.extraPositional2 ?? args.kind;
@@ -1148,7 +1212,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     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, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd }));
+    return print(await newRecord({ kind, fields: input, prefix: args.prefix, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
   }
   const schema = verb === "amend" ? RECORDS_AMEND_SCHEMA_ID : RECORDS_REVIEW_SCHEMA_ID;
   const id = args.extraPositional2;
@@ -1159,11 +1223,11 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (args.by !== undefined) return print(usage(schema, "--by is not taken by amend: set decided_by, or a kind's proposedBy field, with --set"));
     const input = readInput(schema, "--set", args.set, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd }));
+    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
   }
   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, sign: args.sign, 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, agent }),
   );
 }

package/src/workspace/records.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
   "title": "chant workspace records output",
-  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). A closed record of a kind that declares seal carries a whole-file seal, checked on every read (#2546). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }, { "$ref": "#/$defs/set" }],
   "$defs": {
     "decidedIn": {
@@ -47,6 +47,43 @@
             ]
           }
         },
+        "spec": {
+          "description": "Added in contract 1 by #2546 (#2524 D20). With --current only: the workspace's spec, the current records of each declared kind marked spec: true, each with the workspace files it pins. A kind whose read failed is left out, and is listed under kinds with its error.",
+          "type": "object",
+          "required": ["kinds", "records"],
+          "properties": {
+            "kinds": {
+              "type": "array",
+              "description": "The spec kinds, as the declaration names them, in its order.",
+              "items": {
+                "type": "object",
+                "required": ["member", "path", "name"],
+                "properties": {
+                  "member": { "type": ["string", "null"] },
+                  "path": { "type": "string" },
+                  "name": { "type": ["string", "null"] }
+                }
+              }
+            },
+            "records": {
+              "type": "array",
+              "description": "Every current record of the spec kinds, in the order of kinds and then path. Invalid records are listed with valid false, as under kinds.",
+              "items": {
+                "type": "object",
+                "required": ["kind", "id", "path", "state", "valid", "digest", "assets"],
+                "properties": {
+                  "kind": { "type": "string", "description": "The kind's name, such as decision." },
+                  "id": { "type": ["string", "null"] },
+                  "path": { "type": "string" },
+                  "state": { "type": ["string", "null"] },
+                  "valid": { "type": "boolean" },
+                  "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+                  "assets": { "type": "array", "items": { "$ref": "#/$defs/asset" } }
+                }
+              }
+            }
+          }
+        },
         "kind": false,
         "records": false,
         "error": false
@@ -69,6 +106,10 @@
             "format": {
               "enum": ["markdown-front-matter", "json"],
               "description": "Added in contract 1 by #2664 (ws-053). How each record file holds its structured core: the YAML front matter of a Markdown file, or the whole file as one JSON object, read as I-JSON (no repeated member name)."
+            },
+            "spec": {
+              "type": "boolean",
+              "description": "Added in contract 1 by #2546. true when the kind file marks the kind spec: true, so its current records and the files they pin are part of the workspace's spec (#2524 D20)."
             }
           }
         },
@@ -163,7 +204,7 @@
           "items": { "$ref": "#/$defs/warning" }
         },
         "digest": {
-          "description": "Added in contract 1 by #2672. The lowercase hex SHA-256 of the record file's text, with LF line endings and without the kind's reviews block and its top-level seal block (#2688) in the front matter, or for a kind of format json without the top-level reviews and seal members, each with one comma beside it (#2664). A record with no seal hashes as it did before #2688. A review verdict names it in its digest field, and stops counting once the record's digest moves on; a record's author seal signs it. For a kind with no reviews list, the digest of the whole text.",
+          "description": "Added in contract 1 by #2672. The lowercase hex SHA-256 of the record file's text, with LF line endings and without the kind's reviews block and its top-level seal block (#2688) in the front matter, or for a kind of format json without the top-level reviews and seal members, each with one comma beside it (#2664). A record with no seal hashes as it did before #2688. A review verdict names it in its digest field, and stops counting once the record's digest moves on; a record's author seal signs it. A kind that declares seal (#2546) also leaves out the field holding the whole-file seal, and a kind with reviews.ratified its state line (#2873). For a kind with no reviews list, the digest of the whole text. It is not the record's seal: the seal covers the whole file (#2546, ws-063).",
           "type": "string",
           "pattern": "^[0-9a-f]{64}$"
         },
@@ -405,7 +446,17 @@
         "attestor": { "type": "string", "description": "The attestor that answered, such as ssh-commit." },
         "principal": { "type": "string", "description": "The signer, when attested." },
         "key": { "type": "string", "description": "The signing key's fingerprint, when known." },
-        "reason": { "type": "string" }
+        "reason": { "type": "string" },
+        "returned": {
+          "description": "Added in contract 1 by #2552. Set when the record's bytes came back in a return that carries the commit they were made in: level, principal and key then judge that commit, with the signers at base plus those admitted for the return, and commit is the commit here that holds the bytes. A signer neither lists reads as attested-unverifiable-here until an admin admits it.",
+          "type": "object",
+          "required": ["id", "importedIn"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^ret-[0-9a-f]{12}$", "description": "The return, .chant/returns/<id>.json at the workspace root." },
+            "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit in the returned copy that last changed the file." },
+            "importedIn": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The commit here that holds the returned bytes." }
+          }
+        }
       }
     },
     "reason": {
@@ -421,6 +472,7 @@
             "record-supersedes-conflict",
             "record-remediates-unknown",
             "record-remediates-not-closed",
+            "record-seal-mismatch",
             "session-seal-mismatch",
             "session-verdict-unknown-record"
           ]

package/src/workspace/records.ts

@@ -13,15 +13,18 @@
  *
  * A record that fails any of that is still returned, with reason codes, and the
  * read succeeds. Only a failure to read the kind, its schema or the revision is
- * an error. Seals, attestation and the workspace declaration come later (#2546,
- * #2534); nothing here needs a `chant.workspace.json`.
+ * an error. A closed record of a kind that declares `seal` is checked against
+ * its whole-file seal ({@link recordSeal}, #2546); author and verdict seals
+ * are checked by `records-cli.ts` against the policy at base. Nothing here
+ * needs a `chant.workspace.json`.
  *
  * Everything under `workspace/` loads only when a `chant workspace` command
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 
 import { createHash } from "node:crypto";
-import { sha256Hex } from "../content-digest";
+import { contentDigest, sha256Hex } from "../content-digest";
+import { canonicalJson } from "../effect-receipt";
 import { readFileSync, statSync } from "node:fs";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import yaml from "js-yaml";
@@ -57,6 +60,8 @@ export const RECORD_REASON_CODES = [
   "record-remediates-unknown",
   /** A `remediates` link names a record that isn't closed: a record still open is amended instead (#2774). */
   "record-remediates-not-closed",
+  /** A closed record's seal is not the whole-file seal of its text now: it changed after it closed (#2546, ws-063). */
+  "record-seal-mismatch",
   /** A closed session's seal is not the digest of its text: it changed after it closed (#2673). */
   "session-seal-mismatch",
   /** A session's verdict names a record the kind's subject records do not have (#2673). */
@@ -171,13 +176,21 @@ export const RECORD_SEAL_FIELD = "seal";
  * moving a record to that state keeps the verdicts that ratified it
  * counting.
  */
-export function digestFields(kind: Pick<RecordKind, "reviews" | "stateField">): string[] | null {
+export function digestFields(kind: Pick<RecordKind, "reviews" | "stateField" | "seal">): string[] | null {
   if (!kind.reviews) return null;
   const fields = [kind.reviews.field, RECORD_SEAL_FIELD];
   if (kind.reviews.ratified !== undefined && kind.stateField !== undefined) fields.push(kind.stateField);
+  // The whole-file seal is written when the record closes (#2546, ws-063), so
+  // the verdicts that ratified it keep counting on the sealed record.
+  if (kind.seal !== undefined) fields.push(kind.seal.field);
   return fields;
 }
 
+/** The field holding a closed record's whole-file seal: the kind's `seal.field`, or a session kind's `session.seal` (#2546, #2673). */
+export function sealFieldOf(kind: Pick<RecordKind, "seal" | "session">): string | undefined {
+  return kind.seal?.field ?? kind.session?.seal;
+}
+
 /** What a verdict's seal establishes (#2687). See `trust/seal.ts`. */
 export interface VerdictAttestation {
   /** Why the verdict is not attested. Absent when its seal verified. */
@@ -430,8 +443,32 @@ export const recordKindSchema = z
      * Optional.
      */
     answers: z.object({ points: z.string().min(1) }).strict().optional(),
+    /**
+     * The top-level field that holds a closed record's seal (#2546, ws-003,
+     * ws-063): {@link recordSeal}, the whole-file JCS/SHA-256 of the record
+     * without that field. `records amend` and `records new` write it when a
+     * record enters one of `closedStates`, and `records` reports a closed
+     * record whose seal does not match as `record-seal-mismatch`. Requires
+     * states. A session kind's `session.seal` names the same field for a
+     * session, and when both are given they must agree. Optional.
+     */
+    seal: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The kind's current records, with the files they pin, are part of the
+     * workspace's spec (#2524 D20): `chant workspace records --current
+     * --json` lists them under `spec`. Optional, and false when left out.
+     */
+    spec: z.boolean().optional(),
   })
   .strict()
+  .refine((k) => k.states !== undefined || k.seal === undefined, {
+    message: "a kind without states cannot have seal: a record is sealed when it enters a closed state",
+    path: ["seal"],
+  })
+  .refine((k) => k.seal === undefined || k.session === undefined || k.seal.field === k.session.seal, {
+    message: "seal.field and session.seal name the field that holds a closed session's seal, and must be the same",
+    path: ["seal"],
+  })
   .refine((k) => (k.idField === undefined) !== (k.idFrom === undefined), {
     message: "a kind names its id with exactly one of idField and idFrom",
     path: ["idField"],
@@ -748,7 +785,9 @@ function nonJson(v: unknown, at: string, seen: Set<object>): string | undefined
  * record's author seal (#2688; {@link digestFields}), so sealing a record
  * leaves its digest where it was too. A record with no `seal` hashes exactly
  * as it did before author seals existed. A kind with `reviews.ratified` adds
- * its state field (#2873).
+ * its state field (#2873), and a kind with `seal` its seal field (#2546), so
+ * the whole-file seal written at the close moves no digest. The digest is not
+ * that seal: {@link recordSeal} covers the whole record.
  *
  * The rule, which a hand-editor can follow with a text editor and
  * `sha256sum`:
@@ -776,6 +815,50 @@ export function recordTextDigest(text: string, field: string | readonly string[]
   return createHash("sha256").update(kept, "utf8").digest("hex");
 }
 
+// ── Record seal ──────────────────────────────────────────────────────────────
+
+/**
+ * The seal of a closed record (#2546, ws-003, ws-063): `sha256:` and the
+ * lowercase hex SHA-256 of the RFC 8785 (JCS) form of the whole record, with
+ * only the field that holds the seal left out. It is a separate hash from
+ * {@link recordTextDigest}, which a review verdict names: the digest leaves
+ * out the reviews, the author seal and the state so verdicts keep counting,
+ * and the seal covers all of them.
+ *
+ * 1. Line endings become LF (CRLF and a lone CR each become one LF).
+ * 2. The structured core is parsed as the kind's format says: the front
+ *    matter, as the JSON subset of YAML, or the whole JSON object. The
+ *    top-level member `field` is removed from it.
+ * 3. For a Markdown record the value hashed is the object
+ *    `{"body": <the text after the closing --- line>, "core": <the core>}`;
+ *    for a JSON record it is the core itself.
+ * 4. That value is written in JCS (keys sorted by UTF-16 code units, no
+ *    whitespace, ECMAScript number and string forms) and hashed as UTF-8.
+ *
+ * So every value in the record and every byte of its body is sealed, the
+ * reviews, the author seal and the state included, while the key order,
+ * quoting and indentation of the front matter are not: the same record
+ * written another way has the same seal. A YAML comment in the front matter
+ * is not part of the record, so it is not sealed either (#3066). Returns null when
+ * the core can't be parsed.
+ */
+export function recordSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string | null {
+  const lf = text.replace(/\r\n?/g, "\n");
+  const parsed = parseRecord(format, lf);
+  if (!parsed.ok) return null;
+  const core = { ...parsed.value };
+  delete core[field];
+  const sealed = format === "json" ? core : { body: bodyText(lf), core };
+  return contentDigest(canonicalJson(sealed));
+}
+
+/** The text below a Markdown file's front matter, with LF line endings: everything after the closing `---` line. */
+export function bodyText(text: string): string {
+  const normalised = text.replace(/\r\n?/g, "\n");
+  const m = normalised.match(/^---\n[\s\S]*?\n---(?:\n|$)/);
+  return m ? normalised.slice(m[0].length) : "";
+}
+
 /**
  * `text` with the top-level member `field` removed from a JSON record, by the
  * rule a hand-editor follows for a JSON record (ws-053). With several fields
@@ -1282,6 +1365,14 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
         if (drift) entry.warnings.push({ code: "source-transcript-drift", message: drift });
       }
     }
+    if (kind.seal && !kind.session && entry.state !== null && (kind.closedStates ?? []).includes(entry.state)) {
+      // A closed record's whole-file seal (#2546, ws-063). A session's is checked with its verdicts (#2673).
+      const seal = fm.value[kind.seal.field];
+      const actual = typeof seal === "string" ? recordSeal(text, kind.seal.field, kind.format) : null;
+      if (typeof seal === "string" && actual !== seal) {
+        entry.reasons.push({ code: "record-seal-mismatch", message: `${kind.seal.field} is ${seal}, but the record seals to ${actual}: it changed after it closed` });
+      }
+    }
     if (kind.pins) {
       const cited = fm.value[kind.pins.field];
       if (Array.isArray(cited) && cited.length === 0) {