@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/records-write.ts

@@ -19,12 +19,27 @@
  * 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 { dirname, join, posix, relative, resolve } from "node:path";
 import type { CommandContext } from "../cli/registry";
@@ -35,6 +50,7 @@ import {
   loadRecordKind,
   parseFrontMatter,
   readRecords,
+  readSessionSubjects,
   RECORD_REASON_CODES,
   RecordReadError,
   RECORD_SEAL_FIELD,
@@ -50,8 +66,10 @@ import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
 import { workingTree } from "./tree";
-import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError } from "./write-scope";
+import { AGENT_ENV, refuseRecordWrite, WRITE_SCOPE_CODES, WriteScopeError, type ScopeSource } from "./write-scope";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity";
 import type { WriteVerb } from "./declaration";
+import { lastWriteReader, noteWrites, withWriteLock, writeFileAtomic, WriteLockError, WRITE_LOCK_CODES, type LastWrite, type WriteLockWho } from "./write-lock";
 
 // ── Contract ─────────────────────────────────────────────────────────────────
 
@@ -77,7 +95,9 @@ export const NEW_ERROR_CODES = [
   "source-harvest-not-proposed",
   "record-state-not-initial",
   "ratify-quorum-not-met",
+  ...WRITE_LOCK_CODES,
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -92,7 +112,10 @@ export const AMEND_ERROR_CODES = [
   "amend-supersede-instead",
   "record-sign-failed",
   "ratify-quorum-not-met",
+  "record-conflict",
+  ...WRITE_LOCK_CODES,
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -107,7 +130,10 @@ export const REVIEW_ERROR_CODES = [
   "review-sign-failed",
   "session-unknown",
   "session-not-open",
+  "record-conflict",
+  ...WRITE_LOCK_CODES,
   ...WRITE_SCOPE_CODES,
+  ...IDENTITY_CODES,
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -123,12 +149,28 @@ export class RecordWriteError extends Error {
   constructor(
     readonly code: WriteErrorCode,
     message: string,
+    /** With record-conflict: the record as it is now. */
+    readonly conflict?: RecordConflict,
   ) {
     super(message);
     this.name = "RecordWriteError";
   }
 }
 
+/**
+ * What a record-conflict refusal says about the record (#3173): the digest
+ * the caller expected, the one it has now, and the last chant write of it
+ * when the journal knows it. The caller re-reads the record and writes again
+ * with `--expect` set to `digest`.
+ */
+export interface RecordConflict {
+  id: string;
+  path: string;
+  expected: string;
+  digest: string;
+  lastWrite: LastWrite | null;
+}
+
 export interface KindView {
   name: string;
   schema: string;
@@ -147,6 +189,12 @@ export interface WriteResult {
   dryRun: boolean;
   /** The written record's warnings, as `records` would report them. */
   warnings: RecordWarning[];
+  /**
+   * The record's digest after the write, as `records --json` reports it
+   * (#3173): what the caller passes as `--expect` to its next write of the
+   * record.
+   */
+  digest: string;
   /** With --dry-run, the whole text the command would write. */
   text?: string;
 }
@@ -155,6 +203,8 @@ export interface WriteFailure<C> {
   $schema: string;
   contract: number;
   error: { code: C; message: string };
+  /** With record-conflict (#3173): the record as it is now. */
+  conflict?: RecordConflict;
 }
 
 /** A record's author seal as `new` and `amend` write it with `--sign` (#2688). */
@@ -335,15 +385,26 @@ export interface Opened {
   dirRel: string;
 }
 
-export async function open(kind: string, cwd: string): Promise<Opened> {
+/** 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: LoadedRecordKind["kind"]): boolean {
+  return kind.format === "json" && kind.idFrom === "sha256";
+}
+
+export async function open(kind: string, cwd: string, opts: { contentAddressed?: boolean } = {}): Promise<Opened> {
   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. A JSON or
-  // content-addressed kind (ws-053) is read by records, and written by its own tool.
-  if (loaded.kind.format !== "markdown-front-matter" || loaded.kind.idField === undefined) {
+  // 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}`;
-    throw new RecordWriteError("write-usage-invalid", `the ${loaded.kind.name} kind has ${what}, and records new, amend and review write only Markdown front matter records with an idField`);
+    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 {
@@ -361,8 +422,24 @@ export async function open(kind: string, cwd: string): Promise<Opened> {
  * written with `verb`, by the session `agent` names (`CHANT_AGENT`) or the
  * principal `by` names. Throws a {@link WriteScopeError}.
  */
-export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): void {
-  refuseRecordWrite(cwd, { kindName: o.loaded.kind.name, kindFile: o.loaded.file, recordsDir: o.loaded.dir, verb, agent: writer.agent, principal: writer.by });
+export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer: { agent?: string; by?: string }): ScopeSource {
+  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: ScopeSource, kind: Opened["loaded"]["kind"], fields: Record<string, unknown>, flag: string, agent?: string): void {
+  const names = [kind.reviews?.decider, kind.proposedBy?.field]
+    .filter((f): f is string => f !== undefined)
+    .map((f) => fields[f])
+    .filter((v): v is string => typeof v === "string" && v.trim() !== "");
+  refuseUnidentified(source, names, `${flag} author`, { agent });
 }
 
 /**
@@ -372,11 +449,7 @@ export function refuseOutOfScope(o: Opened, verb: WriteVerb, cwd: string, writer
  */
 export async function readAll(o: Opened, source: RecordSource): Promise<RecordEntry[]> {
   const assets = workingTree(o.workspaceRoot === "." ? o.root : join(o.root, ...o.workspaceRoot.split("/")));
-  let subjects: { records: RecordEntry[]; reviews: string } | undefined;
-  if (o.loaded.kind.session) {
-    const subjectKind = await loadRecordKind(resolve(dirname(o.loaded.file), o.loaded.kind.session.subjects.kind), o.root);
-    subjects = { records: (await readRecords(subjectKind, { root: o.root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" };
-  }
+  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;
 }
 
@@ -450,6 +523,35 @@ async function refuseRatifyBelowQuorum(o: Opened, written: RecordEntry, id: stri
   );
 }
 
+/**
+ * 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: Opened, target: RecordEntry, id: string, expect: string | undefined): void {
+  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: string | undefined): void {
+  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: string, opts: { by?: string; agent?: string }): WriteLockWho {
+  return { verb, by: opts.by ?? null, agent: opts.agent ?? null };
+}
+
 export function findRecord(entries: RecordEntry[], id: string, kind: string): RecordEntry & { data: Record<string, unknown> } {
   const hits = entries.filter((e) => e.id === id);
   if (hits.length === 0) throw new RecordWriteError("record-not-found", `no ${kind} record has id ${id}`);
@@ -628,8 +730,9 @@ function today(): string {
 }
 
 export function failure<C>(schema: string, err: unknown): WriteFailure<C> {
-  if (err instanceof RecordWriteError || err instanceof RecordReadError || err instanceof WriteScopeError) {
-    return { $schema: schema, contract: RECORDS_WRITE_CONTRACT_VERSION, error: { code: err.code as C, message: err.message } };
+  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 as C, message: err.message }, ...(conflict ? { conflict } : {}) };
   }
   throw err;
 }
@@ -766,18 +869,28 @@ function applyChannel(o: Opened, fields: Record<string, unknown>, opts: ChannelO
   return out;
 }
 
-/** `records new`: write one new record from validated fields, sealed by its author with `sign`. */
+/** `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: NewRecordOptions & ChannelOptions): Promise<NewDocument> {
+  try {
+    return await withWriteLock(opts.cwd, writeWho("records new", opts), opts.dryRun, () => newRecordLocked(opts));
+  } catch (err) {
+    return failure<NewErrorCode>(RECORDS_NEW_SCHEMA_ID, err);
+  }
+}
+
+async function newRecordLocked(opts: NewRecordOptions & ChannelOptions): Promise<NewDocument> {
   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);
-    refuseOutOfScope(o, "new", opts.cwd, opts);
+    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];
@@ -809,7 +922,10 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
     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" });
+    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,
@@ -819,6 +935,7 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
       ...(seal ? { seal } : {}),
       dryRun: !!opts.dryRun,
       warnings,
+      digest: written.digest,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {
@@ -826,6 +943,43 @@ export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promis
   }
 }
 
+/**
+ * `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: Opened, fields: Record<string, unknown>, opts: NewRecordOptions): Promise<NewDocument> {
+  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 ────────────────────────────────────────────────────────────
 
 export interface AmendRecordOptions {
@@ -839,6 +993,8 @@ export interface AmendRecordOptions {
   sign?: string | true;
   /** The agent session the write is made in (#2548). */
   agent?: string;
+  /** The record's digest the caller last read (#3173): the write is refused with record-conflict when the record has another. */
+  expect?: string;
 }
 
 /**
@@ -856,14 +1012,25 @@ export interface AmendRecordOptions {
  * `--sign` with nothing to change seals the record as it is.
  */
 export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
+  try {
+    refuseExpectShape(opts.expect);
+    return await withWriteLock(opts.cwd, writeWho("records amend", opts), opts.dryRun, () => amendRecordLocked(opts));
+  } catch (err) {
+    return failure<AmendErrorCode>(RECORDS_AMEND_SCHEMA_ID, err);
+  }
+}
+
+async function amendRecordLocked(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
   try {
     const o = await open(opts.kind, opts.cwd);
-    refuseOutOfScope(o, "amend", opts.cwd, opts);
+    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);
@@ -929,12 +1096,17 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
       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));
     }
-    if (!opts.dryRun && changed.length > 0) writeFileSync(abs(o, target.path), text);
     return {
       $schema: RECORDS_AMEND_SCHEMA_ID,
       contract: RECORDS_WRITE_CONTRACT_VERSION,
@@ -946,6 +1118,7 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
       ...(sealDropped ? { sealDropped } : {}),
       dryRun: !!opts.dryRun,
       warnings,
+      digest,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {
@@ -975,6 +1148,8 @@ export interface ReviewRecordOptions {
   sign?: string | true;
   /** The agent session the write is made in (#2548). */
   agent?: string;
+  /** The record's digest the reviewer judged (#3173): the verdict is refused with record-conflict when the record has moved on. */
+  expect?: string;
 }
 
 /**
@@ -984,6 +1159,15 @@ export interface ReviewRecordOptions {
  * id, the digest, the verdict, the reviewer and the date (`trust/seal.ts`).
  */
 export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDocument> {
+  try {
+    refuseExpectShape(opts.expect);
+    return await withWriteLock(opts.cwd, writeWho("records review", opts), opts.dryRun, () => reviewRecordLocked(opts));
+  } catch (err) {
+    return failure<ReviewErrorCode>(RECORDS_REVIEW_SCHEMA_ID, err);
+  }
+}
+
+async function reviewRecordLocked(opts: ReviewRecordOptions): Promise<ReviewDocument> {
   try {
     if (!(VERDICTS as readonly string[]).includes(opts.verdict)) {
       throw new RecordWriteError("write-usage-invalid", `--verdict takes ${VERDICTS.join(", ")}, not ${JSON.stringify(opts.verdict)}`);
@@ -999,6 +1183,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
     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`);
     }
@@ -1025,7 +1210,8 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
     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 warnings = await validateWrite(o, before, target.path, text);
+    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: { path: string; text: string; out: ReviewSession } | undefined;
     if (inSession) {
@@ -1041,8 +1227,9 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       session = { path: st.path, text: sText, out: { id: opts.session!, path: st.path, verdict, ...(opts.dryRun ? { text: sText } : {}) } };
     }
     if (!opts.dryRun) {
-      writeFileSync(abs(o, target.path), text);
-      if (session) writeFileSync(abs(o, session.path), session.text);
+      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,
@@ -1054,6 +1241,7 @@ export async function reviewRecord(opts: ReviewRecordOptions): Promise<ReviewDoc
       ...(session ? { session: session.out } : {}),
       dryRun: !!opts.dryRun,
       warnings,
+      digest: writtenEntry.digest,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {
@@ -1108,9 +1296,9 @@ async function seal(sign: string | true, cwd: string, v: { record: string; diges
 
 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|-> [--sign [<key file>]] [--dry-run]",
-  "chant workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]",
-  "chant workspace records close <session id> [--kind <session kind 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: string, message: string): WriteFailure<"write-usage-invalid"> {
@@ -1204,12 +1392,13 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (!id) return print(usage(RECORDS_CLOSE_SCHEMA_ID, "close needs the session's id"));
     const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : await declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
     if (typeof kind !== "string") return print(kind);
-    return print(await closeRecord({ kind, id, dryRun: args.dryRun, cwd, agent }));
+    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 }));
@@ -1223,11 +1412,11 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (args.by !== undefined) return print(usage(schema, "--by is not taken by amend: set decided_by, or a kind's proposedBy field, with --set"));
     const input = readInput(schema, "--set", args.set, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd, agent }));
+    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 }),
+    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 }),
   );
 }

package/src/workspace/records.schema.json

@@ -124,6 +124,14 @@
         },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "uncommitted": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3160. Whether only the records HEAD doesn't hold were listed (--uncommitted): each record's worktree is then modified or new, checkout is present, and summary's total, valid and invalid count the records listed. Absent from documents written before #3160, which read as false."
+        },
+        "checkout": {
+          "description": "Added in contract 1 by #3160, on a read of the working tree in a git repository; absent under --at and outside git. The branch, head and base the working tree is on, and the records of the kind it has deleted.",
+          "$ref": "#/$defs/checkout"
+        },
         "trust": { "$ref": "#/$defs/trust" },
         "records": {
           "description": "One entry per file the kind locates, sorted by path.",
@@ -145,6 +153,42 @@
           "type": "array",
           "items": { "$ref": "#/$defs/decisionWork" }
         }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "uncommitted": { "const": true } }, "required": ["uncommitted"] },
+          "then": {
+            "required": ["checkout"],
+            "properties": {
+              "checkout": true,
+              "at": { "type": "null" },
+              "records": { "type": "array", "items": { "type": "object", "required": ["worktree"], "properties": { "worktree": { "enum": ["modified", "new"] } } } }
+            }
+          }
+        }
+      ]
+    },
+    "checkout": {
+      "type": "object",
+      "required": ["branch", "head", "base", "baseFrom", "deleted"],
+      "properties": {
+        "branch": { "type": ["string", "null"], "description": "The checked-out branch's short name, such as chant/work/w-12, or null when HEAD is detached." },
+        "head": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id HEAD names, or null before the first commit (every record is then new). Each record's worktree is judged against it."
+        },
+        "base": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The merge base of head and the target branch tip, the commit the branch forked from: what applying the branch would be measured against. The target is --base when given, else origin/HEAD, main or master, as for trust. Null without a head, a target, or common history."
+        },
+        "baseFrom": { "enum": ["flag", "origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." },
+        "deleted": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Record files of the kind that head holds and the working tree no longer has, staged or not, from the repository root with / separators, sorted. A renamed record is here under its old name and in records as new."
+        }
       }
     },
     "workLink": {
@@ -155,6 +199,17 @@
         "state": { "type": ["string", "null"], "description": "The linked record's state as it writes it, or null when no record has the id." }
       }
     },
+    "workAnswer": {
+      "type": "object",
+      "required": ["id", "point", "state", "answer", "answeredBy"],
+      "properties": {
+        "id": { "type": "string", "description": "The answer record's id: the point's name and the first 12 hex digits of its inputs hash." },
+        "point": { "type": ["string", "null"], "description": "The decision point it answers." },
+        "state": { "type": ["string", "null"], "description": "escalated, proposed or answered." },
+        "answer": { "oneOf": [{ "type": "string" }, { "type": "boolean" }, { "type": "null" }], "description": "The answer, or null while there is none." },
+        "answeredBy": { "type": "array", "items": { "type": "string" }, "description": "The people who answered or confirmed it; empty when a table or a model answered." }
+      }
+    },
     "decisionWork": {
       "type": "object",
       "required": ["id", "path", "state", "supersededBy", "implementedBy"],
@@ -199,7 +254,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
@@ -243,6 +298,35 @@
           "description": "Added in contract 1 by #2772, on every parsed record of a work kind whose work block names acceptance criteria. How many of the record's criteria passing evidence meets: evidence naming the criterion, with result pass and the criterion's verification, and for a manual criterion a by other than the implementer. Null when the record lists no criteria, so a record without them reads as before.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workAcceptance" }]
         },
+        "worktree": {
+          "enum": ["committed", "modified", "new"],
+          "description": "Added in contract 1 by #3160, on every record of a read of the working tree in a git repository; absent under --at and outside git. committed when the file is as HEAD holds it, modified when it differs from HEAD, new when HEAD doesn't hold it, staged or not. modified and new are the records a person has kept and not yet committed or applied."
+        },
+        "lastWrite": {
+          "description": "Added in contract 1 by #3173, beside worktree. The last chant write of the record's file in this working tree (records new, amend, review or close, points ask or answer), from the write journal in the git directory, while the file still holds the text that write left; null when the journal doesn't know it, such as after a commit was checked out or the file was edited by hand. A UI shows it with digest, so a person sees who changed a record they are looking at. It is a cache, never a fact: the journal can be lost.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["verb", "by", "agent", "at"],
+              "properties": {
+                "verb": { "type": "string", "description": "The write command, such as records amend or points answer." },
+                "by": { "type": ["string", "null"], "description": "The principal the write named (--by, or the people who answered), or null when it named none." },
+                "agent": { "type": ["string", "null"], "description": "The agent session the write was made in (CHANT_AGENT), or null." },
+                "at": { "type": "string", "description": "When, as an ISO 8601 time." }
+              }
+            }
+          ]
+        },
+        "contract": {
+          "description": "Added in contract 1 by #3147, on every parsed record of a work kind whose work block names a contract kind. The contract record the item builds, by the id in the work block's contract field, with that record's state now; state is null when no record of the contract kind has the id. Null when the item names no contract.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }]
+        },
+        "answers": {
+          "description": "Added in contract 1 by #3147, on every record with an id of a work kind whose work block names an answer kind. The decision-point answers about the item: each answer record whose constrains names the item's id, in path order, joined by id and never copied onto the item. Read at the same revision; in the working tree, with the answers a steward keeps on the lifecycle ledger laid over it. Absent when the answer kind can't be read.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/workAnswer" }
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]
@@ -319,6 +403,9 @@
             "work-done-gap-open",
             "work-acceptance-unmet",
             "work-acceptance-self-verified",
+            "work-contract-unknown",
+            "work-contract-undecided",
+            "work-tier-unknown",
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",