@unicitylabs/sphere-sdk 0.14.0-dev.6 → 0.14.0

package/dist/impl/wallet-api-v2/index.d.cts

@@ -349,8 +349,6 @@ interface WalletApiSessionDeps {
     kv: ScopedKV;
     webSocketFactory: WebSocketFactory;
     emitStatus: (status: ConnectionStatus) => void;
-    /** Runs the syncEpoch re-seed protocol BEFORE any stream resumes. */
-    onEpochChange: (epoch: string) => Promise<void>;
     timing?: Partial<SessionTiming>;
     timers?: SessionTimers;
     random?: () => number;
@@ -366,6 +364,7 @@ declare class WalletApiSession {
     private epochLatch;
     private reseedChain;
     private reseedsPending;
+    private readonly epochHandlers;
     private readonly handlers;
     private readonly statusHandlers;
     private socket;
@@ -389,6 +388,13 @@ declare class WalletApiSession {
     private authenticate;
     private tryRefresh;
     private challengeSignIn;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook (FacadeSession contract): handlers are AWAITED inside
+     * the reseed chain, BEFORE any stream nudge resumes.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     noteEpoch(epoch: string): void;
     private runReseed;
     subscribeStream(stream: WakeStream, handler: () => void): () => void;
@@ -471,6 +477,14 @@ interface DeliveryPort {
     deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
     deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
     incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /**
+     * The syncEpoch of the most recent incoming() page — updated per page, null
+     * before the first. §5.7 restore self-detection: the mailbox page is the
+     * honest epoch source, so Receive voids its (cursor, epoch) continuity on a
+     * mismatch even when the wake socket missed a server restore. (Pinned by the
+     * S7 contract suite; wallet-api#119's S7 text carries the same sentence.)
+     */
+    incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
     onWake?(cb: () => void): () => void;
 }
@@ -525,6 +539,7 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private readonly wake;
     private deriveFn;
     private readonly seenChain;
+    private lastIncomingEpoch;
     constructor(config: WalletApiDeliveryPortConfig);
     bindDeliveryKeys(derive: (blob: Uint8Array) => Promise<{
         tokenId: string;
@@ -538,6 +553,8 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private depositAll;
     private depositOne;
     incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /** §5.7: the page-honest epoch — the restore-detection source Receive keys on. */
+    incomingEpoch(): string | null;
     private toIncoming;
     private openEnvelope;
     private fetchVerified;
@@ -563,6 +580,10 @@ declare class WalletApiSplitCheckpointStore implements SplitCheckpointStore {
     private cacheKey;
     private aad;
     put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
+    /** §5.1 restore (CheckpointReseeder): re-POST the cached ciphertext byte-identical; false = none cached. */
+    reseedCheckpoint(transferId: string, opIndex: number): Promise<boolean>;
+    /** The ONE signed progress-append path put() and reseedCheckpoint() share. */
+    private post;
     get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
     private open;
 }

package/dist/impl/wallet-api-v2/index.d.ts

@@ -349,8 +349,6 @@ interface WalletApiSessionDeps {
     kv: ScopedKV;
     webSocketFactory: WebSocketFactory;
     emitStatus: (status: ConnectionStatus) => void;
-    /** Runs the syncEpoch re-seed protocol BEFORE any stream resumes. */
-    onEpochChange: (epoch: string) => Promise<void>;
     timing?: Partial<SessionTiming>;
     timers?: SessionTimers;
     random?: () => number;
@@ -366,6 +364,7 @@ declare class WalletApiSession {
     private epochLatch;
     private reseedChain;
     private reseedsPending;
+    private readonly epochHandlers;
     private readonly handlers;
     private readonly statusHandlers;
     private socket;
@@ -389,6 +388,13 @@ declare class WalletApiSession {
     private authenticate;
     private tryRefresh;
     private challengeSignIn;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook (FacadeSession contract): handlers are AWAITED inside
+     * the reseed chain, BEFORE any stream nudge resumes.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     noteEpoch(epoch: string): void;
     private runReseed;
     subscribeStream(stream: WakeStream, handler: () => void): () => void;
@@ -471,6 +477,14 @@ interface DeliveryPort {
     deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
     deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
     incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /**
+     * The syncEpoch of the most recent incoming() page — updated per page, null
+     * before the first. §5.7 restore self-detection: the mailbox page is the
+     * honest epoch source, so Receive voids its (cursor, epoch) continuity on a
+     * mismatch even when the wake socket missed a server restore. (Pinned by the
+     * S7 contract suite; wallet-api#119's S7 text carries the same sentence.)
+     */
+    incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
     onWake?(cb: () => void): () => void;
 }
@@ -525,6 +539,7 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private readonly wake;
     private deriveFn;
     private readonly seenChain;
+    private lastIncomingEpoch;
     constructor(config: WalletApiDeliveryPortConfig);
     bindDeliveryKeys(derive: (blob: Uint8Array) => Promise<{
         tokenId: string;
@@ -538,6 +553,8 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private depositAll;
     private depositOne;
     incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /** §5.7: the page-honest epoch — the restore-detection source Receive keys on. */
+    incomingEpoch(): string | null;
     private toIncoming;
     private openEnvelope;
     private fetchVerified;
@@ -563,6 +580,10 @@ declare class WalletApiSplitCheckpointStore implements SplitCheckpointStore {
     private cacheKey;
     private aad;
     put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
+    /** §5.1 restore (CheckpointReseeder): re-POST the cached ciphertext byte-identical; false = none cached. */
+    reseedCheckpoint(transferId: string, opIndex: number): Promise<boolean>;
+    /** The ONE signed progress-append path put() and reseedCheckpoint() share. */
+    private post;
     get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
     private open;
 }

package/dist/impl/wallet-api-v2/index.js

@@ -694,7 +694,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"
 };
 
 // node_modules/@noble/curves/utils.js
@@ -2718,6 +2721,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;
@@ -2820,6 +2824,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;
@@ -2833,7 +2849,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;
@@ -4041,6 +4057,7 @@ var WalletApiDeliveryPort = class {
   wake;
   deriveFn;
   seenChain = new SerialChain();
+  lastIncomingEpoch = null;
   constructor(config) {
     this.client = config.client;
     this.kv = config.kv;
@@ -4135,6 +4152,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;
@@ -4144,6 +4162,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 {
@@ -4299,7 +4321,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);
@@ -4307,10 +4329,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);