@dvmkit/sdk 0.10.0 → 0.11.0-rc.1

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

@@ -1,9 +1,9 @@
 import {
   loggers
-} from "./chunk-M3T5JYDJ.js";
+} from "./chunk-HNXMWHLU.js";
 import {
   diagnosticConsole
-} from "./chunk-QGNXYVBO.js";
+} from "./chunk-Z4FOPROB.js";
 
 // src/sdk/server/mpp-setup.ts
 import { createHash, randomUUID } from "crypto";
@@ -858,31 +858,186 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
   const getClient = config?.getClient;
   const listActive = store?.listActive;
   if (!config || !getClient || !store) return mppx;
-  const terminalizeLostBacking = async (channel, chainState) => {
-    if (chainState.deposit !== 0n) return;
-    if (!creditLedger) return;
+  const retainRefundEvidence = async (drain, refundedNative, payerExit) => {
+    try {
+      if (payerExit) {
+        if (refundedNative > 0n) {
+          if (!creditLedger?.recordTempoDrainPayment) throw new Error("Tempo drain payment evidence persistence is unavailable");
+          await creditLedger.recordTempoDrainPayment({ creditId: drain.creditId, drainId: drain.drainId });
+        }
+      } else {
+        if (!creditLedger?.recordTempoDrainRefund) throw new Error("Tempo drain refund evidence persistence is unavailable");
+        await creditLedger.recordTempoDrainRefund({ creditId: drain.creditId, drainId: drain.drainId, refundedNative });
+      }
+    } catch (error) {
+      loggers.tempo.warn("tempo_drain_refund_evidence_write_failed", { amount_micro: drain.amountMicro });
+      throw error;
+    }
+  };
+  const nextDrainCursor = (page, after) => {
+    const last = page.at(-1);
+    if (page.length < 100 || !last) return void 0;
+    const next = { createdAt: last.createdAt, creditId: last.creditId, drainId: last.drainId };
+    if (after && !(next.createdAt > after.createdAt || next.createdAt === after.createdAt && (next.creditId > after.creditId || next.creditId === after.creditId && next.drainId > after.drainId))) {
+      throw new Error("Tempo drain pagination cursor did not advance");
+    }
+    return next;
+  };
+  const resolveChannelDrainProof = async (channel, chainState, proof) => {
+    const ledger = creditLedger;
+    const key = channel.channelId.toLowerCase();
+    const matches = [];
+    let after;
+    const createdBeforeMs = Date.now();
+    do {
+      const page = await ledger.listChannelDrains({
+        limit: 100,
+        after,
+        createdBeforeMs,
+        rail: "tempo",
+        includeWrittenOff: true
+      });
+      const next = nextDrainCursor(page, after);
+      for (const drain of page) {
+        if (drain.method !== "tempo" || drain.channelId?.toLowerCase() !== key || drain.status !== "pending" && drain.status !== "exit_required" || drain.operatorDecision) continue;
+        const credit = await ledger.get(drain.creditId);
+        if (credit?.tempoChannelId?.toLowerCase() !== key) throw new Error("Tempo drain channel does not match its credit");
+        matches.push(drain);
+      }
+      after = next;
+    } while (after);
+    if (!matches.length) return;
+    const intent = await store.getClose?.(key);
+    const matching = intent ? matches.filter((drain) => intent.channelId.toLowerCase() === key && drain.drainId === intent.drainId) : matches;
+    if (matching.length !== 1) throw new Error("Tempo close proof has no unique matching open drain");
+    if (proof.outcome === "ours") {
+      return { drain: matching[0], refundedNative: proof.receipt.refundedToPayer, payerExit: false };
+    } else {
+      const stored = await store.get(key);
+      const deposit = isStateRecord(stored) && typeof stored.depositBeforeFinalization === "bigint" ? stored.depositBeforeFinalization : channel.deposit;
+      return { drain: matching[0], refundedNative: deposit - maxBigInt(channel.settledOnChain, chainState.settled), payerExit: true };
+    }
+  };
+  const protectFinalizedBacking = async (channel, chainState, proof, classifying = true) => {
+    await store.update(channel.channelId.toLowerCase(), (value) => {
+      const active = readTempoSessionState(value);
+      if (!active || !isStateRecord(value)) throw new Error("Tempo finalized channel state is unavailable");
+      return { op: "set", value: {
+        ...value,
+        finalized: true,
+        deposit: 0n,
+        closeRequestedAt: 0n,
+        creditLossPending: classifying || !active.finalized || value.creditLossPending === true,
+        ...!active.finalized && { depositBeforeFinalization: active.deposit },
+        settledOnChain: maxBigInt(active.settledOnChain, chainState.settled),
+        // Publish positive payment and finalization together. The operator's
+        // channel lock then sees payment even if the drain writer fails.
+        ...proof && proof.refundedNative > 0n && { tempoDrainPaymentObservation: {
+          creditId: proof.drain.creditId,
+          drainId: proof.drain.drainId
+        } }
+      }, result: void 0 };
+    });
+  };
+  const deferHostedCloseSearch = async (channel) => {
+    const obligations = config.hostedObligations;
+    if (!obligations) return false;
+    const key = channel.channelId.toLowerCase();
+    const intent = await store.getClose?.(key);
+    if (isTempoCloseTransaction(intent?.reference)) return false;
+    const pending = await obligations.findPendingTempo(key, "close");
+    if (pending?.state !== "unmatched" || isTempoCloseTransaction(pending.tx_hash) || pending.rail !== "tempo" || pending.operation !== "close" || pending.channel_id.toLowerCase() !== key || pending.network !== `eip155:${channel.chainId}` || pending.contract.toLowerCase() !== channel.escrowContract.toLowerCase() || typeof pending.original.drainId !== "string" || !pending.original.drainId) return false;
+    if (intent && intent.drainId !== pending.original.drainId) return false;
+    return !isTempoCloseTransaction(await obligations.tempoCloseTransaction(key, pending.original.drainId));
+  };
+  const terminalizeLostBacking = async (channel, chainState, proof) => {
+    if (chainState.deposit !== 0n || !creditLedger) return;
     const ledger = creditLedger;
+    const key = channel.channelId.toLowerCase();
+    let resolved = proof;
+    const headroom = channel.highestVoucherAmount - maxBigInt(channel.settledOnChain, chainState.settled);
+    if (!resolved && headroom > 0n) {
+      try {
+        const stored = await store.get(key);
+        const intent = await store.getClose?.(key);
+        const reference = intent && (isTempoCloseTransaction(intent.reference) ? intent.reference : await config.hostedObligations?.tempoCloseTransaction(key, intent.drainId));
+        if (isTempoCloseTransaction(reference)) {
+          const client = await getClient({ chainId: channel.chainId });
+          resolved = { outcome: "ours", receipt: await chainOps.readChannelClose(client, channel.channelId, reference) };
+        } else if (!await deferHostedCloseSearch(channel)) {
+          const client = await getClient({ chainId: channel.chainId });
+          const snapshot = isStateRecord(stored) ? stored : {};
+          const before = typeof snapshot.creditLossSearchBefore === "bigint" ? snapshot.creditLossSearchBefore : void 0;
+          const createdAt = channel.createdAt ? Date.parse(channel.createdAt) : 0;
+          const search = await chainOps.findChannelClose(
+            client,
+            channel.channelId,
+            channel.escrowContract,
+            Number.isFinite(createdAt) ? createdAt : 0,
+            before,
+            Date.now() + TEMPO_CLOSE_POLL_SEARCH_BUDGET_MS
+          );
+          if (search.outcome === "closed") {
+            resolved = cooperativeCloseSenders(stored, config.account.address).has(search.sender.toLowerCase()) ? { outcome: "ours", receipt: await chainOps.readChannelClose(client, channel.channelId, search.txHash) } : { outcome: "exit" };
+          } else if (search.outcome === "exit_requested") {
+            resolved = { outcome: "exit" };
+          } else if (search.outcome === "paused") {
+            await store.update(key, (value) => isStateRecord(value) ? { op: "set", value: { ...value, creditLossSearchBefore: search.resumeAt }, result: void 0 } : { op: "noop", result: void 0 });
+          } else if (before !== void 0) {
+            await store.update(key, (value) => isStateRecord(value) ? { op: "set", value: Object.fromEntries(Object.entries(value).filter(([field]) => field !== "creditLossSearchBefore")), result: void 0 } : { op: "noop", result: void 0 });
+          }
+        }
+      } catch (error) {
+        loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+          channel_id: key,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    const pending = !resolved && headroom > 0n;
+    let drainProof;
+    try {
+      if (resolved) drainProof = await resolveChannelDrainProof(channel, chainState, resolved);
+    } finally {
+      await protectFinalizedBacking(channel, chainState, drainProof);
+    }
+    if (drainProof) await retainRefundEvidence(drainProof.drain, drainProof.refundedNative, drainProof.payerExit);
+    if (pending) return;
+    const refundedNative = resolved?.outcome === "ours" ? resolved.receipt.refundedToPayer : 0n;
     const retire = async (lifecycle, tx) => {
-      const settledOnChain = maxBigInt(lifecycle.settledOnChain, chainState.settled);
-      if (lifecycle.highestVoucherAmount <= settledOnChain) return;
-      await ledger.terminalizeTempoCredits(
-        {
-          channelId: channel.channelId,
-          settledOnChainNative: settledOnChain,
-          highestVoucherNative: lifecycle.highestVoucherAmount,
-          consumedNative: lifecycle.spent
-        },
-        tx
+      const settledOnChainNative = maxBigInt(
+        maxBigInt(lifecycle.settledOnChain, chainState.settled),
+        resolved?.outcome === "ours" ? resolved.receipt.settledToPayee : 0n
       );
+      if (!resolved && lifecycle.highestVoucherAmount > settledOnChainNative) return;
+      const lossNative = maxBigInt(0n, (resolved?.outcome === "exit" ? lifecycle.spent : lifecycle.highestVoucherAmount) - settledOnChainNative - refundedNative);
+      const closeAware = ledger.tempoCreditLossEvidenceVersion === 1;
+      if (lossNative > 0n && !closeAware) return;
+      const candidates2 = lossNative > 0n ? await ledger.terminalizeTempoCredits({
+        channelId: key,
+        settledOnChainNative,
+        highestVoucherNative: lifecycle.highestVoucherAmount,
+        consumedNative: lifecycle.spent,
+        ...resolved?.outcome === "ours" && { closeKind: "cooperative_close", refundedToPayerNative: refundedNative },
+        ...resolved?.outcome === "exit" && { closeKind: "payer_exit" }
+      }, tx) : closeAware ? await ledger.listTempoCreditLosses({ channelId: key, limit: 1e3 }, tx) : void 0;
+      return { settledOnChainNative, refundedNative, lossNative, losses: candidates2 };
     };
-    if (store.withFinalizedCreditLoss) {
-      await store.withFinalizedCreditLoss(
-        channel.channelId,
-        (tx, lifecycle) => retire(lifecycle, tx)
-      );
+    const result = store.withFinalizedCreditLoss ? await store.withFinalizedCreditLoss(key, (tx, lifecycle) => retire(lifecycle, tx)) : await retire(channel);
+    if (!result) return;
+    let candidates = result.losses;
+    try {
+      candidates ??= await ledger.listTempoCreditLosses({ channelId: key, limit: 1e3 });
+    } catch (error) {
+      loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+        channel_id: key,
+        error: error instanceof Error ? error.message : String(error)
+      });
       return;
     }
-    await retire(channel);
+    const losses = candidates.filter((loss) => loss.channelId.toLowerCase() === key);
+    await store.update(key, (value) => isStateRecord(value) ? { op: "set", value: { ...value, creditLossPending: false }, result: void 0 } : { op: "noop", result: void 0 });
+    return { ...result, losses };
   };
   const getTempoSessionDrainState = async (channelId) => {
     const normalized = channelId.toLowerCase();
@@ -1074,11 +1229,19 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         [channel.channelId],
         channel.escrowContract
       );
-      await terminalizeLostBacking(channel, chainState);
+      const backing = await terminalizeLostBacking(channel, chainState);
       const chainFinalized = await writeBackChainState(channel, chainState);
-      const settledOnChain = maxBigInt(channel.settledOnChain, chainState.settled);
+      const settledOnChain = maxBigInt(
+        maxBigInt(channel.settledOnChain, chainState.settled),
+        backing?.settledOnChainNative ?? 0n
+      );
       if (chainFinalized) {
-        const owed = channel.highestVoucherAmount - settledOnChain;
+        if (!backing && creditLedger) return {
+          outcome: "retryable_failure",
+          channelId: normalized,
+          error: "Finalized channel loss evidence or ledger capability is unavailable; retry reconciliation"
+        };
+        const owed = backing?.lossNative ?? channel.highestVoucherAmount - settledOnChain;
         return owed > 0n ? {
           outcome: "finalized_before_protection",
           channelId: normalized,
@@ -1160,10 +1323,22 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
     for (const row of rows) {
       const state = readTempoSessionState(row.state);
       if (!state) continue;
-      const groupKey = `${state.chainId}:${state.escrowContract.toLowerCase()}`;
-      const group = groups.get(groupKey) ?? [];
-      group.push(state);
-      groups.set(groupKey, group);
+      try {
+        if (creditLedger && state.finalized && state.highestVoucherAmount > state.settledOnChain && await deferHostedCloseSearch(state)) {
+          inFlight += 1;
+          continue;
+        }
+        const groupKey = `${state.chainId}:${state.escrowContract.toLowerCase()}`;
+        const group = groups.get(groupKey) ?? [];
+        group.push(state);
+        groups.set(groupKey, group);
+      } catch (error) {
+        inFlight += 1;
+        loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+          channel_id: state.channelId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
     }
     for (const groupedChannels of groups.values()) {
       for (let offset = 0; offset < groupedChannels.length; offset += 100) {
@@ -1176,26 +1351,41 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
           first.escrowContract
         );
         for (const [index, channel] of channels.entries()) {
-          const chainState = chainStates[index];
-          await terminalizeLostBacking(channel, chainState);
-          const chainFinalized = await writeBackChainState(channel, chainState);
-          const forcedClose = !chainFinalized && BigInt(chainState.closeRequestedAt) !== 0n;
-          if (forcedClose) closeRequested += 1;
-          if (!tempoSettlementDue({
-            channel,
-            chainSettled: chainState.settled,
-            forcedClose,
-            intervalMs: config.settlementSchedule?.intervalMs
-          })) {
-            continue;
+          try {
+            const chainState = chainStates[index];
+            await terminalizeLostBacking(channel, chainState);
+            const chainFinalized = await writeBackChainState(channel, chainState);
+            const forcedClose = !chainFinalized && BigInt(chainState.closeRequestedAt) !== 0n;
+            if (forcedClose) closeRequested += 1;
+            if (!tempoSettlementDue({
+              channel,
+              chainSettled: chainState.settled,
+              forcedClose,
+              intervalMs: config.settlementSchedule?.intervalMs
+            })) {
+              continue;
+            }
+            const result = await settleChannel(channel.channelId, client, chainState.settled, forcedClose);
+            if (result.outcome === "settled") settled += 1;
+            else if (result.outcome === "retryable_failure") inFlight += 1;
+          } catch (error) {
+            inFlight += 1;
+            loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+              channel_id: channel.channelId,
+              error: error instanceof Error ? error.message : String(error)
+            });
           }
-          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 reconcileTempoSessionCloses();
+    try {
+      await reconcileTempoSessionCloses();
+    } catch (error) {
+      inFlight += 1;
+      loggers.tempo.warn("tempo_session_close_reconcile_failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
     return { scanned: rows.length, closeRequested, settled, inFlight };
   };
   const recoverTempoSessionClose = async (channelId, drainId, creditId) => {
@@ -1228,6 +1418,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       finalized = chainState.deposit === 0n;
     }
     if (!finalized) return null;
+    if (current.finalized) await terminalizeLostBacking(current, { deposit: 0n, settled: current.settledOnChain });
     const pending = await config.hostedObligations?.pendingTempoClose(channelId, drainId);
     const selfHostedReport = !config.hostedObligations && !!config.onSessionSettlement && !!store.claimCloseReference && !!store.getCloseRecovery;
     let reference = pending?.txHash ?? void 0;
@@ -1388,6 +1579,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
           await terminalizeLostBacking(current, chainState);
           if (!await writeBackChainState(current, chainState)) continue;
         }
+        if (current.finalized) await terminalizeLostBacking(current, { deposit: 0n, settled: current.settledOnChain });
         const found = await findFinalizedClose(current, stored, row.drainId, row.reservedAtMs, {
           from: row.searchBefore,
           obligationId: row.id,
@@ -1421,9 +1613,8 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       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;
+      await protectFinalizedBacking(current, chainState, receipt ? { drain, refundedNative: receipt.refundedToPayer } : void 0, receipt !== void 0);
+      let found = receipt && isTempoCloseTransaction(txHash) ? { outcome: "ours", txHash } : void 0;
       if (found?.outcome === "ours" && pending) {
         await config.hostedObligations.recordSubmitted(pending.id, found.txHash);
       }
@@ -1449,10 +1640,17 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       }
       let refundedNative;
       let reference;
+      let backing;
       if (found.outcome === "ours") {
         reference = found.txHash;
         receipt ??= await chainOps.readChannelClose(client, current.channelId, found.txHash);
         refundedNative = receipt.refundedToPayer;
+        await protectFinalizedBacking(current, chainState, { drain, refundedNative });
+        await retainRefundEvidence(drain, refundedNative, false);
+        backing = await terminalizeLostBacking(current, chainState, { outcome: "ours", receipt });
+        if (!backing) {
+          throw new Error("Tempo close-aware loss classification is unavailable; upgrade the ledger and retry");
+        }
         if (!config.hostedObligations && config.onSessionSettlement && store.claimCloseReference) {
           const claimed = await store.claimCloseReference(drain.channelId, drain.drainId, found.txHash);
           if (claimed.claimed) {
@@ -1462,8 +1660,17 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       } 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");
+        if (deposit <= 0n) {
+          await terminalizeLostBacking(current, chainState, { outcome: "exit" });
+          throw new TempoDrainRefundUnprovenError("collateral_missing", "The pre-exit collateral is unavailable");
+        }
         refundedNative = deposit - maxBigInt(current.settledOnChain, chainState.settled);
+        await protectFinalizedBacking(current, chainState, { drain, refundedNative });
+        await retainRefundEvidence(drain, refundedNative, true);
+        backing = await terminalizeLostBacking(current, chainState, { outcome: "exit" });
+        if (!backing) {
+          throw new Error("Tempo close-aware loss classification is unavailable; upgrade the ledger and retry");
+        }
         reference = `channel:${current.channelId}`;
       } else {
         if (!config.hostedObligations && config.onSessionSettlement) {
@@ -1479,6 +1686,8 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
         throw new TempoDrainRefundUnprovenError("refund_short", "Proven refund is below the drain debit");
       }
       const creditUnbacked = (await ledger.get(drain.creditId))?.status === "unbacked";
+      const retainedLoss = backing?.losses.find((loss) => loss.creditId === drain.creditId);
+      const builderLossNative = retainedLoss?.lossNative ?? (retainedLoss ? maxBigInt(0n, retainedLoss.highestVoucherNative - retainedLoss.settledOnChainNative - (retainedLoss.refundedToPayerNative ?? 0n)) : 0n);
       await store.confirmClose?.(drain.channelId, drain.drainId, reference);
       const changed = await finalizeDrain(drain, {
         reference,
@@ -1493,7 +1702,7 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
           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()
+          builder_loss_native: builderLossNative.toString()
         });
       }
       return { outcome: "completed" };
@@ -1501,6 +1710,11 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
       let failure = error;
       if (error instanceof TempoDrainRefundUnprovenError) {
         try {
+          try {
+            await ledger.recordTempoDrainHold?.({ creditId: drain.creditId, drainId: drain.drainId, reason: error.reason });
+          } catch {
+            loggers.tempo.warn("tempo_drain_hold_reason_write_failed", { amount_micro: drain.amountMicro });
+          }
           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]);
@@ -1536,20 +1750,21 @@ function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
     const ledger = creditLedger;
     if (!ledger || !finalizeDrain) return;
     let after;
+    const createdBeforeMs = Date.now();
     do {
       const page = await ledger.listChannelDrains({
         limit: 100,
         after,
-        createdBeforeMs: Date.now(),
+        createdBeforeMs,
         rail: "tempo",
         includeResolved: true
       });
+      const next = nextDrainCursor(page, after);
       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;
+      after = next;
     } while (after);
   };
   const reconcileTempoSessionCloses = async () => {