@dvmkit/sdk 0.8.1 → 0.10.0

package/dist/{chunk-QKE5NDPF.js → chunk-MU3IE434.js}

@@ -1,9 +1,9 @@
 import {
   loggers
-} from "./chunk-IOQIXRGM.js";
+} from "./chunk-M3T5JYDJ.js";
 import {
   diagnosticConsole
-} from "./chunk-BFGQG4WY.js";
+} from "./chunk-QGNXYVBO.js";
 
 // src/sdk/server/mpp-setup.ts
 import { createHash, randomUUID } from "crypto";
@@ -313,6 +313,15 @@ function logStateFailure(_error) {
 }
 
 // src/sdk/server/mpp-setup.ts
+var TempoDrainRefundUnprovenError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+  }
+  reason;
+};
+var TempoCloseDescriptorError = class extends MppxErrors.VerificationFailedError {
+};
 var MPPX_HMAC_MISMATCH_REASON = "challenge was not issued by this server";
 var TEMPO_SETTLEMENT_LEASE_FIELD = "settlementLeaseUntil";
 var TEMPO_SETTLEMENT_LEASE_OWNER_FIELD = "settlementLeaseOwner";
@@ -654,6 +663,10 @@ function wrapMppx(mppx) {
 var TEMPO_CLOSE_LOG_WINDOW = 5000n;
 var TEMPO_CLOSE_LOG_SLACK_MS = 10 * 60 * 1e3;
 var TEMPO_CLOSE_LOG_MAX_WINDOWS = 500;
+var TEMPO_CLOSE_SEARCH_BUDGET_MS = 3e4;
+var TEMPO_CLOSE_POLL_SEARCH_BUDGET_MS = 1e4;
+var TEMPO_CLOSE_SEARCH_TIMEOUT_MS = 6e4;
+var TEMPO_CLOSE_CURSOR_SAVE_RESERVE_MS = 5e3;
 var DEFAULT_TEMPO_SESSION_CHAIN_OPS = {
   getChannelStatesBatch: TempoSession.Precompile.Chain.getChannelStatesBatch,
   settle: TempoSession.Server.settle,
@@ -664,7 +677,7 @@ var DEFAULT_TEMPO_SESSION_CHAIN_OPS = {
       channelId
     )
   ),
-  findChannelClose: async (client, channelId, escrowContract, notBeforeMs, startBlock) => {
+  findChannelClose: async (client, channelId, escrowContract, notBeforeMs, startBlock, deadlineMs = Date.now() + TEMPO_CLOSE_SEARCH_BUDGET_MS) => {
     const { getBlock, getBlockNumber, getLogs, getTransaction } = await import("viem/actions");
     const eventNamed = (name) => {
       const event = TempoSession.Precompile.escrowAbi.find(
@@ -682,6 +695,8 @@ var DEFAULT_TEMPO_SESSION_CHAIN_OPS = {
     }
     let toBlock = startBlock ?? await getBlockNumber(client);
     for (let window = 0; window < TEMPO_CLOSE_LOG_MAX_WINDOWS; window += 1) {
+      const deadline = typeof deadlineMs === "function" ? deadlineMs() : deadlineMs;
+      if (Date.now() >= deadline) return { outcome: "paused", resumeAt: toBlock };
       const fromBlock = toBlock >= TEMPO_CLOSE_LOG_WINDOW ? toBlock - TEMPO_CLOSE_LOG_WINDOW + 1n : 0n;
       const range = { address: escrowContract, args: { channelId }, fromBlock, toBlock };
       const [closed, requested, cancelled] = await Promise.all([
@@ -717,9 +732,12 @@ var DEFAULT_TEMPO_SESSION_CHAIN_OPS = {
 };
 function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
   let creditLedger;
+  let finalizeDrain;
+  const finalizedCloseSearches = /* @__PURE__ */ new Map();
   Object.assign(mppx, {
-    useTempoCreditLedger: (ledger) => {
+    useTempoCreditLedger: (ledger, finalizer) => {
       creditLedger = ledger;
+      finalizeDrain = finalizer;
     }
   });
   const chainOps = {
@@ -737,7 +755,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       assertTempoSessionCloseVoucher: async (voucher) => {
         const descriptor = readChannelDescriptor(voucher.descriptor);
         if (!descriptor) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "descriptor required for TIP-1034 session action"
           });
         }
@@ -755,22 +773,22 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
           escrow
         });
         if (computed.toLowerCase() !== voucher.channelId.toLowerCase()) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "channel descriptor does not match channelId"
           });
         }
         if (!sameHex(descriptor.payee, voucher.request.recipient)) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "channel descriptor payee does not match server destination"
           });
         }
         if (!sameHex(descriptor.token, voucher.request.currency)) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "channel descriptor token does not match server token"
           });
         }
         if (!sameHex(descriptor.operator, details.operator ?? ZERO_ADDRESS)) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "channel descriptor operator does not match server operator"
           });
         }
