@codespar/cli 0.17.0 → 0.18.0

package/templates/collections-agent/packages/agent-core/test/attempt-replay.test.ts

@@ -0,0 +1,265 @@
+/**
+ * What a repeated `attempt_id` answers on the deployed API (ent#1671,
+ * codespar-enterprise #1683), and what the kit reads each answer as. The
+ * CodeSpar rail is driven through the real SDK client against a mocked HTTP
+ * server, so the error envelope is parsed the way it is in production; the
+ * stub rail is held to the same table, because a stub that answered a repeat
+ * more kindly than the API would let a suite pass that the API fails.
+ */
+import { mkdtempSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createCodeSparClient } from "../src/api/client.js";
+import { CodeSparRail } from "../src/api/rail.js";
+import { batchAttemptId } from "../src/hash.js";
+import { quoteFromApproval } from "../src/quote.js";
+import type { PaymentRail, RailOutcome, RailPayment } from "../src/rail.js";
+import { StubRail } from "../src/stubs/rail.js";
+import { StateStore } from "../src/state/store.js";
+import { ESCOLA, harness, MERCADO } from "./helpers.js";
+
+const actor = { type: "agent" as const, agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" };
+
+function payment(over: Partial<RailPayment> = {}): RailPayment {
+  return {
+    attempt_id: "ska_replay_0",
+    mandate_id: "mdt_test_0001",
+    amount_minor: 185000,
+    currency: "BRL",
+    payee: ESCOLA,
+    purpose: "contas do mes",
+    agent_id: "bills-agent",
+    quote: { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA },
+    approval: { items_hash: `sha256:${"1".repeat(64)}` },
+    actor,
+    ...over,
+  };
+}
+
+type Answer = { status: number; body: unknown };
+
+let server: Server;
+let baseUrl: string;
+let answer: Answer;
+let posts = 0;
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    if (req.method === "POST") posts += 1;
+    res.writeHead(answer.status, { "content-type": "application/json" });
+    res.end(JSON.stringify(answer.body));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+});
+
+afterAll(async () => {
+  server.closeAllConnections();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+beforeEach(() => {
+  posts = 0;
+});
+
+function rail(): CodeSparRail {
+  // The placeholder passes the `csk_test_` guard and is the one test-key-shaped string the secret scan allows.
+  return new CodeSparRail(createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs: 5_000 }));
+}
+
+function refusal(code: string, details?: Record<string, unknown>): Answer {
+  return { status: 409, body: { error: { code, message: `api: ${code}`, ...(details ? { details } : {}) }, request_id: null } };
+}
+
+/** The ORIGINAL settled body, as the API stores it and answers it again with `idempotent_replay: true`. */
+const settledBody = {
+  payment: { transactionId: "tx_original", moneyMoved: false },
+  receipt: { id: "rcpt_original" },
+};
+
+describe("CodeSparRail reads every answer to a repeated attempt_id (ent#1671)", () => {
+  it("settled: the original body with idempotent_replay is the original outcome, same transaction and same receipt, marked replayed", async () => {
+    answer = { status: 200, body: { ...settledBody, idempotent_replay: true } };
+    for (const outcome of [await rail().pay(payment()), await rail().lookup("ska_replay_0", payment())]) {
+      expect(outcome).toMatchObject({ status: "settled", transaction_id: "tx_original", receipt_id: "rcpt_original", replayed: true });
+    }
+  });
+
+  it("the call that settles it is not a replay", async () => {
+    answer = { status: 200, body: { ...settledBody, idempotent_replay: false } };
+    const outcome = await rail().pay(payment());
+    expect(outcome).toMatchObject({ status: "settled" });
+    expect("replayed" in outcome).toBe(false);
+  });
+
+  it("psp_attempt_in_flight: never a refusal. pay() reads it as unknown, lookup() as still running", async () => {
+    answer = refusal("psp_attempt_in_flight");
+    expect(await rail().pay(payment())).toMatchObject({ status: "uncertain", code: "psp_attempt_in_flight" });
+    expect(await rail().lookup("ska_replay_0", payment())).toEqual({ status: "in_flight" });
+  });
+
+  it("psp_attempt_uncertain: pinned for reconciliation, on both paths", async () => {
+    answer = refusal("psp_attempt_uncertain");
+    expect(await rail().pay(payment())).toMatchObject({ status: "uncertain", code: "psp_attempt_uncertain" });
+    expect(await rail().lookup("ska_replay_0", payment())).toMatchObject({ status: "uncertain", code: "psp_attempt_uncertain" });
+  });
+
+  it("psp_attempt_conflict: failed with no money, and the id is spent", async () => {
+    answer = refusal("psp_attempt_conflict");
+    expect(await rail().pay(payment())).toEqual({ status: "failed", code: "psp_attempt_conflict", message: "api: psp_attempt_conflict", spent: true });
+    expect(await rail().lookup("ska_replay_0", payment())).toMatchObject({ status: "failed", spent: true });
+  });
+
+  it("attempt_id_conflict and attempt_id_unavailable: a refusal that sent nothing, held for another payment or project, and NEVER spent", async () => {
+    for (const [code, details, held] of [
+      ["attempt_id_conflict", { mismatched_fields: ["quote"], attempt_id: "ska_replay_0" }, "conflict"],
+      ["attempt_id_unavailable", { attempt_id: "ska_replay_0" }, "unavailable"],
+    ] as const) {
+      answer = refusal(code, details);
+      for (const outcome of [await rail().pay(payment()), await rail().lookup("ska_replay_0", payment())]) {
+        expect(outcome).toEqual({ status: "failed", code, message: `api: ${code}`, held });
+      }
+    }
+  });
+
+  it("every answer above is one POST: a lookup is the same presentation, never a second call of its own", async () => {
+    answer = refusal("psp_attempt_in_flight");
+    await rail().lookup("ska_replay_0", payment());
+    expect(posts).toBe(1);
+  });
+});
+
+describe("the stub rail answers a repeat the way the API does", () => {
+  function stub(options: ConstructorParameters<typeof StubRail>[1] = {}): StubRail {
+    return new StubRail(new StateStore(join(mkdtempSync(join(tmpdir(), "agent-core-replay-")), "state.db")), options);
+  }
+
+  it("settled: the original outcome, marked replayed, and nothing paid again", async () => {
+    const r = stub();
+    const first = await r.pay(payment());
+    const again = await r.pay(payment());
+    expect(r.payCount).toBe(1);
+    expect(again).toMatchObject({ status: "settled", replayed: true, transaction_id: (first as { transaction_id: string }).transaction_id, receipt_id: (first as { receipt_id: string }).receipt_id });
+    expect("replayed" in first).toBe(false);
+    expect((again as { raw: Record<string, unknown> }).raw["idempotent_replay"]).toBe(true);
+  });
+
+  it("a different payment under the same id is attempt_id_conflict, whatever became of the first, and names what differs", async () => {
+    const r = stub();
+    await r.pay(payment());
+    const changed = await r.pay(payment({ quote: { ...payment().quote!, at: "2026-09-23T18:00:00.000Z" } }));
+    expect(changed).toMatchObject({ status: "failed", code: "attempt_id_conflict", held: "conflict" });
+    expect((changed as { message: string }).message).toContain("quote");
+    expect((changed as { spent?: true }).spent).toBeUndefined();
+    const otherPayee = await r.pay(payment({ payee: MERCADO, quote: { ...payment().quote!, payee: MERCADO } }));
+    expect((otherPayee as { message: string }).message).toContain("payee");
+    expect(r.payCount).toBe(1);
+  });
+
+  it("failed: psp_attempt_conflict, spent", async () => {
+    const r = stub({ refusePayees: [ESCOLA] });
+    expect(await r.pay(payment())).toMatchObject({ status: "failed", code: "psp_dispatch_failed" });
+    expect(await r.pay(payment())).toMatchObject({ status: "failed", code: "psp_attempt_conflict", spent: true });
+    expect(r.payCount).toBe(1);
+  });
+
+  it("in flight: psp_attempt_in_flight on another presentation, on the shared books another machine reads too", async () => {
+    const ledger = new StateStore(join(mkdtempSync(join(tmpdir(), "agent-core-ledger-")), "rail.db"));
+    const a = stub({ ledger, uncertainPayees: [ESCOLA] });
+    expect(await a.pay(payment())).toMatchObject({ status: "uncertain", code: "psp_dispatch_uncertain" });
+    const b = stub({ ledger });
+    expect(await b.pay(payment())).toMatchObject({ status: "uncertain", code: "psp_attempt_in_flight" });
+    expect(b.payCount).toBe(0);
+    expect(await b.lookup("ska_replay_0", payment())).toEqual({ status: "in_flight" });
+    expect(await b.lookup("ska_replay_0", payment())).toMatchObject({ status: "settled" });
+    expect(b.payCount).toBe(0);
+  });
+});
+
+describe("a batch line's quote is the same on every run of the list", () => {
+  it("stable leaves the approval time out; anything else keeps it", () => {
+    const artifact = { approved_at: "2026-09-23T18:00:00.000Z", items: [{ beneficiary: "Escola Aurora", description: "outubro", amount: 185000, payee: ESCOLA }] } as never;
+    expect(quoteFromApproval(artifact, 0, "contas do mes")).toEqual({ seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, at: "2026-09-23T18:00:00.000Z" });
+    expect(quoteFromApproval(artifact, 0, "contas do mes", { stable: true })).toEqual({ seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA });
+  });
+});
+
+/**
+ * When a batch line moves to the next generation of its id: on
+ * `psp_attempt_conflict` — the server stating the attempt failed with no
+ * money — and on NOTHING else. Advancing on an unknown outcome is how one line
+ * gets paid under two ids; advancing on `attempt_id_conflict` or
+ * `attempt_id_unavailable` is minting a new payment for an id somebody else's
+ * record holds.
+ */
+describe("a batch line's attempt id advances on a spent id, and on nothing else", () => {
+  const BATCH = { ref: "folha-teste", batch_hash: `sha256:${"a".repeat(64)}`, index: 0, count: 1 };
+  const approver = { id: "usr_demo", channel: "terminal" };
+
+  /** A rail that answers `script(n)` for its n-th call, and records every attempt id it was shown. */
+  function scripted(script: (call: number) => RailOutcome) {
+    const seen: string[] = [];
+    const wrap = (): PaymentRail => ({
+      name: "stub",
+      pay: async (p) => (seen.push(p.attempt_id), script(seen.length - 1)),
+      lookup: async () => undefined,
+      receipt: async () => undefined,
+    });
+    return { seen, wrap };
+  }
+
+  async function runLine(rail: ReturnType<typeof scripted>) {
+    const h = harness({ wrapRail: rail.wrap });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }], batch: BATCH });
+    if (!d.ok) throw new Error(`refused before draft: ${d.reason}`);
+    h.engine.approve(d.execution.id, approver);
+    return h.engine.execute(d.execution.id);
+  }
+
+  const held: Array<[string, RailOutcome]> = [
+    ["attempt_id_conflict", { status: "failed", code: "attempt_id_conflict", message: "used for a different payment", held: "conflict" }],
+    ["attempt_id_unavailable", { status: "failed", code: "attempt_id_unavailable", message: "not available", held: "unavailable" }],
+    ["an unknown refusal", { status: "failed", code: "some_code_nobody_documented", message: "?" }],
+    ["psp_attempt_in_flight", { status: "uncertain", code: "psp_attempt_in_flight", message: "claimed" }],
+    ["psp_attempt_uncertain", { status: "uncertain", code: "psp_attempt_uncertain", message: "pinned" }],
+    ["psp_dispatch_uncertain", { status: "uncertain", code: "psp_dispatch_uncertain", message: "timeout" }],
+  ];
+  for (const [name, answer] of held) {
+    it(`${name}: one presentation, the generation-0 id, no generation recorded`, async () => {
+      const rail = scripted(() => answer);
+      const out = await runLine(rail);
+      const g0 = batchAttemptId(out.mandate.id, BATCH, 0);
+      expect(rail.seen).toEqual([g0]);
+      expect(out.attempt_generations).toBeUndefined();
+      expect(out.state).toBe(answer.status === "failed" ? "failed" : "executing");
+    });
+  }
+
+  it("psp_attempt_conflict: the next generation, derived the same way on any machine, and saved on the execution", async () => {
+    const settled: RailOutcome = { status: "settled", transaction_id: "tx_g2", receipt_id: null, money_moved: false, sandbox: true, raw: {} };
+    const spent: RailOutcome = { status: "failed", code: "psp_attempt_conflict", message: "failed, no money", spent: true };
+    const rail = scripted((call) => (call < 2 ? spent : settled));
+    const out = await runLine(rail);
+    expect(rail.seen).toEqual([0, 1, 2].map((g) => batchAttemptId(out.mandate.id, BATCH, 0, g)));
+    expect(out.state).toBe("settled");
+    expect(out.outcomes[0]!.attempt_id).toBe(rail.seen[2]);
+    expect(out.attempt_generations).toEqual({ 0: 2 });
+  });
+
+  it("a psp_attempt_conflict the rail did not mark spent does not advance either", async () => {
+    const rail = scripted(() => ({ status: "failed", code: "psp_attempt_conflict", message: "no spent flag" }));
+    const out = await runLine(rail);
+    expect(rail.seen).toHaveLength(1);
+    expect(out.attempt_generations).toBeUndefined();
+  });
+
+  it("stops after eight spent generations, failed, never looping", async () => {
+    const rail = scripted(() => ({ status: "failed", code: "psp_attempt_conflict", message: "failed, no money", spent: true }));
+    const out = await runLine(rail);
+    expect(rail.seen).toHaveLength(9);
+    expect(out.state).toBe("failed");
+    expect(out.attempt_generations).toEqual({ 0: 8 });
+  });
+});

