@unicitylabs/sphere-sdk 0.14.1-dev.1 → 0.14.1-dev.2

package/dist/index.js

@@ -11100,7 +11100,10 @@ var STORE_KEYS = {
   shortfalls: "shortfalls",
   settlingLinks: "settling",
   streamCursor: (s) => `cursor:${s}`,
-  epochLatch: "epoch-latch"
+  epochLatch: "epoch-latch",
+  // §5.2 InventoryView durable overlays (#625/#679).
+  suspectedSpent: "suspected-spent",
+  knownSpends: "known-spends"
 };
 
 // modules/payments-v2/machine/journal.ts
@@ -11350,7 +11353,7 @@ var TransferMachine = class {
     }
     if (cls === null) {
       await this.applyCommitted(engine, plan.transferId, committed);
-      this.closeTail(plan.transferId, plan.payload);
+      this.closeTail(engine, plan.transferId, plan.payload, committed);
       return { committed, deliveryPending };
     }
     if (cls === "conflict" && committed.length > 0) {
@@ -11376,10 +11379,10 @@ var TransferMachine = class {
     }
     await this.applyCommitted(engine, r.transferId, committed);
     if (conflicts.length > 0) {
-      return { deliveryPending, partial: await this.settlePartial(r, committed, conflicts) };
+      return { deliveryPending, partial: await this.settlePartial(engine, r, committed, conflicts) };
     }
     await this.completeIntent(r.transferId, r.payload);
-    await this.finishBookkeeping(r.transferId, r.payload, "resumed");
+    await this.finishBookkeeping(engine, r.transferId, r.payload, "resumed", committed);
     return { deliveryPending, partial: null };
   }
   // ── shared transitions ─────────────────────────────────────────────────────
@@ -11561,7 +11564,7 @@ var TransferMachine = class {
     }
     return added;
   }