@@ -784,7 +802,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         }
         const storedDescriptor = readChannelDescriptor(stored.descriptor);
         if (!storedDescriptor || !sameDescriptor(descriptor, storedDescriptor)) {
-          throw new MppxErrors.VerificationFailedError({
+          throw new TempoCloseDescriptorError({
             reason: "credential descriptor does not match stored channel"
           });
         }
@@ -886,6 +904,9 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         value: {
           ...value,
           finalized: active.finalized || chainFinalized,
+          ...chainFinalized && !active.finalized && {
+            depositBeforeFinalization: active.deposit
+          },
           closeRequestedAt: chainFinalized ? 0n : BigInt(chainState.closeRequestedAt),
           deposit: chainFinalized ? 0n : maxBigInt(active.deposit, chainState.deposit),
           settledOnChain: maxBigInt(active.settledOnChain, chainState.settled)
@@ -914,6 +935,9 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         value: {
           ...current,
           finalized: active.finalized || chainFinalized,
+          ...chainFinalized && !active.finalized && {
+            depositBeforeFinalization: active.deposit
+          },
           closeRequestedAt: chainFinalized ? 0n : BigInt(chainState.closeRequestedAt),
           deposit: chainFinalized ? 0n : maxBigInt(active.deposit, chainState.deposit),
           settledOnChain: maxBigInt(active.settledOnChain, chainState.settled)
@@ -925,18 +949,46 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
   };
   const settlingHere = /* @__PURE__ */ new Set();
   const leaseMs = config.settlementSchedule?.leaseMs ?? TEMPO_SETTLEMENT_LEASE_MS;
-  const claimSettlement = async (channelId) => {
-    if (settlingHere.has(channelId)) return false;
+  const claimSettlement = async (channelId, chainSettled, forcedClose) => {
+    const inFlight = {
+      outcome: "retryable_failure",
+      channelId,
+      error: TEMPO_SETTLEMENT_IN_FLIGHT
+    };
+    if (settlingHere.has(channelId)) return inFlight;
     settlingHere.add(channelId);
     const leaseOwner = randomUUID();
     const leaseUntil = Date.now() + leaseMs;
     try {
-      const claimed = await store.update(channelId, (current) => {
-        if (!isStateRecord(current)) return { op: "noop", result: false };
+      const claim = await store.update(channelId, (current) => {
+        const channel = readTempoSessionState(current);
+        if (!channel || !isStateRecord(current)) {
+          return { op: "noop", result: { outcome: "unknown_channel", channelId } };
+        }
         const until = current[TEMPO_SETTLEMENT_LEASE_FIELD];
         const owner = current[TEMPO_SETTLEMENT_LEASE_OWNER_FIELD];
         if (typeof until === "number" && until > Date.now() && owner !== leaseOwner) {
-          return { op: "noop", result: false };
+          return { op: "noop", result: inFlight };
+        }
+        const settledOnChain = maxBigInt(channel.settledOnChain, chainSettled);
+        if (channel.finalized && channel.highestVoucherAmount > settledOnChain) {
+          return {
+            op: "noop",
+            result: {
+              outcome: "finalized_before_protection",
+              channelId,
+              owed: channel.highestVoucherAmount - settledOnChain,
+              settledOnChain
+            }
+          };
+        }
+        if (channel.finalized || !tempoSettlementDue({
+          channel,
+          chainSettled: settledOnChain,
+          forcedClose,
+          intervalMs: config.settlementSchedule?.intervalMs
+        })) {
+          return { op: "noop", result: { outcome: "already_safe", channelId, settledOnChain } };
         }
         return {
           op: "set",
@@ -945,11 +997,11 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
             [TEMPO_SETTLEMENT_LEASE_FIELD]: leaseUntil,
             [TEMPO_SETTLEMENT_LEASE_OWNER_FIELD]: leaseOwner
           },
-          result: true
+          result: { outcome: "claimed", channel }
         };
       });
-      if (!claimed) settlingHere.delete(channelId);
-      return claimed;
+      if (claim.outcome !== "claimed") settlingHere.delete(channelId);
+      return claim;
     } catch (err) {
       settlingHere.delete(channelId);
       throw err;
@@ -971,8 +1023,10 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       settlingHere.delete(channelId);
     }
   };
-  const settleChannel = async (channel, client) => {
-    if (!await claimSettlement(channel.channelId)) return false;
+  const settleChannel = async (channelId, client, chainSettled, forcedClose) => {
+    const claim = await claimSettlement(channelId, chainSettled, forcedClose);
+    if (claim.outcome !== "claimed") return claim;
+    const { channel } = claim;
     try {
       const recoveryVersion = await config.beforeSessionSettlement?.();
       const reservation = await config.hostedObligations?.reserveTempo(channel.channelId, "settle");
@@ -1007,7 +1061,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       throw err;
     }
     await releaseSettlement(channel.channelId);
-    return true;
+    return { outcome: "settled", channelId, settledAmount: channel.highestVoucherAmount };
   };
   const settleTempoSessionChannel = async (channelId) => {
     const normalized = channelId.toLowerCase();
@@ -1048,18 +1102,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       })) {
         return { outcome: "already_safe", channelId: normalized, settledOnChain };
       }
-      if (!await settleChannel(channel, client)) {
-        return {
-          outcome: "retryable_failure",
-          channelId: normalized,
-          error: TEMPO_SETTLEMENT_IN_FLIGHT
-        };
-      }
-      return {
-        outcome: "settled",
-        channelId: normalized,
-        settledAmount: channel.highestVoucherAmount
-      };
+      return await settleChannel(normalized, client, chainState.settled, forcedClose);
     } catch (err) {
       return {
         outcome: "retryable_failure",
@@ -1146,18 +1189,29 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
           })) {
             continue;
           }
-          if (await settleChannel(channel, client)) settled += 1;
-          else inFlight += 1;
+          const result = await settleChannel(channel.channelId, client, chainState.settled, forcedClose);
+          if (result.outcome === "settled") settled += 1;
+          else if (result.outcome === "retryable_failure") inFlight += 1;
         }
       }
     }
