@codespar/cli 0.17.0 → 0.18.0

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

@@ -17,28 +17,34 @@
  *                          reconciling a payout, or a court — parties that
  *                          have no relationship with CodeSpar at all.
  *
- * This module checks the second. It imports `node:crypto` and nothing else: no
+ * This module checks the second. It imports `node:crypto` and two modules of
+ * this package that import nothing else (`receipt-chain`, `hash`): no
  * CodeSpar SDK, no key material, no token, no network of its own (the key
  * document is passed in, or fetched by a function the caller supplies). A
  * third party can read the forty lines that matter and reimplement them.
  *
- * WHAT A `verified` VERDICT PROVES, exactly: CodeSpar sealed a receipt with
- * THIS id and THIS chain. The chain is a SHA-256 over the four links of the
- * Control Record, so the seller, the amount and the payee are inside it — but
- * recomputing that digest from the receipt body needs the canonical link
- * shapes, which CodeSpar does not publish today. Binding the body to the chain
- * is therefore not something this module can promise, and it does not pretend
- * to: see `docs/OPEN_QUESTIONS.md` §47. It is also why the signature survives
- * the proof bundle's masking — the bundle masks the payee, and the signature
- * covers the id and the digest, not the copy in front of you.
+ * TWO LAYERS, and a verdict says which one it reached. The signature proves
+ * CodeSpar sealed a receipt with THIS id and THIS chain; `verifyReceiptWithKeys`
+ * checks that and nothing else, which is why it survives the proof bundle's
+ * masking — the bundle masks the payee, and the signature covers the id and
+ * the digest, not the copy in front of you. The chain is a SHA-256 over the
+ * links of the Control Record, and since ent#1670 CodeSpar publishes how to
+ * recompute it (`chain_recipe`, beside the keys). `verifyReceiptRead` does:
+ * from the API's receipt READ, under the recipe of the SAME document whose
+ * key verified the signature, it recomputes the chain and holds it against
+ * the signed one — and for a v4 chain, holds the sealed approval link against
+ * the local approval artifact. `verified` from it means all of that held;
+ * `signature_only` means the signature held and the body could not be bound
+ * (a v1–v3 chain, a masked payee, no recipe), which is not a failure and is
+ * not a verification of the body either. See `docs/OPEN_QUESTIONS.md` §47.
  *
- * WHICH KEY SET. `kid` is `<did>#<n>` and the DID is the platform's, so it is
- * the same string on every deployment while the KEY behind it is not: a
- * sandbox receipt checked against the production key set finds a key of that
- * name, fails to verify, and reads `tampered`. The verifier therefore points
- * at ONE deployment's `/.well-known/codespar-receipt-keys.json` — the default
- * is production, and `--url` names another. Nothing in the two documents tells
- * them apart today; `docs/OPEN_QUESTIONS.md` §47 says so and names the ask.
+ * WHICH KEY SET. The verifier points at ONE deployment's
+ * `/.well-known/codespar-receipt-keys.json` — the default is production, and
+ * `--url` names another. Since ent#1641 a deployment names its keys by
+ * namespace (`#production-2`, `#staging-2`), so a receipt checked against the
+ * wrong set finds no key of its name (`unknown_key`); the retired `#1` is
+ * still published by both with different keys, and a receipt sealed under it
+ * checked against the wrong set reads `tampered`. `docs/OPEN_QUESTIONS.md` §47.
  *
  * The signed string is the enterprise's `receiptSigningString`
  * (`packages/api/src/receipt-signature.ts`, ent#1633), reproduced here rather
@@ -46,6 +52,9 @@
  * proves nothing about the signer.
  */
 import { createPublicKey, verify as verifyDetached } from "node:crypto";
+import { itemsHash } from "./hash.js";
+import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type SealedApproval } from "./receipt-chain.js";
+import type { ExecutionItem } from "./types.js";
 
 /** The domain tag. A receipt names the version it was sealed under through
  *  this literal, so a future `v2` does not invalidate a `v1` signature. */
