@codespar/cli 0.16.0 → 0.18.0

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/order-marina.transcript.jsonl

@@ -0,0 +1,5 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "list_catalog", "input": {}}]}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_2", "name": "cart_update", "input": {"lines": [{"sku": "aula-avulsa", "quantity": 2}]}}]}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_3", "name": "codespar_charge", "input": {"action": "create", "customer": "marina", "total_minor": 20000}}]}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_4", "name": "codespar_charge", "input": {"action": "issue"}}]}
+{"kind": "assistant_step", "reply": "Pedido de duas aulas avulsas, R$ 200,00: o QR e o copia e cola estao acima."}

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/ordered-marina-awaiting-payer.transcript.jsonl

@@ -0,0 +1,6 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "list_catalog", "input": {}}]}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_2", "name": "cart_update", "input": {"lines": [{"sku": "pacote-10-aulas", "quantity": 1}, {"sku": "avaliacao-inicial", "quantity": 1}]}}]}
+{"kind": "assistant_step", "reply": "Oi, Marina! Montei o carrinho: pacote de 10 aulas de violao (R$ 390,00) e avaliacao inicial de nivel (R$ 89,90). Total R$ 479,90, cobranca por Pix ou boleto com vencimento hoje. Posso fechar o pedido?"}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_3", "name": "codespar_charge", "input": {"action": "create", "customer": "marina", "total_minor": 47990}}]}
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_4", "name": "codespar_charge", "input": {"action": "issue"}}]}
+{"kind": "assistant_step", "reply": "Pronto, Marina: a cobranca de R$ 479,90 esta emitida, o codigo esta acima. Assim que o pagamento cair, eu te confirmo por aqui."}

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/tap-falar-agora-marina.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "status"}}]}
+{"kind": "assistant_step", "reply": "Oi, Marina! Nao ha pedido em aberto nesta conversa. Quer montar um novo?"}

