@codespar/cli 0.16.0 → 0.18.0

package/templates/supplier-payments-agent/agents/supplier-payments-agent/test/batch.test.ts

@@ -8,8 +8,8 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { fixedClock, type Execution, type ToolContext } from "@codespar/agent-core";
-import { assembleTimeline, setup, type Setup } from "@codespar/agent-runtime";
+import { StateStore, batchAttemptId, batchHash, fixedClock, maskPayee, type Execution, type StubRail, type StubRailOptions, type ToolContext } from "@codespar/agent-core";
+import { assembleTimeline, handleExecution, parseBatchGesture, presentBatch, setup, type BatchGestures, type Setup } from "@codespar/agent-runtime";
 import { agent } from "../src/kit.js";
 import { runBatch } from "../src/modules/batch-payout.js";
 import { findBatch, type Batch } from "../src/payables.js";
@@ -27,15 +27,20 @@ function approveAndRun(s: Setup): ToolContext["onExecution"] {
   };
 }
 
-function open(stateDir: string, options: { refusePayees?: string[] } = {}): Setup {
+function open(stateDir: string, options: { refusePayees?: string[]; uncertainPayees?: string[]; ledger?: StateStore; now?: string } = {}): Setup {
+  const stubRail: StubRailOptions = {
+    ...(options.refusePayees ? { refusePayees: options.refusePayees } : {}),
+    ...(options.uncertainPayees ? { uncertainPayees: options.uncertainPayees } : {}),
+    ...(options.ledger ? { ledger: options.ledger } : {}),
+  };
   return setup(agent, {
     mode: "human",
     rail: "stub",
     provider: "replay",
     runsDir,
     stateDir,
-    now: fixedClock("2026-09-23T14:00:00-03:00"),
-    ...(options.refusePayees ? { stubRail: { refusePayees: options.refusePayees } } : {}),
+    now: fixedClock(options.now ?? "2026-09-23T14:00:00-03:00"),
+    ...(Object.keys(stubRail).length > 0 ? { stubRail } : {}),
     say: () => undefined,
   });
 }
@@ -84,6 +89,23 @@ describe("batch-payout: a batch is a loop of executions", () => {
     }
   });
 
+  it("every line presents the quote of its OWN approved line, and its receipt carries the payee that quote sealed (OPEN_QUESTIONS §18)", async () => {
+    const s = open(mkdtempSync(join(tmpdir(), "supplier-batch-q-")));
+    try {
+      await run(s, "folha-2026-10");
+      const artifacts = s.bundle.readApprovals();
+      for (const e of s.engine.list()) {
+        const line = artifacts.find((a) => a.execution_id === e.id)!.items[0]!;
+        const outcome = e.outcomes[0]!;
+        const sent = s.store.stubRailGet(outcome.attempt_id)!.request as { quote?: { price_minor: number; payee: string; seller: string } };
+        expect(sent.quote).toMatchObject({ seller: line.beneficiary, price_minor: line.amount, payee: line.payee });
+        expect(s.bundle.readReceipt(`${outcome.receipt_id}.json`)?.["payment"]).toMatchObject({ payee: maskPayee(line.payee) });
+      }
+    } finally {
+      s.close();
+    }
+  });
+
   it("one refusal does not stop the others: the lines after the refused one still dispatch", async () => {
     const s = open(mkdtempSync(join(tmpdir(), "supplier-batch-b-")), { refusePayees: ["contas@insumos-atlantico.example.com.br"] });
     try {
@@ -382,3 +404,480 @@ describe("batch-payout: the approved list is bound as a set", () => {
     }
   });
 });