-    await reconcileUnsubmittedCloses();
+    await reconcileTempoSessionCloses();
     return { scanned: rows.length, closeRequested, settled, inFlight };
   };
-  const recoverTempoSessionClose = async (channelId, drainId) => {
+  const recoverTempoSessionClose = async (channelId, drainId, creditId) => {
     if (!store.getClose || !store.confirmClose) return null;
     const intent = await store.getClose(channelId);
     if (intent?.drainId !== drainId) return null;
+    const drain = creditId ? await creditLedger?.getDrain({ creditId, drainId }) : void 0;
+    if (drain && drain.channelId !== channelId) throw new Error("Tempo drain channel does not match its credit");
+    if (drain?.status === "pending" || drain?.status === "exit_required") {
+      const result = await reconcileFinalizedDrain(drain, true);
+      if (result.outcome === "retryable_failure") throw result.error;
+      if (result.outcome === "refund_unproven") return { outcome: "refund_unproven" };
+      if (result.outcome === "open") return null;
+      const completed = await creditLedger.getDrain({ creditId: drain.creditId, drainId });
+      return completed?.status === "sent" && typeof completed.sentRef?.tx_hash === "string" ? completed.sentRef.tx_hash : null;
+    }
     if (intent.reference) return intent.reference;
     const stored = await store.get(channelId);
     const current = readTempoSessionState(stored);
@@ -1177,30 +1231,41 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
     const pending = await config.hostedObligations?.pendingTempoClose(channelId, drainId);
     const selfHostedReport = !config.hostedObligations && !!config.onSessionSettlement && !!store.claimCloseReference && !!store.getCloseRecovery;
     let reference = pending?.txHash ?? void 0;
-    if (pending && !reference || selfHostedReport) {
+    if (pending && pending.state !== "unmatched" && !reference || selfHostedReport) {
       const recovery = await store.getCloseRecovery?.(channelId);
       const notBeforeMs = pending?.reservedAtMs ?? recovery?.updatedAtMs;
       if (notBeforeMs === void 0) throw new Error(`Tempo session close intent ${channelId} not found`);
       const obligations = config.hostedObligations;
-      const found = await findFinalizedClose(current, stored, drainId, notBeforeMs, pending ? {
-        from: pending.searchBefore,
-        save: (resumeAt) => obligations.recordTempoCloseSearch(pending.id, resumeAt)
-      } : {
-        from: recovery?.searchBefore ?? null,
-        save: (resumeAt) => store.recordCloseSearch?.(channelId, drainId, resumeAt)
-      });
+      const found = await findFinalizedClose(
+        current,
+        stored,
+        drainId,
+        notBeforeMs,
+        pending ? {
+          from: pending.searchBefore,
+          obligationId: pending.id,
+          save: (resumeAt) => obligations.recordTempoCloseSearch(pending.id, resumeAt)
+        } : {
+          from: recovery?.searchBefore ?? null,
+          save: (resumeAt) => store.recordCloseSearch?.(channelId, drainId, resumeAt)
+        },
+        TEMPO_CLOSE_POLL_SEARCH_BUDGET_MS
+      );
       if (pending) {
         reference = await settleUnsubmittedClose(current.channelId, drainId, pending.id, found);
       } else if (found.outcome === "ours") {
+        const client = await getClient({ chainId: current.chainId });
+        const { settledToPayee } = await chainOps.readChannelClose(client, current.channelId, found.txHash);
         const claimed = await store.claimCloseReference(channelId, drainId, found.txHash);
         if (claimed.claimed) {
-          await reportRecoveredClose(current, found.txHash, recovery?.settledBeforeClose ?? null);
+          await reportRecoveredClose(current, found.txHash, recovery?.settledBeforeClose ?? null, settledToPayee);
         }
         return claimed.reference;
       } else if (found.outcome === "none") {
         loggers.tempo.warn("tempo_session_close_recovery_unmatched", {
           channel_id: current.channelId,
-          drain_id: drainId
+          drain_id: drainId,
+          amount_at_stake_native: (current.highestVoucherAmount - (recovery?.settledBeforeClose ?? current.settledOnChain)).toString()
         });
       }
     }
@@ -1211,30 +1276,67 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
     );
     return recovered.reference;
   };
-  const findFinalizedClose = async (current, stored, drainId, notBeforeMs, cursor) => {
-    const client = await getClient({ chainId: current.chainId });
-    const search = await chainOps.findChannelClose(
-      client,
-      current.channelId,
-      current.escrowContract,
-      notBeforeMs,
-      cursor.from ?? void 0
-    );
-    if (search.outcome === "paused") {
-      await cursor.save(search.resumeAt);
-      loggers.tempo.warn("tempo_session_close_recovery_search_paused", {
-        channel_id: current.channelId,
-        drain_id: drainId,
-        resume_block: search.resumeAt.toString()
-      });
-      throw new Error(`Tempo close search for channel ${current.channelId} continues on the next poll`);
+  const findFinalizedClose = async (current, stored, drainId, notBeforeMs, cursor, budgetMs = TEMPO_CLOSE_SEARCH_BUDGET_MS) => {
+    const key = cursor.obligationId ?? JSON.stringify([current.chainId, current.escrowContract, current.channelId, drainId, notBeforeMs]);
+    const existing = finalizedCloseSearches.get(key);
+    if (existing) {
+      existing.deadline.atMs = Math.min(existing.deadline.atMs ?? Infinity, Date.now() + budgetMs);
+      return existing.promise;
     }
-    if (search.outcome === "closed") {
-      return cooperativeCloseSenders(stored, config.account.address).has(search.sender.toLowerCase()) ? { outcome: "ours", txHash: search.txHash } : { outcome: "exit" };
+    const deadline = {};
+    const backstopDeadlineMs = Date.now() + TEMPO_CLOSE_SEARCH_TIMEOUT_MS;
+    let expired = false;
+    const assertActive = () => {
+      if (expired) throw new Error("Tempo close search exceeded its deadline; retry this drain");
+    };
+    let timeout;
+    const work = (async () => {
+      const client = await getClient({ chainId: current.chainId });
+      assertActive();
+      deadline.atMs = Math.min(deadline.atMs ?? Infinity, Date.now() + budgetMs);
+      const search2 = await chainOps.findChannelClose(
+        client,
+        current.channelId,
+        current.escrowContract,
+        notBeforeMs,
+        cursor.from ?? void 0,
+        () => Math.min(
+          deadline.atMs ?? Infinity,
+          backstopDeadlineMs - TEMPO_CLOSE_CURSOR_SAVE_RESERVE_MS
+        )
+      );
+      assertActive();
+      if (search2.outcome === "paused") {
+        await cursor.save(search2.resumeAt);
+        assertActive();
+        loggers.tempo.warn("tempo_session_close_recovery_search_paused", {
+          channel_id: current.channelId,
+          drain_id: drainId,
+          resume_block: search2.resumeAt.toString()
+        });
+        throw new Error(`Tempo close search for channel ${current.channelId} continues on the next poll`);
+      }
+      if (search2.outcome === "closed") {
+        return cooperativeCloseSenders(stored, config.account.address).has(search2.sender.toLowerCase()) ? { outcome: "ours", txHash: search2.txHash } : { outcome: "exit" };
+      }
+      if (search2.outcome === "exit_requested") return { outcome: "exit" };
+      if (search2.stoppedAt !== void 0) await cursor.save(search2.stoppedAt);
+      assertActive();
+      return { outcome: "none", terminal: search2.stoppedAt !== void 0 };
+    })();
+    const search = Promise.race([work, new Promise((_resolve, reject) => {
+      timeout = setTimeout(() => {
+        expired = true;
+        reject(new Error("Tempo close search exceeded its deadline; retry this drain"));
+      }, TEMPO_CLOSE_SEARCH_TIMEOUT_MS);
+    })]);
+    finalizedCloseSearches.set(key, { promise: search, deadline });
+    try {
+      return await search;
+    } finally {
+      clearTimeout(timeout);
+      finalizedCloseSearches.delete(key);
     }
-    if (search.outcome === "exit_requested") return { outcome: "exit" };
-    if (search.stoppedAt !== void 0) await cursor.save(search.stoppedAt);
-    return { outcome: "none" };
   };
   const settleUnsubmittedClose = async (channelId, drainId, obligationId, found) => {
     const obligations = config.hostedObligations;
@@ -1247,16 +1349,20 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         loggers.tempo.warn("tempo_session_close_exit_resolved", {
           channel_id: channelId,
           drain_id: drainId,
-          obligation_id: obligationId
+          obligation_id: obligationId,
+          amount_at_stake_native: await obligations.tempoCloseAmountAtStake(obligationId)
         });
       }
       return void 0;
     }
-    loggers.tempo.warn("tempo_session_close_recovery_unmatched", {
-      channel_id: channelId,
-      drain_id: drainId,
-      obligation_id: obligationId
-    });
+    if (found.terminal && await obligations.markTempoCloseUnmatched(obligationId)) {
+      loggers.tempo.warn("tempo_session_close_recovery_unmatched", {
+        channel_id: channelId,
+        drain_id: drainId,
+        obligation_id: obligationId,
+        amount_at_stake_native: await obligations.tempoCloseAmountAtStake(obligationId)
+      });
+    }
     return void 0;
   };
   const reconcileUnsubmittedCloses = async () => {
@@ -1267,6 +1373,11 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         const stored = await store.get(row.channelId);
         const current = readTempoSessionState(stored);
         if (!current) continue;
+        const intent = await store.getClose?.(row.channelId);
+        if (intent?.drainId === row.drainId && isTempoCloseTransaction(intent.reference)) {
+          await obligations.recordSubmitted(row.id, intent.reference);
+          continue;
+        }
         if (!current.finalized) {
           const client = await getClient({ chainId: current.chainId });
           const [chainState] = await chainOps.getChannelStatesBatch(
@@ -1279,6 +1390,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         }
         const found = await findFinalizedClose(current, stored, row.drainId, row.reservedAtMs, {
           from: row.searchBefore,
+          obligationId: row.id,
           save: (resumeAt) => obligations.recordTempoCloseSearch(row.id, resumeAt)
         });
         await settleUnsubmittedClose(current.channelId, row.drainId, row.id, found);
@@ -1292,13 +1404,164 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       }
     }
   };
-  const reportRecoveredClose = async (channel, txHash, settledBeforeClose) => {
-    const client = await getClient({ chainId: channel.chainId });
-    const { settledToPayee } = await chainOps.readChannelClose(client, channel.channelId, txHash);
+  const reconcileFinalizedDrain = async (drain, recoverPending = false) => {
+    const ledger = creditLedger;
+    if (!ledger || !finalizeDrain || !drain.channelId) return { outcome: "open" };
+    const searchBudgetMs = recoverPending ? TEMPO_CLOSE_POLL_SEARCH_BUDGET_MS : TEMPO_CLOSE_SEARCH_BUDGET_MS;
+    try {
+      const stored = await store.get(drain.channelId);
+      const current = readTempoSessionState(stored);
+      if (!current) throw new Error("Channel history is unavailable");
+      const client = await getClient({ chainId: current.chainId });
+      const recovery = await store.getCloseRecovery?.(drain.channelId);
+      const pending = await config.hostedObligations?.pendingTempoClose(drain.channelId, drain.drainId);
+      const intent = await store.getClose?.(drain.channelId);
+      const recorded = intent?.drainId === drain.drainId && isTempoCloseTransaction(intent.reference) ? intent.reference : await config.hostedObligations?.tempoCloseTransaction(drain.channelId, drain.drainId);
+      const txHash = recorded ?? pending?.txHash;
+      let receipt = isTempoCloseTransaction(txHash) ? await chainOps.readChannelClose(client, current.channelId, txHash) : void 0;
+      const chainState = receipt ? { deposit: 0n, settled: receipt.settledToPayee, closeRequestedAt: 0 } : (await chainOps.getChannelStatesBatch(client, [current.channelId], current.escrowContract))[0];
+      if (!chainState || chainState.deposit !== 0n) return { outcome: "open" };
+      await terminalizeLostBacking(current, chainState);
+      await writeBackChainState(current, chainState);
+      let found = receipt ? { outcome: "ours", txHash } : void 0;
+      if (found?.outcome === "ours" && pending) {
+        await config.hostedObligations.recordSubmitted(pending.id, found.txHash);
+      }
+      if (!found && pending && !pending.txHash) {
+        if (pending.state === "unmatched") throw new TempoDrainRefundUnprovenError("close_history_unmatched", "Close history requires an operator retry");
+        if (!recoverPending) return { outcome: "open" };
+        found = await findFinalizedClose(current, stored, drain.drainId, pending.reservedAtMs, {
+          from: pending.searchBefore,
+          obligationId: pending.id,
+          save: (resumeAt) => config.hostedObligations.recordTempoCloseSearch(pending.id, resumeAt)
+        }, searchBudgetMs);
+        await settleUnsubmittedClose(current.channelId, drain.drainId, pending.id, found);
+        if (found.outcome === "none" && found.terminal) {
+          throw new TempoDrainRefundUnprovenError("close_history_unmatched", "Close history requires an operator retry");
+        }
+      }
+      found ??= pending?.txHash ? { outcome: "ours", txHash: pending.txHash } : await findFinalizedClose(current, stored, drain.drainId, drain.createdAt, {
+        from: recovery?.searchBefore ?? null,
+        save: (resumeAt) => store.recordCloseSearch?.(drain.channelId, drain.drainId, resumeAt)
+      }, searchBudgetMs);
+      if (found.outcome === "none" && !found.terminal) {
+        throw new Error("Tempo close evidence is not yet available; retry this drain");
+      }
+      let refundedNative;
+      let reference;
+      if (found.outcome === "ours") {
+        reference = found.txHash;
+        receipt ??= await chainOps.readChannelClose(client, current.channelId, found.txHash);
+        refundedNative = receipt.refundedToPayer;
+        if (!config.hostedObligations && config.onSessionSettlement && store.claimCloseReference) {
+          const claimed = await store.claimCloseReference(drain.channelId, drain.drainId, found.txHash);
+          if (claimed.claimed) {
+            await reportRecoveredClose(current, found.txHash, recovery?.settledBeforeClose ?? null, receipt.settledToPayee);
+          }
+        }
+      } else if (found.outcome === "exit") {
+        const snapshot = stored;
+        const deposit = typeof snapshot.depositBeforeFinalization === "bigint" ? snapshot.depositBeforeFinalization : current.deposit;
+        if (deposit <= 0n) throw new TempoDrainRefundUnprovenError("collateral_missing", "The pre-exit collateral is unavailable");
+        refundedNative = deposit - maxBigInt(current.settledOnChain, chainState.settled);
+        reference = `channel:${current.channelId}`;
+      } else {
+        if (!config.hostedObligations && config.onSessionSettlement) {
+          loggers.tempo.warn("tempo_session_close_recovery_unmatched", {
+            channel_id: current.channelId,
+            drain_id: drain.drainId,
+            amount_at_stake_native: (current.highestVoucherAmount - (recovery?.settledBeforeClose ?? current.settledOnChain)).toString()
+          });
+        }
+        throw new TempoDrainRefundUnprovenError("close_evidence_missing", "Channel finalization has no matching refund evidence");
+      }
+      if (drain.drainedNative === null || refundedNative < BigInt(drain.drainedNative)) {
+        throw new TempoDrainRefundUnprovenError("refund_short", "Proven refund is below the drain debit");
+      }
+      const creditUnbacked = (await ledger.get(drain.creditId))?.status === "unbacked";
+      await store.confirmClose?.(drain.channelId, drain.drainId, reference);
+      const changed = await finalizeDrain(drain, {
+        reference,
+        refundedNative,
+        outcome: found.outcome === "ours" ? "cooperative_close" : "payer_exit",
+        creditUnbacked
+      });
+      if (changed) {
+        loggers.tempo.warn(creditUnbacked ? "tempo_session_drain_unbacked_resolved" : "tempo_session_drain_finalized", {
+          channel_id: drain.channelId,
+          credit_id: drain.creditId,
+          drain_id: drain.drainId,
+          amount_at_stake_native: drain.drainedNative.toString(),
+          refund_native: refundedNative.toString(),
+          builder_loss_native: (current.highestVoucherAmount > maxBigInt(current.settledOnChain, chainState.settled) ? current.highestVoucherAmount - maxBigInt(current.settledOnChain, chainState.settled) : 0n).toString()
+        });
+      }
+      return { outcome: "completed" };
+    } catch (error) {
+      let failure = error;
+      if (error instanceof TempoDrainRefundUnprovenError) {
+        try {
+          await store.update(drain.channelId, (current) => {
+            if (!isStateRecord(current)) throw new Error("Channel history is unavailable");
+            const key = JSON.stringify([drain.creditId, drain.drainId, error.reason]);
+            const seen = Array.isArray(current.drainRefundWarnings) ? current.drainRefundWarnings : [];
+            if (seen.includes(key)) return { op: "noop", result: false };
+            loggers.tempo.warn("tempo_session_drain_refund_unproven", {
+              channel_id: drain.channelId,
+              credit_id: drain.creditId,
+              drain_id: drain.drainId,
+              amount_at_stake_native: drain.drainedNative?.toString() ?? null,
+              amount_at_stake_micro: drain.amountMicro,
+              currency: drain.currency,
+              reason: error.reason,
+              error: error.message
+            });
+            return { op: "set", value: { ...current, drainRefundWarnings: [...seen, key] }, result: true };
+          });
+          return { outcome: "refund_unproven" };
+        } catch (claimError) {
+          failure = claimError;
+        }
+      }
+      loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+        channel_id: drain.channelId,
+        credit_id: drain.creditId,
+        drain_id: drain.drainId,
+        error: failure instanceof Error ? failure.message : String(failure)
+      });
+      return { outcome: "retryable_failure", error: failure };
+    }
+  };
+  const reconcileFinalizedDrains = async () => {
+    const ledger = creditLedger;
+    if (!ledger || !finalizeDrain) return;
+    let after;
+    do {
+      const page = await ledger.listChannelDrains({
+        limit: 100,
+        after,
+        createdBeforeMs: Date.now(),
+        rail: "tempo",
+        includeResolved: true
+      });
+      for (const drain of page) {
+        if (drain.status !== "exit_required" || !drain.channelId) continue;
+        await reconcileFinalizedDrain(drain);
+      }
+      const last = page.at(-1);
+      after = page.length === 100 && last ? { createdAt: last.createdAt, creditId: last.creditId, drainId: last.drainId } : void 0;
+    } while (after);
+  };
+  const reconcileTempoSessionCloses = async () => {
+    await reconcileUnsubmittedCloses();
+    await reconcileFinalizedDrains();
+  };
+  const reportRecoveredClose = async (channel, txHash, settledBeforeClose, settledToPayee) => {
     if (settledBeforeClose === null || settledToPayee < settledBeforeClose) {
       loggers.tempo.warn("tempo_session_close_settlement_unreported", {
         channel_id: channel.channelId,
-        tx_hash: txHash
+        tx_hash: txHash,
+        amount_at_stake_native: settledToPayee.toString()
       });
       return;
     }
@@ -1314,6 +1577,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       loggers.tempo.warn("tempo_session_close_settlement_callback_failed", {
         channel_id: channel.channelId,
         tx_hash: txHash,
+        amount_at_stake_native: (settledToPayee - settledBeforeClose).toString(),
         error: error instanceof Error ? error.message : String(error)
       });
     }
@@ -1326,7 +1590,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
   const confirmClose = store.confirmClose?.bind(store);
   return Object.assign(mppx, {
     sweepTempoSessions,
-    ...config?.hostedObligations && { reconcileTempoSessionCloses: reconcileUnsubmittedCloses },
+    ...config?.hostedObligations && { reconcileTempoSessionCloses },
     ...beginClose && {
       beginTempoSessionClose: async (channelId, drainId) => {
         await beginClose(channelId, drainId);
@@ -1412,11 +1676,15 @@ function advertisedMethods(mppx) {
 var _testing = {
   attachTempoSessionRuntime
 };
+function isTempoCloseTransaction(reference) {
+  return typeof reference === "string" && /^0x[0-9a-fA-F]{64}$/.test(reference);
+}
 
 export {
   TEMPO_SETTLEMENT_DEFAULT_LOW_BALANCE_MICRO,
   TempoSettlementReadiness,
   isTempoInsufficientFundsError,
+  TempoCloseDescriptorError,
   MPPX_HMAC_MISMATCH_REASON,
   TEMPO_SETTLEMENT_LEASE_FIELD,
   TEMPO_SETTLEMENT_LEASE_OWNER_FIELD,