@intentius/chant 0.102.0 → 0.104.1

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

@@ -38,6 +38,7 @@ const JSON_FLAG: Record<ReadContractCommand, string[]> = {
   "graph --intent": ["--json"],
   "graph --composites": ["--json"],
   runs: ["--json"],
+  wip: ["--json"],
 };
 
 /** The smallest reader that conforms, with a hook to misbehave. */
@@ -119,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", "records --uncommitted", "graph --intent", "runs"]);
+    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,5 +1,5 @@
 // The entry of `@intentius/chant/workspace/conformance` for plain Node
-// (#2679): the reader suite, and the writer suite (#3159). The suites are
+// (#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
@@ -42,6 +42,11 @@ export const {
   WRITER_PRINCIPALS,
   WRITER_SCRIPT,
   WRITER_FIXTURE_DIR,
+  WRITER_BOX,
+  WRITER_INPUTS,
+  writeWriterInputs,
+  readListing,
+  readWip,
   PRIVATE_STATE_CATEGORIES,
   writeArgv,
   writeContractSchema,
@@ -59,4 +64,20 @@ export const {
   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

@@ -56,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", "records --uncommitted", "graph --intent", "graph --composites", "runs"] 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];
 
 /**
@@ -74,6 +74,7 @@ export const READ_CONTRACT_SCHEMAS: Record<ReadContractCommand, string> = {
   "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. */
@@ -87,6 +88,7 @@ export const READ_CONTRACT_JSON_FLAGS: Record<ReadContractCommand, readonly (rea
   "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. */
@@ -100,6 +102,7 @@ export const REFERENCE_READS: Record<ReadContractCommand, string[]> = {
   "graph --intent": ["app/src/server.mjs:19", "--kind", "decisions/decision.kind.mjs"],
   "graph --composites": [],
   runs: [],
+  wip: [],
 };
 
 /** One chant run: the arguments after `chant`, what it was given on stdin, and what it printed. */
@@ -744,3 +747,4 @@ export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFacto
 
 // The writer suite (#3159), published from this same entry.
 export * from "./writer";
+export * from "./broker";

package/src/workspace/conformance/vitest.ts

@@ -6,7 +6,8 @@
  * (#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.
+ * runner. {@link describeBrokerConformance} (#3164) makes one test per check
+ * of the broker suite.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -26,6 +27,10 @@ import {
   type WorkspaceReaderConformanceConfig,
   type WorkspaceWriterConformanceConfig,
   type WorkspaceWriterConformanceReport,
+  brokerChecks,
+  runBrokerCheck,
+  startBrokerConformance,
+  type BrokerConformanceConfig,
 } from "./index";
 
 export function describeWorkspaceReaderConformance(config: WorkspaceReaderConformanceConfig): void {
@@ -110,4 +115,31 @@ export function describeWorkspaceWriterConformance(config: WorkspaceWriterConfor
   });
 }
 
+/**
+ * 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";

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

@@ -5,6 +5,7 @@
  * run on a workspace generated from the shipped fixtures, at the same time.
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
@@ -13,6 +14,7 @@ import {
   runWorkspaceWriterConformance,
   WRITE_CONTRACT_ACTIONS,
   WRITE_CONTRACT_JSON_FLAGS,
+  WRITER_INPUTS,
   WRITER_KINDS,
   WRITER_SCRIPT,
   type ChantTransport,
@@ -69,7 +71,7 @@ const leakyWriter: WorkspaceWriterFactory = (chant, { stateDir }) => {
         writeFileSync(join(stateDir, "notes.txt"), "kept and not declared");
         return doc;
       }
-      if (step.id === "answer") return perform(chant, step, ["--dry-run"]);
+      if (step.id === "reanswer") return perform(chant, step, ["--dry-run"]);
       return perform(chant, step);
     },
     async facts() {
@@ -92,12 +94,29 @@ describe("the writer conformance suite (#3159)", () => {
     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);
+    // #3173: three amendments of one record at once, one written, two refused with record-conflict and written on retry.
+    expect(report.after.concurrent).toEqual([]);
     expect(report.facts.before).toMatchObject({
       decision: [["fix-001", "decided"], ["fix-002", "proposed"]],
       session: [["S-0001", "closed"]],
-      answer: [[expect.stringMatching(/^slice-tier-/), "answered"]],
+      // #3403: the ad-hoc question an agent asked, answered from the options it offered.
+      answer: [
+        [expect.stringMatching(/^agent-question-/), "answered"],
+        [expect.stringMatching(/^slice-tier-/), "answered"],
+      ],
       work: [["W-001", "open"]],
       runs: [["conformance-run", "ended"], ["writer-run-1", "ended"], ["writer-run-2", "ended"]],
+      // #3308: the box's listing, set through chant with its cover copied in, survives amnesia.
+      listing: {
+        app: {
+          published: true,
+          title: "The writer suite's box",
+          line: "Listed through chant, read back after amnesia.",
+          cover: { path: "app/listing/cover.png", sha256: createHash("sha256").update(WRITER_INPUTS.cover.bytes).digest("hex") },
+        },
+      },
+      // #3172: the checkpoint of the uncommitted work; restoring it to the same tree takes no second one.
+      wip: { main: [["save", "turn:1"]] },
     });
   }, 900_000);
 
@@ -109,13 +128,19 @@ describe("the writer conformance suite (#3159)", () => {
     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.listing).toMatchObject({ by: "suite", problems: [] });
+    expect(by.checkpoint).toMatchObject({ by: "suite", problems: [] });
+    expect(by.undo).toMatchObject({ by: "suite", problems: [] });
     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(by.answer.problems).toEqual([]);
+    expect(by.retract.by).toBe("suite");
+    expect(by.retract.problems).toEqual([]);
+    expect(by.reanswer.problems).toEqual([expect.stringMatching(/^reanswer \(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 -",
@@ -127,5 +152,26 @@ describe("the writer conformance suite (#3159)", () => {
       'holds: events is held as "database"; outside the repo a tool keeps only cache, telemetry, secret, runtime (ws-074)',
     ]);
     expect(report.after.readBack).toEqual([]);
+    expect(report.after.concurrent).toEqual([]);
+  }, 900_000);
+
+  test.concurrent("a writer that hides a conflict by writing again without --expect is caught (#3173)", async () => {
+    const blindRetry: WorkspaceWriterFactory = (chant, ctx) => {
+      const inner = referenceWriter(chant, ctx);
+      return {
+        async write(step) {
+          const doc = (await inner.write(step)) as { error?: { code: string } };
+          if (doc.error?.code !== "record-conflict" || step.action !== "records amend") return doc;
+          // Overwrites whatever the other writer wrote, and reports success.
+          const args = step.args.filter((a, i, all) => a !== "--expect" && all[i - 1] !== "--expect");
+          return JSON.parse((await chant.run(["workspace", "records", "amend", ...args], { input: step.input })).stdout);
+        },
+        facts: () => inner.facts(),
+      };
+    };
+    const report = await runWorkspaceWriterConformance(blindRetry, { actions: ["records amend"] });
+    expect(report.after.concurrent.length).toBeGreaterThan(0);
+    expect(report.after.concurrent.every((p) => p.startsWith("concurrent: "))).toBe(true);
+    expect(report.after.concurrent.join("\n")).toMatch(/made 2 chant calls/);
   }, 900_000);
 });

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

@@ -49,6 +49,25 @@ describe("the script (#3159)", () => {
       input: '{"criterion":"AC-1"}',
     });
     expect(writeArgv("runs end", { id: "r", fields: {} })).toEqual({ args: ["r", "--from", "-"], input: "{}" });
+    expect(writeArgv("box listing set", { member: "app", fields: { title: "T" }, cover: "/in/cover.png" })).toEqual({
+      args: ["app", "--from", "-", "--cover", "/in/cover.png"],
+      input: '{"title":"T"}',
+    });
+    const listing = buildStep(WRITER_SCRIPT.find((s) => s.id === "listing")!, {}, { dir: "/in" });
+    expect(listing.args).toEqual(["app", "--from", "-", "--cover", "/in/cover.png"]);
+    expect(buildStep(WRITER_SCRIPT.find((s) => s.id === "listing")!, {}).args).toEqual(["app", "--from", "-"]);
+    // #3403: an ad-hoc ask reads its question and candidates on stdin, and takes the inputs as JSON.
+    const adhoc = buildStep(WRITER_SCRIPT.find((s) => s.id === "adhoc")!, {});
+    expect(adhoc.args).toEqual(["agent-question", "--inputs", '{"ask.id":"conformance-ask-1","ask.by":"conformance-writer"}', "--candidates", "-", "--subject", "W-001", "--kind", "answers/answer.kind.mjs"]);
+    expect(JSON.parse(adhoc.input!)).toMatchObject({ question: expect.any(String), criteria: { flag: expect.any(String), now: expect.any(String) } });
+    // The inputs may be spelled with other key order or spacing.
+    const respelled = ["workspace", "points", "ask", "agent-question", "--inputs", '{ "ask.by": "conformance-writer", "ask.id": "conformance-ask-1" }', "--candidates", "-", "--subject", "W-001", "--kind", "answers/answer.kind.mjs"];
+    expect(writerCallProblems(adhoc, [run(respelled, adhoc.input)])).toEqual([]);
+    expect(writerCallProblems(adhoc, [run(respelled.map((a) => (a.includes("ask.id") ? '{"ask.id":"other"}' : a)), adhoc.input)])).toHaveLength(1);
+    // #3172: a snapshot takes no stdin, and the restore names the snapshot the save took.
+    expect(writeArgv("wip save", { label: "turn:1", by: "p" })).toEqual({ args: ["--label", "turn:1", "--by", "p"] });
+    expect(writeArgv("wip save", {})).toEqual({ args: [] });
+    expect(buildStep(WRITER_SCRIPT.find((s) => s.id === "undo")!, { checkpoint: { snapshot: { commit: "c0ffee" } } }).args).toEqual(["c0ffee", "--by", "conformance"]);
   });
 
   test("a later step's params come from the documents of the steps before it", () => {
@@ -110,6 +129,12 @@ describe("unreportedChanges (#3159)", () => {
     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": "*" } });
+    expect(reportedWrites("wip save", { ref: "refs/chant/wip/main", snapshot: { commit: "s1" }, replication: { remote: "origin", pushed: [{ ref: "refs/chant/wip/main", commit: "s1" }] } })).toEqual({
+      paths: [],
+      refs: { "refs/chant/wip/main": "s1", "refs/chant/replica/origin/chant/wip/main": "s1" },
+    });
+    expect(reportedWrites("wip restore", { ref: "refs/chant/wip/main", checkpoint: { snapshot: { commit: "s2" } }, paths: ["a.txt"] })).toEqual({ paths: ["a.txt"], refs: { "refs/chant/wip/main": "s2" } });
+    expect(reportedWrites("box listing set", { paths: ["app/listing/cover.png", "chant.workspace.json"], declaration: { path: "chant.workspace.json" } })).toEqual({ paths: ["app/listing/cover.png", "chant.workspace.json"], refs: {} });
     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/);
@@ -128,10 +153,10 @@ describe("state and reads (#3159)", () => {
   });
 
   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"]]) {
+    for (const argv of [["workspace", "wip", "--json"], ["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"]]) {
+    for (const argv of [["workspace", "wip", "save"], ["workspace", "wip", "restore"], ["workspace", "wip", "push"], ["workspace", "wip", "fetch"], ["workspace", "records", "new"], ["workspace", "runs", "start"], ["workspace", "points", "answer"], ["workspace", "points", "retract"], ["workspace", "work", "claim"], ["workspace", "work", "evidence"], ["build"]]) {
       expect(isReadCall(argv), argv.join(" ")).toBe(false);
     }
   });
@@ -146,6 +171,11 @@ describe("the writer fixture (#3159)", () => {
       ["answers/answer.schema.json", "answers/answer.schema.json"],
       ["decisions/points.json", "decisions/points.json"],
       ["sessions/session.schema.json", "design/sessions/session.schema.json"],
+      // The session kind's other subject kinds (#3148).
+      ["contracts/contract.kind.mjs", "design/contracts/contract.kind.mjs"],
+      ["contracts/contract.schema.json", "design/contracts/contract.schema.json"],
+      ["drivers/driver.kind.mjs", "design/drivers/driver.kind.mjs"],
+      ["drivers/driver.schema.json", "design/drivers/driver.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