+
+/**
+ * The interactive terminal's two hooks, driven by scripted answers: one
+ * question for the list, then every line decided by what was answered.
+ */
+function gestureChannel(s: Setup, answers: string[]): { ctx: ToolContext; asked: string[] } {
+  const gestures: BatchGestures = new Map();
+  const asked: string[] = [];
+  const ask = async (question: string) => {
+    asked.push(question);
+    const answer = answers.shift();
+    if (answer === undefined) throw new Error(`asked more than scripted: ${question}`);
+    return answer;
+  };
+  const options = { setup: s, approver: APPROVER, ask, say: () => undefined, gestures };
+  return {
+    asked,
+    ctx: {
+      engine: s.engine,
+      onExecution: (execution) => handleExecution(execution, options),
+      onBatch: (batch) => presentBatch(batch, options),
+    },
+  };
+}
+
+describe("batch-payout: one gesture approves the list, with a veto per line (§39e)", () => {
+  it("reads todas, todas exceto and nenhuma, and refuses to guess at anything else", () => {
+    expect(parseBatchGesture("todas", 4)).toEqual({ vetoed: [] });
+    expect(parseBatchGesture("all", 4)).toEqual({ vetoed: [] });
+    expect(parseBatchGesture("todas exceto 3", 4)).toEqual({ vetoed: [2] });
+    expect(parseBatchGesture("all except 4, 1,4", 4)).toEqual({ vetoed: [0, 3] });
+    expect(parseBatchGesture("nenhuma", 4)).toEqual({ vetoed: [0, 1, 2, 3] });
+    expect(parseBatchGesture("", 4)).toEqual({ vetoed: [0, 1, 2, 3] });
+    // A line that does not exist is a typo, and a typo must not veto nothing.
+    expect(parseBatchGesture("todas exceto 5", 4)).toBeUndefined();
+    expect(parseBatchGesture("todas exceto 0", 4)).toBeUndefined();
+    expect(parseBatchGesture("s", 4)).toBeUndefined();
+    expect(parseBatchGesture("todas menos 2", 4)).toBeUndefined();
+  });
+
+  it("approve-all is one question, and still mints one artifact per line, each naming the list", async () => {
+    const s = open(mkdtempSync(join(tmpdir(), "supplier-gesture-a-")));
+    try {
+      const batch = fourLines();
+      const channel = gestureChannel(s, ["todas"]);
+      const report = await runBatch(batch, channel.ctx);
+
+      expect(channel.asked).toHaveLength(1);
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled", "settled"]);
+      expect(report.gesture).toEqual({ batch_hash: report.batch_hash, approved: [0, 1, 2, 3], vetoed: [] });
+
+      const artifacts = s.bundle.readApprovals();
+      expect(artifacts).toHaveLength(4);
+      expect(new Set(artifacts.map((a) => a.batch!.batch_hash))).toEqual(new Set([report.batch_hash]));
+      expect(artifacts.map((a) => a.batch!.index)).toEqual([0, 1, 2, 3]);
+      for (const a of artifacts) expect(a.approver).toEqual({ type: "person", id: APPROVER.id, channel: APPROVER.channel });
+
+      // The gesture itself is in the attested record, next to the artifacts it produced.
+      const gestures = s.bundle.readEvents().filter((e) => e["type"] === "batch.gesture");
+      expect(gestures).toHaveLength(1);
+      expect(gestures[0]!["payload"]).toMatchObject({ batch_ref: batch.ref, batch_hash: report.batch_hash, count: 4, approved: [0, 1, 2, 3], vetoed: [], approver: { type: "human", id: APPROVER.id } });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("approve-except denies exactly the vetoed lines, and the report says which", async () => {
+    const s = open(mkdtempSync(join(tmpdir(), "supplier-gesture-b-")));
+    try {
+      const batch = fourLines();
+      const channel = gestureChannel(s, ["todas exceto 2,4"]);
+      const report = await runBatch(batch, channel.ctx);
+
+      expect(channel.asked).toHaveLength(1);
+      expect(report.lines.map((l) => [l.index, l.dispatch, l.state])).toEqual([
+        [0, "settled", "settled"],
+        [1, "refused", "denied"],
+        [2, "settled", "settled"],
+        [3, "refused", "denied"],
+      ]);
+      const vetoed = [batch.lines[1]!.alias, batch.lines[3]!.alias];
+      expect(report.denied).toEqual(vetoed);
+      expect(report.failed).toEqual(vetoed);
+      expect(report.gesture).toEqual({ batch_hash: report.batch_hash, approved: [0, 2], vetoed: [1, 3] });
+      expect(report.settled_minor).toBe(batch.lines[0]!.amount_minor + batch.lines[2]!.amount_minor);
+
+      // A vetoed line is a decision: it has an execution, no artifact, and says why.
+      const artifacts = s.bundle.readApprovals();
+      expect(artifacts.map((a) => a.batch!.index)).toEqual([0, 2]);
+      const denied = s.engine.list().filter((e) => e.state === "denied");
+      expect(denied.map((e) => e.batch!.index)).toEqual([1, 3]);
+      expect(denied.map((e) => e.detail)).toEqual(["vetoed in the batch gesture (line 2 of 4)", "vetoed in the batch gesture (line 4 of 4)"]);
+    } finally {
+      s.close();
+    }
+  });
+
+  it("a line that belongs to another list under the same ref is not approved by the gesture", async () => {
+    const s = open(mkdtempSync(join(tmpdir(), "supplier-gesture-c-")));
+    try {
+      const batch = fourLines();
+      const gestures: BatchGestures = new Map();
+      const options = { setup: s, approver: APPROVER, ask: async () => "todas", say: () => undefined, gestures };
+      // The person approved the four-line list...
+      const shown = await runBatch(batch, { engine: s.engine, onExecution: async (e) => e, onBatch: (b) => presentBatch(b, options) });
+      expect(shown.gesture?.vetoed).toEqual([]);
+      // ...and a line arrives claiming the same ref but a list of three with another hash.
+      const edited = await s.engine.draft({
+        items: [{ payee: batch.lines[0]!.alias, amount: batch.lines[0]!.amount_minor }],
+        batch: { ref: batch.ref, batch_hash: "sha256:" + "0".repeat(64), index: 0, count: 3 },
+      });
+      if (!edited.ok) throw new Error(edited.reason);
+      const decided = await handleExecution(edited.execution, options);
+      expect(decided.state).toBe("denied");
+      expect(decided.detail).toContain("the list changed after the gesture");
+      expect(s.bundle.readApprovals().filter((a) => a.execution_id === edited.execution.id)).toEqual([]);
+    } finally {
+      s.close();
+    }
+  });
+
+  it("an edited list after the gesture is refused before anything is drafted, and nobody is asked again", async () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "supplier-gesture-d-"));
+    const four = fourLines();
+    const first = open(stateDir);
+    try {
+      const report = await runBatch(four, gestureChannel(first, ["todas exceto 4"]).ctx);
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled", "refused"]);
+    } finally {
+      first.close();
+    }
+
+    // The fourth line's amount moves after the person approved the list.
+    const edited: Batch = { ...four, lines: four.lines.map((l, i) => (i === 3 ? { ...l, amount_minor: l.amount_minor + 100 } : l)) };
+    const second = open(stateDir);
+    try {
+      const channel = gestureChannel(second, []);
+      const report = await runBatch(edited, channel.ctx);
+      expect(channel.asked).toEqual([]);
+      expect(report.refused?.reason).toBe("batch_set_changed");
+      expect(report.gesture).toBeUndefined();
+      expect(second.engine.list()).toHaveLength(4);
+    } finally {
+      second.close();
+    }
+  });
+
+  it("without the hook nothing changes: each line is its own question, as the one-shot and the scenarios expect", async () => {
+    const s = open(mkdtempSync(join(tmpdir(), "supplier-gesture-e-")));
+    try {
+      const batch = fourLines();
+      const asked: string[] = [];
+      const options = { setup: s, approver: APPROVER, ask: async (q: string) => (asked.push(q), "s"), say: () => undefined };
+      const report = await runBatch(batch, { engine: s.engine, onExecution: (e) => handleExecution(e, options) });
+      expect(asked).toHaveLength(4);
+      expect(report.gesture).toBeUndefined();
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled", "settled"]);
+    } finally {
+      s.close();
+    }
+  });
+});
+
+/**
+ * §39c: the claim in `.codespar/state.db` is the first line of defence, and it
+ * is local. These run the same batch from several state files against ONE
+ * rail ledger that answers a repeated `attempt_id` the way the deployed API
+ * does (ent#1671, #1683): replay when settled, `psp_attempt_in_flight` while
+ * running, `psp_attempt_conflict` when it failed, `attempt_id_conflict` when
+ * the id arrives with a different payment. Another machine has no claim at
+ * all, so the only thing between it and a second payment is that it presents
+ * the same attempt, with the same quote.
+ */
+describe("batch-payout: a batch is idempotent across machines (§39c)", () => {
+  const INSUMOS = "contas@insumos-atlantico.example.com.br";
+
+  function railOf(s: Setup): StubRail {
+    return s.rail as StubRail;
+  }
+
+  function attemptsOf(s: Setup): string[] {
+    return s.engine.list().flatMap((e) => e.outcomes.map((o) => o.attempt_id));
+  }
+
+  function receiptsOf(s: Setup): Array<string | undefined> {
+    return s.engine.list().flatMap((e) => e.outcomes.map((o) => o.receipt_id));
+  }
+
+  function payloadsOf(s: Setup, type: string): Array<Record<string, unknown>> {
+    return s.store
+      .listEvents()
+      .filter((e) => e.type === type)
+      .map((e) => e.payload as Record<string, unknown>);
+  }
+
+  function newLedger(): StateStore {
+    return new StateStore(join(mkdtempSync(join(tmpdir(), "supplier-rail-ledger-")), "rail.db"));
+  }
+
+  function machine(prefix: string, options: Parameters<typeof open>[1]): Setup {
+    return open(mkdtempSync(join(tmpdir(), `supplier-machine-${prefix}-`)), options);
+  }
+
+  it("derives the attempt id from mandate, list, position and generation, and from nothing a run invents", () => {
+    const hash = "sha256:" + "1".repeat(64);
+    const id = batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 0);
+    expect(id).toMatch(/^ska_[0-9a-f]{64}$/);
+    expect(id.length).toBeLessThanOrEqual(128);
+    expect(batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 0)).toBe(id);
+    expect(batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 0, 0)).toBe(id);
+    const others = [
+      batchAttemptId("mdt_b", { batch_hash: hash, index: 2 }, 0),
+      batchAttemptId("mdt_a", { batch_hash: "sha256:" + "2".repeat(64), index: 2 }, 0),
+      batchAttemptId("mdt_a", { batch_hash: hash, index: 3 }, 0),
+      batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 1),
+      batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 0, 1),
+      batchAttemptId("mdt_a", { batch_hash: hash, index: 2 }, 0, 2),
+    ];
+    expect(new Set([id, ...others]).size).toBe(others.length + 1);
+  });
+
+  it("the same batch approved on a second machine, at another time, lands on the same attempts and pays each line once", async () => {
+    const ledger = newLedger();
+    const first = machine("a", { ledger });
+    let firstAttempts: string[];
+    let firstReceipts: Array<string | undefined>;
+    try {
+      const report = await run(first, "folha-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled"]);
+      expect(railOf(first).payCount).toBe(3);
+      firstAttempts = attemptsOf(first);
+      firstReceipts = receiptsOf(first);
+    } finally {
+      first.close();
+    }
+
+    // Another machine: no state.db, so no claim, a new run id, new execution
+    // ids, and a person approving an hour later. The approval time is not in
+    // the quote a batch line presents, so the payment is the same payment.
+    const second = machine("b", { ledger, now: "2026-09-23T15:00:00-03:00" });
+    try {
+      const report = await run(second, "folha-2026-10");
+      expect(railOf(second).payCount).toBe(0);
+      expect(attemptsOf(second)).toEqual(firstAttempts);
+      expect(receiptsOf(second)).toEqual(firstReceipts);
+      // Recorded as the line's outcome — settled, with the first run's receipt — and never as a failure that invites a retry.
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled"]);
+      expect(payloadsOf(second, "rail.outcome").map((p) => [p["status"], p["idempotent_replay"]])).toEqual([
+        ["settled", true],
+        ["settled", true],
+        ["settled", true],
+      ]);
+      expect(second.engine.list().flatMap((e) => e.outcomes.map((o) => o.replayed))).toEqual([true, true, true]);
+    } finally {
+      second.close();
+      ledger.close();
+    }
+  });
+
+  it("a list that differs in one line is a different list, and none of its attempt ids is reused", async () => {
+    const ledger = newLedger();
+    const batch = findBatch("folha-2026-10")!;
+    const changed: Batch = { ...batch, lines: batch.lines.map((l, i) => (i === 2 ? { ...l, amount_minor: l.amount_minor + 100 } : l)) };
+    const first = machine("c", { ledger });
+    const second = machine("d", { ledger });
+    try {
+      const a = await runBatch(batch, { engine: first.engine, onExecution: approveAndRun(first) });
+      const b = await runBatch(changed, { engine: second.engine, onExecution: approveAndRun(second) });
+      expect(b.batch_hash).not.toBe(a.batch_hash);
+      const shared = attemptsOf(first).filter((id) => attemptsOf(second).includes(id));
+      expect(shared).toEqual([]);
+      // Unchanged lines of a changed list are new attempts: the id names a line of THIS list.
+      expect(railOf(second).payCount).toBe(3);
+    } finally {
+      first.close();
+      second.close();
+      ledger.close();
+    }
+  });
+
+  it("a line the provider refused is paid once by the next machine, under the next generation, and a third machine replays it", async () => {
+    const ledger = newLedger();
+    const first = machine("e", { ledger, refusePayees: [INSUMOS] });
+    let refusedAttempt: string;
+    try {
+      const report = await run(first, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "refused", "settled"]);
+      refusedAttempt = first.engine.list()[1]!.outcomes[0]!.attempt_id;
+    } finally {
+      first.close();
+    }
+
+    const second = machine("f", { ledger });
+    let paidAttempt: string;
+    try {
+      const report = await run(second, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled"]);
+      // One new payment: the refused line. The other two replayed.
+      expect(railOf(second).payCount).toBe(1);
+      const line = second.engine.list()[1]!;
+      paidAttempt = line.outcomes[0]!.attempt_id;
+      expect(paidAttempt).toBe(batchAttemptId(line.mandate.id, line.batch!, 0, 1));
+      expect(paidAttempt).not.toBe(refusedAttempt);
+      expect(line.attempt_generations).toEqual({ 0: 1 });
+      expect(payloadsOf(second, "rail.attempt_spent").map((p) => p["attempt_id"])).toEqual([refusedAttempt]);
+    } finally {
+      second.close();
+    }
+
+    const third = machine("g", { ledger });
+    try {
+      const report = await run(third, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "settled", "settled"]);
+      expect(railOf(third).payCount).toBe(0);
+      expect(third.engine.list()[1]!.outcomes[0]!.attempt_id).toBe(paidAttempt);
+    } finally {
+      third.close();
+      ledger.close();
+    }
+  });
+
+  it("a reconcile looks up the generation that was actually sent, not the spent one before it", async () => {
+    const ledger = newLedger();
+    const first = machine("j", { ledger, refusePayees: [INSUMOS] });
+    try {
+      await run(first, "fornecedores-2026-10");
+    } finally {
+      first.close();
+    }
+
+    // Generation 0 is spent; generation 1 goes out and its answer is lost.
+    const second = machine("k", { ledger, uncertainPayees: [INSUMOS] });
+    try {
+      const report = await run(second, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "uncertain", "settled"]);
+      const line = second.engine.list()[1]!;
+      expect(line.attempt_generations).toEqual({ 0: 1 });
+      const sent = batchAttemptId(line.mandate.id, line.batch!, 0, 1);
+      await second.engine.reconcile(line.id);
+      const closed = await second.engine.reconcile(line.id);
+      expect(closed.state).toBe("settled");
+      expect(closed.outcomes[0]!.attempt_id).toBe(sent);
+      expect(payloadsOf(second, "rail.reconcile").map((p) => p["attempt_id"])).toEqual([sent, sent]);
+      expect(railOf(second).payCount).toBe(0);
+    } finally {
+      second.close();
+      ledger.close();
+    }
+  });
+
+  it("A pays at generation 2 after generation 1 failed; B, still at generation 1, is told it is spent, advances, and gets A's payment as a replay", async () => {
+    const ledger = newLedger();
+    // A: the provider refuses generation 0.
+    const a = mkdtempSync(join(tmpdir(), "supplier-machine-l-"));
+    let s = open(a, { ledger, refusePayees: [INSUMOS] });
+    try {
+      await run(s, "fornecedores-2026-10");
+    } finally {
+      s.close();
+    }
+    // B: generation 0 is spent, so it presents generation 1, which the provider also refuses. B is left at generation 1.
+    const b = mkdtempSync(join(tmpdir(), "supplier-machine-m-"));
+    s = open(b, { ledger, refusePayees: [INSUMOS] });
+    let g1: string;
+    try {
+      await run(s, "fornecedores-2026-10");
+      const line = s.engine.list()[1]!;
+      expect(line.state).toBe("failed");
+      expect(line.attempt_generations).toEqual({ 0: 1 });
+      g1 = line.outcomes[0]!.attempt_id;
+    } finally {
+      s.close();
+    }
+    // A again, the provider now accepting: 0 and 1 are spent, generation 2 is paid.
+    s = open(a, { ledger });
+    let g2: string;
+    let receipt: string | undefined;
+    try {
+      const report = await run(s, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["already_settled", "settled", "already_settled"]);
+      expect(railOf(s).payCount).toBe(1);
+      const line = s.engine.list().find((e) => e.batch?.index === 1 && e.state === "settled")!;
+      g2 = line.outcomes[0]!.attempt_id;
+      receipt = line.outcomes[0]!.receipt_id;
+      expect(g2).toBe(batchAttemptId(line.mandate.id, line.batch!, 0, 2));
+    } finally {
+      s.close();
+    }
+    // B again: its claim says the line failed, so it drafts it anew. The new
+    // execution walks the same derivation from 0: spent, spent (its own g1),
+    // then A's generation 2, which the rail answers from its record.
+    s = open(b, { ledger });
+    try {
+      const rail = railOf(s);
+      const answers: Array<{ attempt_id: string; status: string; replay: unknown }> = [];
+      const pay = rail.pay.bind(rail);
+      rail.pay = async (payment) => {
+        const outcome = await pay(payment);
+        answers.push({ attempt_id: payment.attempt_id, status: outcome.status, replay: outcome.status === "settled" ? outcome.replayed : undefined });
+        return outcome;
+      };
+      const report = await run(s, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["already_settled", "settled", "already_settled"]);
+      expect(answers.map((x) => x.status)).toEqual(["failed", "failed", "settled"]);
+      expect(answers[1]!.attempt_id).toBe(g1);
+      expect(answers[2]).toEqual({ attempt_id: g2, status: "settled", replay: true });
+      expect(railOf(s).payCount).toBe(0);
+      const replayed = s.engine.list().find((e) => e.batch?.index === 1 && e.state === "settled")!.outcomes[0]!;
+      expect(replayed).toMatchObject({ receipt_id: receipt, replayed: true });
+      expect(payloadsOf(s, "rail.outcome").filter((p) => p["attempt_id"] === g2)).toEqual([expect.objectContaining({ status: "settled", idempotent_replay: true })]);
+    } finally {
+      s.close();
+      ledger.close();
+    }
+  });
+
+  it("a line whose id is held for another payment is reported attempt_id_conflict, never moved to another id, and never re-drafted", async () => {
+    const ledger = newLedger();
+    // The books hold the line's generation-0 id for a DIFFERENT payment, so the rail answers attempt_id_conflict.
+    const s = machine("n", { ledger });
+    const batch = findBatch("fornecedores-2026-10")!;
+    const presented = batchHash(s.engine.preview(batch.lines.map((l) => ({ payee: l.alias, amount: l.amount_minor, description: `${batch.label}: ${l.reference}`, due_date: batch.due }))));
+    const g0 = batchAttemptId(s.engine.mandate.id, { batch_hash: presented, index: 1 }, 0);
+    ledger.stubRailPut(g0, { attempt_id: g0, mandate_id: s.engine.mandate.id, amount_minor: 1, currency: "BRL", payee: INSUMOS }, { status: "settled", transaction_id: "tx_other", receipt_id: null, money_moved: false, sandbox: true, raw: {} }, "2026-09-23T17:00:00.000Z");
+    try {
+      const first = await run(s, "fornecedores-2026-10");
+      expect(first.lines.map((l) => l.dispatch)).toEqual(["settled", "attempt_id_conflict", "settled"]);
+      expect(first.failed).toEqual(["insumos"]);
+      // The next run reads the claim and does not draft the line again: the same id would get the same refusal.
+      const second = await run(s, "fornecedores-2026-10");
+      expect(second.lines.map((l) => l.dispatch)).toEqual(["already_settled", "attempt_id_conflict", "already_settled"]);
+      const tries = s.engine.list().filter((e) => e.batch?.index === 1);
+      expect(tries).toHaveLength(1);
+      expect(tries[0]!.outcomes).toEqual([expect.objectContaining({ attempt_id: g0, status: "failed", code: "attempt_id_conflict", held: "conflict" })]);
+      expect(tries[0]!.attempt_generations).toBeUndefined();
+      expect(payloadsOf(s, "rail.attempt_spent")).toEqual([]);
+      expect(payloadsOf(s, "rail.dispatch").filter((p) => p["attempt_id"] === g0)).toHaveLength(1);
+    } finally {
+      s.close();
+      ledger.close();
+    }
+  });
+
+  it("a line still in flight on one machine is not paid by another: it stays open there, for reconciliation", async () => {
+    const ledger = newLedger();
+    const first = machine("h", { ledger, uncertainPayees: [INSUMOS] });
+    try {
+      const report = await run(first, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "uncertain", "settled"]);
+      // An unknown answer is kept for reconciliation under the id that was sent: one presentation per line, no generation.
+      expect(payloadsOf(first, "rail.dispatch")).toHaveLength(3);
+      expect(first.engine.list()[1]!.attempt_generations).toBeUndefined();
+    } finally {
+      first.close();
+    }
+
+    const second = machine("i", { ledger });
+    try {
+      const report = await run(second, "fornecedores-2026-10");
+      expect(report.lines.map((l) => l.dispatch)).toEqual(["settled", "uncertain", "settled"]);
+      expect(railOf(second).payCount).toBe(0);
+      const line = second.engine.list()[1]!;
+      expect(line.state).toBe("executing");
+      expect(payloadsOf(second, "rail.dispatch")).toHaveLength(3);
+      expect(line.attempt_generations).toBeUndefined();
+      expect(payloadsOf(second, "rail.uncertain").map((p) => p["code"])).toEqual(["psp_attempt_in_flight"]);
+      // Reconciling asks the rail about the SAME attempt: in flight once, then the provider's own outcome. Still nothing new paid.
+      await second.engine.reconcile(line.id);
+      const closed = await second.engine.reconcile(line.id);
+      expect(closed.state).toBe("settled");
+      expect(railOf(second).payCount).toBe(0);
+    } finally {
+      second.close();
+      ledger.close();
+    }
+  });
+});

