@codespar/cli 0.17.0 → 0.18.1

package/templates/checkout-agent/packages/agent-core/test/fixtures/staging-receipt-keys.json

@@ -0,0 +1,18 @@
+{
+  "issuer": "did:web:id.codespar.dev",
+  "algorithm": "Ed25519",
+  "signing_string": "codespar-receipt:v1:<receipt_id>:<chain>",
+  "keys": [
+    {
+      "kid": "did:web:id.codespar.dev#1",
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "x": "u7hulmfhdU9wxv44pfychrNTF0RvUIwDn_QKi3j5Puk",
+      "alg": "EdDSA",
+      "use": "sig",
+      "status": "active",
+      "created_at": "2026-09-24T22:22:38.589Z",
+      "retired_at": null
+    }
+  ]
+}

package/templates/checkout-agent/packages/agent-core/test/fixtures/staging-receipt.json

@@ -0,0 +1,24 @@
+{
+  "receipt_id": "rcpt_BkYTo_9eJnlyzGsRjfFYHk",
+  "state": "paid",
+  "mandate": {
+    "id": "cm_8m6ew__uzvMrp2i3"
+  },
+  "payment": {
+    "amount_minor": 185000,
+    "payee": null,
+    "attempt_id": "att_50fa99e93ed1183520bfd185d350a7c4_0",
+    "money_moved": false,
+    "sandbox": true,
+    "at": "2026-09-24T22:42:41.242Z"
+  },
+  "chain": "cf5a00d44c4aea42bd7e4bcb48f37f077bfeae1ff5f6f4fff20438861a79e17d",
+  "receipt_sig": "9a63a12e9ab88e10c76f77d8ec0c3f4dec9ca1251579a608be1be260922b312c",
+  "receipt_sig_ed25519": "aQTf3A1UR8kdthPUwBDfAmnnpYyn8SUp1DYyKcvMylOYhLtznQS_h2SB-N9PxQtSS2wTSO-lp_YDrrVS5Nz1CA",
+  "receipt_sig_kid": "did:web:id.codespar.dev#1",
+  "actor": {
+    "type": "agent",
+    "agent": "bills-agent@0.1.0",
+    "on_behalf_of": "usr_demo_titular"
+  }
+}

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

@@ -0,0 +1,142 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hmacSigner } from "../src/approval.js";
+import { ProofBundle } from "../src/bundle.js";
+import { ExecutionEngine, type EngineDeps } from "../src/engine.js";
+import { GuardrailsSchema, type Guardrails } from "../src/guardrails.js";
+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";
+
+export const ESCOLA = "escola@exemplo.com.br";
+export const MERCADO = "+5511999990001";
+export const FUNCIONARIA = "123.456.789-09";
+
+export function testManifest(over: Partial<Manifest> = {}): Manifest {
+  return ManifestSchema.parse({
+    schema: 1,
+    name: "bills-agent",
+    version: "0.1.0",
+    approval: ["human", "mandate"],
+    default_approval: "human",
+    escalate_above: { amount: 150000, new_beneficiary: true, outside_hours: "22:00-07:00" },
+    mcp: "@codespar/mcp@0.5.8",
+    cli: "@codespar/cli@0.14.0",
+    tools: "./tools.json",
+    guardrails: "./guardrails.json",
+    mandate_schema: "./mandate.example.json",
+    events: ["commerce.payment.succeeded", "commerce.payment.failed"],
+    channels: ["terminal"],
+    maturity: { "pix-out": "sandbox", "embedded-consent": "sandbox", "receipt-verification": "blocked" },
+    scenarios: "./scenarios/",
+    evals: "./evals/",
+    agents_md: "./AGENTS.md",
+    ...over,
+  });
+}
+
+export function testGuardrails(over: Partial<Guardrails> = {}): Guardrails {
+  return GuardrailsSchema.parse({
+    approval: "human",
+    escalate_above: { amount: 150000, new_beneficiary: true, outside_hours: "22:00-07:00" },
+    velocity: { window_hours: 24 },
+    ...over,
+  });
+}
+
+export function testMandate(over: Partial<Mandate> = {}): Mandate {
+  return MandateSchema.parse({
+    id: "mdt_test_0001",
+    version: 1,
+    consumer_id: "usr_demo",
+    agent_id: "bills-agent",
+    purpose: "contas do mes",
+    currency: "BRL",
+    cap_minor: 7200000,
+    per_tx_cap_minor: 250000,
+    periodic_cap: { window: "month", cap_minor: 600000 },
+    merchant_pin_kind: "pix-key",
+    merchant_allowlist: [ESCOLA, MERCADO, FUNCIONARIA],
+    beneficiaries: [
+      { alias: "escola", name: "Escola Aurora", payee: ESCOLA },
+      { alias: "mercado", name: "Mercado do Bairro", payee: MERCADO },
+      { alias: "funcionaria", name: "Maria (funcionaria)", payee: FUNCIONARIA },
+    ],
+    status: "active",
+    expires_at: "2027-09-23T00:00:00.000Z",
+    ...over,
+  });
+}
+
+export interface Harness {
+  dir: string;
+  store: StateStore;
+  gate: LocalMandateStatusStub;
+  rail: StubRail;
+  bundle: ProofBundle;
+  engine: ExecutionEngine;
+  now: Date;
+  setNow(date: Date): void;
+}
+
+export interface HarnessOptions {
+  mode?: ApprovalMode;
+  now?: Date;
+  guardrails?: Partial<Guardrails>;
+  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. */
+  status?: MandateStatusSource;
+}
+
+export function harness(options: HarnessOptions = {}): Harness {
+  const dir = options.dir ?? mkdtempSync(join(tmpdir(), "agent-core-"));
+  let now = options.now ?? new Date("2026-09-23T18:00:00Z"); // 15:00 in Sao Paulo
+  const clock = () => now;
+  const store = new StateStore(join(dir, "state.db"));
+  const gate = new LocalMandateStatusStub(store, clock);
+  const rail = new StubRail(store, { clock, ...(options.rail ?? {}) });
+  const runId = options.runId ?? "run_test";
+  const bundle = new ProofBundle(join(dir, "runs"), runId);
+  const mode = options.mode ?? "human";
+  const deps: EngineDeps = {
+    store,
+    rail: options.wrapRail ? options.wrapRail(rail) : rail,
+    status: options.status ?? gate,
+    signer: hmacSigner("test", Buffer.alloc(32, 1)),
+    manifest: testManifest(options.manifest),
+    guardrails: testGuardrails({ approval: mode, ...(options.guardrails ?? {}) }),
+    mandate: testMandate(options.mandate),
+    bundle,
+    mode,
+    runId,
+    onBehalfOf: "usr_demo",
+    clock,
+  };
+  const engine = new ExecutionEngine(deps);
+  return {
+    dir,
+    store,
+    gate,
+    rail,
+    bundle,
+    engine,
+    get now() {
+      return now;
+    },
+    setNow(date: Date) {
+      now = date;
+    },
+  };
+}

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

