@dvmkit/sdk 0.1.5-rc.8 → 0.2.0-rc.9

package/dist/server/index.d.ts

@@ -1,21 +1,21 @@
-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-CXg7ziML.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-CXg7ziML.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-s5HmGCqx.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-s5HmGCqx.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-D4Gcdgc4.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-D4Gcdgc4.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-B0SLBe5x.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-B2uZvga4.js';
+export { a as JobStatus, b as JobStore, h as isStreamableJobStore } from '../job-store-B2uZvga4.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-CQBnQgsT.js';
 
 /** Lifetime of a per-call implicit credit before the ledger refuses new draws. */
 declare const IMPLICIT_CREDIT_TTL_MS: number;
@@ -34,7 +34,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)
@@ -43,7 +43,7 @@ declare function resolveCashuOptsFromEnv(env: Record<string, string>, pool?: Poo
 
 /**
  * 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
+ * report. 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.
  */
@@ -57,7 +57,7 @@ interface DrainReportWiring {
 }
 
 /**
- * Signed body of a `POST /v1/credit` request (internal-review). The op discriminator
+ * Signed body of a `POST /v1/credit` request. The op discriminator
  * lives **inside** the signed bytes, so a network attacker can't rewrite a
  * `balance` read into a `drain`.
  *
@@ -115,28 +115,28 @@ interface CreditRouteDeps {
     /** 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
+     * Book a committed top-up as a platform deposit. 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.
      */
     onDeposit: (funding: NonNullable<PaymentInfo["funding"]>) => void;
     /**
-     * Platform drain-report wiring (internal-review), used by the cashu pickup — the
+     * Platform drain-report wiring, 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.
      */
     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
+     * Receipt signer, when this DVM has a receipt key. Drain ops
+     * countersign every reclaim event with it; absent, drains still
      * work — the ledger stays authoritative, the caller just gets no portable
      * evidence artifact.
      */
     receiptIssuer: ReceiptIssuer | undefined;
     /**
-     * The Lightning receive leg, when this DVM configured one (internal-review).
+     * The Lightning receive leg, when this DVM configured one.
      * Absent ⇒ `method: "lightning"` is refused with `lightning_unavailable`
      * and the funding menu never advertised it in the first place.
      *
@@ -148,7 +148,7 @@ interface CreditRouteDeps {
     } | 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.
@@ -159,22 +159,22 @@ interface CreditRouteDeps {
 }
 /**
  * `POST /v1/credit` — the caller-facing surface of the credits settlement
- * layer (internal-review, spec §4/§7). Three ops on one signed, replay-protected
+ * layer (the funding-menu and signed-operation contract). 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.
+ * 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.
+ * is still the caller's), plus the funding menu, so the same read
+ * also answers what may be added.
+ * - **drain** — reclaim the unspent balance (the reclaim contract). 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>;
 
@@ -200,14 +200,14 @@ type InitLockPool = Pick<Pool, "connect"> & {
  * 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).
+ * unhandled throw that kills the machine.
  *
  * 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.
+ * deadlocked can't recur.
  */
 declare const SDK_INIT_ADVISORY_LOCK = 17320927;
 /**
@@ -216,8 +216,7 @@ declare const SDK_INIT_ADVISORY_LOCK = 17320927;
  *
  * 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
+ * the last one out unlocks and releases the client. That keeps * 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
@@ -234,11 +233,8 @@ declare const SDK_INIT_ADVISORY_LOCK = 17320927;
  * 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.
+ * Guarded DDL needs a second connection while the advisory-lock client stays
+ * pinned. Pools with `max < 2` would starve boot and are rejected.
  */
 declare function withSdkInitLock<T>(db: InitLockPool, fn: () => Promise<T>): Promise<T>;
 
@@ -248,14 +244,14 @@ declare function withSdkInitLock<T>(db: InitLockPool, fn: () => Promise<T>): Pro
  * `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).
+ * so production DVMs must use the Postgres ledger (the durable-ledger requirement).
  * Every mutating verb is synchronous between awaits, so operations are
  * atomic in-process; the `tx` handles are accepted and ignored.
  */
 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 +263,13 @@ 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). */
+    /** See {@link CreditLedger.useX402SettlementGate} — same contract. */
     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). */
+    /** See {@link CreditLedger.blockingX402Refund} — same contract. */
     blockingX402Refund(channelId: string | null | undefined, statuses: X402SettlementStatus[]): Promise<X402UnresolvedRefund | undefined>;
-    /** The unresolved x402 refund that must stop an effect on `creditId` (internal-review). */
+    /** The unresolved x402 refund that must stop an effect on `creditId`. */
     private blockingRefundForCredit;
     growDraw(args: Parameters<CreditLedgerLike["growDraw"]>[0]): Promise<GrownDrawResult>;
     settle(args: Parameters<CreditLedgerLike["settle"]>[0]): Promise<DrawResolution>;
@@ -320,7 +316,7 @@ declare class MemoryCreditLedger implements CreditLedgerLike {
     private findByPaymentHash;
     private fundSync;
     private drawSync;
-    /** Mid-job top-up growth (internal-review) — see `CreditLedger.growDraw` for the semantics. */
+    /** Mid-job top-up growth — see `CreditLedger.growDraw` for the semantics. */
     private growDrawSync;
     get(creditId: string, opts?: {
         nowMs?: number;
@@ -340,7 +336,7 @@ declare class MemoryCreditLedger implements CreditLedgerLike {
         limit: number;
         after?: StalePendingDrawCursor;
     }): Promise<DrawRecord[]>;
-    /** Settled draws' native value for the credit an x402 channel funded (internal-review). */
+    /** Settled draws' native value for the credit an x402 channel funded. */
     earnedNativeForX402Channel(channelId: string): Promise<number | undefined>;
     getCreditByX402Channel(channelId: string): Promise<CreditSnapshot | undefined>;
     terminalizeTempoCredits(evidence: TempoCreditLossEvidence, _tx?: CreditLedgerQuerier): Promise<TempoCreditLoss[]>;
@@ -435,11 +431,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 +450,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 +519,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 +529,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 +546,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;
@@ -587,7 +582,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,11 +596,10 @@ 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
+ * Convenience one-liner over {@link createDVMHost}. 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.
@@ -613,7 +607,7 @@ declare function hasInvalidRequestId(data: unknown): boolean;
  * 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
+ * exposed to the wiring-drift bug class fixed in 485/511, which was
  * about bypassing the host entirely. There is no migration to do.
  */
 declare function serve<State, InputSchema extends ZodLike | undefined = undefined>(descriptor: DVMDescriptor<State, InputSchema>, opts?: DVMHostOpts): Promise<DVMServeResult>;

package/dist/server/index.js

@@ -1,12 +1,12 @@
 import {
   PostgresReplayStore
-} from "../chunk-L4OYF4DQ.js";
+} from "../chunk-FT6HTUM4.js";
 import {
   PostgresJobStore
-} from "../chunk-SSSZUVWM.js";
+} from "../chunk-QP53RWAD.js";
 import {
   PostgresKVStore
-} from "../chunk-FROTD5XQ.js";
+} from "../chunk-JLXYOV4Y.js";
 import {
   SSRFError,
   assertSafeUrl,
@@ -21,10 +21,10 @@ import {
   parseNwcUri,
   validateX402Env,
   withNwcPool
-} from "../chunk-CEOAHV2I.js";
+} from "../chunk-FDKRXOZO.js";
 import {
   MemoryKVStore
-} from "../chunk-RW5LP57K.js";
+} from "../chunk-SDK6KDJN.js";
 import {
   AccumulatorReplayError,
   CLIENT_COMPATIBILITY_HEADERS,
@@ -78,16 +78,16 @@ import {
   stripProtocolEnvelope,
   toCreditView,
   unknownRouteNotFound
-} from "../chunk-UB5FZ43T.js";
+} from "../chunk-PCUQZDZA.js";
 import {
   MemoryProcessedPaymentStore,
   PostgresProcessedPaymentStore,
   ProcessedPaymentReplayError
-} from "../chunk-DMNLFNTW.js";
+} from "../chunk-QT4ONTST.js";
 import "../chunk-BQ2NMWKE.js";
 import {
   MemoryCreditLedger
-} from "../chunk-KVEHHC7W.js";
+} from "../chunk-PHHAYRQV.js";
 import {
   SignedRequestError,
   createDefaultReplayStore,
@@ -96,7 +96,7 @@ import {
 } from "../chunk-H2MEFVH6.js";
 import {
   isStreamableJobStore
-} from "../chunk-U6M3ATSG.js";
+} from "../chunk-JDT5LCJC.js";
 import {
   generateEphemeralReceiptKey,
   isTestMintUrl,
@@ -121,10 +121,10 @@ import {
 } from "../chunk-KXZUCCEY.js";
 import {
   initLoggers
-} from "../chunk-E4EVGPDX.js";
+} from "../chunk-XQXJKJ3P.js";
 import "../chunk-66HGCPBU.js";
 import "../chunk-FUJ36YDV.js";
-import "../chunk-27V2ILSR.js";
+import "../chunk-4A2RAKCW.js";
 import "../chunk-AT6V3SY7.js";
 import {
   CreditLedger,
@@ -133,7 +133,7 @@ import {
   PostgresX402ChannelStorage,
   X402RelaySubmissionLockError,
   allocateDrawValue
-} from "../chunk-MLRCSJYX.js";
+} from "../chunk-V7EVFLAK.js";
 import {
   SDK_INIT_ADVISORY_LOCK,
   withSdkInitLock
@@ -147,7 +147,7 @@ import {
   TEMPO_SETTLEMENT_DEFAULT_LOW_BALANCE_MICRO,
   TempoSettlementReadiness,
   resolveTempoNetwork
-} from "../chunk-M7LHFJ5K.js";
+} from "../chunk-KMZXTBLA.js";
 
 // src/sdk/server/cashu-env.ts
 async function resolveCashuOptsFromEnv(env, pool, cashuModeHint) {
@@ -543,7 +543,7 @@ var LightningReceive = class _LightningReceive {
    * Issue (or re-issue) the bolt11 funding `(creditId, fundId)`.
    *
    * The invoice is minted **for** the credit and amount named in the caller's
-   * signed body — that binding is the internal-review condition-3 commitment on this
+   * signed body — that binding is the condition-3 commitment on this
    * rail, and it is why no artifact hash rides the request: there is no
    * caller-supplied artifact to hash. A re-poll returns the stored row rather
    * than minting again; a second bolt11 for one `fund_id` would leave two
@@ -584,7 +584,7 @@ var LightningReceive = class _LightningReceive {
       currency: args.currency,
       // Both amounts are pinned here and never recomputed at settle time: a
       // rate that moved between issuance and payment must not change what the
-      // caller was quoted (the internal-review shape).
+      // caller was quoted (the shape).
       amountMicro: args.amountMicro,
       amountMsats: created.amountMsats || args.amountMsats,
       paymentHash: created.paymentHash,
@@ -593,7 +593,7 @@ var LightningReceive = class _LightningReceive {
     });
   }
   /**
-   * Ask the wallet whether one payment hash is paid, and when (internal-review).
+   * Ask the wallet whether one payment hash is paid, and when.
    *
    * The operator's reconcile verb runs this before it credits anything. A
    * `blocked` row implies payment — {@link applyOne} returns above the block
@@ -683,7 +683,6 @@ var LightningReceive = class _LightningReceive {
     }
     return settled;
   }
-  // ── Internal ───────────────────────────────────────────────────────────
   /**
    * One invoice's settlement check. Returns the applied settlement, or
    * `undefined` when nothing changed (still unpaid, or retired unpaid).
@@ -1181,7 +1180,7 @@ function createDVMHost(opts = {}) {
     const dbRequired = !opts.jobStore && !opts.devMode && !opts.pool;
     if (!databaseUrl && dbRequired) {
       throw new Error(
-        "createDVMHost requires a Postgres database. Pass `database` opt or set DATABASE_URL env. See public design rationale (internal-review)."
+        "createDVMHost requires a Postgres database. Pass `database` opt or set DATABASE_URL env."
       );
     }
     let store = opts.store ?? new MemoryKVStore();
@@ -1200,13 +1199,13 @@ function createDVMHost(opts = {}) {
       });
       applyRetryToPool(pool, "dvm-host");
       pgPool = pool;
-      const { PostgresJobStore: PostgresJobStore2 } = await import("../postgres-job-store-3RAXMNSY.js");
+      const { PostgresJobStore: PostgresJobStore2 } = await import("../postgres-job-store-OGQ6IT4U.js");
       const pgJobStore = new PostgresJobStore2(pool);
       pendingInits.push(pgJobStore.init(), pgJobStore.initStreaming());
       jobStore = pgJobStore;
       pgStreamStore = pgJobStore;
       if (!opts.store) {
-        const { PostgresKVStore: PostgresKVStore2 } = await import("../postgres-kv-store-JFBDP5IP.js");
+        const { PostgresKVStore: PostgresKVStore2 } = await import("../postgres-kv-store-D5E2EZ24.js");
         const pgKvStore = new PostgresKVStore2(pool);
         pendingInits.push(pgKvStore.init());
         store = pgKvStore;
@@ -1238,7 +1237,7 @@ function createDVMHost(opts = {}) {
       if (testMints.length > 0) {
         if (!envFlag(envMaybe.DVMKIT_ALLOW_TEST_MINTS)) {
           throw new Error(
-            `[FATAL] Refusing to boot: platform-hosted DVM configured with test mint(s) [${testMints.join(", ")}]. A test/FakeWallet mint settles no real money \u2014 every payment would silently no-op and revenue would read $0. If this is intentional (dev stack, smoke test, or the staging fleet), set DVMKIT_ALLOW_TEST_MINTS=true. (internal-review)`
+            `[FATAL] Refusing to boot: platform-hosted DVM configured with test mint(s) [${testMints.join(", ")}]. A test/FakeWallet mint settles no real money \u2014 every payment would silently no-op and revenue would read $0. If this is intentional (dev stack, smoke test, or the staging fleet), set DVMKIT_ALLOW_TEST_MINTS=true.`
           );
         }
         console.warn(
@@ -1246,7 +1245,7 @@ function createDVMHost(opts = {}) {
             level: "warn",
             event: "platform_hosted_test_mint_allowed",
             mints: testMints,
-            message: "Platform-hosted DVM booting with test mint(s) because DVMKIT_ALLOW_TEST_MINTS=true \u2014 payments settle no real money. (internal-review)"
+            message: "Platform-hosted DVM booting with test mint(s) because DVMKIT_ALLOW_TEST_MINTS=true \u2014 payments settle no real money."
           })
         );
       }
@@ -1291,11 +1290,11 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
     let tempoChargeBackend = "user-supplied";
     const mppTempoRecipient = envMaybe.DVMKIT_TEMPO_RECIPIENT;
     if (!mpp && mppTempoRecipient) {
-      const { createMppFromOpts, createDualKeyMppxFromOpts, parseMppMethodsAllowlist } = await import("../mpp-setup-4FJD6ZHV.js");
+      const { createMppFromOpts, createDualKeyMppxFromOpts, parseMppMethodsAllowlist } = await import("../mpp-setup-IOJBF7DB.js");
       tempoChargeBackend = pgPool ? "postgres" : "memory";
       let tempoCharge;
       if (pgPool) {
-        const { PostgresTempoChargeStore } = await import("../tempo-charge-store-RIFTALZK.js");
+        const { PostgresTempoChargeStore } = await import("../tempo-charge-store-76TDAF34.js");
         const chargeStore = new PostgresTempoChargeStore(pgPool);
         pendingInits.push(chargeStore.init());
         tempoCharge = { store: chargeStore };
@@ -1372,7 +1371,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
               chain: selectedChain,
               // Trimmed, so a blank DVMKIT_TEMPO_RPC_URL falls back to the
               // chain's bundled endpoint rather than becoming the transport
-              // target (internal-review).
+              // target.
               transport: http(tempoRpc)
             });
           },
@@ -1445,7 +1444,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
       }
     }
     const fxSource = envMaybe.DVMKIT_FX_SOURCE;
-    const { createFxFetcher, resolveFxSourceFromEnv, warmFxSnapshot } = await import("../pricing-4CEB34RM.js");
+    const { createFxFetcher, resolveFxSourceFromEnv, warmFxSnapshot } = await import("../pricing-MU5GNUJZ.js");
     const fxFetcher = opts.fx ?? createFxFetcher({ source: resolveFxSourceFromEnv(envMaybe) });
     const hostRailConfigured = (opts.paymentMethods?.length ?? 0) > 0 || (effectiveMints?.length ?? 0) > 0 || !!x402WithDualServe || !!mpp;
     if (mounts.some((entry) => mountNeedsFx(entry, hostRailConfigured))) warmFxSnapshot(fxFetcher);
@@ -1455,7 +1454,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
     assertReceiptIdentity(envMaybe, opts.builder, receiptKey, cashuOpts.dvmId, opts.devMode);
     let sharedPgReplayStore;
     if (pgPool) {
-      const { PostgresReplayStore: PostgresReplayStore2 } = await import("../postgres-replay-store-UJXRT6VO.js");
+      const { PostgresReplayStore: PostgresReplayStore2 } = await import("../postgres-replay-store-IZFLTTAC.js");
       const store2 = new PostgresReplayStore2(pgPool);
       pendingInits.push(store2.init());
       sharedPgReplayStore = store2;
@@ -1467,7 +1466,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
       const backend = auth.resolveReplayStore ? auth.resolveReplayStore({ postgresStore: sharedPgReplayStore }) : "user-supplied";
       replayStoreSummaries.push({ mount: entry.descriptor.name, backend });
       if (backend === "memory" && !opts.devMode) {
-        const msg = `secp256k1Auth on "${entry.descriptor.name}" fell back to the in-memory replay store. Multi-machine deploys MUST use a cross-machine store (e.g. PostgresReplayStore) \u2014 each machine's per-process window otherwise lets an attacker replay a captured signed envelope once per machine via the load balancer. Set DATABASE_URL or pass \`replayStore\` to secp256k1Auth(). (internal-review)`;
+        const msg = `secp256k1Auth on "${entry.descriptor.name}" fell back to the in-memory replay store. Multi-machine deploys MUST use a cross-machine store (e.g. PostgresReplayStore) \u2014 each machine's per-process window otherwise lets an attacker replay a captured signed envelope once per machine via the load balancer. Set DATABASE_URL or pass \`replayStore\` to secp256k1Auth().`;
         if (failFast) {
           throw new Error(`[FATAL] ${msg}`);
         }
@@ -1483,24 +1482,24 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
     }
     let sharedPgConsumedStore;
     if (pgPool) {
-      const { PostgresConsumedCredentialStore } = await import("../postgres-consumed-credential-store-VHBT4KEA.js");
+      const { PostgresConsumedCredentialStore } = await import("../postgres-consumed-credential-store-ISRHBMOU.js");
       const consumedStore = new PostgresConsumedCredentialStore(pgPool);
       pendingInits.push(consumedStore.init());
       sharedPgConsumedStore = consumedStore;
     }
     if (pgPool) {
-      const { CreditLedger: CreditLedger2 } = await import("../credit-ledger-2DFQHNLB.js");
+      const { CreditLedger: CreditLedger2 } = await import("../credit-ledger-5ZEJRI46.js");
       const pgLedger = new CreditLedger2(pgPool, tempoSessionStore);
       pendingInits.push(pgLedger.init());
       creditLedger = pgLedger;
-      const { PostgresProcessedPaymentStore: PostgresProcessedPaymentStore2 } = await import("../processed-payment-store-HAA4SFNK.js");
+      const { PostgresProcessedPaymentStore: PostgresProcessedPaymentStore2 } = await import("../processed-payment-store-FIDI3RNH.js");
       const pgProcessed = new PostgresProcessedPaymentStore2(pgPool);
       pendingInits.push(pgProcessed.init());
       processedPayments = pgProcessed;
     } else {
-      const { MemoryCreditLedger: MemoryCreditLedger2 } = await import("../memory-credit-ledger-MNUOTQO5.js");
+      const { MemoryCreditLedger: MemoryCreditLedger2 } = await import("../memory-credit-ledger-ZOH6C3N4.js");
       creditLedger = disposableCashu?.ledger ?? new MemoryCreditLedger2();
-      const { MemoryProcessedPaymentStore: MemoryProcessedPaymentStore2 } = await import("../processed-payment-store-HAA4SFNK.js");
+      const { MemoryProcessedPaymentStore: MemoryProcessedPaymentStore2 } = await import("../processed-payment-store-FIDI3RNH.js");
       processedPayments = new MemoryProcessedPaymentStore2();
     }
     await Promise.all(pendingInits);