package/templates/supplier-payments-agent/packages/agent-core/README.md

@@ -12,10 +12,23 @@ This package is the decisions. The RUNNER around them — the terminal channel,
 
 `ExecutionEngine.policy()` runs at draft, at a human's approval and again immediately before `executing`, inside the transaction that writes the outbox row. Mandate status, allowlist, per-transaction cap, the window cap (counting settled, in flight AND awaiting executions as reservations), `escalate_above` and the artifact's `items_hash` are all re-checked at the last gate. A person's approval satisfies `escalate_above` and nothing else.
 
+## What the artifact binds besides the items
+
+`items_hash` covers the execution's items: payee, amount, currency and a receivable's due date. Two optional bindings cover what those fields cannot see, and each is **omitted, never null**, when it does not apply, so an artifact without them signs the same bytes it signed before they existed (`test/composition.test.ts` pins that against an artifact hashed on `main` before `composition` was added):
+
+- `batch` — the set a line was approved inside (`batch_hash` over the ordered lines, the line's `index`, the `count`). One execution per line, N lines.
+- `composition` — what ONE amount is made of (`{ ref, composition_hash, line_count }`, with `compositionHash` over the resolved lines). One execution, N lines behind it: a sale is one charge, so a cart of three lines is one item whose amount is the order's total. Two units at 100 and one unit at 200 are the same item and the same `items_hash`; they are not the same `composition_hash`. `compositionHash` uses `itemsHash`'s canonicalisation over `ref`, `quantity`, `unit_amount`, `amount` and `currency`, not `itemsHash` itself, because ten units at a 10% discount and nine at list price have the same line amount.
+
+`checkApprovalArtifact` compares both, and the last gate sends a mismatch back to `awaiting_approval` with `items_hash_mismatch`, like a changed list. `ExecutionEngine.restate()` is how an OPEN execution (`awaiting_approval`, `approved`) follows the proposal behind it — a customer who changes the cart after the order was approved — without a transition: items, total, `items_hash` and composition are replaced, the state, the artifact and the idempotency key are kept, and the last gate does the refusing. The payees of a restatement cannot change.
+
+## What of the artifact reaches the receipt
+
+Every spend carries `approval: { items_hash, batch_hash? }`, the artifact's own hashes (`spendApprovalOf`), and the API seals them into the receipt's chain as a link of their own (chain v4, ent#1670). Both rails refuse a spend without them before any call. `composition` is not sent: the API takes the two hashes and nothing else, and only charges carry a composition today. `receipt-chain.ts` recomputes a chain from the receipt read under the `chain_recipe` the key document publishes (RFC 8785 implemented locally, `node:crypto` only), and `verifyReceiptRead` holds the signature, the body and the sealed approval link against the artifact, in that order. It proves WHAT was approved to anybody holding the read; WHO approved stays in the artifact, under the local key. `docs/OPEN_QUESTIONS.md` §3 and §47.
+
 ## Reconcile never re-dispatches
 
 An execution left in `executing` is looked up on the rail, attempt by attempt. A recorded settled or failed outcome closes it; `in_flight`, `uncertain` or unknown leaves it in `executing` with `reason: rail_uncertain` for a human. The single exception is an outbox row still `pending` (the state changed, no call was ever made): those attempts go out once, under the same ids.
 
 ## Stubs
 
-`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, and a read that does not answer is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.
+`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, `org_paused: true` (the organization kill switch, ent#1648) refuses it whatever `status` says, and a read that does not answer, or answers without `org_paused`, is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.

package/templates/supplier-payments-agent/packages/agent-core/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.128.0",
-    "@codespar/sdk": "0.16.6",
+    "@codespar/sdk": "0.16.10",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   }

package/templates/supplier-payments-agent/packages/agent-core/src/agent.ts

@@ -16,6 +16,42 @@ export interface ToolContext {
   engine: ExecutionEngine;
   /** Fires when a payment tool created an execution; the channel decides what to do with it (ask, or run). */
   onExecution: (execution: Execution) => Promise<Execution>;
+  /**
+   * Fires ONCE for a batch, before its first line is drafted, when the channel
+   * can take one gesture for the whole list. Absent on a channel that decides
+   * line by line (the one-shot, the scenario runner), and then nothing changes:
+   * each line reaches `onExecution` and is decided there. The gesture never
+   * approves anything itself; every line is still drafted, still reaches
+   * `onExecution`, and still mints its own artifact.
+   */
+  onBatch?: (batch: BatchPresentation) => Promise<BatchGesture | undefined>;
+}
+
+/** What a person sees when a whole batch is put in front of them: the list, its total, and the hash of the list. */
+export interface BatchPresentation {
+  ref: string;
+  label: string;
+  /** `batchHash` of the ordered lines. The gesture is a decision about THIS hash and no other. */
+  batch_hash: string;
+  count: number;
+  total_minor: number;
+  /** The total as the kit writes money. */
+  total: string;
+  lines: Array<{
+    index: number;
+    beneficiary: string;
+    amount_minor: number;
+    amount: string;
+    /** A line a previous run already covers is shown, and does not run again whatever the gesture says. */
+    status: "open" | "already_settled" | "in_progress" | "attempt_id_conflict";
+  }>;
+}
+
+/** The decision a person took on a presented batch: which positions they approved and which they vetoed. */
+export interface BatchGesture {
+  batch_hash: string;
+  approved: number[];
+  vetoed: number[];
 }
 
 export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
@@ -28,6 +64,7 @@ export interface AgentLoopOptions {
   bundle: ProofBundle;
   engine: ExecutionEngine;
   onExecution: ToolContext["onExecution"];
+  onBatch?: ToolContext["onBatch"] | undefined;
   /** A hard stop on tool round-trips per turn, so a looping model cannot run forever. */
   maxSteps?: number;
   clock?: () => Date;
@@ -91,7 +128,7 @@ export class AgentLoop {
   }
 
   private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
-    const { bundle, handlers, engine, onExecution } = this.options;
+    const { bundle, handlers, engine, onExecution, onBatch } = this.options;
     bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
 
     if (!this.allowed.has(call.name)) {
@@ -110,6 +147,7 @@ export class AgentLoop {
           executions.push(settledOrNot);
           return settledOrNot;
         },
+        ...(onBatch ? { onBatch } : {}),
       });
       return { refused: false, content };
     } catch (err) {