@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/records-write.js

@@ -0,0 +1,1229 @@
+/**
+ * `chant workspace records new|amend|review` (#2670): the commands a UI
+ * writes records through, so it never parses or writes a record file itself
+ * (ws-052).
+ *
+ * Each command loads the kind, reads every record it locates, builds the one
+ * file it would write, and reads the records again with that file in place,
+ * through the same {@link readRecords} a read uses. The write goes ahead only
+ * when the written record comes back valid and no other record gains a
+ * reason. So a write is refused for exactly what a later read would report,
+ * plus the rules only a write has: ids are allocated and never reused, a
+ * closed record never changes, an approved one changes only in place of
+ * what the approval rule allows, and a dissent needs a note.
+ *
+ * Every command writes one file or none, never commits, and prints one JSON
+ * document with a closed error code on refusal. `--dry-run` prints the
+ * document and the text it would write, and writes nothing. The exception is
+ * `review --session` (#2693), which appends the verdict to the open session
+ * as well, after checking both files, so the two lists never differ.
+ * `records close` is in `records-close.ts`.
+ *
+ * Each write holds the working tree's write lock (`write-lock.ts`, #3173,
+ * ws-089) from its first read to its last write, so writes to one working
+ * tree never interleave. `amend`, `review` and `close` take `--expect
+ * <digest>`: the record's digest the caller last read. When the record has
+ * moved on since, the write is refused with record-conflict, naming the
+ * digest it has now and the last chant write of it, and the caller re-reads
+ * and tries again.
+ *
+ * `new --sign` and `amend --sign` seal the record's author (#2688), and
+ * `review --sign` seals a verdict (#2687): see `trust/seal.ts`. A record of
+ * a kind that declares `seal` gets its whole-file seal when `new` or `amend`
+ * writes it into a closed state (#2546, ws-063).
+ *
+ * `new` also writes a record of a content-addressed JSON kind (`format:
+ * "json"`, `idFrom: "sha256"`, ws-053), such as the reference workspace's
+ * evidence (ws-082): the fields as JSON, in a file named for the SHA-256 of
+ * its bytes. Such a record never changes, so amend, review and close refuse
+ * the kind.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, posix, relative, resolve } from "node:path";
+import { gitRoot, workingTreeSource } from "./record-source.js";
+import { computeQuorum, loadRecordKind, parseFrontMatter, readRecords, readSessionSubjects, RECORD_REASON_CODES, RecordReadError, RECORD_SEAL_FIELD, digestFields, recordSeal, recordTextDigest, } from "./records.js";
+import { declaredKindFiles, pinRoot, quorumOptionsFor, realpathOr } from "./records-cli.js";
+import { policyAtBase, resolveBase } from "./trust/provenance.js";
+import { WorkspaceReadError } from "./declaration.js";
+import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds.js";
+import { workingTree } from "./tree.js";
+import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError } from "./write-scope.js";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity.js";
+import { lastWriteReader, noteWrites, withWriteLock, writeFileAtomic, WriteLockError, WRITE_LOCK_CODES } from "./write-lock.js";
+// ── Contract ─────────────────────────────────────────────────────────────────
+/** The version of the write documents this chant prints. */
+export const RECORDS_WRITE_CONTRACT_VERSION = 1;
+export const RECORDS_NEW_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-new/v1/records-new.schema.json";
+export const RECORDS_AMEND_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-amend/v1/records-amend.schema.json";
+export const RECORDS_REVIEW_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records-review/v1/records-review.schema.json";
+/** Loading the kind and reading its records, as `records` reads them. */
+export const LOAD_ERROR_CODES = ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing"];
+/** Why `records new` wrote nothing. Closed: a reader may switch on it. */
+export const NEW_ERROR_CODES = [
+    ...LOAD_ERROR_CODES,
+    "write-usage-invalid",
+    "write-input-invalid",
+    "record-id-taken",
+    "record-id-unallocatable",
+    "record-path-unmatched",
+    "record-sign-failed",
+    "source-harvest-not-proposed",
+    "record-state-not-initial",
+    "ratify-quorum-not-met",
+    ...WRITE_LOCK_CODES,
+    ...WRITE_SCOPE_CODES,
+    ...IDENTITY_CODES,
+    ...RECORD_REASON_CODES,
+];
+/** Why `records amend` wrote nothing. */
+export const AMEND_ERROR_CODES = [
+    ...LOAD_ERROR_CODES,
+    "write-usage-invalid",
+    "write-input-invalid",
+    "record-not-found",
+    "amend-id-immutable",
+    "record-closed",
+    "amend-supersede-instead",
+    "record-sign-failed",
+    "ratify-quorum-not-met",
+    "record-conflict",
+    ...WRITE_LOCK_CODES,
+    ...WRITE_SCOPE_CODES,
+    ...IDENTITY_CODES,
+    ...RECORD_REASON_CODES,
+];
+/** Why `records review` wrote nothing. */
+export const REVIEW_ERROR_CODES = [
+    ...LOAD_ERROR_CODES,
+    "write-usage-invalid",
+    "record-not-found",
+    "review-unsupported",
+    "record-closed",
+    "review-note-required",
+    "review-sign-failed",
+    "session-unknown",
+    "session-not-open",
+    "record-conflict",
+    ...WRITE_LOCK_CODES,
+    ...WRITE_SCOPE_CODES,
+    ...IDENTITY_CODES,
+    ...RECORD_REASON_CODES,
+];
+export const VERDICTS = ["agree", "dissent", "abstain"];
+export class RecordWriteError extends Error {
+    constructor(code, message, 
+    /** With record-conflict: the record as it is now. */
+    conflict) {
+        super(message);
+        this.code = code;
+        this.conflict = conflict;
+        this.name = "RecordWriteError";
+    }
+}
+// ── Rendering ────────────────────────────────────────────────────────────────
+const PLAIN_KEY = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const RESERVED_KEY = new Set(["true", "false", "null"]);
+function yamlKey(k) {
+    return PLAIN_KEY.test(k) && !RESERVED_KEY.has(k) ? k : JSON.stringify(k);
+}
+function isScalar(v) {
+    return v === null || typeof v !== "object";
+}
+function isEmpty(v) {
+    return Array.isArray(v) ? v.length === 0 : v !== null && typeof v === "object" && Object.keys(v).length === 0;
+}
+const scalar = (v) => (v === null ? "null" : JSON.stringify(v));
+const empty = (v) => (Array.isArray(v) ? "[]" : "{}");
+/**
+ * YAML limited to what JSON can say, laid out as the decision README writes a
+ * record: every string double-quoted with JSON escapes, block mappings and
+ * sequences, and `[]` or `{}` for an empty one. `parseFrontMatter` reads it
+ * back to the same value.
+ */
+export function toYaml(value, indent = 0) {
+    const pad = " ".repeat(indent);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return `${pad}[]`;
+        return value
+            .map((item) => {
+            if (isScalar(item))
+                return `${pad}- ${scalar(item)}`;
+            if (isEmpty(item))
+                return `${pad}- ${empty(item)}`;
+            if (Array.isArray(item))
+                return `${pad}-\n${toYaml(item, indent + 2)}`;
+            return `${pad}- ${toYaml(item, indent + 2).slice(indent + 2)}`;
+        })
+            .join("\n");
+    }
+    if (isScalar(value))
+        return `${pad}${scalar(value)}`;
+    const lines = [];
+    for (const [k, v] of Object.entries(value)) {
+        if (isScalar(v))
+            lines.push(`${pad}${yamlKey(k)}: ${scalar(v)}`);
+        else if (isEmpty(v))
+            lines.push(`${pad}${yamlKey(k)}: ${empty(v)}`);
+        else
+            lines.push(`${pad}${yamlKey(k)}:\n${toYaml(v, indent + 2)}`);
+    }
+    return lines.join("\n");
+}
+/** A record file: the front matter, then `body` as it is. */
+export function renderRecord(data, body) {
+    return `---\n${toYaml(data)}\n---\n${body}`;
+}
+/** The text below a file's front matter, line endings normalised. */
+function bodyOf(text) {
+    const normalised = text.replace(/\r\n?/g, "\n");
+    const m = normalised.match(/^---\n[\s\S]*?\n---(?:\n|$)/);
+    return m ? normalised.slice(m[0].length) : "";
+}
+/** JSON with object keys sorted, for comparing two values whatever their key order. */
+export function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`)
+        .join(",")}}`;
+}
+/**
+ * `text` with the top-level fields in `set` replaced in place, and every
+ * other byte kept. A field's block is its key line at column 0 and the lines
+ * after it, up to the closing `---`, that start with a space, a tab, `#` or
+ * `-`: the block {@link recordTextDigest} cuts for the reviews field. Blank
+ * lines ending a block stay where they are. A field the front matter lacks is
+ * added before the closing `---`. Line endings become LF. Returns undefined
+ * when the text has no front matter, or when the result does not read back
+ * as `expected`, so a caller never writes a file it did not mean to.
+ */
+export function replaceFields(text, set, expected) {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    if (lines[0] !== "---")
+        return undefined;
+    let close = lines.indexOf("---", 1);
+    if (close < 0)
+        return undefined;
+    for (const [key, value] of Object.entries(set)) {
+        const rendered = toYaml({ [key]: value }).split("\n");
+        const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const starts = new RegExp(`^(?:${k}|"${k}"|'${k}')[ \\t]*:(?:[ \\t]|$)`);
+        const at = lines.findIndex((l, i) => i > 0 && i < close && starts.test(l));
+        if (at < 0) {
+            lines.splice(close, 0, ...rendered);
+            close += rendered.length;
+            continue;
+        }
+        let end = at;
+        while (end + 1 < close && /^(?:$|[ \t#-])/.test(lines[end + 1]))
+            end++;
+        while (end > at && lines[end] === "")
+            end--;
+        lines.splice(at, end - at + 1, ...rendered);
+        close += rendered.length - (end - at + 1);
+    }
+    const out = lines.join("\n");
+    const back = parseFrontMatter(out);
+    return back.ok && stableJson(back.value) === stableJson(expected) ? out : undefined;
+}
+/**
+ * `text` with the top-level field `key` removed: its key line and the lines
+ * after it that {@link replaceFields} counts as its block, less the blank
+ * lines ending it, which stay. Returns undefined when the result does not
+ * read back as `expected`.
+ */
+export function removeField(text, key, expected) {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    if (lines[0] !== "---")
+        return undefined;
+    const close = lines.indexOf("---", 1);
+    if (close < 0)
+        return undefined;
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const starts = new RegExp(`^(?:${k}|"${k}"|'${k}')[ \\t]*:(?:[ \\t]|$)`);
+    const at = lines.findIndex((l, i) => i > 0 && i < close && starts.test(l));
+    if (at >= 0) {
+        let end = at;
+        while (end + 1 < close && /^(?:$|[ \t#-])/.test(lines[end + 1]))
+            end++;
+        while (end > at && lines[end] === "")
+            end--;
+        lines.splice(at, end - at + 1);
+    }
+    const out = lines.join("\n");
+    const back = parseFrontMatter(out);
+    return back.ok && stableJson(back.value) === stableJson(expected) ? out : undefined;
+}
+/** A file-name slug from a title, as `scripts/import-decisions.mjs` makes one. */
+export function slug(title) {
+    return title
+        .toLowerCase()
+        .replace(/`/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48)
+        .replace(/-$/, "");
+}
+/** A kind `records new` writes as one JSON file named for the SHA-256 of its bytes (ws-053, ws-082). */
+export function isContentAddressed(kind) {
+    return kind.format === "json" && kind.idFrom === "sha256";
+}
+export async function open(kind, cwd, opts = {}) {
+    const real = realpathOr(cwd);
+    const root = gitRoot(real) ?? real;
+    const loaded = await loadRecordKind(kind, real);
+    // The writers write Markdown front matter with an id field. `records new`
+    // also writes a content-addressed JSON kind (ws-082), whose record never
+    // changes once written, so amend, review and close never open one. A JSON
+    // kind with an id field is read by records, and written by its own tool.
+    const writable = (loaded.kind.format === "markdown-front-matter" && loaded.kind.idField !== undefined) || (!!opts.contentAddressed && isContentAddressed(loaded.kind));
+    if (!writable) {
+        const what = loaded.kind.format !== "markdown-front-matter" ? `format ${loaded.kind.format}` : `ids from ${loaded.kind.idFrom}`;
+        const verbs = isContentAddressed(loaded.kind)
+            ? "a content-addressed record never changes once records new writes it, so amend, review and close never write one"
+            : "records new, amend and review write only Markdown front matter records with an idField, and records new a JSON record named for the sha256 of its bytes";
+        throw new RecordWriteError("write-usage-invalid", `the ${loaded.kind.name} kind has ${what}: ${verbs}`);
+    }
+    const dirRel = relative(root, loaded.dir).split("\\").join("/") || ".";
+    return {
+        loaded,
+        root,
+        workspaceRoot: pinRoot(loaded.file, root),
+        source: workingTreeSource(root),
+        view: { name: loaded.kind.name, schema: loaded.kind.schema.id, file: relative(root, loaded.file).split("\\").join("/") },
+        dirRel,
+    };
+}
+/**
+ * Refuse a write outside the writer's scope (#2548): the kind `o` opened,
+ * written with `verb`, by the session `agent` names (`CHANT_AGENT`) or the
+ * principal `by` names. Throws a {@link WriteScopeError}.
+ */
+export function refuseOutOfScope(o, verb, cwd, writer) {
+    const source = refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+    // #3163: under identity.attribution "identified" at base, --by names a forge identity or a signer.
+    if (writer.by !== undefined)
+        refuseUnidentified(source, [writer.by], "--by", { agent: writer.agent });
+    return source;
+}
+/**
+ * Refuse author fields (the kind's reviews.decider and proposedBy fields)
+ * that name a person by a bare name, under identity.attribution
+ * "identified" at base (#3163). `flag` is where the fields came from.
+ */
+function refuseUnidentifiedAuthors(source, kind, fields, flag, agent) {
+    const names = [kind.reviews?.decider, kind.proposedBy?.field]
+        .filter((f) => f !== undefined)
+        .map((f) => fields[f])
+        .filter((v) => typeof v === "string" && v.trim() !== "");
+    refuseUnidentified(source, names, `${flag} author`, { agent });
+}
+/**
+ * The kind's records as `records` reads them from `source`. A session kind's
+ * subject records are read from the same source (#2693), so a write is
+ * refused for a verdict naming a record that does not exist.
+ */
+export async function readAll(o, source) {
+    const assets = workingTree(o.workspaceRoot === "." ? o.root : join(o.root, ...o.workspaceRoot.split("/")));
+    const subjects = await readSessionSubjects(o.loaded, o.root, source);
+    return (await readRecords(o.loaded, { root: o.root, source, assets, workspaceRoot: o.workspaceRoot, ...(subjects ? { subjects } : {}) })).records;
+}
+/** `base` with the file at `path` holding `text`, added to its directory when new. */
+export function overlay(base, path, text) {
+    const dir = posix.dirname(path);
+    const name = posix.basename(path);
+    return {
+        label: base.label,
+        list(d) {
+            const names = base.list(d);
+            if (d !== dir || !names)
+                return names;
+            return names.includes(name) ? names : [...names, name];
+        },
+        read(p) {
+            return p === path ? text : base.read(p);
+        },
+        bytes(p) {
+            return p === path ? Buffer.from(text, "utf-8") : base.bytes(p);
+        },
+    };
+}
+/**
+ * Read the records again with `text` at `path`, over `base` (the working
+ * tree unless another write goes with this one). The written record must come
+ * back with no reason, and no other record may gain one. Returns the written
+ * record's warnings.
+ */
+export async function validateWrite(o, before, path, text, base = o.source) {
+    return (await validatedEntry(o, before, path, text, base)).warnings;
+}
+/** {@link validateWrite}, returning the written record as the read found it. */
+export async function validatedEntry(o, before, path, text, base = o.source) {
+    const after = await readAll(o, overlay(base, path, text));
+    const written = after.find((e) => e.path === path);
+    if (!written)
+        throw new RecordWriteError("record-path-unmatched", `${path} is not a file the kind ${o.view.name} reads`);
+    if (written.reasons.length > 0) {
+        throw new RecordWriteError(written.reasons[0].code, written.reasons.map((r) => `${r.code}: ${r.message}`).join("; "));
+    }
+    const had = new Map(before.map((e) => [e.path, new Set(e.reasons.map((r) => `${r.code}\0${r.message}`))]));
+    for (const e of after) {
+        if (e.path === path)
+            continue;
+        const gained = e.reasons.find((r) => !had.get(e.path)?.has(`${r.code}\0${r.message}`));
+        if (gained)
+            throw new RecordWriteError(gained.code, `writing ${path} would make ${e.path} invalid: ${gained.message}`);
+    }
+    return written;
+}
+/**
+ * Refuse a written record in the kind's ratified state (`reviews.ratified`,
+ * #2873) whose quorum is not met. The quorum is computed on the record as
+ * written, the way `records --json` computes it: the need from the
+ * declaration in the working tree, and agents and seals from the policy at
+ * base. A met quorum with open concerns is met, and the concerns stay listed.
+ */
+async function refuseRatifyBelowQuorum(o, written, id) {
+    const ratified = o.loaded.kind.reviews?.ratified;
+    if (ratified === undefined || written.state !== ratified)
+        return;
+    const top = gitRoot(o.root);
+    const policy = policyAtBase(top ?? o.root, top ? resolveBase(top) : { commit: null, from: null });
+    const tree = workingTree(o.workspaceRoot === "." ? o.root : join(o.root, ...o.workspaceRoot.split("/")));
+    const options = await quorumOptionsFor(o.loaded, tree, policy);
+    const q = options ? computeQuorum(o.loaded.kind, written, options) : null;
+    if (q === null || q.met)
+        return;
+    const notCounted = q.notCounted.length > 0 ? ` (not counted: ${q.notCounted.map((v) => `${v.reviewer}, ${v.reason.code}`).join("; ")})` : "";
+    throw new RecordWriteError("ratify-quorum-not-met", `${id} can't be ${ratified} yet: its quorum needs ${q.need} agreeing verdicts that count, and it has ${q.agreed}${notCounted}. Add verdicts with chant workspace records review ${id} --verdict agree --by <reviewer>, then set ${o.loaded.kind.stateField} to ${ratified} again`);
+}
+/**
+ * Refuse a write to `target` when the caller expected another digest
+ * (#3173): someone wrote the record since the caller read it. Called holding
+ * the write lock, after the records are read, so the digest compared is the
+ * one the write would build on.
+ */
+export function refuseStale(o, target, id, expect) {
+    if (expect === undefined || expect === target.digest)
+        return;
+    const lastWrite = lastWriteReader(o.root)(target.path, o.source.read(target.path));
+    const who = lastWrite ? ` It was last written by chant workspace ${lastWrite.verb}${lastWrite.by ? ` for ${lastWrite.by}` : ""}${lastWrite.agent ? ` in agent session ${lastWrite.agent}` : ""} at ${lastWrite.at}.` : "";
+    throw new RecordWriteError("record-conflict", `${id} has changed since the digest given with --expect (${expect}): its digest is now ${target.digest}.${who} Read it again with chant workspace records --json, and write again with --expect ${target.digest} if the change still stands`, { id, path: target.path, expected: expect, digest: target.digest, lastWrite });
+}
+/** Refuse a --expect that is not a digest, before anything is read. */
+function refuseExpectShape(expect) {
+    if (expect !== undefined && !/^[0-9a-f]{64}$/.test(expect)) {
+        throw new RecordWriteError("write-usage-invalid", `--expect takes a record's digest, 64 lowercase hex digits as records --json prints it, not ${JSON.stringify(expect)}`);
+    }
+}
+/** Who a write names, for the lock's owner file and the journal. */
+export function writeWho(verb, opts) {
+    return { verb, by: opts.by ?? null, agent: opts.agent ?? null };
+}
+export function findRecord(entries, id, kind) {
+    const hits = entries.filter((e) => e.id === id);
+    if (hits.length === 0)
+        throw new RecordWriteError("record-not-found", `no ${kind} record has id ${id}`);
+    if (hits.length > 1) {
+        throw new RecordWriteError("record-id-duplicate", `id ${id} is used by ${hits.map((h) => h.path).join(" and ")}; make the ids unique before writing either`);
+    }
+    return hits[0];
+}
+function parseFields(text, flag) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} are not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} must be a JSON object`);
+    }
+    return value;
+}
+/** Refuse fields that set the author seal by hand: only --sign writes it (#2688). */
+function refuseSealField(o, fields, flag) {
+    if (o.loaded.kind.reviews && RECORD_SEAL_FIELD in fields) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${RECORD_SEAL_FIELD}, and only --sign writes a record's seal`);
+    }
+    const closed = o.loaded.kind.seal?.field;
+    if (closed !== undefined && !o.loaded.kind.session && closed in fields) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${closed}, and chant writes it when the record closes`);
+    }
+}
+/**
+ * `text`, the record `data` holds, with its whole-file seal written into the
+ * kind's `seal.field` when the record is in a closed state (#2546, ws-063).
+ * The seal goes last, after the author seal, so it covers every other value
+ * and the body. `text` is returned as it is for a kind without `seal`, a
+ * session kind (whose seal `records close` writes), or an open record.
+ */
+function sealClosed(o, text, data, id) {
+    const { kind } = o.loaded;
+    if (!kind.seal || kind.session || kind.stateField === undefined)
+        return { text, data };
+    const state = data[kind.stateField];
+    if (typeof state !== "string" || !(kind.closedStates ?? []).includes(state))
+        return { text, data };
+    const field = kind.seal.field;
+    const seal = recordSeal(text, field, kind.format);
+    if (seal === null)
+        throw new RecordWriteError("record-unparseable", `${id} can't be read, so it can't be sealed`);
+    const sealedData = { ...data, [field]: seal };
+    const sealed = replaceFields(text, { [field]: seal }, sealedData);
+    if (sealed === undefined || recordSeal(sealed, field, kind.format) !== seal) {
+        throw new RecordWriteError("record-unparseable", `the ${field} field can't be written into ${id} without changing the text it seals`);
+    }
+    return { text: sealed, data: sealedData };
+}
+/**
+ * Refuse fields that set a session's opening or closing revision by hand
+ * (#2693): `new` writes the first from HEAD and `close` the second. A field
+ * given with the value the record already holds is not a change, so an
+ * amendment that sends the whole record back is taken.
+ */
+function refuseRevisionFields(kind, fields, old, flag) {
+    for (const f of [kind.session?.openedRev, kind.session?.closedRev]) {
+        if (f === undefined || !(f in fields) || (f in old && stableJson(old[f]) === stableJson(fields[f])))
+            continue;
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f}, and chant writes it: records new writes the commit a session opened at, and records close the one it closed at`);
+    }
+}
+/**
+ * Refuse a harvested record in any state but the kind's first (#2708): a
+ * record whose source block says `via: "harvest"` came out of a transcript
+ * after the fact, so it is a proposal, and a person decides it.
+ */
+function refuseHarvestedDecision(kind, fields) {
+    if (!kind.source || !kind.states || kind.stateField === undefined)
+        return;
+    const block = fields[kind.source.field];
+    if (block === null || typeof block !== "object" || Array.isArray(block) || block.via !== "harvest")
+        return;
+    const opens = kind.states[0];
+    const state = fields[kind.stateField];
+    if (state === opens)
+        return;
+    throw new RecordWriteError("source-harvest-not-proposed", `${kind.source.field}.via is harvest, and a harvested ${kind.name} opens ${opens}, not ${JSON.stringify(state ?? null)}: write it with ${kind.stateField} "${opens}", and let the person who decides it move it on with chant workspace records amend or review`);
+}
+/**
+ * `text`, the record `data` holds, with its author sealed (#2688): an ssh
+ * signature by the key `sign` names over the record id, the digest of
+ * `text`, the author (the kind's `reviews.decider` field) and the state, in
+ * the `chant-record` namespace. The seal goes in the top-level `seal` field,
+ * replacing one already there, or added at the end of the front matter. The
+ * digest leaves that field out, so it is the same before and after.
+ */
+async function sealAuthor(o, text, data, id, sign, cwd) {
+    const { kind } = o.loaded;
+    if (!kind.reviews) {
+        throw new RecordWriteError("write-usage-invalid", `--sign seals a record's author, named by the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`);
+    }
+    const field = kind.reviews.decider;
+    const author = data[field];
+    if (typeof author !== "string" || author.trim() === "") {
+        throw new RecordWriteError("record-sign-failed", `${id} names no ${field}, so there is no author to seal: set ${field}, then seal it with records amend ${id} --sign`);
+    }
+    const state = kind.stateField !== undefined && typeof data[kind.stateField] === "string" ? data[kind.stateField] : null;
+    const digest = recordTextDigest(text, digestFields(kind), kind.format);
+    const { resolveSigningKey, sealRecord, SealError } = await import("./trust/seal.js");
+    let seal;
+    try {
+        const key = resolveSigningKey(sign, cwd);
+        try {
+            seal = { ...sealRecord(key.file, { record: id, digest, author, state }) };
+        }
+        finally {
+            key.cleanup();
+        }
+    }
+    catch (err) {
+        if (err instanceof SealError)
+            throw new RecordWriteError("record-sign-failed", err.message);
+        throw err;
+    }
+    const sealed = replaceFields(text, { [RECORD_SEAL_FIELD]: seal }, { ...data, [RECORD_SEAL_FIELD]: seal });
+    if (sealed === undefined)
+        throw new RecordWriteError("record-unparseable", `the ${RECORD_SEAL_FIELD} field can't be written into ${id} without changing the rest of the file`);
+    if (recordTextDigest(sealed, digestFields(kind), kind.format) !== digest) {
+        throw new Error(`sealing ${id} moved its digest; the seal block and the digest rule disagree`);
+    }
+    return { text: sealed, seal };
+}
+/**
+ * What to do instead of changing a closed record. A supersedes link is
+ * advice only when the kind's schema has the field: the session schema has
+ * none, so a closed session is followed by a new session (#2693).
+ */
+function closedAdvice(o, id, supersede) {
+    const { kind, schema } = o.loaded;
+    if (kind.session)
+        return `A closed session is sealed and stays as it is: open a new session for what follows, with chant workspace records new ${o.view.file}`;
+    const props = schema.properties !== null && typeof schema.properties === "object" ? schema.properties : {};
+    if (kind.supersedes && (schema.additionalProperties !== false || kind.supersedes.field in props))
+        return `Write a new record that supersedes it: ${supersede}`;
+    return `Write a new record in its place with chant workspace records new ${o.view.file}; the ${kind.name} schema has no field that links it to ${id}`;
+}
+/**
+ * The opening revision a session lacks (#2693): when the kind names one and
+ * the record holds null there, HEAD, once the repository has a commit.
+ * Every write to the session fills it.
+ */
+export function openedRevFill(kind, data, root) {
+    const f = kind.session?.openedRev;
+    if (f === undefined || data[f] !== null)
+        return {};
+    const head = headCommit(root);
+    return head === null ? {} : { [f]: head };
+}
+/** Keys in the schema's `required` order, then its `properties` order, then the rest as given. */
+export function schemaOrder(data, schema) {
+    const required = Array.isArray(schema.required) ? schema.required.filter((k) => typeof k === "string") : [];
+    const props = schema.properties !== null && typeof schema.properties === "object" ? Object.keys(schema.properties) : [];
+    const order = [...new Set([...required, ...props])];
+    const keys = Object.keys(data);
+    return [...order.filter((k) => keys.includes(k)), ...keys.filter((k) => !order.includes(k))];
+}
+export function pick(data, keys) {
+    return Object.fromEntries(keys.map((k) => [k, data[k]]));
+}
+export function abs(o, path) {
+    return join(o.root, ...path.split("/"));
+}
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function failure(schema, err) {
+    if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError || err instanceof IdentityError || err instanceof WriteLockError) {
+        const conflict = err instanceof RecordWriteError ? err.conflict : undefined;
+        return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code, message: err.message }, ...(conflict ? { conflict } : {}) };
+    }
+    throw err;
+}
+// ── records new ──────────────────────────────────────────────────────────────
+const ALLOCATABLE = /^([A-Za-z][A-Za-z0-9]*)-([0-9]+)$/;
+/**
+ * The next id: `<prefix>-<n>`, one above the highest number any record in the
+ * directory has with that prefix, padded to at least three digits, or to the
+ * widest number those records use. Ids come from the records' own id field
+ * and, for a file that can't be read, from its name, so an id in use is never
+ * handed out again. The shape is derived from the records, with the prefix's
+ * case kept: a work kind's `W-001` and `W-002` give `W-003` (#2683), and a
+ * decision's `ws-052` gives `ws-053`. The kind's schema still judges the id
+ * written. Without `prefix`, every record must share one prefix.
+ */
+export function allocateId(entries, prefix, kind) {
+    const seen = [];
+    for (const e of entries) {
+        const stem = e.id ?? posix.basename(e.path).match(/^([A-Za-z][A-Za-z0-9]*-[0-9]+)/)?.[1] ?? null;
+        const m = stem?.match(ALLOCATABLE);
+        if (m)
+            seen.push({ prefix: m[1], digits: m[2] });
+    }
+    if (prefix === undefined) {
+        const prefixes = [...new Set(seen.map((s) => s.prefix))];
+        if (prefixes.length !== 1) {
+            throw new RecordWriteError("record-id-unallocatable", prefixes.length === 0
+                ? `no ${kind} record has an id of the form <prefix>-<number> to follow; pass --prefix <prefix>, or give the id in the fields`
+                : `the ${kind} records use the prefixes ${prefixes.join(", ")}; pass --prefix with one of them, or give the id in the fields`);
+        }
+        prefix = prefixes[0];
+    }
+    const mine = seen.filter((s) => s.prefix === prefix);
+    const max = mine.reduce((m, s) => Math.max(m, Number(s.digits)), 0);
+    const width = Math.max(3, ...mine.map((s) => s.digits.length));
+    return `${prefix}-${String(max + 1).padStart(width, "0")}`;
+}
+/** `fields` with the channel's author and source laid over them (#2707). `isNew` for `records new`. */
+function applyChannel(o, fields, opts, isNew, flag) {
+    const { kind } = o.loaded;
+    const out = { ...fields };
+    const through = opts.through;
+    if (isNew && through?.opensInitial && kind.states && kind.stateField !== undefined) {
+        const first = kind.states[0];
+        const state = out[kind.stateField];
+        if (state === undefined)
+            out[kind.stateField] = first;
+        else if (state !== first) {
+            throw new RecordWriteError("record-state-not-initial", `a new ${kind.name} opens ${first}, and the fields give ${kind.stateField} ${JSON.stringify(state)}: write it ${first}, and let the person who decides it move it on with a review or an amendment`);
+        }
+    }
+    if (opts.by !== undefined) {
+        if (opts.by.trim() === "")
+            throw new RecordWriteError("write-usage-invalid", "by needs the name of the person or agent that proposed or decided");
+        // A new record that opens in the kind's first state is a proposal, when the kind opts in with proposedBy (#2756):
+        // by names the proposer, kept apart from reviews.decider, which stays null until the record is decided.
+        const opensInitial = isNew && !!kind.states && kind.stateField !== undefined && (out[kind.stateField] === undefined || out[kind.stateField] === kind.states[0]);
+        if (kind.proposedBy && opensInitial) {
+            const f = kind.proposedBy.field;
+            if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
+                throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one proposer`);
+            }
+            out[f] = opts.by;
+        }
+        else {
+            if (!kind.reviews)
+                throw new RecordWriteError("write-usage-invalid", `by names a record's author, the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`);
+            const f = kind.reviews.decider;
+            if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
+                throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one author`);
+            }
+            out[f] = opts.by;
+        }
+    }
+    if (!through)
+        return out;
+    if (kind.source && (isNew || kind.source.field in out)) {
+        const f = kind.source.field;
+        const block = out[f];
+        if (block === undefined || block === null)
+            out[f] = { ...through.source };
+        else if (typeof block === "object" && !Array.isArray(block))
+            out[f] = { ...block, ...through.source };
+    }
+    return out;
+}
+/** `records new`: write one new record from validated fields, sealed by its author with `sign`. Holds the write lock (#3173). */
+export async function newRecord(opts) {
+    try {
+        return await withWriteLock(opts.cwd, writeWho("records new", opts), opts.dryRun, () => newRecordLocked(opts));
+    }
+    catch (err) {
+        return failure(RECORDS_NEW_SCHEMA_ID, err);
+    }
+}
+async function newRecordLocked(opts) {
+    try {
+        if (opts.prefix !== undefined && !/^[A-Za-z][A-Za-z0-9]*$/.test(opts.prefix)) {
+            throw new RecordWriteError("write-usage-invalid", `--prefix takes letters and digits, starting with a letter, not ${JSON.stringify(opts.prefix)}`);
+        }
+        const o = await open(opts.kind, opts.cwd, { contentAddressed: true });
+        const scope = refuseOutOfScope(o, "new", opts.cwd, opts);
+        const fields = applyChannel(o, parseFields(opts.fields, "--from"), opts, true, "--from");
+        const { kind, schema } = o.loaded;
+        refuseUnidentifiedAuthors(scope, kind, fields, "--from", opts.agent);
+        refuseSealField(o, fields, "--from");
+        refuseRevisionFields(kind, fields, {}, "--from");
+        if (isContentAddressed(kind))
+            return await newContentAddressed(o, fields, opts);
+        const idField = kind.idField;
+        const before = await readAll(o, o.source);
+        const given = fields[idField];
+        let id;
+        if (given === undefined) {
+            id = allocateId(before, opts.prefix, kind.name);
+        }
+        else {
+            if (typeof given !== "string" || given === "")
+                throw new RecordWriteError("write-input-invalid", `${idField} must be a non-empty string when it is given`);
+            const taken = before.find((e) => e.id === given || posix.basename(e.path).startsWith(`${given}-`) || posix.basename(e.path) === `${given}.md`);
+            if (taken)
+                throw new RecordWriteError("record-id-taken", `id ${given} is already used by ${taken.path}; ids are never reused, so leave ${idField} out to have the next one allocated`);
+            id = given;
+        }
+        refuseHarvestedDecision(kind, fields);
+        // A session records the commit it opened at (#2693): HEAD now, or null before the first commit.
+        const opened = kind.session?.openedRev ? { [kind.session.openedRev]: headCommit(o.root) } : {};
+        const full = { ...fields, ...opened, [idField]: id };
+        const data = pick(full, schemaOrder(full, schema));
+        const title = typeof data.title === "string" ? data.title : "";
+        const match = new RegExp(kind.location.match);
+        const names = [slug(title) ? `${id}-${slug(title)}.md` : null, `${id}.md`].filter((n) => n !== null);
+        const name = names.find((n) => match.test(n));
+        if (!name)
+            throw new RecordWriteError("record-path-unmatched", `the kind's location.match ${kind.location.match} matches none of ${names.join(", ")}`);
+        const path = o.dirRel === "." ? name : `${o.dirRel}/${name}`;
+        if (o.source.list(o.dirRel)?.includes(name))
+            throw new RecordWriteError("record-id-taken", `${path} already exists`);
+        let text = renderRecord(data, title ? `\n# ${title}\n` : "");
+        let seal;
+        if (opts.sign !== undefined)
+            ({ text, seal } = await sealAuthor(o, text, data, id, opts.sign, opts.cwd));
+        ({ text } = sealClosed(o, text, seal ? { ...data, [RECORD_SEAL_FIELD]: seal } : data, id));
+        const written = await validatedEntry(o, before, path, text);
+        await refuseRatifyBelowQuorum(o, written, id);
+        const warnings = written.warnings;
+        if (!opts.dryRun) {
+            writeFileSync(abs(o, path), text, { flag: "wx" });
+            noteWrites(o.root, [{ path, text }], writeWho("records new", opts));
+        }
+        return {
+            $schema: RECORDS_NEW_SCHEMA_ID,
+            contract: RECORDS_WRITE_CONTRACT_VERSION,
+            kind: o.view,
+            path,
+            id,
+            ...(seal ? { seal } : {}),
+            dryRun: !!opts.dryRun,
+            warnings,
+            digest: written.digest,
+            ...(opts.dryRun ? { text } : {}),
+        };
+    }
+    catch (err) {
+        return failure(RECORDS_NEW_SCHEMA_ID, err);
+    }
+}
+/**
+ * `records new` on a content-addressed JSON kind (ws-053, ws-082), such as
+ * the reference workspace's evidence: the fields, in the schema's order, as
+ * JSON with two-space indents and a final newline, in a file named for the
+ * SHA-256 of those bytes. The id is that hash, so the fields give no id, and
+ * the record never changes afterwards.
+ */
+async function newContentAddressed(o, fields, opts) {
+    const { kind, schema } = o.loaded;
+    if (opts.prefix !== undefined)
+        throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind's ids are the sha256 of each record's bytes, so --prefix allocates nothing`);
+    if (opts.sign !== undefined)
+        throw new RecordWriteError("write-usage-invalid", `the ${kind.name} kind names no author to seal: its records are named for the sha256 of their bytes`);
+    const data = pick(fields, schemaOrder(fields, schema));
+    const text = `${JSON.stringify(data, null, 2)}\n`;
+    const id = createHash("sha256").update(text, "utf-8").digest("hex");
+    const name = `${id}.json`;
+    if (!new RegExp(kind.location.match).test(name))
+        throw new RecordWriteError("record-path-unmatched", `the kind's location.match ${kind.location.match} does not match ${name}`);
+    const path = o.dirRel === "." ? name : `${o.dirRel}/${name}`;
+    if (o.source.list(o.dirRel)?.includes(name))
+        throw new RecordWriteError("record-id-taken", `${path} already exists, with the same bytes: the record is already written`);
+    const before = await readAll(o, o.source);
+    const written = await validatedEntry(o, before, path, text);
+    if (!opts.dryRun) {
+        writeFileSync(abs(o, path), text, { flag: "wx" });
+        noteWrites(o.root, [{ path, text }], writeWho("records new", opts));
+    }
+    return {
+        $schema: RECORDS_NEW_SCHEMA_ID,
+        contract: RECORDS_WRITE_CONTRACT_VERSION,
+        kind: o.view,
+        path,
+        id,
+        dryRun: !!opts.dryRun,
+        warnings: written.warnings,
+        digest: written.digest,
+        ...(opts.dryRun ? { text } : {}),
+    };
+}
+/**
+ * `records amend`: set top-level fields of one record. A record in a closed
+ * state never changes. With approval ranks, a record ranked above 0 (such as
+ * a decided decision) changes in place only in its state, to one ranked at
+ * least as high, its pins field and its reviews: anything else is a new
+ * decision, written as a record that supersedes it (#2524 D4).
+ *
+ * An amendment moves the record's digest, so an author seal no longer holds
+ * (#2688). With `sign` the record is sealed again over the new text; without
+ * it, an amendment that moves the digest removes the seal and says so in
+ * `sealDropped`, so a record never carries a seal that fails. One that
+ * changes only the reviews leaves the digest, and the seal, as they were.
+ * `--sign` with nothing to change seals the record as it is.
+ */
+export async function amendRecord(opts) {
+    try {
+        refuseExpectShape(opts.expect);
+        return await withWriteLock(opts.cwd, writeWho("records amend", opts), opts.dryRun, () => amendRecordLocked(opts));
+    }
+    catch (err) {
+        return failure(RECORDS_AMEND_SCHEMA_ID, err);
+    }
+}
+async function amendRecordLocked(opts) {
+    try {
+        const o = await open(opts.kind, opts.cwd);
+        const scope = refuseOutOfScope(o, "amend", opts.cwd, opts);
+        const given = applyChannel(o, parseFields(opts.fields, "--set"), opts, false, "--set");
+        const { kind } = o.loaded;
+        refuseUnidentifiedAuthors(scope, kind, given, "--set", opts.agent);
+        refuseSealField(o, given, "--set");
+        const before = await readAll(o, o.source);
+        const target = findRecord(before, opts.id, kind.name);
+        refuseStale(o, target, opts.id, opts.expect);
+        const old = target.data;
+        refuseRevisionFields(kind, given, old, "--set");
+        const isClosed = target.state !== null && (kind.closedStates ?? []).includes(target.state);
+        const patch = { ...(isClosed ? {} : openedRevFill(kind, old, o.root)), ...given };
+        const added = Object.keys(patch).filter((k) => !(k in old));
+        const merged = pick({ ...old, ...patch }, [...Object.keys(old), ...schemaOrder(pick(patch, added), o.loaded.schema)]);
+        const changed = Object.keys(merged).filter((k) => stableJson(old[k]) !== stableJson(merged[k]));
+        if (changed.includes(kind.idField)) {
+            throw new RecordWriteError("amend-id-immutable", `${kind.idField} never changes: ids are never renumbered. Write a new record that supersedes ${opts.id} instead`);
+        }
+        const state = target.state;
+        const link = kind.supersedes?.key === undefined ? JSON.stringify(opts.id) : `[{"${kind.supersedes.key}": "${opts.id}"}]`;
+        const supersede = kind.supersedes ? `chant workspace records new with ${kind.supersedes.field}: ${link}` : `chant workspace records new`;
+        if ((changed.length > 0 || opts.sign !== undefined) && state !== null && (kind.closedStates ?? []).includes(state)) {
+            throw new RecordWriteError("record-closed", `${opts.id} is ${state}, a closed state, so nothing in it changes. ${closedAdvice(o, opts.id, supersede)}`);
+        }
+        const rank = (s) => (typeof s === "string" ? (kind.approval?.[s] ?? 0) : 0);
+        if (changed.length > 0 && kind.approval && rank(state) > 0) {
+            const allowed = [kind.stateField, kind.pins?.field, kind.reviews?.field].filter((f) => typeof f === "string");
+            const stronger = (kind.states ?? []).filter((s) => rank(s) >= rank(state));
+            const bad = changed.filter((k) => !allowed.includes(k));
+            if (bad.length > 0) {
+                throw new RecordWriteError("amend-supersede-instead", `${opts.id} is ${state}, so ${bad.join(", ")} can't change in place: only ${allowed.join(", ")} may. Write the change as a new record that supersedes it (${supersede}); it replaces ${opts.id} once it is ${stronger.filter((s) => rank(s) > 0).join(" or ")}`);
+            }
+            if (kind.stateField !== undefined && changed.includes(kind.stateField) && rank(merged[kind.stateField]) < rank(state)) {
+                throw new RecordWriteError("amend-supersede-instead", `${opts.id} is ${state}, and ${JSON.stringify(merged[kind.stateField])} is approved less strongly: a state only moves to ${stronger.join(", ")}. Write a new record that supersedes it (${supersede})`);
+            }
+        }
+        // Only the changed fields' blocks are rewritten, so the rest of the file keeps its bytes.
+        const current = o.source.read(target.path);
+        let text = changed.length === 0 ? current : (replaceFields(current, pick(merged, changed), merged) ?? renderRecord(merged, bodyOf(current)));
+        // The author seal (#2688): signed again over the new text, or dropped once the text moves.
+        let seal;
+        let sealDropped;
+        const sealable = kind.reviews !== undefined && RECORD_SEAL_FIELD in old;
+        if (opts.sign !== undefined) {
+            ({ text, seal } = await sealAuthor(o, text, merged, opts.id, opts.sign, opts.cwd));
+            merged[RECORD_SEAL_FIELD] = seal;
+        }
+        else if (sealable &&
+            (recordTextDigest(text, digestFields(kind), kind.format) !== recordTextDigest(current, digestFields(kind), kind.format) ||
+                (kind.stateField !== undefined && stableJson(old[kind.stateField]) !== stableJson(merged[kind.stateField])))) {
+            // The seal signs the state as well as the digest, and a kind with reviews.ratified leaves the state out of the digest (#2873).
+            const signer = old[RECORD_SEAL_FIELD]?.signer;
+            delete merged[RECORD_SEAL_FIELD];
+            const dropped = removeField(text, RECORD_SEAL_FIELD, merged);
+            if (dropped === undefined)
+                throw new RecordWriteError("record-unparseable", `${target.path}: the ${RECORD_SEAL_FIELD} block can't be removed without changing the rest of the file`);
+            text = dropped;
+            sealDropped = `${opts.id} was sealed${typeof signer === "string" ? ` by ${signer}` : ""}, and the amendment moves its digest or its state, so the seal was removed: seal it again with records amend ${opts.id} --sign`;
+        }
+        if (stableJson(old[RECORD_SEAL_FIELD]) !== stableJson(merged[RECORD_SEAL_FIELD]))
+            changed.push(RECORD_SEAL_FIELD);
+        // Entering a closed state seals the whole record, last (#2546, ws-063).
+        if (changed.length > 0 && kind.seal && !kind.session) {
+            const closedSeal = sealClosed(o, text, merged, opts.id);
+            text = closedSeal.text;
+            if (stableJson(old[kind.seal.field]) !== stableJson(closedSeal.data[kind.seal.field]))
+                changed.push(kind.seal.field);
+        }
+        let warnings = target.warnings;
+        let digest = target.digest;
+        if (changed.length > 0) {
+            const written = await validatedEntry(o, before, target.path, text);
+            if (kind.stateField !== undefined && changed.includes(kind.stateField))
+                await refuseRatifyBelowQuorum(o, written, opts.id);
+            warnings = written.warnings;
+            digest = written.digest;
+        }
+        if (!opts.dryRun && changed.length > 0) {
+            writeFileAtomic(abs(o, target.path), text);
+            noteWrites(o.root, [{ path: target.path, text }], writeWho("records amend", opts));
+        }
+        return {
+            $schema: RECORDS_AMEND_SCHEMA_ID,
+            contract: RECORDS_WRITE_CONTRACT_VERSION,
+            kind: o.view,
+            path: target.path,
+            id: opts.id,
+            changed,
+            ...(seal ? { seal } : {}),
+            ...(sealDropped ? { sealDropped } : {}),
+            dryRun: !!opts.dryRun,
+            warnings,
+            digest,
+            ...(opts.dryRun ? { text } : {}),
+        };
+    }
+    catch (err) {
+        return failure(RECORDS_AMEND_SCHEMA_ID, err);
+    }
+}
+/**
+ * `records review`: append one verdict to a record's reviews, with the date
+ * and the digest of the record text it judged ({@link recordTextDigest}).
+ * With `sign`, the verdict carries a seal: an ssh signature over the record
+ * id, the digest, the verdict, the reviewer and the date (`trust/seal.ts`).
+ */
+export async function reviewRecord(opts) {
+    try {
+        refuseExpectShape(opts.expect);
+        return await withWriteLock(opts.cwd, writeWho("records review", opts), opts.dryRun, () => reviewRecordLocked(opts));
+    }
+    catch (err) {
+        return failure(RECORDS_REVIEW_SCHEMA_ID, err);
+    }
+}
+async function reviewRecordLocked(opts) {
+    try {
+        if (!VERDICTS.includes(opts.verdict)) {
+            throw new RecordWriteError("write-usage-invalid", `--verdict takes ${VERDICTS.join(", ")}, not ${JSON.stringify(opts.verdict)}`);
+        }
+        if (opts.by.trim() === "")
+            throw new RecordWriteError("write-usage-invalid", "--by needs the reviewer's name");
+        if (opts.session !== undefined && opts.session === "")
+            throw new RecordWriteError("write-usage-invalid", "--session needs a session id");
+        const o = await open(opts.kind, opts.cwd);
+        refuseOutOfScope(o, "review", opts.cwd, opts);
+        const { kind } = o.loaded;
+        if (!kind.reviews) {
+            throw new RecordWriteError("review-unsupported", `the ${kind.name} kind declares no reviews field, so its records take no review`);
+        }
+        const field = kind.reviews.field;
+        const before = await readAll(o, o.source);
+        const target = findRecord(before, opts.id, kind.name);
+        refuseStale(o, target, opts.id, opts.expect);
+        if (target.state !== null && (kind.closedStates ?? []).includes(target.state)) {
+            throw new RecordWriteError("record-closed", `${opts.id} is ${target.state}, a closed state, so it takes no more reviews`);
+        }
+        if (opts.verdict === "dissent" && !(opts.note ?? "").trim()) {
+            throw new RecordWriteError("review-note-required", `a dissent needs a reason: pass --note <text> with the concern`);
+        }
+        const inSession = opts.session !== undefined ? await openSession(o, opts.session, opts.cwd) : undefined;
+        // The verdict is appended to the session too, so the session's kind must be in scope as well.
+        if (inSession)
+            refuseOutOfScope(inSession.so, "review", opts.cwd, opts);
+        const reviews = target.data[field] ?? [];
+        if (!Array.isArray(reviews))
+            throw new RecordWriteError("record-schema-invalid", `${target.path}: ${field} is not a list`);
+        const current = o.source.read(target.path);
+        const review = {
+            reviewer: opts.by,
+            verdict: opts.verdict,
+            ...(opts.note !== undefined ? { note: opts.note } : {}),
+            on: opts.on ?? today(),
+            digest: recordTextDigest(current, digestFields(kind), kind.format),
+            ...(opts.session !== undefined ? { session: opts.session } : {}),
+        };
+        if (opts.sign !== undefined)
+            review.seal = await seal(opts.sign, opts.cwd, { record: opts.id, digest: review.digest, verdict: opts.verdict, reviewer: opts.by, on: review.on });
+        // Only the reviews block changes, so the digest the verdict names stays the record's digest (#2672),
+        // and a record's author seal, which the digest leaves out too, still holds (#2688).
+        const list = [...reviews, review];
+        const text = replaceFields(current, { [field]: list }, { ...target.data, [field]: list });
+        if (text === undefined)
+            throw new RecordWriteError("record-unparseable", `${target.path}: the ${field} block can't be rewritten in place without changing the rest of the file`);
+        const writtenEntry = await validatedEntry(o, before, target.path, text);
+        const warnings = writtenEntry.warnings;
+        // The same verdict on the session's own list (#2693), validated with the review in place, so the two lists never differ.
+        let session;
+        if (inSession) {
+            const { so, before: sessions, target: st } = inSession;
+            const decl = so.loaded.kind.session;
+            const verdicts = st.data[decl.verdicts] ?? [];
+            if (!Array.isArray(verdicts))
+                throw new RecordWriteError("record-schema-invalid", `${st.path}: ${decl.verdicts} is not a list`);
+            const verdict = { record: opts.id, principal: opts.by, verdict: opts.verdict, digest: review.digest };
+            const set = { ...openedRevFill(so.loaded.kind, st.data, so.root), [decl.verdicts]: [...verdicts, verdict] };
+            const sText = replaceFields(so.source.read(st.path), set, { ...st.data, ...set });
+            if (sText === undefined)
+                throw new RecordWriteError("record-unparseable", `${st.path}: the ${decl.verdicts} block can't be rewritten in place without changing the rest of the file`);
+            await validateWrite(so, sessions, st.path, sText, overlay(o.source, target.path, text));
+            session = { path: st.path, text: sText, out: { id: opts.session, path: st.path, verdict, ...(opts.dryRun ? { text: sText } : {}) } };
+        }
+        if (!opts.dryRun) {
+            writeFileAtomic(abs(o, target.path), text);
+            if (session)
+                writeFileAtomic(abs(o, session.path), session.text);
+            noteWrites(o.root, [{ path: target.path, text }, ...(session ? [{ path: session.path, text: session.text }] : [])], writeWho("records review", opts));
+        }
+        return {
+            $schema: RECORDS_REVIEW_SCHEMA_ID,
+            contract: RECORDS_WRITE_CONTRACT_VERSION,
+            kind: o.view,
+            path: target.path,
+            id: opts.id,
+            review,
+            ...(session ? { session: session.out } : {}),
+            dryRun: !!opts.dryRun,
+            warnings,
+            digest: writtenEntry.digest,
+            ...(opts.dryRun ? { text } : {}),
+        };
+    }
+    catch (err) {
+        return failure(RECORDS_REVIEW_SCHEMA_ID, err);
+    }
+}
+/**
+ * The open session `id` of a session kind whose subjects are the kind `o`
+ * writes (#2693), found through the workspace declaration. Refused with
+ * session-unknown when no such session exists, and session-not-open when it
+ * is in a closed state.
+ */
+async function openSession(o, id, cwd) {
+    const kinds = await sessionKindsFor(o.loaded.file, cwd);
+    for (const k of kinds) {
+        const so = await open(k.file, cwd);
+        const before = await readAll(so, so.source);
+        if (!before.some((e) => e.id === id))
+            continue;
+        const target = findRecord(before, id, so.view.name);
+        if (target.data === null)
+            throw new RecordWriteError("record-unparseable", `session ${id} (${target.path}) can't be read, so the verdict can't be added to it`);
+        if (target.state !== null && (so.loaded.kind.closedStates ?? []).includes(target.state)) {
+            throw new RecordWriteError("session-not-open", `session ${id} is ${target.state}, so it takes no more verdicts: give the verdict in an open session, or without --session`);
+        }
+        return { so, before, target };
+    }
+    throw new RecordWriteError("session-unknown", kinds.length === 0
+        ? `no session kind the workspace declaration names has ${o.view.file} as its subjects, so there is no session ${id} to give the verdict in`
+        : `no ${kinds.map((k) => k.kind.name).join(" or ")} record has id ${id}`);
+}
+/** A seal over one verdict, or a refusal with review-sign-failed. Loaded only when --sign is given. */
+async function seal(sign, cwd, v) {
+    const { resolveSigningKey, sealVerdict, SealError } = await import("./trust/seal.js");
+    try {
+        const key = resolveSigningKey(sign, cwd);
+        try {
+            return { ...sealVerdict(key.file, v) };
+        }
+        finally {
+            key.cleanup();
+        }
+    }
+    catch (err) {
+        if (err instanceof SealError)
+            throw new RecordWriteError("review-sign-failed", err.message);
+        throw err;
+    }
+}
+// ── The command ──────────────────────────────────────────────────────────────
+export const WRITE_USAGE = [
+    "chant workspace records new [<kind file or declared kind>] --from <file|-> [--prefix <prefix>] [--by <name>] [--sign [<key file>]] [--dry-run]",
+    "chant workspace records amend <id> [--kind <kind file>] --set <file|-> [--expect <digest>] [--sign [<key file>]] [--dry-run]",
+    "chant workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--expect <digest>] [--sign [<key file>]] [--dry-run]",
+    "chant workspace records close <session id> [--kind <session kind file>] [--expect <digest>] [--dry-run]",
+].join("\n");
+function usage(schema, message) {
+    return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message: `${message}\n${WRITE_USAGE}` } };
+}
+/**
+ * The kind a write goes through when none is named (#2680): the one record
+ * kind the declaration nearest above `cwd` names. None declared keeps the
+ * message the verb has always given; several are refused, since a write
+ * never guesses which kind it means.
+ */
+export function declaredWriteKind(schema, cwd, missing) {
+    let kinds;
+    try {
+        kinds = declaredKindFiles(cwd);
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        return usage(schema, `${missing}; the declaration can't name one: ${err.code}: ${err.describe()}`);
+    }
+    if (kinds.length === 0)
+        return usage(schema, missing);
+    if (kinds.length > 1) {
+        return usage(schema, `the declaration names ${kinds.length} record kinds (${kinds.map((k) => k.declared.path).join(", ")}), so name the one to write with --kind`);
+    }
+    return kinds[0].file;
+}
+/**
+ * The kind file a write names: `arg` itself when it is a file, or else the
+ * declared record kind it names (#2683), by the name the declaration gives it
+ * or its file's name without `.kind.mjs`, so `records new work` finds
+ * `work/work.kind.mjs`. Anything else is returned as given, and loading it
+ * fails with kind-unreadable.
+ */
+export function resolveWriteKind(arg, cwd) {
+    try {
+        if (statSync(resolve(cwd, arg)).isFile())
+            return arg;
+    }
+    catch {
+        // Not a file: try the declared kinds.
+    }
+    let kinds;
+    try {
+        kinds = declaredKindFiles(cwd);
+    }
+    catch {
+        return arg;
+    }
+    const hit = kinds.filter((k) => (k.declared.name ?? posix.basename(k.declared.path).replace(/(?:\.kind)?\.[cm]?[jt]s$/, "")) === arg);
+    return hit.length === 1 ? hit[0].file : arg;
+}
+/** The text of `--from` or `--set`: a file, or standard input for `-`. */
+function readInput(schema, flag, value, cwd) {
+    if (value === undefined || value === "")
+        return usage(schema, `${flag} <file|-> is required`);
+    try {
+        return readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
+    }
+    catch (err) {
+        return {
+            $schema: schema,
+            contract: RECORDS_WRITE_CONTRACT_VERSION,
+            error: { code: "write-input-invalid", message: `${flag} ${value} could not be read: ${err instanceof Error ? err.message : String(err)}` },
+        };
+    }
+}
+/**
+ * The session kind `records close` goes through when none is named (#2693):
+ * the one session kind the declaration names.
+ */
+export async function declaredSessionKind(schema, cwd) {
+    const kinds = (await findSessionKinds(cwd)).map((k) => k.file);
+    if (kinds.length === 1)
+        return kinds[0];
+    if (kinds.length === 0)
+        return usage(schema, "--kind <session kind file> is required: the declaration names no session kind");
+    return usage(schema, `the declaration names ${kinds.length} session kinds (${kinds.join(", ")}), so name the one to close with --kind`);
+}
+/** `chant workspace records new|amend|review|close`. Prints one JSON document; exits 0 when it wrote, or would have with --dry-run. */
+export async function runRecordsWrite(ctx) {
+    const { args } = ctx;
+    const cwd = process.cwd();
+    const verb = args.extraPositional;
+    // The agent session the write is made in (#2548): set by the harness that runs the agent.
+    const agent = process.env[AGENT_ENV] || undefined;
+    const print = (doc) => {
+        console.log(JSON.stringify(doc, null, 2));
+        return "error" in doc ? 1 : 0;
+    };
+    if (verb === "close") {
+        const { closeRecord, RECORDS_CLOSE_SCHEMA_ID } = await import("./records-close.js");
+        if (args.sign !== undefined)
+            return print(usage(RECORDS_CLOSE_SCHEMA_ID, "--sign is not taken by close: the seal close writes is the digest of the session text"));
+        const id = args.extraPositional2;
+        if (!id)
+            return print(usage(RECORDS_CLOSE_SCHEMA_ID, "close needs the session's id"));
+        const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : await declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
+        if (typeof kind !== "string")
+            return print(kind);
+        return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd, agent, expect: args.expect }));
+    }
+    if (verb === "new") {
+        const named = args.extraPositional2 ?? args.kind;
+        const kind = named !== undefined ? resolveWriteKind(named, cwd) : declaredWriteKind(RECORDS_NEW_SCHEMA_ID, cwd, "new needs the kind file");
+        if (typeof kind !== "string")
+            return print(kind);
+        if (args.expect !== undefined)
+            return print(usage(RECORDS_NEW_SCHEMA_ID, "--expect is not taken by new: a new record has no digest yet, and its id is allocated under the write lock"));
+        const input = readInput(RECORDS_NEW_SCHEMA_ID, "--from", args.migrateFrom, cwd);
+        if (typeof input !== "string")
+            return print(input);
+        return print(await newRecord({ kind, fields: input, prefix: args.prefix, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
+    }
+    const schema = verb === "amend" ? RECORDS_AMEND_SCHEMA_ID : RECORDS_REVIEW_SCHEMA_ID;
+    const id = args.extraPositional2;
+    if (!id)
+        return print(usage(schema, `${verb} needs the record's id`));
+    const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : declaredWriteKind(schema, cwd, "--kind <kind file> is required");
+    if (typeof kind !== "string")
+        return print(kind);
+    if (verb === "amend") {
+        if (args.by !== undefined)
+            return print(usage(schema, "--by is not taken by amend: set decided_by, or a kind's proposedBy field, with --set"));
+        const input = readInput(schema, "--set", args.set, cwd);
+        if (typeof input !== "string")
+            return print(input);
+        return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd, agent, expect: args.expect }));
+    }
+    if (args.verdict === undefined)
+        return print(usage(schema, "--verdict agree|dissent|abstain is required"));
+    if (args.by === undefined)
+        return print(usage(schema, "--by <principal> is required"));
+    return print(await reviewRecord({ kind, id, verdict: args.verdict, by: args.by, note: args.note, session: args.session, sign: args.sign, dryRun: args.dryRun, cwd, agent, expect: args.expect }));
+}