@codespar/cli 0.17.0 → 0.18.0

package/templates/collections-agent/packages/agent-core/src/revocation.ts

@@ -15,7 +15,7 @@ export type MandateStatus = "active" | "paused" | "revoked" | "expired";
 export interface MandateStatusReport {
   mandate_id: string;
   status: MandateStatus | "unknown";
-  /** True when the organization pressed the kill switch (`org pauseAll`). The API has no such read yet; only the stub can say it. */
+  /** True when the organization pressed the kill switch (ent#1648). The API says it as `org_paused` on `GET /v1/mandates/{id}`; the stub says it from `pauseAll`. */
   org_paused: boolean;
   checked_at: string;
   /** Which source answered, so the bundle says whether the check was real. */

package/templates/collections-agent/packages/agent-core/src/state-machine.ts

@@ -6,7 +6,7 @@
  * does not compile; the runtime check below refuses the same pair when the
  * types were bypassed (a cast, a row read back from SQLite).
  */
-import type { Actor, ApprovalMode, EscalationTrigger, ExecutionBatch, ExecutionItem, ExecutionReason, ItemOutcome, MandateRef } from "./types.js";
+import type { Actor, ApprovalMode, EscalationTrigger, ExecutionBatch, ExecutionComposition, ExecutionItem, ExecutionReason, ItemOutcome, MandateRef } from "./types.js";
 
 export type ExecutionState =
   | "drafted"
@@ -78,6 +78,15 @@ export interface Execution<S extends ExecutionState = ExecutionState> {
   items_hash: string;
   /** Present when this execution is one line of a batch: the set it was presented inside, and where in it. */
   batch?: ExecutionBatch;
+  /** Present when this execution's amount is composed of lines (a cart): the lines' hash, not the lines. */
+  composition?: ExecutionComposition;
+  /**
+   * A batch line's attempt generation per item index, when it is not 0: how
+   * many of the line's derived attempt ids the rail answered as spent before
+   * the one this execution presented (`batchAttemptId`). Saved BEFORE the
+   * next id is presented, so a reconcile looks up the id that was sent.
+   */
+  attempt_generations?: Record<number, number>;
   mandate: MandateRef;
   /** Written once, before the rail is called. Retrying reuses it. */
   idempotency_key: string;

package/templates/collections-agent/packages/agent-core/src/stubs/mandate-status.ts

@@ -8,8 +8,9 @@
  * a run with a test key gets instead; this file is never consulted on that
  * path.
  *
- * It also holds the organization kill switch (`pauseAll`), which the API
- * does not expose yet, so `org_paused` can be exercised locally.
+ * It also holds the organization kill switch (`pauseAll`), so `org_paused`
+ * can be exercised locally the way `GET /v1/mandates/{id}` reports it
+ * (ent#1648): a flag next to the mandate's own status, which it leaves alone.
  */
 import type { MandateStatusSource, MandateStatus, MandateStatusReport } from "../revocation.js";
 import type { StateStore } from "../state/store.js";
@@ -46,7 +47,7 @@ export class LocalMandateStatusStub implements MandateStatusSource {
     this.store.stubSetMandateStatus(mandateId, "active", null, this.clock().toISOString());
   }
 
-  /** The organization kill switch, locally: the API has no `org pauseAll` yet. */
+  /** The organization kill switch, locally. Against the API it is pressed with `POST /v1/orgs/{orgId}/pause`, which the kit never calls. */
   pauseAll(): void {
     this.store.stubSetOrgPaused(STUB_ORG_ID, true, this.clock().toISOString());
   }

package/templates/collections-agent/packages/agent-core/src/stubs/rail.ts

@@ -3,11 +3,16 @@
  * scenarios, the adversarial suite and the restart test run offline. Every
  * attempt is persisted in state.db before the outcome is returned, which is
  * what lets a process killed right after "the money left" be reconciled on
- * `resume` instead of paying again. Receipts here are HMAC-shaped only in
+ * `resume` instead of paying again. A repeat of an attempt id is answered the
+ * way the deployed API answers it (ent#1671): replayed when it settled,
+ * in flight while the provider is on it, spent when it failed, and refused
+ * when the id arrives with a different payment. A stub that simply replayed
+ * whatever it held would let a suite pass that the API fails. Receipts here are HMAC-shaped only in
  * form; nothing about them is verifiable by anyone.
  */
-import { sha256Hex } from "../hash.js";
-import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import { canonicalJson, sha256Hex } from "../hash.js";
+import { checkQuote } from "../quote.js";
+import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
 import type { StateStore } from "../state/store.js";
 import type { Actor } from "../types.js";
 
@@ -29,6 +34,34 @@ export interface StubRailOptions {
   afterDispatch?: (attemptId: string) => void;
   /** Attempt ids whose first lookup answers `in_flight` and whose second lookup finds the provider finished (settled), with no pay() in between. */
   inFlightThenSettled?: string[];
+  /**
+   * Where the "provider" keeps its books, when that is not the agent's own
+   * state file. The real rail is a server two machines share; a test that
+   * runs the same batch from two state files points both at one ledger.
+   */
+  ledger?: StateStore;
+}
+
+/** What the stub's books hold for an attempt the "provider" took and has not finished. */
+const IN_FLIGHT = { status: "in_flight" } as const;
+
+type Recorded = RailOutcome | typeof IN_FLIGHT;
+
+/**
+ * The fields a repeat of an attempt id is compared on, the stub's share of
+ * the API's attempt tuple (ent#1671): whose money, how much, to whom, the
+ * digest of the quote and the approval the spend carried (ent#1670). Rail
+ * and instrument are the API's and have no stub counterpart.
+ */
+function mismatchedFields(recorded: Omit<RailPayment, "actor">, asked: Omit<RailPayment, "actor">): string[] {
+  const out: string[] = [];
+  if (recorded.mandate_id !== asked.mandate_id) out.push("mandate");
+  if (recorded.amount_minor !== asked.amount_minor) out.push("amount_minor");
+  if (recorded.currency !== asked.currency) out.push("currency");
+  if (recorded.payee !== asked.payee) out.push("payee");
+  if (canonicalJson(recorded.quote ?? null) !== canonicalJson(asked.quote ?? null)) out.push("quote");
+  if (canonicalJson(recorded.approval ?? null) !== canonicalJson(asked.approval ?? null)) out.push("approval");
+  return out;
 }
 
 export class StubRail implements PaymentRail {
@@ -36,18 +69,19 @@ export class StubRail implements PaymentRail {
   private readonly clock: () => Date;
   private readonly uncertainPending: Set<string>;
 
+  private readonly store: StateStore;
+
   constructor(
-    private readonly store: StateStore,
+    store: StateStore,
     private readonly options: StubRailOptions = {},
   ) {
+    this.store = options.ledger ?? store;
     this.clock = options.clock ?? (() => new Date());
     this.uncertainPending = new Set(options.uncertainOnce ?? []);
   }
 
   private uncertainArmed = false;
   private readonly inFlightSeen = new Set<string>();
-  /** Attempts that answered `uncertain` because the stub was armed: the "provider" did take them, and a later lookup finds them finished. */
-  private readonly lateAttempts = new Set<string>();
   /** Attempts that already gave their one `uncertain`, so a re-presentation behaves normally. */
   private readonly uncertainAnswered = new Set<string>();
   /** How many times pay() reached the point of persisting a NEW attempt. */
@@ -59,12 +93,19 @@ export class StubRail implements PaymentRail {
   }
 
   async pay(payment: RailPayment): Promise<RailOutcome> {
+    // The same refusal the CodeSpar rail makes before its call, so a scenario exercises it.
+    const quoted = checkQuote(payment);
+    if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
+    const approval = checkSpendApproval(payment);
+    if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
+    const { actor: _actor, ...request } = payment;
     const existing = this.store.stubRailGet(payment.attempt_id);
-    if (existing) return existing.outcome as RailOutcome;
+    if (existing) return this.repeat(payment.attempt_id, existing.request as Omit<RailPayment, "actor">, existing.outcome as Recorded, request);
 
     const uncertainPayee = this.options.uncertainPayees?.includes(payment.payee) === true && !this.uncertainAnswered.has(payment.attempt_id);
     if (this.uncertainArmed || this.uncertainPending.has(payment.attempt_id) || uncertainPayee) {
-      if (this.uncertainArmed || uncertainPayee) this.lateAttempts.add(payment.attempt_id);
+      // Armed and payee-scripted attempts were TAKEN by the provider, so they are on its books as in flight; `uncertainOnce` never reached it.
+      if (this.uncertainArmed || uncertainPayee) this.store.stubRailPut(payment.attempt_id, request, IN_FLIGHT, this.clock().toISOString());
       this.uncertainAnswered.add(payment.attempt_id);
       this.uncertainArmed = false;
       this.uncertainPending.delete(payment.attempt_id);
@@ -74,40 +115,52 @@ export class StubRail implements PaymentRail {
     const at = this.clock().toISOString();
     const outcome: RailOutcome = this.options.refusePayees?.includes(payment.payee)
       ? { status: "failed", code: "psp_dispatch_failed", message: `stub: provider refused payee ${payment.payee}` }
-      : {
-          status: "settled",
-          transaction_id: `stubtx_${sha256Hex(payment.attempt_id).slice(0, 16)}`,
-          receipt_id: `rcpt_stub_${sha256Hex(`receipt:${payment.attempt_id}`).slice(0, 16)}`,
-          money_moved: false,
-          sandbox: true,
-          raw: { stub: true, attempt_id: payment.attempt_id, at },
-        };
-    const { actor: _actor, ...request } = payment;
+      : settledOutcome(payment.attempt_id, { stub: true, attempt_id: payment.attempt_id, at });
     this.payCount += 1;
     this.store.stubRailPut(payment.attempt_id, request, outcome, at);
     this.options.afterDispatch?.(payment.attempt_id);
     return outcome;
   }
 
+  /**
+   * A presentation of an attempt id the books already hold, answered the way
+   * the deployed API answers it (ent#1671, #1683), and never by paying:
+   * a different payment under the id is `attempt_id_conflict`, checked before
+   * the state; a settled one is its ORIGINAL outcome with `idempotent_replay`;
+   * one still in flight is `psp_attempt_in_flight`; a failed one is
+   * `psp_attempt_conflict`, spent for good.
+   */
+  private repeat(attemptId: string, recorded: Omit<RailPayment, "actor">, outcome: Recorded, asked: Omit<RailPayment, "actor">): RailOutcome {
+    const mismatched = mismatchedFields(recorded, asked);
+    if (mismatched.length > 0) {
+      return { status: "failed", code: "attempt_id_conflict", message: `stub: attempt ${attemptId} was already used for a different payment (differs in: ${mismatched.join(", ")}); nothing was held or sent`, held: "conflict" };
+    }
+    switch (outcome.status) {
+      case "in_flight":
+        return { status: "uncertain", code: "psp_attempt_in_flight", message: `stub: attempt ${attemptId} is claimed and its outcome is not yet recorded` };
+      case "settled":
+        return { ...outcome, replayed: true, raw: { ...(outcome.raw as Record<string, unknown>), idempotent_replay: true } };
+      case "failed":
+        return { status: "failed", code: "psp_attempt_conflict", message: `stub: attempt ${attemptId} already failed and moved no money; use a fresh attempt_id`, spent: true };
+      default:
+        return outcome;
+    }
+  }
+
   async lookup(attemptId: string, payment: RailPayment): Promise<RailLookup> {
-    const recorded = this.store.stubRailGet(attemptId)?.outcome as RailOutcome | undefined;
-    if (recorded) return recorded;
-    if (this.options.inFlightThenSettled?.includes(attemptId) || this.lateAttempts.has(attemptId)) {
+    const { actor: _actor, ...request } = payment;
+    const existing = this.store.stubRailGet(attemptId);
+    const recorded = existing?.outcome as Recorded | undefined;
+    // Looking up IS presenting again on the real rail, so a recorded attempt answers exactly what a repeat of it answers.
+    if (existing && recorded && recorded.status !== "in_flight") return this.repeat(attemptId, existing.request as Omit<RailPayment, "actor">, recorded, request);
+    if (this.options.inFlightThenSettled?.includes(attemptId) || recorded?.status === "in_flight") {
       if (!this.inFlightSeen.has(attemptId)) {
         this.inFlightSeen.add(attemptId);
         return { status: "in_flight" };
       }
       // The provider finished on its own; the stub records the outcome as the rail would, without a new dispatch.
-      const { actor: _actor, ...request } = payment;
-      const outcome: RailOutcome = {
-        status: "settled",
-        transaction_id: `stubtx_${sha256Hex(attemptId).slice(0, 16)}`,
-        receipt_id: `rcpt_stub_${sha256Hex(`receipt:${attemptId}`).slice(0, 16)}`,
-        money_moved: false,
-        sandbox: true,
-        raw: { stub: true, attempt_id: attemptId, finished_in_background: true },
-      };
-      this.store.stubRailPut(attemptId, request, outcome, this.clock().toISOString());
+      const outcome = settledOutcome(attemptId, { stub: true, attempt_id: attemptId, finished_in_background: true });
+      this.store.stubRailReplace(attemptId, existing?.request ?? request, outcome, this.clock().toISOString());
       return outcome;
     }
     return undefined;
@@ -118,13 +171,17 @@ export class StubRail implements PaymentRail {
     if (!sealed) return undefined;
     const req = sealed.request as Omit<RailPayment, "actor">;
     const out = sealed.outcome as Extract<RailOutcome, { status: "settled" }>;
+    // Like the API: the payee on the receipt is the one the quote sealed, and none when the spend carried no quote.
     const body = {
       receipt_id: receiptId,
       state: "paid",
       mandate: { id: req.mandate_id },
-      payment: { amount_minor: req.amount_minor, payee: req.payee, attempt_id: req.attempt_id, money_moved: false, sandbox: true, at: sealed.at },
+      // Like the API since ent#1670: the approval the spend carried is sealed and read back, batch_hash null when none was sent.
+      chain_version: req.approval ? 4 : 1,
+      approval: req.approval ? { items_hash: req.approval.items_hash, batch_hash: req.approval.batch_hash ?? null } : null,
+      payment: { amount_minor: req.amount_minor, payee: req.quote?.payee ?? null, attempt_id: req.attempt_id, money_moved: false, sandbox: true, at: sealed.at },
     };
-    const chain = `sha256:${sha256Hex(JSON.stringify(body))}`;
+    const chain = `sha256:${sha256Hex(JSON.stringify(req.quote ? { ...body, quote: req.quote } : body))}`;
     return {
       ...body,
       chain,
@@ -139,3 +196,14 @@ export class StubRail implements PaymentRail {
     };
   }
 }
+
+function settledOutcome(attemptId: string, raw: Record<string, unknown>): RailOutcome {
+  return {
+    status: "settled",
+    transaction_id: `stubtx_${sha256Hex(attemptId).slice(0, 16)}`,
+    receipt_id: `rcpt_stub_${sha256Hex(`receipt:${attemptId}`).slice(0, 16)}`,
+    money_moved: false,
+    sandbox: true,
+    raw,
+  };
+}

package/templates/collections-agent/packages/agent-core/src/tools.ts

@@ -3,10 +3,12 @@
  * authority comes before mandate-level authority: a tool that is not in
  * this file is refused before anything else looks at the call.
  *
- * Two kinds. `meta_tools` are CodeSpar meta-tool names, with the input the
- * kit accepts for them (a snapshot of the MCP shape, pinned by `mcp` in the
- * manifest; see OPEN_QUESTIONS on why the list is not fetched live).
- * `local_tools` are the agent's own read-only helpers.
+ * Two kinds. `meta_tools` borrow a CodeSpar meta-tool's name for the job
+ * they do, but the input shape is the kit's own and the kit's handler runs it:
+ * a payment or charge becomes a `drafted` execution, and the core sends the
+ * real call over REST. It is not a copy of the MCP's schema and does not match
+ * it (OPEN_QUESTIONS section 8 has the comparison). `local_tools` are the
+ * agent's own helpers: reads, and state the agent keeps for itself.
  */
 import { readFileSync } from "node:fs";
 import { z } from "zod";
@@ -17,8 +19,15 @@ const ToolDefinitionSchema = z
     name: z.string().regex(/^[a-z][a-z0-9_]*$/),
     description: z.string().min(1),
     input_schema: z.record(z.string(), z.unknown()),
-    /** `payment` and `charge` tools create a `drafted` execution and nothing else; `read` tools never touch money. `charge` is the receivable side: the counterparty pays us. */
-    effect: z.enum(["payment", "charge", "read"]),
+    /**
+     * `payment` and `charge` tools create a `drafted` execution and nothing
+     * else; `read` tools never touch money and change nothing. `charge` is the
+     * receivable side: the counterparty pays us. `state` changes durable local
+     * state (a cart in `state.db`) and moves no money — not a read, because
+     * calling it twice is not calling it once, and not a payment, because no
+     * execution comes out of it.
+     */
+    effect: z.enum(["payment", "charge", "read", "state"]),
   })
   .strict();
 
@@ -36,6 +45,8 @@ export const ToolsFileSchema = z
     }
     for (const [i, tool] of t.meta_tools.entries()) {
       if (!tool.name.startsWith("codespar_")) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["meta_tools", i, "name"], message: "meta-tools are named codespar_*" });
+      // A meta-tool borrows a CodeSpar name for a job CodeSpar does; the state the agent keeps for itself is not one.
+      if (tool.effect === "state") ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["meta_tools", i, "effect"], message: "a state tool is local: meta-tools move money or read" });
     }
   });
 

package/templates/collections-agent/packages/agent-core/src/types.ts

@@ -52,6 +52,45 @@ export interface ExecutionBatch {
   count: number;
 }
 
+/**
+ * One line of what an execution's amount is MADE OF, as the kit resolved it:
+ * a cart line (`ref` a SKU, a quantity, the unit price the catalog gave it)
+ * or a discount line (a negative `amount`). Only `compositionHash` reads it;
+ * the core never stores the lines, only their hash and their count.
+ */
+export interface CompositionLine {
+  ref: string;
+  quantity: number;
+  unit_amount: number;
+  amount: number;
+  currency: string;
+}
+
+/**
+ * What an execution's single amount was composed from, when it was composed
+ * from something: a sale is ONE charge, so ONE item whose amount is the
+ * order's total, and the lines of the cart behind that total are not items.
+ *
+ * That leaves the composition unattested by `items_hash`: two units at 100
+ * and one unit at 200 are the same item, the same amount, the same hash.
+ * `composition_hash` binds the lines — computed by the kit over the resolved
+ * lines in order, carried by the execution and by every artifact of it — so a
+ * cart recomposed at a constant total after approval is not the cart that was
+ * approved.
+ *
+ * Absent on an execution that is not composed from anything, and an artifact
+ * without it is the artifact of section 4.2 unchanged, byte for byte: the
+ * field is omitted rather than null, the same discipline as `batch`.
+ */
+export interface ExecutionComposition {
+  /** The kit's reference for what was composed (`cart_id`). */
+  ref: string;
+  /** `compositionHash` over the resolved lines, in order. */
+  composition_hash: string;
+  /** How many lines that hash covers. */
+  line_count: number;
+}
+
 /** The trigger of section 4.4 that sent a `mandate` execution to a human. */
 export type EscalationTrigger = "amount" | "new_beneficiary" | "outside_hours";
 
@@ -67,6 +106,8 @@ export type ExecutionReason =
   | "window_cap_exceeded"
   | "approval_expired"
   | "items_hash_mismatch"
+  /** The quote a spend would present does not name the approved amount and payee; refused before the call. */
+  | "quote_mismatch"
   | "mandate_changed"
   | "denied_by_approver"
   | "rail_failed"
@@ -80,7 +121,13 @@ export type ExecutionReason =
   /** A receivable was issued and the rail is waiting for the payer; the execution stays `executing` until `commerce.charge.*` closes it. */
   | "awaiting_settlement"
   | "charge_expired"
-  | "charge_cancelled";
+  | "charge_cancelled"
+  /**
+   * An ISSUED receivable whose read now answers that its reference matches more than one charge. Terminal for the
+   * execution, but not "nothing moved": the charge exists and may still be paid. Reconcile it by the charge id; never
+   * issue another to the same payee until that is done, which is why the core refuses one (`policy`).
+   */
+  | "charge_reference_ambiguous";
 
 export interface MandateRef {
   id: string;
@@ -102,6 +149,8 @@ export interface ApprovalArtifact {
   items_hash: string;
   /** Present when this execution is one line of a batch: what binds the SET this line was approved inside. */
   batch?: ExecutionBatch;
+  /** Present when this execution's amount is composed of lines (a cart): what binds the composition that was approved. */
+  composition?: ExecutionComposition;
   /** Present when a section 4.4 trigger sent the execution to a human first. */
   escalation?: { trigger: EscalationTrigger; detail: string };
   actor: Actor;
@@ -117,6 +166,10 @@ export interface ItemOutcome {
   transaction_id?: string;
   /** The rail's code on a failed outcome (`charge_expired`, `charge_cancelled`, a provider code). */
   code?: string;
+  /** A failed outcome because the attempt id is held for another payment or another project (`RailOutcome.held`). */
+  held?: "conflict" | "unavailable";
+  /** A settled outcome the rail answered from its record of an earlier presentation (`RailOutcome.replayed`). */
+  replayed?: true;
   error?: string;
   /** What the payer is shown for an accepted receivable, as the rail handed it back. Presentation only; nothing here decides money. */
   instrument?: ChargeInstrument;

package/templates/collections-agent/packages/agent-core/test/approval-seal.test.ts

@@ -0,0 +1,233 @@
+/**
+ * OPEN_QUESTIONS §3: every spend carries the approval artifact's hashes, and
+ * the API seals them into the receipt's chain (v4, ent#1670). What is sent is
+ * the artifact's own `items_hash`, and for a batch line its `batch_hash` —
+ * the values the artifact's HMAC covers — and nothing the execution says
+ * later. A spend without them, or with a shape the API would refuse, never
+ * goes out; the bundle's receipt copy names the artifact by id so `verify`
+ * finds it by identity.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ApiClient } from "@codespar/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { CodeSparRail } from "../src/api/rail.js";
+import { copyDisagreesWithRead, maskPayee } from "../src/bundle.js";
+import { ReceiptSealMismatchError } from "../src/engine.js";
+import { checkSpendApproval, spendApprovalOf, type PaymentRail, type RailPayment, type SealedSpendApproval } 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" };
+const ITEMS_HASH = `sha256:${"1".repeat(64)}`;
+
+function payment(over: Partial<RailPayment> = {}): RailPayment {
+  return {
+    attempt_id: "att_seal_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: ITEMS_HASH },
+    actor,
+    ...over,
+  };
+}
+
+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" } }));
+  return { api: { post, get: vi.fn(async () => receiptBody) } as unknown as ApiClient, post };
+}
+
+/** The stub rail, but the receipt it hands back seals whatever approval the test says. */
+function sealingApproval(sealed: SealedSpendApproval | null) {
+  return (inner: PaymentRail): PaymentRail => ({
+    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, approval: sealed };
+    },
+  });
+}
+
+function recording() {
+  const h = harness({ mode: "human" });
+  const seen: RailPayment[] = [];
+  const pay = h.rail.pay.bind(h.rail);
+  h.rail.pay = async (p) => (seen.push(p), pay(p));
+  return { h, seen };
+}
+
+describe("every spend presents the artifact's hashes", () => {
+  it("a single execution: the artifact's items_hash on every line, no batch_hash, and the quote keeps the moment of approval", async () => {
+    const { h, seen } = recording();
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }, { 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.approval)).toEqual([{ items_hash: artifact.items_hash }, { items_hash: artifact.items_hash }]);
+    expect(seen.map((p) => p.quote?.at)).toEqual([artifact.approved_at, artifact.approved_at]);
+    // The form the API seals a timestamp in (RFC 3339, UTC, milliseconds), so the read gives back what was sent (ent#1670).
+    expect(artifact.approved_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    // What the "provider" holds for the attempt is what was sent.
+    expect((h.store.stubRailGet(seen[0]!.attempt_id)!.request as RailPayment).approval).toEqual({ items_hash: artifact.items_hash });
+  });
+
+  it("a batch line: the line's items_hash and the batch's batch_hash, and a quote with no time in it", async () => {
+    const { h, seen } = recording();
+    const batch = { ref: "folha-teste", batch_hash: `sha256:${"a".repeat(64)}`, index: 0, count: 2 };
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }], batch });
+    if (!d.ok) throw new Error("refused");
+    const approved = h.engine.approve(d.execution.id, approver);
+    const artifact = h.store.getApproval(approved.approval_id!)!;
+    await h.engine.execute(approved.id);
+    expect(seen[0]!.approval).toEqual({ items_hash: artifact.items_hash, batch_hash: batch.batch_hash });
+    expect(seen[0]!.quote).not.toHaveProperty("at");
+  });
+
+  it("spendApprovalOf carries exactly the artifact's two hashes", () => {
+    expect(spendApprovalOf({ items_hash: ITEMS_HASH })).toEqual({ items_hash: ITEMS_HASH });
+    expect(spendApprovalOf({ items_hash: ITEMS_HASH, batch: { ref: "r", batch_hash: `sha256:${"b".repeat(64)}`, index: 1, count: 3 } })).toEqual({ items_hash: ITEMS_HASH, batch_hash: `sha256:${"b".repeat(64)}` });
+  });
+});
+
+describe("the CodeSpar rail", () => {
+  it("sends approval on both spend routes, as the artifact spells it", async () => {
+    const withBatch = { items_hash: ITEMS_HASH, batch_hash: `sha256:${"b".repeat(64)}` };
+    const byEnvelope = fakeApi();
+    await new CodeSparRail(byEnvelope.api, { canonical: { any: "envelope" } as never, signature: "a".repeat(64) }).pay(payment({ approval: withBatch }));
+    expect(byEnvelope.post.mock.calls[0]![0]).toBe("/v1/consumer-payments/execute");
+    expect(byEnvelope.post.mock.calls[0]![1].body["approval"]).toEqual(withBatch);
+    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["approval"]).toEqual({ items_hash: ITEMS_HASH });
+  });
+
+  it("refuses a spend without it, or with a hash the API would refuse, without calling the API", async () => {
+    const { api, post } = fakeApi();
+    const rail = new CodeSparRail(api);
+    const { approval: _a, ...bare } = payment();
+    expect(await rail.pay(bare)).toMatchObject({ status: "failed", code: "approval_missing" });
+    expect(await rail.pay(payment({ approval: { items_hash: "sha256:ABC" } }))).toMatchObject({ status: "failed", code: "approval_malformed" });
+    expect(await rail.pay(payment({ approval: { items_hash: ITEMS_HASH, batch_hash: "f".repeat(63) } }))).toMatchObject({ status: "failed", code: "approval_malformed" });
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("checkSpendApproval accepts the two spellings the API accepts", () => {
+    expect(checkSpendApproval({ approval: { items_hash: ITEMS_HASH } }).ok).toBe(true);
+    expect(checkSpendApproval({ approval: { items_hash: "1".repeat(64) } }).ok).toBe(true);
+    expect(checkSpendApproval({ approval: { items_hash: `sha256:${"1".repeat(64)}`.toUpperCase() } }).ok).toBe(false);
+  });
+});
+
+describe("the receipt seals the approval the spend sent, or the run stops", () => {
+  it("the CodeSpar rail reads chain_version, the sealed approval and sig_sha256 through the SDK's types", async () => {
+    const read = {
+      receipt_id: "rcpt_1",
+      state: "paid",
+      chain_version: 4,
+      mandate: { id: "cm_1", nonce: "n", scope: "s", currency: "BRL", sig: "x", sig_sha256: "d".repeat(64) },
+      quote: { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, session_id: null, sig: "q", at: "2026-09-23T18:00:00.000Z" },
+      approval: { items_hash: ITEMS_HASH, batch_hash: null },
+      payment: { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_seal_0", money_moved: false, at: "2026-09-23T18:00:01.000Z" },
+      delivery: null,
+      chain: "c".repeat(64),
+      receipt_sig: "s",
+      exceptions: [],
+    };
+    const receipt = await new CodeSparRail(fakeApi(read).api).receipt("rcpt_1", actor);
+    expect(receipt).toMatchObject({ chain_version: 4, approval: { items_hash: ITEMS_HASH, batch_hash: null }, mandate: { id: "cm_1", sig_sha256: "d".repeat(64) } });
+    expect(JSON.stringify({ ...receipt, raw: undefined })).not.toContain('"sig":"x"');
+    const { approval: _a, ...older } = read;
+    expect((await new CodeSparRail(fakeApi({ ...older, chain_version: 1 }).api).receipt("rcpt_1", actor))?.approval).toBeNull();
+  });
+
+  for (const [name, sealed] of [
+    ["another list", { items_hash: `sha256:${"9".repeat(64)}`, batch_hash: null }],
+    ["no approval at all", null],
+  ] as const) {
+    it(`a receipt that seals ${name} is ReceiptSealMismatchError, after the outcome is saved`, async () => {
+      const h = harness({ mode: "human", wrapRail: sealingApproval(sealed) });
+      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);
+      const artifact = h.store.getApproval(approved.approval_id!)!;
+      await expect(h.engine.execute(approved.id)).rejects.toBeInstanceOf(ReceiptSealMismatchError);
+      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_approval: sealed, sent_approval: { items_hash: artifact.items_hash } });
+    });
+  }
+
+  it("the same hash in the other spelling of the prefix is the same approval", 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);
+    const bare = h.store.getApproval(approved.approval_id!)!.items_hash.replace(/^sha256:/, "");
+    const spelled = harness({ mode: "human", dir: h.dir, wrapRail: sealingApproval({ items_hash: bare, batch_hash: null }) });
+    expect((await spelled.engine.execute(approved.id)).state).toBe("settled");
+    expect(spelled.bundle.readEvents().some((e) => e["type"] === "receipt.seal_mismatch")).toBe(false);
+  });
+});
+
+describe("the stub rail", () => {
+  it("makes the same refusal, so a scenario cannot pass without the hashes", async () => {
+    const h = harness();
+    const { approval: _a, ...bare } = payment();
+    expect(await h.rail.pay(bare)).toMatchObject({ status: "failed", code: "approval_missing" });
+    expect(h.rail.payCount).toBe(0);
+  });
+
+  it("answers a repeat under a different approval as attempt_id_conflict naming it, the way the API's fingerprint does (ent#1670)", async () => {
+    const h = harness();
+    expect(await h.rail.pay(payment())).toMatchObject({ status: "settled" });
+    const other = await h.rail.pay(payment({ approval: { items_hash: `sha256:${"9".repeat(64)}` } }));
+    expect(other).toMatchObject({ status: "failed", code: "attempt_id_conflict", held: "conflict" });
+    expect((other as { message: string }).message).toContain("approval");
+    expect(h.rail.payCount).toBe(1);
+  });
+});
+
+describe("the bundle's receipt copy", () => {
+  it("names the artifact the spend carried, by id, and stays 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 approved = h.engine.approve(d.execution.id, approver);
+    const settled = await h.engine.execute(approved.id);
+    const copy = JSON.parse(readFileSync(join(h.bundle.dir, "receipts", `${settled.outcomes[0]!.receipt_id}.json`), "utf8")) as Record<string, unknown>;
+    expect(copy["approval_id"]).toBe(approved.approval_id);
+    expect(h.bundle.readApprovals().map((a) => a.approval_id)).toContain(copy["approval_id"]);
+    expect(JSON.stringify(copy)).not.toContain(ESCOLA);
+  });
+
+  it("is held against the read field by field, the payee in its masked form", () => {
+    const read = {
+      receipt_id: "rcpt_1",
+      chain: "c".repeat(64),
+      mandate: { id: "cm_1", nonce: "n" },
+      quote: { payee: ESCOLA },
+      payment: { rail: "pix", amount_minor: 185000, attempt_id: "att_0", money_moved: false, at: "2026-09-26T18:00:01.000Z" },
+    };
+    const copy = { receipt_id: "rcpt_1", chain: "c".repeat(64), mandate: { id: "cm_1" }, payment: { amount_minor: 185000, payee: maskPayee(ESCOLA), attempt_id: "att_0", money_moved: false, sandbox: true, at: "2026-09-26T18:00:01.000Z" } };
+    expect(copyDisagreesWithRead(copy, read)).toEqual([]);
+    expect(copyDisagreesWithRead({ ...copy, payment: { ...copy.payment, amount_minor: 1 } }, read)).toEqual(["payment.amount_minor"]);
+    expect(copyDisagreesWithRead({ ...copy, payment: { ...copy.payment, payee: maskPayee(MERCADO) } }, read)).toEqual(["payment.payee"]);
+    expect(copyDisagreesWithRead({ ...copy, chain: "d".repeat(64) }, read)).toEqual(["chain"]);
+    // A copy written since 0.16.10 carries what was sealed, and is held to it; one from before carries neither and is not faulted.
+    const sealedRead = { ...read, chain_version: 4, approval: { items_hash: ITEMS_HASH, batch_hash: null } };
+    const sealedCopy = { ...copy, chain_version: 4, approval: { batch_hash: null, items_hash: ITEMS_HASH } };
+    expect(copyDisagreesWithRead(sealedCopy, sealedRead)).toEqual([]);
+    expect(copyDisagreesWithRead({ ...sealedCopy, approval: { items_hash: `sha256:${"9".repeat(64)}`, batch_hash: null } }, sealedRead)).toEqual(["approval"]);
+    expect(copyDisagreesWithRead({ ...sealedCopy, chain_version: 3 }, sealedRead)).toEqual(["chain_version"]);
+    expect(copyDisagreesWithRead(copy, sealedRead)).toEqual([]);
+  });
+});