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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +2 -0
  2. package/dist/{chunk-V7EVFLAK.js → chunk-2D75MNNG.js} +154 -523
  3. package/dist/{chunk-BIFLRKMO.js → chunk-2KGG5ORW.js} +1 -1
  4. package/dist/{chunk-PCUQZDZA.js → chunk-4VHTKNOR.js} +635 -321
  5. package/dist/{chunk-5URG56JJ.js → chunk-A4CM2BD3.js} +18 -2
  6. package/dist/{chunk-FT6HTUM4.js → chunk-AJNFXR7J.js} +1 -1
  7. package/dist/{chunk-S3XAHZQY.js → chunk-COYKJRMM.js} +24 -3
  8. package/dist/{chunk-UP2F5RRT.js → chunk-D7YQYLLM.js} +1 -4
  9. package/dist/{chunk-OMIQMMME.js → chunk-FPOLJRBF.js} +3 -3
  10. package/dist/{chunk-QP53RWAD.js → chunk-HHTL3ZFT.js} +9 -6
  11. package/dist/{chunk-JDT5LCJC.js → chunk-MD3H3BF7.js} +1 -1
  12. package/dist/{chunk-KSQEFVFJ.js → chunk-MMCE7XSR.js} +1 -1
  13. package/dist/{chunk-MRAGS5VP.js → chunk-N5B66UOS.js} +4 -16
  14. package/dist/{chunk-2ATUAUAO.js → chunk-O6D72KYA.js} +2 -2
  15. package/dist/{chunk-KXCKFIJI.js → chunk-QX52F6IB.js} +1 -1
  16. package/dist/{chunk-PHHAYRQV.js → chunk-U5VNEALI.js} +23 -10
  17. package/dist/{chunk-JLXYOV4Y.js → chunk-V5ZRATJH.js} +1 -1
  18. package/dist/{chunk-6GRIKOFB.js → chunk-VA7GT6C6.js} +5 -16
  19. package/dist/{chunk-O2X2CCKH.js → chunk-VIVXB4CD.js} +1 -1
  20. package/dist/{chunk-L67WTZX2.js → chunk-XMDQOXHO.js} +10 -33
  21. package/dist/{chunk-QT4ONTST.js → chunk-XRLKGCAW.js} +1 -1
  22. package/dist/{chunk-KMZXTBLA.js → chunk-XZ7LW4S5.js} +0 -1
  23. package/dist/{chunk-XQXJKJ3P.js → chunk-YO56VCTQ.js} +0 -4
  24. package/dist/{credit-ledger-5ZEJRI46.js → credit-ledger-MHA652TV.js} +2 -2
  25. package/dist/{credit-menu-D4Gcdgc4.d.ts → credit-menu-0-UtJ3hh.d.ts} +179 -533
  26. package/dist/{fx-B0SLBe5x.d.ts → fx-DhyT1Cjh.d.ts} +1 -1
  27. package/dist/index.d.ts +5 -17
  28. package/dist/internal/caller.d.ts +109 -698
  29. package/dist/internal/caller.js +10 -12
  30. package/dist/internal/server.d.ts +17 -42
  31. package/dist/internal/server.js +16 -15
  32. package/dist/{job-store-B2uZvga4.d.ts → job-store-D3CcZp_g.d.ts} +6 -10
  33. package/dist/{lightning-backend-CQBnQgsT.d.ts → lightning-backend-BhsyrBLa.d.ts} +1 -15
  34. package/dist/{memory-credit-ledger-ZOH6C3N4.js → memory-credit-ledger-BYBATRN3.js} +3 -3
  35. package/dist/{mpp-secret-state-WNAQQ6K4.js → mpp-secret-state-B5GCILVH.js} +1 -1
  36. package/dist/{mpp-setup-IOJBF7DB.js → mpp-setup-MPP3ST5X.js} +1 -1
  37. package/dist/{payout-reporter-5PIRYFVQ.js → payout-reporter-KEMUXEUO.js} +2 -2
  38. package/dist/{postgres-consumed-credential-store-ISRHBMOU.js → postgres-consumed-credential-store-6N2V5MJN.js} +1 -1
  39. package/dist/postgres-job-store-VE2JRUEC.js +7 -0
  40. package/dist/postgres-kv-store-DXGTKXLU.js +7 -0
  41. package/dist/{postgres-replay-store-IZFLTTAC.js → postgres-replay-store-ZF4JNZOW.js} +2 -2
  42. package/dist/{processed-payment-store-FIDI3RNH.js → processed-payment-store-GKMAWOM3.js} +2 -2
  43. package/dist/revenue-reporter-O75BGYFK.js +7 -0
  44. package/dist/server/index.d.ts +37 -140
  45. package/dist/server/index.js +64 -127
  46. package/dist/{step-cache-CXg7ziML.d.ts → step-cache-v2yhyhSZ.d.ts} +359 -1112
  47. package/dist/{tempo-charge-store-76TDAF34.js → tempo-charge-store-SDTUNTKA.js} +2 -2
  48. package/dist/{tempo-lifecycle-DXM7QXJQ.js → tempo-lifecycle-G5SB4HFC.js} +4 -4
  49. package/dist/{tempo-session-store-2JNOKJGX.js → tempo-session-store-WF3VZXNF.js} +2 -2
  50. package/dist/{tempo-wallet-O67H5M4N.js → tempo-wallet-ZFNUDFVO.js} +1 -1
  51. package/dist/testing/index.d.ts +2 -2
  52. package/dist/testing/index.js +2 -2
  53. package/dist/{usd-BNDg1715.d.ts → usd-Cu9G6xv2.d.ts} +1 -1
  54. package/dist/{x402-7S2EFINY.js → x402-CI6PSHNO.js} +4 -4
  55. package/package.json +2 -2
  56. package/dist/postgres-job-store-OGQ6IT4U.js +0 -7
  57. package/dist/postgres-kv-store-D5E2EZ24.js +0 -7
  58. package/dist/revenue-reporter-NNCNRY4C.js +0 -7
@@ -1,16 +1,15 @@
1
- import { ah as FundingMethod, o as PaymentMethod, bM as CreditLedgerLike, a1 as Message, X as FundingReceipt, bO as CreditSnapshot, Y as JobReceipt, S as SDKJobContext, aw as StepCache, u as ResponseContent, P as PaymentContent, a2 as MessageType, bj as X402Receipt, aE as X402Config, bi as X402ExactVersionSupport, cT as X402SettlementIntent, aq as PaymentRequirementsV2, c1 as CreditLedgerQuerier, cU as X402SettlementCursor, bQ as X402SettlementStatus, cV as X402SettlementWriteOff, bN as X402RefundSettlementGate, cW as X402FacilitatorAuth, cX as X402BatchSettlementConfig, cz as PostgresX402ChannelStorage, cY as X402PayoutObserver, br as MppxServer, ab as CashuMode, cZ as CreditDepositEnqueue, c_ as X402SettlementReconciliationReason, ao as PaymentRequirements, a0 as MppxCredential, bm as CreditDepositPayload, bP as DrawResult, cn as CreditLedgerError, a6 as ReceiptCredit, ae as DrainReceiptEvent, ad as DrainReceipt, K as KVStore, y as SignedRequestAudience, c$ as CreditDrawReleaseEnqueue, cx as JobCostReportPayload, cy as JobTerminalReportPayload, cB as RevenueSkippedNoRailPayload, Z as ZodLike, a as DVMDescriptor, bV as CreditInvoiceRecord, bW as InvoiceSettlement, ch as ClientCompatibilityGate, cf as ClientCompatibility, bu as PayoutReporter, R as ResolvedCreditConfig, g as CreditView } from './step-cache-CXg7ziML.js';
1
+ import { ah as FundingMethod, o as PaymentMethod, bM as CreditLedgerLike, a1 as Message, X as FundingReceipt, bO as CreditSnapshot, Y as JobReceipt, S as SDKJobContext, aw as StepCache, u as ResponseContent, P as PaymentContent, a2 as MessageType, bj as X402Receipt, aE as X402Config, bi as X402ExactVersionSupport, cT as X402SettlementIntent, aq as PaymentRequirementsV2, c1 as CreditLedgerQuerier, cU as X402SettlementCursor, bQ as X402SettlementStatus, cV as X402SettlementWriteOff, bN as X402RefundSettlementGate, cW as X402FacilitatorAuth, cX as X402BatchSettlementConfig, cz as PostgresX402ChannelStorage, cY as X402PayoutObserver, br as MppxServer, ab as CashuMode, cZ as CreditDepositEnqueue, c_ as X402SettlementReconciliationReason, ao as PaymentRequirements, a0 as MppxCredential, bm as CreditDepositPayload, bP as DrawResult, cn as CreditLedgerError, a6 as ReceiptCredit, ae as DrainReceiptEvent, ad as DrainReceipt, K as KVStore, y as SignedRequestAudience, c$ as CreditDrawReleaseEnqueue, cx as JobCostReportPayload, cy as JobTerminalReportPayload, cB as RevenueSkippedNoRailPayload, Z as ZodLike, a as DVMDescriptor, bV as CreditInvoiceRecord, bW as InvoiceSettlement, ch as ClientCompatibilityGate, cf as ClientCompatibility, bu as PayoutReporter, R as ResolvedCreditConfig, g as CreditView } from './step-cache-v2yhyhSZ.js';
2
2
  import { ProofLike, SerializedDLEQ, Proof } from '@cashu/cashu-ts';
3
3
  import { Hono, Context } from 'hono';
4
4
  import { Pool } from 'pg';
5
- import { b as FxRateSnapshot, F as FxFetcher } from './fx-B0SLBe5x.js';
6
- import { g as LockPubkey, f as CheckMintHealthOptions, b as LightningBackend, A as AttestationPayload } from './lightning-backend-CQBnQgsT.js';
7
- import { T as TopUpCapUnenforcedReason, A as AppendOutgoingOptions, J as JobRecord, b as JobStore } from './job-store-B2uZvga4.js';
5
+ import { b as FxRateSnapshot, F as FxFetcher } from './fx-DhyT1Cjh.js';
6
+ import { g as LockPubkey, f as CheckMintHealthOptions, b as LightningBackend, A as AttestationPayload } from './lightning-backend-BhsyrBLa.js';
7
+ import { T as TopUpCapUnenforcedReason, A as AppendOutgoingOptions, J as JobRecord, b as JobStore } from './job-store-D3CcZp_g.js';
8
8
  import { Challenge } from 'mppx';
9
9
  import { SettleResponse, SupportedResponse } from '@x402/core/types';
10
10
  import { Channel, AutoSettlementConfig } from '@x402/evm/batch-settlement/server';
11
11
  import { FacilitatorClient } from '@x402/core/server';
12
12
 
