@codespar/cli 0.17.0 → 0.18.1

package/templates/supplier-payments-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/supplier-payments-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/supplier-payments-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),

package/templates/supplier-payments-agent/packages/agent-core/test/mandate-status.test.ts

@@ -2,12 +2,16 @@
  * Section 4.7 against the real client: `ApiMandateStatusSource` reads
  * `GET /v1/mandates/{id}` on a mocked HTTP server, and the engine is driven
  * through it. Every answer but `active` must keep `rail.pay` from ever
- * being called, and a read that does not answer must refuse too.
+ * being called, and a read that does not answer must refuse too. The
+ * organization kill switch (ent#1648) rides on the same read as `org_paused`,
+ * and the spend route refuses 403 `org_paused` on its own when the switch is
+ * pressed after the read.
  */
 import { createServer, type Server } from "node:http";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createCodeSparClient } from "../src/api/client.js";
 import { ApiMandateStatusSource } from "../src/api/mandate-status.js";
+import { CodeSparRail } from "../src/api/rail.js";
 import type { MandateStatusSource } from "../src/revocation.js";
 import { harness, type Harness } from "./helpers.js";
 
@@ -15,7 +19,7 @@ const MANDATE_ID = "mdt_test_0001";
 const NOW = new Date("2026-09-23T18:00:00Z");
 const approver = { id: "usr_demo_titular", channel: "terminal" };
 
-/** The 14-field projection `GET /v1/mandates/{id}` answers (measured on staging, 2026-09-23). */
+/** The 14-field projection `GET /v1/mandates/{id}` answers (measured on staging, 2026-09-23), plus the two kill-switch fields of ent#1648. */
 function mandateBody(over: Record<string, unknown> = {}): Record<string, unknown> {
   return {
     id: MANDATE_ID,
@@ -32,6 +36,8 @@ function mandateBody(over: Record<string, unknown> = {}): Record<string, unknown
     status: "active",
     expires_at: "2027-09-23T00:00:00.000Z",
     created_at: "2026-09-23T00:00:00.000Z",
+    org_paused: false,
+    org_paused_at: null,
     ...over,
   };
 }
@@ -41,14 +47,17 @@ type Answer = { status: number; body?: unknown; hang?: boolean };
 let server: Server;
 let baseUrl: string;
 let next: Answer = { status: 200, body: mandateBody() };
