@dvmkit/sdk 0.2.0-rc.9 → 0.3.0-rc.9

package/dist/{step-cache-CXg7ziML.d.ts → step-cache-v2yhyhSZ.d.ts}

@@ -170,20 +170,7 @@ interface X402Receipt {
     invalidReason?: string;
 }
 
-/**
- * dvmkit's x402 wire-format implementation — the v1/v2 `PaymentRequirements` /
- * `PaymentPayload` envelope shapes, payment-header encode/decode, and the
- * facilitator verify/settle calls that a deployed DVM's 402 response and
- * payment parsing are built from. A wire-format change lands here.
- *
- * **On a change here, or an x402 reference-client upgrade, run the conformance
- * check** — `public compatibility guide`. Our own SDK round-trips
- * against itself (the vitest tiers, `money-loop:x402`), so only a client
- * that isn't dvmkit can catch a *mutual* misreading of the spec. The runbook
- * names the out-of-tree v1 and v2 clients plus the funded Base Sepolia key
- * (`public compatibility guide`); the runbook carries a run log of
- * what it last ran against.
- */
+/** Wire compatibility requires independent v1 and v2 reference-client checks. */
 
 /** Current x402 protocol version preferred by dvmkit clients and servers. */
 declare const X402_VERSION = 2;
@@ -341,11 +328,8 @@ interface BuildPaymentRequirementsOpts {
     version?: X402Version;
 }
 /**
- * Build a single x402 `PaymentRequirements` entry from the DVM's `X402Config`,
- * the resolved per-call USDC amount, and the live request's resource URL.
- * The resource string is bound into the EIP-3009 `extra` field on signing in
- * the reference clients, so it must match exactly between the 402 response
- * and the retry payload — pass the request URL the client will retry against.
+ * V1 carries the resource URL in each requirement; v2 carries it in the outer
+ * response. This metadata is not part of the EIP-3009 authorization signature.
  */
 declare function buildPaymentRequirements(opts: BuildPaymentRequirementsOpts & {
     version: typeof X402_V1_VERSION;
@@ -361,13 +345,7 @@ declare function buildPaymentRequiredV2(opts: Omit<BuildPaymentRequirementsOpts,
 }): PaymentRequiredV2;
 /** Convert the server's legacy body requirements into the parallel v2 declaration. */
 declare function paymentRequiredV2FromV1(requirements: PaymentRequirementsV1[], error?: string): PaymentRequiredV2;
-/**
- * Translate a CAIP-2 chain id (`eip155:8453`) to the x402-spec network slug
- * (`base`). Operators configure DVMs in CAIP-2 because it's the lingua-franca
- * across our other rails; the x402 facilitator API only accepts named slugs.
- * Unknown CAIP-2 ids fall through to the original string so non-EVM rails
- * (Solana mainnet, etc.) can also be plumbed once supported.
- */
+/** Legacy v1 network slugs; unknown identifiers pass through unchanged. */
 declare function caip2ToX402Network(network: string): string;
 /** Translate a legacy x402 network slug back to its CAIP-2 chain id. */
 declare function x402NetworkToCaip2(network: string): string;
@@ -375,12 +353,6 @@ declare function x402NetworkToCaip2(network: string): string;
 declare function chainIdFromCaip2(network: string): number;
 /** USDC contract address for a network slug (post-translation). */
 declare function usdcContractFor(networkSlug: string): `0x${string}` | undefined;
-/**
- * USDC contract address for a CAIP-2 chain id (e.g. `eip155:8453`). Resolves
- * via {@link caip2ToX402Network} so the one network table is the source of
- * truth — keeps callers that hold the CAIP-2 form (CLI wallet) in lockstep
- * with the SDK 402-builder which already speaks x402 slugs.
- */
 declare function usdcContractByCaip2(caip2: string): `0x${string}` | undefined;
 /** USDC EIP-712 domain `name` for a network slug. */
 declare function usdcDomainNameFor(networkSlug: string): string | undefined;
@@ -575,7 +547,6 @@ interface ProgressContent {
     /** Optional human-readable hint about what's happening right now. */
     hint?: string;
 }
-/** A single message in a job conversation — discriminated union on `type`. */
 type Message = (MessageBase & {
     type: "text";
     content: TextContent;
@@ -610,37 +581,30 @@ type Message = (MessageBase & {
     type: "progress";
     content: ProgressContent;
 });
-/** Type guard: message is a prompt from the provider. */
 declare function isPromptMessage(msg: Message): msg is MessageBase & {
     type: "prompt";
     content: PromptContent;
 };
-/** Type guard: message contains an artifact. */
 declare function isArtifactMessage(msg: Message): msg is MessageBase & {
     type: "artifact";
     content: ArtifactContent;
 };
-/** Type guard: message is a payment request. */
 declare function isPaymentRequestMessage(msg: Message): msg is MessageBase & {
     type: "payment-request";
     content: PaymentRequestContent;
 };
-/** Type guard: message is a text message. */
 declare function isTextMessage(msg: Message): msg is MessageBase & {
     type: "text";
     content: TextContent;
 };
-/** Type guard: message signals completion. */
 declare function isCompleteMessage(msg: Message): msg is MessageBase & {
     type: "complete";
     content: CompleteContent;
 };
-/** Type guard: message is a cancellation. */
 declare function isCancelMessage(msg: Message): msg is MessageBase & {
     type: "cancel";
     content: CancelContent;
 };
-/** Type guard: message is a working signal. */
 declare function isWorkingMessage(msg: Message): msg is MessageBase & {
     type: "working";
     content: WorkingContent;
@@ -686,7 +650,6 @@ declare const CLIENT_COMPATIBILITY_HEADERS: {
     readonly protocolVersion: "DVM-Protocol-Version";
     readonly capabilities: "DVM-Client-Capabilities";
 };
-/** A parsed SemVer value carried by `DVM-Client`. */
 interface ClientSemVer {
     readonly version: string;
     readonly major: number;
@@ -694,7 +657,6 @@ interface ClientSemVer {
     readonly patch: number;
     readonly prerelease: readonly (string | number)[];
 }
-/** Validated compatibility metadata from one HTTP request. */
 interface ClientCompatibility {
     readonly clientVersion?: ClientSemVer;
     readonly protocolVersion?: number;
@@ -710,16 +672,13 @@ interface ClientCompatibility {
         readonly capabilities: boolean;
     };
 }
-/** Compatibility requirement attached to one endpoint. */
 interface ClientCompatibilityRequirement {
     /** Additive capability tokens the caller must advertise. */
     readonly requiredCapabilities?: readonly string[];
     /** Lowest `dvm` SemVer accepted by this endpoint. */
     readonly minimumClientVersion?: string;
 }
-/** Factory for compatibility middleware attached to one custom route. */
 type ClientCompatibilityGate = (requirement: ClientCompatibilityRequirement) => MiddlewareHandler<ClientCompatibilityEnv>;
-/** Hono variables installed by the SDK compatibility middleware. */
 interface ClientCompatibilityEnv {
     Variables: {
         clientCompatibility?: ClientCompatibility;
@@ -737,35 +696,20 @@ declare function parseClientCapabilities(value: string): readonly string[] | und
 declare function clientCompatibilityAttributes(compatibility: ClientCompatibility): Record<string, unknown>;
 /** Parse request metadata and advertise the server protocol version on every response. */
 declare function clientCompatibilityMiddleware(): MiddlewareHandler<ClientCompatibilityEnv>;
-/** Build pre-handler enforcement middleware for one endpoint declaration. */
 declare const requireClientCompatibility: ClientCompatibilityGate;
-/** Render the normal structured HTTP 426 compatibility error. */
 declare function clientUpgradeRequired(c: Context, compatibility: ClientCompatibility, requirement: ClientCompatibilityRequirement): Response;
 
-/**
- * Algorithm: recursively sort object keys lexicographically (UTF-16 code-unit
- * order — JavaScript's default), then JSON.stringify with no whitespace.
- * Arrays preserve order.
- */
-/** Any JSON-serialisable value accepted by `canonicalize`. */
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /**
- * Serialise `value` to its canonical JSON form (sorted keys, no whitespace).
- *
- * `undefined` properties on objects are silently omitted (mirroring
- * `JSON.stringify`), so callers don't need to explicitly delete optional fields
- * that weren't set. Throws `TypeError` for unsupported scalar types (functions,
- * symbols, non-finite numbers). The caller is responsible for stripping fields
- * that shouldn't appear in the signed payload (e.g. `signature` itself).
+ * Object keys sort recursively in UTF-16 code-unit order; arrays preserve order.
+ * Undefined object properties are omitted. Unsupported scalars, including
+ * non-finite numbers, throw TypeError. Callers strip unsigned fields themselves.
  */
 declare function canonicalize(value: JsonValue): string;
 /**
- * Canonicalise `value` and return the UTF-8 bytes the signer should produce a
- * signature over. Both the cast client signer (`signAddEpisode`) and the
- * server verifier (`verifyCanonicalSignedRequest`) call this — sharing the function
- * guarantees byte-identical input on both sides.
+ * UTF-8 encoding of the canonical JSON form.
  */
 declare function canonicaliseForSigning(value: JsonValue): Uint8Array;
 
@@ -895,9 +839,8 @@ interface DrainReceipt {
     /** Amount reclaimed, micro-units of the credit's currency. */
     amount_micro: number;
     /**
-     * Credit balance immediately after the drain debit (micro-units) — the
-     * pending job holds at request time, fixed when the drain was recorded.
-     * Every event's receipt attests this same figure.
+     * Credit balance left after the drain debit, in micro-units. It includes
+     * pending job holds at request time and is fixed across this drain's event receipts.
      */
     balance_after_micro: number;
     /** Per-credit monotonic sequence the drain consumed, shared with draws. */
@@ -965,13 +908,6 @@ type UnsignedFundingReceipt = Omit<FundingReceipt, "signature">;
  * issuer does the same (`resultHashFor` in `sdk/server/receipt-issuer.ts`).
  */
 declare function computeResultHash(summary: string | undefined, artifactContents: JsonValue[]): string;
-/**
- * Sign an unsigned receipt with the DVM's receipt secret, returning the
- * complete receipt. Signs `canonicaliseForSigning(receipt)` — the same
- * sorted-key canonical JSON the caller-auth envelope and the builder
- * attestation use, so {@link verifyReceipt} is symmetric with
- * `verifyCanonicalSignedRequest`. There is no second canonicalisation.
- */
 declare function signReceipt(unsigned: UnsignedJobReceipt, secretHex: string): JobReceipt;
 /**
  * Verify a receipt's self-consistency: the BIP-340 signature over the
@@ -1155,43 +1091,41 @@ declare function isInKindDepletion(depletion: LotDepletion, amountMicro: number)
 /** The rails a payout lands on. Lightning never pays out: credits fund straight into the receive wallet. */
 type PayoutRail = "cashu" | "x402" | "tempo";
 /**
- * What gathered the payments into one transfer: a cashu accumulator melt, an
- * x402 batch settle to `pay_to`, a Tempo channel's cooperative close, or a
- * Tempo channel's scheduled / manual settlement to the recipient.
+ * Transfers aggregate payments: a Cashu melt, x402 batch to pay_to, or Tempo recipient
+ * settlement/close.
  */
 type PayoutKind = "melt" | "batch" | "close" | "settle";
-/** Which repair verb completed a stuck movement. Only `tempo_close_reconciled` is produced here today. */
 type PayoutRepairKind = "x402_settlement_reconciled" | "lightning_invoice_reconciled" | "tempo_close_reconciled";
 /**
- * JSON wire shape POSTed to the platform's `/_internal/payout` endpoint —
- * one landed movement into the builder's custody. Idempotent platform-side
- * on `(dvmId, payoutId)`, so the durable retry loop can redeliver freely; a
- * `repaired` redelivery of an id that already landed upgrades that row rather
- * than adding a second.
+ * One landed movement into builder custody. Platform retries deduplicate by (dvmId,
+ * payoutId); repaired redelivery upgrades that movement rather than adding another.
  */
 interface PayoutReportPayload {
-    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    /**
+     * Platform record ID; must match the bearer token’s DVM.
+     */
     dvmId: string;
     /** Required. The DVM's own id for the movement — `cashu:melt:<quote>`, `x402:batch:<uuid>`, `tempo:<tx>`. */
     payoutId: string;
     rail: PayoutRail;
     kind: PayoutKind;
-    /** Required. Rail-native atomic units: sats, or USDC micro. Always > 0. */
+    /**
+     * Positive rail-native atomic units: sats or USDC micro.
+     */
     nativeAmount: number;
-    /** Required. `sats` for cashu, `usdc` for the stablecoin rails. */
     nativeAsset: "sats" | "usdc";
     /** Where it landed; `null` for a melt, whose Lightning destination the platform never records. */
     recipient: string | null;
-    /** Mechanism references — mint, melt quote, tx hash, batch id, voucher count, channel id. Description material, never arithmetic. */
+    /**
+     * Descriptive mechanism references, never an arithmetic basis.
+     */
     refs: Record<string, unknown>;
     /** Required. When the money landed (epoch ms). */
     landedAt: number;
-    /** Set when a repair verb completed this movement. */
     repaired?: boolean;
     /** Required iff `repaired`. */
     repairKind?: PayoutRepairKind;
 }
-/** A stuck movement inside a pending snapshot. */
 interface PayoutWedge {
     id: string;
     /**
@@ -1211,17 +1145,14 @@ interface PayoutWedge {
     /** Rail-native amount held up, when known. */
     native?: number;
 }
-/** One pool inside a rail's pending figure — a mint, a batch, a channel. */
 interface PayoutPool {
     id: string;
     native: number;
     label?: string;
 }
 /**
- * JSON wire shape POSTed to the platform's `/_internal/payout-pending`
- * endpoint — one rail's snapshot of money still moving toward the builder,
- * replaced on each report. Best-effort: a lost one is superseded by the next
- * tick, so it rides no durable queue.
+ * A replaceable snapshot of one rail’s pending builder funds. Best-effort delivery uses no
+ * durable queue; a later tick supersedes a lost report.
  */
 interface PayoutPendingPayload {
     dvmId: string;
@@ -1229,14 +1160,12 @@ interface PayoutPendingPayload {
     /** Everything on this rail still moving toward the builder, in atomic units. */
     poolNative: number;
     nativeAsset: "sats" | "usdc";
-    /** How many pools the figure is made of. */
     items: number;
     pools: PayoutPool[];
     wedged: PayoutWedge[];
     /** This DVM's clock when the snapshot was taken (epoch ms). */
     snapshotAt: number;
 }
-/** The delivery seam — implemented by `RevenueReporter`, stubbed in tests. */
 interface PayoutTransport {
     /**
      * Queue a payout through the caller's open transaction, so the row and the
@@ -1253,19 +1182,13 @@ interface PayoutTransport {
     drainPending?(): Promise<void>;
 }
 /**
- * A money-path hook whose report must commit with the fact it describes.
- * `enqueue` runs inside the caller's transaction, and a throw rolls the fact
- * back with it — the drain report's own discipline: a call the
- * caller has to repeat costs a round trip, where a landed movement with no
- * row understates paid-out forever. `committed` runs once that transaction
- * has committed, for the delivery and the snapshot that must not read
- * uncommitted state.
+ * enqueue joins the money transaction and must throw on failure so its fact rolls back.
+ * committed runs after commit, when delivery and snapshots can safely read the new state.
  */
 interface TransactionalPayoutHook<E> {
     enqueue(event: E, tx: RevenueReporterQuerier): Promise<void>;
     committed(): void;
 }
-/** What `/admin/cashu/mark-melted` knows once the rows are marked. */
 interface CashuMeltCompleted {
     rows: {
         id: string;
@@ -1275,7 +1198,6 @@ interface CashuMeltCompleted {
     meltQuoteId: string;
     paymentPreimage: string;
 }
-/** What mppx reports after a Tempo channel settlement or close confirmed on chain. */
 interface TempoSessionSettled {
     txHash: string;
     channelId: string;
@@ -1285,27 +1207,23 @@ interface TempoSessionSettled {
     /** Newly settled to the payee by this transaction, atomic units. */
     delta: bigint;
 }
-/** What `reconcile-tempo-drain` re-read from the close receipt it booked against. */
 interface TempoCloseReconciled {
     channelId: string;
     txHash: string;
     /** Captured by the payee — this DVM — per the receipt, atomic units as a decimal string. */
     settledToPayee: string;
 }
-/** The channel view the tracker sums claims over. */
 interface X402TrackedChannel {
     channelId: string;
     chargedCumulativeAmount: string;
     totalClaimed: string;
 }
-/** A refund settlement wedged between chain and ledger, for the wedge list. */
 interface X402WedgedRefund {
     settlementId: string;
     /** Epoch ms the settlement was first prepared. */
     createdAt: number;
     native?: number;
 }
-/** What the batch-settlement server hands the tracker once it knows its scope. */
 interface X402PayoutContext {
     /** `${network}|${payTo}|${token}` — the scope the settle-pending marker is keyed on. */
     scope: string;
@@ -1318,7 +1236,6 @@ interface X402PayoutContext {
     settleIntervalMs: number;
     listWedgedRefunds?: () => Promise<X402WedgedRefund[]>;
 }
-/** The two manager verbs the tracker wraps. */
 interface X402TrackedManager {
     claim(...args: never[]): Promise<{
         vouchers: number;
@@ -1341,9 +1258,7 @@ interface X402PayoutObserver {
     /** A settle attempt that failed outside the tracked manager. One call per attempt a builder would count as one. */
     recordSettleFailure(error: unknown): Promise<void>;
 }
-/** The Tempo readers the host attaches after mounting. */
 interface TempoPayoutReader {
-    /** The recipient address every Tempo payout names. */
     recipient?: string;
     /** CAIP-2 network for the refs, when known. */
     network?: string;
@@ -1363,11 +1278,8 @@ interface TempoPayoutReader {
     }) => Promise<CreditDrainRecord[]>;
 }
 /**
- * The claims gathered since the last settle — the batch the next settle pays
- * out. Durable across machines because claims run under the fleet lock on
- * whichever machine won the tick, and the settle that finally moves the money
- * may run on another: an in-process figure would report a partial amount
- * after any restart in between.
+ * Claims accumulated since the last settle. The batch is durable across machines: claims and
+ * eventual settlement can run on different hosts under the fleet lock.
  */
 interface X402OpenBatch {
     scope: string;
@@ -1381,55 +1293,39 @@ interface X402OpenBatch {
     lastError: string | null;
     nextRetryAt: number | null;
 }
-/** Where the open batch lives — Postgres beside the settlement rows, or memory in dev. */
 interface X402BatchStore {
     get(scope: string): Promise<X402OpenBatch | undefined>;
     put(batch: X402OpenBatch): Promise<void>;
     delete(scope: string): Promise<void>;
     /**
-     * Close the open batch and run `enqueue` in the same transaction, so the
-     * payout row is queued exactly when the batch is gone and never otherwise:
-     * a settle can never lose its payout, because a failed enqueue leaves the
-     * batch open for the next settle to report in full. `false` when the batch
-     * under `scope` is no longer `batchId` — a sibling settled it first — in
-     * which case nothing is queued.
+     * Atomically delete the matching batch and enqueue its payout. Failed enqueue preserves the
+     * batch for retry; false means the scope no longer holds batchId and nothing was queued.
      */
     settle(scope: string, batchId: string, enqueue: (tx?: RevenueReporterQuerier) => Promise<void>): Promise<boolean>;
 }
-/** Construction options for {@link PayoutReporter}. */
 interface PayoutReporterOpts {
-    /** Platform DVM record ID, bound into every report. */
     dvmId: string;
     transport: PayoutTransport;
     /**
-     * The SDK's Postgres. Reads the cashu accumulator for the pending pool and
-     * holds the open x402 batch; without it the batch lives in memory (dev) and
-     * no cashu snapshot is taken.
+     * Postgres holds durable x402 batches and supplies Cashu snapshots. Without it, the default
+     * batch store is memory and Cashu snapshots are omitted.
      */
     db?: Pool;
     /**
-     * Whether this DVM runs the cashu accumulator. The cashu snapshot reads
-     * `wallet_accumulator`, which only that mode creates — on any other DVM the
-     * read would fail every tick and warn about a rail it does not carry.
+     * Only accumulator hosts create wallet_accumulator; enabling this on another host makes
+     * each snapshot query fail.
      */
     cashu?: boolean;
     /** Override the batch store (tests); defaults to Postgres on `db`, memory without. */
     batchStore?: X402BatchStore;
     /** Snapshot cadence, ms. Default 5 minutes. */
     snapshotIntervalMs?: number;
-    /** Override for the current time (tests). */
     now?: () => number;
 }
 /**
- * Builds the payout and pending reports from the SDK's money paths and hands
- * them to the transport.
- *
- * Two entry points are transactional: `cashuMelted` and `tempoCloseReconciled`
- * queue their row inside the caller's transaction and throw when they cannot,
- * so the melt or the reconciled close rolls back with its missing report rather
- * than landing without one. The x402 settle and the pending snapshots are
- * fail-safe instead: a report that cannot be built or queued there is logged and
- * picked up on the next tick, never thrown into the settle that produced it.
+ * Cashu melts and repaired Tempo closes enqueue inside their caller’s transaction and
+ * propagate failures. x402 reporting and pending snapshots instead log failures; failed x402
+ * enqueue preserves the open batch for retry.
  */
 declare class PayoutReporter implements PayoutTransport {
     private readonly dvmId;
@@ -1446,7 +1342,6 @@ declare class PayoutReporter implements PayoutTransport {
     private timer;
     private warmup;
     constructor(opts: PayoutReporterOpts);
-    /** Boot DDL for the durable batch store, when this reporter owns one. */
     init(): Promise<void>;
     /**
      * Start the snapshot loop. Unref'd, so it never keeps a scale-to-zero
@@ -1460,23 +1355,13 @@ declare class PayoutReporter implements PayoutTransport {
     reportPayoutPending(payload: PayoutPendingPayload): Promise<void>;
     /** Deliver what is queued now; a transport without the seam waits for its retry loop. */
     flush(): Promise<void>;
-    /** The hook `mark-melted` runs inside its transaction: the mark and its payout commit together. */
     meltHook(): TransactionalPayoutHook<CashuMeltCompleted>;
     /**
-     * A melt completed: the accumulator rows are SPENT at the mint and the
-     * Lightning payment reached the builder's destination. One payout per mint
-     * in the call — a `mark-melted` normally names one, since a melt quote
-     * belongs to one mint. The amount is the face value melted; the mint's fee
-     * and the Lightning amount received are builder-machine facts this DVM does
-     * not see.
-     *
-     * Queued through `tx` when the caller is inside the transaction that marks
-     * the rows, and a failure is thrown rather than swallowed so that mark rolls
-     * back with it — see {@link TransactionalPayoutHook}. Without `tx` the rows
-     * are queued on their own and delivered at once.
+     * Report melted face value per mint, not the Lightning amount received after fees. Hash the
+     * payment preimage; do not publish it. With tx, propagate enqueue failures and defer
+     * delivery until commit. Without tx, enqueue independently and start delivery.
      */
     cashuMelted(event: CashuMeltCompleted, tx?: RevenueReporterQuerier): Promise<void>;
-    /** The host attaches the session store and ledger readers once they exist. */
     attachTempo(reader: TempoPayoutReader): void;
     /**
      * A Tempo channel settled or closed on chain. `delta` is what this
@@ -1484,29 +1369,18 @@ declare class PayoutReporter implements PayoutTransport {
      * (a close of a fully settled channel) is no payout.
      */
     tempoSettled(event: TempoSessionSettled): Promise<void>;
-    /** The hook `reconcile-tempo-drain` runs inside its transaction: the booking and its payout commit together. */
     tempoRepairHook(): TransactionalPayoutHook<TempoCloseReconciled>;
     /**
-     * The operator repaired a wedged cooperative close. The close's
-     * payee side landed on chain when the close did; if the live hook reported
-     * it, this upgrades that row to `repair`, otherwise it is the row. The
-     * figure is the receipt's payee total for the channel.
-     *
-     * Queued through `tx` when the caller is inside the transaction that books
-     * the drain, and thrown rather than swallowed so that booking rolls back
-     * with it — see {@link TransactionalPayoutHook}.
+     * Report the receipt’s payee total under the live close’s transaction ID, flagged repaired.
+     * The platform upgrades a live row if one exists. Join tx and propagate enqueue failures;
+     * this does not report the caller refund.
      */
     tempoCloseReconciled(event: TempoCloseReconciled, tx?: RevenueReporterQuerier): Promise<void>;
-    /** The observer the batch-settlement server attaches to and routes its manager through. */
     x402Observer(): X402PayoutObserver;
     /**
-     * Wrap the upstream channel manager so every claim grows the open batch and
-     * every settle closes it. The claim delta is read off storage rather than
-     * off upstream's result, which carries only a voucher count; under the
-     * fleet lock the before/after read is consistent. A channel the claim
-     * removed on its way through — a refund's claim-then-delete —
-     * moved whatever it still owed before it went, and that value reaches
-     * `pay_to` in this batch too, so it counts at its pre-claim figure.
+     * Read claim deltas from storage because upstream returns voucher counts. Under the fleet
+     * lock, before/after reads are consistent. A deleted channel contributes its pre-claim
+     * unclaimed value, including refund claim-then-delete.
      */
     private trackX402Manager;
     private recordX402Claim;
@@ -1540,28 +1414,28 @@ declare class PayoutReporter implements PayoutTransport {
  * and stored in `pending_dvm_reports.payload` for durable retry.
  */
 interface RevenueReportPayload {
-    /** Required. Platform DVM record ID (`dvms.id`). Identifies which DVM earned the revenue. */
+    /** Platform DVM record ID (`dvms.id`). Identifies which DVM earned the revenue. */
     dvmId: string;
-    /** Required. Job identifier used by the platform to de-duplicate revenue rows and link to the job record. */
+    /** Job identifier used by the platform to de-duplicate revenue rows and link to the job record. */
     jobId: string;
     /**
-     * Optional. Capability selected by dispatch for this job. Omitted for
+     * Capability selected by dispatch for this job. Omitted for
      * reports from older SDKs and legacy persisted jobs that predate capability
      * dispatch; absence must not be rewritten as a capability name.
      */
     capability?: string;
-    /** Required. Total amount paid by the caller in millisatoshis, across all credits that satisfied the job. */
+    /** Total amount paid by the caller in millisatoshis, across all credits that satisfied the job. */
     paidMsats: number;
-    /** Optional. Cashu mint URL from which the payment tokens were issued. Set only for the `cashu` rail; omitted for all other rails. */
+    /** Cashu mint URL from which the payment tokens were issued. Set only for the `cashu` rail; omitted for all other rails. */
     paymentMint?: string;
     /**
-     * Required. Payment rail identifier (`"cashu"`, `"tempo"`, `"x402"`, `"stripe"`).
+     * Payment rail identifier (`"cashu"`, `"tempo"`, `"x402"`, `"stripe"`).
      * Mirrors `PaymentMethod` on the platform; carried as a plain string over the wire
      * so the SDK has no platform-type dependency.
      */
     rail: string;
     /**
-     * Optional. Settlement reference for the credit: EVM tx hash for `x402`, credential
+     * Settlement reference for the credit: EVM tx hash for `x402`, credential
      * challenge ID for `tempo`, `X-Cashu-Request-Id` UUID for `cashu`. Required by the
      * platform revenue ledger for `tempo`/`x402` rails (recordJobRevenue throws without it);
      * nullable for `cashu`.
@@ -1574,20 +1448,20 @@ interface RevenueReportPayload {
      */
     nativeAmount?: number;
     /**
-     * Optional. Asset tag paired with `nativeAmount`: `"sats"`, `"usdc"`, `"usdc.e"`, or
+     * Asset tag paired with `nativeAmount`: `"sats"`, `"usdc"`, `"usdc.e"`, or
      * `"usd-cents"`. Both fields must be present for the platform to write a non-cashu
      * revenue row.
      */
     nativeAsset?: string;
     /**
-     * Optional. Cashu flow discriminator. Set to `"p2pk_accumulator"` when the cashu
+     * Cashu flow discriminator. Set to `"p2pk_accumulator"` when the cashu
      * accumulator path satisfied the job; omitted for legacy cashu. Written into
      * `revenue_events.metadata.cashu_flow` by the platform so ops can split per-call cashu
      * rows by source.
      */
     cashuFlow?: string;
     /**
-     * Optional. What the job cost the **builder** to serve, as declared by the
+     * What the job cost the **builder** to serve, as declared by the
      * handler through `ctx.cost()` — the other half of the
      * margin the dashboard states. `amountMicro` is 1e-6 of `currency`, which
      * is the currency the builder incurred the cost in and need not be the
@@ -1609,28 +1483,28 @@ interface RevenueReportPayload {
         currency: string;
     };
     /**
-     * Optional. Credit this job's payment drew against. Present on
+     * Credit this job's payment drew against. Present on
      * every job a ledger-backed payment satisfied; its presence is what tells
      * the platform the row is a **draw-keyed** revenue event rather than a
      * pre-credits per-call one.
      */
     creditId?: string;
-    /** Optional. The draw this job settled — one draw, one revenue row. */
+    /** The draw this job settled — one draw, one revenue row. */
     drawId?: string;
-    /** Optional. The draw's fiat amount, 1e-6 of `creditCurrency`. The exact liability offset. */
+    /** The draw's fiat amount, 1e-6 of `creditCurrency`. The exact liability offset. */
     drawAmountMicro?: number;
-    /** Optional. Currency the credit is denominated in (lowercase ISO, e.g. `usd`). */
+    /** Currency the credit is denominated in (lowercase ISO, e.g. `usd`). */
     creditCurrency?: string;
     /**
-     * Optional. Settlement instant (epoch ms) — draws are revenue *when they
+     * Settlement instant (epoch ms) — draws are revenue *when they
      * settle*, so this dates the row. Omitted for pre-credits rows, which the
      * platform dates at record time as before.
      */
     settledAt?: number;
-    /** Optional. The funding's own rail reference, for reconciling a draw back to its deposit. */
+    /** The funding's own rail reference, for reconciling a draw back to its deposit. */
     fundingRef?: string;
     /**
-     * Optional. Revenue class when this row is not ordinary service revenue.
+     * Revenue class when this row is not ordinary service revenue.
      * `short_pay_forfeit` marks money kept from an underpayment that bought no
      * job so analytics can exclude it.
      */
@@ -1663,16 +1537,16 @@ interface JobTerminalReportPayload {
  * delivery order.
  */
 interface JobCostReportPayload {
-    /** Required. Platform DVM record ID (`dvms.id`); bound to the authenticating token. */
+    /** Platform DVM record ID (`dvms.id`); bound to the authenticating token. */
     dvmId: string;
-    /** Required. Job identifier and the report's platform-side idempotency key. */
+    /** Job identifier and the report's platform-side idempotency key. */
     jobId: string;
-    /** Optional. Capability selected by dispatch; absent only on legacy persisted jobs. */
+    /** Capability selected by dispatch; absent only on legacy persisted jobs. */
     capability?: string;
-    /** Required. Terminal outcome that explains why this event carries no revenue. */
+    /** Terminal outcome that explains why this event carries no revenue. */
     outcome: "completed" | "failed" | "cancelled";
     /**
-     * Required. Number of declarations incorporated into `cost`; the
+     * Number of declarations incorporated into `cost`; the
      * platform keeps the payload with the highest revision for this job.
      */
     costRevision: number;
@@ -1695,34 +1569,34 @@ interface JobCostReportPayload {
  * redeliver freely.
  */
 interface CreditDepositPayload {
-    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    /** Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
     dvmId: string;
     creditId: string;
-    /** Required. Canonical owner of the funded credit. */
+    /** Canonical owner of the funded credit. */
     callerPubkey: string;
-    /** Required. The rail's settlement reference — the deposit's idempotency key. */
+    /** The rail's settlement reference — the deposit's idempotency key. */
     fundingId: string;
     /** Payment rail (`"cashu"`, `"tempo"`, `"x402"`). */
     rail: string;
-    /** Required. Rail value received, in millisatoshis. */
+    /** Rail value received, in millisatoshis. */
     paidMsats: number;
     /** Cashu only. Full received proof face before its receiver input fee. */
     grossPaidMsats?: number;
     /** Cashu only. Standalone NUT-02 fee reserved by the received proofs. */
     cashuInputFeeMsats?: number;
-    /** Optional. Rail-native atomic units; omitted for cashu (derived from `paidMsats`). */
+    /** Rail-native atomic units; omitted for cashu (derived from `paidMsats`). */
     nativeAmount?: number;
-    /** Optional. Asset tag paired with `nativeAmount`. */
+    /** Asset tag paired with `nativeAmount`. */
     nativeAsset?: string;
-    /** Optional. Cashu mint URL the funding proofs were issued from. */
+    /** Cashu mint URL the funding proofs were issued from. */
     paymentMint?: string;
-    /** Required. Fiat micro credited to the ledger — the liability this deposit creates. */
+    /** Fiat micro credited to the ledger — the liability this deposit creates. */
     amountMicro: number;
-    /** Required. Currency `amountMicro` is 1e-6 of. */
+    /** Currency `amountMicro` is 1e-6 of. */
     creditCurrency: string;
-    /** Required. When the funding committed (epoch ms). */
+    /** When the funding committed (epoch ms). */
     fundedAt: number;
-    /** Required. Current credit expiry after this funding committed (epoch ms). */
+    /** Current credit expiry after this funding committed (epoch ms). */
     expiryMs: number;
     /**
      * Tempo session funding only: the TIP-1034 channel this deposit
@@ -1783,59 +1657,45 @@ interface CreditDepositPayload {
  * redeliver freely.
  */
 interface CreditDrawReleasePayload {
-    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    /** Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
     dvmId: string;
     creditId: string;
-    /** Required. Released draw; the platform idempotency key with DVM and credit. */
+    /** Released draw; the platform idempotency key with DVM and credit. */
     drawId: string;
-    /** Required. Fiat micro restored to availability. */
+    /** Fiat micro restored to availability. */
     amountMicro: number;
-    /** Required. Currency `amountMicro` is 1e-6 of. */
+    /** Currency `amountMicro` is 1e-6 of. */
     creditCurrency: string;
-    /** Required. Per-credit gap-free sequence assigned when the draw was placed. */
+    /** Per-credit gap-free sequence assigned when the draw was placed. */
     ledgerSeq: number;
-    /** Required. When the hold reached `released` (epoch ms). */
+    /** When the hold reached `released` (epoch ms). */
     releasedAt: number;
 }
 type CreditDrainRepairKind = "x402_settlement_reconciled" | "tempo_close_reconciled";
 /**
- * JSON wire shape POSTed to the platform's `/_internal/credit-drain`
- * endpoint. A drain is a **reclaim**: deposited money paid back to
- * the caller, which extinguishes the liability the funding created. Reported
- * so outstanding liability nets out to `deposited − drawn − drained`; never
- * summed into revenue, and never a revenue row — no job was sold.
- *
- * Reported only on the drain's **terminal** transition (`picked_up` for cashu,
- * `sent` for the other rails), because that is where the money has verifiably
- * left. `requested` and `parked` have not paid the caller yet.
- *
- * Idempotent on `(dvmId, creditId, drainId)`, so the shared retry loop can
- * redeliver freely.
- *
- * Fiat micro only, with no `paidMsats` sibling: `credit_drains` holds no rail
- * value (the sats figure is derived at read time from a live rate), so there
- * would be nothing truthful to put in one — and the liability arithmetic this
- * feeds is exact fiat micro on all three of its terms.
+ * Terminal picked_up/sent drains report reclaimed fiat micro-units, reducing
+ * outstanding liability rather than adding revenue. Requested or parked drains
+ * have not paid the caller. Idempotency key: (dvmId, creditId, drainId).
  */
 interface CreditDrainPayload {
-    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    /** Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
     dvmId: string;
     creditId: string;
-    /** Required. Canonical owner of the reclaimed credit. */
+    /** Canonical owner of the reclaimed credit. */
     callerPubkey: string;
-    /** Required. The drain's own idempotency key. */
+    /** The drain's own idempotency key. */
     drainId: string;
     /** Payout rail (`"cashu"`, `"x402"`, `"tempo"`). */
     method: string;
-    /** Required. Fiat micro reclaimed — the liability this drain extinguishes. */
+    /** Fiat micro reclaimed — the liability this drain extinguishes. */
     amountMicro: number;
-    /** Required. Currency `amountMicro` is 1e-6 of. */
+    /** Currency `amountMicro` is 1e-6 of. */
     creditCurrency: string;
     /** Terminal state: `"picked_up"` for cashu, `"sent"` for other rails. */
     status: string;
-    /** Required. When the money left (epoch ms). */
+    /** When the money left (epoch ms). */
     drainedAt: number;
-    /** Optional. Per-credit gap-free ledger sequence, for reconciling against the DVM's ledger. */
+    /** Per-credit gap-free ledger sequence, for reconciling against the DVM's ledger. */
     ledgerSeq?: number;
     /** Set when an operator repair verb completed this reclaim. */
     repaired?: boolean;
@@ -1893,21 +1753,21 @@ type CreditDrainEnqueue = (tx: RevenueReporterQuerier, payload: CreditDrainPaylo
  * redeliver freely.
  */
 interface CreditExpiryReleasePayload {
-    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    /** Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
     dvmId: string;
     creditId: string;
-    /** Required. Per-expiry-episode key; the platform idempotency key with DVM and credit. */
+    /** Per-expiry-episode key; the platform idempotency key with DVM and credit. */
     releaseId: string;
     callerPubkey: string;
     /** Funding rail. `null` on a credit funded before the basis became mandatory. */
     rail: string | null;
-    /** Required. Fiat micro released — the liability this expiry extinguishes. */
+    /** Fiat micro released — the liability this expiry extinguishes. */
     amountMicro: number;
-    /** Required. Currency `amountMicro` is 1e-6 of. */
+    /** Currency `amountMicro` is 1e-6 of. */
     creditCurrency: string;
-    /** Required. When the credit's TTL ran out (epoch ms) — when the liability ended. */
+    /** When the credit's TTL ran out (epoch ms) — when the liability ended. */
     expiryMs: number;
-    /** Required. When the sweep observed the expiry (epoch ms). */
+    /** When the sweep observed the expiry (epoch ms). */
     releasedAt: number;
     /** Set only on the reversal report: when the revival funding landed (epoch ms). */
     reversedAt?: number | null;
@@ -1933,21 +1793,21 @@ type CreditExpiryReleaseEnqueue = (tx: RevenueReporterQuerier, payload: CreditEx
  * report degrades to log-only rather than blocking the sweep.
  */
 interface PaidJobDeathPayload {
-    /** Required. Platform DVM record ID (`dvms.id`). Bound to the authenticating token. */
+    /** Platform DVM record ID (`dvms.id`). Bound to the authenticating token. */
     dvmId: string;
     jobId: string;
     capability: string;
-    /** Required. Amount of the released credit draw in millisatoshis. */
+    /** Amount of the released credit draw in millisatoshis. */
     paidMsats: number;
     /** Payment rail of the released draw (`"cashu"`, `"tempo"`, `"x402"`). */
     rail: string;
     /** Reaper reason: dead worker or never-terminal idle job. */
     reason: string;
-    /** Optional. Rail-native released amount, paired with `nativeAsset`. */
+    /** Rail-native released amount, paired with `nativeAsset`. */
     nativeAmount?: number;
-    /** Optional. Asset tag for `nativeAmount` (`"sats"` / `"usdc"` / …). */
+    /** Asset tag for `nativeAmount` (`"sats"` / `"usdc"` / …). */
     nativeAsset?: string;
-    /** Optional. Cashu mint URL the credit draw's tokens were issued from. */
+    /** Cashu mint URL the credit draw's tokens were issued from. */
     paymentMint?: string;
 }
 type RevenueSkippedNoRailReason = "credit_rail_null" | "credit_rail_unrecognized" | "job_rail_missing" | "ledger_not_configured";
@@ -1959,16 +1819,16 @@ type RevenueSkippedNoRailReason = "credit_rail_null" | "credit_rail_unrecognized
  * and a failed alert must never block terminal handling or reconciliation.
  */
 interface RevenueSkippedNoRailPayload {
-    /** Required. Platform DVM record ID (`dvms.id`). Bound to the authenticating token. */
+    /** Platform DVM record ID (`dvms.id`). Bound to the authenticating token. */
     dvmId: string;
     jobId: string;
     creditId: string;
     drawId: string;
-    /** Required. Caller payment captured for the job, in millisatoshis. */
+    /** Caller payment captured for the job, in millisatoshis. */
     paidMsats: number;
-    /** Optional. Settled draw amount in 1e-6 of `creditCurrency`. */
+    /** Settled draw amount in 1e-6 of `creditCurrency`. */
     drawAmountMicro?: number;
-    /** Optional. Currency the draw amount is denominated in. */
+    /** Currency the draw amount is denominated in. */
     creditCurrency?: string;
     /** Credit funding rail as stored on the draw, or null for legacy rows. */
     creditRail: string | null;
@@ -2084,13 +1944,8 @@ declare class RevenueReporter {
     /** Join a released draw to the transaction that made the hold terminal. */
     enqueueCreditDrawRelease(tx: RevenueReporterQuerier, payload: CreditDrawReleasePayload): Promise<void>;
     /**
-     * Join a credit drain to the transaction that made it terminal.
-     *
-     * Same discipline as {@link enqueueDeposit} and the same reason: no network
-     * I/O here, only the durable queue row, written through `tx` so the report
-     * and the status CAS commit or roll back together. A drain whose row was
-     * lost between the two would overstate outstanding liability forever —
-     * the mirror image of a lost deposit.
+     * Await durable queue insertion through tx so the terminal drain and its
+     * report commit or roll back together; no network I/O here.
      */
     enqueueCreditDrain(tx: RevenueReporterQuerier, payload: CreditDrainPayload): Promise<void>;
     /**
@@ -2120,14 +1975,8 @@ declare class RevenueReporter {
      */
     reportPayoutPending(payload: PayoutPendingPayload): Promise<void>;
     /**
-     * Join a credit-expiry release — or the revival that reverses one — to the
-     * transaction that made it true.
-     *
-     * Same discipline as {@link enqueueCreditDrain}: no network I/O, only the
-     * durable queue row written through `tx`. A release whose row was lost after
-     * the sweep committed would understate committed value forever; a lost
-     * reversal would overstate it, which is the worse direction — the builder
-     * would see money as theirs that a revived credit can still buy work with.
+     * Await durable queue insertion through tx so expiry release or reversal and
+     * its report commit together. A missing reversal would overstate builder value.
      */
     enqueueCreditExpiryRelease(tx: RevenueReporterQuerier, payload: CreditExpiryReleasePayload): Promise<void>;
     /**
@@ -2259,7 +2108,6 @@ interface X402SettlementPage {
 interface X402RelaySubmissionLock {
     withRelaySubmissionLock<T>(key: string, operation: () => Promise<T>): Promise<T>;
 }
-/** Construction options for {@link PostgresX402ChannelStorage}. */
 interface X402ChannelStorageOpts {
     /**
      * Override the relay submission lock's wait ceiling, in milliseconds.
@@ -2360,7 +2208,6 @@ declare class PostgresX402ChannelStorage implements ChannelStorage {
     private readonly relayLockTimeoutMs;
     private readonly terminalizeUnbackedCredit?;
     constructor(pool: Pool, opts?: X402ChannelStorageOpts);
-    /** Create the durable channel table under the SDK-wide DDL lock. */
     init(): Promise<void>;
     /**
      * Read the fleet's durable "claimed funds are awaiting transfer" marker.
@@ -2492,7 +2339,6 @@ declare class PostgresX402ChannelStorage implements ChannelStorage {
      * to finish.
      */
     completeSettlement(settlementId: string, resolvedAtMs?: number): Promise<void>;
-    /** Load one channel snapshot. */
     get(channelId: string): Promise<Channel | undefined>;
     /** List all channel snapshots in stable channel-id order. */
     list(): Promise<Channel[]>;
@@ -2568,7 +2414,6 @@ declare class PostgresX402ChannelStorage implements ChannelStorage {
     private updateInTransaction;
 }
 
-/** Durable channel seam used to compose a settled draw with consumed Tempo value. */
 interface TempoSessionSettlementStore {
     withDrawPlacement<value>(channelId: string, operation: (tx: CreditLedgerQuerier, lifecycle: TempoSessionLifecycle$1) => Promise<value>, tx?: CreditLedgerQuerier): Promise<value>;
     withTerminalConsumption<value>(channelId: string, operation: (tx: CreditLedgerQuerier, lifecycle: TempoSessionLifecycle$1) => Promise<{
@@ -2577,7 +2422,6 @@ interface TempoSessionSettlementStore {
         consume: boolean;
     }>): Promise<value>;
 }
-/** Tempo channel state read while holding its durable row lock. */
 interface TempoSessionLifecycle$1 {
     finalized: boolean;
     closeRequestedAt: bigint;
@@ -2593,7 +2437,6 @@ interface TempoCreditLossEvidence {
     consumedNative: bigint;
     observedAt?: number;
 }
-/** Immutable audit record for one terminal, unbacked Tempo credit. */
 interface TempoCreditLoss {
     creditId: string;
     channelId: string;
@@ -2613,7 +2456,6 @@ interface X402CreditLossEvidence {
     totalClaimedNative: bigint;
     observedAt?: number;
 }
-/** Immutable audit record for one terminal, unbacked x402 credit. */
 interface X402CreditLoss {
     creditId: string;
     channelId: string;
@@ -2626,25 +2468,13 @@ interface X402CreditLoss {
     observedAt: number;
 }
 /**
- * Money-safe credit ledger — the SDK-owned settlement primitive required for
- * prepaid balances in production DVMs.
- * Two tables in the DVM's own Postgres (`credits`, `credit_draws`), two-phase
- * draws (`pending` at job-accept → `settled` on success / `released` on
- * failure), and a per-credit gap-free `ledger_seq` for the receipt evidence
- * chain (`ReceiptCredit` in `lib/receipt.ts`).
- *
- * Concurrency contract: **every write to `credit_draws` happens inside a
- * transaction that first takes `SELECT … FOR UPDATE` on the parent `credits`
- * row.** The pending-hold SUM that defines available balance is only stable
- * because of that lock — never add a `credit_draws` write path that skips it.
- * `ctx.store` / KV is prohibited for credit state: last-write-wins KV on a
- * multi-machine fleet loses money under concurrency (spec condition 2).
+ * Every write to credit_draws takes SELECT … FOR UPDATE on its parent credit within the same
+ * transaction. That lock keeps the pending-hold sum and available balance stable across
+ * machines; KV storage cannot provide this money boundary.
  *
- * Scope note: the ledger is host-wide, keyed only by `credit_id` /
- * `caller_pubkey`. A multi-mount host shares one ledger across its mounts —
- * same operator, same money destination, so not a money hazard; a `dvm_id`
- * column can be added by idempotent migration if per-mount ledgers are ever
- * needed.
+ * The ledger is host-wide: credit_id and caller_pubkey identify rows, without a per-mount
+ * dvm_id. Draws hold funds until settlement or release, and share a gap-free per-credit
+ * ledger_seq with drains.
  */
 declare class CreditLedger {
     private readonly pool;
@@ -2658,267 +2488,95 @@ declare class CreditLedger {
     private expiryReleaseOutbox?;
     constructor(pool: CreditLedgerPool, tempoSessionStore?: TempoSessionSettlementStore | undefined);
     /**
-     * Bind the durable x402 settlement state this ledger gates spending on
-     *
-     * Late, because the settlement store is built with the batch-settlement
-     * server, which is built *after* the ledger it reads earned draws from. An
-     * unbound ledger simply does not gate — correct for a DVM with no x402
-     * channel storage, where no settlement row can exist to wedge.
+     * Bound after construction because the settlement store shares this ledger and is
+     * initialized separately. Ledger effects and route preflights use the same refund gate.
      */
     useX402SettlementGate(gate: X402RefundSettlementGate): void;
     /**
-     * Bind the durable outbox that reports credit-expiry releases and their
-     * revivals to the platform.
-     *
-     * Held on the ledger rather than threaded through {@link fund} for the same
-     * reason as the gate above: the revival half fires from *every* funding path
-     * Cashu commit, x402 exact and channel, Tempo, the Lightning invoice
-     * settle, the implicit N=1 per-call payment — and a seam each of those has to
-     * remember to pass is a seam one of them will eventually forget.
-     *
-     * Unbound (a `dvmctl dev` server, a self-hosted builder, a test host) the
-     * sweep and the reversal still run and still write the ledger's own rows;
-     * only the platform report is skipped. Reporting is bookkeeping and must
-     * never gate the ledger.
+     * Expiry release and revival reports join the ledger transaction. A caller-owned funding
+     * transaction must not commit a reversal independently of its outbox row. Without this
+     * wiring, ledger transitions still run.
      */
     useCreditExpiryReleaseOutbox(outbox: CreditExpiryReleaseOutbox): void;
-    /** Create the `credits` / `credit_draws` tables if absent. Call once at SDK boot. */
     init(): Promise<void>;
-    /** The boot DDL itself — always runs under {@link withSdkInitLock}. */
     private createTables;
     /**
-     * Give every open non-channel Bitcoin credit a funding lot.
-     *
-     * Runs inside the boot DDL, is guarded per credit by `NOT EXISTS`, and is
-     * therefore both the one-time migration and a standing self-heal for a
-     * credit that somehow reaches a positive balance with no lot behind it.
-     *
-     * The lot is derived from `credits.msats_remaining`, not replayed out of
-     * `credit_fundings`. That is not a shortcut: `credit_fundings` records only
-     * `{amount_micro, rail}` — no instrument amount at all — and is not written
-     * on every funding path, whereas `msats_remaining` **is** the credit's
-     * current unspent rail value, maintained pro rata on every draw since
-     * One synthetic lot pairing it with `balance_micro` therefore
-     * reproduces today's in-kind position exactly, and FIFO over a single lot is
-     * trivially correct. Historic per-funding rates are unrecoverable and would
-     * change nothing: only the remaining position is owed.
-     *
-     * The semantics change is deliberately retroactive — every
-     * current holder is first-party, so there is one regime and no legacy
-     * branch.
+     * Backfill an open non-channel Bitcoin credit only when it has no funding lot. Pair
+     * balance_micro with current msats_remaining; credit_fundings lacks historical instrument
+     * amounts and does not cover every funding path. Historical per-funding rates cannot be
+     * recovered. Existing lots are left untouched, so this does not repair partial coverage
+     * gaps.
      */
     private backfillFundingLots;
     /**
-     * Create a credit, or top up an existing one (same `creditId`). Top-ups add
-     * to the balance and overwrite `expiry_ms` with the provided value — funding
-     * an expired credit revives it (the caller-ownership contract carry-forward: the credit is a
-     * rolling buffer, not per-job escrow). The existing row's `caller_pubkey`
-     * and `currency` must match or the fund is refused with a typed error —
-     * without that check a top-up against someone else's `credit_id` would
-     * silently merge two callers' money.
-     *
-     * Pass `tx` (a client inside a caller-owned `BEGIN`) to commit the rail
-     * receive and the ledger credit atomically (spec condition 3 — the
-     * verifier does this). The ledger issues **no** transaction control on `tx`.
-     *
-     * Without `tx` it opens one of its own, because a funding is no longer a
-     * single statement: it upserts the credit, records its funding lot
-     * and reverses any standing expiry release — and that
-     * last leg restores balance and queues a report. A crash between the upsert
-     * and the reversal would leave a revived credit whose release still stands,
-     * which the sweep's own exclusion then makes permanent: `balance_micro > 0`
-     * but a standing release means it is neither drainable nor re-releasable.
-     *
-     * `basis` records the rail value behind the fiat so each draw can
-     * be allocated its share of the rail-native amount actually received. A
-     * top-up on a different rail than the credit's is refused with
-     * `rail_mismatch`: sats and USDC microunits aren't summable, so a blended
-     * credit would have no coherent native basis to allocate from.
+     * Funding adds balance and overwrites expiry, reviving an expired credit. It is additive,
+     * not idempotent: the caller’s rail marker or funding record must prevent replay. Owner and
+     * currency must match; rail and reusable-channel bindings cannot be mixed with other
+     * instruments. A legacy NULL rail adopts its first typed top-up.
      *
-     * It is **required**, in the type and again at runtime via
-     * {@link assertFundingBasis}. A basis-less fund wrote `rail = NULL`, and a
-     * draw against such a credit settles — a real debit — while
-     * `railAsFundingMethod` correctly declines to guess a rail, so `bookRevenue`
-     * books nothing and outstanding liability (`deposits − draw revenue`) stays
-     * overstated by the drawn amount forever. `credits.rail` stays nullable
-     * because rows written before this change still exist in live databases:
-     * **write is closed, read is not.** A legacy row adopts a rail from its first
-     * typed top-up via the `COALESCE` below.
+     * With tx, all writes join the caller’s transaction without transaction control. Otherwise
+     * the ledger owns a transaction covering balance, funding lot, reversal of standing expiry
+     * releases and their reports. A partial revival would leave restored balance with a release
+     * still counted.
      *
-     * The rail-native **instrument** is pinned at first funding too, and both
-     * channel guards are symmetric for the same reason. A reusable
-     * channel — Tempo session or x402 batch-settlement — may only ever top up
-     * the credit it opened, and a credit opened by a one-shot (a Tempo charge, an
-     * x402 exact authorization) may never adopt one. The x402 half used to admit
-     * `credits.x402_channel_id IS NULL`, so a channel deposit bound itself to a
-     * credit already holding exact-funded value: `earnedNativeForX402Channel`
-     * then read that credit's whole settled-draw history as the channel's
-     * earnings, and the first claim tick swept a deposit nobody had consumed,
-     * while the unspent balance lost every exit (the drain's refund base goes
-     * below `totalClaimed`, and a channel-bound credit refuses every non-x402
-     * drain). `credits_x402_channel_uidx` does not cover this: it guards
-     * one-credit-per-channel, not one-source-per-credit.
-     *
-     * An x402 channel deposit is additionally refused `settlement_pending` while
-     * that channel carries an unresolved refund — see the gate read
-     * below. This method is the authority on that rule, as it is on the binding
-     * rules above; every door preflights it where a refusal is still free.
+     * An incoming x402 channel with an unresolved refund is refused before the upsert. That
+     * preflight is not atomic with a concurrent cooperative drain; see the incoming-channel
+     * gate below.
      */
     fund(args: CreditFundArgs): Promise<CreditSnapshot>;
-    /**
-     * The funding itself, on whichever handle {@link fund} chose. Every refusal
-     * it raises is the caller's to see unchanged; a self-opened transaction rolls
-     * back around it.
-     */
     private fundOn;
     /**
-     * Undo any expiry release this credit still carries, because a funding just
-     * landed on it (the revival rule), restoring the balance the
-     * release took.
-     *
-     * A release records the credit's **final** undrawn remainder and zeroes it
-     * (see {@link releaseExpiredCreditLocked}). Funding adds to the balance and
-     * overwrites `expiry_ms` (the caller-ownership contract carry-forward: the credit is a rolling
-     * buffer), so the moment money arrives the recorded remainder is no longer
-     * final: the release stops counting and its micro come back.
-     *
-     * Deliberately unconditional on the incoming expiry rather than gated on
-     * `expiryMs > nowMs`. A release exists only for a credit that had already
-     * lapsed, so any funding that reaches one is money the release did not
-     * account for — and a funding that arrives with an already-past expiry leaves
-     * a credit the very next sweep re-releases at its new, larger remainder. One
-     * rule, self-healing in both directions, and it never needs to read the
-     * pre-funding expiry the upsert has already overwritten.
+     * Funding reverses standing expiry releases, restores their released micro and queues
+     * reversal reports on the funding transaction. Do this even when the new expiry is already
+     * past: the next sweep must release the enlarged remainder as a new episode.
      *
-     * Runs on the funding's own handle — which {@link fund} now guarantees is a
-     * transaction — so the reversal, the restored balance and the report commit
-     * with the money or not at all. A reversal that committed without its report
-     * would be unrecoverable: `WHERE reversed_at IS NULL` means no later pass
-     * re-derives it.
-     *
-     * @returns the credit row as the restore left it, or undefined when there was
-     * nothing to reverse. The caller reads its snapshot off this rather than off
-     * the funding upsert's `RETURNING`, which predates the restore.
+     * Returns the row after restoration, or undefined when no release stood. The upsert’s
+     * RETURNING row predates the restoration and is not the final balance.
      */
     private reverseExpiryReleases;
     /**
-     * Release the undrawn remainder of every credit whose TTL has run out
-     * Returns the releases this pass recorded.
-     *
-     * **What is released.** The credit's whole `balance_micro`. Expiry ends
-     * spending but never ownership of the record, so the balance stays readable;
-     * what ends is the caller's claim on it, and on the prepaid rails the value
-     * behind it is already in builder custody.
-     *
-     * **Tempo is excluded**, at both of its markers (`tempo_channel_id` and a
-     * `tempo` rail). A Tempo credit is channel-backed and its undrawn value
-     * returns to the *caller* at channel exit, so releasing it would book the
-     * builder money the chain is about to hand back.
-     *
-     * **A credit with a pending hold is skipped, not partially released.** A draw
-     * placed before expiry stays settleable afterwards (`draw`'s replay lookup
-     * runs above the expiry check, so a lost response is still recoverable), so
-     * the remainder is not final while a hold is outstanding. Skipping costs one
-     * sweep interval and keeps the released figure exactly "what nothing bought";
-     * holds do resolve — the orphan-draw watchdog is what guarantees
-     * a stranded one still reaches a terminal state.
-     *
-     * **Idempotent** two ways. `release_id` is derived from the expiry instant,
-     * so a re-sweep after a crash between the insert and its report collides on
-     * the same primary key instead of writing a second row; and the candidate
-     * scan excludes any credit that already has an un-reversed release.
+     * Release expired undrawn balances, retaining readable credit records. Tempo rail or
+     * channel-backed credits are excluded because their collateral returns to the caller
+     * through the channel lifecycle.
      *
-     * Each candidate is re-checked under the credit row lock every
-     * `credit_draws` write is taken under, so a draw racing the sweep either
-     * loses the race (its credit is already released and it would have been
-     * refused `credit_expired` anyway) or wins it and leaves a pending hold the
-     * locked re-check sees.
+     * Pending holds prevent release: jobs accepted before expiry may still settle or release.
+     * Candidates are rechecked under the same parent-credit lock used by draw writes. The
+     * balance debit, episode record and report commit together; standing releases exclude
+     * repeat work. A later revival may reuse the expiry instant but receives a new release
+     * sequence.
      */
     sweepExpiredCredits(args?: {
         nowMs?: number;
-        /** Credits released per pass. Bounds the work a long-idle DVM does at boot. */
         limit?: number;
     }): Promise<{
         released: CreditExpiryRelease[];
     }>;
     /**
-     * Write one credit's expiry release under its row lock, zero the balance it
-     * released, and re-assert every condition the unlocked candidate scan tested.
-     * Returns undefined when the credit no longer qualifies — funded, drawn
-     * against, or already released between the scan and the lock.
+     * Recheck eligibility under the credit lock and zero the released balance in the same
+     * transaction as its episode/report. Otherwise requestDrain, which intentionally ignores
+     * expiry, could reclaim value already released to the builder.
      *
-     * **Zeroing the balance is what makes the release real**, and it is the whole
-     * reason this runs under the lock rather than as a bare INSERT. The row alone
-     * records that the caller's claim ended; it does not *end* it. `requestDrain`
-     * has no expiry check by design (expiry gates new draws, not reclaims), so a
-     * credit whose remainder had been released and reported was still fully
-     * drainable: the DVM would pay out money the platform had already booked as
-     * the builder's, and `deposited - drawn - drained - released` would go
-     * negative on the same micro. With the balance at zero, `requestDrain`'s
-     * existing `availableMicro <= 0` guard refuses with `nothing_to_drain` and no
-     * new check is needed anywhere. {@link reverseExpiryReleases} puts the
-     * balance back when a funding revives the credit.
-     *
-     * `status` deliberately stays `active`: a released credit must remain
-     * fundable, or the revival rule has nothing to revive.
-     *
-     * The zeroed balance also takes the credit out of `BITCOIN_CREDIT_PREDICATE`
-     * (`balance_micro > 0`), so the in-kind sweep floor stops counting sats the
-     * builder no longer owes back — and counts them again after a revival, with
-     * the credit's funding lots untouched throughout.
+     * Keep status active so future funding can revive it. Funding lots remain intact: balance
+     * zero excludes this credit from Bitcoin liability, and reversal restores that liability.
      */
     private releaseExpiredCreditLocked;
     /**
-     * Record this funding's in-kind basis as a lot.
-     *
-     * Called from inside {@link fund}, on the same handle, so the lot shares
-     * whatever transaction the rail opened — `withCommitTx` for Cashu,
-     * `ProcessedPaymentStore.withTx` for x402/Tempo, `settleInvoice`'s own
-     * `BEGIN` for Lightning. The funding-atomicity invariant therefore extends
-     * to it structurally rather than by every call site remembering: a lot
-     * cannot exist without its ledger credit, or the credit without its lot.
-     *
-     * Only a **channel-backed** credit writes no lot: it is in-kind already —
-     * the escrow itself retains the unused value — so a lot on one would be
-     * counted as Bitcoin deposit liability the hub does not hold.
-     *
-     * Every other non-channel Bitcoin funding writes one, the implicit N=1
-     * per-call payment included. That one funds and draws the same amount in
-     * this transaction, so it looks like a lot born depleted — but the draw is a
-     * *pending hold*, not a debit, and only a `completed` job settles it
-     * (`JobManager.settlesDraw`). A failed, cancelled or stale-swept job
-     * releases the hold and the whole funded amount becomes reclaimable balance,
-     * so suppressing the lot here would leave routine traffic reclaiming off a
-     * live rate and missing from the sweep floor. One small insert on the hot
-     * path buys the invariant the liability read depends on: open lots cover
-     * `balance_micro` for every Bitcoin credit, always.
+     * Record non-channel Bitcoin funding lots on the funding transaction. An implicit payment
+     * also needs a lot: its draw is initially only a hold, and failure releases the whole
+     * balance for reclaim. Channel collateral is excluded from Bitcoin lots.
      *
-     * A zero-sats basis still writes a lot. It is honest — the credit exists and
-     * we know its rail — and it is what makes "covered but unbacked" a
-     * distinguishable state from "no lot at all" for the reclaim and the
-     * liability rollup, instead of both reading as a gap.
+     * A zero-sats basis still records a lot, distinguishing covered but basisless credit from a
+     * missing-lot coverage gap.
      */
     private recordFundingLot;
     /**
-     * Place a two-phase `pending` hold of `amountMicro` against the credit and
-     * assign the next `ledger_seq`. Idempotent on `(creditId, drawId)`: a replay
-     * returns the original `{balanceAfterMicro, ledgerSeq}` with
-     * `replayed: true` and places no second hold — this is how a caller recovers
-     * a lost response (spec condition 1). A replay whose `amountMicro` or
-     * `jobId` differs from the recorded draw is not a replay but a money bug in
-     * the caller, refused with `draw_conflict`.
+     * Place a pending hold with the next shared per-credit sequence. A matching (creditId,
+     * drawId) replay returns its recorded tuple without another hold; conflicting amount or
+     * jobId is draw_conflict.
      *
-     * The replay lookup runs **before** the expiry check, deliberately: a draw
-     * placed pre-expiry must stay recoverable after the credit expires, or the
-     * DVM holds a debit the caller can never reconcile. Fresh draws on an
-     * expired credit are refused with `credit_expired`; the balance stays
-     * intact and readable (the caller-ownership contract: expiry ends spending, never ownership).
-     *
-     * Pass `tx` (a client inside a caller-owned `BEGIN`) to place the hold in
-     * the same transaction as the rail commit and the `fund` upsert (spec
-     * condition 3 — the implicit N=1 path). The ledger issues no
-     * transaction control on `tx`; the `SELECT … FOR UPDATE` row lock is still
-     * taken on the caller's transaction, so the locking invariant holds.
+     * Replay precedes expiry and settlement gates so a lost response stays recoverable. Fresh
+     * draws require spendable credit. With tx, take the parent-credit lock on the caller’s
+     * transaction without issuing transaction control.
      */
     draw(args: {
         creditId: string;
@@ -2931,63 +2589,23 @@ declare class CreditLedger {
         nowMs?: number;
     }): Promise<DrawResult>;
     /**
-     * The unresolved refund on `channelId` that must stop this ledger effect, if
-     * any.
-     *
-     * `undefined` whenever there is nothing to ask — an unbound credit, or a DVM
-     * with no durable settlement store, where a settlement row cannot exist.
-     *
-     * Public since the behavior was introduced, so `/v1/credit`'s pre-payment preflight can ask the
-     * same question `fund` will ask from inside the rail transaction — one read,
-     * one answer, rather than a second copy of the rule in the routes.
+     * Return the unresolved refund that blocks an effect on this channel, or undefined. Route
+     * preflights use the same rule before moving money; draw and drain also read it under the
+     * credit lock.
      */
     blockingX402Refund(channelId: string | null | undefined, statuses: X402SettlementStatus[]): Promise<X402UnresolvedRefund | undefined>;
     /**
-     * Grow a pending draw by `addAmountMicro` — the ledger half of a
-     * mid-job `requestPayment` top-up. One job keeps **one** draw: the mid-job
-     * money funds the same credit and enlarges the hold the upfront leg placed,
-     * so the receipt's `ReceiptCredit` block countersigns the job's full cost
-     * and `revenue_events` still books exactly one row per job.
-     *
-     * `draw()` cannot express this: a same-`draw_id` call with a different
-     * amount is `draw_conflict` by design (a replayed draw must never re-price).
+     * Grow an accepted job’s pending hold while preserving its original ledger_seq. The balance
+     * tuple is updated at that sequence, so interleaved draws need not form a monotonic balance
+     * trajectory. No expiry check applies to an already accepted job.
      *
-     * The arithmetic is `draw()`'s, unchanged: `addAmountMicro` is checked
-     * against — and `balance_after_micro` recomputed from — the balance net of
-     * **every** pending hold, this draw's own included. That is deliberately the
-     * conservative reading (a fresh draw of `addAmountMicro` would see exactly
-     * the same figure), and it is what keeps the total held after growth inside
-     * the credit's balance.
+     * Available balance excludes every pending hold, including this one. An earmark allocates
+     * the incoming funding’s rail value; absent one, growth uses the pool.
      *
-     * The increment's rail value comes from {@link growthRailValue}: earmarked
-     * to the funding that backs it when the caller names one (the mid-job case),
-     * pro-rata otherwise. Either way the draws of a credit keep summing to
-     * precisely what the rails paid.
-     *
-     * **`ledger_seq` is not re-taken.** The per-credit sequence is gap-free
-     * (`credit_draws_seq_uidx`), so moving this draw forward would strand its
-     * original number. The consequence is deliberate and worth knowing: the
-     * recorded `balance_after_micro` is the post-growth figure stamped at the
-     * *original* seq, so a credit with interleaved sibling activity has a
-     * trajectory that is truthful per draw rather than monotonic across seqs.
-     *
-     * **No expiry check**, matching `settle`/`release`: the job was accepted
-     * pre-expiry and is still running. Refusing here would strand the handler
-     * mid-flight over a clock the caller can't influence.
-     *
-     * **Not idempotent by itself.** Growth carries no key of its own — it
-     * inherits the rail's (the accumulator's `(dvm_id, request_id)` UNIQUE rolls
-     * the whole transaction back on replay; x402/mpp collide on the
-     * `processed_payments` marker). Never call it outside a rail commit.
-     *
-     * **`capMicro` bounds cumulative growth at what the job cumulatively asked,**
-     * and it is the only ceiling that can refuse a top-up: the
-     * available-balance check cannot, because the `fund` a moment earlier in
-     * this same transaction raised the balance by exactly the amount being
-     * drawn. Excess is **granted partially or not at all rather than thrown** —
-     * this runs inside the rail commit, so a throw would roll back cashu proofs
-     * the caller already sent. The refused remainder stays funded balance the
-     * caller owns and can drain.
+     * Growth has no independent replay key: compose it with the rail’s replay protection in one
+     * transaction. capMicro bounds cumulative growth at the job’s cumulative ask. Excess
+     * remains caller-owned funded balance; partial or zero growth returns that excess rather
+     * than throwing and rolling back accepted proofs.
      */
     growDraw(args: {
         creditId: string;
@@ -3051,18 +2669,9 @@ declare class CreditLedger {
         nowMs?: number;
     }): Promise<DrawResolution>;
     /**
-     * Record a fund-only top-up under its client-generated `fundId`.
-     * The deposit half of the evidence chain, and the top-up path's idempotency
-     * key: `PRIMARY KEY (credit_id, fund_id)` means a concurrent duplicate
-     * loses with a typed `funding_replayed` rather than crediting twice.
-     *
-     * Call it inside the same `tx` as {@link fund} — the rail commit, the
-     * funding record, and the balance increment must land together or not at
-     * all (the funding-commitment rule). Like `fund`, this issues no transaction
-     * control on `tx`; it is a single statement.
-     *
-     * This does **not** move money on its own. `fund` still does the crediting;
-     * this row is what lets a retry be answered with the original outcome.
+     * Record the fund-only replay key without moving money. A duplicate (credit_id, fund_id)
+     * raises funding_replayed. Compose this insert, fund and rail acceptance on the same
+     * caller-owned transaction; a retry reads the recorded funding outcome.
      */
     recordFunding(args: {
         creditId: string;
@@ -3121,7 +2730,6 @@ declare class CreditLedger {
         expiresAt: number;
         nowMs?: number;
     }): Promise<CreditInvoiceRecord>;
-    /** Read one invoice (no lock). */
     getInvoice(args: {
         creditId: string;
         fundId: string;
@@ -3137,30 +2745,17 @@ declare class CreditLedger {
         limit: number;
     }): Promise<CreditInvoiceRecord[]>;
     /**
-     * Apply an observed Lightning settlement to the ledger — **the exactly-once
-     * boundary** (the funding-commitment rule for a rail whose commit happens
-     * off-box).
-     *
-     * One transaction covers the funding record, the balance, and the invoice's
-     * own status flip, so the three can never disagree. A crash anywhere inside
-     * leaves the invoice `pending` and the balance untouched: the next
-     * `lookup_invoice` observes the same settled payment and credits it, once.
-     * A replayed check after the commit sees `settled` and moves nothing.
-     *
-     * The lock is on the **invoice** row, not the credit row: the first
-     * Lightning top-up is what opens the credit, so there is frequently no
-     * `credits` row to take `FOR UPDATE` yet. That does not weaken the ledger's
-     * concurrency contract — no `credit_draws` write happens here, and `fund`'s
-     * upsert is a single statement — while still serialising two settlement
-     * checks racing on the same invoice.
+     * Serialize settlement on the invoice row, which exists before the first credit does.
+     * Funding record, balance, invoice status and optional deposit outbox commit together. An
+     * interrupted transaction leaves the prior invoice status intact for retry; a settled replay
+     * moves no money.
      */
     settleInvoice(args: {
         creditId: string;
         fundId: string;
         expiryMs: number;
         /**
-         * Rail-value basis, pinned when the invoice was issued. Required
-         * by — it is what `fund` writes to `credits.rail`.
+         * Funding rail value pinned when this invoice was issued.
          */
         basis: CreditFundingBasis;
         /**
@@ -3184,39 +2779,20 @@ declare class CreditLedger {
         fundId: string;
     }): Promise<CreditInvoiceRecord | undefined>;
     /**
-     * Retire an invoice that **was paid** and can never be credited.
-     *
-     * Distinct from `expired` because the money is the opposite way round: an
-     * expired invoice was never paid and owes nobody anything, whereas a blocked
-     * one has sats sitting in the builder's wallet with no ledger row to put them
-     * on. Only an operator can resolve that, so the row records `reason` and
-     * stops being swept — leaving it `pending` would spend one of the sweep's few
-     * slots re-deriving the same verdict on every request the caller makes, and
-     * three of them would wedge that caller's sweep so a genuinely payable
-     * invoice behind them never credits.
-     *
-     * A CAS on `pending`, like the expiry retirement: a settlement observed
-     * concurrently must win.
+     * Mark a paid invoice blocked when its payment cannot be credited. This removes it from the
+     * bounded pending sweep and leaves its reason for operator repair. The pending-only CAS
+     * cannot overwrite a committed settlement.
      */
     markInvoiceBlocked(args: {
         creditId: string;
         fundId: string;
         reason: string;
     }): Promise<CreditInvoiceRecord | undefined>;
-    /** Read one invoice by the wallet's own identifier for the payment (no lock). */
     getInvoiceByPaymentHash(paymentHash: string): Promise<CreditInvoiceRecord | undefined>;
     /**
-     * The operator's queue: invoices the sweep gave up on.
-     *
-     * **Keyset-paginated, not offset.** Blocked rows are terminal and never
-     * self-clear, so a row the operator declines to act on sits at the head of
-     * the age ordering forever; a fixed first page would starve everything
-     * behind it on every run, which is the shape one page up.
-     *
-     * `includeResolved` widens to the operator-resolved statuses so a run can be
-     * audited after the fact.
-     * Host-wide, like `listPendingDrains`: the ledger has no `dvm_id`, so on a
-     * multi-mount host one builder's admin credential reads every mount's rows.
+     * Host-wide operator queue, keyset-paginated so an untouched blocked row does not starve
+     * later rows. includeResolved also exposes reconciled and written-off history; the ledger
+     * has no per-mount dvm_id.
      */
     listBlockedInvoices(args: {
         limit: number;
@@ -3224,37 +2800,15 @@ declare class CreditLedger {
         includeResolved?: boolean;
     }): Promise<CreditInvoiceRecord[]>;
     /**
-     * Apply a blocked invoice's payment to a credit an operator named — the
-     * repair for the one Lightning outcome the DVM cannot fix itself.
-     *
-     * Shaped statement-for-statement on {@link settleInvoice}, because it is the
-     * same money doing the same thing a different way: one transaction covering
-     * the funding record, the balance, the invoice's status flip and the deposit
-     * outbox row, so the four can never disagree. Three deliberate differences:
+     * Apply a blocked or written-off invoice to an operator-named credit. Lock the invoice by
+     * its unique payment_hash before funding the credit, matching settlement’s
+     * invoice-to-credit lock order. Funding, balance, resolution and optional outbox share one
+     * transaction.
      *
-     * - **The lock is taken on `payment_hash`**, which is UNIQUE and is the
-     * identifier the operator actually holds (it is what the
-     * `lightning_settlement_blocked` log carries and what names the payment in
-     * their wallet). Invoice row first, credit row second via `fund`'s upsert —
-     * the same order `settleInvoice` takes, which is what keeps a reconcile and
-     * a concurrent settlement check from deadlocking against each other.
-     * - **The funding lands at `(targetCreditId, paymentHash)`, not the invoice's
-     * own `(credit_id, fund_id)`.** That key is frequently the reason the row
-     * is blocked at all — `funding_replayed_on_cashu` means something else
-     * already holds it — and the operator's most natural target is that very
-     * credit. The payment hash cannot collide with it, and it makes all three
-     * references to this payment agree: `basis.fundingRef`, the deposit's
-     * `funding_id`, and the funding row's `fund_id`.
-     * - **`written_off` is an accepted input status.** A write-off unwound
-     * nothing, so an operator who closed a row by mistake must not need raw SQL
-     * against a money table to reopen it.
-     *
-     * The invoice row's status — never the funding row — is the idempotency
-     * source of truth. `fund_id` is caller-chosen and the payment hash is
-     * disclosed to them, so a caller *can* squat `(theirCredit, thatHash)` with a
-     * top-up on another rail; when they have, `recordFunding` throws
-     * `funding_replayed` and that surfaces as its own loud failure rather than
-     * being absorbed as "already reconciled".
+     * The repair funding key is (targetCreditId, paymentHash), distinct from the original
+     * caller-chosen fundId. Invoice status determines replay. A caller can still occupy the
+     * repair key with another payment; funding_replayed must remain a refusal, not be absorbed
+     * as already reconciled. Preserve blocked_reason and the wallet’s settlement instant.
      */
     reconcileBlockedInvoice(args: {
         paymentHash: string;
@@ -3272,17 +2826,9 @@ declare class CreditLedger {
         nowMs?: number;
     }): Promise<InvoiceReconciliation>;
     /**
-     * Record that an operator reviewed a blocked invoice and chose not to credit
-     * it — no ledger effect, purely a queue transition.
-     *
-     * A CAS on `blocked`, and idempotent: re-running returns the recorded row
-     * rather than overwriting the first note. It cannot capture a `reconciled`
-     * row, because that one moved money.
-     *
-     * `written` reports whether *this* call was the transition. The caller has
-     * no other way to tell — the row reads identically either way — and the
-     * write-off's audit log is the only record of the amount, so a re-emitted
-     * one reads as a second decision about the same sats.
+     * Write off an invoice without crediting or moving money. Only the first transition records
+     * the note; its written bit controls the audit event. An operator can later reconcile a
+     * written-off invoice, because write-off did not return its payment.
      */
     writeOffBlockedInvoice(args: {
         paymentHash: string;
@@ -3297,14 +2843,12 @@ declare class CreditLedger {
     getForCaller(callerPubkey: string, opts?: {
         nowMs?: number;
     }): Promise<CreditSnapshot[]>;
-    /** Read one draw (no lock), with its credit's rail basis joined in. */
     getDraw(args: {
         creditId: string;
         drawId: string;
     }): Promise<DrawRecord | undefined>;
     /** Read the sole draw bound to a pre-allocated job id; ambiguity fails closed. */
     getDrawByJobId(jobId: string): Promise<DrawRecord | undefined>;
-    /** Read every draw linked to a job, including already-resolved rows. */
     listDrawsByJobId(jobId: string): Promise<DrawRecord[]>;
     /**
      * All pending holds on a credit, in `ledger_seq` order (no lock). Read
@@ -3313,22 +2857,10 @@ declare class CreditLedger {
      */
     listPendingDraws(creditId: string): Promise<DrawRecord[]>;
     /**
-     * One page of pending holds host-wide placed before `createdBeforeMs`,
-     * oldest first (no lock). The orphan sweeper's read surface: a
-     * draw commits with its `job_id` before the job row is persisted, so a crash
-     * or a fail-closed refusal in that window strands a hold nothing can ever
-     * resolve — the only release path keys off the `credit_id`/`draw_id` written
-     * on the job row.
-     *
-     * Host-wide like {@link listPendingDrains}, not per-credit: the sweeper has
-     * no candidate credit to start from. Age-bounded so it never sees a draw
-     * whose job row is merely still in flight.
-     *
-     * `limit` is required and `after` keyset-paginates: an aged hold whose job
-     * row *does* exist is legitimately un-sweepable and stays `pending`
-     * indefinitely, so a caller that re-issues the same first page would never
-     * see past a `limit`-sized wall of them. Pass the last row's
-     * {@link StalePendingDrawCursor} to advance.
+     * Page host-wide pending holds older than createdBeforeMs by (created_at, credit_id,
+     * ledger_seq). Use the same compound key for ordering and continuation, preserving
+     * same-millisecond rows. Terminal resolution still rechecks state under the parent-credit
+     * lock.
      */
     listStalePendingDraws(args: {
         createdBeforeMs: number;
@@ -3336,38 +2868,18 @@ declare class CreditLedger {
         after?: StalePendingDrawCursor;
     }): Promise<DrawRecord[]>;
     /**
-     * Rail-native value the credit an x402 settlement channel funded has
-     * actually earned — the sum of its **settled** draws, in the credit's native
-     * atomic units (USDC micro on this rail). The batch-settlement claim job's
-     * ceiling: a channel is claimable up to what its credit's draws
-     * have earned, never up to the deposit that funded it.
-     *
-     * `undefined` when no credit is bound to the channel, which the claim job
-     * treats as "cannot be resolved" and claims nothing for — distinct from a
-     * resolved credit that has earned `0`.
-     *
-     * Deliberately a sum over settled draws rather than `funded − remaining`:
-     * a drain lowers `native_remaining` without earning anything, so the
-     * subtraction would read the caller's own reclaim as revenue. Pending holds
-     * are excluded for the mirror reason — a hold is work in flight, and
-     * claiming against it would take money a release still owes back.
+     * Sum settled draws’ native value for the credit bound to this x402 channel.
+     * Pending/released holds and drains earn nothing. Return undefined for an unbound channel,
+     * distinct from earned zero, so settlement cannot guess a claim limit.
      */
     earnedNativeForX402Channel(channelId: string): Promise<number | undefined>;
     /**
-     * The credit an x402 settlement channel funded, if one is bound to it — the
-     * binding is UNIQUE, so at most one row can answer.
-     *
-     * The operator repair's entry point: a wedged settlement row carries the
-     * channel and an `effect_id`, and this is what turns them back into the
-     * credit id, the caller pubkey, and the drain id the effect encodes. Deriving
-     * the credit id by splitting `effect_id` instead would be wrong — credit ids
-     * carry their own colons (`imp:`, `fnd:` and the rail segment inside them).
+     * Resolve the unique credit bound to the channel. The ID is opaque and can contain colons;
+     * do not reconstruct it by splitting settlement effect IDs.
      */
     getCreditByX402Channel(channelId: string): Promise<CreditSnapshot | undefined>;
-    /** Retire every active credit backed by a chain-proven lost Tempo channel. */
     terminalizeTempoCredits(evidence: TempoCreditLossEvidence, tx?: CreditLedgerQuerier): Promise<TempoCreditLoss[]>;
     private terminalizeTempoCreditsLocked;
-    /** List terminal Tempo credit losses, newest observation first. */
     listTempoCreditLosses(args?: {
         limit?: number;
     }): Promise<TempoCreditLoss[]>;
@@ -3382,36 +2894,21 @@ declare class CreditLedger {
      */
     terminalizeX402Credit(evidence: X402CreditLossEvidence, tx?: CreditLedgerQuerier): Promise<X402CreditLoss[]>;
     private terminalizeX402CreditLocked;
-    /** List terminal x402 credit losses, newest observation first. */
     listX402CreditLosses(args?: {
         limit?: number;
     }): Promise<X402CreditLoss[]>;
     /**
-     * Debit the caller's entire available balance into a drain liability
-     * (the caller-ownership contract: expiry ends spending, never ownership — this is the
-     * builder-honored reclaim floor). Runs under the credit row lock: the
-     * amount is `balance − pending holds` read under `FOR UPDATE`, the balance
-     * is decremented in the same transaction, and the drain takes the next
-     * gap-free `ledger_seq` — so the balance zeroes exactly once however many
-     * machines race the request.
-     *
-     * Idempotent on `(creditId, drainId)`: a replay returns the recorded drain
-     * (this is also the poll/pickup read). A replay whose `method` or `payout`
-     * differs from the recorded drain is refused with `drain_conflict` —
-     * silently honouring a changed payout would ship the caller's money to a
-     * destination they never signed alongside this `drain_id`.
+     * Move all available balance to a drain liability under the credit lock; pending holds stay
+     * reserved. Expiry alone does not prevent reclaim before a sweep releases the balance.
+     * Repeating (creditId, drainId) returns the recorded liability; owner, method and payout
+     * conflicts refuse.
      *
-     * Pending holds are NOT drained — in-flight jobs keep their money until
-     * they settle or release. A release after a drain restores available
-     * balance the caller reclaims with a **new** `drain_id`; drains are ledger
-     * arithmetic, not a terminal credit state, so `status` stays `active`.
-     *
-     * Deliberately **no expiry check**: draining works before and after
-     * expiry. The one thing expiry gates is new draws.
+     * An unresolved channel refund blocks fresh drain IDs but admits its own effect ID for
+     * repair. Caller-supplied payout validation belongs to the route. With tx, join the channel
+     * transaction without controlling it.
      */
     requestDrain(args: {
         creditId: string;
-        /** Client-generated drain id from the signed request body. */
         drainId: string;
         /** Verified caller pubkey — a drain may only be requested by the owner. */
         callerPubkey: string;
@@ -3424,7 +2921,6 @@ declare class CreditLedger {
         tx?: CreditLedgerQuerier;
         nowMs?: number;
     }): Promise<DrainRequestResult>;
-    /** Read one drain (no lock), joined with its credit for currency + owner. */
     getDrain(args: {
         creditId: string;
         drainId: string;
@@ -3436,25 +2932,11 @@ declare class CreditLedger {
      */
     listFundingLots(creditId: string): Promise<FundingLot[]>;
     /**
-     * What this DVM owes back in satoshis if every open non-channel Bitcoin
-     * credit reclaimed right now — the deposit half of the hub
-     * balance, and the floor a payout sweep must never go below.
-     *
-     * Read entirely off the funding lots, at their own funding rates, with no
-     * exchange-rate lookup anywhere: the obligation is in kind, so a rate has
-     * nothing to say about it. Pending job holds are deliberately **not**
-     * subtracted — a hold either settles into revenue or releases back to the
-     * caller, and until it does, treating it as already earned would understate
-     * the floor. The figure is conservative by exactly that amount.
-     *
-     * The two coverage holes ride along rather than being folded in silently, so
-     * a gap reads as a gap: `uncovered` is a credit whose lots fall short of its
-     * balance, `unbacked` is one holding any open micro with no sats basis. A
-     * reclaim on either prices the **whole** balance off a live rate — the
-     * depletion refuses a mixture rather than blending two bases — so both are
-     * reported as the whole balance, and neither contributes to `depositSats`.
-     * A figure that counted the backed half of a mixed credit would be a floor
-     * the payout never matches.
+     * Host-wide in-kind Bitcoin deposit liability, excluding channel collateral. Credits with
+     * missing coverage or any basisless lot are reported as gaps and use the live-rate fallback
+     * rather than a guessed sats obligation. Group fiat micro by currency; never sum
+     * denominations.
+     * Pending job holds remain liabilities until settled because they may release to the caller.
      */
     bitcoinDepositLiability(): Promise<BitcoinDepositLiability>;
     /**
@@ -3467,40 +2949,15 @@ declare class CreditLedger {
      */
     listPendingDrains(): Promise<CreditDrainRecord[]>;
     /**
-     * One page of still-`pending` drains on a channel-backed credit, oldest
-     * first (no lock) — the operator's repair queue.
-     *
-     * Keyset-paginated for the x402 settlement queue's reason: a wedged row
-     * never self-clears, so a caller that re-issues the same first page would
-     * never see past a `limit`-sized wall of them. The keyset is
-     * `(created_at, credit_id, drain_id)` — `created_at` is immutable, so no
-     * concurrent write can push an unexamined row past the cursor. It is a
-     * BIGINT of epoch milliseconds rather than a `TIMESTAMPTZ`, so the
-     * microsecond-vs-millisecond cursor trap that bit `listSettlements` cannot
-     * arise here: the value round-trips as the integer it already is.
-     *
-     * `createdBeforeMs` is the staleness floor. A healthy cooperative close
-     * moves the drain to `sent` inside the request that opened it, so anything
-     * younger is in flight rather than stuck.
-     *
-     * The method filter is `'tempo'`, and it is the one line here worth a second
-     * look: `init()` migrates the legacy `'mpp'` spelling away and
-     * `DrainMethod` no longer carries it, so a query naming it matches nothing a
-     * DVM has ever written. It named it anyway until rename sweep and
-     * live rung caught it independently — the whole operator queue
-     * read empty in production while every route test stayed green, because
-     * those run on `MemoryCreditLedger`, which filters on the typed value. The
-     * two implementations of this one predicate must be read together.
-     *
-     * A written-off row is excluded unless `includeResolved`: the operator has
-     * already decided about it, and leaving it on the live queue would re-serve
-     * a closed decision on every walk.
+     * Page pending Tempo-channel drains by (created_at, credit_id, drain_id), optionally
+     * age-bounded, excluding written-off rows. Accept the legacy mpp stored method as well as
+     * tempo so pre-migration drains remain repairable. Use the compound key for both ordering
+     * and continuation.
      */
     listChannelDrains(args: {
         limit: number;
         after?: ChannelDrainCursor;
         createdBeforeMs: number;
-        /** Which channel binding to walk. Today only Tempo has a repair. */
         rail: "tempo";
         includeResolved?: boolean;
     }): Promise<CreditDrainRecord[]>;
@@ -3606,11 +3063,9 @@ declare class CreditLedger {
         nowMs?: number;
     }): Promise<DrainTransitionResult>;
     /**
-     * Append a countersigned reclaim-event receipt to the drain's evidence
-     * trail. A single-statement JSONB append — receipts are emitted after the
-     * state transition they attest, and losing one never loses money (the
-     * transition is the source of truth; the receipt is the proof the caller
-     * can carry away).
+     * Append an opaque supplied receipt observation to the drain’s JSONB evidence array.
+     * Issuance and authentication belong to callers/consumers; this store does not verify
+     * signatures. Preserve append order on replay/poll reads.
      */
     appendDrainReceipt(args: {
         creditId: string;
@@ -3619,31 +3074,13 @@ declare class CreditLedger {
         tx?: CreditLedgerQuerier;
     }): Promise<void>;
     private readDrain;
-    /** Re-read the credit join fields for a freshly-updated drain row. */
     private rejoin;
-    /** Shared refusal tail for the CAS transitions: idempotent replay or typed error. */
     private refuseTransition;
     /**
-     * Price a reclaim in kind and say which lots it takes.
-     *
-     * The debits are returned whether or not the reclaim can be priced, and the
-     * caller applies them either way: the money is leaving the credit, so the
-     * lots have to shrink with it or the deposit-liability rollup would keep
-     * counting a balance that is gone.
-     *
-     * `owedSats` is `null` where {@link isInKindDepletion} refuses — the lots
-     * are short of the balance, or the covering lots carry no sats basis (a
-     * legacy credit whose funding recorded no sats basis. That row is priced off a live rate by the
-     * admin surface instead, which is what *every* row did before this change,
-     * so the fallback is the old behaviour rather than a new failure mode.
-     *
-     * What it publishes is **net of the delivery reserve**: handing a
-     * refund over costs a mint fee and, when the notes have to be minted just in
-     * time, a Lightning hop. The caller carries that cost per and a
-     * flat reserve is how they carry it without the figure moving — an
-     * actual-fee true-up could only be applied after the promise was made. The
-     * debits stay gross because they are denominated in micro and are what
-     * `releaseDrain` restores; only the sats figure is netted.
+     * Deplete FIFO lots even when they cannot price the reclaim; stale open lots must not
+     * remain behind a debited balance. Publish owedSats only with complete positive sats
+     * coverage, net of one delivery reserve. Otherwise preserve null for a live-rate fallback.
+     * Returned debits allow an unpaid drain release to restore the exact lots.
      */
     private reclaimInKind;
     /**
@@ -3663,7 +3100,6 @@ declare class CreditLedger {
      * as every other balance move is.
      */
     private applyLotDebits;
-    /** Shared settle/release state machine — see the public JSDoc on each verb. */
     private resolveDraw;
     private resolveDrawLocked;
     /**
@@ -3672,7 +3108,6 @@ declare class CreditLedger {
      * success (harmless for read-only replay paths), rolls back on throw.
      */
     private withCreditLock;
-    /** `SELECT … FOR UPDATE` the credit row on `q` (which must be inside a transaction). */
     private lockCreditRow;
     private readDraw;
     /**
@@ -3687,13 +3122,9 @@ declare class CreditLedger {
     private readX402CreditLosses;
 }
 /**
- * The ledger surface the SDK server codes against. Implemented by
- * the Postgres {@link CreditLedger} (production — spec condition 2 requires
- * the DVM's own Postgres) and by `MemoryCreditLedger` (devMode / in-process
- * tests / pool-less `createDVMServer` setups, mirroring the `MemoryJobStore`
- * precedent). The `tx` handles on `fund`/`draw` are meaningful only on the
- * Postgres implementation; the memory ledger ignores them — its operations
- * are synchronous-atomic in-process, so there is no rail transaction to join.
+ * Implemented by durable Postgres and per-process memory ledgers. Production funding menus
+ * require durable storage; memory is for explicit development and tests. Mutations accepting
+ * tx join the caller’s transaction; memory implementations ignore that handle.
  */
 interface CreditLedgerLike {
     /**
@@ -3882,9 +3313,7 @@ interface CreditLedgerLike {
         creditId: string;
         drawId: string;
     }): Promise<DrawRecord | undefined>;
-    /** Read the sole draw linked to a stable pre-payment job id. */
     getDrawByJobId(jobId: string): Promise<DrawRecord | undefined>;
-    /** Read every draw linked to a job so retention can resolve all holds before redaction. */
     listDrawsByJobId(jobId: string): Promise<DrawRecord[]>;
     listPendingDraws(creditId: string): Promise<DrawRecord[]>;
     listStalePendingDraws(args: {
@@ -3919,7 +3348,6 @@ interface CreditLedgerLike {
     listPendingDrains(): Promise<CreditDrainRecord[]>;
     /** See {@link CreditLedger.bitcoinDepositLiability} — the in-kind deposit floor. */
     bitcoinDepositLiability(): Promise<BitcoinDepositLiability>;
-    /** One credit's undepleted funding lots, oldest first. */
     listFundingLots(creditId: string): Promise<FundingLot[]>;
     listChannelDrains(args: {
         limit: number;
@@ -3981,14 +3409,12 @@ interface CreditLedgerLike {
 interface CreditLedgerQuerier {
     query: Pool["query"];
 }
-/** Reporter outbox joined to a draw release's own transaction. */
 interface CreditDrawReleaseOutbox {
     /** Platform DVM record ID bound into the report. */
     dvmId: string;
     /** Reporter-owned insert executed through the ledger transaction. */
     enqueue: CreditDrawReleaseEnqueue;
 }
-/** Reporter seam for credit-expiry releases and the revivals that reverse them. */
 interface CreditExpiryReleaseOutbox {
     /** Platform DVM record ID bound into the report. */
     dvmId: string;
@@ -3996,16 +3422,15 @@ interface CreditExpiryReleaseOutbox {
     enqueue: CreditExpiryReleaseEnqueue;
 }
 /**
- * One recorded expiry episode: a credit's undrawn remainder passing to the
- * builder when its TTL ran out.
- *
- * `reversedAt` is set when a later funding revived the credit, at which point
- * the release stops counting against committed value — the row stays as the
- * record that it once did.
+ * One committed expiry episode. The sweep releases the undrawn remainder; later funding sets
+ * reversedAt and restores that release on the same transaction. Multiple episodes may share
+ * an expiry instant.
  */
 interface CreditExpiryRelease {
     creditId: string;
-    /** Per-expiry-episode key, derived from {@link CreditExpiryRelease.expiryMs}. */
+    /**
+     * Key derived from expiry instant and the release sequence counted under the credit lock.
+     */
     releaseId: string;
     callerPubkey: string;
     currency: string;
@@ -4013,31 +3438,29 @@ interface CreditExpiryRelease {
     rail: string | null;
     /** Fiat micro released, 1e-6 of `currency`. */
     amountMicro: number;
-    /** When the credit's TTL ran out — when the liability ended. */
+    /**
+     * Nominal credit expiry, ms since epoch; the claim is released only when the sweep commits.
+     */
     expiryMs: number;
-    /** When the sweep observed the expiry. */
+    /**
+     * When the sweep recorded this release, ms since epoch.
+     */
     releasedAt: number;
     /** When a funding revived the credit and undid this release. */
     reversedAt: number | null;
 }
-/** Pool-shaped handle (`query` + `connect`). Required for the locked write paths. */
 type CreditLedgerPool = Pick<Pool, "query" | "connect">;
 /**
- * Credit lifecycle status. `unbacked` is the terminal audit state for a Tempo
- * channel that finalized below its accepted voucher; its nominal balance is
- * preserved, but it can never be drawn, funded, grown, or drained.
+ * unbacked credit is unavailable for spending or reclaim while channel collateral is gone. An
+ * x402 credit with no remaining liability can be restored to active by channel
+ * reconciliation.
  */
 type CreditStatus = "active" | "unbacked";
 /** Draw lifecycle: two-phase hold → terminal settle/release. */
 type DrawStatus = "pending" | "settled" | "released";
 /**
- * Rails a drain can pay out on (the reclaim contract).
- *
- * Direct Lightning payout is deliberately absent: a
- * first-party deployment holds no send-capable Lightning credential by design
- * (the funding NWC is receive-only), so P2PK-locked Cashu notes are
- * the only non-channel Bitcoin reclaim path. Adding `lightning` back means
- * re-deciding that, not just widening a union.
+ * Drain payout rails. Direct Lightning send is excluded: deployments reclaiming Bitcoin can
+ * use Cashu notes without putting a spending wallet credential in the DVM.
  */
 type DrainMethod = "cashu" | "x402" | "tempo";
 /**
@@ -4076,12 +3499,20 @@ interface BitcoinDepositLiability {
     }[];
     /** Credits holding balance no funding lot backs — a defect, not a liability figure. */
     uncoveredCredits: number;
-    /** Their whole balance: a short-covered credit reclaims off a live rate entirely. */
-    uncoveredMicro: number;
+    /** Whole balances of short-covered credits, by ledger currency; reclaim uses a live rate. */
+    uncoveredByCurrency: {
+        currency: string;
+        micro: number;
+        credits: number;
+    }[];
     /** Credits holding any open micro with no sats basis, so their reclaim prices off a live rate. */
     unbackedCredits: number;
-    /** Their whole balance, for the same all-or-nothing reason. */
-    unbackedMicro: number;
+    /** Whole balances of basisless credits, by ledger currency. */
+    unbackedByCurrency: {
+        currency: string;
+        micro: number;
+        credits: number;
+    }[];
 }
 /**
  * What it cost to put a just-in-time-minted refund in the caller's hands
@@ -4119,16 +3550,9 @@ interface CreditDrainRecord {
     currency: string;
     method: DrainMethod;
     /**
-     * The channel this drain's credit is bound to (Tempo session or x402
-     * settlement channel), `null` on a one-payment or Cashu/Lightning credit.
-     *
-     * The method alone does not say who settles a reclaim: an `mpp` or `x402`
-     * drain on a channel-bound credit is closed by the channel itself, and a
-     * `pending` one is routinely mid-reconciliation rather than owed by anybody
-     * `completeTempoDrain` leaves every ambiguous close pending on purpose for
-     * `recoverTempoSessionClose` to finish on the caller's next poll. Carrying
-     * the binding on the record is what lets a reader tell that apart from a
-     * one-payment reclaim only a person can settle.
+     * Reusable Tempo or x402 channel backing this drain, or null for one-payment/non-channel
+     * credit. The channel’s cooperative lifecycle owns fulfillment; the operator’s manual sent
+     * route refuses channel-bound drains.
      */
     channelId: string | null;
     /** Method-specific payout target as signed by the caller. */
@@ -4143,12 +3567,11 @@ interface CreditDrainRecord {
      */
     drainedNative: number | null;
     /**
-     * What this reclaim owes in satoshis, computed from the credit's funding
-     * lots when it was requested and never re-priced: the deposited
-     * sats, pro rata to the share of the credit being reclaimed, floored per
-     * lot. `null` on a channel rail (in-kind structurally, through the escrow)
-     * and on a Bitcoin credit whose lots cannot price it — that one falls back
-     * to a live rate on the admin surface.
+     * In-kind sats obligation fixed at request time: the decrease in FIFO lots’ remaining
+     * floored obligations, net of one delivery reserve. A non-null obligation is not repriced.
+     * Null on unpriceable non-channel Bitcoin refunds requires the live-rate Cashu fallback.
+     * Channel and stablecoin refunds also use null: they have no sats obligation and follow
+     * their native/channel payout lifecycle, using `drainedNative` where applicable.
      */
     owedSats: number | null;
     /**
@@ -4174,7 +3597,10 @@ interface CreditDrainRecord {
      * already holding.
      */
     fulfilment: DrainFulfilment | null;
-    /** Countersigned reclaim-event receipts, in emission order. */
+    /**
+     * Opaque supplied reclaim-event observations in append order; consumers shape-check and
+     * authenticate them.
+     */
     receipts: Record<string, unknown>[];
     createdAt: number;
     parkedAt: number | null;
@@ -4245,9 +3671,8 @@ interface DrainRequestResult {
     replayed: boolean;
 }
 /**
- * Read-model of one credit. `availableMicro` = `balanceMicro` − pending
- * holds; `expired` is computed from `expiryMs` at read time (expiry ends
- * spending, never ownership — the balance stays readable).
+ * Read model with funded balance and pending holds. Expiry is computed at read time and does
+ * not erase the record; unbacked credit has no available balance.
  */
 interface CreditSnapshot {
     creditId: string;
@@ -4255,7 +3680,9 @@ interface CreditSnapshot {
     currency: string;
     /** Funded balance, 1e-6 currency units. Pending holds are NOT subtracted. */
     balanceMicro: number;
-    /** Spendable balance: `balanceMicro` minus pending holds. */
+    /**
+     * Balance minus pending holds, or zero while backing is unbacked.
+     */
     availableMicro: number;
     /**
      * `availableMicro` in the funding rail's own units — the ceiling any
@@ -4266,7 +3693,9 @@ interface CreditSnapshot {
     expiryMs: number;
     expired: boolean;
     status: CreditStatus;
-    /** High-water `ledger_seq` — the seq of the most recent draw. */
+    /**
+     * High-water sequence shared by draw placements and drains.
+     */
     lastLedgerSeq: number;
     createdAt: number;
     /**
@@ -4281,19 +3710,17 @@ interface CreditSnapshot {
     /** Reusable x402 channel bound to this credit, if one funded it. */
     x402ChannelId: string | null;
 }
-/**
- * Result of a draw — carries the receipt tuple the countersignature
- * consumes (`ReceiptCredit`: `draw_id`, `amount`, `balance_after`,
- * `ledger_seq`). `balanceAfterMicro` and `ledgerSeq` are the values recorded
- * when the draw was first placed; a replay returns them unchanged.
- */
 interface DrawResult {
     creditId: string;
     drawId: string;
     amountMicro: number;
-    /** Available balance immediately after this draw's hold, as first recorded. */
+    /**
+     * Recorded balance after placement or latest growth, at the draw’s original sequence.
+     */
     balanceAfterMicro: number;
-    /** Per-credit monotonic, gap-free draw counter. */
+    /**
+     * Per-credit gap-free sequence shared with drains; growth keeps the original value.
+     */
     ledgerSeq: number;
     status: DrawStatus;
     /** True when this call was an idempotent replay of an already-recorded state. */
@@ -4304,14 +3731,9 @@ interface DrawResult {
     resolvedAt: number | null;
 }
 /**
- * The rail-native slice of a credit that one draw carries — what
- * makes a settled draw bookable as a revenue event on the funding's rail.
- *
- * Allocated at draw time as `remaining × amountMicro / availableMicro`, where
- * both remainders are net of pending holds. The draw that consumes a credit's
- * last micro therefore takes ratio 1 and the exact remainder, so the draws of
- * a credit sum to precisely the value funded — no rounding residue, and no
- * last-draw special case.
+ * A draw’s rail value and funding identity. Placement records a pooled forecast; settling
+ * non-channel Bitcoin can replace it with FIFO lot pricing while retaining the original as
+ * allocatedMsats. Native null means no native amount was reported, distinct from zero.
  */
 interface DrawRailValue {
     /** Millisatoshis of rail value allocated to this draw. */
@@ -4364,7 +3786,6 @@ interface DrawResolution extends DrawResult {
     /** Settlement instant — the timestamp a draw-keyed revenue event is dated by. */
     resolvedAt: number;
 }
-/** Full persisted draw row, camel-cased. */
 interface DrawRecord extends Omit<DrawResult, "replayed"> {
     jobId: string | null;
     createdAt: number;
@@ -4434,9 +3855,11 @@ interface CreditFundingBasis {
         maxClaimableAmount: string;
     };
 }
-/** What {@link CreditLedger.fund} takes. Named so the private body can share the shape. */
 interface CreditFundArgs {
-    /** Omit to mint a fresh credit id; provide to top up (or idempotently create). */
+    /**
+     * Omit to mint a credit ID; provide to add funding to that credit. Replay prevention is the
+     * caller’s responsibility.
+     */
     creditId?: string;
     callerPubkey: string;
     /** The DVM's pricing currency; `amountMicro` is 1e-6 of it. */
@@ -4444,9 +3867,13 @@ interface CreditFundArgs {
     amountMicro: number;
     /** Absolute expiry, ms since epoch. Overwrites the previous value on top-up. */
     expiryMs: number;
-    /** Rail-value basis this funding contributes (required by ). */
+    /**
+     * Rail value contributed by this funding; required on writes.
+     */
     basis: CreditFundingBasis;
-    /** External transaction handle — caller owns BEGIN/COMMIT (spec condition 3). */
+    /**
+     * External transaction handle; caller owns BEGIN, COMMIT and ROLLBACK.
+     */
     tx?: CreditLedgerQuerier;
     nowMs?: number;
 }
@@ -4466,7 +3893,6 @@ declare function allocateDrawValue(args: {
     drawMsats: number;
     drawNative: number | null;
 };
-/** Full persisted `credit_fundings` row, camel-cased. */
 interface FundingRecord {
     creditId: string;
     fundId: string;
@@ -4498,7 +3924,6 @@ interface FundingRecord {
  * human had to intervene.
  */
 type CreditInvoiceStatus = "pending" | "settled" | "expired" | "blocked" | "reconciled" | "written_off";
-/** Full persisted `credit_invoices` row, camel-cased. */
 interface CreditInvoiceRecord {
     creditId: string;
     fundId: string;
@@ -4531,7 +3956,6 @@ interface CreditInvoiceRecord {
     /** When the payment landed at the wallet — never the instant an operator acted on it. */
     settledAt: number | null;
 }
-/** Outcome of applying an observed settlement to the ledger. */
 interface InvoiceSettlement {
     invoice: CreditInvoiceRecord;
     /** The `credit_fundings` row; absent only if a legacy row somehow lacks one. */
@@ -4541,10 +3965,8 @@ interface InvoiceSettlement {
     replayed: boolean;
 }
 /**
- * Outcome of an operator crediting a blocked invoice onto a credit they named;
- * it has the same shape as {@link InvoiceSettlement}, but `funding` and
- * `credit` describe the **target** credit, not the one the invoice was minted
- * against.
+ * Reconciliation keeps the original invoice identity; funding and credit describe the
+ * operator-selected target credit, which may differ from the invoice’s original credit.
  */
 interface InvoiceReconciliation {
     invoice: CreditInvoiceRecord;
@@ -4553,7 +3975,6 @@ interface InvoiceReconciliation {
     /** True when this reconcile had already been applied — nothing moved. */
     replayed: boolean;
 }
-/** Outcome of `writeOffBlockedInvoice` — the recorded row, plus whether this call wrote it. */
 interface InvoiceWriteOff {
     invoice: CreditInvoiceRecord;
     /** False when the invoice was already written off, so nothing changed. */
@@ -4565,31 +3986,13 @@ interface BlockedInvoiceCursor {
     creditId: string;
     fundId: string;
 }
-/** Typed failure codes for {@link CreditLedgerError}. */
 type CreditLedgerErrorCode = "credit_not_found" | "credit_expired" | "credit_unbacked" | "tempo_channel_closing" | "tempo_settlement_pending" | "settlement_pending" | "insufficient_credit" | "draw_conflict" | "draw_not_found" | "invalid_draw_state" | "funding_replayed" | "currency_mismatch" | "caller_mismatch" | "rail_mismatch" | "invalid_amount" | "invalid_expiry" | "invalid_basis" | "nothing_to_drain" | "drain_below_dust" | "drain_not_found" | "drain_conflict" | "invalid_drain_state" | "invoice_not_found" | "invoice_conflict" | "invoice_not_blocked" | "below_rail_minimum";
 /**
- * Which conflict a `drain_conflict` is, for the routes that answer one.
- *
- * One code covers refusals whose only common property is that no drain was
- * booked; the copy a caller relays to a human differs entirely between them.
- * A tag rather than a message substring because that is what the copy used to
- * key on, and both of the x402 commit leg's conflicts missed it by a word —
- * silently, since the fallback is a well-formed answer about a different
- * refusal.
- *
- * The three are not one shape with three causes. `pending_draws` and
- * `balance_moved` roll back with nothing on any chain and clear on their own;
- * `refund_floor` is the opposite — the cooperative refund reached the chain and
- * paid short, so the caller's money moved and only the operator repair resolves
- * it. A route's `retryable` and `drain_registered` follow from which
- * one it is, so the tag has to reach it.
- *
- * Absent means the duplicate-payout conflict `PAYMENT_ERROR_COPY.drain_conflict`
- * was written for, which is also the conservative default for a conflict nobody
- * has classified yet.
+ * Structured drain_conflict reasons select caller instructions without matching prose. A
+ * refund_floor shortfall needs operator resolution, unlike duplicate payout; foreign_credit
+ * discloses no liability to the wrong owner; drain_id_retired requires a fresh ID.
  */
 type DrainConflictReason = "pending_draws" | "balance_moved" | "refund_floor";
-/** Structured context on a {@link CreditLedgerError}, per code. */
 interface CreditLedgerErrorDetails {
     /** On `drain_conflict`: which conflict it is, so a route can answer it without matching on prose. */
     drainConflict?: DrainConflictReason;
@@ -4689,7 +4092,8 @@ interface TempoSessionLifecycle {
  *
  * Every mutation takes an advisory transaction lock keyed by the channel
  * before locking its row with `FOR UPDATE`, applies mppx's synchronous
- * transition exactly once, and commits before returning. The advisory lock
+ * transition and commits before returning. Transaction recovery may retry a callback
+ * attempt; a rolled-back attempt is not a second committed transition. The advisory lock
  * covers a channel's first write, when there is no row for `FOR UPDATE` to
  * lock. Together these are the cross-machine linearization point for voucher,
  * top-up, spend, and close state; mppx's process-local fallback is
@@ -4717,13 +4121,10 @@ declare class PostgresTempoSessionStore implements Store.AtomicStore {
     private readonly pool;
     private readonly acceptance;
     constructor(pool: Pool);
-    /** Create the channel table under the SDK-wide migration lock. */
     init(): Promise<void>;
-    /** Read one channel snapshot. */
     get(key: string): Promise<unknown>;
     /** Replace one channel snapshot. Used by mppx only for non-RMW maintenance. */
     put(key: string, value: unknown): Promise<void>;
-    /** Delete one channel snapshot. */
     delete(key: string): Promise<void>;
     /** Atomic read-modify-write using a row lock shared by every SDK replica. */
     update<result>(key: string, fn: (current: unknown) => Store.Change<unknown, result>): Promise<result>;
@@ -5103,7 +4504,6 @@ declare const _testing: {
     attachTempoSessionRuntime: typeof attachTempoSessionRuntime;
 };
 
-/** Envelope fields the verifier validates around the signed payload. */
 interface CanonicalEnvelope {
     pubkey: string;
     signature: string;
@@ -5115,21 +4515,20 @@ interface CreateSignedRequestVerifierOpts {
     /** Fixed audience/operation for a custom signed route or standalone verifier. */
     domain?: SignedRequestDomain;
     /**
-     * Permitted clock drift in seconds. Defaults to 300 (5 minutes — matches
-     * cast's `SIGNATURE_DRIFT_SECONDS`).
+     * Permitted clock drift in seconds; default 300.
      */
     driftSeconds?: number;
     /**
-     * Field names to strip from the parsed input when computing the canonical
-     * bytes the signature covers. Defaults to `["signature"]`. The signature
-     * itself is always stripped (callers don't need to repeat it).
+     * Fields stripped from raw input when forming signing bytes; default signature,
+     * which is always stripped even when additional fields are configured.
      */
     envelopeFields?: string[];
     /**
      * Field names removed from the input before `schema` validates it — and
      * **kept** in the canonical bytes the signature covers. For protocol-reserved
      * keys the caller signs but the schema never declares: the credit
-     * envelope riding a capability schema. Defaults to none.
+     * envelope riding a capability schema. No additional fields are ignored by default;
+     * auth_statement is always excluded from schema validation.
      *
      * This is the one place where "what is validated" and "what is signed"
      * legitimately differ. Don't reach for it to paper over a schema mismatch —
@@ -5144,7 +4543,6 @@ interface CreateSignedRequestVerifierOpts {
     /** Current Unix-seconds source. Defaults to `() => Math.floor(Date.now() / 1000)`. */
     now?: () => number;
 }
-/** Minimal replay-store contract — same shape as cast's `ReplayStore`. */
 interface SignedRequestReplayStore {
     /**
      * True iff (pubkey, timestamp, nonce) was already seen within the retention
@@ -5161,20 +4559,9 @@ interface SignedRequestSignOpts {
     nonce?: string;
 }
 /**
- * Round-trip verifier + signer for secp256k1+BIP-340 Schnorr-signed protocol requests.
- *
- * Authentication is two-step so the replay nonce is committed iff a job is
- * created, not on every request entry:
- *
- * 1. {@link checkAuth} runs schema → drift → signature at request entry on
- * both `/v1/quote` and `/v1/job`. Sync; no replay-store touch.
- * 2. {@link recordReplay} commits `(pubkey, timestamp, nonce)` to the replay
- * store. Called from `/v1/job` only, after upfront payment is verified
- * and immediately before `jobManager.createJob`.
- *
- * The unpaid `/v1/job` warmup probe (price discovery → 402) thus no longer
- * burns the nonce — clients can re-submit the same envelope with a real
- * payment.
+ * Authentication does not touch replay state. Job submission commits replay
+ * only after upfront payment verification, so unpaid discovery cannot burn
+ * the nonce. Reactivation rechecks the persisted signature without drift/replay.
  */
 interface SignedRequestVerifier<T> {
     /**
@@ -5208,20 +4595,11 @@ interface SignedRequestVerifier<T> {
      */
     signRequest(privkey: Uint8Array, body: Record<string, unknown>, opts?: SignedRequestSignOpts, domain?: SignedRequestDomain): T & CanonicalEnvelope;
 }
-/** Failure mode taxonomy returned from `verify()`. */
 type SignedRequestFailure = "schema_invalid" | "timestamp_drift" | "signature_invalid" | "replay_detected";
 /**
- * The four fields every signed-request envelope carries around the payload,
- * with the runtime type each must have once the schema has parsed.
- *
- * The single definition of "which part of a schema failure is the envelope's":
- * the post-parse shape check in `parse()` iterates it, and `authErrorBody`'s
- * classifier reads its keys to decide whether a `schema_invalid` throw
- * is the caller's *input* being wrong (disclosable: the schema is public on
- * `/v1/info`) or their *signing* being wrong (folded into `signature_invalid`,
- * one answer for every key and signature failure). `satisfies` pins it to
- * {@link CanonicalEnvelope}, so a fifth envelope field can't be added to the
- * type without both readers picking it up.
+ * One definition of envelope field types shared by the runtime shape guard
+ * and error disclosure classifier. Envelope failures stay private; violations
+ * of the published builder input schema can be disclosed.
  */
 declare const SIGNED_ENVELOPE_TYPES: {
     readonly pubkey: "string";
@@ -5230,9 +4608,7 @@ declare const SIGNED_ENVELOPE_TYPES: {
     readonly nonce: "string";
     readonly auth_statement: "object";
 };
-/** The envelope field names — {@link SIGNED_ENVELOPE_TYPES}' keys. */
 declare const SIGNED_ENVELOPE_FIELDS: readonly (keyof CanonicalEnvelope)[];
-/** Structured error from `verify()` — `sub_reason` is the failure kind. */
 declare class SignedRequestError extends Error {
     readonly sub_reason: SignedRequestFailure;
     /**
@@ -5259,38 +4635,15 @@ declare class SignedRequestError extends Error {
     issues?: readonly z.core.$ZodIssue[] | undefined);
 }
 /**
- * Build a secp256k1+BIP-340 Schnorr-over-canonical-JSON request verifier.
- *
- * Generalises cast's `canonicalSignedPayload` + `verifyCanonicalSignedRequest`
- * into a reusable primitive — `(schema, opts) -> { verify, canonicalBytes, signRequest }`.
- * Both halves derive their canonical bytes through the same function so any
- * Zod schema change automatically propagates to both signer and verifier.
+ * Signatures cover the raw input, not Zod-parsed output. Schema validation
+ * may apply defaults or transformations without changing the signed bytes.
  */
 declare function createSignedRequestVerifier<T = unknown>(schema: ZodLike<T>, opts?: CreateSignedRequestVerifierOpts): SignedRequestVerifier<T>;
 /**
- * The wire object the caller signed, taken out of a request body.
- *
- * **The single definition of which bytes get verified, and every auth call site
- * reads it**: `/v1/quote`, the `/v1/job` submit, and the reactivation
- * re-verify. They used to disagree — quote checked the raw `body.data`, submit
- * checked `JobManager.parseInput`'s Zod output — so the two agreed only where
- * the parse happened to be an identity on the caller's payload. A nested
- * `.default()`, a `.transform()`, a `z.coerce.*`, or any key the caller sent
- * that the schema doesn't declare made the quote pass and the paid submit 401
- * `signature_invalid`, blaming the signature for a schema shape the caller
- * never saw.
- *
- * Raw is what `public SDK documentation` specifies ("take the body, remove the
- * `signature` field, and canonicalise"), what the CLI signs, and what the SDK
- * persists as `record.input` — so the parsed form has no claim here. The
- * capability schema still validates what the handler receives; it just doesn't
- * get to rewrite the bytes the signature covers. It also means the credit
- * envelope needs no re-merge: it never left.
- *
- * `body.data` wins when present; otherwise the JSON-encoded `body.input` form
- * is parsed. Anything else — no input at all, a non-JSON legacy string — yields
- * `{}`, which carries no envelope and so fails the auth check, exactly as
- * before.
+ * Raw structured input for authentication and durable replay. data wins;
+ * otherwise input is parsed as JSON, with absent/legacy text becoming {}.
+ * Builder validation may transform the handler input but cannot rewrite these
+ * signing bytes, including protocol-owned credit fields.
  */
 declare function signedRequestInput(body: {
     input?: string;
@@ -5315,55 +4668,15 @@ declare function signedRequestInput(body: {
 declare function createDefaultReplayStore(): SignedRequestReplayStore;
 
 /**
- * A DVM-level auth scheme, declared on `DVMDescriptor.auth`. Authentication
- * is two-step:
- *
- * 1. {@link checkAuth} fires at request entry on `/v1/quote` and `/v1/job`,
- * before payment verification. Schema / drift / signature checks only —
- * no replay-store touch. Unsigned / malformed / stale / wrong-sig
- * envelopes reject with HTTP 401 with no Cashu round-trip and no pending
- * revenue row.
- * 2. {@link recordReplay} fires on `/v1/job` only, after upfront payment is
- * verified and immediately before `jobManager.createJob`. Commits the
- * `(pubkey, timestamp, nonce)` tuple to the replay store; throws 401
- * `replay_detected` on duplicate. The unpaid 402-discovery hop does not
- * burn the nonce, so clients can re-submit with payment.
- *
- * On `replay_detected` after payment was already accepted, the SDK responds
- * 401 fail-closed uniformly across cashu / mppx / x402 — no rail-specific
- * refund or compensation logic. The Cashu accept path
- * commits proofs into the accumulator wallet inside `verifyUpfrontPayment`
- * before `recordReplay` runs. Unlocked Cashu is rejected upstream, so the
- * accumulator is the only production path and no proofs are held to
- * refund; mppx / x402 credentials are single-use and already consumed by
- * the facilitator.
- *
- * The SDK picks the active capability's `input` schema and dispatches the
- * `checkAuth` call against it — schemes themselves take no schema parameter,
- * so one declaration covers every capability under a multi-capability DVM.
- *
- * A scheme validates the input it is handed, and on `/v1/job` that input
- * carries the credit envelope (`credit_id` / `draw_id` / `fund`) because the
- * signature covers it. Those keys are the protocol's, not the capability's, so
- * a scheme must not fail a schema that doesn't declare them — `secp256k1Auth`
- * removes them for the schema check only, keeping the signing bytes verbatim
- * A custom scheme owes callers the same tolerance, or every strict
- * schema 401s on an explicit draw.
+ * Boot-summary backend: postgres is shared across machines; memory is per-process.
+ * Explicit user-supplied stores and null (disabled) are never overridden.
  */
+type ReplayStoreBackend = "postgres" | "memory" | "user-supplied" | "disabled";
 /**
- * The replay-store backend resolved at host-boot time. Surfaced in
- * the boot summary so operators see which protection is active.
- *
- * - `postgres` — SDK auto-wired a `PostgresReplayStore` against the host's
- * pool. Cross-machine safe.
- * - `memory` — SDK fell back to the in-memory FIFO. Per-process; unsafe for
- * multi-machine deploys. `createDVMHost` emits a warning (or throws under
- * `DVMKIT_FAIL_FAST=true`) when this kicks in outside `devMode`.
- * - `user-supplied` — user passed an explicit `replayStore` at factory time.
- * SDK doesn't override.
- * - `disabled` — user passed `replayStore: null`. No replay tracking.
+ * Auth runs before payment; replay commits after accepted upfront payment.
+ * Custom schemes must validate builder input while tolerating signed protocol
+ * fields (credit, recovery and auth statement) outside the builder schema.
  */
-type ReplayStoreBackend = "postgres" | "memory" | "user-supplied" | "disabled";
 interface DVMAuthScheme {
     /** Wire-level identifier surfaced on `/v1/info#auth`. */
     readonly id: typeof SIGNED_REQUEST_AUTH_ID;
@@ -5373,13 +4686,9 @@ interface DVMAuthScheme {
         envelope: T & CanonicalEnvelope;
     };
     /**
-     * Re-verify the signature on a persisted envelope at reactivation time
-     * Schema + signature only — no drift check, no replay-store
-     * touch. Catches DB-layer tampering: persisted `record.input` would
-     * otherwise be trusted as authentic, and a compromised row could feed an
-     * attacker-supplied pubkey/envelope into the handler. Throws
-     * {@link SignedRequestError} with `sub_reason: "signature_invalid"` or
-     * `"schema_invalid"` on failure.
+     * Reactivation validates schema and signature without timestamp drift or replay
+     * checks: the original timestamp and already-committed nonce must remain usable.
+     * Throws signature_invalid or schema_invalid on failed validation.
      */
     recheckSignature<T>(schema: ZodLike<T>, input: unknown, domain?: SignedRequestDomain): void;
     /** Commit the envelope's `(pubkey, timestamp, nonce)` to the replay store. Throws on duplicate. */
@@ -5397,17 +4706,9 @@ interface DVMAuthScheme {
 }
 interface Secp256k1AuthOpts {
     /**
-     * Override the replay-window store. Most callers should omit this opt:
-     * `createDVMHost` auto-wires a cross-machine `PostgresReplayStore` when a
-     * pool is available, and falls back to a bounded in-memory FIFO (10-min
-     * window, 100k cap) only when no pool exists — emitting a warning (or
-     * throwing under `DVMKIT_FAIL_FAST=true`) outside `devMode` so multi-machine
-     * deploys can't silently inherit the per-process default.
-     *
-     * Pass a custom `SignedRequestReplayStore` here only to override that
-     * default (e.g. a different cross-machine backend), or pass `null` to
-     * disable replay tracking entirely. Any explicit value — including `null` —
-     * locks the choice: the host-boot wiring never overrides it.
+     * Omitting this lets the host adopt Postgres, otherwise falling back to a
+     * bounded per-process store with a warning or fail-fast refusal outside dev mode.
+     * Any explicit store, including null to disable replay tracking, is locked.
      */
     replayStore?: SignedRequestReplayStore | null;
     /** Permitted clock drift in seconds. Defaults to 300 (5 minutes). */
@@ -5416,30 +4717,16 @@ interface Secp256k1AuthOpts {
     now?: () => number;
 }
 /**
- * Build a descriptor-level secp256k1+BIP-340 Schnorr auth scheme.
- *
- * Declare on `configureDVM({ auth: secp256k1Auth({...}) })` to gate every
- * capability's `/v1/job` and `/v1/quote` on a signed request envelope
- * (`pubkey` / `signature` / `timestamp` / `nonce`) over the canonical JSON
- * form of the capability's input. The SDK calls {@link DVMAuthScheme.checkAuth}
- * at request entry on both endpoints, and {@link DVMAuthScheme.recordReplay}
- * on `/v1/job` only — after upfront payment is verified, just before the job
- * is created. The 402-discovery hop on `/v1/job` therefore does not consume
- * the replay nonce; the same signed envelope is accepted on the paid resubmit.
- *
- * One scheme instance covers every capability under the DVM — internally
- * the SDK caches a per-schema verifier so each capability's Zod schema is
- * compiled once. The replay store is shared across all capabilities.
+ * One scheme covers all capabilities and shares their replay store. Per-schema
+ * verifiers validate without touching replay state; the host commits replay
+ * only after upfront payment verification, immediately before job creation.
  */
 declare function secp256k1Auth(opts?: Secp256k1AuthOpts): DVMAuthScheme;
 
 /** Structural type matching any Zod schema. Avoids a hard dependency on zod. */
 interface ZodLike<T = unknown> {
-    /** Internal Zod metadata (used for duck-type detection). */
     _zod: unknown;
-    /** Parse and validate data, throwing on failure. */
     parse(data: unknown): T;
-    /** Parse and validate data, returning a result object instead of throwing. */
     safeParse(data: unknown): {
         success: true;
         data: T;
@@ -5448,28 +4735,13 @@ interface ZodLike<T = unknown> {
         error: unknown;
     };
 }
-/** Extract the output type from a ZodLike schema, or default to string. */
 type InputType<T> = T extends ZodLike<infer O> ? O : string;
 /**
- * Narrowed type for capability `example` payloads.
- *
- * Surfaces the Zod schema's output type so a drifted example produces a
- * TypeScript error at the `configureDVM` call site. Falls back to
- * `Record<string, unknown>` when `InputSchema` is undefined or a plain JSON
- * Schema object (which can't validate at type-level; the runtime
- * `validateExampleAgainstInput` in `configure.ts` covers schema-less paths).
- *
- * Approximation: `ZodLike<T>` exposes only one type param. True `z.input`
- * distinguishes pre-coercion input from post-coercion output for schemas
- * that use `.transform()` or `z.coerce.*`. None of the first-party DVMs do
- * that on their input schemas today. Revisit — extend `ZodLike` to a
- * two-param shape `ZodLike<Output, Input = Output>` — if a builder ever
- * hits a real divergence on `example`.
+ * Zod examples use the schema output type, including transforms. Plain JSON Schema examples have
+ * no equivalent static validation.
  */
 type ExampleType<InputSchema> = [InputSchema] extends [ZodLike<infer O>] ? O : Record<string, unknown>;
-/** Runtime check for whether a value is a Zod schema. */
 declare function isZodSchema(value: unknown): value is ZodLike;
-/** Structured logging interface injected via ctx.log. */
 interface Logger {
     debug(message: string, data?: Record<string, unknown>): void;
     info(message: string, data?: Record<string, unknown>): void;
@@ -5495,7 +4767,6 @@ interface PromptOpts {
     schema?: Record<string, unknown>;
 }
 interface SDKPaymentRequestOpts {
-    /** Cashu mints accepted for this payment. */
     mints?: string[];
     /** Minimum P2PK locktime in seconds. */
     minLocktimeSeconds?: number;
@@ -5548,11 +4819,8 @@ interface JobCost {
     /** ISO 4217 lowercase, e.g. `"usd"`. */
     currency: Currency;
 }
-/** Extended job context provided by the SDK runtime to DVM handlers. */
 interface SDKJobContext<State = Record<string, unknown>, Input = string> {
-    /** Server-assigned job ID. */
     readonly jobId: string;
-    /** Tags from the DVM descriptor (what this DVM handles). */
     readonly tags: string[];
     /** Job input — raw string or parsed/validated object when an input schema is defined. */
     readonly input: Input;
@@ -5572,24 +4840,17 @@ interface SDKJobContext<State = Record<string, unknown>, Input = string> {
         pubkey: string;
         envelope: CanonicalEnvelope & Record<string, unknown>;
     };
-    /** Send a progress text message to the client. */
     text(message: string): void;
-    /** Send an artifact (output data) to the client. */
     artifact(content: ArtifactContent): void;
     /** Send a raw typed message (escape hatch). */
     sendMessage(type: MessageType, content: Record<string, unknown>): void;
     /** Ask the client a question. Resolves when the client responds. */
     prompt(id: string, text: string, opts?: PromptOpts): Promise<ResponseContent>;
     /**
-     * Request payment from the client. Resolves when payment is received.
-     *
-     * - `number` = msats raw (sats-native operators).
-     * - `{ amount, currency }` = fiat envelope; the SDK converts to sats at
-     * send-time via its centralised fx fetcher. v1 supports `currency: "usd"`
-     * only; other currencies throw `UnsupportedCurrencyError`.
-     *
-     * The legacy `string` form (`"$0.05"`) was removed in under the
-     * project's no-shims convention. Migrate callers to the fiat envelope.
+     * Request payment; resolves when the ask is satisfied by the upfront pool or a payment.
+     * Numbers are millisatoshis. Fiat envelopes use major units in the supplied
+     * supported currency; the ledger pin is converted into the job's denomination.
+     * x402 is offered only for USD; other configured rails can use supported FX currencies.
      */
     requestPayment(amount: number | {
         amount: number;
@@ -5673,7 +4934,7 @@ interface SDKJobContext<State = Record<string, unknown>, Input = string> {
     step<T>(id: string, fn: () => Promise<T>): Promise<T>;
     /** Per-job typed state, auto-loaded and auto-persisted. */
     state: State;
-    /** Persistent cross-job KV storage. */
+    /** Persistent storage shared across jobs. */
     store: KVStore;
     /**
      * Instrumented fetch — emits `dvm.fetch` spans with redacted URLs, and
@@ -5690,17 +4951,14 @@ interface SDKJobContext<State = Record<string, unknown>, Input = string> {
      * / `ctx.fail` are no-ops: the job stays `cancelled`.
      */
     readonly signal: AbortSignal;
-    /** Environment variables configured by the operator. */
     env: Record<string, string>;
     log: Logger;
 }
-/** Context provided to the onQuote handler. */
 interface QuoteContext<QuoteData = Record<string, unknown>> {
-    /** Parsed quote data — typed when a Zod schema is provided. */
+    /** Quote data, parsed by the configured Zod schema when present. */
     data: QuoteData;
-    /** Raw input string from the client, if provided. */
+    /** The client's raw input string, when supplied. */
     input?: string;
-    /** Job parameters from the client, if provided. */
     params?: Record<string, string>;
     /**
      * Operator environment — same object threaded into `JobContext.env`.
@@ -5822,14 +5080,10 @@ interface QuoteResult {
         max_units?: number;
     };
 }
-/** Quote handler configuration with a Zod schema for structured quote data. */
 interface QuoteConfig<QuoteData = Record<string, unknown>> {
-    /** Schema describing the data clients must provide for a quote. */
     schema: ZodLike<QuoteData> | Record<string, unknown>;
-    /** Compute a price based on the structured quote data. */
     handler(ctx: QuoteContext<QuoteData>): Promise<QuoteResult>;
 }
-/** Incoming message shape for the onMessage catch-all handler. */
 interface IncomingMessage {
     /** Message type (e.g. "response", "payment", "approval", "cancel"). */
     type: MessageType;
@@ -5846,7 +5100,6 @@ interface IncomingMessage {
  * the SDK converts at request time.
  */
 type PriceValue = string;
-/** Accepted payment rail identifier. */
 type PaymentMethod = "cashu" | "x402" | "tempo";
 /**
  * Rails that may fund a prepaid **credit**.
@@ -6263,11 +5516,9 @@ interface DVMDescriptor<State = Record<string, unknown>, InputSchema extends Zod
     readonly auth?: DVMAuthScheme;
 }
 
-/** Serializable record of a completed step. */
 interface StepRecord {
     /** Step identifier (must be unique within a job). */
     id: string;
-    /** Cached return value of the step function. */
     value: unknown;
     /** Cost declarations made while the step body ran, replayed on cache hits. */
     costs?: JobCost[];
@@ -6283,14 +5534,10 @@ interface StepRecord {
 declare class StepCache {
     private cache;
     has(id: string): boolean;
-    /** Get a cached step result. Throws if not present. */
     get(id: string): unknown;
-    /** Get a cached step record, including replay metadata. Throws if not present. */
     getRecord(id: string): StepRecord;
     set(id: string, value: unknown, costs?: readonly JobCost[]): void;
-    /** Export all cached steps for persistence. */
     serialize(): StepRecord[];
-    /** Restore a StepCache from persisted records. */
     static deserialize(records: StepRecord[]): StepCache;
 }