@codespar/cli 0.17.0 → 0.18.1

package/templates/supplier-payments-agent/packages/agent-core/src/api/charge-rail.ts

@@ -19,30 +19,39 @@
  * There is no receipt object for a receivable; the paid charge as the API
  * reports it is what the bundle keeps, marked `kind: "charge"` and unsealed.
  */
-import type { ApiClient } from "@codespar/sdk";
+import type { ApiClient, ApiOperation, ApiSuccess } from "@codespar/sdk";
 import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
 import type { Actor, ChargeInstrument } from "../types.js";
-import { describeApiError, isUncertain } from "./client.js";
+import { describeApiError, isUncertain, type ApiErrorCode } from "./client.js";
 
-/** The `/v1/charges` answer, as the SDK types it. */
-export interface ChargeView {
-  id: string | null;
-  status: string;
-  local_status: string;
-  status_conflict: boolean;
-  method: string;
-  currency: string;
-  amount: number;
-  amount_minor: number;
-  due_date: string | null;
-  payable: boolean;
-  boleto_bar_code: string | null;
-  boleto_bank_line: string | null;
-  pix_copy_paste: string | null;
-  credit_correlation_armed: boolean;
-  payment_in_flight: boolean;
-  settlement: "confirmed" | "pending" | "unconfirmable" | null;
-  issuance_unconfirmed: boolean;
+/** The `/v1/charges/{chargeId}` answer, as the SDK's generated OpenAPI types it. The create answers the same shape, and the compiler holds them together. */
+export type ChargeView = ApiSuccess<ApiOperation<"/v1/charges/{chargeId}", "get">>;
+
+/**
+ * Documented as the read's 409. The create does not document it, and the
+ * create's error path below still treats it as uncertain, which is the safe
+ * reading of a code the route is not known to send (OPEN_QUESTIONS §8).
+ */
+const ISSUANCE_UNCONFIRMED: ApiErrorCode<ApiOperation<"/v1/charges/{chargeId}", "get">> = "issuance_unconfirmed";
+
+/** The read's other 409: the reference matched more than one charge. Terminal for that reference; the API answers by the charge id. */
+const REFERENCE_AMBIGUOUS: ApiErrorCode<ApiOperation<"/v1/charges/{chargeId}", "get">> = "charge_reference_ambiguous";
+
+type ChargeRead =
+  | { kind: "view"; view: ChargeView }
+  | { kind: "missing" }
+  | { kind: "in_flight" }
+  | { kind: "failed"; outcome: Extract<RailOutcome, { status: "failed" }> }
+  | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> };
+
+/**
+ * When the charge settled, if the answer says so. `settled_at` is a column of
+ * the charge row, but the SDK's type for the read does not carry it, so this
+ * is the one field here read outside the type (OPEN_QUESTIONS §8).
+ */
+function settledAt(view: ChargeView): string | undefined {
+  const value: unknown = (view as Record<string, unknown>)["settled_at"];
+  return typeof value === "string" && value !== "" ? value : undefined;
 }
 
 export function instrumentOf(view: ChargeView): ChargeInstrument {
@@ -82,7 +91,7 @@ export class CodeSparChargeRail implements PaymentRail {
     if (!payment.consumer_id) return { status: "failed", code: "consumer_id_required", message: "a receivable settles into the principal's account; the policy names no consumer_id" };
     let view: ChargeView;
     try {
-      view = (await this.api.post("/v1/charges", {
+      view = await this.api.post("/v1/charges", {
         body: {
           consumer_id: payment.consumer_id,
           amount: payment.amount_minor / 100,
@@ -93,13 +102,13 @@ export class CodeSparChargeRail implements PaymentRail {
           due_date: payment.due_date,
           idempotency_key: payment.attempt_id,
         },
-      })) as ChargeView;
+      });
     } catch (err) {
       const failure = describeApiError(err);
-      if (isUncertain(failure) || failure.code === "issuance_unconfirmed") return { status: "uncertain", code: failure.code, message: failure.message };
+      if (isUncertain(failure) || failure.code === ISSUANCE_UNCONFIRMED) return { status: "uncertain", code: failure.code, message: failure.message };
       return { status: "failed", code: failure.code, message: failure.message };
     }
-    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: "issuance_unconfirmed", message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
+    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: ISSUANCE_UNCONFIRMED, message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
     if (view.amount_minor !== payment.amount_minor) {
       // The API understood another amount than the one approved. The receivable exists; withdraw it rather than leave a debt nobody approved.
       const withdrawn = await this.withdraw(view.id);
@@ -107,7 +116,7 @@ export class CodeSparChargeRail implements PaymentRail {
     }
     const outcome = outcomeOf(view);
     // `in_flight` is excluded above (`issuance_unconfirmed` / no id); the create answers a state, never "still running".
-    return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
+    return outcome.status === "in_flight" ? { status: "uncertain", code: ISSUANCE_UNCONFIRMED, message: "the create answered no readable state" } : outcome;
   }
 
   /**
@@ -119,37 +128,48 @@ export class CodeSparChargeRail implements PaymentRail {
     const byId = transactionId ? await this.read(transactionId) : { kind: "missing" as const };
     if (byId.kind === "view") return outcomeOf(byId.view);
     if (byId.kind === "in_flight") return { status: "in_flight" };
-    if (byId.kind === "uncertain") return byId.outcome;
+    if (byId.kind === "failed" || byId.kind === "uncertain") return byId.outcome;
     const byKey = await this.read(attemptId);
     if (byKey.kind === "view") return outcomeOf(byKey.view);
     if (byKey.kind === "in_flight") return { status: "in_flight" };
-    if (byKey.kind === "uncertain") return byKey.outcome;
+    if (byKey.kind === "failed" || byKey.kind === "uncertain") return byKey.outcome;
     return undefined;
   }
 
-  private async read(chargeRef: string): Promise<{ kind: "view"; view: ChargeView } | { kind: "missing" } | { kind: "in_flight" } | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> }> {
+  /**
+   * A 409 is branched on its code, never on the status alone: only `issuance_unconfirmed` means "still issuing".
+   * `charge_reference_ambiguous` is terminal for the reference and fails explicitly instead of being polled forever,
+   * and a 409 whose code this kit does not read is a failure too.
+   */
+  private async read(chargeRef: string): Promise<ChargeRead> {
     try {
-      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } })) as ChargeView;
+      const view = await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } });
       return { kind: "view", view };
     } catch (err) {
       const failure = describeApiError(err);
       if (failure.status === 404) return { kind: "missing" };
-      if (failure.status === 409) return { kind: "in_flight" };
+      if (failure.status === 409) {
+        if (failure.code === ISSUANCE_UNCONFIRMED) return { kind: "in_flight" };
+        const message =
+          failure.code === REFERENCE_AMBIGUOUS
+            ? `the reference ${chargeRef} matches more than one charge, and the API answers for the charge id only; which one is this attempt's is not assumed, so reconcile it by the charge id`
+            : `GET /v1/charges/${chargeRef} answered 409 with a code this kit does not read (${failure.code}); it is not read as a charge still issuing`;
+        return { kind: "failed", outcome: { status: "failed", code: failure.code, message } };
+      }
       return { kind: "uncertain", outcome: { status: "uncertain", code: failure.code, message: failure.message } };
     }
   }
 
   async receipt(chargeId: string, actor: Actor): Promise<RailReceipt | undefined> {
     try {
-      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } })) as ChargeView;
-      const raw = view as ChargeView & { settled_at?: string };
+      const view = await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } });
       return {
         receipt_id: chargeId,
         kind: "charge",
         state: view.local_status === "settled" ? "paid" : view.local_status,
         mandate: { id: "n/a" },
         // The read names no buyer, so the payee is not on this record; the execution's item names the debtor.
-        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: raw.settled_at ?? new Date().toISOString() },
+        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: settledAt(view) ?? new Date().toISOString() },
         chain: null,
         receipt_sig: null,
         receipt_sig_ed25519: null,

