@intentius/chant 0.86.0 → 0.88.0

package/src/workspace/records-cli.ts

@@ -34,6 +34,7 @@ import {
   loadRecordKind,
   normalisePrincipal,
   readRecords,
+  RECORD_SEAL_FIELD,
   RecordReadError,
   type LoadedRecordKind,
   type Quorum,
@@ -42,11 +43,15 @@ import {
   type RecordEntry,
   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;
@@ -55,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;
@@ -68,13 +73,26 @@ export interface RecordsQuery {
   base?: string;
   /** Where `kind` is resolved from and the repository is found. */
   cwd: string;
+  /**
+   * For a work kind: walk the region of each done item's `source` and raise
+   * `work-done-gap-open` when its finding still fires (#2686). On unless
+   * false; the intent graph passes false, since it raises the warning itself.
+   */
+  workGaps?: boolean;
 }
 
 /**
  * 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";
@@ -266,15 +284,26 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       paths: result.records.map((r) => r.path),
       attestors: policy.active ? await activeAttestors() : [],
     });
-    // The quorum: the need from the declaration in the tree read, agents and
-    // whether verdicts need a seal from the policy at base (#2671).
-    const quorumOptions = loaded.kind.reviews
+    // 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 seals = loaded.kind.reviews ? await import("./trust/seal") : undefined;
+    const checkVerdictSeal = seals?.checkVerdictSeal;
+    const quorumOptions = checkVerdictSeal
       ? {
           ...declaredQuorum(tree),
           agents: new Set((policy.roles[AGENT_ROLE] ?? []).map(normalisePrincipal)),
           attestation: policy.active,
+          verifySeal: (v: SealInput) => checkVerdictSeal(policy, v),
         }
       : undefined;
+    const records: RecordView[] = result.records.map((r) => ({
+      ...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 {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -288,11 +317,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       workspaceRoot,
       current: !!query.current,
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
-      records: result.records.map((r) => ({
-        ...r,
-        provenance: provenance.get(r.path)!,
-        ...(quorumOptions ? { quorum: computeQuorum(loaded.kind, r, quorumOptions) } : {}),
-      })),
+      records,
       summary: result.summary,
       ...(result.decisions ? { decisions: result.decisions } : {}),
     };
@@ -302,6 +327,79 @@ 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
+ * intent graph, at the same revision, and copy the warning the walk raises
+ * on the record. One walk per region, and only a region some done item names.
+ * The walk reads the record kinds the declaration names, and the work kind
+ * and its decision kind if it names neither. It needs git and a workspace
+ * declaration; when the walk can't be made, for one without them or a region
+ * that no longer exists, the record is left as it was.
+ */
+async function raiseWorkGaps(loaded: LoadedRecordKind, records: RecordView[], opts: { root: string; workspaceRoot: string; at: string | undefined }): Promise<void> {
+  const work = loaded.kind.work!;
+  const byRegion = new Map<string, RecordView[]>();
+  for (const r of records) {
+    if (r.id === null || r.state !== work.done) continue;
+    const src = r.data?.source;
+    if (src === null || typeof src !== "object" || Array.isArray(src)) continue;
+    const { finding, region } = src as Record<string, unknown>;
+    if (typeof finding !== "string" || typeof region !== "string") continue;
+    byRegion.set(region, [...(byRegion.get(region) ?? []), r]);
+  }
+  if (byRegion.size === 0) return;
+  const cwd = opts.workspaceRoot === "." ? opts.root : join(opts.root, ...opts.workspaceRoot.split("/"));
+  let declared: string[];
+  try {
+    declared = declaredKindFiles(cwd, opts.at).map((k) => k.file);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return;
+    throw err;
+  }
+  const kinds: string[] = [];
+  const seen = new Set<string>();
+  for (const file of [...declared, resolve(dirname(loaded.file), work.decisions), loaded.file]) {
+    const real = realpathOr(file);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    kinds.push(file);
+  }
+  const { intentGraph } = await import("./intent");
+  for (const [region, items] of byRegion) {
+    const { doc } = await intentGraph({ cwd, region, at: opts.at, kinds });
+    if ("error" in doc) continue;
+    for (const r of items) {
+      const node = doc.nodes.find((n) => n.kind === "work" && n.id === `record:${loaded.kind.name}/${r.id}`);
+      const warning = node?.kind === "work" ? node.warnings.find((w) => w.code === "work-done-gap-open") : undefined;
+      if (warning && !r.warnings.some((w) => w.code === warning.code)) r.warnings.push(warning);
+    }
+  }
+}
+
 /**
  * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
  * evidence entry holds for a file, with the path from the workspace root
@@ -321,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") {
@@ -338,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);
@@ -493,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, except work-done-gap-open, which only graph --intent raises (#2683).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES.filter((c) => c !== "work-done-gap-open")]);
+    // 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",