@intentius/chant 0.87.0 → 0.88.0

package/src/workspace/environments.ts

@@ -0,0 +1,165 @@
+/**
+ * The environments a member's components may deploy to, for `chant workspace
+ * graph --composites` (#2695), so a reader such as hud can offer staging or
+ * prod beside the default without guessing a name.
+ *
+ * Each environment comes from one of three places, and says which:
+ *
+ * - `config`: a name the member's `chant.config.ts` declares in
+ *   `environments`. A pattern such as `pr-*` names no environment by itself
+ *   and is not listed, but it legalizes the ledger's `pr-42`.
+ * - `ledger`: an environment with a release ledger for the member on
+ *   `chant/lifecycle` (`_members/<member>/<env>/releases.jsonl`, or the flat
+ *   `<env>/releases.jsonl`, read the way `workspace status` reads it).
+ * - `builtin`: `local`, which `chant run --components` uses without `--env`
+ *   (`../cli/handlers/run.ts`), when neither the config nor the ledger names
+ *   it.
+ *
+ * The component contract declares no environments, so every component of a
+ * member lists the member's environments.
+ *
+ * `chant run --env` refuses a name the config's `environments` doesn't cover
+ * whenever it declares any (`unknownEnvError` in `../env.ts`), so a ledger
+ * environment the config no longer covers is left out, with a reason. The
+ * default is `local`: `chant.config.ts` has no default environment, and
+ * `chant run` without `--env` deploys to `local` even when the config's
+ * `environments` leaves it out.
+ *
+ * The config is the one `runtimes.ts` loads, in the working tree or the tree
+ * `--at` exported. The ledger is always the local `chant/lifecycle` branch,
+ * as for `workspace status`, and is never fetched.
+ */
+
+import { execFileSync } from "node:child_process";
+import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment } from "../config";
+import type { ReasonCode } from "./reason-codes";
+import { LOCAL_RUNTIME, type MemberRuntimes } from "./runtimes";
+import { ENV_PATTERN, LIFECYCLE_REF, MEMBERS_DIR } from "./status";
+
+/** The environment `chant run --components` deploys to without `--env`. */
+export const LOCAL_ENVIRONMENT = "local";
+
+/** Why a member's environments are only `local`, or leave out one the ledger has. Closed: part of the read contract. */
+export const ENVIRONMENT_REASON_CODES = [
+  /** The member's chant.config.ts could not be read: the same read and the same code as its runtimes. */
+  "runtimes-config-unreadable",
+  /** The config declares no environments, so only local and the ledger's environments are listed. */
+  "environments-none-declared",
+  /** The ledger has releases in an environment the config's environments no longer cover, so chant run --env would refuse it. */
+  "environments-ledger-undeclared",
+  /** The chant/lifecycle branch exists and the member's ledger directories could not be listed. */
+  "environments-ledger-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
+
+export interface EnvironmentReason {
+  code: EnvironmentReasonCode;
+  message: string;
+}
+
+/** One environment a component may deploy to. */
+export interface ComponentEnvironment {
+  /** What `--env` takes. */
+  name: string;
+  /** True for the environment `chant run --components` deploys to without `--env`. */
+  default: boolean;
+  /** Where the name came from; the first of config, ledger and builtin that names it. */
+  source: "config" | "ledger" | "builtin";
+  /** The command that deploys the component there on the default runtime, run in the member's directory. */
+  command: string;
+}
+
+/** The environments a member's ledger has, or why they couldn't be listed. */
+export interface LedgerEnvironments {
+  envs: string[];
+  reason: EnvironmentReason | null;
+}
+
+/** Lists one member's ledger environments; git unless a test swaps it. */
+export type LedgerEnvironmentReader = (member: { name: string; dir: string }, cwd: string) => LedgerEnvironments;
+
+/** What one member's config and ledger say about environments. */
+export interface MemberEnvironments {
+  /** Each environment in list order, without the per-component command. */
+  environments: Omit<ComponentEnvironment, "command">[];
+  reasons: EnvironmentReason[];
+}
+
+function git(cwd: string, args: string[], input?: string): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+}
+
+function exists(cwd: string, spec: string): boolean {
+  try {
+    git(cwd, ["rev-parse", "--verify", "--quiet", spec]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The environments with a release ledger for `member` on the local
+ * `chant/lifecycle` branch: the directories under `_members/<member>/` when it
+ * exists (the root member never has one), else the flat layout's top-level
+ * directories, that hold a `releases.jsonl`.
+ */
+export const readLedgerEnvironments: LedgerEnvironmentReader = (member, cwd) => {
+  if (!exists(cwd, `refs/heads/${LIFECYCLE_REF}`)) return { envs: [], reason: null };
+  const own = member.dir !== "." && exists(cwd, `refs/heads/${LIFECYCLE_REF}:${MEMBERS_DIR}/${member.name}`);
+  const base = own ? `${MEMBERS_DIR}/${member.name}/` : "";
+  try {
+    const dirs = git(cwd, ["ls-tree", "--full-tree", `refs/heads/${LIFECYCLE_REF}:${base}`])
+      .split("\n")
+      .map((line) => line.match(/^\d+ tree [0-9a-f]+\t(.+)$/)?.[1])
+      .filter((name): name is string => !!name && ENV_PATTERN.test(name));
+    if (dirs.length === 0) return { envs: [], reason: null };
+    const checked = git(cwd, ["cat-file", "--batch-check"], dirs.map((d) => `refs/heads/${LIFECYCLE_REF}:${base}${d}/releases.jsonl\n`).join(""))
+      .split("\n")
+      .filter(Boolean);
+    return { envs: dirs.filter((_, i) => checked[i] !== undefined && !checked[i].endsWith(" missing")).sort(), reason: null };
+  } catch (err) {
+    const message = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+    return { envs: [], reason: { code: "environments-ledger-unreadable", message: `${LIFECYCLE_REF}:${base || "."}: ${message}` } };
+  }
+};
+
+/** Join a member's config and ledger into its environment list, `local` first, then config order, then the ledger's. */
+export function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger: LedgerEnvironments | undefined): MemberEnvironments {
+  const reasons: EnvironmentReason[] = [];
+  const declared = runtimes?.environments ?? null;
+  if (runtimes && declared === null) {
+    const unreadable = runtimes.reasons.find((r) => r.code === "runtimes-config-unreadable");
+    reasons.push({ code: "runtimes-config-unreadable", message: unreadable?.message ?? "chant.config.ts could not be read" });
+  } else if (declared && declared.length === 0) {
+    reasons.push({ code: "environments-none-declared", message: "chant.config.ts declares no environments, so only local and the environments in the ledger are listed" });
+  }
+  if (ledger?.reason) reasons.push(ledger.reason);
+
+  const literals = (declared ?? []).map(environmentName).filter((n) => !isEnvironmentPattern(n));
+  const ledgerEnvs = ledger?.envs ?? [];
+  const covered = (env: string): boolean => !declared || declared.length === 0 || matchesDeclaredEnvironment(declared, env);
+  const undeclared = ledgerEnvs.filter((e) => e !== LOCAL_ENVIRONMENT && !covered(e));
+  if (undeclared.length > 0) {
+    reasons.push({
+      code: "environments-ledger-undeclared",
+      message: `the ledger has releases in ${undeclared.join(", ")}, which chant.config.ts's environments don't cover, so chant run --env refuses ${undeclared.length === 1 ? "it" : "them"}`,
+    });
+  }
+
+  const out: MemberEnvironments["environments"] = [];
+  const add = (name: string, source: ComponentEnvironment["source"]) => {
+    if (!out.some((e) => e.name === name)) out.push({ name, default: name === LOCAL_ENVIRONMENT, source });
+  };
+  add(LOCAL_ENVIRONMENT, literals.includes(LOCAL_ENVIRONMENT) ? "config" : ledgerEnvs.includes(LOCAL_ENVIRONMENT) ? "ledger" : "builtin");
+  for (const name of literals) add(name, "config");
+  for (const name of ledgerEnvs) if (covered(name)) add(name, "ledger");
+  return { environments: out, reasons };
+}
+
+/** The environments one component may deploy to, each with its command line on the member's default runtime. */
+export function componentEnvironments(component: string, member: MemberEnvironments | undefined, runtime = LOCAL_RUNTIME): ComponentEnvironment[] {
+  const list = member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }];
+  const on = runtime === LOCAL_RUNTIME ? "" : ` --on ${runtime}`;
+  return list.map((e) => ({ ...e, command: `chant run --components ${component}${on}${e.default ? "" : ` --env ${e.name}`}` }));
+}

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

