@dvmkit/sdk 0.10.1 → 0.12.0-rc.1

package/dist/{chunk-STJBBVNL.js → chunk-2VGMZ7VF.js}

@@ -1,15 +1,22 @@
+import {
+  parseStoreValue
+} from "./chunk-YG7G4DPZ.js";
 import {
   withSdkInitLock
 } from "./chunk-COYKJRMM.js";
+import {
+  isSignedJobReceipt,
+  verifyReceipt
+} from "./chunk-5H7P3ORL.js";
 import {
   applyRetryToPool
-} from "./chunk-MMGSYMIC.js";
+} from "./chunk-EP7OVWI5.js";
 import {
   x402NetworkByCaip2
 } from "./chunk-BPYMEMQX.js";
 import {
   diagnosticConsole
-} from "./chunk-QGNXYVBO.js";
+} from "./chunk-Z4FOPROB.js";
 
 // src/sdk/server/credit-ledger.ts
 import { randomUUID } from "crypto";
@@ -35,7 +42,7 @@ function depleteLots(lots, amountMicro) {
     const sats = lotSats(lot, available) - lotSats(lot, available - micro);
     debits.push({ lotId: lot.lotId, micro, sats });
     satsOwed += sats;
-    if (lot.satsFunded > 0) backedMicro += micro;
+    if (lot.satsFunded > 0 || lot.satsBasisKnown) backedMicro += micro;
     left -= micro;
   }
   return { debits, satsOwed, uncoveredMicro: left, backedMicro };
@@ -59,7 +66,28 @@ function isInKindDepletion(depletion, amountMicro) {
 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);
+  return Number(BigInt(lot.satsFunded) * BigInt(taken) / BigInt(lot.creditedMicro));
+}
+
+// src/sdk/server/credit-draw-refund.ts
+function refundRequest(args) {
+  const id = (value) => typeof value === "string" && value.length > 0;
+  if (!id(args.refundId) || !(id(args.jobId) && args.creditId === void 0 && args.drawId === void 0 || args.jobId === void 0 && id(args.creditId) && id(args.drawId)) || args.amountMicro !== void 0 && (!Number.isSafeInteger(args.amountMicro) || args.amountMicro <= 0) || args.reason !== void 0 && (typeof args.reason !== "string" || args.reason.length > 280)) {
+    throw new CreditLedgerError("invalid_refund", "Provide one draw selector, a refundId, a positive integer amountMicro if specified, and a reason of at most 280 characters.");
+  }
+  return JSON.stringify({
+    dvmId: args.outbox.dvmId,
+    jobId: args.jobId ?? null,
+    creditId: args.creditId ?? null,
+    drawId: args.drawId ?? null,
+    amountMicro: args.amountMicro ?? null,
+    reason: args.reason ?? null
+  });
+}
+function refundAssetDelta(original, amountMicro, before, after) {
+  const value = BigInt(original);
+  const denominator = BigInt(amountMicro);
+  return Number(value * BigInt(after) / denominator - value * BigInt(before) / denominator);
 }
 
 // src/sdk/server/x402-channel-store.ts
