@lunora/x402 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -1,5 +1,7 @@
 # @lunora/x402
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 > Agentic payments over the [x402](https://x402.org) protocol for [Lunora](https://lunora.sh).
 
 x402 turns HTTP `402 Payment Required` into a machine-payable rail: no accounts,

package/dist/charge/index.d.mts

@@ -1,5 +1,5 @@
-import { F as FacilitatorConfig, c as X402ChargeConfig, f as X402Price } from "../packem_shared/config.d-CddwCiBm.mjs";
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, type a as EvmAddress, type P as PaymentEventRow, type d as X402Network, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/config.d-CddwCiBm.mjs";
+import { F as FacilitatorConfig, c as X402ChargeConfig, f as X402Price } from "../packem_shared/config.d-5Nqi5iox.mjs";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, type a as EvmAddress, type P as PaymentEventRow, type d as X402Network, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/config.d-5Nqi5iox.mjs";
 import { HTTPFacilitatorClient } from '@x402/core/server';
 import { RouteConfig } from '@x402/core/http';
 import '@x402/evm';
@@ -14,21 +14,44 @@ import '@x402/core/types';
 * `supported`), so the same header map is handed to each. With no config the
 * client points at the public {@link resolveFacilitatorUrl default} and sends no
 * auth headers.
+* @experimental
 */
 declare const createFacilitatorClient: (config?: FacilitatorConfig) => HTTPFacilitatorClient;
-/** A handler shaped like a Lunora HTTP action: `(context, request) => Response`. */
+/**
+* A handler shaped like a Lunora HTTP action: `(context, request) => Response`.
+* @experimental
+*/
 type HttpActionHandler<Context> = (context: Context, request: Request) => Promise<Response> | Response;
 /**
 * Gate `handler` behind an x402 paywall described by `config`. Returns a handler
 * of the same shape, ready to pass to `httpAction`.
+* @experimental
 */
 declare const withX402: <Context>(config: X402ChargeConfig, handler: HttpActionHandler<Context>) => HttpActionHandler<Context>;
-/** Runs the protected resource handler, producing the Response to gate. */
+/**
+* Runs the protected resource handler, producing the Response to gate.
+* @experimental
+*/
 type ChargeHandler = () => Promise<Response> | Response;