package/templates/checkout-agent/agents/checkout-agent/test/nfse.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Checkout §4: the NFS-e is a second execution after `settled`, called by
+ * code, that never moves the sale. A proven-unsent attempt is retried; an
+ * issuer refusal is terminal; anything else is `invoice_uncertain` and is
+ * never sent again.
+ */
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { StateStore, type ExecutionEngine } from "@codespar/agent-core";
+import { CodesparApiError } from "@codespar/sdk";
+import { checkScenario, loadScenario, runScenario, setup, type ScenarioRun } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { classifyExecuteAnswer, CodeSparInvoiceRail, InvoiceBook, resumeInvoices, type InvoiceRail, type InvoiceRecord, type NfseRequest } from "../src/modules/nfse-invoice.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "checkout-nfse-runs-"));
+const events = (run: ScenarioRun) => readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; execution_id?: string | null; actor?: unknown; payload?: Record<string, unknown> });
+
+async function scenario(name: string, mode: "human" | "mandate" = "human") {
+  const stateDir = mkdtempSync(join(tmpdir(), `checkout-nfse-${name}-`));
+  const run = await runScenario(agent, loadScenario(agent, name), { mode, runsDir, stateDir });
+  const store = new StateStore(join(stateDir, "state.db"));
+  const invoices = new InvoiceBook(store).all();
+  const outbox = store.listOutbox().filter((o) => o.kind === "nfse.issue");
+  store.close();
+  return { run, invoices, outbox, stateDir };
+}
+
+const ENV = "CHECKOUT_STUB_ISSUER";
+afterEach(() => {
+  delete process.env[ENV];
+});
+
+describe("checkout §4: the paid order opens its service invoice, and the invoice never moves the sale", () => {
+  it("codespar_invoice is not the model's: it is not in tools.json and no handler answers it (checkout §7.3, point 4)", () => {
+    const tools = JSON.parse(readFileSync(join(agent.dir, "tools.json"), "utf8")) as { meta_tools: Array<{ name: string }>; local_tools: Array<{ name: string }> };
+    expect([...tools.meta_tools, ...tools.local_tools].map((t) => t.name)).not.toContain("codespar_invoice");
+    const s = setup(agent, { rail: "stub", provider: "replay", transcript: "unused", stateDir: mkdtempSync(join(tmpdir(), "checkout-nfse-tools-")), runsDir, say: () => undefined });
+    try {
+      expect(Object.keys(s.handlers)).not.toContain("codespar_invoice");
+    } finally {
+      s.close();
+    }
+  });
+
+  it("happy-path: one NFS-e per paid order, issued from the order's own data, and the customer is told about the order only", async () => {
+    const { run, invoices, outbox } = await scenario("happy-path");
+    expect(run.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(invoices).toHaveLength(1);
+    const [invoice] = invoices;
+    expect(invoice).toMatchObject({ sale_execution_id: run.executions[0]!.id, state: "accepted", attempts: 1, charge_id: run.executions[0]!.charge_ids[0] });
+    expect(invoice!.document?.id).toMatch(/^nfse_stub_/);
+    expect(invoice!.history.map((h) => h.to)).toEqual(["pending", "issuing", "accepted"]);
+    expect(outbox).toEqual([expect.objectContaining({ status: "done", execution_id: invoice!.id })]);
+    const all = events(run);
+    const dispatched = all.filter((e) => e.type === "invoice.dispatch");
+    expect(dispatched).toHaveLength(1);
+    // What was PAID is what is invoiced, in the major units the meta-tool reads.
+    expect(dispatched[0]!.payload!["services_amount"]).toBe(479.9);
+    expect(all.filter((e) => e.type === "message.debtor")).toHaveLength(1);
+    expect(all.filter((e) => e.type === "message.attendant")).toHaveLength(0);
+    for (const e of all) expect(e.actor).toBeDefined();
+  });
+
+  it("nfse-failed: a refusal ends invoice_refused with the issuer's code; a timeout ends invoice_uncertain and is not sent again; both sales stay paid", async () => {
+    for (const mode of ["human", "mandate"] as const) {
+      const { run, invoices, outbox } = await scenario("nfse-failed", mode);
+      expect(checkScenario(loadScenario(agent, "nfse-failed"), run).failures).toEqual([]);
+      expect(run.executions.map((e) => e.state)).toEqual(["settled", "settled"]);
+      const [refused, uncertain] = invoices;
+      expect(refused).toMatchObject({ state: "failed", reason: "invoice_refused", code: "E0101", attempts: 1 });
+      expect(uncertain).toMatchObject({ state: "failed", reason: "invoice_uncertain", code: "timeout", attempts: 1 });
+      expect(outbox.map((o) => o.status)).toEqual(["failed", "failed"]);
+      const all = events(run);
+      // The attendant is told about each failure; the customers are told about their orders, twice in all, never about an invoice.
+      expect(all.filter((e) => e.type === "message.attendant").map((e) => e.payload!["reason"])).toEqual(["invoice_refused", "invoice_uncertain"]);
+      const told = all.filter((e) => e.type === "message.debtor").map((e) => String(e.payload!["text"]));
+      expect(told).toHaveLength(2);
+      for (const text of told) expect(text).not.toMatch(/nota|NFS-e|fiscal/i);
+      // Nothing moved the sale after it settled.
+      const settledAt = all.filter((e) => e.type === "execution.transition" && e.payload!["to"] === "settled").length;
+      expect(settledAt).toBe(2);
+      expect(all.filter((e) => e.type === "invoice.dispatch")).toHaveLength(2);
+    }
+  });
+
+  it("a timed-out issuance is NOT re-sent by resume: the stub issuer did authorize a note, and a second call would mint another", async () => {
+    const { invoices, stateDir } = await scenario("nfse-failed");
+    const calls: string[] = [];
+    const counting: InvoiceRail = { name: "stub-nfse", issue: async (_r, key) => (calls.push(key), { status: "accepted", document_id: "second", document_status: "X", pdf_url: null }) };
+    const s = setup(agent, { rail: "stub", provider: "replay", transcript: "unused", stateDir, runsDir, say: () => undefined });
+    try {
+      const resumed = await resumeInvoices({ store: s.store, engine: s.engine, rail: counting, cart: () => undefined, say: () => undefined });
+      expect(resumed).toEqual([]);
+      expect(calls).toEqual([]);
+      const store = s.store;
+      expect(store.getCursor(`stub-nfse:${invoices[1]!.idempotency_key}`)).toBeDefined();
+    } finally {
+      s.close();
+    }
+  });
+
+  it("an attempt proven unsent is retried under the same key, and stops at the bound", async () => {
+    process.env[ENV] = "unsent_once";
+    const once = await scenario("happy-path");
+    expect(once.invoices[0]).toMatchObject({ state: "accepted", attempts: 2 });
+    expect(once.invoices[0]!.history.map((h) => h.to)).toEqual(["pending", "issuing", "pending", "issuing", "accepted"]);
+
+    process.env[ENV] = "unsent";
+    const never = await scenario("happy-path");
+    expect(never.invoices[0]).toMatchObject({ state: "failed", reason: "invoice_unsent", code: "no_eligible_providers", attempts: 3 });
+    expect(never.run.executions.map((e) => e.state)).toEqual(["settled"]);
+  });
+
+  it("a crash after the request left (the record says issuing) is reconciled as uncertain by resume, and nothing is sent", async () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "checkout-nfse-crash-"));
+    const s = setup(agent, { rail: "stub", provider: "replay", transcript: "unused", stateDir, runsDir, say: () => undefined });
+    try {
+      const record: InvoiceRecord = { id: "inv_crash", sale_execution_id: "exe_crash", cart_ref: "run/cart-1", charge_id: "chg_1", idempotency_key: "nfse_crash", state: "issuing", attempts: 1, history: [], created_at: "2026-09-23T18:00:00.000Z", updated_at: "2026-09-23T18:00:00.000Z" };
+      new InvoiceBook(s.store).save(record);
+      s.store.putOutbox({ idempotency_key: "nfse_crash", execution_id: "inv_crash", kind: "nfse.issue", payload: {}, status: "sent", response: undefined, created_at: record.created_at });
+      const calls: string[] = [];
+      const said: string[] = [];
+      const [after] = await resumeInvoices({ store: s.store, engine: s.engine as ExecutionEngine, rail: { name: "stub-nfse", issue: async (_r, k) => (calls.push(k), { status: "accepted", document_id: "x", document_status: "X", pdf_url: null }) }, cart: () => undefined, say: (l) => said.push(l) });
+      expect(after).toMatchObject({ state: "failed", reason: "invoice_uncertain", code: "interrupted" });
+      expect(calls).toEqual([]);
+      expect(said.join(" ")).toContain("INCERTO");
+      expect(s.store.getOutbox("nfse_crash")?.status).toBe("failed");
+    } finally {
+      s.close();
+    }
+  });
+});
+
+describe("the wire, read by structure and code (codespar_invoice through POST /v1/sessions/{id}/execute)", () => {
+  it("classifies every answer the route can give", () => {
+    expect(classifyExecuteAnswer({ success: true, data: { id: "nf_1", status: "WAITINGSEND" }, error: null })).toMatchObject({ status: "accepted", document_id: "nf_1" });
+    // A success that names no document may still have minted one.
+    expect(classifyExecuteAnswer({ success: true, data: {}, error: null }).status).toBe("uncertain");
+    // provider_error is raised for an issuer 4xx AND for a timeout or a 5xx; the wire does not say which.
+    expect(classifyExecuteAnswer({ success: false, data: { error: "provider nfe-io returned status=400", code: "provider_error" }, error: "x", server: "unknown" }).status).toBe("uncertain");
+    for (const code of ["no_eligible_providers", "credential_unavailable", "invalid_args", "org_paused", "tool_unknown"]) {
+      expect(classifyExecuteAnswer({ success: false, data: { error: "x", code }, error: "x", server: "unknown" }).status).toBe("unsent");
+    }
+    expect(classifyExecuteAnswer({ success: false, data: { error: "x", code: "scope_missing" }, error: "x", server: "agentgate" }).status).toBe("unsent");
+    expect(classifyExecuteAnswer({ success: false, data: null, error: "Tool not registered: codespar_invoice", server: "" }).status).toBe("unsent");
+    // An unexpected throw inside the strategy answers output null: nobody can say.
+    expect(classifyExecuteAnswer({ success: false, data: null, error: "boom", server: "unknown" }).status).toBe("uncertain");
+    // The day the wire carries the provenance, it decides.
+    expect(classifyExecuteAnswer({ success: false, data: { code: "provider_error", dispatch: "rejected" }, error: "x", server: "unknown" }).status).toBe("refused");
+    expect(classifyExecuteAnswer({ success: false, data: { code: "provider_error", dispatch: "unsent" }, error: "x", server: "unknown" }).status).toBe("unsent");
+  });
+
+  it("the API rail: a session that will not open sent nothing; a 4xx from the route sent nothing; a timeout or a 5xx may have", async () => {
+    const request = { action: "issue", type: "nfse" } as NfseRequest;
+    const failing = (status: number, onSession = false) =>
+      new CodeSparInvoiceRail({
+        post: async (path: string) => {
+          if (path === "/v1/sessions" && !onSession) return { id: "ses_1" };
+          throw new CodesparApiError(`http ${status}`, { status });
+        },
+      } as never);
+    expect((await failing(503, true).issue(request)).status).toBe("unsent");
+    expect((await failing(403).issue(request)).status).toBe("unsent");
+    expect((await failing(503).issue(request)).status).toBe("uncertain");
+    const answered = new CodeSparInvoiceRail({ post: async (path: string, init: { body: { tool?: string; input?: unknown } }) => (path === "/v1/sessions" ? { id: "ses_1" } : { success: true, data: { id: "nf_9", status: "PROCESSING", tool: init.body.tool }, error: null, server: "nfe-io" }) } as never);
+    expect(await answered.issue(request)).toMatchObject({ status: "accepted", document_id: "nf_9", document_status: "PROCESSING" });
+  });
+});

