@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/conformance/index.mjs

@@ -1,7 +1,8 @@
 // The entry of `@intentius/chant/workspace/conformance` for plain Node
-// (#2679). The suite is written in TypeScript like the rest of the package,
-// and Node does not strip types under node_modules, so this file loads it
-// through tsx, a dependency of this package. `node --test` runs a reader's
+// (#2679): the reader suite, and the writer suite (#3159). The suites are
+// written in TypeScript like the rest of the package, and Node does not
+// strip types under node_modules, so this file loads them through tsx, a
+// dependency of this package. `node --test` runs a reader's or a writer's
 // test file that imports it with no loader flag. Types come from
 // dist/workspace/conformance/index.d.ts.
 
@@ -15,6 +16,7 @@ export const {
   READ_CONTRACT_JSON_FLAGS,
   REFERENCE_READS,
   CONFORMANCE_FIXTURE_DIR,
+  UNCOMMITTED_DECISION,
   defaultChantCommand,
   referenceWorkspaceDir,
   readContractSchema,
@@ -32,4 +34,29 @@ export const {
   recordingTransport,
   readAndCheck,
   runWorkspaceReaderConformance,
+  runChant,
+  WRITE_CONTRACT_ACTIONS,
+  WRITE_CONTRACT_SCHEMAS,
+  WRITE_CONTRACT_JSON_FLAGS,
+  WRITER_KINDS,
+  WRITER_PRINCIPALS,
+  WRITER_SCRIPT,
+  WRITER_FIXTURE_DIR,
+  PRIVATE_STATE_CATEGORIES,
+  writeArgv,
+  writeContractSchema,
+  worktreeDigest,
+  gitRefs,
+  refChanges,
+  isReadCall,
+  writerCallProblems,
+  writerDocumentProblems,
+  reportedWrites,
+  unreportedChanges,
+  buildStep,
+  referenceWriter,
+  createWriterConformanceWorkspace,
+  selectActions,
+  undeclaredState,
+  runWorkspaceWriterConformance,
 } = suite;

package/src/workspace/conformance/index.ts

@@ -35,6 +35,14 @@
  * app, and a chant member with one composite and one component), declared
  * by `chant workspace init --yes`, so {@link REFERENCE_READS} resolve in
  * both. `workspaceDir` names another workspace with the same files.
+ *
+ * The workspace the suite generates for a run also holds one decision,
+ * proposed and never committed ({@link UNCOMMITTED_DECISION}), so
+ * `records --uncommitted` (#3160) has a record to list with its `worktree`.
+ * {@link createConformanceWorkspace} called directly leaves it out unless
+ * asked, so a test that writes records there allocates the ids it always
+ * did. In the chant repository the reference workspace holds whatever the
+ * checkout does, often nothing uncommitted.
  */
 
 import { execFileSync, spawn } from "node:child_process";
@@ -48,7 +56,7 @@ import { isDeepStrictEqual } from "node:util";
 import { READ_CONTRACT_VERSION } from "../reason-codes";
 
 /** The read-contract commands, as a reader names them. */
-export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "graph --intent", "graph --composites"] as const;
+export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "records --uncommitted", "graph --intent", "graph --composites", "runs"] as const;
 export type ReadContractCommand = (typeof READ_CONTRACT_COMMANDS)[number];
 
 /**
@@ -62,8 +70,10 @@ export const READ_CONTRACT_SCHEMAS: Record<ReadContractCommand, string> = {
   check: "check.schema.json",
   status: "status.schema.json",
   records: "records.schema.json",
+  "records --uncommitted": "records.schema.json",
   "graph --intent": "intent.schema.json",
   "graph --composites": "composites.schema.json",
+  runs: "runs.schema.json",
 };
 
 /** The flags that ask each command for its JSON document. A reader adds one of these and nothing else. */
@@ -73,8 +83,10 @@ export const READ_CONTRACT_JSON_FLAGS: Record<ReadContractCommand, readonly (rea
   check: [["--format", "json"]],
   status: [["--json"]],
   records: [["--json"]],
+  "records --uncommitted": [["--json"]],
   "graph --intent": [["--json"]],
   "graph --composites": [[], ["--json"]],
+  runs: [["--json"]],
 };
 
 /** The arguments the suite passes each read, on the reference workspace or the generated one. */
@@ -84,21 +96,30 @@ export const REFERENCE_READS: Record<ReadContractCommand, string[]> = {
   check: [],
   status: ["dev"],
   records: ["--kind", "decisions/decision.kind.mjs"],
+  "records --uncommitted": ["--kind", "decisions/decision.kind.mjs"],
   "graph --intent": ["app/src/server.mjs:19", "--kind", "decisions/decision.kind.mjs"],
   "graph --composites": [],
+  runs: [],
 };
 