package/templates/collections-agent/packages/agent-core/test/composition.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Deterministic ids, so an artifact is the same bytes on every run and its hash can be pinned.
+vi.mock("../src/ids.js", async (original) => {
+  const real = await original<typeof import("../src/ids.js")>();
+  let n = 0;
+  return { ...real, newId: (prefix: string) => `${prefix}_${String((n += 1)).padStart(16, "0")}` };
+});
+
+import { checkApprovalArtifact, createApprovalArtifact, hmacSigner } from "../src/approval.js";
+import { canonicalJson, compositionHash, itemsHash, sha256Hex } from "../src/hash.js";
+import type { Execution } from "../src/state-machine.js";
+import { ToolsFileSchema } from "../src/tools.js";
+import type { CompositionLine, ExecutionComposition, ExecutionItem } from "../src/types.js";
+import { harness } from "./helpers.js";
+
+const signer = hmacSigner("local-dev-stub", Buffer.alloc(32, 1));
+const now = new Date("2026-09-23T18:00:00.000Z");
+const person = { type: "person" as const, id: "usr_terminal", channel: "terminal" };
+const human = { type: "human" as const, id: "usr_terminal", channel: "terminal" };
+const approver = { id: "usr_terminal", channel: "terminal" };
+
+function execution(items: ExecutionItem[], over: Partial<Execution> = {}): Execution {
+  return {
+    id: "exe_1",
+    run_id: "run_1",
+    state: "awaiting_approval",
+    mode: "human",
+    actor: { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" },
+    items,
+    total: items.reduce((s, i) => s + i.amount, 0),
+    currency: "BRL",
+    items_hash: itemsHash(items),
+    mandate: { id: "mdt_test_0001", version: 1 },
+    idempotency_key: "idk_1",
+    blocking_reasons: [],
+    outcomes: [],
+    history: [],
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    ...over,
+  } as Execution;
+}
+
+const escola: ExecutionItem = { alias: "escola", beneficiary: "Escola Aurora", payee: "escola@exemplo.com.br", amount: 185000, currency: "BRL", description: "outubro" };
+
+const line = (ref: string, quantity: number, unit_amount: number, amount = quantity * unit_amount): CompositionLine => ({ ref, quantity, unit_amount, amount, currency: "BRL" });
+const twoLessons = [line("aula-avulsa", 2, 10000)];
+const oneConsulting = [line("consultoria-1h", 1, 20000)];
+const composition = (ref: string, lines: CompositionLine[]): ExecutionComposition => ({ ref, composition_hash: compositionHash(lines), line_count: lines.length });
+
+describe("dependency 9.7: an artifact without a composition is the artifact it was before, byte for byte", () => {
+  it("hashes to what the same artifact hashed to on main before `composition` existed", () => {
+    // The bills-agent's shape: one payee, no batch, no composition. The two
+    // constants were computed on origin/main at 768c1a2, before this change,
+    // with the same ids, key, clock and execution. If `composition` were
+    // written as null — or any key added — both would move.
+    const artifact = createApprovalArtifact(signer, { execution: execution([escola]), approver: person, actor: human, now });
+    expect("composition" in artifact).toBe(false);
+    expect(sha256Hex(canonicalJson(artifact))).toBe("3c7da9ead8078c58e6727dc6645ff1cde3f7e69d78502ea17350887ba201f030");
+    expect(artifact.signature.value).toBe("5fd40687454f7a67a84cb6bb375eb91b7d9ba3d20242d1fe95c7845c9dc31a0a");
+  });
+});
+
+describe("dependency 9.7: the composition is carried, signed and compared", () => {
+  it("an artifact carries the composition of the execution it approves, and the signature covers it", () => {
+    const order: ExecutionItem = { beneficiary: "Marina Costa", payee: "11144477735", amount: 20000, currency: "BRL", due_date: "2026-09-23" };
+    const exe = execution([order], { composition: composition("cart-1", twoLessons) });
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: person, actor: human, now });
+    expect(artifact.composition).toEqual(exe.composition);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+    for (const changed of [composition("cart-1", oneConsulting), { ...exe.composition!, ref: "cart-2" }, { ...exe.composition!, line_count: 2 }]) {
+      expect(checkApprovalArtifact(signer, { ...artifact, composition: changed }, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+      expect(checkApprovalArtifact(signer, artifact, { ...exe, composition: changed }, now)).toEqual({ ok: false, problem: "composition_mismatch" });
+    }
+  });
+
+  it("the case items_hash cannot see: the same total, another cart", () => {
+    const order: ExecutionItem = { beneficiary: "Marina Costa", payee: "11144477735", amount: 20000, currency: "BRL", due_date: "2026-09-23" };
+    const approved = execution([order], { composition: composition("cart-1", twoLessons) });
+    const artifact = createApprovalArtifact(signer, { execution: approved, approver: person, actor: human, now });
+    const recomposed = { ...approved, composition: composition("cart-1", oneConsulting) };
+    expect(recomposed.items_hash).toBe(artifact.items_hash);
+    expect(checkApprovalArtifact(signer, artifact, recomposed, now)).toEqual({ ok: false, problem: "composition_mismatch" });
+  });
+
+  it("gaining or losing a composition after approval is a different execution", () => {
+    const order: ExecutionItem = { beneficiary: "Marina Costa", payee: "11144477735", amount: 20000, currency: "BRL" };
+    const bare = execution([order]);
+    const bareArtifact = createApprovalArtifact(signer, { execution: bare, approver: person, actor: human, now });
+    expect(checkApprovalArtifact(signer, bareArtifact, { ...bare, composition: composition("cart-1", twoLessons) }, now)).toEqual({ ok: false, problem: "composition_mismatch" });
+    const composed = execution([order], { composition: composition("cart-1", twoLessons) });
+    const composedArtifact = createApprovalArtifact(signer, { execution: composed, approver: person, actor: human, now });
+    const { composition: _dropped, ...stripped } = composed;
+    expect(checkApprovalArtifact(signer, composedArtifact, stripped as Execution, now)).toEqual({ ok: false, problem: "composition_mismatch" });
+  });
+
+  it("the hash sees quantity, unit price and order, which items_hash's fields cannot", () => {
+    // Ten at a 10% discount and nine at list price: the same line amount, not the same sale.
+    expect(compositionHash([line("aula-avulsa", 10, 10000, 90000)])).not.toBe(compositionHash([line("aula-avulsa", 9, 10000, 90000)]));
+    expect(compositionHash([line("aula-avulsa", 10, 9000, 90000)])).not.toBe(compositionHash([line("aula-avulsa", 10, 10000, 90000)]));
+    const a = line("aula-avulsa", 1, 10000);
+    const b = line("avaliacao-inicial", 1, 8990);
+    expect(compositionHash([a, b])).not.toBe(compositionHash([b, a]));
+    expect(compositionHash([a, b])).toMatch(/^sha256:[0-9a-f]{64}$/);
+    // A discount line is a line: a coupon swapped at a constant total is another composition.
+    expect(compositionHash([a, line("coupon:BEMVINDO10", 1, -1000)])).not.toBe(compositionHash([a, line("discount:order", 1, -1000)]));
+  });
+});
+
+describe("dependency 9.7 in the engine: a cart recomposed after approval goes back to a person", () => {
+  const draftOrder = async (h: ReturnType<typeof harness>, lines: CompositionLine[]) => {
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 20000 }], composition: composition("cart-1", lines) });
+    if (!d.ok) throw new Error("refused");
+    return d.execution;
+  };
+
+  it("draft stamps the composition on the execution and on every artifact of it", async () => {
+    const h = harness({ mode: "human" });
+    const drafted = await draftOrder(h, twoLessons);
+    expect(drafted.composition).toEqual(composition("cart-1", twoLessons));
+    const approved = h.engine.approve(drafted.id, approver);
+    expect(h.store.getApproval(approved.approval_id!)!.composition).toEqual(composition("cart-1", twoLessons));
+  });
+
+  it("restated at a constant total: items_hash unchanged, the last gate refuses, a second yes mints a second artifact", async () => {
+    const h = harness({ mode: "human" });
+    const approved = h.engine.approve((await draftOrder(h, twoLessons)).id, approver);
+    const first = approved.approval_id!;
+    const restated = h.engine.restate(approved.id, { items: [{ payee: "escola", amount: 20000 }], composition: composition("cart-1", oneConsulting) });
+    expect(restated.state).toBe("approved");
+    expect(restated.items_hash).toBe(approved.items_hash);
+    expect(restated.approval_id).toBe(first);
+
+    const back = await h.engine.execute(approved.id);
+    expect(back.state).toBe("awaiting_approval");
+    expect(back.reason).toBe("items_hash_mismatch");
+    expect(back.detail).toContain("composition_mismatch");
+    expect(back.approval_id).toBeUndefined();
+    expect(h.store.listOutbox()).toHaveLength(0);
+
+    const again = h.engine.approve(back.id, approver);
+    expect(again.approval_id).not.toBe(first);
+    expect(h.store.getApproval(again.approval_id!)!.composition).toEqual(composition("cart-1", oneConsulting));
+    const ran = await h.engine.execute(again.id);
+    expect(ran.state).toBe("settled");
+    expect(ran.history.map((t) => t.to)).toEqual(["awaiting_approval", "approved", "awaiting_approval", "approved", "executing", "settled"]);
+  });
+
+  it("restated with a new total: the new total is the one judged and run", async () => {
+    const h = harness({ mode: "human" });
+    const approved = h.engine.approve((await draftOrder(h, twoLessons)).id, approver);
+    const fiveLessons = [line("aula-avulsa", 5, 10000)];
+    h.engine.restate(approved.id, { items: [{ payee: "escola", amount: 50000 }], composition: composition("cart-1", fiveLessons) });
+    const back = await h.engine.execute(approved.id);
+    expect(back.state).toBe("awaiting_approval");
+    expect(back.total).toBe(50000);
+    const ran = await h.engine.execute(h.engine.approve(back.id, approver).id);
+    expect(ran.state).toBe("settled");
+    expect(h.engine.list({ state: "settled" }).map((e) => e.total)).toEqual([50000]);
+  });
+
+  it("restate changes what is charged, never to whom, and never an execution that is no longer open", async () => {
+    const h = harness({ mode: "human" });
+    const drafted = await draftOrder(h, twoLessons);
+    expect(() => h.engine.restate(drafted.id, { items: [{ payee: "mercado", amount: 20000 }] })).toThrow(/payees/);
+    expect(() => h.engine.restate(drafted.id, { items: [{ payee: "escola", amount: 10000 }, { payee: "escola", amount: 10000 }] })).toThrow(/payees/);
+    expect(() => h.engine.restate(drafted.id, { items: [{ payee: "escola", amount: 20000 }], batch: { ref: "b", batch_hash: "sha256:x", index: 0, count: 1 } })).toThrow(/batch/);
+    const denied = h.engine.deny(drafted.id, approver);
+    expect(() => h.engine.restate(denied.id, { items: [{ payee: "escola", amount: 20000 }] })).toThrow(/only an open execution/);
+  });
+
+  it("a composition that cannot be a hash of lines is refused where the execution is minted", async () => {
+    const h = harness({ mode: "human" });
+    await expect(h.engine.draft({ items: [{ payee: "escola", amount: 20000 }], composition: { ref: "cart-1", composition_hash: "sha256:nope", line_count: 1 } })).rejects.toThrow(/composition_hash/);
+    await expect(h.engine.draft({ items: [{ payee: "escola", amount: 20000 }], composition: { ...composition("cart-1", twoLessons), line_count: 0 } })).rejects.toThrow(/line_count/);
+    await expect(h.engine.draft({ items: [{ payee: "escola", amount: 20000 }], composition: { ...composition("cart-1", twoLessons), ref: " " } })).rejects.toThrow(/ref/);
+  });
+
+  it("an execution without a composition carries no composition key, in state or in the bundle", async () => {
+    const h = harness({ mode: "human" });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    expect("composition" in approved).toBe(false);
+    expect("composition" in h.store.getApproval(approved.approval_id!)!).toBe(false);
+    for (const e of h.store.listEvents()) expect(JSON.stringify(e.payload)).not.toContain("composition");
+  });
+});
+
+describe("dependency 9.8: `state` is an effect, and only a local tool has it", () => {
+  const tool = (effect: string) => ({ name: "cart_update", effect, description: "replaces the cart", input_schema: { type: "object" } });
+  it("a local tool may change state", () => {
+    expect(ToolsFileSchema.safeParse({ meta_tools: [], local_tools: [tool("state")] }).success).toBe(true);
+  });
+  it("a meta-tool may not: CodeSpar's names are for money and reads", () => {
+    const parsed = ToolsFileSchema.safeParse({ meta_tools: [{ ...tool("state"), name: "codespar_cart" }], local_tools: [] });
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.message).toContain("a state tool is local");
+  });
+  it("an effect outside the enum is still refused", () => {
+    expect(ToolsFileSchema.safeParse({ meta_tools: [], local_tools: [tool("write")] }).success).toBe(false);
+  });
+});