@@ -160,6 +160,9 @@ describe("every schema against the reference workspace (#2543)", () => {
         // #2674: the reference config's lexicons host no component runs, so local is the only runtime, read at HEAD too.
         expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
         expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
+        // #2695: the reference config declares no environments, so the app deploys to local only.
+        expect(doc.components[0].environments).toEqual([{ name: "local", default: true, source: "builtin", command: "chant run --components app" }]);
+        expect(doc.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
         expect(doc.reasons).toEqual([]);
       }
     },

package/src/workspace/reason-codes.test.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
-import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
+import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
@@ -19,9 +19,10 @@ import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import intentSchema from "./intent.schema.json";
 import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
 import { contract } from "./__fixtures__/contract-repo";
-import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { AMEND_ERROR_CODES, NEW_ERROR_CODES, REVIEW_ERROR_CODES } from "./records-write";
-import { RECORDS_SINCE_ERROR_CODES } from "./records-since";
+import { CLOSE_ERROR_CODES } from "./records-close";
+import { RECORDS_SINCE_ERROR_CODES, RECORDS_SINCE_REASON_CODES } from "./records-since";
 import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
 import { WORK_WARNING_CODES } from "./work";
 
@@ -42,18 +43,22 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RECORD_WARNING_CODES,
   REVIEW_REASON_CODES,
   SEAL_REASON_CODES,
+  SEAL_WARNING_CODES,
   WORK_WARNING_CODES,
   READ_ERROR_CODES,
   NEW_ERROR_CODES,
   AMEND_ERROR_CODES,
   REVIEW_ERROR_CODES,
+  CLOSE_ERROR_CODES,
   RECORDS_SINCE_ERROR_CODES,
+  RECORDS_SINCE_REASON_CODES,
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
+  COMPOSITES_ENVIRONMENT_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

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
+      }
+    }
+  }
+}