package/templates/checkout-agent/agents/checkout-agent/test/pricing.test.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { compositionHash, GuardrailsSchema, itemsHash, type ExecutionItem } from "@codespar/agent-core";
+import { checkOrder, EnvelopeSchema, loadEnvelope, priceCart, type PricedCart } from "../src/pricing.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const guardrails = GuardrailsSchema.parse(JSON.parse(readFileSync(resolve(AGENT_DIR, "guardrails.json"), "utf8")));
+const envelope = loadEnvelope(guardrails);
+const TODAY = "2026-09-23";
+const AFTERNOON = new Date("2026-09-23T18:00:00Z"); // 15:00 in Sao Paulo
+const TZ = "America/Sao_Paulo";
+
+const codes = (cart: PricedCart) => cart.validation_issues.map((i) => i.code);
+const order = (cart: PricedCart, over: Partial<ExecutionItem> = {}) => {
+  const items: ExecutionItem[] = [{ beneficiary: "Marina Costa", payee: "27548613008", amount: cart.total, currency: "BRL", due_date: TODAY, ...over }];
+  return { items, total: items.reduce((s, i) => s + i.amount, 0), composition: { ref: "run/cart-1", composition_hash: cart.cart_hash, line_count: cart.composition.length } };
+};
+
+describe("checkout §2: the cart the code prices", () => {
+  it("the totals are the catalog's: lines priced, subtotal, discount and total computed, not taken", () => {
+    const cart = priceCart({ lines: [{ sku: "pacote-10-aulas", quantity: 1 }, { sku: "avaliacao-inicial", quantity: 1 }] }, envelope, TODAY);
+    expect(cart.validation_issues).toEqual([]);
+    expect(cart.total).toBe(47990);
+    expect(cart.line_items.map((l) => [l.sku, l.quantity, l.unit_amount])).toEqual([["pacote-10-aulas", 1, 39000], ["avaliacao-inicial", 1, 8990]]);
+    expect(cart.totals.find((t) => t.type === "total")?.amount).toBe(47990);
+  });
+
+  it("a line that carries a price is refused whole (price_not_caller_input), whatever the field is called", () => {
+    for (const field of ["price", "unit_price", "amount_minor", "total", "preco"]) {
+      const cart = priceCart({ lines: [{ sku: "avaliacao-inicial", quantity: 1, [field]: 1000 }] }, envelope, TODAY);
+      expect(codes(cart)).toEqual(["price_not_caller_input"]);
+      expect(cart.line_items).toEqual([]);
+      expect(cart.total).toBe(0);
+    }
+  });
+
+  it("the closed vocabulary: each code for its case, and a bad line is left out rather than guessed", () => {
+    expect(codes(priceCart({ lines: [{ sku: "guitarra", quantity: 1 }] }, envelope, TODAY))).toEqual(["sku_unknown"]);
+    expect(codes(priceCart({ lines: [{ sku: "masterclass-producao", quantity: 1 }] }, envelope, TODAY))).toEqual(["item_unavailable"]);
+    for (const q of [0, -1, 1.5, 11, "2"]) expect(codes(priceCart({ lines: [{ sku: "aula-avulsa", quantity: q }] }, envelope, TODAY))).toEqual(["quantity_invalid"]);
+    expect(codes(priceCart({ lines: [{ sku: "ingresso-recital", quantity: 5 }] }, envelope, TODAY))).toEqual(["quantity_above_stock"]);
+    expect(codes(priceCart({ lines: [{ sku: "aula-avulsa", quantity: 1 }], coupon: "PRIMEIRACOMPRA30" }, envelope, TODAY))).toEqual(["coupon_unknown"]);
+    expect(codes(priceCart({ lines: [{ sku: "aula-avulsa", quantity: 1 }], coupon: "BEMVINDO10" }, envelope, TODAY))).toEqual(["coupon_not_applicable"]);
+    expect(codes(priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "BEMVINDO10" }, envelope, "2027-01-01"))).toEqual(["coupon_not_applicable"]);
+    const mixed = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }, { sku: "guitarra", quantity: 1 }] }, envelope, TODAY);
+    expect(codes(mixed)).toEqual(["sku_unknown"]);
+    expect(mixed.total).toBe(20000);
+  });
+
+  it("an unknown coupon prices the cart with NO discount, never an equivalent one", () => {
+    const cart = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "PRIMEIRACOMPRA30" }, envelope, TODAY);
+    expect(cart.coupon).toBeNull();
+    expect(cart.order_discounts).toEqual([]);
+    expect(cart.total).toBe(20000);
+  });
+
+  it("a coupon in the table applies its own percentage and becomes a line of the composition", () => {
+    const cart = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "bemvindo10" }, envelope, TODAY);
+    expect(cart.coupon).toBe("BEMVINDO10");
+    expect(cart.total).toBe(18000);
+    expect(cart.composition.at(-1)).toMatchObject({ ref: "coupon:BEMVINDO10", amount: -2000 });
+  });
+
+  it("cart_hash is compositionHash over the resolved lines: it moves with quantity, SKU and order, and the same total can hash differently", () => {
+    const two = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }] }, envelope, TODAY);
+    const one = priceCart({ lines: [{ sku: "consultoria-1h", quantity: 1 }] }, envelope, TODAY);
+    expect(two.total).toBe(one.total);
+    expect(two.cart_hash).not.toBe(one.cart_hash);
+    expect(two.cart_hash).toBe(compositionHash(two.composition));
+    // The order's single item is the same in both: this is the case items_hash cannot see.
+    const item = (c: PricedCart): ExecutionItem => ({ beneficiary: "Marina Costa", payee: "27548613008", amount: c.total, currency: "BRL", due_date: TODAY });
+    expect(itemsHash([item(two)])).toBe(itemsHash([item(one)]));
+    const ab = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 1 }, { sku: "avaliacao-inicial", quantity: 1 }] }, envelope, TODAY);
+    const ba = priceCart({ lines: [{ sku: "avaliacao-inicial", quantity: 1 }, { sku: "aula-avulsa", quantity: 1 }] }, envelope, TODAY);
+    expect(ab.cart_hash).not.toBe(ba.cart_hash);
+  });
+
+  it("the envelope schema is strict: an extra key is a load error, not a key ignored", () => {
+    expect(() => EnvelopeSchema.parse({ ...envelope, free_shipping: true })).toThrow();
+  });
+});
+
+describe("checkout §3.3, §5: the gate the core runs at every gate", () => {
+  const ok = priceCart({ lines: [{ sku: "pacote-10-aulas", quantity: 1 }, { sku: "avaliacao-inicial", quantity: 1 }] }, envelope, TODAY);
+
+  it("passes an order that is the cart, at list price, inside the hours, due today", () => {
+    expect(checkOrder(order(ok), ok, envelope, AFTERNOON, TZ)).toBeUndefined();
+  });
+
+  it("refuses the discount that would reach an injected price (checkout §5.1), and never names the ceiling", () => {
+    const injected = priceCart({ lines: [{ sku: "avaliacao-inicial", quantity: 1, discount_pct: 88.88 }] }, envelope, TODAY);
+    expect(injected.total).toBe(1000);
+    const verdict = checkOrder(order(injected), injected, envelope, AFTERNOON, TZ);
+    expect(verdict?.reason).toBe("outside_envelope");
+    expect(verdict?.detail).not.toMatch(/12|%/);
+  });
+
+  it("refuses a line under the margin floor even inside the discount ceiling, without quoting a cost", () => {
+    // The package costs 300,00 to deliver: 5% off (370,50) is inside the 12% ceiling and below the 20% margin floor.
+    const thin = priceCart({ lines: [{ sku: "pacote-10-aulas", quantity: 1, discount_pct: 5 }] }, envelope, TODAY);
+    const verdict = checkOrder(order(thin), thin, envelope, AFTERNOON, TZ);
+    expect(verdict?.detail).toContain("piso de margem");
+    expect(verdict?.detail).not.toMatch(/300|3\.000|30000/);
+    const fine = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2, discount_pct: 10 }] }, envelope, TODAY);
+    expect(checkOrder(order(fine), fine, envelope, AFTERNOON, TZ)).toBeUndefined();
+  });
+
+  it("refuses a negotiated order discount above its ceiling, and a coupon stacked on a negotiated one", () => {
+    const over = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], order_discount_pct: 9 }, envelope, TODAY);
+    expect(checkOrder(order(over), over, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
+    const stacked = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "BEMVINDO10", order_discount_pct: 2 }, envelope, TODAY);
+    expect(checkOrder(order(stacked), stacked, envelope, AFTERNOON, TZ)?.detail).toContain("nao se somam");
+    const coupon = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "BEMVINDO10" }, envelope, TODAY);
+    expect(checkOrder(order(coupon), coupon, envelope, AFTERNOON, TZ)).toBeUndefined();
+  });
+
+  it("refuses an order that is not the current cart, a total that is not the cart's, and a missing cart", () => {
+    const changed = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 5 }] }, envelope, TODAY);
+    expect(checkOrder(order(ok), changed, envelope, AFTERNOON, TZ)?.detail).toContain("carrinho mudou");
+    expect(checkOrder({ ...order(ok), total: 100, items: [{ ...order(ok).items[0]!, amount: 100 }] }, ok, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
+    expect(checkOrder(order(ok), undefined, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
+    const { composition: _c, ...bare } = order(ok);
+    expect(checkOrder(bare, ok, envelope, AFTERNOON, TZ)?.detail).toContain("nasce de um carrinho");
+  });
+
+  it("refuses outside the service hours in either mode (outside_hours), and a due date outside the window", () => {
+    expect(checkOrder(order(ok), ok, envelope, new Date("2026-09-23T23:30:00Z"), TZ)?.reason).toBe("outside_hours");
+    expect(checkOrder(order(ok, { due_date: "2026-09-22" }), ok, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
+    expect(checkOrder(order(ok, { due_date: "2026-09-27" }), ok, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
+    expect(checkOrder(order(ok, { due_date: "2026-09-26" }), ok, envelope, AFTERNOON, TZ)).toBeUndefined();
+  });
+
+  it("refuses an order above the ticket ceiling", () => {
+    const big = priceCart({ lines: [{ sku: "pacote-10-aulas", quantity: 6 }] }, envelope, TODAY);
+    expect(checkOrder(order(big), big, envelope, AFTERNOON, TZ)?.detail).toContain("ticket maximo");
+  });
+});

package/templates/checkout-agent/agents/checkout-agent/test/scenarios.test.ts

@@ -0,0 +1,113 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ProofBundle } from "@codespar/agent-core";
+import { assembleTimeline, checkScenario, listScenarios, loadScenario, renderText, runScenario, type ScenarioRun } from "@codespar/agent-runtime";
+import { CUSTOMERS } from "../src/catalog.js";
+import { agent } from "../src/kit.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "checkout-runs-"));
+const DOCUMENTS = CUSTOMERS.map((c) => c.document);
+type Artifact = { execution_id: string; approver: { type: string }; items_hash: string; items: Array<{ amount: number; due_date?: string }>; composition?: { ref: string; composition_hash: string; line_count: number } };
+const approvals = (run: ScenarioRun): Artifact[] => {
+  const path = join(run.bundle_dir, "approval.json");
+  return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Artifact[]) : [];
+};
+const events = (run: ScenarioRun) => readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; actor?: unknown; payload?: Record<string, unknown> });
+
+describe("checkout §6: scenario packs, on the replay provider and the stub rail", () => {
+  const required = ["happy-path", "cart-replaced", "cart-recomposed", "price-injected", "coupon-unknown", "payment-claimed", "item-unavailable", "escalated-above-threshold", "charge-expired", "cap-exceeded", "beneficiary-not-allowed", "mandate-revoked", "prompt-injection", "nfse-failed"];
+
+  it("ships the fourteen scenarios of checkout §6", () => {
+    for (const name of required) expect(listScenarios(agent)).toContain(name);
+  });
+
+  for (const name of required) {
+    const scenario = loadScenario(agent, name);
+    for (const mode of scenario.modes) {
+      it(`${name} [${mode}] ends in the states the pack declares`, async () => {
+        const run = await runScenario(agent, scenario, { mode, runsDir });
+        const check = checkScenario(scenario, run);
+        expect(check.failures).toEqual([]);
+        expect(check.ok).toBe(true);
+        const all = events(run);
+        expect(all.length).toBeGreaterThan(0);
+        for (const e of all) expect(e.actor).toBeDefined();
+        for (const file of readdirSync(join(run.bundle_dir, "receipts"))) {
+          const receipt = JSON.parse(readFileSync(join(run.bundle_dir, "receipts", file), "utf8")) as { actor?: unknown; kind?: string; chain: string | null; payment: { payee: string | null; money_moved: boolean } };
+          expect(receipt.actor).toBeDefined();
+          expect(receipt.kind).toBe("charge");
+          expect(receipt.chain).toBeNull();
+          expect(receipt.payment.money_moved).toBe(false);
+        }
+        const snapshot = readFileSync(join(run.bundle_dir, "mandate.snapshot.json"), "utf8");
+        for (const doc of DOCUMENTS) expect(snapshot).not.toContain(doc);
+        // Every order that reached executing did so under an artifact that carries its composition, and that composition is the one it ran with.
+        for (const e of run.executions) {
+          if (!e.trail.includes("executing")) continue;
+          const artifact = approvals(run).filter((a) => a.execution_id === e.id).at(-1);
+          expect(artifact?.composition?.ref).toMatch(/\/cart-\d+$/);
+        }
+      });
+    }
+  }
+
+  it("happy-path: the same records in human and in mandate; the person decided in human, the policy in mandate; the order is due today", async () => {
+    const scenario = loadScenario(agent, "happy-path");
+    const human = await runScenario(agent, scenario, { mode: "human", runsDir });
+    const mandate = await runScenario(agent, scenario, { mode: "mandate", runsDir });
+    const [h] = approvals(human);
+    const [m] = approvals(mandate);
+    expect(h!.approver.type).toBe("person");
+    expect(m!.approver.type).toBe("mandate");
+    expect(h!.items_hash).toBe(m!.items_hash);
+    expect(h!.composition!.composition_hash).toBe(m!.composition!.composition_hash);
+    expect(h!.composition!.line_count).toBe(2);
+    expect(h!.items).toEqual([expect.objectContaining({ amount: 47990, due_date: "2026-09-23" })]);
+    for (const run of [human, mandate]) {
+      const all = events(run);
+      expect(all.filter((e) => e.type === "charge.instrument" && e.payload?.["payable"] === true)).toHaveLength(1);
+      expect(all.filter((e) => e.type === "message.debtor")).toHaveLength(1);
+      expect(all.filter((e) => e.type === "commerce.charge.paid")).toHaveLength(1);
+      expect(all.filter((e) => e.type === "rail.dispatch")).toHaveLength(1);
+    }
+  });
+
+  it("cart-recomposed: the two artifacts share items_hash and differ only in the composition, and one charge goes out", async () => {
+    for (const mode of ["human", "mandate"] as const) {
+      const run = await runScenario(agent, loadScenario(agent, "cart-recomposed"), { mode, runsDir });
+      const [first, second] = approvals(run);
+      expect(approvals(run)).toHaveLength(2);
+      expect(first!.items_hash).toBe(second!.items_hash);
+      expect(first!.composition!.composition_hash).not.toBe(second!.composition!.composition_hash);
+      expect(first!.composition!.ref).toBe(second!.composition!.ref);
+      expect(run.charges_issued).toBe(1);
+      const restated = events(run).filter((e) => e.type === "execution.restated");
+      expect(restated).toHaveLength(1);
+      expect(restated[0]!.payload!["items_hash"]).toMatchObject({ from: first!.items_hash, to: first!.items_hash });
+    }
+  });
+
+  it("npm run inspect reads the composition back from the artifact, beside items_hash", async () => {
+    const run = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "human", runsDir });
+    const text = renderText(assembleTimeline(new ProofBundle(runsDir, run.run_id)));
+    expect(text).toContain(`composed of 2 line(s) of ${run.run_id}/cart-1 · composition_hash ${approvals(run)[0]!.composition!.composition_hash}`);
+  });
+
+  it("cart-replaced: the order follows the cart, and the charge is for five lessons, never for two", async () => {
+    const run = await runScenario(agent, loadScenario(agent, "cart-replaced"), { mode: "human", runsDir });
+    const dispatched = events(run).filter((e) => e.type === "rail.dispatch").map((e) => e.payload?.["amount"]);
+    expect(dispatched).toEqual([50000]);
+    expect(approvals(run).map((a) => a.items[0]!.amount)).toEqual([20000, 50000]);
+  });
+
+  it("coupon-unknown and item-unavailable: the issue is named by code in the cart the model read", async () => {
+    for (const [name, code] of [["coupon-unknown", "coupon_unknown"], ["item-unavailable", "item_unavailable"]] as const) {
+      const run = await runScenario(agent, loadScenario(agent, name), { mode: "human", runsDir });
+      const replaced = events(run).filter((e) => e.type === "cart.replaced");
+      expect((replaced[0]!.payload!["validation_issues"] as Array<{ code: string }>).map((i) => i.code)).toEqual([code]);
+      expect(run.executions).toEqual([]);
+    }
+  });
+});