package/templates/supplier-payments-agent/packages/agent-core/src/api/client.ts

@@ -3,7 +3,7 @@
  * the `csk_test_` prefix before the client is built, so no live key ever
  * reaches the network from this repository.
  */
-import { ApiClient, CodesparApiError, TimeoutError } from "@codespar/sdk";
+import { ApiClient, CodesparApiError, TimeoutError, type ApiOperation, type ApiResponse } from "@codespar/sdk";
 import { assertTestKey } from "../secrets.js";
 
 export const DEFAULT_BASE_URL = "https://api.codespar.dev";
@@ -32,15 +32,38 @@ export interface ApiFailure {
   body?: unknown;
 }
 
+/**
+ * The `error.code` values an operation documents on its non-2xx answers, read
+ * from the SDK's generated types. A code the kit branches on is declared
+ * against this, so a code the API stops documenting fails `tsc`.
+ */
+export type ApiErrorCode<Op> = Extract<ApiResponse<Op>, { ok: false }>["data"] extends infer D ? (D extends { error: { code: infer C } } ? C : never) : never;
+
+/** The codes both spend routes document; the rail takes either. */
+export type SpendErrorCode = ApiErrorCode<ApiOperation<"/v1/consumers/mandates/{id}/spend", "post">> & ApiErrorCode<ApiOperation<"/v1/consumer-payments/execute", "post">>;
+
+const UNCERTAIN_CODES: readonly SpendErrorCode[] = ["psp_dispatch_uncertain", "psp_attempt_uncertain"];
+
+/** The thrown error's body is `unknown` to the SDK, whatever the route documents; this reads `{ error: { code, message } }` off it without a cast. */
+function errorEnvelope(body: unknown): { code?: string; message?: string } {
+  if (!body || typeof body !== "object" || !("error" in body)) return {};
+  const error = body.error;
+  if (!error || typeof error !== "object") return {};
+  return {
+    ...("code" in error && typeof error.code === "string" ? { code: error.code } : {}),
+    ...("message" in error && typeof error.message === "string" ? { message: error.message } : {}),
+  };
+}
+
 /** Normalise the SDK's two error classes into one readable shape without leaking the body into logs. */
 export function describeApiError(err: unknown): ApiFailure {
   if (err instanceof TimeoutError) return { status: 0, code: "timeout", message: `request timed out after ${err.timeoutMs}ms` };
   if (err instanceof CodesparApiError) {
-    const body = err.body as { error?: { code?: string; message?: string } } | undefined;
+    const envelope = errorEnvelope(err.body);
     return {
       status: err.status,
-      code: err.code ?? body?.error?.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
-      message: body?.error?.message ?? err.message,
+      code: err.code ?? envelope.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: envelope.message ?? err.message,
       body: err.body,
     };
   }
@@ -49,5 +72,5 @@ export function describeApiError(err: unknown): ApiFailure {
 
 /** 5xx, timeouts and `psp_dispatch_uncertain` mean "the money may have moved". */
 export function isUncertain(failure: ApiFailure): boolean {
-  return failure.status === 0 || failure.status >= 500 || failure.code === "psp_dispatch_uncertain" || failure.code === "psp_attempt_uncertain";
+  return failure.status === 0 || failure.status >= 500 || UNCERTAIN_CODES.some((code) => code === failure.code);
 }

package/templates/supplier-payments-agent/packages/agent-core/src/api/mandate-status.ts

@@ -6,26 +6,36 @@
  * the same `csk_test_` client every other call of the kit uses.
  *
  * Fail-closed: this source never throws and never assumes. A transport
- * failure, a timeout, a 404, a 5xx, an unreadable body or a status outside
- * `active | paused | revoked | expired` is reported as `unknown`, and the
- * engine executes nothing on `unknown`.
+ * failure, a timeout, a 404, a 5xx, an unreadable body, a status outside
+ * `active | paused | revoked | expired` or an `org_paused` that is not a
+ * boolean is reported as `unknown`, and the engine executes nothing on
+ * `unknown`.
  *
- * The organization kill switch (`org pauseAll`) has no API surface, so
- * `org_paused` is `false` here: the API cannot say it, and this source does
- * not invent it.
+ * The organization kill switch (ent#1648) answers on the same read:
+ * `org_paused` next to `status`, which stays the mandate's own. A missing
+ * `org_paused` is `unknown`, never "not paused": a deployment that cannot
+ * say whether the organization stopped every spend has not said it did not.
  */
-import type { ApiClient } from "@codespar/sdk";
+import type { ApiOperation, ApiSuccess, ApiClient } from "@codespar/sdk";
 import { z } from "zod";
 import type { MandateStatusReport, MandateStatusSource } from "../revocation.js";
 import { describeApiError } from "./client.js";
 
-/** The two fields of the 14-field projection the gate reads; the rest is passed through untouched. */
+/** `GET /v1/mandates/{id}` as the SDK's generated OpenAPI types it. */
+type MandateRead = ApiSuccess<ApiOperation<"/v1/mandates/{id}", "get">>;
+
+/**
+ * The three fields the gate reads; the rest is passed through untouched.
+ * Bound to the SDK's type, so a field the API renames or retypes breaks the
+ * compile here instead of reading as absent at run time.
+ */
 const MandateReadSchema = z
   .object({
     status: z.enum(["active", "paused", "revoked", "expired"]),
     expires_at: z.string(),
+    org_paused: z.boolean(),
   })
-  .passthrough();
+  .passthrough() satisfies z.ZodType<Pick<MandateRead, "status" | "expires_at" | "org_paused">>;
 
 export class ApiMandateStatusSource implements MandateStatusSource {
   constructor(
@@ -35,7 +45,7 @@ export class ApiMandateStatusSource implements MandateStatusSource {
 
   async check(mandateId: string): Promise<MandateStatusReport> {
     const base = { mandate_id: mandateId, org_paused: false, checked_at: this.clock().toISOString(), source: "api" as const };
-    let body: unknown;
+    let body: MandateRead;
     try {
       body = await this.api.get("/v1/mandates/{id}", { path: { id: mandateId } });
     } catch (err) {
@@ -46,11 +56,17 @@ export class ApiMandateStatusSource implements MandateStatusSource {
           : `GET /v1/mandates/${mandateId} did not answer (${failure.code}): ${failure.message}`;
       return { ...base, status: "unknown", detail };
     }
+    // The type says what the API promises; the parse checks that this answer kept the promise.
     const parsed = MandateReadSchema.safeParse(body);
     if (!parsed.success) {
-      const status = body && typeof body === "object" && "status" in body ? String((body as { status: unknown }).status) : "missing";
-      return { ...base, status: "unknown", detail: `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})` };
+      const unread = parsed.error.issues.map((issue) => issue.path.join(".") || "body");
+      const status = body && typeof body === "object" && "status" in body ? String(body.status) : "missing";
+      const detail = unread.includes("org_paused")
+        ? `GET /v1/mandates/${mandateId} did not say whether the organization is paused (org_paused unreadable)`
+        : `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})`;
+      return { ...base, status: "unknown", detail };
     }
+    if (parsed.data.org_paused) return { ...base, org_paused: true, status: parsed.data.status };
     const expiresAt = new Date(parsed.data.expires_at).getTime();
     const expired = Number.isFinite(expiresAt) && expiresAt <= this.clock().getTime();
     return { ...base, status: expired && parsed.data.status === "active" ? "expired" : parsed.data.status };

package/templates/supplier-payments-agent/packages/agent-core/src/api/rail.ts

@@ -2,8 +2,10 @@
  * The CodeSpar sandbox rail. With the signed envelope the consent returned
  * (`mandate.canonical` + `mandate.signature`) it spends through
  * `POST /v1/consumer-payments/execute`; without it, by mandate id through
- * `POST /v1/consumers/mandates/{id}/spend`. Both are idempotent on
- * `attempt_id`. The by-id route answered `bad_signature` on staging for a
+ * `POST /v1/consumers/mandates/{id}/spend`. Idempotence on both is OPT-IN
+ * and keyed on an explicit `attempt_id`, which every payment here carries: a
+ * spend without one is a fresh payment on every request (ent#1671, #1683).
+ * What a repeat of an attempt answers is in `lookup` below. The by-id route answered `bad_signature` on staging for a
  * mandate carrying `periodic_cap` (OPEN_QUESTIONS §14), which is why the
  * envelope is preferred when it exists. Receipts come back from
  * `GET /v1/consumers/receipts/{id}`.
@@ -14,19 +16,19 @@
  */
 import type { ApiClient } from "@codespar/sdk";
 import type { Mandate } from "../mandate.js";
-import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import { checkQuote } from "../quote.js";
+import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
 import type { Actor } from "../types.js";
-import { describeApiError, isUncertain } from "./client.js";
+import { describeApiError, isUncertain, type SpendErrorCode } from "./client.js";
 
-/** The asymmetric seal as the API serves it, or nulls when this deployment
- *  does not serve one. Never throws on a shape it does not recognise: a
- *  receipt is evidence of a payment that already happened, and refusing to
- *  record it over an unexpected field would trade the record for the proof. */
-function readEd25519Seal(body: unknown): { receipt_sig_ed25519: string | null; receipt_sig_kid: string | null } {
-  const r = body as { receipt_sig_ed25519?: unknown; receipt_sig_kid?: unknown };
-  const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
-  return { receipt_sig_ed25519: str(r.receipt_sig_ed25519), receipt_sig_kid: str(r.receipt_sig_kid) };
-}
+/** Another presentation of this attempt is claimed and has no recorded outcome yet: it may be moving money right now. */
+const ATTEMPT_IN_FLIGHT: SpendErrorCode = "psp_attempt_in_flight";
+/** This attempt failed, moved no money and was compensated; the API will never run this id again. */
+const ATTEMPT_SPENT: SpendErrorCode = "psp_attempt_conflict";
+/** This attempt id was already used for a DIFFERENT payment (checked before its state); nothing was held or sent. */
+const ATTEMPT_ID_CONFLICT: SpendErrorCode = "attempt_id_conflict";
+/** Another project of this organization holds this attempt id; opaque by design, nothing was held or sent. */
+const ATTEMPT_ID_UNAVAILABLE: SpendErrorCode = "attempt_id_unavailable";
 
 export class CodeSparRail implements PaymentRail {
   readonly name = "codespar" as const;
@@ -37,6 +39,12 @@ export class CodeSparRail implements PaymentRail {
   ) {}
 
   async pay(payment: RailPayment): Promise<RailOutcome> {
+    // Without the quote the sealed receipt names no payee (OPEN_QUESTIONS §18), and the API pays a quote that disagrees. Neither goes out.
+    const quoted = checkQuote(payment);
+    if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
+    // Without it the receipt seals no link to what was approved (OPEN_QUESTIONS §3), and the API refuses a malformed one with 400 anyway.
+    const approval = checkSpendApproval(payment);
+    if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
     try {
       const outcome =
         this.envelope?.canonical && this.envelope.signature
@@ -49,11 +57,13 @@ export class CodeSparRail implements PaymentRail {
                 agent_id: payment.agent_id,
                 payee: payment.payee,
                 attempt_id: payment.attempt_id,
+                quote: quoted.quote,
+                approval: approval.approval,
               },
             })
           : await this.api.post("/v1/consumers/mandates/{id}/spend", {
               path: { id: payment.mandate_id },
-              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval },
             });
       return {
         status: "settled",
@@ -61,24 +71,50 @@ export class CodeSparRail implements PaymentRail {
         receipt_id: outcome.receipt?.id ?? null,
         money_moved: outcome.payment.moneyMoved,
         sandbox: !outcome.payment.moneyMoved,
+        ...(outcome.idempotent_replay ? { replayed: true as const } : {}),
         raw: outcome,
       };
     } catch (err) {
       const failure = describeApiError(err);
+      // Not a refusal: the other presentation may already have reached the provider, so "nothing moved" would be a claim nobody can make.
+      if (failure.code === ATTEMPT_IN_FLIGHT) return { status: "uncertain", code: failure.code, message: failure.message };
       if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      if (failure.code === ATTEMPT_SPENT) return { status: "failed", code: failure.code, message: failure.message, spent: true };
+      // Held, never spent: the id belongs to another payment or another project, so no generation may be derived past it.
+      if (failure.code === ATTEMPT_ID_CONFLICT) return { status: "failed", code: failure.code, message: failure.message, held: "conflict" };
+      if (failure.code === ATTEMPT_ID_UNAVAILABLE) return { status: "failed", code: failure.code, message: failure.message, held: "unavailable" };
       return { status: "failed", code: failure.code, message: failure.message };
     }
   }
 
   /**
-   * There is no read route for an attempt. The documented way is to present
-   * the same `attempt_id` again: the lifecycle is idempotent on it and
-   * answers the state it reached. `psp_attempt_in_flight` means the first
-   * presentation is still running.
+   * There is no read route for an attempt: the way to learn what became of
+   * one is to present the same `attempt_id`, with the same payment, again.
+   * Against the deployed API (ent#1671, #1683) that call never moves money
+   * for an attempt it already holds, and each answer maps to one reading:
+   *
+   * - settled: `200` with the ORIGINAL body verbatim (same `transactionId`,
+   *   same stored `receipt.id`, which the receipt route resolves) plus
+   *   `idempotent_replay: true`. Read as `settled`, exactly as the first
+   *   answer, and marked `replayed`.
+   * - `psp_attempt_in_flight` (409): claimed, no outcome yet, on every rail.
+   *   Read as `in_flight`; the next reconcile asks again with the SAME id.
+   * - `psp_attempt_uncertain` (409): pinned, dispatch outcome unknown. Read as
+   *   `uncertain`, which leaves the execution open for a person.
+   * - `psp_attempt_conflict` (409): failed, compensated, no money. Read as
+   *   `failed` and `spent`.
+   * - `attempt_id_conflict` / `attempt_id_unavailable` (409): the id is held for
+   *   a different payment, or by another project. Read as `failed` and `held`,
+   *   never `spent`: nothing was held or sent by this call. Neither can come from re-presenting the
+   *   payment this execution sent, whose tuple is the one the id was claimed
+   *   with, so seeing one here is a defect worth its readable failure.
+   * - an attempt the API never took: there is no record to answer from, so
+   *   this call IS the payment. Reconcile runs only after the outbox row
+   *   flipped to `sent`, so an attempt it looks up was presented once already.
    */
   async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
     const outcome = await this.pay(payment);
-    if (outcome.status === "failed" && outcome.code === "psp_attempt_in_flight") return { status: "in_flight" };
+    if (outcome.status === "uncertain" && outcome.code === ATTEMPT_IN_FLIGHT) return { status: "in_flight" };
     return outcome;
   }
 
@@ -88,7 +124,9 @@ export class CodeSparRail implements PaymentRail {
       return {
         receipt_id: r.receipt_id,
         state: r.state,
-        mandate: { id: r.mandate.id },
+        mandate: { id: r.mandate.id, sig_sha256: r.mandate.sig_sha256 },
+        chain_version: r.chain_version,
+        approval: r.approval ?? null,
         payment: {
           amount_minor: r.payment.amount_minor,
           payee: r.quote?.payee ?? null,
@@ -99,12 +137,10 @@ export class CodeSparRail implements PaymentRail {
         },
         chain: r.chain,
         receipt_sig: r.receipt_sig,
-        // ent#1633 landed after `@codespar/sdk@0.16.6` was generated, so the
-        // typed response does not carry these two yet. Read off the body
-        // defensively rather than pinning a new SDK for two nullable strings:
-        // a deployment that predates the change answers null, which is the
-        // same answer the columns hold and reads as `unsigned`.
-        ...readEd25519Seal(r),
+        // `||`, not `??`: a deployment older than ent#1633 omits both fields,
+        // and an empty string is no signature either. Both read as `unsigned`.
+        receipt_sig_ed25519: r.receipt_sig_ed25519 || null,
+        receipt_sig_kid: r.receipt_sig_kid || null,
         actor,
         raw: r,
       };

package/templates/supplier-payments-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -12,27 +12,12 @@
  * `fetch`, see docs/OPEN_QUESTIONS.md section 31c. The key is checked for
  * the `csk_test_` prefix before a client exists, like every other call.
  */
-import { ApiClient } from "@codespar/sdk";
+import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
 import type { ApiFailure } from "./client.js";
 import { createCodeSparClient, describeApiError } from "./client.js";
 
-export interface SandboxPaidState {
-  charge_id: string;
-  status: "paid";
-  local_status: string;
-  currency: string;
-  quoted_minor: number;
-  paid_minor: number;
-  payment: "full" | "partial" | "over";
-  paid_via: string;
-  wallet_id: string;
-  ledger_entry_id: string | null;
-  event: { id: string; type: string } | null;
-  simulated: boolean;
-  settled_against: string | null;
-  money_moved: false;
-  idempotent_replay: boolean;
-}
+/** What the payer route answers, as the SDK's generated OpenAPI types it. */
+export type SandboxPaidState = ApiSuccess<ApiOperation<"/v1/test/charges/{chargeId}/pay", "post">>;
 
 export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
 

package/templates/supplier-payments-agent/packages/agent-core/src/approval.ts

@@ -13,7 +13,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { dirname, join } from "node:path";
 import { canonicalJson, hexEqual, hmacSha256Hex, itemsHash } from "./hash.js";
 import type { Execution } from "./state-machine.js";
-import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch } from "./types.js";
+import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch, ExecutionComposition } from "./types.js";
 import { newId } from "./ids.js";
 
 export const APPROVAL_KEY_ID = "local-dev-stub";
@@ -78,6 +78,8 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
     // null — on an execution that is not part of a batch, so the payload a
     // bills-agent artifact signs is unchanged by this field existing.
     ...(execution.batch ? { batch: execution.batch } : {}),
+    // What the single amount was composed of, when it was composed of lines. Same rule as `batch`: omitted, never null.
+    ...(execution.composition ? { composition: execution.composition } : {}),
     ...(input.escalation ? { escalation: input.escalation } : {}),
     actor: input.actor,
   };
@@ -89,7 +91,7 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
 
 export type ApprovalCheck =
   | { ok: true }
-  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" };
+  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" | "composition_mismatch" };
 
 /** Two batch bindings are the same binding, or one is absent and so is the other. */
 function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined): boolean {
@@ -97,6 +99,12 @@ function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined)
   return a.ref === b.ref && a.batch_hash === b.batch_hash && a.index === b.index && a.count === b.count;
 }
 
+/** Two compositions are the same binding, or one is absent and so is the other. */
+function sameComposition(a: ExecutionComposition | undefined, b: ExecutionComposition | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.composition_hash === b.composition_hash && a.line_count === b.line_count;
+}
+
 /**
  * The rule that makes the artifact proof: before `executing`, recompute the
  * hash of what is about to be executed and compare it with the artifact.
@@ -118,6 +126,10 @@ export function checkApprovalArtifact(
   // line was one OF. An execution that gained, lost or moved its place in a
   // batch after approval is not the one that was approved.
   if (!sameBatch(artifact.batch, execution.batch)) return { ok: false, problem: "batch_mismatch" };
+  // The item's amount is attested above; this is what that amount was made of.
+  // A cart recomposed at a constant total leaves `items_hash` unchanged and
+  // this hash changed, and that is the only thing that sees it.
+  if (!sameComposition(artifact.composition, execution.composition)) return { ok: false, problem: "composition_mismatch" };
   if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
   return { ok: true };
 }

package/templates/supplier-payments-agent/packages/agent-core/src/bundle.ts

@@ -5,6 +5,7 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { canonicalJson } from "./hash.js";
 import type { Mandate } from "./mandate.js";
 import type { RailReceipt } from "./rail.js";
 import type { ApprovalArtifact } from "./types.js";
@@ -97,11 +98,18 @@ export class ProofBundle {
     writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
   }
 
-  /** Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it. */
-  receipt(receipt: RailReceipt): string {
+  /**
+   * Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it.
+   *
+   * `approval_id` names the artifact in `approval.json` whose hashes the spend carried, so `npm run verify` holds the receipt's sealed
+   * approval link against THAT artifact, found by identity and never by looking for one whose hash happens to match. The copy stays
+   * masked: binding its body to the chain needs the unmasked read, which `verify --from-api` takes from the API and writes nowhere.
+   */
+  receipt(receipt: RailReceipt, context: { approval_id?: string | undefined } = {}): string {
     const relative = join("receipts", `${receipt.receipt_id}.json`);
     const { raw: _raw, ...safe } = receipt;
-    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
+    const copy = { ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null }, ...(context.approval_id ? { approval_id: context.approval_id } : {}) };
+    writeFileSync(join(this.dir, relative), JSON.stringify(copy, null, 2) + "\n");
     return relative;
   }
 
@@ -149,6 +157,30 @@ function readdirSorted(dir: string): string[] {
     .sort();
 }
 
+/**
+ * Where the bundle's masked copy of a receipt says something the API's read of the same receipt does not. The copy is not what the
+ * signature covers, so a copy edited after the fact still verifies at the signature level; this is what catches it once the read is
+ * in hand. The payee is compared masked, the only form the copy holds. An empty list means the copy is a faithful mask of the read.
+ */
+export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Record<string, unknown>): string[] {
+  const field = (o: unknown, k: string): unknown => (o && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined);
+  const readPayee = field(read["quote"], "payee");
+  const expected: Array<[string, unknown, unknown]> = [
+    ["receipt_id", copy["receipt_id"], read["receipt_id"]],
+    ["chain", copy["chain"], read["chain"]],
+    ["mandate.id", field(copy["mandate"], "id"), field(read["mandate"], "id")],
+    ["payment.amount_minor", field(copy["payment"], "amount_minor"), field(read["payment"], "amount_minor")],
+    ["payment.attempt_id", field(copy["payment"], "attempt_id"), field(read["payment"], "attempt_id")],
+    ["payment.money_moved", field(copy["payment"], "money_moved"), field(read["payment"], "money_moved")],
+    ["payment.at", field(copy["payment"], "at"), field(read["payment"], "at")],
+    ["payment.payee", field(copy["payment"], "payee"), typeof readPayee === "string" ? maskPayee(readPayee) : null],
+  ];
+  // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
+  if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
+  if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
+}
+
 /** `escola@exemplo.com.br` -> `es***@exemplo.com.br`; `+5511999998888` -> `+55***8888`; a UUID keeps its first and last 4. */
 export function maskPayee(payee: string): string {
   if (payee === "*") return payee;