@codespar/cli 0.17.0 → 0.18.1

package/templates/checkout-agent/packages/agent-core/test/approval-seal.test.ts

@@ -0,0 +1,233 @@
+/**
+ * OPEN_QUESTIONS §3: every spend carries the approval artifact's hashes, and
+ * the API seals them into the receipt's chain (v4, ent#1670). What is sent is
+ * the artifact's own `items_hash`, and for a batch line its `batch_hash` —
+ * the values the artifact's HMAC covers — and nothing the execution says
+ * later. A spend without them, or with a shape the API would refuse, never
+ * goes out; the bundle's receipt copy names the artifact by id so `verify`
+ * finds it by identity.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ApiClient } from "@codespar/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { CodeSparRail } from "../src/api/rail.js";
+import { copyDisagreesWithRead, maskPayee } from "../src/bundle.js";
+import { ReceiptSealMismatchError } from "../src/engine.js";
+import { checkSpendApproval, spendApprovalOf, type PaymentRail, type RailPayment, type SealedSpendApproval } from "../src/rail.js";
+import { ESCOLA, harness, MERCADO } from "./helpers.js";
+
+const approver = { id: "usr_demo", channel: "terminal" };
+const actor = { type: "agent" as const, agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" };
+const ITEMS_HASH = `sha256:${"1".repeat(64)}`;
+
+function payment(over: Partial<RailPayment> = {}): RailPayment {
+  return {
+    attempt_id: "att_seal_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, at: "2026-09-23T18:00:00.000Z" },
+    approval: { items_hash: ITEMS_HASH },
+    actor,
+    ...over,
+  };
+}
+
+function fakeApi(receiptBody?: unknown) {
+  const post = vi.fn(async (_path: string, _init: { body: Record<string, unknown> }) => ({ payment: { transactionId: "tx_1", moneyMoved: false }, receipt: { id: "rcpt_1" } }));
+  return { api: { post, get: vi.fn(async () => receiptBody) } as unknown as ApiClient, post };
+}
+
+/** The stub rail, but the receipt it hands back seals whatever approval the test says. */
+function sealingApproval(sealed: SealedSpendApproval | null) {
+  return (inner: PaymentRail): PaymentRail => ({
+    name: inner.name,
+    pay: (p) => inner.pay(p),
+    lookup: (id, p, tx) => inner.lookup(id, p, tx),
+    receipt: async (id, a) => {
+      const r = await inner.receipt(id, a);
+      return r && { ...r, approval: sealed };
+    },
+  });
+}
+
+function recording() {
+  const h = harness({ mode: "human" });
+  const seen: RailPayment[] = [];
+  const pay = h.rail.pay.bind(h.rail);
+  h.rail.pay = async (p) => (seen.push(p), pay(p));
+  return { h, seen };
+}
+
+describe("every spend presents the artifact's hashes", () => {
+  it("a single execution: the artifact's items_hash on every line, no batch_hash, and the quote keeps the moment of approval", async () => {
+    const { h, seen } = recording();
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }, { payee: "mercado", amount: 32000 }] });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    const artifact = h.store.getApproval(approved.approval_id!)!;
+    expect((await h.engine.execute(approved.id)).state).toBe("settled");
+    expect(seen.map((p) => p.approval)).toEqual([{ items_hash: artifact.items_hash }, { items_hash: artifact.items_hash }]);
+    expect(seen.map((p) => p.quote?.at)).toEqual([artifact.approved_at, artifact.approved_at]);
+    // The form the API seals a timestamp in (RFC 3339, UTC, milliseconds), so the read gives back what was sent (ent#1670).
+    expect(artifact.approved_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    // What the "provider" holds for the attempt is what was sent.
+    expect((h.store.stubRailGet(seen[0]!.attempt_id)!.request as RailPayment).approval).toEqual({ items_hash: artifact.items_hash });
+  });
+
+  it("a batch line: the line's items_hash and the batch's batch_hash, and a quote with no time in it", async () => {
+    const { h, seen } = recording();
+    const batch = { ref: "folha-teste", batch_hash: `sha256:${"a".repeat(64)}`, index: 0, count: 2 };
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }], batch });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    const artifact = h.store.getApproval(approved.approval_id!)!;
+    await h.engine.execute(approved.id);
+    expect(seen[0]!.approval).toEqual({ items_hash: artifact.items_hash, batch_hash: batch.batch_hash });
+    expect(seen[0]!.quote).not.toHaveProperty("at");
+  });
+
+  it("spendApprovalOf carries exactly the artifact's two hashes", () => {
+    expect(spendApprovalOf({ items_hash: ITEMS_HASH })).toEqual({ items_hash: ITEMS_HASH });
+    expect(spendApprovalOf({ items_hash: ITEMS_HASH, batch: { ref: "r", batch_hash: `sha256:${"b".repeat(64)}`, index: 1, count: 3 } })).toEqual({ items_hash: ITEMS_HASH, batch_hash: `sha256:${"b".repeat(64)}` });
+  });
+});
+
+describe("the CodeSpar rail", () => {
+  it("sends approval on both spend routes, as the artifact spells it", async () => {
+    const withBatch = { items_hash: ITEMS_HASH, batch_hash: `sha256:${"b".repeat(64)}` };
+    const byEnvelope = fakeApi();
+    await new CodeSparRail(byEnvelope.api, { canonical: { any: "envelope" } as never, signature: "a".repeat(64) }).pay(payment({ approval: withBatch }));
+    expect(byEnvelope.post.mock.calls[0]![0]).toBe("/v1/consumer-payments/execute");
+    expect(byEnvelope.post.mock.calls[0]![1].body["approval"]).toEqual(withBatch);
+    const byId = fakeApi();
+    await new CodeSparRail(byId.api).pay(payment());
+    expect(byId.post.mock.calls[0]![0]).toBe("/v1/consumers/mandates/{id}/spend");
+    expect(byId.post.mock.calls[0]![1].body["approval"]).toEqual({ items_hash: ITEMS_HASH });
+  });
+
+  it("refuses a spend without it, or with a hash the API would refuse, without calling the API", async () => {
+    const { api, post } = fakeApi();
+    const rail = new CodeSparRail(api);
+    const { approval: _a, ...bare } = payment();
+    expect(await rail.pay(bare)).toMatchObject({ status: "failed", code: "approval_missing" });
+    expect(await rail.pay(payment({ approval: { items_hash: "sha256:ABC" } }))).toMatchObject({ status: "failed", code: "approval_malformed" });
+    expect(await rail.pay(payment({ approval: { items_hash: ITEMS_HASH, batch_hash: "f".repeat(63) } }))).toMatchObject({ status: "failed", code: "approval_malformed" });
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("checkSpendApproval accepts the two spellings the API accepts", () => {
+    expect(checkSpendApproval({ approval: { items_hash: ITEMS_HASH } }).ok).toBe(true);
+    expect(checkSpendApproval({ approval: { items_hash: "1".repeat(64) } }).ok).toBe(true);
+    expect(checkSpendApproval({ approval: { items_hash: `sha256:${"1".repeat(64)}`.toUpperCase() } }).ok).toBe(false);
+  });
+});
+
+describe("the receipt seals the approval the spend sent, or the run stops", () => {
+  it("the CodeSpar rail reads chain_version, the sealed approval and sig_sha256 through the SDK's types", async () => {
+    const read = {
+      receipt_id: "rcpt_1",
+      state: "paid",
+      chain_version: 4,
+      mandate: { id: "cm_1", nonce: "n", scope: "s", currency: "BRL", sig: "x", sig_sha256: "d".repeat(64) },
+      quote: { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, session_id: null, sig: "q", at: "2026-09-23T18:00:00.000Z" },
+      approval: { items_hash: ITEMS_HASH, batch_hash: null },
+      payment: { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_seal_0", money_moved: false, at: "2026-09-23T18:00:01.000Z" },
+      delivery: null,
+      chain: "c".repeat(64),
+      receipt_sig: "s",
+      exceptions: [],
+    };
+    const receipt = await new CodeSparRail(fakeApi(read).api).receipt("rcpt_1", actor);
+    expect(receipt).toMatchObject({ chain_version: 4, approval: { items_hash: ITEMS_HASH, batch_hash: null }, mandate: { id: "cm_1", sig_sha256: "d".repeat(64) } });
+    expect(JSON.stringify({ ...receipt, raw: undefined })).not.toContain('"sig":"x"');
+    const { approval: _a, ...older } = read;
+    expect((await new CodeSparRail(fakeApi({ ...older, chain_version: 1 }).api).receipt("rcpt_1", actor))?.approval).toBeNull();
+  });
+
+  for (const [name, sealed] of [
+    ["another list", { items_hash: `sha256:${"9".repeat(64)}`, batch_hash: null }],
+    ["no approval at all", null],
+  ] as const) {
+    it(`a receipt that seals ${name} is ReceiptSealMismatchError, after the outcome is saved`, async () => {
+      const h = harness({ mode: "human", wrapRail: sealingApproval(sealed) });
+      const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+      if (!d.ok) throw new Error("refused");
+      const approved = h.engine.approve(d.execution.id, approver);
+      const artifact = h.store.getApproval(approved.approval_id!)!;
+      await expect(h.engine.execute(approved.id)).rejects.toBeInstanceOf(ReceiptSealMismatchError);
+      expect(h.engine.get(approved.id)?.state).toBe("settled");
+      const mismatch = h.bundle.readEvents().find((e) => e["type"] === "receipt.seal_mismatch");
+      expect(mismatch?.["payload"]).toMatchObject({ sealed_approval: sealed, sent_approval: { items_hash: artifact.items_hash } });
+    });
+  }
+
+  it("the same hash in the other spelling of the prefix is the same approval", async () => {
+    const h = harness({ mode: "human" });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    const bare = h.store.getApproval(approved.approval_id!)!.items_hash.replace(/^sha256:/, "");
+    const spelled = harness({ mode: "human", dir: h.dir, wrapRail: sealingApproval({ items_hash: bare, batch_hash: null }) });
+    expect((await spelled.engine.execute(approved.id)).state).toBe("settled");
+    expect(spelled.bundle.readEvents().some((e) => e["type"] === "receipt.seal_mismatch")).toBe(false);
+  });
+});
+
+describe("the stub rail", () => {
+  it("makes the same refusal, so a scenario cannot pass without the hashes", async () => {
+    const h = harness();
+    const { approval: _a, ...bare } = payment();
+    expect(await h.rail.pay(bare)).toMatchObject({ status: "failed", code: "approval_missing" });
+    expect(h.rail.payCount).toBe(0);
+  });
+
+  it("answers a repeat under a different approval as attempt_id_conflict naming it, the way the API's fingerprint does (ent#1670)", async () => {
+    const h = harness();
+    expect(await h.rail.pay(payment())).toMatchObject({ status: "settled" });
+    const other = await h.rail.pay(payment({ approval: { items_hash: `sha256:${"9".repeat(64)}` } }));
+    expect(other).toMatchObject({ status: "failed", code: "attempt_id_conflict", held: "conflict" });
+    expect((other as { message: string }).message).toContain("approval");
+    expect(h.rail.payCount).toBe(1);
+  });
+});
+
+describe("the bundle's receipt copy", () => {
+  it("names the artifact the spend carried, by id, and stays masked", async () => {
+    const h = harness({ mode: "human" });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    const settled = await h.engine.execute(approved.id);
+    const copy = JSON.parse(readFileSync(join(h.bundle.dir, "receipts", `${settled.outcomes[0]!.receipt_id}.json`), "utf8")) as Record<string, unknown>;
+    expect(copy["approval_id"]).toBe(approved.approval_id);
+    expect(h.bundle.readApprovals().map((a) => a.approval_id)).toContain(copy["approval_id"]);
+    expect(JSON.stringify(copy)).not.toContain(ESCOLA);
+  });
+
+  it("is held against the read field by field, the payee in its masked form", () => {
+    const read = {
+      receipt_id: "rcpt_1",
+      chain: "c".repeat(64),
+      mandate: { id: "cm_1", nonce: "n" },
+      quote: { payee: ESCOLA },
+      payment: { rail: "pix", amount_minor: 185000, attempt_id: "att_0", money_moved: false, at: "2026-09-26T18:00:01.000Z" },
+    };
+    const copy = { receipt_id: "rcpt_1", chain: "c".repeat(64), mandate: { id: "cm_1" }, payment: { amount_minor: 185000, payee: maskPayee(ESCOLA), attempt_id: "att_0", money_moved: false, sandbox: true, at: "2026-09-26T18:00:01.000Z" } };
+    expect(copyDisagreesWithRead(copy, read)).toEqual([]);
+    expect(copyDisagreesWithRead({ ...copy, payment: { ...copy.payment, amount_minor: 1 } }, read)).toEqual(["payment.amount_minor"]);
+    expect(copyDisagreesWithRead({ ...copy, payment: { ...copy.payment, payee: maskPayee(MERCADO) } }, read)).toEqual(["payment.payee"]);
+    expect(copyDisagreesWithRead({ ...copy, chain: "d".repeat(64) }, read)).toEqual(["chain"]);
+    // A copy written since 0.16.10 carries what was sealed, and is held to it; one from before carries neither and is not faulted.
+    const sealedRead = { ...read, chain_version: 4, approval: { items_hash: ITEMS_HASH, batch_hash: null } };
+    const sealedCopy = { ...copy, chain_version: 4, approval: { batch_hash: null, items_hash: ITEMS_HASH } };
+    expect(copyDisagreesWithRead(sealedCopy, sealedRead)).toEqual([]);
+    expect(copyDisagreesWithRead({ ...sealedCopy, approval: { items_hash: `sha256:${"9".repeat(64)}`, batch_hash: null } }, sealedRead)).toEqual(["approval"]);
+    expect(copyDisagreesWithRead({ ...sealedCopy, chain_version: 3 }, sealedRead)).toEqual(["chain_version"]);
+    expect(copyDisagreesWithRead(copy, sealedRead)).toEqual([]);
+  });
+});

package/templates/checkout-agent/packages/agent-core/test/approval.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { checkApprovalArtifact, createApprovalArtifact, hmacSigner } from "../src/approval.js";
+import { batchHash, itemsHash } from "../src/hash.js";
+import type { Execution } from "../src/state-machine.js";
+import type { Actor, ExecutionBatch, ExecutionItem } from "../src/types.js";
+
+const actor: Actor = { type: "human", id: "usr_1", channel: "terminal" };
+const signer = hmacSigner("test", Buffer.alloc(32, 7));
+const now = new Date("2026-09-23T14:03:11Z");
+
+function execution(items: ExecutionItem[]): Execution<"awaiting_approval"> {
+  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_1" },
+    items,
+    total: items.reduce((s, i) => s + i.amount, 0),
+    currency: "BRL",
+    items_hash: itemsHash(items),
+    mandate: { id: "mdt_1", version: 3 },
+    idempotency_key: "idk_1",
+    blocking_reasons: [],
+    outcomes: [],
+    history: [],
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  };
+}
+
+const escola: ExecutionItem = { alias: "escola", beneficiary: "Escola", payee: "escola@exemplo.com.br", amount: 185000, currency: "BRL" };
+const mercado: ExecutionItem = { alias: "mercado", beneficiary: "Mercado", payee: "+5511999990001", amount: 42000, currency: "BRL" };
+
+describe("section 4.2: approval artifact", () => {
+  it("has the schema of the spec and an HMAC signature that verifies", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(artifact.approval_id).toMatch(/^apr_/);
+    expect(artifact.execution_id).toBe("exe_1");
+    expect(artifact.mode).toBe("human");
+    expect(artifact.mandate).toEqual({ id: "mdt_1", version: 3 });
+    expect(artifact.items_hash).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(artifact.signature.alg).toBe("HMAC-SHA256");
+    expect(artifact.actor).toEqual(actor);
+    expect(new Date(artifact.expires_at).getTime() - new Date(artifact.approved_at).getTime()).toBe(15 * 60 * 1000);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+  });
+
+  it("items_hash ignores presentation fields and changes when the money fields change", () => {
+    const base = itemsHash([escola]);
+    expect(itemsHash([{ ...escola, description: "outubro", beneficiary: "Escola X" }])).toBe(base);
+    expect(itemsHash([{ ...escola, amount: 185001 }])).not.toBe(base);
+    expect(itemsHash([{ ...escola, payee: "outra@chave" }])).not.toBe(base);
+  });
+
+  it("refuses when the list changed after approval (items_hash mismatch)", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    const tampered = { ...exe, items: [{ ...escola, amount: 500000 }] };
+    expect(checkApprovalArtifact(signer, artifact, tampered, now)).toEqual({ ok: false, problem: "items_hash_mismatch" });
+  });
+
+  it("refuses a tampered artifact, an expired one and a foreign key", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(checkApprovalArtifact(signer, { ...artifact, items_hash: itemsHash([{ ...escola, amount: 1 }]) }, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+    expect(checkApprovalArtifact(signer, artifact, exe, new Date(now.getTime() + 16 * 60 * 1000))).toEqual({ ok: false, problem: "expired" });
+    expect(checkApprovalArtifact(hmacSigner("other", Buffer.alloc(32, 9)), artifact, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+    expect(checkApprovalArtifact(signer, artifact, { ...exe, mandate: { id: "mdt_1", version: 4 } }, now)).toEqual({ ok: false, problem: "wrong_mandate" });
+  });
+
+  it("carries the batch this line belongs to, and the whole of it is signed", () => {
+    const batch: ExecutionBatch = { ref: "folha-2026-10", batch_hash: batchHash([escola, mercado]), index: 0, count: 2 };
+    const exe = { ...execution([escola]), batch };
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(artifact.batch).toEqual(batch);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+    // Moving the line inside the list, re-pricing the list, or renaming it:
+    // each is a different set, and the signature covers all of it.
+    for (const changed of [{ ...batch, index: 1 }, { ...batch, count: 3 }, { ...batch, ref: "folha-2026-11" }, { ...batch, batch_hash: batchHash([escola]) }]) {
+      expect(checkApprovalArtifact(signer, { ...artifact, batch: changed }, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+      expect(checkApprovalArtifact(signer, artifact, { ...exe, batch: changed }, now)).toEqual({ ok: false, problem: "batch_mismatch" });
+    }
+  });
+
+  it("an artifact with no batch signs the payload it signed before batches existed", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    // Omitted, never null: a bills-agent run has no batch and must not grow a key.
+    expect("batch" in artifact).toBe(false);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+    // An execution that gained a batch after the artifact was signed is not the one that was approved.
+    const joined = { ...exe, batch: { ref: "folha-2026-10", batch_hash: batchHash([escola]), index: 0, count: 1 } };
+    expect(checkApprovalArtifact(signer, artifact, joined, now)).toEqual({ ok: false, problem: "batch_mismatch" });
+  });
+
+  it("the batch hash IS the items hash of the whole ordered list, so a reader can recompute it", () => {
+    expect(batchHash([escola, mercado])).toBe(itemsHash([escola, mercado]));
+    // Order is part of it: `index` names a position, and a position only means something in a fixed order.
+    expect(batchHash([mercado, escola])).not.toBe(batchHash([escola, mercado]));
+    // A line dropped is a different set, which is the whole point.
+    expect(batchHash([escola])).not.toBe(batchHash([escola, mercado]));
+  });
+
+  it("records the escalation trigger when there was one", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, {
+      execution: exe,
+      approver: { type: "person", id: "usr_1", channel: "terminal" },
+      actor,
+      now,
+      escalation: { trigger: "amount", detail: "above 150000" },
+    });
+    expect(artifact.escalation).toEqual({ trigger: "amount", detail: "above 150000" });
+  });
+});

package/templates/checkout-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 });
+  });
+});