@codespar/cli 0.14.1 → 0.17.0

package/templates/collections-agent/packages/agent-core/test/clock.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { FIXED_CLOCK_ENV, InvalidFixedClockError, fixedClock, resolveFixedClock } from "../src/clock.js";
+
+describe("fixedClock", () => {
+  it("starts at the instant and ticks one second per read, so no two events share a timestamp", () => {
+    const clock = fixedClock("2026-09-23T14:00:00-03:00");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:00.000Z");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:01.000Z");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:02.000Z");
+  });
+
+  it("refuses what Date cannot parse, and a bare date, naming the source", () => {
+    expect(() => fixedClock("yesterday")).toThrow(InvalidFixedClockError);
+    expect(() => fixedClock("2026-09-23", FIXED_CLOCK_ENV)).toThrow(/CODESPAR_AGENT_NOW must be an ISO 8601 instant/);
+  });
+});
+
+describe("resolveFixedClock", () => {
+  it("prefers the flag, falls back to the environment, and is undefined (the wall clock) without either", () => {
+    expect(resolveFixedClock(undefined, {})).toBeUndefined();
+    expect(resolveFixedClock(undefined, { [FIXED_CLOCK_ENV]: "   " })).toBeUndefined();
+    expect(resolveFixedClock(undefined, { [FIXED_CLOCK_ENV]: "2026-09-23T20:08:00-03:00" })!().toISOString()).toBe("2026-09-23T23:08:00.000Z");
+    expect(resolveFixedClock("2026-09-23T14:00:00-03:00", { [FIXED_CLOCK_ENV]: "2026-09-23T20:08:00-03:00" })!().toISOString()).toBe("2026-09-23T17:00:00.000Z");
+  });
+});

package/templates/collections-agent/packages/agent-core/test/engine.test.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { ESCOLA, harness, MERCADO } from "./helpers.js";
+import { ESCOLA, FUNCIONARIA, harness, MERCADO } from "./helpers.js";
 
 const approver = { id: "usr_demo", channel: "terminal" };
 
@@ -521,4 +521,76 @@ describe("multi-item partial failure is named item by item", () => {
     expect(h.store.getOutbox(out.idempotency_key)?.status).toBe("failed");
     expect(h.store.getOutbox(out.idempotency_key)?.response).toEqual(out.outcomes);
   });
