cross-tab-worker-databus 0.1.2 → 0.2.1

package/dist/{chunk-53INHVYO.js → chunk-LBXREMZA.js}

@@ -80,23 +80,36 @@ function getOrCreateTabId(environment, key = "cross-tab-worker-databus:tab-id")
 
 // src/core/hash.ts
 function createOpaqueKey(value) {
-  let h1 = 3735928559 ^ value.length;
-  let h2 = 1103547991 ^ value.length;
-  let h3 = 3235826430 ^ value.length;
-  let h4 = 2654435769 ^ value.length;
+  let h1 = SEED_H1 ^ value.length;
+  let h2 = SEED_H2 ^ value.length;
+  let h3 = SEED_H3 ^ value.length;
+  let h4 = SEED_H4 ^ value.length;
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);
-    h1 = Math.imul(h1 ^ code, 2654435761);
-    h2 = Math.imul(h2 ^ code, 1597334677);
-    h3 = Math.imul(h3 ^ code, 2246822519);
-    h4 = Math.imul(h4 ^ code, 3266489917);
-  }
-  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
-  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h3 ^ h3 >>> 13, 3266489909);
-  h3 = Math.imul(h3 ^ h3 >>> 16, 2246822507) ^ Math.imul(h4 ^ h4 >>> 13, 3266489909);
-  h4 = Math.imul(h4 ^ h4 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+    h1 = Math.imul(h1 ^ code, PRIME_H1);
+    h2 = Math.imul(h2 ^ code, PRIME_H2);
+    h3 = Math.imul(h3 ^ code, PRIME_H3);
+    h4 = Math.imul(h4 ^ code, PRIME_H4);
+  }
+  h1 = avalancheMix(h1, h2);
+  h2 = avalancheMix(h2, h3);
+  h3 = avalancheMix(h3, h4);
+  h4 = avalancheMix(h4, h1);
   return [h1, h2, h3, h4].map((hash) => (hash >>> 0).toString(16).padStart(8, "0")).join("");
 }
+var SEED_H1 = 3735928559;
+var SEED_H2 = 1103547991;
+var SEED_H3 = 3235826430;
+var SEED_H4 = 2654435769;
+var PRIME_H1 = 2654435761;
+var PRIME_H2 = 1597334677;
+var PRIME_H3 = 2246822519;
+var PRIME_H4 = 3266489917;
+var AVALANCHE_PRIME = 2246822507;
+var AVALANCHE_CROSS = 3266489909;
+function avalancheMix(self, neighbor) {
+  return Math.imul(self ^ self >>> 16, AVALANCHE_PRIME) ^ Math.imul(neighbor ^ neighbor >>> 13, AVALANCHE_CROSS);
+}
 
 // src/core/routing.ts
 var DEFAULT_MAX_ACTIVE_WORKERS = 3;
