@dvmkit/sdk 0.1.5-rc.9 → 0.2.1-rc.9

package/dist/server/index.d.ts

@@ -1,26 +1,25 @@
-import { ab as CashuMode, bK as CreditDrainEnqueue, R as ResolvedCreditConfig, bL as DVMAuthScheme, z as SignedRequestDomain, bM as CreditLedgerLike, bN as X402RefundSettlementGate, bO as CreditSnapshot, bP as DrawResult, bQ as X402SettlementStatus, bR as X402UnresolvedRefund, bS as GrownDrawResult, bT as DrawResolution, bU as FundingRecord, X as FundingReceipt, bV as CreditInvoiceRecord, bW as InvoiceSettlement, bX as BlockedInvoiceCursor, bY as InvoiceReconciliation, bZ as InvoiceWriteOff, b_ as DrawRecord, b$ as StalePendingDrawCursor, c0 as TempoCreditLossEvidence, c1 as CreditLedgerQuerier, c2 as TempoCreditLoss, c3 as X402CreditLossEvidence, c4 as X402CreditLoss, c5 as DrainMethod, c6 as DrainRequestResult, c7 as BitcoinDepositLiability, bo as FundingLot, c8 as CreditDrainRecord, c9 as ChannelDrainCursor, ca as DrainWriteOff, cb as DrainReleaseResult, cc as DrainFulfilment, cd as DrainTransitionResult, Y as JobReceipt, a1 as Message, K as KVStore, F as SignedRequestReplayStore, Z as ZodLike, a as DVMDescriptor } from '../step-cache-5dljDqrQ.js';
-export { ce as CLIENT_COMPATIBILITY_HEADERS, d as CanonicalEnvelope, cf as ClientCompatibility, cg as ClientCompatibilityEnv, ch as ClientCompatibilityGate, ci as ClientCompatibilityRequirement, cj as ClientSemVer, e as CreateSignedRequestVerifierOpts, ck as CreditFundingBasis, cl as CreditInvoiceStatus, cm as CreditLedger, cn as CreditLedgerError, co as CreditLedgerErrorCode, cp as CreditLedgerErrorDetails, cq as CreditLedgerPool, cr as CreditStatus, cs as DRAIN_DELIVERY_RESERVE_SATS, ct as DVM_PROTOCOL_VERSION, cu as DrainConflictReason, cv as DrawRailValue, cw as DrawStatus, cx as JobCostReportPayload, cy as PostgresX402ChannelStorage, cz as ReplayStoreBackend, cA as RevenueSkippedNoRailPayload, cB as RevenueSkippedNoRailReason, w as SIGNED_REQUEST_AUTH_ID, x as SIGNED_REQUEST_STATEMENT_VERSION, cC as Secp256k1AuthOpts, y as SignedRequestAudience, B as SignedRequestError, E as SignedRequestFailure, G as SignedRequestSignOpts, H as SignedRequestStatementHeader, M as SignedRequestVerifier, cD as X402ChannelStorageOpts, cE as X402RelayLockHolder, cF as X402RelaySubmissionLock, cG as X402RelaySubmissionLockError, cH as allocateDrawValue, cI as clientCompatibilityAttributes, cJ as clientCompatibilityMiddleware, cK as clientUpgradeRequired, N as createSignedRequestVerifier, cL as parseClientCapabilities, cM as parseClientCompatibility, cN as parseDvmClient, cO as parseProtocolVersion, cP as requireClientCompatibility, cQ as secp256k1Auth, cR as signedRequestInput, T as signedRequestStatementHeader } from '../step-cache-5dljDqrQ.js';
+import { ab as CashuMode, bK as CreditDrainEnqueue, R as ResolvedCreditConfig, bL as DVMAuthScheme, z as SignedRequestDomain, bM as CreditLedgerLike, bN as X402RefundSettlementGate, bO as CreditSnapshot, bP as DrawResult, bQ as X402SettlementStatus, bR as X402UnresolvedRefund, bS as GrownDrawResult, bT as DrawResolution, bU as FundingRecord, X as FundingReceipt, bV as CreditInvoiceRecord, bW as InvoiceSettlement, bX as BlockedInvoiceCursor, bY as InvoiceReconciliation, bZ as InvoiceWriteOff, b_ as DrawRecord, b$ as StalePendingDrawCursor, c0 as TempoCreditLossEvidence, c1 as CreditLedgerQuerier, c2 as TempoCreditLoss, c3 as X402CreditLossEvidence, c4 as X402CreditLoss, c5 as DrainMethod, c6 as DrainRequestResult, c7 as BitcoinDepositLiability, bo as FundingLot, c8 as CreditDrainRecord, c9 as ChannelDrainCursor, ca as DrainWriteOff, cb as DrainReleaseResult, cc as DrainFulfilment, cd as DrainTransitionResult, Y as JobReceipt, a1 as Message, K as KVStore, F as SignedRequestReplayStore, Z as ZodLike, a as DVMDescriptor } from '../step-cache-v2yhyhSZ.js';
+export { ce as CLIENT_COMPATIBILITY_HEADERS, d as CanonicalEnvelope, cf as ClientCompatibility, cg as ClientCompatibilityEnv, ch as ClientCompatibilityGate, ci as ClientCompatibilityRequirement, cj as ClientSemVer, e as CreateSignedRequestVerifierOpts, ck as CreditFundingBasis, cl as CreditInvoiceStatus, cm as CreditLedger, cn as CreditLedgerError, co as CreditLedgerErrorCode, cp as CreditLedgerErrorDetails, cq as CreditLedgerPool, cr as CreditStatus, cs as DRAIN_DELIVERY_RESERVE_SATS, ct as DVM_PROTOCOL_VERSION, cu as DrainConflictReason, cv as DrawRailValue, cw as DrawStatus, cx as JobCostReportPayload, cy as JobTerminalReportPayload, cz as PostgresX402ChannelStorage, cA as ReplayStoreBackend, cB as RevenueSkippedNoRailPayload, cC as RevenueSkippedNoRailReason, w as SIGNED_REQUEST_AUTH_ID, x as SIGNED_REQUEST_STATEMENT_VERSION, cD as Secp256k1AuthOpts, y as SignedRequestAudience, B as SignedRequestError, E as SignedRequestFailure, G as SignedRequestSignOpts, H as SignedRequestStatementHeader, M as SignedRequestVerifier, cE as X402ChannelStorageOpts, cF as X402RelayLockHolder, cG as X402RelaySubmissionLock, cH as X402RelaySubmissionLockError, cI as allocateDrawValue, cJ as clientCompatibilityAttributes, cK as clientCompatibilityMiddleware, cL as clientUpgradeRequired, N as createSignedRequestVerifier, cM as parseClientCapabilities, cN as parseClientCompatibility, cO as parseDvmClient, cP as parseProtocolVersion, cQ as requireClientCompatibility, cR as secp256k1Auth, cS as signedRequestInput, T as signedRequestStatementHeader } from '../step-cache-v2yhyhSZ.js';
 import { Pool } from 'pg';
