@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/conformance/writer.ts

@@ -33,13 +33,25 @@
  *      repository does not have, unless it names itself one of the four
  *      exceptions.
  *
+ *   5. Concurrent writes (#3173, ws-089). When the writer performs `records
+ *      amend`, the suite has it make three amendments of the script's
+ *      decision at once, each from the digest the suite read
+ *      (`--expect <digest>`), as two people and an agent would. Exactly one
+ *      must be written; the other two must come back as chant's
+ *      record-conflict refusal, naming the winner's digest, returned to the
+ *      suite unchanged rather than retried blindly or hidden. The suite then
+ *      has the writer retry each from the digest its refusal named, and each
+ *      retry must be written. See {@link CONCURRENT_AMENDS}.
+ *
  * `facts()` may only read: every chant call it makes must be a read-contract
  * command, and it must leave the workspace as it was.
  *
  * The workspace is generated for each run, from the reader suite's fixture
  * and the `__writer_fixture__/` overlay this package ships beside this module:
- * the reference workspace's work, answer and session kinds, its decision
- * points, and one open work item, W-001. Nothing is written anywhere else.
+ * the reference workspace's work, answer and session kinds (with the
+ * contract and driver kinds a session's verdicts may also name), its
+ * decision points, and one open work item, W-001. Nothing is written
+ * anywhere else.
  *
  * Actions a writer does not list in `actions` are not applicable to it. The
  * suite still performs those steps itself, directly through chant, so a later
@@ -68,6 +80,7 @@ export const WRITE_CONTRACT_ACTIONS = [
   "records close",
   "points ask",
   "points answer",
+  "points retract",
   "work claim",
   "work renew",
   "work evidence",
@@ -75,6 +88,9 @@ export const WRITE_CONTRACT_ACTIONS = [
   "runs start",
   "runs end",
   "runs record",
+  "box listing set",
+  "wip save",
+  "wip restore",
 ] as const;
 export type WriteContractAction = (typeof WRITE_CONTRACT_ACTIONS)[number];
 
@@ -86,6 +102,7 @@ export const WRITE_CONTRACT_SCHEMAS: Record<WriteContractAction, string> = {
   "records close": "records-close.schema.json",
   "points ask": "points-write.schema.json",
   "points answer": "points-write.schema.json",
+  "points retract": "points-write.schema.json",
   "work claim": "work-lease.schema.json",
   "work renew": "work-lease.schema.json",
   "work evidence": "work-evidence.schema.json",
@@ -93,12 +110,15 @@ export const WRITE_CONTRACT_SCHEMAS: Record<WriteContractAction, string> = {
   "runs start": "runs-write.schema.json",
   "runs end": "runs-write.schema.json",
   "runs record": "runs-write.schema.json",
+  "box listing set": "box-listing-write.schema.json",
+  "wip save": "wip-write.schema.json",
+  "wip restore": "wip-write.schema.json",
 };
 
 /**
- * The flags a writer may add to each command. The record, points, evidence
- * and run writes always print their document, so a writer adds nothing or
- * `--json`; a lease prints its document only with `--json`.
+ * The flags a writer may add to each command. The record, points, evidence,
+ * run and listing writes always print their document, so a writer adds
+ * nothing or `--json`; a lease prints its document only with `--json`.
  */
 export const WRITE_CONTRACT_JSON_FLAGS: Record<WriteContractAction, readonly (readonly string[])[]> = {
   "records new": [[], ["--json"]],
@@ -107,6 +127,7 @@ export const WRITE_CONTRACT_JSON_FLAGS: Record<WriteContractAction, readonly (re
   "records close": [[], ["--json"]],
   "points ask": [[], ["--json"]],
   "points answer": [[], ["--json"]],
+  "points retract": [[], ["--json"]],
   "work claim": [["--json"]],
   "work renew": [["--json"]],
   "work evidence": [[], ["--json"]],
@@ -114,16 +135,22 @@ export const WRITE_CONTRACT_JSON_FLAGS: Record<WriteContractAction, readonly (re
   "runs start": [[], ["--json"]],
   "runs end": [[], ["--json"]],
   "runs record": [[], ["--json"]],
+  "box listing set": [[], ["--json"]],
+  "wip save": [[], ["--json"]],
+  "wip restore": [[], ["--json"]],
 };
 
 /** What each action is given. Field documents are JSON values; the command reads them from stdin. */
 export interface WriteParams {
   "records new": { kind: string; fields: Record<string, unknown> };
-  "records amend": { id: string; kind: string; fields: Record<string, unknown> };
+  /** `expect` (#3173): the record's digest the write builds on, passed as `--expect`. */
+  "records amend": { id: string; kind: string; fields: Record<string, unknown>; expect?: string };
   "records review": { id: string; kind: string; verdict: "agree" | "dissent" | "abstain"; by: string; note?: string };
   "records close": { id: string; kind: string };
-  "points ask": { point: string; kind: string; inputs: Record<string, unknown>; subject?: string };
-  "points answer": { id: string; kind: string; answer: string; by: string };
+  /** `candidates` is an ad-hoc point's question and candidates (#3403), `{ question, criteria }`: they go on stdin, and the inputs as JSON on the command line. */
+  "points ask": { point: string; kind: string; inputs: Record<string, unknown>; subject?: string; candidates?: { question: string; criteria: Record<string, string> | string[] } };
+  "points answer": { id: string; kind: string; answer: string; by: string; note?: string };
+  "points retract": { id: string; kind: string; by: string; note?: string };
   "work claim": { id: string; kind: string; holder: string };
   "work renew": { id: string; kind: string; holder: string; token: string };
   "work evidence": { id: string; kind: string; holder: string; token: string; entry: Record<string, unknown> };
@@ -131,6 +158,12 @@ export interface WriteParams {
   "runs start": { run: Record<string, unknown> };
   "runs end": { id: string; fields: Record<string, unknown> };
   "runs record": { run: Record<string, unknown> };
+  /** A box's listing (#3308): the member, the listing fields, and an image to copy in as its cover. */
+  "box listing set": { member: string; fields: Record<string, unknown>; cover?: string };
+  /** A snapshot of the working tree, uncommitted records included, onto refs/chant/wip/<branch> (#3172): what the caller calls it, and who took it. */
+  "wip save": { label?: string; by?: string };
+  /** Put the working tree back as a snapshot holds it (#3172). */
+  "wip restore": { snapshot: string; by?: string };
 }
 
 /** One write the suite asks of the writer: the action, what it is given, and the command that performs it. */
@@ -142,7 +175,7 @@ export type WriteStep = {
     params: WriteParams[A];
     /** The arguments after `chant workspace <action>`, as {@link writeArgv} builds them from `params`. */
     args: string[];
-    /** What the command reads on stdin (`--from -`, `--set -`, `--inputs -`), when it reads anything. */
+    /** What the command reads on stdin (`--from -`, `--set -`, `--inputs -`, `--candidates -`), when it reads anything. */
     input?: string;
   };
 }[WriteContractAction];
@@ -162,7 +195,7 @@ export function writeArgv<A extends WriteContractAction>(action: A, params: Writ
     }
     case "records amend": {
       const q = p as WriteParams["records amend"];
-      return { args: [q.id, "--kind", q.kind, "--set", "-"], input: json(q.fields) };
+      return { args: [q.id, "--kind", q.kind, "--set", "-", ...(q.expect !== undefined ? ["--expect", q.expect] : [])], input: json(q.fields) };
     }
     case "records review": {
       const q = p as WriteParams["records review"];
@@ -174,11 +207,18 @@ export function writeArgv<A extends WriteContractAction>(action: A, params: Writ
     }
     case "points ask": {
       const q = p as WriteParams["points ask"];
-      return { args: [q.point, "--inputs", "-", ...(q.subject !== undefined ? ["--subject", q.subject] : []), "--kind", q.kind], input: json(q.inputs) };
+      const subject = q.subject !== undefined ? ["--subject", q.subject] : [];
+      // An ad-hoc ask (#3403): the question and candidates read from stdin, and the inputs given as JSON.
+      if (q.candidates !== undefined) return { args: [q.point, "--inputs", json(q.inputs), "--candidates", "-", ...subject, "--kind", q.kind], input: json(q.candidates) };
+      return { args: [q.point, "--inputs", "-", ...subject, "--kind", q.kind], input: json(q.inputs) };
     }
     case "points answer": {
       const q = p as WriteParams["points answer"];
-      return { args: [q.id, "--answer", q.answer, "--by", q.by, "--kind", q.kind] };
+      return { args: [q.id, "--answer", q.answer, "--by", q.by, ...(q.note !== undefined ? ["--note", q.note] : []), "--kind", q.kind] };
+    }
+    case "points retract": {
+      const q = p as WriteParams["points retract"];
+      return { args: [q.id, "--by", q.by, ...(q.note !== undefined ? ["--note", q.note] : []), "--kind", q.kind] };
     }
     case "work claim": {
       const q = p as WriteParams["work claim"];
@@ -205,6 +245,18 @@ export function writeArgv<A extends WriteContractAction>(action: A, params: Writ
       const q = p as WriteParams["runs end"];
       return { args: [q.id, "--from", "-"], input: json(q.fields) };
     }
+    case "box listing set": {
+      const q = p as WriteParams["box listing set"];
+      return { args: [q.member, "--from", "-", ...(q.cover !== undefined ? ["--cover", q.cover] : [])], input: json(q.fields) };
+    }
+    case "wip save": {
+      const q = p as WriteParams["wip save"];
+      return { args: [...(q.label !== undefined ? ["--label", q.label] : []), ...(q.by !== undefined ? ["--by", q.by] : [])] };
+    }
+    case "wip restore": {
+      const q = p as WriteParams["wip restore"];
+      return { args: [q.snapshot, ...(q.by !== undefined ? ["--by", q.by] : [])] };
+    }
     default:
       throw new Error(`not a write-contract action: ${String(action)}`);
   }
@@ -218,6 +270,32 @@ export const WRITER_KINDS = {
   work: "work/work.kind.mjs",
 } as const;
 
+/** The member of the writer workspace whose box block the script lists (#3308). */
+export const WRITER_BOX = "app";
+
+/**
+ * The files the suite makes for a run outside the workspace, for a step to
+ * hand chant: the cover image the listing step copies in (#3308), a PNG.
+ */
+export const WRITER_INPUTS = {
+  cover: {
+    name: "cover.png",
+    bytes: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "base64"),
+  },
+} as const;
+
+/** Where the suite put {@link WRITER_INPUTS} for this run. */
+export interface WriterInputs {
+  dir: string;
+}
+
+/** Write {@link WRITER_INPUTS} into `dir`. */
+export function writeWriterInputs(dir: string): WriterInputs {
+  mkdirSync(dir, { recursive: true });
+  for (const f of Object.values(WRITER_INPUTS)) writeFileSync(join(dir, f.name), f.bytes);
+  return { dir };
+}
+
 /** The principals the script writes as. */
 export const WRITER_PRINCIPALS = { holder: "conformance-writer", reviewer: "conformance-reviewer", by: "conformance" } as const;
 
@@ -225,10 +303,11 @@ export const WRITER_PRINCIPALS = { holder: "conformance-writer", reviewer: "conf
 export interface WriterScriptStep<A extends WriteContractAction = WriteContractAction> {
   id: string;
   action: A;
-  params(done: Record<string, Record<string, unknown>>): WriteParams[A];
+  /** `inputs` is where the suite put {@link WRITER_INPUTS}; a step that hands chant one of them leaves it out without. */
+  params(done: Record<string, Record<string, unknown>>, inputs?: WriterInputs): WriteParams[A];
 }
 
-const step = <A extends WriteContractAction>(id: string, action: A, params: (done: Record<string, Record<string, unknown>>) => WriteParams[A]): WriterScriptStep => ({ id, action, params }) as WriterScriptStep;
+const step = <A extends WriteContractAction>(id: string, action: A, params: (done: Record<string, Record<string, unknown>>, inputs?: WriterInputs) => WriteParams[A]): WriterScriptStep => ({ id, action, params }) as WriterScriptStep;
 
 const leaseToken = (done: Record<string, Record<string, unknown>>): string => String((done.claim?.lease as { token?: unknown } | undefined)?.token ?? "");
 const RUN_STARTED = { harness: { name: "conformance", version: "1" }, model: "none", provider: "none", by: WRITER_PRINCIPALS.by, unit: "W-001" };
@@ -236,9 +315,12 @@ const RUN_STARTED = { harness: { name: "conformance", version: "1" }, model: "no
 /**
  * The writes the suite drives, in order, each action at least once: a
  * decision made, amended and reviewed; a review session opened and closed; a
- * decision point asked and answered; the work item's lease claimed, renewed,
+ * decision point asked, answered with a note, the answer retracted and the
+ * question answered again (#3351); an ad-hoc question asked with its own
+ * question and candidates, as an agent asks the room, and answered (#3403); the work item's lease claimed, renewed,
  * evidence attached under it and released; one run started and ended, and one
- * recorded whole.
+ * recorded whole; the box's listing set, with a cover image copied in; and a
+ * snapshot of the working tree taken and restored (#3172).
  */
 export const WRITER_SCRIPT: readonly WriterScriptStep[] = [
   step("decision", "records new", () => ({
@@ -275,6 +357,16 @@ export const WRITER_SCRIPT: readonly WriterScriptStep[] = [
       opened: "2026-01-01T00:00:00Z",
       closed: null,
       verdicts: [],
+      // A review comment anchored in the app, as a UI review batch keeps it (#3350).
+      comments: [
+        {
+          text: "The status line should say which build is running.",
+          by: WRITER_PRINCIPALS.reviewer,
+          anchor: { route: "/", elements: [{ selector: "#status", tag: "p", text: "Running.", state: "anchored", basis: "id" }] },
+          answers: [{ round: 0, disposition: "needs-discussion", note: "Which build: the commit or the release?", by: WRITER_PRINCIPALS.holder, at: "2026-01-01T00:02:00Z" }],
+        },
+      ],
+      rounds: [{ round: 0, note: null, by: WRITER_PRINCIPALS.reviewer, at: "2026-01-01T00:01:00Z", ended: "2026-01-01T00:03:00Z" }],
     },
   })),
   step("close", "records close", (d) => ({ id: String(d.session.id), kind: WRITER_KINDS.session })),
@@ -284,7 +376,21 @@ export const WRITER_SCRIPT: readonly WriterScriptStep[] = [
     subject: "W-001",
     inputs: { "work-item.criteria": 1, "work-item.files": 1, "work-item.words": 40, "work-item.fits_small": false, "work-item.fits_medium": false },
   })),
-  step("answer", "points answer", (d) => ({ id: String(d.ask.id), kind: WRITER_KINDS.answer, answer: "medium", by: WRITER_PRINCIPALS.reviewer })),
+  step("answer", "points answer", (d) => ({ id: String(d.ask.id), kind: WRITER_KINDS.answer, answer: "medium", by: WRITER_PRINCIPALS.reviewer, note: "Two criteria and one file, but past the small limits." })),
+  step("retract", "points retract", (d) => ({ id: String(d.ask.id), kind: WRITER_KINDS.answer, by: WRITER_PRINCIPALS.reviewer, note: "Answered for the wrong work item." })),
+  step("reanswer", "points answer", (d) => ({ id: String(d.ask.id), kind: WRITER_KINDS.answer, answer: "large", by: WRITER_PRINCIPALS.reviewer })),
+  // #3403: an agent's question to the room, its text and options arriving with the ask.
+  step("adhoc", "points ask", () => ({
+    point: "agent-question",
+    kind: WRITER_KINDS.answer,
+    subject: "W-001",
+    inputs: { "ask.id": "conformance-ask-1", "ask.by": WRITER_PRINCIPALS.holder },
+    candidates: {
+      question: "Should the writer suite's item ship behind a flag?",
+      criteria: { flag: "Behind a flag, off by default.", now: "On for everyone at once." },
+    },
+  })),
+  step("adhoc-answer", "points answer", (d) => ({ id: String(d.adhoc.id), kind: WRITER_KINDS.answer, answer: "flag", by: WRITER_PRINCIPALS.reviewer })),
   step("claim", "work claim", () => ({ id: "W-001", kind: WRITER_KINDS.work, holder: WRITER_PRINCIPALS.holder })),
   step("renew", "work renew", (d) => ({ id: "W-001", kind: WRITER_KINDS.work, holder: WRITER_PRINCIPALS.holder, token: leaseToken(d) })),
   step("evidence", "work evidence", (d) => ({
@@ -312,8 +418,34 @@ export const WRITER_SCRIPT: readonly WriterScriptStep[] = [
       ...RUN_STARTED,
     },
   })),
+  step("listing", "box listing set", (_d, inputs) => ({
+    member: WRITER_BOX,
+    fields: { published: true, title: "The writer suite's box", line: "Listed through chant, read back after amnesia." },
+    ...(inputs ? { cover: join(inputs.dir, WRITER_INPUTS.cover.name) } : {}),
+  })),
+  // #3172: a checkpoint of everything the script left uncommitted, and putting it back.
+  step("checkpoint", "wip save", () => ({ label: "turn:1", by: WRITER_PRINCIPALS.by })),
+  step("undo", "wip restore", (done) => ({ snapshot: String((done.checkpoint?.snapshot as { commit?: unknown } | undefined)?.commit ?? ""), by: WRITER_PRINCIPALS.by })),
 ];
 
+/**
+ * The concurrent case (#3173): three amendments of the script's decision the
+ * writer makes at once, each setting its question, as two people and an
+ * agent answering the same record would. The suite gives each the digest it
+ * read as `expect`.
+ */
+export const CONCURRENT_AMENDS: readonly { id: string; fields: Record<string, unknown> }[] = [
+  { id: "concurrent-alice", fields: { question: "How does a tool write a fact about this workspace, as alice reads it?" } },
+  { id: "concurrent-bob", fields: { question: "How does a tool write a fact about this workspace, as bob reads it?" } },
+  { id: "concurrent-agent", fields: { question: "How does a tool write a fact about this workspace, as the agent reads it?" } },
+];
+
+/** The amend step of {@link CONCURRENT_AMENDS} entry `c`, on record `id`, from digest `expect`. */
+export function concurrentAmendStep(c: { id: string; fields: Record<string, unknown> }, id: string, expect: string): WriteStep {
+  const params: WriteParams["records amend"] = { id, kind: WRITER_KINDS.decision, fields: c.fields, expect };
+  return { id: c.id, action: "records amend", params, ...writeArgv("records amend", params) } as WriteStep;
+}
+
 /** The four things ws-074 lets a tool keep outside the repo. */
 export const PRIVATE_STATE_CATEGORIES = ["cache", "telemetry", "secret", "runtime"] as const;
 export type PrivateStateCategory = (typeof PRIVATE_STATE_CATEGORIES)[number];
@@ -395,8 +527,8 @@ export interface WorkspaceWriterConformanceReport {
   /** The actions not in `actions`, so not applicable to this writer. */
   skipped: WriteContractAction[];
   results: WriterStepResult[];
-  /** The problems of the checks after the script, by check. */
-  after: { facts: string[]; state: string[]; amnesia: string[]; holds: string[]; readBack: string[] };
+  /** The problems of the checks after the script, by check. `concurrent` is empty, and not run, when the writer does not perform records amend. */
+  after: { facts: string[]; state: string[]; amnesia: string[]; holds: string[]; readBack: string[]; concurrent: string[] };
   /** What `facts()` returned before amnesia and after. */
   facts: { before: unknown; after: unknown };
   /** The workspace written. Removed before the report is returned. */
@@ -482,14 +614,31 @@ export function isReadCall(argv: readonly string[]): boolean {
     case "runs":
       return !["start", "end", "record"].includes(sub ?? "");
     case "points":
-      return !["ask", "answer"].includes(sub ?? "");
+      return !["ask", "answer", "retract"].includes(sub ?? "");
     case "work":
       return sub === "history";
+    case "wip":
+      return !["save", "restore", "push", "fetch"].includes(sub ?? "");
     default:
       return false;
   }
 }
 
+/**
+ * Whether an argument a writer passed is the step's: the same text, or for a
+ * step argument that is JSON (an ad-hoc ask's inputs, #3403) the same value,
+ * whatever its key order or spacing.
+ */
+function sameArg(given: string | undefined, want: string): boolean {
+  if (given === want) return true;
+  if (given === undefined || !/^[[{]/.test(want)) return false;
+  try {
+    return isDeepStrictEqual(JSON.parse(given), JSON.parse(want));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * What is wrong with the chant calls one step made: anything but exactly
  * one call, of `workspace <action>` with the step's arguments in order and
@@ -503,7 +652,7 @@ export function writerCallProblems(step: WriteStep, calls: readonly ChantRun[]):
   const prefix = ["workspace", ...step.action.split(" ")];
   if (prefix.some((t, i) => argv[i] !== t)) return [`${name}: ran chant ${argv.join(" ")}, which is not workspace ${step.action}`];
   const rest = argv.slice(prefix.length);
-  const at = rest.findIndex((_, i) => step.args.every((a, j) => rest[i + j] === a));
+  const at = rest.findIndex((_, i) => step.args.every((a, j) => sameArg(rest[i + j], a)));
   if (step.args.length > 0 && at === -1) return [`${name}: ran chant ${argv.join(" ")}, which does not pass ${step.args.join(" ")} in order`];
   const extra = step.args.length > 0 ? [...rest.slice(0, at), ...rest.slice(at + step.args.length)] : rest;
   const allowed = WRITE_CONTRACT_JSON_FLAGS[step.action];
@@ -558,6 +707,16 @@ export function reportedWrites(action: WriteContractAction, doc: unknown): { pat
     const ledger = (d.ledger ?? {}) as Record<string, unknown>;
     return { paths: [], refs: str(ledger.commit) ? { "refs/heads/chant/lifecycle": String(ledger.commit) } : {} };
   }
+  if (action === "box listing set") return { paths: Array.isArray(d.paths) ? d.paths.filter((p): p is string => typeof p === "string") : [], refs: {} };
+  if (action === "wip save" || action === "wip restore") {
+    // The one snapshot ref, at the snapshot taken (the restore's checkpoint), and any ref a push recorded under refs/chant/replica/.
+    const snapshot = (action === "wip save" ? d.snapshot : (d.checkpoint as Record<string, unknown> | undefined)?.snapshot) as { commit?: unknown } | undefined;
+    const refs: Record<string, string> = {};
+    if (str(d.ref) && str(snapshot?.commit)) refs[String(d.ref)] = String(snapshot!.commit);
+    const replication = (d.replication ?? null) as { remote?: string; pushed?: { ref: string; commit: string }[]; upToDate?: number } | null;
+    for (const p of replication?.pushed ?? []) refs[`refs/chant/replica/${replication!.remote}/${p.ref.slice("refs/".length)}`] = p.commit;
+    return { paths: Array.isArray(d.paths) ? d.paths.filter((p): p is string => typeof p === "string") : [], refs };
+  }
   return { paths: str(d.path) ? [String(d.path)] : [], refs: {} };
 }
 
@@ -582,12 +741,24 @@ export function unreportedChanges(
   return problems;
 }
 
-/** Build the step a script step is at, from the documents of the steps before it. */
-export function buildStep(s: WriterScriptStep, done: Record<string, Record<string, unknown>>): WriteStep {
-  const params = s.params(done);
+/** Build the step a script step is at, from the documents of the steps before it and where the suite put its inputs. */
+export function buildStep(s: WriterScriptStep, done: Record<string, Record<string, unknown>>, inputs?: WriterInputs): WriteStep {
+  const params = s.params(done, inputs);
   return { id: s.id, action: s.action, params, ...writeArgv(s.action, params) } as WriteStep;
 }
 
+/** The box listings `status --json` prints, by member: what a home site shows of each box (#3308). */
+export async function readListing(run: (argv: string[]) => Promise<ChantRun>): Promise<Record<string, unknown>> {
+  const doc = JSON.parse((await run(["workspace", "status", "dev", "--json"])).stdout) as { members?: { name: string; box: { listing?: unknown } | null }[] };
+  return Object.fromEntries((doc.members ?? []).filter((m) => m.box?.listing).map((m) => [m.name, m.box!.listing]));
+}
+
+/** Each branch's work-in-progress snapshots `wip --json` lists (#3172), by branch: each snapshot's kind and label, newest first. */
+export async function readWip(run: (argv: string[]) => Promise<ChantRun>): Promise<Record<string, [string, string | null][]>> {
+  const doc = JSON.parse((await run(["workspace", "wip", "--json"])).stdout) as { branches?: { branch: string; snapshots: { kind: string; label: string | null }[] }[] };
+  return Object.fromEntries((doc.branches ?? []).map((b) => [b.branch, b.snapshots.map((s) => [s.kind, s.label] as [string, string | null])]));
+}
+
 /** The smallest writer that conforms: each step is its one command, and its facts are read through the read contract. */
 export const referenceWriter: WorkspaceWriterFactory = (chant) => ({
   async write(step) {
@@ -603,6 +774,8 @@ export const referenceWriter: WorkspaceWriterFactory = (chant) => ({
     }
     const runs = JSON.parse((await chant.run(["workspace", "runs", "--json"])).stdout) as { runs: { id: string; state: string }[] };
     out.runs = runs.runs.map((r) => [r.id, r.state]).sort();
+    out.listing = await readListing((argv) => chant.run(argv));
+    out.wip = await readWip((argv) => chant.run(argv));
     return out;
   },
 });
@@ -616,7 +789,8 @@ export interface WriterConformanceWorkspace {
 /**
  * Generate the writer conformance workspace: the reader suite's workspace
  * ({@link createConformanceWorkspace}), with `__writer_fixture__/` copied over
- * it, the four kinds declared in its `records`, and that committed.
+ * it, the four kinds declared in its `records`, a box block on
+ * {@link WRITER_BOX} for the listing step, and that committed.
  */
 export function createWriterConformanceWorkspace(options: { chantCommand?: string[]; timeoutMs?: number } = {}): WriterConformanceWorkspace {
   const ws = createConformanceWorkspace({ chantCommand: options.chantCommand, timeoutMs: options.timeoutMs });
@@ -625,6 +799,8 @@ export function createWriterConformanceWorkspace(options: { chantCommand?: strin
     const declFile = join(ws.dir, "chant.workspace.json");
     const decl = JSON.parse(readFileSync(declFile, "utf-8")) as Record<string, unknown>;
     decl.records = Object.values(WRITER_KINDS).map((kind) => ({ kind }));
+    const box = (decl.members as { name: string; box?: unknown }[] | undefined)?.find((m) => m.name === WRITER_BOX);
+    if (box) box.box = {};
     writeFileSync(declFile, `${JSON.stringify(decl, null, 2)}\n`);
     const git = (...args: string[]) =>
       execFileSync("git", ["-c", "user.name=chant", "-c", "user.email=chant@localhost", "-c", "commit.gpgsign=false", ...args], {
@@ -712,6 +888,8 @@ export async function runWorkspaceWriterConformance(writer: WorkspaceWriterFacto
   const privateState = options.privateState ?? [];
   const ws = createWriterConformanceWorkspace({ chantCommand, timeoutMs });
   const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "chant-writer-state-")));
+  const inputsDir = realpathSync(mkdtempSync(join(tmpdir(), "chant-writer-inputs-")));
+  const inputs = writeWriterInputs(inputsDir);
   const calls: ChantRun[] = [];
   const transport: ChantTransport = {
     async run(argv, opts) {
@@ -728,14 +906,14 @@ export async function runWorkspaceWriterConformance(writer: WorkspaceWriterFacto
       throw new Error(`chant ${argv.join(" ")} printed no JSON (exit ${run.status}): ${run.stderr.trim()}`);
     }
   };
-  const after = { facts: [] as string[], state: [] as string[], amnesia: [] as string[], holds: [] as string[], readBack: [] as string[] };
+  const after = { facts: [] as string[], state: [] as string[], amnesia: [] as string[], holds: [] as string[], readBack: [] as string[], concurrent: [] as string[] };
   const facts: { before: unknown; after: unknown } = { before: undefined, after: undefined };
   const results: WriterStepResult[] = [];
   try {
     let built = writer(transport, { stateDir });
     const done: Record<string, Record<string, unknown>> = {};
     for (const s of WRITER_SCRIPT) {
-      const st = buildStep(s, done);
+      const st = buildStep(s, done, inputs);
       if (!checked.includes(st.action)) {
         const doc = await direct(["workspace", ...st.action.split(" "), ...st.args, ...WRITE_CONTRACT_JSON_FLAGS[st.action][0]], st.input);
         done[st.id] = doc;
@@ -765,6 +943,11 @@ export async function runWorkspaceWriterConformance(writer: WorkspaceWriterFacto
       results.push({ id: st.id, action: st.action, by: "writer", args: st.args, problems });
     }
 
+    // Concurrent writes (#3173): three amendments of one record at once, each from the digest read.
+    if (checked.includes("records amend")) {
+      after.concurrent.push(...(await concurrentAmends(built, calls, direct, String(done.decision?.id ?? ""), ws.dir)));
+    }
+
     // What the writer shows, read only through the read contract.
     const readFacts = async (w: WorkspaceWriter, when: string): Promise<unknown> => {
       const files = worktreeDigest(ws.dir);
@@ -849,13 +1032,22 @@ export async function runWorkspaceWriterConformance(writer: WorkspaceWriterFacto
     }
     const runs = new Map(((await direct(["workspace", "runs", "--json"])).runs as { id: string; state: string }[] | undefined ?? []).map((r) => [r.id, r.state]));
     const history = await direct(["workspace", "work", "history", "W-001", "--kind", WRITER_KINDS.work, "--json"]);
+    const listings = await readListing((argv) => runChant(chantCommand, argv, ws.dir, timeoutMs));
+    const wipDoc = await direct(["workspace", "wip", "--json"]);
+    const snapshots = new Set(((wipDoc.branches ?? []) as { snapshots: { commit: string }[] }[]).flatMap((b) => b.snapshots.map((x) => x.commit)));
     const claims = (history.claims ?? []) as { token: string; ended: string | null; release?: { outcome?: string } | null }[];
+    const questions = new Map(((await direct(["workspace", "points", "--kind", WRITER_KINDS.answer, "--json"])).questions as { id: string; retractions?: unknown[]; asked?: unknown }[] | undefined ?? []).map((q) => [q.id, q]));
     for (const s of WRITER_SCRIPT) {
       const doc = done[s.id] ?? {};
       if (s.action.startsWith("records ") || s.action.startsWith("points ")) {
         const kind = String((doc.kind as { file?: unknown } | undefined)?.file ?? "");
         const id = String(doc.id ?? "");
         if (!uncommitted.get(kind)?.has(id)) after.readBack.push(`read back: ${s.id} (${s.action}) wrote ${id}, and records --uncommitted --kind ${kind} does not list it`);
+        else if (s.action === "points retract" && !(questions.get(id)?.retractions?.length ?? 0)) after.readBack.push(`read back: ${s.id} (${s.action}) retracted the answer to ${id}, and points --json lists no retraction for it`);
+        else if (s.action === "points ask") {
+          const asked = (doc.question as { asked?: unknown } | undefined)?.asked;
+          if (asked && !isDeepStrictEqual(questions.get(id)?.asked, asked)) after.readBack.push(`read back: ${s.id} (${s.action}) asked ${id} with its own question and candidates, and points --json does not list them as asked`);
+        }
       } else if (s.action === "work evidence") {
         if (!uncommitted.get(WRITER_KINDS.work)?.has(String(doc.item ?? ""))) after.readBack.push(`read back: ${s.id} (${s.action}) amended ${String(doc.item)}, and records --uncommitted does not list it`);
       } else if (s.action.startsWith("work ")) {
@@ -868,13 +1060,132 @@ export async function runWorkspaceWriterConformance(writer: WorkspaceWriterFacto
         const want = s.action === "runs start" ? undefined : "ended";
         if (!runs.has(id)) after.readBack.push(`read back: ${s.id} (${s.action}) wrote run ${id}, and runs does not list it`);
         else if (want && runs.get(id) !== want) after.readBack.push(`read back: ${s.id} (${s.action}) ended run ${id}, and runs says it is ${runs.get(id)}`);
+      } else if (s.action === "box listing set") {
+        const member = String(doc.member ?? "");
+        if (!isDeepStrictEqual(listings[member], doc.listing)) after.readBack.push(`read back: ${s.id} (${s.action}) set ${member}'s listing to ${brief(doc.listing)}, and status --json says ${brief(listings[member] ?? null)}`);
+      } else if (s.action === "wip save" || s.action === "wip restore") {
+        const snap = (s.action === "wip save" ? doc.snapshot : (doc.checkpoint as Record<string, unknown> | undefined)?.snapshot) as { commit?: unknown } | undefined;
+        const commit = String(snap?.commit ?? "");
+        if (!snapshots.has(commit)) after.readBack.push(`read back: ${s.id} (${s.action}) wrote snapshot ${commit}, and wip --json does not list it`);
       }
     }
 
