@intentius/chant 0.87.0 → 0.89.0

package/src/workspace/reason-codes.ts

@@ -87,11 +87,13 @@ export const REASONS = {
   "review-duplicate": "A later verdict by the same principal replaces this one. Names are compared after NFKC, trimming and lower-casing.",
   "review-older-digest": "The verdict names a digest other than the record's text now: the record changed after the verdict.",
   "review-unattested": "An attestation policy is active at base, and the verdict carries no seal that verifies for its reviewer.",
-  // A verdict's seal that is not attested (records, #2687). Every verdict reports one of these in its attestation, unless its seal verified.
-  "seal-missing": "The verdict carries no seal.",
-  "seal-signer-unlisted": "The reviewer has no key in the signers file at base, so the seal can't count.",
-  "seal-signature-invalid": "The seal is malformed, names a signer other than the reviewer, or its signature does not verify over the verdict.",
+  // A seal that is not attested (records): a verdict's (#2687) or a record's author seal (#2688). Each reports one of these in its attestation, unless its seal verified.
+  "seal-missing": "The verdict, or the record, carries no seal.",
+  "seal-signer-unlisted": "The reviewer, or the record's author, has no key in the signers file at base, so the seal can't count.",
+  "seal-signature-invalid": "The seal is malformed, names a signer other than the reviewer or author, or its signature does not verify over the verdict or record.",
   "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.",
+  // A record whose author seal is not attested under a signers file at base (records, #2688). A warning: the record is still read.
+  "record-unattested": "A signers file is active at base, and the record names an author whose seal does not verify: it has none, the author has no key in the file, or the signature fails.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -112,8 +114,14 @@ export const REASONS = {
   "review-unsupported": "The kind's schema has no reviews field, so its records take no review.",
   "review-note-required": "A dissent was given with no note: a dissent needs a reason.",
   "review-sign-failed": "--sign was given and no seal could be made: the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  // A review given in a session (records review --session, #2693).
+  "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
+  "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
   // records --since that fails (#2673).
-  "since-rev-unknown": "--since names no commit.",
+  "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
+  "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
+  "since-session-open": "--since names a session that is still open, so the comparison runs to the working tree.",
   // The intent graph (graph --intent, #2651): a read that fails.
   "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
   // The intent graph: part of the walk that can't be read. The document is still printed.
@@ -142,8 +150,12 @@ export const REASONS = {
   "composites-none-declared": "The members read declare no composite instance.",
   "composites-no-component": "The members read declare no component, so no composite instance has one.",
   // The runtimes a member's components can deploy on (graph --composites, #2674).
-  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed.",
+  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed, and no environment from the config.",
   "runtimes-lexicon-unreadable": "A lexicon the member's config lists could not be loaded, so it is not listed as a runtime.",
+  // The environments a member's components may deploy to (graph --composites, #2695).
+  "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
+  "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
+  "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",

package/src/workspace/record-assets.test.ts

@@ -16,7 +16,7 @@ import { cleanScratch, commitAll, contract, declaration, repo, REPO } from "./__
 import { runChecks } from "./lineage-check";
 import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTERN } from "./record-assets";
 import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
-import { parseFrontMatter, RECORD_WARNING_CODES } from "./records";
+import { parseFrontMatter, RECORD_WARNING_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
@@ -169,8 +169,9 @@ describe("chant workspace records checks each pin", () => {
   });
 
   test("the schema lists exactly the 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).
-    expect(recordsSchema.$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(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...SEAL_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

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

@@ -67,7 +67,35 @@
           "items": {
             "type": "string"
           },
-          "description": "The top-level fields whose value differs from the record as it was, in the record's order. Empty when the fields set change nothing, and then nothing is written."
+          "description": "The top-level fields whose value differs from the record as it was, in the record's order, with seal last when the author seal was written or removed (#2688). Empty when the fields set change nothing, and then nothing is written."
+        },
+        "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."
+            }
+          }
+        },
+        "sealDropped": {
+          "type": "string",
+          "description": "Added in contract 1 by #2688. Present when the record carried an author seal, the amendment moved its digest and --sign was not given: the seal no longer covers the text, so it was removed, and this says so. changed then lists seal."
         },
         "dryRun": {
           "type": "boolean",
@@ -145,6 +173,7 @@
                 "amend-id-immutable",
                 "record-closed",
                 "amend-supersede-instead",
+                "record-sign-failed",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/records-cli.ts

@@ -34,6 +34,7 @@ import {
   loadRecordKind,
   normalisePrincipal,
   readRecords,
+  RECORD_SEAL_FIELD,
   RecordReadError,
   type LoadedRecordKind,
   type Quorum,
@@ -43,11 +44,14 @@ import {
   type RecordFormat,
   type RecordHistory,
   type SealInput,
+  type VerdictAttestation,
 } from "./records";
 import { gitTree, workingTree, type WorkspaceTree } from "./tree";
 import type { DecisionWork } from "./work";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
+import type { TrustPolicy } from "./trust/policy";
+import type { SealedRecord } from "./trust/seal";
 
 /** The version of the `records` output this chant writes. */
 export const RECORDS_CONTRACT_VERSION = 1;
@@ -56,7 +60,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
 const USAGE =
-  "chant workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review (#2670)";
+  "chant workspace records [--kind <kind file>] [--current] [--at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review|close (#2670, #2693)";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -79,9 +83,16 @@ export interface RecordsQuery {
 
 /**
  * A record as the output carries it: the entry plus its provenance (#2547),
- * and its quorum when the kind has a reviews list (#2671).
+ * and, when the kind has a reviews list, its quorum (#2671) and what its
+ * author seal establishes (#2688).
  */
-export type RecordView = RecordEntry & { provenance: RecordProvenance; quorum?: Quorum | null };
+export type RecordView = RecordEntry & {
+  provenance: RecordProvenance;
+  quorum?: Quorum | null;
+  /** true when the record's seal verifies for its author against the signers at base; false when it fails, or is missing under an active policy; null when nothing here can say (#2688). */
+  attested?: boolean | null;
+  attestation?: VerdictAttestation;
+};
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
 export const AGENT_ROLE = "agent";
@@ -276,7 +287,8 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
     // The quorum: the need from the declaration in the tree read, agents,
     // whether verdicts need a seal, and the keys a seal verifies against,
     // all from the policy at base (#2671, #2687).
-    const checkVerdictSeal = loaded.kind.reviews ? (await import("./trust/seal")).checkVerdictSeal : undefined;
+    const seals = loaded.kind.reviews ? await import("./trust/seal") : undefined;
+    const checkVerdictSeal = seals?.checkVerdictSeal;
     const quorumOptions = checkVerdictSeal
       ? {
           ...declaredQuorum(tree),
@@ -289,6 +301,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       ...r,
       provenance: provenance.get(r.path)!,
       ...(quorumOptions ? { quorum: computeQuorum(loaded.kind, r, quorumOptions) } : {}),
+      ...(seals ? authorSeal(loaded.kind, r, policy, seals.checkRecordSeal) : {}),
     }));
     if (loaded.kind.work && query.workGaps !== false && top) await raiseWorkGaps(loaded, records, { root, workspaceRoot, at: query.at });
     return {
@@ -314,6 +327,29 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   }
 }
 
+/**
+ * A record's author seal checked against the policy at base (#2688), for a
+ * kind with a reviews list: its author is the kind's `reviews.decider` field.
+ * Under an active signers file, a record that names an author and is not
+ * attested gains the warning `record-unattested`, and is still read: sealing
+ * records is opt-in for now. A record that can't be parsed gets neither field.
+ */
+function authorSeal(
+  kind: LoadedRecordKind["kind"],
+  r: RecordEntry,
+  policy: TrustPolicy,
+  check: (policy: TrustPolicy, r: SealedRecord) => { attested: boolean | null } & VerdictAttestation,
+): { attested?: boolean | null; attestation?: VerdictAttestation } {
+  if (r.data === null) return {};
+  const field = kind.reviews!.decider;
+  const author = typeof r.data[field] === "string" && (r.data[field] as string).trim() !== "" ? (r.data[field] as string) : null;
+  const { attested, ...attestation } = check(policy, { record: r.id, digest: r.digest, author, authorField: field, state: r.state, seal: r.data[RECORD_SEAL_FIELD] });
+  if (policy.active && author !== null && attested !== true) {
+    r.warnings.push({ code: "record-unattested", message: `an attestation policy is active at base, and ${attestation.message}` });
+  }
+  return { attested, attestation };
+}
+
 /**
  * `work-done-gap-open` on a records read (#2686): for each done work record
  * whose `source` names a finding and a region, walk that region with the
@@ -383,7 +419,7 @@ export function pinFile(file: string, cwd: string): { path: string; sha256: stri
 
 export async function runWorkspaceRecords(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
-  if (args.extraPositional === "new" || args.extraPositional === "amend" || args.extraPositional === "review") {
+  if (args.extraPositional === "new" || args.extraPositional === "amend" || args.extraPositional === "review" || args.extraPositional === "close") {
     return (await import("./records-write")).runRecordsWrite(ctx);
   }
   if (args.extraPositional === "pin") {
@@ -400,7 +436,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     return 0;
   }
   if (args.extraPositional) {
-    console.error(formatError({ message: `chant workspace records takes no argument but pin, new, amend or review (got ${args.extraPositional})`, hint: USAGE }));
+    console.error(formatError({ message: `chant workspace records takes no argument but pin, new, amend, review or close (got ${args.extraPositional})`, hint: USAGE }));
     return 1;
   }
   if (!args.kind) return runDeclaredRecords(args);
@@ -555,7 +591,8 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const flag = r.valid ? "" : "  INVALID";
     const superseded = r.supersededBy ? `  superseded by ${r.supersededBy}` : "";
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${flag}`);
+    const sealed = r.attested === true ? `  sealed by ${(r.data?.[RECORD_SEAL_FIELD] as { signer: string }).signer}` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${sealed}${flag}`);
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");

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

@@ -0,0 +1,192 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json",
+  "title": "chant workspace records close output",
+  "description": "What `chant workspace records close <session id> [--kind <session kind file>]` prints (#2693): the session's path and id, the fields the close set (the state, and the close time and closing revision when the session kind names fields for them), the seal written and the commit the session closed at, 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.88.0 and newer; an older chant refuses the close verb.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "changed",
+        "seal",
+        "closedRev",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The kind's name, such as \"session\"."
+            },
+            "schema": {
+              "type": "string",
+              "description": "The `$id` of the schema the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The top-level fields whose value differs from the session as it was: its state, the close time, the closing revision and the seal, and the opening revision when it was null and the repository now has a commit."
+        },
+        "seal": {
+          "type": "object",
+          "required": [
+            "field",
+            "digest"
+          ],
+          "properties": {
+            "field": {
+              "type": "string",
+              "description": "The seal field, as the session kind's session.seal names it, such as closed_digest."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The seal written: the lowercase hex SHA-256 of the file with LF line endings and without its seal line, which records checks on every read (session-seal-mismatch)."
+            }
+          }
+        },
+        "closedRev": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id HEAD named at the close, or null outside git or before the first commit. It is written to the field session.closedRev names, when the kind names one. The caller commits the close, so the commit that carries it comes after this one."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-close/v1/records-close.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "record-not-found",
+                "record-closed",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something. A session already closed is record-closed; a verdict naming a record the session kind's subjects lack is session-verdict-unknown-record."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

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",