@@ -107,7 +120,8 @@ function selectLeastLoadedWorker(workers, preferredWorkerId) {
     if (!least) return worker;
     const byLoad = worker.load - least.load;
     if (byLoad !== 0) return byLoad < 0 ? worker : least;
-    return worker.workerId.localeCompare(least.workerId) < 0 ? worker : least;
+    if (worker.workerId < least.workerId) return worker;
+    return least;
   }, void 0);
 }
 function selectActiveWorkers(workers, maxActiveWorkers = DEFAULT_MAX_ACTIVE_WORKERS) {
@@ -116,7 +130,7 @@ function selectActiveWorkers(workers, maxActiveWorkers = DEFAULT_MAX_ACTIVE_WORK
   const visibleWorkers = availableWorkers.filter((worker) => worker.visibilityState === "visible");
   const candidates = visibleWorkers.length > 0 ? visibleWorkers : availableWorkers;
   return candidates.sort(
-    (left, right) => left.registeredAt - right.registeredAt || left.workerId.localeCompare(right.workerId)
+    (left, right) => left.registeredAt - right.registeredAt || (left.workerId < right.workerId ? -1 : left.workerId > right.workerId ? 1 : 0)
   ).slice(0, maxActiveWorkers);
 }
 function selectRebalanceTarget(workers, currentWorkerId) {
@@ -146,6 +160,9 @@ var BatchingStorageWriter = class {
   flushScheduled = false;
   retryHandle = null;
   retryDelayMs = INITIAL_RETRY_DELAY_MS;
+  /** Number of writes queued in memory but not yet flushed to storage.
+   * Used by tests to assert the coalescing window and by flush() to detect
+   * the all-drained state. */
   get pendingSize() {
     return this.pending.size;
   }
@@ -180,7 +197,7 @@ var BatchingStorageWriter = class {
   flush() {
     this.flushScheduled = false;
     this.cancelRetry();
-    for (const [key, value] of [...this.pending]) {
+    for (const [key, value] of Array.from(this.pending)) {
       try {
         if (value === null) this.storage.removeItem(key);
         else this.storage.setItem(key, value);
@@ -217,10 +234,12 @@ var BatchingStorageWriter = class {
       if (value === null) keys.delete(key);
       else keys.add(key);
     }
-    return [...keys];
+    return Array.from(keys);
   }
   // Coalesce all synchronous writes within one task into a single microtask
   // flush, avoiding a localStorage write per heartbeat/route/subscriber update.
+  // The queueMicrotask fallback to setTimeout handles older runtimes and
+  // non-browser environments where queueMicrotask is absent.
   scheduleFlush() {
     if (this.flushScheduled) return;
     this.flushScheduled = true;
@@ -231,6 +250,9 @@ var BatchingStorageWriter = class {
     if (typeof queueMicrotask === "function") queueMicrotask(flush);
     else setTimeout(flush, 0);
   }
+  // Schedule a single retry timer. The guard ensures only one retry is in
+  // flight at a time; subsequent scheduleRetry calls during the wait are
+  // no-ops because the first retry will re-flush all pending keys together.
   scheduleRetry() {
     if (this.retryHandle !== null) return;
     this.retryHandle = setTimeout(() => {
@@ -275,6 +297,9 @@ function listKeys(storage, prefix) {
     return [];
   }
 }
+function readAllByPrefix(storage, prefix) {
+  return listKeys(storage, prefix).map((key) => ({ key, value: readJson(storage, key) })).filter((entry) => entry.value !== null);
+}
 var WorkerClusterRuntime = class {
   tabId;
   workerId;
@@ -344,6 +369,9 @@ var WorkerClusterRuntime = class {
   /**
    * Stop the cluster: pause heartbeats, hand off assigned topics, remove
    * the worker record, and clean up lifecycle listeners. Idempotent.
+   * The .clear() calls after pause() are safe no-ops when pause already
+   * cleared the maps (the handoff path), but ensure a full teardown in the
+   * stop() path where callers expect every Set/Map to be empty afterwards.
    */
   stop() {
     if (!this.started && !this.suspended) return;
@@ -374,12 +402,10 @@ var WorkerClusterRuntime = class {
     };
     this.refreshRole(this.readWorkers());
     this.writeRecord(true);
-    if (!this.storage) {
-      for (const topic of this.subscribedTopics) {
-        this.sendControl(this.workerId, "SUBSCRIBE", topic, this.rememberTopic(topic));
-      }
-    } else {
-      for (const topic of this.subscribedTopics) this.writeSubscriber(this.rememberTopic(topic));
+    for (const topic of this.subscribedTopics) {
+      const topicKey = this.rememberTopic(topic);
+      if (!this.storage) this.sendControl(this.workerId, "SUBSCRIBE", topic, topicKey);
+      else this.writeSubscriber(topicKey);
     }
     this.reconcile();
     this.heartbeatHandle = this.environment.setInterval(() => {
@@ -430,8 +456,8 @@ var WorkerClusterRuntime = class {
     this.writeSubscriber(topicKey);
     const workers = this.readWorkers();
     const existingRoute = this.readRoute(topicKey);
-    if (existingRoute && workers.some((worker) => worker.workerId === existingRoute.workerId)) {
-      return existingRoute.workerId === this.workerId;
+    if (this.routeOwnerIsLive(existingRoute, workers)) {
+      return existingRoute?.workerId === this.workerId;
     }
     const activeWorkers = selectActiveWorkers(workers, this.maxActiveWorkers);
     const owner = selectLeastLoadedWorker(activeWorkers) ?? this.currentRecord;
@@ -445,22 +471,24 @@ var WorkerClusterRuntime = class {
    * subscribers remain, deletes the route so the owning Worker can unsubscribe.
    */
   unsubscribe(topic) {
-    const topicKey = this.rememberTopic(topic);
     this.subscribedTopics.delete(topic);
-    this.releaseSubscription(topic);
-    if (!this.assignedTopics.has(topicKey)) this.knownTopics.delete(topicKey);
+    const topicKey = this.releaseSubscription(topic);
+    if (topicKey && !this.assignedTopics.has(topicKey)) this.knownTopics.delete(topicKey);
   }
-  /** Remove this tab's subscriber record and, when it was the last one, delete the route. */
+  /** Remove this tab's subscriber record and, when it was the last one, delete
+   * the route. Returns the topicKey (so callers like `unsubscribe` can reuse
+   * it instead of re-hashing the topic to evict the reverse cache). */
   releaseSubscription(topic, notifyOwner = true) {
     const topicKey = this.rememberTopic(topic);
     this.removeStorage(this.subscriberStorageKey(topicKey, this.tabId));
     const route = this.readRoute(topicKey);
-    if (!route) return;
+    if (!route) return topicKey;
     const subscribers = this.readSubscriberTabIds(topicKey, this.readWorkers());
     if (subscribers.length === 0) {
       this.removeStorage(this.routeStorageKey(topicKey));
       if (notifyOwner) this.sendControl(route.workerId, "UNSUBSCRIBE", topic, topicKey);
     }
+    return topicKey;
   }
   /** Transfer assigned topics to other active workers so subscribers are not orphaned during pause. */
   handoffAssignedTopics() {
@@ -469,7 +497,8 @@ var WorkerClusterRuntime = class {
     const activeWorkers = selectActiveWorkers(remainingWorkers, this.maxActiveWorkers);
     const projectedLoads = new Map(activeWorkers.map((worker) => [worker.workerId, worker.load]));
     for (const [topicKey, topic] of this.assignedTopics) {
-      if (this.readRoute(topicKey)?.workerId !== this.workerId) continue;
+      const previous = this.readRoute(topicKey);
+      if (previous?.workerId !== this.workerId) continue;
       const subscribers = this.readSubscriberTabIds(topicKey, remainingWorkers);
       if (subscribers.length === 0) {
         this.removeStorage(this.routeStorageKey(topicKey));
@@ -480,19 +509,11 @@ var WorkerClusterRuntime = class {
       );
       if (!owner) continue;
       projectedLoads.set(owner.workerId, (projectedLoads.get(owner.workerId) ?? owner.load) + 1);
-      const previous = this.readRoute(topicKey);
-      this.writeRoute(topicKey, owner, previous?.workerId, (previous?.generation ?? 0) + 1);
-      this.flushStorage();
       const generation = (previous?.generation ?? 0) + 1;
+      this.writeRoute(topicKey, owner, previous?.workerId, generation);
+      this.flushStorage();
       this.handlers.onControl("UNSUBSCRIBE", topic);
-      this.send({
-        type: "ROUTE_RELEASED",
-        sourceWorkerId: this.workerId,
-        targetWorkerId: owner.workerId,
-        topic,
-        topicKey,
-        generation
-      });
+      this.sendRouteReleased(owner.workerId, topic, topicKey, generation);
     }
   }
   /**
@@ -505,8 +526,15 @@ var WorkerClusterRuntime = class {
     const topicKey = this.rememberTopic(topic);
     const workers = this.readWorkers();
     const route = this.readRoute(topicKey);
-    const target = route && workers.some((worker) => worker.workerId === route.workerId) ? route.workerId : this.workerId;
-    return this.sendControl(target ?? this.workerId, "PUBLISH", topic, topicKey, data);
+    const target = this.routeOwnerIsLive(route, workers) ? route?.workerId ?? this.workerId : this.workerId;
+    return this.sendControl(target, "PUBLISH", topic, topicKey, data);
+  }
+  /** True when `route` exists and its owner worker is among `workers`.
+   * Shared by subscribe (skip re-assignment) and publish (route to owner).
+   * Intentionally returns a plain boolean (not a type guard) so the caller
+   * can still access `route?.generation` in the false branch. */
+  routeOwnerIsLive(route, workers) {
+    return Boolean(route && workers.some((worker) => worker.workerId === route.workerId));
   }
   /** Broadcast an event to every tab — used to fan out transport publications. */
   broadcastEvent(eventType, payload) {
@@ -519,7 +547,12 @@ var WorkerClusterRuntime = class {
   }
   /** True if this worker is among the active set (eligible to own topics). */
   isActiveWorker() {
-    return selectActiveWorkers(this.readWorkers(), this.maxActiveWorkers).some(
+    return this.isActiveAmong(this.readWorkers());
+  }
+  /** True when this workerId is in the active subset of `workers`. Shared by
+   * isActiveWorker() and refreshRole() so both compute role identically. */
+  isActiveAmong(workers) {
+    return selectActiveWorkers(workers, this.maxActiveWorkers).some(
       (worker) => worker.workerId === this.workerId
     );
   }
@@ -529,19 +562,19 @@ var WorkerClusterRuntime = class {
   }
   /** Read-only snapshot of the cluster state (workers, routes, assignments). */
   getSnapshot() {
-    const routes = listKeysSafe(this.storage, this.routePrefix).map((key) => this.storage ? readJson(this.storage, key) : null).filter((route) => Boolean(route)).map((route) => ({
-      ...route,
-      topic: this.knownTopics.get(route.topicKey) ?? null
-    }));
+    const routes = this.storage ? readAllByPrefix(this.storage, this.routePrefix).map(({ value }) => ({
+      ...value,
+      topic: this.knownTopics.get(value.topicKey) ?? null
+    })) : [];
     return {
       coordinated: Boolean(this.storage && this.channel),
       suspended: this.suspended,
       currentWorker: { ...this.currentRecord },
       workers: this.readWorkers().map((worker) => ({ ...worker })),
       routes,
-      subscribedTopics: [...this.subscribedTopics],
-      assignedTopics: [...this.assignedTopics.values()],
-      knownTopics: [...this.knownTopics.entries()].map(([topicKey, topic]) => ({ topicKey, topic }))
+      subscribedTopics: Array.from(this.subscribedTopics),
+      assignedTopics: Array.from(this.assignedTopics.values()),
+      knownTopics: Array.from(this.knownTopics.entries(), ([topicKey, topic]) => ({ topicKey, topic }))
     };
   }
   handlePageHide = () => this.pause();
@@ -578,24 +611,35 @@ var WorkerClusterRuntime = class {
   handleMessage = (event) => {
     const message = event.data;
     if (!message || message.sourceWorkerId === this.workerId) return;
-    if (message.type === "CONTROL") return this.handleControlMessage(message);
-    if (message.type === "ROUTE_RELEASED") return this.handleRouteReleasedMessage(message);
-    if (message.type === "EVENT") {
-      this.handlers.onEvent(message.eventType, message.payload, message.sourceWorkerId);
-      return;
+    switch (message.type) {
+      case "CONTROL":
+        return this.handleControlMessage(message);
+      case "ROUTE_RELEASED":
+        return this.handleRouteReleasedMessage(message);
+      case "EVENT":
+        this.handlers.onEvent(message.eventType, message.payload, message.sourceWorkerId);
+        return;
+      case "REGISTRY":
+      default:
+        this.reconcile();
+        return;
     }
-    this.reconcile();
   };
   /** Handle a point-to-point CONTROL message (SUBSCRIBE / UNSUBSCRIBE / PUBLISH). */
   handleControlMessage(message) {
     if (message.targetWorkerId !== this.workerId) return;
     this.rememberTopic(message.topic);
-    if (message.action === "SUBSCRIBE") {
-      this.assignedTopics.set(message.topicKey, message.topic);
-      this.confirmRoute(message.topicKey);
-    }
-    if (message.action === "UNSUBSCRIBE") {
-      if (this.releaseHandoffOnUnsubscribe(message)) return;
+    switch (message.action) {
+      case "SUBSCRIBE":
+        this.assignedTopics.set(message.topicKey, message.topic);
+        this.confirmRoute(message.topicKey);
+        break;
+      case "UNSUBSCRIBE":
+        if (this.releaseHandoffOnUnsubscribe(message)) return;
+        break;
+      case "PUBLISH":
+      default:
+        break;
     }
     this.handlers.onControl(message.action, message.topic, message.data);
     if (message.action !== "PUBLISH") this.updateLoad();
@@ -611,16 +655,21 @@ var WorkerClusterRuntime = class {
     const route = this.readRoute(message.topicKey);
     if (route?.handoffFromWorkerId !== this.workerId) return false;
     this.handlers.onControl("UNSUBSCRIBE", message.topic, void 0);
+    this.sendRouteReleased(route.workerId, message.topic, message.topicKey, route.generation);
+    this.updateLoad();
+    return true;
+  }
+  /** Post a ROUTE_RELEASED ACK to the new owner, carrying the current route
+   * generation so only the matching new owner may act on it. */
+  sendRouteReleased(targetWorkerId, topic, topicKey, generation) {
     this.send({
       type: "ROUTE_RELEASED",
       sourceWorkerId: this.workerId,
-      targetWorkerId: route.workerId,
-      topic: message.topic,
-      topicKey: message.topicKey,
-      generation: route.generation
+      targetWorkerId,
+      topic,
+      topicKey,
+      generation
     });
-    this.updateLoad();
-    return true;
   }
   /**
    * Accept a graceful handoff only when the route still points to this worker,
@@ -630,12 +679,18 @@ var WorkerClusterRuntime = class {
   handleRouteReleasedMessage(message) {
     if (message.targetWorkerId !== this.workerId) return;
     const route = this.readRoute(message.topicKey);
-    if (!route || route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || route.generation < message.generation) return;
+    if (!route || this.isStaleRouteRelease(route, message)) return;
     this.assignedTopics.set(message.topicKey, message.topic);
     this.confirmRoute(message.topicKey);
     this.handlers.onControl("SUBSCRIBE", message.topic, void 0);
     this.updateLoad();
   }
+  /** A ROUTE_RELEASED is stale (and must be dropped) unless the route still
+   * points to us, the release comes from the recorded previous owner, and
+   * the release generation is at least as new as ours. */
+  isStaleRouteRelease(route, message) {
+    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || route.generation < message.generation;
+  }
   /** Full reconciliation cycle: workers, subscriptions, and assigned topics. */
   reconcile() {
     if (!this.started) return;
@@ -645,7 +700,9 @@ var WorkerClusterRuntime = class {
     this.reconcileAssignedTopics();
     this.updateLoad();
   }
-  /** Prune stale workers/subscribers/routes and refresh role. Returns the live worker list. */
+  /** Prune stale workers/subscribers/routes and refresh role. Returns the live worker list.
+   * Subscribers are cleaned before routes so cleanupOrphanedRoutes sees the
+   * updated subscriber set when deciding whether a route is truly orphaned. */
   reconcileWorkers() {
     const workers = this.readWorkers();
     this.cleanupOrphanedSubscribers(workers);
@@ -686,19 +743,12 @@ var WorkerClusterRuntime = class {
   /** Drop assignments where the route no longer points to this worker. */
   reconcileAssignedTopics() {
     for (const [topicKey, topic] of [...this.assignedTopics]) {
-      if (this.readRoute(topicKey)?.workerId === this.workerId) continue;
+      const route = this.readRoute(topicKey);
+      if (route?.workerId === this.workerId) continue;
       this.assignedTopics.delete(topicKey);
       this.handlers.onControl("UNSUBSCRIBE", topic, void 0);
-      const route = this.readRoute(topicKey);
       if (route?.handoffFromWorkerId === this.workerId) {
-        this.send({
-          type: "ROUTE_RELEASED",
-          sourceWorkerId: this.workerId,
-          targetWorkerId: route.workerId,
-          topic,
-          topicKey,
-          generation: route.generation
-        });
+        this.sendRouteReleased(route.workerId, topic, topicKey, route.generation);
       }
       if (!this.subscribedTopics.has(topic)) this.knownTopics.delete(topicKey);
     }
@@ -710,11 +760,18 @@ var WorkerClusterRuntime = class {
    */
   sendControl(targetWorkerId, action, topic, topicKey, data) {
     if (targetWorkerId === this.workerId) {
-      if (action === "SUBSCRIBE") {
-        this.assignedTopics.set(topicKey, topic);
-        this.confirmRoute(topicKey);
+      switch (action) {
+        case "SUBSCRIBE":
+          this.assignedTopics.set(topicKey, topic);
+          this.confirmRoute(topicKey);
+          break;
+        case "UNSUBSCRIBE":
+          this.assignedTopics.delete(topicKey);
+          break;
+        case "PUBLISH":
+        default:
+          break;
       }
-      if (action === "UNSUBSCRIBE") this.assignedTopics.delete(topicKey);
       this.handlers.onControl(action, topic, data);
       if (action !== "PUBLISH") this.updateLoad();
       return true;
@@ -744,9 +801,7 @@ var WorkerClusterRuntime = class {
     if (!this.storage) return [this.currentRecord];
     const now = this.environment.now();
     const workers = [];
-    for (const key of listKeys(this.storage, this.workerPrefix)) {
-      const worker = readJson(this.storage, key);
-      if (!worker) continue;
+    for (const { key, value: worker } of readAllByPrefix(this.storage, this.workerPrefix)) {
       if (worker.workerId !== this.workerId && now - worker.heartbeatAt > this.workerTtlMs) {
         this.removeStorage(key);
         continue;
@@ -758,44 +813,62 @@ var WorkerClusterRuntime = class {
   }
   /** Enumerate all tab IDs that have a subscriber record for `topicKey`. */
   readSubscriberTabIds(topicKey, workers) {
-    if (!this.storage) return this.subscribedTopics.has(this.knownTopics.get(topicKey) ?? "") ? [this.tabId] : [];
+    if (!this.storage) {
+      const topic = this.knownTopics.get(topicKey);
+      return topic && this.subscribedTopics.has(topic) ? [this.tabId] : [];
+    }
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
     const subscribers = /* @__PURE__ */ new Set();
-    for (const key of listKeys(this.storage, `${this.subscriberPrefix}${topicKey}:`)) {
-      const record = readJson(this.storage, key);
-      if (!record || !activeTabIds.has(record.tabId)) {
+    for (const { key, value: record } of readAllByPrefix(
+      this.storage,
+      `${this.subscriberPrefix}${topicKey}:`
+    )) {
+      if (!activeTabIds.has(record.tabId)) {
         this.removeStorage(key);
         continue;
       }
       subscribers.add(record.tabId);
     }
-    return [...subscribers];
+    return Array.from(subscribers);
   }
   /** Read the current route for `topicKey`, returning null when no storage layer exists. */
   readRoute(topicKey) {
-    if (!this.storage) {
-      const topic = this.knownTopics.get(topicKey);
-      return topic && (this.subscribedTopics.has(topic) || this.assignedTopics.has(topicKey)) ? {
-        topicKey,
-        workerId: this.workerId,
-        tabId: this.tabId,
-        updatedAt: this.environment.now(),
-        generation: 1
-      } : null;
-    }
+    if (!this.storage) return this.buildLocalRoute(topicKey);
     return readJson(this.storage, this.routeStorageKey(topicKey));
   }
+  /** Synthesize a self-owned route when storage is unavailable (degraded mode).
+   * The plaintext topic must be recoverable from the knownTopics cache; a
+   * missing entry means we never subscribed to or were assigned the topic,
+   * so there is no route to report. */
+  buildLocalRoute(topicKey) {
+    const topic = this.knownTopics.get(topicKey);
+    if (!topic) return null;
+    if (!this.subscribedTopics.has(topic) && !this.assignedTopics.has(topicKey)) return null;
+    return {
+      topicKey,
+      workerId: this.workerId,
+      tabId: this.tabId,
+      updatedAt: this.environment.now(),
+      generation: 1
+    };
+  }
   /** Persist a route assignment, mapping `topicKey` to the owning Worker. */
   writeRoute(topicKey, owner, handoffFromWorkerId, generation = 1) {
     if (!this.storage) return;
-    writeJson(this.storage, this.routeStorageKey(topicKey), {
+    writeJson(this.storage, this.routeStorageKey(topicKey), this.buildRouteRecord(topicKey, owner, handoffFromWorkerId, generation));
+  }
+  /** Construct a WorkerRoute record from the owner + handoff fields. Extracted
+   * so writeRoute and confirmRoute share the same shape; confirmedAt is added
+   * by confirmRoute via spread. */
+  buildRouteRecord(topicKey, owner, handoffFromWorkerId, generation) {
+    return {
       topicKey,
       workerId: owner.workerId,
       tabId: owner.tabId,
       updatedAt: this.environment.now(),
       generation,
       ...handoffFromWorkerId ? { handoffFromWorkerId } : {}
-    });
+    };
   }
   /** Stamp a route as confirmed once the owning Worker has acknowledged the assignment. */
   confirmRoute(topicKey) {
@@ -811,9 +884,8 @@ var WorkerClusterRuntime = class {
   cleanupOrphanedRoutes(workers) {
     if (!this.storage) return;
     const now = this.environment.now();
-    for (const key of listKeys(this.storage, this.routePrefix)) {
-      const route = readJson(this.storage, key);
-      if (!route || now - route.updatedAt <= this.workerTtlMs) continue;
+    for (const { key, value: route } of readAllByPrefix(this.storage, this.routePrefix)) {
+      if (now - route.updatedAt <= this.workerTtlMs) continue;
       if (this.readSubscriberTabIds(route.topicKey, workers).length > 0) continue;
       this.removeStorage(key);
     }
@@ -822,9 +894,8 @@ var WorkerClusterRuntime = class {
   cleanupOrphanedSubscribers(workers) {
     if (!this.storage) return;
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
-    for (const key of listKeys(this.storage, this.subscriberPrefix)) {
-      const record = readJson(this.storage, key);
-      if (!record || !activeTabIds.has(record.tabId)) this.removeStorage(key);
+    for (const { key, value: record } of readAllByPrefix(this.storage, this.subscriberPrefix)) {
+      if (!activeTabIds.has(record.tabId)) this.removeStorage(key);
     }
   }
   /** Persist a subscriber record for this tab on `topicKey`. */
@@ -835,7 +906,12 @@ var WorkerClusterRuntime = class {
       updatedAt: this.environment.now()
     });
   }
-  /** Persist the current worker record with an updated heartbeat timestamp. */
+  /** Persist the current worker record with an updated heartbeat timestamp.
+   * @param notify — when true, broadcast a REGISTRY nudge so peers reconcile
+   *   immediately instead of waiting for the next heartbeat. False on the
+   *   periodic heartbeat tick (peers will notice on their own heartbeat) to
+   *   avoid a REGISTRY storm every 3 s; true on status/role changes that
+   *   peers should observe promptly. */
   writeRecord(notify) {
     this.currentRecord = { ...this.currentRecord, heartbeatAt: this.environment.now() };
     if (this.storage) writeJson(this.storage, this.workerStorageKey(this.workerId), this.currentRecord);
@@ -847,7 +923,7 @@ var WorkerClusterRuntime = class {
   }
   /** Recompute whether this worker is active (eligible to own topics) or standby. Returns true when changed. */
   refreshRole(workers) {
-    const role = selectActiveWorkers(workers, this.maxActiveWorkers).some((worker) => worker.workerId === this.workerId) ? "active" : "standby";
+    const role = this.isActiveAmong(workers) ? "active" : "standby";
     if (role === this.currentRecord.role) return false;
     this.currentRecord = { ...this.currentRecord, role };
     return true;
@@ -902,9 +978,6 @@ var WorkerClusterRuntime = class {
     if (this.storage instanceof BatchingStorageWriter) this.storage.flush();
   }
 };
-function listKeysSafe(storage, prefix) {
-  return storage ? listKeys(storage, prefix) : [];
-}
 
 // src/core/trace.ts
 var DEFAULT_METRICS_INTERVAL_MS = 5e3;
@@ -936,7 +1009,8 @@ var DataBusTraceReporter = class {
     this.sink = options?.sink ?? (() => void 0);
     this.now = now;
   }
-  /** Start the periodic metrics flush interval. No-op when mode is 'events'. */
+  /** Start the periodic metrics flush interval. No-op when mode is 'events'
+   * (no metrics to emit), when disabled, or when already running. */
   start() {
     if (!this.enabled || this.intervalHandle || this.mode === "events") return;
     this.intervalStartedAt = this.now();
@@ -959,7 +1033,7 @@ var DataBusTraceReporter = class {
   }
   /** Record that a message was received on `topic`; stores its timestamp for latency tracking. */
   recordReceived(topic) {
-    if (!this.enabled || this.mode === "events") return;
+    if (!this.metricsActive) return;
     this.received += 1;
     this.topics.add(topic);
     const queue = this.receivedAt.get(topic);
@@ -977,7 +1051,7 @@ var DataBusTraceReporter = class {
    * with a stale receive timestamp.
    */
   recordDiscarded(topic) {
-    if (!this.enabled || this.mode === "events") return;
+    if (!this.metricsActive) return;
     const queue = this.receivedAt.get(topic);
     if (!queue) return;
     queue.shift();
@@ -990,7 +1064,7 @@ var DataBusTraceReporter = class {
    * as dispatched but do not produce a latency sample.
    */
   recordDispatched(topic) {
-    if (!this.enabled || this.mode === "events") return;
+    if (!this.metricsActive) return;
     this.dispatched += 1;
     this.topics.add(topic);
     const queue = this.receivedAt.get(topic);
@@ -1003,9 +1077,15 @@ var DataBusTraceReporter = class {
     this.latencyBuckets[bucketIndex] = (this.latencyBuckets[bucketIndex] ?? 0) + 1;
     this.latencySumMs += delayMs;
   }
+  /** True when metrics recording is active: enabled and mode includes metrics.
+   * Extracted so the four record / flush methods share one guard expression
+   * instead of repeating `!this.enabled || this.mode === 'events'` at each. */
+  get metricsActive() {
+    return this.enabled && this.mode !== "events";
+  }
   /** Emit the accumulated metrics snapshot if the interval is active. */
   flush() {
-    if (!this.enabled || this.mode === "events") return;
+    if (!this.metricsActive) return;
     this.flushNow();
   }
   flushNow() {
@@ -1121,16 +1201,25 @@ var CrossTabDataBus = class _CrossTabDataBus {
         // The cluster calls `onControl` when it receives a SUBSCRIBE/UNSUBSCRIBE/PUBLISH
         // control message — meaning the owning Worker has delegated the action to us.
         onControl: (action, topic, data) => {
-          if (action === "SUBSCRIBE") {
-            if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
+          switch (action) {
+            case "SUBSCRIBE":
+              if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
+              break;
+            case "UNSUBSCRIBE":
+              if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
+              break;
+            case "PUBLISH":
+              this.runTransport(() => this.transport.publish(topic, data));
+              break;
+            default:
+              break;
           }
-          if (action === "UNSUBSCRIBE") {
-            if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
-          }
-          if (action === "PUBLISH") this.runTransport(() => this.transport.publish(topic, data));
         },
         // The cluster calls `onEvent` when a publication broadcast arrives from
-        // another tab. Dispatch locally if we have subscribers.
+        // another tab. Dispatch locally if we have subscribers. The payload is
+        // typed `unknown` at the cluster boundary (the cluster is transport-
+        // agnostic); here we narrow it to DataBusMessage — the sender is our
+        // own broadcastEvent call, which always posts a DataBusMessage.
         onEvent: (eventType, payload) => {
           if (eventType !== PUBLICATION_EVENT) return;
           const message = payload;
@@ -1180,8 +1269,8 @@ var CrossTabDataBus = class _CrossTabDataBus {
       type: "coordination",
       coordinated: snapshot.coordinated,
       activeWorkers: snapshot.workers.filter((worker) => worker.role === "active").length,
-      workers: snapshot.workers.map((w) => `${w.workerId}|${w.status}|load=${w.load}|tab=${w.tabId}`),
-      routes: snapshot.routes.map((r) => `${r.topicKey}@${r.workerId}|confirmed=${r.confirmedAt !== void 0}`)
+      workers: snapshot.workers.map(formatWorkerTrace),
+      routes: snapshot.routes.map(formatRouteTrace)
     });
     void opening.then(
       () => {
@@ -1219,7 +1308,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }).catch((error) => {
       if (stopClusterOnFailure) this.started = false;
       if (!this.pendingStop) {
-        this.pendingStop = Promise.resolve().then(() => this.transport.stop()).catch((stopError) => this.reportError(stopError));
+        this.pendingStop = this.createStopPromise();
       }
       this.updateStatus("error");
       this.reportError(error);
@@ -1266,7 +1355,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (wasUnused) this.cluster.subscribe(topic);
     return () => this.unsubscribe(topic, handler);
   }
-  /** Remove a specific handler, or all handlers for `topic`. */
+  /** Remove a specific handler, or all handlers for `topic`.
+   * When `handler` is omitted, clears every handler for the topic — the
+   * caller used the `unsubscribe(topic)` form expecting a full teardown.
+   * The cluster is only notified on the n→0 transition (handlers.size === 0). */
   unsubscribe(topic, handler) {
     const handlers = this.topicHandlers.get(topic);
     if (!handlers) return;
@@ -1304,7 +1396,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
   getStatus() {
     return this.status;
   }
-  /** Snapshot of the cluster state (workers, routes, assignments). */
+  /** Snapshot of the cluster state (workers, routes, assignments).
+   * For diagnostics only — the returned object is a shallow copy but
+   * nested arrays are snapshots at call time. */
   getClusterSnapshot() {
     return this.cluster.getSnapshot();
   }
@@ -1358,13 +1452,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
   /** Deliver a message to every local handler registered for its topic. */
   dispatch(message) {
     this.trace.recordDispatched(message.topic);
-    for (const handler of this.topicHandlers.get(message.topic) ?? []) {
-      try {
-        handler(message);
-      } catch (error) {
-        this.reportError(error);
-      }
-    }
+    this.invokeHandlers(this.topicHandlers.get(message.topic) ?? [], (handler) => handler(message));
   }
   /**
    * Propagate a status change to the cluster, trace, and all registered
@@ -1390,25 +1478,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
         }, _CrossTabDataBus.RECOVERY_COOLDOWN_MS);
       }
     }
-    for (const handler of this.statusHandlers) {
-      try {
-        handler(status);
-      } catch (error) {
-        this.reportError(error);
-      }
-    }
+    this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
   }
   reportError(error) {
     this.trace.event({ type: "error", source: "transport" });
-    for (const handler of this.errorHandlers) {
-      try {
-        handler(error);
-      } catch (handlerError) {
-        if (typeof console !== "undefined" && typeof console.warn === "function") {
-          console.warn("[cross-tab-worker-databus] error handler threw:", handlerError);
-        }
-      }
-    }
+    this.invokeHandlers(this.errorHandlers, (handler) => handler(error), "error handler");
   }
   traceSubscription(action, topic) {
     this.trace.event({
@@ -1430,6 +1504,26 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.runTransport(() => this.transport.unsubscribe(topic));
     return true;
   }
+  /** Invoke `callback` for each item in `handlers`, isolating a throwing
+   * callback so the remaining ones still run. Dispatch/status handler failures
+   * are routed to `reportError` (which surfaces them to error subscribers);
+   * error-handler failures are logged to the console to avoid infinite
+   * recursion through reportError itself. */
+  invokeHandlers(handlers, callback, label = "dispatch") {
+    for (const handler of handlers) {
+      try {
+        callback(handler);
+      } catch (error) {
+        if (label === "error handler") {
+          if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn("[cross-tab-worker-databus] error handler threw:", error);
+          }
+        } else {
+          this.reportError(error);
+        }
+      }
+    }
+  }
   /**
    * Suspend the transport when the tab goes hidden. Stops the transport and
    * clears subscription state so it will be re-established on resume.
@@ -1446,6 +1540,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.startPromise = stopping;
     this.pendingStop = stopping;
   }
+  /** Create an immediate stop promise (no prior chain). Used by openTransport's
+   * failure path where there is no in-flight start to wait for. */
+  createStopPromise() {
+    return Promise.resolve().then(() => this.transport.stop()).catch((stopError) => this.reportError(stopError));
+  }
   /**
    * Resume the transport when the tab becomes visible again, or recover from a
    * runtime transport failure. Re-opens the transport with the stored active
@@ -1520,6 +1619,12 @@ var CrossTabDataBus = class _CrossTabDataBus {
     void starting.catch(() => void 0);
   }
 };
+function formatWorkerTrace(worker) {
+  return `${worker.workerId}|${worker.status}|load=${worker.load}|tab=${worker.tabId}`;
+}
+function formatRouteTrace(route) {
+  return `${route.topicKey}@${route.workerId}|confirmed=${route.confirmedAt !== void 0}`;
+}
 
 // src/worker-mode.ts
 function selectWorkerBackend(mode, availability = {}) {
@@ -1544,4 +1649,4 @@ export {
   CrossTabDataBus,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-53INHVYO.js.map
+//# sourceMappingURL=chunk-LBXREMZA.js.map