+/** What a POST (the spend) answers, when a test sends one; the mandate read keeps answering `next`. */
+let spendNext: Answer | undefined;
 const requests: Array<{ method: string; url: string; bearerIsTestKey: boolean }> = [];
 
 beforeAll(async () => {
   server = createServer((req, res) => {
     requests.push({ method: req.method ?? "", url: req.url ?? "", bearerIsTestKey: (req.headers.authorization ?? "").startsWith("Bearer csk_test_") });
-    if (next.hang) return; // never answers: the client's timeout is the only way out
-    res.writeHead(next.status, { "content-type": "application/json" });
-    res.end(typeof next.body === "string" ? next.body : JSON.stringify(next.body));
+    const answer = req.method === "POST" && spendNext ? spendNext : next;
+    if (answer.hang) return; // never answers: the client's timeout is the only way out
+    res.writeHead(answer.status, { "content-type": "application/json" });
+    res.end(typeof answer.body === "string" ? answer.body : 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}`;
@@ -61,12 +70,17 @@ afterAll(async () => {
 
 beforeEach(() => {
   next = { status: 200, body: mandateBody() };
+  spendNext = undefined;
   requests.length = 0;
 });
 
-function apiSource(timeoutMs = 5_000): ApiMandateStatusSource {
+function apiClient(timeoutMs = 5_000) {
   // The placeholder passes the `csk_test_` guard and is the one test-key-shaped string the secret scan allows.
-  return new ApiMandateStatusSource(createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs }), () => NOW);
+  return createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs });
+}
+
+function apiSource(timeoutMs = 5_000): ApiMandateStatusSource {
+  return new ApiMandateStatusSource(apiClient(timeoutMs), () => NOW);
 }
 
 function apiHarness(status: MandateStatusSource = apiSource()): Harness {
@@ -147,7 +161,69 @@ describe("section 4.7 through the engine, on the API source: executing only on a
     expect(h.rail.payCount).toBe(0);
   });
 
-  it("the API source never reports org_paused: the API has no kill-switch read, and the source does not invent one", async () => {
-    expect((await apiSource().check(MANDATE_ID)).org_paused).toBe(false);
+});
+
+describe("the organization kill switch (ent#1648): org_paused on the read, 403 org_paused on the spend", () => {
+  const PAUSED = { org_paused: true, org_paused_at: "2026-09-23T17:30:00.000Z" };
+
+  it("the source reports org_paused as the API says it, and keeps the mandate's own status next to it", async () => {
+    next = { status: 200, body: mandateBody(PAUSED) };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "active", org_paused: true, source: "api" });
+  });
+
+  it("org_paused missing, or not a boolean, is unknown: never read as a running organization", async () => {
+    const { org_paused: _dropped, ...withoutFlag } = mandateBody();
+    next = { status: 200, body: withoutFlag };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", org_paused: false, detail: expect.stringContaining("org_paused") });
+    next = { status: 200, body: mandateBody({ org_paused: "false" }) };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("org_paused") });
+    next = { status: 200, body: mandateBody({ org_paused: null }) };
+    expect((await apiSource().check(MANDATE_ID)).status).toBe("unknown");
+  });
+
+  it("paused before execute: the gate denies (org_paused) whatever status says, no outbox row, rail.pay never called", async () => {
+    const h = apiHarness();
+    const id = await approvedThen(h, { status: 200, body: mandateBody(PAUSED) });
+    const out = await h.engine.execute(id);
+    expect(out).toMatchObject({ state: "denied", reason: "org_paused" });
+    expect(h.store.listOutbox()).toHaveLength(0);
+    expect(h.rail.payCount).toBe(0);
+    expect(await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] })).toMatchObject({ ok: false, refused_before_draft: true, reason: "org_paused" });
+  });
+
+  it("a read without org_paused after approval: denied (mandate_status_unavailable), rail.pay never called", async () => {
+    const h = apiHarness();
+    const { org_paused: _dropped, ...withoutFlag } = mandateBody();
+    const id = await approvedThen(h, { status: 200, body: withoutFlag });
+    const out = await h.engine.execute(id);
+    expect(out).toMatchObject({ state: "denied", reason: "mandate_status_unavailable" });
+    expect(out.detail).toContain("org_paused");
+    expect(h.rail.payCount).toBe(0);
   });
+
+  // Paused between the gate and the spend: the read said running, the API refuses the spend itself before any hold.
+  // The execution is already `executing`, and section 4.7 closes that state as `settled` or `failed` only: no new edge.
+  const spendRefusals: Array<[string, unknown]> = [
+    ["the documented envelope", { error: { code: "org_paused", message: "the organization paused all agent spend (kill switch)" }, request_id: null }],
+    ["the flat body the guardrail sends", { error: "org_paused", message: "the organization paused all agent spend (kill switch)" }],
+  ];
+  for (const [shape, body] of spendRefusals) {
+    it(`paused between the gate and the spend, 403 org_paused (${shape}): failed (org_paused), and nothing but the read and the one spend reached the API`, async () => {
+      const h = harness({ mode: "mandate", now: NOW, manifest: { escalate_above: {} }, guardrails: { escalate_above: {} }, status: apiSource(), wrapRail: () => new CodeSparRail(apiClient()) });
+      const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] });
+      if (!d.ok) throw new Error(`refused before draft: ${d.reason}`);
+      spendNext = { status: 403, body };
+      const out = await h.engine.execute(d.execution.id);
+      expect(out.state).toBe("failed");
+      expect(out.reason).toBe("org_paused");
+      expect(out.history.at(-1)).toMatchObject({ from: "executing", to: "failed", reason: "org_paused" });
+      expect(out.outcomes).toEqual([expect.objectContaining({ status: "failed", code: "org_paused" })]);
+      expect(out.outcomes.some((o) => "receipt_id" in o || "transaction_id" in o)).toBe(false);
+      expect(h.store.listOutbox({ execution_id: out.id })).toEqual([expect.objectContaining({ status: "failed" })]);
+      // No receipt read, no ledger or fund call, no second spend: the mandate read(s) and exactly one POST.
+      const spend = `/v1/consumers/mandates/${out.mandate.id}/spend`;
+      expect(requests.filter((r) => r.method === "POST").map((r) => r.url)).toEqual([spend]);
+      expect(requests.filter((r) => !(r.method === "GET" && r.url === `/v1/mandates/${out.mandate.id}`) && r.url !== spend)).toEqual([]);
+    });
+  }
 });

package/templates/supplier-payments-agent/packages/agent-core/test/quote.test.ts

@@ -0,0 +1,198 @@
+/**
+ * OPEN_QUESTIONS §18: the sealed receipt names the payee only when the spend
+ * carries a `SpendQuote`. Every spend carries one, built from the approval
+ * artifact's line; a spend without one, or with one that disagrees with the
+ * money about to move, never reaches the API; and a receipt whose sealed
+ * payee is not the payee that was paid is an error, not a line in a log.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ApiClient } from "@codespar/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { hmacSigner } from "../src/approval.js";
+import { CodeSparRail } from "../src/api/rail.js";
+import { maskPayee } from "../src/bundle.js";
+import { ReceiptSealMismatchError } from "../src/engine.js";
+import { canonicalJson } from "../src/hash.js";
+import { checkQuote } from "../src/quote.js";
+import type { PaymentRail, RailPayment } 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" };
+
+function payment(over: Partial<RailPayment> = {}): RailPayment {
+  return {
+    attempt_id: "att_quote_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: `sha256:${"1".repeat(64)}` },
+    actor,
+    ...over,
+  };
+}
+
+/** An ApiClient that records what it was asked and answers a settled spend. */
+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" } }));
+  const get = vi.fn(async () => receiptBody);
+  return { api: { post, get } as unknown as ApiClient, post, get };
+}
+
+/** The stub rail, but the receipt it hands back seals whatever payee the test says. */
+function sealing(inner: PaymentRail, sealedPayee: string | null): PaymentRail {
+  return {
+    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, payment: { ...r.payment, payee: sealedPayee } };
+    },
+  };
+}
+
+describe("§18: every spend presents the quote of what was approved", () => {
+  it("the quote is the approved line: seller, resource, price, payee and the moment of approval", async () => {
+    const h = harness({ mode: "human" });
+    const seen: RailPayment[] = [];
+    const inner = h.rail;
+    const pay = inner.pay.bind(inner);
+    inner.pay = async (p) => (seen.push(p), pay(p));
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000, description: "outubro" }, { 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.quote)).toEqual([
+      { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, at: artifact.approved_at },
+      // No description on the line: the resource is the mandate's purpose, never something the model adds later.
+      { seller: "Mercado do Bairro", resource: "contas do mes", price_minor: 32000, payee: MERCADO, at: artifact.approved_at },
+    ]);
+  });
+
+  it("the local receipt copy carries the payee the receipt sealed, 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 settled = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    const copy = JSON.parse(readFileSync(join(h.bundle.dir, "receipts", `${settled.outcomes[0]!.receipt_id}.json`), "utf8"));
+    expect(copy.payment.payee).toBe(maskPayee(ESCOLA));
+    expect(JSON.stringify(copy)).not.toContain(ESCOLA);
+  });
+
+  it("an artifact whose line disagrees with the execution is refused before the call, even when its hash and signature hold", 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);
+    // A writer bug, not an attacker: the artifact's items no longer say what its items_hash says. Re-signed with the harness key.
+    const { signature: _old, ...unsigned } = h.store.getApproval(approved.approval_id!)!;
+    const drifted = { ...unsigned, items: unsigned.items.map((i) => ({ ...i, amount: 999 })) };
+    h.store.saveApproval({ ...drifted, signature: { alg: "HMAC-SHA256", key_id: "test", value: hmacSigner("test", Buffer.alloc(32, 1)).sign(canonicalJson(drifted)) } });
+
+    const denied = await h.engine.execute(approved.id);
+    expect(denied.state).toBe("denied");
+    expect(denied.reason).toBe("quote_mismatch");
+    expect(h.rail.payCount).toBe(0);
+  });
+});
+
+describe("§18: a spend that would not seal what was approved never goes out", () => {
+  it("checkQuote: missing, wrong price, wrong payee", () => {
+    expect(checkQuote(payment())).toMatchObject({ ok: true });
+    const { quote: _q, ...bare } = payment();
+    expect(checkQuote(bare)).toMatchObject({ ok: false, code: "quote_missing" });
+    expect(checkQuote(payment({ amount_minor: 185001 }))).toMatchObject({ ok: false, code: "quote_mismatch" });
+    expect(checkQuote(payment({ payee: MERCADO }))).toMatchObject({ ok: false, code: "quote_mismatch" });
+  });
+
+  it("the CodeSpar rail refuses a spend without a quote, and one that disagrees, without calling the API", async () => {
+    const { api, post } = fakeApi();
+    const rail = new CodeSparRail(api, { canonical: { any: "envelope" } as never, signature: "a".repeat(64) });
+    const { quote: _q, ...bare } = payment();
+    expect(await rail.pay(bare)).toMatchObject({ status: "failed", code: "quote_missing" });
+    expect(await rail.pay(payment({ amount_minor: 1 }))).toMatchObject({ status: "failed", code: "quote_mismatch" });
+    expect(await rail.pay(payment({ payee: MERCADO }))).toMatchObject({ status: "failed", code: "quote_mismatch" });
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("the CodeSpar rail sends the quote on both spend routes", async () => {
+    const quote = payment().quote;
+    const byEnvelope = fakeApi();
+    await new CodeSparRail(byEnvelope.api, { canonical: { any: "envelope" } as never, signature: "a".repeat(64) }).pay(payment());
+    expect(byEnvelope.post.mock.calls[0]![0]).toBe("/v1/consumer-payments/execute");
+    expect(byEnvelope.post.mock.calls[0]![1].body["quote"]).toEqual(quote);
+    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["quote"]).toEqual(quote);
+  });
+
+  it("the stub rail makes the same refusal, so a scenario cannot pass without a quote", async () => {
+    const h = harness();
+    const { quote: _q, ...bare } = payment();
+    expect(await h.rail.pay(bare)).toMatchObject({ status: "failed", code: "quote_missing" });
+    expect(h.rail.payCount).toBe(0);
+  });
+});
+
+describe("§18: the receipt's payee is the sealed one, and a mismatch is an error", () => {
+  const sealed = (quote: unknown) => ({
+    receipt_id: "rcpt_1",
+    state: "paid",
+    mandate: { id: "cm_1", nonce: "n", scope: "s", currency: "BRL", sig: "x" },
+    quote,
+    payment: { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_quote_0", money_moved: false, at: "2026-09-23T18:00:01.000Z" },
+    delivery: null,
+    chain: "c".repeat(64),
+    receipt_sig: "s",
+    exceptions: [],
+  });
+
+  it("the CodeSpar rail reads the payee from the sealed quote, and null when the receipt sealed none", async () => {
+    const withQuote = await new CodeSparRail(fakeApi(sealed({ seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, session_id: null, sig: "q", at: null })).api).receipt("rcpt_1", actor);
+    expect(withQuote?.payment.payee).toBe(ESCOLA);
+    const without = await new CodeSparRail(fakeApi(sealed(null)).api).receipt("rcpt_1", actor);
+    expect(without?.payment.payee).toBeNull();
+  });
+
+  it("a mixed-case key sealed as it was sent raises nothing; the same key sealed lower-cased is a mismatch", async () => {
+    const MIXED = "Financeiro@Escola-Aurora.example.com.br";
+    const mandate = { merchant_allowlist: [MIXED] as [string], beneficiaries: [{ alias: "escola", name: "Escola Aurora", payee: MIXED }] as [{ alias: string; name: string; payee: string }] };
+    const verbatim = harness({ mode: "human", mandate });
+    const d1 = await verbatim.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!d1.ok) throw new Error("refused");
+    expect((await verbatim.engine.execute(verbatim.engine.approve(d1.execution.id, approver).id)).state).toBe("settled");
+    expect(verbatim.bundle.readEvents().some((e) => e["type"] === "receipt.seal_mismatch")).toBe(false);
+
+    // The API stores and returns quote.payee verbatim (OPEN_QUESTIONS §18); if that ever changes, this is what the kit says.
+    const lowered = harness({ mode: "human", mandate, wrapRail: (stub) => sealing(stub, MIXED.toLowerCase()) });
+    const d2 = await lowered.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!d2.ok) throw new Error("refused");
+    await expect(lowered.engine.execute(lowered.engine.approve(d2.execution.id, approver).id)).rejects.toBeInstanceOf(ReceiptSealMismatchError);
+  });
+
+  for (const [label, sealedPayee] of [["a different payee", MERCADO], ["no payee at all (a spend the API sealed without a quote)", null]] as const) {
+    it(`a receipt sealing ${label} throws after the outcome is saved, and the bundle says why without the key in the clear`, async () => {
+      const h = harness({ mode: "human", wrapRail: (stub) => sealing(stub, sealedPayee) });
+      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);
+
+      await expect(h.engine.execute(approved.id)).rejects.toBeInstanceOf(ReceiptSealMismatchError);
+      // The money is recorded where the rail put it; the error is about the evidence.
+      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_payee: sealedPayee === null ? null : maskPayee(sealedPayee), paid_payee: maskPayee(ESCOLA) });
+      expect(JSON.stringify(mismatch)).not.toContain(ESCOLA);
+      if (sealedPayee) expect(JSON.stringify(mismatch)).not.toContain(sealedPayee);
+    });
+  }
+});