@@ -1140,6 +1168,7 @@ var CreditLedger = class {
    * fleet, so this DVM may advertise credit.
    */
   durable = true;
+  tempoCreditLossEvidenceVersion = 1;
   x402Settlements;
   expiryReleaseOutbox;
   hostingCleanupFence;
@@ -1200,6 +1229,10 @@ var CreditLedger = class {
         observed_at               BIGINT NOT NULL
       );
     `);
+    await this.pool.query(`ALTER TABLE tempo_credit_losses
+      ADD COLUMN IF NOT EXISTS refunded_to_payer_native BIGINT,
+      ADD COLUMN IF NOT EXISTS loss_native BIGINT,
+      ADD COLUMN IF NOT EXISTS loss_basis TEXT`);
     await this.pool.query(
       `CREATE INDEX IF NOT EXISTS idx_tempo_credit_losses_observed
          ON tempo_credit_losses(observed_at, credit_id);`
@@ -1229,7 +1262,8 @@ var CreditLedger = class {
       "tempo_channel_id TEXT",
       "msats_remaining BIGINT NOT NULL DEFAULT 0",
       "native_remaining BIGINT",
-      "x402_channel_id TEXT"
+      "x402_channel_id TEXT",
+      "last_funding_ledger_seq BIGINT"
     ]) {
       await this.pool.query(`ALTER TABLE credits ADD COLUMN IF NOT EXISTS ${column}`);
     }
@@ -1261,10 +1295,25 @@ var CreditLedger = class {
       "draw_msats BIGINT NOT NULL DEFAULT 0",
       "draw_native BIGINT",
       "grown_micro BIGINT NOT NULL DEFAULT 0",
-      "allocated_msats BIGINT"
+      "allocated_msats BIGINT",
+      "settled_sats BIGINT",
+      "refund_dvm_id TEXT"
     ]) {
       await this.pool.query(`ALTER TABLE credit_draws ADD COLUMN IF NOT EXISTS ${column}`);
     }
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS credit_draw_refunds (
+        refund_id TEXT PRIMARY KEY,
+        credit_id TEXT NOT NULL,
+        draw_id TEXT NOT NULL,
+        request TEXT NOT NULL,
+        amount_micro BIGINT NOT NULL CHECK (amount_micro > 0),
+        restored_sats BIGINT,
+        result JSONB NOT NULL
+      );
+    `);
+    await this.pool.query(`CREATE INDEX IF NOT EXISTS credit_draw_refunds_draw_idx
+      ON credit_draw_refunds(credit_id, draw_id)`);
     await this.pool.query(
       `CREATE UNIQUE INDEX IF NOT EXISTS credit_draws_seq_uidx
          ON credit_draws(credit_id, ledger_seq);`
@@ -1312,6 +1361,8 @@ var CreditLedger = class {
         created_at      BIGINT NOT NULL
       );
     `);
+    await this.pool.query(`ALTER TABLE credit_funding_lots
+      ADD COLUMN IF NOT EXISTS sats_basis_known BOOLEAN NOT NULL DEFAULT false`);
     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;`
@@ -1354,6 +1405,10 @@ var CreditLedger = class {
     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 operator_decision JSONB`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS hold_reason TEXT`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS proven_refund_native NUMERIC(78,0)`);
+    await this.pool.query(`ALTER TABLE credit_drains ADD COLUMN IF NOT EXISTS refund_payment_proven BOOLEAN NOT NULL DEFAULT FALSE`);
     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(
@@ -1556,10 +1611,11 @@ var CreditLedger = class {
       ({ 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)
+                            tempo_channel_id, x402_channel_id, last_funding_ledger_seq)
+       VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, $9, $10, $11, $12, $13, $14, 0)
        ON CONFLICT (credit_id) DO UPDATE
          SET balance_micro    = credits.balance_micro + EXCLUDED.balance_micro,
+             last_funding_ledger_seq = credits.last_ledger_seq,
              expiry_ms        = EXCLUDED.expiry_ms,
              rail             = COALESCE(credits.rail, EXCLUDED.rail),
              native_asset     = COALESCE(EXCLUDED.native_asset, credits.native_asset),
@@ -1973,7 +2029,8 @@ var CreditLedger = class {
   /**
    * Grow an accepted job’s pending hold while preserving its original ledger_seq. The balance
    * tuple is updated at that sequence, so interleaved draws need not form a monotonic balance
-   * trajectory. No expiry check applies to an already accepted job.
+   * trajectory. Existing rail top-ups retain accepted-job semantics; spending existing balance
+   * opts into fresh-spend expiry and channel gates.
    *
    * Available balance excludes every pending hold, including this one. An earmark allocates
    * the incoming funding’s rail value; absent one, growth uses the pool.
@@ -1985,7 +2042,7 @@ var CreditLedger = class {
    */
   async growDraw(args) {
     assertAmount(args.addAmountMicro, { min: 1 });
-    const run = async (client, credit) => {
+    const run = async (client, credit, tempoLifecycle) => {
       const existing = await this.readDraw(client, args.creditId, args.drawId);
       if (!existing) {
         throw new CreditLedgerError(
@@ -2008,6 +2065,14 @@ var CreditLedger = class {
           { expectedJobId: existing.job_id ?? null }
         );
       }
+      if (args.spendExistingBalance && toSafeInt(credit.expiry_ms) <= (args.nowMs ?? Date.now())) {
+        throw new CreditLedgerError("credit_expired", "Credit has expired");
+      }
+      if (args.spendExistingBalance && tempoLifecycle && (tempoLifecycle.finalized || tempoLifecycle.closeRequestedAt !== 0n)) {
+        throw new CreditLedgerError("tempo_channel_closing", "Credit channel is closing");
+      }
+      const refund = args.spendExistingBalance ? await this.blockingX402Refund(credit.x402_channel_id, X402_SPEND_BLOCKING_SETTLEMENT_STATUSES) : void 0;
+      if (refund) throw x402SettlementPending(args.creditId, refund);
       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);
@@ -2055,6 +2120,12 @@ var CreditLedger = class {
       const balanceAfterMicro = available - grantMicro;
       const drawMsats = priorMsats + added.drawMsats;
       const drawNative = added.drawNative === null ? priorNative : (priorNative ?? 0) + added.drawNative;
+      if (args.spendExistingBalance) {
+        await this.hostingCleanupFence?.assertNewIntent(client, {
+          jobId: args.jobId,
+          paymentSeq: args.hostingPaymentSeq
+        });
+      }
       await client.query(
         `UPDATE credit_draws
             SET amount_micro = $3, balance_after_micro = $4, draw_msats = $5, draw_native = $6,
@@ -2085,12 +2156,198 @@ var CreditLedger = class {
         cappedMicro: args.addAmountMicro - grantMicro
       };
     };
+    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 (args.spendExistingBalance && 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, run);
   }
