@cmdoss/suipay-mcp 0.2.2-dev.9 → 0.3.0-dev.0

package/dist/http-BCFfQFIg.d.ts

@@ -0,0 +1,4786 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+/**
+ * Resolve which grant policy target may pay a seller offer's targetHash (WS7.6).
+ *
+ * SINGLE SOURCE — consent validation and MCP pay MUST use this helper.
+ * Never inline "find policy by hash" in tools or consent UI.
+ *
+ * Seller offer carries targetHash only (no buyer policyId). Buyer authority
+ * is the OAuth grant snapshot of policies/targets at consent time.
+ */
+type GrantLifecycleStatus = 'pending' | 'active' | 'paused' | 'revoked' | 'expired';
+type PolicyLifecycleStatus = 'draft' | 'active' | 'paused' | 'revoked';
+interface GrantTargetBinding {
+    /** 32-byte hex target hash. */
+    targetHash: string;
+    /** Optional per-target ceiling (atomic units). */
+    maxPerPayment?: string;
+    /**
+     * The address this target pays, when the authority source records one.
+     * Carried for callers that want to pin the payee before signing; target
+     * resolution itself matches on {@link targetHash} alone, because the offer's
+     * `payTo` is what the settlement actually pays.
+     */
+    recipient?: string;
+}
+interface GrantPolicyBinding {
+    /** Off-chain policy id (for audit). */
+    policyId: string;
+    /** On-chain policy id (u64) inside SpendAccount. */
+    onChainPolicyId: number | string;
+    status: PolicyLifecycleStatus;
+    targets: readonly GrantTargetBinding[];
+}
+/**
+ * Immutable snapshot of buyer authority for one OAuth grant.
+ * Pool/grant object ids come from finalized on-chain objects (or fake in WS6B).
+ */
+interface GrantSnapshot {
+    grantId: string;
+    status: GrantLifecycleStatus;
+    grantObjectId: string | null;
+    poolObjectId: string;
+    coinType: string;
+    delegateAddress: string;
+    policies: readonly GrantPolicyBinding[];
+    /**
+     * `open` = open-recipient (no allowlist, caps required); `scoped` / omit = policy-bound.
+     */
+    accessMode?: 'scoped' | 'open';
+    /** Grant-level max per payment (atomic); used for open and as a grant ceiling. */
+    maxPerPayment?: string | null;
+    /** Grant-level session cap (atomic); open requires a positive value. */
+    sessionCap?: string | null;
+}
+type ResolveGrantTargetResult = {
+    ok: true;
+    policyId: string;
+    onChainPolicyId: number | string;
+    targetHash: string;
+    maxPerPayment?: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    coinType: string;
+    delegateAddress: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pick the policy target that matches offer.targetHash under an active grant.
+ * Pause/revoke of grant or policy fails closed without decrypting the delegate.
+ */
+declare function resolveGrantTarget(snapshot: GrantSnapshot, offerTargetHash: string): ResolveGrantTargetResult;
+
+/**
+ * Public authorization facts exposed to authenticated MCP clients.
+ *
+ * This shape is descriptive only. Payment authorization continues to use the
+ * immutable on-chain GrantSnapshot; callers must never derive spend authority
+ * from this object.
+ */
+interface McpAccessProfile {
+    id: string;
+    name: string;
+    status: 'active' | 'disabled';
+}
+interface McpAccessTarget {
+    serviceId: string;
+    /** Friendly seller service name (live catalog), or serviceId if unresolved. */
+    name: string;
+    endpointId: string;
+    method: string;
+    path: string;
+    targetHash: string;
+    maxPerPayment: string;
+}
+interface McpAccessPolicy {
+    id: string;
+    name: string;
+    status: 'draft' | 'active' | 'paused' | 'revoked';
+    asset: string;
+    coinType: string;
+    totalCap: string;
+    spent: string;
+    maxPerPayment: string;
+    expiresAt: string | null;
+    targets: McpAccessTarget[];
+}
+interface McpAccessContext {
+    accessMode: 'scoped' | 'open';
+    grant: {
+        id: string;
+        status: 'pending' | 'active' | 'paused' | 'revoked' | 'expired';
+        sessionCap: string | null;
+        sessionSpent: string;
+        expiresAt: string | null;
+    };
+    profiles: McpAccessProfile[];
+    policies: McpAccessPolicy[];
+}
+
+/**
+ * Settlement rail identity + authority (WS7.1 / WS7.2 single source).
+ *
+ * Consumers MUST import `SettlementRail` / `SettlementRailAuthority` from here
+ * - do not redefine rail strings or package/module/function lookups inline.
+ *
+ * `dialectModes` is the rail CAPABILITY CEILING (what the rail can do per
+ * dialect). `supportedDialects` is DERIVED as `Object.keys(dialectModes)` -
+ * ONE SSOT, no parallel array to drift.
+ *
+ * Demo ships SpendAccount as MPP-only. WS12 dual-dialect (x402 on delegate)
+ * is STRETCH and must stay behind an explicit rollout flag, default off.
+ *
+ * Keep `spendAccountSponsorTargets()` SEPARATE - that is lifecycle sponsorship,
+ * not settlement authority.
+ */
+
+/**
+ * Wire tokens for settlement rails. Three engines, three tokens: `direct`,
+ * `delegate`, and `recurring` (mandate rail; HTTP mint + Move `RAIL_TAG`).
+ * The Move *module* is still `subscription`; that name is not a wire rail.
+ * V1 `allowance` and `auth_capture` are not members: they do not decode.
+ */
+declare const SETTLEMENT_RAILS: readonly ["direct", "delegate", "recurring"];
+type SettlementRail = (typeof SETTLEMENT_RAILS)[number];
+/**
+ * The delegation SCOPE discriminator: which `spend_account` pay surface a
+ * delegate draws on, and so which on-chain function settles the payment.
+ *
+ *  - `'scoped'`  — policy scope. The grant carries a policy allowlist; the
+ *                  payment resolves a target and settles via
+ *                  `settle_policy`.
+ *  - `'open'`    — any-recipient scope. No allowlist; the caps are the only
+ *                  limit; settles via `settle_any_recipient`.
+ *
+ * This is ONE of three orthogonal concepts that must never be conflated:
+ *  - SCOPE       — this type, `accessMode` (which pay function / recipient
+ *                  surface). Selects the on-chain entry point.
+ *  - ELIGIBILITY — `SpendAccountGrantKind` (`'GrantCap' | 'SpendGrant'`), the
+ *                  x402 grant-object discriminator. A separate field.
+ *  - CAP         — the budget (`maxPerPayment` / total), a separate field.
+ *
+ * The string VALUES `'scoped'`/`'open'` are FROZEN: they persist in the
+ * `access_mode` DB column (legacy `profile_bound`/`catalog_open` already
+ * normalize onto them) and ride the non-signed `PreparedSettlement` 402-body
+ * field. They are NOT part of any signed/hashed payload — the scope selects a
+ * Move function via `spendAccountDebitFunction`; the string itself is never a
+ * serialized argument — so this type names the concept without touching the
+ * wire. Rename the VALUES only as a deliberate wire+DB migration, not here.
+ */
+type DelegationScope = 'scoped' | 'open';
+
+/**
+ * Shared vocabulary for both 402 dialects.
+ *
+ * The central claim of this PoC is that MPP and x402 are two encodings of one
+ * payment offer, not two payment systems. Everything below the dialect codecs
+ * therefore speaks in these types; only `mpp.ts` and `x402.ts` know about
+ * headers and JSON bodies.
+ */
+
+/**
+ * Digest canonicalization version.
+ * v1 = legacy direct wire;
+ * v2 = two-layer SpendAccount fields;
+ * v3 = additive body binding (bodyHash, contentType) + subscription mandate
+ *      (intent, periodMs, periodCount) fields (does not break v1/v2);
+ * v4 = additive cross-rail-exclusion binding: the normalized accepted-rail set
+ *      plus the exclusion protocol version and canonical registry identity the
+ *      offer commits to (does not break v1/v2/v3). Never the derived exclusion
+ *      key — that is computed inside Move, never on the wire.
+ */
+type OfferDigestVersion = 1 | 2 | 3 | 4;
+/** Payment intent on a signed offer. Default / omitted = one-shot charge. */
+type PaymentIntent = 'charge' | 'subscription';
+/** What the provider is willing to be paid, for one specific request. */
+interface Offer {
+    /** Single-use id. Both dialects carry this same value — the binding this PoC demonstrates. */
+    challengeId: string;
+    /** Absolute URL of the resource being sold. */
+    resource: string;
+    /** Human-readable description of the resource. */
+    description: string;
+    /** Content type the payer receives on success. */
+    mimeType: string;
+    /**
+     * Gross amount the buyer pays, in the asset's smallest unit, as a decimal
+     * string (no float rounding). Equals `netAmount + platformFee`.
+     */
+    amount: string;
+    /**
+     * Seller-declared net price (atomic units). Explicit even when equal to
+     * `amount` so fee semantics stay visible. Optional on legacy decoded offers
+     * that predate fee fields. Signed under digest v2.
+     */
+    netAmount?: string;
+    /**
+     * Facilitator-owned platform fee (atomic units). PoC is `"0"`; field is
+     * still present on freshly minted offers. Signed under digest v2.
+     */
+    platformFee?: string;
+    /** Fully-qualified Move coin type, e.g. `0x2::sui::SUI`. */
+    asset: string;
+    /** Decimal places of `asset`, for display only. */
+    decimals: number;
+    /** CAIP-2-style network id, e.g. `sui:testnet`. */
+    network: string;
+    /** Address that receives the funds. */
+    payTo: string;
+    /** Move package implementing the rail pay function. */
+    packageId: string;
+    /** Epoch ms. */
+    issuedAt: number;
+    /** Epoch ms. After this the offer is dead and must be re-fetched. */
+    expiresAt: number;
+    /**
+     * Canonicalization version for `digest`. Omitted / 1 = legacy fields only
+     * (existing wire format). 2 = includes settlementRail, service snapshot,
+     * method/path, and fee fields under the HMAC (WS7.3). 3 = adds the optional
+     * body-binding and subscription-mandate fields (additive; v1/v2 unchanged).
+     */
+    digestVersion?: OfferDigestVersion;
+    /** Settlement rail (signed in v2+). Never carries buyer policy/grant/pool. */
+    settlementRail?: SettlementRail;
+    /** Seller service id from one immutable registry snapshot (v2). */
+    serviceId?: string;
+    /** Active revision of that service snapshot (v2). */
+    serviceRevision?: number;
+    /** On-chain policy target hash hex (v2; delegate). */
+    targetHash?: string;
+    /** Authorization epoch bound into targetHash (v2; same snapshot). */
+    authorizationEpoch?: number;
+    /** HTTP method of the paid request (v2). */
+    method?: string;
+    /** Public path of the paid request (v2). */
+    path?: string;
+    /**
+     * Canonical hash of the paid request body (v3), base64url SHA-256 as produced
+     * by `hashRequestBody`. Present on body-bearing offers only; a GET offer omits
+     * it. Signing it is what stops a paid credential being replayed against
+     * different bytes.
+     */
+    bodyHash?: string;
+    /**
+     * Content type of the paid request body (v3), normalized. Signed alongside
+     * `bodyHash` so the seller executes the body under the type it was paid for.
+     */
+    contentType?: string;
+    /**
+     * Payment intent (v3). `charge` = one-shot; `subscription` = period mandate.
+     * Omitted on v1/v2 offers.
+     */
+    intent?: PaymentIntent;
+    /** Billing period length in ms (v3; required when intent=subscription). */
+    periodMs?: number;
+    /** Maximum billable periods (v3; required when intent=subscription). */
+    periodCount?: number;
+    /**
+     * Opt-in dispute-window vault settlement (ADR-0007).
+     * When true, settlement opens a RefundVault instead of paying the merchant.
+     * Omit / false keeps today's non-refundable path. Signed under v3 when present
+     * (omit-when-absent, same rule as subscription fields).
+     */
+    refundable?: boolean;
+    /**
+     * Refund window length in ms (v3). Deposit + this = release_at_ms.
+     * Required when refundable=true; omit-when-absent for non-refundable digests.
+     */
+    refundWindowMs?: number;
+    /**
+     * Delivery-decision window length in ms (v3). Deposit + this = decide_by_ms.
+     * Must be strictly less than refundWindowMs. Omit-when-absent.
+     */
+    decideWindowMs?: number;
+    /**
+     * Sui chain id (u64) for payment_key derivation. Required when refundable.
+     * Signed under v3 when present (omit-when-absent).
+     */
+    chainId?: number;
+    /**
+     * Per-payment salt for payment_key (utf8). Gateway mints; buyer echoes.
+     * Signed under v3 when present (omit-when-absent).
+     */
+    paymentSalt?: string;
+    /**
+     * Pinned refund destination expected on VaultOpened. When omitted on a
+     * refundable offer, facilitators default to the rail-derived beneficiary
+     * (pool owner / payer). Signed under v3 when present (omit-when-absent).
+     */
+    refundTo?: string;
+    /**
+     * Optional override for the rail-specific settlement_ref bytes in
+     * payment_key. When omitted, facilitators default to challengeId (direct)
+     * or the rail's on-chain identity (terms_hash for delegate).
+     * Signed under v3 when present (omit-when-absent).
+     */
+    settlementRef?: string;
+    /**
+     * Offer-pinned sponsor gas for delegate x402 (transaction mode).
+     * Omit-when-absent under digest v2+ so MPP-only offers keep byte-identical
+     * digests. When present, the agent must build TransactionData.gasData to
+     * match exactly, and the gateway precheck asserts equality.
+     */
+    sponsorGasOwner?: string;
+    /** Atomic units (decimal string), pinned gas budget. */
+    sponsorGasBudget?: string;
+    /** Atomic units (decimal string), pinned gas price. */
+    sponsorGasPrice?: string;
+    /**
+     * Compact reserved gas coin ref(s):
+     * `objectId@version@digest` joined by `,` (stable, HMAC-safe).
+     */
+    sponsorGasPayment?: string;
+    /**
+     * Cross-rail-exclusion accepted-rail set (v4). The normalized, ordered,
+     * deduped rails the offer is issued for. Unsigned before v4; signing it under
+     * v4 makes the multi-rail-with-delegate capability consensus-bound — a
+     * tampered set fails verification. Omit-when-absent under the v4 HMAC.
+     */
+    acceptedRails?: SettlementRail[];
+    /**
+     * Exclusion-protocol version the offer commits to (v4). The on-chain mutual
+     * exclusion the guarded settle path consumes is versioned; the offer pins
+     * which version it was minted against. Omit-when-absent under the v4 HMAC.
+     */
+    exclusionProtocolVersion?: number;
+    /**
+     * Canonical exclusion directory/registry identity the offer commits to (v4):
+     * the module-created directory and package the guarded settle resolves the
+     * recipient registry through, as one opaque canonical string (e.g.
+     * `packageId::directoryId`). Never the derived exclusion key. Omit-when-absent
+     * under the v4 HMAC.
+     */
+    registryIdentity?: string;
+    /** HMAC over the versioned canonical form. Detects tampering in transit. */
+    digest: string;
+}
+/** Proof of settlement, returned alongside the resource. */
+interface Receipt {
+    challengeId: string;
+    /** On-chain transaction digest. */
+    txDigest: string;
+    network: string;
+    payer: string;
+    /** Gross amount settled (atomic units). */
+    amount: string;
+    asset: string;
+    status: 'settled';
+    /**
+     * Merchant address the native-transfer path paid. Absent on the event path,
+     * where PaymentMade.recipient is the evidence.
+     */
+    payTo?: string;
+    /**
+     * Canonical requestDigest this settlement paid for. Bound to `txDigest` so
+     * a receipt proves one specific HTTP request was settled on chain.
+     */
+    requestDigest?: string;
+    /** Seller net proceeds (atomic units). Explicit fee semantics; PoC equals amount. */
+    netAmount?: string;
+    /** Facilitator platform fee (atomic units). PoC is `"0"`. */
+    platformFee?: string;
+    /** Payment intent when settled via a non-charge flow (e.g. subscription). */
+    intent?: PaymentIntent;
+    /** Subscription mandate object id when intent=subscription. */
+    mandateId?: string;
+    /** Clock-derived period index that was charged (subscription). */
+    periodIndex?: string;
+    /**
+     * Canonical payment_key hex when settlement opened a RefundVault (refundable).
+     * Used as the durable delivery-success key and operator-refund identity.
+     */
+    paymentKey?: string;
+    /** Shared vault object id when refundable. */
+    vaultId?: string;
+    /** Pinned refund beneficiary from VaultOpened when refundable. */
+    refundTo?: string;
+    /**
+     * Canonical grant object id (on-chain Move type: `Grant<T>`) this settlement
+     * drew against (delegate rail only). `padObjectId` form — the SAME identity
+     * the session receipt ledger keys by (`sessionIdForGrant`), so the durable
+     * projection and the session ledger converge on one grant id. Absent for
+     * non-delegate rails and refundable-vault settlements, which carry no
+     * PaymentMade grant.
+     */
+    grantId?: string;
+    /**
+     * Canonical spend-account object id (`Account<T>`) the grant draws from
+     * (delegate rail only). Absent wherever `grantId` is.
+     */
+    poolId?: string;
+}
+/** Which encoding a message used. Recorded so the provider can answer in kind. */
+type Dialect = 'mpp' | 'x402';
+
+/**
+ * The settled-payment DTO.
+ *
+ * Shared vocabulary: the gateway produces it, `@cmdoss/suipay-mcp` consumes it.
+ * Only the shape lives here — the gateway's read-model mappers and row types
+ * stay in `apps/gateway/src/buyer/settlement-dto.ts`, which re-exports this.
+ */
+
+interface SettlementDTO {
+    at: string;
+    resourceId?: string;
+    recipient: string;
+    dialect?: Dialect;
+    receipt: {
+        challengeId: string;
+        txDigest: string;
+        network: string;
+        payer: string;
+        amount: string;
+        asset: string;
+        status: 'settled';
+    };
+    /**
+     * Present only on the live in-memory feed. The read model dedups on
+     * (network, digest), so a durable row is never a replay — the field is
+     * omitted there rather than asserted false. Consumers must treat absent as
+     * not-replayed.
+     */
+    replayed?: boolean;
+}
+
+/**
+ * Authenticated MCP request context (remote Streamable HTTP).
+ * Bearer is required on /mcp; tools enforce scope from the resolved grant.
+ */
+
+/**
+ * Read/prepare-only shared-pool context for an authenticated MCP bearer.
+ *
+ * Non-custodial: the gateway holds NO key that can spend. There is deliberately
+ * no `decryptDelegateSeed` and no forwarded `sponsorAuthorization` here — the
+ * `pay` tool only PREPARES an unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction from the
+ * immutable grant snapshot (`prepareSpendAccountPayment`), and the client that
+ * holds the delegate key signs locally and submits. Only signatures ever reach
+ * the gateway. See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
+ */
+interface McpSpendAccountPayAuth {
+    snapshot: GrantSnapshot;
+    packageId: string;
+    /**
+     * Re-verify the paying authority against a FRESH graph + injected clock at
+     * prepare time. Throws on drift/expiry so the pay tool refuses to hand back a
+     * signing request for a grant that just went paused/revoked/expired. Optional:
+     * absent for legacy/local paths.
+     */
+    assertLive?: () => Promise<void>;
+}
+interface McpAuthContext {
+    grantId: string;
+    buyerAccountId: string;
+    /** Space-separated scopes from the access token. */
+    scope: string;
+    /** Public, descriptive policy context. Never used as payment authority. */
+    access?: McpAccessContext;
+    /**
+     * When present, `pay` prepares unsigned spend_account::settle_policy / settle_any_recipient bytes for the
+     * client-held delegate key to sign locally — no server-side decrypt or
+     * signing. Stdio local V1 profile path remains when absent.
+     */
+    spendAccountPay?: McpSpendAccountPayAuth;
+    /**
+     * Server-scoped receipts reader, built by the /mcp route from the verified
+     * bearer's connection. The `receipts` tool calls this instead of hitting the
+     * global settlement feed with a forwarded credential — the bearer never
+     * enters the tool surface, and scoping is enforced server-side. Absent for
+     * local stdio (no connection, no settlement source).
+     */
+    listReceipts?: (challengeId?: string) => Promise<SettlementDTO[]>;
+}
+
+type McpTarget = 'dev' | 'local';
+/**
+ * Public suipay-dev origins (Railway). `local` is the laptop stack from
+ * `pnpm demo:testnet`. Explicit `SUIPAY_GATEWAY_URL` / `SUIPAY_CONSOLE_URL`
+ * still win over the preset.
+ */
+declare const MCP_TARGET_PRESETS: Record<McpTarget, {
+    consoleUrl: string;
+    gatewayUrl: string;
+}>;
+interface McpConfig {
+    /** Preset used when console/gateway env is unset. Set by `loadMcpConfig`. */
+    target?: McpTarget;
+    consoleUrl: string;
+    gatewayUrl: string;
+    rpcUrl: string;
+    network: 'testnet' | 'mainnet' | 'devnet' | 'localnet';
+    packageId: string;
+    recipient: string;
+    coinType: string;
+    sponsorUrl: string;
+    minFunded: bigint;
+    minMaxPerPayment: bigint;
+    label: string;
+    /**
+     * Optional override of the gateway's published `ExclusionDirectory` id.
+     * When null, pay reads `GET /v1/delegate/deployment` and turns the resolver
+     * on only if that response names one. The id here does not choose the
+     * directory a settle uses — the offer's `registryIdentity` does.
+     */
+    exclusionDirectoryObjectId: string | null;
+}
+/**
+ * CLI flags: `--local` / `-local`, `--dev` / `-dev`. Unknown args are ignored
+ * so an MCP host can pass extra argv without breaking stdio.
+ */
+declare function parseMcpTargetFlag(argv: readonly string[]): McpTarget | undefined;
+declare function resolveMcpTarget(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpTarget;
+/** Same public origin, or the same laptop loopback port (`localhost` ≡ `127.0.0.1`). */
+declare function sameMcpGateway(a: string, b: string): boolean;
+declare function loadMcpConfig(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpConfig;
+
+/**
+ * Grant-scoped read DTOs a delegate may see. Split from `principal.ts` because
+ * `agent-sdk/reads.ts` (published) needs only these shapes, not the gateway-side
+ * projection functions that build them from a resolved authority record.
+ */
+/**
+ * A delegate's grant-scoped balance view. The on-chain money facts for its OWN
+ * grant: the containment caps, the projected session spend, and the derived
+ * remaining headroom — never the owner tenant id or any operational context.
+ */
+interface DelegateBalanceDTO {
+    grantObjectId: string;
+    poolObjectId: string;
+    asset: string;
+    coinType: string;
+    /** `open` (full access, caps) vs `scoped` (policy allowlist). */
+    grantType: 'open' | 'scoped';
+    /** Per-session ceiling in atomic units; null = unlimited. */
+    sessionCap: string | null;
+    /** Per-payment ceiling in atomic units; null = unlimited. */
+    maxPerPayment: string | null;
+    /** Projected session spend in atomic units; null = not wired / unknown. */
+    sessionSpent: string | null;
+    /**
+     * Remaining session headroom in atomic units when both a finite cap and a
+     * known spend exist, clamped at zero; null when the cap is unlimited or the
+     * spend is unknown (never guessed).
+     */
+    sessionRemaining: string | null;
+}
+/** One allowlisted target of one policy, as the delegate may see it. */
+interface DelegatePolicyTargetDTO {
+    /** 32-byte hex target hash the offer's `targetHash` must equal. */
+    targetHash: string;
+    /**
+     * The only address this target may pay, when the authority source records
+     * one. Omitted rather than blank when it does not: an agent that pins an
+     * empty recipient would refuse every offer, and one that pins a fabricated
+     * value would refuse the right one.
+     */
+    recipient?: string;
+    /** Per-target ceiling in atomic units, when the target sets one. */
+    maxPerPayment?: string;
+}
+/** One policy backing this grant's on-chain spend authority. */
+interface DelegatePolicyDTO {
+    /** Off-chain policy id (audit). */
+    policyId: string;
+    /** On-chain policy id (u64) the settlement call names. */
+    onChainPolicyId: number | string;
+    status: 'draft' | 'active' | 'paused' | 'revoked';
+    targets: DelegatePolicyTargetDTO[];
+}
+/**
+ * A delegate's grant-scoped policy view: the immutable policy snapshot the grant
+ * was created with — off-chain ids, on-chain ids, and each policy's allowlisted
+ * TARGETS — plus the grant surface. An open grant carries no allowlist (empty
+ * arrays). Never the owner tenant id, policy names, or catalog enrichment.
+ *
+ * The targets are here because without them a scoped grant cannot be paid at
+ * all. A payment names a policy id and a target hash, and the ids alone let a
+ * caller name neither: `resolveGrantTarget` matches the offer's `targetHash`
+ * against this allowlist, and nothing else publishes it to the key that holds
+ * the grant.
+ *
+ * Publishing them adds no authority. This is a signed, grant-scoped read: the
+ * caller proved possession of the delegate key and the signature binds the
+ * grant, so the response can only ever describe that one grant. It states the
+ * bound the chain already enforces on `spend_account::settle_policy`;
+ * it does not widen it. What an agent gains is the ability to check an offer
+ * BEFORE signing instead of discovering the bound as an on-chain abort.
+ */
+interface DelegatePoliciesDTO {
+    grantObjectId: string;
+    grantType: 'open' | 'scoped';
+    offChainPolicyIds: string[];
+    onChainPolicyIds: number[];
+    /**
+     * The bound policies with their targets, in the order the authority source
+     * returns them. Empty for an open grant (no allowlist exists) and empty when
+     * no target source is configured — never a partial list, because a truncated
+     * allowlist reads as "this target is not authorized" for targets that are.
+     */
+    policies: DelegatePolicyDTO[];
+}
+
+/**
+ * Agent signing helper — emit the four `x-suipay-*` signed-request headers.
+ *
+ * A delegate agent proves identity on every private, grant-scoped request by
+ * signing the canonical `SignedRequestV1` payload with a Sui personal-message
+ * signature. This helper is the client-side counterpart to the gateway verifier:
+ * it canonicalizes the path/query and hashes the body EXACTLY as the verifier
+ * will (reusing the P0 codec's `canonicalizePath` / `canonicalizeQuery` /
+ * `hashBodyHex`), builds the payload, signs it through P0's `signSignedRequest`,
+ * and returns the four headers keyed by P0's `SIGNED_REQUEST_HEADERS`.
+ *
+ * It NEVER holds or transmits the private key: the caller injects a
+ * `signPersonalMessage` callback (a wallet, a keystore, or an `Ed25519Keypair`
+ * bound via {@link personalMessageSigner}). Money never moves on this signature;
+ * it authorizes only the grant-scoped reads the epic defines.
+ *
+ * Byte-for-byte parity with P0 is locked by the golden vector in
+ * `tests/agent-sdk-signed-headers.test.ts`, which reproduces the exact
+ * signature the cross-language vector (`tests/parity/signed-request-golden.test.ts`)
+ * pins.
+ */
+
+/** Sui personal-message signer: returns the serialized signature (base64). */
+type SignPersonalMessage = (message: Uint8Array) => Promise<string>;
+/**
+ * The deployment + grant identity every signed request binds. `network` and
+ * `packageId` MUST equal the gateway's server-authoritative config; `delegate`
+ * MUST equal the grant's registered on-chain delegate (the signer's address).
+ */
+interface SessionSignerContext {
+    /** e.g. `sui:testnet` — must equal the gateway config. */
+    network: string;
+    /** Deployed package id — must equal the gateway config. */
+    packageId: string;
+    /** On-chain grant object id — the authorization scope. */
+    grantObjectId: string;
+    /** Registered delegate Sui address (the signer). */
+    delegateAddress: string;
+}
+/** Deterministic overrides (tests / golden vectors) + injectable entropy/clock. */
+interface SignRequestOptions {
+    /** Pin the signed timestamp (epoch ms). Defaults to `now()`. */
+    timestampMs?: number;
+    /** Pin the single-use nonce. Defaults to `generateNonce()`. */
+    nonce?: string;
+    /** Injectable clock; defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable nonce source; defaults to {@link generateSignedRequestNonce}. */
+    generateNonce?: () => string;
+}
+
+/**
+ * Grant-scoped read ergonomics for a delegate agent.
+ *
+ * Two kinds of read, mirroring the epic's public/private split:
+ *
+ *   1. Enriched-context reads ({@link createReader}) — the private,
+ *      off-chain-enriched projections behind P2's signed routes
+ *      (`GET /v1/delegate/{balance,policies,receipts}`). Each request is signed
+ *      with the four `x-suipay-*` headers (via the P0-backed signing helper),
+ *      so the gateway resolves the caller's grant and returns ONLY that grant's
+ *      state. Non-2xx responses are classified, never swallowed.
+ *
+ *   2. Direct on-chain reads ({@link readPublicSessionState} /
+ *      {@link readPublicSpendAccountState}) — the PUBLIC on-chain facts (delegate, caps,
+ *      spend, policy ids, pause/revoke, pool balance) read straight from a
+ *      `getObject` projection with no signature. Public data stays public.
+ *
+ * The read client never spends and never holds the private key: money still
+ * moves only through the delegate's own on-chain `spend_account::settle_policy`.
+ */
+
+/** A delegate's own receipts, as P2's receipts route shapes them. */
+interface PayerReceiptsDTO {
+    source: 'read-model' | 'memory';
+    receipts: unknown[];
+}
+/**
+ * A classified read outcome. `ok` is a 2xx with a parsed body; a failure carries
+ * the HTTP status, a coarse class, and the gateway's stable error code (never a
+ * raw internal string — the gateway already sanitizes `{ error }`).
+ */
+type PayerReadResult<T> = {
+    ok: true;
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    /**
+     * Coarse failure class: `rejected` = auth/authz refusal (4xx);
+     * `unavailable` = a 5xx or a transport failure; `malformed` = unparseable;
+     * `signing` = the local signature could not be produced (the request never
+     * left the client). Never a throw — every failure is a typed result.
+     */
+    error: 'rejected' | 'unavailable' | 'malformed' | 'signing';
+    /** Gateway's public failure code from `{ error }`, or a stable client code. */
+    code?: string;
+    body?: unknown;
+};
+interface PayerReadClientOptions {
+    /** Gateway origin, e.g. `https://gateway.suipay.dev` (no trailing slash needed). */
+    gatewayUrl: string;
+    /** Deployment + grant identity every signed read binds. */
+    context: SessionSignerContext;
+    /** Local personal-message signer; the key never leaves it. */
+    signPersonalMessage: SignPersonalMessage;
+    /** Injectable fetch (tests / custom transports). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injectable clock + nonce for deterministic signing in tests. */
+    signOptions?: Pick<SignRequestOptions, 'now' | 'generateNonce' | 'timestampMs' | 'nonce'>;
+    /** Route prefix; defaults to `/v1/delegate`. */
+    basePath?: string;
+}
+/** The read surface a delegate agent gets from its grant. */
+interface PayerReadClient {
+    balance(): Promise<PayerReadResult<DelegateBalanceDTO>>;
+    policies(): Promise<PayerReadResult<DelegatePoliciesDTO>>;
+    receipts(): Promise<PayerReadResult<PayerReceiptsDTO>>;
+    /** Sign an arbitrary grant-scoped GET under the same context (escape hatch). */
+    signedGet<T = unknown>(pathSuffix: string): Promise<PayerReadResult<T>>;
+}
+/**
+ * A signed, grant-scoped read client. Every method signs a GET with the four
+ * `x-suipay-*` headers and returns a classified result. A signed GET carries no
+ * body, so the body hash is the empty-string hash — matching the verifier.
+ */
+declare function createReader(options: PayerReadClientOptions): PayerReadClient;
+/**
+ * Fetch the Move JSON contents of an object. Wire this to
+ * `client.core.getObject({ objectId, include: { json: true } })` and return its
+ * `object.json`. `null` for a missing object. Injected so the reader is pure and
+ * testable with fakes and depends on no Sui client at load time.
+ */
+type GetObjectJson = (objectId: string) => Promise<Record<string, unknown> | null | undefined>;
+
+type PaidHttpMethod = 'GET' | 'POST';
+interface PaidHttpRequest {
+    url: string;
+    method: PaidHttpMethod;
+    /** Exact wire bytes. Empty for GET. */
+    body: Uint8Array;
+    /** Normalized media type, or null when no body is sent. */
+    contentType: string | null;
+    /** `hashRequestBody(body)` — the single canonical body hash. */
+    bodyHash: string;
+}
+
+/**
+ * Shapes of the one error model every SuiPay surface shares.
+ *
+ * The registry (`registry.ts`) is the only place a code is defined. Everything
+ * here describes an entry or a value derived from one; nothing here names a
+ * code.
+ */
+/** Whether money moved for the request the error is about. */
+type PaymentState = 'not_charged' | 'charged' | 'unknown';
+/** The one thing a caller, agent or person should do next. */
+type NextAction = 'retry' | 'retry_later' | 'fix_request' | 'sign_in' | 'approve_access' | 'add_funds' | 'reconcile' | 'contact_support' | 'none';
+/** Where an error can originate. A builder accepts only codes tagged for it. */
+type Surface = 'gateway' | 'seller' | 'console_server' | 'browser' | 'sdk' | 'mcp_local' | 'mcp_hosted' | 'indexer';
+
+declare const ERRORS: {
+    readonly 'indexer.chain_unavailable': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Transient chain read failure; retrying with backoff";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.checkpoint_gap': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Checkpoint gap cannot be closed; fullnode has pruned it";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.checkpoint_malformed': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Checkpoint payload is malformed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.checkpoint_refetch_failed': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Checkpoint re-fetch returned nothing";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.config_invalid': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Indexer configuration is invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.event_legacy_field': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Event used a deprecated field name; decoded anyway";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.event_undecodable': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Owned event body failed to decode";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.event_unrecognized': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Package emitted an event type no pipeline claims";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.retries_exhausted': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Retry budget exhausted for a checkpoint";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.stopped': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Indexer loop exited";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'indexer.store_failed': {
+        readonly surfaces: readonly ["indexer"];
+        readonly status: null;
+        readonly title: "Indexer database write failed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'client.agent_handoff_failed': {
+        readonly surfaces: readonly ["browser", "mcp_local"];
+        readonly status: null;
+        readonly title: "Key hand-off to the local agent failed";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Couldn't reach your agent";
+            readonly message: "We couldn't pass the key to your agent. Try again.";
+        };
+    };
+    readonly 'client.already_paid': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Request was already paid in this tab";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: {
+            readonly title: "Already paid";
+            readonly message: "You already paid for this request in this tab.";
+        };
+    };
+    readonly 'client.build_failed': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Payment transaction could not be built";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Couldn't prepare payment";
+            readonly message: "We couldn't prepare this payment. If it keeps happening, contact support.";
+        };
+    };
+    readonly 'client.config_invalid': {
+        readonly surfaces: readonly ["sdk", "mcp_local"];
+        readonly status: null;
+        readonly title: "Client configuration is missing or invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Setup incomplete";
+            readonly message: "Your app is missing required settings. Check its setup and try again.";
+        };
+    };
+    readonly 'client.delivery_file_not_saved': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "Paid result could not be written to a file";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Result not saved";
+            readonly message: "The result couldn't be saved to a file.";
+        };
+    };
+    readonly 'client.gateway_unreachable': {
+        readonly surfaces: readonly ["browser", "sdk", "mcp_local"];
+        readonly status: null;
+        readonly title: "Payment service could not be reached";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service unreachable";
+            readonly message: "We couldn't reach the payment service.";
+        };
+    };
+    readonly 'client.input_invalid': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Form input failed local validation";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check the form";
+            readonly message: "Some fields need fixing. Check the highlighted fields and try again.";
+        };
+    };
+    readonly 'client.key_already_active': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Edit asked to change a key that is already active";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Key already active";
+            readonly message: "Nothing changed. To change this key's limits, revoke it and set it up again.";
+        };
+    };
+    readonly 'client.key_invalid': {
+        readonly surfaces: readonly ["browser", "mcp_local"];
+        readonly status: null;
+        readonly title: "Pasted or supplied key is not a delegate key";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Key not recognized";
+            readonly message: "That isn't a valid agent key. Paste the key you saved when you set up access.";
+        };
+    };
+    readonly 'client.ledger_failed': {
+        readonly surfaces: readonly ["sdk", "mcp_local"];
+        readonly status: null;
+        readonly title: "Local payment ledger read or write failed";
+        readonly paymentState: "emitter";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Payment record not saved";
+            readonly message: "We couldn't save this payment's record on your device.";
+        };
+    };
+    readonly 'client.local_credentials_invalid': {
+        readonly surfaces: readonly ["sdk", "mcp_local"];
+        readonly status: null;
+        readonly title: "Stored or environment credentials are unreadable, malformed or mismatched";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Saved key not usable";
+            readonly message: "Your saved agent key is damaged or doesn't match. Sign in again to replace it.";
+        };
+    };
+    readonly 'client.manifest_invalid': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Agent manifest is malformed or missing a field";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Access details incomplete";
+            readonly message: "Your agent's access details are missing something. Set up access again.";
+        };
+    };
+    readonly 'client.offline': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Browser is offline or the network request failed";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "You're offline";
+            readonly message: "Check your internet connection.";
+        };
+    };
+    readonly 'client.page_stale': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Page state is missing data a reload restores";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Page out of date";
+            readonly message: "This page is out of date. Reload it and try again.";
+        };
+    };
+    readonly 'client.payer_misconfigured': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Payer lacks a required dependency (signer, executor, ledger or secret)";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment setup incomplete";
+            readonly message: "Your app isn't set up to make this payment. Check its settings.";
+        };
+    };
+    readonly 'client.payment_unresolved': {
+        readonly surfaces: readonly ["browser", "sdk"];
+        readonly status: null;
+        readonly title: "An earlier payment did not resolve";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment didn't finish";
+            readonly message: "A payment didn't finish. Check its status.";
+        };
+    };
+    readonly 'client.sign_failed': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Local signer failed";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Couldn't sign";
+            readonly message: "Your key couldn't sign this request. Try again.";
+        };
+    };
+    readonly 'client.tx_mismatch': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Prepared transaction does not match the offer";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Payment stopped for safety";
+            readonly message: "The transaction didn't match the quote, so we stopped before signing.";
+        };
+    };
+    readonly 'client.unexpected': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Unexpected client error";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "If it keeps happening, contact support.";
+        };
+    };
+    readonly 'client.wallet_not_connected': {
+        readonly surfaces: readonly ["browser"];
+        readonly status: null;
+        readonly title: "Action needs a connected, signed-in owner wallet";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Connect your wallet";
+            readonly message: "Connect your wallet and sign in to continue.";
+        };
+    };
+    readonly 'client.wallet_rejected': {
+        readonly surfaces: readonly ["browser", "sdk"];
+        readonly status: null;
+        readonly title: "Wallet request was rejected by the user";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Signature declined";
+            readonly message: "You declined the request in your wallet. Try again when ready.";
+        };
+    };
+    readonly 'service.internal': {
+        readonly surfaces: readonly ["gateway", "seller", "console_server", "mcp_hosted"];
+        readonly status: 500;
+        readonly title: "Internal error";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "If it keeps happening, contact support with the code below.";
+        };
+    };
+    readonly 'service.unavailable': {
+        readonly surfaces: readonly ["gateway", "console_server", "mcp_hosted", "browser"];
+        readonly status: 503;
+        readonly title: "Service temporarily unavailable";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Temporarily unavailable";
+            readonly message: "This isn't available right now. Try again in a moment.";
+        };
+    };
+    readonly 'service.not_ready': {
+        readonly surfaces: readonly ["gateway", "seller", "console_server"];
+        readonly status: 503;
+        readonly title: "Service is not ready";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'service.job_failed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: null;
+        readonly title: "Background job attempt failed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'service.config_degraded': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: null;
+        readonly title: "Service started with degraded configuration";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'service.bookkeeping_failed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: null;
+        readonly title: "Best-effort record write failed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'limit.concurrency_exceeded': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 429;
+        readonly title: "Too many concurrent streams";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Too many open connections";
+            readonly message: "You have too many open connections. Close some and try again.";
+        };
+    };
+    readonly 'limit.gas_quota_exceeded': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 429;
+        readonly title: "Per-signer gas sponsorship quota exceeded";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 3600;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Fee cover limit reached";
+            readonly message: "You've used up your covered network fees for now. Try again later.";
+        };
+    };
+    readonly 'limit.rate_limited': {
+        readonly surfaces: readonly ["gateway", "console_server"];
+        readonly status: 429;
+        readonly title: "Rate limit exceeded";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Too many requests";
+            readonly message: "You're sending requests too fast. Wait a moment and try again.";
+        };
+    };
+    readonly 'chain.tx_failed': {
+        readonly surfaces: readonly ["gateway", "sdk", "browser"];
+        readonly status: 502;
+        readonly title: "Transaction failed on chain";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Transaction failed";
+            readonly message: "The network rejected your transaction. Check the details and try again.";
+        };
+    };
+    readonly 'chain.tx_not_final': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Owner transaction is not final yet";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 3;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Still confirming";
+            readonly message: "Your transaction is still being confirmed. Try again in a few seconds.";
+        };
+    };
+    readonly 'chain.tx_unconfirmed': {
+        readonly surfaces: readonly ["sdk", "browser"];
+        readonly status: null;
+        readonly title: "Owner transaction was submitted but finality is not confirmed";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Transaction still processing";
+            readonly message: "Your transaction was sent but isn't confirmed yet. Check its status before doing anything else.";
+        };
+    };
+    readonly 'chain.tx_unverified': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Transaction effects could not be verified";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Couldn't verify transaction";
+            readonly message: "We couldn't confirm your transaction's result. Check its status before doing anything else.";
+        };
+    };
+    readonly 'chain.unavailable': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 503;
+        readonly title: "Chain read failed or the network is unavailable";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Network busy";
+            readonly message: "We couldn't reach the network.";
+        };
+    };
+    readonly 'chain.event_legacy_field': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: null;
+        readonly title: "On-chain event carries a legacy field";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'sponsor.challenge_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Sponsor challenge expired or its nonce was rejected";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Fee cover expired";
+            readonly message: "Your request for a covered network fee expired. Start again.";
+        };
+    };
+    readonly 'sponsor.execute_auth_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Sponsored execute authorization is missing, invalid or expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Fee cover not confirmed";
+            readonly message: "Your approval for the covered fee is missing or expired. Start again.";
+        };
+    };
+    readonly 'sponsor.execute_digest_mismatch': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Executed digest does not match the sponsored transaction";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Transaction needs checking";
+            readonly message: "We can't confirm what was sent. Check its status before doing anything else.";
+        };
+    };
+    readonly 'sponsor.execute_failed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Sponsored transaction executed and aborted on chain";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Transaction failed";
+            readonly message: "The network rejected this transaction. Check the details and try again.";
+        };
+    };
+    readonly 'sponsor.execute_not_pending': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Sponsored transaction is no longer pending";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Already submitted";
+            readonly message: "This transaction may already have been sent. Check its status before doing anything else.";
+        };
+    };
+    readonly 'sponsor.execute_outcome_unknown': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 503;
+        readonly title: "Sponsored execute outcome is unknown";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Transaction still processing";
+            readonly message: "We can't confirm this transaction yet. Check its status before doing anything else.";
+        };
+    };
+    readonly 'sponsor.gas_lease_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 402;
+        readonly title: "Gas lease is missing, expired or in the wrong state";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Fee cover expired";
+            readonly message: "The covered network fee for this quote expired. Get a new quote and try again.";
+        };
+    };
+    readonly 'sponsor.gas_pin_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 402;
+        readonly title: "Transaction gas does not match the pinned sponsor gas";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Fee details not valid";
+            readonly message: "The network fee in your payment doesn't match the quote. Update your app and try again.";
+        };
+    };
+    readonly 'sponsor.kind_rejected': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Transaction kind is not sponsorable";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Fee can't be covered";
+            readonly message: "We can't cover your network fee for this kind of transaction.";
+        };
+    };
+    readonly 'sponsor.personal_message_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Sponsor personal-message approval is missing or invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Approval not valid";
+            readonly message: "Your approval signature didn't check out. Sign again with the right key.";
+        };
+    };
+    readonly 'sponsor.sponsorship_not_found': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Sponsored digest has no known sponsorship";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Fee cover not found";
+            readonly message: "We couldn't find the fee cover for this transaction. Start again.";
+        };
+    };
+    readonly 'sponsor.target_not_allowed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Move call target is not sponsorable";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Action can't be covered";
+            readonly message: "We can't cover your network fee for that action.";
+        };
+    };
+    readonly 'sponsor.tx_mismatch': {
+        readonly surfaces: readonly ["sdk", "mcp_local"];
+        readonly status: null;
+        readonly title: "Sponsored transaction bytes do not reconstruct the payment";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Payment stopped for safety";
+            readonly message: "The prepared transaction didn't match your payment, so we stopped before signing.";
+        };
+    };
+    readonly 'sponsor.unavailable': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "browser"];
+        readonly status: 503;
+        readonly title: "Gas sponsorship is unavailable";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Fee cover unavailable";
+            readonly message: "Covered network fees are unavailable right now. Try again in a moment.";
+        };
+    };
+    readonly 'sponsor.would_abort': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 422;
+        readonly title: "Sponsored dry run would abort";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Transaction would fail";
+            readonly message: "A test run shows this transaction would fail. Check the details and try again.";
+        };
+    };
+    readonly 'seller.config_locked': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Seller configuration is locked";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Settings locked";
+            readonly message: "Settings are locked. Use the settings token to change them.";
+        };
+    };
+    readonly 'seller.config_origin_rejected': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Configuration request came from a foreign origin";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Request blocked";
+            readonly message: "You can only change settings from this server's own setup page.";
+        };
+    };
+    readonly 'seller.config_pinned': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 400;
+        readonly title: "Gateway binding is pinned by environment";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Settings set by the server";
+            readonly message: "These settings come from the server's environment, so you can't change them here.";
+        };
+    };
+    readonly 'seller.content_too_large': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 413;
+        readonly title: "Content exceeds the seller's storage limit";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Content too large";
+            readonly message: "What you sent is too large to store.";
+        };
+    };
+    readonly 'seller.delivery_proof_expired': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 401;
+        readonly title: "Delivery proof has expired";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The service couldn't confirm this request in time. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_malformed': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Delivery proof claims are malformed";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The service couldn't read the confirmation for this request. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_missing': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 401;
+        readonly title: "Paid request arrived without a delivery proof";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The service didn't receive the confirmation for this request. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_mismatch': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Delivery proof does not match the request";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The confirmation didn't match this request. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_replayed': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Delivery proof was already used";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "This request was already served once. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_unknown_audience': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Delivery proof is for a different audience";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "This request was meant for a different service. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_unknown_service': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 403;
+        readonly title: "Delivery proof names an unknown service";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The service didn't recognize this request. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.delivery_proof_verify_failed': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 401;
+        readonly title: "Delivery proof signature did not verify";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not accepted";
+            readonly message: "The service couldn't confirm this request came through us. Contact support with the code below.";
+        };
+    };
+    readonly 'seller.execution_failed': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Buyer's code exited with an error";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Your code failed";
+            readonly message: "Your code stopped with an error.";
+        };
+    };
+    readonly 'seller.gateway_invalid': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 400;
+        readonly title: "Address is not a payment gateway or its issuer does not match";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Not a payment gateway";
+            readonly message: "That address doesn't look like a payment gateway. Check it.";
+        };
+    };
+    readonly 'seller.gateway_unreachable': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 400;
+        readonly title: "Gateway could not be reached while binding";
+        readonly paymentState: "emitter";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Couldn't reach the gateway";
+            readonly message: "We couldn't reach that gateway. Check the address.";
+        };
+    };
+    readonly 'seller.gateway_url_invalid': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 400;
+        readonly title: "Gateway URL is missing, malformed or not allowed";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check the gateway address";
+            readonly message: "Enter a public https address for the gateway, with no username or password.";
+        };
+    };
+    readonly 'seller.invalid_input': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 400;
+        readonly title: "Seller rejected the request input";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check your request";
+            readonly message: "The service couldn't use what you sent. Fix the request.";
+        };
+    };
+    readonly 'seller.not_configured': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller product or gateway binding is not configured";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 60;
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Service not set up";
+            readonly message: "This service isn't set up yet.";
+        };
+    };
+    readonly 'seller.not_ready': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller failed its readiness check";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service not ready";
+            readonly message: "This service isn't ready right now.";
+        };
+    };
+    readonly 'seller.canonical_price_unavailable': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 503;
+        readonly title: "Seller could not read the canonical price";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Service not ready";
+            readonly message: "This service can't confirm its price right now.";
+        };
+    };
+    readonly 'seller.price_mismatch': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: 503;
+        readonly title: "Seller price does not match the canonical price";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 60;
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Service not ready";
+            readonly message: "This service's price is being updated.";
+        };
+    };
+    readonly 'seller.quota_exhausted': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller's vendor quota or credits are exhausted";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 300;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service at capacity";
+            readonly message: "This service has used up its capacity for now.";
+        };
+    };
+    readonly 'seller.rate_limited': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller's vendor is rate limiting or throttling";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service busy";
+            readonly message: "This service is busy.";
+        };
+    };
+    readonly 'seller.registration_rejected': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: null;
+        readonly title: "Gateway rejected the seller registration";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'seller.registration_unreachable': {
+        readonly surfaces: readonly ["seller"];
+        readonly status: null;
+        readonly title: "Gateway was unreachable during seller registration";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "retry_later";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'seller.storage_full': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller's storage has insufficient space";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 300;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Storage full";
+            readonly message: "Storage is full right now.";
+        };
+    };
+    readonly 'seller.storage_guarantee_failed': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Stored content does not meet the permanence or window guarantee";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Couldn't confirm storage";
+            readonly message: "We couldn't confirm your data will be kept as long as promised.";
+        };
+    };
+    readonly 'seller.upstream_auth_failed': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Seller's vendor credentials were refused";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Service not working";
+            readonly message: "This service can't reach its provider right now.";
+        };
+    };
+    readonly 'seller.upstream_failed': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Seller's vendor returned an error";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service error";
+            readonly message: "This service hit an error.";
+        };
+    };
+    readonly 'seller.upstream_malformed': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Seller's vendor returned a malformed response";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Service error";
+            readonly message: "This service couldn't read its provider's answer. Contact support if it keeps happening.";
+        };
+    };
+    readonly 'seller.upstream_response_too_large': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 502;
+        readonly title: "Seller's vendor response exceeded the size limit";
+        readonly paymentState: "emitter";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Result too large";
+            readonly message: "The result was too large for this service to return to you.";
+        };
+    };
+    readonly 'seller.upstream_timeout': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 504;
+        readonly title: "Seller's vendor timed out";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service too slow";
+            readonly message: "This service took too long to answer.";
+        };
+    };
+    readonly 'seller.upstream_unavailable': {
+        readonly surfaces: readonly ["seller", "gateway"];
+        readonly status: 503;
+        readonly title: "Seller's vendor is unavailable";
+        readonly paymentState: "emitter";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 30;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Service unavailable";
+            readonly message: "This service's provider is unavailable.";
+        };
+    };
+    readonly 'delivery.seller_unreachable': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Seller did not respond after payment";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "No result came back from the service.";
+        };
+    };
+    readonly 'delivery.seller_timeout': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 504;
+        readonly title: "Seller timed out after payment";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "The service took too long to answer.";
+        };
+    };
+    readonly 'delivery.seller_rejected': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 502;
+        readonly title: "Seller rejected the paid request";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Request not completed";
+            readonly message: "The service didn't accept this request.";
+        };
+    };
+    readonly 'delivery.seller_failed': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 502;
+        readonly title: "Seller failed while serving the paid request";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "The service failed while handling this request.";
+        };
+    };
+    readonly 'delivery.seller_redirect_refused': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Seller answered the paid request with a redirect";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "The service didn't return a result.";
+        };
+    };
+    readonly 'delivery.response_too_large': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 502;
+        readonly title: "Seller response exceeded the size limit";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Result too large";
+            readonly message: "The result was too large to deliver.";
+        };
+    };
+    readonly 'delivery.proof_unavailable': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 503;
+        readonly title: "Delivery proof could not be produced after payment";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Result delayed";
+            readonly message: "Your result is delayed. Check the payment status later.";
+        };
+    };
+    readonly 'delivery.reconciliation_required': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Settled payment needs reconciliation before delivery";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Result delayed";
+            readonly message: "Your result needs a status check before it can be delivered.";
+        };
+    };
+    readonly 'delivery.proof_rejected': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 502;
+        readonly title: "Resource refused the paid proof after finality";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "The result couldn't be delivered.";
+        };
+    };
+    readonly 'delivery.internal': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 500;
+        readonly title: "Internal error after payment";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Something went wrong";
+            readonly message: "No result came back. Contact support with the code below.";
+        };
+    };
+    readonly 'delivery.refund_failed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: null;
+        readonly title: "Operator refund after a failed delivery was not sent";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: null;
+        readonly logOnly: true;
+    };
+    readonly 'payment.required': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 402;
+        readonly title: "Payment required";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "none";
+        readonly user: {
+            readonly title: "Payment needed";
+            readonly message: "This service needs a payment before it can answer.";
+        };
+        readonly mppProblem: "payment-required";
+    };
+    readonly 'payment.credential_malformed': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 402;
+        readonly title: "Payment credential could not be read";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment not accepted";
+            readonly message: "Your payment couldn't be read. Try paying again.";
+        };
+        readonly mppProblem: "malformed-credential";
+    };
+    readonly 'payment.proof_invalid': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 402;
+        readonly title: "Payment proof failed verification";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment not accepted";
+            readonly message: "Your payment couldn't be verified. Try paying again.";
+        };
+        readonly mppProblem: "verification-failed";
+    };
+    readonly 'payment.amount_insufficient': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk"];
+        readonly status: 402;
+        readonly title: "Payment amount is below the price";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment too small";
+            readonly message: "The amount offered is below the price. Pay the full amount.";
+        };
+        readonly mppProblem: "payment-insufficient";
+    };
+    readonly 'payment.method_unsupported': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "console_server", "browser"];
+        readonly status: 400;
+        readonly title: "Payment method is not supported";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment method not supported";
+            readonly message: "This service doesn't accept that way of paying.";
+        };
+        readonly mppProblem: "method-unsupported";
+    };
+    readonly 'payment.version_unsupported': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "console_server", "browser"];
+        readonly status: 400;
+        readonly title: "Payment protocol version is not supported";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Update your client";
+            readonly message: "This service can't read the payment format your client uses. Update your client and try again.";
+        };
+    };
+    readonly 'payment.verify_failed': {
+        readonly surfaces: readonly ["gateway", "sdk", "console_server", "browser"];
+        readonly status: 503;
+        readonly title: "Payment verification failed unexpectedly";
+        readonly paymentState: "not_charged";
+        readonly retry: "after_delay";
+        readonly retryAfterSeconds: 5;
+        readonly nextAction: "retry_later";
+        readonly user: {
+            readonly title: "Payment check unavailable";
+            readonly message: "We couldn't check your payment just now. Wait a moment and try again.";
+        };
+    };
+    readonly 'payment.settlement_rejected': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 402;
+        readonly title: "Settlement was rejected";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment not accepted";
+            readonly message: "The payment was refused. Check your access key and try again.";
+        };
+        readonly mppProblem: "verification-failed";
+    };
+    readonly 'payment.proof_not_accepted': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 409;
+        readonly title: "Payment proof refused before its finality was read";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment needs a check";
+            readonly message: "Your payment was sent but couldn't be matched to this request. Check its status before doing anything else.";
+        };
+    };
+    readonly 'payment.attempt_in_flight': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 409;
+        readonly title: "Another payment for this request is in progress";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment already in progress";
+            readonly message: "A payment for this request is still being processed. Wait for it to finish before doing anything else.";
+        };
+        readonly mppProblem: "invalid-challenge";
+    };
+    readonly 'payment.challenge_spent': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 409;
+        readonly title: "Payment challenge was already settled";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment may already have gone through";
+            readonly message: "This payment may already have gone through. Check its status before doing anything else.";
+        };
+        readonly mppProblem: "invalid-challenge";
+    };
+    readonly 'payment.settlement_unknown': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 503;
+        readonly title: "Settlement outcome is not yet known";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment still processing";
+            readonly message: "We can't confirm your payment yet. Check its status before doing anything else.";
+        };
+    };
+    readonly 'payment.finality_unconfirmed': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 503;
+        readonly title: "Transaction was submitted but finality is not confirmed";
+        readonly paymentState: "unknown";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 10;
+        readonly nextAction: "reconcile";
+        readonly user: {
+            readonly title: "Payment still processing";
+            readonly message: "Your payment was sent but is not confirmed yet. Check its status before doing anything else.";
+        };
+    };
+    readonly 'payment.settlement_mismatch': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 502;
+        readonly title: "Settlement effects do not match the offer";
+        readonly paymentState: "charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Payment needs review";
+            readonly message: "Your payment went through but didn't match the offer. Contact support with the code below.";
+        };
+    };
+    readonly 'offer.expired': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 402;
+        readonly title: "Offer expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Offer expired";
+            readonly message: "The price quote expired before you paid. Try again for a new quote.";
+        };
+        readonly mppProblem: "payment-expired";
+    };
+    readonly 'offer.challenge_invalid': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk"];
+        readonly status: 402;
+        readonly title: "Challenge is unknown or already used";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Offer no longer valid";
+            readonly message: "That price quote can't be used anymore. Try again for a new quote.";
+        };
+        readonly mppProblem: "invalid-challenge";
+    };
+    readonly 'offer.terms_changed': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 409;
+        readonly title: "Registration terms changed since the offer was made";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Price changed";
+            readonly message: "The service changed its terms. Try again for a new quote.";
+        };
+    };
+    readonly 'offer.invalid': {
+        readonly surfaces: readonly ["console_server", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 422;
+        readonly title: "Offer is unreadable or internally inconsistent";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Price quote can't be used";
+            readonly message: "This service sent a price quote we can't use. Try another service or contact support.";
+        };
+    };
+    readonly 'offer.not_offered': {
+        readonly surfaces: readonly ["console_server", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 422;
+        readonly title: "Resource answered without a payment challenge";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "No price quote";
+            readonly message: "This address didn't ask for a payment. Check that you're using the right address.";
+        };
+    };
+    readonly 'offer.not_payable': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 409;
+        readonly title: "Offer's recipient or rail setup cannot be paid here";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Can't pay this service";
+            readonly message: "You can't pay this service this way right now.";
+        };
+    };
+    readonly 'offer.request_mismatch': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 409;
+        readonly title: "Request does not match what the offer bound";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Request doesn't match quote";
+            readonly message: "What you sent differs from what the price was quoted for. Get a new quote and try again.";
+        };
+    };
+    readonly 'account.asset_unsupported': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 400;
+        readonly title: "Asset is not supported for this account";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Currency not supported";
+            readonly message: "This currency isn't supported here. Pick a supported one.";
+        };
+    };
+    readonly 'account.authority_stale': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 409;
+        readonly title: "Grant authority changed since it was read";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access needs renewing";
+            readonly message: "Your agent's access changed since it was last checked. Approve access again.";
+        };
+    };
+    readonly 'account.delegate_conflict': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Consent session is bound to a different delegate";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Different key already chosen";
+            readonly message: "This setup is tied to another agent key. Use that key or start again.";
+        };
+    };
+    readonly 'account.delegate_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Delegate address is missing or invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Agent address not valid";
+            readonly message: "Enter a valid agent address and try again.";
+        };
+    };
+    readonly 'account.finalize_mismatch': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Submitted transaction does not match the prepared intent";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Transaction doesn't match";
+            readonly message: "The transaction you sent doesn't match this request. Submit the right one.";
+        };
+    };
+    readonly 'account.funds_in_address_balance': {
+        readonly surfaces: readonly ["sdk", "browser"];
+        readonly status: null;
+        readonly title: "Funds are held as address balance, not coin objects";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Funds need moving";
+            readonly message: "Your funds aren't in a form this payment can use yet. Move them into coins and try again.";
+        };
+    };
+    readonly 'account.funds_insufficient': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 402;
+        readonly title: "Insufficient funds";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "add_funds";
+        readonly user: {
+            readonly title: "Not enough funds";
+            readonly message: "You don't have enough funds for this. Add funds and try again.";
+        };
+    };
+    readonly 'account.grant_ambiguous': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 409;
+        readonly title: "More than one live grant matches";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "More than one access found";
+            readonly message: "Your key has more than one active access. Choose one and try again.";
+        };
+    };
+    readonly 'account.grant_denied': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 403;
+        readonly title: "Grant does not authorize this payment";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access not allowed";
+            readonly message: "Your agent's access doesn't cover this payment. Approve access for it.";
+        };
+    };
+    readonly 'account.grant_expired': {
+        readonly surfaces: readonly ["gateway", "sdk", "browser"];
+        readonly status: 403;
+        readonly title: "Grant has expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access expired";
+            readonly message: "Your agent's access has expired. Approve access again.";
+        };
+    };
+    readonly 'account.grant_not_active': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Grant is not active or not finalized";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access not ready";
+            readonly message: "Your agent's access isn't active yet. Finish setting it up.";
+        };
+    };
+    readonly 'account.grant_not_found': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 404;
+        readonly title: "No grant found for this delegate or asset";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "No access set up";
+            readonly message: "Your agent has no access for this yet. Set up access to continue.";
+        };
+    };
+    readonly 'account.grant_not_verified': {
+        readonly surfaces: readonly ["sdk", "mcp_local", "browser"];
+        readonly status: null;
+        readonly title: "Grant on chain does not belong to this delegate key";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Key doesn't match access";
+            readonly message: "This key isn't the one your access was given to. Use the right key.";
+        };
+    };
+    readonly 'account.grant_paused': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 403;
+        readonly title: "Grant is paused";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access paused";
+            readonly message: "Your agent's access is paused. Resume it to continue.";
+        };
+    };
+    readonly 'account.grant_retired': {
+        readonly surfaces: readonly ["mcp_hosted"];
+        readonly status: 403;
+        readonly title: "Grant type is retired and cannot sign here";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access type retired";
+            readonly message: "This kind of access is no longer supported. Remove it and set up access again.";
+        };
+    };
+    readonly 'account.grant_revoked': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 403;
+        readonly title: "Grant was revoked";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access removed";
+            readonly message: "Your agent's access was removed. Approve access again to continue.";
+        };
+    };
+    readonly 'account.grant_scope_unsupported': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "browser"];
+        readonly status: 400;
+        readonly title: "Grant scope cannot pay with this method";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Access can't pay this way";
+            readonly message: "This kind of access can't pay this way. Set up access for specific services.";
+        };
+    };
+    readonly 'account.limit_exceeded': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 403;
+        readonly title: "Amount exceeds the grant or session spending cap";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Over your spending limit";
+            readonly message: "This costs more than your agent is allowed to spend. Raise the limit to continue.";
+        };
+    };
+    readonly 'account.mandate_inactive': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 402;
+        readonly title: "Subscription mandate is paused or cancelled";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Subscription not active";
+            readonly message: "Your subscription is paused or cancelled. Renew it to continue.";
+        };
+    };
+    readonly 'account.mandate_not_found': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 402;
+        readonly title: "Subscription mandate not found";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "No subscription";
+            readonly message: "You don't have a subscription for this. Subscribe to continue.";
+        };
+    };
+    readonly 'account.mandate_period_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 402;
+        readonly title: "Requested period is outside the mandate";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Outside your subscription";
+            readonly message: "This falls outside your subscription's dates.";
+        };
+    };
+    readonly 'account.policy_conflict': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 409;
+        readonly title: "More than one policy matches the payment";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Spending rules overlap";
+            readonly message: "More than one of your spending rules matches this payment. Fix your rules to continue.";
+        };
+    };
+    readonly 'account.policy_missing': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Account has no active policies or profiles";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "No spending rules";
+            readonly message: "Add a spending rule before you connect an agent.";
+        };
+    };
+    readonly 'account.policy_rejected': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted", "browser"];
+        readonly status: 403;
+        readonly title: "Payment is outside the allowed policy";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Not allowed by your rules";
+            readonly message: "This payment is outside what your spending rules allow.";
+        };
+    };
+    readonly 'account.spend_account_missing': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Owner has no spend account";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "add_funds";
+        readonly user: {
+            readonly title: "No spending account";
+            readonly message: "Create and fund a spending account first.";
+        };
+    };
+    readonly 'account.spend_account_not_deployed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 503;
+        readonly title: "Spending account package is not deployed on this network";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly retryAfterSeconds: 60;
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Not available on this network";
+            readonly message: "You can't use spending accounts on this network yet.";
+        };
+    };
+    readonly 'account.spend_account_package_mismatch': {
+        readonly surfaces: readonly ["gateway", "sdk"];
+        readonly status: 409;
+        readonly title: "Spend account was published under a different package";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Spending account out of date";
+            readonly message: "Your spending account is from an older version. Set up a new one to continue.";
+        };
+    };
+    readonly 'account.recipient_rejected': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Recipient is not allowed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Recipient not allowed";
+            readonly message: "You can't pay that recipient from here.";
+        };
+    };
+    readonly 'account.session_expired': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Spending session has expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Session expired";
+            readonly message: "Your spending session has expired. Start a new one to continue.";
+        };
+    };
+    readonly 'account.session_inactive': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Spending session is not active";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Session not active";
+            readonly message: "Your spending session isn't active. Start a new one to continue.";
+        };
+    };
+    readonly 'account.session_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Session request does not match the session grant or amount rules";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Session can't be used";
+            readonly message: "This request doesn't fit your spending session. Check the amount and try again.";
+        };
+    };
+    readonly 'account.session_state_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Session state or accounting is inconsistent";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "contact_support";
+        readonly user: {
+            readonly title: "Session needs review";
+            readonly message: "Your spending session is in a state we can't use. Contact support with the code below.";
+        };
+    };
+    readonly 'account.too_many_coins': {
+        readonly surfaces: readonly ["sdk", "browser"];
+        readonly status: null;
+        readonly title: "Payment would need too many coin objects";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Funds too split up";
+            readonly message: "Your funds are split into too many pieces. Combine them and try again.";
+        };
+    };
+    readonly 'auth.client_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "OAuth client is unknown or failed authentication";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "App not recognized";
+            readonly message: "The app you're connecting isn't registered. Connect it again.";
+        };
+    };
+    readonly 'auth.client_metadata_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "OAuth client registration metadata is invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "App details not accepted";
+            readonly message: "The app's registration details aren't valid. Fix them and try again.";
+        };
+    };
+    readonly 'auth.clock_skew': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Signed request timestamp is outside the allowed skew";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Clock out of sync";
+            readonly message: "Your device's clock is off. Fix the time and try again.";
+        };
+    };
+    readonly 'auth.connection_binding_mismatch': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 401;
+        readonly title: "Bearer connection is bound to a different principal";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Connection not valid";
+            readonly message: "Your agent's connection doesn't match this account. Connect it again.";
+        };
+    };
+    readonly 'auth.connection_denied': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 401;
+        readonly title: "Agent connection was revoked or is missing";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access removed";
+            readonly message: "Your agent's access was removed. Approve access again to continue.";
+        };
+    };
+    readonly 'auth.connection_expired': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 409;
+        readonly title: "Agent connection has expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Access expired";
+            readonly message: "Your agent's access has expired. Approve access again to continue.";
+        };
+    };
+    readonly 'auth.connection_not_found': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted", "browser"];
+        readonly status: 404;
+        readonly title: "Agent connection not found";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Connection not found";
+            readonly message: "We couldn't find your agent's connection. Connect it again.";
+        };
+    };
+    readonly 'auth.connection_required': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 401;
+        readonly title: "An agent connection is required";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "Connect your agent";
+            readonly message: "Connect your agent to your account to continue.";
+        };
+    };
+    readonly 'auth.forbidden': {
+        readonly surfaces: readonly ["gateway", "console_server", "sdk"];
+        readonly status: 403;
+        readonly title: "Caller is not allowed to perform this action";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: {
+            readonly title: "Not allowed";
+            readonly message: "You don't have permission to do this.";
+        };
+    };
+    readonly 'auth.grant_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Authorization code or refresh token is invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Sign-in no longer valid";
+            readonly message: "Your sign-in is no longer valid. Sign in again.";
+        };
+    };
+    readonly 'auth.grant_type_unsupported': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "OAuth grant type is not supported";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Sign-in method not supported";
+            readonly message: "The app you're connecting asked to sign in a way we don't support.";
+        };
+    };
+    readonly 'auth.login_required': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "Local agent has no usable credentials";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Sign in first";
+            readonly message: "Your agent isn't signed in yet. Sign in from your agent to continue.";
+        };
+    };
+    readonly 'auth.nonce_replayed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Signed request nonce was already used";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Request already used";
+            readonly message: "This signed request was already used. Send a new one.";
+        };
+    };
+    readonly 'auth.redirect_uri_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "OAuth redirect URI is not registered or not allowed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "App address not allowed";
+            readonly message: "The app's return address isn't allowed. Check the app's settings.";
+        };
+    };
+    readonly 'auth.required': {
+        readonly surfaces: readonly ["gateway", "console_server", "sdk", "mcp_hosted"];
+        readonly status: 401;
+        readonly title: "Authentication required";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Sign in required";
+            readonly message: "You need to sign in to continue.";
+        };
+    };
+    readonly 'auth.resource_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "OAuth resource indicator does not match this server";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Wrong service address";
+            readonly message: "The app asked for access to a different address. Connect it again.";
+        };
+    };
+    readonly 'auth.response_type_unsupported': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "OAuth response type is not supported";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Sign-in method not supported";
+            readonly message: "The app you're connecting asked to sign in a way we don't support.";
+        };
+    };
+    readonly 'auth.scope_insufficient': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 403;
+        readonly title: "Token scope does not cover this action";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "approve_access";
+        readonly user: {
+            readonly title: "More access needed";
+            readonly message: "Your agent needs more access for this. Approve the extra access to continue.";
+        };
+    };
+    readonly 'auth.scope_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Requested OAuth scope is invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Access request not valid";
+            readonly message: "The app asked for access that doesn't exist. Check the app's settings.";
+        };
+    };
+    readonly 'auth.sign_in_expired': {
+        readonly surfaces: readonly ["console_server", "browser"];
+        readonly status: 401;
+        readonly title: "Wallet sign-in challenge expired or is unknown";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Sign-in expired";
+            readonly message: "Your sign-in request expired. Sign in again.";
+        };
+    };
+    readonly 'auth.sign_in_failed': {
+        readonly surfaces: readonly ["console_server", "browser"];
+        readonly status: 401;
+        readonly title: "Wallet sign-in signature did not verify";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Couldn't sign you in";
+            readonly message: "We couldn't verify your wallet signature. Try signing in again.";
+        };
+    };
+    readonly 'auth.signature_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Request signature does not verify";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Signature not valid";
+            readonly message: "Your request's signature didn't check out. Sign it again with the right key.";
+        };
+    };
+    readonly 'auth.signed_request_expired': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Signed request timestamp has expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Request expired";
+            readonly message: "Your signed request is too old. Send a new one.";
+        };
+    };
+    readonly 'auth.signed_request_malformed': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Signed request headers are missing or malformed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Signed request incomplete";
+            readonly message: "Your request is missing signing details. Update your app and try again.";
+        };
+    };
+    readonly 'auth.signer_not_delegate': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 401;
+        readonly title: "Signer is not the grant's delegate";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Wrong key";
+            readonly message: "This key isn't the one your access was given to. Use the right key.";
+        };
+    };
+    readonly 'auth.token_invalid': {
+        readonly surfaces: readonly ["gateway", "mcp_hosted"];
+        readonly status: 401;
+        readonly title: "Bearer token is invalid or expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "sign_in";
+        readonly user: {
+            readonly title: "Sign in again";
+            readonly message: "Your sign-in is no longer valid. Sign in again to continue.";
+        };
+    };
+    readonly 'request.body_invalid': {
+        readonly surfaces: readonly ["gateway", "console_server", "sdk"];
+        readonly status: 400;
+        readonly title: "Request body does not match the service's schema";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check your request";
+            readonly message: "Some details you sent aren't what this service expects. Fix them and try again.";
+        };
+    };
+    readonly 'request.body_too_large': {
+        readonly surfaces: readonly ["gateway", "seller", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 413;
+        readonly title: "Request body exceeds the size limit";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Request too large";
+            readonly message: "What you sent is larger than this service accepts. Send less and try again.";
+        };
+    };
+    readonly 'request.clock_not_controllable': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Clock is not controllable on this deployment";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Clock control not available";
+            readonly message: "You can't change the clock in this environment.";
+        };
+    };
+    readonly 'request.clock_not_monotonic': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Clock can only move forward";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Clock can only move forward";
+            readonly message: "You can only move the clock forward. Pick a later time.";
+        };
+    };
+    readonly 'request.conflict': {
+        readonly surfaces: readonly ["gateway", "console_server"];
+        readonly status: 409;
+        readonly title: "Resource state conflicts with the request";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Already changed";
+            readonly message: "This was changed somewhere else. Reload and try again.";
+        };
+    };
+    readonly 'request.credential_ambiguous': {
+        readonly surfaces: readonly ["gateway", "seller"];
+        readonly status: 400;
+        readonly title: "Request carries more than one payment credential";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Payment not accepted";
+            readonly message: "You sent two kinds of payment at once. Send only one.";
+        };
+    };
+    readonly 'request.expired': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 410;
+        readonly title: "Session or pending request expired";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Request expired";
+            readonly message: "This request has expired. Start again.";
+        };
+    };
+    readonly 'request.feature_retired': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 410;
+        readonly title: "Feature has been retired";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "No longer available";
+            readonly message: "This option was retired. Use the current version of the app.";
+        };
+    };
+    readonly 'request.file_args_invalid': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File and field arguments are incomplete or conflicting";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File options incomplete";
+            readonly message: "Give both the file and a new field name, and only on a POST request.";
+        };
+    };
+    readonly 'request.file_empty': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File is empty";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File is empty";
+            readonly message: "The file you chose is empty. Pick a file with content.";
+        };
+    };
+    readonly 'request.file_forbidden': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File is in a protected folder";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File can't be used";
+            readonly message: "That file is in a protected folder. Pick a file outside it.";
+        };
+    };
+    readonly 'request.file_invalid': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File path is not a readable regular file";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File can't be read";
+            readonly message: "Give the full path to a regular file on this computer.";
+        };
+    };
+    readonly 'request.file_not_found': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File not found";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File not found";
+            readonly message: "No file exists at that path. Check the path and try again.";
+        };
+    };
+    readonly 'request.file_outside_root': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File is outside the allowed folder";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File outside allowed folder";
+            readonly message: "You can only send files from the folder set up for uploads.";
+        };
+    };
+    readonly 'request.file_root_unset': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "Upload folder is not configured";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Upload folder not set";
+            readonly message: "Set an upload folder for your agent before you send files.";
+        };
+    };
+    readonly 'request.file_too_large': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File exceeds the size limit";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File too large";
+            readonly message: "That file is larger than the limit. Pick a smaller file.";
+        };
+    };
+    readonly 'request.file_unreadable': {
+        readonly surfaces: readonly ["mcp_local"];
+        readonly status: null;
+        readonly title: "File is not readable by the agent process";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "File can't be opened";
+            readonly message: "You don't have permission to read that file.";
+        };
+    };
+    readonly 'request.invalid': {
+        readonly surfaces: readonly ["gateway", "seller", "console_server", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 400;
+        readonly title: "Request is invalid";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check your request";
+            readonly message: "Something in your request isn't valid. Fix it and try again.";
+        };
+    };
+    readonly 'request.local_only': {
+        readonly surfaces: readonly ["mcp_hosted"];
+        readonly status: 400;
+        readonly title: "Only available on the local agent server";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Only in the local agent tool";
+            readonly message: "This works only when your agent runs on your own computer.";
+        };
+    };
+    readonly 'request.method_not_allowed': {
+        readonly surfaces: readonly ["gateway", "seller", "console_server"];
+        readonly status: 405;
+        readonly title: "Method not allowed on this path";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Method not allowed";
+            readonly message: "You can't send that kind of request to this address.";
+        };
+    };
+    readonly 'request.network_mismatch': {
+        readonly surfaces: readonly ["gateway", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 400;
+        readonly title: "Request targets a different network or deployment";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Wrong network";
+            readonly message: "This is set up for a different network. Switch networks and try again.";
+        };
+    };
+    readonly 'request.not_found': {
+        readonly surfaces: readonly ["gateway", "seller", "console_server"];
+        readonly status: 404;
+        readonly title: "Not found";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Not found";
+            readonly message: "We couldn't find what you asked for. Check the address and try again.";
+        };
+    };
+    readonly 'request.origin_already_listed': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 422;
+        readonly title: "Origin is an already-listed managed product";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Already listed";
+            readonly message: "That service is already in the catalog. Add your own seller address instead.";
+        };
+    };
+    readonly 'request.origin_not_public': {
+        readonly surfaces: readonly ["seller", "console_server"];
+        readonly status: 422;
+        readonly title: "Origin resolves to a private or reserved address";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Address not public";
+            readonly message: "You can only use a public web address here.";
+        };
+    };
+    readonly 'request.origin_not_seller': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 422;
+        readonly title: "Origin serves no valid seller setup document";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "No seller found";
+            readonly message: "We found no valid seller setup at that address. Check it and try again.";
+        };
+    };
+    readonly 'request.origin_self_hosted': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 422;
+        readonly title: "Origin issues its own payment challenges";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Seller takes its own payments";
+            readonly message: "That seller takes payments itself. Add a managed seller address instead.";
+        };
+    };
+    readonly 'request.origin_unreachable': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 422;
+        readonly title: "Origin could not be reached";
+        readonly paymentState: "not_charged";
+        readonly retry: "safe";
+        readonly nextAction: "retry";
+        readonly user: {
+            readonly title: "Couldn't reach that address";
+            readonly message: "We couldn't reach that address. Check it and try again.";
+        };
+    };
+    readonly 'request.origin_unresolved': {
+        readonly surfaces: readonly ["console_server"];
+        readonly status: 422;
+        readonly title: "Origin hostname did not resolve";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Address not found";
+            readonly message: "That web address doesn't exist. Check the spelling and try again.";
+        };
+    };
+    readonly 'request.redirect_refused': {
+        readonly surfaces: readonly ["console_server", "sdk"];
+        readonly status: 422;
+        readonly title: "Target redirected and the redirect was refused";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Address redirects elsewhere";
+            readonly message: "That address sends you somewhere else. Use the final address instead.";
+        };
+    };
+    readonly 'request.route_conflict': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Route is already used by another service";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Path already in use";
+            readonly message: "Another service already uses that path. Pick a different one.";
+        };
+    };
+    readonly 'request.secret_refused': {
+        readonly surfaces: readonly ["console_server", "browser", "sdk"];
+        readonly status: 400;
+        readonly title: "Request contained a private key";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Private key not accepted";
+            readonly message: "Never send a private key. Your key stays on your device.";
+        };
+    };
+    readonly 'request.service_definition_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Service registration has a missing or invalid field";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check your service details";
+            readonly message: "Some service details are missing or not valid. Fix them and publish again.";
+        };
+    };
+    readonly 'request.service_id_taken': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Service id is already registered";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "ID already taken";
+            readonly message: "Another service already uses that ID. Pick a different one.";
+        };
+    };
+    readonly 'request.service_inactive': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 403;
+        readonly title: "Service is paused, revoked or not listed";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: {
+            readonly title: "Service not available";
+            readonly message: "You can't use this service right now because it isn't taking requests.";
+        };
+    };
+    readonly 'request.service_logo_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 400;
+        readonly title: "Service logo is not accepted";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Logo not accepted";
+            readonly message: "Use a smaller image in a supported format for your logo.";
+        };
+    };
+    readonly 'request.service_terminal': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Service is in a terminal state";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "none";
+        readonly user: {
+            readonly title: "Service retired";
+            readonly message: "This service was retired, so you can't change it.";
+        };
+    };
+    readonly 'request.transition_invalid': {
+        readonly surfaces: readonly ["gateway"];
+        readonly status: 409;
+        readonly title: "Status change is not allowed from the current state";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Can't make that change";
+            readonly message: "You can't make that change while the service is in its current state.";
+        };
+    };
+    readonly 'request.url_invalid': {
+        readonly surfaces: readonly ["seller", "console_server", "sdk", "mcp_local", "mcp_hosted"];
+        readonly status: 400;
+        readonly title: "URL is missing, malformed or on the wrong origin";
+        readonly paymentState: "not_charged";
+        readonly retry: "never";
+        readonly nextAction: "fix_request";
+        readonly user: {
+            readonly title: "Check the address";
+            readonly message: "Enter a complete web address that starts with https and try again.";
+        };
+    };
+};
+type Registry = typeof ERRORS;
+/** Every registered code. */
+type ErrorCode = keyof Registry & string;
+/** The codes a given surface may originate. Builders are typed with this. */
+type CodeFor<S extends Surface> = {
+    [K in ErrorCode]: S extends Registry[K]['surfaces'][number] ? K : never;
+}[ErrorCode];
+
+/**
+ * Non-MCP SDK/REST delegated-signer payer (Phase C1).
+ *
+ * MPP pay-then-prove over `spend_account::settle_policy` with a bring-your-own
+ * delegated key. Mirrors packages/mcp/src/spend-account-pay.ts but:
+ *   - gas: agent-provided coins (default when configured) OR sponsored gas
+ *     gated by sponsor personal-message challenge (Phase C2 / ADR-0008)
+ *   - x402 (`dialect: 'x402'`) signs the pay with the offer's pinned sponsor
+ *     gas and presents it as PAYMENT-SIGNATURE; the gateway co-signs and
+ *     submits (docs/decisions/ADR-0045-delegate-x402-from-the-spend-account.md)
+ *
+ * Order is load-bearing on the money path (no step may run before the prior):
+ *   1. Bound the offer FIRST — the gateway secret's HMAC over it, the agent's
+ *      own SpendIntent, or both; at least one is required. Nothing else
+ *      (ledger, capability, hashing) runs before this.
+ *   2. Request-binding + offer-expiry checks.
+ *   3. ATOMIC reserve on the REQUIRED payment-attempt ledger (payment_id).
+ *      - reserved  -> this attempt owns the id; may proceed to build/sign
+ *      - done      -> return validated prior ok/ambiguous (no re-sign)
+ *      - in_flight -> another attempt is mid-flight; return ambiguous (no sign)
+ *      Reserve failure fails closed: never sign without a durable claim.
+ *   4. Execution-capability check (submitter present). After reserve so a
+ *      prior done result is never lost when capability is unavailable.
+ *   5. Derive payment_id_hash / terms_hash.
+ *   6. Build the full executable pay transaction (real shared-object versions).
+ *   7. Validate-before-sign (built tx encodes exactly the intended pay; gas may differ).
+ *   8. Sign, 9. execute, 10. complete(ledger) with terminal ok/ambiguous, settle.
+ *   x402 refuses before 3 when its offer, gas pins or epoch are missing, skips
+ *   4, builds 6 with the offer-pinned sponsor gas, and in place of 9-10
+ *   presents the signed credential (the gateway co-signs and submits).
+ *
+ * Exactly-once for concurrent pay() on the same payment_id is the ledger
+ * reserve CAS (memory: sync check-and-insert; Postgres: INSERT ON CONFLICT).
+ * Settlement single-use on chain is the pool-scoped payment_id_hash replay
+ * marker inside pay. The durable ChallengeStore is a delivery/proof CAS
+ * (prevents a second proof/delivery for the same challenge), not the money
+ * CAS (see ADR-0002).
+ */
+
+type DelegatedPayStatus = 'ok' | 'failed' | 'ambiguous';
+/**
+ * Classification of a resource's non-402 response. Distinguishes a resource
+ * served without payment (`unpaid_ok`, a 2xx) from a client-side refusal
+ * (`rejected`, a non-2xx below 500) and a transient outage (`unavailable`, a
+ * 5xx) — so a caller never mistakes a 503 for "already paid / ok". Absent on a
+ * 402-driven pay outcome, which the `status`/`code`/`paid` fields describe.
+ */
+type DelegatedPayResponseClass = 'unpaid_ok' | 'rejected' | 'unavailable';
+/**
+ * The settled effects of a finality-confirmed pay, so a caller need not do a
+ * separate on-chain read to learn what moved. `spend_account::settle_policy` debits exactly
+ * `amount` of `coinType` to `recipient` from the grant's pool, and a `success`
+ * finality confirms that transfer executed — so these are the settled effects,
+ * not merely the intended ones. Present only on a settled (`paid`) result.
+ */
+interface DelegatedPaySettlement {
+    /** Finality-confirmed settlement status (only `success` reaches a paid result). */
+    status: 'success';
+    /** The settling transaction digest. */
+    txDigest: string;
+    /** Atomic units debited to the recipient (the offer amount the pay enforced). */
+    amount: string;
+    /** The paid recipient (the offer/target payTo the pay debited to). */
+    recipient: string;
+    /** Coin type settled. */
+    coinType: string;
+    /** Off-chain asset id of the offer. */
+    asset: string;
+    /** Grant object that authorized the draw. */
+    grantObjectId: string;
+    /** Pool object the draw debited. */
+    poolObjectId: string;
+}
+interface DelegatedPayResult {
+    /**
+     * How resolved the outcome is: `ok` = settled AND delivered; `ambiguous` =
+     * something after the signature is unresolved, so reconcile rather than retry;
+     * `failed` = nothing was signed, or the chain rejected the settlement.
+     */
+    status: DelegatedPayStatus;
+    /**
+     * Did money leave the grant?
+     *
+     * - `true` — settlement was finality-confirmed `success`. {@link settlement}
+     *   carries the confirmed effects.
+     * - `false` — nothing was signed, or the chain rejected the settlement. The
+     *   money is still in the pool.
+     * - `'unknown'` — a signature left this process and execute/finality did not
+     *   resolve. The money may have moved. A caller that treats this as `false`
+     *   and retries will pay twice. `if (!result.paid)` is false for `'unknown'`.
+     */
+    paid: boolean | 'unknown';
+    /**
+     * Whether money moved, in the registry's words. Always agrees with `paid`:
+     * `charged` ↔ `true`, `not_charged` ↔ `false`, `unknown` ↔ `'unknown'`. On a
+     * result that is not `ok`, `failed` ⇔ `not_charged`.
+     */
+    paymentState: PaymentState;
+    body?: unknown;
+    receipt?: Receipt | null;
+    /**
+     * The registry code of a failed or ambiguous result. A gateway problem
+     * document's code is kept as received, including one this SDK's registry
+     * does not know yet (a newer gateway); a legacy gateway string never is.
+     * Branch on this.
+     */
+    code?: ErrorCode | (string & {});
+    /** True only when retrying cannot charge twice; derived, never guessed. */
+    retryable?: boolean;
+    /** What the caller should do next; derived from the code and the money state. */
+    nextAction?: NextAction;
+    /** The offer's challenge id (the same value as `paymentId`), when known. */
+    challengeId?: string;
+    /** Resource HTTP status for a non-402 outcome (preserved, not swallowed). */
+    httpStatus?: number;
+    /** Classification of a non-402 outcome; see {@link DelegatedPayResponseClass}. */
+    responseClass?: DelegatedPayResponseClass;
+    /** Caller-safe detail only; never raw RPC/gateway exception text. */
+    detail?: string;
+    /**
+     * On-chain digest when known. For digestless ambiguity after a possible
+     * broadcast, set to {@link BROADCAST_UNKNOWN}.
+     */
+    txDigest?: string;
+    /** payment_id = offer.challengeId; reconcile key on ambiguous outcomes. */
+    paymentId?: string;
+    /**
+     * Settled effects (amount/recipient/status) of a finality-confirmed pay.
+     * Present on every `paid` result, including a settled pay whose delivery then
+     * failed — that is exactly the case where a caller cannot afford to guess.
+     */
+    settlement?: DelegatedPaySettlement;
+}
+/**
+ * Non-secret connection manifest produced at authorize-agent success.
+ * Enough for the agent to resolve grant/policy/target without owner SIWS.
+ */
+interface DelegatedSignerConnectionManifest {
+    network: string;
+    packageId: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    coinType: string;
+    delegateAddress: string;
+    /** Off-chain grant id for audit; optional. */
+    grantId?: string;
+    status?: GrantSnapshot['status'];
+    policies: GrantSnapshot['policies'];
+    /** Delegation-grant ceiling (on-chain Move type: `GrantCap.max_per_payment`). */
+    maxPerPayment?: string;
+    /** Grant-level session cap. Required positive for open surface. */
+    sessionCap?: string;
+    /** `open` = full access (no allowlist); omit/scoped = policy-bound. */
+    accessMode?: 'scoped' | 'open';
+}
+/** Signer callback: address + sign over full transaction bytes (base64). */
+interface DelegatedKeySigner {
+    address: string;
+    signTransaction(txBytes: string): Promise<string>;
+    /**
+     * Personal-message signature (Sui IntentScope.PersonalMessage). Required
+     * for the sponsored-gas personal-message path; not used when the agent supplies gas.
+     */
+    signPersonalMessage?(message: Uint8Array): Promise<string>;
+}
+/**
+ * Platform gas sponsorship client for BYO personal-message (ADR-0008). The payer obtains
+ * a single-use nonce, signs the domain-separated personal-message over the pre-sponsor
+ * kind hash, then create+execute the sponsored pay. The x402 dialect does not
+ * use it: there the gateway co-signs the offer-pinned gas (ADR-0045).
+ */
+interface SponsoredGasClient {
+    /** Gateway origin hosting /api/sponsor (no trailing slash). */
+    sponsorUrl: string;
+    fetchImpl?: typeof fetch;
+}
+type DelegatedSignerInput = DelegatedKeySigner | Ed25519Keypair | (() => Promise<DelegatedKeySigner> | DelegatedKeySigner);
+/**
+ * Authority for one payment. Prefer an in-process snapshot/manifest; a
+ * read-only fetch callback may load the same shape from a connection
+ * manifest or a read endpoint the agent is allowed to call.
+ */
+type GrantResolutionSource = GrantSnapshot | DelegatedSignerConnectionManifest | (() => Promise<GrantSnapshot | DelegatedSignerConnectionManifest>);
+interface DelegatedPayerSession {
+    /** Package id of the published spend_account module (must match offer). */
+    packageId: string;
+    /** Network as offer.network expects, e.g. `sui:testnet`. */
+    network: string;
+    /** Grant + pool + policies for resolveGrantTarget. */
+    authority: GrantResolutionSource;
+    /** BYO delegated key (keypair or sign callback). Never platform-custodied. */
+    signer: DelegatedSignerInput;
+    /**
+     * Optional re-check immediately before sign (pause/revoke race). Throw to
+     * abort. When absent, request-time snapshot is the only pre-sign gate.
+     */
+    assertLive?: () => Promise<void>;
+}
+/** Gas coin ref for a complete executable transaction. */
+interface GasPaymentRef {
+    objectId: string;
+    version: string | number | bigint;
+    digest: string;
+}
+interface AgentGasInput {
+    budget?: string | number | bigint;
+    price?: string | number | bigint;
+    payment: GasPaymentRef[];
+    /** Defaults to the delegate (sender). */
+    owner?: string;
+}
+/**
+ * Inputs for building a complete executable spend_account::settle_policy transaction
+ * (sender + gas + move call). Not kind-only bytes.
+ *
+ * Pool and grant must carry real initial shared versions from chain (not a
+ * hard-coded "1"). Mirror SpendAccountChain.buildPayKind / MCP production path
+ * which resolve via getObject / tx.object + client.
+ */
+interface BuildPayTxInput {
+    packageId: string;
+    delegate: string;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    /** Real initial shared version of the pool object (from chain). */
+    poolInitialSharedVersion: string;
+    /** Real initial shared version of the grant object (from chain). */
+    grantInitialSharedVersion: string;
+    /**
+     * Initial shared version of the system Clock (0x6). Defaults to genesis
+     * version "1" when omitted.
+     */
+    clockInitialSharedVersion?: string;
+    policyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+    gas: AgentGasInput;
+    /**
+     * Guarded settle inputs. Present for a guarded delegate offer; when set the
+     * builder emits `settle_policy` threading the exclusion directory +
+     * per-recipient registry (each as a shared object ref built from its initial
+     * shared version) + signed expiry. Required on the fresh lineage even for a
+     * single-rail settle (there is no unguarded twin).
+     */
+    exclusionDirectoryId?: string;
+    recipientRegistryId?: string;
+    exclusionDirectoryInitialSharedVersion?: string;
+    recipientRegistryInitialSharedVersion?: string;
+    expiresAtMs?: string | number;
+}
+/**
+ * Result of an atomic payment-id reserve (exactly-once attempt claim).
+ *
+ * - reserved: this caller owns the attempt; only then may build/sign/execute
+ * - in_flight: another attempt is mid-flight (or complete never landed); do not sign
+ * - done: a terminal ok/ambiguous is recorded; return validated prior
+ */
+type PaymentAttemptReserveResult = {
+    state: 'reserved';
+} | {
+    state: 'in_flight';
+    prior?: DelegatedPayResult;
+} | {
+    state: 'done';
+    prior: DelegatedPayResult;
+};
+/**
+ * Durable ledger of payment attempts keyed by payment_id (offer.challengeId).
+ * REQUIRED on the pay path. Exactly-once is reserve-before-sign:
+ *   reserve (atomic) -> build/validate/sign/execute only if reserved -> complete
+ * Persistence failure fails closed (never sign without a durable claim).
+ */
+interface PaymentAttemptLedger {
+    /**
+     * Atomically claim paymentId for this attempt, or report prior/in-flight.
+     * Must not interleave another reserve for the same id between check and claim
+     * (memory: sync Map check-and-insert; Postgres: INSERT ON CONFLICT DO NOTHING).
+     */
+    reserve(paymentId: string, fingerprint: string): Promise<PaymentAttemptReserveResult>;
+    /**
+     * Write the terminal ok/ambiguous result for a reserved payment_id.
+     * After complete, further reserve() calls return state:'done' with prior.
+     * Throws on persistence failure (caller must not swallow).
+     */
+    complete(paymentId: string, result: DelegatedPayResult): Promise<void>;
+    /**
+     * Drop an in-flight reservation when no sign/execute happened (clean abort).
+     * No-op when the row is already terminal. Optional; missing release leaves
+     * in_flight so retries stay fail-closed (ambiguous, no re-sign).
+     */
+    release?(paymentId: string): Promise<void>;
+}
+/**
+ * Resolve real initial shared versions for pool + grant from chain.
+ * Production should call getObject (or SpendAccountChain-equivalent resolution).
+ */
+type ResolveSharedObjectVersions = (ids: {
+    poolObjectId: string;
+    grantObjectId: string;
+    clockObjectId?: string;
+}) => Promise<{
+    poolInitialSharedVersion: string;
+    grantInitialSharedVersion: string;
+    clockInitialSharedVersion?: string;
+}>;
+/**
+ * One step of an x402 payment, reported as it happens so a caller can show it
+ * (the console playground's timeline). `presented` and `answered` repeat once
+ * per presentation while the gateway answers 503.
+ */
+type X402PayProgress = {
+    stage: 'built';
+    txBytes: string;
+} | {
+    stage: 'signed';
+    signature: string;
+} | {
+    stage: 'presented';
+    header: string;
+    attempt: number;
+} | {
+    stage: 'answered';
+    status: number;
+    paymentResponse: string | null;
+    attempt: number;
+};
+interface DelegatedPayerDeps {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /**
+     * The gateway's HMAC secret, when the caller legitimately holds one — an
+     * operator running its own gateway, or a test. Present: offer digests are
+     * verified client-side before any ledger, capability, hash, build, or sign.
+     *
+     * Optional, because an external agent must never be given it: it is the
+     * secret that authenticates the gateway to itself, and handing it out makes
+     * every holder able to forge offers for every other. An agent without it
+     * supplies a {@link SpendIntent} instead. One of the two is REQUIRED — with
+     * neither, nothing bounds what the offer may charge, and payment is refused
+     * before any ledger, hash, build, or sign.
+     */
+    offerSecret?: string;
+    /**
+     * REQUIRED payment-attempt ledger. Absent ledger refuses to pay (config
+     * error) rather than run an unprotected re-sign/rebroadcast path.
+     */
+    paymentLedger: PaymentAttemptLedger;
+    /**
+     * Build a COMPLETE executable pay transaction (delegate sender, gas,
+     * real move call). Default uses {@link buildSpendAccountPayTx} with
+     * {@link gas}. Must never return kind-only non-executable bytes.
+     */
+    buildPayTx?: (input: BuildPayTxInput) => Promise<{
+        txBytes: string;
+    }>;
+    /**
+     * Agent-owned gas payment objects for the default full-tx builder.
+     * Required when buildPayTx is not injected and sponsor is not set.
+     * When both `gas` and `sponsor` are set, `gasMode` selects the path
+     * (default: agent gas when `gas` is present, else sponsored).
+     */
+    gas?: AgentGasInput;
+    /**
+     * Sponsored-gas path gated by sponsor personal-message challenge (Phase C2).
+     * Alternative to agent-provided gas. Keep agent gas as the other option.
+     */
+    sponsor?: SponsoredGasClient;
+    /**
+     * Force gas path when both agent gas and sponsor are configured.
+     * Default: `'agent'` when `gas` has payment objects, else `'sponsored'`.
+     */
+    gasMode?: 'agent' | 'sponsored';
+    /**
+     * Resolve real initial shared versions for pool/grant. Required for the
+     * default full-tx builder when {@link sharedObjectVersions} is not set.
+     * Mirror SpendAccountChain.buildPayKind (getObject Shared owner / tx.object).
+     */
+    resolveSharedObjectVersions?: ResolveSharedObjectVersions;
+    /**
+     * Pre-resolved pool/grant initial shared versions (tests / offline inject).
+     * When set, skips {@link resolveSharedObjectVersions}.
+     */
+    sharedObjectVersions?: {
+        poolInitialSharedVersion: string;
+        grantInitialSharedVersion: string;
+        clockInitialSharedVersion?: string;
+    };
+    /**
+     * Resolve the per-recipient `RecipientRegistry` object id + directory/registry
+     * shared versions for a guarded delegate offer. REQUIRED for a
+     * guarded offer: without it such an offer FAILS CLOSED (BUILD_FAILED) —
+     * it never builds an unguarded settle, which the self-settled verifier would
+     * reject anyway. An unguarded offer never calls it. In production this binds
+     * the shared `resolveExclusionRegistry`
+     * (`buyer-control/exclusion-registry`) to a live chain
+     * reader — which supplies the shared versions at runtime; tests stub it.
+     */
+    resolveExclusionRegistry?: (input: {
+        directoryId: string;
+        packageId: string;
+        recipient: string;
+    }) => Promise<{
+        recipientRegistryId: string;
+        directoryInitialSharedVersion?: string;
+        registryInitialSharedVersion?: string;
+    }>;
+    /** Submit signed full transaction bytes; returns the broadcast digest. */
+    executeTx?: (txBytes: string, signature: string) => Promise<{
+        digest: string;
+    }>;
+    /**
+     * Confirm on-chain settlement of a broadcast digest: `success`/`failed`, or
+     * `null` while not yet observed. REQUIRED on any pay that reaches settlement —
+     * a pay is refused (`FINALITY_UNAVAILABLE`) before signing when this is absent,
+     * so a settled tx is never mis-reported as a false `FINALIZATION_TIMEOUT`.
+     */
+    getSettledTx?: (digest: string) => Promise<{
+        status: 'success' | 'failed';
+        reason?: string;
+    } | null>;
+    /**
+     * Await the proof-presentation delivery before returning (DEFAULT `true` —
+     * today's behavior: the result carries the delivered `body` + `receipt`). Set
+     * `false` to return `paid:true` with the digest + settlement summary as soon
+     * as settlement is finality-confirmed, skipping the (possibly slow, e.g.
+     * ~13s Walrus blob-publish) delivery fetch — the caller presents the proof and
+     * fetches the body later. Non-breaking: only an explicit `false` changes flow.
+     */
+    awaitDelivery?: boolean;
+    /**
+     * Current Sui epoch from the agent's own chain client (see
+     * {@link currentEpochReader}). The x402 dialect needs it to bound the
+     * transaction's expiration; absent or failing, x402 is refused before
+     * anything is reserved. MPP never calls it.
+     */
+    getCurrentEpoch?: () => Promise<bigint | number>;
+    /**
+     * Chain identifier from the agent's own chain client (see
+     * {@link chainIdentifierReader}). Needed only for an x402 offer that pins
+     * `address-balance` gas (ADR-0055); absent or failing, that offer is refused
+     * before anything is reserved.
+     */
+    getChainIdentifier?: () => Promise<string>;
+    /**
+     * Build the complete x402 pay transaction. Default
+     * {@link buildSpendAccountX402PayTx}. Whatever it returns is still checked
+     * against the intended pay before signing.
+     */
+    buildX402PayTx?: (input: BuildX402PayTxInput) => Promise<{
+        txBytes: string;
+    }>;
+    /**
+     * Total presentations of one x402 credential while the gateway answers 503
+     * (default 10). The gateway's execution store is single-flight per
+     * challenge, so re-presenting the same credential cannot submit twice.
+     */
+    x402PresentAttempts?: number;
+    /** Wait between x402 re-presentations (default: a 1000 ms timer). */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Server-side log port for internal failure detail. Never surfaces to the
+     * caller result (error hygiene). Defaults to the core structured error
+     * logger (one JSON line, scope `delegated-payer`).
+     */
+    log?: DelegatedPayerLog;
+}
+/** One structured line about an internal payer failure. Never reaches the caller's result. */
+type DelegatedPayerLog = (entry: {
+    code: CodeFor<'sdk'>;
+    msg: string;
+    level?: 'error' | 'warn';
+    context?: Record<string, unknown>;
+}, error?: unknown) => void;
+interface DelegatedPayerConfig {
+    /** Gateway origin the resource URL must match. */
+    gatewayUrl: string;
+}
+/**
+ * The offer-pinned sponsor gas of a delegate x402 offer, parsed. An empty
+ * `payment` is the `address-balance` pin: gas comes from the sponsor's address
+ * balance (ADR-0055).
+ */
+interface X402GasPin {
+    owner: string;
+    budget: bigint;
+    price: bigint;
+    payment: {
+        objectId: string;
+        version: string;
+        digest: string;
+    }[];
+}
+/** Inputs for {@link buildSpendAccountX402PayTx}: the pay kind's fields plus the pinned gas. */
+interface BuildX402PayTxInput extends Omit<BuildPayTxInput, 'gas'> {
+    /** Offer-pinned sponsor gas; see {@link readX402GasPin}. */
+    gas: X402GasPin;
+    /** Current epoch; the transaction expires 32 epochs after it. */
+    currentEpoch: bigint;
+    /**
+     * Chain identifier. Required when `gas.payment` is empty (address-balance
+     * gas), which takes a `ValidDuring` expiration instead of `Epoch`.
+     */
+    chainIdentifier?: string;
+    /** `ValidDuring` nonce for address-balance gas; random u32 when absent. */
+    nonce?: number;
+}
+/**
+ * Pay a shared-pool 402 resource with a BYO delegated key via pay.
+ * MPP by default; `dialect: 'x402'` presents a signed transaction credential
+ * instead (docs/decisions/ADR-0045-delegate-x402-from-the-spend-account.md).
+ *
+ * Ordering is load-bearing: offer verify -> binding/expiry -> reserve ->
+ * capability -> hash -> build -> validate -> sign -> execute -> complete.
+ */
+/**
+ * Economic terms already verified against a prepared settlement kind.
+ *
+ * A caller that verified a kind built from one 402 offer, and then hands the
+ * settlement to this payer, must pin what that verification covered. The payer
+ * mints its own offer from its own 402 hop; without this pin, nothing compares
+ * the two, and the bytes that were checked are not the bytes that get signed.
+ * Absent for direct signer mode, which reads exactly one offer.
+ */
+interface PreparedSettlementTerms {
+    /** Recipient the verified kind pays. */
+    recipient: string;
+    /** Atomic amount the verified kind moves. */
+    amount: string;
+    /** Coin type the verified kind spends. */
+    asset: string;
+    /** Policy target hash the verified kind binds. */
+    targetHash: string;
+}
+/**
+ * The agent's own statement of what it is buying, checked against the offer
+ * before anything else happens.
+ *
+ * This is the input that lets an agent hold nothing but its key and a gateway
+ * URL. The offer HMAC ({@link DelegatedPayerDeps.offerSecret}) proves an offer
+ * came from the party that minted it — which, on this path, is the same gateway
+ * the agent is paying and reached over TLS at an origin the payer already pins.
+ * A gateway that wanted to overcharge never needed to forge its own offer; it
+ * could simply mint an honest one for the wrong amount. So the HMAC was never
+ * the check that protected the agent from its counterparty, and requiring the
+ * agent to hold the gateway's secret to perform it bought nothing while making
+ * every agent able to forge offers for every other.
+ *
+ * What does protect the agent is a ceiling it set itself, which no gateway can
+ * see or change. That is this.
+ */
+interface SpendIntent {
+    /** Inclusive per-payment ceiling in atomic units, as a decimal string. */
+    maxAmount: string;
+    /** The coin type the agent is willing to spend. */
+    asset: string;
+    /**
+     * The exact recipient the agent expects to pay. Optional: an agent buying
+     * from a catalog usually learns `payTo` from the offer itself. When it does
+     * know, pinning it here is the strongest single check available, because
+     * recipient substitution — not overspend — is the attack the caps do not stop.
+     */
+    recipient?: string;
+}
+/** Optional guarded-settle fields carried on a build input. */
+interface GuardedSettleFields {
+    exclusionDirectoryId?: string;
+    recipientRegistryId?: string;
+    exclusionDirectoryInitialSharedVersion?: string;
+    recipientRegistryInitialSharedVersion?: string;
+    expiresAtMs?: string | number;
+}
+
+/**
+ * Agent-held settlement wiring for the `pay` tool.
+ *
+ * The gateway prepares (it holds no key). Settlement needs the delegate key, so
+ * it can only happen in the process that holds one. This module answers a single
+ * question for a given grant: *is this process that grant's agent, and is it
+ * configured to settle?* Any "no" returns null and `pay` falls back to handing
+ * back unsigned bytes — the pre-existing behavior.
+ *
+ * Two conditions gate it, and the first is the security one:
+ *
+ * 1. **The persisted key must be the key the grant names.** A hosted gateway
+ *    running this same tool code either holds no credentials file (null) or
+ *    holds one for some unrelated key (address mismatch → null). It can only
+ *    settle by already possessing the grant's delegate seed — which is exactly
+ *    the custody ADR-0015 removed, not a state a flag protects against.
+ * 2. **The settlement dependencies must all be present.** A half-configured
+ *    settler is worse than none: it would sign and then fail to confirm. Missing
+ *    anything → null, prepare-only.
+ *
+ * The key is read, never minted. See `loadLocalSigner`.
+ */
+
+/** Everything `pay` needs to settle rather than prepare. */
+interface AgentHeldSettlement {
+    signer: DelegatedKeySigner;
+    getObjectJson: GetObjectJson;
+    payerDeps: DelegatedPayerDeps;
+}
+/**
+ * Resolve agent-held settlement for one grant, or null to stay prepare-only.
+ * Injectable so `createServer` can be driven without touching disk,
+ * chain, or environment.
+ */
+type AgentHeldResolver = (cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth) => AgentHeldSettlement | null;
+/** Test seam: drop the process ledger so suites do not share reservations. */
+declare function resetAgentHeldProcessLedger(): void;
+declare function resolveAgentHeldSettlement(cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth, env?: NodeJS.ProcessEnv): AgentHeldSettlement | null;
+
+/**
+ * Shared live-trace vocabulary.
+ *
+ * Owned by the SDK because two independent consumers need it: `apps/gateway`,
+ * which emits and stores traces, and `@cmdoss/suipay-mcp`, which proxies them.
+ * A published package cannot reach into a deployed service's source tree for
+ * its own public types, so the names both sides speak live here.
+ *
+ * Gateway-only concerns — the store contract, run keys, redaction brands,
+ * retention limits — stay in `apps/gateway/src/trace/types.ts`, which
+ * re-exports everything below so its existing importers are unaffected.
+ */
+type TraceSource = 'mcp_wire' | 'suipay' | 'sui';
+type TraceStatus = 'started' | 'ok' | 'warning' | 'error' | 'ambiguous';
+type TraceEventKind = 'mcp_connected' | 'tools_listed' | 'tool_called' | 'tool_result' | 'tool_error' | 'challenge_received' | 'authority_matched' | 'authority_revalidated' | 'sponsor_requested' | 'transaction_sponsored' | 'delegate_signed' | 'transaction_submitted' | 'payment_finalized' | 'proof_presented' | 'upstream_delivered' | 'upstream_delivery_failed' | 'settlement_projected' | 'settlement_projection_failed' | 'receipt_issued' | 'payment_failed' | 'payment_ambiguous';
+interface TraceEventInput {
+    traceId: string;
+    requestId: string | null;
+    buyerAccountId: string;
+    connectionId: string;
+    at: string;
+    source: TraceSource;
+    kind: TraceEventKind;
+    status: TraceStatus;
+    summary: string;
+    publicPayload: Record<string, unknown>;
+    technicalPayload?: Record<string, unknown>;
+}
+/**
+ * Correlation constraints an emitter can attach to one event.
+ *
+ * `requireSoleActiveRunForBuyer` is the server-side (ADR-0011) fallback's
+ * atomicity guard: the event is persisted only if, at append time, that buyer
+ * still has exactly one active run. It closes the window between selecting the
+ * sole run and appending to it — a second run opening in between makes the
+ * append fail closed rather than land on a run that is no longer sole.
+ */
+interface TraceEmitOptions {
+    requireSoleActiveRunForBuyer?: string;
+}
+interface TraceSink {
+    emit(event: TraceEventInput, options?: TraceEmitOptions): Promise<void>;
+}
+type TraceRunEndReason = 'completed' | 'idle' | 'superseded' | 'event_cap' | 'byte_cap' | 'shutdown';
+interface TraceRun {
+    id: string;
+    buyerAccountId: string;
+    connectionId: string;
+    clientName: string | null;
+    startedAt: string;
+    lastEventAt: string;
+    endedAt: string | null;
+    endReason: TraceRunEndReason | null;
+    /** Persisted events accepted into this run. */
+    eventCount: number;
+    /** Serialized sanitized payload bytes accepted into this run. */
+    payloadBytes: number;
+}
+interface TraceRunResolver {
+    resolveRun(input: {
+        buyerAccountId: string;
+        connectionId: string;
+        jsonRpcMethod: string | null;
+        clientName: string | null;
+        now: number;
+    }): Promise<TraceRun>;
+}
+
+/**
+ * Transparent MCP wire proxy.
+ *
+ * This module is the *only* place in the system that parses MCP methods and
+ * JSON-RPC ids. The gateway authenticates and hands over a run manager and a
+ * sink; it never sniffs an MCP body a second time. Payment code emits domain
+ * facts, never wire facts. That single-owner rule is what stops two subsystems
+ * from disagreeing about which tool call a payment belongs to.
+ *
+ * Transparency is the top invariant, and it is structural rather than
+ * best-effort:
+ *
+ *  - With no runtime, this file is a pass-through and does not touch the
+ *    request or the response at all.
+ *  - With a runtime, observation reads `Request.clone()` and `Response.clone()`
+ *    only. The exact `Response` instance the handler produced is what the caller
+ *    receives, so byte equality is by construction, not by careful copying.
+ *  - Response observation is started and deliberately not awaited. A trace
+ *    store that hangs cannot hold an MCP response open.
+ *  - The request side cannot be fire-and-forget — the proxy must know the run
+ *    and the JSON-RPC ids before the handler runs — so it is bounded instead:
+ *    one deadline over envelope parsing plus run selection, and the same byte
+ *    cap the response observer uses. A hung store or an oversized body costs
+ *    the trace, never the request.
+ *  - Every observation path is wrapped: a hostile body, a failing run manager or
+ *    a throwing sink degrades to "no trace", never to a changed response.
+ *
+ * Volume control lives here too. One `tool_called` per JSON-RPC id and one
+ * terminal `tool_result` / `tool_error` per id — never one row per SSE frame.
+ */
+
+/** Everything the proxy needs to attribute wire facts to one owned run. */
+interface McpTraceRuntime {
+    buyerAccountId: string;
+    connectionId: string;
+    runs: TraceRunResolver;
+    sink: TraceSink;
+    /**
+     * HMAC secret for signed cross-request context. Supplied by the composition
+     * root so a published SDK never reads a gateway-only environment variable.
+     * Absent means internal hops carry no correlation and the gateway simply
+     * emits no linked events.
+     */
+    secret?: string | null;
+    /** Injected clock; tests pin it, production leaves it out. */
+    now?: () => number;
+}
+/** The proxy-resolved context handed down to payment code (Task 5 seams). */
+interface McpTraceContext {
+    traceId: string;
+    requestId: string | null;
+}
+interface McpTraceHooks {
+    runtime: McpTraceRuntime;
+    context: McpTraceContext;
+    sink: TraceSink;
+}
+/** One JSON-RPC message read off the request side. */
+interface McpEnvelopeEntry {
+    method: string | null;
+    jsonRpcId: string | number | null;
+    /** Canonical, header-safe request id. `null` for notifications. */
+    requestId: string | null;
+    toolName: string | null;
+    toolArguments: unknown;
+    clientName: string | null;
+    clientVersion: string | null;
+    protocolVersion: string | null;
+}
+interface McpEnvelope {
+    batch: boolean;
+    entries: McpEnvelopeEntry[];
+    /** First entry's method — what run selection keys on. */
+    method: string | null;
+    requestId: string | null;
+    clientName: string | null;
+}
+/**
+ * Canonical MCP request id.
+ *
+ * JSON-RPC allows both `7` and `"7"` as distinct ids, and they must stay
+ * distinct: correlating a payment to the wrong tool call is worse than not
+ * correlating it. Numbers keep their JSON form under `n:`; strings are
+ * base64url-encoded under `s:` so an id containing newlines, colons or quotes
+ * survives being carried in an HTTP header without escaping games.
+ */
+declare function canonicalMcpRequestId(id: unknown): string | null;
+/**
+ * Read the JSON-RPC envelope from a request **clone**.
+ *
+ * The caller owns cloning; this consumes the body it is given. An unparsable,
+ * bodiless or over-cap request yields an empty envelope rather than an error — a
+ * malformed request is the transport's problem to answer, not tracing's problem
+ * to block.
+ */
+declare function inspectMcpEnvelope(request: Request, maxBytes?: number): Promise<McpEnvelope>;
+interface TraceMcpHttpRequestInput {
+    request: Request;
+    /**
+     * The real MCP handler. Receives the untouched original request, plus the
+     * resolved trace context when tracing is live.
+     */
+    handle: (request: Request, hooks?: McpTraceHooks) => Promise<Response>;
+    runtime?: McpTraceRuntime | null;
+    /** Cap on bytes read for observation, request and response. Never unbounded. */
+    maxObservedBytes?: number;
+    /**
+     * Deadline for envelope parsing plus run selection, the only trace work that
+     * happens before the handler. Past it the exchange proceeds untraced.
+     */
+    runSetupTimeoutMs?: number;
+}
+/**
+ * Wrap one MCP HTTP exchange in observation.
+ *
+ * The response returned here is the exact object `handle` produced. Nothing on
+ * the observation path can change it, delay it, or prevent it.
+ */
+declare function traceMcpHttpRequest(input: TraceMcpHttpRequestInput): Promise<Response>;
+
+/**
+ * Shared interfaces for the pay-operation module.
+ *
+ * This is the unified prepare/verify/sign/submit/resume pipeline. It extracts
+ * the offer-acquisition and authority-resolution logic shared by the SDK payer
+ * and the MCP prepare module into one place.
+ *
+ * Design constraints:
+ *  - Never signs, executes, or holds a key (pure read + PTB-build).
+ *  - Never touches the payment ledger (SDK payer's exactly-once concern).
+ *  - Returns the full Offer object so callers can build proofs/summaries.
+ *  - The signer is a callback interface (never holds private keys).
+ *  - Gas strategy is injectable (agent-provided or sponsor callback).
+ */
+
+interface PayOperationDeps {
+    fetchImpl?: typeof fetch;
+    /** Preferred dialect (default 'mpp'). */
+    preferredDialect?: Dialect;
+    /**
+     * Optional prefetched 402 Response. When present, resolvePayment reuses it
+     * instead of fetching again (mirrors resolveDirectX402). When omitted,
+     * resolvePayment fetches url with request.
+     */
+    prefetchedResponse?: Response;
+    /**
+     * Called with the offer immediately after reading the 402. Caller may
+     * verify HMAC, check SpendIntent, check expiry, check preparedTerms.
+     * Throw to abort with { status: 'failed', code: OFFER_VALIDATION_FAILED }.
+     */
+    validateOffer?: (offer: Offer, paymentId: string) => void | Promise<void>;
+    /**
+     * Build unsigned kind bytes. Caller controls whether initialSharedVersion
+     * comes from chain (SDK) or is hardcoded '1' (MCP prepare).
+     */
+    buildPayKind: (input: BuildPayKindInput) => Promise<BuildPayKindOutput>;
+    /**
+     * Resolve the per-recipient `RecipientRegistry` object id bound in the offer's
+     * exclusion directory. REQUIRED for a guarded delegate offer — including
+     * a single-rail delegate offer and one whose authenticated `acceptedRails`
+     * co-advertise the delegate rail with a gateway-executed rail. When present,
+     * the operation threads the guarded-settle inputs into `buildPayKind` so the
+     * built tx calls the GUARDED entrypoint and consumes the shared on-chain
+     * marker. Without this resolver a guarded offer fails closed rather than
+     * building an unguarded settle.
+     */
+    resolveExclusionRegistry?: (input: {
+        /** The exclusion directory object id from the offer's registryIdentity. */
+        directoryId: string;
+        /** The settlement package (from the offer / registryIdentity). */
+        packageId: string;
+        /** The recipient (offer.payTo) whose registry to resolve. */
+        recipient: string;
+    }) => Promise<{
+        recipientRegistryId: string;
+        /**
+         * Initial shared versions of the directory + registry (both shared objects).
+         * OPTIONAL here: a client-backed builder (`tx.object`) resolves versions at
+         * build time and does not need them, while the SDK's offline
+         * (`sharedObjectRef`) builder does. When present they are threaded through
+         * `buildPayKind` and exposed on the resolved payment so an offline caller can
+         * rebuild the same guarded PTB.
+         */
+        directoryInitialSharedVersion?: string;
+        registryInitialSharedVersion?: string;
+    }>;
+}
+interface BuildPayKindInput {
+    packageId: string;
+    delegate: string;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    onChainPolicyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+    recipient: string;
+    /** Delegation scope — selects the on-chain pay function (see `DelegationScope`). */
+    accessMode: DelegationScope;
+    /**
+     * Guarded settle inputs. Present for a guarded delegate offer; when set,
+     * the builder emits the GUARDED delegate entrypoint threading the exclusion
+     * directory + per-recipient registry + signed expiry. Required on the fresh
+     * lineage even for a single-rail delegate offer (there is no unguarded twin).
+     */
+    exclusionDirectoryId?: string;
+    recipientRegistryId?: string;
+    expiresAtMs?: string | number;
+    /**
+     * Initial shared versions of the directory + registry, for an offline builder
+     * that references them by `sharedObjectRef`. Absent for a client-backed builder
+     * that resolves shared versions at build time (`tx.object`).
+     */
+    exclusionDirectoryInitialSharedVersion?: string;
+    recipientRegistryInitialSharedVersion?: string;
+}
+interface BuildPayKindOutput {
+    /** Unsigned transaction kind bytes (base64). */
+    kindBytes: string;
+}
+
+/**
+ * Shared pay-request helpers.
+ *
+ * The V1 allowance sponsored payer (ADR-0010) is retired; only the
+ * rail-neutral request surface the SpendAccount payer depends on survives here:
+ * the `PayResult` shape every payer returns. `paidRequestInit` is the SDK helper
+ * that builds the one RequestInit replayed byte for byte on both calls.
+ */
+
+type PayResult = {
+    status: 'ok' | 'failed' | 'ambiguous';
+    /**
+     * `true` — settlement confirmed. `false` — money did not leave the
+     * account. `'unknown'` — execute/finality did not resolve; a retry can
+     * pay twice.
+     */
+    paid: boolean | 'unknown';
+    /** Whether money moved; always agrees with `paid`. */
+    paymentState?: PaymentState;
+    body?: unknown;
+    receipt?: unknown;
+    /** Registry code on a failed or ambiguous result. */
+    code?: string;
+    retryable?: boolean;
+    nextAction?: NextAction;
+    detail?: string;
+    txDigest?: string;
+    paymentId?: string;
+    challengeId?: string;
+    httpStatus?: number;
+    responseClass?: 'unpaid_ok' | 'rejected' | 'unavailable';
+};
+
+/**
+ * SpendAccount PREPARE-only client (non-custodial MCP).
+ *
+ * The remote MCP `pay` tool runs inside the gateway, which holds NO key that can
+ * spend. So this module does not sign or submit: it PREPARES a payment and hands
+ * back an unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction plus everything the client
+ * needs. The client — which holds the delegate key — sponsors, signs locally,
+ * and submits through the same personal-message challenge → local-sign → submit flow the
+ * REST/SDK delegate path uses. Only signatures ever reach the gateway; the
+ * private key is never placed in an HTTP body, a bearer, or any header.
+ *
+ * Flow: 402 Offer → request-binding → package/network SSOT →
+ * resolveGrantTarget(snapshot, offer.targetHash) (pause/revoke gate) → cap/coin
+ * checks → assertLive (fresh authority) → build unsigned kind bytes → return the
+ * signing request. There is deliberately no sponsor call, no decrypt, no
+ * signature, and no forwarded bearer here.
+ *
+ * See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
+ */
+
+type SharedObjectReader = (objectId: string) => Promise<{
+    owner?: unknown;
+} | null | undefined>;
+/**
+ * Read/prepare-only session for the non-custodial MCP pay tool. It carries the
+ * immutable grant snapshot and an optional prepare-time live gate — and no key,
+ * by construction. There is no `decryptDelegateSeed` and no `sponsorAuthorization`.
+ */
+interface SpendAccountPrepareSession {
+    snapshot: GrantSnapshot;
+    /** SpendAccount package id (V2). */
+    packageId: string;
+    /**
+     * Re-assert the grant is still live (not paused/revoked/expired) against fresh
+     * canonical state, invoked immediately before a signing request is handed back.
+     * Throw to abort. Optional; when absent, only the request-time snapshot gates
+     * the prepare (on-chain `spend_account::settle_policy` remains the final backstop for any
+     * spend the client later submits).
+     */
+    assertLive?: () => Promise<void>;
+}
+interface SpendAccountPayDeps {
+    fetchImpl?: typeof fetch;
+    /**
+     * Build only-transaction-kind bytes for the canonical guarded debit
+     * (`spend_account::settle_policy` / `settle_any_recipient`).
+     *
+     * The guarded-settle fields ({@link GuardedSettleFields}) are required on the
+     * fresh lineage: every delegate settle consumes the shared exclusion marker.
+     * Dropping them fails closed rather than building an unguarded call that no
+     * longer exists on chain.
+     */
+    buildPayKind?: (input: {
+        delegate: string;
+        coinType: string;
+        poolObjectId: string;
+        grantObjectId: string;
+        policyId: number | string;
+        targetHash: string;
+        amount: string;
+        paymentIdHash: Uint8Array;
+        termsHash: Uint8Array;
+        recipient?: string;
+        accessMode?: 'scoped' | 'open';
+    } & GuardedSettleFields) => Promise<{
+        kindBytes: string;
+    }>;
+    /**
+     * Resolve the per-recipient `RecipientRegistry` bound in the offer's exclusion
+     * directory (guarded offers only). Injected seam for tests; production
+     * leaves it unset and the prepare wires a live gRPC-backed resolver from the
+     * configured `ExclusionDirectory` id when present, else fails closed.
+     */
+    resolveExclusionRegistry?: PayOperationDeps['resolveExclusionRegistry'];
+    /**
+     * Read a shared object's owner so prepare binds the real initial version.
+     * Missing owner fails the prepare; version 1 is not a substitute.
+     */
+    readSharedObject?: SharedObjectReader;
+    /**
+     * Live trace for this prepare. Purely observational: emission records what the
+     * canonical read decisions already returned — an event is written after a check
+     * passes and can never be the thing that lets the next step run.
+     */
+    trace?: SpendAccountPayTrace;
+}
+interface SpendAccountPayTrace {
+    sink: TraceSink;
+    traceId: string;
+    requestId: string | null;
+    buyerAccountId: string;
+    connectionId: string;
+    /** HMAC secret for signed cross-request context. Absent disables signing. */
+    secret?: string | null;
+    /** Injected clock, for tests. */
+    now?: () => number;
+}
+/** The unsigned payment the client signs locally and submits. */
+interface SpendAccountSigningRequest {
+    /**
+     * Unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction-kind bytes (base64), sender set to
+     * `delegateAddress`. The client sponsors these for gas, signs with the delegate
+     * key, and submits — the gateway never receives the key.
+     */
+    unsignedKindBytes: string;
+    delegateAddress: string;
+    packageId: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    /** On-chain policy id the pay is bound to. */
+    policyId: number | string;
+    coinType: string;
+    targetHash: string;
+    amount: string;
+    /** Hex (no 0x) of the payment-id hash bound into the transaction. */
+    paymentIdHashHex: string;
+    /** Hex (no 0x) of the terms hash bound into the transaction. */
+    termsHashHex: string;
+    challengeId: string;
+    /** The exact paid request to replay after the client submits. */
+    resource: {
+        url: string;
+        method: string;
+    };
+    dialect: Dialect;
+    /** Recipient the agent requested (offer.payTo). */
+    recipient: string;
+    /** Where the client (holding the key) sponsors and submits. */
+    submit: {
+        sponsorUrl: string;
+        executeUrl: string;
+        moveCallTarget: string;
+    };
+    /**
+     * ISO-8601 timestamp when this prepared operation expires. After this time the
+     * unsigned bytes are no longer valid and the client must re-call pay() for a
+     * fresh prepare. Derived from the offer TTL.
+     */
+    expiresAt: string;
+    /** Restated hard rule for the agent host. */
+    note: string;
+}
+interface PreparedPayment {
+    status: 'prepared';
+    paid: false;
+    signingRequest: SpendAccountSigningRequest;
+}
+/** Prepared signing request, or a canonical failure (never a spend). */
+type SpendAccountPrepareResult = PreparedPayment | PayResult;
+/** Default kind builder (no chain client — pure PTB). */
+declare function buildSpendAccountPayKind(input: {
+    packageId: string;
+    delegate: string;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    policyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+    poolInitialSharedVersion?: string;
+    grantInitialSharedVersion?: string;
+    clockInitialSharedVersion?: string;
+} & GuardedSettleFields): Promise<{
+    kindBytes: string;
+}>;
+/**
+ * Refuse blind signing: a client validating a sponsored transaction must be able
+ * to prove the sponsored bytes reconstruct the intended spend_account::settle_policy. Kept
+ * here (and exported) so both the client signer and its tests share one check.
+ */
+declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
+    kindBytes: string;
+    packageId: string;
+    delegate: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    amount: string;
+}): void;
+/**
+ * Prepare a delegate payment WITHOUT signing. Reads the 402 offer, binds it,
+ * gates on the immutable grant snapshot + a fresh authority check, builds the
+ * unsigned transaction, and returns a signing request. The client holding the
+ * delegate key signs locally and submits. This function never decrypts, signs,
+ * sponsors, or submits.
+ *
+ * Uses `resolvePayment` from the SDK pay-operation module for the
+ * shared offer-acquisition + authority-resolution pipeline (steps 1–5 + assertLive
+ * + hash derivation + buildPayKind). This module wraps that with MCP-specific
+ * concerns: trace events, dialect-mode ceiling check, and signing-request
+ * construction.
+ */
+declare function prepareSpendAccountPayment(args: {
+    url: string;
+    /** The one normalized paid request, replayed byte for byte after signing. */
+    request?: PaidHttpRequest;
+    session: SpendAccountPrepareSession;
+    cfg: McpConfig;
+    deps?: SpendAccountPayDeps;
+    /** Preferred dialect when the 402 advertises both (default mpp). */
+    preferredDialect?: Dialect;
+}): Promise<SpendAccountPrepareResult>;
+
+/**
+ * Transport-neutral SuiPay MCP server + tool registry.
+ * Used by stdio (index.ts) and Streamable HTTP (http.ts).
+ * Remote HTTP passes McpAuthContext so tools enforce OAuth scope + shared-pool pay.
+ */
+
+declare const PACKAGE_NAME = "@cmdoss/suipay-mcp";
+declare const TOOLS: readonly [{
+    readonly name: "access_context";
+    readonly description: "Inspect profiles, policies, service targets, spend caps, usage, and lifecycle state enforced for this authenticated SuiPay session. Call before choosing a paid service.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "pay";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: "Full gateway resource URL.";
+            };
+            readonly method: {
+                readonly type: "string";
+                readonly enum: readonly ["GET", "POST"];
+                readonly description: "HTTP method of the paid request. Defaults to GET.";
+            };
+            readonly json: {
+                readonly type: "object";
+                readonly description: "JSON request body for a POST. Sent as application/json and bound to the payment.";
+            };
+            readonly file: {
+                readonly type: "string";
+                readonly description: "Absolute path under SUIPAY_MCP_FILE_ROOT (unset disables attach). Stdio POST only; requires fileField. Regular non-empty file whose decoded size fits the paid-body ceiling. Not a URL, FIFO, device, or path under ~/.suipay. Bytes fill json[fileField] as canonical base64.";
+            };
+            readonly fileField: {
+                readonly type: "string";
+                readonly description: "JSON key to set from file (e.g. contentBase64). Required with file. Pattern [A-Za-z][A-Za-z0-9_]{0,63}. Must not already be present on json.";
+            };
+            readonly recipient: {
+                readonly type: "string";
+                readonly description: "Sui address you expect to be paid. The payment is refused, unsigned, if the prepared transaction pays anyone else.";
+            };
+            readonly maxAmount: {
+                readonly type: "string";
+                readonly description: "Atomic ceiling you will spend on this call. The payment is refused, unsigned, if the offer costs more.";
+            };
+        };
+        readonly required: readonly ["url"];
+    };
+}, {
+    readonly name: "discover";
+    readonly description: "Search SuiPay gateway resources. After login, each row includes name, path, url, catalog price, and whether the current session can cover one call at that price (descriptive only — pay still enforces the grant).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Optional service search terms.";
+            };
+        };
+    };
+}, {
+    readonly name: "receipts";
+    readonly description: "List SuiPay settlement receipts, optionally filtered by challenge id.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly challengeId: {
+                readonly type: "string";
+                readonly description: "Optional payment challenge id.";
+            };
+        };
+    };
+}, {
+    readonly name: "suipay_login";
+    readonly description: "Mint or reuse the local delegate key (version-2, mode 0600) and return a clickable console URL immediately so the owner can bind a spend-account grant. Does not wait for the wallet. Default target is Railway suipay-dev; pass target=\"local\" (or start the binary with --local) for the laptop stack. Stdio only; hosted /mcp never holds a spendable key.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly label: {
+                readonly type: "string";
+                readonly description: "Label shown in SuiPay console.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["dev", "local"];
+                readonly description: "Where to bind the grant. Default is Railway suipay-dev. Pass \"local\" for localhost:3000 / 127.0.0.1:4340.";
+            };
+            readonly gatewayResourceUrl: {
+                readonly type: "string";
+                readonly description: "Gateway resource URL whose 402 defines recipient, asset, and package.";
+            };
+        };
+    };
+}, {
+    readonly name: "suipay_logout";
+    readonly description: "Remove the local delegate-key credentials file. Missing file is success. Force clears a corrupt file without printing the seed.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly force: {
+                readonly type: "boolean";
+                readonly description: "Remove local credentials even if the file is unreadable.";
+            };
+        };
+    };
+}];
+/**
+ * Create a Server with the public SuiPay tool surface registered.
+ *
+ * `trace` is the proxy-resolved run for this HTTP exchange. It is threaded into
+ * tool dependencies so payment code can emit *domain* events, and nothing else:
+ * this wrapper deliberately emits no tool lifecycle of its own, because the
+ * proxy observes the actual JSON-RPC wire and a second source would double-count
+ * every call and disagree on ids.
+ */
+interface McpServerOptions {
+    /**
+     * How `pay` finds an agent-held delegate key for the authenticated grant.
+     * Defaults to the persisted local key (`resolveAgentHeldSettlement`), which
+     * returns null on any process that does not hold the key the grant names — so
+     * the default is prepare-only everywhere except the agent's own machine.
+     * Injectable for tests; there is no way to make it hand over a key the grant
+     * does not already authorize.
+     */
+    resolveAgentHeld?: AgentHeldResolver;
+    /** Override the exclusion-registry resolver (tests / offline). */
+    resolveExclusionRegistry?: SpendAccountPayDeps['resolveExclusionRegistry'];
+    /**
+     * Wire that created this server. Hosted HTTP never forwards `file` into `pay`.
+     * Stdio is the default so existing tests stay local.
+     */
+    transport?: 'stdio' | 'http';
+}
+declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks, options?: McpServerOptions): Server;
+
+/**
+ * Streamable HTTP transport for SuiPay MCP.
+ * Stateless per-request (sessionIdGenerator undefined) — same public tools as stdio.
+ * Auth context is required for remote gateway /mcp (bearer resolved upstream).
+ *
+ * The optional trace runtime turns on live observation. It is a pure wrapper:
+ * `traceMcpHttpRequest` reads clones and returns the transport's own Response,
+ * so passing a runtime cannot change what an MCP client sees.
+ */
+
+/**
+ * Handle one MCP Streamable HTTP request (initialize, tools/list, tools/call, …).
+ * Creates a fresh transport+server pair per request (stateless mode).
+ */
+declare function handleSuipayMcpHttpRequest(req: Request, cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceRuntime | null, options?: McpServerOptions): Promise<Response>;
+
+export { type AgentHeldResolver as A, buildSpendAccountPayKind as B, type CodeFor as C, type DelegatedKeySigner as D, canonicalMcpRequestId as E, createServer as F, type GetObjectJson as G, handleSuipayMcpHttpRequest as H, inspectMcpEnvelope as I, loadMcpConfig as J, parseMcpTargetFlag as K, prepareSpendAccountPayment as L, type McpConfig as M, type NextAction as N, type Offer as O, type PaidHttpRequest as P, resetAgentHeldProcessLedger as Q, resolveAgentHeldSettlement as R, type SpendAccountSigningRequest as S, TOOLS as T, resolveGrantTarget as U, resolveMcpTarget as V, sameMcpGateway as W, type X402PayProgress as X, traceMcpHttpRequest as Y, verifySpendAccountPayReconstructs as Z, type DelegatedPayerSession as a, type DelegatedPayerConfig as b, type DelegatedPayerDeps as c, type SpendIntent as d, type DelegatedPayResult as e, type DelegationScope as f, type GrantPolicyBinding as g, type PaymentAttemptLedger as h, type DelegatedPayerLog as i, type PreparedSettlementTerms as j, type McpAuthContext as k, type McpTraceHooks as l, type SpendAccountPayDeps as m, createReader as n, type AgentHeldSettlement as o, MCP_TARGET_PRESETS as p, type McpEnvelope as q, type McpEnvelopeEntry as r, type McpServerOptions as s, type McpTarget as t, type McpTraceContext as u, type McpTraceRuntime as v, PACKAGE_NAME as w, type PreparedPayment as x, type SpendAccountPrepareResult as y, type SpendAccountPrepareSession as z };