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

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-D8gKQLAq.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-D8gKQLAq.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';
@@ -34,12 +34,24 @@ declare const withX402: <Context>(config: X402ChargeConfig, handler: HttpActionH
 */
 type ChargeHandler = () => Promise<Response> | Response;
 /**
+* 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
@@ -51,13 +63,39 @@ interface ChargeMiddleware {
 */
 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
@@ -79,17 +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-D8gKQLAq.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-D8gKQLAq.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';
@@ -34,12 +34,24 @@ declare const withX402: <Context>(config: X402ChargeConfig, handler: HttpActionH
 */
 type ChargeHandler = () => Promise<Response> | Response;
 /**
+* 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
@@ -51,13 +63,39 @@ interface ChargeMiddleware {
 */
 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
@@ -79,17 +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-SOW47gf3.mjs';
-export { createChargeMiddleware } from '../packem_shared/createChargeMiddleware-CARkBOyH.mjs';
-export { createProcedureChargeGate } from '../packem_shared/createProcedureChargeGate-MaMhu9L9.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-D8gKQLAq.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-D8gKQLAq.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-D8gKQLAq.d.mts → config.d-5Nqi5iox.d.mts}

@@ -1,7 +1,7 @@
 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
@@ -193,17 +193,20 @@ 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;
@@ -226,19 +229,38 @@ 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;
@@ -379,4 +401,4 @@ type X402SignerConfig = X402CdpSignerConfig | {
 * @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-D8gKQLAq.d.ts → config.d-5Nqi5iox.d.ts}

@@ -1,7 +1,7 @@
 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
@@ -193,17 +193,20 @@ 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;
@@ -226,19 +229,38 @@ 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;
@@ -379,4 +401,4 @@ type X402SignerConfig = X402CdpSignerConfig | {
 * @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-CARkBOyH.mjs → createChargeMiddleware-D3yhOpFs.mjs}

@@ -25,13 +25,14 @@ const headerRecord = (headers) => {
   }
   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 {
   }
 };
@@ -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-MaMhu9L9.mjs → createProcedureChargeGate-eh9yv36U.mjs}

@@ -1,18 +1,20 @@
-import { createChargeMiddleware } from './createChargeMiddleware-CARkBOyH.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-SOW47gf3.mjs → withX402-DILL2DvD.mjs}

@@ -1,4 +1,4 @@
-import { createChargeMiddleware } from './createChargeMiddleware-CARkBOyH.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-D8gKQLAq.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-D8gKQLAq.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';

package/dist/pay/index.d.ts

@@ -1,5 +1,5 @@
-import { e as X402PayConfig } from "../packem_shared/config.d-D8gKQLAq.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-D8gKQLAq.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';

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.3",
+  "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",