+
+  it("a refusal in the MIDDLE does not stop the items after it: every attempt is sent and every one is named", async () => {
+    const h = harness({ mode: "human", rail: { refusePayees: [MERCADO] } });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }, { payee: "mercado", amount: 2000 }, { payee: "funcionaria", amount: 3000 }] });
+    if (!d.ok) throw new Error("refused");
+    const out = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    // Section 4.1: the execution closes `failed` because one attempt failed,
+    // and `outcomes` names EVERY item — including the one after the refusal.
+    expect(out.state).toBe("failed");
+    expect(out.outcomes.map((o) => o.status)).toEqual(["settled", "failed", "settled"]);
+    expect(h.rail.payCount).toBe(3); // all three reached the rail; the stub records a refusal too
+    expect(readdirSync(join(h.bundle.dir, "receipts"))).toHaveLength(2);
+  });
+
+  it("an unknown answer in the MIDDLE still sends the siblings, and the execution stays open until it is resolved", async () => {
+    const h = harness({ mode: "human", rail: { uncertainPayees: [MERCADO] } });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }, { payee: "mercado", amount: 2000 }, { payee: "funcionaria", amount: 3000 }] });
+    if (!d.ok) throw new Error("refused");
+    const out = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    // Open, not closed: one attempt has no outcome at all, and §4.1 says an
+    // execution closes only when every attempt has one.
+    expect(out.state).toBe("executing");
+    expect(out.reason).toBe("rail_uncertain");
+    expect(out.outcomes.map((o) => o.index)).toEqual([0, 2]);
+    expect(out.detail).toContain("psp_dispatch_uncertain");
+    // Reconciliation resolves the unknown one and only then does it close.
+    // The stub answers `in_flight` on the first look and finds the provider
+    // finished on the second, which is the shape a real timeout has.
+    expect((await h.engine.reconcile(d.execution.id)).state).toBe("executing");
+    const closed = await h.engine.reconcile(d.execution.id);
+    expect(closed.state).toBe("settled");
+    expect(closed.outcomes.map((o) => o.status)).toEqual(["settled", "settled", "settled"]);
+  });
+
+  it("an execution with a failed attempt AND an unknown one does not close as failed", async () => {
+    const h = harness({ mode: "human", rail: { refusePayees: [ESCOLA], uncertainPayees: [MERCADO] } });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }, { payee: "mercado", amount: 2000 }, { payee: "funcionaria", amount: 3000 }] });
+    if (!d.ok) throw new Error("refused");
+    const out = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    // "One of them failed and one of them we cannot see" is not a closed
+    // outcome: reporting `failed` here would call a batch finished while a
+    // payment may still be in flight.
+    expect(out.state).toBe("executing");
+    expect(out.outcomes.map((o) => o.status)).toEqual(["failed", "settled"]);
+    expect((await h.engine.reconcile(d.execution.id)).state).toBe("executing");
+    const closed = await h.engine.reconcile(d.execution.id);
+    expect(closed.state).toBe("failed");
+    expect(closed.outcomes.map((o) => o.status)).toEqual(["failed", "settled", "settled"]);
+  });
+
+  it("why the siblings are sent and not deferred: an attempt that was never sent is recovered by nothing", async () => {
+    // This is the measurement the choice rests on. `reconcile` is read-only by
+    // contract and never dispatches; `resumePending` dispatches only while the
+    // outbox row is still `pending`, and it flips to `sent` before the first
+    // rail call. So an attempt skipped at dispatch is not sent later — it is
+    // never sent, by any path the runtime has.
+    const h = harness({ mode: "human", rail: { uncertainPayees: [MERCADO] } });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }, { payee: "mercado", amount: 2000 }, { payee: "funcionaria", amount: 3000 }] });
+    if (!d.ok) throw new Error("refused");
+    const out = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    const third = `att_${out.idempotency_key.slice(4)}_2`;
+    // Under the fix the third attempt WAS sent, so the rail knows it.
+    expect(h.store.stubRailGet(third)).toBeDefined();
+    expect(h.store.getOutbox(out.idempotency_key)?.status).toBe("sent");
+    // And that is the only reason it is recoverable: `resumePending` on a
+    // `sent` row reconciles instead of dispatching, and never pays again.
+    const before = h.rail.payCount;
+    expect((await h.engine.resumePending(d.execution.id)).state).toBe("executing");
+    const resumed = await h.engine.resumePending(d.execution.id);
+    expect(h.rail.payCount).toBe(before); // reconciled, never re-sent
+    expect(resumed.state).toBe("settled");
+  });
 });

package/templates/collections-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/collections-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/collections-agent/packages/agent-core/test/helpers.ts

