@dexterai/x402 3.16.0 → 3.18.0

package/dist/tab/seller/index.d.cts

@@ -1,7 +1,123 @@
-import { TabNetworkId, HumanAmount, SignedVoucher, AtomicAmount } from '@dexterai/vault/types';
+import { SignedVoucher, AtomicAmount, TabNetworkId, HumanAmount } from '@dexterai/vault/types';
 import { RequestHandler, Request, Response } from 'express';
 import { Connection, PublicKey } from '@solana/web3.js';
 
+/**
+ * Durable per-channel seller ledger for OTS tab streaming.
+ *
+ * Supersedes VoucherStore: it persists the latest accepted voucher AND the
+ * one quantity the chain never sees — `deliveredCumulativeAtomic`, the
+ * cumulative service the meter has actually delivered on this channel across
+ * ALL requests. Monotonic, never reset. This is what closes the channel-reuse
+ * metering leak: the meter budgets each request against
+ * `signedCumulative − deliveredCumulative`, not the lifetime cumulative.
+ *
+ * Shape mirrors the on-chain SessionRegistration money ledger
+ * (spent / crystallized_cumulative / current_outstanding / last_locked_sequence)
+ * that already ships in V6, via the optional `onChain` snapshot. That field is
+ * RESERVED for the Step-4 lock/LockedClaim model (lock_voucher reads/writes
+ * those on-chain) — the off-chain meter does not populate it today. Reserving
+ * it here keeps the ledger forward-compatible without a later breaking change.
+ *
+ * The same durable state is the substrate resumeTab / stranded-tab recovery
+ * needs (last voucher + delivered baseline per channel).
+ *
+ * Single-stream lease (multi-instance boundary): the per-channel `lease`
+ * (tryAcquireLease/releaseLease) enforces ONE live stream per channel, the
+ * defense against the concurrent-same-channel over-delivery rug. The default
+ * InMemoryChannelLedger / FileChannelLedger acquire it atomically WITHIN one
+ * seller process (via the per-channel async lock). A seller running MULTIPLE
+ * instances behind a load balancer MUST either back ChannelLedger with a store
+ * that makes acquire atomic across processes (Redis `SET NX PX`, Postgres
+ * advisory lock / `INSERT ... ON CONFLICT`) or route a channel's requests to a
+ * consistent instance — otherwise two instances can each acquire the lease and
+ * the rug reopens.
+ */
+
+/**
+ * Read-through cache of the on-chain SessionRegistration money ledger.
+ * RESERVED for Step 4 (lock_voucher / LockedClaim). Not populated by the
+ * off-chain meter today. All amounts are atomic (base units) strings.
+ */
+interface OnChainLedgerSnapshot {
+    spentAtomic: AtomicAmount;
+    crystallizedCumulativeAtomic: AtomicAmount;
+    currentOutstandingAtomic: AtomicAmount;
+    lastLockedSequence: number;
+    /** Unix seconds when this snapshot was read from chain. */
+    fetchedAtUnixSec: number;
+}
+interface ChannelLedgerEntry {
+    /**
+     * Latest accepted voucher (`payload.cumulativeAmount` is the signedCumulative),
+     * or `null` for a lease-only entry created when the first request on a channel
+     * acquires its single-stream lease BEFORE any voucher is persisted. The
+     * middleware writes the real voucher immediately after acquiring the lease, so
+     * a null `lastVoucher` is only ever a transient pre-first-voucher state.
+     */
+    lastVoucher: SignedVoucher | null;
+    /**
+     * Off-chain cumulative the meter has DELIVERED on this channel across all
+     * requests. Monotonic; never reset. The leak-fix field.
+     */
+    deliveredCumulativeAtomic: AtomicAmount;
+    /**
+     * Delivered cumulative (atomic) that the seller has already crystallized into
+     * an on-chain LockedClaim via the keyless `/tab/lock` cadence (Step-4). The
+     * crystallization cadence fires when `deliveredCumulativeAtomic −
+     * lastCrystallizedCumulativeAtomic` crosses the configured threshold, then
+     * advances this on a successful lock so it can't double-fire. Treated as
+     * `'0'` when absent (older entries / lease-only entries). Optional so
+     * pre-Step-4 ledger constructors remain valid without a breaking change.
+     */
+    lastCrystallizedCumulativeAtomic?: AtomicAmount;
+    /** RESERVED (Step 4): on-chain money ledger snapshot. Unset today. */
+    onChain?: OnChainLedgerSnapshot;
+    /**
+     * Active-stream lease. Set while a meter is live on this channel; cleared on
+     * the meter's terminal path. `heldUntilUnixMs` is a TTL so a crashed holder's
+     * lease auto-expires (a stuck lease would otherwise block the buyer's own
+     * next request on this tab). Enforces one live stream per channel — the
+     * defense against the concurrent-same-channel over-delivery rug.
+     */
+    lease?: {
+        heldUntilUnixMs: number;
+    };
+}
+interface ChannelLedger {
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    /**
+     * Atomically acquire the channel's single-stream lease if free or expired.
+     * Returns true if acquired, false if another live stream holds it. The
+     * in-process/file impls serialize via the per-channel lock (correct for a
+     * single seller process). A multi-instance seller MUST back this with a store
+     * that makes acquire atomic across processes (Redis SETNX, Postgres, ...).
+     */
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    /** Release the channel's lease (no-op if not held). */
+    releaseLease(channelId: string): Promise<void>;
+}
+declare class InMemoryChannelLedger implements ChannelLedger {
+    private map;
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    releaseLease(channelId: string): Promise<void>;
+}
+declare class FileChannelLedger implements ChannelLedger {
+    private readonly dir;
+    constructor(dir: string);
+    private pathFor;
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    releaseLease(channelId: string): Promise<void>;
+}
+
 /**
  * @dexterai/x402/tab/seller — types for the seller side of OTS tab streaming.
  *
@@ -17,6 +133,7 @@ import { Connection, PublicKey } from '@solana/web3.js';
  * loses at most the last in-flight voucher's worth of revenue. Pluggable to
  * match `batch-settlement/store`'s ChannelStore pattern.
  */
