@unicitylabs/sphere-sdk 0.14.11-dev.6 → 0.14.11-dev.8

package/dist/modules/payments-v2/index.d.cts

@@ -340,8 +340,22 @@ interface DeliveryPort {
      */
     incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /** Settle many acks at once (#757). Contract pinned by the delivery-port contract suite. */
+    ackBatch?(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
     onWake?(cb: () => void): () => void;
 }
+interface AckRequest {
+    readonly deliveryId: string;
+    readonly disposition: 'claimed' | 'rejected';
+    readonly reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other';
+}
+type AckOutcome = {
+    readonly deliveryId: string;
+    readonly status: 'settled';
+} | {
+    readonly deliveryId: string;
+    readonly status: 'conflict';
+};
 
 interface IntentPayload {
     v: 2;

package/dist/modules/payments-v2/index.d.ts

@@ -340,8 +340,22 @@ interface DeliveryPort {
      */
     incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /** Settle many acks at once (#757). Contract pinned by the delivery-port contract suite. */
+    ackBatch?(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
     onWake?(cb: () => void): () => void;
 }
+interface AckRequest {
+    readonly deliveryId: string;
+    readonly disposition: 'claimed' | 'rejected';
+    readonly reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other';
+}
+type AckOutcome = {
+    readonly deliveryId: string;
+    readonly status: 'settled';
+} | {
+    readonly deliveryId: string;
+    readonly status: 'conflict';
+};
 
 interface IntentPayload {
     v: 2;

package/dist/modules/payments-v2/index.js

@@ -536,6 +536,33 @@ var SerialChain = class {
     return run;
   }
 };
+function coalesced(run, observe) {
+  let inFlight = false;
+  let queued = false;
+  const start = () => {
+    inFlight = true;
+    let running;
+    try {
+      running = run();
+    } catch {
+      running = Promise.resolve();
+    }
+    observe?.(running);
+    void running.catch(() => void 0).finally(() => {
+      inFlight = false;
+      if (!queued) return;
+      queued = false;
+      start();
+    });
+  };
+  return () => {
+    if (inFlight) {
+      queued = true;
+      return;
+    }
+    start();
+  };
+}
 
 // modules/payments-v2/machine/journal.ts
 var MAX_DELIVERY_ATTEMPTS = 6;
@@ -2841,6 +2868,16 @@ var InventoryView = class {
     this.inFlight.add(tokenId);
     this.deps.emit("inventory:updated");
   }
+  /** Reserve a whole plan as ONE change — per token emitted 54 events per send. */
+  markInFlightMany(tokenIds) {
+    let changed = false;
+    for (const tokenId of tokenIds) {
+      if (this.inFlight.has(tokenId)) continue;
+      this.inFlight.add(tokenId);
+      changed = true;
+    }
+    if (changed) this.deps.emit("inventory:updated");
+  }
   release(tokenId) {
     if (this.inFlight.delete(tokenId)) this.deps.emit("inventory:updated");
   }
@@ -3157,6 +3194,11 @@ var logger = {
   }
 };
 
+// modules/payments-v2/ports.ts
+function isRetryableAckError(err) {
+  return err !== null && typeof err === "object" && err.retryable === true;
+}
+
 // modules/payments-v2/receive/Receive.ts
 var ACK_BATCH_SIZE = 200;
 var REFRESH_INTERVAL_MS = 2500;
@@ -3213,6 +3255,17 @@ var Receive = class {
     await flushAcks(deps, pending, epochOf);
     deps.refreshView();
   }
+  /** One listing pass: process each entry, flushing and refreshing as it goes. */
+  async drainPages(ctx, basis) {
+    const { deps, engine, pending, stored, pageEpoch } = ctx;
+    for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
+      const storedBefore = stored.length;
+      await this.processEntry(deps, engine, entry, pending, stored);
+      if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
+      if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
+    }
+    await flushAcks(deps, pending, pageEpoch);
+  }
   async doDrain() {
     const deps = this.deps;
     this.lastRefreshAt = deps.now?.() ?? Date.now();
@@ -3224,13 +3277,7 @@ var Receive = class {
       const record = await deps.kv.get(STORE_KEYS.streamCursor("mailbox"));
       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))) {
-          const storedBefore = stored.length;
-          await this.processEntry(deps, engine, entry, pending, stored);
-          if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
-          if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
-        }
-        await flushAcks(deps, pending, pageEpoch);
+        await this.drainPages({ deps, engine, pending, stored, pageEpoch }, basis);
         const served = deps.delivery.incomingEpoch();
         if (basis === null || served === null || served === basis.syncEpoch) break;
         await deps.kv.remove(STORE_KEYS.streamCursor("mailbox"));