@@ -26,7 +26,7 @@ export function testManifest(over: Partial<Manifest> = {}): Manifest {
     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.13.0",
+    cli: "@codespar/cli@0.14.0",
     tools: "./tools.json",
     guardrails: "./guardrails.json",
     mandate_schema: "./mandate.example.json",

package/templates/collections-agent/packages/agent-core/test/manifest.test.ts

@@ -12,7 +12,7 @@ escalate_above:
   new_beneficiary: true
   outside_hours: "22:00-07:00"
 mcp: "@codespar/mcp@0.5.8"
-cli: "@codespar/cli@0.13.0"
+cli: "@codespar/cli@0.14.0"
 tools: ./tools.json
 guardrails: ./guardrails.json
 mandate_schema: ./mandate.example.json
@@ -36,7 +36,7 @@ describe("section 4.3: agent.yaml schema 1", () => {
 
   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.13.0"', '"@codespar/cli@latest"'))).toThrow(/cli/);
+    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/);

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

@@ -0,0 +1,316 @@
+/**
+ * The wave-5 contract: a party with the receipt JSON and the published key set
+ * reaches the right answer, and the wrong answers stay apart from each other.
+ *
+ * The signatures here are made with stock `node:crypto` and a key generated in
+ * the test, never with the module under test: a test that signed with the
+ * verifier's own helper would prove the helper agrees with itself. The signed
+ * string is written out literally for the same reason — if the enterprise ever
+ * changes the shape, this line fails rather than following it.
+ *
+ * No network: the key set is a document, or a fetcher the test supplies.
+ */
+import { createPublicKey, generateKeyPairSync, sign as signDetached, verify as nodeVerify, type KeyObject } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_RECEIPT_KEYS_URL,
+  RECEIPT_SIGNATURE_DOMAIN,
+  VERDICT_EXIT_CODES,
+  receiptKeysUrl,
+  receiptSigningString,
+  verifyReceipt,
+  verifyReceiptWithKeys,
+  type PublishedReceiptKey,
+} from "../src/receipt-verification.js";
+
+const KID = "did:web:id.codespar.dev#1";
+const CHAIN = "9f2c4a1b6d0e8f3a5c7b9d1e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f01";
+const RECEIPT_ID = "rcpt_V1StGXR8Z5jdHi6BmyT0sw";
+
+function keypair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32);
+  return { privateKey, x: Buffer.from(raw).toString("base64url") };
+}
+
+function publishedKey(x: string, over: Partial<PublishedReceiptKey> = {}): PublishedReceiptKey {
+  return { kid: KID, kty: "OKP", crv: "Ed25519", x, alg: "EdDSA", use: "sig", status: "active", ...over };
+}
+
+function keySet(...keys: PublishedReceiptKey[]) {
+  return { issuer: "did:web:id.codespar.dev", algorithm: "Ed25519", signing_string: `${RECEIPT_SIGNATURE_DOMAIN}:<receipt_id>:<chain>`, keys };
+}
+
+function seal(privateKey: KeyObject, receiptId = RECEIPT_ID, chain = CHAIN): string {
+  return signDetached(null, Buffer.from(`codespar-receipt:v1:${receiptId}:${chain}`, "utf8"), privateKey).toString("base64url");
+}
+
+function receipt(over: Record<string, unknown> = {}) {
+  return {
+    receipt_id: RECEIPT_ID,
+    state: "paid",
+    mandate: { id: "mnd_1" },
+    payment: { amount_minor: 12345, payee: "es***@exemplo.com.br", attempt_id: "att_1", money_moved: false, sandbox: true, at: "2026-09-24T12:00:00.000Z" },
+    chain: CHAIN,
+    receipt_sig: "hmac-half-not-read-here",
+    receipt_sig_ed25519: null,
+    receipt_sig_kid: null,
+    ...over,
+  };
+}
+
+describe("the signed string", () => {
+  it("is the enterprise's, byte for byte", () => {
+    expect(receiptSigningString(RECEIPT_ID, CHAIN)).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
+    expect(RECEIPT_SIGNATURE_DOMAIN).toBe("codespar-receipt:v1");
+  });
+
+  it("names the key set of a deployment from its base url", () => {
+    expect(receiptKeysUrl("https://api.codespar.dev")).toBe(DEFAULT_RECEIPT_KEYS_URL);
+    expect(receiptKeysUrl("https://staging.example/v1/anything")).toBe("https://staging.example/.well-known/codespar-receipt-keys.json");
+  });
+});
+
+describe("verified", () => {
+  it("accepts a receipt CodeSpar sealed, and says which key signed it", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("verified");
+    expect(report.receipt_id).toBe(RECEIPT_ID);
+    expect(report.kid).toBe(KID);
+    expect(report.key_status).toBe("active");
+    expect(report.signing_string).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
+  });
+
+  it("accepts a signature made by a RETIRED key: rotation retires, it does not revoke", () => {
+    const { privateKey, x } = keypair();
+    const retired = publishedKey(x, { status: "retired", retired_at: "2026-09-01T00:00:00.000Z" });
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(retired, publishedKey("ignored", { kid: "did:web:id.codespar.dev#2" })));
+    expect(report.verdict).toBe("verified");
+    expect(report.key_status).toBe("retired");
+  });
+
+  it("still verifies the proof bundle's masked copy: the signature covers the id and the chain, not the body", () => {
+    const { privateKey, x } = keypair();
+    const sealed = receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID });
+    const masked = { ...sealed, payment: { ...sealed.payment, payee: "es***@exemplo.com.br" }, raw: undefined };
+    expect(verifyReceiptWithKeys(masked, keySet(publishedKey(x))).verdict).toBe("verified");
+  });
+});
+
+describe("tampered", () => {
+  it("refuses a receipt whose chain was changed after it was sealed", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID, chain: CHAIN.replace(/^9/, "8") }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.reason).toBe("signature_does_not_match");
+  });
+
+  it("refuses a signature lifted from another receipt: the id is in the signed string", () => {
+    const { privateKey, x } = keypair();
+    const other = seal(privateKey, "rcpt_somebodyelsesreceipt", CHAIN);
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: other, receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+  });
+
+  it("refuses a signature made by a key that is not the published one, and names the deployment case", () => {
+    const { privateKey } = keypair();
+    const other = keypair();
+    // The shape of the staging-receipt-against-production-keys mistake: both
+    // deployments publish a key called `did:web:id.codespar.dev#1` and the two
+    // are not the same key, so the message has to offer that reading.
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey(other.x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.message).toContain("deployment");
+  });
+
+  it("refuses a signature that is not 64 base64url bytes", () => {
+    const { x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: "not-a-signature", receipt_sig_kid: KID }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("tampered");
+    expect(report.reason).toBe("signature_malformed");
+  });
+});
+
+describe("unsigned", () => {
+  it("is not a failure: it says the receipt predates the capability, and that the HMAC is unaffected", () => {
+    const report = verifyReceiptWithKeys(receipt(), keySet());
+    expect(report.verdict).toBe("unsigned");
+    expect(report.message).toContain("never will");
+    expect(report.message).toContain("HMAC");
+    expect(report.kid).toBeNull();
+  });
+
+  it("answers the same when the two fields are absent rather than null", () => {
+    const { receipt_sig_ed25519: _sig, receipt_sig_kid: _kid, ...older } = receipt();
+    expect(verifyReceiptWithKeys(older, keySet()).verdict).toBe("unsigned");
+  });
+
+  it("answers without a key set at all, and without fetching one", async () => {
+    let fetched = 0;
+    const report = await verifyReceipt(receipt(), {
+      url: "https://example.invalid/keys.json",
+      fetch: async () => {
+        fetched += 1;
+        return keySet();
+      },
+    });
+    expect(report.verdict).toBe("unsigned");
+    expect(fetched).toBe(0);
+  });
+
+  it("covers a paid charge, which the API seals nothing for", () => {
+    const charge = { receipt_id: "chg_1", kind: "charge", state: "paid", chain: null, receipt_sig: null, receipt_sig_ed25519: null, receipt_sig_kid: null };
+    expect(verifyReceiptWithKeys(charge, keySet()).verdict).toBe("unsigned");
+  });
+});
+
+describe("unknown_key", () => {
+  it("refuses to guess when the kid is not published", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: "did:web:id.codespar.dev#9" }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("unknown_key");
+    expect(report.kid).toBe("did:web:id.codespar.dev#9");
+    expect(report.message).toContain("retired keys published");
+  });
+
+  it("does not fall back to the only key in the set", () => {
+    const { privateKey, x } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: "did:web:other.example#1" }), keySet(publishedKey(x)));
+    expect(report.verdict).toBe("unknown_key");
+  });
+});
+
+describe("unreachable", () => {
+  it("is what a failed fetch answers — never `tampered`", async () => {
+    const { privateKey } = keypair();
+    const report = await verifyReceipt(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), {
+      url: "https://example.invalid/keys.json",
+      fetch: async () => {
+        throw new Error("getaddrinfo ENOTFOUND example.invalid");
+      },
+    });
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("fetch_failed");
+    expect(report.message).toContain("Nothing is proved and nothing is disproved");
+  });
+
+  it("is what a document that is not a key set answers", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), { error: "not found" });
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("key_document_unreadable");
+  });
+
+  it("is what an unusable published key answers: a key we cannot read tells us nothing about the signature", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), keySet(publishedKey("AAAA")));
+    expect(report.verdict).toBe("unreachable");
+    expect(report.reason).toBe("key_unusable");
+  });
+
+  it("fetches the published set and verifies against it when the fetch works", async () => {
+    const { privateKey, x } = keypair();
+    const seen: string[] = [];
+    const report = await verifyReceipt(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID }), {
+      fetch: async (url) => {
+        seen.push(url);
+        return keySet(publishedKey(x));
+      },
+    });
+    expect(seen).toEqual([DEFAULT_RECEIPT_KEYS_URL]);
+    expect(report.verdict).toBe("verified");
+  });
+});
+
+describe("malformed", () => {
+  it("does not call an arbitrary JSON file an unsigned receipt", () => {
+    const report = verifyReceiptWithKeys({ hello: "world" }, keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("receipt_id_missing");
+  });
+
+  it("refuses a signature whose kid was deleted, instead of reading it as unsigned", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: null }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("kid_missing");
+  });
+
+  it("refuses a kid whose signature was deleted", () => {
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_kid: KID }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("signature_missing");
+  });
+
+  it("refuses a signed receipt whose chain was deleted: the signed string cannot be rebuilt", () => {
+    const { privateKey } = keypair();
+    const report = verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: seal(privateKey), receipt_sig_kid: KID, chain: null }), keySet());
+    expect(report.verdict).toBe("malformed");
+    expect(report.reason).toBe("chain_missing");
+  });
+
+  it("refuses a JSON array or a string", () => {
+    expect(verifyReceiptWithKeys([], keySet()).verdict).toBe("malformed");
+    expect(verifyReceiptWithKeys("rcpt_1", keySet()).verdict).toBe("malformed");
+  });
+});
+
+describe("the exit codes", () => {
+  it("keep every verdict apart, and do not call an unsigned receipt a success", () => {
+    expect(VERDICT_EXIT_CODES.verified).toBe(0);
+    expect(new Set(Object.values(VERDICT_EXIT_CODES)).size).toBe(Object.keys(VERDICT_EXIT_CODES).length);
+    expect(Object.values(VERDICT_EXIT_CODES)).not.toContain(2); // 2 is the usage error every other command uses
+  });
+});
+
+describe("the check a third party reimplements", () => {
+  it("is four lines of node:crypto over the published JWK", () => {
+    const { privateKey, x } = keypair();
+    const signature = seal(privateKey);
+    // Exactly what someone outside CodeSpar writes, with no code of ours.
+    const ok = nodeVerify(
+      null,
+      Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`, "utf8"),
+      createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x }, format: "jwk" }),
+      Buffer.from(signature, "base64url"),
+    );
+    expect(ok).toBe(true);
+    expect(verifyReceiptWithKeys(receipt({ receipt_sig_ed25519: signature, receipt_sig_kid: KID }), keySet(publishedKey(x))).verdict).toBe("verified");
+  });
+});
+
+/**
+ * The one fixture that is not this test's own: a receipt the CodeSpar sandbox
+ * actually sealed (bills-agent, staging, 2026-09-24), as the proof bundle
+ * wrote it, and the key set that deployment publishes, as it was served. Every
+ * other case here signs with a key the test made, which proves the module is
+ * self-consistent; this one proves it agrees with the signer.
+ *
+ * Offline: both are files. If the API ever changes the signed string, this is
+ * the case that fails.
+ */
+describe("a receipt the sandbox really sealed", () => {
+  const dir = join(import.meta.dirname, "fixtures");
+  const real = JSON.parse(readFileSync(join(dir, "staging-receipt.json"), "utf8")) as Record<string, unknown>;
+  const realKeys = JSON.parse(readFileSync(join(dir, "staging-receipt-keys.json"), "utf8")) as unknown;
+
+  it("verifies against the key set that deployment publishes", () => {
+    const report = verifyReceiptWithKeys(real, realKeys, "staging");
+    expect(report.verdict).toBe("verified");
+    expect(report.kid).toBe("did:web:id.codespar.dev#1");
+    expect(report.signing_string).toBe(`codespar-receipt:v1:${real["receipt_id"] as string}:${real["chain"] as string}`);
+  });
+
+  it("is refused when one character of the chain changes", () => {
+    const chain = real["chain"] as string;
+    const edited = { ...real, chain: chain.slice(0, -1) + (chain.endsWith("0") ? "1" : "0") };
+    expect(verifyReceiptWithKeys(edited, realKeys, "staging").verdict).toBe("tampered");
+  });
+
+  it("is refused when the receipt id changes, which is why the id is in the signed string", () => {
+    expect(verifyReceiptWithKeys({ ...real, receipt_id: "rcpt_0000000000000000000000" }, realKeys, "staging").verdict).toBe("tampered");
+  });
+});

package/templates/collections-agent/packages/agent-core/test/receivables.test.ts

@@ -263,3 +263,54 @@ describe("outcomeOf: the API's charge view, mapped by fields and never by prose"
     expect(outcomeOf({ ...base, payment_in_flight: true, settlement: "pending" })).toMatchObject({ status: "accepted" });
   });
 });
+
+describe("CodeSparChargeRail: what crosses the wire on a create", () => {
+  it("sends consumer_id, method boleto, due_date, the attempt id as idempotency_key and the amount in major units; refuses without a consumer", async () => {
+    const { CodeSparChargeRail } = await import("../src/api/charge-rail.js");
+    const calls: Array<{ path: string; body: Record<string, unknown> }> = [];
+    const api = {
+      post: async (path: string, opts: { body: Record<string, unknown> }) => {
+        calls.push({ path, body: opts.body });
+        return { id: "chg_wire_1", status: "PROCESSING", local_status: "pending", status_conflict: false, method: "boleto", currency: "BRL", amount: 1080, amount_minor: 108000, due_date: "2026-09-30", payable: false, boleto_bar_code: null, boleto_bank_line: null, pix_copy_paste: null, credit_correlation_armed: false, payment_in_flight: false, settlement: null, issuance_unconfirmed: false };
+      },
+      get: async () => { throw new Error("not called"); },
+    };
+    const rail = new CodeSparChargeRail(api as never);
+    const base = { attempt_id: "att_x_0", mandate_id: "pol_1", amount_minor: 108000, currency: "BRL", payee: DEBTOR, beneficiary: "Joana Ribeiro", purpose: "cobranca", agent_id: "collections-agent", description: "Acordo #1042 - parcela 1/1", due_date: "2026-09-30", actor: { type: "agent" as const, agent: "collections-agent@0.1.0", on_behalf_of: "merchant_demo_loja" } };
+    expect(await rail.pay(base)).toMatchObject({ status: "failed", code: "consumer_id_required" });
+    expect(calls).toHaveLength(0);
+    const out = await rail.pay({ ...base, consumer_id: "merchant_demo_loja" });
+    expect(out).toMatchObject({ status: "accepted", transaction_id: "chg_wire_1", instrument: { payable: false, status: "PROCESSING" } });
+    expect(calls[0]).toEqual({ path: "/v1/charges", body: { consumer_id: "merchant_demo_loja", amount: 1080, currency: "BRL", method: "boleto", description: "Acordo #1042 - parcela 1/1", buyer: { name: "Joana Ribeiro", document: DEBTOR }, due_date: "2026-09-30", idempotency_key: "att_x_0" } });
+  });
+});
+
+describe("paySandboxCharge: the SDK's typed call to the payer route", () => {
+  it("posts to /v1/test/charges/{id}/pay with the key, the project header and the amount; refuses a live key before any request", async () => {
+    const { paySandboxCharge } = await import("../src/api/sandbox-payer.js");
+    const seen: Array<{ url: string; init: RequestInit }> = [];
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      seen.push({ url: String(url), init: init ?? {} });
+      return new Response(JSON.stringify({ charge_id: "chg_1", status: "paid", local_status: "settled", simulated: true, settled_against: "sandbox_fixture", money_moved: false, quoted_minor: 1000, paid_minor: 1000, payment: "full", idempotent_replay: false }), { status: 200, headers: { "content-type": "application/json" } });
+    }) as typeof fetch;
+    try {
+      const live = await paySandboxCharge({ apiKey: ["csk", "live", "0000000000"].join("_") }, "chg_1").catch((e: Error) => e);
+      expect(live).toBeInstanceOf(Error);
+      expect(seen).toHaveLength(0);
+      const out = await paySandboxCharge({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/", projectId: "prj_1" }, "chg_1", 1000);
+      expect(out).toMatchObject({ ok: true, state: { charge_id: "chg_1", status: "paid", simulated: true, money_moved: false } });
+      expect(seen[0]?.url).toBe("https://api.example.test/v1/test/charges/chg_1/pay");
+      const headers = new Headers(seen[0]?.init.headers);
+      expect(headers.get("authorization")).toBe("Bearer csk_test_unit_0000");
+      expect(headers.get("x-codespar-project")).toBe("prj_1");
+      expect(headers.get("content-type")).toBe("application/json");
+      expect(seen[0]?.init.body).toBe(JSON.stringify({ amount_minor: 1000 }));
+      const bare = await paySandboxCharge({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/", projectId: "prj_1" }, "chg_1");
+      expect(bare).toMatchObject({ ok: true });
+      expect(seen[1]?.init.body).toBe("{}");
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+});

package/templates/collections-agent/packages/agent-runtime/README.md

@@ -0,0 +1,68 @@
+# @codespar/agent-runtime
+
+The runner every starter-kit agent shares. It is not published: it is a
+workspace package the agents depend on, and it ships one binary,
+`codespar-agent`, so an agent's `package.json` script is the command and
+nothing else.
+
+```json
+"scripts": { "start": "codespar-agent start", "check": "codespar-agent check" }
+```
+
+## What it owns
+
+- The terminal channel: the banner, the approval question, the transitions it
+  prints, the receipt path.
+- The WhatsApp channel (`src/channels/`): one adapter over two backends that
+  are the SAME code with a different base URL — a local Cloud API emulator
+  ([`dyvit-wa-sim`](https://github.com/fabianocruz/whatsapp-simulator), MIT,
+  run at a pinned npm version by `npm run whatsapp:emulator`) and Meta's own
+  host.
+  `live` is derived from that host, which is what the consent-evidence builder
+  refuses on. The rules live in the adapter, above both — the collection
+  hours, the bound contact, the secrecy of the debt, the document rule, the
+  24-hour session window — so choosing a backend changes who carries the bytes
+  and nothing else. What an AGENT ships for this channel is the conversations
+  and its template registry, under `agents/<name>/channels/whatsapp/`.
+- `poll --channel whatsapp` comes back to a conversation the run that opened it
+  has ended: it reads the window back from the bundle's `channel.jsonl` and
+  confirms the outcome free-form while the 24 hours are open, as an approved
+  template once they have shut.
+- Every command: `start` (interactive, `--input`, `--scenario`, `--transcript`,
+  `--json`, `--approve`/`--deny`, `--now`, `--channel`, `--backend`,
+  `--conversation`, `--scripted`), `consent`, `approve`, `deny`, `resume`,
+  `rerun`, `reconcile`, `inspect` (`--json`, `--html <file>`), `poll`
+  (`--channel`, `--conversation`, `--backend`, `--wait`, `--simulate-payer`,
+  `--payer`, `--now`, `--json`), `webhook`, `check`, `eval`.
+- Setup: the manifest, the guardrails, the tools file, the system prompt, the
+  local state, the signer, the proof bundle, the provider (Anthropic with a
+  real key, replay without one), and the pinned clock (`--now`,
+  `CODESPAR_AGENT_NOW`).
+- The section 9 adversarial runner and the section 12 scenario runner.
+- The `csk_test_` guard and the `.env.example` placeholder rule.
+
+## What an agent owns
+
+Its five files (`agent.yaml`, `SYSTEM_PROMPT.md`, `tools.json`,
+`guardrails.json`, `mandate.example.json`), its `scenarios/` and `evals/`, and
+one optional module, `src/kit.ts`:
+
+```ts
+import { defineAgent, defaultKit } from "@codespar/agent-runtime";
+
+export const agent = defineAgent(import.meta.url, {
+  ...defaultKit,
+  handlers: () => ({ list_bills: listBills }),
+});
+```
+
+`AgentKit` (in `src/kit.ts`) is the whole seam: the rail adapter
+(`buildRail`), the tool handlers, the `policyExtension`, the console labels,
+what a one-shot prints as JSON, and — for an agent whose money comes IN — the
+sandbox payer and the one message per outcome. An agent that declares none of
+it gets `defaultKit`: the stub rail, the example mandate, no tools.
+
+`defineAgent(import.meta.url, kit)` finds the nearest `agent.yaml` above the
+module, which is what makes every path (`scenarios/`, `evals/`, `.codespar/`,
+`runs/`) and every test-only environment variable (`BILLS_STATE_DIR`,
+`COLLECTIONS_RUNS_DIR`) resolve per agent without the agent naming them.