package/templates/collections-agent/packages/agent-core/test/fixtures/production-receipt-keys.json

@@ -0,0 +1 @@
+{"issuer":"did:web:id.codespar.dev","key_namespace":"production","algorithm":"Ed25519","signing_string":"codespar-receipt:v1:<receipt_id>:<chain>","chain_recipe":{"canonicalization":"RFC 8785 (JCS)","digest":"SHA-256 over the UTF-8 bytes of the canonical JSON, lowercase hex","input":"{ \"v\": <chain_version>, \"links\": [ <each link below that applies, in this order> ] }","version":{"field":"chain_version","rule":"4 when `approval` is present; else 3 when `payment.amount_authorized` is present; else 2 when `payment.amount_atomic` is not null; else 1"},"optional_marker":"?","links":[{"link":"mandate","from":"mandate","when":"always","fields_by_version":{"1":["id","nonce","scope","currency","sig"],"2":["id","nonce","scope","currency","sig"],"3":["id","nonce","scope","currency","sig"],"4":["id","nonce","scope","currency","sig_sha256"]}},{"link":"quote","from":"quote","when":"quote is not null","fields":["seller","resource","price_minor","payee","session_id","sig","at"]},{"link":"approval","from":"approval","when":"chain_version is 4","fields":["items_hash","batch_hash"]},{"link":"payment","from":"payment","when":"always","fields":["rail","provider","tx_id","amount_minor","amount_atomic?","amount_authorized?","amount_charged?","amount_refunded?","metering?","sandbox?","attempt_id","money_moved","at"]},{"link":"delivery","from":"delivery","when":"delivery is not null","fields":["result","proof","kind","nfe_chave","at"]}],"notes":["`mandate.sig_sha256` is SHA-256 over the UTF-8 bytes of `mandate.sig`, lowercase hex. A v4 chain seals it in place of `sig`, which must not be shared; v1-v3 seal `sig` itself, so only the tenant, whose read carries `sig`, can recompute those. Anyone can still verify their signature over `chain`.","Recomputing needs `quote.payee` unmasked. Whoever shares a receipt decides whether to hand it over.","Timestamps are RFC 3339 UTC with milliseconds, exactly as read."]},"keys":[{"kid":"did:web:id.codespar.dev#1","kty":"OKP","crv":"Ed25519","x":"fz1svKf1AFlnIEZSseNqH5zCXkKqPmtkjx9mMNBz8pU","alg":"EdDSA","use":"sig","status":"retired","created_at":"2026-07-05T13:29:23.276Z","retired_at":"2026-09-25T02:43:45.971Z"},{"kid":"did:web:id.codespar.dev#production-2","kty":"OKP","crv":"Ed25519","x":"WKVTphnIma44d5T7bugYnLvI6h79LhaSdNDrkOFxmRs","alg":"EdDSA","use":"sig","status":"active","created_at":"2026-09-25T02:43:45.971Z","retired_at":null}]}