-import { ak as CreditMenu, b as AppEnv, U as UpfrontPaymentOpts, h as PaymentInfo, al as ReceiptIssuer, am as LightningReceive, an as TempoSettlementReadiness, ao as DVMHostOpts, ap as DVMServeResult } from '../credit-menu-enwMbn55.js';
-export { aq as BuildCreditMenuArgs, ar as BuilderIdentity, as as CREDIT_ENVELOPE_KEYS, C as ConsumedCredentialStore, at as CreateX402BatchSettlementServerOpts, au as CreditEnvelope, av as CreditEnvelopeError, aw as CreditFundCommitment, ax as CreditTerms, ay as DEFAULT_INVOICE_TTL_SECONDS, az as DVMHost, aA as JobManager, aB as JobManagerOpts, aC as LightningReceiveConfig, aD as MIN_INVOICE_TTL_SECONDS, aE as MemoryConsumedCredentialStore, aF as MemoryConsumedCredentialStoreOpts, aG as MemoryProcessedPaymentStore, aH as MemoryX402ExactSettlementStore, aI as MountOpts, aJ as OwnerDisplay, aK as PaidJobCompletion, aL as PaymentMode, aM as PlatformReporterOpts, aN as PostgresProcessedPaymentStore, aO as PostgresX402ExactSettlementStore, aP as PriceFiat, aQ as ProcessedPaymentQuerier, aR as ProcessedPaymentRail, aS as ProcessedPaymentRecord, aT as ProcessedPaymentReplayError, aU as ProcessedPaymentStore, aV as X402BatchAcceptance, aW as X402BatchFunding, aX as X402BatchRefusal, aY as X402BatchSettlementServer, aZ as X402ExactAcceptance, a_ as X402ExactIntentConflictError, a$ as X402ExactSettlementAttempt, b0 as X402ExactSettlementChainEvidence, b1 as X402ExactSettlementEffect, b2 as X402ExactSettlementEvidenceMissingError, b3 as X402ExactSettlementEvidenceReader, b4 as X402ExactSettlementIntent, b5 as X402ExactSettlementNotReadyError, b6 as X402ExactSettlementServer, b7 as X402ExactSettlementServerOpts, b8 as X402ExactSettlementStatus, b9 as X402ExactSettlementStore, ba as X402SettlementChainEvidence, bb as X402SettlementEvidenceReader, bc as X402SettlementSubmissionError, bd as X402_BATCH_AUTO_SETTLEMENT, be as X402_BATCH_MIN_WITHDRAW_DELAY_SECONDS, bf as X402_BATCH_SETTLEMENT_NETWORK, bg as attachCreditMenu, bh as buildCreditMenu, bi as createDVMHost, bj as createX402BatchSettlementServer, bk as creditEnvelopeIgnoreFields, bl as drawSettlementRef, bm as extractCreditEnvelope, bn as fundingCommitment, bo as selectPrimaryCredit, bp as stripCreditEnvelope, bq as toCreditView } from '../credit-menu-enwMbn55.js';
+import { ak as CreditMenu, b as AppEnv, U as UpfrontPaymentOpts, h as PaymentInfo, al as ReceiptIssuer, am as LightningReceive, an as TempoSettlementReadiness, ao as DVMHostOpts, ap as DVMServeResult } from '../credit-menu-kDA9RVzD.js';
+export { aq as BuildCreditMenuArgs, ar as BuilderIdentity, as as CREDIT_ENVELOPE_KEYS, C as ConsumedCredentialStore, at as CreateX402BatchSettlementServerOpts, au as CreditEnvelope, av as CreditEnvelopeError, aw as CreditFundCommitment, ax as CreditTerms, ay as DEFAULT_INVOICE_TTL_SECONDS, az as DVMHost, aA as JobManager, aB as JobManagerOpts, aC as LightningReceiveConfig, aD as MIN_INVOICE_TTL_SECONDS, aE as MemoryConsumedCredentialStore, aF as MemoryConsumedCredentialStoreOpts, aG as MemoryProcessedPaymentStore, aH as MemoryX402ExactSettlementStore, aI as MountOpts, aJ as OwnerDisplay, aK as PaidJobCompletion, aL as PaymentMode, aM as PlatformReporterOpts, aN as PostgresProcessedPaymentStore, aO as PostgresX402ExactSettlementStore, aP as PriceFiat, aQ as ProcessedPaymentQuerier, aR as ProcessedPaymentRail, aS as ProcessedPaymentRecord, aT as ProcessedPaymentReplayError, aU as ProcessedPaymentStore, aV as X402BatchAcceptance, aW as X402BatchFunding, aX as X402BatchRefusal, aY as X402BatchSettlementServer, aZ as X402ExactAcceptance, a_ as X402ExactIntentConflictError, a$ as X402ExactSettlementAttempt, b0 as X402ExactSettlementChainEvidence, b1 as X402ExactSettlementEffect, b2 as X402ExactSettlementEvidenceMissingError, b3 as X402ExactSettlementEvidenceReader, b4 as X402ExactSettlementIntent, b5 as X402ExactSettlementNotReadyError, b6 as X402ExactSettlementServer, b7 as X402ExactSettlementServerOpts, b8 as X402ExactSettlementStatus, b9 as X402ExactSettlementStore, ba as X402SettlementChainEvidence, bb as X402SettlementEvidenceReader, bc as X402SettlementSubmissionError, bd as X402_BATCH_AUTO_SETTLEMENT, be as X402_BATCH_MIN_WITHDRAW_DELAY_SECONDS, bf as X402_BATCH_SETTLEMENT_NETWORK, bg as attachCreditMenu, bh as buildCreditMenu, bi as createDVMHost, bj as createX402BatchSettlementServer, bk as creditEnvelopeIgnoreFields, bl as drawSettlementRef, bm as extractCreditEnvelope, bn as fundingCommitment, bo as selectPrimaryCredit, bp as stripCreditEnvelope, bq as toCreditView } from '../credit-menu-kDA9RVzD.js';
 import { Context } from 'hono';
 import { z } from 'zod';
