@codespar/cli 0.17.0 → 0.18.1

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

package/templates/collections-agent/packages/agent-core/test/receipt-chain.test.ts

@@ -0,0 +1,220 @@
+/**
+ * The chain recomputed from a receipt read (ent#1670): the RFC 8785
+ * canonicalization, the published recipe as data, and the digest.
+ *
+ * Nothing here is checked against the module agreeing with itself. The
+ * canonicalization is held to the RFC's own examples; the recipe is the one
+ * production served on 2026-09-26 (`fixtures/production-receipt-keys.json`,
+ * fetched from `https://api.codespar.dev/.well-known/codespar-receipt-keys.json`;
+ * staging served the same recipe that day); and the chains are either a
+ * literal the enterprise computed with its own code before ent#1670 existed,
+ * or the digest of a link list written out by hand, field by field, the way
+ * the enterprise's own seal test writes it. The published recipe carries no
+ * worked example of its own, so those two are the external vectors.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { canonicalize, isMaskedPayee, readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type ChainRecipe } from "../src/receipt-chain.js";
+
+const PUBLISHED = JSON.parse(readFileSync(join(import.meta.dirname, "fixtures", "production-receipt-keys.json"), "utf8")) as Record<string, unknown>;
+
+function recipe(document: unknown = PUBLISHED): ChainRecipe {
+  const read = readChainRecipe(document);
+  if (!read.ok) throw new Error(read.message);
+  return read.recipe;
+}
+
+const sha256 = (s: string) => createHash("sha256").update(s, "utf8").digest("hex");
+const ITEMS = `sha256:${"1".repeat(64)}`;
+const BATCH = `sha256:${"2".repeat(64)}`;
+const MANDATE_SIG = "a".repeat(64);
+
+/** A v4 read, shaped as `GET /v1/consumers/receipts/{id}` answers it: fields the recipe does not name are there too, and must be ignored. */
+function v4Read(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    receipt_id: "rcpt_V1StGXR8Z5jdHi6BmyT0sw",
+    state: "paid",
+    chain_version: 4,
+    mandate: { id: "cm_gWEZO68q", nonce: "nonce-123456789", scope: "food", currency: "BRL", sig: MANDATE_SIG, sig_sha256: sha256(MANDATE_SIG) },
+    quote: { seller: "Sushi Yassu", resource: "Combinado 20 pc", price_minor: 9980, payee: "yassu@pix.com.br", session_id: "chk_abc123", sig: "q".repeat(64), at: "2026-06-25T12:00:00.000Z" },
+    approval: { items_hash: ITEMS, batch_hash: BATCH },
+    payment: {
+      rail: "pix",
+      provider: "celcoin",
+      tx_id: "E1393589202606251200",
+      amount_minor: 9980,
+      amount_atomic: null,
+      amount_authorized: null,
+      amount_charged: null,
+      amount_refunded: null,
+      metering: null,
+      attempt_id: "cmexec_nonce-123456789",
+      money_moved: true,
+      at: "2026-06-25T12:00:05.000Z",
+    },
+    delivery: null,
+    chain: "0".repeat(64),
+    receipt_sig: "hmac-not-read-here",
+    exceptions: [],
+    ...over,
+  };
+}
+
+describe("RFC 8785", () => {
+  it("serializes the RFC's own example (section 3.2.4) byte for byte", () => {
+    // The input as JSON text, so the numbers go through a parser exactly as the RFC's do.
+    const input = JSON.parse(
+      '{"numbers": [333333333.33333329, 1E30, 4.50, 2e-3, 0.000000000000000000000000001], "string": "\\u20ac$\\u000F\\u000aA\'\\u0042\\u0022\\u005c\\\\\\"\\/", "literals": [null, true, false]}',
+    ) as unknown;
+    expect(canonicalize(input)).toBe('{"literals":[null,true,false],"numbers":[333333333.3333333,1e+30,4.5,0.002,1e-27],"string":"€$\\u000f\\nA\'B\\"\\\\\\\\\\"/"}');
+  });
+
+  it("sorts members by UTF-16 code units, the RFC's sorting example (section 3.2.3)", () => {
+    const input = JSON.parse('{"\\u20ac": "Euro Sign", "\\r": "Carriage Return", "\\ufb33": "Hebrew Letter Dalet With Dagesh", "1": "One", "\\ud83d\\ude00": "Emoji: Grinning Face", "\\u0080": "Control", "\\u00f6": "Latin Small Letter O With Diaeresis"}') as Record<string, string>;
+    const order = [...canonicalize(input).matchAll(/"([^"]+)":"([^"]+)"/g)].map((m) => m[2]);
+    expect(order).toEqual(["Carriage Return", "One", "Control", "Latin Small Letter O With Diaeresis", "Euro Sign", "Emoji: Grinning Face", "Hebrew Letter Dalet With Dagesh"]);
+  });
+
+  it("serializes numbers as the RFC's Appendix B lists them", () => {
+    const cases: Array<[string, string]> = [
+      ["0000000000000000", "0"],
+      ["8000000000000000", "0"],
+      ["0000000000000001", "5e-324"],
+      ["7fefffffffffffff", "1.7976931348623157e+308"],
+      ["4340000000000000", "9007199254740992"],
+      ["4430000000000000", "295147905179352830000"],
+      ["44b52d02c7e14af6", "1e+23"],
+      ["444b1ae4d6e2ef50", "1e+21"],
+      ["3eb0c6f7a0b5ed8d", "0.000001"],
+      ["41b3de4355555555", "333333333.3333333"],
+      ["becbf647612f3696", "-0.0000033333333333333333"],
+      ["43143ff3c1cb0959", "1424953923781206.2"],
+    ];
+    for (const [ieee, text] of cases) expect(canonicalize(Buffer.from(ieee, "hex").readDoubleBE(0))).toBe(text);
+  });
+
+  it("refuses what is not I-JSON rather than hashing something nobody can reproduce", () => {
+    expect(() => canonicalize(Number.NaN)).toThrow(/not a JSON number/);
+    expect(() => canonicalize(Number.POSITIVE_INFINITY)).toThrow(/not a JSON number/);
+    expect(() => canonicalize("\ud800")).toThrow(/lone surrogate/);
+    expect(() => canonicalize({ ["\udc00"]: 1 })).toThrow(/lone surrogate/);
+    expect(() => canonicalize(undefined)).toThrow(/not a JSON value/);
+    expect(() => canonicalize({ a: undefined })).toThrow(/not a JSON value/);
+    expect(canonicalize("😀")).toBe('"😀"');
+  });
+});
+
+describe("the published recipe is read as data", () => {
+  it("reads the document production serves", () => {
+    const r = recipe();
+    expect(r.canonicalization).toBe("RFC 8785 (JCS)");
+    expect(r.links.map((l) => l.link)).toEqual(["mandate", "quote", "approval", "payment", "delivery"]);
+    expect(r.links[0]!.fields_by_version?.["4"]).toContain("sig_sha256");
+  });
+
+  it("names a document with no recipe for what it is: a deployment older than ent#1670", () => {
+    const { chain_recipe: _r, ...older } = PUBLISHED;
+    expect(readChainRecipe(older)).toMatchObject({ ok: false, reason: "recipe_unpublished" });
+  });
+
+  it("refuses a recipe it would only half follow", () => {
+    const base = PUBLISHED["chain_recipe"] as Record<string, unknown>;
+    expect(readChainRecipe({ chain_recipe: { ...base, canonicalization: "sorted keys" } })).toMatchObject({ ok: false, reason: "recipe_unrecognized" });
+    expect(readChainRecipe({ chain_recipe: { ...base, digest: "SHA-512" } })).toMatchObject({ ok: false, reason: "recipe_unrecognized" });
+    expect(readChainRecipe({ chain_recipe: { ...base, links: [] } })).toMatchObject({ ok: false, reason: "recipe_unrecognized" });
+  });
+});
+
+describe("the chain, recomputed from the read", () => {
+  it("reproduces a chain the enterprise's own code computed before ent#1670 (v2, pinned in its receipt-approval-seal test)", () => {
+    const read = {
+      chain_version: 2,
+      mandate: { id: "cm_gWEZO68q", nonce: "nonce-123456789", scope: "food", currency: "BRL", sig: MANDATE_SIG },
+      quote: null,
+      payment: { rail: "usdc-onchain", provider: "cdp", tx_id: "0xabc", amount_minor: 1, amount_atomic: "10000", amount_authorized: null, amount_charged: null, amount_refunded: null, metering: null, sandbox: true, attempt_id: "cmexec_nonce-123456789", money_moved: true, at: "2026-06-25T12:00:05.000Z" },
+      delivery: null,
+    };
+    expect(recomputeChain(read, recipe())).toEqual({ ok: true, version: 2, chain: "3519728810c899d3b85de0edd0dad1f9991c1bf659ce98597d099b09400df26b" });
+  });
+
+  it("v4 is the digest of {v:4, links:[mandate, quote, approval, payment]} with sig_sha256 in place of the signature", () => {
+    const read = v4Read();
+    const byHand = sha256(
+      canonicalize({
+        v: 4,
+        links: [
+          { id: "cm_gWEZO68q", nonce: "nonce-123456789", scope: "food", currency: "BRL", sig_sha256: sha256(MANDATE_SIG) },
+          { seller: "Sushi Yassu", resource: "Combinado 20 pc", price_minor: 9980, payee: "yassu@pix.com.br", session_id: "chk_abc123", sig: "q".repeat(64), at: "2026-06-25T12:00:00.000Z" },
+          { items_hash: ITEMS, batch_hash: BATCH },
+          { rail: "pix", provider: "celcoin", tx_id: "E1393589202606251200", amount_minor: 9980, attempt_id: "cmexec_nonce-123456789", money_moved: true, at: "2026-06-25T12:00:05.000Z" },
+        ],
+      }),
+    );
+    expect(recomputeChain(read, recipe())).toEqual({ ok: true, version: 4, chain: byHand });
+  });
+
+  it("a v4 read recomputes without the mandate's signature, which a third party must never be handed", () => {
+    const read = v4Read();
+    const { sig: _sig, ...mandate } = read["mandate"] as Record<string, unknown>;
+    expect(recomputeChain({ ...read, mandate }, recipe())).toEqual(recomputeChain(read, recipe()));
+  });
+
+  it("every field it seals changes it: payee, amount, approval, batch, a timestamp", () => {
+    const original = recomputeChain(v4Read(), recipe());
+    const q = v4Read()["quote"] as Record<string, unknown>;
+    const p = v4Read()["payment"] as Record<string, unknown>;
+    for (const altered of [
+      v4Read({ quote: { ...q, payee: "outra@pix.com.br" } }),
+      v4Read({ payment: { ...p, amount_minor: 9981 } }),
+      v4Read({ approval: { items_hash: `sha256:${"3".repeat(64)}`, batch_hash: BATCH } }),
+      v4Read({ approval: { items_hash: ITEMS, batch_hash: null } }),
+      v4Read({ payment: { ...p, at: "2026-06-25T12:00:05Z" } }),
+    ]) {
+      const r = recomputeChain(altered, recipe());
+      expect(r.ok).toBe(true);
+      expect(r.ok && original.ok && r.chain !== original.chain).toBe(true);
+    }
+  });
+
+  it("follows the order the document publishes, not one of its own", () => {
+    const base = PUBLISHED["chain_recipe"] as { links: unknown[] };
+    const [mandate, quote, approval, payment, delivery] = base.links;
+    const reordered = recipe({ chain_recipe: { ...base, links: [mandate, approval, quote, payment, delivery] } });
+    const a = recomputeChain(v4Read(), recipe());
+    const b = recomputeChain(v4Read(), reordered);
+    expect(a.ok && b.ok && a.chain !== b.chain).toBe(true);
+  });
+
+  it("answers why it cannot, and never guesses", () => {
+    const { sig: _sig, ...v2Mandate } = v4Read()["mandate"] as Record<string, unknown>;
+    expect(recomputeChain(v4Read({ chain_version: 2, approval: undefined, mandate: v2Mandate }), recipe())).toMatchObject({ ok: false, reason: "mandate_sig_required", version: 2 });
+    expect(recomputeChain(v4Read({ quote: { ...(v4Read()["quote"] as object), payee: "yu***@pix.com.br" } }), recipe())).toMatchObject({ ok: false, reason: "payee_masked" });
+    expect(recomputeChain(v4Read({ chain_version: undefined }), recipe())).toMatchObject({ ok: false, reason: "chain_version_missing" });
+    expect(recomputeChain(v4Read({ approval: null }), recipe())).toMatchObject({ ok: false, reason: "field_missing" });
+    const base = PUBLISHED["chain_recipe"] as { links: Array<Record<string, unknown>> };
+    const strange = recipe({ chain_recipe: { ...base, links: base.links.map((l) => (l["link"] === "delivery" ? { ...l, when: "the moon is full" } : l)) } });
+    expect(recomputeChain(v4Read(), strange)).toMatchObject({ ok: false, reason: "recipe_unrecognized" });
+  });
+});
+
+describe("the approval link", () => {
+  it("is read off the receipt, batch_hash null when the spend sent none", () => {
+    expect(readSealedApproval(v4Read())).toEqual({ items_hash: ITEMS, batch_hash: BATCH });
+    expect(readSealedApproval(v4Read({ approval: { items_hash: ITEMS, batch_hash: null } }))).toEqual({ items_hash: ITEMS, batch_hash: null });
+    expect(readSealedApproval(v4Read({ approval: undefined }))).toBeNull();
+  });
+
+  it("compares the two spellings of one hash as one hash, and nothing else as equal", () => {
+    expect(sameApprovalHash(ITEMS, "1".repeat(64))).toBe(true);
+    expect(sameApprovalHash(null, null)).toBe(true);
+    expect(sameApprovalHash(ITEMS, BATCH)).toBe(false);
+    expect(sameApprovalHash(null, BATCH)).toBe(false);
+  });
+
+  it("knows a masked payee when it sees one", () => {
+    expect(isMaskedPayee("es***@exemplo.com.br")).toBe(true);
+    expect(isMaskedPayee("escola@exemplo.com.br")).toBe(false);
+  });
+});