@intentius/chant 0.101.0 → 0.104.0

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

@@ -5,6 +5,7 @@
  * ships.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
@@ -12,6 +13,7 @@ import {
   checkReaderRead,
   CONFORMANCE_FIXTURE_DIR,
   createConformanceWorkspace,
+  UNCOMMITTED_DECISION,
   READ_CONTRACT_COMMANDS,
   REFERENCE_READS,
   runWorkspaceReaderConformance,
@@ -32,8 +34,11 @@ const JSON_FLAG: Record<ReadContractCommand, string[]> = {
   check: ["--format", "json"],
   status: ["--json"],
   records: ["--json"],
+  "records --uncommitted": ["--json"],
   "graph --intent": ["--json"],
   "graph --composites": ["--json"],
+  runs: ["--json"],
+  wip: ["--json"],
 };
 
 /** The smallest reader that conforms, with a hook to misbehave. */
@@ -48,7 +53,7 @@ function reader(twist: (doc: Record<string, unknown>, chant: ChantTransport) =>
 
 let ws: ConformanceWorkspace;
 beforeAll(() => {
-  ws = createConformanceWorkspace();
+  ws = createConformanceWorkspace({ uncommitted: true });
 }, 300_000);
 afterAll(() => ws?.dispose());
 
@@ -72,9 +77,37 @@ describe("the generated conformance workspace (#2679)", () => {
   test("the decision record and the region the intent read names are in the workspace", async () => {
     const docs: Record<string, unknown>[] = [];
     await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["records", "graph --intent"] });
-    expect((docs[0].records as { id: string }[]).map((r) => r.id)).toEqual(["fix-001"]);
+    expect((docs[0].records as { id: string; worktree: string }[]).map((r) => [r.id, r.worktree])).toEqual([
+      ["fix-001", "committed"],
+      ["fix-002", "new"],
+    ]);
     expect(docs[1].region).toBe(`region:${REFERENCE_READS["graph --intent"][0]}`);
   }, 300_000);
+
+  test("records --uncommitted lists the decision the workspace leaves uncommitted, with the branch, head and base (#3160)", async () => {
+    const docs: Record<string, unknown>[] = [];
+    const report = await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["records --uncommitted"] });
+    expect(report.problems).toEqual([]);
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: ws.dir, encoding: "utf-8" }).trim();
+    expect(docs[0]).toMatchObject({
+      uncommitted: true,
+      checkout: { branch: "main", head, base: head, baseFrom: "main", deleted: [] },
+      records: [{ id: "fix-002", path: UNCOMMITTED_DECISION.path, worktree: "new", state: "proposed", valid: true }],
+      summary: { total: 1, valid: 1, invalid: 0 },
+    });
+  }, 300_000);
+});
+
+describe("the generated workspace's agent run (#3033)", () => {
+  test("runs reads the run the workspace commit names, joined by its trailer and its record", async () => {
+    const docs: Record<string, unknown>[] = [];
+    const report = await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["runs"] });
+    expect(report.problems).toEqual([]);
+    expect(docs[0]).toMatchObject({
+      runs: [{ id: "conformance-run", state: "ended", by: "conformance", cost: { amount: 0.01, currency: "USD" }, commits: [{ joinedBy: ["record", "trailer"] }] }],
+      totals: { all: { runs: 1, unpriced: [] } },
+    });
+  }, 300_000);
 });
 
 describe("commands (#2679)", () => {
@@ -87,7 +120,7 @@ describe("commands (#2679)", () => {
     expect(report.problems).toEqual([]);
     expect(read).toEqual(["ls", "status", "graph --composites"]);
     expect(report.checked).toEqual(["ls", "status", "graph --composites"]);
-    expect(report.skipped).toEqual(["graph", "check", "records", "graph --intent"]);
+    expect(report.skipped).toEqual(["graph", "check", "records", "records --uncommitted", "graph --intent", "runs", "wip"]);
   }, 300_000);
 
   test("a name that is not a contract command, or an empty list, is refused", () => {

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, the writer suite (#3159), and the broker suite (#3164). 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,50 @@ 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,
+  WRITER_BOX,
+  WRITER_INPUTS,
+  writeWriterInputs,
+  readListing,
+  readWip,
+  PRIVATE_STATE_CATEGORIES,
+  writeArgv,
+  writeContractSchema,
+  worktreeDigest,
+  gitRefs,
+  refChanges,
+  isReadCall,
+  writerCallProblems,
+  writerDocumentProblems,
+  reportedWrites,
+  unreportedChanges,
+  buildStep,
+  referenceWriter,
+  createWriterConformanceWorkspace,
+  selectActions,
+  undeclaredState,
+  runWorkspaceWriterConformance,
+  CONCURRENT_AMENDS,
+  concurrentAmendStep,
+  concurrentAmends,
+  BROKER_CONFORMANCE_CAPABILITIES,
+  LOBBY_CAPABILITIES,
+  CONFORMANCE_BOXES,
+  CONFORMANCE_SECRET,
+  CONFORMANCE_UNHELD_SECRET,
+  BROKER_CHECKS,
+  brokerChecks,
+  brokerSchemaValidator,
+  schemaInstance,
+  startBrokerConformance,
+  runBrokerCheck,
+  runBrokerConformance,
+  upstreamHandlers,
 } = 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", "wip"] as const;
 export type ReadContractCommand = (typeof READ_CONTRACT_COMMANDS)[number];
 
 /**
@@ -62,8 +70,11 @@ 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",
+  wip: "wip.schema.json",
 };
 
 /** The flags that ask each command for its JSON document. A reader adds one of these and nothing else. */
@@ -73,8 +84,11 @@ 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"]],
+  wip: [["--json"]],
 };
 
 /** The arguments the suite passes each read, on the reference workspace or the generated one. */
@@ -84,21 +98,31 @@ 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: [],
+  wip: [],
 };
 
-/** 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 +340,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 +376,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 +395,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 +489,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 +541,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 +563,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 +588,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 +606,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 +670,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 +744,7 @@ export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFacto
     target.dispose();
   }
 }
+
+// The writer suite (#3159), published from this same entry.
+export * from "./writer";
+export * from "./broker";

package/src/workspace/conformance/vitest.ts

@@ -2,8 +2,12 @@
  * 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. {@link describeBrokerConformance} (#3164) makes one test per check
+ * of the broker suite.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -17,7 +21,16 @@ import {
   selectCommands,
   treeChanges,
   treeDigest,
+  runWorkspaceWriterConformance,
+  selectActions,
+  WRITER_SCRIPT,
   type WorkspaceReaderConformanceConfig,
+  type WorkspaceWriterConformanceConfig,
+  type WorkspaceWriterConformanceReport,
+  brokerChecks,
+  runBrokerCheck,
+  startBrokerConformance,
+  type BrokerConformanceConfig,
 } from "./index";
 
 export function describeWorkspaceReaderConformance(config: WorkspaceReaderConformanceConfig): void {
@@ -68,4 +81,65 @@ 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([]));
+  });
+}
+
+/**
+ * The broker suite in vitest (#3164): the upstreams and the broker start
+ * before the tests, and each check is one test, run in order. A check of a
+ * capability the broker does not serve is skipped.
+ */
+export function describeBrokerConformance(config: BrokerConformanceConfig): void {
+  describe(`broker conformance (#3164): ${config.name}`, () => {
+    let run: Awaited<ReturnType<typeof startBrokerConformance>> | undefined;
+    beforeAll(async () => {
+      run = await startBrokerConformance(config);
+    }, 120_000);
+    afterAll(async () => {
+      await run?.close();
+    });
+    for (const { check, skipped } of brokerChecks(config)) {
+      if (skipped) {
+        it.skip(`${check.id}: not applicable, ${skipped}`, () => {});
+        continue;
+      }
+      it(`${check.id}: ${check.title}`, async () => {
+        expect(run, "the broker did not start").toBeDefined();
+        expect(await runBrokerCheck(run!.ctx, check)).toEqual([]);
+      }, 60_000);
+    }
+  });
+}
+
 export * from "./index";