package/templates/collections-agent/packages/agent-core/test/helpers.ts

@@ -9,6 +9,7 @@ import { MandateSchema, type Mandate } from "../src/mandate.js";
 import { ManifestSchema, type Manifest } from "../src/manifest.js";
 import { StateStore } from "../src/state/store.js";
 import { LocalMandateStatusStub } from "../src/stubs/mandate-status.js";
+import type { PaymentRail } from "../src/rail.js";
 import type { MandateStatusSource } from "../src/revocation.js";
 import { StubRail, type StubRailOptions } from "../src/stubs/rail.js";
 import type { ApprovalMode } from "../src/types.js";
@@ -91,6 +92,8 @@ export interface HarnessOptions {
   mandate?: Partial<Mandate>;
   manifest?: Partial<Manifest>;
   rail?: StubRailOptions;
+  /** What the engine dispatches to instead of the stub itself, e.g. the stub with a different receipt. `rail` on the harness stays the stub. */
+  wrapRail?: (stub: StubRail) => PaymentRail;
   dir?: string;
   runId?: string;
   /** The section 4.7 status source; the local stub unless a test wires the API one. */
@@ -109,7 +112,7 @@ export function harness(options: HarnessOptions = {}): Harness {
   const mode = options.mode ?? "human";
   const deps: EngineDeps = {
     store,
-    rail,
+    rail: options.wrapRail ? options.wrapRail(rail) : rail,
     status: options.status ?? gate,
     signer: hmacSigner("test", Buffer.alloc(32, 1)),
     manifest: testManifest(options.manifest),