-  async settlePartial(r, committed, conflicts) {
+  async settlePartial(engine, r, committed, conflicts) {
     const undelivered = conflicts.reduce((sum, c) => sum + c.amount, 0n);
     const entry = {
       transferId: r.transferId,
@@ -11573,26 +11576,27 @@ var TransferMachine = class {
     };
     await this.stores.shortfalls.upsert(entry);
     await this.completeIntent(r.transferId, r.payload);
-    await this.finishBookkeeping(r.transferId, r.payload, "resumed");
+    await this.finishBookkeeping(engine, r.transferId, r.payload, "resumed", committed);
     return entry;
   }
-  closeTail(transferId, payload) {
+  closeTail(engine, transferId, payload, committed) {
     void (async () => {
       try {
         await this.completeIntent(transferId, payload);
       } catch {
         return;
       }
-      await this.finishBookkeeping(transferId, payload, "sent");
+      await this.finishBookkeeping(engine, transferId, payload, "sent", committed);
     })();
   }
   async completeIntent(transferId, payload) {
     const signature = payload.split !== void 0 ? await this.deps.signComplete(transferId) : void 0;
     await this.deps.intents.complete(transferId, signature);
   }
-  async finishBookkeeping(transferId, payload, phase) {
+  async finishBookkeeping(engine, transferId, payload, phase, committed) {
     try {
-      await this.deps.recordHistory?.({ transferId, payload, phase });
+      const committedAmount = await this.settledAmount(engine, payload.coinId, committed);
+      await this.deps.recordHistory?.({ transferId, payload, phase, committedAmount });
     } catch {
     }
     try {
@@ -11600,6 +11604,26 @@ var TransferMachine = class {
     } catch {
     }
   }
+  /**
+   * §5.9: SENT history records what SETTLED, never the plan — the value of the
+   * certified recipient blobs (summarize()'s committed set is the only source;
+   * a journal-rehydrated resume leg has no source token, but every committed
+   * leg carries its recipient blob, so the outcome-derived rule is uniform).
+   */
+  async settledAmount(engine, coinId, committed) {
+    let total = 0n;
+    for (const outcome of committed) {
+      if (outcome.recipientBlob === void 0) continue;
+      const token = await engine.decodeToken({
+        v: TOKEN_BLOB_VERSION,
+        network: 0,
+        tokenId: "",
+        token: outcome.recipientBlob
+      });
+      total += engine.balanceOf(token, coinId);
+    }
+    return total.toString();
+  }
   async disposeOnFailure(transferId, committed, cls) {
     if (committed.length > 0 || cls === "keep-open") return;
     try {
@@ -11624,7 +11648,7 @@ function conflictAmount(engine, payload, op, source) {
 }
 
 // modules/payments-v2/machine/resume.ts
-async function resumeAll(deps) {
+async function resumeAll(deps, options = {}) {
   const report = { resumed: [], conflicted: [], failed: [] };
   const stores = createMachineStores(deps.kv);
   const open = await deps.intents.listOpen();
@@ -11634,7 +11658,12 @@ async function resumeAll(deps) {
   } catch {
     return report;
   }
-  await dropStaleLocalAborts(stores, locals, new Set(open.map((i) => i.transferId)));
+  await dropStaleBackstops(
+    stores,
+    locals,
+    new Set(open.map((i) => i.transferId)),
+    options.isLocallyActive ?? (() => false)
+  );
   const jobs = await gateAndDecode(deps, stores, open, locals, report);
   const ctx = {
     deps,
@@ -11647,11 +11676,16 @@ async function resumeAll(deps) {
   }
   return report;
 }
-async function dropStaleLocalAborts(stores, locals, openIds) {
+async function dropStaleBackstops(stores, locals, openIds, isLocallyActive) {
   for (const entry of locals.values()) {
-    if (entry.disposition !== "open" && !openIds.has(entry.transferId)) {
+    if (openIds.has(entry.transferId)) continue;
+    if (entry.disposition !== "open") {
       await stores.backstop.removeByKey(entry.transferId);
+      continue;
     }
+    if (isLocallyActive(entry.transferId)) continue;
+    if ((await stores.deliveryJournal.byTransfer(entry.transferId)).size > 0) continue;
+    await stores.backstop.removeByKey(entry.transferId);
   }
 }
 async function gateAndDecode(deps, stores, open, locals, report) {
@@ -11859,7 +11893,9 @@ var Converger = class {
     return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mints.length > 0;
   }
   async resumePass() {
-    const report = await resumeAll(this.filteredMachineDeps());
+    const report = await resumeAll(this.filteredMachineDeps(), {
+      isLocallyActive: (id) => this.deps.isActiveOp(id)
+    });
     const progress = report.resumed.length > 0 || report.conflicted.length > 0;
     await this.deps.reconcile({
       resumed: report.resumed,
@@ -11975,6 +12011,136 @@ function distinctOpCount(entries) {
   return new Set(entries.map((entry) => entry.opIndex)).size;
 }
 
+// modules/payments-v2/restore.ts
+var ATTENTION_RESEED_REJECTED = "intent:reseed-rejected";
+var ALL_STREAMS = ["inventory", "mailbox", "payment_requests", "history"];
+async function reseedAndReset(deps) {
+  for (const entry of await deps.stores.backstop.list()) {
+    if (entry.disposition !== "open") continue;
+    try {
+      await deps.reput(entry.transferId, entry.payloadEnvelope, entry.requiresSeedClose);
+      if (entry.requiresSeedClose) {
+        await deps.reseedCheckpoint(entry.transferId, await splitOpIndex(deps, entry.payloadEnvelope));
+      }
+    } catch (err) {
+      deps.attention(entry.transferId, ATTENTION_RESEED_REJECTED, err instanceof Error ? err.message : String(err));
+    }
+  }
+  for (const stream of ALL_STREAMS) await deps.kv.remove(STORE_KEYS.streamCursor(stream));
+  await deps.fullRePull();
+}
+async function splitOpIndex(deps, envelope) {
+  const payload = await deps.decryptPayload(envelope);
+  return Array.isArray(payload.direct) ? payload.direct.length : 0;
+}
+
+// modules/payments-v2/inventory/presentation.ts
+function toToken(tokenId, snapshot, asset, registry, flags) {
+  const iconUrl = registry.getIconUrl(asset.coinId);
+  return {
+    id: tokenId,
+    coinId: asset.coinId,
+    symbol: registry.getSymbol(asset.coinId),
+    name: registry.getName(asset.coinId),
+    decimals: registry.getDecimals(asset.coinId),
+    ...iconUrl !== null ? { iconUrl } : {},
+    amount: asset.amount,
+    status: flags.transferring ? "transferring" : "confirmed",
+    createdAt: snapshot.createdAt,
+    updatedAt: snapshot.updatedAt,
+    lazy: true,
+    ...flags.suspectedSpent ? { suspectedSpent: true } : {}
+  };
+}
+function aggregateAssets(entries, isTransferring, registry) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [tokenId, entry] of entries) {
+    const moving = isTransferring(tokenId);
+    for (const asset of entry.assets) {
+      let group = groups.get(asset.coinId);
+      if (!group) {
+        group = { total: 0n, count: 0, transferring: 0n, transferringCount: 0 };
+        groups.set(asset.coinId, group);
+      }
+      if (moving) {
+        group.transferring += BigInt(asset.amount);
+        group.transferringCount += 1;
+      } else {
+        group.total += BigInt(asset.amount);
+        group.count += 1;
+      }
+    }
+  }
+  return [...groups].map(([coinId, totals]) => toAsset(coinId, totals, registry));
+}
+function toAsset(coinId, totals, registry) {
+  const iconUrl = registry.getIconUrl(coinId);
+  return {
+    coinId,
+    symbol: registry.getSymbol(coinId),
+    name: registry.getName(coinId),
+    decimals: registry.getDecimals(coinId),
+    ...iconUrl !== null ? { iconUrl } : {},
+    totalAmount: totals.total.toString(),
+    tokenCount: totals.count,
+    confirmedAmount: totals.total.toString(),
+    unconfirmedAmount: "0",
+    confirmedTokenCount: totals.count,
+    unconfirmedTokenCount: 0,
+    transferringTokenCount: totals.transferringCount,
+    transferringAmount: totals.transferring.toString(),
+    priceUsd: null,
+    priceEur: null,
+    change24h: null,
+    fiatValueUsd: null,
+    fiatValueEur: null
+  };
+}
+async function withPrices(raw, registry, price) {
+  try {
+    const names = [...new Set(raw.map((a) => registry.getName(a.coinId)))];
+    const quotes = await price.getPrices(names);
+    return raw.map((a) => priceOne(a, quotes.get(registry.getName(a.coinId))));
+  } catch {
+    return raw;
+  }
+}
+function priceOne(asset, quote) {
+  if (!quote) return asset;
+  const human = Number(asset.totalAmount) / Math.pow(10, asset.decimals);
+  return {
+    ...asset,
+    priceUsd: quote.priceUsd,
+    priceEur: quote.priceEur ?? null,
+    change24h: quote.change24h ?? null,
+    fiatValueUsd: human * quote.priceUsd,
+    fiatValueEur: quote.priceEur != null ? human * quote.priceEur : null
+  };
+}
+
+// modules/payments-v2/machine/payload.ts
+function buildPayload(recipientPubkey, request, spend, spentStates) {
+  return {
+    v: 2,
+    recipient: recipientPubkey,
+    coinId: request.coinId,
+    amount: request.amount,
+    ...request.memo !== void 0 ? { memo: request.memo } : {},
+    direct: [...spend.plan.direct],
+    ...spend.plan.split !== void 0 ? {
+      split: {
+        tokenId: spend.plan.split.tokenId,
+        splitAmount: spend.plan.split.splitAmount.toString(),
+        remainderAmount: spend.plan.split.remainderAmount.toString()
+      }
+    } : {},
+    spentStates
+  };
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // modules/payments-v2/history/History.ts
 var WIRE_TOKEN_ID = /^(?:[0-9a-f]{2}){1,64}$/;
 var WIRE_PUBKEY = /^0[23][0-9a-f]{64}$/;
@@ -12033,13 +12199,14 @@ var History = class {
   }
   // ── internals ────────────────────────────────────────────────────────────────
   async post(build) {
+    const record = build();
     try {
-      await this.deps.client.postHistory([build()]);
+      await this.deps.client.postHistory([record]);
     } catch (err) {
       this.deps.log?.("history POST failed (dedupKey makes retry safe)", err);
       return;
     }
-    this.deps.emit("history:updated");
+    this.deps.emit("history:updated", this.toEntry(record));
   }
   ts(timestamp) {
     return new Date(timestamp ?? (this.deps.now ?? Date.now)()).toISOString();
@@ -12096,93 +12263,9 @@ var History = class {
   }
 };
 
-// modules/payments-v2/inventory/presentation.ts
-function toToken(tokenId, snapshot, asset, registry, flags) {
-  const iconUrl = registry.getIconUrl(asset.coinId);
-  return {
-    id: tokenId,
-    coinId: asset.coinId,
-    symbol: registry.getSymbol(asset.coinId),
-    name: registry.getName(asset.coinId),
-    decimals: registry.getDecimals(asset.coinId),
-    ...iconUrl !== null ? { iconUrl } : {},
-    amount: asset.amount,
-    status: flags.transferring ? "transferring" : "confirmed",
-    createdAt: snapshot.createdAt,
-    updatedAt: snapshot.updatedAt,
-    lazy: true,
-    ...flags.suspectedSpent ? { suspectedSpent: true } : {}
-  };
-}
-function aggregateAssets(entries, isTransferring, registry) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const [tokenId, entry] of entries) {
-    const moving = isTransferring(tokenId);
-    for (const asset of entry.assets) {
-      let group = groups.get(asset.coinId);
-      if (!group) {
-        group = { total: 0n, count: 0, transferring: 0n, transferringCount: 0 };
-        groups.set(asset.coinId, group);
-      }
-      if (moving) {
-        group.transferring += BigInt(asset.amount);
-        group.transferringCount += 1;
-      } else {
-        group.total += BigInt(asset.amount);
-        group.count += 1;
-      }
-    }
-  }
-  return [...groups].map(([coinId, totals]) => toAsset(coinId, totals, registry));
-}
-function toAsset(coinId, totals, registry) {
-  const iconUrl = registry.getIconUrl(coinId);
-  return {
-    coinId,
-    symbol: registry.getSymbol(coinId),
-    name: registry.getName(coinId),
-    decimals: registry.getDecimals(coinId),
-    ...iconUrl !== null ? { iconUrl } : {},
-    totalAmount: totals.total.toString(),
-    tokenCount: totals.count,
-    confirmedAmount: totals.total.toString(),
-    unconfirmedAmount: "0",
-    confirmedTokenCount: totals.count,
-    unconfirmedTokenCount: 0,
-    transferringTokenCount: totals.transferringCount,
-    transferringAmount: totals.transferring.toString(),
-    priceUsd: null,
-    priceEur: null,
-    change24h: null,
-    fiatValueUsd: null,
-    fiatValueEur: null
-  };
-}
-async function withPrices(raw, registry, price) {
-  try {
-    const names = [...new Set(raw.map((a) => registry.getName(a.coinId)))];
-    const quotes = await price.getPrices(names);
-    return raw.map((a) => priceOne(a, quotes.get(registry.getName(a.coinId))));
-  } catch {
-    return raw;
-  }
-}
-function priceOne(asset, quote) {
-  if (!quote) return asset;
-  const human = Number(asset.totalAmount) / Math.pow(10, asset.decimals);
-  return {
-    ...asset,
-    priceUsd: quote.priceUsd,
-    priceEur: quote.priceEur ?? null,
-    change24h: quote.change24h ?? null,
-    fiatValueUsd: human * quote.priceUsd,
-    fiatValueEur: quote.priceEur != null ? human * quote.priceEur : null
-  };
-}
-
 // modules/payments-v2/inventory/InventoryView.ts
-var SUSPECTED_KEY = "suspected-spent";
-var KNOWN_SPENDS_KEY = "known-spends";
+var SUSPECTED_KEY = STORE_KEYS.suspectedSpent;
+var KNOWN_SPENDS_KEY = STORE_KEYS.knownSpends;
 var CURSOR_KEY = STORE_KEYS.streamCursor("inventory");
 function stateKey(tokenId, stateHash) {
   return `${tokenId}:${stateHash}`;
@@ -12486,19 +12569,24 @@ var Receive = class {
     const engine = deps.engine();
     const stored = [];
     const pending = [];
-    let epoch = "";
+    const pageEpoch = () => deps.delivery.incomingEpoch() ?? deps.syncEpoch();
     try {
-      epoch = deps.syncEpoch();
       const record = await deps.kv.get(STORE_KEYS.streamCursor("mailbox"));
-      const since = record !== null && record.syncEpoch === epoch ? String(record.cursor) : void 0;
-      for await (const entry of deps.delivery.incoming(since)) {
-        await this.processEntry(deps, engine, entry, pending, stored);
-        if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, epoch);
+      let basis = record !== null && record.syncEpoch === deps.syncEpoch() ? record : null;
+      for (let pass = 0; pass < 2; pass++) {
+        for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
+          await this.processEntry(deps, engine, entry, pending, stored);
+          if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
+        }
+        await flushAcks(deps, pending, pageEpoch);
+        const served = deps.delivery.incomingEpoch();
+        if (basis === null || served === null || served === basis.syncEpoch) break;
+        await deps.kv.remove(STORE_KEYS.streamCursor("mailbox"));
+        basis = null;
       }
-      await flushAcks(deps, pending, epoch);
     } catch (err) {
       logger.warn("PaymentsV2", "receive drain interrupted \u2014 unacked entries retry next drain:", err);
-      await flushAcks(deps, pending, epoch).catch((flushErr) => {
+      await flushAcks(deps, pending, pageEpoch).catch((flushErr) => {
         logger.warn("PaymentsV2", "receive ack flush failed \u2014 cursor holds at the acked prefix:", flushErr);
       });
     }
@@ -12571,7 +12659,7 @@ async function announce(deps, entry, record) {
     receivedAt
   };
 }
-async function flushAcks(deps, pending, epoch) {
+async function flushAcks(deps, pending, epochOf) {
   let lastAcked = null;
   try {
     while (pending.length > 0) {
@@ -12582,7 +12670,7 @@ async function flushAcks(deps, pending, epoch) {
     }
   } finally {
     if (lastAcked !== null) {
-      const record = { cursor: lastAcked, syncEpoch: epoch };
+      const record = { cursor: lastAcked, syncEpoch: epochOf() };
       await deps.kv.set(STORE_KEYS.streamCursor("mailbox"), record);
     }
   }
@@ -12683,9 +12771,19 @@ var Requests = class {
       }
     });
   }
+  /** Idempotent for a same-transferId re-write: committed only ratchets up, createdAt kept. */
   writeLink(requestId, transferId, committed) {
     return this.mutateJournal((m) => {
-      m.set(requestId, { requestId, transferId, committed, createdAt: this.now() });
+      const prev = m.get(requestId);
+      const same = prev !== void 0 && prev.transferId === transferId;
+      const next = {
+        requestId,
+        transferId,
+        committed: committed || same && prev.committed,
+        createdAt: same ? prev.createdAt : this.now()
+      };
+      if (same && prev.committed === next.committed) return false;
+      m.set(requestId, next);
       return true;
     });
   }
@@ -12838,23 +12936,46 @@ var Requests = class {
         const transferId = error instanceof SphereError && error.transferId !== void 0 ? error.transferId : void 0;
         if (transferId !== void 0) {
           const committed = error instanceof PartialSendConflictError;
-          await this.writeLink(id, transferId, committed);
-          this.setStatus(id, "settling");
+          await this.settle(id, transferId, { committed, respond: false });
         } else {
           logger.error("PaymentsV2", `possibly-committed send for ${id} carried no transferId \u2014 paid (fail-closed)`);
           this.setStatus(id, "paid");
         }
       } else {
-        await this.clearLink(id);
-        this.setStatus(id, "pending");
+        await this.revertPayable(id);
       }
       throw error;
     }
-    this.setStatus(id, "paid");
-    await this.respondPaid(id, result.id);
-    await this.clearLink(id);
+    await this.settle(id, result.id, { committed: true, respond: true });
     return result;
   }
+  /**
+   * THE settlement invariant (#441 + the failed-respond P1): a settling link is
+   * removed ONLY by (a) a CONFIRMED paid respond — a 2xx, or the 409
+   * already-resolved absorb — or (b) a proven clean pre-commit failure
+   * (revertPayable). Nothing else removes one: not a network error, not a 5xx,
+   * not a reload. Every path that binds a request to a transfer outcome funnels
+   * through here — pay()'s clean success (respond now), pay()'s
+   * possibly-committed throw (respond deferred), and reconcile's deferred arms
+   * — so a failed respond always leaves the link + 'settling' and the next
+   * reconcile pass (the committed-link override) retries the respond.
+   */
+  async settle(requestId, transferId, opts) {
+    let journalDown = false;
+    try {
+      await this.writeLink(requestId, transferId, opts.committed);
+    } catch (err) {
+      if (!opts.respond) throw err;
+      journalDown = true;
+      logger.error("PaymentsV2", `settling link write failed for ${requestId} \u2014 responding fail-closed:`, err);
+    }
+    if (!(opts.respond && await this.respondPaid(requestId, transferId))) {
+      this.setStatus(requestId, journalDown ? "paid" : "settling");
+      return;
+    }
+    if (!journalDown) await this.clearLink(requestId).catch(() => void 0);
+    this.setStatus(requestId, "paid");
+  }
   /** 'paid' respond leg: 409 = already resolved = idempotent success; other errors defer. */
   async respondPaid(id, transferId) {
     try {
@@ -12890,32 +13011,32 @@ var Requests = class {
     let aborted = null;
     for (const [requestId, link] of [...this.journal]) {
       if (link.committed || resumed.has(link.transferId)) {
-        await this.resolvePaid(requestId, link.transferId);
+        await this.resolvePaid(requestId, link);
       } else if (conflicted.has(link.transferId)) {
         await this.revertPayable(requestId);
       } else if (open.has(link.transferId)) {
       } else {
-        aborted = await this.reconcileUnaccounted(requestId, link.transferId, aborted);
+        aborted = await this.reconcileUnaccounted(requestId, link, aborted);
       }
     }
   }
   // Unaccounted link: consult the server aborted authority (lazy, memoized);
   // a probe failure defers the link to the next session.
-  async reconcileUnaccounted(requestId, transferId, aborted) {
+  async reconcileUnaccounted(requestId, link, aborted) {
     try {
       aborted ??= new Set(await this.deps.listAbortedTransferIds());
-      if (aborted.has(transferId)) await this.revertPayable(requestId);
-      else await this.resolvePaid(requestId, transferId);
+      if (aborted.has(link.transferId)) await this.revertPayable(requestId);
+      else await this.resolvePaid(requestId, link);
     } catch (err) {
       logger.warn("PaymentsV2", `aborted-intent probe failed \u2014 ${requestId} deferred:`, err);
     }
     return aborted;
   }
-  async resolvePaid(requestId, transferId) {
-    if (!await this.respondPaid(requestId, transferId)) return;
-    await this.clearLink(requestId);
-    this.setStatus(requestId, "paid");
+  /** Deferred paid: the ONE settlement path again — a failed respond keeps the link. */
+  resolvePaid(requestId, link) {
+    return this.settle(requestId, link.transferId, { committed: link.committed, respond: true });
   }
+  /** Removal cause (b): a PROVEN clean outcome (pre-commit failure / server-aborted). */
   async revertPayable(requestId) {
     await this.clearLink(requestId);
     this.setStatus(requestId, "pending");
@@ -13239,11 +13360,12 @@ function composeFacadeParts(deps, hooks) {
     client: deps.client,
     fieldKey: deps.fieldKey,
     registry: deps.registry,
-    emit: (event) => deps.emit(event, {}),
+    emit: (event, entry) => deps.emit(event, entry),
     ...deps.now !== void 0 ? { now: deps.now } : {},
     ...deps.newId !== void 0 ? { newId: deps.newId } : {}
   });
   const machineDeps = buildMachineDeps(deps, hooks, historyStore);
+  const machineStores = createMachineStores(deps.kv);
   const heldStates = /* @__PURE__ */ new Map();
   return {
     ownPubkeyBytes,
@@ -13251,12 +13373,29 @@ function composeFacadeParts(deps, hooks) {
     ledger,
     queue,
     historyStore,
-    machineStores: createMachineStores(deps.kv),
+    machineStores,
     machineDeps,
     machine: new TransferMachine(machineDeps),
     heldStates,
     receiveLoop: buildReceive(deps, hooks, historyStore, heldStates),
-    requests: buildRequests(deps, hooks)
+    requests: buildRequests(deps, hooks),
+    restoreDeps: buildRestoreDeps(deps, machineDeps, machineStores, view)
+  };
+}
+function buildRestoreDeps(deps, machineDeps, machineStores, view) {
+  return {
+    stores: machineStores,
+    kv: deps.kv,
+    reput: (transferId, envelope, requiresSeedClose) => machineDeps.intents.put(transferId, envelope, requiresSeedClose),
+    reseedCheckpoint: (transferId, opIndex) => deps.checkpointStore.reseedCheckpoint(transferId, opIndex),
+    decryptPayload: machineDeps.decryptPayload,
+    fullRePull: () => view.onEpochReset(),
+    attention: (transferId, code, detail) => {
+      deps.emit(
+        "transfer:attention",
+        detail === void 0 ? { transferId, code } : { transferId, code, detail }
+      );
+    }
   };
 }
 function buildMachineDeps(deps, hooks, historyStore) {
@@ -13278,11 +13417,13 @@ function buildMachineDeps(deps, hooks, historyStore) {
     ownPubkey: hexToBytes4(deps.ownPubkey),
     emit: deps.emit,
     now: deps.now ?? Date.now,
-    recordHistory: async ({ transferId, payload }) => {
+    recordHistory: async ({ transferId, payload, committedAmount }) => {
       await historyStore.recordSent({
         transferId,
         coinId: payload.coinId,
-        amount: payload.amount,
+        // §5.9: the SETTLED amount (machine-computed from the certified
+        // recipient blobs), never payload.amount — the plan.
+        amount: committedAmount,
         recipientPubkey: payload.recipient,
         ...payload.memo !== void 0 ? { memo: payload.memo } : {}
       });
@@ -13309,7 +13450,7 @@ function buildReceive(deps, hooks, historyStore, heldStates) {
         detail === void 0 ? { transferId, code } : { transferId, code, detail }
       );
     },
-    syncEpoch: deps.syncEpoch ?? (() => ""),
+    syncEpoch: deps.syncEpoch,
     ...deps.now !== void 0 ? { now: deps.now } : {}
   });
 }
@@ -13362,6 +13503,7 @@ var PaymentsFacade = class {
     this.receiveLoop = parts.receiveLoop;
     this.heldStates = parts.heldStates;
     this.ownPubkeyBytes = parts.ownPubkeyBytes;
+    this.restoreDeps = parts.restoreDeps;
     this.requests = parts.requests;
     deps.deliveryPort.bindDeliveryKeys((blob) => this.engine().deliveryKeys(blob));
     this.heartbeat = new ConvergenceHeartbeat({
@@ -13390,6 +13532,7 @@ var PaymentsFacade = class {
   receiveLoop;
   heldStates;
   ownPubkeyBytes;
+  restoreDeps;
   requests;
   currentEngine = null;
   pendingOps = /* @__PURE__ */ new Set();
@@ -13400,6 +13543,8 @@ var PaymentsFacade = class {
   converger;
   /** Resume single-flight (§7): ticks, start() and resumeNow() coalesce onto ONE pass. */
   resumeFlight = new SingleFlight();
+  /** §5.1/§7: restore + convergence passes SERIALIZE here. */
+  passChain = new SerialChain();
   /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
   activeMoneyOps = /* @__PURE__ */ new Set();
   // ── lifecycle ──────────────────────────────────────────────────────────────
@@ -13407,8 +13552,8 @@ var PaymentsFacade = class {
     if (this.started) return;
     this.started = true;
     this.heartbeat.start();
-    await this.deps.session.start();
     this.unsubscribers.push(
+      this.deps.session.subscribeEpochChange((epoch) => this.handleEpochChange(epoch)),
       this.deps.session.subscribeStream("mailbox", () => {
         this.trackTail(this.receiveLoop.drainOnce());
       }),
@@ -13423,6 +13568,7 @@ var PaymentsFacade = class {
       if (status === "connected") this.heartbeat.recovered();
     });
     if (statusUnsub !== void 0) this.unsubscribers.push(statusUnsub);
+    await this.deps.session.start();
     this.trackTail(this.runConvergencePass());
     this.trackTail(this.seedHeldStates());
     await this.view.fullPull().catch(() => void 0);
@@ -13463,7 +13609,7 @@ var PaymentsFacade = class {
   }
   // ── money movement ─────────────────────────────────────────────────────────
   send(request) {
-    return this.track(this.sendWithPolicy(request));
+    return this.track(this.sendOutcome(request));
   }
   async receive() {
     const transfers = await this.track(this.receiveLoop.drainOnce());
@@ -13478,20 +13624,27 @@ var PaymentsFacade = class {
     if (!this.started) return;
     await this.track(this.runConvergencePass());
   }
+  /** §5.1 restore — awaited by the session latch BEFORE streams resume; never coalesced onto a pre-restore pass. */
+  async handleEpochChange(_newEpoch) {
+    await this.passChain.enqueue(() => reseedAndReset(this.restoreDeps));
+    await this.passChain.enqueue(() => this.convergeBody());
+  }
   /** One single-flighted pass + its reschedule: concurrent callers coalesce. */
   runConvergencePass() {
-    return this.resumeFlight.run(async () => {
-      const outcome = await this.converger.convergeOnce();
-      const pending = await this.converger.pendingWork().catch(() => true);
-      this.heartbeat.settle(outcome, pending);
-    });
+    return this.resumeFlight.run(() => this.passChain.enqueue(() => this.convergeBody()));
+  }
+  async convergeBody() {
+    const outcome = await this.converger.convergeOnce();
+    const pending = await this.converger.pendingWork().catch(() => true);
+    this.heartbeat.settle(outcome, pending);
   }
   nowMs() {
     return (this.deps.now ?? Date.now)();
   }
   // ── send policy (§5.5 + old-loop parity; the machine stays policy-free) ────
-  async sendWithPolicy(request) {
-    const recipient = await this.requireSameNetworkRecipient(request.recipient);
+  /** The ONE place a send() outcome is shaped: success emits in finishSend, a
+   *  CLEAN rejection emits `transfer:updated{status:'failed'}` here (§4). */
+  async sendOutcome(request) {
     const run = {
       amount: request.amount,
       delivered: [],
@@ -13499,12 +13652,36 @@ var PaymentsFacade = class {
       tokenTransfers: [],
       settledShortfalls: [],
       firstPartialId: void 0,
-      pendingAny: false
+      pendingAny: false,
+      lastTransferId: ""
     };
+    try {
+      return await this.sendWithPolicy(request, run);
+    } catch (err) {
+      this.emitCleanFailure(err, run.lastTransferId);
+      throw err;
+    }
+  }
+  /** Only a CLEAN failure (nothing certified, classifyError 'other') is 'failed'.
+   *  Keep-open/partial/conflict outcomes are pending/converging — labelling them
+   *  'failed' invites a dApp re-send, i.e. a double-pay (#631/#676). */
+  emitCleanFailure(err, transferId) {
+    if (isPossiblyCommittedSendOutcome(err) || classifyError(err) !== "other") return;
+    const failed = {
+      id: transferId,
+      status: "failed",
+      tokens: [],
+      tokenTransfers: [],
+      error: messageOf(err)
+    };
+    this.deps.emit("transfer:updated", failed);
+  }
+  async sendWithPolicy(request, run) {
+    const recipient = await this.requireSameNetworkRecipient(request.recipient);
     for (let attempt = 0; ; attempt++) {
       let ctx;
       try {
-        ctx = await this.planAndMaterialize(recipient.chainPubkey, { ...request, amount: run.amount });
+        ctx = await this.planAndMaterialize(recipient.chainPubkey, { ...request, amount: run.amount }, run);
       } catch (err) {
         throw this.partialize(err, run);
       }
@@ -13549,11 +13726,8 @@ var PaymentsFacade = class {
       this.activeMoneyOps.delete(ctx.transferId);
     }
   }
-  /**
-   * Partial outcome (#677/#690): the shortfall is already durable (written by
-   * the machine BEFORE complete). Accumulate the settled set, then re-plan ONLY
-   * the remainder under a NEW transferId — never the full amount.
-   */
+  /** Partial (#677/#690): shortfall already durable (machine wrote it BEFORE
+   *  complete); accumulate settled, re-plan ONLY the remainder, NEW transferId. */
   async consumePartial(ctx, disposition, run, attempt) {
     if (disposition.deliveryPending) {
       run.pendingAny = true;
@@ -13579,11 +13753,8 @@ var PaymentsFacade = class {
     run.amount = partial.remainingAmount;
     return null;
   }
-  /**
-   * One attempt's failure disposition: possibly-committed → rethrow UNWRAPPED;
-   * backstop still 'open' (committed>0) → converge via the same machine's
-   * resumeIntent; clean conflict with a demoted source → bounded full re-plan.
-   */
+  /** Failure disposition: possibly-committed → rethrow UNWRAPPED; backstop
+   *  'open' → converge via resumeIntent; clean demoted conflict → full re-plan. */
   async disposeFailedAttempt(ctx, err) {
     if (isPossiblyCommittedSendOutcome(err)) {
       this.settleKeepOpen(ctx);
@@ -13632,8 +13803,9 @@ var PaymentsFacade = class {
     }
     return { kind: "rethrow", error: err };
   }
-  async planAndMaterialize(recipientPubkey, request) {
+  async planAndMaterialize(recipientPubkey, request, run) {
     const transferId = this.newId();
+    run.lastTransferId = transferId;
     const planned = this.queue.plan(transferId, { coinId: request.coinId, amount: request.amount });
     const spend = planned.kind === "planned" ? planned.spend : await planned.settled;
     const sourceIds = this.markPlanned(transferId, request.coinId, spend);
@@ -13765,11 +13937,7 @@ var PaymentsFacade = class {
     this.deps.emit("transfer:updated", result);
     return result;
   }
-  /**
-   * With nothing delivered the error passes UNWRAPPED (identity + cause kept);
-   * after ≥1 delivered leg EVERY failure surfaces as PartialSendConflictError
-   * over the accumulated settled set — never bare, never a full-amount retry.
-   */
+  /** Nothing delivered → UNWRAPPED; after ≥1 delivered leg every failure surfaces as PartialSendConflictError over the settled set. */
   partialize(err, run) {
     if (run.delivered.length === 0) return err;
     return new PartialSendConflictError(
@@ -13921,22 +14089,14 @@ var PaymentsFacade = class {
     }
   }
   toUiToken(tokenId, coinId, amount) {
-    const registry = this.deps.registry;
-    const iconUrl = registry.getIconUrl(coinId);
     const now = this.nowMs();
-    return {
-      id: tokenId,
-      coinId,
-      symbol: registry.getSymbol(coinId),
-      name: registry.getName(coinId),
-      decimals: registry.getDecimals(coinId),
-      ...iconUrl !== null ? { iconUrl } : {},
-      amount: amount.toString(),
-      status: "transferring",
-      createdAt: now,
-      updatedAt: now,
-      lazy: true
-    };
+    return toToken(
+      tokenId,
+      { assets: [], createdAt: now, updatedAt: now },
+      { coinId, amount: amount.toString() },
+      this.deps.registry,
+      { transferring: true, suspectedSpent: false }
+    );
   }
   track(op) {
     const settled = op.then(
@@ -13951,27 +14111,6 @@ var PaymentsFacade = class {
     this.track(op).catch(() => void 0);
   }
 };
-function buildPayload(recipientPubkey, request, spend, spentStates) {
-  return {
-    v: 2,
-    recipient: recipientPubkey,
-    coinId: request.coinId,
-    amount: request.amount,
-    ...request.memo !== void 0 ? { memo: request.memo } : {},
-    direct: [...spend.plan.direct],
-    ...spend.plan.split !== void 0 ? {
-      split: {
-        tokenId: spend.plan.split.tokenId,
-        splitAmount: spend.plan.split.splitAmount.toString(),
-        remainderAmount: spend.plan.split.remainderAmount.toString()
-      }
-    } : {},
-    spentStates
-  };
-}
-function messageOf(err) {
-  return err instanceof Error ? err.message : String(err);
-}
 
 // impl/wallet-api-v2/http.ts
 var WalletApiHttpError = class extends Error {
@@ -14317,6 +14456,7 @@ var WalletApiSession = class {
   epochLatch = null;
   reseedChain = Promise.resolve();
   reseedsPending = 0;
+  epochHandlers = /* @__PURE__ */ new Set();
   handlers = /* @__PURE__ */ new Map();
   statusHandlers = /* @__PURE__ */ new Set();
   socket = null;
@@ -14419,6 +14559,18 @@ var WalletApiSession = class {
     await this.deps.kv.set(this.refreshKey, tokens.refreshToken);
   }
   // ── epoch latch (F12) ─────────────────────────────────────────────────────
+  /** §5.1: the latched server syncEpoch ('' before first server contact). */
+  currentEpoch() {
+    return this.epochLatch ?? "";
+  }
+  /**
+   * §5.1 restore hook (FacadeSession contract): handlers are AWAITED inside
+   * the reseed chain, BEFORE any stream nudge resumes.
+   */
+  subscribeEpochChange(handler) {
+    this.epochHandlers.add(handler);
+    return () => this.epochHandlers.delete(handler);
+  }
   noteEpoch(epoch) {
     if (this.epochLatch === epoch) return;
     const previous = this.epochLatch;
@@ -14432,7 +14584,7 @@ var WalletApiSession = class {
   }
   async runReseed(epoch, previous) {
     try {
-      await this.deps.onEpochChange(epoch);
+      for (const handler of [...this.epochHandlers]) await handler(epoch);
       await this.deps.kv.set(STORE_KEYS.epochLatch, epoch);
     } catch {
       if (this.epochLatch === epoch) this.epochLatch = previous;
@@ -14694,6 +14846,7 @@ var WalletApiDeliveryPort = class {
   wake;
   deriveFn;
   seenChain = new SerialChain();
+  lastIncomingEpoch = null;
   constructor(config) {
     this.client = config.client;
     this.kv = config.kv;
@@ -14788,6 +14941,7 @@ var WalletApiDeliveryPort = class {
     const seen = await this.readSeen();
     let page = await this.client.listMailbox(sinceCursor === void 0 ? 0 : Number(sinceCursor));
     for (; ; ) {
+      this.lastIncomingEpoch = String(page.syncEpoch);
       for (const entry of page.entries) {
         if (entry.status !== "unclaimed") continue;
         if (seen.has(entry.entryId)) continue;
@@ -14797,6 +14951,10 @@ var WalletApiDeliveryPort = class {
       page = await this.client.listMailbox(page.cursor);
     }
   }
+  /** §5.7: the page-honest epoch — the restore-detection source Receive keys on. */
+  incomingEpoch() {
+    return this.lastIncomingEpoch;
+  }
   toIncoming(entry) {
     const bundle = this.openEnvelope(entry);
     return {
@@ -14874,7 +15032,7 @@ var WalletApiSplitCheckpointStore = class {
     return utf8(`${transferId}:${String(opIndex)}`);
   }
   async put(transferId, opIndex, bytes) {
-    const { client, kv, fieldKey, signProgress } = this.config;
+    const { kv, fieldKey } = this.config;
     const aad = this.aad(transferId, opIndex);
     const cacheKey = this.cacheKey(transferId, opIndex);
     let envelope = await kv.get(cacheKey);
@@ -14882,10 +15040,21 @@ var WalletApiSplitCheckpointStore = class {
       envelope = encryptFieldBytes(fieldKey, bytes, aad);
       await kv.set(cacheKey, envelope);
     }
-    const signature = await signProgress(progressSignMessage(transferId, opIndex, envelope));
-    const record = await client.postProgress(transferId, opIndex, envelope, signature);
+    const record = await this.post(transferId, opIndex, envelope);
     return this.open(record.payload, aad);
   }
+  /** §5.1 restore (CheckpointReseeder): re-POST the cached ciphertext byte-identical; false = none cached. */
+  async reseedCheckpoint(transferId, opIndex) {
+    const envelope = await this.config.kv.get(this.cacheKey(transferId, opIndex));
+    if (envelope === null) return false;
+    await this.post(transferId, opIndex, envelope);
+    return true;
+  }
+  /** The ONE signed progress-append path put() and reseedCheckpoint() share. */
+  async post(transferId, opIndex, envelope) {
+    const signature = await this.config.signProgress(progressSignMessage(transferId, opIndex, envelope));
+    return this.config.client.postProgress(transferId, opIndex, envelope, signature);
+  }
   async get(transferId, opIndex) {
     const records = await this.config.client.getProgress(transferId);
     const record = records.find((r) => r.opIndex === opIndex);
@@ -14908,7 +15077,7 @@ var WalletApiSplitCheckpointStore = class {
 };
 
 // core/payments-v2-wiring.ts
-function resolvePaymentsV2Composition(walletApi) {
+function resolvePaymentsV2Composition(walletApi, sphereNetwork) {
   const source = walletApi;
   const network = typeof source?.network === "string" && source.network !== "" ? source.network : null;
   if (!source || network === null) {
@@ -14917,6 +15086,18 @@ function resolvePaymentsV2Composition(walletApi) {
       "INVALID_CONFIG"
     );
   }
+  if (!(network in NETWORKS)) {
+    throw new SphereError(
+      `payments: walletApi.network "${network}" is not a known network (${Object.keys(NETWORKS).join("/")}) \u2014 a payments composition is single-network (Sphere network "${String(sphereNetwork)}").`,
+      "INVALID_CONFIG"
+    );
+  }
+  if (network !== sphereNetwork) {
+    throw new SphereError(
+      `payments: walletApi.network "${network}" does not match the Sphere network "${String(sphereNetwork)}" the engine/registry run on \u2014 a payments composition is single-network.`,
+      "INVALID_CONFIG"
+    );
+  }
   if (typeof source.paymentsV2Transport === "function") {
     return { network, factory: source.paymentsV2Transport.bind(source) };
   }
@@ -14981,8 +15162,7 @@ function defaultPaymentsV2Transport(config) {
       deviceId: `${config.deviceId}:pv2`,
       kv: args.kv,
       webSocketFactory,
-      emitStatus: args.emitStatus,
-      onEpochChange: args.onEpochChange
+      emitStatus: args.emitStatus
     });
     return { session, client: authedWireClient(session, client) };
   };
@@ -15052,8 +15232,7 @@ function composePaymentsV2(spec) {
     identity: identitySlice,
     network,
     kv,
-    emitStatus: (status) => host.emit("connection:status", { status }),
-    onEpochChange: async () => void 0
+    emitStatus: (status) => host.emit("connection:status", { status })
   });
   const deps = {
     session: transport.session,
@@ -15083,7 +15262,10 @@ function composePaymentsV2(spec) {
     network,
     ownPubkey: identity.chainPubkey,
     ownNametag: host.nametag,
-    requestMemo: requestMemoCodec(identity.privateKey)
+    requestMemo: requestMemoCodec(identity.privateKey),
+    // §5.1: the session is the epoch authority — the facade registers its
+    // restore hook on the session itself (FacadeSession.subscribeEpochChange).
+    syncEpoch: () => transport.session.currentEpoch()
   };
   return new PaymentsFacade(deps);
 }
@@ -15238,7 +15420,7 @@ var Sphere = class _Sphere {
   static async init(options) {
     if (options.debug) logger.configure({ debug: true });
     _Sphere.refuseRetiredModuleOptions(options);
-    resolvePaymentsV2Composition(options.walletApi);
+    resolvePaymentsV2Composition(options.walletApi, options.network);
     _Sphere.configureTokenRegistry(options.storage, options.network);
     const groupChat = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const market = _Sphere.resolveMarketConfig(options.market);
@@ -15380,7 +15562,7 @@ var Sphere = class _Sphere {
   static async create(options) {
     if (options.debug) logger.configure({ debug: true });
     _Sphere.refuseRetiredModuleOptions(options);
-    const composition = resolvePaymentsV2Composition(options.walletApi);
+    const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
     if (!options.mnemonic || !_Sphere.validateMnemonic(options.mnemonic)) {
       throw new SphereError("Invalid mnemonic", "INVALID_IDENTITY");
     }
@@ -15448,7 +15630,7 @@ var Sphere = class _Sphere {
   static async load(options) {
     if (options.debug) logger.configure({ debug: true });
     _Sphere.refuseRetiredModuleOptions(options);
-    const composition = resolvePaymentsV2Composition(options.walletApi);
+    const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
     if (!await _Sphere.exists(options.storage)) {
       throw new SphereError("No wallet found. Use Sphere.create() to create a new wallet.", "NOT_INITIALIZED");
     }
@@ -15502,7 +15684,7 @@ var Sphere = class _Sphere {
   static async import(options) {
     if (options.debug) logger.configure({ debug: true });
     _Sphere.refuseRetiredModuleOptions(options);
-    const composition = resolvePaymentsV2Composition(options.walletApi);
+    const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
     if (!options.mnemonic && !options.masterKey) {
       throw new SphereError("Either mnemonic or masterKey is required", "INVALID_CONFIG");
     }