cross-tab-worker-databus 0.20.85 → 0.20.87

package/dist/cjs/index.cjs

@@ -1855,6 +1855,36 @@ function roundMs(value) {
   return Math.round(value * 10) / 10;
 }
 
+// src/core/replay-pruning.ts
+function pruneReplayHistory(messages, options) {
+  const { maxPerTopic, pruneStrategy, retentionMs, now } = options;
+  const ageEnabled = pruneStrategy !== PRUNE_STRATEGY.COUNT && retentionMs !== void 0;
+  if (!ageEnabled) {
+    return messages.length > maxPerTopic ? messages.slice(-maxPerTopic) : messages;
+  }
+  const cutoff = now - retentionMs;
+  let hasExpired = false;
+  let timestamplessCount = 0;
+  for (const message of messages) {
+    if (message.timestamp === void 0) timestamplessCount += 1;
+    else if (message.timestamp < cutoff) hasExpired = true;
+  }
+  let pruned = hasExpired ? messages.filter((message) => message.timestamp === void 0 || message.timestamp >= cutoff) : messages;
+  if (pruneStrategy === PRUNE_STRATEGY.BOTH) {
+    return pruned.length > maxPerTopic ? pruned.slice(-maxPerTopic) : pruned;
+  }
+  if (timestamplessCount <= maxPerTopic) return pruned;
+  let timestamplessToDrop = timestamplessCount - maxPerTopic;
+  pruned = pruned.filter((message) => {
+    if (message.timestamp === void 0 && timestamplessToDrop > 0) {
+      timestamplessToDrop -= 1;
+      return false;
+    }
+    return true;
+  });
+  return pruned;
+}
+
 // src/core/replay-manager.ts
 var PersistenceRetryCancelledError = class extends Error {
   constructor() {
@@ -1916,17 +1946,15 @@ var ReplayManager = class {
       this.buffers.set(message.topic, buffer);
     }
     buffer.push(message);
-    const ageBounded = this.pruneStrategy !== PRUNE_STRATEGY.COUNT && this.retentionMs !== void 0;
-    if (this.pruneStrategy !== PRUNE_STRATEGY.AGE || !ageBounded) {
-      while (buffer.length > this.maxPerTopic) buffer.shift();
-    }
-    if (ageBounded) {
-      const cutoff = this.now() - this.retentionMs;
-      while (buffer.length > 0) {
-        const first = buffer[0];
-        if (!first || first.timestamp === void 0 || first.timestamp >= cutoff) break;
-        buffer.shift();
-      }
+    const pruned = pruneReplayHistory(buffer, {
+      maxPerTopic: this.maxPerTopic,
+      pruneStrategy: this.pruneStrategy,
+      retentionMs: this.retentionMs,
+      now: this.now()
+    });
+    if (pruned !== buffer) {
+      buffer = pruned;
+      this.buffers.set(message.topic, buffer);
     }
     if (!this.persistence) return;
     if (this.persistence.appendBatch) {
@@ -2107,14 +2135,24 @@ var ReplayManager = class {
       if (this.retentionMs !== void 0 && this.persistence.clearBefore) {
         await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(this.now() - this.retentionMs));
       }
-      for (const message of await this.withPersistenceRetry(PERSISTENCE_OPERATION.LOAD, () => this.persistence.load())) {
+      const loaded = await this.withPersistenceRetry(PERSISTENCE_OPERATION.LOAD, () => this.persistence.load());
+      for (const message of loaded) {
         let buffer = this.buffers.get(message.topic);
         if (!buffer) {
           buffer = [];
           this.buffers.set(message.topic, buffer);
         }
         buffer.push(message);
-        if (buffer.length > this.maxPerTopic) buffer.shift();
+      }
+      const hydrationNow = this.now();
+      for (const [topic, buffer] of this.buffers) {
+        const pruned = pruneReplayHistory(buffer, {
+          maxPerTopic: this.maxPerTopic,
+          pruneStrategy: this.pruneStrategy,
+          retentionMs: this.retentionMs,
+          now: hydrationNow
+        });
+        if (pruned !== buffer) this.buffers.set(topic, pruned);
       }
     } catch (error) {
       this.onPersistenceError(error);
@@ -2291,7 +2329,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.20.85" : "";
+var SDK_VERSION = true ? "0.20.87" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2316,6 +2354,11 @@ var CrossTabDataBus = class {
   started = false;
   stopping = false;
   transportReady = false;
+  // Whether the installed transport has reported `connected` at least once
+  // since the current open began. A clean `disconnected` after this point is
+  // a lost working connection, not the pre-connect window of a worker-style
+  // backend whose start() resolves before it reports the connection.
+  transportHasConnected = false;
   // Last transport failure, retained so ready() can surface it to callers who
   // never awaited start() directly. Cleared on the next successful start.
   lastError = null;
@@ -2329,6 +2372,24 @@ var CrossTabDataBus = class {
   // Gate that serialises start/stop/suspend/resume — only one lifecycle
   // transition at a time. Resets to null once the operation settles.
   startPromise = null;
+  // Gate for an explicit stop(). Concurrent stop() calls share it, and a
+  // start() received while stopping chains a fresh start after it.
+  stopPromise = null;
+  // A start() requested while an explicit stop() is still settling. Kept
+  // separate from startPromise because stop()'s finally block clears the
+  // ordinary lifecycle gate before the queued start is allowed to run.
+  queuedStart = null;
+  // Lazy readiness view of queuedStart. start() keeps its documented
+  // resolve-on-cancellation contract, while ready() must reject when the
+  // queued intent was superseded by a later stop().
+  queuedStartReady = null;
+  queuedStartReadyToken = 0;
+  // The queued continuation is chained to the stop promise and cannot be
+  // un-scheduled once scheduled. A later stop() therefore invalidates the
+  // current intent by recording its token; a subsequent start() issues a
+  // higher token so the latest lifecycle request still wins.
+  queuedStartToken = 0;
+  canceledQueuedStartToken = 0;
   // Timestamp of the last automatic transport recovery attempt.
   // Used to avoid a tight retry loop when the transport fails repeatedly.
   lastRecoveryAt = 0;
@@ -2336,6 +2397,19 @@ var CrossTabDataBus = class {
   // a transport reopen succeeds so traces can correlate repeated failures.
   recoveryAttempt = 0;
   recoveryExhausted = false;
+  // Gate that holds transport operations issued after a runtime `error` until
+  // the scheduled recovery attempt has actually run. Without it, a dead
+  // transport still has `transportReady === true` during the cooldown, so
+  // publishes/subscribes would be written to the failed connection and lost.
+  recoveryGate = null;
+  recoveryGateRelease = null;
+  recoveryTimer = null;
+  recoveryTimerToken = 0;
+  // Once an automatic attempt fails, an explicit transport operation may
+  // recover immediately instead of waiting for the next paced attempt. The
+  // gate still stays closed so the operation cannot reach the failed
+  // transport; it is released by the successful on-demand reopen.
+  recoveryDemandAllowed = false;
   /** Monotonic generation incremented on every successful transport open.
    * Stays in lockstep with `lastSuccessAt` so callers can detect that the
    * transport has been reopened even if the timestamp window is short. */
@@ -2351,6 +2425,9 @@ var CrossTabDataBus = class {
   // surfaces a failure while later opens and automatic recovery wait for the
   // stop to settle.
   pendingStop = null;
+  // Ownership token for asynchronous transport opens. Every lifecycle
+  // transition invalidates callbacks and failure cleanup from older opens.
+  lifecycleEpoch = 0;
   // Minimum interval in ms between automatic recovery attempts.
   recoveryCooldownMs;
   recoveryMaxAttempts;
@@ -2463,37 +2540,51 @@ var CrossTabDataBus = class {
    * Start the DataBus with the given transport config.
    *
    * The first call starts the cluster and opens the transport. Concurrent calls
-   * during an in-flight start return the same promise. Once the operation
-   * settles (success or failure) the promise gate is cleared so a subsequent
-   * start() or resumeTransport() can open a fresh lifecycle.
+   * during an in-flight open return the same promise. A call received while an
+   * explicit stop() is settling queues one fresh start after cleanup; a later
+   * stop() before that queued start runs cancels it, so the latest lifecycle
+   * intent wins. Once an operation settles (success or failure) its promise
+   * gate is cleared so a subsequent start() or resumeTransport() can open a
+   * fresh lifecycle.
    */
   start(config) {
-    if (this.startPromise) return this.startPromise;
-    if (this.started) return Promise.resolve();
+    if (this.queuedStart) return this.queuedStart;
+    if (this.stopping) return this.queueStartAfterStop(config);
+    if (this.startPromise && this.startPromise !== this.pendingStop) return this.startPromise;
+    if (this.started) {
+      const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+      if (!transportDown) return Promise.resolve();
+      this.activeConfig = config;
+      this.resetFailureState();
+      return this.reopenTransport();
+    }
     this.started = true;
     this.stopping = false;
     this.suspended = false;
     this.activeConfig = config;
-    this.lastError = null;
-    this.lastFailure = null;
-    this.persistenceFailureCount = 0;
-    this.persistenceLastFailureAt = null;
-    this.persistenceLastErrorMessage = null;
+    this.resetFailureState();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.START });
     this.trace.start();
     this.startDedupSweep();
     this.replayManager.start();
     this.updateStatus(WORKER_STATUS.CONNECTING);
     this.cluster.start();
-    const opening = this.openTransport(config, this.pendingStop ?? Promise.resolve(), true);
+    const lifecycleEpoch = ++this.lifecycleEpoch;
+    const opening = this.openTransport(
+      config,
+      this.pendingStop ?? Promise.resolve(),
+      true,
+      lifecycleEpoch
+    );
     this.startPromise = opening;
     for (const topic of this.topicHandlers.keys()) {
       this.cluster.subscribe(topic);
     }
     void opening.then(
       () => {
+        if (this.startPromise !== opening) return;
         this.emitCoordinationTrace();
-        if (this.startPromise === opening) this.startPromise = null;
+        this.startPromise = null;
       },
       () => {
         if (this.startPromise === opening) this.startPromise = null;
@@ -2501,24 +2592,111 @@ var CrossTabDataBus = class {
     );
     return opening;
   }
+  /** Return a cancellation-aware readiness view of the current queued start. */
+  getQueuedStartReady() {
+    const queued = this.queuedStart;
+    if (!queued) {
+      return Promise.reject(new Error("No queued start is in flight."));
+    }
+    const token = this.queuedStartToken;
+    if (this.queuedStartReady && this.queuedStartReadyToken === token) {
+      return this.queuedStartReady;
+    }
+    this.queuedStartReadyToken = token;
+    this.queuedStartReady = queued.then(() => {
+      if (token <= this.canceledQueuedStartToken) {
+        throw new Error(
+          "CrossTabDataBus start was canceled by a later stop(); ready() cannot report readiness. Call start() again after stop() resolves."
+        );
+      }
+      if (!this.started || !this.transportReady) {
+        throw new Error("CrossTabDataBus restart completed without a ready transport.");
+      }
+    });
+    return this.queuedStartReady;
+  }
+  /** Queue exactly one fresh start after an in-flight explicit stop settles. */
+  queueStartAfterStop(config) {
+    if (this.queuedStart) return this.queuedStart;
+    const stop = this.stopPromise ?? Promise.resolve();
+    const token = ++this.queuedStartToken;
+    const queued = stop.catch(() => void 0).then(() => {
+      if (this.queuedStart === queued) this.queuedStart = null;
+      if (token <= this.canceledQueuedStartToken) return;
+      return this.start(config);
+    });
+    this.queuedStart = queued;
+    return queued;
+  }
+  /** Release every operation waiting on the scheduled recovery attempt. */
+  releaseRecoveryGate() {
+    const release = this.recoveryGateRelease;
+    this.recoveryGate = null;
+    this.recoveryGateRelease = null;
+    this.recoveryDemandAllowed = false;
+    release?.();
+  }
+  /** Cancel a pending automatic retry when an explicit lifecycle transition
+   * supersedes it. The released gate re-enters runTransport(), which then
+   * follows the newest start/stop/suspend intent. */
+  cancelScheduledRecovery() {
+    this.recoveryTimerToken += 1;
+    if (this.recoveryTimer !== null) {
+      clearTimeout(this.recoveryTimer);
+      this.recoveryTimer = null;
+    }
+    this.releaseRecoveryGate();
+  }
+  /** Keep the recovery gate closed after a failed attempt while allowing the
+   * next explicit transport operation to start an immediate on-demand reopen.
+   * If no gate/successor retry remains, release any waiters. */
+  allowDemandRecovery() {
+    if (this.recoveryGate !== null && this.started && !this.stopping && !this.suspended && this.status === WORKER_STATUS.ERROR) {
+      this.recoveryDemandAllowed = true;
+      return;
+    }
+    this.releaseRecoveryGate();
+  }
+  /** Reset failure and recovery diagnostics for a new explicit start session. */
+  resetFailureState() {
+    this.cancelScheduledRecovery();
+    this.lastError = null;
+    this.lastErrorAt = null;
+    this.lastFailure = null;
+    this.persistenceFailureCount = 0;
+    this.persistenceLastFailureAt = null;
+    this.persistenceLastErrorMessage = null;
+    this.recoveryAttempt = 0;
+    this.recoveryExhausted = false;
+    this.lastRecoveryAt = 0;
+  }
   /**
    * Open the transport, chained after `before` to ensure lifecycle ordering.
    * When `stopClusterOnFailure` is true (initial start), a transport failure
    * tears down the cluster as well.
    */
-  openTransport(config, before, stopClusterOnFailure) {
+  openTransport(config, before, stopClusterOnFailure, lifecycleEpoch) {
     this.transportReady = false;
     const chainedPendingStop = this.pendingStop;
+    const isCurrentLifecycle = () => lifecycleEpoch === this.lifecycleEpoch;
     return before.catch(() => void 0).then(() => {
-      if (this.stopping || this.suspended) return;
+      if (!isCurrentLifecycle() || this.stopping || this.suspended) return;
       if (this.pendingStop === chainedPendingStop) this.pendingStop = null;
+      this.transportHasConnected = false;
       return Promise.resolve(
         this.transport.start(config, {
-          onMessage: (message) => this.handleTransportMessage(message),
-          onStatus: (status) => this.updateStatus(status),
-          onError: (error) => this.reportError(error)
+          onMessage: (message) => {
+            if (isCurrentLifecycle()) this.handleTransportMessage(message);
+          },
+          onStatus: (status) => {
+            if (isCurrentLifecycle()) this.updateStatus(status);
+          },
+          onError: (error) => {
+            if (isCurrentLifecycle()) this.reportError(error);
+          }
         })
       ).then(() => {
+        if (!isCurrentLifecycle()) return;
         if (this.status === WORKER_STATUS.ERROR) {
           throw new Error("Transport failed during startup.");
         }
@@ -2526,33 +2704,51 @@ var CrossTabDataBus = class {
           this.recoveryGeneration += 1;
           this.lastSuccessAt = this.now();
           this.transportReady = true;
+          this.releaseRecoveryGate();
         }
       });
     }).catch((error) => {
+      if (!isCurrentLifecycle()) throw error;
       if (stopClusterOnFailure) this.started = false;
       if (!this.pendingStop) {
         this.pendingStop = this.createStopPromise();
       }
+      this.transportReady = false;
       this.updateStatus(WORKER_STATUS.ERROR);
       this.reportError(error);
-      this.lastError = error;
-      this.lastErrorAt = this.now();
-      this.transportReady = false;
       if (stopClusterOnFailure) {
         this.stopping = true;
         this.cluster.stop();
         this.stopping = false;
       }
-      this.startPromise = null;
       throw error;
     });
   }
   /**
    * Await the DataBus to be fully started (lazy init when using initialConfig).
    * Returns a rejected promise when the transport has failed and no start is in
-   * flight — the caller can retry by calling start() or ready() again.
+   * flight — the caller can retry by calling start() or ready() again. While an
+   * explicit stop() is settling, this rejects unless a restart is queued behind
+   * it; false readiness during teardown is never reported. While the tab is
+   * BFCache-suspended (pagehide without a following pageshow), this also
+   * rejects: the suspended start promise is the transport-stop gate, not a
+   * readiness signal.
    */
   ready() {
+    if (this.queuedStart) return this.getQueuedStartReady();
+    if (this.stopping) {
+      return Promise.reject(new Error(
+        "CrossTabDataBus is stopping; ready() cannot report readiness until stop() resolves. Wait for stop() to resolve, then call start() before awaiting ready()."
+      ));
+    }
+    if (this.suspended) {
+      return Promise.reject(new Error(
+        "CrossTabDataBus is suspended; ready() cannot report readiness until pageshow resumes the transport."
+      ));
+    }
+    if (!this.started && !this.hasInitialConfig && this.lastError !== null) {
+      return Promise.reject(this.lastError);
+    }
     try {
       this.ensureStarted();
     } catch (error) {
@@ -2568,9 +2764,18 @@ var CrossTabDataBus = class {
   /**
    * Register a handler for `topic`. The handler fires on every publication
    * delivered to this tab, regardless of which tab published it. Returns an
-   * unsubscribe function for convenience.
+   * unsubscribe function for convenience. During an explicit stop() the
+   * registration is rejected through onError and a no-op cleanup is returned,
+   * so a late subscriber cannot leak into a future restart.
    */
   subscribe(topic, handler, options) {
+    if (this.stopping) {
+      this.reportError(new Error(
+        "CrossTabDataBus is stopping; subscribe() was not registered. Wait for stop() to resolve, then call start() before subscribing again."
+      ));
+      return () => {
+      };
+    }
     this.ensureStarted();
     const handlers = this.topicHandlers.get(topic) ?? /* @__PURE__ */ new Set();
     const wasUnused = handlers.size === 0;
@@ -2624,6 +2829,7 @@ var CrossTabDataBus = class {
   /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
   publish(topic, data, options) {
     this.ensureStarted();
+    if (this.rejectPublishDuringStop("publish")) return;
     if (!this.cluster.publish(topic, data, options)) {
       this.reportError(
         new Error("Failed to send the publish control message to the owning worker.")
@@ -2640,6 +2846,7 @@ var CrossTabDataBus = class {
   publishBatch(topic, items) {
     this.ensureStarted();
     if (items.length === 0) return;
+    if (this.rejectPublishDuringStop("publishBatch")) return;
     if (items.length === 1) {
       const first = items[0];
       this.publish(topic, first.data, first.options);
@@ -2674,11 +2881,15 @@ var CrossTabDataBus = class {
   getStatus() {
     return this.status;
   }
-  /** Return the current automatic transport recovery state. `hasError` means a transport error is currently retained. */
   /** Return the current automatic transport recovery state plus diagnostics.
-   * `generation` increments on every successful transport open (initial start
-   * and every recovery); `lastSuccessAt` is the timestamp of the most recent
-   * successful open, or `null` until the transport reaches `ready`. */
+   * `hasError`/`errorMessage`/`errorAt` describe the most recent retained
+   * *transport* failure — from a transport open or a runtime `onError`. They
+   * share the lifetime of the unified `lastFailure` ledger: a successful
+   * recovery keeps the last failure visible, and only an explicit `start()`
+   * clears it. `generation` increments on every successful transport open
+   * (initial start and every recovery); `lastSuccessAt` is the timestamp of
+   * the most recent successful open, or `null` until the transport reaches
+   * `ready`. */
   getRecoveryStats() {
     const errorMessage = this.lastError instanceof Error ? this.lastError.message : this.lastError === null ? null : String(this.lastError);
     return {
@@ -2705,7 +2916,7 @@ var CrossTabDataBus = class {
    * unified failure ledger and recovery context that explains the verdict. */
   getHealthSummary() {
     const transport = this.transport;
-    const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+    const transportDown = this.status !== WORKER_STATUS.CONNECTED;
     const state = !this.started ? HEALTH_STATE.STOPPED : this.suspended ? HEALTH_STATE.SUSPENDED : transportDown ? this.recoveryExhausted ? HEALTH_STATE.DEGRADED : this.status === WORKER_STATUS.CONNECTING && this.recoveryAttempt === 0 ? HEALTH_STATE.STARTING : HEALTH_STATE.RECOVERING : HEALTH_STATE.HEALTHY;
     return {
       healthy: state === HEALTH_STATE.HEALTHY,
@@ -2768,11 +2979,35 @@ var CrossTabDataBus = class {
   }
   /**
    * Gracefully stop the DataBus: unsubscribe all topics, stop the cluster,
-   * and close the transport. Idempotent.
+   * and close the transport. Concurrent and repeated calls share the in-flight
+   * stop promise. A start() received while stopping runs after this completes,
+   * unless another stop() arrives first and cancels that queued restart.
    */
-  async stop() {
-    if (!this.started) return;
+  stop() {
+    if (this.queuedStart) {
+      this.canceledQueuedStartToken = this.queuedStartToken;
+      this.queuedStart = null;
+    }
+    if (this.stopPromise) return this.stopPromise;
+    if (!this.started && !this.startPromise && !this.pendingStop && !this.transportReady) {
+      return Promise.resolve();
+    }
+    const stopPromise = this.performStop();
+    this.stopPromise = stopPromise;
+    void stopPromise.then(
+      () => {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      },
+      () => {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      }
+    );
+    return stopPromise;
+  }
+  async performStop() {
+    this.lifecycleEpoch += 1;
     this.stopping = true;
+    this.cancelScheduledRecovery();
     this.replayManager.suspend();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.STOP });
     this.trace.stop();
@@ -2785,6 +3020,8 @@ var CrossTabDataBus = class {
       const pendingStop = this.pendingStop;
       if (pendingStop) await pendingStop.catch(() => void 0);
       else await this.transport.stop();
+    } catch (error) {
+      this.reportError(error);
     } finally {
       this.transportSubscribedTopics.clear();
       this.resetDedup();
@@ -2850,10 +3087,12 @@ var CrossTabDataBus = class {
   updateStatus(status) {
     const previousStatus = this.status;
     this.status = status;
+    if (status === WORKER_STATUS.CONNECTED) this.transportHasConnected = true;
     if (previousStatus !== status) this.trace.event({ type: TRACE_EVENT_TYPE.STATUS, status });
     this.cluster.setStatus(status);
     if (status === WORKER_STATUS.DISCONNECTED || status === WORKER_STATUS.ERROR) this.transportSubscribedTopics.clear();
     if (status === WORKER_STATUS.CONNECTED && previousStatus !== WORKER_STATUS.CONNECTED) {
+      if (this.transportReady) this.releaseRecoveryGate();
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
     if (status === WORKER_STATUS.ERROR && this.started && !this.stopping) {
@@ -2866,23 +3105,49 @@ var CrossTabDataBus = class {
             this.recoveryExhausted = true;
             this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: this.recoveryMaxAttempts, outcome: RECOVERY_OUTCOME.EXHAUSTED });
           }
+          this.releaseRecoveryGate();
           return;
         }
         this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt, outcome: RECOVERY_OUTCOME.SCHEDULED });
-        setTimeout(() => {
-          if (this.stopping || !this.started || this.suspended) return;
-          if (this.status !== WORKER_STATUS.ERROR) return;
-          void this.reopenTransport(attempt);
+        if (this.recoveryGate === null) {
+          let release;
+          this.recoveryGate = new Promise((resolve) => {
+            release = resolve;
+          });
+          this.recoveryGateRelease = release;
+        }
+        this.recoveryDemandAllowed = false;
+        const timerToken = ++this.recoveryTimerToken;
+        this.recoveryTimer = setTimeout(() => {
+          if (timerToken !== this.recoveryTimerToken) return;
+          this.recoveryTimer = null;
+          if (this.stopping || !this.started || this.suspended || this.status !== WORKER_STATUS.ERROR) {
+            this.releaseRecoveryGate();
+            return;
+          }
+          this.recoveryDemandAllowed = false;
+          const opening = this.reopenTransport(attempt);
+          void opening.then(
+            () => this.releaseRecoveryGate(),
+            () => this.allowDemandRecovery()
+          );
         }, this.recoveryCooldownMs);
       }
+    } else if (status === WORKER_STATUS.ERROR) {
+      this.releaseRecoveryGate();
     }
     this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
   }
   reportError(error, source = FAILURE_SOURCE.TRANSPORT) {
+    const at = this.now();
+    if (source === FAILURE_SOURCE.TRANSPORT) {
+      this.lastError = error;
+      this.lastErrorAt = at;
+    }
     this.lastFailure = {
       source,
       message: error instanceof Error ? error.message : String(error),
-      at: this.now()
+      at
     };
     if (source === FAILURE_SOURCE.PERSISTENCE) {
       this.persistenceFailureCount += 1;
@@ -2963,7 +3228,9 @@ var CrossTabDataBus = class {
    */
   suspendTransport() {
     if (this.stopping) return;
+    this.lifecycleEpoch += 1;
     this.suspended = true;
+    this.cancelScheduledRecovery();
     this.transportReady = false;
     this.transportSubscribedTopics.clear();
     this.updateStatus(WORKER_STATUS.DISCONNECTED);
@@ -3001,19 +3268,23 @@ var CrossTabDataBus = class {
     this.started = true;
     this.suspended = false;
     this.updateStatus(WORKER_STATUS.CONNECTING);
+    const lifecycleEpoch = ++this.lifecycleEpoch;
     const pending = this.startPromise ?? this.pendingStop ?? Promise.resolve();
-    const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false));
+    const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false, lifecycleEpoch));
     this.startPromise = opening;
     void opening.then(
       () => {
+        if (this.startPromise === opening) this.startPromise = null;
+        if (lifecycleEpoch !== this.lifecycleEpoch) return;
         if (traceAttempt !== void 0) {
           this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: traceAttempt, outcome: RECOVERY_OUTCOME.SUCCEEDED });
           this.recoveryAttempt = 0;
           this.recoveryExhausted = false;
         }
-        if (this.startPromise === opening) this.startPromise = null;
       },
       () => {
+        if (this.startPromise === opening) this.startPromise = null;
+        if (lifecycleEpoch !== this.lifecycleEpoch) return;
         if (traceAttempt !== void 0) {
           this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: traceAttempt, outcome: RECOVERY_OUTCOME.FAILED });
         }
@@ -3029,7 +3300,24 @@ var CrossTabDataBus = class {
    */
   runTransport(operation) {
     if (this.suspended) return;
-    if (this.transportReady && !this.stopping) {
+    if (this.recoveryGate && !this.stopping) {
+      if (this.recoveryDemandAllowed && this.status === WORKER_STATUS.ERROR && !this.suspended) {
+        this.recoveryDemandAllowed = false;
+        const opening = this.reopenTransport();
+        void opening.then(
+          () => this.releaseRecoveryGate(),
+          () => this.allowDemandRecovery()
+        );
+      }
+      const gate = this.recoveryGate;
+      void gate.then(() => {
+        if (this.stopping || this.suspended) return;
+        this.runTransport(operation);
+      });
+      return;
+    }
+    const droppedAfterConnect = this.transportHasConnected && this.status === WORKER_STATUS.DISCONNECTED;
+    if (this.transportReady && this.status !== WORKER_STATUS.ERROR && !droppedAfterConnect && !this.stopping) {
       try {
         void Promise.resolve(operation()).catch((error) => this.reportError(error));
       } catch (error) {
@@ -3047,6 +3335,19 @@ var CrossTabDataBus = class {
       return operation();
     }).catch((error) => this.reportError(error));
   }
+  /**
+   * Publications started after teardown begins cannot reach any transport.
+   * Surface that as a normal asynchronous API failure instead of letting
+   * runTransport() return silently. Empty publishBatch() calls remain a no-op
+   * and are filtered by the caller before this check.
+   */
+  rejectPublishDuringStop(operation) {
+    if (!this.stopping) return false;
+    this.reportError(new Error(
+      `CrossTabDataBus is stopping; ${operation}() was not sent. Wait for stop() to resolve, then call start() before publishing again.`
+    ));
+    return true;
+  }
   /**
    * Ensure the DataBus is started, throwing if no initialConfig was provided.
    * Called automatically by subscribe/publish/ready when autoStart is true.
@@ -3152,35 +3453,29 @@ function createIndexedDbReplayPersistence(options) {
         grouped.set(message.topic, [...grouped.get(message.topic) ?? [], message]);
       }
       let hasError = false;
+      const fail = (error) => {
+        if (hasError) return;
+        hasError = true;
+        invalidate(db);
+        reject(error);
+      };
       for (const [topic, topicMessages] of grouped) {
         const request = store.get(topic);
         request.onsuccess = () => {
           if (hasError) return;
-          let history = (request.result?.messages ?? []).concat(topicMessages);
-          const ageBounded = pruneStrategy !== PRUNE_STRATEGY.COUNT && retentionMs !== void 0;
-          if (ageBounded) {
-            const cutoff = Date.now() - retentionMs;
-            history = history.filter((item) => item.timestamp === void 0 || item.timestamp >= cutoff);
-          }
-          if (pruneStrategy !== PRUNE_STRATEGY.AGE || !ageBounded) history = history.slice(-maxPerTopic);
+          const history = pruneReplayHistory(
+            (request.result?.messages ?? []).concat(topicMessages),
+            { maxPerTopic, pruneStrategy, retentionMs, now: Date.now() }
+          );
           store.put({ topic, messages: history });
         };
-        request.onerror = () => {
-          if (hasError) return;
-          hasError = true;
-          invalidate(db);
-          reject(request.error ?? new Error("Failed to read replay history."));
-        };
+        request.onerror = () => fail(request.error ?? new Error("Failed to read replay history."));
       }
       transaction.oncomplete = () => {
         if (!hasError) resolve();
       };
-      transaction.onerror = () => {
-        if (hasError) return;
-        hasError = true;
-        invalidate(db);
-        reject(transaction.error ?? new Error("Failed to persist replay history."));
-      };
+      transaction.onerror = () => fail(transaction.error ?? new Error("Failed to persist replay history."));
+      transaction.onabort = () => fail(transaction.error ?? new Error("Failed to persist replay history."));
     });
   })();
   const open = () => {
@@ -3208,19 +3503,34 @@ function createIndexedDbReplayPersistence(options) {
     async load() {
       const db = await open();
       return new Promise((resolve, reject) => {
+        let transaction;
         let request;
         try {
-          request = db.transaction(storeName, "readonly").objectStore(storeName).getAll();
+          transaction = db.transaction(storeName, "readonly");
+          request = transaction.objectStore(storeName).getAll();
         } catch (error) {
           invalidate(db);
           reject(error);
           return;
         }
-        request.onsuccess = () => resolve(request.result.flatMap((record) => record.messages));
-        request.onerror = () => {
+        let settled = false;
+        const fail = (error) => {
+          if (settled) return;
+          settled = true;
           invalidate(db);
-          reject(request.error ?? new Error("Failed to load replay history."));
+          reject(error);
+        };
+        let records = [];
+        request.onsuccess = () => {
+          records = request.result;
         };
+        request.onerror = () => fail(request.error ?? new Error("Failed to load replay history."));
+        transaction.oncomplete = () => {
+          if (settled) return;
+          settled = true;
+          resolve(records.flatMap((record) => record.messages));
+        };
+        transaction.onabort = () => fail(transaction.error ?? new Error("Failed to load replay history."));
       });
     },
     append(message) {
@@ -3244,12 +3554,20 @@ function createIndexedDbReplayPersistence(options) {
               reject(error);
               return;
             }
-            transaction.objectStore(storeName).clear();
-            transaction.oncomplete = () => resolve();
-            transaction.onerror = () => {
+            let settled = false;
+            const fail = (error) => {
+              if (settled) return;
+              settled = true;
               invalidate(db);
-              reject(transaction.error ?? new Error("Failed to clear replay history."));
+              reject(error);
             };
+            transaction.objectStore(storeName).clear();
+            transaction.oncomplete = () => {
+              settled = true;
+              resolve();
+            };
+            transaction.onerror = () => fail(transaction.error ?? new Error("Failed to clear replay history."));
+            transaction.onabort = () => fail(transaction.error ?? new Error("Failed to clear replay history."));
           });
         })()
       });
@@ -3268,12 +3586,20 @@ function createIndexedDbReplayPersistence(options) {
               reject(error);
               return;
             }
-            transaction.objectStore(storeName).delete(topic);
-            transaction.oncomplete = () => resolve();
-            transaction.onerror = () => {
+            let settled = false;
+            const fail = (error) => {
+              if (settled) return;
+              settled = true;
               invalidate(db);
-              reject(transaction.error ?? new Error("Failed to clear topic replay history."));
+              reject(error);
             };
+            transaction.objectStore(storeName).delete(topic);
+            transaction.oncomplete = () => {
+              settled = true;
+              resolve();
+            };
+            transaction.onerror = () => fail(transaction.error ?? new Error("Failed to clear topic replay history."));
+            transaction.onabort = () => fail(transaction.error ?? new Error("Failed to clear topic replay history."));
           });
         })()
       });
@@ -3292,6 +3618,13 @@ function createIndexedDbReplayPersistence(options) {
               reject(error);
               return;
             }
+            let settled = false;
+            const fail = (error) => {
+              if (settled) return;
+              settled = true;
+              invalidate(db);
+              reject(error);
+            };
             const store = transaction.objectStore(storeName);
             const request = store.getAll();
             request.onsuccess = () => {
@@ -3301,15 +3634,13 @@ function createIndexedDbReplayPersistence(options) {
                 else if (messages.length !== record.messages.length) store.put({ topic: record.topic, messages });
               }
             };
-            request.onerror = () => {
-              invalidate(db);
-              reject(request.error ?? new Error("Failed to read replay history."));
-            };
-            transaction.oncomplete = () => resolve();
-            transaction.onerror = () => {
-              invalidate(db);
-              reject(transaction.error ?? new Error("Failed to prune replay history."));
+            request.onerror = () => fail(request.error ?? new Error("Failed to read replay history."));
+            transaction.oncomplete = () => {
+              settled = true;
+              resolve();
             };
+            transaction.onerror = () => fail(transaction.error ?? new Error("Failed to prune replay history."));
+            transaction.onabort = () => fail(transaction.error ?? new Error("Failed to prune replay history."));
           });
         })()
       });
@@ -3340,6 +3671,7 @@ function parseDataBusPublication(value, fallbackTopic) {
 }
 
 // src/websocket.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 var WS_OPEN = 1;
 var WebSocketTransport = class {
   constructor(connection) {
@@ -3349,12 +3681,27 @@ var WebSocketTransport = class {
   diagnosticsName = "websocket";
   diagnosticsBackend = "native-websocket";
   socket = null;
+  socketActive = false;
   handlers = null;
   subscribedTopics = /* @__PURE__ */ new Set();
-  /** Open the WebSocket and wire lifecycle listeners. A factory failure is
-   * reported through `onStatus('error')` so the DataBus can recover. */
+  // Handshake gate for the current start(). Resolves once the socket opens,
+  // rejects when the attempt fails, so the DataBus start Promise — and every
+  // operation parked behind it — settles at the real connection boundary.
+  connectPromise = null;
+  connectResolve = null;
+  connectReject = null;
+  connectTimer = null;
+  /** Open the WebSocket and wire lifecycle listeners. Resolves once the
+   * handshake completes and rejects when the attempt fails, matching the
+   * `DataBusTransport.start` contract ("resolves on connect or rejects on
+   * failure"). A factory failure is reported through `onStatus('error')` so
+   * the DataBus can recover. */
   start(config, handlers) {
-    if (this.socket) return;
+    if (this.socket && this.socketActive) {
+      return this.connectPromise ?? void 0;
+    }
+    this.socket = null;
+    this.socketActive = false;
     this.handlers = handlers;
     const factory = config.webSocketFactory ?? this.connection.webSocketFactory ?? defaultWebSocketFactory;
     const protocols = config.protocols ?? this.connection.protocols;
@@ -3366,23 +3713,66 @@ var WebSocketTransport = class {
       handlers.onError(error);
       return;
     }
-    socket.onopen = () => {
-      if (this.socket !== socket || this.handlers !== handlers) return;
-      for (const topic of this.subscribedTopics) {
-        this.sendFrame({ op: WS_OP.SUBSCRIBE, topic });
+    const opening = new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+      let handshakeCompleted = false;
+      let handshakeFailed = false;
+      const timeoutMs = config.connectTimeoutMs ?? this.connection.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+      if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        this.connectTimer = setTimeout(() => {
+          if (this.socket !== socket || this.handlers !== handlers || handshakeCompleted) return;
+          handshakeFailed = true;
+          this.connectTimer = null;
+          this.socketActive = false;
+          const error = new Error(`WebSocket did not open within ${timeoutMs}ms.`);
+          handlers.onStatus(WORKER_STATUS.ERROR);
+          handlers.onError(error);
+          this.failConnect(error);
+          socket.close();
+        }, timeoutMs);
       }
-      handlers.onStatus(WORKER_STATUS.CONNECTED);
-    };
-    socket.onclose = () => {
-      if (this.socket === socket && this.handlers === handlers) handlers.onStatus(WORKER_STATUS.DISCONNECTED);
-    };
-    socket.onerror = () => {
-      if (this.socket === socket && this.handlers === handlers) handlers.onStatus(WORKER_STATUS.ERROR);
-    };
-    socket.onmessage = (event) => {
-      if (this.socket === socket && this.handlers === handlers) void this.handleMessage(event.data);
-    };
-    this.socket = socket;
+      socket.onopen = () => {
+        if (this.socket !== socket || this.handlers !== handlers || handshakeFailed) return;
+        this.socketActive = true;
+        this.clearConnectTimer();
+        for (const topic of this.subscribedTopics) {
+          this.sendFrame({ op: WS_OP.SUBSCRIBE, topic });
+        }
+        handlers.onStatus(WORKER_STATUS.CONNECTED);
+        if (!handshakeCompleted) {
+          handshakeCompleted = true;
+          this.settleConnect();
+        }
+      };
+      socket.onclose = () => {
+        if (this.socket !== socket || this.handlers !== handlers || !this.socketActive) return;
+        this.socketActive = false;
+        handlers.onStatus(WORKER_STATUS.DISCONNECTED);
+        if (!handshakeCompleted) {
+          handshakeFailed = true;
+          this.failConnect(new Error("WebSocket closed before the handshake completed."));
+        }
+      };
+      socket.onerror = () => {
+        if (this.socket !== socket || this.handlers !== handlers || !this.socketActive) return;
+        this.socketActive = false;
+        handlers.onStatus(WORKER_STATUS.ERROR);
+        if (!handshakeCompleted) {
+          handshakeFailed = true;
+          this.failConnect(new Error("WebSocket failed to open."));
+        }
+      };
+      socket.onmessage = (event) => {
+        if (this.socket === socket && this.handlers === handlers && this.socketActive) {
+          void this.handleMessage(event.data);
+        }
+      };
+      this.socket = socket;
+      this.socketActive = true;
+    });
+    this.connectPromise = opening;
+    return opening;
   }
   /** Idempotent: re-subscribing an active topic re-sends the frame but does
    * not duplicate the local tracking entry. */
@@ -3438,10 +3828,38 @@ var WebSocketTransport = class {
   /** Close the socket and drop all state. Safe to call multiple times. */
   stop() {
     const socket = this.socket;
+    const shouldClose = this.socketActive;
     this.socket = null;
+    this.socketActive = false;
     this.handlers = null;
     this.subscribedTopics.clear();
-    socket?.close();
+    this.settleConnect();
+    this.connectPromise = null;
+    if (shouldClose) socket?.close();
+  }
+  /** Resolve the in-flight handshake gate. Idempotent: once the socket has
+   * opened (or a newer attempt replaced it) later calls are no-ops. */
+  settleConnect() {
+    this.clearConnectTimer();
+    const resolve = this.connectResolve;
+    this.connectResolve = null;
+    this.connectReject = null;
+    resolve?.();
+  }
+  /** Reject the in-flight handshake gate. Idempotent on the same terms as
+   * {@link settleConnect}. */
+  failConnect(error) {
+    this.clearConnectTimer();
+    const reject = this.connectReject;
+    this.connectResolve = null;
+    this.connectReject = null;
+    reject?.(error);
+  }
+  clearConnectTimer() {
+    if (this.connectTimer !== null) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
   }
   /** Send one JSON frame. Frames are dropped with an `onError` report when
    * the socket is not open — subscribe frames are re-sent on open, so the