@@ -1509,7 +1508,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
     const checkStoreFallback = (label, event, active, backend, hazardHint) => {
       storeSummaries.push({ label, backend });
       if (active && backend === "memory" && !opts.devMode) {
-        const msg = `The ${label} store fell back to in-memory. Multi-machine deploys MUST use a cross-machine store (set DATABASE_URL) \u2014 each machine's per-process window otherwise lets an attacker ${hazardHint} once per machine via the load balancer. (internal-review)`;
+        const msg = `The ${label} store fell back to in-memory. Multi-machine deploys MUST use a cross-machine store (set DATABASE_URL) \u2014 each machine's per-process window otherwise lets an attacker ${hazardHint} once per machine via the load balancer.`;
         if (failFast) {
           throw new Error(`[FATAL] ${msg}`);
         }
@@ -1691,8 +1690,9 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
       replayStores: replayStoreSummaries,
       stores: storeSummaries
     });
-    return new Promise((resolvePromise) => {
+    return new Promise((resolvePromise, rejectPromise) => {
       const server = honoServe({ fetch: app.fetch, port }, (info) => {
+        server.off("error", rejectPromise);
         const url = `http://{authority}`.replace("{authority}", `localhost:${info.port}`);
         nodeServer = server;
         const portBindMs = Date.now() - bootStart;
@@ -1708,7 +1708,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
             level: "dvm_boot_phase_timings",
             totalMsToPortBind: portBindMs,
             phaseMs: deltas
-            // internal-review removed the pre-`listen` `mint_wait` phase: mint health
+            // removed the pre-`listen` `mint_wait` phase: mint health
             // is now validated by the runtime tracker after the port binds, so
             // `totalMsToPortBind` no longer carries the mint-probe tail.
           })
@@ -1722,6 +1722,7 @@ ${config.facilitatorAuth?.keyId ?? ""}`;
           }
         });
       });
+      server.once("error", rejectPromise);
     });
   }
   async function serveFn(serveOpts) {
@@ -2071,7 +2072,7 @@ function secp256k1Auth(opts = {}) {
       replayStore: null,
       driftSeconds,
       now,
-      // internal-review: the caller signs over the credit envelope, so it has to be in
+      // the caller signs over the credit envelope, so it has to be in
       // the canonical bytes — but it is protocol-level, not capability input, so
       // the builder's schema must not have to tolerate it. Resolved once per
       // schema, cached with the verifier below.

package/dist/{ssrf-DbFkpDv0.d.ts → ssrf-dMooihtY.d.ts}

@@ -26,7 +26,6 @@ type SSRFResolver = (host: string) => Promise<{
  * baseline denylist; extra entries compose with (never replace) the defaults.
  */
 interface SSRFGuardOpts {
-    /** Custom DNS resolver — typically a test stub. */
     resolver?: SSRFResolver;
     /** Additional exact hostnames to deny on top of the defaults (lowercased on input). */
     extraHostnamesExact?: Iterable<string>;
@@ -61,7 +60,7 @@ interface SSRFGuardOpts {
  * link-local IP ranges, the AWS / GCP metadata IP, Fly's `*.internal`
  * service-discovery names, and a small denylist of obviously-internal
  * hostnames. Defence-in-depth — full mitigation belongs at the egress firewall
- * and at fetch-time IP pinning (`createPinnedFetch`, internal-review).
+ * and at fetch-time IP pinning (`createPinnedFetch`).
  *
  * Throws `SSRFError` with a `reason` discriminator so callers can branch onto
  * their own typed error taxonomy.