@@ -0,0 +1,229 @@
+/**
+ * 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. 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";
+
+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), plus the two kill-switch fields of ent#1648. */
+function mandateBody(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: MANDATE_ID,
+    consumer_id: "usr_demo",
+    agent_id: "bills-agent",
+    display_name: null,
+    purpose: "contas do mes",
+    merchant_allowlist: ["escola@exemplo.com.br"],
+    merchant_pin_kind: "pix-key",
+    intent_note: null,
+    cap_minor: "7200000",
+    per_tx_cap_minor: "250000",
+    currency: "BRL",
+    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,
+  };
+}
+
+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_") });
+    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}`;
+});
+
+afterAll(async () => {
+  server.closeAllConnections();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+beforeEach(() => {
+  next = { status: 200, body: mandateBody() };
+  spendNext = undefined;
+  requests.length = 0;
+});
+
+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 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 {
+  return harness({ mode: "mandate", now: NOW, manifest: { escalate_above: {} }, guardrails: { escalate_above: {} }, status });
+}
+
+/** Drafts and approves under `active`, then flips the API's answer: the last gate is what is under test. */
+async function approvedThen(h: Harness, answer: Answer): Promise<string> {
+  const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] });
+  if (!d.ok) throw new Error(`refused before draft: ${d.reason}`);
+  expect(d.execution.state).toBe("approved");
+  next = answer;
+  return d.execution.id;
+}
+
+describe("ApiMandateStatusSource reads GET /v1/mandates/{id} with the test key", () => {
+  it("answers the status the API gives, on the one registered spelling of the route", async () => {
+    const report = await apiSource().check(MANDATE_ID);
+    expect(report).toMatchObject({ mandate_id: MANDATE_ID, status: "active", org_paused: false, source: "api" });
+    expect(requests).toEqual([{ method: "GET", url: `/v1/mandates/${MANDATE_ID}`, bearerIsTestKey: true }]);
+  });
+
+  it("an active mandate past its expires_at is expired, whatever the status field says", async () => {
+    next = { status: 200, body: mandateBody({ expires_at: "2026-09-23T17:59:59.000Z" }) };
+    expect((await apiSource().check(MANDATE_ID)).status).toBe("expired");
+  });
+
+  it("never throws: 404, 500, a hung connection, a body without a readable status and a status outside the four are all `unknown`, with a reason", async () => {
+    next = { status: 404, body: { error: { code: "mandate_not_found", message: "no such mandate" }, request_id: null } };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("no mandate") });
+    next = { status: 500, body: { error: { code: "internal", message: "boom" } } };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("did not answer") });
+    next = { status: 200, body: "not json at all" };
+    expect((await apiSource().check(MANDATE_ID)).status).toBe("unknown");
+    next = { status: 200, body: mandateBody({ status: "frozen" }) };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("frozen") });
+    next = { status: 200, hang: true };
+    expect(await apiSource(150).check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("timeout") });
+  });
+});
+
+describe("section 4.7 through the engine, on the API source: executing only on active", () => {
+  it("active: the approved execution reaches executing and settles on the rail", async () => {
+    const h = apiHarness();
+    const id = await approvedThen(h, { status: 200, body: mandateBody() });
+    const out = await h.engine.execute(id);
+    expect(out.state).toBe("settled");
+    expect(h.rail.payCount).toBe(1);
+  });
+
+  const refusals: Array<[string, Answer, string, string]> = [
+    ["paused", { status: 200, body: mandateBody({ status: "paused" }) }, "denied", "mandate_paused"],
+    ["revoked", { status: 200, body: mandateBody({ status: "revoked" }) }, "denied", "mandate_revoked"],
+    ["expired", { status: 200, body: mandateBody({ status: "expired" }) }, "expired", "mandate_expired"],
+    ["500", { status: 500, body: { error: { code: "internal", message: "boom" } } }, "denied", "mandate_status_unavailable"],
+    ["404", { status: 404, body: { error: { code: "mandate_not_found", message: "gone" } } }, "denied", "mandate_status_unavailable"],
+    ["timeout", { status: 200, hang: true }, "denied", "mandate_status_unavailable"],
+  ];
+  for (const [name, answer, state, reason] of refusals) {
+    it(`${name} after approval: ${state} (${reason}), no outbox row, rail.pay never called`, async () => {
+      const h = apiHarness(name === "timeout" ? apiSource(150) : apiSource());
+      const id = await approvedThen(h, answer);
+      const out = await h.engine.execute(id);
+      expect(out.state).toBe(state);
+      expect(out.reason).toBe(reason);
+      expect(out.detail).toContain(MANDATE_ID);
+      expect(h.store.listOutbox()).toHaveLength(0);
+      expect(h.rail.payCount).toBe(0);
+      // A new request under the same answer is refused before anything is drafted.
+      expect(await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] })).toMatchObject({ ok: false, refused_before_draft: true, reason });
+      expect(h.store.listExecutions()).toHaveLength(1);
+    });
+  }
+
+  it("a source that throws is fail-closed too: mandate_status_unavailable, rail.pay never called", async () => {
+    const h = apiHarness({ check: async () => { throw new Error("socket hang up"); } });
+    expect(await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] })).toMatchObject({ ok: false, reason: "mandate_status_unavailable" });
+    expect(h.rail.payCount).toBe(0);
+  });
+
+});
+
+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/checkout-agent/packages/agent-core/test/manifest.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { parseManifest } from "../src/manifest.js";
+
+const valid = `
+schema: 1
+name: bills-agent
+version: 0.1.0
+approval: [human, mandate]
+default_approval: human
+escalate_above:
+  amount: 150000
+  new_beneficiary: true
+  outside_hours: "22:00-07:00"
+mcp: "@codespar/mcp@0.5.8"
+cli: "@codespar/cli@0.14.0"
+tools: ./tools.json
+guardrails: ./guardrails.json
+mandate_schema: ./mandate.example.json
+events: [commerce.payment.succeeded, commerce.payment.failed]
+channels: [terminal]
+maturity:
+  pix-out: sandbox
+  embedded-consent: sandbox
+  receipt-verification: blocked
+scenarios: ./scenarios/
+evals: ./evals/
+agents_md: ./AGENTS.md
+`;
+
+describe("section 4.3: agent.yaml schema 1", () => {
+  it("parses the example", () => {
+    const m = parseManifest(valid);
+    expect(m.name).toBe("bills-agent");
+    expect(m.escalate_above?.amount).toBe(150000);
+  });
+
+  it("refuses an unpinned mcp or cli, a wrong schema, and an unknown field", () => {
+    expect(() => parseManifest(valid.replace('"@codespar/mcp@0.5.8"', '"@codespar/mcp"'))).toThrow(/mcp/);
+    expect(() => parseManifest(valid.replace('"@codespar/cli@0.14.0"', '"@codespar/cli@latest"'))).toThrow(/cli/);
+    expect(() => parseManifest(valid.replace("schema: 1", "schema: 2"))).toThrow();
+    expect(() => parseManifest(valid + "telemetry: true\n")).toThrow(/unrecognized/i);
+    expect(() => parseManifest(valid.replace("default_approval: human", "default_approval: mandate").replace("approval: [human, mandate]", "approval: [human]"))).toThrow(/default_approval/);
+    expect(() => parseManifest(valid.replace('outside_hours: "22:00-07:00"', 'outside_hours: "10pm-7am"'))).toThrow(/HH:MM/);
+  });
+});

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