-/** One chant run: the arguments after `chant`, and what it printed. */
+/** One chant run: the arguments after `chant`, what it was given on stdin, and what it printed. */
 export interface ChantRun {
   argv: string[];
+  /** What the caller gave chant on stdin, such as a record's fields for `--from -` (#3159). Absent when nothing was. */
+  input?: string;
   status: number | null;
   stdout: string;
   stderr: string;
 }
 
-/** How a reader runs chant. It runs in the workspace; the reader never sees the path. */
+/**
+ * How a reader or a writer runs chant. It runs in the workspace; the caller
+ * never sees the path. A writer passes `input` for a command that reads its
+ * fields from stdin (`--from -`, `--set -`, `--inputs -`, #3159); a reader
+ * never needs it.
+ */
 export interface ChantTransport {
-  run(argv: string[]): Promise<ChantRun>;
+  run(argv: string[], options?: { input?: string }): Promise<ChantRun>;
 }
 
 export interface WorkspaceReader {
@@ -316,8 +337,10 @@ export const MCP_READ_TOOLS: Partial<Record<ReadContractCommand, string>> = {
   graph: "workspace-graph",
   status: "workspace-status",
   records: "workspace-records",
+  "records --uncommitted": "workspace-records",
   "graph --intent": "workspace-graph",
   "graph --composites": "workspace-graph",
+  runs: "workspace-runs",
 };
 
 /**
@@ -350,6 +373,10 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
     else if (a === "--work") args.work = value();
     else if (a === "--severity") args.severity = value();
     else if (a === "--current") args.current = true;
+    else if (a === "--unit") args.unit = value();
+    else if (a === "--decision") args.decision = value();
+    else if (a === "--by") args.by = value();
+    else if (a === "--uncommitted") args.uncommitted = true;
     else if (a === "--composites") args.composites = true;
     else if (a.startsWith("-")) return undefined;
     else positional.push(a);
@@ -365,6 +392,8 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
       return positional.length === 0 && args.range !== undefined ? { name: "workspace-changes", arguments: { ...args, ...(kinds.length ? { kind: kinds } : {}) } } : undefined;
     case "graph":
       return positional.length === 0 ? { name: "workspace-graph", arguments: { ...args, ...(kinds.length ? { kind: kinds } : {}) } } : undefined;
+    case "runs":
+      return positional.length === 0 && kinds.length === 0 ? { name: "workspace-runs", arguments: args } : undefined;
     default:
       return undefined;
   }
@@ -457,6 +486,47 @@ function git(cwd: string, ...args: string[]): void {
   });
 }
 
+/**
+ * The decision the generated workspace leaves uncommitted (#3160): proposed,
+ * about the delivery member only, so the app region the intent read walks
+ * is unchanged. Its path from the workspace root, and its text.
+ */
+export const UNCOMMITTED_DECISION = {
+  path: "decisions/fix-002-where-kept-records-wait.md",
+  text: `---
+schema: 1
+id: "fix-002"
+title: "Where kept records wait"
+state: "proposed"
+area: "delivery"
+source:
+  kind: "workspace"
+  member: "delivery"
+question: "Where does a record wait between being kept and being applied?"
+options:
+  - id: "a"
+    label: "uncommitted in the working tree"
+    how: "The record stays a file in the checkout until it is committed or applied."
+    tradeoff: "A reader lists it with records --uncommitted, and nothing else holds it."
+choice: null
+rejected: []
+supersedes: []
+evidence:
+  - title: "INTENTIUS/chant#3160, uncommitted records in the read contract"
+    url: "https://github.com/INTENTIUS/chant/issues/3160"
+decided_by: null
+decided_on: null
+reviews: []
+constrains:
+  - "member:delivery"
+---
+
+# Where kept records wait
+
+The reader conformance workspace leaves this decision uncommitted, so \`records --uncommitted\` has one record to list.
+`,
+} as const;
+
 /** A workspace generated for a conformance run, and how to remove it. */
 export interface ConformanceWorkspace {
   dir: string;
@@ -468,9 +538,10 @@ export interface ConformanceWorkspace {
  * `__fixture__/`, link this package in as `node_modules/@intentius/chant`
  * so the chant member resolves it, declare the workspace with
  * `chant workspace init --yes --name conformance` and commit it all to a new
- * git repository on `main`.
+ * git repository on `main`. With `uncommitted`, then write
+ * {@link UNCOMMITTED_DECISION} and leave it uncommitted (#3160).
  */
-export function createConformanceWorkspace(options: { chantCommand?: string[]; timeoutMs?: number } = {}): ConformanceWorkspace {
+export function createConformanceWorkspace(options: { chantCommand?: string[]; timeoutMs?: number; uncommitted?: boolean } = {}): ConformanceWorkspace {
   const chant = options.chantCommand ?? defaultChantCommand();
   const scratch = realpathSync(mkdtempSync(join(tmpdir(), "chant-reader-conformance-")));
   const dispose = () => rmSync(scratch, { recursive: true, force: true });
@@ -489,7 +560,18 @@ export function createConformanceWorkspace(options: { chantCommand?: string[]; t
       timeout: options.timeoutMs ?? 120_000,
     });
     git(dir, "add", "-A");
-    git(dir, "commit", "--quiet", "-m", "the reader conformance workspace");
+    git(dir, "commit", "--quiet", "-m", "the reader conformance workspace", "-m", "Chant-Run: conformance-run");
+    // One agent run in the run ledger (#3033), which made that commit, so `runs` reads a run with every field.
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    const run = { id: "conformance-run", harness: { name: "conformance", version: "1" }, model: "none", provider: "none", by: "conformance", startedAt: "2026-01-01T00:00:00Z", endedAt: "2026-01-01T00:01:00Z", outcome: "done", usage: { turns: 1, inputTokens: 10, outputTokens: 5 }, cost: { amount: 0.01, currency: "USD", source: "conformance" }, transcript: { sha256: "0".repeat(64), ref: "conformance" }, commits: [head] };
+    execFileSync(chant[0], [...chant.slice(1), "workspace", "runs", "record", "--from", "-"], {
+      cwd: dir,
+      input: JSON.stringify(run),
+      env: { ...process.env, ...GIT_ENV, NO_COLOR: "1" },
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? 120_000,
+    });
+    if (options.uncommitted) writeFileSync(join(dir, ...UNCOMMITTED_DECISION.path.split("/")), UNCOMMITTED_DECISION.text);
     return { dir, dispose };
   } catch (e) {
     dispose();
@@ -503,14 +585,17 @@ export function conformanceTarget(options: WorkspaceReaderConformanceOptions = {
   const chantCommand = options.chantCommand ?? defaultChantCommand();
   const given = options.workspaceDir ?? referenceWorkspaceDir();
   if (given) return { workspaceDir: given, chantCommand, dispose: () => {} };
-  const ws = createConformanceWorkspace({ chantCommand, timeoutMs: options.timeoutMs });
+  const ws = createConformanceWorkspace({ chantCommand, timeoutMs: options.timeoutMs, uncommitted: true });
   return { workspaceDir: ws.dir, chantCommand, dispose: ws.dispose };
 }
 
-/** Run `command` in `cwd`, collecting what it printed. Resolves, never rejects. */
-function runChant(command: string[], argv: string[], cwd: string, timeoutMs: number): Promise<ChantRun> {
+/** Run `command` in `cwd`, with `input` on stdin when given, collecting what it printed. Resolves, never rejects. */
+export function runChant(command: string[], argv: string[], cwd: string, timeoutMs: number, input?: string): Promise<ChantRun> {
   return new Promise((settle) => {
-    const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["pipe", "pipe", "pipe"] });
+    const given = input === undefined ? {} : { input };
+    // Without input, stdin is closed at once, as it was when it was ignored.
+    child.stdin.on("error", () => {}).end(input ?? "");
     let stdout = "";
     let stderr = "";
     child.stdout.setEncoding("utf-8").on("data", (s: string) => (stdout += s));
@@ -518,11 +603,11 @@ function runChant(command: string[], argv: string[], cwd: string, timeoutMs: num
     const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
     child.on("error", (e) => {
       clearTimeout(timer);
-      settle({ argv: [...argv], status: null, stdout, stderr: `${stderr}${e.message}` });
+      settle({ argv: [...argv], ...given, status: null, stdout, stderr: `${stderr}${e.message}` });
     });
     child.on("close", (status) => {
       clearTimeout(timer);
-      settle({ argv: [...argv], status, stdout, stderr });
+      settle({ argv: [...argv], ...given, status, stdout, stderr });
     });
   });
 }
@@ -582,10 +667,10 @@ export function recordingTransport(target: () => { workspaceDir: string; chantCo
     return { argv: [...argv], status: 0, stdout: JSON.stringify(doc), stderr: "" };
   };
   const transport: ChantTransport = {
-    async run(argv) {
+    async run(argv, options) {
       calls.push([...argv]);
       const t = target();
-      const run = over === "mcp" ? await viaMcp(argv) : await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs);
+      const run = over === "mcp" ? await viaMcp(argv) : await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs, options?.input);
       printed.push(run);
       return run;
     },
@@ -656,3 +741,6 @@ export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFacto
     target.dispose();
   }
 }
+
+// The writer suite (#3159), published from this same entry.
+export * from "./writer";

package/src/workspace/conformance/vitest.ts

@@ -2,8 +2,11 @@
  * The workspace reader conformance suite for vitest (#2657, #2679):
  * {@link describeWorkspaceReaderConformance} wraps the runner-neutral checks
  * of `./index` in `describe` and `it`, one test per listed command and one
- * for the workspace's files. This is the only module of the suite that
- * imports vitest; `@intentius/chant/workspace/conformance` imports no runner.
+ * for the workspace's files. {@link describeWorkspaceWriterConformance}
+ * (#3159) does the same for the writer suite: one test per step of the
+ * script, and one per check after it. This is the only module of the suite
+ * that imports vitest; `@intentius/chant/workspace/conformance` imports no
+ * runner.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -17,7 +20,12 @@ import {
   selectCommands,
   treeChanges,
   treeDigest,
+  runWorkspaceWriterConformance,
+  selectActions,
+  WRITER_SCRIPT,
   type WorkspaceReaderConformanceConfig,
+  type WorkspaceWriterConformanceConfig,
+  type WorkspaceWriterConformanceReport,
 } from "./index";
 
 export function describeWorkspaceReaderConformance(config: WorkspaceReaderConformanceConfig): void {
@@ -68,4 +76,38 @@ export function describeWorkspaceReaderConformance(config: WorkspaceReaderConfor
   });
 }
 
+/**
+ * The writer suite in vitest: the runner-neutral run happens once, before the
+ * tests, and each test reports its part of it. A step whose action the writer
+ * does not list is skipped, as not applicable; the suite still performed it.
+ */
+export function describeWorkspaceWriterConformance(config: WorkspaceWriterConformanceConfig): void {
+  const { checked } = selectActions(config.actions);
+  describe(`workspace writer conformance (#3159): ${config.name}`, () => {
+    let report: WorkspaceWriterConformanceReport | undefined;
+    beforeAll(async () => {
+      report = await runWorkspaceWriterConformance(config.writer, config);
+    }, 900_000);
+    const ran = () => {
+      expect(report, "the writer suite did not run").toBeDefined();
+      return report!;
+    };
+
+    for (const s of WRITER_SCRIPT) {
+      if (!checked.includes(s.action)) {
+        it.skip(`${s.id}: ${s.action} is not applicable, the writer does not list it in actions`, () => {});
+        continue;
+      }
+      it(`${s.id}: writes through chant workspace ${s.action} alone, and every change it made is one chant reports`, () => {
+        expect(ran().results.find((r) => r.id === s.id)?.problems).toEqual([]);
+      });
+    }
+    it("facts() reads only through the read contract and changes nothing", () => expect(ran().after.facts).toEqual([]));
+    it("the state directory holds only what privateState declares", () => expect(ran().after.state).toEqual([]));
+    it("amnesia: with its private state deleted, the writer shows the same facts", () => expect(ran().after.amnesia).toEqual([]));
+    it("everything the writer holds is in the repository, or one of ws-074's four exceptions", () => expect(ran().after.holds).toEqual([]));
+    it("every fact the script produced reads back through the read contract, uncommitted ones included", () => expect(ran().after.readBack).toEqual([]));
+  });
+}
+
 export * from "./index";

package/src/workspace/conformance/writer-conformance.e2e.test.ts

@@ -0,0 +1,131 @@
+/**
+ * The writer conformance suite run end to end (#3159): a writer that
+ * conforms, with a cache in its state directory, passes every action; a
+ * writer that breaks each rule once is caught at the step that broke it. Both
+ * run on a workspace generated from the shipped fixtures, at the same time.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  referenceWriter,
+  runWorkspaceWriterConformance,
+  WRITE_CONTRACT_ACTIONS,
+  WRITE_CONTRACT_JSON_FLAGS,
+  WRITER_KINDS,
+  WRITER_SCRIPT,
+  type ChantTransport,
+  type WorkspaceWriterFactory,
+  type WriteStep,
+} from "./index";
+
+/** One call of the step's command, as a writer makes it. */
+const perform = async (chant: ChantTransport, step: WriteStep, extra: string[] = []) => {
+  const run = await chant.run(["workspace", ...step.action.split(" "), ...step.args, ...WRITE_CONTRACT_JSON_FLAGS[step.action][0], ...extra], step.input === undefined ? undefined : { input: step.input });
+  return JSON.parse(run.stdout) as Record<string, unknown>;
+};
+
+/** The reference writer with a cache of its facts in its state directory: rebuilt from chant when it is gone. */
+const cachingWriter: WorkspaceWriterFactory = (chant, { stateDir }) => {
+  const inner = referenceWriter(chant, { stateDir });
+  const cache = join(stateDir, "cache", "facts.json");
+  return {
+    write: (step) => inner.write(step),
+    async facts() {
+      if (existsSync(cache)) return JSON.parse(readFileSync(cache, "utf-8"));
+      const facts = await inner.facts();
+      // A cache is private state the suite allows; the suite deletes it for amnesia.
+      const { mkdirSync } = await import("node:fs");
+      mkdirSync(join(stateDir, "cache"), { recursive: true });
+      writeFileSync(cache, JSON.stringify(facts));
+      return facts;
+    },
+    holds: () => [
+      { record: "fix-002", kind: WRITER_KINDS.decision },
+      { run: "writer-run-1" },
+      { lease: "W-001", kind: WRITER_KINDS.work },
+      { exempt: "cache", what: "cache/facts.json, the facts as last read" },
+    ],
+  };
+};
+
+/** A writer that breaks one rule at each step it performs, and keeps a review only in its own state. */
+const leakyWriter: WorkspaceWriterFactory = (chant, { stateDir }) => {
+  const reviews = join(stateDir, "reviews.json");
+  return {
+    async write(step) {
+      if (step.id === "decision") return { ...(await perform(chant, step)), note: "the writer's own field" };
+      if (step.id === "amend") {
+        const doc = await perform(chant, step);
+        // A second write the step did not ask for: another decision.
+        const extra = WRITER_SCRIPT.find((s) => s.id === "decision")!;
+        await chant.run(["workspace", "records", "new", WRITER_KINDS.decision, "--from", "-"], { input: JSON.stringify({ ...(extra.params({}) as { fields: object }).fields, title: "A decision nobody asked for" }) });
+        return doc;
+      }
+      if (step.id === "review") {
+        const doc = await perform(chant, step);
+        writeFileSync(reviews, JSON.stringify([{ id: doc.id, by: "conformance-reviewer", verdict: "agree" }]));
+        writeFileSync(join(stateDir, "notes.txt"), "kept and not declared");
+        return doc;
+      }
+      if (step.id === "answer") return perform(chant, step, ["--dry-run"]);
+      return perform(chant, step);
+    },
+    async facts() {
+      // A write made while reading: refused by chant, still not a read.
+      await chant.run(["workspace", "runs", "start", "--from", "-"], { input: "{}" });
+      return { reviews: existsSync(reviews) ? JSON.parse(readFileSync(reviews, "utf-8")) : [] };
+    },
+    holds: () => [
+      { record: "fix-999", kind: WRITER_KINDS.decision },
+      { exempt: "database" as never, what: "events" },
+    ],
+  };
+};
+
+describe("the writer conformance suite (#3159)", () => {
+  test.concurrent("a writer that writes only through chant passes every action, the amnesia test and its holdings", async () => {
+    const report = await runWorkspaceWriterConformance(cachingWriter, { privateState: [{ path: "cache", is: "cache" }] });
+    expect(report.problems).toEqual([]);
+    expect(report.checked).toEqual([...WRITE_CONTRACT_ACTIONS]);
+    expect(report.skipped).toEqual([]);
+    expect(report.results.map((r) => [r.id, r.by])).toEqual(WRITER_SCRIPT.map((s) => [s.id, "writer"]));
+    expect(report.facts.after).toEqual(report.facts.before);
+    expect(report.facts.before).toMatchObject({
+      decision: [["fix-001", "decided"], ["fix-002", "proposed"]],
+      session: [["S-0001", "closed"]],
+      answer: [[expect.stringMatching(/^slice-tier-/), "answered"]],
+      work: [["W-001", "open"]],
+      runs: [["conformance-run", "ended"], ["writer-run-1", "ended"], ["writer-run-2", "ended"]],
+    });
+  }, 900_000);
+
+  test.concurrent("a writer that breaks the rules is caught at each step and after", async () => {
+    const report = await runWorkspaceWriterConformance(leakyWriter, {
+      actions: ["records new", "records amend", "records review", "points answer"],
+      privateState: [{ path: "reviews.json", is: "cache" }],
+    });
+    expect(report.checked).toEqual(["records new", "records amend", "records review", "points answer"]);
+    const by = Object.fromEntries(report.results.map((r) => [r.id, r]));
+    expect(by.claim.by).toBe("suite");
+    expect(by.session.problems).toEqual([]);
+    expect(by.decision.problems).toEqual(["decision (records new): the writer must return the document chant printed, unchanged, and it returned something else"]);
+    expect(by.amend.problems).toHaveLength(2);
+    expect(by.amend.problems[0]).toMatch(/^amend \(records amend\): made 2 chant calls .* expected exactly one$/);
+    expect(by.amend.problems[1]).toMatch(/^amend \(records amend\): files changed that chant did not report writing: decisions\/fix-003-a-decision-nobody-asked-for\.md \(added\)$/);
+    expect(by.review.problems).toEqual([]);
+    expect(by.answer.problems).toEqual([expect.stringMatching(/^answer \(points answer\): .* it may add only nothing or --json, and it added --dry-run$/)]);
+    expect(report.after.facts).toEqual([
+      "facts: before amnesia, facts() made calls outside the read contract: workspace runs start --from -",
+      "facts: after amnesia, facts() made calls outside the read contract: workspace runs start --from -",
+    ]);
+    expect(report.after.state).toEqual(["state: the writer keeps notes.txt in its state directory, and privateState does not declare it"]);
+    expect(report.after.amnesia).toEqual([expect.stringMatching(/^amnesia: after its private state was deleted, the writer shows other facts; before: \{"reviews":\[\{"id":"fix-002".*after: \{"reviews":\[\]\}$/)]);
+    expect(report.after.holds).toEqual([
+      "holds: the writer holds record fix-999 of decisions/decision.kind.mjs, which the repository does not have",
+      'holds: events is held as "database"; outside the repo a tool keeps only cache, telemetry, secret, runtime (ws-074)',
+    ]);
+    expect(report.after.readBack).toEqual([]);
+  }, 900_000);
+});

package/src/workspace/conformance/writer.test.ts

@@ -0,0 +1,156 @@
+/**
+ * The writer conformance suite's checks on their own (#3159): the calls a
+ * step may make, the changes a step may leave, the state a writer may keep,
+ * and the fixture it writes to. No chant runs here; the suite run end to end
+ * is writer-conformance.e2e.test.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  buildStep,
+  isReadCall,
+  reportedWrites,
+  selectActions,
+  undeclaredState,
+  unreportedChanges,
+  WRITE_CONTRACT_ACTIONS,
+  WRITE_CONTRACT_SCHEMAS,
+  writeArgv,
+  writeContractSchema,
+  writerCallProblems,
+  writerDocumentProblems,
+  WRITER_FIXTURE_DIR,
+  WRITER_SCRIPT,
+  type ChantRun,
+  type WriteStep,
+} from "./index";
+
+const repoRoot = resolve(import.meta.dirname, "..", "..", "..", "..", "..");
+
+const review = buildStep(WRITER_SCRIPT.find((s) => s.id === "review")!, { decision: { id: "fix-002" } });
+const decision = buildStep(WRITER_SCRIPT.find((s) => s.id === "decision")!, {});
+const run = (argv: string[], input?: string, stdout = ""): ChantRun => ({ argv, ...(input === undefined ? {} : { input }), status: 0, stdout, stderr: "" });
+
+describe("the script (#3159)", () => {
+  test("covers every write-contract action, and each action has a schema that ships", () => {
+    expect(new Set(WRITER_SCRIPT.map((s) => s.action))).toEqual(new Set(WRITE_CONTRACT_ACTIONS));
+    for (const a of WRITE_CONTRACT_ACTIONS) expect(writeContractSchema(a).schema.$id, a).toMatch(new RegExp(`/${WRITE_CONTRACT_SCHEMAS[a].replace(".", "\\.")}$`));
+  });
+
+  test("writeArgv: fields go on stdin, everything else is a flag", () => {
+    expect(review.args).toEqual(["fix-002", "--kind", "decisions/decision.kind.mjs", "--verdict", "agree", "--by", "conformance-reviewer", "--note", "Written through chant, read back after amnesia."]);
+    expect(review.input).toBeUndefined();
+    expect(decision.args).toEqual(["decisions/decision.kind.mjs", "--from", "-"]);
+    expect(JSON.parse(decision.input!)).toMatchObject({ title: "How a writer writes the workspace", state: "proposed" });
+    expect(writeArgv("work evidence", { id: "W-001", kind: "work/work.kind.mjs", holder: "h", token: "t", entry: { criterion: "AC-1" } })).toEqual({
+      args: ["W-001", "--holder", "h", "--token", "t", "--from", "-", "--kind", "work/work.kind.mjs"],
+      input: '{"criterion":"AC-1"}',
+    });
+    expect(writeArgv("runs end", { id: "r", fields: {} })).toEqual({ args: ["r", "--from", "-"], input: "{}" });
+  });
+
+  test("a later step's params come from the documents of the steps before it", () => {
+    const renew = buildStep(WRITER_SCRIPT.find((s) => s.id === "renew")!, { claim: { lease: { token: "tok-1" } } });
+    expect(renew.args).toEqual(["W-001", "--holder", "conformance-writer", "--token", "tok-1", "--kind", "work/work.kind.mjs"]);
+  });
+
+  test("selectActions refuses a name that is not an action, and an empty list", () => {
+    expect(selectActions(["records review", "points answer"])).toEqual({
+      checked: ["records review", "points answer"],
+      skipped: WRITE_CONTRACT_ACTIONS.filter((a) => a !== "records review" && a !== "points answer"),
+    });
+    expect(() => selectActions(["records pin" as never])).toThrow(/not write-contract actions: records pin/);
+    expect(() => selectActions([])).toThrow(/actions is empty/);
+  });
+});
+
+describe("writerCallProblems (#3159)", () => {
+  test("exactly one call of the action, its arguments in order, its JSON flag, its fields on stdin", () => {
+    expect(writerCallProblems(review, [run(["workspace", "records", "review", ...review.args])])).toEqual([]);
+    expect(writerCallProblems(review, [run(["workspace", "records", "review", ...review.args, "--json"])])).toEqual([]);
+    expect(writerCallProblems(decision, [run(["workspace", "records", "new", ...decision.args], JSON.stringify(JSON.parse(decision.input!), null, 2))])).toEqual([]);
+  });
+
+  test("a second call, another command, an extra flag, other fields or stdin for a command that reads none", () => {
+    const argv = ["workspace", "records", "review", ...review.args];
+    expect(writerCallProblems(review, [run(["workspace", "ls", "--json"]), run(argv)])[0]).toMatch(/^review \(records review\): made 2 chant calls .* expected exactly one$/);
+    expect(writerCallProblems(review, [run(["workspace", "records", "amend", ...review.args])])[0]).toMatch(/which is not workspace records review/);
+    expect(writerCallProblems(review, [run([...argv, "--dry-run"])])[0]).toMatch(/it may add only nothing or --json, and it added --dry-run/);
+    expect(writerCallProblems(review, [run(argv, "{}")])[0]).toMatch(/gave chant .* something on stdin, and the command reads nothing there/);
+    expect(writerCallProblems(decision, [run(["workspace", "records", "new", ...decision.args], '{"title":"other"}')])[0]).toMatch(/other fields on stdin than the step's/);
+  });
+});
+
+describe("writerDocumentProblems (#3159)", () => {
+  test("a refusal, a changed document and one that does not validate", () => {
+    const refusal = { $schema: writeContractSchema("records review").schema.$id, contract: 1, error: { code: "record-not-found", message: "no fix-002" } };
+    const printed = run(["workspace", "records", "review"], undefined, JSON.stringify(refusal));
+    expect(writerDocumentProblems(review, printed, refusal)).toEqual(["review (records review): chant did not write: record-not-found: no fix-002"]);
+    expect(writerDocumentProblems(review, printed, { ...refusal, extra: 1 }).join("\n")).toMatch(/must return the document chant printed, unchanged/);
+    const bad = { $schema: refusal.$schema, contract: 2 };
+    expect(writerDocumentProblems(review, run([], undefined, JSON.stringify(bad)), bad).join("\n")).toMatch(/does not validate against records-review.schema.json/);
+    expect(writerDocumentProblems(review, run(["workspace"], undefined, ""), undefined)).toEqual(["review (records review): chant workspace printed nothing"]);
+  });
+});
+
+describe("unreportedChanges (#3159)", () => {
+  const files = (o: Record<string, string>) => o;
+  test("a record write may change only the path it reports, and no ref", () => {
+    const doc = { path: "decisions/fix-002-x.md" };
+    expect(unreportedChanges(review, doc, { before: files({ a: "1" }), after: files({ a: "1", "decisions/fix-002-x.md": "2" }) }, { before: { HEAD: "m 1" }, after: { HEAD: "m 1" } })).toEqual([]);
+    expect(unreportedChanges(review, doc, { before: files({ a: "1" }), after: files({ a: "9", "notes.md": "2" }) }, { before: { HEAD: "m 1" }, after: { HEAD: "m 2" } })).toEqual([
+      "review (records review): files changed that chant did not report writing: a (changed), notes.md (added)",
+      "review (records review): git refs changed that chant did not report writing: HEAD",
+    ]);
+  });
+
+  test("a lease may move its ref and chant/lifecycle to the commit it reports; a run only chant/lifecycle", () => {
+    const claim = buildStep(WRITER_SCRIPT.find((s) => s.id === "claim")!, {});
+    const doc = { ref: "refs/chant/lease/work/W-001", history: { commit: "c2" } };
+    expect(reportedWrites("work claim", doc)).toEqual({ paths: [], refs: { "refs/heads/chant/lifecycle": "c2", "refs/chant/lease/work/W-001": "*" } });
+    const before = { "refs/heads/chant/lifecycle": "c1", HEAD: "m 1" };
+    expect(unreportedChanges(claim, doc, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c2", "refs/chant/lease/work/W-001": "b" } })).toEqual([]);
+    expect(unreportedChanges(claim, doc, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c3" } })[0]).toMatch(/git refs changed that chant did not report writing: refs\/heads\/chant\/lifecycle/);
+    const start = { id: "run-start", action: "runs start", params: { run: {} }, args: ["--from", "-"], input: "{}" } as WriteStep;
+    expect(unreportedChanges(start, { ledger: { commit: "c2" } }, { before: {}, after: {} }, { before, after: { ...before, "refs/heads/chant/lifecycle": "c2" } })).toEqual([]);
+  });
+});
+
+describe("state and reads (#3159)", () => {
+  test("undeclaredState: everything in the state directory is declared, as one of ws-074's four", () => {
+    expect(undeclaredState(["hud/events.db", "hud/events.db-wal"], [{ path: "hud", is: "cache" }])).toEqual([]);
+    expect(undeclaredState(["events.db", "notes.json"], [{ path: "events.db", is: ["cache", "telemetry"] }])).toEqual([
+      "state: the writer keeps notes.json in its state directory, and privateState does not declare it",
+    ]);
+    expect(undeclaredState([], [{ path: "db", is: "database" as never }])[0]).toMatch(/private state is cache, telemetry, secret, runtime/);
+  });
+
+  test("isReadCall: the read contract, never a write verb", () => {
+    for (const argv of [["workspace", "records", "--kind", "k", "--json"], ["workspace", "records", "--uncommitted", "--json"], ["workspace", "runs", "--json"], ["workspace", "points", "--open", "--json"], ["workspace", "work", "history", "W-001"], ["workspace", "ls", "--json"]]) {
+      expect(isReadCall(argv), argv.join(" ")).toBe(true);
+    }
+    for (const argv of [["workspace", "records", "new"], ["workspace", "runs", "start"], ["workspace", "points", "answer"], ["workspace", "work", "claim"], ["workspace", "work", "evidence"], ["build"]]) {
+      expect(isReadCall(argv), argv.join(" ")).toBe(false);
+    }
+  });
+});
+
+describe("the writer fixture (#3159)", () => {
+  test("its kinds, schemas and decision points are the reference workspace's", () => {
+    const same: [string, string][] = [
+      ["work/work.kind.mjs", "work/work.kind.mjs"],
+      ["work/work.schema.json", "work/work.schema.json"],
+      ["answers/answer.kind.mjs", "answers/answer.kind.mjs"],
+      ["answers/answer.schema.json", "answers/answer.schema.json"],
+      ["decisions/points.json", "decisions/points.json"],
+      ["sessions/session.schema.json", "design/sessions/session.schema.json"],
+    ];
+    for (const [ours, theirs] of same) expect(readFileSync(join(WRITER_FIXTURE_DIR, ours), "utf-8"), ours).toBe(readFileSync(join(repoRoot, "reference-workspace", theirs), "utf-8"));
+    // The session kind sits one directory higher here than in the reference
+    // workspace's design member, so its subjects path is one level shorter.
+    const session = readFileSync(join(repoRoot, "reference-workspace", "design", "sessions", "session.kind.mjs"), "utf-8").replace('"../../decisions/decision.kind.mjs"', '"../decisions/decision.kind.mjs"');
+    expect(readFileSync(join(WRITER_FIXTURE_DIR, "sessions", "session.kind.mjs"), "utf-8")).toBe(session);
+  });
+});