-/** A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request. */
+/**
+* Per-request platform seams `handle` can use, beyond the request/handler pair.
+* @experimental
+*/
+interface ChargeHandlerDeps {
+  /**
+  * Keep background work (the receipt sink) alive past the response — the
+  * request's `ctx.waitUntil`. Absent on paths with no platform execution
+  * context reaching the middleware (e.g. today's HTTP-action rail).
+  */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request.
+* @experimental
+*/
 interface ChargeMiddleware {
   /** Gate `request`: challenge / verify / settle around `runHandler`. */
-  handle: (request: Request, runHandler: ChargeHandler) => Promise<Response>;
+  handle: (request: Request, runHandler: ChargeHandler, deps?: ChargeHandlerDeps) => Promise<Response>;
 }
 /**
 * Route metadata a caller can layer onto the generated catch-all route. The
@@ -36,22 +59,54 @@ interface ChargeMiddleware {
 * names the paid function (x402 core falls back to the request URL otherwise —
 * every RPC POSTs to the same `/_lunora/rpc`, so the URL can't tell two paid
 * procedures apart).
+* @experimental
 */
 type ChargeRouteOverrides = Pick<RouteConfig, "description" | "resource">;
 /**
+* Behaviour knobs for {@link createChargeMiddleware} beyond route metadata.
+* @experimental
+*/
+interface ChargeMiddlewareOptions {
+  /**
+  * Settle the verified payment **before** dispatching `runHandler`, instead
+  * of after. Use this for a mutation/procedure gate: a settlement failure
+  * then means the handler never runs at all, so a paid mutation's writes can
+  * never be committed without payment (the free-execution gap X402-04
+  * closes). Once settlement succeeds the payment is final (on-chain) — a
+  * handler failure after that point is a normal application error, not a
+  * payment to unwind: there is nothing left to cancel, so it is not caught
+  * here and simply propagates.
+  *
+  * Default `false` (settle-after, the historical behaviour): the handler's
+  * response is passed to settlement as transport context (`responseHeaders`
+  * — read by some schemes for settlement overrides), and a handler throw
+  * still releases the verified-but-unsettled payment via
+  * `cancellationDispatcher.cancel`. Because settlement can still fail after
+  * the handler already ran on this path, `.x402()` handlers gated this way
+  * MUST be idempotent or compensatable — see the `@lunora/x402` charge docs.
+  */
+  readonly settleBeforeHandler?: boolean;
+}
+/**
 * Build and initialise a {@link ChargeMiddleware} for `config`. Fetches
 * facilitator support once (via `initialize()`), so call this once per config
 * and reuse the result across requests. `routeOverrides` layers extra route
-* metadata (e.g. `resource`) onto the generated catch-all route.
+* metadata (e.g. `resource`) onto the generated catch-all route; `options`
+* controls settlement ordering (see {@link ChargeMiddlewareOptions}).
+* @experimental
 */
-declare const createChargeMiddleware: (config: X402ChargeConfig, routeOverrides?: ChargeRouteOverrides) => Promise<ChargeMiddleware>;
+declare const createChargeMiddleware: (config: X402ChargeConfig, routeOverrides?: ChargeRouteOverrides, options?: ChargeMiddlewareOptions) => Promise<ChargeMiddleware>;
 /**
 * Charge config for the procedure gate: the worker-level settlement vocabulary
 * (network, recipient, facilitator) minus `price` — price is per-procedure and
 * arrives with each {@link X402ProcedureSpec}.
+* @experimental
 */
 type X402ProcedureChargeConfig = Omit<X402ChargeConfig, "price">;
-/** The per-RPC charge spec the runtime passes the gate for each paid dispatch. */
+/**
+* The per-RPC charge spec the runtime passes the gate for each paid dispatch.
+* @experimental
+*/
 interface X402ProcedureSpec {
   /** The `file:function` id of the paid procedure; becomes the x402 challenge `resource`. */
   readonly functionPath: string;
@@ -62,15 +117,23 @@ interface X402ProcedureSpec {
 * Gate one paid RPC. Returns a real `402` + `PAYMENT-REQUIRED` challenge when the
 * request is unpaid, or the dispatched response (with `X-PAYMENT-RESPONSE`
 * attached) once the client's `X-PAYMENT` is verified and settled. `dispatch`
-* runs the actual shard forward — it is only invoked after payment is verified.
+* runs the actual shard forward — settlement happens **before** `dispatch` is
+* invoked (settle-first), so a settlement failure means the shard forward
+* (the mutation's commit) never runs at all — no committed-but-unpaid write is
+* possible. `deps.waitUntil`, when supplied (the request's `ctx.waitUntil`),
+* keeps the opt-in receipt sink alive past the response.
+* @experimental
 */
-type X402ProcedureChargeGate = (request: Request, spec: X402ProcedureSpec, dispatch: () => Promise<Response>) => Promise<Response>;
+type X402ProcedureChargeGate = (request: Request, spec: X402ProcedureSpec, dispatch: () => Promise<Response>, deps?: ChargeHandlerDeps) => Promise<Response>;
 /**
 * Build the injectable procedure charge gate for `config`. One initialised
 * {@link ChargeMiddleware} is memoised per `functionPath` (each bakes that
 * function's price + `resource`), since `createChargeMiddleware` fetches
 * facilitator support on first use. A failed init is not cached, so a transient
-* facilitator outage retries on the next request.
+* facilitator outage retries on the next request. Settlement runs before
+* `dispatch` (`settleBeforeHandler: true`) since `dispatch` commits the
+* procedure's real mutation — see `createChargeMiddleware`'s `ChargeMiddlewareOptions`.
+* @experimental
 */
 declare const createProcedureChargeGate: (config: X402ProcedureChargeConfig) => X402ProcedureChargeGate;
-export { type ChargeHandler, type ChargeMiddleware, type ChargeRouteOverrides, type FacilitatorConfig, type HttpActionHandler, type X402ChargeConfig, type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };
+export { type ChargeHandler, type ChargeHandlerDeps, type ChargeMiddleware, type ChargeMiddlewareOptions, type ChargeRouteOverrides, type FacilitatorConfig, type HttpActionHandler, type X402ChargeConfig, type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };

package/dist/charge/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FacilitatorConfig, c as X402ChargeConfig, f as X402Price } from "../packem_shared/config.d-CddwCiBm.js";
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, type a as EvmAddress, type P as PaymentEventRow, type d as X402Network, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/config.d-CddwCiBm.js";
+import { F as FacilitatorConfig, c as X402ChargeConfig, f as X402Price } from "../packem_shared/config.d-5Nqi5iox.js";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, type a as EvmAddress, type P as PaymentEventRow, type d as X402Network, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/config.d-5Nqi5iox.js";
 import { HTTPFacilitatorClient } from '@x402/core/server';
 import { RouteConfig } from '@x402/core/http';
 import '@x402/evm';
@@ -14,21 +14,44 @@ import '@x402/core/types';
 * `supported`), so the same header map is handed to each. With no config the
 * client points at the public {@link resolveFacilitatorUrl default} and sends no
 * auth headers.
+* @experimental
 */
 declare const createFacilitatorClient: (config?: FacilitatorConfig) => HTTPFacilitatorClient;
-/** A handler shaped like a Lunora HTTP action: `(context, request) => Response`. */
+/**
+* A handler shaped like a Lunora HTTP action: `(context, request) => Response`.
+* @experimental
+*/
 type HttpActionHandler<Context> = (context: Context, request: Request) => Promise<Response> | Response;
 /**
 * Gate `handler` behind an x402 paywall described by `config`. Returns a handler
 * of the same shape, ready to pass to `httpAction`.
+* @experimental
 */
 declare const withX402: <Context>(config: X402ChargeConfig, handler: HttpActionHandler<Context>) => HttpActionHandler<Context>;
-/** Runs the protected resource handler, producing the Response to gate. */
+/**
+* Runs the protected resource handler, producing the Response to gate.
+* @experimental
+*/
 type ChargeHandler = () => Promise<Response> | Response;
-/** A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request. */
+/**
+* Per-request platform seams `handle` can use, beyond the request/handler pair.
+* @experimental
+*/
+interface ChargeHandlerDeps {
+  /**
+  * Keep background work (the receipt sink) alive past the response — the
+  * request's `ctx.waitUntil`. Absent on paths with no platform execution
+  * context reaching the middleware (e.g. today's HTTP-action rail).
+  */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request.
+* @experimental
+*/
 interface ChargeMiddleware {
   /** Gate `request`: challenge / verify / settle around `runHandler`. */
-  handle: (request: Request, runHandler: ChargeHandler) => Promise<Response>;
+  handle: (request: Request, runHandler: ChargeHandler, deps?: ChargeHandlerDeps) => Promise<Response>;
 }
 /**
 * Route metadata a caller can layer onto the generated catch-all route. The
@@ -36,22 +59,54 @@ interface ChargeMiddleware {
 * names the paid function (x402 core falls back to the request URL otherwise —
 * every RPC POSTs to the same `/_lunora/rpc`, so the URL can't tell two paid
 * procedures apart).
+* @experimental
 */
 type ChargeRouteOverrides = Pick<RouteConfig, "description" | "resource">;
 /**
+* Behaviour knobs for {@link createChargeMiddleware} beyond route metadata.
+* @experimental
+*/
+interface ChargeMiddlewareOptions {
+  /**
+  * Settle the verified payment **before** dispatching `runHandler`, instead
+  * of after. Use this for a mutation/procedure gate: a settlement failure
+  * then means the handler never runs at all, so a paid mutation's writes can
+  * never be committed without payment (the free-execution gap X402-04
+  * closes). Once settlement succeeds the payment is final (on-chain) — a
+  * handler failure after that point is a normal application error, not a
+  * payment to unwind: there is nothing left to cancel, so it is not caught
+  * here and simply propagates.
+  *
+  * Default `false` (settle-after, the historical behaviour): the handler's
+  * response is passed to settlement as transport context (`responseHeaders`
+  * — read by some schemes for settlement overrides), and a handler throw
+  * still releases the verified-but-unsettled payment via
+  * `cancellationDispatcher.cancel`. Because settlement can still fail after
+  * the handler already ran on this path, `.x402()` handlers gated this way
+  * MUST be idempotent or compensatable — see the `@lunora/x402` charge docs.
+  */
+  readonly settleBeforeHandler?: boolean;
+}
+/**
 * Build and initialise a {@link ChargeMiddleware} for `config`. Fetches
 * facilitator support once (via `initialize()`), so call this once per config
 * and reuse the result across requests. `routeOverrides` layers extra route
-* metadata (e.g. `resource`) onto the generated catch-all route.
+* metadata (e.g. `resource`) onto the generated catch-all route; `options`
+* controls settlement ordering (see {@link ChargeMiddlewareOptions}).
+* @experimental
 */
-declare const createChargeMiddleware: (config: X402ChargeConfig, routeOverrides?: ChargeRouteOverrides) => Promise<ChargeMiddleware>;
+declare const createChargeMiddleware: (config: X402ChargeConfig, routeOverrides?: ChargeRouteOverrides, options?: ChargeMiddlewareOptions) => Promise<ChargeMiddleware>;
 /**
 * Charge config for the procedure gate: the worker-level settlement vocabulary
 * (network, recipient, facilitator) minus `price` — price is per-procedure and
 * arrives with each {@link X402ProcedureSpec}.
+* @experimental
 */
 type X402ProcedureChargeConfig = Omit<X402ChargeConfig, "price">;
-/** The per-RPC charge spec the runtime passes the gate for each paid dispatch. */
+/**
+* The per-RPC charge spec the runtime passes the gate for each paid dispatch.
+* @experimental
+*/
 interface X402ProcedureSpec {
   /** The `file:function` id of the paid procedure; becomes the x402 challenge `resource`. */
   readonly functionPath: string;
@@ -62,15 +117,23 @@ interface X402ProcedureSpec {
 * Gate one paid RPC. Returns a real `402` + `PAYMENT-REQUIRED` challenge when the
 * request is unpaid, or the dispatched response (with `X-PAYMENT-RESPONSE`
 * attached) once the client's `X-PAYMENT` is verified and settled. `dispatch`
-* runs the actual shard forward — it is only invoked after payment is verified.
+* runs the actual shard forward — settlement happens **before** `dispatch` is
+* invoked (settle-first), so a settlement failure means the shard forward
+* (the mutation's commit) never runs at all — no committed-but-unpaid write is
+* possible. `deps.waitUntil`, when supplied (the request's `ctx.waitUntil`),
+* keeps the opt-in receipt sink alive past the response.
+* @experimental
 */
-type X402ProcedureChargeGate = (request: Request, spec: X402ProcedureSpec, dispatch: () => Promise<Response>) => Promise<Response>;
+type X402ProcedureChargeGate = (request: Request, spec: X402ProcedureSpec, dispatch: () => Promise<Response>, deps?: ChargeHandlerDeps) => Promise<Response>;
 /**
 * Build the injectable procedure charge gate for `config`. One initialised
 * {@link ChargeMiddleware} is memoised per `functionPath` (each bakes that
 * function's price + `resource`), since `createChargeMiddleware` fetches
 * facilitator support on first use. A failed init is not cached, so a transient
-* facilitator outage retries on the next request.
+* facilitator outage retries on the next request. Settlement runs before
+* `dispatch` (`settleBeforeHandler: true`) since `dispatch` commits the
+* procedure's real mutation — see `createChargeMiddleware`'s `ChargeMiddlewareOptions`.
+* @experimental
 */
 declare const createProcedureChargeGate: (config: X402ProcedureChargeConfig) => X402ProcedureChargeGate;
-export { type ChargeHandler, type ChargeMiddleware, type ChargeRouteOverrides, type FacilitatorConfig, type HttpActionHandler, type X402ChargeConfig, type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };
+export { type ChargeHandler, type ChargeHandlerDeps, type ChargeMiddleware, type ChargeMiddlewareOptions, type ChargeRouteOverrides, type FacilitatorConfig, type HttpActionHandler, type X402ChargeConfig, type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };

package/dist/charge/index.mjs

@@ -1,7 +1,7 @@
 export { DEFAULT_FACILITATOR_URL, resolveFacilitatorUrl } from '../packem_shared/DEFAULT_FACILITATOR_URL-Cbz6kIqa.mjs';
 export { createFacilitatorClient } from '../packem_shared/createFacilitatorClient-rXHBnCZm.mjs';
 export { isEvmNetwork, isSvmNetwork, toCaip2 } from '../packem_shared/EVM_NETWORKS-BhnYWUQ4.mjs';
-export { withX402 } from '../packem_shared/withX402-rUq0voT8.mjs';
-export { createChargeMiddleware } from '../packem_shared/createChargeMiddleware-BJkYJeFf.mjs';
-export { createProcedureChargeGate } from '../packem_shared/createProcedureChargeGate-CV8ITlQP.mjs';
+export { withX402 } from '../packem_shared/withX402-DILL2DvD.mjs';
+export { createChargeMiddleware } from '../packem_shared/createChargeMiddleware-D3yhOpFs.mjs';
+export { createProcedureChargeGate } from '../packem_shared/createProcedureChargeGate-eh9yv36U.mjs';
 export { toPaymentEventRow, toReceipt } from '../packem_shared/toPaymentEventRow-DW4O9N7Y.mjs';

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, E as EVM_NETWORKS, type a as EvmAddress, type F as FacilitatorConfig, type b as FriendlyNetwork, N as NETWORK_TO_CAIP2, S as SVM_NETWORKS, type X as X402CdpSignerConfig, type c as X402ChargeConfig, type d as X402Network, type e as X402PayConfig, type f as X402Price, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, type j as X402SignerConfig, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2 } from "./packem_shared/config.d-CddwCiBm.mjs";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, E as EVM_NETWORKS, type a as EvmAddress, type F as FacilitatorConfig, type b as FriendlyNetwork, N as NETWORK_TO_CAIP2, S as SVM_NETWORKS, type X as X402CdpSignerConfig, type c as X402ChargeConfig, type d as X402Network, type e as X402PayConfig, type f as X402Price, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, type j as X402SignerConfig, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2 } from "./packem_shared/config.d-5Nqi5iox.mjs";
 import '@x402/evm';
 import '@x402/svm';
 import '@x402/core/http';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, E as EVM_NETWORKS, type a as EvmAddress, type F as FacilitatorConfig, type b as FriendlyNetwork, N as NETWORK_TO_CAIP2, S as SVM_NETWORKS, type X as X402CdpSignerConfig, type c as X402ChargeConfig, type d as X402Network, type e as X402PayConfig, type f as X402Price, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, type j as X402SignerConfig, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2 } from "./packem_shared/config.d-CddwCiBm.js";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, E as EVM_NETWORKS, type a as EvmAddress, type F as FacilitatorConfig, type b as FriendlyNetwork, N as NETWORK_TO_CAIP2, S as SVM_NETWORKS, type X as X402CdpSignerConfig, type c as X402ChargeConfig, type d as X402Network, type e as X402PayConfig, type f as X402Price, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, type j as X402SignerConfig, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2 } from "./packem_shared/config.d-5Nqi5iox.js";
 import '@x402/evm';
 import '@x402/svm';
 import '@x402/core/http';

package/dist/packem_shared/{DEFAULT_STABLECOIN_DECIMALS-CSu5b5lD.mjs → DEFAULT_STABLECOIN_DECIMALS-CpW619nu.mjs}

@@ -10,6 +10,9 @@ const createSpendState = () => {
     add: (amount) => {
       spent += amount;
     },
+    release: (amount) => {
+      spent = spent > amount ? spent - amount : 0n;
+    },
     get spentAtomic() {
       return spent;
     }
@@ -59,27 +62,29 @@ const buildPaymentGuard = (policy, state) => {
         reason: `x402 policy: this payment (${requirement.amount}) would exceed the per-run cap (already spent ${state.spentAtomic.toString()}, cap ${maxPerRun.toString()}, in atomic base units).`
       };
     }
+    state.add(amount);
     if (policy.onPaymentRequired !== void 0) {
       const approved = await policy.onPaymentRequired(requirement);
       if (!approved) {
+        state.release(amount);
         return { abort: true, reason: "x402 policy: payment was declined by onPaymentRequired." };
       }
     }
     return void 0;
   };
 };
-const recordSpend = (state) => (context) => {
-  state.add(BigInt(context.selectedRequirements.amount));
+const releaseSpendOnFailure = (state) => (context) => {
+  state.release(BigInt(context.selectedRequirements.amount));
   return Promise.resolve();
 };
 const assertBoundedPolicy = (policy) => {
-  const bounded = policy.maxPerCall !== void 0 || policy.maxPerRun !== void 0 || (policy.allowedRecipients?.length ?? 0) > 0 || (policy.allowedNetworks?.length ?? 0) > 0 || policy.onPaymentRequired !== void 0;
+  const bounded = policy.maxPerCall !== void 0 || policy.maxPerRun !== void 0 || policy.onPaymentRequired !== void 0;
   if (!bounded) {
     throw new LunoraError(
       "FORBIDDEN",
-      "x402 pay: refusing to build a wallet with an unbounded spend policy. Set at least one of maxPerCall, maxPerRun, allowedRecipients, allowedNetworks, or onPaymentRequired."
+      "x402 pay: refusing to build a wallet with an unbounded spend policy. Set at least one of maxPerCall, maxPerRun, or onPaymentRequired (allowedNetworks/allowedRecipients narrow but do not bound spend)."
     );
   }
 };
 
-export { DEFAULT_STABLECOIN_DECIMALS, assertBoundedPolicy, buildPaymentGuard, buildSpendPolicy, createSpendState, recordSpend, usdToAtomic };
+export { DEFAULT_STABLECOIN_DECIMALS, assertBoundedPolicy, buildPaymentGuard, buildSpendPolicy, createSpendState, releaseSpendOnFailure, usdToAtomic };

package/dist/packem_shared/{config.d-CddwCiBm.d.mts → config.d-5Nqi5iox.d.mts}

@@ -1,13 +1,14 @@
 import { ClientEvmSigner } from '@x402/evm';
 import { ClientSvmSigner } from '@x402/svm';
 import { ProcessSettleSuccessResponse } from '@x402/core/http';
-import { BeforePaymentCreationHook, PaymentPolicy, AfterPaymentCreationHook } from '@x402/core/client';
+import { BeforePaymentCreationHook, PaymentPolicy, OnPaymentCreationFailureHook } from '@x402/core/client';
 import { PaymentRequirements } from '@x402/core/types';
 /**
 * A normalised record of one settled x402 payment. The settled `amount` is kept
 * as its exact on-chain atomic-unit string (USDC has 6 decimals) — never coerced
 * to a fractional-dollar number — so no precision is lost crossing the reporting
 * seam.
+* @experimental
 */
 interface X402Receipt {
   /** Settled amount in the asset's atomic base units (USDC: 6 decimals), as an exact string. */
@@ -33,6 +34,7 @@ interface X402Receipt {
 * settlement, does not block the paid response on it, and swallows any error it
 * throws — so a sink must never rely on being awaited or on its failures
 * surfacing.
+* @experimental
 */
 type X402ReceiptSink = (receipt: X402Receipt) => Promise<void> | void;
 /**
@@ -41,6 +43,7 @@ type X402ReceiptSink = (receipt: X402Receipt) => Promise<void> | void;
 * the settlement result carries neither. Prefers the actual settled `amount`
 * (present for `upto`-scheme partial settlements) and falls back to the route's
 * required amount for `exact`.
+* @experimental
 */
 declare const toReceipt: (settlement: ProcessSettleSuccessResponse, context: {
   readonly resource: string;
@@ -50,6 +53,7 @@ declare const toReceipt: (settlement: ProcessSettleSuccessResponse, context: {
 * A row for `@lunora/payment`'s durable `events` table. Deliberately a plain
 * structural type — building one imports nothing from `@lunora/payment`, so the
 * rails stay decoupled.
+* @experimental
 */
 interface PaymentEventRow {
   /** Epoch milliseconds the settlement was recorded. */
@@ -77,6 +81,7 @@ interface PaymentEventRow {
 * table (`packages/payment/src/schema.ts`). Amount / from / to / resource are
 * intentionally not on this row — that card renders none of them; read them off
 * the {@link X402Receipt} (e.g. into your own revenue table) if you need them.
+* @experimental
 */
 declare const toPaymentEventRow: (receipt: X402Receipt) => PaymentEventRow;
 /**
@@ -96,19 +101,27 @@ declare const toPaymentEventRow: (receipt: X402Receipt) => PaymentEventRow;
 * friendly aliases; a caller who needs them can still pass a raw CAIP-2 id with an
 * explicit asset.
 */
-/** A CAIP-2 chain identifier, e.g. `"eip155:8453"` (Base) or `"solana:5eyk…"`. */
+/**
+* A CAIP-2 chain identifier, e.g. `"eip155:8453"` (Base) or `"solana:5eyk…"`.
+* @experimental
+*/
 type Caip2 = `${string}:${string}`;
-/** Friendly network names Lunora maps to CAIP-2 for `@x402/core`. */
+/**
+* Friendly network names Lunora maps to CAIP-2 for `@x402/core`.
+* @experimental
+*/
 type FriendlyNetwork = "arbitrum" | "arbitrum-sepolia" | "base" | "base-sepolia" | "ethereum" | "polygon" | "solana" | "solana-devnet";
 /**
 * A network Lunora can settle on: a {@link FriendlyNetwork} alias (mapped to
 * CAIP-2 internally) or a raw {@link Caip2} id for chains without a friendly name.
+* @experimental
 */
 type X402Network = Caip2 | FriendlyNetwork;
 /**
 * Friendly name → CAIP-2 id. Values verified against `@x402/evm` and `@x402/svm`
 * `DEFAULT_STABLECOINS` at 2.17.0. `base` / `base-sepolia` are the primary
 * prod / test pair.
+* @experimental
 */
 declare const NETWORK_TO_CAIP2: {
   readonly arbitrum: "eip155:42161";
@@ -120,23 +133,37 @@ declare const NETWORK_TO_CAIP2: {
   readonly solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
   readonly "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
 };
-/** EVM friendly networks (signed via `@x402/evm` + viem). */
+/**
+* EVM friendly networks (signed via `@x402/evm` + viem).
+* @experimental
+*/
 declare const EVM_NETWORKS: readonly ["arbitrum", "arbitrum-sepolia", "base", "base-sepolia", "ethereum", "polygon"];
-/** Solana friendly networks (signed via `@x402/svm`). */
+/**
+* Solana friendly networks (signed via `@x402/svm`).
+* @experimental
+*/
 declare const SVM_NETWORKS: readonly ["solana", "solana-devnet"];
 /**
 * Resolve a network to its CAIP-2 id. Friendly aliases are looked up; a value
 * that already looks like CAIP-2 (`namespace:reference`) passes through.
+* @experimental
 */
 declare const toCaip2: (network: X402Network) => Caip2;
-/** True when `network` settles on an EVM chain (viem signer path). */
+/**
+* True when `network` settles on an EVM chain (viem signer path).
+* @experimental
+*/
 declare const isEvmNetwork: (network: X402Network) => boolean;
-/** True when `network` settles on Solana (`@x402/svm` signer path). */
+/**
+* True when `network` settles on Solana (`@x402/svm` signer path).
+* @experimental
+*/
 declare const isSvmNetwork: (network: X402Network) => boolean;
 /**
 * USDC — and every asset in `@x402/evm` / `@x402/svm`'s `DEFAULT_STABLECOINS` —
 * uses 6 decimals, so a USD price converts to atomic base units at `10 ** 6`.
 * Override per {@link SpendPolicy.decimals} only for a custom, non-6-decimal asset.
+* @experimental
 */
 declare const DEFAULT_STABLECOIN_DECIMALS = 6;
 /**
@@ -145,6 +172,7 @@ declare const DEFAULT_STABLECOIN_DECIMALS = 6;
 *
 * Caps are denominated in USD (the stablecoin's dollar value); addresses and
 * networks are matched against the requirement the server offers.
+* @experimental
 */
 interface SpendPolicy {
   /** Network allowlist. When set, only these networks may be paid on. */
@@ -164,51 +192,88 @@ interface SpendPolicy {
   */
   readonly onPaymentRequired?: (requirement: PaymentRequirements) => Promise<boolean> | boolean;
 }
-/** A running spend ledger the per-run cap is measured against; the guard reads it, the recorder adds to it. */
+/**
+* A running spend ledger the per-run cap is measured (and reserved) against.
+* @experimental
+*/
 interface SpendState {
-  /** Add a just-committed payment (atomic base units) to the total. */
+  /** Reserve a payment (atomic base units) against the running total, before it is signed. */
   readonly add: (amount: bigint) => void;
+  /** Release a previously reserved amount (atomic base units) — e.g. a declined or failed payment. Clamps at 0. */
+  readonly release: (amount: bigint) => void;
   /** Cumulative spend so far, in atomic base units. */
   readonly spentAtomic: bigint;
 }
-/** A fresh spend ledger. One per wallet instance; the guard + recorder share it. */
+/**
+* A fresh spend ledger. One per wallet instance; the guard reserves into it and
+* releases from it.
+* @experimental
+*/
 declare const createSpendState: () => SpendState;
 /**
 * Convert a USD amount (`0.01`, `"0.01"`, or the `"$0.01"` shorthand) to atomic
 * stablecoin base units, exactly — parsed digit-by-digit so no binary-float drift
 * can round a cap the wrong way. Throws on a malformed amount (including
 * exponential notation like `"1e-7"`, which a decimal string never needs).
+* @experimental
 */
 declare const usdToAtomic: (usd: X402Price, decimals?: number) => bigint;
 /**
 * A `PaymentPolicy` that narrows the server's offered requirements to those a
 * bounded wallet may pay: within the per-call cap, to an allowed recipient, on an
 * allowed network. An empty result means the client cannot pay — fail-closed.
+* @experimental
 */
 declare const buildSpendPolicy: (policy: SpendPolicy) => PaymentPolicy;
 /**
 * A `BeforePaymentCreationHook` enforcing the stateful bounds the stateless
 * {@link buildSpendPolicy} filter can't: the cumulative per-run cap and the async
 * confirmation gate. Aborts (no signature) when either would be violated.
+*
+* The per-run cap is *reserved* into `state` as soon as the check passes — before
+* the `await policy.onPaymentRequired` below, and before `@x402/core` ever attempts
+* to sign — not recorded afterwards. This closes a check-then-act race: without an
+* atomic reserve, N concurrent payments could each read the same `spentAtomic`,
+* all pass the cap check, and all record, overspending the cap by up to
+* (N−1)×maxPerCall. A declined confirmation releases the reservation before this
+* hook returns; {@link releaseSpendOnFailure} releases it if the signature itself
+* later fails. The reservation is intentionally *not* released on success — a
+* committed payment stays counted.
+* @experimental
 */
 declare const buildPaymentGuard: (policy: SpendPolicy, state: SpendState) => BeforePaymentCreationHook;
 /**
-* An `AfterPaymentCreationHook` that adds the just-created payment to `state`, so
-* the next {@link buildPaymentGuard} call measures the per-run cap against it.
+* An `OnPaymentCreationFailureHook` that releases a reservation
+* {@link buildPaymentGuard} made when the scheme's signature creation itself
+* throws (network error, wallet error, …) after the guard already approved and
+* reserved the amount. Without this, a failed signature would permanently
+* over-count against the per-run cap for the rest of the run — fail-closed, but
+* needlessly so when the client (`wrapFetchWithPayment`) may retry.
+* @experimental
 */
-declare const recordSpend: (state: SpendState) => AfterPaymentCreationHook;
+declare const releaseSpendOnFailure: (state: SpendState) => OnPaymentCreationFailureHook;
 /**
 * Guard at wallet-build time: refuse a policy with no bound whatsoever. Signing
 * money on an agent's behalf with unlimited spend authority is never the intent,
 * so this fails loudly rather than defaulting to unbounded.
+*
+* `allowedNetworks` / `allowedRecipients` narrow *where* a payment can go, but
+* neither caps *how much* — a policy with only an allowlist still authorises
+* unlimited spend to any recipient it permits. Only `maxPerCall`, `maxPerRun`, or
+* a dynamic `onPaymentRequired` gate actually bound spend, so only those count here.
+* @experimental
 */
 declare const assertBoundedPolicy: (policy: SpendPolicy) => void;
 /**
 * The public, Coinbase-operated facilitator (verify + settle). It needs no API
 * key. Override with a self-hosted or CDP facilitator via {@link FacilitatorConfig}.
+* @experimental
 */
 declare const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
-/** How to reach a facilitator's `/verify` + `/settle` endpoints. */
+/**
+* How to reach a facilitator's `/verify` + `/settle` endpoints.
+* @experimental
+*/
 interface FacilitatorConfig {
   /** Extra headers for a private facilitator (e.g. a CDP bearer token). */
   readonly headers?: Record<string, string>;
@@ -221,11 +286,18 @@ interface FacilitatorConfig {
 * to the network's stablecoin base units (USDC has 6 decimals) at challenge
 * time. (Kept `number | string` rather than a `` `$${string}` `` template
 * member — the template is subsumed by `string`, so it only adds noise.)
+* @experimental
 */
 type X402Price = number | string;
-/** An EVM recipient address (the merchant wallet that receives settlement). */
+/**
+* An EVM recipient address (the merchant wallet that receives settlement).
+* @experimental
+*/
 type EvmAddress = `0x${string}`;
-/** Recipient wallet the facilitator settles payments to, per network family. */
+/**
+* Recipient wallet the facilitator settles payments to, per network family.
+* @experimental
+*/
 interface X402Recipient {
   /** EVM payout address (required for EVM networks). */
   readonly evm?: EvmAddress;
@@ -235,6 +307,7 @@ interface X402Recipient {
 /**
 * Server-side (charge rail) config. The server needs only a **recipient
 * address** — no private key — because the facilitator performs settlement.
+* @experimental
 */
 interface X402ChargeConfig {
   readonly facilitator?: FacilitatorConfig;
@@ -256,6 +329,7 @@ interface X402ChargeConfig {
 * Client-side (pay rail) config. The signer holds spending authority, so the
 * pay rail is ActionCtx-only and MUST be paired with a spend `policy` — the pay
 * rail refuses to build if the policy is unbounded.
+* @experimental
 */
 interface X402PayConfig {
   /** Network to transact on. Determines the signer family (EVM vs SVM). */
@@ -275,6 +349,7 @@ interface X402PayConfig {
 * custody is `@coinbase/cdp-sdk`.) EVM only today; for CDP on Solana, build a
 * `@solana/kit` signer around your CDP account and pass it via the `"signer"`
 * escape hatch.
+* @experimental
 */
 interface X402CdpSignerConfig {
   /** CDP account name to get-or-create and sign with. */
@@ -306,6 +381,7 @@ interface X402CdpSignerConfig {
 * Wired today: raw-key (EVM + SVM), the user-supplied signer (both families),
 * and CDP-managed EVM custody. CDP on Solana is not yet wired — use the escape
 * hatch.
+* @experimental
 */
 type X402SignerConfig = X402CdpSignerConfig | {
   /** Name of the `ctx.secrets` entry holding the private key. */
@@ -320,6 +396,9 @@ type X402SignerConfig = X402CdpSignerConfig | {
   readonly signer: ClientEvmSigner | ClientSvmSigner;
   readonly type: "signer";
 };
-/** Resolve a facilitator's base URL, applying the public default. */
+/**
+* Resolve a facilitator's base URL, applying the public default.
+* @experimental
+*/
 declare const resolveFacilitatorUrl: (facilitator?: FacilitatorConfig) => string;
-export { Caip2 as C, DEFAULT_FACILITATOR_URL as D, EVM_NETWORKS as E, FacilitatorConfig as F, NETWORK_TO_CAIP2 as N, PaymentEventRow as P, SVM_NETWORKS as S, X402CdpSignerConfig as X, EvmAddress as a, FriendlyNetwork as b, X402ChargeConfig as c, X402Network as d, X402PayConfig as e, X402Price as f, X402Receipt as g, X402ReceiptSink as h, X402Recipient as i, X402SignerConfig as j, isEvmNetwork as k, isSvmNetwork as l, DEFAULT_STABLECOIN_DECIMALS as m, SpendPolicy as n, SpendState as o, assertBoundedPolicy as p, buildPaymentGuard as q, resolveFacilitatorUrl as r, buildSpendPolicy as s, toCaip2 as t, createSpendState as u, recordSpend as v, usdToAtomic as w, toPaymentEventRow as x, toReceipt as y };
+export { Caip2 as C, DEFAULT_FACILITATOR_URL as D, EVM_NETWORKS as E, FacilitatorConfig as F, NETWORK_TO_CAIP2 as N, PaymentEventRow as P, SVM_NETWORKS as S, X402CdpSignerConfig as X, EvmAddress as a, FriendlyNetwork as b, X402ChargeConfig as c, X402Network as d, X402PayConfig as e, X402Price as f, X402Receipt as g, X402ReceiptSink as h, X402Recipient as i, X402SignerConfig as j, isEvmNetwork as k, isSvmNetwork as l, DEFAULT_STABLECOIN_DECIMALS as m, SpendPolicy as n, SpendState as o, assertBoundedPolicy as p, buildPaymentGuard as q, resolveFacilitatorUrl as r, buildSpendPolicy as s, toCaip2 as t, createSpendState as u, releaseSpendOnFailure as v, usdToAtomic as w, toPaymentEventRow as x, toReceipt as y };

package/dist/packem_shared/{config.d-CddwCiBm.d.ts → config.d-5Nqi5iox.d.ts}

@@ -1,13 +1,14 @@
 import { ClientEvmSigner } from '@x402/evm';
 import { ClientSvmSigner } from '@x402/svm';
 import { ProcessSettleSuccessResponse } from '@x402/core/http';
-import { BeforePaymentCreationHook, PaymentPolicy, AfterPaymentCreationHook } from '@x402/core/client';
+import { BeforePaymentCreationHook, PaymentPolicy, OnPaymentCreationFailureHook } from '@x402/core/client';
 import { PaymentRequirements } from '@x402/core/types';
 /**
 * A normalised record of one settled x402 payment. The settled `amount` is kept
 * as its exact on-chain atomic-unit string (USDC has 6 decimals) — never coerced
 * to a fractional-dollar number — so no precision is lost crossing the reporting
 * seam.
+* @experimental
 */
 interface X402Receipt {
   /** Settled amount in the asset's atomic base units (USDC: 6 decimals), as an exact string. */
@@ -33,6 +34,7 @@ interface X402Receipt {
 * settlement, does not block the paid response on it, and swallows any error it
 * throws — so a sink must never rely on being awaited or on its failures
 * surfacing.
+* @experimental
 */
 type X402ReceiptSink = (receipt: X402Receipt) => Promise<void> | void;
 /**
@@ -41,6 +43,7 @@ type X402ReceiptSink = (receipt: X402Receipt) => Promise<void> | void;
 * the settlement result carries neither. Prefers the actual settled `amount`
 * (present for `upto`-scheme partial settlements) and falls back to the route's
 * required amount for `exact`.
+* @experimental
 */
 declare const toReceipt: (settlement: ProcessSettleSuccessResponse, context: {
   readonly resource: string;
@@ -50,6 +53,7 @@ declare const toReceipt: (settlement: ProcessSettleSuccessResponse, context: {
 * A row for `@lunora/payment`'s durable `events` table. Deliberately a plain
 * structural type — building one imports nothing from `@lunora/payment`, so the
 * rails stay decoupled.
+* @experimental
 */
 interface PaymentEventRow {
   /** Epoch milliseconds the settlement was recorded. */
@@ -77,6 +81,7 @@ interface PaymentEventRow {
 * table (`packages/payment/src/schema.ts`). Amount / from / to / resource are
 * intentionally not on this row — that card renders none of them; read them off
 * the {@link X402Receipt} (e.g. into your own revenue table) if you need them.
+* @experimental
 */
 declare const toPaymentEventRow: (receipt: X402Receipt) => PaymentEventRow;
 /**
@@ -96,19 +101,27 @@ declare const toPaymentEventRow: (receipt: X402Receipt) => PaymentEventRow;
 * friendly aliases; a caller who needs them can still pass a raw CAIP-2 id with an
 * explicit asset.
 */
-/** A CAIP-2 chain identifier, e.g. `"eip155:8453"` (Base) or `"solana:5eyk…"`. */
+/**
+* A CAIP-2 chain identifier, e.g. `"eip155:8453"` (Base) or `"solana:5eyk…"`.
+* @experimental
+*/
 type Caip2 = `${string}:${string}`;
-/** Friendly network names Lunora maps to CAIP-2 for `@x402/core`. */
+/**
+* Friendly network names Lunora maps to CAIP-2 for `@x402/core`.
+* @experimental
+*/
 type FriendlyNetwork = "arbitrum" | "arbitrum-sepolia" | "base" | "base-sepolia" | "ethereum" | "polygon" | "solana" | "solana-devnet";
 /**
 * A network Lunora can settle on: a {@link FriendlyNetwork} alias (mapped to
 * CAIP-2 internally) or a raw {@link Caip2} id for chains without a friendly name.
+* @experimental
 */
 type X402Network = Caip2 | FriendlyNetwork;
 /**
 * Friendly name → CAIP-2 id. Values verified against `@x402/evm` and `@x402/svm`
 * `DEFAULT_STABLECOINS` at 2.17.0. `base` / `base-sepolia` are the primary
 * prod / test pair.
+* @experimental
 */
 declare const NETWORK_TO_CAIP2: {
   readonly arbitrum: "eip155:42161";
@@ -120,23 +133,37 @@ declare const NETWORK_TO_CAIP2: {
   readonly solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
   readonly "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
 };
-/** EVM friendly networks (signed via `@x402/evm` + viem). */
+/**
+* EVM friendly networks (signed via `@x402/evm` + viem).
+* @experimental
+*/
 declare const EVM_NETWORKS: readonly ["arbitrum", "arbitrum-sepolia", "base", "base-sepolia", "ethereum", "polygon"];
-/** Solana friendly networks (signed via `@x402/svm`). */
+/**
+* Solana friendly networks (signed via `@x402/svm`).
+* @experimental
+*/
 declare const SVM_NETWORKS: readonly ["solana", "solana-devnet"];
 /**
 * Resolve a network to its CAIP-2 id. Friendly aliases are looked up; a value
 * that already looks like CAIP-2 (`namespace:reference`) passes through.
+* @experimental
 */
 declare const toCaip2: (network: X402Network) => Caip2;
-/** True when `network` settles on an EVM chain (viem signer path). */
+/**
+* True when `network` settles on an EVM chain (viem signer path).
+* @experimental
+*/
 declare const isEvmNetwork: (network: X402Network) => boolean;
-/** True when `network` settles on Solana (`@x402/svm` signer path). */
+/**
+* True when `network` settles on Solana (`@x402/svm` signer path).
+* @experimental
+*/
 declare const isSvmNetwork: (network: X402Network) => boolean;
 /**
 * USDC — and every asset in `@x402/evm` / `@x402/svm`'s `DEFAULT_STABLECOINS` —
 * uses 6 decimals, so a USD price converts to atomic base units at `10 ** 6`.
 * Override per {@link SpendPolicy.decimals} only for a custom, non-6-decimal asset.
+* @experimental
 */
 declare const DEFAULT_STABLECOIN_DECIMALS = 6;
 /**
@@ -145,6 +172,7 @@ declare const DEFAULT_STABLECOIN_DECIMALS = 6;
 *
 * Caps are denominated in USD (the stablecoin's dollar value); addresses and
 * networks are matched against the requirement the server offers.
+* @experimental
 */
 interface SpendPolicy {
   /** Network allowlist. When set, only these networks may be paid on. */
@@ -164,51 +192,88 @@ interface SpendPolicy {
   */
   readonly onPaymentRequired?: (requirement: PaymentRequirements) => Promise<boolean> | boolean;
 }
-/** A running spend ledger the per-run cap is measured against; the guard reads it, the recorder adds to it. */
+/**
+* A running spend ledger the per-run cap is measured (and reserved) against.
+* @experimental
+*/
 interface SpendState {
-  /** Add a just-committed payment (atomic base units) to the total. */
+  /** Reserve a payment (atomic base units) against the running total, before it is signed. */
   readonly add: (amount: bigint) => void;
+  /** Release a previously reserved amount (atomic base units) — e.g. a declined or failed payment. Clamps at 0. */
+  readonly release: (amount: bigint) => void;
   /** Cumulative spend so far, in atomic base units. */
   readonly spentAtomic: bigint;
 }
-/** A fresh spend ledger. One per wallet instance; the guard + recorder share it. */
+/**
+* A fresh spend ledger. One per wallet instance; the guard reserves into it and
+* releases from it.
+* @experimental
+*/
 declare const createSpendState: () => SpendState;
 /**
 * Convert a USD amount (`0.01`, `"0.01"`, or the `"$0.01"` shorthand) to atomic
 * stablecoin base units, exactly — parsed digit-by-digit so no binary-float drift
 * can round a cap the wrong way. Throws on a malformed amount (including
 * exponential notation like `"1e-7"`, which a decimal string never needs).
+* @experimental
 */
 declare const usdToAtomic: (usd: X402Price, decimals?: number) => bigint;
 /**
 * A `PaymentPolicy` that narrows the server's offered requirements to those a
 * bounded wallet may pay: within the per-call cap, to an allowed recipient, on an
 * allowed network. An empty result means the client cannot pay — fail-closed.
+* @experimental
 */
 declare const buildSpendPolicy: (policy: SpendPolicy) => PaymentPolicy;
 /**
 * A `BeforePaymentCreationHook` enforcing the stateful bounds the stateless
 * {@link buildSpendPolicy} filter can't: the cumulative per-run cap and the async
 * confirmation gate. Aborts (no signature) when either would be violated.
+*
+* The per-run cap is *reserved* into `state` as soon as the check passes — before
+* the `await policy.onPaymentRequired` below, and before `@x402/core` ever attempts
+* to sign — not recorded afterwards. This closes a check-then-act race: without an
+* atomic reserve, N concurrent payments could each read the same `spentAtomic`,
+* all pass the cap check, and all record, overspending the cap by up to
+* (N−1)×maxPerCall. A declined confirmation releases the reservation before this
+* hook returns; {@link releaseSpendOnFailure} releases it if the signature itself
+* later fails. The reservation is intentionally *not* released on success — a
+* committed payment stays counted.
+* @experimental
 */
 declare const buildPaymentGuard: (policy: SpendPolicy, state: SpendState) => BeforePaymentCreationHook;
 /**
-* An `AfterPaymentCreationHook` that adds the just-created payment to `state`, so
-* the next {@link buildPaymentGuard} call measures the per-run cap against it.
+* An `OnPaymentCreationFailureHook` that releases a reservation
+* {@link buildPaymentGuard} made when the scheme's signature creation itself
+* throws (network error, wallet error, …) after the guard already approved and
+* reserved the amount. Without this, a failed signature would permanently
+* over-count against the per-run cap for the rest of the run — fail-closed, but
+* needlessly so when the client (`wrapFetchWithPayment`) may retry.
+* @experimental
 */
-declare const recordSpend: (state: SpendState) => AfterPaymentCreationHook;
+declare const releaseSpendOnFailure: (state: SpendState) => OnPaymentCreationFailureHook;
 /**
 * Guard at wallet-build time: refuse a policy with no bound whatsoever. Signing
 * money on an agent's behalf with unlimited spend authority is never the intent,
 * so this fails loudly rather than defaulting to unbounded.
+*
+* `allowedNetworks` / `allowedRecipients` narrow *where* a payment can go, but
+* neither caps *how much* — a policy with only an allowlist still authorises
+* unlimited spend to any recipient it permits. Only `maxPerCall`, `maxPerRun`, or
+* a dynamic `onPaymentRequired` gate actually bound spend, so only those count here.
+* @experimental
 */
 declare const assertBoundedPolicy: (policy: SpendPolicy) => void;
 /**
 * The public, Coinbase-operated facilitator (verify + settle). It needs no API
 * key. Override with a self-hosted or CDP facilitator via {@link FacilitatorConfig}.
+* @experimental
 */
 declare const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
-/** How to reach a facilitator's `/verify` + `/settle` endpoints. */
+/**
+* How to reach a facilitator's `/verify` + `/settle` endpoints.
+* @experimental
+*/
 interface FacilitatorConfig {
   /** Extra headers for a private facilitator (e.g. a CDP bearer token). */
   readonly headers?: Record<string, string>;
@@ -221,11 +286,18 @@ interface FacilitatorConfig {
 * to the network's stablecoin base units (USDC has 6 decimals) at challenge
 * time. (Kept `number | string` rather than a `` `$${string}` `` template
 * member — the template is subsumed by `string`, so it only adds noise.)
+* @experimental
 */
 type X402Price = number | string;
-/** An EVM recipient address (the merchant wallet that receives settlement). */
+/**
+* An EVM recipient address (the merchant wallet that receives settlement).
+* @experimental
+*/
 type EvmAddress = `0x${string}`;
-/** Recipient wallet the facilitator settles payments to, per network family. */
+/**
+* Recipient wallet the facilitator settles payments to, per network family.
+* @experimental
+*/
 interface X402Recipient {
   /** EVM payout address (required for EVM networks). */
   readonly evm?: EvmAddress;
@@ -235,6 +307,7 @@ interface X402Recipient {
 /**
 * Server-side (charge rail) config. The server needs only a **recipient
 * address** — no private key — because the facilitator performs settlement.
+* @experimental
 */
 interface X402ChargeConfig {
   readonly facilitator?: FacilitatorConfig;
@@ -256,6 +329,7 @@ interface X402ChargeConfig {
 * Client-side (pay rail) config. The signer holds spending authority, so the
 * pay rail is ActionCtx-only and MUST be paired with a spend `policy` — the pay
 * rail refuses to build if the policy is unbounded.
+* @experimental
 */
 interface X402PayConfig {
   /** Network to transact on. Determines the signer family (EVM vs SVM). */
@@ -275,6 +349,7 @@ interface X402PayConfig {
 * custody is `@coinbase/cdp-sdk`.) EVM only today; for CDP on Solana, build a
 * `@solana/kit` signer around your CDP account and pass it via the `"signer"`
 * escape hatch.
+* @experimental
 */
 interface X402CdpSignerConfig {
   /** CDP account name to get-or-create and sign with. */
@@ -306,6 +381,7 @@ interface X402CdpSignerConfig {
 * Wired today: raw-key (EVM + SVM), the user-supplied signer (both families),
 * and CDP-managed EVM custody. CDP on Solana is not yet wired — use the escape
 * hatch.
+* @experimental
 */
 type X402SignerConfig = X402CdpSignerConfig | {
   /** Name of the `ctx.secrets` entry holding the private key. */
@@ -320,6 +396,9 @@ type X402SignerConfig = X402CdpSignerConfig | {
   readonly signer: ClientEvmSigner | ClientSvmSigner;
   readonly type: "signer";
 };
-/** Resolve a facilitator's base URL, applying the public default. */
+/**
+* Resolve a facilitator's base URL, applying the public default.
+* @experimental
+*/
 declare const resolveFacilitatorUrl: (facilitator?: FacilitatorConfig) => string;
-export { Caip2 as C, DEFAULT_FACILITATOR_URL as D, EVM_NETWORKS as E, FacilitatorConfig as F, NETWORK_TO_CAIP2 as N, PaymentEventRow as P, SVM_NETWORKS as S, X402CdpSignerConfig as X, EvmAddress as a, FriendlyNetwork as b, X402ChargeConfig as c, X402Network as d, X402PayConfig as e, X402Price as f, X402Receipt as g, X402ReceiptSink as h, X402Recipient as i, X402SignerConfig as j, isEvmNetwork as k, isSvmNetwork as l, DEFAULT_STABLECOIN_DECIMALS as m, SpendPolicy as n, SpendState as o, assertBoundedPolicy as p, buildPaymentGuard as q, resolveFacilitatorUrl as r, buildSpendPolicy as s, toCaip2 as t, createSpendState as u, recordSpend as v, usdToAtomic as w, toPaymentEventRow as x, toReceipt as y };
+export { Caip2 as C, DEFAULT_FACILITATOR_URL as D, EVM_NETWORKS as E, FacilitatorConfig as F, NETWORK_TO_CAIP2 as N, PaymentEventRow as P, SVM_NETWORKS as S, X402CdpSignerConfig as X, EvmAddress as a, FriendlyNetwork as b, X402ChargeConfig as c, X402Network as d, X402PayConfig as e, X402Price as f, X402Receipt as g, X402ReceiptSink as h, X402Recipient as i, X402SignerConfig as j, isEvmNetwork as k, isSvmNetwork as l, DEFAULT_STABLECOIN_DECIMALS as m, SpendPolicy as n, SpendState as o, assertBoundedPolicy as p, buildPaymentGuard as q, resolveFacilitatorUrl as r, buildSpendPolicy as s, toCaip2 as t, createSpendState as u, releaseSpendOnFailure as v, usdToAtomic as w, toPaymentEventRow as x, toReceipt as y };

package/dist/packem_shared/{createChargeMiddleware-BJkYJeFf.mjs → createChargeMiddleware-D3yhOpFs.mjs}

@@ -19,19 +19,20 @@ const buildResourceServer = async (config) => {
 
 const PAYMENT_HEADER = "X-PAYMENT";
 const headerRecord = (headers) => {
-  const record = {};
+  const record = /* @__PURE__ */ Object.create(null);
   for (const [key, value] of headers) {
     record[key] = value;
   }
   return record;
 };
-const reportReceipt = (sink, settlement, resource) => {
+const reportReceipt = (sink, settlement, resource, waitUntil) => {
   if (sink === void 0) {
     return;
   }
   try {
-    Promise.resolve(sink(toReceipt(settlement, { resource, ts: Date.now() }))).catch(() => {
+    const sent = Promise.resolve(sink(toReceipt(settlement, { resource, ts: Date.now() }))).catch(() => {
     });
+    waitUntil?.(sent);
   } catch {
   }
 };
@@ -66,7 +67,7 @@ const createRequestAdapter = (request, url) => {
       return values.length === 1 ? values[0] : values;
     },
     getQueryParams: () => {
-      const params = {};
+      const params = /* @__PURE__ */ Object.create(null);
       for (const key of new Set(url.searchParams.keys())) {
         const values = url.searchParams.getAll(key);
         const [first, ...rest] = values;
@@ -102,11 +103,12 @@ const withHeaders = (response, extra) => {
   }
   return new Response(response.body, { headers, status: response.status, statusText: response.statusText });
 };
-const createChargeMiddleware = async (config, routeOverrides) => {
+const createChargeMiddleware = async (config, routeOverrides, options) => {
   const server = await buildResourceServer(config);
   const http = new x402HTTPResourceServer(server, { ...buildRoute(config), ...routeOverrides });
   await http.initialize();
-  const handle = async (request, runHandler) => {
+  const settleBeforeHandler = options?.settleBeforeHandler ?? false;
+  const handle = async (request, runHandler, deps) => {
     const url = new URL(request.url);
     const context = {
       adapter: createRequestAdapter(request, url),
@@ -121,6 +123,18 @@ const createChargeMiddleware = async (config, routeOverrides) => {
     if (result.type === "payment-error") {
       return toResponse(result.response);
     }
+    const resource = routeOverrides?.resource ?? request.url;
+    if (settleBeforeHandler) {
+      const settlement2 = await http.processSettlement(result.paymentPayload, result.paymentRequirements, result.declaredExtensions, {
+        request: context
+      });
+      if (!settlement2.success) {
+        return toResponse(settlement2.response);
+      }
+      reportReceipt(config.onReceipt, settlement2, resource, deps?.waitUntil);
+      const response2 = await runHandler();
+      return withHeaders(response2, settlement2.headers);
+    }
     let response;
     try {
       response = await runHandler();
@@ -137,7 +151,7 @@ const createChargeMiddleware = async (config, routeOverrides) => {
       responseHeaders: headerRecord(response.headers)
     });
     if (settlement.success) {
-      reportReceipt(config.onReceipt, settlement, routeOverrides?.resource ?? request.url);
+      reportReceipt(config.onReceipt, settlement, resource, deps?.waitUntil);
       return withHeaders(response, settlement.headers);
     }
     return toResponse(settlement.response);

package/dist/packem_shared/{createPayFetch-O2vkvM1v.mjs → createPayFetch-BeT05njL.mjs}

@@ -1,6 +1,6 @@
 import { x402Client } from '@x402/core/client';
 import { wrapFetchWithPayment } from '@x402/fetch';
-import { assertBoundedPolicy, buildSpendPolicy, buildPaymentGuard, recordSpend, createSpendState } from './DEFAULT_STABLECOIN_DECIMALS-CSu5b5lD.mjs';
+import { assertBoundedPolicy, buildSpendPolicy, buildPaymentGuard, releaseSpendOnFailure, createSpendState } from './DEFAULT_STABLECOIN_DECIMALS-CpW619nu.mjs';
 import { registerWallet } from './registerWallet-I4pVwq65.mjs';
 
 const createPayFetch = async (config, deps) => {
@@ -10,7 +10,7 @@ const createPayFetch = async (config, deps) => {
   const state = createSpendState();
   client.registerPolicy(buildSpendPolicy(config.policy));
   client.onBeforePaymentCreation(buildPaymentGuard(config.policy, state));
-  client.onAfterPaymentCreation(recordSpend(state));
+  client.onPaymentCreationFailure(releaseSpendOnFailure(state));
   return wrapFetchWithPayment(deps.fetch ?? globalThis.fetch, client);
 };
 

package/dist/packem_shared/{createProcedureChargeGate-CV8ITlQP.mjs → createProcedureChargeGate-eh9yv36U.mjs}

@@ -1,18 +1,20 @@
-import { createChargeMiddleware } from './createChargeMiddleware-BJkYJeFf.mjs';
+import { createChargeMiddleware } from './createChargeMiddleware-D3yhOpFs.mjs';
 
 const createProcedureChargeGate = (config) => {
   const middlewareByFunction = /* @__PURE__ */ new Map();
-  return async (request, spec, dispatch) => {
+  return async (request, spec, dispatch, deps) => {
     let pending = middlewareByFunction.get(spec.functionPath);
     if (pending === void 0) {
-      pending = createChargeMiddleware({ ...config, price: spec.price }, { resource: spec.functionPath }).catch((error) => {
-        middlewareByFunction.delete(spec.functionPath);
-        throw error;
-      });
+      pending = createChargeMiddleware({ ...config, price: spec.price }, { resource: spec.functionPath }, { settleBeforeHandler: true }).catch(
+        (error) => {
+          middlewareByFunction.delete(spec.functionPath);
+          throw error;
+        }
+      );
       middlewareByFunction.set(spec.functionPath, pending);
     }
     const middleware = await pending;
-    return middleware.handle(request, dispatch);
+    return middleware.handle(request, dispatch, deps);
   };
 };
 

package/dist/packem_shared/{withX402-rUq0voT8.mjs → withX402-DILL2DvD.mjs}

@@ -1,4 +1,4 @@
-import { createChargeMiddleware } from './createChargeMiddleware-BJkYJeFf.mjs';
+import { createChargeMiddleware } from './createChargeMiddleware-D3yhOpFs.mjs';
 
 const withX402 = (config, handler) => {
   let pending;

package/dist/pay/index.d.mts

@@ -1,5 +1,5 @@
-import { e as X402PayConfig } from "../packem_shared/config.d-CddwCiBm.mjs";
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, m as DEFAULT_STABLECOIN_DECIMALS, type n as SpendPolicy, type o as SpendState, type X as X402CdpSignerConfig, type d as X402Network, type f as X402Price, type j as X402SignerConfig, p as assertBoundedPolicy, q as buildPaymentGuard, s as buildSpendPolicy, u as createSpendState, k as isEvmNetwork, l as isSvmNetwork, v as recordSpend, r as resolveFacilitatorUrl, t as toCaip2, w as usdToAtomic } from "../packem_shared/config.d-CddwCiBm.mjs";
+import { e as X402PayConfig } from "../packem_shared/config.d-5Nqi5iox.mjs";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, m as DEFAULT_STABLECOIN_DECIMALS, type n as SpendPolicy, type o as SpendState, type X as X402CdpSignerConfig, type d as X402Network, type f as X402Price, type j as X402SignerConfig, p as assertBoundedPolicy, q as buildPaymentGuard, s as buildSpendPolicy, u as createSpendState, k as isEvmNetwork, l as isSvmNetwork, v as releaseSpendOnFailure, r as resolveFacilitatorUrl, t as toCaip2, w as usdToAtomic } from "../packem_shared/config.d-5Nqi5iox.mjs";
 import { x402Client } from '@x402/core/client';
 import { ClientSvmSigner } from '@x402/svm';
 import { PrivateKeyAccount } from 'viem/accounts';
@@ -8,7 +8,10 @@ import '@x402/core/http';
 import '@x402/core/types';
 /** Reads a secret by name; resolves `undefined` when unset. */
 type GetSecret = (name: string) => Promise<string | undefined> | string | undefined;
-/** How the wallet reads its key material — wired to `ctx.secrets.get` in an action. */
+/**
+* How the wallet reads its key material — wired to `ctx.secrets.get` in an action.
+* @experimental
+*/
 interface WalletDeps {
   /** Read a secret (e.g. a private key) by name; `undefined` when unset. */
   readonly getSecret: GetSecret;
@@ -17,6 +20,7 @@ interface WalletDeps {
 * Resolve a viem `LocalAccount` from a raw private key. The key may be given with
 * or without the `0x` prefix. The account is a structural `ClientEvmSigner`
 * (`address` + `signTypedData`), so `@x402/evm` accepts it directly.
+* @experimental
 */
 declare const resolveEvmAccount: (privateKey: string) => Promise<PrivateKeyAccount>;
 /**
@@ -25,6 +29,7 @@ declare const resolveEvmAccount: (privateKey: string) => Promise<PrivateKeyAccou
 * format) or as a base58 string. A 64-byte value is a full secret key (seed ‖
 * public key); a 32-byte value is the seed alone. The returned signer is a
 * structural `ClientSvmSigner` (`TransactionSigner`), so `@x402/svm` accepts it.
+* @experimental
 */
 declare const resolveSvmSigner: (secret: string) => Promise<ClientSvmSigner>;
 /**
@@ -34,11 +39,18 @@ declare const resolveSvmSigner: (secret: string) => Promise<ClientSvmSigner>;
 * read), `"raw-key"` (a `ctx.secrets` private key → viem account on EVM or a
 * `@solana/kit` keypair on SVM), or `"cdp"` (a Coinbase-managed wallet via
 * `@coinbase/cdp-sdk`).
+* @experimental
 */
 declare const registerWallet: (client: x402Client, config: X402PayConfig, deps: WalletDeps) => Promise<void>;
-/** A payment-enabled `fetch`: same signature as the platform `fetch`. */
+/**
+* A payment-enabled `fetch`: same signature as the platform `fetch`.
+* @experimental
+*/
 type PayFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
-/** Dependencies for building a pay-rail fetch: secret access, plus an optional base `fetch` to wrap. */
+/**
+* Dependencies for building a pay-rail fetch: secret access, plus an optional base `fetch` to wrap.
+* @experimental
+*/
 interface X402PayDeps extends WalletDeps {
   /** The `fetch` to wrap (defaults to `globalThis.fetch`). Inject to test or to chain transports. */
   readonly fetch?: typeof globalThis.fetch;
@@ -47,9 +59,13 @@ interface X402PayDeps extends WalletDeps {
 * Build a payment-enabled `fetch` for `config`. Throws (before resolving a
 * signer) when `config.policy` is unbounded — an agent wallet is never built
 * with unlimited spend authority.
+* @experimental
 */
 declare const createPayFetch: (config: X402PayConfig, deps: X402PayDeps) => Promise<PayFetch>;
-/** A configured pay rail: a payment-enabled `fetch` bounded by the spend policy. */
+/**
+* A configured pay rail: a payment-enabled `fetch` bounded by the spend policy.
+* @experimental
+*/
 interface X402Pay {
   /** A `fetch` that transparently pays for `402`-gated resources under the policy. */
   readonly fetch: PayFetch;
@@ -58,6 +74,7 @@ interface X402Pay {
 * Build a pay rail for `config`. The returned `fetch` answers `402` challenges by
 * signing and retrying, within `config.policy`. Throws (before touching the
 * signer) when the policy is unbounded.
+* @experimental
 */
 declare const createX402Pay: (config: X402PayConfig, deps: X402PayDeps) => Promise<X402Pay>;
 /**
@@ -72,6 +89,7 @@ declare const createX402Pay: (config: X402PayConfig, deps: X402PayDeps) => Promi
 * per-run cap scopes to the ctx, not to each request. A failed build (e.g. an
 * unbounded policy) is memoised too, keeping the rail deterministically
 * fail-closed.
+* @experimental
 */
 declare const lazyX402Pay: (config: X402PayConfig, deps: X402PayDeps) => X402Pay;
 export { type PayFetch, type WalletDeps, X402Pay, type X402PayConfig, type X402PayDeps, createPayFetch, createX402Pay, lazyX402Pay, registerWallet, resolveEvmAccount, resolveSvmSigner };

package/dist/pay/index.d.ts

@@ -1,5 +1,5 @@
-import { e as X402PayConfig } from "../packem_shared/config.d-CddwCiBm.js";
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, m as DEFAULT_STABLECOIN_DECIMALS, type n as SpendPolicy, type o as SpendState, type X as X402CdpSignerConfig, type d as X402Network, type f as X402Price, type j as X402SignerConfig, p as assertBoundedPolicy, q as buildPaymentGuard, s as buildSpendPolicy, u as createSpendState, k as isEvmNetwork, l as isSvmNetwork, v as recordSpend, r as resolveFacilitatorUrl, t as toCaip2, w as usdToAtomic } from "../packem_shared/config.d-CddwCiBm.js";
+import { e as X402PayConfig } from "../packem_shared/config.d-5Nqi5iox.js";
+export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, m as DEFAULT_STABLECOIN_DECIMALS, type n as SpendPolicy, type o as SpendState, type X as X402CdpSignerConfig, type d as X402Network, type f as X402Price, type j as X402SignerConfig, p as assertBoundedPolicy, q as buildPaymentGuard, s as buildSpendPolicy, u as createSpendState, k as isEvmNetwork, l as isSvmNetwork, v as releaseSpendOnFailure, r as resolveFacilitatorUrl, t as toCaip2, w as usdToAtomic } from "../packem_shared/config.d-5Nqi5iox.js";
 import { x402Client } from '@x402/core/client';
 import { ClientSvmSigner } from '@x402/svm';
 import { PrivateKeyAccount } from 'viem/accounts';
@@ -8,7 +8,10 @@ import '@x402/core/http';
 import '@x402/core/types';
 /** Reads a secret by name; resolves `undefined` when unset. */
 type GetSecret = (name: string) => Promise<string | undefined> | string | undefined;
-/** How the wallet reads its key material — wired to `ctx.secrets.get` in an action. */
+/**
+* How the wallet reads its key material — wired to `ctx.secrets.get` in an action.
+* @experimental
+*/
 interface WalletDeps {
   /** Read a secret (e.g. a private key) by name; `undefined` when unset. */
   readonly getSecret: GetSecret;
@@ -17,6 +20,7 @@ interface WalletDeps {
 * Resolve a viem `LocalAccount` from a raw private key. The key may be given with
 * or without the `0x` prefix. The account is a structural `ClientEvmSigner`
 * (`address` + `signTypedData`), so `@x402/evm` accepts it directly.
+* @experimental
 */
 declare const resolveEvmAccount: (privateKey: string) => Promise<PrivateKeyAccount>;
 /**
@@ -25,6 +29,7 @@ declare const resolveEvmAccount: (privateKey: string) => Promise<PrivateKeyAccou
 * format) or as a base58 string. A 64-byte value is a full secret key (seed ‖
 * public key); a 32-byte value is the seed alone. The returned signer is a
 * structural `ClientSvmSigner` (`TransactionSigner`), so `@x402/svm` accepts it.
+* @experimental
 */
 declare const resolveSvmSigner: (secret: string) => Promise<ClientSvmSigner>;
 /**
@@ -34,11 +39,18 @@ declare const resolveSvmSigner: (secret: string) => Promise<ClientSvmSigner>;
 * read), `"raw-key"` (a `ctx.secrets` private key → viem account on EVM or a
 * `@solana/kit` keypair on SVM), or `"cdp"` (a Coinbase-managed wallet via
 * `@coinbase/cdp-sdk`).
+* @experimental
 */
 declare const registerWallet: (client: x402Client, config: X402PayConfig, deps: WalletDeps) => Promise<void>;
-/** A payment-enabled `fetch`: same signature as the platform `fetch`. */
+/**
+* A payment-enabled `fetch`: same signature as the platform `fetch`.
+* @experimental
+*/
 type PayFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
-/** Dependencies for building a pay-rail fetch: secret access, plus an optional base `fetch` to wrap. */
+/**
+* Dependencies for building a pay-rail fetch: secret access, plus an optional base `fetch` to wrap.
+* @experimental
+*/
 interface X402PayDeps extends WalletDeps {
   /** The `fetch` to wrap (defaults to `globalThis.fetch`). Inject to test or to chain transports. */
   readonly fetch?: typeof globalThis.fetch;
@@ -47,9 +59,13 @@ interface X402PayDeps extends WalletDeps {
 * Build a payment-enabled `fetch` for `config`. Throws (before resolving a
 * signer) when `config.policy` is unbounded — an agent wallet is never built
 * with unlimited spend authority.
+* @experimental
 */
 declare const createPayFetch: (config: X402PayConfig, deps: X402PayDeps) => Promise<PayFetch>;
-/** A configured pay rail: a payment-enabled `fetch` bounded by the spend policy. */
+/**
+* A configured pay rail: a payment-enabled `fetch` bounded by the spend policy.
+* @experimental
+*/
 interface X402Pay {
   /** A `fetch` that transparently pays for `402`-gated resources under the policy. */
   readonly fetch: PayFetch;
@@ -58,6 +74,7 @@ interface X402Pay {
 * Build a pay rail for `config`. The returned `fetch` answers `402` challenges by
 * signing and retrying, within `config.policy`. Throws (before touching the
 * signer) when the policy is unbounded.
+* @experimental
 */
 declare const createX402Pay: (config: X402PayConfig, deps: X402PayDeps) => Promise<X402Pay>;
 /**
@@ -72,6 +89,7 @@ declare const createX402Pay: (config: X402PayConfig, deps: X402PayDeps) => Promi
 * per-run cap scopes to the ctx, not to each request. A failed build (e.g. an
 * unbounded policy) is memoised too, keeping the rail deterministically
 * fail-closed.
+* @experimental
 */
 declare const lazyX402Pay: (config: X402PayConfig, deps: X402PayDeps) => X402Pay;
 export { type PayFetch, type WalletDeps, X402Pay, type X402PayConfig, type X402PayDeps, createPayFetch, createX402Pay, lazyX402Pay, registerWallet, resolveEvmAccount, resolveSvmSigner };

package/dist/pay/index.mjs

@@ -1,7 +1,7 @@
-import { createPayFetch } from '../packem_shared/createPayFetch-O2vkvM1v.mjs';
+import { createPayFetch } from '../packem_shared/createPayFetch-BeT05njL.mjs';
 export { DEFAULT_FACILITATOR_URL, resolveFacilitatorUrl } from '../packem_shared/DEFAULT_FACILITATOR_URL-Cbz6kIqa.mjs';
 export { isEvmNetwork, isSvmNetwork, toCaip2 } from '../packem_shared/EVM_NETWORKS-BhnYWUQ4.mjs';
-export { DEFAULT_STABLECOIN_DECIMALS, assertBoundedPolicy, buildPaymentGuard, buildSpendPolicy, createSpendState, recordSpend, usdToAtomic } from '../packem_shared/DEFAULT_STABLECOIN_DECIMALS-CSu5b5lD.mjs';
+export { DEFAULT_STABLECOIN_DECIMALS, assertBoundedPolicy, buildPaymentGuard, buildSpendPolicy, createSpendState, releaseSpendOnFailure, usdToAtomic } from '../packem_shared/DEFAULT_STABLECOIN_DECIMALS-CpW619nu.mjs';
 export { registerWallet, resolveEvmAccount, resolveSvmSigner } from '../packem_shared/registerWallet-I4pVwq65.mjs';
 
 const createX402Pay = async (config, deps) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/x402",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Agentic payments (x402) for Lunora: charge agents per request (charge rail) and let your agents pay x402-gated resources (pay rail)",
   "keywords": [
     "agents",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.4",
+    "@lunora/errors": "1.0.0-alpha.5",
     "@solana/kit": "5.5.1",
     "@x402/core": "2.17.0",
     "@x402/evm": "2.17.0",