+/** @deprecated Superseded by ChannelLedger (channel-ledger.ts), which also persists deliveredCumulative. */
 interface VoucherStore {
     get(channelId: string): Promise<SignedVoucher | null>;
     set(channelId: string, voucher: SignedVoucher): Promise<void>;
@@ -39,6 +156,19 @@ interface SellerTab {
      * monotonicity check fails. The middleware persists on success.
      */
     charge(incrementHuman: HumanAmount): Promise<void>;
+    /**
+     * Off-chain cumulative (human amount) the meter has DELIVERED on this
+     * channel across ALL requests, read from the ChannelLedger at request start.
+     * The meter's per-request budget is `cumulative() − deliveredCumulative()`.
+     */
+    deliveredCumulative(): HumanAmount;
+    /**
+     * Add `incrementAtomic` (this request's delivered amount, atomic) to the
+     * channel's durable lifetime delivered total, under a per-channel lock.
+     * Monotonic — a non-positive increment is a no-op. Called by the meter once
+     * per request on the terminal path (end / cap-reject / disconnect).
+     */
+    recordDelivered(incrementAtomic: AtomicAmount): Promise<void>;
 }
 /** Options for `tabMiddleware`. */
 interface TabMiddlewareOptions {
@@ -48,16 +178,42 @@ interface TabMiddlewareOptions {
     network: TabNetworkId;
     /** When to settle on chain: at tab close (the common case) vs periodically. */
     settle: 'on-close' | 'periodic';
-    /** Facilitator base URL. Default: https://facilitator.dexter.cash. */
+    /** Facilitator base URL. Default: DEFAULT_FACILITATOR_URL (https://x402.dexter.cash). */
     facilitatorUrl?: string;
-    /** Voucher persistence. Default: file-backed. */
-    store?: VoucherStore;
+    /**
+     * Durable per-channel state (latest voucher + delivered cumulative).
+     * Default: in-memory (loses state on restart). Pass a FileChannelLedger or
+     * your own ChannelLedger for restart-safe revenue + resumeTab support.
+     */
+    ledger?: ChannelLedger;
+    /**
+     * Max single-stream duration before a crashed holder's lease auto-expires.
+     * Default 300000 (5 min).
+     */
+    leaseTtlMs?: number;
     /**
      * Hard cap on a single voucher's incremental amount. Protects the seller's
      * middleware from accepting a buyer trying to slip in a giant single
      * voucher. Default: 100x `perUnit`.
      */
     maxPerVoucherAtomic?: AtomicAmount;
+    /**
+     * Keyless crystallization cadence (Step-4 lock-mode). On the configured
+     * delivered-amount threshold — and at tab close — the meter POSTs the
+     * buyer's already-stored signed voucher to `${facilitatorUrl}/tab/lock`,
+     * crystallizing it into an on-chain LockedClaim. BEST-EFFORT: a failed
+     * crystallize never blocks or errors the seller's response; a missed lock
+     * just widens the seller's unsecured window (their risk dial).
+     *
+     * Defaults when omitted: `{ thresholdAtomic: humanToAtomic('0.10'),
+     * onClose: true }`. Set `thresholdAtomic` higher to crystallize less often
+     * (cheaper, wider window) or lower to lock more aggressively. Set
+     * `onClose: false` to skip the close-time lock.
+     */
+    lockCadence?: {
+        thresholdAtomic?: string;
+        onClose?: boolean;
+    };
 }
 /**
  * Options for `openSse` — the Express response → SSE stream helper. Returns
@@ -76,12 +232,12 @@ interface OpenSseOptions {
 interface SseMeter {
     charge(units?: number): Promise<void>;
     send(chunk: string | Uint8Array): void;
-    end(): void;
+    end(): Promise<void>;
 }
 /** Errors thrown by the seller middleware on bad vouchers. */
 declare class InvalidVoucherError extends Error {
-    readonly reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic';
-    constructor(reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic', detail?: string);
+    readonly reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic' | 'channel_busy';
+    constructor(reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic' | 'channel_busy', detail?: string);
 }
 
 /**
@@ -148,6 +304,16 @@ declare function requireTab(req: Request): SellerTab;
  * left for Phase 4+; the v3 meter ships the simpler "one voucher bounds
  * the whole request" model, which is correct for any reasonable chunk
  * count under a single per-request increment.
+ *
+ * Concurrency note: delivered accounting is exact for requests that run
+ * sequentially per channel (the normal case — an agent streams one request at
+ * a time per tab). Two GENUINELY concurrent streams on the SAME channel each
+ * read the same delivered baseline, so they can over-deliver in-flight up to
+ * the sum of their budgets before either persists. The lifetime ledger stays
+ * correct (additive under a per-channel lock), so the over-delivery is bounded
+ * to the overlap and never compounds across future requests. Sellers needing
+ * exact metering under parallel same-channel streams should serialize requests
+ * per channel.
  */
 
 declare function openSse(res: Response, options: OpenSseOptions): SseMeter;
@@ -306,4 +472,39 @@ interface TabChallengeConfig {
 }
 declare function tabChallengeMiddleware(config: TabChallengeConfig): RequestHandler;
 
-export { FileVoucherStore, InMemoryVoucherStore, InvalidRegistrationError, InvalidVoucherError, InvalidVoucherSignatureError, OnChainVerificationError, type OpenSseOptions, type ParsedRegistration, ScopeViolationError, type SellerTab, type SseMeter, TAB_VOUCHER_HEADER, type TabChallengeConfig, type TabMiddlewareConfig, type TabMiddlewareOptions, type VoucherStore, enforceScope, openSse, parseRegistration, requireTab, tabChallengeMiddleware, tabMiddleware, verifyRegistrationOnChain, verifyVoucherSignature };
+/**
+ * Dual-rail tab seller: ONE middleware advertising BOTH payment rails in a
+ * single standard x402 v2 402 challenge —
+ *
+ *   scheme 'tab'   — agents open a freeze-protected tab and stream vouchers
+ *   scheme 'exact' — one-shot buyers (and catalog verifiers, which cannot
+ *                    open tabs) pay per request
+ *
+ * Compose as the ONLY payment middleware on the route:
+ *
+ *   app.get('/paid/x', tabOrExactMiddleware({ ... }), handler);
+ *
+ * In the handler: `(req as X402Request).x402` set -> the request was paid
+ * via exact (respond normally); otherwise `requireTab(req)` -> tab rail
+ * (charge via openSse meter).
+ *
+ * SECURITY: the exact rail passes requirements EXPLICITLY to verify/settle
+ * (built from OUR configured amount). X402Server's no-requirements fallback
+ * rebuilds them from the BUYER'S header amount on cache miss — an
+ * underpayment hole this middleware must never take (pinned in dual.test.ts).
+ */
+
+interface TabOrExactConfig {
+    /** For tab voucher verification (V6 session PDA reads). */
+    connection: Connection;
+    /** Seller pubkey — payTo on BOTH rails. */
+    sellerPubkey: string | PublicKey;
+    network: TabNetworkId;
+    /** Price per request, human units — identical on both rails. */
+    perUnit: HumanAmount;
+    facilitatorUrl?: string;
+    description?: string;
+}
+declare function tabOrExactMiddleware(config: TabOrExactConfig): RequestHandler;
+
+export { type ChannelLedger, type ChannelLedgerEntry, FileChannelLedger, FileVoucherStore, InMemoryChannelLedger, InMemoryVoucherStore, InvalidRegistrationError, InvalidVoucherError, InvalidVoucherSignatureError, type OnChainLedgerSnapshot, OnChainVerificationError, type OpenSseOptions, type ParsedRegistration, ScopeViolationError, type SellerTab, type SseMeter, TAB_VOUCHER_HEADER, type TabChallengeConfig, type TabMiddlewareConfig, type TabMiddlewareOptions, type TabOrExactConfig, type VoucherStore, enforceScope, openSse, parseRegistration, requireTab, tabChallengeMiddleware, tabMiddleware, tabOrExactMiddleware, verifyRegistrationOnChain, verifyVoucherSignature };

package/dist/tab/seller/index.d.ts

@@ -1,7 +1,123 @@
-import { TabNetworkId, HumanAmount, SignedVoucher, AtomicAmount } from '@dexterai/vault/types';
+import { SignedVoucher, AtomicAmount, TabNetworkId, HumanAmount } from '@dexterai/vault/types';
 import { RequestHandler, Request, Response } from 'express';
 import { Connection, PublicKey } from '@solana/web3.js';
 
+/**
+ * Durable per-channel seller ledger for OTS tab streaming.
+ *
+ * Supersedes VoucherStore: it persists the latest accepted voucher AND the
+ * one quantity the chain never sees — `deliveredCumulativeAtomic`, the
+ * cumulative service the meter has actually delivered on this channel across
+ * ALL requests. Monotonic, never reset. This is what closes the channel-reuse
+ * metering leak: the meter budgets each request against
+ * `signedCumulative − deliveredCumulative`, not the lifetime cumulative.
+ *
+ * Shape mirrors the on-chain SessionRegistration money ledger
+ * (spent / crystallized_cumulative / current_outstanding / last_locked_sequence)
+ * that already ships in V6, via the optional `onChain` snapshot. That field is
+ * RESERVED for the Step-4 lock/LockedClaim model (lock_voucher reads/writes
+ * those on-chain) — the off-chain meter does not populate it today. Reserving
+ * it here keeps the ledger forward-compatible without a later breaking change.
+ *
+ * The same durable state is the substrate resumeTab / stranded-tab recovery
+ * needs (last voucher + delivered baseline per channel).
+ *
+ * Single-stream lease (multi-instance boundary): the per-channel `lease`
+ * (tryAcquireLease/releaseLease) enforces ONE live stream per channel, the
+ * defense against the concurrent-same-channel over-delivery rug. The default
+ * InMemoryChannelLedger / FileChannelLedger acquire it atomically WITHIN one
+ * seller process (via the per-channel async lock). A seller running MULTIPLE
+ * instances behind a load balancer MUST either back ChannelLedger with a store
+ * that makes acquire atomic across processes (Redis `SET NX PX`, Postgres
+ * advisory lock / `INSERT ... ON CONFLICT`) or route a channel's requests to a
+ * consistent instance — otherwise two instances can each acquire the lease and
+ * the rug reopens.
+ */
+
+/**
+ * Read-through cache of the on-chain SessionRegistration money ledger.
+ * RESERVED for Step 4 (lock_voucher / LockedClaim). Not populated by the
+ * off-chain meter today. All amounts are atomic (base units) strings.
+ */
+interface OnChainLedgerSnapshot {
+    spentAtomic: AtomicAmount;
+    crystallizedCumulativeAtomic: AtomicAmount;
+    currentOutstandingAtomic: AtomicAmount;
+    lastLockedSequence: number;
+    /** Unix seconds when this snapshot was read from chain. */
+    fetchedAtUnixSec: number;
+}
+interface ChannelLedgerEntry {
+    /**
+     * Latest accepted voucher (`payload.cumulativeAmount` is the signedCumulative),
+     * or `null` for a lease-only entry created when the first request on a channel
+     * acquires its single-stream lease BEFORE any voucher is persisted. The
+     * middleware writes the real voucher immediately after acquiring the lease, so
+     * a null `lastVoucher` is only ever a transient pre-first-voucher state.
+     */
+    lastVoucher: SignedVoucher | null;
+    /**
+     * Off-chain cumulative the meter has DELIVERED on this channel across all
+     * requests. Monotonic; never reset. The leak-fix field.
+     */
+    deliveredCumulativeAtomic: AtomicAmount;
+    /**
+     * Delivered cumulative (atomic) that the seller has already crystallized into
+     * an on-chain LockedClaim via the keyless `/tab/lock` cadence (Step-4). The
+     * crystallization cadence fires when `deliveredCumulativeAtomic −
+     * lastCrystallizedCumulativeAtomic` crosses the configured threshold, then
+     * advances this on a successful lock so it can't double-fire. Treated as
+     * `'0'` when absent (older entries / lease-only entries). Optional so
+     * pre-Step-4 ledger constructors remain valid without a breaking change.
+     */
+    lastCrystallizedCumulativeAtomic?: AtomicAmount;
+    /** RESERVED (Step 4): on-chain money ledger snapshot. Unset today. */
+    onChain?: OnChainLedgerSnapshot;
+    /**
+     * Active-stream lease. Set while a meter is live on this channel; cleared on
+     * the meter's terminal path. `heldUntilUnixMs` is a TTL so a crashed holder's
+     * lease auto-expires (a stuck lease would otherwise block the buyer's own
+     * next request on this tab). Enforces one live stream per channel — the
+     * defense against the concurrent-same-channel over-delivery rug.
+     */
+    lease?: {
+        heldUntilUnixMs: number;
+    };
+}
+interface ChannelLedger {
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    /**
+     * Atomically acquire the channel's single-stream lease if free or expired.
+     * Returns true if acquired, false if another live stream holds it. The
+     * in-process/file impls serialize via the per-channel lock (correct for a
+     * single seller process). A multi-instance seller MUST back this with a store
+     * that makes acquire atomic across processes (Redis SETNX, Postgres, ...).
+     */
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    /** Release the channel's lease (no-op if not held). */
+    releaseLease(channelId: string): Promise<void>;
+}
+declare class InMemoryChannelLedger implements ChannelLedger {
+    private map;
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    releaseLease(channelId: string): Promise<void>;
+}
+declare class FileChannelLedger implements ChannelLedger {
+    private readonly dir;
+    constructor(dir: string);
+    private pathFor;
+    get(channelId: string): Promise<ChannelLedgerEntry | null>;
+    set(channelId: string, entry: ChannelLedgerEntry): Promise<void>;
+    delete(channelId: string): Promise<void>;
+    tryAcquireLease(channelId: string, ttlMs: number): Promise<boolean>;
+    releaseLease(channelId: string): Promise<void>;
+}
+
 /**
  * @dexterai/x402/tab/seller — types for the seller side of OTS tab streaming.
  *
@@ -17,6 +133,7 @@ import { Connection, PublicKey } from '@solana/web3.js';
  * loses at most the last in-flight voucher's worth of revenue. Pluggable to
  * match `batch-settlement/store`'s ChannelStore pattern.
  */
+/** @deprecated Superseded by ChannelLedger (channel-ledger.ts), which also persists deliveredCumulative. */
 interface VoucherStore {
     get(channelId: string): Promise<SignedVoucher | null>;
     set(channelId: string, voucher: SignedVoucher): Promise<void>;
@@ -39,6 +156,19 @@ interface SellerTab {
      * monotonicity check fails. The middleware persists on success.
      */
     charge(incrementHuman: HumanAmount): Promise<void>;
+    /**
+     * Off-chain cumulative (human amount) the meter has DELIVERED on this
+     * channel across ALL requests, read from the ChannelLedger at request start.
+     * The meter's per-request budget is `cumulative() − deliveredCumulative()`.
+     */
+    deliveredCumulative(): HumanAmount;
+    /**
+     * Add `incrementAtomic` (this request's delivered amount, atomic) to the
+     * channel's durable lifetime delivered total, under a per-channel lock.
+     * Monotonic — a non-positive increment is a no-op. Called by the meter once
+     * per request on the terminal path (end / cap-reject / disconnect).
+     */
+    recordDelivered(incrementAtomic: AtomicAmount): Promise<void>;
 }
 /** Options for `tabMiddleware`. */
 interface TabMiddlewareOptions {
@@ -48,16 +178,42 @@ interface TabMiddlewareOptions {
     network: TabNetworkId;
     /** When to settle on chain: at tab close (the common case) vs periodically. */
     settle: 'on-close' | 'periodic';
-    /** Facilitator base URL. Default: https://facilitator.dexter.cash. */
+    /** Facilitator base URL. Default: DEFAULT_FACILITATOR_URL (https://x402.dexter.cash). */
     facilitatorUrl?: string;
-    /** Voucher persistence. Default: file-backed. */
-    store?: VoucherStore;
+    /**
+     * Durable per-channel state (latest voucher + delivered cumulative).
+     * Default: in-memory (loses state on restart). Pass a FileChannelLedger or
+     * your own ChannelLedger for restart-safe revenue + resumeTab support.
+     */
+    ledger?: ChannelLedger;
+    /**
+     * Max single-stream duration before a crashed holder's lease auto-expires.
+     * Default 300000 (5 min).
+     */
+    leaseTtlMs?: number;
     /**
      * Hard cap on a single voucher's incremental amount. Protects the seller's
      * middleware from accepting a buyer trying to slip in a giant single
      * voucher. Default: 100x `perUnit`.
      */
     maxPerVoucherAtomic?: AtomicAmount;
+    /**
+     * Keyless crystallization cadence (Step-4 lock-mode). On the configured
+     * delivered-amount threshold — and at tab close — the meter POSTs the
+     * buyer's already-stored signed voucher to `${facilitatorUrl}/tab/lock`,
+     * crystallizing it into an on-chain LockedClaim. BEST-EFFORT: a failed
+     * crystallize never blocks or errors the seller's response; a missed lock
+     * just widens the seller's unsecured window (their risk dial).
+     *
+     * Defaults when omitted: `{ thresholdAtomic: humanToAtomic('0.10'),
+     * onClose: true }`. Set `thresholdAtomic` higher to crystallize less often
+     * (cheaper, wider window) or lower to lock more aggressively. Set
+     * `onClose: false` to skip the close-time lock.
+     */
+    lockCadence?: {
+        thresholdAtomic?: string;
+        onClose?: boolean;
+    };
 }
 /**
  * Options for `openSse` — the Express response → SSE stream helper. Returns
@@ -76,12 +232,12 @@ interface OpenSseOptions {
 interface SseMeter {
     charge(units?: number): Promise<void>;
     send(chunk: string | Uint8Array): void;
-    end(): void;
+    end(): Promise<void>;
 }
 /** Errors thrown by the seller middleware on bad vouchers. */
 declare class InvalidVoucherError extends Error {
-    readonly reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic';
-    constructor(reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic', detail?: string);
+    readonly reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic' | 'channel_busy';
+    constructor(reason: 'signature_invalid' | 'registration_invalid' | 'cap_exceeded' | 'session_expired' | 'wrong_counterparty' | 'non_monotonic' | 'channel_busy', detail?: string);
 }
 
 /**
@@ -148,6 +304,16 @@ declare function requireTab(req: Request): SellerTab;
  * left for Phase 4+; the v3 meter ships the simpler "one voucher bounds
  * the whole request" model, which is correct for any reasonable chunk
  * count under a single per-request increment.
+ *
+ * Concurrency note: delivered accounting is exact for requests that run
+ * sequentially per channel (the normal case — an agent streams one request at
+ * a time per tab). Two GENUINELY concurrent streams on the SAME channel each
+ * read the same delivered baseline, so they can over-deliver in-flight up to
+ * the sum of their budgets before either persists. The lifetime ledger stays
+ * correct (additive under a per-channel lock), so the over-delivery is bounded
+ * to the overlap and never compounds across future requests. Sellers needing
+ * exact metering under parallel same-channel streams should serialize requests
+ * per channel.
  */
 
 declare function openSse(res: Response, options: OpenSseOptions): SseMeter;
@@ -306,4 +472,39 @@ interface TabChallengeConfig {
 }
 declare function tabChallengeMiddleware(config: TabChallengeConfig): RequestHandler;
 
-export { FileVoucherStore, InMemoryVoucherStore, InvalidRegistrationError, InvalidVoucherError, InvalidVoucherSignatureError, OnChainVerificationError, type OpenSseOptions, type ParsedRegistration, ScopeViolationError, type SellerTab, type SseMeter, TAB_VOUCHER_HEADER, type TabChallengeConfig, type TabMiddlewareConfig, type TabMiddlewareOptions, type VoucherStore, enforceScope, openSse, parseRegistration, requireTab, tabChallengeMiddleware, tabMiddleware, verifyRegistrationOnChain, verifyVoucherSignature };
+/**
+ * Dual-rail tab seller: ONE middleware advertising BOTH payment rails in a
+ * single standard x402 v2 402 challenge —
+ *
+ *   scheme 'tab'   — agents open a freeze-protected tab and stream vouchers
+ *   scheme 'exact' — one-shot buyers (and catalog verifiers, which cannot
+ *                    open tabs) pay per request
+ *
+ * Compose as the ONLY payment middleware on the route:
+ *
+ *   app.get('/paid/x', tabOrExactMiddleware({ ... }), handler);
+ *
+ * In the handler: `(req as X402Request).x402` set -> the request was paid
+ * via exact (respond normally); otherwise `requireTab(req)` -> tab rail
+ * (charge via openSse meter).
+ *
+ * SECURITY: the exact rail passes requirements EXPLICITLY to verify/settle
+ * (built from OUR configured amount). X402Server's no-requirements fallback
+ * rebuilds them from the BUYER'S header amount on cache miss — an
+ * underpayment hole this middleware must never take (pinned in dual.test.ts).
+ */
+
+interface TabOrExactConfig {
+    /** For tab voucher verification (V6 session PDA reads). */
+    connection: Connection;
+    /** Seller pubkey — payTo on BOTH rails. */
+    sellerPubkey: string | PublicKey;
+    network: TabNetworkId;
+    /** Price per request, human units — identical on both rails. */
+    perUnit: HumanAmount;
+    facilitatorUrl?: string;
+    description?: string;
+}
+declare function tabOrExactMiddleware(config: TabOrExactConfig): RequestHandler;
+
+export { type ChannelLedger, type ChannelLedgerEntry, FileChannelLedger, FileVoucherStore, InMemoryChannelLedger, InMemoryVoucherStore, InvalidRegistrationError, InvalidVoucherError, InvalidVoucherSignatureError, type OnChainLedgerSnapshot, OnChainVerificationError, type OpenSseOptions, type ParsedRegistration, ScopeViolationError, type SellerTab, type SseMeter, TAB_VOUCHER_HEADER, type TabChallengeConfig, type TabMiddlewareConfig, type TabMiddlewareOptions, type TabOrExactConfig, type VoucherStore, enforceScope, openSse, parseRegistration, requireTab, tabChallengeMiddleware, tabMiddleware, tabOrExactMiddleware, verifyRegistrationOnChain, verifyVoucherSignature };