+  /** Restore a completed draw and its report under one durable transaction. */
+  async refundDraw(args) {
+    const request = refundRequest(args);
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [args.refundId]);
+      const prior = await client.query(
+        "SELECT request, result FROM credit_draw_refunds WHERE refund_id = $1",
+        [args.refundId]
+      );
+      if (prior.rows[0]) {
+        if (prior.rows[0].request !== request) {
+          throw new CreditLedgerError("refund_conflict", "This refundId was recorded with different arguments.");
+        }
+        await client.query("COMMIT");
+        return { ...prior.rows[0].result, replayed: true };
+      }
+      let creditId = args.creditId;
+      let drawId = args.drawId;
+      if (args.jobId !== void 0) {
+        const matches = await client.query(
+          "SELECT credit_id, draw_id FROM credit_draws WHERE job_id = $1 LIMIT 2",
+          [args.jobId]
+        );
+        if (matches.rows.length === 1) {
+          creditId = matches.rows[0].credit_id;
+          drawId = matches.rows[0].draw_id;
+        }
+      }
+      if (creditId === void 0 || drawId === void 0) {
+        throw new CreditLedgerError("draw_not_found", "No unique credit draw matches this job.");
+      }
+      let credit;
+      try {
+        credit = await this.lockCreditRow(client, creditId);
+      } catch (error) {
+        if (error instanceof CreditLedgerError && error.code === "credit_not_found") {
+          throw new CreditLedgerError("draw_not_found", "No draw matches this credit.");
+        }
+        throw error;
+      }
+      const draw = await this.readDraw(client, creditId, drawId);
+      if (!credit || !draw || !draw.job_id || args.jobId !== void 0 && draw.job_id !== args.jobId) {
+        throw new CreditLedgerError("draw_not_found", "No job-bound draw matches this selector.");
+      }
+      const owners = new Set(draw.refund_dvm_id ? [draw.refund_dvm_id] : []);
+      const sources = await client.query(
+        "SELECT to_regclass('jobs')::text AS jobs, to_regclass('reported_job_terminals')::text AS terminals"
+      );
+      if (sources.rows[0].jobs) {
+        const jobs = await client.query(
+          "SELECT dvm_id, receipt FROM jobs WHERE id = $1",
+          [draw.job_id]
+        );
+        const job = jobs.rows[0];
+        if (job?.dvm_id) owners.add(job.dvm_id);
+        const receipt = job?.receipt;
+        if (args.trustedReceiptPubkey !== void 0 && isSignedJobReceipt(receipt) && receipt.receipt_pubkey === args.trustedReceiptPubkey && receipt.job_id === draw.job_id && verifyReceipt(receipt)) {
+          owners.add(receipt.dvm_id);
+        }
+      }
+      if (sources.rows[0].terminals) {
+        const terminals = await client.query(
+          "SELECT dvm_id FROM reported_job_terminals WHERE job_id = $1",
+          [draw.job_id]
+        );
+        for (const terminal of terminals.rows) owners.add(terminal.dvm_id);
+      }
+      if (owners.size !== 1 || !owners.has(args.outbox.dvmId)) {
+        throw new CreditLedgerError("draw_not_found", "No draw with proven ownership matches this DVM.");
+      }
+      if (draw.status !== "settled") {
+        throw new CreditLedgerError("draw_not_completed", "Only a settled completed draw can be refunded.");
+      }
+      const nowMs = args.nowMs ?? Date.now();
+      const drained = await client.query(`SELECT 1 FROM credit_drains d
+        WHERE d.credit_id = $1 AND d.status <> 'released' AND d.balance_after_micro = 0
+          AND (SELECT MAX(ledger_seq) FROM credit_drains WHERE credit_id = $1 AND status <> 'released') = d.ledger_seq
+          AND ($2::bigint IS NULL OR $2::bigint < d.ledger_seq)
+          AND NOT EXISTS (SELECT 1 FROM credit_draws later WHERE later.credit_id = $1
+            AND later.ledger_seq > d.ledger_seq AND later.amount_micro > 0)
+          AND NOT EXISTS (SELECT 1 FROM credit_fundings f WHERE f.credit_id = $1
+            AND f.ledger_seq >= d.ledger_seq AND f.amount_micro > 0)
+        LIMIT 1`, [creditId, credit.last_funding_ledger_seq]);
+      if (credit.status !== "active" || toSafeInt(credit.expiry_ms) <= nowMs) {
+        throw new CreditLedgerError("credit_not_open", "The original credit is no longer open for refunds.");
+      }
+      if (credit.tempo_channel_id || credit.x402_channel_id) {
+        throw new CreditLedgerError("credit_refund_channel_unsupported", "Channel collateral cannot back a refund of settled spending.");
+      }
+      if (toSafeInt(credit.balance_micro) === 0 && drained.rows.length > 0) {
+        if (credit.last_funding_ledger_seq === null) {
+          throw new CreditLedgerError("credit_refund_state_unavailable", "The original credit's historical funding and drain order cannot be established.");
+        }
+        throw new CreditLedgerError("credit_not_open", "The original credit is no longer open for refunds.");
+      }
+      const totals = await client.query(`SELECT COALESCE(SUM(amount_micro), 0) AS refunded
+        FROM credit_draw_refunds WHERE credit_id = $1 AND draw_id = $2`, [creditId, drawId]);
+      const before = toSafeInt(totals.rows[0].refunded);
+      const originalMicro = toSafeInt(draw.amount_micro);
+      const amountMicro = args.amountMicro ?? originalMicro - before;
+      if (amountMicro <= 0 || amountMicro > originalMicro - before) {
+        throw new CreditLedgerError("refund_exceeds_draw", "The refund exceeds the draw's remaining unrefunded charge.");
+      }
+      const after = before + amountMicro;
+      if (!isFundingRail(credit.rail)) {
+        throw new CreditLedgerError("credit_refund_basis_unavailable", "The original funding rail is not recorded on this older credit.");
+      }
+      const bitcoin = isNonChannelBitcoinRail(credit.rail);
+      const originalSats = draw.settled_sats === null ? null : toSafeInt(draw.settled_sats);
+      if (bitcoin && originalSats === null) {
+        throw new CreditLedgerError("credit_refund_basis_unavailable", "The original Bitcoin value is not provable from this older draw.");
+      }
+      const restoredSats = bitcoin ? refundAssetDelta(originalSats, originalMicro, before, after) : null;
+      const restoredMsats = restoredSats === null ? refundAssetDelta(toSafeInt(draw.draw_msats), originalMicro, before, after) : restoredSats * 1e3;
+      const restoredNative = draw.draw_native === null ? null : refundAssetDelta(toSafeInt(draw.draw_native), originalMicro, before, after);
+      const balanceAfterMicro = toSafeInt(toSafeInt(credit.balance_micro) + amountMicro);
+      const ledgerSeq = toSafeInt(toSafeInt(credit.last_ledger_seq) + 1);
+      toSafeInt(toSafeInt(credit.msats_remaining) + restoredMsats);
+      if (credit.native_remaining !== null) toSafeInt(toSafeInt(credit.native_remaining) + (restoredNative ?? 0));
+      await client.query(`UPDATE credit_draws SET refund_dvm_id = $3
+        WHERE credit_id = $1 AND draw_id = $2`, [creditId, drawId, args.outbox.dvmId]);
+      await client.query(`UPDATE credits SET balance_micro = $2, last_ledger_seq = $3,
+        msats_remaining = msats_remaining + $4,
+        native_remaining = CASE WHEN native_remaining IS NULL THEN NULL ELSE native_remaining + $5 END
+        WHERE credit_id = $1`, [creditId, balanceAfterMicro, ledgerSeq, restoredMsats, restoredNative ?? 0]);
+      if (bitcoin) {
+        await client.query(
+          `INSERT INTO credit_funding_lots
+          (lot_id, credit_id, rail, sats_funded, credited_micro, remaining_micro, funding_ref, created_at, sats_basis_known)
+          VALUES ($1, $2, $3, $4, $5, $5, $6, $7, true)`,
+          [`lot:refund:${randomUUID()}`, creditId, credit.rail, restoredSats, amountMicro, args.refundId, nowMs]
+        );
+      }
+      const result = {
+        refundId: args.refundId,
+        creditId,
+        drawId,
+        jobId: draw.job_id,
+        amountMicro,
+        currency: credit.currency,
+        ledgerSeq,
+        refundedAt: nowMs,
+        balanceAfterMicro,
+        replayed: false
+      };
+      await client.query(
+        `INSERT INTO credit_draw_refunds
+        (refund_id, credit_id, draw_id, request, amount_micro, restored_sats, result)
+        VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+        [args.refundId, creditId, drawId, request, amountMicro, restoredSats, JSON.stringify(result)]
+      );
+      await args.outbox.enqueue(client, {
+        dvmId: args.outbox.dvmId,
+        creditId,
+        drawId,
+        jobId: draw.job_id,
+        refundId: args.refundId,
+        amountMicro,
+        creditCurrency: credit.currency,
+        ledgerSeq,
+        refundedAt: nowMs,
+        ...args.reason === void 0 ? {} : { reason: args.reason }
+      });
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
   /**
    * Finalize a pending draw: the hold becomes a real debit
    * (`balance_micro −= amount`). Available balance is unchanged — the amount
@@ -2779,6 +3036,15 @@ var CreditLedger = class {
     }
   }
   async terminalizeTempoCreditsLocked(q, evidence, channelId, observedAt) {
+    const refunded = evidence.refundedToPayerNative ?? 0n;
+    if (refunded < 0n) throw new Error("Tempo close refund must be nonnegative");
+    const payerExit = evidence.closeKind === "payer_exit";
+    if (payerExit && evidence.refundedToPayerNative !== void 0 || evidence.closeKind === "cooperative_close" && evidence.refundedToPayerNative === void 0) {
+      throw new Error("Tempo close kind requires matching exact cooperative refund evidence");
+    }
+    const lossNative = (payerExit ? evidence.consumedNative : evidence.highestVoucherNative) - evidence.settledOnChainNative - (payerExit ? 0n : refunded);
+    const lossBasis = payerExit ? "payer_exit" : evidence.refundedToPayerNative === void 0 ? "caller_asserted" : "cooperative_close";
+    if (lossNative <= 0n) return this.readTempoCreditLosses(q, { channelId });
     const { rows: credits } = await q.query(
       `SELECT * FROM credits
         WHERE tempo_channel_id = $1
@@ -2799,8 +3065,8 @@ var CreditLedger = class {
         `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)
+            consumed_native, observed_at, refunded_to_payer_native, loss_native, loss_basis)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
          ON CONFLICT (credit_id) DO NOTHING`,
         [
           credit.credit_id,
@@ -2812,7 +3078,10 @@ var CreditLedger = class {
           evidence.highestVoucherNative.toString(),
           consumed[0]?.amount ?? "0",
           evidence.consumedNative.toString(),
-          observedAt
+          observedAt,
+          evidence.refundedToPayerNative?.toString() ?? null,
+          lossNative.toString(),
+          lossBasis
         ]
       );
       await q.query(`UPDATE credits SET status = 'unbacked' WHERE credit_id = $1`, [
@@ -2821,8 +3090,8 @@ var CreditLedger = class {
     }
     return this.readTempoCreditLosses(q, { channelId });
   }
-  async listTempoCreditLosses(args) {
-    return this.readTempoCreditLosses(this.pool, { limit: args?.limit ?? 50 });
+  async listTempoCreditLosses(args, tx) {
+    return this.readTempoCreditLosses(tx ?? this.pool, { limit: args?.limit ?? 50, channelId: args?.channelId?.toLowerCase() });
   }
   /**
    * Reconcile the credit bound to a chain-proven empty x402 channel.
@@ -3158,26 +3427,27 @@ var CreditLedger = class {
     return rows.map(drainRecordFromJoinRow);
   }
   /**
-   * Page pending Tempo-channel drains by (created_at, credit_id, drain_id), optionally
-   * age-bounded, excluding written-off rows. Accept the legacy mpp stored method as well as
+   * Page held Tempo-channel drains by (created_at, credit_id, drain_id), optionally
+   * age-bounded. Audit reads also include terminal operator decisions. Accept the legacy mpp stored method as well as
    * tempo so pre-migration drains remain repairable. Use the compound key for both ordering
    * and continuation.
    */
   async listChannelDrains(args) {
-    const params = [args.createdBeforeMs, args.limit];
+    const params = [args.createdBeforeMs, args.limit, args.includeResolved ?? false, args.includeWrittenOff || args.includeResolved || false];
     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)`;
+      keyset = ` AND (d.created_at, d.credit_id, d.drain_id) > ($5, $6, $7)`;
     }
     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 IN ('pending','exit_required')
+       WHERE (d.status IN ('pending','exit_required')
+              OR ($3::boolean AND d.operator_decision IS NOT NULL))
          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"}
+         AND ($4::boolean OR d.written_off_at IS NULL)
          ${keyset}
        ORDER BY d.created_at, d.credit_id, d.drain_id
        LIMIT $2`,
@@ -3241,49 +3511,182 @@ var CreditLedger = class {
       verb: "require timed exit"
     });
   }
+  /** Retain an exact receipt-derived refund; a later missing/zero read cannot erase payment. */
+  async recordTempoDrainRefund(args) {
+    const amount = String(args.refundedNative);
+    if (!/^\d{1,78}$/.test(amount)) throw new CreditLedgerError("invalid_basis", "Tempo refund evidence must be a bounded non-negative integer.");
+    await this.recordTempoDrainRefundEvidence(args, amount);
+  }
+  /** Retain trusted proof that some refund was paid, without claiming an exact amount. */
+  async recordTempoDrainPayment(args) {
+    await this.recordTempoDrainRefundEvidence(args, null);
+  }
+  async recordTempoDrainRefundEvidence(args, amount) {
+    const { rows } = await this.pool.query(
+      "SELECT tempo_channel_id FROM credits WHERE credit_id=$1",
+      [args.creditId]
+    );
+    const record = async (tx) => {
+      await tx.query(
+        `UPDATE credit_drains SET proven_refund_native=
+        GREATEST(proven_refund_native, $3::numeric),
+        refund_payment_proven=refund_payment_proven OR COALESCE($3::numeric > 0, TRUE)
+        WHERE credit_id=$1 AND drain_id=$2 AND method='tempo'
+          AND status IN ('pending','exit_required') AND operator_decision IS NULL`,
+        [args.creditId, args.drainId, amount]
+      );
+    };
+    const channelId = rows[0]?.tempo_channel_id;
+    if (channelId && this.tempoSessionStore) {
+      await this.tempoSessionStore.withDrawPlacement(channelId, record);
+    } else {
+      await record(this.pool);
+    }
+  }
+  /** Record the latest established proof refusal without changing the held debit. */
+  async recordTempoDrainHold(args) {
+    await this.pool.query(
+      `UPDATE credit_drains SET hold_reason=
+      CASE WHEN hold_reason='refund_short' AND proven_refund_native IS NULL THEN hold_reason ELSE $3 END
+      WHERE credit_id=$1 AND drain_id=$2 AND method='tempo'
+        AND status IN ('pending','exit_required') AND operator_decision IS NULL`,
+      [args.creditId, args.drainId, args.reason]
+    );
+  }
   /**
-   * 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.
+   * An operator attests a full off-path refund or restores the exact unpaid debit. The
+   * channel lock precedes the credit and drain locks; automatic booking shares the drain
+   * CAS, so only one terminal outcome can commit. No channel lifecycle state is reopened.
+   * Direct callers own reporting: hosted booking must join the caller's drain outbox transaction.
    */
-  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 {
+  async decideTempoDrain(args) {
+    if (!["book_refunded", "release"].includes(args.decision) || typeof args.reason !== "string" || !args.reason.trim() || args.reason.trim().length > 2e3 || args.evidence !== void 0 && (typeof args.evidence !== "string" || !args.evidence.trim() || args.evidence.trim().length > 4e3)) {
+      throw new CreditLedgerError("invalid_drain_decision", "A decision requires a reason of 1\u20132000 characters and optional evidence of 1\u20134000 characters.");
+    }
+    const query = args.tx ?? this.pool;
+    const { rows } = await query.query(
+      `SELECT tempo_channel_id FROM credits WHERE credit_id=$1`,
+      [args.creditId]
+    );
+    if (!rows[0]) throw new CreditLedgerError("credit_not_found", "The credit was not found.");
+    const channelId = rows[0].tempo_channel_id;
+    if (!channelId || !this.tempoSessionStore) {
+      throw new CreditLedgerError("drain_not_repairable", "A durable Tempo session channel is required for an operator decision.");
+    }
+    return this.tempoSessionStore.withDrawPlacement(channelId, async (tx, lifecycle) => {
+      const intent = await tx.query(
+        `SELECT reference, settled_before_close, forecast_pending FROM mpp_tempo_close_intents
+          WHERE channel_id=$1 AND drain_id=$2 FOR UPDATE`,
+        [channelId, args.drainId]
+      );
+      const credit = await this.lockCreditRow(tx, args.creditId);
+      const { rows: rows2 } = await tx.query(
+        `SELECT * FROM credit_drains WHERE credit_id=$1 AND drain_id=$2 FOR UPDATE`,
+        [args.creditId, args.drainId]
+      );
+      const row = rows2[0];
+      if (!row) throw new CreditLedgerError("drain_not_found", "The drain was not found.");
+      if (row.method !== "tempo") throw new CreditLedgerError("drain_not_repairable", "Only a held Tempo session drain accepts an operator decision.");
+      const reason = args.reason.trim();
+      const evidence = args.evidence?.trim();
+      let result;
+      if (row.operator_decision) {
+        const prior = row.operator_decision;
+        if (prior.decision !== args.decision || prior.reason !== reason || prior.evidence !== evidence) {
+          throw new CreditLedgerError("drain_decision_conflict", "This drain already has a different immutable operator decision.");
+        }
+        result = {
           drain: drainRecordFromRow(row, credit),
-          credit: await this.snapshotFromRow(credit, client, nowMs),
+          credit: await this.snapshotFromRow(credit, tx, args.nowMs ?? Date.now()),
           replayed: true
         };
+      } else {
+        if (row.status !== "pending" && row.status !== "exit_required") {
+          throw new CreditLedgerError("drain_decision_conflict", "This drain has already reached another terminal outcome.");
+        }
+        if (args.decision === "release") {
+          const closeIntent = intent.rows[0];
+          const reference = closeIntent?.reference;
+          if (!lifecycle.finalized && closeIntent && (closeIntent.forecast_pending !== true || closeIntent.settled_before_close != null || reference && /^0x[0-9a-fA-F]{64}$/.test(reference))) {
+            throw new CreditLedgerError("tempo_drain_close_pending", "The close may still pay. Reconcile its final outcome before releasing this drain.");
+          }
+          const channel = await tx.query(
+            "SELECT state_json FROM mpp_tempo_channels WHERE channel_key=$1",
+            [channelId]
+          );
+          const state = channel.rows[0] && parseStoreValue(channel.rows[0].state_json);
+          const observation = state?.tempoDrainPaymentObservation;
+          const paymentObserved = observation?.creditId === args.creditId && observation.drainId === args.drainId;
+          if (paymentObserved || row.refund_payment_proven || row.proven_refund_native !== null && BigInt(row.proven_refund_native) > 0n) {
+            throw new CreditLedgerError("tempo_drain_refund_paid", "A positive refund is already proven. Verify return of the full held amount, including any remainder, then book it as refunded; never release it as unpaid.");
+          }
+          if (row.hold_reason === "refund_short" && row.proven_refund_native === null) {
+            throw new CreditLedgerError("tempo_drain_refund_unknown", "This short-refund history has no retained exact amount. Recover its refund evidence before releasing it as unpaid.");
+          }
+        }
+        const decision = {
+          source: "operator",
+          decision: args.decision,
+          reason,
+          ...evidence === void 0 ? {} : { evidence },
+          decidedAt: args.nowMs ?? Date.now()
+        };
+        await tx.query(`UPDATE credit_drains SET operator_decision=$3
+          WHERE credit_id=$1 AND drain_id=$2`, [args.creditId, args.drainId, JSON.stringify(decision)]);
+        row.operator_decision = decision;
+        if (args.decision === "release") {
+          result = await this.releaseDrainLocked(tx, row, args, decision.decidedAt);
+        } else {
+          await this.clearDrainWriteOff({ creditId: args.creditId, drainId: args.drainId, tx });
+          const booked = await this.markDrainSent({
+            creditId: args.creditId,
+            drainId: args.drainId,
+            sentRef: { source: "operator", channel_id: channelId },
+            tx,
+            nowMs: decision.decidedAt
+          });
+          result = { ...booked, credit: await this.snapshotFromRow(credit, tx, decision.decidedAt) };
+        }
       }
-      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'
+      const spendableMicro = lifecycle.finalized || lifecycle.closeRequestedAt !== 0n || result.credit.expired ? 0 : result.credit.availableMicro;
+      return { ...result, spendableMicro };
+    }, args.tx);
+  }
+  /** Restore an unpaid pending drain; operator decisions also admit exit_required. */
+  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}`
+      );
+      return this.releaseDrainLocked(client, row, args, nowMs);
+    };
+    if (args.tx) return run(args.tx, await this.lockCreditRow(args.tx, args.creditId));
+    return this.withCreditLock(args.creditId, run);
+  }
+  async releaseDrainLocked(client, row, args, nowMs) {
+    const { rows } = await client.query(
+      `UPDATE credit_drains SET status = 'released', released_at = $3
+         WHERE credit_id = $1 AND drain_id = $2 AND status = $4
          RETURNING *`,
-        [args.creditId, args.drainId, nowMs]
+      [args.creditId, args.drainId, nowMs, row.status]
+    );
+    if (!rows[0]) {
+      throw new CreditLedgerError(
+        "invalid_drain_state",
+        `drain ${args.drainId} changed while it was being released`
       );
-      if (!rows[0]) {
-        throw new CreditLedgerError(
-          "invalid_drain_state",
-          `drain ${args.drainId} changed while it was being released`
-        );
-      }
-      await client.query(
-        `UPDATE credits
+    }
+    await client.query(
+      `UPDATE credits
            SET balance_micro = balance_micro + $2,
                msats_remaining = msats_remaining + $3,
                native_remaining = CASE
@@ -3291,18 +3694,15 @@ var CreditLedger = class {
                  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
-      };
+      [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`).
@@ -3525,7 +3925,13 @@ var CreditLedger = class {
         let settledMsats = forecastMsats;
         if (isNonChannelBitcoinRail(credit.rail)) {
           const depletion = depleteLots(await this.openLots(client, args.creditId), amountMicro);
-          settledMsats = inKindDrawMsats(depletion, amountMicro) ?? forecastMsats;
+          const inKindMsats = inKindDrawMsats(depletion, amountMicro);
+          settledMsats = inKindMsats ?? forecastMsats;
+          await client.query(
+            `UPDATE credit_draws SET settled_sats = $3
+            WHERE credit_id = $1 AND draw_id = $2`,
+            [args.creditId, args.drawId, inKindMsats === null ? null : inKindMsats / 1e3]
+          );
           await this.applyLotDebits(client, depletion.debits, -1);
         }
         if (settledMsats !== forecastMsats) {
@@ -3771,8 +4177,8 @@ var BITCOIN_CREDIT_PREDICATE = `c.rail IN ('cashu', 'lightning')
           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
+            COALESCE(SUM(l.remaining_micro) FILTER (WHERE l.sats_funded = 0 AND NOT l.sats_basis_known), 0) AS basisless_micro,
+            COALESCE(SUM(FLOOR(l.sats_funded::numeric * 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`;
@@ -3840,6 +4246,9 @@ function tempoCreditLossFromRow(row) {
     highestVoucherNative: BigInt(row.highest_voucher_native),
     consumedServiceMicro: toSafeInt(row.consumed_service_micro),
     consumedNative: BigInt(row.consumed_native),
+    refundedToPayerNative: row.refunded_to_payer_native === null ? null : BigInt(row.refunded_to_payer_native),
+    lossNative: row.loss_native === null ? null : BigInt(row.loss_native),
+    lossBasis: row.loss_basis === "cooperative_close" || row.loss_basis === "payer_exit" || row.loss_basis === "caller_asserted" ? row.loss_basis : null,
     observedAt: toSafeInt(row.observed_at)
   };
 }
@@ -3883,7 +4292,11 @@ function drainRecordFromRow(row, credit) {
     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)
+    writtenOffAt: row.written_off_at === null ? null : toSafeInt(row.written_off_at),
+    operatorDecision: row.operator_decision ?? null,
+    holdReason: row.hold_reason ?? null,
+    provenRefundNative: row.proven_refund_native ?? null,
+    refundPaymentProven: row.refund_payment_proven ?? false
   };
 }
 function drainRecordFromJoinRow(row) {
@@ -3900,6 +4313,7 @@ function fundingLotFromRow(row) {
     creditId: row.credit_id,
     rail: row.rail,
     satsFunded: toSafeInt(row.sats_funded),
+    satsBasisKnown: row.sats_basis_known,
     creditedMicro: toSafeInt(row.credited_micro),
     remainingMicro: toSafeInt(row.remaining_micro),
     fundingRef: row.funding_ref,
@@ -3983,6 +4397,8 @@ export {
   netOwedSats,
   fifoOrder,
   isInKindDepletion,
+  refundRequest,
+  refundAssetDelta,
   X402SettlementRaceError,
   X402RelaySubmissionLockError,
   X402_WEDGED_SETTLEMENT_STATUSES,