@@ -3238,10 +3285,12 @@ var Receive = class {
       }
     } catch (err) {
       logger.warn("PaymentsV2", "receive drain interrupted \u2014 unacked entries retry next drain:", err);
+      if (isRetryableAckError(err)) return stored;
       await flushAcks(deps, pending, pageEpoch).catch((flushErr) => {
         logger.warn("PaymentsV2", "receive ack flush failed \u2014 cursor holds at the acked prefix:", flushErr);
       });
     }
+    if (stored.length > 0) deps.refreshView?.();
     return stored;
   }
   async processEntry(deps, engine, entry, pending, stored) {
@@ -3312,14 +3361,18 @@ async function announce(deps, entry, record) {
   };
 }
 async function flushAcks(deps, pending, epochOf) {
+  if (pending.length === 0) return;
   let lastAcked = null;
   try {
-    while (pending.length > 0) {
-      const next = pending[0];
-      await ackOne(deps, next);
-      lastAcked = next.cursor;
-      pending.shift();
+    const settled = await settleAcks(deps, pending);
+    let i = 0;
+    while (i < pending.length && settled.has(pending[i].deliveryId)) {
+      lastAcked = pending[i].cursor;
+      i += 1;
     }
+    const stuck = pending.filter((p) => !settled.has(p.deliveryId));
+    pending.length = 0;
+    pending.push(...stuck);
   } finally {
     if (lastAcked !== null) {
       const record = { cursor: lastAcked, syncEpoch: epochOf() };
@@ -3327,14 +3380,65 @@ async function flushAcks(deps, pending, epochOf) {
     }
   }
 }
+async function settleAcks(deps, pending) {
+  const batch = deps.delivery.ackBatch?.bind(deps.delivery);
+  if (batch === void 0) return settleOneByOne(deps, pending);
+  let outcomes;
+  try {
+    outcomes = await batch(pending.map(toAckRequest));
+  } catch (err) {
+    if (isRetryableAckError(err)) throw err;
+    logger.warn("PaymentsV2", "batched mailbox ack failed \u2014 settling one at a time:", err);
+    return settleOneByOne(deps, pending);
+  }
+  const settled = new Set(outcomes.filter((o) => o.status === "settled").map((o) => o.deliveryId));
+  const conflicts = outcomes.filter((o) => o.status === "conflict").map((o) => o.deliveryId);
+  if (conflicts.length > 0) await resolveConflicts(deps, pending, conflicts, settled);
+  return settled;
+}
+async function resolveConflicts(deps, pending, conflicts, settled) {
+  for (const deliveryId of conflicts) {
+    const entry = pending.find((p) => p.deliveryId === deliveryId);
+    try {
+      await rejectStaleClaim(deps, deliveryId, entry?.transferId);
+    } catch (err) {
+      logger.warn("PaymentsV2", `stale-reject failed for ${deliveryId} \u2014 cursor holds here:`, err);
+      continue;
+    }
+    settled.add(deliveryId);
+  }
+}
+async function rejectStaleClaim(deps, deliveryId, transferId) {
+  logger.warn("PaymentsV2", `mailbox claim CONFLICT for ${deliveryId} \u2014 rejected('other') as stale`);
+  await deps.delivery.ack(deliveryId, "rejected", "other");
+  deps.attention(transferId ?? "", ATTENTION_CLAIM_CONFLICT, deliveryId);
+}
+async function settleOneByOne(deps, pending) {
+  const settled = /* @__PURE__ */ new Set();
+  for (const ack of pending) {
+    try {
+      await ackOne(deps, ack);
+    } catch (err) {
+      logger.warn("PaymentsV2", `mailbox ack failed for ${ack.deliveryId} \u2014 cursor holds here:`, err);
+      break;
+    }
+    settled.add(ack.deliveryId);
+  }
+  return settled;
+}
+function toAckRequest(ack) {
+  return {
+    deliveryId: ack.deliveryId,
+    disposition: ack.disposition,
+    ...ack.reason !== void 0 ? { reason: ack.reason } : {}
+  };
+}
 async function ackOne(deps, ack) {
   try {
     await deps.delivery.ack(ack.deliveryId, ack.disposition, ack.reason);
   } catch (err) {
     if (ack.disposition !== "claimed" || !isClaimConflict(err)) throw err;
-    logger.warn("PaymentsV2", `mailbox claim CONFLICT for ${ack.deliveryId} \u2014 rejected('other') as stale`);
-    await deps.delivery.ack(ack.deliveryId, "rejected", "other");
-    deps.attention(ack.transferId ?? "", ATTENTION_CLAIM_CONFLICT, ack.deliveryId);
+    await rejectStaleClaim(deps, ack.deliveryId, ack.transferId);
   }
 }
 function claimAck(entry) {
@@ -4088,26 +4192,6 @@ function parseAmount(raw) {
 function supportsDeterministicMint(engine) {
   return engine.deterministicMint === true;
 }
-function makeCoalescedRefresh(refresh) {
-  let inFlight = false;
-  let queued = false;
-  const run = () => {
-    inFlight = true;
-    void refresh().catch(() => void 0).finally(() => {
-      inFlight = false;
-      if (!queued) return;
-      queued = false;
-      run();
-    });
-  };
-  return () => {
-    if (inFlight) {
-      queued = true;
-      return;
-    }
-    run();
-  };
-}
 function composeFacadeParts(deps, hooks) {
   const ownPubkeyBytes = hexToBytes(deps.ownPubkey);
   const ledger = new ReservationLedger();
@@ -4137,9 +4221,11 @@ function composeFacadeParts(deps, hooks) {
   const machineDeps = buildMachineDeps(deps, hooks, historyStore);
   const machineStores = createMachineStores(deps.kv);
   const heldStates = /* @__PURE__ */ new Map();
+  const refreshView = coalesced(() => view.delta(), hooks.track);
   return {
     ownPubkeyBytes,
     view,
+    refreshView,
     ledger,
     pins: buildPins(deps, hooks, { ledger, view, machineStores, machineDeps }),
     queue,
@@ -4148,7 +4234,7 @@ function composeFacadeParts(deps, hooks) {
     machineDeps,
     machine: new TransferMachine(machineDeps),
     heldStates,
-    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates, view),
+    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates, refreshView),
     requests: buildRequests(deps, hooks),
     restoreDeps: buildRestoreDeps(deps, machineDeps, machineStores, view)
   };
@@ -4215,7 +4301,7 @@ function buildMachineDeps(deps, hooks, historyStore) {
     }
   };
 }
-function buildReceive(deps, hooks, historyStore, heldStates, view) {
+function buildReceive(deps, hooks, historyStore, heldStates, refreshView) {
   return new Receive({
     delivery: deps.deliveryPort,
     engine: () => hooks.engine(),
@@ -4229,8 +4315,7 @@ function buildReceive(deps, hooks, historyStore, heldStates, view) {
     registry: deps.registry,
     recordReceived: (record) => recordReceived(historyStore, record),
     emit: (event, transfer) => deps.emit(event, transfer),
-    // Coalesced — see makeCoalescedRefresh.
-    refreshView: makeCoalescedRefresh(() => view.delta()),
+    refreshView,
     attention: (transferId, code, detail) => {
       deps.emit(
         "transfer:attention",
@@ -4279,10 +4364,11 @@ var PaymentsFacade = class {
     const parts = composeFacadeParts(deps, {
       engine: () => this.engine(),
       send: (request) => this.send(request),
-      isActiveOp: (id) => this.activeMoneyOps.has(id)
+      isActiveOp: (id) => this.activeMoneyOps.has(id),
+      track: (op) => this.trackTail(op)
     });
     this.view = parts.view;
-    this.wakeRefresh = makeCoalescedRefresh(() => this.view.delta());
+    this.wakeRefresh = parts.refreshView;
     this.ledger = parts.ledger;
     this.queue = parts.queue;
     this.machine = parts.machine;
@@ -4419,7 +4505,6 @@ var PaymentsFacade = class {
   }
   async receive() {
     const transfers = await this.track(this.receiveLoop.drainOnce());
-    if (transfers.length > 0) this.trackTail(this.view.delta());
     return { transfers };
   }
   mint(coinId, amount) {
@@ -4615,7 +4700,7 @@ var PaymentsFacade = class {
       ...spend.plan.direct,
       ...spend.plan.split !== void 0 ? [spend.plan.split.tokenId] : []
     ];
-    for (const tokenId of sourceIds) this.view.markInFlight(tokenId);
+    this.view.markInFlightMany(sourceIds);
     if (spend.plan.split !== void 0) {
       this.queue.declareExpectedChange(transferId, coinId, spend.plan.split.remainderAmount);
     }