@dvmkit/sdk 0.0.0 → 0.1.0-rc.1

package/dist/chunk-RPXHKMYE.js

@@ -0,0 +1,3808 @@
+import {
+  applyRetryToPool
+} from "./chunk-H25M54MI.js";
+import {
+  withSdkInitLock
+} from "./chunk-S3XAHZQY.js";
+
+// src/sdk/server/credit-ledger.ts
+import { randomUUID } from "crypto";
+
+// src/sdk/server/credit-lots.ts
+var NON_CHANNEL_BITCOIN_RAILS = [
+  "cashu",
+  "lightning"
+];
+function isNonChannelBitcoinRail(rail) {
+  return typeof rail === "string" && NON_CHANNEL_BITCOIN_RAILS.includes(rail);
+}
+function depleteLots(lots, amountMicro) {
+  const debits = [];
+  let left = Math.max(0, amountMicro);
+  let satsOwed = 0;
+  let backedMicro = 0;
+  for (const lot of lots) {
+    if (left <= 0) break;
+    const available = Math.max(0, lot.remainingMicro);
+    if (available === 0) continue;
+    const micro = Math.min(available, left);
+    const sats = lotSats(lot, available) - lotSats(lot, available - micro);
+    debits.push({ lotId: lot.lotId, micro, sats });
+    satsOwed += sats;
+    if (lot.satsFunded > 0) backedMicro += micro;
+    left -= micro;
+  }
+  return { debits, satsOwed, uncoveredMicro: left, backedMicro };
+}
+function inKindDrawMsats(depletion, amountMicro) {
+  return isInKindDepletion(depletion, amountMicro) ? depletion.satsOwed * 1e3 : null;
+}
+function lotOwedSats(lots) {
+  return lots.reduce((sum, lot) => sum + lotSats(lot, lot.remainingMicro), 0);
+}
+var DRAIN_DELIVERY_RESERVE_SATS = 8;
+function netOwedSats(grossSats) {
+  return Math.max(0, grossSats - DRAIN_DELIVERY_RESERVE_SATS);
+}
+function fifoOrder(left, right) {
+  return left.createdAt - right.createdAt || left.lotId.localeCompare(right.lotId);
+}
+function isInKindDepletion(depletion, amountMicro) {
+  return depletion.uncoveredMicro === 0 && depletion.backedMicro === amountMicro && amountMicro > 0;
+}
+function lotSats(lot, micro) {
+  if (lot.satsFunded <= 0 || lot.creditedMicro <= 0 || micro <= 0) return 0;
+  const taken = Math.min(micro, lot.creditedMicro);
+  return Math.floor(lot.satsFunded * taken / lot.creditedMicro);
+}
+
+// src/sdk/server/x402-channel-store.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { isDeepStrictEqual } from "util";
+var X402SettlementRaceError = class extends Error {
+};
+var X402RelaySubmissionLockError = class extends Error {
+  constructor(lockKey, timeoutMs, holder) {
+    super(
+      `x402 self-relay submission lock '${lockKey}' still held after ${String(timeoutMs)}ms${holder ? ` (held by ${describeHolder(holder)})` : ""}`
+    );
+    this.lockKey = lockKey;
+    this.timeoutMs = timeoutMs;
+    this.holder = holder;
+    this.name = "X402RelaySubmissionLockError";
+  }
+  lockKey;
+  timeoutMs;
+  holder;
+  code = "x402_relay_submission_lock_timeout";
+  retryable = true;
+};
+var X402_WEDGED_SETTLEMENT_STATUSES = ["submitting", "settled"];
+var X402_RESOLVED_SETTLEMENT_STATUSES = [
+  ...X402_WEDGED_SETTLEMENT_STATUSES,
+  "written_off"
+];
+var X402_SPEND_BLOCKING_SETTLEMENT_STATUSES = [
+  ...X402_WEDGED_SETTLEMENT_STATUSES,
+  "written_off"
+];
+var SETTLEMENT_POOL_MAX = 5;
+var SETTLEMENT_CONNECT_TIMEOUT_MS = 1e4;
+var FLEET_LOCK_TIMEOUT_MS = 3e4;
+var RELAY_SUBMISSION_LOCK_TIMEOUT_MS = 3e4;
+var LOCK_NOT_AVAILABLE = "55P03";
+var PostgresX402ChannelStorage = class {
+  constructor(pool, opts) {
+    this.pool = pool;
+    this.relayLockTimeoutMs = opts?.relaySubmissionLockTimeoutMs ?? RELAY_SUBMISSION_LOCK_TIMEOUT_MS;
+    this.terminalizeUnbackedCredit = opts?.terminalizeUnbackedCredit;
+    if (!Number.isInteger(this.relayLockTimeoutMs) || this.relayLockTimeoutMs <= 0) {
+      throw new Error("relaySubmissionLockTimeoutMs must be a positive integer number of ms");
+    }
+  }
+  pool;
+  transaction = new AsyncLocalStorage();
+  refundBase = new AsyncLocalStorage();
+  settlementPool;
+  fleetLock = Promise.resolve();
+  fleetLockQueueDepth = 0;
+  relayLockTimeoutMs;
+  terminalizeUnbackedCredit;
+  /** Create the durable channel table under the SDK-wide DDL lock. */
+  async init() {
+    this.settlementPool ??= createSettlementPool(this.pool);
+    await withSdkInitLock(this.pool, async () => {
+      await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS x402_batch_channels (
+          channel_id                  TEXT PRIMARY KEY,
+          channel_config              JSONB NOT NULL,
+          charged_cumulative_amount   NUMERIC(78, 0) NOT NULL,
+          signed_max_claimable         NUMERIC(78, 0) NOT NULL,
+          signature                   TEXT NOT NULL,
+          balance                     NUMERIC(78, 0) NOT NULL,
+          total_claimed                NUMERIC(78, 0) NOT NULL,
+          withdraw_requested_at        BIGINT NOT NULL,
+          refund_nonce                 BIGINT NOT NULL,
+          onchain_synced_at             BIGINT,
+          last_request_timestamp       BIGINT NOT NULL,
+          pending_request              JSONB
+        )
+      `);
+      await this.pool.query(
+        `CREATE INDEX IF NOT EXISTS idx_x402_batch_channels_withdrawal
+           ON x402_batch_channels(withdraw_requested_at)
+         WHERE withdraw_requested_at <> 0`
+      );
+      await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS x402_batch_settlements (
+          settlement_id       TEXT PRIMARY KEY,
+          channel_id          TEXT NOT NULL,
+          operation           TEXT NOT NULL CHECK (operation IN ('fund', 'refund')),
+          effect_id           TEXT NOT NULL,
+          payment_id          TEXT NOT NULL,
+          payment_payload     JSONB NOT NULL,
+          payment_requirements JSONB NOT NULL,
+          channel_before      JSONB,
+          submission_block    NUMERIC(78, 0),
+          pending_id          TEXT,
+          status              TEXT NOT NULL,
+          settle_response     JSONB,
+          created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          UNIQUE (operation, effect_id),
+          UNIQUE (operation, payment_id)
+        )
+      `);
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements ADD COLUMN IF NOT EXISTS channel_before JSONB`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements ADD COLUMN IF NOT EXISTS submission_block NUMERIC(78, 0)`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements ADD COLUMN IF NOT EXISTS channel_at_submission JSONB`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements ADD COLUMN IF NOT EXISTS write_off_note TEXT`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements ADD COLUMN IF NOT EXISTS resolved_at BIGINT`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements
+           DROP CONSTRAINT IF EXISTS x402_batch_settlements_status_check`
+      );
+      await this.pool.query(
+        `ALTER TABLE x402_batch_settlements
+           ADD CONSTRAINT x402_batch_settlements_status_check
+           CHECK (status IN ('prepared', 'submitting', 'settled', 'complete', 'written_off'))`
+      );
+      await this.pool.query(`DROP INDEX IF EXISTS idx_x402_batch_settlements_repair`);
+      await this.pool.query(
+        `CREATE INDEX IF NOT EXISTS idx_x402_batch_settlements_repair_created
+           ON x402_batch_settlements(created_at, settlement_id)
+         WHERE status IN ('submitting', 'settled', 'written_off')`
+      );
+      await this.pool.query(
+        `CREATE INDEX IF NOT EXISTS idx_x402_batch_settlements_channel_open
+           ON x402_batch_settlements(channel_id, created_at)
+         WHERE operation = 'refund'
+           AND status IN ('submitting', 'settled', 'written_off')`
+      );
+      await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS x402_batch_settlement_state (
+          scope          TEXT PRIMARY KEY,
+          pending_settle BOOLEAN NOT NULL,
+          updated_at     BIGINT NOT NULL
+        )
+      `);
+    });
+  }
+  /**
+   * Read the fleet's durable "claimed funds are awaiting transfer" marker.
+   *
+   * Upstream keeps this in process memory, which a multi-machine fleet cannot
+   * share: the machine that won a claim tick is rarely the one that wins the
+   * next settle tick. An unset scope reads false, so a receiver that has never
+   * claimed never submits a settlement.
+   *
+   * Both accessors run on the settlement pool: every caller reads or writes the
+   * marker while {@link withFleetSettlementLock} holds a host-pool client, which
+   * is the nesting the internal-review split exists to keep off a non-terminal pool.
+   */
+  async isSettlePending(scope) {
+    const reader = await this.settlementWriter();
+    const { rows } = await reader.query(
+      `SELECT pending_settle FROM x402_batch_settlement_state WHERE scope = $1`,
+      [scope]
+    );
+    return rows[0]?.pending_settle ?? false;
+  }
+  /** Record whether a claim's funds still need a `settle(receiver, token)` transfer. */
+  async setSettlePending(scope, pending) {
+    const writer = await this.settlementWriter();
+    await writer.query(
+      `INSERT INTO x402_batch_settlement_state (scope, pending_settle, updated_at)
+         VALUES ($1, $2, $3)
+       ON CONFLICT (scope) DO UPDATE
+         SET pending_settle = EXCLUDED.pending_settle,
+             updated_at = EXCLUDED.updated_at`,
+      [scope, pending, Date.now()]
+    );
+  }
+  /**
+   * Look up the durable settlement state for one credit-ledger effect.
+   *
+   * On the dedicated settlement pool like every other marker, and for a sharper
+   * reason than they had: this and {@link prepareSettlement} now run *inside*
+   * the channel transaction (internal-review), which holds a host-pool client for its
+   * whole duration. Taking a second client from that same pool is the
+   * self-deadlock internal-review fixed — at pool max every client is a holder and a
+   * waiter — and moving these calls under the transaction is exactly what would
+   * reintroduce it.
+   */
+  async getSettlement(operation, effectId) {
+    const { rows } = await (await this.settlementWriter()).query(
+      `SELECT * FROM x402_batch_settlements WHERE operation = $1 AND effect_id = $2`,
+      [operation, effectId]
+    );
+    return rows[0] ? toSettlementIntent(rows[0]) : void 0;
+  }
+  /**
+   * The refund on this channel that is neither finished nor abandoned, if there
+   * is one — the credit ledger's spend gate (internal-review).
+   *
+   * `statuses` is the caller's, because the two gates disagree by design: a
+   * draw is blocked by {@link X402_SPEND_BLOCKING_SETTLEMENT_STATUSES}, a fresh
+   * drain only by {@link X402_WEDGED_SETTLEMENT_STATUSES}.
+   *
+   * On the dedicated settlement pool, and that is what makes the gate callable
+   * at all: a draw routinely runs inside an open channel transaction holding a
+   * host-pool client, and taking a second one from that pool is the internal-review
+   * self-deadlock. The oldest blocking row wins, so a channel that somehow
+   * accumulated two names the one an operator should reach for first.
+   *
+   * Projects three columns rather than decoding a whole {@link
+   * X402SettlementIntent}: the decoder refuses a pre-internal-review row that carries
+   * no reconciliation snapshot, and a gate that throws on one would take every
+   * draw on that channel down with it — when the row is exactly the kind that
+   * ought to block them.
+   */
+  async pendingRefundSettlement(channelId, statuses) {
+    const { rows } = await (await this.settlementWriter()).query(
+      `SELECT settlement_id, effect_id, status FROM x402_batch_settlements
+        WHERE channel_id = $1 AND operation = 'refund' AND status = ANY($2::text[])
+        ORDER BY created_at, settlement_id
+        LIMIT 1`,
+      [normalizeChannelId(channelId), statuses]
+    );
+    if (rows.length === 0) return void 0;
+    const row = rows[0];
+    return { settlementId: row.settlement_id, effectId: row.effect_id, status: row.status };
+  }
+  /**
+   * Read one settlement by its own identifier — the handle an operator holds
+   * (internal-review). Same dedicated pool as {@link getSettlement}, for the same
+   * reason: the repair reads this while a channel transaction may be open.
+   */
+  async getSettlementById(settlementId) {
+    const { rows } = await (await this.settlementWriter()).query(`SELECT * FROM x402_batch_settlements WHERE settlement_id = $1`, [
+      settlementId
+    ]);
+    return rows[0] ? toSettlementIntent(rows[0]) : void 0;
+  }
+  /** Lazily move a legacy settlement row onto its authorization/effect-scoped replay key. */
+  async normalizeLegacyPaymentId(settlementId, operation, legacyPaymentId, paymentId) {
+    const writer = await this.settlementWriter();
+    const updated = await writer.query(
+      `UPDATE x402_batch_settlements
+          SET payment_id = $3
+        WHERE settlement_id = $1 AND operation = $4 AND payment_id = $2
+        RETURNING *`,
+      [settlementId, legacyPaymentId, paymentId, operation]
+    );
+    if (updated.rows[0]) return toSettlementIntent(updated.rows[0]);
+    const existing = await this.getSettlementById(settlementId);
+    if (existing?.operation === operation && existing.paymentId === paymentId) return existing;
+    throw new Error(`x402 settlement ${settlementId} legacy payment identity changed`);
+  }
+  /**
+   * The operator's repair queue: settlements stuck between "chain paid" and
+   * "ledger booked", oldest write first (internal-review).
+   *
+   * Keyset-paginated on `(created_at, settlement_id)` for the reason the
+   * blocked-invoice queue is: a wedged row never self-clears, so a fixed first
+   * page of rows the operator has declined to act on would starve everything
+   * behind it on every run, forever.
+   *
+   * The keyset is on `created_at`, which never moves, while `updatedBeforeMs`
+   * filters on `updated_at`, which does — so a row an operator touches mid-walk
+   * can leave the queue but can never jump the cursor and be skipped. The cursor
+   * itself is Postgres's text rendering of that timestamp, handed back verbatim;
+   * see {@link X402SettlementCursor} for why a `Date` cannot carry it.
+   *
+   * `updatedBeforeMs` is the staleness floor. A healthy settlement passes
+   * through `submitting` and `settled` inside one request, so anything younger
+   * than the floor is in flight rather than wedged and must not be offered as
+   * repairable work.
+   */
+  async listSettlements(args) {
+    const { rows } = await (await this.settlementWriter()).query(
+      `SELECT *, created_at::text AS created_at_key FROM x402_batch_settlements
+        WHERE status = ANY($1::text[])
+          AND updated_at <= to_timestamp($2::double precision / 1000)
+          AND ($3::text IS NULL
+               OR (created_at, settlement_id) > ($3::timestamptz, $4::text))
+        ORDER BY created_at, settlement_id
+        LIMIT $5`,
+      [
+        args.statuses,
+        args.updatedBeforeMs,
+        args.after?.createdAt ?? null,
+        args.after?.settlementId ?? null,
+        args.limit
+      ]
+    );
+    const last = rows.length === args.limit ? rows[rows.length - 1] : void 0;
+    return {
+      settlements: rows.map(toSettlementIntent),
+      ...last ? { nextAfter: { createdAt: last.created_at_key, settlementId: last.settlement_id } } : {}
+    };
+  }
+  /**
+   * Close a wedged settlement without booking anything (internal-review).
+   *
+   * A single-statement CAS on the wedged statuses, on the settlement pool —
+   * there is no ledger effect to be atomic with, which is the whole point:
+   * the write-off records that an operator reviewed this settlement and is not
+   * completing it, and no dvmkit table moves. Idempotent, and the first note
+   * wins; `written` is the transition bit the caller logs on, so the one place
+   * the amount is ever recorded gets exactly one entry.
+   *
+   * Reversible by construction: a later reconcile calls
+   * {@link recordSettlementResponse}, whose `status <> 'complete'` CAS lifts a
+   * written-off row back to `settled`.
+   */
+  async writeOffSettlement(settlementId, note, nowMs) {
+    const writer = await this.settlementWriter();
+    const updated = await writer.query(
+      `UPDATE x402_batch_settlements
+          SET status = 'written_off', write_off_note = $2, resolved_at = $3, updated_at = NOW()
+        WHERE settlement_id = $1 AND status = ANY($4::text[])
+        RETURNING *`,
+      [settlementId, note ?? null, nowMs, X402_WEDGED_SETTLEMENT_STATUSES]
+    );
+    if (updated.rows[0]) return { intent: toSettlementIntent(updated.rows[0]), written: true };
+    const existing = await this.getSettlementById(settlementId);
+    return existing ? { intent: existing, written: false } : void 0;
+  }
+  /** Persist the reconciliation identity, refreshing a prepared retry's transient reservation. */
+  async prepareSettlement(intent) {
+    const settlements = await this.settlementWriter();
+    await settlements.query(
+      `INSERT INTO x402_batch_settlements (
+         settlement_id, channel_id, operation, effect_id, payment_id,
+         payment_payload, payment_requirements, channel_before, pending_id, status
+       ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'prepared')
+       ON CONFLICT DO NOTHING`,
+      [
+        intent.settlementId,
+        normalizeChannelId(intent.channelId),
+        intent.operation,
+        intent.effectId,
+        intent.paymentId,
+        intent.payload,
+        intent.requirements,
+        intent.channelBefore,
+        intent.pendingId ?? null
+      ]
+    );
+    const { rows } = await settlements.query(
+      `SELECT * FROM x402_batch_settlements
+        WHERE settlement_id = $1
+           OR (operation = $2 AND effect_id = $3)
+           OR (operation = $2 AND payment_id = $4)
+        ORDER BY settlement_id = $1 DESC
+        LIMIT 1`,
+      [intent.settlementId, intent.operation, intent.effectId, intent.paymentId]
+    );
+    let stored = rows[0] ? toSettlementIntent(rows[0]) : void 0;
+    if (stored?.settlementId !== intent.settlementId || stored.channelId !== normalizeChannelId(intent.channelId) || stored.operation !== intent.operation || stored.effectId !== intent.effectId) {
+      throw new Error("x402 settlement identity conflicts with a prior credit effect");
+    }
+    if (stored.paymentId !== intent.paymentId || !isDeepStrictEqual(stored.payload, intent.payload) || !isDeepStrictEqual(stored.requirements, intent.requirements)) {
+      if (!canRefreshPreparedDepositAuthorization(stored, intent, Date.now())) {
+        throw new Error("x402 settlement identity conflicts with a prior credit effect");
+      }
+      const refreshed = await settlements.query(
+        `UPDATE x402_batch_settlements
+            SET payment_id = $2, payment_payload = $3, channel_before = $4,
+                pending_id = $5, updated_at = NOW()
+          WHERE settlement_id = $1 AND status = 'prepared'
+            AND payment_id = $6 AND payment_payload = $7
+          RETURNING *`,
+        [
+          intent.settlementId,
+          intent.paymentId,
+          intent.payload,
+          intent.channelBefore,
+          intent.pendingId ?? null,
+          stored.paymentId,
+          stored.payload
+        ]
+      );
+      if (refreshed.rows[0]) return toSettlementIntent(refreshed.rows[0]);
+      const raced = await this.getSettlementById(intent.settlementId);
+      if (raced?.paymentId !== intent.paymentId || !isDeepStrictEqual(raced.payload, intent.payload) || !isDeepStrictEqual(raced.requirements, intent.requirements)) {
+        throw new Error("x402 settlement identity conflicts with a prior credit effect");
+      }
+      stored = raced;
+    }
+    if (stored.status === "prepared" && (!isDeepStrictEqual(stored.channelBefore, intent.channelBefore) || stored.pendingId !== intent.pendingId)) {
+      const refreshed = await settlements.query(
+        `UPDATE x402_batch_settlements
+            SET channel_before = $2, pending_id = $3, updated_at = NOW()
+          WHERE settlement_id = $1 AND status = 'prepared'
+          RETURNING *`,
+        [intent.settlementId, intent.channelBefore, intent.pendingId ?? null]
+      );
+      if (refreshed.rowCount !== 1) {
+        throw new Error(`x402 settlement ${intent.settlementId} is no longer prepared for retry`);
+      }
+      return toSettlementIntent(refreshed.rows[0]);
+    }
+    if (!isDeepStrictEqual(stored.channelBefore, intent.channelBefore)) {
+      throw new Error("x402 settlement identity conflicts with a prior credit effect");
+    }
+    return stored;
+  }
+  /**
+   * Mark that the next operation is the ambiguous external-call boundary.
+   *
+   * `channelAtSubmission` is the live channel the facilitator is about to size
+   * and sign the settlement against (internal-review) — bookmarked here, with the
+   * block height, because these two are the only description of that instant
+   * that survives the call.
+   */
+  async markSettlementSubmitting(settlementId, submissionBlock, channelAtSubmission) {
+    if (!/^\d+$/.test(submissionBlock)) {
+      throw new Error(`x402 settlement ${settlementId} has an invalid submission block`);
+    }
+    const writer = await this.settlementWriter();
+    const result = await writer.query(
+      `UPDATE x402_batch_settlements
+          SET status = 'submitting', submission_block = $2,
+              channel_at_submission = $3, updated_at = NOW()
+        WHERE settlement_id = $1 AND status = 'prepared'`,
+      [settlementId, submissionBlock, channelAtSubmission ?? null]
+    );
+    if (result.rowCount !== 1) {
+      throw new Error(`x402 settlement ${settlementId} is not prepared for submission`);
+    }
+  }
+  /** Return an explicitly failed facilitator submission to the safe retry phase. */
+  async markSettlementRetryable(settlementId) {
+    const writer = await this.settlementWriter();
+    const result = await writer.query(
+      `UPDATE x402_batch_settlements
+          SET status = 'prepared', submission_block = NULL,
+              channel_at_submission = NULL, updated_at = NOW()
+        WHERE settlement_id = $1 AND status = 'submitting'`,
+      [settlementId]
+    );
+    if (result.rowCount !== 1) {
+      throw new Error(`x402 settlement ${settlementId} is not awaiting a submission result`);
+    }
+  }
+  /**
+   * Record a successful facilitator response independently of the enclosing
+   * ledger transaction.
+   *
+   * The write-off columns are cleared, not carried: this CAS is what lifts a
+   * `written_off` row back to `settled` (which is what makes the write-off
+   * reversible), and a row that is no longer written off must not still be
+   * carrying the note and resolution timestamp of a decision that has been
+   * reversed. On the live path the columns are already `NULL` and this is a
+   * no-op.
+   */
+  async recordSettlementResponse(settlementId, response) {
+    const writer = await this.settlementWriter();
+    const result = await writer.query(
+      `UPDATE x402_batch_settlements
+          SET status = 'settled', settle_response = $2,
+              write_off_note = NULL, resolved_at = NULL, updated_at = NOW()
+        WHERE settlement_id = $1 AND status <> 'complete'`,
+      [settlementId, response]
+    );
+    if (result.rowCount !== 1) {
+      throw new X402SettlementRaceError(`x402 settlement ${settlementId} is not recoverable`);
+    }
+  }
+  /**
+   * Mark the external settlement and ledger effect complete in the active transaction.
+   *
+   * `resolvedAtMs` is set only by the operator repair (internal-review), so an audit
+   * read can tell a settlement that completed on its own from one a human had
+   * to finish.
+   */
+  async completeSettlement(settlementId, resolvedAtMs) {
+    const q = this.transaction.getStore() ?? this.pool;
+    const result = await q.query(
+      `UPDATE x402_batch_settlements
+          SET status = 'complete',
+              resolved_at = COALESCE($2::bigint, resolved_at),
+              updated_at = NOW()
+        WHERE settlement_id = $1 AND status = 'settled'`,
+      [settlementId, resolvedAtMs ?? null]
+    );
+    if (result.rowCount !== 1) {
+      throw new X402SettlementRaceError(
+        `x402 settlement ${settlementId} has no recorded facilitator response`
+      );
+    }
+  }
+  /** Load one channel snapshot. */
+  async get(channelId) {
+    const q = this.transaction.getStore() ?? this.pool;
+    const { rows } = await q.query(
+      `SELECT * FROM x402_batch_channels WHERE channel_id = $1`,
+      [normalizeChannelId(channelId)]
+    );
+    return rows[0] ? toChannel(rows[0]) : void 0;
+  }
+  /** List all channel snapshots in stable channel-id order. */
+  async list() {
+    const q = this.transaction.getStore() ?? this.pool;
+    const { rows } = await q.query(
+      `SELECT * FROM x402_batch_channels ORDER BY channel_id`
+    );
+    return rows.map(toChannel);
+  }
+  /** Atomic backend-level read/modify/write for one channel. */
+  async updateChannel(channelId, update) {
+    const active = this.transaction.getStore();
+    if (active) return this.updateInTransaction(active, channelId, update, true);
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const result = await this.updateInTransaction(client, channelId, update, false);
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Run channel state and its ledger effect under the channel lock.
+   *
+   * Upstream's voucher-only settle updates `chargedCumulativeAmount` through
+   * `updateChannel`. Keeping that update and `commitMarkedFunding` in this one
+   * transaction means a ledger refusal rolls the voucher state back. External
+   * deposit/refund responses are recorded separately before this transaction
+   * commits, leaving a durable reconciliation row if COMMIT fails.
+   */
+  /**
+   * Sanction one cooperative-refund base for the updates inside `operation`.
+   *
+   * The store cannot derive the base — it comes from the credit ledger — so
+   * this is how the settlement layer says "this exact decrease is the one the
+   * payer's verified refund voucher authorises". Outside this scope a decrease
+   * of `chargedCumulativeAmount` is refused flat, which is what keeps the
+   * arbitrary-decrease guard meaningful (internal-review).
+   */
+  withSanctionedRefundBase(base, operation) {
+    return this.refundBase.run(base, operation);
+  }
+  async withChannelTransaction(channelId, operation) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await lockChannel(client, channelId);
+      const result = await this.transaction.run(client, () => operation(client));
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Run one fleet-wide settlement operation, optionally waiting for the current owner.
+   *
+   * The lock is session-scoped, so its client stays checked out for the whole
+   * operation — and `operation()` (upstream's claim/settle) re-enters the pool
+   * through {@link updateChannel}. Two bounds keep that from wedging the pool
+   * (internal-review): local callers are serialized in-process, so this holds at most
+   * one client per process no matter how many requests arrive, and a waiting
+   * acquire carries a `lock_timeout` so a wedged fleet-mate can't pin that
+   * client — and the caller's request — indefinitely. A timeout reports the
+   * lock as not acquired, which is what every caller already handles.
+   *
+   * The queue depth is reserved synchronously, before the promise chain can
+   * yield. That makes the non-waiting form a true local try-lock even while the
+   * first caller is still acquiring its connection: an overlapping request
+   * returns `false` instead of queuing behind the facilitator operation.
+   */
+  async withFleetSettlementLock(operation, wait = false) {
+    if (!wait && this.fleetLockQueueDepth > 0) return false;
+    this.fleetLockQueueDepth += 1;
+    const turn = this.fleetLock.then(() => this.runUnderFleetLock(operation, wait));
+    this.fleetLock = turn.catch(() => void 0);
+    try {
+      return await turn;
+    } finally {
+      this.fleetLockQueueDepth -= 1;
+    }
+  }
+  /**
+   * Hold the fleet-wide self-relay submission lock for one chain submission (internal-review).
+   *
+   * The session lock keeps one per-DVM gas EOA to one in-flight submission
+   * across the whole fleet — two machines submitting at once collide on the
+   * nonce. It is reached from `resource.settlePayment` inside
+   * {@link withChannelTransaction} and from upstream's claim/settle inside
+   * {@link withFleetSettlementLock}, so on both paths a host-pool client is
+   * already checked out: it therefore acquires from the terminal settlement
+   * pool, which is the rule in this class's doc, and never from the host pool
+   * the caller is holding.
+   *
+   * The wait is bounded by `lock_timeout` and a timeout **refuses** rather than
+   * proceeding unlocked, which is where this differs from
+   * {@link withFleetSettlementLock}: a fleet lock nobody got means the claim is
+   * someone else's turn, while a submission lock nobody got means the caller
+   * must not submit at all. The refusal is typed and retryable, and names the
+   * holder when Postgres will tell us who it is.
+   *
+   * The relay's own in-process tail serialises callers before they reach here,
+   * so one process pins at most one settlement-pool client no matter how many
+   * deposits arrive.
+   */
+  async withRelaySubmissionLock(key, operation) {
+    const pool = await this.settlementPoolRef();
+    const client = await pool.connect();
+    let locked = false;
+    let destroyClient = false;
+    try {
+      await client.query(`SET lock_timeout = ${String(this.relayLockTimeoutMs)}`);
+      try {
+        await client.query(RELAY_LOCK_SQL, [key]);
+        locked = true;
+      } catch (error) {
+        if (!isLockTimeout(error)) throw error;
+        throw new X402RelaySubmissionLockError(
+          key,
+          this.relayLockTimeoutMs,
+          await relayLockHolder(client, key)
+        );
+      }
+      return await operation();
+    } finally {
+      if (locked) {
+        await client.query(RELAY_UNLOCK_SQL, [key]).catch(() => {
+          destroyClient = true;
+        });
+      }
+      await client.query(`RESET lock_timeout`).catch(() => {
+        destroyClient = true;
+      });
+      client.release(destroyClient);
+    }
+  }
+  /** Release the dedicated settlement pool; the host-owned pool is left alone. */
+  async close() {
+    const settlement = this.settlementPool;
+    this.settlementPool = void 0;
+    if (settlement) await (await settlement).end();
+  }
+  async settlementWriter() {
+    return this.settlementPoolRef();
+  }
+  async settlementPoolRef() {
+    this.settlementPool ??= createSettlementPool(this.pool);
+    return this.settlementPool;
+  }
+  async runUnderFleetLock(operation, wait) {
+    const client = await this.pool.connect();
+    let locked = false;
+    let timeoutSet = false;
+    try {
+      if (wait) {
+        await client.query(`SET lock_timeout = ${FLEET_LOCK_TIMEOUT_MS}`);
+        timeoutSet = true;
+        try {
+          await client.query(
+            `SELECT pg_advisory_lock(hashtextextended('x402-batch-settlement', 1762))`
+          );
+          locked = true;
+        } catch (error) {
+          if (!isLockTimeout(error)) throw error;
+        }
+      } else {
+        const { rows } = await client.query(
+          `SELECT pg_try_advisory_lock(hashtextextended('x402-batch-settlement', 1762)) AS locked`
+        );
+        locked = rows[0]?.locked ?? false;
+      }
+      if (!locked) return false;
+      await operation();
+      return true;
+    } finally {
+      let destroyClient = false;
+      if (locked) {
+        await client.query(`SELECT pg_advisory_unlock(hashtextextended('x402-batch-settlement', 1762))`).catch(() => {
+          destroyClient = true;
+        });
+      }
+      if (timeoutSet) {
+        await client.query(`RESET lock_timeout`).catch(() => {
+          destroyClient = true;
+        });
+      }
+      client.release(destroyClient);
+    }
+  }
+  async updateInTransaction(client, channelId, update, alreadyLocked) {
+    const normalized = normalizeChannelId(channelId);
+    if (!alreadyLocked) await lockChannel(client, normalized);
+    const { rows } = await client.query(
+      `SELECT * FROM x402_batch_channels WHERE channel_id = $1 FOR UPDATE`,
+      [normalized]
+    );
+    const current = rows[0] ? toChannel(rows[0]) : void 0;
+    const next = update(current);
+    if (next === void 0) {
+      if (!current) return { channel: void 0, status: "unchanged" };
+      await client.query(`DELETE FROM x402_batch_channels WHERE channel_id = $1`, [normalized]);
+      return { channel: void 0, status: "deleted" };
+    }
+    assertChannelTransition(current, next, normalized, this.refundBase.getStore());
+    if (this.terminalizeUnbackedCredit && next.onchainSyncedAt !== void 0 && next.onchainSyncedAt !== current?.onchainSyncedAt && next.withdrawRequestedAt === 0 && BigInt(next.balance) === BigInt(next.totalClaimed)) {
+      await this.terminalizeUnbackedCredit(
+        {
+          channelId: normalized,
+          channelBalanceNative: BigInt(next.balance),
+          totalClaimedNative: BigInt(next.totalClaimed),
+          observedAt: next.onchainSyncedAt
+        },
+        client
+      );
+    }
+    if (current && sameChannel(current, next)) {
+      return { channel: current, status: "unchanged" };
+    }
+    await writeChannel(client, normalized, next);
+    return { channel: cloneChannel(next), status: "updated" };
+  }
+};
+async function createSettlementPool(pool) {
+  const pg = await import("pg");
+  const options = pool.options ?? {};
+  const settlement = new pg.default.Pool({
+    ...options,
+    // pg defines `password` non-enumerably on `pool.options`, so a spread drops
+    // it — read it through explicitly or every connection fails to authenticate.
+    ...options.password !== void 0 ? { password: options.password } : {},
+    max: SETTLEMENT_POOL_MAX,
+    connectionTimeoutMillis: SETTLEMENT_CONNECT_TIMEOUT_MS
+  });
+  applyRetryToPool(settlement, "x402-settlement");
+  return settlement;
+}
+var RELAY_LOCK_SQL = `SELECT pg_advisory_lock(hashtextextended($1, 1759))`;
+var RELAY_UNLOCK_SQL = `SELECT pg_advisory_unlock(hashtextextended($1, 1759))`;
+async function relayLockHolder(client, key) {
+  try {
+    const { rows } = await client.query(
+      `SELECT a.pid,
+              a.application_name,
+              a.client_addr::text AS client_addr,
+              a.state,
+              EXTRACT(EPOCH FROM (NOW() - a.query_start))::float8 AS held_seconds
+         FROM pg_locks l
+         JOIN pg_stat_activity a ON a.pid = l.pid
+        WHERE l.locktype = 'advisory'
+          AND l.granted
+          AND l.classid = ((hashtextextended($1, 1759) >> 32) & 4294967295)::oid
+          AND l.objid = (hashtextextended($1, 1759) & 4294967295)::oid
+        LIMIT 1`,
+      [key]
+    );
+    if (rows.length === 0) return void 0;
+    const row = rows[0];
+    return {
+      pid: row.pid,
+      ...row.application_name ? { applicationName: row.application_name } : {},
+      ...row.client_addr ? { clientAddr: row.client_addr } : {},
+      ...row.state ? { state: row.state } : {},
+      ...row.held_seconds !== null ? { heldSeconds: Math.round(row.held_seconds) } : {}
+    };
+  } catch {
+    return void 0;
+  }
+}
+function describeHolder(holder) {
+  const parts = [`pid ${String(holder.pid)}`];
+  if (holder.applicationName) parts.push(holder.applicationName);
+  if (holder.clientAddr) parts.push(holder.clientAddr);
+  if (holder.state) parts.push(holder.state);
+  if (holder.heldSeconds !== void 0) parts.push(`${String(holder.heldSeconds)}s in`);
+  return parts.join(", ");
+}
+function isLockTimeout(error) {
+  return typeof error === "object" && error !== null && error.code === LOCK_NOT_AVAILABLE;
+}
+function toSettlementIntent(row) {
+  if (!row.channel_before) {
+    throw new Error(`x402 settlement ${row.settlement_id} has no reconciliation snapshot`);
+  }
+  return {
+    settlementId: row.settlement_id,
+    channelId: row.channel_id,
+    operation: row.operation,
+    effectId: row.effect_id,
+    paymentId: row.payment_id,
+    payload: row.payment_payload,
+    requirements: row.payment_requirements,
+    channelBefore: row.channel_before,
+    ...row.channel_at_submission ? { channelAtSubmission: row.channel_at_submission } : {},
+    ...row.submission_block !== null ? { submissionBlock: row.submission_block } : {},
+    ...row.pending_id ? { pendingId: row.pending_id } : {},
+    status: row.status,
+    ...row.settle_response ? { response: row.settle_response } : {},
+    createdAt: row.created_at.getTime(),
+    updatedAt: row.updated_at.getTime(),
+    ...row.write_off_note !== null ? { writeOffNote: row.write_off_note } : {},
+    ...row.resolved_at !== null ? { resolvedAt: Number(row.resolved_at) } : {}
+  };
+}
+function canRefreshPreparedDepositAuthorization(stored, intent, nowMs) {
+  if (stored.status !== "prepared" || stored.operation !== "fund" || !isDeepStrictEqual(stored.requirements, intent.requirements))
+    return false;
+  const before = refreshableDepositAuthorization(stored.payload);
+  const after = refreshableDepositAuthorization(intent.payload);
+  if (!before || !after || !isDeepStrictEqual(before.shape, after.shape)) return false;
+  const nowSeconds = BigInt(Math.floor(nowMs / 1e3));
+  return before.validBefore < nowSeconds && after.validBefore > nowSeconds;
+}
+function refreshableDepositAuthorization(payload) {
+  const shape = structuredClone(payload);
+  const body = objectRecord(shape.payload);
+  const deposit = objectRecord(body?.deposit);
+  const wrapper = objectRecord(deposit?.authorization);
+  const authorization = objectRecord(wrapper?.erc3009Authorization);
+  const validBefore = authorization?.validBefore;
+  const signature = authorization?.signature;
+  if (!authorization || body?.type !== "deposit" || typeof validBefore !== "string" || !/^\d+$/.test(validBefore) || typeof signature !== "string" || signature.length === 0)
+    return void 0;
+  delete authorization.validBefore;
+  delete authorization.salt;
+  delete authorization.signature;
+  return { validBefore: BigInt(validBefore), shape };
+}
+function objectRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+async function lockChannel(client, channelId) {
+  await client.query(`SELECT pg_advisory_xact_lock(hashtextextended($1, 1762))`, [
+    normalizeChannelId(channelId)
+  ]);
+}
+async function writeChannel(client, channelId, channel) {
+  await client.query(
+    `INSERT INTO x402_batch_channels (
+       channel_id, channel_config, charged_cumulative_amount, signed_max_claimable,
+       signature, balance, total_claimed, withdraw_requested_at, refund_nonce,
+       onchain_synced_at, last_request_timestamp, pending_request
+     ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+     ON CONFLICT (channel_id) DO UPDATE SET
+       channel_config = EXCLUDED.channel_config,
+       charged_cumulative_amount = EXCLUDED.charged_cumulative_amount,
+       signed_max_claimable = EXCLUDED.signed_max_claimable,
+       signature = EXCLUDED.signature,
+       balance = EXCLUDED.balance,
+       total_claimed = EXCLUDED.total_claimed,
+       withdraw_requested_at = EXCLUDED.withdraw_requested_at,
+       refund_nonce = EXCLUDED.refund_nonce,
+       onchain_synced_at = EXCLUDED.onchain_synced_at,
+       last_request_timestamp = EXCLUDED.last_request_timestamp,
+       pending_request = EXCLUDED.pending_request`,
+    [
+      channelId,
+      channel.channelConfig,
+      channel.chargedCumulativeAmount,
+      channel.signedMaxClaimable,
+      channel.signature,
+      channel.balance,
+      channel.totalClaimed,
+      channel.withdrawRequestedAt,
+      channel.refundNonce,
+      channel.onchainSyncedAt ?? null,
+      channel.lastRequestTimestamp,
+      channel.pendingRequest ?? null
+    ]
+  );
+}
+function toChannel(row) {
+  return {
+    channelId: row.channel_id,
+    channelConfig: row.channel_config,
+    chargedCumulativeAmount: row.charged_cumulative_amount,
+    signedMaxClaimable: row.signed_max_claimable,
+    signature: row.signature,
+    balance: row.balance,
+    totalClaimed: row.total_claimed,
+    withdrawRequestedAt: safeInteger(row.withdraw_requested_at, "withdraw_requested_at"),
+    refundNonce: safeInteger(row.refund_nonce, "refund_nonce"),
+    ...row.onchain_synced_at !== null ? { onchainSyncedAt: safeInteger(row.onchain_synced_at, "onchain_synced_at") } : {},
+    lastRequestTimestamp: safeInteger(row.last_request_timestamp, "last_request_timestamp"),
+    ...row.pending_request ? { pendingRequest: row.pending_request } : {}
+  };
+}
+function assertChannelTransition(current, next, expectedId, sanctionedRefundBase) {
+  if (normalizeChannelId(next.channelId) !== expectedId) {
+    throw new Error(`x402 channel update changed channelId ${expectedId}`);
+  }
+  if (!current) return;
+  if (!isDeepStrictEqual(current.channelConfig, next.channelConfig)) {
+    throw new Error(`x402 channel ${expectedId} attempted to mutate immutable channelConfig`);
+  }
+  const revokesUnclaimedAuthority = sanctionedRefundBase !== void 0 && BigInt(next.chargedCumulativeAmount) < BigInt(current.chargedCumulativeAmount) && BigInt(next.chargedCumulativeAmount) === BigInt(sanctionedRefundBase) && BigInt(next.chargedCumulativeAmount) >= BigInt(next.totalClaimed) && next.signedMaxClaimable === current.signedMaxClaimable && next.signature === current.signature && current.pendingRequest === void 0 && next.pendingRequest === void 0;
+  if (BigInt(next.chargedCumulativeAmount) < BigInt(current.chargedCumulativeAmount) && !revokesUnclaimedAuthority) {
+    throw new Error(`x402 channel ${expectedId} attempted to decrease chargedCumulativeAmount`);
+  }
+  if (BigInt(next.totalClaimed) < BigInt(current.totalClaimed)) {
+    throw new Error(`x402 channel ${expectedId} attempted to decrease totalClaimed`);
+  }
+  const reservesRevokedVoucher = BigInt(next.signedMaxClaimable) < BigInt(current.signedMaxClaimable) && next.chargedCumulativeAmount === current.chargedCumulativeAmount && next.signedMaxClaimable === next.chargedCumulativeAmount && current.pendingRequest === void 0 && next.pendingRequest !== void 0;
+  if (BigInt(next.signedMaxClaimable) < BigInt(current.signedMaxClaimable) && !reservesRevokedVoucher && (!current.pendingRequest || next.pendingRequest || BigInt(next.signedMaxClaimable) < BigInt(next.chargedCumulativeAmount))) {
+    throw new Error(`x402 channel ${expectedId} attempted to decrease signedMaxClaimable`);
+  }
+  if (next.refundNonce < current.refundNonce) {
+    throw new Error(`x402 channel ${expectedId} attempted to decrease refundNonce`);
+  }
+}
+function sameChannel(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function cloneChannel(channel) {
+  return structuredClone(channel);
+}
+function normalizeChannelId(channelId) {
+  const normalized = channelId.toLowerCase();
+  if (!/^0x[0-9a-f]{64}$/.test(normalized)) {
+    throw new Error(`x402 channelId must be a canonical bytes32 value; got ${channelId}`);
+  }
+  return normalized;
+}
+function safeInteger(value, field) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new Error(`x402 channel ${field} exceeds JavaScript's safe integer range`);
+  }
+  return parsed;
+}
+
+// src/sdk/server/credit-ledger.ts
+var CreditLedger = class {
+  constructor(pool, tempoSessionStore) {
+    this.pool = pool;
+    this.tempoSessionStore = tempoSessionStore;
+  }
+  pool;
+  tempoSessionStore;
+  /**
+   * Postgres-backed: balances survive a restart and are shared across the
+   * fleet, so this DVM may advertise credit (internal-review).
+   */
+  durable = true;
+  x402Settlements;
+  /**
+   * Bind the durable x402 settlement state this ledger gates spending on
+   * (internal-review).
+   *
+   * Late, because the settlement store is built with the batch-settlement
+   * server, which is built *after* the ledger it reads earned draws from. An
+   * unbound ledger simply does not gate — correct for a DVM with no x402
+   * channel storage, where no settlement row can exist to wedge.
+   */
+  useX402SettlementGate(gate) {
+    this.x402Settlements = gate;
+  }
+  /** Create the `credits` / `credit_draws` tables if absent. Call once at SDK boot. */
+  async init() {
+    await withSdkInitLock(this.pool, () => this.createTables());
+  }
+  /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
+  async createTables() {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credits (
+        credit_id        TEXT PRIMARY KEY,
+        caller_pubkey    TEXT NOT NULL,
+        currency         TEXT NOT NULL,
+        balance_micro    BIGINT NOT NULL,
+        expiry_ms        BIGINT NOT NULL,
+        status           TEXT NOT NULL DEFAULT 'active',
+        last_ledger_seq  BIGINT NOT NULL DEFAULT 0,
+        created_at       BIGINT NOT NULL,
+        rail             TEXT,
+        native_asset     TEXT,
+        mint             TEXT,
+        funding_ref      TEXT,
+        tempo_channel_id TEXT,
+        msats_remaining  BIGINT NOT NULL DEFAULT 0,
+        native_remaining BIGINT,
+        x402_channel_id  TEXT
+      );
+    `);
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS tempo_credit_losses (
+        credit_id                 TEXT PRIMARY KEY,
+        channel_id                TEXT NOT NULL,
+        caller_pubkey             TEXT NOT NULL,
+        currency                  TEXT NOT NULL,
+        former_balance_micro      BIGINT NOT NULL,
+        settled_on_chain_native   BIGINT NOT NULL,
+        highest_voucher_native    BIGINT NOT NULL,
+        consumed_service_micro    BIGINT NOT NULL,
+        consumed_native           BIGINT NOT NULL,
+        observed_at               BIGINT NOT NULL
+      );
+    `);
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_tempo_credit_losses_observed
+         ON tempo_credit_losses(observed_at, credit_id);`
+    );
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS x402_credit_losses (
+        credit_id                 TEXT PRIMARY KEY,
+        channel_id                TEXT NOT NULL,
+        caller_pubkey             TEXT NOT NULL,
+        currency                  TEXT NOT NULL,
+        former_balance_micro      BIGINT NOT NULL,
+        channel_balance_native    BIGINT NOT NULL,
+        total_claimed_native      BIGINT NOT NULL,
+        consumed_service_micro    BIGINT NOT NULL,
+        observed_at               BIGINT NOT NULL
+      );
+    `);
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_x402_credit_losses_observed
+         ON x402_credit_losses(observed_at, credit_id);`
+    );
+    for (const column of [
+      "rail TEXT",
+      "native_asset TEXT",
+      "mint TEXT",
+      "funding_ref TEXT",
+      "tempo_channel_id TEXT",
+      "msats_remaining BIGINT NOT NULL DEFAULT 0",
+      "native_remaining BIGINT",
+      "x402_channel_id TEXT"
+    ]) {
+      await this.pool.query(`ALTER TABLE credits ADD COLUMN IF NOT EXISTS ${column}`);
+    }
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credits_caller ON credits(caller_pubkey);`
+    );
+    await this.pool.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS credits_x402_channel_uidx
+         ON credits(x402_channel_id) WHERE x402_channel_id IS NOT NULL;`
+    );
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_draws (
+        credit_id           TEXT NOT NULL,
+        draw_id             TEXT NOT NULL,
+        amount_micro        BIGINT NOT NULL,
+        job_id              TEXT,
+        ledger_seq          BIGINT NOT NULL,
+        status              TEXT NOT NULL,
+        balance_after_micro BIGINT NOT NULL,
+        created_at          BIGINT NOT NULL,
+        resolved_at         BIGINT,
+        draw_msats          BIGINT NOT NULL DEFAULT 0,
+        draw_native         BIGINT,
+        grown_micro         BIGINT NOT NULL DEFAULT 0,
+        PRIMARY KEY (credit_id, draw_id)
+      );
+    `);
+    for (const column of [
+      "draw_msats BIGINT NOT NULL DEFAULT 0",
+      "draw_native BIGINT",
+      "grown_micro BIGINT NOT NULL DEFAULT 0",
+      "allocated_msats BIGINT"
+    ]) {
+      await this.pool.query(`ALTER TABLE credit_draws ADD COLUMN IF NOT EXISTS ${column}`);
+    }
+    await this.pool.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS credit_draws_seq_uidx
+         ON credit_draws(credit_id, ledger_seq);`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_draws_pending
+         ON credit_draws(credit_id) WHERE status = 'pending';`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_draws_pending_age
+         ON credit_draws(created_at, credit_id, ledger_seq) WHERE status = 'pending';`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_draws_job_id
+         ON credit_draws(job_id) WHERE job_id IS NOT NULL;`
+    );
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_fundings (
+        credit_id    TEXT NOT NULL,
+        fund_id      TEXT NOT NULL,
+        amount_micro BIGINT NOT NULL,
+        rail         TEXT,
+        created_at   BIGINT NOT NULL,
+        PRIMARY KEY (credit_id, fund_id)
+      );
+    `);
+    await this.pool.query(`ALTER TABLE credit_fundings ADD COLUMN IF NOT EXISTS rail TEXT`);
+    for (const column of [
+      "caller_pubkey TEXT",
+      "balance_after_micro BIGINT",
+      "ledger_seq BIGINT",
+      "receipt JSONB"
+    ]) {
+      await this.pool.query(`ALTER TABLE credit_fundings ADD COLUMN IF NOT EXISTS ${column}`);
+    }
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_funding_lots (
+        lot_id          TEXT PRIMARY KEY,
+        credit_id       TEXT NOT NULL,
+        rail            TEXT NOT NULL,
+        sats_funded     BIGINT NOT NULL,
+        credited_micro  BIGINT NOT NULL,
+        remaining_micro BIGINT NOT NULL,
+        funding_ref     TEXT,
+        created_at      BIGINT NOT NULL
+      );
+    `);
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_funding_lots_open
+         ON credit_funding_lots(credit_id, created_at, lot_id) WHERE remaining_micro > 0;`
+    );
+    await this.backfillFundingLots();
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_drains (
+        credit_id           TEXT NOT NULL,
+        drain_id            TEXT NOT NULL,
+        method              TEXT NOT NULL,
+        payout              JSONB NOT NULL,
+        amount_micro        BIGINT NOT NULL,
+        balance_after_micro BIGINT NOT NULL,
+        drained_msats       BIGINT NOT NULL DEFAULT 0,
+        drained_native      BIGINT,
+        owed_sats           BIGINT,
+        lot_debits          JSONB,
+        ledger_seq          BIGINT NOT NULL,
+        status              TEXT NOT NULL,
+        token               TEXT,
+        sent_ref            JSONB,
+        receipts            JSONB NOT NULL DEFAULT '[]'::jsonb,
+        created_at          BIGINT NOT NULL,
+        parked_at           BIGINT,
+        picked_up_at        BIGINT,
+        sent_at             BIGINT,
+        released_at         BIGINT,
+        PRIMARY KEY (credit_id, drain_id)
+      );
+    `);
+    await this.pool.query(
+      `ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS balance_after_micro BIGINT NOT NULL DEFAULT 0`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS drained_msats BIGINT NOT NULL DEFAULT 0`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS drained_native BIGINT`
+    );
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS owed_sats BIGINT`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS lot_debits JSONB`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS released_at BIGINT`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS fulfilment JSONB`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS write_off_note TEXT`);
+    await this.pool.query(
+      `ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS written_off_at BIGINT`
+    );
+    await this.pool.query(
+      `UPDATE credit_drains d SET drained_native = d.amount_micro
+       FROM credits c
+       WHERE d.credit_id = c.credit_id
+         AND c.tempo_channel_id IS NOT NULL
+         AND d.drained_native IS NULL`
+    );
+    await this.pool.query(`UPDATE credits SET rail = 'tempo' WHERE rail = 'mpp'`);
+    await this.pool.query(`UPDATE credit_fundings SET rail = 'tempo' WHERE rail = 'mpp'`);
+    await this.pool.query(`UPDATE credit_drains SET method = 'tempo' WHERE method = 'mpp'`);
+    await this.pool.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS credit_drains_seq_uidx
+         ON credit_drains(credit_id, ledger_seq);`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_drains_pending
+         ON credit_drains(status) WHERE status = 'pending';`
+    );
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_invoices (
+        credit_id     TEXT NOT NULL,
+        fund_id       TEXT NOT NULL,
+        caller_pubkey TEXT NOT NULL,
+        currency      TEXT NOT NULL,
+        amount_micro  BIGINT NOT NULL,
+        amount_msats  BIGINT NOT NULL,
+        payment_hash  TEXT NOT NULL,
+        bolt11        TEXT NOT NULL,
+        status        TEXT NOT NULL,
+        blocked_reason TEXT,
+        expires_at    BIGINT NOT NULL,
+        created_at    BIGINT NOT NULL,
+        settled_at    BIGINT,
+        PRIMARY KEY (credit_id, fund_id)
+      );
+    `);
+    await this.pool.query(
+      `ALTER TABLE credit_invoices ADD COLUMN IF NOT EXISTS blocked_reason TEXT`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_invoices ADD COLUMN IF NOT EXISTS reconciled_credit_id TEXT`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_invoices ADD COLUMN IF NOT EXISTS reconciled_fund_id TEXT`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_invoices ADD COLUMN IF NOT EXISTS resolved_at BIGINT`
+    );
+    await this.pool.query(
+      `ALTER TABLE credit_invoices ADD COLUMN IF NOT EXISTS write_off_note TEXT`
+    );
+    await this.pool.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS credit_invoices_hash_uidx
+         ON credit_invoices(payment_hash);`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_invoices_pending
+         ON credit_invoices(caller_pubkey, created_at) WHERE status = 'pending';`
+    );
+    await this.pool.query(
+      `CREATE INDEX IF NOT EXISTS idx_credit_invoices_blocked
+         ON credit_invoices(created_at, credit_id, fund_id) WHERE status = 'blocked';`
+    );
+  }
+  /**
+   * Give every open non-channel Bitcoin credit a funding lot (internal-review).
+   *
+   * Runs inside the boot DDL, is guarded per credit by `NOT EXISTS`, and is
+   * therefore both the one-time migration and a standing self-heal for a
+   * credit that somehow reaches a positive balance with no lot behind it.
+   *
+   * The lot is derived from `credits.msats_remaining`, not replayed out of
+   * `credit_fundings`. That is not a shortcut: `credit_fundings` records only
+   * `{amount_micro, rail}` — no instrument amount at all — and is not written
+   * on every funding path, whereas `msats_remaining` **is** the credit's
+   * current unspent rail value, maintained pro rata on every draw since
+   * internal-review. One synthetic lot pairing it with `balance_micro` therefore
+   * reproduces today's in-kind position exactly, and FIFO over a single lot is
+   * trivially correct. Historic per-funding rates are unrecoverable and would
+   * change nothing: only the remaining position is owed.
+   *
+   * The semantics change is deliberately retroactive (internal-review) — every
+   * current holder is first-party, so there is one regime and no legacy
+   * branch.
+   */
+  async backfillFundingLots() {
+    const { rowCount } = await this.pool.query(
+      `INSERT INTO credit_funding_lots
+         (lot_id, credit_id, rail, sats_funded, credited_micro, remaining_micro, funding_ref, created_at)
+       SELECT 'lot:backfill:' || c.credit_id, c.credit_id, c.rail,
+              c.msats_remaining / 1000, c.balance_micro, c.balance_micro, c.funding_ref, c.created_at
+         FROM credits c
+        WHERE ${BITCOIN_CREDIT_PREDICATE}
+          AND NOT EXISTS (SELECT 1 FROM credit_funding_lots l WHERE l.credit_id = c.credit_id)
+       ON CONFLICT (lot_id) DO NOTHING`
+    );
+    const { rows } = await this.pool.query(
+      `SELECT COUNT(*) FILTER (WHERE cov.covered_micro < c.balance_micro) AS uncovered,
+              COUNT(*) FILTER (WHERE cov.covered_micro >= c.balance_micro AND cov.basisless_micro > 0)
+                AS unbacked
+         FROM credits c
+         CROSS JOIN LATERAL (${LOT_COVERAGE_LATERAL}) cov
+        WHERE ${BITCOIN_CREDIT_PREDICATE}`
+    );
+    const uncovered = Number(rows[0]?.uncovered ?? 0);
+    const unbacked = Number(rows[0]?.unbacked ?? 0);
+    if (rowCount === 0 && uncovered === 0 && unbacked === 0) return;
+    console.warn(
+      JSON.stringify({
+        level: uncovered > 0 ? "warn" : "info",
+        event: "credit_funding_lot_backfill",
+        backfilled: rowCount ?? 0,
+        uncovered_credits: uncovered,
+        unbacked_credits: unbacked,
+        message: uncovered > 0 ? "Some open Bitcoin credits hold more balance than their funding lots cover. Those reclaims are priced off a live rate rather than in kind until the gap is repaired." : "Funding lots are in place for every open Bitcoin credit."
+      })
+    );
+  }
+  /**
+   * Create a credit, or top up an existing one (same `creditId`). Top-ups add
+   * to the balance and overwrite `expiry_ms` with the provided value — funding
+   * an expired credit revives it (spec §5 carry-forward: the credit is a
+   * rolling buffer, not per-job escrow). The existing row's `caller_pubkey`
+   * and `currency` must match or the fund is refused with a typed error —
+   * without that check a top-up against someone else's `credit_id` would
+   * silently merge two callers' money.
+   *
+   * Pass `tx` (a client inside a caller-owned `BEGIN`) to commit the rail
+   * receive and the ledger credit atomically (spec condition 3 — the internal-review
+   * verifier does this). The ledger issues **no** transaction control on `tx`;
+   * the upsert is a single statement, so without `tx` it is equally atomic on
+   * the pool.
+   *
+   * `basis` records the rail value behind the fiat (internal-review) so each draw can
+   * be allocated its share of the rail-native amount actually received. A
+   * top-up on a different rail than the credit's is refused with
+   * `rail_mismatch`: sats and USDC microunits aren't summable, so a blended
+   * credit would have no coherent native basis to allocate from.
+   *
+   * It is **required** (internal-review), in the type and again at runtime via
+   * {@link assertFundingBasis}. A basis-less fund wrote `rail = NULL`, and a
+   * draw against such a credit settles — a real debit — while
+   * `railAsFundingMethod` correctly declines to guess a rail, so `bookRevenue`
+   * books nothing and outstanding liability (`deposits − draw revenue`) stays
+   * overstated by the drawn amount forever. `credits.rail` stays nullable
+   * because rows written before this change still exist in live databases:
+   * **write is closed, read is not.** A legacy row adopts a rail from its first
+   * typed top-up via the `COALESCE` below.
+   *
+   * The rail-native **instrument** is pinned at first funding too, and both
+   * channel guards are symmetric for the same reason (internal-review). A reusable
+   * channel — Tempo session or x402 batch-settlement — may only ever top up
+   * the credit it opened, and a credit opened by a one-shot (a Tempo charge, an
+   * x402 exact authorization) may never adopt one. The x402 half used to admit
+   * `credits.x402_channel_id IS NULL`, so a channel deposit bound itself to a
+   * credit already holding exact-funded value: `earnedNativeForX402Channel`
+   * then read that credit's whole settled-draw history as the channel's
+   * earnings, and the first claim tick swept a deposit nobody had consumed,
+   * while the unspent balance lost every exit (the drain's refund base goes
+   * below `totalClaimed`, and a channel-bound credit refuses every non-x402
+   * drain). `credits_x402_channel_uidx` does not cover this: it guards
+   * one-credit-per-channel, not one-source-per-credit.
+   *
+   * An x402 channel deposit is additionally refused `settlement_pending` while
+   * that channel carries an unresolved refund (internal-review) — see the gate read
+   * below. This method is the authority on that rule, as it is on the binding
+   * rules above; every door preflights it where a refusal is still free.
+   */
+  async fund(args) {
+    assertAmount(args.amountMicro, { min: 1 });
+    if (!Number.isSafeInteger(args.expiryMs) || args.expiryMs <= 0) {
+      throw new CreditLedgerError(
+        "invalid_expiry",
+        `expiryMs must be a positive safe integer (got ${args.expiryMs})`
+      );
+    }
+    const b = assertFundingBasis(args.basis);
+    const q = args.tx ?? this.pool;
+    const nowMs = args.nowMs ?? Date.now();
+    const creditId = args.creditId ?? randomUUID();
+    const wedged = await this.blockingX402Refund(
+      b.x402Channel?.channelId,
+      X402_SPEND_BLOCKING_SETTLEMENT_STATUSES
+    );
+    if (wedged) throw x402SettlementPending(creditId, wedged);
+    let rows;
+    try {
+      ({ rows } = await q.query(
+        `INSERT INTO credits (credit_id, caller_pubkey, currency, balance_micro, expiry_ms, status, created_at,
+                            rail, native_asset, mint, funding_ref, msats_remaining, native_remaining,
+                            tempo_channel_id, x402_channel_id)
+       VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, $9, $10, $11, $12, $13, $14)
+       ON CONFLICT (credit_id) DO UPDATE
+         SET balance_micro    = credits.balance_micro + EXCLUDED.balance_micro,
+             expiry_ms        = EXCLUDED.expiry_ms,
+             rail             = COALESCE(credits.rail, EXCLUDED.rail),
+             native_asset     = COALESCE(EXCLUDED.native_asset, credits.native_asset),
+             mint             = COALESCE(EXCLUDED.mint, credits.mint),
+             funding_ref      = COALESCE(EXCLUDED.funding_ref, credits.funding_ref),
+             tempo_channel_id = COALESCE(credits.tempo_channel_id, EXCLUDED.tempo_channel_id),
+             msats_remaining  = credits.msats_remaining + EXCLUDED.msats_remaining,
+             native_remaining = CASE
+               WHEN EXCLUDED.native_remaining IS NULL THEN credits.native_remaining
+               ELSE COALESCE(credits.native_remaining, 0) + EXCLUDED.native_remaining
+             END,
+             x402_channel_id = COALESCE(credits.x402_channel_id, EXCLUDED.x402_channel_id)
+         WHERE credits.caller_pubkey = EXCLUDED.caller_pubkey
+           AND credits.status = 'active'
+           AND credits.currency = EXCLUDED.currency
+           AND (credits.rail IS NULL OR credits.rail = EXCLUDED.rail)
+           AND ((credits.tempo_channel_id IS NULL AND EXCLUDED.tempo_channel_id IS NULL)
+                OR credits.tempo_channel_id = EXCLUDED.tempo_channel_id)
+           AND ((credits.x402_channel_id IS NULL AND EXCLUDED.x402_channel_id IS NULL)
+                OR credits.x402_channel_id = EXCLUDED.x402_channel_id)
+       RETURNING *`,
+        [
+          creditId,
+          args.callerPubkey,
+          args.currency,
+          args.amountMicro,
+          args.expiryMs,
+          nowMs,
+          b.rail,
+          b.nativeAsset ?? null,
+          b.mint ?? null,
+          b.fundingRef ?? null,
+          b.paidMsats,
+          b.nativeAmount ?? null,
+          b.tempoSession?.channelId.toLowerCase() ?? null,
+          b.x402Channel?.channelId ?? null
+        ]
+      ));
+    } catch (err) {
+      if (b.x402Channel && isUniqueViolation(err)) {
+        const channelId = b.x402Channel.channelId;
+        const { rows: bound } = await this.pool.query(
+          `SELECT credit_id, rail, x402_channel_id
+             FROM credits
+            WHERE x402_channel_id = $1`,
+          [channelId]
+        );
+        throw new CreditLedgerError(
+          "rail_mismatch",
+          bound[0] ? `x402 channel ${channelId} is already bound to credit ${bound[0].credit_id}` : `x402 channel ${channelId} is already bound to another credit`,
+          {
+            expectedRail: bound[0]?.rail ?? "x402",
+            expectedInstrument: "x402_channel",
+            expectedChannelId: channelId,
+            ...bound[0] ? { boundCreditId: bound[0].credit_id } : {}
+          },
+          { cause: err }
+        );
+      }
+      throw err;
+    }
+    if (rows.length === 0) {
+      const { rows: existing } = await q.query(
+        `SELECT caller_pubkey, currency, status, rail, tempo_channel_id, x402_channel_id
+         FROM credits WHERE credit_id = $1`,
+        [creditId]
+      );
+      const row = existing[0];
+      if (row.caller_pubkey !== args.callerPubkey) {
+        throw new CreditLedgerError(
+          "caller_mismatch",
+          `credit ${creditId} belongs to a different caller pubkey`
+        );
+      }
+      if (row.status !== "active") throw terminalCreditError(creditId, row.status);
+      if (row.currency !== args.currency) {
+        throw new CreditLedgerError(
+          "currency_mismatch",
+          `credit ${creditId} is denominated in ${row.currency}, not ${args.currency}`
+        );
+      }
+      if (row.rail !== null && row.rail !== b.rail) {
+        throw new CreditLedgerError(
+          "rail_mismatch",
+          `credit ${creditId} was funded on the ${row.rail} rail, not ${b.rail}`,
+          { expectedRail: row.rail }
+        );
+      }
+      const incomingTempoChannel = b.tempoSession?.channelId.toLowerCase() ?? null;
+      if (row.tempo_channel_id !== incomingTempoChannel) {
+        throw new CreditLedgerError(
+          "rail_mismatch",
+          row.tempo_channel_id ? `credit ${creditId} belongs to Tempo session channel ${row.tempo_channel_id}` : row.rail === "tempo" ? `credit ${creditId} was funded by a one-shot Tempo charge and cannot accept a Tempo session voucher` : `credit ${creditId} is not bound to a Tempo session channel and cannot adopt one`,
+          {
+            expectedRail: row.rail,
+            ...row.tempo_channel_id || row.rail === "tempo" ? { expectedInstrument: row.tempo_channel_id ? "tempo_session" : "tempo_charge" } : {},
+            expectedChannelId: row.tempo_channel_id
+          }
+        );
+      }
+      if (row.x402_channel_id !== (b.x402Channel?.channelId ?? null)) {
+        throw new CreditLedgerError(
+          "rail_mismatch",
+          row.x402_channel_id ? `credit ${creditId} is bound to x402 settlement channel ${row.x402_channel_id}` : row.rail === "x402" ? `credit ${creditId} was funded by a one-shot x402 exact payment and cannot accept an x402 batch-settlement channel deposit` : `credit ${creditId} is not bound to an x402 batch-settlement channel and cannot adopt one`,
+          {
+            expectedRail: row.rail,
+            ...row.x402_channel_id || row.rail === "x402" ? { expectedInstrument: row.x402_channel_id ? "x402_channel" : "x402_exact" } : {},
+            expectedChannelId: row.x402_channel_id
+          }
+        );
+      }
+      throw new CreditLedgerError(
+        "rail_mismatch",
+        `credit ${creditId} was funded on the ${row.rail} rail, not ${b.rail}`,
+        { expectedRail: row.rail }
+      );
+    }
+    await this.recordFundingLot(q, creditId, args.amountMicro, b, nowMs);
+    return this.snapshotFromRow(rows[0], q, nowMs);
+  }
+  /**
+   * Record this funding's in-kind basis as a lot (internal-review).
+   *
+   * Called from inside {@link fund}, on the same handle, so the lot shares
+   * whatever transaction the rail opened — `withCommitTx` for Cashu,
+   * `ProcessedPaymentStore.withTx` for x402/Tempo, `settleInvoice`'s own
+   * `BEGIN` for Lightning. The funding-atomicity invariant therefore extends
+   * to it structurally rather than by every call site remembering: a lot
+   * cannot exist without its ledger credit, or the credit without its lot.
+   *
+   * Only a **channel-backed** credit writes no lot: it is in-kind already —
+   * the escrow itself retains the unused value — so a lot on one would be
+   * counted as Bitcoin deposit liability the hub does not hold.
+   *
+   * Every other non-channel Bitcoin funding writes one, the implicit N=1
+   * per-call payment included. That one funds and draws the same amount in
+   * this transaction, so it looks like a lot born depleted — but the draw is a
+   * *pending hold*, not a debit, and only a `completed` job settles it
+   * (`JobManager.settlesDraw`). A failed, cancelled or stale-swept job
+   * releases the hold and the whole funded amount becomes reclaimable balance,
+   * so suppressing the lot here would leave routine traffic reclaiming off a
+   * live rate and missing from the sweep floor. One small insert on the hot
+   * path buys the invariant the liability read depends on: open lots cover
+   * `balance_micro` for every Bitcoin credit, always.
+   *
+   * A zero-sats basis still writes a lot. It is honest — the credit exists and
+   * we know its rail — and it is what makes "covered but unbacked" a
+   * distinguishable state from "no lot at all" for the reclaim and the
+   * liability rollup, instead of both reading as a gap.
+   */
+  async recordFundingLot(q, creditId, amountMicro, basis, nowMs) {
+    if (!isNonChannelBitcoinRail(basis.rail)) return;
+    if (basis.tempoSession || basis.x402Channel) return;
+    await q.query(
+      `INSERT INTO credit_funding_lots
+         (lot_id, credit_id, rail, sats_funded, credited_micro, remaining_micro, funding_ref, created_at)
+       VALUES ($1, $2, $3, $4, $5, $5, $6, $7)`,
+      [
+        `lot:${randomUUID()}`,
+        creditId,
+        basis.rail,
+        Math.floor(basis.paidMsats / 1e3),
+        amountMicro,
+        basis.fundingRef ?? null,
+        nowMs
+      ]
+    );
+  }
+  /**
+   * Place a two-phase `pending` hold of `amountMicro` against the credit and
+   * assign the next `ledger_seq`. Idempotent on `(creditId, drawId)`: a replay
+   * returns the original `{balanceAfterMicro, ledgerSeq}` with
+   * `replayed: true` and places no second hold — this is how a caller recovers
+   * a lost response (spec condition 1). A replay whose `amountMicro` or
+   * `jobId` differs from the recorded draw is not a replay but a money bug in
+   * the caller, refused with `draw_conflict`.
+   *
+   * The replay lookup runs **before** the expiry check, deliberately: a draw
+   * placed pre-expiry must stay recoverable after the credit expires, or the
+   * DVM holds a debit the caller can never reconcile. Fresh draws on an
+   * expired credit are refused with `credit_expired`; the balance stays
+   * intact and readable (spec §5: expiry ends spending, never ownership).
+   *
+   * Pass `tx` (a client inside a caller-owned `BEGIN`) to place the hold in
+   * the same transaction as the rail commit and the `fund` upsert (spec
+   * condition 3 — the internal-review implicit N=1 path). The ledger issues no
+   * transaction control on `tx`; the `SELECT … FOR UPDATE` row lock is still
+   * taken on the caller's transaction, so the locking invariant holds.
+   */
+  async draw(args) {
+    assertAmount(args.amountMicro, { min: 0 });
+    const nowMs = args.nowMs ?? Date.now();
+    const jobId = args.jobId ?? null;
+    const run = async (client, credit, tempoLifecycle) => {
+      const existing = await this.readDraw(client, args.creditId, args.drawId);
+      if (existing) {
+        const recordedJobId = existing.job_id ?? null;
+        if (toSafeInt(existing.amount_micro) !== args.amountMicro || recordedJobId !== jobId) {
+          throw new CreditLedgerError(
+            "draw_conflict",
+            `draw ${args.drawId} on credit ${args.creditId} was recorded with different parameters`,
+            {
+              expectedAmountMicro: toSafeInt(existing.amount_micro),
+              expectedJobId: recordedJobId
+            }
+          );
+        }
+        return { ...drawResultFromRow(existing, credit), replayed: true };
+      }
+      if (credit.status !== "active") throw terminalCreditError(args.creditId, credit.status);
+      if (tempoLifecycle && (tempoLifecycle.finalized || tempoLifecycle.closeRequestedAt !== 0n)) {
+        throw new CreditLedgerError(
+          "tempo_channel_closing",
+          `credit ${args.creditId} is bound to a Tempo channel that is closing or finalized`
+        );
+      }
+      const x402Refund = await this.blockingX402Refund(
+        credit.x402_channel_id,
+        X402_SPEND_BLOCKING_SETTLEMENT_STATUSES
+      );
+      if (x402Refund) throw x402SettlementPending(args.creditId, x402Refund);
+      const balanceMicro = toSafeInt(credit.balance_micro);
+      const expiryMs = toSafeInt(credit.expiry_ms);
+      if (expiryMs <= nowMs) {
+        throw new CreditLedgerError("credit_expired", `credit ${args.creditId} expired`, {
+          expiryMs,
+          balanceMicro
+        });
+      }
+      const pending = await this.pendingSums(client, args.creditId);
+      const available = balanceMicro - pending.micro;
+      if (args.amountMicro > available) {
+        throw new CreditLedgerError(
+          "insufficient_credit",
+          `draw of ${args.amountMicro} exceeds available balance ${available}`,
+          { availableMicro: available, balanceMicro, requestedMicro: args.amountMicro }
+        );
+      }
+      const nativeRemaining = credit.native_remaining === null ? null : toSafeInt(credit.native_remaining);
+      const railValue = allocateDrawValue({
+        amountMicro: args.amountMicro,
+        availableMicro: available,
+        availableMsats: Math.max(0, toSafeInt(credit.msats_remaining) - pending.msats),
+        availableNative: nativeRemaining === null ? null : Math.max(0, nativeRemaining - pending.native)
+      });
+      const ledgerSeq = toSafeInt(credit.last_ledger_seq) + 1;
+      const balanceAfterMicro = available - args.amountMicro;
+      await client.query(`UPDATE credits SET last_ledger_seq = $2 WHERE credit_id = $1`, [
+        args.creditId,
+        ledgerSeq
+      ]);
+      await client.query(
+        `INSERT INTO credit_draws
+           (credit_id, draw_id, amount_micro, job_id, ledger_seq, status, balance_after_micro, created_at,
+            draw_msats, draw_native)
+         VALUES ($1, $2, $3, $4, $5, 'pending', $6, $7, $8, $9)`,
+        [
+          args.creditId,
+          args.drawId,
+          args.amountMicro,
+          jobId,
+          ledgerSeq,
+          balanceAfterMicro,
+          nowMs,
+          railValue.drawMsats,
+          railValue.drawNative
+        ]
+      );
+      return {
+        creditId: args.creditId,
+        drawId: args.drawId,
+        amountMicro: args.amountMicro,
+        balanceAfterMicro,
+        ledgerSeq,
+        status: "pending",
+        replayed: false,
+        railValue: { ...railValue, ...creditBasisFromRow(credit) },
+        resolvedAt: null
+      };
+    };
+    const query = args.tx ?? this.pool;
+    const { rows } = await query.query(
+      `SELECT tempo_channel_id FROM credits WHERE credit_id = $1`,
+      [args.creditId]
+    );
+    const channelId = rows[0]?.tempo_channel_id;
+    if (channelId && this.tempoSessionStore) {
+      return this.tempoSessionStore.withDrawPlacement(
+        channelId,
+        async (tx, lifecycle) => {
+          const credit = await this.lockCreditRow(tx, args.creditId);
+          return run(tx, credit, lifecycle);
+        },
+        args.tx
+      );
+    }
+    if (args.tx) {
+      const credit = await this.lockCreditRow(args.tx, args.creditId);
+      return run(args.tx, credit);
+    }
+    return this.withCreditLock(args.creditId, (client, credit) => run(client, credit));
+  }
+  /**
+   * The unresolved refund on `channelId` that must stop this ledger effect, if
+   * any (internal-review).
+   *
+   * `undefined` whenever there is nothing to ask — an unbound credit, or a DVM
+   * with no durable settlement store, where a settlement row cannot exist.
+   *
+   * Public since internal-review, so `/v1/credit`'s pre-payment preflight can ask the
+   * same question `fund` will ask from inside the rail transaction — one read,
+   * one answer, rather than a second copy of the rule in the routes.
+   */
+  async blockingX402Refund(channelId, statuses) {
+    if (!channelId || !this.x402Settlements) return void 0;
+    return this.x402Settlements.pendingRefundSettlement(channelId, statuses);
+  }
+  /**
+   * Grow a pending draw by `addAmountMicro` (internal-review) — the ledger half of a
+   * mid-job `requestPayment` top-up. One job keeps **one** draw: the mid-job
+   * money funds the same credit and enlarges the hold the upfront leg placed,
+   * so the receipt's `ReceiptCredit` block countersigns the job's full cost
+   * and `revenue_events` still books exactly one row per job.
+   *
+   * `draw()` cannot express this: a same-`draw_id` call with a different
+   * amount is `draw_conflict` by design (a replayed draw must never re-price).
+   *
+   * The arithmetic is `draw()`'s, unchanged: `addAmountMicro` is checked
+   * against — and `balance_after_micro` recomputed from — the balance net of
+   * **every** pending hold, this draw's own included. That is deliberately the
+   * conservative reading (a fresh draw of `addAmountMicro` would see exactly
+   * the same figure), and it is what keeps the total held after growth inside
+   * the credit's balance.
+   *
+   * The increment's rail value comes from {@link growthRailValue}: earmarked
+   * to the funding that backs it when the caller names one (the mid-job case),
+   * pro-rata otherwise. Either way the draws of a credit keep summing to
+   * precisely what the rails paid (internal-review).
+   *
+   * **`ledger_seq` is not re-taken.** The per-credit sequence is gap-free
+   * (`credit_draws_seq_uidx`), so moving this draw forward would strand its
+   * original number. The consequence is deliberate and worth knowing: the
+   * recorded `balance_after_micro` is the post-growth figure stamped at the
+   * *original* seq, so a credit with interleaved sibling activity has a
+   * trajectory that is truthful per draw rather than monotonic across seqs.
+   *
+   * **No expiry check**, matching `settle`/`release`: the job was accepted
+   * pre-expiry and is still running. Refusing here would strand the handler
+   * mid-flight over a clock the caller can't influence.
+   *
+   * **Not idempotent by itself.** Growth carries no key of its own — it
+   * inherits the rail's (the accumulator's `(dvm_id, request_id)` UNIQUE rolls
+   * the whole transaction back on replay; x402/mpp collide on the
+   * `processed_payments` marker). Never call it outside a rail commit.
+   *
+   * **`capMicro` bounds cumulative growth at what the job cumulatively asked
+   * (internal-review)**, and it is the only ceiling that can refuse a top-up: the
+   * available-balance check cannot, because the `fund` a moment earlier in
+   * this same transaction raised the balance by exactly the amount being
+   * drawn. Excess is **granted partially or not at all rather than thrown** —
+   * this runs inside the rail commit, so a throw would roll back cashu proofs
+   * the caller already sent. The refused remainder stays funded balance the
+   * caller owns and can drain.
+   */
+  async growDraw(args) {
+    assertAmount(args.addAmountMicro, { min: 1 });
+    const run = async (client, credit) => {
+      const existing = await this.readDraw(client, args.creditId, args.drawId);
+      if (!existing) {
+        throw new CreditLedgerError(
+          "draw_not_found",
+          `draw ${args.drawId} not found on credit ${args.creditId}`
+        );
+      }
+      if (existing.status !== "pending") {
+        throw new CreditLedgerError(
+          "invalid_draw_state",
+          `cannot grow draw ${args.drawId}: status is ${existing.status}`,
+          { currentStatus: existing.status }
+        );
+      }
+      if (credit.status !== "active") throw terminalCreditError(args.creditId, credit.status);
+      if (args.jobId !== void 0 && (existing.job_id ?? null) !== args.jobId) {
+        throw new CreditLedgerError(
+          "draw_conflict",
+          `draw ${args.drawId} on credit ${args.creditId} belongs to a different job`,
+          { expectedJobId: existing.job_id ?? null }
+        );
+      }
+      const priorGrown = toSafeInt(existing.grown_micro);
+      const headroom = args.capMicro === void 0 ? args.addAmountMicro : Math.max(0, args.capMicro - priorGrown);
+      const grantMicro = Math.min(args.addAmountMicro, headroom);
+      const balanceMicro = toSafeInt(credit.balance_micro);
+      const pending = await this.pendingSums(client, args.creditId);
+      const available = balanceMicro - pending.micro;
+      if (grantMicro <= 0) {
+        return {
+          creditId: args.creditId,
+          drawId: args.drawId,
+          amountMicro: toSafeInt(existing.amount_micro),
+          balanceAfterMicro: toSafeInt(existing.balance_after_micro),
+          ledgerSeq: toSafeInt(existing.ledger_seq),
+          status: "pending",
+          replayed: false,
+          railValue: {
+            drawMsats: toSafeInt(existing.draw_msats),
+            drawNative: existing.draw_native === null ? null : toSafeInt(existing.draw_native),
+            ...creditBasisFromRow(credit)
+          },
+          resolvedAt: null,
+          addedRailValue: { drawMsats: 0, drawNative: null },
+          addedAmountMicro: 0,
+          cappedMicro: args.addAmountMicro
+        };
+      }
+      if (grantMicro > available) {
+        throw new CreditLedgerError(
+          "insufficient_credit",
+          `top-up draw of ${grantMicro} exceeds available balance ${available}`,
+          { availableMicro: available, balanceMicro, requestedMicro: grantMicro }
+        );
+      }
+      const priorMsats = toSafeInt(existing.draw_msats);
+      const priorNative = existing.draw_native === null ? null : toSafeInt(existing.draw_native);
+      const nativeRemaining = credit.native_remaining === null ? null : toSafeInt(credit.native_remaining);
+      const added = growthRailValue({
+        earmark: clipEarmark(args.addRailValue, grantMicro, args.addAmountMicro),
+        amountMicro: grantMicro,
+        availableMicro: available,
+        availableMsats: Math.max(0, toSafeInt(credit.msats_remaining) - pending.msats),
+        availableNative: nativeRemaining === null ? null : Math.max(0, nativeRemaining - pending.native)
+      });
+      const amountMicro = toSafeInt(existing.amount_micro) + grantMicro;
+      const balanceAfterMicro = available - grantMicro;
+      const drawMsats = priorMsats + added.drawMsats;
+      const drawNative = added.drawNative === null ? priorNative : (priorNative ?? 0) + added.drawNative;
+      await client.query(
+        `UPDATE credit_draws
+            SET amount_micro = $3, balance_after_micro = $4, draw_msats = $5, draw_native = $6,
+                grown_micro = $7
+          WHERE credit_id = $1 AND draw_id = $2`,
+        [
+          args.creditId,
+          args.drawId,
+          amountMicro,
+          balanceAfterMicro,
+          drawMsats,
+          drawNative,
+          priorGrown + grantMicro
+        ]
+      );
+      return {
+        creditId: args.creditId,
+        drawId: args.drawId,
+        amountMicro,
+        balanceAfterMicro,
+        ledgerSeq: toSafeInt(existing.ledger_seq),
+        status: "pending",
+        replayed: false,
+        railValue: { drawMsats, drawNative, ...creditBasisFromRow(credit) },
+        resolvedAt: null,
+        addedRailValue: added,
+        addedAmountMicro: grantMicro,
+        cappedMicro: args.addAmountMicro - grantMicro
+      };
+    };
+    if (args.tx) {
+      const credit = await this.lockCreditRow(args.tx, args.creditId);
+      return run(args.tx, credit);
+    }
+    return this.withCreditLock(args.creditId, run);
+  }
+  /**
+   * Finalize a pending draw: the hold becomes a real debit
+   * (`balance_micro −= amount`). Available balance is unchanged — the amount
+   * moves from "held" to "spent" — so the `balanceAfterMicro` trajectory
+   * recorded at draw time stays truthful for settled draws, which is what the
+   * receipt chain countersigns. Idempotent: settling a settled draw returns
+   * the original tuple. A released draw cannot be settled
+   * (`invalid_draw_state`) — release-then-settle would debit money the caller
+   * was already told is theirs again.
+   *
+   * Deliberately **no expiry check** here (nor on `release`): a job accepted
+   * pre-expiry routinely reaches its terminal post-expiry, and refusing would
+   * leak the hold forever. Expiry gates new draws only.
+   */
+  async settle(args) {
+    if (!this.tempoSessionStore) return this.resolveDraw({ ...args, to: "settled" });
+    const { rows } = await this.pool.query(
+      `SELECT tempo_channel_id FROM credits WHERE credit_id = $1`,
+      [args.creditId]
+    );
+    const channelId = rows[0]?.tempo_channel_id;
+    if (!channelId) return this.resolveDraw({ ...args, to: "settled" });
+    return this.tempoSessionStore.withTerminalConsumption(channelId, async (tx, lifecycle) => {
+      const credit = await this.lockCreditRow(tx, args.creditId);
+      const draw = await this.readDraw(tx, args.creditId, args.drawId);
+      if (!draw) {
+        throw new CreditLedgerError(
+          "draw_not_found",
+          `draw ${args.drawId} not found on credit ${args.creditId}`
+        );
+      }
+      const drawNative = draw.draw_native === null ? null : BigInt(draw.draw_native);
+      if (drawNative === null) {
+        throw new CreditLedgerError(
+          "invalid_basis",
+          `Tempo session draw ${args.drawId} has no native value to consume`
+        );
+      }
+      if (draw.status === "settled") {
+        const value2 = await this.resolveDrawLocked(tx, credit, { ...args, to: "settled" });
+        return { value: value2, amount: drawNative, consume: false };
+      }
+      if (credit.status === "unbacked") {
+        const value2 = await this.resolveDrawLocked(tx, credit, {
+          ...args,
+          to: "released"
+        });
+        return { value: value2, amount: 0n, consume: false };
+      }
+      const closing = lifecycle.finalized || lifecycle.closeRequestedAt !== 0n;
+      const covered = lifecycle.settledOnChain >= lifecycle.highestVoucherAmount;
+      if (closing && !covered) {
+        if (!lifecycle.finalized) {
+          throw new CreditLedgerError(
+            "tempo_settlement_pending",
+            `Tempo channel settlement has not yet covered draw ${args.drawId}`
+          );
+        }
+        const value2 = await this.resolveDrawLocked(tx, credit, {
+          ...args,
+          to: "released"
+        });
+        return { value: value2, amount: 0n, consume: false };
+      }
+      const value = await this.resolveDrawLocked(tx, credit, { ...args, to: "settled" });
+      return {
+        value,
+        amount: drawNative,
+        consume: !closing && !value.replayed
+      };
+    });
+  }
+  /**
+   * Release a pending draw: the hold evaporates, the balance is untouched —
+   * this is how "no debit on job failure" is mechanically real (spec §1).
+   * Idempotent: releasing a released draw returns the original tuple. A
+   * settled draw cannot be released (`invalid_draw_state`) — un-settling
+   * booked revenue is a reconciliation problem, not a ledger verb.
+   */
+  async release(args) {
+    return this.resolveDraw({ ...args, to: "released" });
+  }
+  /**
+   * Record a fund-only top-up under its client-generated `fundId` (internal-review).
+   * The deposit half of the evidence chain, and the top-up path's idempotency
+   * key: `PRIMARY KEY (credit_id, fund_id)` means a concurrent duplicate
+   * loses with a typed `funding_replayed` rather than crediting twice.
+   *
+   * Call it inside the same `tx` as {@link fund} — the rail commit, the
+   * funding record, and the balance increment must land together or not at
+   * all (spec §2 condition 3). Like `fund`, this issues no transaction
+   * control on `tx`; it is a single statement.
+   *
+   * This does **not** move money on its own. `fund` still does the crediting;
+   * this row is what lets a retry be answered with the original outcome.
+   */
+  async recordFunding(args) {
+    assertAmount(args.amountMicro, { min: 1 });
+    const q = args.tx ?? this.pool;
+    const nowMs = args.nowMs ?? Date.now();
+    const { rows } = await q.query(
+      `INSERT INTO credit_fundings (credit_id, fund_id, amount_micro, rail, created_at)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (credit_id, fund_id) DO NOTHING
+       RETURNING *`,
+      [args.creditId, args.fundId, args.amountMicro, args.rail ?? null, nowMs]
+    );
+    if (rows.length === 0) {
+      throw new CreditLedgerError(
+        "funding_replayed",
+        `funding ${args.fundId} on credit ${args.creditId} was already recorded`
+      );
+    }
+    return fundingRecordFromRow(rows[0]);
+  }
+  /**
+   * Read one funding record (no lock). The `/v1/credit` fund path checks this
+   * **before** touching a rail, so a retried top-up costs nothing and returns
+   * the original outcome instead of presenting an artifact the rail would
+   * refuse as spent.
+   */
+  async getFunding(args) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credit_fundings WHERE credit_id = $1 AND fund_id = $2`,
+      [args.creditId, args.fundId]
+    );
+    return rows.length > 0 ? fundingRecordFromRow(rows[0]) : void 0;
+  }
+  /** Fix the funding-time receipt tuple inside the rail's open transaction. */
+  async completeFunding(args) {
+    const q = args.tx ?? this.pool;
+    const { rows } = await q.query(
+      `UPDATE credit_fundings
+          SET caller_pubkey = COALESCE(caller_pubkey, $3),
+              balance_after_micro = COALESCE(balance_after_micro, $4),
+              ledger_seq = COALESCE(ledger_seq, $5)
+        WHERE credit_id = $1 AND fund_id = $2
+        RETURNING *`,
+      [args.creditId, args.fundId, args.callerPubkey, args.balanceAfterMicro, args.ledgerSeq]
+    );
+    if (rows.length === 0) {
+      throw new CreditLedgerError(
+        "credit_not_found",
+        `funding ${args.fundId} on credit ${args.creditId} was not recorded`
+      );
+    }
+    return fundingRecordFromRow(rows[0]);
+  }
+  /** Persist the first signature for a funding; concurrent issuers read back the winner. */
+  async saveFundingReceipt(args) {
+    const { rows } = await this.pool.query(
+      `UPDATE credit_fundings SET receipt = COALESCE(receipt, $3::jsonb)
+        WHERE credit_id = $1 AND fund_id = $2
+        RETURNING *`,
+      [args.creditId, args.fundId, JSON.stringify(args.receipt)]
+    );
+    if (!rows[0]?.receipt) {
+      throw new CreditLedgerError(
+        "credit_not_found",
+        `funding ${args.fundId} on credit ${args.creditId} was not recorded`
+      );
+    }
+    return rows[0].receipt;
+  }
+  /**
+   * Record the bolt11 issued for a `(creditId, fundId)` top-up (internal-review), or
+   * return the one already issued for it.
+   *
+   * **Returning the existing row is the point.** A caller re-polling an unpaid
+   * top-up must get the invoice they were handed the first time; minting a
+   * fresh bolt11 per attempt is the double-charge bug — they pay the second
+   * one, the first stays payable, and both settle onto one `fund_id` that can
+   * only be credited once.
+   */
+  async recordInvoice(args) {
+    assertAmount(args.amountMicro, { min: 1 });
+    const nowMs = args.nowMs ?? Date.now();
+    let rows;
+    try {
+      ({ rows } = await this.pool.query(
+        `INSERT INTO credit_invoices (credit_id, fund_id, caller_pubkey, currency, amount_micro,
+                                      amount_msats, payment_hash, bolt11, status, expires_at, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'pending', $9, $10)
+         ON CONFLICT (credit_id, fund_id) DO NOTHING
+         RETURNING *`,
+        [
+          args.creditId,
+          args.fundId,
+          args.callerPubkey,
+          args.currency,
+          args.amountMicro,
+          args.amountMsats,
+          args.paymentHash,
+          args.bolt11,
+          args.expiresAt,
+          nowMs
+        ]
+      ));
+    } catch (err) {
+      if (isUniqueViolation(err)) {
+        throw new CreditLedgerError(
+          "invoice_conflict",
+          `payment hash ${args.paymentHash} is already bound to another funding`,
+          {},
+          { cause: err }
+        );
+      }
+      throw err;
+    }
+    if (rows.length > 0) return invoiceRecordFromRow(rows[0]);
+    const existing = await this.getInvoice({ creditId: args.creditId, fundId: args.fundId });
+    if (!existing) {
+      throw new CreditLedgerError(
+        "invoice_not_found",
+        `invoice for funding ${args.fundId} on credit ${args.creditId} vanished between write and read`
+      );
+    }
+    return existing;
+  }
+  /** Read one invoice (no lock). */
+  async getInvoice(args) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credit_invoices WHERE credit_id = $1 AND fund_id = $2`,
+      [args.creditId, args.fundId]
+    );
+    return rows.length > 0 ? invoiceRecordFromRow(rows[0]) : void 0;
+  }
+  /**
+   * A caller's outstanding invoices, oldest first — the settlement sweep's
+   * read. Local and indexed, so the wallet is only consulted when something is
+   * genuinely outstanding.
+   */
+  async listPendingInvoices(args) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credit_invoices
+        WHERE caller_pubkey = $1 AND status = 'pending'
+          AND ($2::text IS NULL OR credit_id = $2)
+        ORDER BY created_at, fund_id
+        LIMIT $3`,
+      [args.callerPubkey, args.creditId ?? null, args.limit]
+    );
+    return rows.map(invoiceRecordFromRow);
+  }
+  /**
+   * Apply an observed Lightning settlement to the ledger — **the exactly-once
+   * boundary** (internal-review; spec §2 condition 3 for a rail whose commit happens
+   * off-box).
+   *
+   * One transaction covers the funding record, the balance, and the invoice's
+   * own status flip, so the three can never disagree. A crash anywhere inside
+   * leaves the invoice `pending` and the balance untouched: the next
+   * `lookup_invoice` observes the same settled payment and credits it, once.
+   * A replayed check after the commit sees `settled` and moves nothing.
+   *
+   * The lock is on the **invoice** row, not the credit row: the first
+   * Lightning top-up is what opens the credit, so there is frequently no
+   * `credits` row to take `FOR UPDATE` yet. That does not weaken the ledger's
+   * concurrency contract — no `credit_draws` write happens here, and `fund`'s
+   * upsert is a single statement — while still serialising two settlement
+   * checks racing on the same invoice.
+   */
+  async settleInvoice(args) {
+    assertFundingBasis(args.basis);
+    const nowMs = args.nowMs ?? Date.now();
+    const settledAt = args.settledAtMs ?? nowMs;
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `SELECT * FROM credit_invoices WHERE credit_id = $1 AND fund_id = $2 FOR UPDATE`,
+        [args.creditId, args.fundId]
+      );
+      if (rows.length === 0) {
+        throw new CreditLedgerError(
+          "invoice_not_found",
+          `no invoice for funding ${args.fundId} on credit ${args.creditId}`
+        );
+      }
+      const invoice = invoiceRecordFromRow(rows[0]);
+      if (invoice.status === "settled") {
+        await client.query("COMMIT");
+        const [funding2, credit2] = await Promise.all([
+          this.getFunding({ creditId: args.creditId, fundId: args.fundId }),
+          this.get(args.creditId, { nowMs })
+        ]);
+        return { invoice, funding: funding2, credit: credit2, replayed: true };
+      }
+      const funding = await this.recordFunding({
+        creditId: invoice.creditId,
+        fundId: invoice.fundId,
+        amountMicro: invoice.amountMicro,
+        rail: "lightning",
+        tx: client,
+        nowMs
+      });
+      const credit = await this.fund({
+        creditId: invoice.creditId,
+        callerPubkey: invoice.callerPubkey,
+        currency: invoice.currency,
+        amountMicro: invoice.amountMicro,
+        expiryMs: args.expiryMs,
+        basis: args.basis,
+        tx: client,
+        nowMs
+      });
+      await this.completeFunding({
+        creditId: invoice.creditId,
+        fundId: invoice.fundId,
+        callerPubkey: invoice.callerPubkey,
+        balanceAfterMicro: credit.availableMicro,
+        ledgerSeq: credit.lastLedgerSeq,
+        tx: client
+      });
+      const settled = await client.query(
+        `UPDATE credit_invoices SET status = 'settled', settled_at = $3
+          WHERE credit_id = $1 AND fund_id = $2
+          RETURNING *`,
+        [args.creditId, args.fundId, settledAt]
+      );
+      if (args.depositOutbox) {
+        await args.depositOutbox.enqueue(client, args.depositOutbox.payload);
+      }
+      await client.query("COMMIT");
+      return {
+        invoice: invoiceRecordFromRow(settled.rows[0]),
+        funding,
+        credit,
+        replayed: false
+      };
+    } catch (err) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Retire an invoice that expired without being paid — bookkeeping only, no
+   * ledger effect. A CAS on `pending` so it can never overwrite a settlement
+   * observed concurrently.
+   */
+  async markInvoiceExpired(args) {
+    await this.pool.query(
+      `UPDATE credit_invoices SET status = 'expired'
+        WHERE credit_id = $1 AND fund_id = $2 AND status = 'pending'`,
+      [args.creditId, args.fundId]
+    );
+    return this.getInvoice(args);
+  }
+  /**
+   * Retire an invoice that **was paid** and can never be credited (internal-review).
+   *
+   * Distinct from `expired` because the money is the opposite way round: an
+   * expired invoice was never paid and owes nobody anything, whereas a blocked
+   * one has sats sitting in the builder's wallet with no ledger row to put them
+   * on. Only an operator can resolve that, so the row records `reason` and
+   * stops being swept — leaving it `pending` would spend one of the sweep's few
+   * slots re-deriving the same verdict on every request the caller makes, and
+   * three of them would wedge that caller's sweep so a genuinely payable
+   * invoice behind them never credits.
+   *
+   * A CAS on `pending`, like the expiry retirement: a settlement observed
+   * concurrently must win.
+   */
+  async markInvoiceBlocked(args) {
+    await this.pool.query(
+      `UPDATE credit_invoices SET status = 'blocked', blocked_reason = $3
+        WHERE credit_id = $1 AND fund_id = $2 AND status = 'pending'`,
+      [args.creditId, args.fundId, args.reason]
+    );
+    return this.getInvoice(args);
+  }
+  /** Read one invoice by the wallet's own identifier for the payment (no lock). */
+  async getInvoiceByPaymentHash(paymentHash) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credit_invoices WHERE payment_hash = $1`,
+      [paymentHash]
+    );
+    return rows.length > 0 ? invoiceRecordFromRow(rows[0]) : void 0;
+  }
+  /**
+   * The operator's queue: invoices the sweep gave up on (internal-review).
+   *
+   * **Keyset-paginated, not offset.** Blocked rows are terminal and never
+   * self-clear, so a row the operator declines to act on sits at the head of
+   * the age ordering forever; a fixed first page would starve everything
+   * behind it on every run, which is the internal-review shape one page up.
+   *
+   * `includeResolved` widens to the operator-resolved statuses so a run can be
+   * audited after the fact — the acceptance criterion this verb exists for.
+   * Host-wide, like `listPendingDrains`: the ledger has no `dvm_id`, so on a
+   * multi-mount host one builder's admin credential reads every mount's rows.
+   */
+  async listBlockedInvoices(args) {
+    const statuses = args.includeResolved ? ["blocked", "reconciled", "written_off"] : ["blocked"];
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credit_invoices
+        WHERE status = ANY($1::text[])
+          AND ($2::bigint IS NULL
+               OR (created_at, credit_id, fund_id) > ($2::bigint, $3::text, $4::text))
+        ORDER BY created_at, credit_id, fund_id
+        LIMIT $5`,
+      [
+        statuses,
+        args.after?.createdAt ?? null,
+        args.after?.creditId ?? null,
+        args.after?.fundId ?? null,
+        args.limit
+      ]
+    );
+    return rows.map(invoiceRecordFromRow);
+  }
+  /**
+   * Apply a blocked invoice's payment to a credit an operator named — the
+   * repair for the one Lightning outcome the DVM cannot fix itself (internal-review).
+   *
+   * Shaped statement-for-statement on {@link settleInvoice}, because it is the
+   * same money doing the same thing a different way: one transaction covering
+   * the funding record, the balance, the invoice's status flip and the deposit
+   * outbox row, so the four can never disagree. Three deliberate differences:
+   *
+   * - **The lock is taken on `payment_hash`**, which is UNIQUE and is the
+   *   identifier the operator actually holds (it is what the
+   *   `lightning_settlement_blocked` log carries and what names the payment in
+   *   their wallet). Invoice row first, credit row second via `fund`'s upsert —
+   *   the same order `settleInvoice` takes, which is what keeps a reconcile and
+   *   a concurrent settlement check from deadlocking against each other.
+   * - **The funding lands at `(targetCreditId, paymentHash)`, not the invoice's
+   *   own `(credit_id, fund_id)`.** That key is frequently the reason the row
+   *   is blocked at all — `funding_replayed_on_cashu` means something else
+   *   already holds it — and the operator's most natural target is that very
+   *   credit. The payment hash cannot collide with it, and it makes all three
+   *   references to this payment agree: `basis.fundingRef`, the deposit's
+   *   `funding_id`, and the funding row's `fund_id`.
+   * - **`written_off` is an accepted input status.** A write-off unwound
+   *   nothing, so an operator who closed a row by mistake must not need raw SQL
+   *   against a money table to reopen it.
+   *
+   * The invoice row's status — never the funding row — is the idempotency
+   * source of truth. `fund_id` is caller-chosen and the payment hash is
+   * disclosed to them, so a caller *can* squat `(theirCredit, thatHash)` with a
+   * top-up on another rail; when they have, `recordFunding` throws
+   * `funding_replayed` and that surfaces as its own loud failure rather than
+   * being absorbed as "already reconciled".
+   */
+  async reconcileBlockedInvoice(args) {
+    assertFundingBasis(args.basis);
+    const nowMs = args.nowMs ?? Date.now();
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `SELECT * FROM credit_invoices WHERE payment_hash = $1 FOR UPDATE`,
+        [args.paymentHash]
+      );
+      if (rows.length === 0) {
+        throw new CreditLedgerError(
+          "invoice_not_found",
+          `no invoice for payment hash ${args.paymentHash}`
+        );
+      }
+      const invoice = invoiceRecordFromRow(rows[0]);
+      if (invoice.status === "reconciled") {
+        await client.query("COMMIT");
+        const [funding2, credit2] = await Promise.all([
+          invoice.reconciledCreditId && invoice.reconciledFundId ? this.getFunding({
+            creditId: invoice.reconciledCreditId,
+            fundId: invoice.reconciledFundId
+          }) : Promise.resolve(void 0),
+          invoice.reconciledCreditId ? this.get(invoice.reconciledCreditId, { nowMs }) : Promise.resolve(void 0)
+        ]);
+        return { invoice, funding: funding2, credit: credit2, replayed: true };
+      }
+      if (invoice.status !== "blocked" && invoice.status !== "written_off") {
+        throw new CreditLedgerError(
+          "invoice_not_blocked",
+          `invoice ${args.paymentHash} is ${invoice.status}; only a blocked or written-off invoice can be reconciled`
+        );
+      }
+      const funding = await this.recordFunding({
+        creditId: args.targetCreditId,
+        fundId: invoice.paymentHash,
+        amountMicro: invoice.amountMicro,
+        rail: "lightning",
+        tx: client,
+        nowMs
+      });
+      const credit = await this.fund({
+        creditId: args.targetCreditId,
+        callerPubkey: invoice.callerPubkey,
+        currency: invoice.currency,
+        amountMicro: invoice.amountMicro,
+        expiryMs: args.expiryMs,
+        basis: args.basis,
+        tx: client,
+        nowMs
+      });
+      await this.completeFunding({
+        creditId: args.targetCreditId,
+        fundId: invoice.paymentHash,
+        callerPubkey: invoice.callerPubkey,
+        balanceAfterMicro: credit.availableMicro,
+        ledgerSeq: credit.lastLedgerSeq,
+        tx: client
+      });
+      const reconciled = await client.query(
+        `UPDATE credit_invoices
+            SET status = 'reconciled',
+                reconciled_credit_id = $2,
+                reconciled_fund_id = $3,
+                resolved_at = $4,
+                settled_at = COALESCE($5, settled_at)
+          WHERE payment_hash = $1
+          RETURNING *`,
+        [
+          args.paymentHash,
+          args.targetCreditId,
+          invoice.paymentHash,
+          nowMs,
+          args.settledAtMs ?? null
+        ]
+      );
+      if (args.depositOutbox) {
+        await args.depositOutbox.enqueue(client, args.depositOutbox.payload);
+      }
+      await client.query("COMMIT");
+      return {
+        invoice: invoiceRecordFromRow(reconciled.rows[0]),
+        funding,
+        credit,
+        replayed: false
+      };
+    } catch (err) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Record that an operator reviewed a blocked invoice and chose not to credit
+   * it (internal-review) — no ledger effect, purely a queue transition.
+   *
+   * A CAS on `blocked`, and idempotent: re-running returns the recorded row
+   * rather than overwriting the first note. It cannot capture a `reconciled`
+   * row, because that one moved money.
+   *
+   * `written` reports whether *this* call was the transition. The caller has
+   * no other way to tell — the row reads identically either way — and the
+   * write-off's audit log is the only record of the amount, so a re-emitted
+   * one reads as a second decision about the same sats.
+   */
+  async writeOffBlockedInvoice(args) {
+    const { rowCount } = await this.pool.query(
+      `UPDATE credit_invoices SET status = 'written_off', write_off_note = $2, resolved_at = $3
+        WHERE payment_hash = $1 AND status = 'blocked'`,
+      [args.paymentHash, args.note ?? null, args.nowMs ?? Date.now()]
+    );
+    const invoice = await this.getInvoiceByPaymentHash(args.paymentHash);
+    if (!invoice) return void 0;
+    return { invoice, written: (rowCount ?? 0) > 0 };
+  }
+  /** Read one credit (no lock). Expired credits stay fully readable. */
+  async get(creditId, opts) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credits WHERE credit_id = $1`,
+      [creditId]
+    );
+    if (rows.length === 0) return void 0;
+    return this.snapshotFromRow(rows[0], this.pool, opts?.nowMs ?? Date.now());
+  }
+  /** Read all credits held by a caller pubkey, oldest first (no lock). */
+  async getForCaller(callerPubkey, opts) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credits WHERE caller_pubkey = $1 ORDER BY created_at, credit_id`,
+      [callerPubkey]
+    );
+    const nowMs = opts?.nowMs ?? Date.now();
+    const out = [];
+    for (const row of rows) {
+      out.push(await this.snapshotFromRow(row, this.pool, nowMs));
+    }
+    return out;
+  }
+  /** Read one draw (no lock), with its credit's rail basis joined in. */
+  async getDraw(args) {
+    const { rows } = await this.pool.query(
+      `${DRAW_WITH_BASIS_SELECT} WHERE d.credit_id = $1 AND d.draw_id = $2`,
+      [args.creditId, args.drawId]
+    );
+    return rows[0] ? drawRecordFromRow(rows[0], rows[0]) : void 0;
+  }
+  /** Read the sole draw bound to a pre-allocated job id; ambiguity fails closed. */
+  async getDrawByJobId(jobId) {
+    const { rows } = await this.pool.query(
+      `${DRAW_WITH_BASIS_SELECT} WHERE d.job_id = $1 ORDER BY d.created_at LIMIT 2`,
+      [jobId]
+    );
+    return rows.length === 1 ? drawRecordFromRow(rows[0], rows[0]) : void 0;
+  }
+  /**
+   * All pending holds on a credit, in `ledger_seq` order (no lock). Read
+   * surface for the internal-review sweeper wiring — a worker that dies mid-job
+   * leaves its hold `pending` until something releases it.
+   */
+  async listPendingDraws(creditId) {
+    const { rows } = await this.pool.query(
+      `${DRAW_WITH_BASIS_SELECT} WHERE d.credit_id = $1 AND d.status = 'pending' ORDER BY d.ledger_seq`,
+      [creditId]
+    );
+    return rows.map((row) => drawRecordFromRow(row, row));
+  }
+  /**
+   * One page of pending holds host-wide placed before `createdBeforeMs`,
+   * oldest first (no lock). The orphan sweeper's read surface (internal-review): a
+   * draw commits with its `job_id` before the job row is persisted, so a crash
+   * or a fail-closed refusal in that window strands a hold nothing can ever
+   * resolve — the only release path keys off the `credit_id`/`draw_id` written
+   * on the job row.
+   *
+   * Host-wide like {@link listPendingDrains}, not per-credit: the sweeper has
+   * no candidate credit to start from. Age-bounded so it never sees a draw
+   * whose job row is merely still in flight.
+   *
+   * `limit` is required and `after` keyset-paginates: an aged hold whose job
+   * row *does* exist is legitimately un-sweepable and stays `pending`
+   * indefinitely, so a caller that re-issues the same first page would never
+   * see past a `limit`-sized wall of them. Pass the last row's
+   * {@link StalePendingDrawCursor} to advance.
+   */
+  async listStalePendingDraws(args) {
+    const after = args.after;
+    const { rows } = await this.pool.query(
+      `${DRAW_WITH_BASIS_SELECT}
+         WHERE d.status = 'pending' AND d.created_at < $1
+           AND ($3::bigint IS NULL
+                OR (d.created_at, d.credit_id, d.ledger_seq) > ($3::bigint, $4::text, $5::bigint))
+         ORDER BY d.created_at, d.credit_id, d.ledger_seq
+         LIMIT $2`,
+      [
+        args.createdBeforeMs,
+        args.limit,
+        after?.createdAt ?? null,
+        after?.creditId ?? null,
+        after?.ledgerSeq ?? null
+      ]
+    );
+    return rows.map((row) => drawRecordFromRow(row, row));
+  }
+  /**
+   * Rail-native value the credit an x402 settlement channel funded has
+   * actually earned — the sum of its **settled** draws, in the credit's native
+   * atomic units (USDC micro on this rail). The batch-settlement claim job's
+   * ceiling (internal-review): a channel is claimable up to what its credit's draws
+   * have earned, never up to the deposit that funded it.
+   *
+   * `undefined` when no credit is bound to the channel, which the claim job
+   * treats as "cannot be resolved" and claims nothing for — distinct from a
+   * resolved credit that has earned `0`.
+   *
+   * Deliberately a sum over settled draws rather than `funded − remaining`:
+   * a drain lowers `native_remaining` without earning anything, so the
+   * subtraction would read the caller's own reclaim as revenue. Pending holds
+   * are excluded for the mirror reason — a hold is work in flight, and
+   * claiming against it would take money a release still owes back.
+   */
+  async earnedNativeForX402Channel(channelId) {
+    const { rows } = await this.pool.query(
+      `SELECT COALESCE(
+                (SELECT SUM(d.draw_native)
+                   FROM credit_draws d
+                  WHERE d.credit_id = c.credit_id
+                    AND d.status = 'settled'
+                    AND d.draw_native IS NOT NULL),
+                0
+              )::text AS earned
+         FROM credits c
+        WHERE c.x402_channel_id = $1`,
+      [channelId]
+    );
+    if (rows.length === 0) return void 0;
+    return toSafeInt(rows[0].earned);
+  }
+  /**
+   * The credit an x402 settlement channel funded, if one is bound to it — the
+   * binding is UNIQUE, so at most one row can answer (internal-review).
+   *
+   * The operator repair's entry point: a wedged settlement row carries the
+   * channel and an `effect_id`, and this is what turns them back into the
+   * credit id, the caller pubkey, and the drain id the effect encodes. Deriving
+   * the credit id by splitting `effect_id` instead would be wrong — credit ids
+   * carry their own colons (`imp:`, `fnd:` and the rail segment inside them).
+   */
+  async getCreditByX402Channel(channelId) {
+    const { rows } = await this.pool.query(
+      `SELECT * FROM credits WHERE x402_channel_id = $1`,
+      [channelId]
+    );
+    return rows[0] ? this.snapshotFromRow(rows[0], this.pool, Date.now()) : void 0;
+  }
+  /** Retire every active credit backed by a chain-proven lost Tempo channel. */
+  async terminalizeTempoCredits(evidence, tx) {
+    const channelId = evidence.channelId.toLowerCase();
+    const observedAt = evidence.observedAt ?? Date.now();
+    if (tx) return this.terminalizeTempoCreditsLocked(tx, evidence, channelId, observedAt);
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const losses = await this.terminalizeTempoCreditsLocked(
+        client,
+        evidence,
+        channelId,
+        observedAt
+      );
+      await client.query("COMMIT");
+      return losses;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  async terminalizeTempoCreditsLocked(q, evidence, channelId, observedAt) {
+    const { rows: credits } = await q.query(
+      `SELECT * FROM credits
+        WHERE tempo_channel_id = $1
+        ORDER BY credit_id
+        FOR UPDATE`,
+      [channelId]
+    );
+    for (const credit of credits) {
+      if (credit.status === "unbacked") continue;
+      if (credit.status !== "active") throw terminalCreditError(credit.credit_id, credit.status);
+      const { rows: consumed } = await q.query(
+        `SELECT COALESCE(SUM(amount_micro), 0)::text AS amount
+           FROM credit_draws
+          WHERE credit_id = $1 AND status = 'settled'`,
+        [credit.credit_id]
+      );
+      await q.query(
+        `INSERT INTO tempo_credit_losses
+           (credit_id, channel_id, caller_pubkey, currency, former_balance_micro,
+            settled_on_chain_native, highest_voucher_native, consumed_service_micro,
+            consumed_native, observed_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+         ON CONFLICT (credit_id) DO NOTHING`,
+        [
+          credit.credit_id,
+          channelId,
+          credit.caller_pubkey,
+          credit.currency,
+          credit.balance_micro,
+          evidence.settledOnChainNative.toString(),
+          evidence.highestVoucherNative.toString(),
+          consumed[0]?.amount ?? "0",
+          evidence.consumedNative.toString(),
+          observedAt
+        ]
+      );
+      await q.query(`UPDATE credits SET status = 'unbacked' WHERE credit_id = $1`, [
+        credit.credit_id
+      ]);
+    }
+    return this.readTempoCreditLosses(q, { channelId });
+  }
+  /** List terminal Tempo credit losses, newest observation first. */
+  async listTempoCreditLosses(args) {
+    return this.readTempoCreditLosses(this.pool, { limit: args?.limit ?? 50 });
+  }
+  /** Retire the active credit bound to a chain-proven empty x402 channel. */
+  async terminalizeX402Credit(evidence, tx) {
+    const channelId = evidence.channelId.toLowerCase();
+    const observedAt = evidence.observedAt ?? Date.now();
+    if (tx) return this.terminalizeX402CreditLocked(tx, evidence, channelId, observedAt);
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const losses = await this.terminalizeX402CreditLocked(
+        client,
+        evidence,
+        channelId,
+        observedAt
+      );
+      await client.query("COMMIT");
+      return losses;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  async terminalizeX402CreditLocked(q, evidence, channelId, observedAt) {
+    const { rows: credits } = await q.query(
+      `SELECT * FROM credits WHERE x402_channel_id = $1 FOR UPDATE`,
+      [channelId]
+    );
+    if (credits.length > 0 && credits[0].status !== "unbacked") {
+      const credit = credits[0];
+      if (credit.status !== "active") throw terminalCreditError(credit.credit_id, credit.status);
+      const { rows: consumed } = await q.query(
+        `SELECT COALESCE(SUM(amount_micro), 0)::text AS amount
+           FROM credit_draws
+          WHERE credit_id = $1 AND status = 'settled'`,
+        [credit.credit_id]
+      );
+      await q.query(
+        `INSERT INTO x402_credit_losses
+           (credit_id, channel_id, caller_pubkey, currency, former_balance_micro,
+            channel_balance_native, total_claimed_native, consumed_service_micro, observed_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         ON CONFLICT (credit_id) DO NOTHING`,
+        [
+          credit.credit_id,
+          channelId,
+          credit.caller_pubkey,
+          credit.currency,
+          credit.balance_micro,
+          evidence.channelBalanceNative.toString(),
+          evidence.totalClaimedNative.toString(),
+          consumed[0]?.amount ?? "0",
+          observedAt
+        ]
+      );
+      await q.query(`UPDATE credits SET status = 'unbacked' WHERE credit_id = $1`, [
+        credit.credit_id
+      ]);
+    }
+    return this.readX402CreditLosses(q, { channelId });
+  }
+  /** List terminal x402 credit losses, newest observation first. */
+  async listX402CreditLosses(args) {
+    return this.readX402CreditLosses(this.pool, { limit: args?.limit ?? 50 });
+  }
+  // ── Drains (internal-review) ─────────────────────────────────────────────────
+  /**
+   * Debit the caller's entire available balance into a drain liability
+   * (spec §5: expiry ends spending, never ownership — this is the
+   * builder-honored reclaim floor). Runs under the credit row lock: the
+   * amount is `balance − pending holds` read under `FOR UPDATE`, the balance
+   * is decremented in the same transaction, and the drain takes the next
+   * gap-free `ledger_seq` — so the balance zeroes exactly once however many
+   * machines race the request.
+   *
+   * Idempotent on `(creditId, drainId)`: a replay returns the recorded drain
+   * (this is also the poll/pickup read). A replay whose `method` or `payout`
+   * differs from the recorded drain is refused with `drain_conflict` —
+   * silently honouring a changed payout would ship the caller's money to a
+   * destination they never signed alongside this `drain_id`.
+   *
+   * Pending holds are NOT drained — in-flight jobs keep their money until
+   * they settle or release. A release after a drain restores available
+   * balance the caller reclaims with a **new** `drain_id`; drains are ledger
+   * arithmetic, not a terminal credit state, so `status` stays `active`.
+   *
+   * Deliberately **no expiry check**: draining works before and after
+   * expiry. The one thing expiry gates is new draws.
+   */
+  async requestDrain(args) {
+    const nowMs = args.nowMs ?? Date.now();
+    const run = async (client, credit) => {
+      if (credit.caller_pubkey !== args.callerPubkey) {
+        throw new CreditLedgerError(
+          "caller_mismatch",
+          `credit ${args.creditId} belongs to a different caller pubkey`
+        );
+      }
+      const existing = await this.readDrain(client, args.creditId, args.drainId);
+      if (existing) {
+        if (existing.method !== args.method || JSON.stringify(existing.payout) !== JSON.stringify(args.payout)) {
+          throw new CreditLedgerError(
+            "drain_conflict",
+            `drain ${args.drainId} on credit ${args.creditId} was recorded with a different method or payout`
+          );
+        }
+        return {
+          drain: drainRecordFromRow(existing, credit),
+          credit: await this.snapshotFromRow(credit, client, nowMs),
+          replayed: true
+        };
+      }
+      if (credit.status !== "active") throw terminalCreditError(args.creditId, credit.status);
+      const blocking = await this.blockingX402Refund(
+        credit.x402_channel_id,
+        X402_WEDGED_SETTLEMENT_STATUSES
+      );
+      if (blocking && blocking.effectId !== `${args.creditId}:${args.drainId}`) {
+        throw x402SettlementPending(args.creditId, blocking);
+      }
+      const balanceMicro = toSafeInt(credit.balance_micro);
+      const pending = await this.pendingSums(client, args.creditId);
+      const availableMicro = balanceMicro - pending.micro;
+      if (args.requireNoPending && pending.micro > 0) {
+        throw new CreditLedgerError(
+          "drain_conflict",
+          `credit ${args.creditId} has pending draws that must finish before it can drain`,
+          { drainConflict: "pending_draws" }
+        );
+      }
+      if (availableMicro <= 0) {
+        throw new CreditLedgerError(
+          "nothing_to_drain",
+          `credit ${args.creditId} has no available balance to drain`,
+          { availableMicro, balanceMicro }
+        );
+      }
+      const inKind = isNonChannelBitcoinRail(credit.rail) ? await this.reclaimInKind(client, args.creditId, availableMicro) : void 0;
+      if (inKind?.owedSats === 0) {
+        throw new CreditLedgerError(
+          "drain_below_dust",
+          `credit ${args.creditId} holds ${availableMicro} micro, worth ${inKind.grossSats ?? 0} sats at the rate it was funded \u2014 no more than the ${DRAIN_DELIVERY_RESERVE_SATS} sats it costs to hand back`,
+          { availableMicro, balanceMicro }
+        );
+      }
+      const ledgerSeq = toSafeInt(credit.last_ledger_seq) + 1;
+      const balanceAfter = balanceMicro - availableMicro;
+      const drainedMsats = Math.max(0, toSafeInt(credit.msats_remaining) - pending.msats);
+      const drainedNative = credit.native_remaining === null ? null : Math.max(0, toSafeInt(credit.native_remaining) - pending.native);
+      await client.query(
+        `UPDATE credits
+           SET balance_micro    = $2,
+               last_ledger_seq  = $3,
+               msats_remaining  = LEAST(msats_remaining, $4),
+               native_remaining = CASE WHEN native_remaining IS NULL THEN NULL
+                                       ELSE LEAST(native_remaining, $5) END
+         WHERE credit_id = $1`,
+        [args.creditId, balanceAfter, ledgerSeq, pending.msats, pending.native]
+      );
+      const { rows } = await client.query(
+        `INSERT INTO credit_drains
+           (credit_id, drain_id, method, payout, amount_micro, balance_after_micro,
+            drained_msats, drained_native, owed_sats, lot_debits, ledger_seq, status, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'pending', $12)
+         RETURNING *`,
+        [
+          args.creditId,
+          args.drainId,
+          args.method,
+          JSON.stringify(args.payout),
+          availableMicro,
+          balanceAfter,
+          drainedMsats,
+          drainedNative,
+          inKind?.owedSats ?? null,
+          inKind ? JSON.stringify(inKind.debits) : null,
+          ledgerSeq,
+          nowMs
+        ]
+      );
+      if (inKind) await this.applyLotDebits(client, inKind.debits, -1);
+      const updated = {
+        ...credit,
+        balance_micro: String(balanceAfter),
+        last_ledger_seq: String(ledgerSeq)
+      };
+      return {
+        drain: drainRecordFromRow(rows[0], credit),
+        credit: await this.snapshotFromRow(updated, client, nowMs),
+        replayed: false
+      };
+    };
+    if (args.tx) {
+      return run(args.tx, await this.lockCreditRow(args.tx, args.creditId));
+    }
+    return this.withCreditLock(args.creditId, run);
+  }
+  /** Read one drain (no lock), joined with its credit for currency + owner. */
+  async getDrain(args) {
+    const { rows } = await this.pool.query(
+      `SELECT d.*, ${DRAIN_CREDIT_COLUMNS} FROM credit_drains d
+       JOIN credits c ON c.credit_id = d.credit_id
+       WHERE d.credit_id = $1 AND d.drain_id = $2`,
+      [args.creditId, args.drainId]
+    );
+    return rows.length > 0 ? drainRecordFromJoinRow(rows[0]) : void 0;
+  }
+  /**
+   * One credit's undepleted funding lots, oldest first (internal-review) — the
+   * public read behind the reclaim's own arithmetic, for anything that needs
+   * to show its work.
+   */
+  async listFundingLots(creditId) {
+    return this.openLots(this.pool, creditId);
+  }
+  /**
+   * What this DVM owes back in satoshis if every open non-channel Bitcoin
+   * credit reclaimed right now (internal-review) — the deposit half of the hub
+   * balance, and the floor a payout sweep must never go below.
+   *
+   * Read entirely off the funding lots, at their own funding rates, with no
+   * exchange-rate lookup anywhere: the obligation is in kind, so a rate has
+   * nothing to say about it. Pending job holds are deliberately **not**
+   * subtracted — a hold either settles into revenue or releases back to the
+   * caller, and until it does, treating it as already earned would understate
+   * the floor. The figure is conservative by exactly that amount.
+   *
+   * The two coverage holes ride along rather than being folded in silently, so
+   * a gap reads as a gap: `uncovered` is a credit whose lots fall short of its
+   * balance, `unbacked` is one holding any open micro with no sats basis. A
+   * reclaim on either prices the **whole** balance off a live rate — the
+   * depletion refuses a mixture rather than blending two bases — so both are
+   * reported as the whole balance, and neither contributes to `depositSats`.
+   * A figure that counted the backed half of a mixed credit would be a floor
+   * the payout never matches.
+   */
+  async bitcoinDepositLiability() {
+    const { rows } = await this.pool.query(
+      `SELECT c.rail, c.currency,
+              COUNT(*) AS credits,
+              COALESCE(SUM(cov.owed_sats) FILTER (WHERE ${IN_KIND_PREDICATE}), 0) AS owed_sats,
+              COALESCE(SUM(c.balance_micro), 0) AS balance_micro,
+              COUNT(*) FILTER (WHERE cov.covered_micro < c.balance_micro) AS uncovered_credits,
+              COALESCE(SUM(c.balance_micro) FILTER (WHERE cov.covered_micro < c.balance_micro), 0)
+                AS uncovered_micro,
+              COUNT(*) FILTER (WHERE cov.covered_micro >= c.balance_micro AND cov.basisless_micro > 0)
+                AS unbacked_credits,
+              COALESCE(SUM(c.balance_micro)
+                FILTER (WHERE cov.covered_micro >= c.balance_micro AND cov.basisless_micro > 0), 0)
+                AS unbacked_micro
+         FROM credits c
+         CROSS JOIN LATERAL (${LOT_COVERAGE_LATERAL}) cov
+        WHERE ${BITCOIN_CREDIT_PREDICATE}
+        GROUP BY c.rail, c.currency
+        ORDER BY c.rail, c.currency`
+    );
+    const liability = {
+      depositSats: 0,
+      credits: 0,
+      byRail: [],
+      byCurrency: [],
+      uncoveredCredits: 0,
+      uncoveredMicro: 0,
+      unbackedCredits: 0,
+      unbackedMicro: 0
+    };
+    const byRail = /* @__PURE__ */ new Map();
+    const byCurrency = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const sats = toSafeInt(row.owed_sats);
+      const credits = toSafeInt(row.credits);
+      liability.depositSats += sats;
+      liability.credits += credits;
+      liability.uncoveredCredits += toSafeInt(row.uncovered_credits);
+      liability.uncoveredMicro += toSafeInt(row.uncovered_micro);
+      liability.unbackedCredits += toSafeInt(row.unbacked_credits);
+      liability.unbackedMicro += toSafeInt(row.unbacked_micro);
+      const rail = byRail.get(row.rail) ?? { rail: row.rail, sats: 0, credits: 0 };
+      rail.sats += sats;
+      rail.credits += credits;
+      byRail.set(row.rail, rail);
+      const currency = byCurrency.get(row.currency) ?? {
+        currency: row.currency,
+        micro: 0,
+        credits: 0
+      };
+      currency.micro += toSafeInt(row.balance_micro);
+      currency.credits += credits;
+      byCurrency.set(row.currency, currency);
+    }
+    liability.byRail = [...byRail.values()];
+    liability.byCurrency = [...byCurrency.values()];
+    return liability;
+  }
+  /**
+   * Every unfulfilled drain, oldest first (no lock) — the builder batch
+   * job's work list and the outstanding-refund-liability read the
+   * scoped-budget assertion sums over. `pending` means un-parked (Cashu) or
+   * un-sent (Lightning/x402/mpp); `parked` value is already committed to a
+   * caller-locked token, so it is out of the liability the LN send budget
+   * must cover.
+   */
+  async listPendingDrains() {
+    const { rows } = await this.pool.query(
+      `SELECT d.*, ${DRAIN_CREDIT_COLUMNS} FROM credit_drains d
+       JOIN credits c ON c.credit_id = d.credit_id
+       WHERE d.status = 'pending' ORDER BY d.created_at, d.credit_id, d.drain_id`
+    );
+    return rows.map(drainRecordFromJoinRow);
+  }
+  /**
+   * One page of still-`pending` drains on a channel-backed credit, oldest
+   * first (no lock) — the operator's repair queue (internal-review).
+   *
+   * Keyset-paginated for the x402 settlement queue's reason: a wedged row
+   * never self-clears, so a caller that re-issues the same first page would
+   * never see past a `limit`-sized wall of them. The keyset is
+   * `(created_at, credit_id, drain_id)` — `created_at` is immutable, so no
+   * concurrent write can push an unexamined row past the cursor. It is a
+   * BIGINT of epoch milliseconds rather than a `TIMESTAMPTZ`, so the
+   * microsecond-vs-millisecond cursor trap that bit `listSettlements` cannot
+   * arise here: the value round-trips as the integer it already is.
+   *
+   * `createdBeforeMs` is the staleness floor. A healthy cooperative close
+   * moves the drain to `sent` inside the request that opened it, so anything
+   * younger is in flight rather than stuck.
+   *
+   * The method filter is `'tempo'`, and it is the one line here worth a second
+   * look: `init()` migrates the pre-internal-review `'mpp'` spelling away and
+   * `DrainMethod` no longer carries it, so a query naming it matches nothing a
+   * DVM has ever written. It named it anyway until internal-review's rename sweep and
+   * internal-review's live rung caught it independently — the whole operator queue
+   * read empty in production while every route test stayed green, because
+   * those run on `MemoryCreditLedger`, which filters on the typed value. The
+   * two implementations of this one predicate must be read together.
+   *
+   * A written-off row is excluded unless `includeResolved`: the operator has
+   * already decided about it, and leaving it on the live queue would re-serve
+   * a closed decision on every walk.
+   */
+  async listChannelDrains(args) {
+    const params = [args.createdBeforeMs, args.limit];
+    let keyset = "";
+    if (args.after) {
+      params.push(args.after.createdAt, args.after.creditId, args.after.drainId);
+      keyset = ` AND (d.created_at, d.credit_id, d.drain_id) > ($3, $4, $5)`;
+    }
+    const { rows } = await this.pool.query(
+      `SELECT d.*, ${DRAIN_CREDIT_COLUMNS} FROM credit_drains d
+       JOIN credits c ON c.credit_id = d.credit_id
+       WHERE d.status = 'pending'
+         AND d.method = 'tempo'
+         AND c.tempo_channel_id IS NOT NULL
+         AND d.created_at <= $1
+         ${args.includeResolved ? "" : "AND d.written_off_at IS NULL"}
+         ${keyset}
+       ORDER BY d.created_at, d.credit_id, d.drain_id
+       LIMIT $2`,
+      params
+    );
+    return rows.map(drainRecordFromJoinRow);
+  }
+  /**
+   * Record that an operator reviewed a floor-refused channel drain and is not
+   * booking it (internal-review). Books nothing anywhere — no status change, no
+   * balance movement, no platform report.
+   *
+   * A single-statement CAS on `written_off_at IS NULL`, so the first note on
+   * file wins: a second operator asking for the same decision finds one
+   * already recorded and is told so (`written: false`) rather than writing
+   * over a colleague's reason. Only a `pending` drain may be written off — a
+   * terminal one has an answer already.
+   */
+  async writeOffDrain(args) {
+    const { rowCount } = await this.pool.query(
+      `UPDATE credit_drains SET write_off_note = $3, written_off_at = $4
+        WHERE credit_id = $1 AND drain_id = $2
+          AND status = 'pending' AND written_off_at IS NULL`,
+      [args.creditId, args.drainId, args.note ?? null, args.nowMs ?? Date.now()]
+    );
+    const drain = await this.getDrain({ creditId: args.creditId, drainId: args.drainId });
+    if (!drain) return void 0;
+    return { drain, written: (rowCount ?? 0) > 0 };
+  }
+  /**
+   * Drop a recorded write-off, inside the transaction that books the drain.
+   *
+   * This is the reversibility half, and its placement is the whole guarantee:
+   * a reconcile clears the note in the same transaction as the `pending →
+   * sent` CAS, so a ledger leg that rolls back leaves the operator's decision
+   * exactly as it found it. The x402 repair needs an explicit compensating
+   * restore for this because its settlement row lives outside the ledger's
+   * transaction; here the two are one row.
+   */
+  async clearDrainWriteOff(args) {
+    const q = args.tx ?? this.pool;
+    await q.query(
+      `UPDATE credit_drains SET write_off_note = NULL, written_off_at = NULL
+        WHERE credit_id = $1 AND drain_id = $2`,
+      [args.creditId, args.drainId]
+    );
+  }
+  /**
+   * Cancel an unfulfilled Tempo cooperative drain and restore the exact
+   * balance plus rail basis it removed (`pending -> released`). This is only
+   * for a close the channel reconciliation proved cannot pay; ordinary payout
+   * rails never re-credit a liability after it has been handed to a worker.
+   */
+  async releaseDrain(args) {
+    const nowMs = args.nowMs ?? Date.now();
+    const run = async (client, credit) => {
+      const row = await this.readDrain(client, args.creditId, args.drainId);
+      if (!row) {
+        throw new CreditLedgerError(
+          "drain_not_found",
+          `drain ${args.drainId} on credit ${args.creditId} not found`
+        );
+      }
+      if (row.status === "released") {
+        return {
+          drain: drainRecordFromRow(row, credit),
+          credit: await this.snapshotFromRow(credit, client, nowMs),
+          replayed: true
+        };
+      }
+      if (row.status !== "pending") {
+        throw new CreditLedgerError(
+          "invalid_drain_state",
+          `cannot release ${row.method} drain ${args.drainId} from status ${row.status}`
+        );
+      }
+      const { rows } = await client.query(
+        `UPDATE credit_drains SET status = 'released', released_at = $3
+         WHERE credit_id = $1 AND drain_id = $2 AND status = 'pending'
+         RETURNING *`,
+        [args.creditId, args.drainId, nowMs]
+      );
+      if (!rows[0]) {
+        throw new CreditLedgerError(
+          "invalid_drain_state",
+          `drain ${args.drainId} changed while it was being released`
+        );
+      }
+      await client.query(
+        `UPDATE credits
+           SET balance_micro = balance_micro + $2,
+               msats_remaining = msats_remaining + $3,
+               native_remaining = CASE
+                 WHEN native_remaining IS NULL OR $4::BIGINT IS NULL THEN native_remaining
+                 ELSE native_remaining + $4
+               END
+         WHERE credit_id = $1`,
+        [args.creditId, row.amount_micro, row.drained_msats, row.drained_native]
+      );
+      await this.applyLotDebits(client, row.lot_debits ?? [], 1);
+      const restored = await this.lockCreditRow(client, args.creditId);
+      return {
+        drain: drainRecordFromRow(rows[0], restored),
+        credit: await this.snapshotFromRow(restored, client, nowMs),
+        replayed: false
+      };
+    };
+    if (args.tx) return run(args.tx, await this.lockCreditRow(args.tx, args.creditId));
+    return this.withCreditLock(args.creditId, run);
+  }
+  /**
+   * Attach the parked Cashu token to a pending drain (`pending → parked`).
+   * A single-statement CAS on `status = 'pending'` — no credit lock needed;
+   * the money already left the balance at request time. Idempotent: parking
+   * an already-parked/picked-up drain with the same token returns the
+   * recorded row (the builder's park retry after a lost response); a
+   * different token refuses with `drain_conflict` rather than silently
+   * replacing notes the caller may already hold.
+   *
+   * Pass `tx` to commit the park atomically with the accumulator row swap
+   * the admin route performs alongside it.
+   */
+  async parkDrain(args) {
+    const q = args.tx ?? this.pool;
+    const nowMs = args.nowMs ?? Date.now();
+    const { rows } = await q.query(
+      `UPDATE credit_drains
+          SET status = 'parked', token = $3, parked_at = $4,
+              fulfilment = COALESCE($5::jsonb, fulfilment)
+       WHERE credit_id = $1 AND drain_id = $2 AND status = 'pending' AND method = 'cashu'
+       RETURNING *`,
+      [
+        args.creditId,
+        args.drainId,
+        args.token,
+        nowMs,
+        args.fulfilment ? JSON.stringify(args.fulfilment) : null
+      ]
+    );
+    if (rows.length > 0) return this.rejoin(q, rows[0]);
+    const refusal = await this.refuseTransition(q, args.creditId, args.drainId, {
+      idempotentWhen: (row) => (row.status === "parked" || row.status === "picked_up") && row.token === args.token,
+      verb: "park"
+    });
+    return refusal.drain;
+  }
+  /**
+   * Record that the caller collected the parked token (`parked →
+   * picked_up`). Idempotent on `picked_up` — pickup must survive response
+   * loss, so the caller's re-poll keeps returning the same token either way.
+   *
+   * Returns `replayed` because this is a **terminal** transition and the money
+   * has left at exactly one of these calls (internal-review): the platform drain
+   * report must be emitted by that caller and no other. Pass `tx` to write the
+   * report through the same transaction as the CAS.
+   */
+  async markDrainPickedUp(args) {
+    const q = args.tx ?? this.pool;
+    const nowMs = args.nowMs ?? Date.now();
+    const { rows } = await q.query(
+      `UPDATE credit_drains SET status = 'picked_up', picked_up_at = $3
+       WHERE credit_id = $1 AND drain_id = $2 AND status = 'parked'
+       RETURNING *`,
+      [args.creditId, args.drainId, nowMs]
+    );
+    if (rows.length > 0) return { drain: await this.rejoin(q, rows[0]), replayed: false };
+    return this.refuseTransition(q, args.creditId, args.drainId, {
+      idempotentWhen: (row) => row.status === "picked_up",
+      verb: "mark picked up"
+    });
+  }
+  /**
+   * Record a completed send-back (`pending → sent`) for the non-parked
+   * methods — the builder's batch job paid the Lightning invoice or shipped
+   * the on-chain transfer and posts the settlement reference. Idempotent on
+   * `sent` (the recorded `sent_ref` wins; a retry after a lost response
+   * carries the same reference or none at all).
+   *
+   * `replayed` and `tx` carry the same meaning as on {@link markDrainPickedUp},
+   * and matter more here: the builder's batch job re-POSTs `mark-drain-sent`
+   * on every recovery pass, so the replay is the routine case rather than the
+   * exception.
+   */
+  async markDrainSent(args) {
+    const q = args.tx ?? this.pool;
+    const nowMs = args.nowMs ?? Date.now();
+    const { rows } = await q.query(
+      `UPDATE credit_drains SET status = 'sent', sent_ref = $3, sent_at = $4
+       WHERE credit_id = $1 AND drain_id = $2 AND status = 'pending' AND method <> 'cashu'
+       RETURNING *`,
+      [args.creditId, args.drainId, JSON.stringify(args.sentRef), nowMs]
+    );
+    if (rows.length > 0) return { drain: await this.rejoin(q, rows[0]), replayed: false };
+    return this.refuseTransition(q, args.creditId, args.drainId, {
+      idempotentWhen: (row) => row.status === "sent",
+      verb: "mark sent"
+    });
+  }
+  /**
+   * Append a countersigned reclaim-event receipt to the drain's evidence
+   * trail. A single-statement JSONB append — receipts are emitted after the
+   * state transition they attest, and losing one never loses money (the
+   * transition is the source of truth; the receipt is the proof the caller
+   * can carry away).
+   */
+  async appendDrainReceipt(args) {
+    const q = args.tx ?? this.pool;
+    await q.query(
+      `UPDATE credit_drains SET receipts = receipts || $3::jsonb
+       WHERE credit_id = $1 AND drain_id = $2`,
+      [args.creditId, args.drainId, JSON.stringify([args.receipt])]
+    );
+  }
+  // ── Internals ─────────────────────────────────────────────────────────
+  async readDrain(q, creditId, drainId) {
+    const { rows } = await q.query(
+      `SELECT * FROM credit_drains WHERE credit_id = $1 AND drain_id = $2`,
+      [creditId, drainId]
+    );
+    return rows[0];
+  }
+  /** Re-read the credit join fields for a freshly-updated drain row. */
+  async rejoin(q, row) {
+    const { rows } = await q.query(
+      `SELECT currency, caller_pubkey, tempo_channel_id, x402_channel_id
+         FROM credits WHERE credit_id = $1`,
+      [row.credit_id]
+    );
+    return drainRecordFromRow(row, rows[0]);
+  }
+  /** Shared refusal tail for the CAS transitions: idempotent replay or typed error. */
+  async refuseTransition(q, creditId, drainId, opts) {
+    const row = await this.readDrain(q, creditId, drainId);
+    if (!row) {
+      throw new CreditLedgerError(
+        "drain_not_found",
+        `drain ${drainId} not found on credit ${creditId}`
+      );
+    }
+    if (opts.idempotentWhen(row)) return { drain: await this.rejoin(q, row), replayed: true };
+    throw new CreditLedgerError(
+      row.status === "parked" || row.status === "picked_up" || row.status === "sent" ? "drain_conflict" : "invalid_drain_state",
+      `cannot ${opts.verb} drain ${drainId}: status is ${row.status} (method ${row.method})`
+    );
+  }
+  /**
+   * Price a reclaim in kind and say which lots it takes (internal-review).
+   *
+   * The debits are returned whether or not the reclaim can be priced, and the
+   * caller applies them either way: the money is leaving the credit, so the
+   * lots have to shrink with it or the deposit-liability rollup would keep
+   * counting a balance that is gone.
+   *
+   * `owedSats` is `null` where {@link isInKindDepletion} refuses — the lots
+   * are short of the balance, or the covering lots carry no sats basis (a
+   * credit funded before internal-review). That row is priced off a live rate by the
+   * admin surface instead, which is what *every* row did before this change,
+   * so the fallback is the old behaviour rather than a new failure mode.
+   *
+   * What it publishes is **net of the delivery reserve** (internal-review): handing a
+   * refund over costs a mint fee and, when the notes have to be minted just in
+   * time, a Lightning hop. The caller carries that cost per internal-review, and a
+   * flat reserve is how they carry it without the figure moving — an
+   * actual-fee true-up could only be applied after the promise was made. The
+   * debits stay gross because they are denominated in micro and are what
+   * `releaseDrain` restores; only the sats figure is netted.
+   */
+  async reclaimInKind(q, creditId, amountMicro) {
+    const depletion = depleteLots(await this.openLots(q, creditId), amountMicro);
+    const inKind = isInKindDepletion(depletion, amountMicro);
+    return {
+      owedSats: inKind ? netOwedSats(depletion.satsOwed) : null,
+      grossSats: inKind ? depletion.satsOwed : null,
+      debits: depletion.debits
+    };
+  }
+  /**
+   * This credit's undepleted funding lots, oldest first (internal-review).
+   *
+   * Ordered in SQL on the same `(created_at, lot_id)` key the partial index
+   * carries, so FIFO is the index's own order rather than something a reader
+   * re-establishes. Depleted lots stay on the table as the deposit's audit
+   * trail and are excluded here — they price nothing.
+   */
+  async openLots(q, creditId) {
+    const { rows } = await q.query(
+      `SELECT * FROM credit_funding_lots
+        WHERE credit_id = $1 AND remaining_micro > 0
+        ORDER BY created_at, lot_id`,
+      [creditId]
+    );
+    return rows.map(fundingLotFromRow);
+  }
+  /**
+   * Move `debits` out of (`sign: -1`) or back into (`sign: 1`) their lots.
+   *
+   * Always runs under the credit row lock the caller already holds, on that
+   * caller's handle, so the read-then-write is serialized per credit exactly
+   * as every other balance move is.
+   */
+  async applyLotDebits(q, debits, sign) {
+    for (const debit of debits) {
+      await q.query(
+        `UPDATE credit_funding_lots
+            SET remaining_micro = GREATEST(LEAST(remaining_micro + $2, credited_micro), 0)
+          WHERE lot_id = $1`,
+        [debit.lotId, sign * debit.micro]
+      );
+    }
+  }
+  /** Shared settle/release state machine — see the public JSDoc on each verb. */
+  async resolveDraw(args) {
+    if (args.tx) {
+      const credit = await this.lockCreditRow(args.tx, args.creditId);
+      return this.resolveDrawLocked(args.tx, credit, args);
+    }
+    return this.withCreditLock(
+      args.creditId,
+      (client, credit) => this.resolveDrawLocked(client, credit, args)
+    );
+  }
+  async resolveDrawLocked(client, credit, args) {
+    const nowMs = args.nowMs ?? Date.now();
+    const draw = await this.readDraw(client, args.creditId, args.drawId);
+    if (!draw) {
+      throw new CreditLedgerError(
+        "draw_not_found",
+        `draw ${args.drawId} not found on credit ${args.creditId}`
+      );
+    }
+    let balanceMicro = toSafeInt(credit.balance_micro);
+    let replayed = false;
+    if (draw.status === args.to) {
+      replayed = true;
+    } else if (draw.status !== "pending") {
+      throw new CreditLedgerError(
+        "invalid_draw_state",
+        `cannot ${args.to === "settled" ? "settle" : "release"} draw ${args.drawId}: status is ${draw.status}`,
+        { currentStatus: draw.status }
+      );
+    } else {
+      await client.query(
+        `UPDATE credit_draws SET status = $3, resolved_at = $4
+           WHERE credit_id = $1 AND draw_id = $2`,
+        [args.creditId, args.drawId, args.to, nowMs]
+      );
+      if (args.to === "settled") {
+        const amountMicro = toSafeInt(draw.amount_micro);
+        balanceMicro -= amountMicro;
+        const forecastMsats = toSafeInt(draw.draw_msats);
+        let settledMsats = forecastMsats;
+        if (isNonChannelBitcoinRail(credit.rail)) {
+          const depletion = depleteLots(await this.openLots(client, args.creditId), amountMicro);
+          settledMsats = inKindDrawMsats(depletion, amountMicro) ?? forecastMsats;
+          await this.applyLotDebits(client, depletion.debits, -1);
+        }
+        if (settledMsats !== forecastMsats) {
+          await client.query(
+            `UPDATE credit_draws SET draw_msats = $3, allocated_msats = $4
+               WHERE credit_id = $1 AND draw_id = $2`,
+            [args.creditId, args.drawId, settledMsats, forecastMsats]
+          );
+          draw.draw_msats = String(settledMsats);
+          draw.allocated_msats = String(forecastMsats);
+        }
+        await client.query(
+          `UPDATE credits
+               SET balance_micro    = $2,
+                   msats_remaining  = GREATEST(msats_remaining - $3, 0),
+                   native_remaining = CASE WHEN native_remaining IS NULL THEN NULL
+                                           ELSE GREATEST(native_remaining - $4, 0) END
+             WHERE credit_id = $1`,
+          [args.creditId, balanceMicro, settledMsats, Number(draw.draw_native ?? 0)]
+        );
+      }
+    }
+    const availableMicro = credit.status === "unbacked" ? 0 : balanceMicro - (await this.pendingSums(client, args.creditId)).micro;
+    const resolution = {
+      ...drawResultFromRow(draw, credit),
+      status: args.to,
+      replayed,
+      availableMicro,
+      resolvedAt: draw.status === "pending" ? nowMs : Number(draw.resolved_at ?? nowMs)
+    };
+    if (!replayed && args.to === "released" && resolution.amountMicro > 0 && args.releaseOutbox) {
+      await args.releaseOutbox.enqueue(client, {
+        dvmId: args.releaseOutbox.dvmId,
+        creditId: resolution.creditId,
+        drawId: resolution.drawId,
+        amountMicro: resolution.amountMicro,
+        creditCurrency: credit.currency,
+        ledgerSeq: resolution.ledgerSeq,
+        releasedAt: resolution.resolvedAt
+      });
+    }
+    return resolution;
+  }
+  /**
+   * Run `fn` inside a transaction holding `SELECT … FOR UPDATE` on the credit
+   * row — the lock every `credit_draws` write must be under. Commits on
+   * success (harmless for read-only replay paths), rolls back on throw.
+   */
+  async withCreditLock(creditId, fn) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const credit = await this.lockCreditRow(client, creditId);
+      const result = await fn(client, credit);
+      await client.query("COMMIT");
+      return result;
+    } catch (err) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+  /** `SELECT … FOR UPDATE` the credit row on `q` (which must be inside a transaction). */
+  async lockCreditRow(q, creditId) {
+    const { rows } = await q.query(
+      `SELECT * FROM credits WHERE credit_id = $1 FOR UPDATE`,
+      [creditId]
+    );
+    if (rows.length === 0) {
+      throw new CreditLedgerError("credit_not_found", `credit ${creditId} not found`);
+    }
+    return rows[0];
+  }
+  async readDraw(q, creditId, drawId) {
+    const { rows } = await q.query(
+      `SELECT * FROM credit_draws WHERE credit_id = $1 AND draw_id = $2`,
+      [creditId, drawId]
+    );
+    return rows[0];
+  }
+  /**
+   * Held-but-unresolved totals for a credit, in all three units at once — the
+   * fiat micro that defines available balance plus the rail-value remainders
+   * a new draw allocates against (internal-review). One round-trip, since every
+   * caller needs the micro sum anyway.
+   */
+  async pendingSums(q, creditId) {
+    const { rows } = await q.query(
+      `SELECT COALESCE(SUM(amount_micro), 0) AS micro,
+              COALESCE(SUM(draw_msats), 0)   AS msats,
+              COALESCE(SUM(draw_native), 0)  AS native
+       FROM credit_draws WHERE credit_id = $1 AND status = 'pending'`,
+      [creditId]
+    );
+    return {
+      micro: toSafeInt(rows[0].micro),
+      msats: toSafeInt(rows[0].msats),
+      native: toSafeInt(rows[0].native)
+    };
+  }
+  async snapshotFromRow(row, q, nowMs) {
+    const balanceMicro = toSafeInt(row.balance_micro);
+    const expiryMs = toSafeInt(row.expiry_ms);
+    const pending = await this.pendingSums(q, row.credit_id);
+    const live = row.status === "active";
+    return {
+      creditId: row.credit_id,
+      callerPubkey: row.caller_pubkey,
+      currency: row.currency,
+      balanceMicro,
+      availableMicro: live ? balanceMicro - pending.micro : 0,
+      nativeAvailable: row.native_remaining === null ? null : live ? Math.max(0, toSafeInt(row.native_remaining) - pending.native) : 0,
+      expiryMs,
+      expired: expiryMs <= nowMs,
+      status: row.status === "unbacked" ? "unbacked" : "active",
+      lastLedgerSeq: toSafeInt(row.last_ledger_seq),
+      createdAt: toSafeInt(row.created_at),
+      rail: row.rail,
+      tempoChannelId: row.tempo_channel_id ?? null,
+      x402ChannelId: row.x402_channel_id
+    };
+  }
+  async readTempoCreditLosses(q, args) {
+    const { rows } = await q.query(
+      `SELECT * FROM tempo_credit_losses
+        WHERE ($1::text IS NULL OR channel_id = $1)
+        ORDER BY observed_at DESC, credit_id
+        LIMIT $2`,
+      [args.channelId ?? null, args.limit ?? 1e3]
+    );
+    return rows.map(tempoCreditLossFromRow);
+  }
+  async readX402CreditLosses(q, args) {
+    const { rows } = await q.query(
+      `SELECT * FROM x402_credit_losses
+        WHERE ($1::text IS NULL OR channel_id = $1)
+        ORDER BY observed_at DESC, credit_id
+        LIMIT $2`,
+      [args.channelId ?? null, args.limit ?? 1e3]
+    );
+    return rows.map(x402CreditLossFromRow);
+  }
+};
+var DRAIN_METHODS = ["cashu", "x402", "tempo"];
+function isDrainMethod(value) {
+  return DRAIN_METHODS.includes(value);
+}
+var FUNDING_RAILS = {
+  cashu: true,
+  x402: true,
+  tempo: true,
+  lightning: true
+};
+function isFundingRail(rail) {
+  return typeof rail === "string" && Object.hasOwn(FUNDING_RAILS, rail);
+}
+function assertFundingBasis(basis) {
+  if (!basis) {
+    throw new CreditLedgerError("invalid_basis", "basis is required (internal-review)");
+  }
+  if (!isFundingRail(basis.rail)) {
+    throw new CreditLedgerError(
+      "invalid_basis",
+      `basis.rail must be one of ${Object.keys(FUNDING_RAILS).join(", ")} (got ${String(basis.rail)})`
+    );
+  }
+  if (!Number.isSafeInteger(basis.paidMsats) || basis.paidMsats < 0) {
+    throw new CreditLedgerError(
+      "invalid_basis",
+      `basis.paidMsats must be a non-negative safe integer (got ${String(basis.paidMsats)})`
+    );
+  }
+  return basis;
+}
+function allocateDrawValue(args) {
+  const share = (remaining) => {
+    if (args.availableMicro <= 0 || args.amountMicro <= 0 || remaining <= 0) return 0;
+    return Math.min(remaining, Math.round(remaining * args.amountMicro / args.availableMicro));
+  };
+  return {
+    drawMsats: share(args.availableMsats),
+    drawNative: args.availableNative === null ? null : share(args.availableNative)
+  };
+}
+function growthRailValue(args) {
+  const { earmark } = args;
+  if (!earmark) return allocateDrawValue(args);
+  return {
+    drawMsats: Math.min(Math.max(0, earmark.drawMsats), args.availableMsats),
+    drawNative: args.availableNative === null ? null : Math.min(Math.max(0, earmark.drawNative ?? 0), args.availableNative)
+  };
+}
+function clipEarmark(earmark, grantMicro, addAmountMicro) {
+  if (!earmark || grantMicro >= addAmountMicro || addAmountMicro <= 0) return earmark;
+  const scale = (value) => Math.min(value, Math.ceil(value * grantMicro / addAmountMicro));
+  return {
+    drawMsats: scale(earmark.drawMsats),
+    drawNative: earmark.drawNative === null ? null : scale(earmark.drawNative)
+  };
+}
+var CreditLedgerError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}, opts) {
+    super(message, opts);
+    this.name = "CreditLedgerError";
+    this.code = code;
+    this.details = details;
+  }
+};
+function x402SettlementPending(creditId, refund) {
+  const drainId = X402_WEDGED_SETTLEMENT_STATUSES.includes(refund.status) && refund.effectId.startsWith(`${creditId}:`) ? refund.effectId.slice(creditId.length + 1) : "";
+  return new CreditLedgerError(
+    "settlement_pending",
+    `credit ${creditId} is bound to an x402 channel whose refund ${refund.settlementId} is ${refund.status}`,
+    {
+      settlementId: refund.settlementId,
+      settlementStatus: refund.status,
+      ...drainId ? { blockingDrainId: drainId } : {}
+    }
+  );
+}
+function terminalCreditError(creditId, status) {
+  return new CreditLedgerError(
+    "credit_unbacked",
+    `credit ${creditId} is terminal (${status}); its Tempo backing finalized before the DVM was protected`
+  );
+}
+function isUniqueViolation(err) {
+  return typeof err === "object" && err !== null && err.code === "23505";
+}
+var DRAW_WITH_BASIS_SELECT = `
+  SELECT d.*, c.rail, c.native_asset, c.mint, c.funding_ref, c.currency
+  FROM credit_draws d
+  LEFT JOIN credits c ON c.credit_id = d.credit_id`;
+var DRAIN_CREDIT_COLUMNS = "c.currency, c.caller_pubkey, c.tempo_channel_id, c.x402_channel_id";
+var BITCOIN_CREDIT_PREDICATE = `c.rail IN ('cashu', 'lightning')
+          AND c.tempo_channel_id IS NULL
+          AND c.x402_channel_id IS NULL
+          AND c.balance_micro > 0`;
+var LOT_COVERAGE_LATERAL = `SELECT
+            COALESCE(SUM(l.remaining_micro), 0) AS covered_micro,
+            COALESCE(SUM(l.remaining_micro) FILTER (WHERE l.sats_funded = 0), 0) AS basisless_micro,
+            COALESCE(SUM(l.sats_funded * l.remaining_micro / NULLIF(l.credited_micro, 0)), 0) AS owed_sats
+          FROM credit_funding_lots l
+         WHERE l.credit_id = c.credit_id AND l.remaining_micro > 0`;
+var IN_KIND_PREDICATE = `cov.covered_micro >= c.balance_micro AND cov.basisless_micro = 0`;
+function toSafeInt(value) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(n)) {
+    throw new Error(`credit ledger: BIGINT value ${value} outside safe integer range`);
+  }
+  return n;
+}
+function assertAmount(amountMicro, opts) {
+  if (!Number.isSafeInteger(amountMicro) || amountMicro < opts.min) {
+    throw new CreditLedgerError(
+      "invalid_amount",
+      `amountMicro must be a safe integer \u2265 ${opts.min} (got ${amountMicro})`
+    );
+  }
+}
+function creditBasisFromRow(row) {
+  return {
+    rail: row.rail,
+    nativeAsset: row.native_asset,
+    mint: row.mint,
+    fundingRef: row.funding_ref,
+    creditCurrency: row.currency
+  };
+}
+function railValueFromRow(row, basis) {
+  return {
+    drawMsats: toSafeInt(row.draw_msats),
+    drawNative: row.draw_native === null ? null : toSafeInt(row.draw_native),
+    ...creditBasisFromRow(basis)
+  };
+}
+function drawResultFromRow(row, basis) {
+  return {
+    creditId: row.credit_id,
+    drawId: row.draw_id,
+    amountMicro: toSafeInt(row.amount_micro),
+    balanceAfterMicro: toSafeInt(row.balance_after_micro),
+    ledgerSeq: toSafeInt(row.ledger_seq),
+    status: row.status,
+    replayed: false,
+    railValue: railValueFromRow(row, basis),
+    resolvedAt: row.resolved_at === null ? null : toSafeInt(row.resolved_at)
+  };
+}
+function drawRecordFromRow(row, basis) {
+  const { replayed: _replayed, ...rest } = drawResultFromRow(row, basis);
+  return {
+    ...rest,
+    jobId: row.job_id,
+    createdAt: toSafeInt(row.created_at),
+    allocatedMsats: row.allocated_msats === null ? rest.railValue.drawMsats : toSafeInt(row.allocated_msats)
+  };
+}
+function tempoCreditLossFromRow(row) {
+  return {
+    creditId: row.credit_id,
+    channelId: row.channel_id,
+    callerPubkey: row.caller_pubkey,
+    currency: row.currency,
+    formerBalanceMicro: toSafeInt(row.former_balance_micro),
+    settledOnChainNative: BigInt(row.settled_on_chain_native),
+    highestVoucherNative: BigInt(row.highest_voucher_native),
+    consumedServiceMicro: toSafeInt(row.consumed_service_micro),
+    consumedNative: BigInt(row.consumed_native),
+    observedAt: toSafeInt(row.observed_at)
+  };
+}
+function x402CreditLossFromRow(row) {
+  return {
+    creditId: row.credit_id,
+    channelId: row.channel_id,
+    callerPubkey: row.caller_pubkey,
+    currency: row.currency,
+    formerBalanceMicro: toSafeInt(row.former_balance_micro),
+    channelBalanceNative: BigInt(row.channel_balance_native),
+    totalClaimedNative: BigInt(row.total_claimed_native),
+    consumedServiceMicro: toSafeInt(row.consumed_service_micro),
+    observedAt: toSafeInt(row.observed_at)
+  };
+}
+function drainRecordFromRow(row, credit) {
+  return {
+    creditId: row.credit_id,
+    drainId: row.drain_id,
+    callerPubkey: credit.caller_pubkey,
+    currency: credit.currency,
+    method: row.method,
+    // One column or the other, never both: a credit binds to at most one
+    // channel, and the two rails' ids never coexist on a row.
+    channelId: credit.tempo_channel_id ?? credit.x402_channel_id,
+    payout: row.payout,
+    amountMicro: toSafeInt(row.amount_micro),
+    drainedNative: row.drained_native === null ? null : toSafeInt(row.drained_native),
+    owedSats: row.owed_sats === null ? null : toSafeInt(row.owed_sats),
+    balanceAfterMicro: toSafeInt(row.balance_after_micro),
+    ledgerSeq: toSafeInt(row.ledger_seq),
+    status: row.status,
+    token: row.token,
+    sentRef: row.sent_ref,
+    fulfilment: row.fulfilment,
+    receipts: row.receipts,
+    createdAt: toSafeInt(row.created_at),
+    parkedAt: row.parked_at === null ? null : toSafeInt(row.parked_at),
+    pickedUpAt: row.picked_up_at === null ? null : toSafeInt(row.picked_up_at),
+    sentAt: row.sent_at === null ? null : toSafeInt(row.sent_at),
+    releasedAt: row.released_at === null ? null : toSafeInt(row.released_at),
+    writeOffNote: row.write_off_note,
+    writtenOffAt: row.written_off_at === null ? null : toSafeInt(row.written_off_at)
+  };
+}
+function drainRecordFromJoinRow(row) {
+  return drainRecordFromRow(row, {
+    currency: row.currency,
+    caller_pubkey: row.caller_pubkey,
+    tempo_channel_id: row.tempo_channel_id,
+    x402_channel_id: row.x402_channel_id
+  });
+}
+function fundingLotFromRow(row) {
+  return {
+    lotId: row.lot_id,
+    creditId: row.credit_id,
+    rail: row.rail,
+    satsFunded: toSafeInt(row.sats_funded),
+    creditedMicro: toSafeInt(row.credited_micro),
+    remainingMicro: toSafeInt(row.remaining_micro),
+    fundingRef: row.funding_ref,
+    createdAt: toSafeInt(row.created_at)
+  };
+}
+function fundingRecordFromRow(row) {
+  return {
+    creditId: row.credit_id,
+    fundId: row.fund_id,
+    amountMicro: toSafeInt(row.amount_micro),
+    rail: row.rail,
+    createdAt: toSafeInt(row.created_at),
+    callerPubkey: row.caller_pubkey,
+    balanceAfterMicro: row.balance_after_micro === null ? null : toSafeInt(row.balance_after_micro),
+    ledgerSeq: row.ledger_seq === null ? null : toSafeInt(row.ledger_seq),
+    receipt: row.receipt
+  };
+}
+function invoiceRecordFromRow(row) {
+  return {
+    creditId: row.credit_id,
+    fundId: row.fund_id,
+    callerPubkey: row.caller_pubkey,
+    currency: row.currency,
+    amountMicro: toSafeInt(row.amount_micro),
+    amountMsats: toSafeInt(row.amount_msats),
+    paymentHash: row.payment_hash,
+    bolt11: row.bolt11,
+    status: row.status,
+    blockedReason: row.blocked_reason,
+    reconciledCreditId: row.reconciled_credit_id,
+    reconciledFundId: row.reconciled_fund_id,
+    resolvedAt: row.resolved_at === null ? null : toSafeInt(row.resolved_at),
+    writeOffNote: row.write_off_note,
+    expiresAt: toSafeInt(row.expires_at),
+    createdAt: toSafeInt(row.created_at),
+    settledAt: row.settled_at === null ? null : toSafeInt(row.settled_at)
+  };
+}
+
+export {
+  isNonChannelBitcoinRail,
+  depleteLots,
+  inKindDrawMsats,
+  lotOwedSats,
+  DRAIN_DELIVERY_RESERVE_SATS,
+  netOwedSats,
+  fifoOrder,
+  isInKindDepletion,
+  X402SettlementRaceError,
+  X402RelaySubmissionLockError,
+  X402_WEDGED_SETTLEMENT_STATUSES,
+  X402_RESOLVED_SETTLEMENT_STATUSES,
+  X402_SPEND_BLOCKING_SETTLEMENT_STATUSES,
+  PostgresX402ChannelStorage,
+  CreditLedger,
+  DRAIN_METHODS,
+  isDrainMethod,
+  FUNDING_RAILS,
+  isFundingRail,
+  assertFundingBasis,
+  allocateDrawValue,
+  growthRailValue,
+  clipEarmark,
+  CreditLedgerError,
+  x402SettlementPending
+};