@codespar/cli 0.13.0 → 0.14.0

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

@@ -0,0 +1,139 @@
+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 { 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.13.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;
+  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,
+    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/collections-agent/packages/agent-core/test/mandate-status.test.ts

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+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 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). */
+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",
+    ...over,
+  };
+}
+
+type Answer = { status: number; body?: unknown; hang?: boolean };
+
+let server: Server;
+let baseUrl: string;
+let next: Answer = { status: 200, body: mandateBody() };
+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));
+  });
+  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() };
+  requests.length = 0;
+});
+
+function apiSource(timeoutMs = 5_000): ApiMandateStatusSource {
+  // 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);
+}
+
+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);
+  });
+
+  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);
+  });
+});

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

@@ -0,0 +1,265 @@
+/**
+ * The receivable side of the core (collections-agent): a charge is ISSUED,
+ * not settled, when the rail accepts it; the execution stays `executing`
+ * until the payer acts, and closes from a lookup (the poll) or from a
+ * `commerce.charge.*` event (the webhook). Never twice, never on prose.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { outcomeOf, type ChargeView } from "../src/api/charge-rail.js";
+import { hmacSigner } from "../src/approval.js";
+import { ProofBundle } from "../src/bundle.js";
+import { ExecutionEngine, type EngineDeps, type PolicyExtension } from "../src/engine.js";
+import { itemsHash } from "../src/hash.js";
+import { StateStore } from "../src/state/store.js";
+import { LocalMandateStatusStub } from "../src/stubs/mandate-status.js";
+import { StubChargeRail, type StubChargeRailOptions } from "../src/stubs/charge-rail.js";
+import { testGuardrails, testManifest, testMandate } from "./helpers.js";
+
+const DEBTOR = "11144477735";
+const OTHER = "22233344450";
+
+function receivables(options: { mode?: "human" | "mandate"; rail?: StubChargeRailOptions; policyExtension?: PolicyExtension; dir?: string } = {}) {
+  const dir = options.dir ?? mkdtempSync(join(tmpdir(), "agent-core-recv-"));
+  let now = new Date("2026-09-23T18:00:00Z");
+  const clock = () => now;
+  const store = new StateStore(join(dir, "state.db"));
+  const gate = new LocalMandateStatusStub(store, clock);
+  const rail = new StubChargeRail(store, { clock, ...(options.rail ?? {}) });
+  const bundle = new ProofBundle(join(dir, "runs"), "run_recv");
+  const mode = options.mode ?? "mandate";
+  const deps: EngineDeps = {
+    store,
+    rail,
+    status: gate,
+    signer: hmacSigner("test", Buffer.alloc(32, 2)),
+    manifest: testManifest({ name: "collections-agent", escalate_above: {}, maturity: { "bolepix-receivables": "sandbox" } }),
+    guardrails: testGuardrails({ approval: mode, escalate_above: {} }),
+    mandate: testMandate({
+      agent_id: "collections-agent",
+      purpose: "cobranca",
+      merchant_pin_kind: "document",
+      merchant_allowlist: [DEBTOR, OTHER],
+      beneficiaries: [{ alias: "acordo-1", name: "Joana Devedora", payee: DEBTOR }],
+    }),
+    bundle,
+    mode,
+    runId: "run_recv",
+    onBehalfOf: "merchant_demo",
+    clock,
+    policyExtension: options.policyExtension,
+  };
+  const engine = new ExecutionEngine(deps);
+  return { dir, store, rail, bundle, engine, setNow: (d: Date) => (now = d) };
+}
+
+describe("a receivable is accepted, then settled by the payer", () => {
+  it("execute leaves the execution executing (awaiting_settlement) with the instrument; two looks later it is settled with the charge as receipt", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 108000, due_date: "2026-09-30", description: "acordo 1042, a vista" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("approved");
+    expect(d.execution.items[0]?.due_date).toBe("2026-09-30");
+
+    const issued = await h.engine.execute(d.execution.id);
+    expect(issued.state).toBe("executing");
+    expect(issued.reason).toBe("awaiting_settlement");
+    expect(issued.outcomes[0]).toMatchObject({ status: "accepted", instrument: { payable: false, status: "PROCESSING" } });
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("sent");
+
+    const registered = await h.engine.reconcile(issued.id);
+    expect(registered.state).toBe("executing");
+    expect(registered.outcomes[0]?.instrument).toMatchObject({ payable: true, status: "PENDING" });
+    expect(registered.outcomes[0]?.instrument?.pix_copy_paste).toContain("br.gov.bcb.pix");
+
+    const paid = await h.engine.reconcile(issued.id);
+    expect(paid.state).toBe("settled");
+    expect(paid.history.map((t) => t.to)).toEqual(["approved", "executing", "settled"]);
+    expect(paid.outcomes[0]).toMatchObject({ status: "settled", receipt_id: paid.outcomes[0]!.transaction_id });
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("done");
+    expect(h.bundle.listReceipts()).toHaveLength(1);
+    const events = h.bundle.readEvents();
+    expect(events.filter((e) => e["type"] === "commerce.charge.paid")).toHaveLength(1);
+    expect(events.filter((e) => e["type"] === "charge.instrument").map((e) => (e["payload"] as { payable: boolean }).payable)).toEqual([false, true]);
+    // A third look changes nothing and issues nothing.
+    expect((await h.engine.reconcile(issued.id)).state).toBe("settled");
+    expect(h.rail.issueCount).toBe(1);
+  });
+
+  it("a receivable nobody pays closes failed with charge_expired, never settled", async () => {
+    const h = receivables({ rail: { payer: "expires" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    await h.engine.reconcile(issued.id);
+    const closed = await h.engine.reconcile(issued.id);
+    expect(closed.state).toBe("failed");
+    expect(closed.reason).toBe("charge_expired");
+    expect(h.bundle.listReceipts()).toHaveLength(0);
+    expect(h.store.getOutbox(issued.idempotency_key)!.status).toBe("failed");
+  });
+
+  it("the poll logs an observed state once, however many times it sees it", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    for (let i = 0; i < 5; i += 1) await h.engine.reconcile(issued.id);
+    const events = h.store.listEvents({ execution_id: issued.id });
+    // Five looks, one observed state (PENDING, payable): one line. The instrument log names the two states the charge went through.
+    expect(events.filter((e) => e.type === "rail.reconcile")).toHaveLength(1);
+    expect(events.filter((e) => e.type === "charge.instrument")).toHaveLength(2);
+    expect(events.filter((e) => e.type === "execution.awaiting_settlement")).toHaveLength(1);
+  });
+
+  it("killed after the issuance and resumed: one charge, one settlement", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    let died = false;
+    const flaky = receivables({ dir: h.dir, rail: { afterDispatch: () => { died = true; throw new Error("killed"); } } });
+    await expect(flaky.engine.execute(d.execution.id)).rejects.toThrow("killed");
+    expect(died).toBe(true);
+    // The row says executing and the outbox says sent: resume reconciles, never re-issues.
+    const again = receivables({ dir: h.dir });
+    const stuck = again.store.getExecution(d.execution.id)!;
+    expect(stuck.state).toBe("executing");
+    const first = await again.engine.resumePending(stuck.id);
+    expect(first.state).toBe("executing");
+    expect(first.outcomes[0]?.status).toBe("accepted");
+    const settled = await again.engine.reconcile(stuck.id);
+    expect(settled.state).toBe("settled");
+    expect(again.rail.issueCount).toBe(0);
+    expect((again.store as unknown as { db: { prepare(sql: string): { get(): { n: number } } } }).db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get().n).toBe(1);
+  });
+
+  it("an instalment agreement is N receivables; the execution settles when every parcel is paid", async () => {
+    const h = receivables();
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 40000, due_date: "2026-09-30" }, { payee: "acordo-1", amount: 40000, due_date: "2026-10-30" }, { payee: "acordo-1", amount: 40000, due_date: "2026-11-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.total).toBe(120000);
+    const issued = await h.engine.execute(d.execution.id);
+    expect(issued.outcomes.map((o) => o.status)).toEqual(["accepted", "accepted", "accepted"]);
+    expect(h.rail.issueCount).toBe(3);
+    const a2 = issued.outcomes[2]!.attempt_id;
+    h.rail.decide(a2, "never");
+    await h.engine.reconcile(issued.id);
+    const partly = await h.engine.reconcile(issued.id);
+    expect(partly.state).toBe("executing");
+    expect(partly.outcomes.map((o) => o.status)).toEqual(["settled", "settled", "accepted"]);
+    h.rail.decide(a2, "pays");
+    const done = await h.engine.reconcile(issued.id);
+    expect(done.state).toBe("settled");
+    expect(h.bundle.listReceipts()).toHaveLength(3);
+  });
+});
+
+describe("the webhook path: commerce.charge.* by attempt id or by the rail's charge id", () => {
+  it("paid twice settles once; paid before created is fine; expired after paid moves nothing", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    const chargeId = issued.outcomes[0]!.transaction_id!;
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_1", type: "commerce.charge.paid", transaction_id: chargeId })).toEqual({ applied: true, reason: "settled" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_1", type: "commerce.charge.paid", transaction_id: chargeId })).toEqual({ applied: false, reason: "duplicate event id" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_created_late", type: "commerce.charge.created", transaction_id: chargeId })).toMatchObject({ applied: false });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_2", type: "commerce.charge.paid", transaction_id: chargeId })).toMatchObject({ applied: false, reason: "execution already settled" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_expired_late", type: "commerce.charge.expired", transaction_id: chargeId })).toMatchObject({ applied: false, reason: "execution already settled" });
+    const settled = h.store.getExecution(issued.id)!;
+    expect(settled.state).toBe("settled");
+    expect(settled.outcomes[0]).toMatchObject({ status: "settled", transaction_id: chargeId, receipt_id: chargeId });
+    expect(h.store.listEvents({ execution_id: issued.id }).filter((e) => e.type === "execution.transition" && (e.payload as { to: string }).to === "settled")).toHaveLength(1);
+    // The settlement came by event, so the bundle holds no receipt yet; collectReceipts fetches it once.
+    expect(h.bundle.listReceipts()).toHaveLength(0);
+    expect(await h.engine.collectReceipts(issued.id)).toEqual([chargeId]);
+    expect(await h.engine.collectReceipts(issued.id)).toEqual([]);
+    expect(h.bundle.listReceipts()).toHaveLength(1);
+  });
+
+  it("expired by event closes failed with charge_expired; a later paid for the same charge moves nothing", async () => {
+    const h = receivables({ rail: { payer: "never" } });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 50000, due_date: "2026-09-25" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await h.engine.execute(d.execution.id);
+    const attempt = issued.outcomes[0]!.attempt_id;
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_exp", type: "commerce.charge.expired", attempt_id: attempt })).toEqual({ applied: true, reason: "failed" });
+    expect(h.store.getExecution(issued.id)!.reason).toBe("charge_expired");
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_paid_after", type: "commerce.charge.paid", attempt_id: attempt })).toMatchObject({ applied: false });
+  });
+
+  it("an event naming a charge this kit never issued is not applied", () => {
+    const h = receivables();
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_x", type: "commerce.charge.paid", transaction_id: "chg_someone_elses" })).toEqual({ applied: false, reason: "unknown attempt" });
+    expect(h.engine.ingestExternalEvent({ event_id: "evt_y", type: "commerce.charge.paid" })).toMatchObject({ applied: false });
+  });
+});
+
+describe("the kit's envelope runs at every gate, and only tightens", () => {
+  const envelope: PolicyExtension = (execution) => {
+    const principal = 120000;
+    if (execution.total < principal * 0.85) return { reason: "outside_envelope", detail: `total ${execution.total} is below the floor of ${principal * 0.85} (15% off ${principal})` };
+    return undefined;
+  };
+
+  it("a proposal below the discount floor is denied at draft, even in human mode", async () => {
+    const h = receivables({ mode: "human", policyExtension: envelope });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 1000, due_date: "2026-09-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("denied");
+    expect(d.execution.reason).toBe("outside_envelope");
+  });
+
+  it("a debtor without an open agreement is not a payee: denied in mandate, blocked for the human, never approvable", async () => {
+    const h = receivables({ mode: "human", policyExtension: envelope });
+    const d = await h.engine.draft({ items: [{ payee: "99988877766", amount: 120000, due_date: "2026-09-30" }] });
+    if (!d.ok) throw new Error("refused");
+    expect(d.execution.state).toBe("awaiting_approval");
+    expect(d.execution.blocking_reasons).toEqual(["beneficiary_not_allowed"]);
+    expect(h.engine.approve(d.execution.id, { id: "usr_operator", channel: "terminal" }).state).toBe("denied");
+  });
+
+  it("the due date is part of the items_hash: moving it after approval is another charge", () => {
+    const a = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL", due_date: "2026-09-30" }]);
+    const b = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL", due_date: "2026-10-30" }]);
+    const c = itemsHash([{ beneficiary: "x", payee: DEBTOR, amount: 100, currency: "BRL" }]);
+    expect(a).not.toBe(b);
+    expect(a).not.toBe(c);
+  });
+});
+
+describe("outcomeOf: the API's charge view, mapped by fields and never by prose", () => {
+  const base: ChargeView = {
+    id: "chg_1",
+    status: "PENDING",
+    local_status: "pending",
+    status_conflict: false,
+    method: "boleto",
+    currency: "BRL",
+    amount: 1080.5,
+    amount_minor: 108050,
+    due_date: "2026-09-30",
+    payable: true,
+    boleto_bar_code: "1".repeat(44),
+    boleto_bank_line: "2".repeat(47),
+    pix_copy_paste: "000201...",
+    credit_correlation_armed: true,
+    payment_in_flight: false,
+    settlement: null,
+    issuance_unconfirmed: false,
+  };
+  it("maps the five states", () => {
+    expect(outcomeOf(base)).toMatchObject({ status: "accepted", transaction_id: "chg_1", instrument: { payable: true, status: "PENDING", pix_copy_paste: "000201..." } });
+    expect(outcomeOf({ ...base, status: "PROCESSING", payable: false, pix_copy_paste: null })).toMatchObject({ status: "accepted", instrument: { payable: false } });
+    expect(outcomeOf({ ...base, local_status: "settled", status: "CONFIRMED", settlement: "confirmed" })).toMatchObject({ status: "settled", transaction_id: "chg_1", receipt_id: "chg_1", money_moved: false });
+    expect(outcomeOf({ ...base, local_status: "expired", status: "CANCELLED" })).toMatchObject({ status: "failed", code: "charge_expired" });
+    expect(outcomeOf({ ...base, status: "EXPIRED" })).toMatchObject({ status: "failed", code: "charge_expired" });
+    expect(outcomeOf({ ...base, status: "CANCELLED" })).toMatchObject({ status: "failed", code: "charge_cancelled" });
+    expect(outcomeOf({ ...base, id: null, issuance_unconfirmed: true })).toEqual({ status: "in_flight" });
+  });
+  it("a payment notified and not yet credited is still accepted: nothing settles on a notification", () => {
+    expect(outcomeOf({ ...base, payment_in_flight: true, settlement: "pending" })).toMatchObject({ status: "accepted" });
+  });
+});

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createCodeSparClient } from "../src/api/client.js";
+import { assertTestKey, isTestKey, NotATestKeyError, redactKey } from "../src/secrets.js";
+
+// Built at runtime so the secret scan (which refuses key-shaped literals) stays honest about this file.
+const TEST = ["csk", "test", "0123456789abcdef"].join("_");
+const LIVE = ["csk", "live", "0123456789"].join("_");
+
+describe("sandbox by construction", () => {
+  it("accepts only csk_test_ keys", () => {
+    expect(isTestKey(TEST)).toBe(true);
+    expect(isTestKey(LIVE)).toBe(false);
+    expect(isTestKey("csk_test_")).toBe(false);
+    expect(isTestKey(undefined)).toBe(false);
+    expect(() => assertTestKey(LIVE)).toThrow(NotATestKeyError);
+  });
+
+  it("refuses to build an API client with a live key, before any network", () => {
+    expect(() => createCodeSparClient({ apiKey: LIVE })).toThrow(NotATestKeyError);
+    expect(() => createCodeSparClient({ apiKey: undefined })).toThrow(NotATestKeyError);
+    expect(createCodeSparClient({ apiKey: TEST })).toBeDefined();
+  });
+
+  it("redacts keys for logs", () => {
+    expect(redactKey(TEST)).toBe("csk_test_…cdef");
+    expect(redactKey(TEST)).not.toContain("0123456789");
+  });
+});