-    const problems = [...results.flatMap((r) => r.problems), ...after.facts, ...after.state, ...after.amnesia, ...after.holds, ...after.readBack];
+    const problems = [...results.flatMap((r) => r.problems), ...after.concurrent, ...after.facts, ...after.state, ...after.amnesia, ...after.holds, ...after.readBack];
     return { problems, checked, skipped, results, after, facts, workspaceDir: ws.dir };
   } finally {
     rmSync(stateDir, { recursive: true, force: true });
+    rmSync(inputsDir, { recursive: true, force: true });
     ws.dispose();
   }
 }
+
+/**
+ * The concurrent case (#3173, ws-089): the writer makes the three
+ * {@link CONCURRENT_AMENDS} of record `id` at once, each from the digest the
+ * suite read. Exactly one is written and the others are refused with
+ * record-conflict naming its digest; each is then retried from the digest
+ * its refusal named, and written. Returns the problems, each starting
+ * `concurrent:`.
+ */
+export async function concurrentAmends(
+  built: WorkspaceWriter,
+  calls: ChantRun[],
+  direct: (argv: string[], input?: string) => Promise<Record<string, unknown>>,
+  id: string,
+  dir: string,
+): Promise<string[]> {
+  const problems: string[] = [];
+  const digestOf = async (): Promise<{ digest: string; path: string } | undefined> => {
+    const doc = await direct(["workspace", "records", "--kind", WRITER_KINDS.decision, "--json"]);
+    const r = ((doc.records ?? []) as { id: string; digest: string; path: string }[]).find((x) => x.id === id);
+    return r ? { digest: r.digest, path: r.path } : undefined;
+  };
+  const start = await digestOf();
+  if (!start) return [`concurrent: the script's decision ${id || "(none)"} can't be read back to amend`];
+  const files = { before: worktreeDigest(dir), after: {} as Record<string, string> };
+  const refs = { before: gitRefs(dir), after: {} as Record<string, string> };
+  const steps = CONCURRENT_AMENDS.map((c) => concurrentAmendStep(c, id, start.digest));
+  calls.length = 0;
+  const docs = await Promise.all(
+    steps.map(async (st) => {
+      try {
+        return { st, doc: await built.write(st) };
+      } catch (e) {
+        problems.push(`concurrent: ${st.id} (${st.action}): the writer threw: ${(e as Error).message}`);
+        return { st, doc: undefined };
+      }
+    }),
+  );
+  // Each step's call: the one that gave chant its fields.
+  const printed = new Map<string, Record<string, unknown> | undefined>();
+  for (const { st, doc } of docs) {
+    const mine = calls.filter((c) => c.input !== undefined && st.input !== undefined && isDeepStrictEqual(safeJson(c.input), JSON.parse(st.input)));
+    const callProblems = writerCallProblems(st, mine);
+    if (callProblems.length > 0) {
+      problems.push(...callProblems.map((p) => `concurrent: ${p}`));
+      continue;
+    }
+    const out = safeJson(mine[0].stdout) as Record<string, unknown> | undefined;
+    printed.set(st.id, out);
+    if (!isDeepStrictEqual(doc, out)) problems.push(`concurrent: ${st.id} (${st.action}): the writer must return the document chant printed, unchanged, refusal included, and it returned something else`);
+    const { validate } = writeContractSchema(st.action);
+    if (!validate(out)) problems.push(`concurrent: ${st.id} (${st.action}): the document does not validate against ${WRITE_CONTRACT_SCHEMAS[st.action]}: ${JSON.stringify(validate.errors)}`);
+  }
+  if (problems.length > 0) return problems;
+  const won = steps.filter((st) => printed.get(st.id)?.error === undefined);
+  const lost = steps.filter((st) => printed.get(st.id)?.error !== undefined);
+  if (won.length !== 1) {
+    problems.push(`concurrent: ${won.length} of the three amendments from digest ${start.digest} were written (${won.map((s) => s.id).join(", ") || "none"}); exactly one may be`);
+    return problems;
+  }
+  const d1 = String(printed.get(won[0].id)?.digest ?? "");
+  for (const st of lost) {
+    const doc = printed.get(st.id)!;
+    const code = (doc.error as { code?: string }).code;
+    const conflict = doc.conflict as { digest?: string; expected?: string } | undefined;
+    if (code !== "record-conflict") problems.push(`concurrent: ${st.id} was refused with ${code}, not record-conflict`);
+    else if (conflict?.digest !== d1 || conflict?.expected !== start.digest) problems.push(`concurrent: ${st.id}'s conflict names ${brief(conflict)}, not expected ${start.digest} and digest ${d1}`);
+  }
+  files.after = worktreeDigest(dir);
+  refs.after = gitRefs(dir);
+  const changed = treeChanges(files.before, files.after).filter((c) => c.replace(/ \((added|changed|removed)\)$/, "") !== start.path);
+  if (changed.length > 0) problems.push(`concurrent: files changed that chant did not report writing: ${changed.join(", ")}`);
+  if (Object.keys(refChanges(refs.before, refs.after)).length > 0) problems.push(`concurrent: git refs changed: ${Object.keys(refChanges(refs.before, refs.after)).join(", ")}`);
+  if (problems.length > 0) return problems;
+  // Each loser retries from the digest it was told, one after the other.
+  let digest = d1;
+  for (const st of lost) {
+    const retry = concurrentAmendStep(CONCURRENT_AMENDS.find((c) => c.id === st.id)!, id, digest);
+    calls.length = 0;
+    let doc: unknown;
+    try {
+      doc = await built.write(retry);
+    } catch (e) {
+      problems.push(`concurrent: ${st.id}'s retry: the writer threw: ${(e as Error).message}`);
+      continue;
+    }
+    const p = writerCallProblems({ ...retry, id: `${st.id} retry` } as WriteStep, calls);
+    if (p.length > 0) {
+      problems.push(...p.map((x) => `concurrent: ${x}`));
+      continue;
+    }
+    const out = safeJson(calls[0].stdout) as Record<string, unknown> | undefined;
+    if (out?.error !== undefined) {
+      problems.push(`concurrent: ${st.id}'s retry from ${digest} was refused: ${brief(out.error)}`);
+      continue;
+    }
+    if (!isDeepStrictEqual(doc, out)) problems.push(`concurrent: ${st.id}'s retry: the writer must return the document chant printed, unchanged`);
+    digest = String(out?.digest ?? "");
+  }
+  const end = await digestOf();
+  if (problems.length === 0 && end?.digest !== digest) problems.push(`concurrent: after the retries records --json gives ${id} digest ${end?.digest}, and the last retry printed ${digest}`);
+  return problems;
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}