13
- /** A row in the per-DVM `wallet_accumulator` table. */
14
13
  interface WalletAccumulatorRow {
15
14
  id: string;
16
15
  dvmId: string;
@@ -36,11 +35,8 @@ interface WalletAccumulatorRow {
36
35
  * rows created before the column existed.
37
36
  */
38
37
  meltQuoteId: string | null;
39
- /**
40
- * NUT-11 locktime captured at accept time (ms since epoch). Null when the
41
- * accepted proof has no `locktime` tag. Drives oldest-first
42
- * ordering and the future `wallet_accumulator_batch_expiring_soon` monitor.
43
- */
38
+ /** NUT-11 locktime at acceptance, in epoch ms; null without a tag.
39
+ * Drives oldest-first ordering and expiring-soon monitoring. */
44
40
  tExpire: number | null;
45
41
  }
46
42
  /**
@@ -174,7 +170,6 @@ interface DisposableCashuCommit {
174
170
  commit(requestId: string, proofs: Proof[], account: (ledger: CreditLedgerLike) => Promise<void>): Promise<void>;
175
171
  }
176
172
 
177
- /** How often the sweep runs, and how long after boot its first pass fires. */
178
173
  interface CreditExpirySweepOpts {
179
174
  /** Sweep period. Defaults to {@link DEFAULT_SWEEP_INTERVAL_MS}; `0` disables the timer. */
180
175
  intervalMs?: number;
@@ -183,21 +178,56 @@ interface CreditExpirySweepOpts {
183
178
  * disables the boot pass, leaving only the interval.
184
179
  */
185
180
  bootDelayMs?: number;
186
- /** Credits released per pass. Passed straight to the ledger. */
187
181
  limit?: number;
188
182
  }
189
183
 
190
- /** Promise resolver for a pending client prompt response. */
184
+ interface HostingControlConfig {
185
+ /** Dedicated management key. Use at least 32 random bytes; never reuse a caller or builder key. */
186
+ secret: string;
187
+ /** Deployment scope shared by the platform and this DVM, independent of its caller origin. */
188
+ scope: string;
189
+ }
190
+ interface HostingControlCommand {
191
+ /** Version two is required for resume; version one remains valid for drain and status. */
192
+ version?: 2;
193
+ action: "drain" | "resume" | "status";
194
+ scope: string;
195
+ dvmId: string;
196
+ timestampMs: number;
197
+ nonce: string;
198
+ generation?: number;
199
+ deadlineMs?: number;
200
+ leaseExpiresAtMs?: number;
201
+ }
202
+ /** Ordered JSON arrays are the versioned wire signing contract. */
203
+ declare function signHostingControl(secret: string, command: HostingControlCommand): string;
204
+ interface HostingControlStatus {
205
+ state: "accepting" | "draining";
206
+ generation: number;
207
+ deadlineMs: number | null;
208
+ leaseExpiresAtMs: number | null;
209
+ activeJobIds: string[];
210
+ unownedActiveJobIds: string[];
211
+ pendingAdmissionCount: number;
212
+ pendingAdmissions: {
213
+ admissionId: string;
214
+ workId: string;
215
+ }[];
216
+ unresolvedAdmissionCount: number;
217
+ unresolvedAdmissions: {
218
+ admissionId: string;
219
+ jobId: string;
220
+ }[];
221
+ }
222
+
191
223
  interface PromptResolver {
192
224
  resolve: (value: ResponseContent) => void;
193
225
  reject: (reason: Error) => void;
194
226
  }
195
- /** Promise resolver for a pending client payment. */
196
227
  interface PaymentResolver {
197
228
  resolve: (value: PaymentContent) => void;
198
229
  reject: (reason: Error) => void;
199
230
  }
200
- /** In-memory representation of a running job. */
201
231
  interface ServerJob {
202
232
  id: string;
203
233
  tags: string[];
@@ -262,17 +292,13 @@ interface ServerJob {
262
292
  /** Chain transaction returned to callers recovering x402 or Tempo acceptance. */
263
293
  paymentTransactionHash?: string;
264
294
  /**
265
- * Rail-native amount accumulated across all successful credits on this
266
- * job (sats for mpp, USDC microunits for x402). The single
267
- * `revenue_events` row written at completion uses this as `gross_native`,
268
- * so multi-credit jobs sum the per-credit native amounts.
269
- * The upfront credit initializes this value; mid-job credits accumulate same-rail
270
- * and reset on a cross-rail switch (see `processIncomingPayment`).
295
+ * Rail-native atomic units accumulated across same-rail credits: Tempo and
296
+ * x402 use stablecoin micro-units. A rail switch resets this amount; Cashu
297
+ * revenue is derived from paidMsats instead.
271
298
  */
272
299
  nativeAmount?: number;
273
300
  /** Native asset tag paired with `nativeAmount`. */
274
301
  nativeAsset?: "sats" | "usdc" | "usdc.e" | "usd-cents";
275
- /** Cashu flow discriminator written into `revenue_events.metadata.cashu_flow`. */
276
302
  cashuFlow?: "p2pk_accumulator";
277
303
  /**
278
304
  * What this job cost the **builder** to serve, in 1e-6 of
@@ -316,8 +342,8 @@ interface ServerJob {
316
342
  * nonce issued by `requestPayment` and stamped onto the outbound x402
317
343
  * envelope; the caller signs `TransferWithAuthorization` against this exact
318
344
  * `bytes32`. Verification rejects an incoming `x402_payment` whose decoded
319
- * authorization nonce differs, blocking a cross-job replay before the
320
- * facilitator settles. Cleared on successful credit.
345
+ * authorization nonce differs before crediting the job. Cleared on
346
+ * successful credit.
321
347
  */
322
348
  pendingX402Nonce?: string;
323
349
  /**
@@ -415,9 +441,8 @@ interface ServerJob {
415
441
  /** Unix ms timestamp of last activity (message, yield, terminal). */
416
442
  lastActivityAt: number;
417
443
  }
418
- /** Extract the persistent fields from a ServerJob into a JobRecord. */
419
444
  declare function toJobRecord(job: ServerJob): JobRecord;
420
- /** Reconstitute a ServerJob from a persisted JobRecord with fresh runtime fields. */
445
+ /** Restored snapshots receive fresh process-local listeners, cancellation and prompt state. */
421
446
  declare function fromJobRecord(record: JobRecord): ServerJob;
422
447
  /**
423
448
  * Signal cancellation to a running handler. Idempotent — aborting an
@@ -433,40 +458,14 @@ declare function abortJob(job: ServerJob, reason: string): void;
433
458
  declare class JobCancelledError extends Error {
434
459
  constructor(message?: string);
435
460
  }
436
- /** Append a provider-sent message to the job and notify SSE listeners. */
437
461
  declare function providerMessage(job: ServerJob, type: MessageType, content: Record<string, unknown> | object): void;
438
462
  declare function isTerminal(status: ServerJob["status"]): boolean;
439
- /** Check if a message is a yield point (ends the provider's turn). */
440
463
  declare function isYieldMessage(msg: Message): boolean;
441
464
 
442
- /**
443
- * Per-DVM runtime mint-health tracker. Alongside the platform's
444
- * durable mint-health cron, probes every configured
445
- * mint on a timer, tracks consecutive failures, and flips a mint to `sick`
446
- * once the threshold is crossed. The SDK uses the resulting view to:
447
- *
448
- * 1. Filter `/v1/info`'s advertised `mints` to currently-healthy ones.
449
- * 2. Reject new accumulator receives at sick mints before they touch the
450
- * DB (`cashu_mint_sick` 503 from `verifyAccumulatorReceipt`).
451
- *
452
- * Since this tracker is the sole owner of mint health: boot no longer
453
- * runs a fail-fast check before binding the port. To preserve what boot used
454
- * to guarantee it (a) treats a mint as healthy only when it's reachable AND
455
- * NUT-compliant (reproducing `assertNutSupport` via `nutCompliant`), and (b)
456
- * exposes `initialProbeComplete()` so the paid path holds calls at
457
- * `mint_health_pending` until the first probe validates ≥1 mint.
458
- *
459
- * Existing accumulator entries are not touched — they're P2PK-locked to the
460
- * original mint and stay put until `dvmctl melt-pending` drains them. The
461
- * accumulator monitor's `wallet_accumulator_batch_expiring_soon` already
462
- * pages the builder when a stuck batch nears `t_expire`.
463
- *
464
- * In-memory only — no DB persistence. The platform cron keeps the durable
465
- * record + email path; the SDK only needs fresh in-process state
466
- * to make routing decisions.
467
- */
465
+ /** In-process mint health gates advertising and new receives. Paid calls wait for
466
+ * the first probe; NUT incompatibility fails immediately, transient failures
467
+ * use a consecutive threshold. Existing accumulator proofs remain at their mint. */
468
468
 
469
- /** Per-mint runtime view exposed by `snapshot()`. */
470
469
  interface MintHealthSnapshot {
471
470
  /** Last-observed wall-clock latency of the probe in ms. */
472
471
  latencyMs?: number;
@@ -486,9 +485,7 @@ interface MintHealthSnapshot {
486
485
  * never resolves without a config/mint change.
487
486
  */
488
487
  nutIncompatible?: boolean;
489
- /** Mint version reported by the last successful probe. */
490
488
  version?: string;
491
- /** Error category from the most recent failed probe. */
492
489
  errorCode?: string;
493
490
  }
494
491
  interface MintHealthTrackerOptions {
@@ -508,22 +505,9 @@ interface MintHealthTrackerOptions {
508
505
  consecutiveFailuresToSick?: number;
509
506
  fetchImpl?: typeof fetch;
510
507
  now?: () => number;
511
- /**
512
- * Per-probe timeout / retry / backoff, forwarded to {@link checkMintHealth}.
513
- * Defaults to that function's own defaults — 3 attempts with `[200, 500]`
514
- * backoff, which is what a real tick should do.
515
- *
516
- * Tests that drive several failing ticks set `backoffMs: [0]`: a failing
517
- * probe otherwise costs 700ms of real `setTimeout`, and four of them put a
518
- * unit test within a loaded CI runner's reach of the 5s default timeout.
519
- * `fetchImpl` is set on the tracker, not here.
520
- */
508
+ /** Forwarded to checkMintHealth; fetchImpl is supplied on the tracker. */
521
509
  probe?: Omit<CheckMintHealthOptions, "fetchImpl">;
522
510
  }
523
- /**
524
- * Runtime mint-health tracker. Owns its own timer; `start()` runs an initial
525
- * probe immediately so the first received call doesn't see a stale snapshot.
526
- */
527
511
  declare class MintHealthTracker {
528
512
  private readonly mints;
529
513
  private readonly tickIntervalMs;
@@ -569,60 +553,31 @@ declare class MintHealthTracker {
569
553
  * where a merely-flapping mint is still published.
570
554
  */
571
555
  isNutIncompatible(mintUrl: string): boolean;
572
- /** Plain-object snapshot keyed by mint URL — for tests + observability. */
573
556
  snapshot(): Record<string, MintHealthSnapshot>;
574
557
  private applyResult;
575
- /**
576
- * One-shot structured summary emitted after the first probe tick. Replaces
577
- * the boot check's per-mint `cashu_mint_startup_health` lines and surfaces an
578
- * all-mints-unhealthy warning — the operator alert that the Fly restart-loop
579
- * used to be before boot stopped refusing to start.
580
- */
558
+ /** One boot summary, including an all-unhealthy warning. */
581
559
  private logBootHealth;
582
560
  }
583
561
 
584
562
  /**
585
- * Credit fields carried inside the signed request body.
586
- *
587
- * An explicit draw references the credit INSIDE the secp256k1/Schnorr-signed
588
- * `body.data` — no new caller crypto. Wire field names (snake_case, matching
589
- * the rest of the wire surface):
590
- *
591
- * - `credit_id` — the credit to draw against.
592
- * - `draw_id` — client-generated draw id; the ledger's idempotency key.
593
- * - `fund` — optional `{ amount_micro, commitment }` funding commitment:
594
- * present iff a funding artifact (X-Cashu / X-PAYMENT / mpp credential)
595
- * rides the same request. `commitment` is the SHA-256 hex over the raw
596
- * artifact bytes, binding the header-borne proof — which sits OUTSIDE the
597
- * signed body — to the credit its sender intended (the funding-commitment rule).
563
+ * Credit fields belong to the raw signed body. The funding commitment hashes the header
564
+ * artifact, binding money outside that body to its intended credit.
598
565
  *
599
- * These are envelope-level fields, not capability input: **the SDK** removes
600
- * them before any builder-owned schema parses ({@link stripCreditEnvelope} in
601
- * `JobManager.parseInput` and on the quote path; {@link
602
- * creditEnvelopeIgnoreFields} feeding the auth verifier's own schema check), so
603
- * handlers never see them and a top-level `.strict()` capability schema is
604
- * fine. Relying on Zod's default strip mode instead was the trap:
605
- * `.strict()` rejects unknown keys, so an explicit draw 400'd at parse before
606
- * the envelope was ever extracted.
607
- *
608
- * The strip never touches the canonical signing bytes. Every auth call site
609
- * verifies the raw wire body (`signedRequestInput`), so the credit
610
- * fields are in the verified bytes because they were never taken out of them —
611
- * the strip is only ever applied to what a schema is about to parse.
566
+ * Schema projection strips undeclared protocol keys before builder input parsing, without
567
+ * changing canonical signing bytes. Signature verification must use the original wire body; a
568
+ * parsed projection may omit credit fields.
612
569
  */
613
570
  interface CreditEnvelope {
614
571
  creditId: string;
615
572
  drawId: string;
616
573
  fund?: CreditFundCommitment;
617
574
  }
618
- /** The signed funding commitment for a fund-and-draw request. */
619
575
  interface CreditFundCommitment {
620
576
  /** Funding amount in 1e-6 units of the credit's currency. */
621
577
  amountMicro: number;
622
578
  /** SHA-256 hex over the raw funding artifact bytes. */
623
579
  commitment: string;
624
580
  }
625
- /** Wire keys reserved for the credit envelope inside `body.data`. */
626
581
  declare const CREDIT_ENVELOPE_KEYS: readonly ["credit_id", "draw_id", "fund"];
627
582
  /**
628
583
  * Thrown by {@link extractCreditEnvelope} on a structurally invalid credit
@@ -640,28 +595,16 @@ declare class CreditEnvelopeError extends Error {
640
595
  */
641
596
  declare function extractCreditEnvelope(data: unknown): CreditEnvelope | undefined;
642
597
  /**
643
- * The reserved keys `schema` does not itself declare — the ones the SDK is
644
- * free to remove before handing it an input.
645
- *
646
- * A capability schema declares none of them, so all three are removable. The
647
- * one exception this exists for is `/v1/credit`'s own `CREDIT_REQUEST_SCHEMA`,
648
- * where `credit_id` and `fund` are real fields on a different wire shape and
649
- * removing them would empty the request. It is not an escape hatch for a
650
- * capability: the three names stay reserved on `body.data`, and declaring one
651
- * doesn't win a builder their own value — `app.ts` runs
652
- * {@link extractCreditEnvelope} over the raw body on every submit, so a
653
- * capability that declares `fund` answers `invalid_credit_fields` instead.
598
+ * Return protocol keys not declared by the schema. Schema-declared keys remain available,
599
+ * including /v1/credit’s differently shaped credit_id and fund fields. Submit separately
600
+ * extracts and validates the credit envelope from raw body.data; declaring a key does not
601
+ * bypass that validation.
654
602
  */
655
603
  declare function creditEnvelopeIgnoreFields(schema: unknown): readonly string[];
656
604
  /**
657
- * Remove the reserved credit keys from `data` before `schema` parses it, so a
658
- * strict schema doesn't reject the protocol's own envelope. Keys
659
- * `schema` declares are left alone — see {@link creditEnvelopeIgnoreFields}.
660
- *
661
- * Returns `data` unchanged when it isn't a plain object or carries none of the
662
- * removable keys, so the ordinary no-credit request allocates nothing. Never
663
- * use the result to derive canonical signing bytes: those cover the wire form,
664
- * credit fields included (`signedRequestInput`).
605
+ * Remove undeclared credit keys before schema parsing. Preserve nonobject/array inputs and
606
+ * objects with no removable keys. Never derive signing bytes from this projection; signatures
607
+ * cover the raw wire body.
665
608
  */
666
609
  declare function stripCreditEnvelope(schema: unknown, data: unknown): unknown;
667
610
 
@@ -904,18 +847,8 @@ declare function derivedFundCreditId(callerPubkey: string, fundId: string): stri
904
847
  declare function drawSettlementRef(dvmId: string, creditId: string, drawId: string): string;
905
848
 
906
849
  /**
907
- * Durable marker for a rail payment that already funded the credit ledger
908
- * (the funding-commitment rule). The x402 and mpp rails have no dvmkit-side
909
- * commit point of their own — the money moves at the facilitator / the payer's
910
- * mpp server — so the marker row, inserted in the SAME transaction as
911
- * `CreditLedger.fund` + `draw`, is what makes a crash-replayed credential
912
- * unable to fund twice: the second attempt collides on the primary key and
913
- * surfaces as {@link ProcessedPaymentReplayError}, which the verifier routes
914
- * into the recovery gates instead of a second fund.
915
- *
916
- * The Cashu rail does not use this store — its accumulator insert is already
917
- * the durable commit point, and its replay key (the `X-Cashu-Request-Id`
918
- * regime) must stay exactly as-is (dual-idempotency rule, the signed credit contract).
850
+ * x402/Tempo marker, funding and draw commit in one transaction so a retry
851
+ * cannot fund twice. Cashu retains its separate accumulator replay regime.
919
852
  */
920
853
  interface ProcessedPaymentStore {
921
854
  /**
@@ -941,11 +874,8 @@ interface ProcessedPaymentStore {
941
874
  paymentId: string;
942
875
  }): Promise<ProcessedPaymentRecord | undefined>;
943
876
  /**
944
- * Run `fn` inside one transaction (Postgres: BEGIN → fn → COMMIT, rollback
945
- * on throw). The verifier funds and draws the ledger inside `fn`, passing
946
- * the handle through to `record` / `CreditLedger.fund` / `draw` so all
947
- * three commit atomically. The memory implementation invokes `fn` with no
948
- * handle — its operations are synchronous-atomic in-process.
877
+ * Postgres supplies a transaction for marker, fund and draw; failure rolls it
878
+ * back. Memory invokes fn without a transactional handle or rollback.
949
879
  */
950
880
  withTx<T>(fn: (tx?: ProcessedPaymentQuerier) => Promise<T>): Promise<T>;
951
881
  }
@@ -1024,7 +954,6 @@ declare class MemoryProcessedPaymentStore implements ProcessedPaymentStore {
1024
954
  */
1025
955
  type AccumulatorRejectionCode = "missing_request_id" | "missing_lock_pubkey" | "not_p2pk_locked" | "wrong_lock_pubkey" | "proof_not_unspent" | "proof_pending" | "replay_rejected" | "mint_unreachable" | "invalid_token";
1026
956
 
1027
- /** Durable state of one exact x402 authorization. */
1028
957
  type X402ExactSettlementStatus = "prepared" | "submitting" | "settled" | "local_committed" | "ambiguous" | "rejected" | "complete";
1029
958
  /** Serializable local economic effect that follows an exact settlement. */
1030
959
  interface X402ExactSettlementEffect {
@@ -1073,7 +1002,6 @@ interface X402ExactAuthorizationFacts {
1073
1002
  nonce: string;
1074
1003
  fingerprint: string;
1075
1004
  }
1076
- /** One durable exact-x402 settlement intent. */
1077
1005
  interface X402ExactSettlementIntent extends X402ExactAuthorizationFacts {
1078
1006
  id: string;
1079
1007
  dvmId: string;
@@ -1128,11 +1056,9 @@ interface X402ExactSettlementStore {
1128
1056
  }): Promise<X402ExactSettlementIntent[]>;
1129
1057
  attempts(dvmId: string, intentId: string): Promise<X402ExactSettlementAttempt[]>;
1130
1058
  }
1131
- /** Postgres-backed exact settlement intent store. */
1132
1059
  declare class PostgresX402ExactSettlementStore implements X402ExactSettlementStore {
1133
1060
  private readonly pool;
1134
1061
  constructor(pool: Pick<Pool, "query" | "connect">);
1135
- /** Create the exact settlement tables. */
1136
1062
  init(): Promise<void>;
1137
1063
  prepare(intent: Omit<X402ExactSettlementIntent, "status" | "createdAt" | "updatedAt" | "resolvedAt">): Promise<X402ExactSettlementIntent>;
1138
1064
  get(dvmId: string, intentId: string): Promise<X402ExactSettlementIntent | undefined>;
@@ -1241,7 +1167,6 @@ type X402ExactAcceptance<T> = {
1241
1167
  intentId: string;
1242
1168
  reason: string;
1243
1169
  };
1244
- /** Dependencies for the durable exact x402 settlement coordinator. */
1245
1170
  interface X402ExactSettlementServerOpts {
1246
1171
  store: X402ExactSettlementStore;
1247
1172
  evidence?: X402ExactSettlementEvidenceReader;
@@ -1264,13 +1189,11 @@ declare class X402ExactSettlementServer {
1264
1189
  effect?: X402ExactSettlementEffect;
1265
1190
  commit: (receipt: X402Receipt, tx?: ProcessedPaymentQuerier, effect?: X402ExactSettlementEffect) => Promise<T>;
1266
1191
  }): Promise<X402ExactAcceptance<T>>;
1267
- /** Read the operator queue. */
1268
1192
  list(args: {
1269
1193
  dvmId: string;
1270
1194
  limit: number;
1271
1195
  includeResolved?: boolean;
1272
1196
  }): Promise<X402ExactSettlementIntent[]>;
1273
- /** Read durable attempt evidence for one intent. */
1274
1197
  attempts(dvmId: string, intentId: string): Promise<X402ExactSettlementAttempt[]>;
1275
1198
  /** Reconcile and finish one intent from chain evidence. */
1276
1199
  reconcile(dvmId: string, intentId: string): Promise<{
@@ -1614,7 +1537,6 @@ interface CreateX402BatchSettlementServerOpts {
1614
1537
  */
1615
1538
  declare function createX402BatchSettlementServer(opts: CreateX402BatchSettlementServerOpts): Promise<X402BatchSettlementServer>;
1616
1539
 
1617
- /** Payment state from upfront token verification. */
1618
1540
  interface PaymentInfo {
1619
1541
  /**
1620
1542
  * Rail value this payment contributes to the job, in millisatoshis.
@@ -1647,12 +1569,10 @@ interface PaymentInfo {
1647
1569
  /** Chain transaction returned to a caller recovering this accepted request. */
1648
1570
  paymentTransactionHash?: string;
1649
1571
  /**
1650
- * Rail-native payment amount in atomic units. Sats for mpp,
1651
- * USDC microunits for x402. Cashu leaves it unset — the existing
1652
- * `paidMsats / 1000` derivation in the platform callback covers it.
1572
+ * Stablecoin micro-units for Tempo and x402. Cashu leaves this unset; its revenue is derived
1573
+ * from paidMsats.
1653
1574
  */
1654
1575
  nativeAmount?: number;
1655
- /** Native asset tag matching `revenue_events.native_asset`. */
1656
1576
  nativeAsset?: "sats" | "usdc" | "usdc.e" | "usd-cents";
1657
1577
  /**
1658
1578
  * Discriminator written into `revenue_events.metadata.cashu_flow` so ops
@@ -1801,7 +1721,6 @@ interface UpfrontPaymentOpts {
1801
1721
  * no per-process replay protection beyond mppx's own expiry check.
1802
1722
  */
1803
1723
  consumedCredentialStore?: ConsumedCredentialStore;
1804
- /** Cashu receive mode. Routes the receive path. */
1805
1724
  cashuMode?: CashuMode;
1806
1725
  /** Per-DVM Postgres pool — required for the `p2pk-accumulator` path. */
1807
1726
  accumulatorDb?: AccumulatorPool;
@@ -1834,12 +1753,9 @@ interface UpfrontPaymentOpts {
1834
1753
  */
1835
1754
  fxFetcher?: FxFetcher;
1836
1755
  /**
1837
- * Credit ledger every payment funds and draws through (the credit lifecycle contract):
1838
- * an attached rail payment is an implicit N=1 funding — `fund` the paid
1839
- * amount + `draw` it, atomically with the rail commit. When absent (or
1840
- * when the price can't be fiat-denominated), the payment is accepted with
1841
- * legacy semantics and a structured warning — money is never refused
1842
- * because the ledger is unavailable.
1756
+ * Attached payments fund and draw an implicit per-job credit atomically with
1757
+ * rail accounting. Omitting the ledger uses the legacy ledgerless path;
1758
+ * a configured ledger requires a fiat-denominated price before acceptance.
1843
1759
  */
1844
1760
  creditLedger?: CreditLedgerLike;
1845
1761
  /**
@@ -1917,7 +1833,6 @@ interface FundOnlyRequest {
1917
1833
  */
1918
1834
  commitment: string;
1919
1835
  }
1920
- /** Structured payment validation error detail carried through `PaymentValidationError`. */
1921
1836
  interface PaymentErrorDetail {
1922
1837
  body: Record<string, unknown>;
1923
1838
  status: number;
@@ -2065,7 +1980,6 @@ declare function hasPaymentProof(content: Record<string, unknown>): boolean;
2065
1980
  * surfaces always keep charge.
2066
1981
  */
2067
1982
  declare function issueUpfrontChallenges(mpp: MppxServer, requiredMsats: number, resourcePath: string, btcUsdRate: number, sessionIssuable?: boolean, allowOneShotStablecoin?: unknown, priceFiat?: PriceFiat): Promise<Challenge.Challenge[]>;
2068
- /** Verify an upfront payment on job submission (Cashu, x402, or MPP). */
2069
1983
  declare function verifyUpfrontPayment(opts: UpfrontPaymentOpts): Promise<PaymentResult>;
2070
1984
  /**
2071
1985
  * A management credential signed for a channel other than the one required
@@ -2117,25 +2031,9 @@ declare function verifyTempoSessionManagementCredential(args: {
2117
2031
  */
2118
2032
  type PaymentErrorCode = "payment_invalid" | "x402_not_offered" | "x402_settlement_ambiguous" | "cashu_unavailable" | "cashu_not_p2pk_locked" | "mint_health_pending" | "cashu_mint_sick" | "payment_insufficient" | "payment_unapplied" | "insufficient_credit" | "credit_expired" | "credit_unbacked" | "credit_not_found" | "tempo_channel_closing" | "settlement_pending" | "draw_conflict" | "funding_commitment_mismatch" | "credit_not_supported" | "one_shot_credit_not_supported" | "credit_below_min" | "below_rail_minimum" | "credit_over_max" | "credit_id_unavailable" | "nothing_to_drain" | "drain_below_dust" | "drain_not_found" | "drain_conflict" | "drain_method_unsupported" | "tempo_channel_exit_required" | "x402_settlement_submission_failed" | X402SettlementReconciliationReason | "lightning_settlement_pending" | "lightning_invoice_expired" | "lightning_unavailable" | AccumulatorRejectionCode;
2119
2033
  /**
2120
- * Build a flat payment-error body carrying the four agent-facing fields every
2121
- * payment error must have: the machine `code`, the operator-facing
2122
- * `message`, and the `display`/`hint`/`retryable` copy an agent relays to a
2123
- * human and branches retries on. `display`, `hint`, and `retryable` default from
2124
- * {@link PAYMENT_ERROR_COPY} keyed on `code`; `message` is the per-site operator
2125
- * log line. The prose fields can be overridden for dynamic cases (e.g.
2126
- * `cashu_mint_sick` naming the currently-healthy mints, or a retained deposit
2127
- * distinguishing "not spent" from "not paid"). `extra` carries a code's ad-hoc
2128
- * fields (`mints`, `required_msats`, `received_msats`) and is merged last so
2129
- * those are preserved.
2130
- *
2131
- * `retryable` overrides on the same terms, and for the same reason: a code that
2132
- * covers more than one refusal can be terminal for one of them and clear on its
2133
- * own for another — `drain_conflict` is both. Override it only
2134
- * alongside the `hint`, since the two are one answer: a hint that says retry
2135
- * under `retryable: false` is the disagreement this exists to prevent.
2136
- *
2137
- * Upstream of {@link buildPaymentErrorResponse}, which serializes the body onto
2138
- * a `Response` — this shapes it.
2034
+ * Per-code display, hint and retryability may be overridden for a particular
2035
+ * refusal. Keep the hint and retry decision consistent. Extra fields merge
2036
+ * last, so callers can supply code-specific amounts and alternatives.
2139
2037
  */
2140
2038
  declare function paymentErrorBody(code: PaymentErrorCode, opts: {
2141
2039
  message: string;
@@ -2216,14 +2114,9 @@ interface IncomingPaymentOpts {
2216
2114
  creditTtlMs?: number;
2217
2115
  }
2218
2116
  /**
2219
- * Pure verification of an incoming mid-job payment. Runs the
2220
- * rail-specific verify path and returns the credit shape; does not mutate
2221
- * the job. The caller (`JobManager.processPayment`) applies the result
2222
- * inside Tx C so verify+credit land atomically.
2223
- *
2224
- * `snapshot` carries the read-only job state the verification path needs
2225
- * (`pendingPaymentMsats` for amount checks, the MPP/x402 per-job bindings,
2226
- * `paymentRail` for the same-rail accumulator check).
2117
+ * Job state read by incoming-payment verification; the job itself is not mutated. Rail
2118
+ * acceptance and ledger funding can still occur before the caller applies the returned credit in
2119
+ * Tx C.
2227
2120
  */
2228
2121
  interface VerifyIncomingSnapshot {
2229
2122
  pendingPaymentMsats?: number;
@@ -2326,16 +2219,8 @@ declare function verifyIncomingPayment(body: {
2326
2219
  */
2327
2220
  declare function applyPaymentInfoToJob(job: ServerJob, info: VerifiedIncomingPayment): void;
2328
2221
  /**
2329
- * Process an incoming payment message. Returns an error body on failure.
2330
- *
2331
- * **The isolate-runtime path, and deliberately ledger-less** (the isolate-runtime rule). Its
2332
- * only caller is `platform/isolate-job-manager.ts`; isolate DVMs have no
2333
- * Postgres of their own, so they run implicit N=1 with today's semantics
2334
- * preserved and never advertise credit. The credits-carrying mid-job path is
2335
- * {@link verifyIncomingPayment} + `JobManager.processPayment` (Tx C), where
2336
- * wired `fund` + `growDraw`. Wiring a ledger here would need a
2337
- * platform-side ledger leg with its own funding-atomicity and receipt-key
2338
- * story — the trust-surface expansion exists to decide.
2222
+ * Legacy ledgerless payment path. Mutates the job on acceptance; durable credit hosts use
2223
+ * verifyIncomingPayment and apply its result in Tx C.
2339
2224
  */
2340
2225
  declare function processIncomingPayment(job: ServerJob, body: {
2341
2226
  type: MessageType;
@@ -2414,14 +2299,8 @@ interface ReceiptIssuerOpts {
2414
2299
  dvmId: string;
2415
2300
  }
2416
2301
  /**
2417
- * Signs job receipts for one DVM.
2418
- *
2419
- * Constructed only when a receipt key is wired, so the presence of an issuer
2420
- * *is* the "this DVM emits receipts" signal that `/v1/info` advertises. Pure:
2421
- * it holds the key and the slug and turns a terminal `JobRecord` plus an
2422
- * allocated sequence number into signed bytes — sequence allocation and
2423
- * persistence belong to the store, which is what makes issuance idempotent
2424
- * across machines.
2302
+ * An issuer indicates receipt support. Sequence allocation and write-once
2303
+ * persistence belong to the store; signing alone does not provide idempotency.
2425
2304
  */
2426
2305
  declare class ReceiptIssuer {
2427
2306
  /** x-only pubkey this issuer signs under; the attested `receipt_pubkey`. */
@@ -2431,20 +2310,10 @@ declare class ReceiptIssuer {
2431
2310
  private readonly dvmId;
2432
2311
  constructor(opts: ReceiptIssuerOpts);
2433
2312
  /**
2434
- * Build and sign the receipt for a terminal job. `seq` comes from
2435
- * `JobStore.claimReceiptSeq`; `issuedAt` is epoch seconds and defaults to now.
2436
- *
2437
- * Free jobs get receipts too, with `paid.msats: 0` — they still consume a
2438
- * sequence number and still attest an outcome. Whether feedback is
2439
- * paid-only is the feedback layer's call, not this one's.
2440
- *
2441
- * Timing and attribution come from the committed terminal row, not signing
2442
- * time or handler input. Legacy rows without those durable inputs omit the
2443
- * optional blocks rather than inventing historical evidence.
2444
- *
2445
- * `credit` is the resolved draw block — present on every job
2446
- * whose payment funded/drew the ledger, absent otherwise. Signature-
2447
- * compatible either way: `canonicalize` omits absent keys.
2313
+ * seq is store-allocated; issuedAt is epoch seconds. Free jobs also consume a
2314
+ * sequence and attest their outcome. Timing/attribution comes from the committed
2315
+ * terminal row; legacy rows omit unknown historical fields. credit is present
2316
+ * only for a resolved ledger draw.
2448
2317
  */
2449
2318
  issue(record: JobRecord, seq: number, issuedAt?: number, credit?: ReceiptCredit): JobReceipt;
2450
2319
  /**
@@ -2544,9 +2413,9 @@ interface JobManagerOpts {
2544
2413
  env: Record<string, string>;
2545
2414
  store: KVStore;
2546
2415
  mints?: string[];
2547
- /** Persistent backing store for job records. Default: in-memory. */
2416
+ /** Durable in production; defaults to memory only in development/test mode. */
2548
2417
  jobStore?: JobStore;
2549
- /** When true, payment messages auto-credit without verification. */
2418
+ /** Skips payment only when no payment rail is configured. Wired rails still verify. */
2550
2419
  devMode?: boolean;
2551
2420
  /** Payment methods this DVM accepts. Default: derived by the server from configured rails. */
2552
2421
  paymentMethods?: PaymentMethod[];
@@ -2555,9 +2424,7 @@ interface JobManagerOpts {
2555
2424
  x402ExactSettlement?: X402ExactSettlementServer;
2556
2425
  /** Live facilitator capabilities for version-specific mid-job payment handling. */
2557
2426
  x402FacilitatorHealth?: X402FacilitatorHealthLike;
2558
- /** MPP multi-rail payment handle (built via `createMppFromOpts`). */
2559
2427
  mpp?: MppxServer;
2560
- /** Cashu receive mode. */
2561
2428
  cashuMode?: CashuMode;
2562
2429
  /** Builder's NUT-11 P2PK lock pubkey. Required for accumulator mode. */
2563
2430
  lockPubkey?: string;
@@ -2693,16 +2560,10 @@ interface JobManagerOpts {
2693
2560
  */
2694
2561
  onRevenueSkippedNoRail?: (info: RevenueSkippedNoRailPayload) => void | Promise<void>;
2695
2562
  /**
2696
- * Stale-job sweep threshold in ms. Jobs in a non-terminal status
2697
- * (`processing` / `working` / `awaiting-input`) whose `lastActivityAt` is
2698
- * older than this are force-cancelled with reason `stale_no_terminal_status`,
2699
- * so callers always reach a terminal status instead of polling forever after
2700
- * a worker crash, OOM, or silent `messageAppender` failure. Default:
2701
- * `2 × descriptor.idleTimeout + STALE_JOB_WATCHDOG_HEADROOM_MS`, which keeps
2702
- * the default beyond scrape's `JOB_TIMEOUT_MS`.
2703
- * Builders whose per-handler wall-clock bound exceeds 90s must override
2704
- * this — otherwise the watchdog fires on a legitimate in-flight handler.
2705
- * Set to `0` to disable (test seam).
2563
+ * Awaiting-input age in milliseconds before cancellation. Defaults to
2564
+ * twice descriptor.idleTimeout (seconds), converted to milliseconds, plus
2565
+ * STALE_JOB_WATCHDOG_HEADROOM_MS. Set to 0 to disable this arm; processing
2566
+ * jobs use processingWatchdogMs.
2706
2567
  */
2707
2568
  staleJobTimeoutMs?: number;
2708
2569
  /**
@@ -2907,9 +2768,7 @@ declare class JobManager<State, InputSchema extends ZodLike | undefined> {
2907
2768
  * never promise something `issueReceipt` silently declines to do.
2908
2769
  */
2909
2770
  get receiptsEnabled(): boolean;
2910
- /** True when the named capability exists on this descriptor. */
2911
2771
  hasCapability(name: string): boolean;
2912
- /** Names of every capability this descriptor exposes — used for error envelopes. */
2913
2772
  capabilityNames(): string[];
2914
2773
  /**
2915
2774
  * Resolve a capability's static `price` to msats.
@@ -3101,9 +2960,7 @@ declare class JobManager<State, InputSchema extends ZodLike | undefined> {
3101
2960
  * `artifact`'s NOTIFY silently drops the artifact.
3102
2961
  */
3103
2962
  private wireMessageAppender;
3104
- /** Start (or restart) the idle timer for a job. */
3105
2963
  startIdleTimer(job: ServerJob): void;
3106
- /** Clear the idle timer for a job. */
3107
2964
  clearIdleTimer(id: string): void;
3108
2965
  /** Cancel a job due to idle timeout. Exposed for the reactivation path's idle-expiry guard. */
3109
2966
  cancelJobIdle(job: ServerJob): Promise<void>;
@@ -3609,7 +3466,6 @@ declare class JobManager<State, InputSchema extends ZodLike | undefined> {
3609
3466
  private reportTerminalJob;
3610
3467
  private terminalReportRecoveryCursor?;
3611
3468
  private recoverTerminalReports;
3612
- /** Handle job reaching terminal state (completed, failed, cancelled). */
3613
3469
  private handleJobTerminal;
3614
3470
  /**
3615
3471
  * Re-enqueue terminal cost-only rows left between the job commit and outbox
@@ -3671,19 +3527,16 @@ declare class JobManager<State, InputSchema extends ZodLike | undefined> {
3671
3527
  private bookRevenue;
3672
3528
  /** Schedule job removal from activeJobs after a delay so clients can still poll final status. */
3673
3529
  scheduleCleanup(job: ServerJob): void;
3674
- /** Clear all timers. Called on server shutdown to allow clean exit. */
3675
3530
  shutdown(): void;
3676
3531
  }
3677
3532
 
3678
3533
  /** Cached liveness signal for a platform-hosted DVM's Lightning receive rail. */
3679
3534
  interface LightningRailHealth {
3680
- /** Whether the receive rail may be advertised at this instant. */
3681
3535
  available(): boolean;
3682
3536
  /** Prime the cached signal at boot when the source supports it. */
3683
3537
  refresh?(): Promise<void>;
3684
3538
  }
3685
3539
 
3686
- /** Builder-facing wiring for the Lightning receive leg. */
3687
3540
  interface LightningReceiveConfig {
3688
3541
  /**
3689
3542
  * Receive-only NWC connection URI (`DVMKIT_NWC_RECEIVE_URI`). Validated at
@@ -3722,25 +3575,14 @@ declare const DEFAULT_INVOICE_TTL_SECONDS = 900;
3722
3575
  */
3723
3576
  declare const MIN_INVOICE_TTL_SECONDS = 600;
3724
3577
  /**
3725
- * The builder-side Lightning receive leg for funding prepaid credit.
3578
+ * Prepaid Lightning funding over a receive-safe NWC connection. URI construction validates
3579
+ * the advertised method allowlist, refusing spending or unknown authority; the injected
3580
+ * backend seam bypasses that probe. Receive-safe methods include invoice, read and
3581
+ * hold-invoice operations.
3726
3582
  *
3727
- * Issues a bolt11 over a **receive-only** NWC connection while the DVM is
3728
- * awake serving the 402, and credits the ledger when a later request observes
3729
- * settlement. Two properties are load-bearing:
3730
- *
3731
- * - **It never holds a send credential.** `pay_invoice` on this connection is
3732
- * refused at construction, so a compromised DVM can mint invoices and
3733
- * nothing else. The drain/refund sender is a separate, budgeted
3734
- * connection by rule.
3735
- * - **Crediting is pull-based — there is no settlement watcher.** The caller's
3736
- * next request drives `lookup_invoice`, which is what makes this work on a
3737
- * suspend-to-zero fleet: a machine that is asleep has nothing to miss.
3738
- * Wallet downtime at that moment delays crediting; it never loses money,
3739
- * because the invoice→credit binding is a durable row.
3740
- *
3741
- * Reachability is **cached**, never probed per request: the funding menu is
3742
- * assembled on every quote and every 402, so a live NIP-47 round trip there
3743
- * would put a nostr relay in the latency path of every priced call.
3583
+ * Crediting is pull-based: later requests observe settlement against the durable invoice
3584
+ * binding, so sleeping hosts need no watcher. Reachability is cached and refreshed in the
3585
+ * background for funding menus.
3744
3586
  */
3745
3587
  declare class LightningReceive {
3746
3588
  private readonly source;
@@ -3753,36 +3595,21 @@ declare class LightningReceive {
3753
3595
  private constructor();
3754
3596
  private readonly railHealth;
3755
3597
  /**
3756
- * Validate the configured connection and build the receive leg, or return
3757
- * `undefined` when this DVM didn't configure one.
3758
- *
3759
- * **Throws on a credential that is wrong, degrades on one that is merely
3760
- * unreachable.** A wallet outage at boot must not stop a DVM whose other
3761
- * rails are fine — the menu simply omits `lightning` until a later probe
3762
- * succeeds. A connection that can spend, or one that can't state what it can
3763
- * do, is a different thing entirely: it is a standing money risk that no
3764
- * amount of retrying fixes, so it fails the boot loudly with the fix in the
3765
- * message.
3598
+ * Return undefined when unconfigured. Permission/URI failures refuse construction with a
3599
+ * corrective message; wallet transport failure constructs an unavailable receive leg so
3600
+ * other rails can still boot. Recovery must validate method scope before advertising
3601
+ * Lightning.
3766
3602
  */
3767
3603
  static create(config: LightningReceiveConfig): Promise<LightningReceive | undefined>;
3768
3604
  /**
3769
- * Whether `lightning` belongs on the funding menu right now.
3770
- *
3771
- * Reads the cached observation and never blocks; a stale one kicks off a
3772
- * background refresh and answers with what we last knew. Advertising a rail
3773
- * whose wallet is down would hand the caller an option that 402s on use —
3774
- * the §4 posture is to drop it and let the sale survive on the others.
3605
+ * Answer from cached wallet and optional rail-health observations without blocking. A stale
3606
+ * wallet observation starts a background refresh.
3775
3607
  */
3776
3608
  available(): boolean;
3777
3609
  /**
3778
- * Issue (or re-issue) the bolt11 funding `(creditId, fundId)`.
3779
- *
3780
- * The invoice is minted **for** the credit and amount named in the caller's
3781
- * signed body — that binding is the condition-3 commitment on this
3782
- * rail, and it is why no artifact hash rides the request: there is no
3783
- * caller-supplied artifact to hash. A re-poll returns the stored row rather
3784
- * than minting again; a second bolt11 for one `fund_id` would leave two
3785
- * payable invoices against a funding that can only be credited once.
3610
+ * Return the stored invoice on retry: two payable bolt11s for one fund ID could charge
3611
+ * twice while only one credits. Caller and amount are bound to the recorded credit/funding
3612
+ * pair, without a caller-supplied artifact hash.
3786
3613
  */
3787
3614
  issue(ledger: CreditLedgerLike, args: {
3788
3615
  creditId: string;
@@ -3794,24 +3621,9 @@ declare class LightningReceive {
3794
3621
  description?: string;
3795
3622
  }): Promise<CreditInvoiceRecord>;
3796
3623
  /**
3797
- * Ask the wallet whether one payment hash is paid, and when.
3798
- *
3799
- * The operator's reconcile verb runs this before it credits anything. A
3800
- * `blocked` row implies payment — {@link applyOne} returns above the block
3801
- * classification when the lookup says unpaid — but that is *this fleet's
3802
- * belief, recorded possibly weeks ago*, and the verb it gates mints balance
3803
- * against it. One round trip turns the belief into a fact and recovers the
3804
- * true settlement instant for `settled_at`, which a blocked row never got to
3805
- * write.
3806
- *
3807
- * Unlike {@link settlePending} this **throws**: there is no request whose
3808
- * latency it protects, and crediting on an unverifiable wallet is exactly
3809
- * what it exists to prevent. `NOT_FOUND` is the one exception, and it is not
3810
- * an outage — it is the wallet saying it has never seen this hash, the same
3811
- * reading {@link applyOne} and the caller-side reconcile in `src/lib/nwc.ts`
3812
- * take. It comes back as `known: false` because the operator's repair for it
3813
- * ("you are pointed at a different wallet than the one that minted this")
3814
- * is not the repair for an unpaid invoice, and certainly not for a retry.
3624
+ * Re-observe the wallet payment before an operator credits a blocked invoice and recover
3625
+ * its settlement instant. Unlike settlePending, lookup failures throw. NOT_FOUND returns
3626
+ * known:false, distinguishing the wrong wallet/unknown hash from an unpaid known invoice.
3815
3627
  */
3816
3628
  lookupSettlement(paymentHash: string): Promise<{
3817
3629
  settled: boolean;
@@ -3819,23 +3631,12 @@ declare class LightningReceive {
3819
3631
  known: boolean;
3820
3632
  }>;
3821
3633
  /**
3822
- * Consult the wallet about this caller's outstanding invoices and credit the
3823
- * ones that settled — the pull half of pull-based crediting.
3824
- *
3825
- * The pending rows are read locally first, so the common case (nothing
3826
- * outstanding) costs one indexed SELECT and no network at all. Bounded to
3827
- * {@link MAX_SETTLE_CHECKS} invoices on a short deadline, and **never throws
3828
- * into the request**: a wallet failure here means the caller's balance is
3829
- * merely not updated yet, which the ordinary `insufficient_credit` path
3830
- * already states honestly.
3634
+ * Read pending invoices locally, then check at most MAX_SETTLE_CHECKS on bounded wallet
3635
+ * deadlines. Log failures without throwing into the request.
3831
3636
  *
3832
- * **Each invoice gets its own failure boundary.** The sweep window is a few
3833
- * rows wide, so a row that fails on its own terms — a `fund_id` the caller
3834
- * reused on another rail, a credit someone else opened first — must not take
3835
- * the rest of the pass down with it: the next invoice in the window may be
3836
- * the paid one, and it would never be looked up. Only a transport failure
3837
- * ends the pass early, because there the wallet itself is gone and the
3838
- * remaining lookups would just spend the caller's latency confirming it.
3637
+ * An invoice-specific failure must not suppress payable siblings; wallet transport failure
3638
+ * ends the pass. Deterministic refusals retire that row as blocked for operator repair,
3639
+ * while transient failures remain pending.
3839
3640
  */
3840
3641
  settlePending(ledger: CreditLedgerLike, args: {
3841
3642
  callerPubkey: string;
@@ -3845,49 +3646,21 @@ declare class LightningReceive {
3845
3646
  enqueueCreditDeposit?: CreditDepositEnqueue;
3846
3647
  nowMs?: number;
3847
3648
  }): Promise<InvoiceSettlement[]>;
3848
- /**
3849
- * One invoice's settlement check. Returns the applied settlement, or
3850
- * `undefined` when nothing changed (still unpaid, or retired unpaid).
3851
- *
3852
- * Throws whatever the wallet or the ledger threw — classifying that is
3853
- * {@link retireOrLog}'s job, so this stays one invoice's happy path.
3854
- */
3855
3649
  private applyOne;
3856
3650
  /**
3857
- * Decide what one invoice's failure means, and retire the invoice when the
3858
- * answer is "this can never succeed".
3859
- *
3860
- * The split that matters is permanent-versus-transient, because it decides
3861
- * whether the row keeps a slot in the sweep window. A transient failure — the
3862
- * database blinked, the wallet answered oddly — leaves it `pending` and the
3863
- * caller's next request retries it. A **permanent** one means the ledger will
3864
- * refuse this invoice identically forever, so leaving it pending costs a
3865
- * `lookup_invoice` on every subsequent request and, at
3866
- * {@link MAX_SETTLE_CHECKS} of them, fills the window so a genuinely payable
3867
- * invoice behind them is never even looked up. Those get `blocked`, which
3868
- * drops them out of the sweep and hands the operator the payment hash.
3651
+ * Retire a deterministic uncreditable payment as blocked so it no longer occupies the
3652
+ * bounded sweep window. Transient failures stay pending for a later request; report the
3653
+ * payment hash for operator repair.
3869
3654
  */
3870
3655
  private retireOrLog;
3871
3656
  /**
3872
- * The reason this invoice can never be credited, or `undefined` if the
3873
- * failure was transient.
3874
- *
3875
- * Every code here is decided by state a retry cannot move — a row the ledger
3876
- * has already committed (a `credit_fundings` entry at this
3877
- * `(credit_id, fund_id)`, or a `credits` row whose owner, denomination or
3878
- * rail disagrees with the invoice), or the basis this module rebuilds
3879
- * identically from the invoice row on every pass. None of them is a race.
3880
- *
3881
- * `funding_replayed` is the one that needs a second read to classify.
3882
- * Usually it *is* benign — a concurrent check won the race and the money is
3883
- * credited either way — but the key is `(credit_id, fund_id)` and `fund_id`
3884
- * is **caller-chosen**: reuse it on cashu or x402 after this bolt11 was
3885
- * minted and the row that collided is a different payment entirely, so the
3886
- * sats this invoice received have nowhere to land.
3657
+ * Classify funding_replayed by reading the existing funding’s rail. A Lightning row can
3658
+ * represent a concurrent applied check; another rail at this caller-chosen key is a
3659
+ * different payment, leaving the invoice’s sats uncredited. A failed diagnostic read
3660
+ * remains transient, never a guessed permanent refusal.
3887
3661
  */
3888
3662
  private blockingReason;
3889
3663
  private withBackend;
3890
- /** Record activity without letting it promote an unvalidated connection. */
3891
3664
  private noteOperationOk;
3892
3665
  private notePermissionsOk;
3893
3666
  private notePermissionRefused;
@@ -3910,7 +3683,7 @@ interface OwnerDisplay {
3910
3683
  avatarUrl?: string | null;
3911
3684
  type: "builder" | "org";
3912
3685
  }
3913
- /** Optional builder identity surfaced on `/v1/info` (forward-compatible stub). */
3686
+ /** Builder identity advertised on /v1/info. */
3914
3687
  interface BuilderIdentity {
3915
3688
  id?: string;
3916
3689
  name?: string;
@@ -3935,7 +3708,6 @@ interface PlatformReporterOpts {
3935
3708
  /** Platform internal URL. Defaults to `DVMKIT_PLATFORM_URL` env. */
3936
3709
  url?: string;
3937
3710
  }
3938
- /** Running host handle returned by serve(). */
3939
3711
  interface DVMServeResult {
3940
3712
  url: string;
3941
3713
  close: () => Promise<void>;
@@ -3943,6 +3715,8 @@ interface DVMServeResult {
3943
3715
  paymentModes: PaymentMode[];
3944
3716
  }
3945
3717
  interface DVMHostOpts {
3718
+ /** Dedicated hosting-management authority for each mounted DVM. Requires durable Postgres. */
3719
+ hostingControl?: HostingControlConfig;
3946
3720
  /**
3947
3721
  * Postgres connection string. Defaults to `DATABASE_URL` env.
3948
3722
  * Required at runtime. Boot fails when missing unless `jobStore`
@@ -3957,7 +3731,6 @@ interface DVMHostOpts {
3957
3731
  * to ambient process variables.
3958
3732
  */
3959
3733
  env?: Record<string, string>;
3960
- /** Builder identity for `/v1/info` (forward-compatible). */
3961
3734
  builder?: BuilderIdentity;
3962
3735
  /** Owner display identity for `/v1/info#owner`. Falls back to env vars. */
3963
3736
  owner?: OwnerDisplay;
@@ -3985,7 +3758,6 @@ interface DVMHostOpts {
3985
3758
  pool?: Pool;
3986
3759
  /** Cashu mints accepted. Defaults to env `DVMKIT_CASHU_MINTS`. */
3987
3760
  mints?: string[];
3988
- /** Cashu receive mode override. */
3989
3761
  cashuMode?: CashuMode;
3990
3762
  /** MPP handle override. Defaults to env-resolved via `createMppFromOpts`. */
3991
3763
  mpp?: MppxServer;
@@ -4008,9 +3780,7 @@ interface DVMHostOpts {
4008
3780
  onPaidJobCompleted?: (event: PaidJobCompletion) => void | Promise<void>;
4009
3781
  /** When true, payment is skipped only when no payment rail is configured. */
4010
3782
  devMode?: boolean;
4011
- /** Consumed-credential store override (test seam). */
4012
3783
  consumedCredentialStore?: ConsumedCredentialStore;
4013
- /** Mint-health tracker override (test seam). */
4014
3784
  mintHealthTracker?: MintHealthTracker;
4015
3785
  /** Operator-alert boundary for failed terminal-job retention passes. */
4016
3786
  onJobRetentionSweepFailed?: JobManagerOpts["onJobRetentionSweepFailed"];
@@ -4023,12 +3793,10 @@ interface DVMHostOpts {
4023
3793
  */
4024
3794
  wrapRouteClientCompatibility?: (sdkGate: ClientCompatibilityGate) => ClientCompatibilityGate;
4025
3795
  }
4026
- /** Per-mount options. Currently only `prefix` is supported. */
4027
3796
  interface MountOpts {
4028
3797
  /** Path prefix for this DVM's protocol routes (e.g. `/delete-feed`). */
4029
3798
  prefix?: string;
4030
3799
  }
4031
- /** Live DVM host. Single wiring locus for the SDK. */
4032
3800
  interface DVMHost {
4033
3801
  /**
4034
3802
  * Underlying Hono app for custom non-protocol routes that belong to the
@@ -4057,7 +3825,6 @@ interface DVMHost {
4057
3825
  * a single mount with no prefix attaches at root.
4058
3826
  */
4059
3827
  mount<S, I extends ZodLike | undefined>(descriptor: DVMDescriptor<S, I>, opts?: MountOpts): void;
4060
- /** Start listening. Returns the live server handle. */
4061
3828
  serve(opts?: {
4062
3829
  port?: number;
4063
3830
  }): Promise<DVMServeResult>;
@@ -4101,22 +3868,10 @@ interface TempoObserverHealth {
4101
3868
  /** Prime the cached signal at boot. */
4102
3869
  refresh?(): Promise<void>;
4103
3870
  /**
4104
- * Register a mount's `tempo/session` **capability** so the poll can carry it
4105
- * back to the platform.
4106
- *
4107
- * The platform's `dvms.tempo_session_advertised_at` — the only filter on the
4108
- * close observer's payee-fallback rung 2 — was written once per container
4109
- * deploy and never refreshed, so a builder flipping sessions on with
4110
- * `dvmctl env --set` stayed invisible to the fallback indefinitely. That is a
4111
- * `no_route` on the first close of that DVM's first channel, which is exactly
4112
- * the race the rung exists to cover.
4113
- *
4114
- * The reader must answer from **configuration**, never from
4115
- * {@link TempoObserverHealth.available} — a fail-closed gate blip must not
4116
- * de-stamp the DVM, which is the failure through a new door.
4117
- *
4118
- * Returns a disposer the mount calls on shutdown, so a torn-down capability
4119
- * stops voting in the OR below.
3871
+ * Report the OR of mounted session capabilities to keep the platform's
3872
+ * observer watch signal current. Readers must use configuration, not current
3873
+ * availability: an observer outage must not erase the capability it watches.
3874
+ * The returned disposer removes a mount's contribution on shutdown.
4120
3875
  */
4121
3876
  declareSessionCapability?(read: () => boolean): () => void;
4122
3877
  }
@@ -4164,7 +3919,6 @@ interface TempoSettlementReadinessStateStore {
4164
3919
  clearFailureIfRefilled(version: string, balanceMicro: bigint, lowBalanceMicro: bigint): Promise<boolean>;
4165
3920
  clearFailureAfterSuccessfulTransaction(version: string): Promise<boolean>;
4166
3921
  }
4167
- /** Construction inputs for {@link TempoSettlementReadiness}. */
4168
3922
  interface TempoSettlementReadinessOptions {
4169
3923
  address: `0x${string}`;
4170
3924
  network: string;
@@ -4211,7 +3965,6 @@ declare class TempoSettlementReadiness {
4211
3965
  start(): void;
4212
3966
  /** Stop the cadence without affecting any in-flight reading. */
4213
3967
  stop(): void;
4214
- /** Read and report the configured fee-token balance now. */
4215
3968
  checkBalance(opts?: {
4216
3969
  successfulTransaction?: boolean;
4217
3970
  recoveryVersion?: string;
@@ -4234,24 +3987,11 @@ declare class TempoSettlementReadiness {
4234
3987
  private notify;
4235
3988
  }
4236
3989
 
4237
- /**
4238
- * Options for the revenue reporter readiness assertion.
4239
- *
4240
- * The check branches on `platformUrl` presence — that's the unambiguous
4241
- * "platform-hosted" signal. `failFast` stays on the opts as a general SDK
4242
- * strict-mode flag but is not consulted by this assertion.
4243
- */
4244
3990
  interface RevenueBootCheckOpts {
4245
3991
  /**
4246
- * General SDK strict-mode flag, sourced from `DVMKIT_FAIL_FAST` at the host
4247
- * boundary. Reserved for future warning-vs-fatal SDK checks; the
4248
- * reporter check itself ignores it, hence optional.
3992
+ * Reporter readiness ignores this host strict-mode flag.
4249
3993
  */
4250
3994
  failFast?: boolean;
4251
- /**
4252
- * The SDK's canonical "this is a dev/test run" signal. Exempts the boot from
4253
- * the platform-hosted wiring requirement — see below.
4254
- */
4255
3995
  devMode?: boolean;
4256
3996
  platformToken: string | undefined;
4257
3997
  platformUrl: string | undefined;
@@ -4355,11 +4095,11 @@ interface SDKServerOpts {
4355
4095
  canonicalDvmId?: string;
4356
4096
  /** Postgres pool for builder admin state and wallet accumulator persistence. */
4357
4097
  db?: Pool;
4098
+ /** Enables authenticated, durable hosting admission and bounded drain. Requires Postgres and dvmId. */
4099
+ hostingControl?: HostingControlConfig;
4358
4100
  /**
4359
- * General SDK strict-mode flag, sourced from `DVMKIT_FAIL_FAST` at
4360
- * the host boundary. Reserved for future warning-vs-fatal SDK checks; the
4361
- * revenue-reporter boot check is gated on platform context, not on this
4362
- * flag.
4101
+ * Host strict-mode flag. Reporter readiness follows hosted context regardless
4102
+ * of this value.
4363
4103
  */
4364
4104
  failFast?: boolean;
4365
4105
  /** Agent-wallet: per-DVM identifier — drives the monitor advisory lock + replay key. */
@@ -4486,12 +4226,6 @@ interface SDKServerOpts {
4486
4226
  */
4487
4227
  creditExpirySweep?: CreditExpirySweepOpts;
4488
4228
  }
4489
- /**
4490
- * Builds a Hono sub-app for one DVM descriptor, wires payment verification,
4491
- * auto-wires `RevenueReporter` when platform env + db + dvmId are present, and
4492
- * runs the platform-hosted partial-wiring assertion — gated on
4493
- * `DVMKIT_PLATFORM_URL` presence, independent of `DVMKIT_FAIL_FAST`.
4494
- */
4495
4229
  declare function createDVMServer<State, InputSchema extends ZodLike | undefined>(descriptor: DVMDescriptor<State, InputSchema>, opts: SDKServerOpts): Promise<{
4496
4230
  app: Hono<AppEnv>;
4497
4231
  authAudience?: SignedRequestAudience;
@@ -4533,13 +4267,8 @@ interface AppEnv {
4533
4267
  declare function unknownRouteNotFound(c: Context): Response;
4534
4268
 
4535
4269
  /**
4536
- * The public prepaid-credit terms a DVM advertises before a caller identifies
4537
- * itself. Snake_case: this is the wire shape.
4538
- *
4539
- * This type deliberately excludes the per-caller echo. `/v1/info` is public
4540
- * and cacheable, so its type must make a caller credit ID or balance
4541
- * unrepresentable rather than relying on the current handler not to ask for
4542
- * one.
4270
+ * Public, cacheable prepaid terms exclude caller IDs and balances. toCreditTerms explicitly
4271
+ * whitelists this shape so later caller-specific menu fields cannot leak into /v1/info.
4543
4272
  */
4544
4273
  interface CreditTerms {
4545
4274
  /** Smallest funding accepted, in 1e-6 units of `currency`. */
@@ -4552,7 +4281,10 @@ interface CreditTerms {
4552
4281
  currency: string;
4553
4282
  /** Rails a top-up may be funded over. */
4554
4283
  funding: FundingMethod[];
4555
- /** MPP instruments offered or temporarily withheld for credit funding. */
4284
+ /**
4285
+ * Tempo methods are actionable. withheld names configured but temporarily unavailable
4286
+ * instruments, preserving capability discovery without advertising them for funding.
4287
+ */
4556
4288
  tempo?: {
4557
4289
  methods: {
4558
4290
  method: string;
@@ -4564,63 +4296,32 @@ interface CreditTerms {
4564
4296
  reason: string;
4565
4297
  }[];
4566
4298
  };
4567
- /** x402 flavours accepted for credit funding. */
4299
+ /**
4300
+ * Present with offered x402 funding. Reusable batch settlement is enabled by default; exact
4301
+ * requires explicit acceptance of its manual refund obligation.
4302
+ */
4568
4303
  x402?: {
4569
4304
  schemes: {
4570
4305
  scheme: string;
4571
4306
  network: string;
4572
4307
  }[];
4573
4308
  };
4574
- /** Smallest Lightning funding accepted, in 1e-6 units of `currency`. */
4309
+ /**
4310
+ * Configured Lightning receive floor in micro-units of currency, including the advertised
4311
+ * FX margin. Issuance checks the raw sats floor at current rates; arbitrary drift can still
4312
+ * make the advertised amount insufficient.
4313
+ */
4575
4314
  lightning_min_micro?: number;
4576
4315
  }
4577
4316
  /**
4578
- * The **funding menu** a DVM advertises on `/v1/quote` and in every 402;
4579
- * this is the snake_case wire shape.
4580
- *
4581
- * `min_micro` / `max_micro` / `ttl_ms` are the DVM's sizing terms — `max_micro`
4582
- * binds the **residual balance**, not a funding amount, so a job priced above
4583
- * it still clears as fund-and-immediately-draw. `funding` is the rail list a
4584
- * top-up may arrive on — a {@link FundingMethod}, not a `PaymentMethod`, since
4585
- * `lightning` funds a credit without ever being an attached-proof wire method.
4586
- * A rail whose backing wallet is unreachable drops out and the sale survives
4587
- * on the others.
4317
+ * Funding options and sizing in the wire denomination. max_micro limits residual balance,
4318
+ * not a job’s price; fund-and-draw can spend a larger payment immediately. Lightning funds
4319
+ * credit but is not an attached-proof payment method.
4588
4320
  *
4589
- * The `credit_id` / `balance_micro` / `remaining_micro` / `expiry_ms` echo
4590
- * appears only for an authenticated caller who already holds a live credit —
4591
- * so one round trip answers "what does this cost, and what do I have left?"
4592
- * through the signed credit endpoint.
4321
+ * An authenticated caller’s live credit may add an echo with funded and spendable balance;
4322
+ * pending holds are included only in the funded figure.
4593
4323
  */
4594
4324
  interface CreditMenu extends CreditTerms {
4595
- /**
4596
- * MPP instruments accepted for this credit, reusable sessions first when
4597
- * available.
4598
- *
4599
- * `withheld` names an instrument this DVM is configured for and is not
4600
- * offering at this instant, with the reason. Two audiences read
4601
- * it. An agent gets to relay *why* `tempo/session` vanished instead of
4602
- * inferring the DVM never had it. And the platform's deploy probe reads
4603
- * capability from `methods ∪ withheld`, so a deploy landing during an
4604
- * observer blip no longer stamps `tempo_session_advertised_at` NULL and
4605
- * drops the DVM out of the close observer's payee fallback permanently.
4606
- * `methods` stays the list a caller acts on — never widen it to include a
4607
- * withheld instrument.
4608
- */
4609
- /**
4610
- * Which x402 flavours a top-up may arrive on, and the chain each rides
4611
- * Present exactly when `funding` lists `x402`. Reusable
4612
- * `batch-settlement` is admitted by default; one-payment `exact` appears
4613
- * only when the builder explicitly accepts its manual refund obligation.
4614
- */
4615
- /**
4616
- * Smallest funding the `lightning` rail accepts, in 1e-6 units of
4617
- * `currency`. Present only when `funding` lists `lightning`. This is the
4618
- * deployment's sats-physical receive floor rendered into fiat
4619
- * with a ×{@link LIGHTNING_FLOOR_FX_MARGIN} margin absorbing rate drift
4620
- * between menu fetch and funding — issuance enforces the *raw* floor at
4621
- * request-time rates, so funding exactly this figure always clears. Rails
4622
- * without an entry (cashu) have no floor beyond `min_micro`.
4623
- */
4624
4325
  /** The caller's credit this echo describes. Present only with the echo. */
4625
4326
  credit_id?: string;
4626
4327
  /** Funded balance, pending holds NOT subtracted. */
@@ -4630,7 +4331,6 @@ interface CreditMenu extends CreditTerms {
4630
4331
  /** Absolute expiry of the echoed credit, ms since epoch. */
4631
4332
  expiry_ms?: number;
4632
4333
  }
4633
- /** Everything {@link buildCreditMenu} needs, assembled per request. */
4634
4334
  interface BuildCreditMenuArgs {
4635
4335
  /**
4636
4336
  * Which runtime is answering. `"isolate"` is refused unconditionally — see
@@ -4640,13 +4340,8 @@ interface BuildCreditMenuArgs {
4640
4340
  /** The DVM's resolved `credit` block; `undefined` means it didn't opt in. */
4641
4341
  config: ResolvedCreditConfig | undefined;
4642
4342
  /**
4643
- * Currency the menu — and the credit it funds — denominates in: the DVM's
4644
- * declared `DVMConfig.currency`, which every call site reads off the single
4645
- * `DVMServer.creditCurrency()`. Deliberately *not* the currency of
4646
- * the response this menu rides on: a quote priced elsewhere is refused before
4647
- * it reaches here, so the two agree, and sourcing it from the response is
4648
- * what left `POST /v1/credit` — which has no response to read — funding in
4649
- * hardwired USD at a DVM whose jobs draw in something else.
4343
+ * Use the DVM’s declared denomination, including /v1/credit where no quote response supplies
4344
+ * it. Quote validation refuses a different denomination before menu construction.
4650
4345
  */
4651
4346
  currency: string;
4652
4347
  /** Rails this DVM settles over — the menu's funding options. */
@@ -4662,31 +4357,19 @@ interface BuildCreditMenuArgs {
4662
4357
  intent: "charge" | "session";
4663
4358
  reason: string;
4664
4359
  }[];
4665
- /**
4666
- * x402 flavours this DVM can actually accept a top-up on — one
4667
- * server read, so what the sub-block advertises is what `/v1/credit` will
4668
- * answer a 402 with.
4669
- */
4670
4360
  x402Schemes?: {
4671
4361
  scheme: string;
4672
4362
  network: string;
4673
4363
  }[];
4674
4364
  /**
4675
- * The deployment's Lightning receive floor in sats, when `lightning` is on
4676
- * the menu — rendered into `lightning_min_micro`. An fx failure during that
4677
- * rendering drops `lightning` from `funding` rather than suppressing the
4678
- * menu: a rail whose minimum we can't state honestly is a rail we must not
4679
- * advertise, but the other rails' sale survives.
4365
+ * Configured raw receive floor in sats, rendered with an FX margin for the menu. Failure
4366
+ * omits Lightning while allowing the rest of the menu; issuance checks the raw floor at
4367
+ * current request-time rates.
4680
4368
  */
4681
4369
  lightningFundingMinSats?: number;
4682
4370
  /**
4683
- * Whether this DVM has at least one accepted Cashu mint configured
4684
- * Without one, no Bitcoin funding rail may be advertised — see
4685
- * the filter in {@link buildCreditMenu}.
4686
- *
4687
- * Read off the **configured** mint list, never the health-filtered
4688
- * advertised one: a mint blip must not make a funding rail appear and
4689
- * disappear between quotes.
4371
+ * Read the configured accepted mint list, not its health-filtered advertisement. Non-channel
4372
+ * Bitcoin refunds need a mint, but configuration alone does not establish refund solvency.
4690
4373
  */
4691
4374
  hasAcceptedMint?: boolean;
4692
4375
  fxFetcher: FxFetcher;
@@ -4699,50 +4382,18 @@ interface BuildCreditMenuArgs {
4699
4382
  callerPubkey?: string;
4700
4383
  }
4701
4384
  /**
4702
- * Assemble the funding menu, or return `undefined` when this DVM must not
4703
- * advertise credit. **The refusal ladder is the feature**; each rung exists
4704
- * because advertising anyway would misadvertise:
4705
- *
4706
- * 1. **Isolate runtime** (the isolate-runtime rule) — checked first and unconditionally,
4707
- * before config is even read. Isolate DVMs have no Postgres of their own;
4708
- * their only DVM-side persistence is the last-write-wins callback KV, which
4709
- * the durable-ledger requirement prohibits for credit state. Until isolate
4710
- * runtimes have durable credit storage, they run implicit N=1 only and their quote never offers
4711
- * credit so nothing is misadvertised.
4712
- * 2. **Not opted in** — no `credit` block on `configureDVM`.
4713
- * 3. **No descriptor auth** — a credit belongs to a verified secp256k1 pubkey.
4714
- * Without auth the ledger's funder identity degrades to the requester id or
4715
- * `"anonymous"` (see `resolveLedgerContext`), which would pool every
4716
- * anonymous caller's money into one balance. Advertising a per-caller
4717
- * balance on such a DVM would be a lie at best and a disclosure at worst.
4718
- * 4. **Non-durable ledger outside devMode** — a `MemoryCreditLedger` is
4719
- * per-process, so a caller funding on machine A and drawing on machine B
4720
- * gets `credit_not_found`. Advertise only what survives the fleet.
4721
- * 5. **Bounds not expressible in `currency`** — an fx outage, or a currency the
4722
- * snapshot doesn't carry. Omit rather than quote a number we can't state.
4723
- *
4724
- * The balance echo is added only when a verified `callerPubkey` holds a live,
4725
- * same-currency credit.
4385
+ * Return no menu for static ineligibility or unresolvable denomination bounds. Isolates
4386
+ * currently lack durable credit storage; anonymous balances must not be advertised.
4726
4387
  *
4727
- * Rungs 1–4 live in {@link creditMenuConfigured}, which the capability refresh
4728
- * reads too.
4388
+ * Select the caller echo only from live, same-currency credits with spendable value.
4729
4389
  */
4730
4390
  declare function buildCreditMenu(args: BuildCreditMenuArgs): Promise<CreditMenu | undefined>;
4731
4391
  /**
4732
- * The one credit a caller's quote echoes, from the several they may hold —
4733
- * every implicit N=1 payment mints its own `imp:<rail>:<paymentId>` credit, so
4734
- * this list grows with each paid job.
4392
+ * Choose the largest live, active, same-currency spendable balance; newest creation breaks
4393
+ * a tie. Released implicit payments can hold reclaimable value and are eligible too.
4735
4394
  *
4736
- * Live, same-currency credits with something left in them; largest spendable
4737
- * balance wins, newest breaks a tie. That is the credit a caller would in fact
4738
- * draw against next. A failed job's released hold leaves a positive implicit
4739
- * balance, which is real caller money (the credit lifecycle contract, no debit on failure) and is
4740
- * echoed like any other.
4741
- *
4742
- * **Requires a verified pubkey.** Never call this with a requester id or
4743
- * `"anonymous"`: on an auth-less DVM the ledger pools every anonymous caller
4744
- * under one `caller_pubkey`, so echoing it would show one caller another's
4745
- * balance.
4395
+ * The caller supplies a verified pubkey. Anonymous/missing identity returns no credit; the
4396
+ * ledger’s anonymous pool must not be exposed to an individual caller.
4746
4397
  */
4747
4398
  declare function selectPrimaryCredit(args: {
4748
4399
  ledger: CreditLedgerLike;
@@ -4750,21 +4401,16 @@ declare function selectPrimaryCredit(args: {
4750
4401
  currency: string;
4751
4402
  nowMs?: number;
4752
4403
  }): Promise<CreditSnapshot | undefined>;
4753
- /** Narrow a ledger snapshot to the read-only shape a quote handler receives. */
4754
4404
  declare function toCreditView(snapshot: CreditSnapshot): CreditView;
4755
4405
  /**
4756
- * Attach a menu to a response body when there is one. Keeps the "omit the key
4757
- * entirely rather than emit `credit: null`" rule in one place — every consumer
4758
- * checks presence, and the isolate tier depends on the key never appearing.
4406
+ * Omit the credit key entirely when there is no menu; consumers use presence to determine
4407
+ * whether credit is offered.
4759
4408
  */
4760
4409
  declare function attachCreditMenu(body: Record<string, unknown>, menu: CreditMenu | undefined): Record<string, unknown>;
4761
4410
  /**
4762
- * Project a quote/402 menu onto the public, cache-safe `/v1/info` terms.
4763
- *
4764
- * This is an explicit whitelist rather than object rest syntax: a later
4765
- * caller-specific field added to {@link CreditMenu} cannot cross this boundary
4766
- * until someone deliberately adds it to {@link CreditTerms} and this copy.
4411
+ * Explicitly whitelist public /v1/info terms. A future caller-specific menu field cannot
4412
+ * cross this cacheable boundary merely by being added to CreditMenu.
4767
4413
  */
4768
4414
  declare function toCreditTerms(menu: CreditMenu): CreditTerms;
4769
4415
 
4770
- export { isTerminal as $, type AccumulatorPool as A, buildPaymentErrorResponse as B, type ConsumedCredentialStore as C, clearAccumulatorForDvm as D, createDVMServer as E, type FiatDenomination as F, creditDepositPayload as G, derivedFundCreditId as H, type IncomingPaymentOpts as I, JobCancelledError as J, devModeSkipsPaymentVerification as K, fromJobRecord as L, MintHealthTracker as M, fundedMicroFor as N, hasPaymentProof as O, PAYMENT_PROOF_KEYS as P, hashLockKey as Q, type ReporterBannerOpts as R, type SDKServerOpts as S, type TempoChannelReport as T, type UpfrontPaymentOpts as U, type VerifiedIncomingPayment as V, implicitCreditId as W, type X402BatchChannelObservation as X, initWalletAccumulatorTable as Y, insertAccumulatorRows as Z, isDerivedCreditId as _, type AccumulatorQuerier as a, type X402ExactSettlementAttempt as a$, isYieldMessage as a0, issueUpfrontChallenges as a1, msatsToFiatMicro as a2, paymentErrorBody as a3, pinAskFiat as a4, priceFiatMicro as a5, processIncomingPayment as a6, providerMessage as a7, repairX402ExactSettlementEffect as a8, resolveFxSnapshot as a9, JobManager as aA, type JobManagerOpts as aB, type LightningReceiveConfig as aC, MIN_INVOICE_TTL_SECONDS as aD, MemoryConsumedCredentialStore as aE, type MemoryConsumedCredentialStoreOpts as aF, MemoryProcessedPaymentStore as aG, MemoryX402ExactSettlementStore as aH, type MountOpts as aI, type OwnerDisplay as aJ, type PaidJobCompletion as aK, type PaymentMode as aL, type PlatformReporterOpts as aM, PostgresProcessedPaymentStore as aN, PostgresX402ExactSettlementStore as aO, type PriceFiat as aP, type ProcessedPaymentQuerier as aQ, type ProcessedPaymentRail as aR, type ProcessedPaymentRecord as aS, ProcessedPaymentReplayError as aT, type ProcessedPaymentStore as aU, type X402BatchAcceptance as aV, type X402BatchFunding as aW, type X402BatchRefusal as aX, type X402BatchSettlementServer as aY, type X402ExactAcceptance as aZ, X402ExactIntentConflictError as a_, resolvePriceFiat as aa, revenueReporterBannerState as ab, toCreditTerms as ac, toJobRecord as ad, unknownRouteNotFound as ae, verifyIncomingPayment as af, verifyTempoSessionManagementCredential as ag, verifyUpfrontPayment as ah, x402RequiredUsdcMicro as ai, x402SettledShare as aj, type CreditMenu as ak, ReceiptIssuer as al, LightningReceive as am, TempoSettlementReadiness as an, type DVMHostOpts as ao, type DVMServeResult as ap, type BuildCreditMenuArgs as aq, type BuilderIdentity as ar, CREDIT_ENVELOPE_KEYS as as, type CreateX402BatchSettlementServerOpts as at, type CreditEnvelope as au, CreditEnvelopeError as av, type CreditFundCommitment as aw, type CreditTerms as ax, DEFAULT_INVOICE_TTL_SECONDS as ay, type DVMHost as az, type AppEnv as b, type X402ExactSettlementChainEvidence as b0, type X402ExactSettlementEffect as b1, X402ExactSettlementEvidenceMissingError as b2, type X402ExactSettlementEvidenceReader as b3, type X402ExactSettlementIntent as b4, X402ExactSettlementNotReadyError as b5, X402ExactSettlementServer as b6, type X402ExactSettlementServerOpts as b7, type X402ExactSettlementStatus as b8, type X402ExactSettlementStore as b9, type X402SettlementChainEvidence as ba, type X402SettlementEvidenceReader as bb, X402SettlementSubmissionError as bc, X402_BATCH_AUTO_SETTLEMENT as bd, X402_BATCH_MIN_WITHDRAW_DELAY_SECONDS as be, X402_BATCH_SETTLEMENT_NETWORK as bf, attachCreditMenu as bg, buildCreditMenu as bh, createDVMHost as bi, createX402BatchSettlementServer as bj, creditEnvelopeIgnoreFields as bk, drawSettlementRef as bl, extractCreditEnvelope as bm, fundingCommitment as bn, selectPrimaryCredit as bo, stripCreditEnvelope as bp, toCreditView as bq, type CreditFundingReport as c, type FiatDenominationFailure as d, type FundOnlyRequest as e, type PaymentErrorCode as f, type PaymentErrorDetail as g, type PaymentInfo as h, type ResolvedFx as i, type RevenueBootCheckOpts as j, type ServerJob as k, type ShortPayForfeit as l, type TempoObserverHealth as m, TempoSessionChannelMismatchError as n, type VerifyIncomingSnapshot as o, X402FacilitatorHealth as p, type X402SettlementEvidenceOutcome as q, type X402SettlementRepair as r, type X402SettlementRepairRefusal as s, type X402SettlementRepaired as t, type X402WedgedSettlement as u, type X402WedgedSettlementPage as v, X402_BATCH_SETTLEMENT_MAINNET_NETWORK as w, abortJob as x, applyPaymentInfoToJob as y, assertRevenueReporterReady as z };
4416
+ export { isTerminal as $, type AccumulatorPool as A, buildPaymentErrorResponse as B, type ConsumedCredentialStore as C, clearAccumulatorForDvm as D, createDVMServer as E, type FiatDenomination as F, creditDepositPayload as G, derivedFundCreditId as H, type IncomingPaymentOpts as I, JobCancelledError as J, devModeSkipsPaymentVerification as K, fromJobRecord as L, MintHealthTracker as M, fundedMicroFor as N, hasPaymentProof as O, PAYMENT_PROOF_KEYS as P, hashLockKey as Q, type ReporterBannerOpts as R, type SDKServerOpts as S, type TempoChannelReport as T, type UpfrontPaymentOpts as U, type VerifiedIncomingPayment as V, implicitCreditId as W, type X402BatchChannelObservation as X, initWalletAccumulatorTable as Y, insertAccumulatorRows as Z, isDerivedCreditId as _, type AccumulatorQuerier as a, type X402BatchSettlementServer as a$, isYieldMessage as a0, issueUpfrontChallenges as a1, msatsToFiatMicro as a2, paymentErrorBody as a3, pinAskFiat as a4, priceFiatMicro as a5, processIncomingPayment as a6, providerMessage as a7, repairX402ExactSettlementEffect as a8, resolveFxSnapshot as a9, type HostingControlCommand as aA, type HostingControlConfig as aB, type HostingControlStatus as aC, JobManager as aD, type JobManagerOpts as aE, type LightningReceiveConfig as aF, MIN_INVOICE_TTL_SECONDS as aG, MemoryConsumedCredentialStore as aH, type MemoryConsumedCredentialStoreOpts as aI, MemoryProcessedPaymentStore as aJ, MemoryX402ExactSettlementStore as aK, type MountOpts as aL, type OwnerDisplay as aM, type PaidJobCompletion as aN, type PaymentMode as aO, type PlatformReporterOpts as aP, PostgresProcessedPaymentStore as aQ, PostgresX402ExactSettlementStore as aR, type PriceFiat as aS, type ProcessedPaymentQuerier as aT, type ProcessedPaymentRail as aU, type ProcessedPaymentRecord as aV, ProcessedPaymentReplayError as aW, type ProcessedPaymentStore as aX, type X402BatchAcceptance as aY, type X402BatchFunding as aZ, type X402BatchRefusal as a_, resolvePriceFiat as aa, revenueReporterBannerState as ab, toCreditTerms as ac, toJobRecord as ad, unknownRouteNotFound as ae, verifyIncomingPayment as af, verifyTempoSessionManagementCredential as ag, verifyUpfrontPayment as ah, x402RequiredUsdcMicro as ai, x402SettledShare as aj, type CreditMenu as ak, ReceiptIssuer as al, LightningReceive as am, TempoSettlementReadiness as an, type DVMHostOpts as ao, type DVMServeResult as ap, type BuildCreditMenuArgs as aq, type BuilderIdentity as ar, CREDIT_ENVELOPE_KEYS as as, type CreateX402BatchSettlementServerOpts as at, type CreditEnvelope as au, CreditEnvelopeError as av, type CreditFundCommitment as aw, type CreditTerms as ax, DEFAULT_INVOICE_TTL_SECONDS as ay, type DVMHost as az, type AppEnv as b, type X402ExactAcceptance as b0, X402ExactIntentConflictError as b1, type X402ExactSettlementAttempt as b2, type X402ExactSettlementChainEvidence as b3, type X402ExactSettlementEffect as b4, X402ExactSettlementEvidenceMissingError as b5, type X402ExactSettlementEvidenceReader as b6, type X402ExactSettlementIntent as b7, X402ExactSettlementNotReadyError as b8, X402ExactSettlementServer as b9, type X402ExactSettlementServerOpts as ba, type X402ExactSettlementStatus as bb, type X402ExactSettlementStore as bc, type X402SettlementChainEvidence as bd, type X402SettlementEvidenceReader as be, X402SettlementSubmissionError as bf, X402_BATCH_AUTO_SETTLEMENT as bg, X402_BATCH_MIN_WITHDRAW_DELAY_SECONDS as bh, X402_BATCH_SETTLEMENT_NETWORK as bi, attachCreditMenu as bj, buildCreditMenu as bk, createDVMHost as bl, createX402BatchSettlementServer as bm, creditEnvelopeIgnoreFields as bn, drawSettlementRef as bo, extractCreditEnvelope as bp, fundingCommitment as bq, selectPrimaryCredit as br, signHostingControl as bs, stripCreditEnvelope as bt, toCreditView as bu, type CreditFundingReport as c, type FiatDenominationFailure as d, type FundOnlyRequest as e, type PaymentErrorCode as f, type PaymentErrorDetail as g, type PaymentInfo as h, type ResolvedFx as i, type RevenueBootCheckOpts as j, type ServerJob as k, type ShortPayForfeit as l, type TempoObserverHealth as m, TempoSessionChannelMismatchError as n, type VerifyIncomingSnapshot as o, X402FacilitatorHealth as p, type X402SettlementEvidenceOutcome as q, type X402SettlementRepair as r, type X402SettlementRepairRefusal as s, type X402SettlementRepaired as t, type X402WedgedSettlement as u, type X402WedgedSettlementPage as v, X402_BATCH_SETTLEMENT_MAINNET_NETWORK as w, abortJob as x, applyPaymentInfoToJob as y, assertRevenueReporterReady as z };