-import { F as FxFetcher } from '../fx-D860pZvP.js';
-import { c as StreamableJobStore, R as ReceiptIssuingStore, J as JobRecord, d as RequestIdClaim, e as RequestIdClaimResult, f as JobRetentionCursor, O as OutgoingMessage, A as AppendOutgoingOptions, P as PaymentCreditDelta, V as VerifyAndCreditResult, g as JobCounters } from '../job-store-BUGqvCfL.js';
-export { a as JobStatus, b as JobStore, h as isStreamableJobStore } from '../job-store-BUGqvCfL.js';
-export { P as PinnedFetch, S as SSRFError, a as SSRFGuardOpts, b as SSRFReason, c as SSRFResolver, d as assertSafeUrl, e as createPinnedFetch } from '../ssrf-DbFkpDv0.js';
+import { F as FxFetcher } from '../fx-DhyT1Cjh.js';
+import { c as StreamableJobStore, R as ReceiptIssuingStore, J as JobRecord, d as RequestIdClaim, e as RequestIdClaimResult, f as JobRetentionCursor, O as OutgoingMessage, A as AppendOutgoingOptions, P as PaymentCreditDelta, V as VerifyAndCreditResult, g as JobCounters } from '../job-store-D3CcZp_g.js';
+export { a as JobStatus, b as JobStore, h as isStreamableJobStore } from '../job-store-D3CcZp_g.js';
+export { P as PinnedFetch, S as SSRFError, a as SSRFGuardOpts, b as SSRFReason, c as SSRFResolver, d as assertSafeUrl, e as createPinnedFetch } from '../ssrf-dMooihtY.js';
 import 'mppx';
 import '@x402/core/server';
 import '@x402/evm/batch-settlement/server';
 import 'viem';
 import '@x402/core/types';
 import '@cashu/cashu-ts';