@@ -86,8 +95,51 @@ export function receiptSigningString(receiptId: string, chain: string): string {
  *                  arbitrary JSON file would state that it is a receipt from
  *                  before the capability existed, which is a claim about a
  *                  file nobody checked.
+ *
+ * And three that only the body check (`verifyReceiptRead`) reaches, each
+ * after the signature verified:
+ *
+ *   `signature_only`     the body could not be bound to the chain: a v1–v3
+ *                        chain, a masked payee, no read, no recipe. NOT a
+ *                        failure, and NOT `verified`: the signature is
+ *                        CodeSpar's, and nothing here says the body beside it
+ *                        is the body it sealed.
+ *   `chain_mismatch`     the body, recomputed under the published recipe, is
+ *                        NOT the signed chain. The signature is genuine and
+ *                        the body in front of you is not the one it covers.
+ *   `approval_mismatch`  the body is the signed one, and the approval link it
+ *                        seals is NOT the local artifact's: this payment was
+ *                        not sealed against the list that artifact approved.
  */
-export type ReceiptVerdict = "verified" | "tampered" | "unsigned" | "unknown_key" | "unreachable" | "malformed";
+export type ReceiptVerdict = "verified" | "tampered" | "unsigned" | "unknown_key" | "unreachable" | "malformed" | "signature_only" | "chain_mismatch" | "approval_mismatch";
+
+/** What recomputing the chain from the body found. */
+export interface ChainCheck {
+  /** `recomputed`: equal to the signed chain. `mismatch`: not equal. `not_recomputed`: see `reason`. */
+  status: "recomputed" | "mismatch" | "not_recomputed";
+  version: number | null;
+  /** The digest recomputed from the body, when it could be. */
+  recomputed: string | null;
+  reason: string;
+}
+
+/** What the sealed approval link was held against. Present on a v4 chain that recomputed. */
+export interface ApprovalLinkCheck {
+  /** `matched`: the artifact's hashes are the sealed ones. `mismatch`: they are not. `not_compared`: no artifact was given. */
+  status: "matched" | "mismatch" | "not_compared";
+  sealed: SealedApproval;
+  artifact: { approval_id: string; items_hash: string; batch_hash: string | null } | null;
+  reason: string;
+}
+
+/** The part of an approval artifact the approval link is held against: what was approved, never who. */
+export interface ApprovalClaim {
+  approval_id: string;
+  items_hash: string;
+  /** When present, `items_hash` is recomputed from them first: a hash that does not describe its own list proves nothing about the list. */
+  items?: readonly ExecutionItem[];
+  batch?: { batch_hash: string };
+}
 
 export interface ReceiptVerification {
   verdict: ReceiptVerdict;
@@ -106,6 +158,9 @@ export interface ReceiptVerification {
   reason: string;
   /** One sentence for a person. Never a stack trace. */
   message: string;
+  /** The body check, when one was attempted: only `verifyReceiptRead` attempts it, and only on a signature that verified. */
+  chain_check?: ChainCheck;
+  approval_check?: ApprovalLinkCheck;
 }
 
 /** One published key, RFC 8037 shape, as the JWKS serves it. */
@@ -398,4 +453,125 @@ export const VERDICT_EXIT_CODES: Record<ReceiptVerdict, number> = {
   unknown_key: 4,
   unreachable: 5,
   malformed: 6,
+  signature_only: 7,
+  chain_mismatch: 8,
+  approval_mismatch: 9,
 };
+
+/* ── The body: the chain recomputed from the read ────────────── */
+
+/** The first chain version that seals `sha256(mandate.sig)` instead of the signature, and the approval link. */
+export const FIRST_THIRD_PARTY_CHAIN_VERSION = 4;
+
+/** Whether a JSON is the API's receipt read, rather than the proof bundle's masked copy of one: only the read carries the links. */
+export function isReceiptRead(input: unknown): input is Record<string, unknown> {
+  if (!isRecord(input)) return false;
+  const mandate = input["mandate"];
+  const payment = input["payment"];
+  return isRecord(mandate) && "nonce" in mandate && isRecord(payment) && "rail" in payment;
+}
+
+/** A verified signature whose body could not be bound: `signature_only`, with the reason. */
+export function signatureOnly(signature: ReceiptVerification, reason: string, why: string, version: number | null = null): ReceiptVerification {
+  return {
+    ...signature,
+    verdict: "signature_only",
+    reason,
+    message: `receipt ${signature.receipt_id ?? "(no id)"} carries CodeSpar's signature over its id and chain, and its body is NOT bound to that chain: ${why}`,
+    chain_check: { status: "not_recomputed", version, recomputed: null, reason },
+  };
+}
+
+/**
+ * Verify a receipt READ — the JSON of `GET /v1/consumers/receipts/{id}` —
+ * against a key set already in hand: the signature, then the body, then the
+ * approval. Synchronous and offline, like `verifyReceiptWithKeys`.
+ *
+ * The recipe is taken from the SAME document whose key verified the
+ * signature, never from another: each deployment names its keys by
+ * namespace (§47), so a document that verified the signature is the sealing
+ * deployment's, and its recipe is the one that sealed.
+ *
+ * A v1–v3 chain is never recomputed here, even from a tenant's read that
+ * carries `mandate.sig`: that signature is a bearer proof (it authorizes
+ * spends), a verifier has no business handling it, and the API is retiring
+ * it from the read. Those chains also predate the API's timestamp fix
+ * (ent#1670), so some of them no longer recompute from their read at all —
+ * and a mismatch there would accuse a genuine receipt. They answer
+ * `signature_only`, never `verified` and never `chain_mismatch`.
+ */
+export function verifyReceiptRead(read: unknown, keyDocument: unknown, options: { label?: string; approval?: ApprovalClaim } = {}): ReceiptVerification {
+  const signature = verifyReceiptWithKeys(read, keyDocument, options.label ?? "file");
+  if (signature.verdict !== "verified" || !isRecord(read)) return signature;
+  if (!isReceiptRead(read)) return signatureOnly(signature, "read_required", "this is not the API's receipt read (the proof bundle's copy masks the payee and carries none of the links); recompute from `GET /v1/consumers/receipts/{id}`");
+
+  const recipe = readChainRecipe(keyDocument);
+  if (!recipe.ok) return signatureOnly(signature, recipe.reason, recipe.message);
+
+  const versionRaw = read[recipe.recipe.version.field];
+  if (typeof versionRaw === "number" && versionRaw < FIRST_THIRD_PARTY_CHAIN_VERSION) {
+    return signatureOnly(
+      signature,
+      "mandate_sig_required",
+      `the chain is not recomputable without the mandate signature. Chain v${versionRaw} seals the mandate's raw signature, a bearer proof this verifier does not take; and a receipt sealed before ent#1670 may not recompute from its read at all. It carries no approval link either: that starts at v${FIRST_THIRD_PARTY_CHAIN_VERSION}`,
+      versionRaw,
+    );
+  }
+
+  const recomputed = recomputeChain(read, recipe.recipe);
+  if (!recomputed.ok) return signatureOnly(signature, recomputed.reason, recomputed.message, recomputed.version);
+  const sealedChain = read["chain"];
+  if (recomputed.chain !== sealedChain) {
+    return {
+      ...signature,
+      verdict: "chain_mismatch",
+      reason: "body_does_not_recompute",
+      message: `receipt ${signature.receipt_id} carries a genuine CodeSpar signature over chain ${sealedChain}, and the body beside it recomputes to ${recomputed.chain} under the published recipe (v${recomputed.version}): this body is not the one that was sealed. A payee, an amount, a timestamp or the approval was changed after sealing`,
+      chain_check: { status: "mismatch", version: recomputed.version, recomputed: recomputed.chain, reason: "body_does_not_recompute" },
+    };
+  }
+  const chainCheck: ChainCheck = { status: "recomputed", version: recomputed.version, recomputed: recomputed.chain, reason: "body_recomputes" };
+  const bound = `the body recomputes to the signed chain under the published recipe (v${recomputed.version})`;
+
+  const sealed = readSealedApproval(read);
+  if (!sealed) {
+    // Unreachable through the published recipe (v4 seals the link, and a read without it fails the recomputation above), kept so a future version is not misread.
+    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck };
+  }
+  const approval = options.approval;
+  if (!approval) {
+    return {
+      ...signature,
+      reason: "body_recomputes",
+      message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}. It seals the approval ${sealed.items_hash}${sealed.batch_hash ? ` (batch ${sealed.batch_hash})` : ""}; no approval artifact was given to hold it against`,
+      chain_check: chainCheck,
+      approval_check: { status: "not_compared", sealed, artifact: null, reason: "no_artifact" },
+    };
+  }
+
+  const artifact = { approval_id: approval.approval_id, items_hash: approval.items_hash, batch_hash: approval.batch?.batch_hash ?? null };
+  const mismatch = (reason: string, why: string): ReceiptVerification => ({
+    ...signature,
+    verdict: "approval_mismatch",
+    reason,
+    message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}, and ${why}: this payment was not sealed against the list artifact ${approval.approval_id} approved`,
+    chain_check: chainCheck,
+    approval_check: { status: "mismatch", sealed, artifact, reason },
+  });
+  if (approval.items && itemsHash(approval.items) !== approval.items_hash) {
+    return mismatch("artifact_items_hash_inconsistent", `the artifact's items_hash ${approval.items_hash} is not the hash of the items it lists (${itemsHash(approval.items)})`);
+  }
+  if (!sameApprovalHash(sealed.items_hash, artifact.items_hash)) {
+    return mismatch("items_hash_differs", `it seals items_hash ${sealed.items_hash} where the artifact carries ${artifact.items_hash}`);
+  }
+  if (!sameApprovalHash(sealed.batch_hash, artifact.batch_hash)) {
+    return mismatch("batch_hash_differs", `it seals batch_hash ${sealed.batch_hash ?? "none"} where the artifact carries ${artifact.batch_hash ?? "none"}`);
+  }
+  return {
+    ...signature,
+    reason: "approval_matches",
+    message: `receipt ${signature.receipt_id} was sealed by CodeSpar, ${bound}, and it was paid against the list artifact ${approval.approval_id} approved (${sealed.items_hash}${sealed.batch_hash ? `, batch ${sealed.batch_hash}` : ""}). WHO approved it is in the artifact, under a local key, and nowhere in the seal`,
+    chain_check: chainCheck,
+    approval_check: { status: "matched", sealed, artifact, reason: "approval_matches" },
+  };
+}

package/templates/supplier-payments-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/supplier-payments-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/supplier-payments-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/supplier-payments-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/supplier-payments-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" });
     }
   });