@intentius/chant 0.102.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,
@@ -53,6 +69,7 @@ import { workingTree } from "./tree";
 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 ─────────────────────────────────────────────────────────────────
 
@@ -78,6 +95,7 @@ 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,
@@ -94,6 +112,8 @@ 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,
@@ -110,6 +130,8 @@ 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,
@@ -127,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;
@@ -151,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;
 }
@@ -159,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). */
@@ -339,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 {
@@ -392,11 +449,7 @@ function refuseUnidentifiedAuthors(source: ScopeSource, kind: Opened["loaded"]["
  */
 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;
 }
 
@@ -470,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}`);
@@ -648,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 || err instanceof IdentityError) {
-    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;
 }
@@ -786,19 +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);
+    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];
@@ -830,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,
@@ -840,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) {
@@ -847,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 {
@@ -860,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;
 }
 
 /**
@@ -877,6 +1012,15 @@ 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);
     const scope = refuseOutOfScope(o, "amend", opts.cwd, opts);
@@ -886,6 +1030,7 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
     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);
@@ -951,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,
@@ -968,6 +1118,7 @@ export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Pr
       ...(sealDropped ? { sealDropped } : {}),
       dryRun: !!opts.dryRun,
       warnings,
+      digest,
       ...(opts.dryRun ? { text } : {}),
     };
   } catch (err) {
@@ -997,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;
 }
 
 /**
@@ -1006,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)}`);
@@ -1021,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`);
     }
@@ -1047,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) {
@@ -1063,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,
@@ -1076,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) {
@@ -1130,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"> {
@@ -1226,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 }));
@@ -1245,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

@@ -302,6 +302,22 @@
           "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" }]

package/src/workspace/records.ts

@@ -381,9 +381,11 @@ export const recordKindSchema = z
      * A review-session kind (#2673, #2650 C10): the front-matter list of the
      * verdicts a session produced, the field that seals a closed session, and
      * the records its verdicts name, as the kind file that locates them
-     * (relative to this kind file's directory). The entries of that kind's
-     * reviews list (its `reviews.field`, or `reviews`) name a session in
-     * `session`. Optional.
+     * (relative to this kind file's directory), or as `kinds`, several kind
+     * files, when a session judges records of more than one kind, such as
+     * decisions and contracts (#3148, ws-082). The entries of each such
+     * kind's reviews list (its `reviews.field`, or `reviews`) name a session
+     * in `session`. Optional.
      *
      * `openedRev`, `closedRev` and `closedOn` (#2693) name the fields that
      * hold the commit a session opened at, the commit it closed at, and when
@@ -395,7 +397,13 @@ export const recordKindSchema = z
       .object({
         verdicts: z.string().min(1),
         seal: z.string().min(1),
-        subjects: z.object({ kind: z.string().min(1) }).strict(),
+        subjects: z.union([
+          z.object({ kind: z.string().min(1) }).strict(),
+          z
+            .object({ kinds: z.array(z.string().min(1)).min(1) })
+            .strict()
+            .refine((x) => new Set(x.kinds).size === x.kinds.length, { message: "session.subjects.kinds lists each kind file once", path: ["kinds"] }),
+        ]),
         openedRev: z.string().min(1).optional(),
         closedRev: z.string().min(1).optional(),
         closedOn: z.string().min(1).optional(),
@@ -448,7 +456,12 @@ export const recordKindSchema = z
         acceptance: z.object({ field: z.string().min(1), implementer: z.string().min(1) }).strict().optional(),
         contract: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict().optional(),
         tier: z
-          .object({ field: z.string().min(1), tiers: z.array(z.string().min(1)).min(1) })
+          .object({
+            field: z.string().min(1),
+            tiers: z.array(z.string().min(1)).min(1),
+            // What each tier may hold, for the slice-tier point's fits_<tier> inputs (#3150, work-size.ts).
+            limits: z.record(z.string().min(1), z.object({ criteria: z.number().int().min(0).optional(), files: z.number().int().min(0).optional(), words: z.number().int().min(0).optional() }).strict()).optional(),
+          })
           .strict()
           .refine((t) => new Set(t.tiers).size === t.tiers.length, { message: "work.tier.tiers lists each tier once", path: ["tiers"] })
           .optional(),
@@ -561,6 +574,34 @@ export const ANSWER_STATES = ["escalated", "proposed", "answered"] as const;
 
 export type RecordKind = z.infer<typeof recordKindSchema>;
 
+/** The kind files a session kind's verdicts name records of, relative to the session kind file: `subjects.kind`, or each of `subjects.kinds` (ws-082). */
+export function sessionSubjectKinds(session: NonNullable<RecordKind["session"]>): string[] {
+  return "kinds" in session.subjects ? session.subjects.kinds : [session.subjects.kind];
+}
+
+/** The records of one of a session kind's subject kinds, and the name of their reviews list. */
+export interface SessionSubjects {
+  /** The subject kind file, as the session kind names it. */
+  kind: string;
+  records: RecordEntry[];
+  reviews: string;
+}
+
+/**
+ * A session kind's subject records, each subject kind read from `source`
+ * (#2673, ws-082), for {@link readRecords}' `subjects`. Undefined for a kind
+ * that is not a session kind.
+ */
+export async function readSessionSubjects(loaded: LoadedRecordKind, root: string, source: RecordSource): Promise<SessionSubjects[] | undefined> {
+  if (!loaded.kind.session) return undefined;
+  const out: SessionSubjects[] = [];
+  for (const file of sessionSubjectKinds(loaded.kind.session)) {
+    const subjectKind = await loadRecordKind(resolve(dirname(loaded.file), file), root);
+    out.push({ kind: file, records: (await readRecords(subjectKind, { root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" });
+  }
+  return out;
+}
+
 /** A kind as loaded: its data, where it came from, and its schema. */
 export interface LoadedRecordKind {
   kind: RecordKind;
@@ -1195,11 +1236,11 @@ export interface ReadRecordsOptions {
    */
   history?: RecordHistory;
   /**
-   * For a session kind: the records its `session.subjects.kind` locates, read
-   * from the same tree (#2673). Without them no verdict is checked and no
-   * session is cited.
+   * For a session kind: the records each of its subject kinds locates, read
+   * from the same tree (#2673, ws-082). Without them no verdict is checked
+   * and no session is cited.
    */
-  subjects?: { records: RecordEntry[]; reviews: string };
+  subjects?: SessionSubjects[];
   /**
    * The workspace root, from `root` with / separators ("." for `root`
    * itself): where a content-addressed record's own path is reported from

package/src/workspace/reference-kinds/app/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "chant-reference-app-kind",
+  "version": "1.0.0",
+  "private": true,
+  "description": "The app member kind (INTENTIUS/chant#3151): a data-only kinds file a workspace pins by path. chant reads it as data and never runs it.",
+  "files": ["workspace-kinds.json"],
+  "exports": {
+    "./workspace-kinds": "./workspace-kinds.json"
+  }
+}

package/src/workspace/reference-kinds/app/workspace-kinds.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "The app member kind (#3151, ws-093). A workspace pins a copy of this directory by path, as the reference workspace does at kinds/app, and chant reads it as data. The fields are the conventions an orchestrator relies on to run, migrate, test and check an app: the scripts in its package.json, the environment variables it reads, and the path it answers health on. The canonical copy ships in @intentius/chant at src/workspace/reference-kinds/app.",
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "app",
+      "description": "an app: a Node package with a start script in the package.json directly in its directory",
+      "precedence": 100,
+      "probe": {
+        "anyJsonKey": {
+          "in": ["package.json"],
+          "pointers": ["/scripts/start"]
+        }
+      },
+      "outputs": ["source", "url"],
+      "fields": {
+        "scripts": {
+          "type": "object",
+          "description": "Which package.json script plays each part, run with npm run from the member's directory",
+          "properties": {
+            "start": { "type": "string", "description": "Runs a release of the app; it listens on the port env.port names", "default": "start" },
+            "dev": { "type": "string", "description": "Runs the app in development", "default": "dev" },
+            "test": { "type": "string", "description": "The app's own tests, run before a release", "default": "test" },
+            "migrate": { "type": "string", "description": "Applies the app's migrations to the data directory env.data names; a missing script means there are none", "default": "migrate" }
+          }
+        },
+        "env": {
+          "type": "object",
+          "description": "The environment variables the app reads, by name",
+          "properties": {
+            "port": { "type": "string", "description": "The port the app listens on", "default": "PORT", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "data": { "type": "string", "description": "The directory the app keeps its data in", "default": "APP_DATA", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "revision": { "type": "string", "description": "The revision the running app reports, such as the release's commit", "default": "APP_REVISION", "pattern": "^[A-Z_][A-Z0-9_]*$" }
+          }
+        },
+        "health": {
+          "type": "string",
+          "description": "The path the running app answers on with a status below 500 once it is up",
+          "default": "/health",
+          "pattern": "^/"
+        }
+      }
+    }
+  ]
+}