-import '../lightning-backend-BozcevPZ.js';
+import '../lightning-backend-BhsyrBLa.js';
 
 /** Lifetime of a per-call implicit credit before the ledger refuses new draws. */
 declare const IMPLICIT_CREDIT_TTL_MS: number;
 
-/** Builder-lock and Cashu accumulator opts resolved from environment variables. */
 interface ResolvedCashuOpts {
     cashuMode: CashuMode | undefined;
     lockPubkey: string | undefined;
@@ -34,7 +33,7 @@ interface ResolvedCashuOpts {
  * variables, initializing DB tables when their prerequisites are met.
  * Extracted from serve() so DVMs that call createDVMServer directly (cast,
  * scrape) can wire Cashu and the builder admin surface without using the
- * serve() wrapper (internal-review).
+ * serve() wrapper.
  *
  * @param pool - existing Postgres pool to reuse; pass undefined when no DB is available
  * @param cashuModeHint - programmatic override for cashu mode (serve()'s opts.cashuMode)
@@ -42,10 +41,7 @@ interface ResolvedCashuOpts {
 declare function resolveCashuOptsFromEnv(env: Record<string, string>, pool?: Pool, cashuModeHint?: CashuMode): Promise<ResolvedCashuOpts>;
 
 /**
- * What a terminal drain transition needs in order to book its platform drain
- * report (internal-review). Every field is optional because a DVM can legitimately
- * run without platform reporting — a `dvmctl dev` server, a self-hosted
- * builder, a test host — and a drain must still be fulfillable there.
+ * Reporting is optional; an unwired host still runs the money transition.
  */
 interface DrainReportWiring {
     /** The SDK's own Postgres, which holds both the ledger and the reporter's outbox. */
@@ -57,14 +53,8 @@ interface DrainReportWiring {
 }
 
 /**
- * Signed body of a `POST /v1/credit` request (internal-review). The op discriminator
- * lives **inside** the signed bytes, so a network attacker can't rewrite a
- * `balance` read into a `drain`.
- *
- * Deliberately independent of `credit-envelope.ts`, which parses the credit
- * fields riding a `/v1/job` body: that shape pairs `credit_id` with a
- * mandatory `draw_id`, and a fund-only top-up has no draw. Two routes, two
- * schemas — sharing one would force a top-up to invent a draw id.
+ * Authenticate the raw body, including op. Its schema is independent of job-input credit/draw
+ * envelopes; normal job schema projection must not define this wire contract.
  */
 declare const CREDIT_REQUEST_SCHEMA: z.ZodObject<{
     op: z.ZodEnum<{
@@ -99,83 +89,48 @@ declare const CREDIT_REQUEST_SCHEMA: z.ZodObject<{
     timestamp: z.ZodNumber;
     nonce: z.ZodString;
 }, z.core.$strip>;
-/** Parsed `/v1/credit` body. */
 type CreditRequest = z.infer<typeof CREDIT_REQUEST_SCHEMA>;
-/** Everything the `/v1/credit` handler needs from the server that mounts it. */
 interface CreditRouteDeps {
-    /** Resolved credit sizing, or `undefined` when this DVM didn't opt in. */
     menu: () => Promise<CreditMenu | undefined>;
-    /** Resolved builder policy; absent and older config fail closed. */
     creditConfig: ResolvedCreditConfig | undefined;
     auth: DVMAuthScheme | undefined;
     /** Exact `/v1/credit` audience and operation expected by the auth gate. */
     authDomain?: SignedRequestDomain;
     ledger: CreditLedgerLike;
     fxFetcher: FxFetcher;
-    /** Per-DVM + per-request rail wiring, shared with `/v1/job` (see `railVerifyOpts`). */
     railOpts: (c: Context<AppEnv>) => Promise<UpfrontPaymentOpts>;
     /**
-     * Book a committed top-up as a platform deposit (internal-review). A fund-only
-     * top-up moves real money onto a credit whose draws will each book revenue
-     * later, so skipping this would report the spending without the money that
-     * backed it — the DVM's outstanding liability would go negative.
+     * Report committed fund-only top-ups as deposits. They have no job terminal to book the
+     * liability; replay must not report it twice.
      */
     onDeposit: (funding: NonNullable<PaymentInfo["funding"]>) => void;
     /**
-     * Platform drain-report wiring (internal-review), used by the cashu pickup — the
-     * one terminal drain transition that lands on this caller-facing route.
-     * Empty on a DVM with no platform reporting, which changes nothing about
-     * the reclaim itself.
+     * Optional terminal drain report wiring: Cashu pickup and channel completion commit their
+     * ledger transition with its report.
      */
     drainReport: DrainReportWiring;
     /**
-     * Receipt signer, when this DVM has a receipt key (internal-review). Drain ops
-     * countersign every reclaim event with it (internal-review); absent, drains still
-     * work — the ledger stays authoritative, the caller just gets no portable
-     * evidence artifact.
+     * Optional signer for reclaim observations. The ledger transition remains authoritative;
+     * signature issuance happens after commit and may fail separately.
      */
     receiptIssuer: ReceiptIssuer | undefined;
     /**
-     * The Lightning receive leg, when this DVM configured one (internal-review).
-     * Absent ⇒ `method: "lightning"` is refused with `lightning_unavailable`
-     * and the funding menu never advertised it in the first place.
-     *
-     * Only the *issue* path reaches through this. Settling goes via
-     * {@link settleLightning}, which is where a settlement books its deposit.
+     * Optional receive-only Lightning funding leg. Issuance uses the wallet; polling uses the
+     * shared settlement hook. An absent leg refuses method:lightning.
      */
     lightning: {
         receive: LightningReceive;
     } | undefined;
     /**
      * Apply any Lightning invoice this caller has paid since the last check, and
-     * book the deposit for each one that credits (internal-review). A no-op when the
+     * book the deposit for each one that credits. A no-op when the
      * rail isn't configured. Runs before the read ops so a balance reflects a
      * top-up that settled out of band, and behind the fund poll so a sibling
      * invoice on the same credit is swept with it.
      */
     settleLightning: (callerPubkey: string, creditId?: string) => Promise<void>;
-    /** Hosted operator fee-token gate; absent on self-hosted DVMs. */
     tempoSettlementReadiness?: TempoSettlementReadiness;
 }
-/**
- * `POST /v1/credit` — the caller-facing surface of the credits settlement
- * layer (internal-review, spec §4/§7). Three ops on one signed, replay-protected
- * envelope, mirroring `/v1/job`'s auth discipline exactly:
- *
- * - **fund** — a top-up with no job attached. The rail artifact rides the same
- *   headers as `/v1/job` (`X-Cashu` + `X-Cashu-Request-Id`, `X-PAYMENT`,
- *   `Authorization: Payment …`) and a missing or bad one comes back as the
- *   same 402 envelope, which is what lets a caller's existing resumable-submit
- *   machinery drive a top-up with no new client code.
- * - **balance** — what do I hold here, including expired credits (their value
- *   is still the caller's; spec §5), plus the funding menu, so the same read
- *   also answers what may be added (internal-review).
- * - **drain** — reclaim the unspent balance (internal-review, spec §5 tier 3). One
- *   op is both the request and the poll/pickup: the first call debits the
- *   available balance into a `pending` liability; re-polling the same
- *   `drain_id` returns the current state, delivers the parked Cashu token
- *   when the builder's batch job has parked it, and is idempotent throughout.
- */
 declare function handleCreditRequest(c: Context<AppEnv>, deps: CreditRouteDeps): Promise<Response>;
 
 /**
@@ -192,70 +147,29 @@ type InitLockPool = Pick<Pool, "connect"> & {
     };
 };
 /**
- * The single session advisory-lock key serializing **all** SDK boot-time
- * schema work against concurrent creators — two machines cold-booting one DVM
- * against a fresh database, or parallel test files sharing one DB.
- *
- * Postgres' `IF NOT EXISTS` existence check is not atomic against a concurrent
- * creator: two sessions running the same `CREATE TABLE IF NOT EXISTS` at once
- * can raise `duplicate key value violates unique constraint
- * "pg_type_typname_nsp_index"` (23505) in the loser, which at SDK boot is an
- * unhandled throw that kills the machine (internal-review).
- *
- * Deliberately distinct from `PLATFORM_INIT_ADVISORY_LOCK` (17320917) — a
- * DVM's own database is not the platform database — and from the first-party
- * DVMs' own keys (cast 17320918, scrape 17320926, scribe 24700919). **A new
- * SDK store reuses this key rather than inventing a second one**: one key means
- * there is only ever one lock order, so the per-store lock-order inversion that
- * deadlocked internal-review can't recur.
+ * All SDK boot DDL shares one advisory-lock key. CREATE TABLE IF NOT EXISTS
+ * can still race in Postgres system catalogs across machines. Reusing one key
+ * also prevents inconsistent lock acquisition order between SDK stores.
  */
 declare const SDK_INIT_ADVISORY_LOCK = 17320927;
 /**
- * Run `fn` holding {@link SDK_INIT_ADVISORY_LOCK} on `db`. Every SDK
- * boot-path `CREATE TABLE IF NOT EXISTS` goes through here.
- *
- * Overlapping callers on the same pool share **one** acquisition: the first
- * connects and locks, concurrent and nested callers join the held lock, and
- * the last one out unlocks and releases the client. That keeps internal-review's
- * deliberately-parallel store-init batch parallel — six `init()`s racing each
- * other would otherwise queue behind one another — and keeps the uncontended
- * cost at one extra round trip per boot phase rather than one per store.
- * Sharing is safe for the DDL, which is what this lock is for: it excludes
- * *other machines*, and within one process no two inits create the same table.
- * It is not by itself a mutex between same-pool callers — two of them
- * concurrently running one non-idempotent statement still race, so anything
- * riding this lock that isn't `CREATE … IF NOT EXISTS` must carry its own
- * conflict handling (`seedLockPubkeyState`'s `ON CONFLICT DO NOTHING`).
- *
- * Session-level (not `pg_advisory_xact_lock`) because the DDL runs in
- * autocommit with no enclosing transaction, so the lock and the unlock ride a
- * dedicated pinned client — advisory locks are session-scoped and the unlock
- * must land on the backend that holds it. Released in `finally` on every path
- * including throws: an SDK boot that died holding this lock would block every
- * sibling until its connection closed.
- *
- * The guarded DDL runs on the pool's *other* connections, so the pool must
- * allow at least two — `pg`'s default `max` is 10 and the host never narrows
- * it, but a builder-supplied `Pool({ max: 1 })` would starve boot. That one
- * deadlocks with no error and reads as a dead database, so it is refused up
- * front instead.
+ * Overlapping callers on one pool share a pinned session lock and run their
+ * guarded work in order. A nested call from the active callback is reentrant.
+ * The last caller unlocks, preserving protection against other pools/processes.
+ * DDL runs on another connection; pools smaller than two are rejected.
+ * The pinned client is released in finally, including guarded failures.
  */
 declare function withSdkInitLock<T>(db: InitLockPool, fn: () => Promise<T>): Promise<T>;
 
 /**
- * In-memory {@link CreditLedgerLike} for pool-less setups — devMode, direct
- * `createDVMServer` tests, and the in-process x402 money loop — mirroring the
- * `MemoryJobStore` precedent. Same semantics as the Postgres `CreditLedger`
- * (two-phase draws, replay-before-expiry, `draw_conflict`, gap-free
- * `ledger_seq`), minus durability and cross-machine safety: per-process only,
- * so production DVMs must use the Postgres ledger (spec §2 condition 2).
- * Every mutating verb is synchronous between awaits, so operations are
- * atomic in-process; the `tx` handles are accepted and ignored.
+ * Per-process development/test ledger without durability or cross-machine safety. Mutations
+ * run synchronously between awaits; accepted tx handles are ignored. Production funding
+ * requires a durable ledger.
  */
 declare class MemoryCreditLedger implements CreditLedgerLike {
     /**
      * Per-process and lost on restart, so a DVM backed by this ledger never
-     * advertises the funding menu outside devMode (internal-review) — funding on one
+     * advertises the funding menu outside devMode — funding on one
      * machine and drawing on another would `credit_not_found`.
      */
     readonly durable = false;
@@ -267,13 +181,10 @@ declare class MemoryCreditLedger implements CreditLedgerLike {
     private x402Settlements?;
     /** Internal disposable transaction snapshot. The caller must serialize every ledger access. */
     forkForTransaction(): MemoryCreditLedger;
-    /** See {@link CreditLedger.useX402SettlementGate} — same contract (internal-review). */
     useX402SettlementGate(gate: X402RefundSettlementGate): void;
     fund(args: Parameters<CreditLedgerLike["fund"]>[0]): Promise<CreditSnapshot>;
     draw(args: Parameters<CreditLedgerLike["draw"]>[0]): Promise<DrawResult>;
-    /** See {@link CreditLedger.blockingX402Refund} — same contract (internal-review). */
     blockingX402Refund(channelId: string | null | undefined, statuses: X402SettlementStatus[]): Promise<X402UnresolvedRefund | undefined>;
-    /** The unresolved x402 refund that must stop an effect on `creditId` (internal-review). */
     private blockingRefundForCredit;
     growDraw(args: Parameters<CreditLedgerLike["growDraw"]>[0]): Promise<GrownDrawResult>;
     settle(args: Parameters<CreditLedgerLike["settle"]>[0]): Promise<DrawResolution>;
@@ -320,7 +231,6 @@ declare class MemoryCreditLedger implements CreditLedgerLike {
     private findByPaymentHash;
     private fundSync;
     private drawSync;
-    /** Mid-job top-up growth (internal-review) — see `CreditLedger.growDraw` for the semantics. */
     private growDrawSync;
     get(creditId: string, opts?: {
         nowMs?: number;
@@ -340,7 +250,6 @@ declare class MemoryCreditLedger implements CreditLedgerLike {
         limit: number;
         after?: StalePendingDrawCursor;
     }): Promise<DrawRecord[]>;
-    /** Settled draws' native value for the credit an x402 channel funded (internal-review). */
     earnedNativeForX402Channel(channelId: string): Promise<number | undefined>;
     getCreditByX402Channel(channelId: string): Promise<CreditSnapshot | undefined>;
     terminalizeTempoCredits(evidence: TempoCreditLossEvidence, _tx?: CreditLedgerQuerier): Promise<TempoCreditLoss[]>;
@@ -435,11 +344,10 @@ declare class PostgresJobStore implements StreamableJobStore, ReceiptIssuingStor
     constructor(pool: Pool);
     /** Run the CREATE TABLE migration. Call once at startup. */
     init(): Promise<void>;
-    /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
     private createTables;
     get(id: string): Promise<JobRecord | undefined>;
     /**
-     * internal-review. Indexed by `idx_jobs_payment_tx_hash`. `paymentTxHash` is unique
+     * Indexed by `idx_jobs_payment_tx_hash`. `paymentTxHash` is unique
      * per settlement in practice — the accumulator's
      * `UNIQUE(dvm_id, request_id, proof_secret)` is what makes a second job under
      * the same request id impossible — but order by `created_at` so a
@@ -455,6 +363,10 @@ declare class PostgresJobStore implements StreamableJobStore, ReceiptIssuingStor
     /** Persist a job while retaining its mount identity for cost-report recovery. */
     saveForDvm(record: JobRecord, dvmId: string): Promise<void>;
     private saveRecord;
+    /** Advance only after the reporter durably enqueued or deduplicated the event. */
+    markTerminalReported(jobId: string): Promise<void>;
+    /** Bounded crash recovery for terminal events not yet queued. */
+    listUnreportedTerminalReports(dvmId: string, capabilities: string[] | null, afterJobId?: string): Promise<JobRecord[]>;
     /**
      * Read terminal zero-revenue jobs whose latest declared-cost revision has
      * not yet reached the durable reporter outbox.
@@ -520,7 +432,7 @@ declare class PostgresJobStore implements StreamableJobStore, ReceiptIssuingStor
     private terminateJob;
     private fetchCountersTx;
     /**
-     * The credit binding on the job row, read inside Tx C (internal-review). Used on the
+     * The credit binding on the job row, read inside Tx C. Used on the
      * paths that don't get it from a `RETURNING` — the `alreadyVerified` skip and
      * a non-payment inbound.
      */
@@ -530,17 +442,14 @@ declare class PostgresJobStore implements StreamableJobStore, ReceiptIssuingStor
 /**
  * Postgres-backed KVStore. Requires the `pg` package as a peer dependency.
  *
- * Expired rows are filtered on read but never deleted. A periodic cleanup
- * mechanism (e.g. `DELETE FROM kv_store WHERE expires_at IS NOT NULL AND
- * expires_at < now()`) should be added before production use to prevent
- * unbounded table growth.
+ * Expired rows are filtered on read and list, but never deleted; callers
+ * must arrange their own cleanup to bound physical storage.
  */
 declare class PostgresKVStore implements KVStore {
     private pool;
     constructor(pool: Pool);
     /** Run the CREATE TABLE migration. Call once at startup. */
     init(): Promise<void>;
-    /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
     private createTables;
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown, opts?: {
@@ -550,7 +459,6 @@ declare class PostgresKVStore implements KVStore {
     list(prefix?: string): Promise<string[]>;
 }
 
-/** Options for `PostgresReplayStore`. */
 interface PostgresReplayStoreOpts {
     /** Table name. Defaults to `"signed_request_replays"`. Must match `/^[a-zA-Z_][a-zA-Z0-9_]*$/`. */
     tableName?: string;
@@ -568,16 +476,8 @@ interface PostgresReplayStoreOpts {
     gcSampleRate?: number;
 }
 /**
- * Postgres-backed replay store implementing {@link SignedRequestReplayStore}.
- *
- * Cross-machine safe: relies on the PK on `(pubkey, timestamp, nonce)` with
- * `INSERT ... ON CONFLICT DO NOTHING` to detect duplicates atomically across
- * concurrent inserts from multiple machines. The consumer hands in a `Pool`
- * (matching `PostgresJobStore` / `PostgresKVStore`) and manages its lifecycle.
- *
- * Multi-machine deploys of secp256k1-auth'd DVMs SHOULD use this store to
- * close the per-process replay window — see {@link SignedRequestReplayStore}
- * for the threat model.
+ * The (pubkey, timestamp, nonce) primary key detects concurrent duplicates
+ * atomically across machines. The caller owns the pool lifecycle.
  */
 declare class PostgresReplayStore implements SignedRequestReplayStore {
     private pool;
@@ -587,7 +487,7 @@ declare class PostgresReplayStore implements SignedRequestReplayStore {
     constructor(pool: Pool, opts?: PostgresReplayStoreOpts);
     /** Run the CREATE TABLE migration. Idempotent — safe to call repeatedly. */
     init(): Promise<void>;
-    /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
+    /** The boot DDL itself — always runs under {@link withSdkInitLock}. */
     private createTables;
     checkAndRecord(pubkey: string, timestamp: number, nonce: string, now: number): Promise<boolean>;
     private gcSweep;
@@ -601,21 +501,9 @@ declare function protocolEnvelopeIgnoreFields(schema: unknown): readonly string[
 declare function stripProtocolEnvelope(schema: unknown, data: unknown): unknown;
 /** Read and validate the optional recovery id from a signed request body. */
 declare function requestIdFromEnvelope(data: unknown): string | undefined;
-/** True when the request body carries a request id field but its value is invalid. */
 declare function hasInvalidRequestId(data: unknown): boolean;
 
-/**
- * Convenience one-liner over {@link createDVMHost} (internal-review). For
- * single-DVM hosts, `serve(dvm, opts)` is equivalent to
- * `createDVMHost(opts).mount(dvm).serve()`. Multi-DVM hosts go through
- * `createDVMHost` directly so each mount can carry its own prefix.
- *
- * This is **shorthand-over-host**, not a parallel code path — every wiring
- * step (Cashu/MPP/x402 envelope resolution, platform reporter, db, fx) flows
- * through `createDVMHost`. First-party DVMs that use `serve(...)` are NOT
- * exposed to the wiring-drift bug class fixed in internal-review/485/511, which was
- * about bypassing the host entirely. There is no migration to do.
- */
+/** Single-DVM host. Use createDVMHost for multiple mounts with distinct prefixes. */
 declare function serve<State, InputSchema extends ZodLike | undefined = undefined>(descriptor: DVMDescriptor<State, InputSchema>, opts?: DVMHostOpts): Promise<DVMServeResult>;
 
-export { BlockedInvoiceCursor, CREDIT_REQUEST_SCHEMA, CreditInvoiceRecord, CreditLedgerLike, CreditLedgerQuerier, CreditMenu, type CreditRequest, type CreditRouteDeps, CreditSnapshot, DVMAuthScheme, DVMHostOpts, DVMServeResult, DrawRecord, DrawResolution, DrawResult, FundingRecord, GrownDrawResult, IMPLICIT_CREDIT_TTL_MS, type InitLockPool, InvoiceReconciliation, InvoiceSettlement, InvoiceWriteOff, JobRecord, LightningReceive, MemoryCreditLedger, PostgresJobStore, PostgresKVStore, PostgresReplayStore, type PostgresReplayStoreOpts, REQUEST_ID_FIELD, type ResolvedCashuOpts, SDK_INIT_ADVISORY_LOCK, SignedRequestDomain, SignedRequestReplayStore, StalePendingDrawCursor, StreamableJobStore, handleCreditRequest, hasInvalidRequestId, protocolEnvelopeIgnoreFields, requestIdFromEnvelope, resolveCashuOptsFromEnv, serve, stripProtocolEnvelope, withSdkInitLock };
+export { BitcoinDepositLiability, BlockedInvoiceCursor, CREDIT_REQUEST_SCHEMA, CreditInvoiceRecord, CreditLedgerLike, CreditLedgerQuerier, CreditMenu, type CreditRequest, type CreditRouteDeps, CreditSnapshot, DVMAuthScheme, DVMHostOpts, DVMServeResult, DrawRecord, DrawResolution, DrawResult, FundingRecord, GrownDrawResult, IMPLICIT_CREDIT_TTL_MS, type InitLockPool, InvoiceReconciliation, InvoiceSettlement, InvoiceWriteOff, JobRecord, LightningReceive, MemoryCreditLedger, PostgresJobStore, PostgresKVStore, PostgresReplayStore, type PostgresReplayStoreOpts, REQUEST_ID_FIELD, type ResolvedCashuOpts, SDK_INIT_ADVISORY_LOCK, SignedRequestDomain, SignedRequestReplayStore, StalePendingDrawCursor, StreamableJobStore, handleCreditRequest, hasInvalidRequestId, protocolEnvelopeIgnoreFields, requestIdFromEnvelope, resolveCashuOptsFromEnv, serve, stripProtocolEnvelope, withSdkInitLock };