package/templates/checkout-agent/agents/checkout-agent/test/whatsapp.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The checkout-agent on WhatsApp, through the adapter the collections-agent
+ * already uses (checkout decision 6). The conversing cases need
+ * `dyvit-wa-sim` listening and SKIP when it is not, like the
+ * collections-agent's; `npm run whatsapp:gate` fails rather than skipping, and
+ * the CI runs it. What the binding and the templates refuse needs no emulator
+ * and runs everywhere.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseConversationScript, parseTemplateRegistry, templateArity, type Execution } from "@codespar/agent-core";
+import { handleExecution, setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+interface ChannelLine {
+  direction: "in" | "out";
+  kind: string;
+  text?: string;
+  refused?: { rule: string };
+}
+
+interface Payload {
+  executions: Array<{ state: string; reason: string | null; charge_id: string | null }>;
+  invoices: Array<{ state: string }>;
+  receipts: string[];
+  channel: { backend: string; refused: Array<{ rule: string }>; log: string };
+}
+
+function start(args: string[], extra: Record<string, string> = {}) {
+  const stateDir = mkdtempSync(join(tmpdir(), "checkout-wa-"));
+  const result = spawnSync(NODE, [BIN, "start", ...args], {
+    cwd: AGENT_DIR,
+    env: {
+      ...process.env,
+      ANTHROPIC_API_KEY: "",
+      CODESPAR_API_KEY: "",
+      WHATSAPP_PHONE_NUMBER_ID: "",
+      WHATSAPP_ACCESS_TOKEN: "",
+      WHATSAPP_VERIFY_TOKEN: "",
+      WHATSAPP_APP_SECRET: "",
+      CHECKOUT_STATE_DIR: stateDir,
+      CHECKOUT_RUNS_DIR: join(stateDir, "runs"),
+      // A conversation of its own on the emulator (#42): no case inherits another's inbound messages, or the window they anchor.
+      WHATSAPP_SIM_PHONE_NUMBER_ID: `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`,
+      ...extra,
+    },
+    encoding: "utf8",
+    timeout: 90_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+const payloadOf = (stdout: string) => JSON.parse(stdout.split("\n").filter(Boolean).pop()!) as Payload;
+const conversationOf = (p: Payload) => {
+  const path = isAbsolute(p.channel.log) ? p.channel.log : join(AGENT_DIR, p.channel.log);
+  expect(existsSync(path)).toBe(true);
+  return readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as ChannelLine);
+};
+
+const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+const emulatorUp = await (async () => {
+  try {
+    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+  } catch {
+    return false;
+  }
+})();
+if (!emulatorUp) process.stderr.write(`[whatsapp] no emulator at ${EMULATOR}; the conversing cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
+
+const NOW = ["--now", "2026-09-23T14:00:00-03:00"];
+
+describe.skipIf(!emulatorUp)("the sale closes over the WhatsApp channel", () => {
+  it("mandate, nobody at a keyboard: settled, the QR then the copy-and-paste, 'pedido confirmado', and the NFS-e that follows it accepted", () => {
+    const out = start(["--channel", "whatsapp", "--conversation", "pedido-marina", "--scripted", "--mode", "mandate", "--simulate-payer", "--json", ...NOW]);
+    expect(out.code).toBe(0);
+    const p = payloadOf(out.stdout);
+    expect(p.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(p.invoices.map((i) => i.state)).toEqual(["accepted"]);
+    expect(p.channel.backend).toBe("emulator");
+    const outbound = conversationOf(p).filter((l) => l.direction === "out");
+    const qr = outbound.findIndex((l) => l.kind === "media");
+    expect(outbound[qr + 1]?.kind).toBe("instrument");
+    expect(outbound.filter((l) => l.kind === "text" && /pedido confirmado/i.test(l.text ?? ""))).not.toHaveLength(0);
+    // The invoice is the attendant's business, never the customer's.
+    expect(outbound.some((l) => /nota fiscal|nfs-e/i.test(l.text ?? ""))).toBe(false);
+  });
+
+  it("human: the attendant's question goes to the console and never into the conversation", () => {
+    const out = start(["--channel", "whatsapp", "--conversation", "pedido-marina", "--scripted", "--mode", "human", "--approve", "--simulate-payer", "--json", ...NOW]);
+    expect(out.code).toBe(0);
+    const p = payloadOf(out.stdout);
+    expect(p.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(conversationOf(p).some((l) => /atendente|Confirmar este pedido/i.test(l.text ?? ""))).toBe(false);
+  });
+
+  it("checkout §5.4 on the channel: 'ja paguei' moves nothing, the order stays open and the customer hears no confirmation", () => {
+    const out = start(["--channel", "whatsapp", "--conversation", "pedido-beatriz", "--scripted", "--mode", "mandate", "--json", ...NOW], { CHECKOUT_STUB_PAYER: "never" });
+    expect(out.code).toBe(3);
+    const p = payloadOf(out.stdout);
+    expect(p.executions).toEqual([expect.objectContaining({ state: "executing", reason: "awaiting_settlement" })]);
+    expect(p.invoices).toEqual([]);
+    expect(conversationOf(p).some((l) => l.direction === "out" && /pedido confirmado|recebemos/i.test(l.text ?? ""))).toBe(false);
+  });
+});
+
+describe.skipIf(!emulatorUp)("§46: a tap is a turn on the checkout-agent too", () => {
+  it("a tapped 'Falar agora' on the fallback template is handed to the model as the intent the template declared", () => {
+    const out = start(["--channel", "whatsapp", "--conversation", "pedido-marina-retomada", "--scripted", "--mode", "mandate", "--transcript", "test/fixtures/tap-falar-agora-marina.transcript.jsonl", "--json", ...NOW]);
+    expect(out.code).toBe(0);
+    const p = JSON.parse(out.stdout.split("\n").filter(Boolean).pop()!) as { channel: { taps: unknown[]; log: string } };
+    expect(p.channel.taps).toEqual([{ id: "falar_agora", turn: true }]);
+    const tap = conversationOf(p as unknown as Payload).find((l) => l.kind === "reply") as ChannelLine & { reply?: { id: string } };
+    expect(tap.text).toBe("quero saber qual e a atualizacao do meu atendimento");
+  });
+});
+
+describe("the conversation decides who is charged, with no emulator in sight", () => {
+  it("an order in Marina's conversation for another customer of the store is refused before it exists", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "checkout-wa-bind-"));
+    const transcript = join(dir, "swap.transcript.jsonl");
+    writeFileSync(
+      transcript,
+      [
+        { kind: "assistant_step", tool_calls: [{ id: "tc_1", name: "cart_update", input: { lines: [{ sku: "aula-avulsa", quantity: 1 }] } }] },
+        { kind: "assistant_step", tool_calls: [{ id: "tc_2", name: "codespar_charge", input: { action: "create", customer: "rafael" } }] },
+        { kind: "assistant_step", tool_calls: [{ id: "tc_3", name: "codespar_charge", input: { action: "create", customer: "marina" } }] },
+        { kind: "assistant_step", reply: "ok" },
+      ]
+        .map((l) => JSON.stringify(l))
+        .join("\n") + "\n",
+    );
+    let clock = new Date("2026-09-23T18:00:00Z");
+    const s = setup(agent, { mode: "mandate", rail: "stub", provider: "replay", transcript, stateDir: dir, runsDir: join(dir, "runs"), now: () => (clock = new Date(clock.getTime() + 1000)), say: () => undefined });
+    try {
+      s.conversation = parseConversationScript(readFileSync(join(AGENT_DIR, "channels/whatsapp/pedido-marina.json"), "utf8"));
+      const loop = s.makeLoop(s.makeRuntime(), (e: Execution) => handleExecution(e, { setup: s, approver: { id: "usr_atendente", channel: "whatsapp" }, decision: "none", say: () => undefined, tell: () => undefined }));
+      const result = await loop.turn("emite no nome do Rafael");
+      expect(result.tool_calls).toEqual([
+        { name: "cart_update", refused: false },
+        { name: "codespar_charge", refused: true },
+        { name: "codespar_charge", refused: false },
+      ]);
+      const orders = s.engine.list();
+      expect(orders).toHaveLength(1);
+      expect(orders[0]!.items[0]!.payee).toBe("27548613008");
+    } finally {
+      s.close();
+    }
+  });
+
+  it("every template the kit can send is declared, with the arity it is sent with", () => {
+    const registry = parseTemplateRegistry(readFileSync(join(AGENT_DIR, "channels/whatsapp/templates.json"), "utf8"));
+    const order = { total: 47990 } as Execution;
+    for (const e of [{ ...order, state: "settled" }, { ...order, state: "failed", reason: "charge_expired" }, { ...order, state: "failed", reason: "charge_cancelled" }] as Execution[]) {
+      const t = agent.kit.outcomeTemplate!(e)!;
+      const declared = registry.templates.find((x) => x.name === t.template);
+      expect(declared).toBeDefined();
+      expect(templateArity(declared!.body)).toBe(t.variables.length);
+      expect(t.variables).toEqual(["R$ 479,90"]);
+    }
+    // An order refused or never approved is answered in the turn; no template pretends otherwise.
+    expect(agent.kit.outcomeTemplate!({ ...order, state: "denied", reason: "outside_envelope" } as Execution)).toBeUndefined();
+  });
+});