cross-tab-worker-databus 0.21.56 → 0.21.58

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [0.21.58] - 2026-10-30
+
+A small patch that clears the one debt `0.21.57` left behind, plus the dependency batch. No public API, export, default, frame or storage key changes; the only emitted-code delta is the removal of a guard term that could never decide anything, so behaviour is unchanged. The coverage denominators move by that one removed branch and nothing else.
+
+### Fixed
+
+- **A guard term added by `0.21.57` could not decide anything.** The identity probe's `claimedByPeer` guard carried `!hasOpener` on top of the `if` immediately below, whose first disjunct is already `hasOpener` — so the term never changed the outcome, and deleting it left the whole suite green (measured: **1058 passed**). That is the "a redundant re-read is load-bearing in the wrong direction" shape `AGENTS.md` records: a term that cannot decide anything has no defensive reading to keep. Removed, with the measurement recorded beside the guard and the three remaining terms each pinned by a named case (`existing` → the create path, `!tabIdentityInitialized` → the probe landing once per document, and the probe itself → the duplicated-tab case). The opener half is still checked where it actually decides. No runtime behaviour changes; the branch denominator is one smaller (`1931/1977`).
+
+### Changed
+
+- **The comment explaining why the coordination fuzz's shape arm exists was wrong, and is corrected.** It said "three Tabs have independent identities, so the old shape delivers consistently"; a 20-line probe printing the ids showed `['tab-coord-a', 'tab-coord-a', 'tab-coord-a']` — `getOrCreateTabId()`'s module-level cache resolves three fresh `sessionStorage`s to the first document's id, so the harness actually drives the documented *one-Tab-many-Runtimes* shape (×3). The honest reason is stronger: with records keyed per Tab the first unsubscribe can drop the shared record and release the route, and the fuzz still passes because every behavioural arm is about the *quiesced* cluster and the next reconcile re-elects. The loss is momentary and the assertions only see the end state — which is also why the `0.21.57` behavioural cases had to be unit tests that assert *immediately after* unsubscribe. A new case pins the harness premise (one `tabId`, three `workerId`s) so a future "fix" that seeds distinct ids hits a test rather than silently invalidating the reason.
+
+### Dependencies
+
+- Dev-dependency batch merged as one PR (all touch the lockfile): `vite` 7.3.7 → **8.3.5** (a major, admitted because `vitest` 5's `peerDependencies.vite` is `^6.4.0 || ^7.0.0 || ^8.0.0`, and `vite` is a root devDependency with no `vite.config` and no direct import — examples build with esbuild), `react` + `react-dom` 19.3.0 → **19.3.1** (paired: dependabot's react-only bump failed `hooks.test.tsx` with "Incompatible React versions"), `vue` 3.5.43 → 3.5.44, Playwright Test 1.63.0 → 1.64.1, `fake-indexeddb` 6.2.5 → 6.2.6. Dev dependencies do not ship.
+
+## [0.21.57] - 2026-10-30
+
+Three coordination fixes found by asking what still depends on a Tab's identity being unique. One is the browser's own **Duplicate tab**, which the opener guard could not see; the other two were already reachable in the documented one-document-many-DataBuses pattern and in a stranded handoff. The public surface gains one *optional* argument on `getOrCreateTabId()` and no new export; the subscriber record's key changes shape, and both directions stay compatible with older peers.
+
+### Fixed
+
+- **A browser-duplicated tab took the original's identity.** `getOrCreateTabId()` discarded an inherited `sessionStorage` id only when `window.opener` was present, which covers `window.open()` and not the browser's Duplicate tab — that copy carries the same session and no opener at all. `WorkerClusterRuntime` now answers an optional `isIdentityClaimedByPeer` probe from this cluster's live Worker records, which a duplicated tab cannot copy (they live in `localStorage` under a random `workerId`), and the copy mints and persists a fresh id. The probe runs on a document's first lookup only, so later Runtimes in the same document keep sharing it, and a refresh still keeps its id because `pause()` removes and flushes the departing record. After an abnormal exit that record survives for up to `workerTtlMs`, so a reload inside that window takes a fresh id — recorded at the probe and in both architecture references.
+- **Two Runtimes in one Tab shared one subscriber record.** The documented pattern of several DataBuses in one document (market + notice) means several `workerId`s under one `tabId`, and a tab-keyed subscriber record belonged to all of them: whichever unsubscribed first deleted the others' intent, the route then looked orphaned, and the owner dropped its transport subscription — up to one heartbeat of genuinely lost publications, because the transport was no longer subscribed. Records are now keyed by `workerId` and carry it, and liveness is per Runtime, so a crashed sibling's record is pruned while its tab is still alive.
+- **A stranded handoff could be stalled forever by a leftover record.** `reconcileSubscriptions()` stands down when the elected owner looks subscribed, because an owner with no local subscription never reconciles the topic itself. It asked whether the owner's *tab* had a subscriber record, so a leftover record from a live sibling Runtime in that tab — what a lost removal leaves — read as "the owner subscribes": the peer stood down, nobody ever wrote the route, and the unconfirmed handoff sat there for good. The decision now asks the Runtime set. A legacy tab-keyed record cannot name the Runtime that wrote it, so it does not answer the question at all: sending one redundant `CONTROL/SUBSCRIBE` to a peer that is about to confirm costs a frame, while standing down on that record can cost the topic.
+
+### Changed
+
+- **Subscriber records are keyed per Runtime**: `{clusterHash}:subscriber:{topicKey}:{workerId}`, with the record carrying its `workerId`. A record written by an older version carries none; it is honoured by the finest identity it has (its tab) and pruned with it, so a mixed-version cluster keeps working in both directions — old readers enumerate by prefix and read `tabId`, old sweeps keep the new records because that field is still present. The `docs/configuration.md` boundary list and both architecture references state the new shape.
+
+### Documentation
+
+- The inner dispatch gate is described accurately in both languages: `hasLocalSubscriber()` reads the in-memory subscription set (wildcard patterns included), not the durable subscriber record, whose job is to tell peers the intent exists.
+- The tab-identity paragraphs state what a shared `tabId` now costs — a false identity in the public snapshot and the diagnostics — instead of the record collision, which per-Runtime keys removed.
+
+### Verification
+
+- `pnpm check` — 40 files and **1057 tests**, plus the 5 perf gates; `pnpm lint`; `pnpm typecheck`; `pnpm test:coverage` **99.03 / 97.67 / 99.28 / 99.69**; `pnpm test:e2e` **39 passed**; `pnpm verify:pack` / `verify:compat` / `verify:types`; `pnpm bench` + `bench:compare --fail-above-pct 50`; `pnpm audit --registry=https://registry.npmjs.org` clean; `npm pack --dry-run` 109 files; `git diff --check` clean.
+- The duplicate-tab path is exercised in a real browser: a second page whose init script seeds the first page's stored id before any page script runs takes its own identity, stays a live peer of the original, and a reload of the original keeps its id. Deleting the probe wiring and rebuilding fails exactly that assertion.
+- Every fix was mutation-checked with the mutant's own failing case named, including the one that survived a vacuous assertion first (an expected value minted by the same `randomId` as the code under test) and the one classified rather than repaired (a `!this.storage` leg the compiler holds and `listKeys()`'s catch makes undecidable).
+
 ## [0.21.56] - 2026-10-25
 
 A benchmark-trend release that also carries one shipped-comment correction. No behavior, API shape, export, default, frame or storage key changed, and the coverage floors and the zero-count arm ledger are `0.21.55`'s.

package/dist/centrifuge.js

@@ -7,7 +7,7 @@ import {
   publicationMetadata,
   selectWorkerBackend,
   serializeError
-} from "./chunk-VDCLCCMN.js";
+} from "./chunk-X33QQUTG.js";
 import {
   CENTRIFUGE_INPUT_TYPE,
   CENTRIFUGE_OUTPUT_TYPE,

package/dist/{chunk-VDCLCCMN.js → chunk-X33QQUTG.js}

@@ -144,12 +144,13 @@ function canUseStorage(storage, probeKey) {
     return false;
   }
 }
-function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY) {
+function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY, options) {
   const storage = environment.sessionStorage;
   try {
     const existing = storage?.getItem(key);
     const hasOpener = typeof window !== "undefined" && Boolean(window.opener);
-    if (existing && (!hasOpener || tabIdentityInitialized)) {
+    const claimedByPeer = existing !== null && existing !== void 0 && existing !== "" && !tabIdentityInitialized && options?.isIdentityClaimedByPeer?.(existing) === true;
+    if (existing && (!hasOpener || tabIdentityInitialized) && !claimedByPeer) {
       tabIdentityInitialized = true;
       cachedTabId = existing;
       return existing;
@@ -716,7 +717,21 @@ var WorkerClusterRuntime = class {
     this.subscriberPrefix = `${baseKey}:subscriber:`;
     this.channelName = `${prefix}:bus:${clusterHash}`;
     this.storage = canUseStorage(this.environment.storage, `${baseKey}:probe`) ? new BatchingStorageWriter(this.environment.storage) : null;
-    this.tabId = options.tabId ?? getOrCreateTabId(this.environment, `${prefix}:tab-id`);
+    this.tabId = options.tabId ?? getOrCreateTabId(this.environment, `${prefix}:tab-id`, {
+      // A browser-duplicated tab inherits sessionStorage without an opener, so
+      // `getOrCreateTabId()`'s opener guard cannot see it. A live Worker
+      // record carrying that id is the evidence the copy cannot carry: it
+      // lives in localStorage under a random `workerId`, and this probe runs
+      // in the constructor, before this Runtime has written a record of its
+      // own — so every match belongs to a different live document. A refresh
+      // removes its record in `pause()` and flushes that removal before the
+      // document goes away, so the refresh path keeps the stored id. The one
+      // case that does not is an abnormal exit, whose record survives for up
+      // to `workerTtlMs`; a reload inside that window takes a fresh identity,
+      // which costs one observer a changed `tabId` and nothing else — the
+      // stale record is pruned by the normal TTL path.
+      isIdentityClaimedByPeer: (candidate) => this.isTabIdLiveElsewhere(candidate)
+    });
     this.workerId = options.workerId ?? `worker-${this.tabId}-${this.environment.randomId()}`;
     const now = this.nowMs();
     this.currentRecord = {
@@ -910,12 +925,12 @@ var WorkerClusterRuntime = class {
     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
+  /** Remove this Runtime'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));
+    this.removeStorage(this.subscriberStorageKey(topicKey, this.workerId));
     const route = this.readRoute(topicKey);
     if (!route) return topicKey;
     const subscribers = this.readSubscriberTabIds(topicKey, this.readWorkers());
@@ -1357,11 +1372,7 @@ var WorkerClusterRuntime = class {
           ) ?? this.currentRecord;
           recoveryProjectedLoads.set(owner.workerId, (recoveryProjectedLoads.get(owner.workerId) ?? owner.load) + 1);
           if (owner.workerId !== this.workerId) {
-            const subscriberTabIds = new Set(this.readSubscriberTabIds(topicKey, workers));
-            const ownerSubscribed = workers.some(
-              (worker) => worker.workerId === owner.workerId && subscriberTabIds.has(worker.tabId)
-            );
-            if (ownerSubscribed) continue;
+            if (this.readSubscriberIds(topicKey, workers).workerIds.has(owner.workerId)) continue;
           }
           this.writeRoute(topicKey, owner, void 0, route.generation + 1);
           this.sendControl(owner.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
@@ -1482,6 +1493,38 @@ var WorkerClusterRuntime = class {
       return false;
     }
   }
+  /**
+   * Whether any other live Worker record already carries `tabId`.
+   *
+   * Used once per document, from the constructor, to tell a browser-duplicated
+   * tab from this tab's own refresh: the copy inherits `sessionStorage` but not
+   * the opener, so the identity stored there is the only shared state and the
+   * Worker records are the only evidence that another live document holds it.
+   * Liveness is the same heartbeat window `readWorkers()` prunes by, so a record
+   * left behind by an abnormal exit is reported as live until it expires — the
+   * only false positive, and it re-mints one identity instead of letting two
+   * live tabs share one.
+   *
+   * The `!this.storage` leg is the degraded mode, and it earns its line for two
+   * reasons rather than one. It is what narrows the field for the scan below
+   * (`StorageLike | null` is rejected by `readAllByPrefix`), so the compiler
+   * holds it; and it is *not* what decides the verdict, because `listKeys()`
+   * catches its own failure and returns no records either way — measured by
+   * emptying this consequent, which leaves the suite green. What the inverted
+   * return does prove is the behaviour, not the deletion: returning `true` here
+   * fails 'keeps the inherited id when there is no storage to probe', since
+   * without `localStorage` there is no second document to collide with.
+   */
+  isTabIdLiveElsewhere(tabId) {
+    if (!this.storage) return false;
+    const now = this.nowMs();
+    for (const { value: worker } of readAllByPrefix(this.storage, this.workerPrefix)) {
+      if (worker.tabId !== tabId) continue;
+      if (now - worker.heartbeatAt > this.workerTtlMs) continue;
+      return true;
+    }
+    return false;
+  }
   /** Read all live worker records from storage, pruning stale entries past the TTL. */
   readWorkers() {
     if (!this.storage) return [this.currentRecord];
@@ -1499,23 +1542,61 @@ var WorkerClusterRuntime = class {
   }
   /** Enumerate all tab IDs that have a subscriber record for `topicKey`. */
   readSubscriberTabIds(topicKey, workers) {
+    return Array.from(this.readSubscriberIds(topicKey, workers).tabIds);
+  }
+  /**
+   * One scan of `topicKey`'s subscriber records, answering the two questions
+   * callers ask: which Tabs hold a subscription (emptiness checks, orphan-route
+   * pruning) and which **Runtimes** do (the stranded-handoff re-election).
+   *
+   * The second answer is the finer one and the reason this is one method rather
+   * than two scans: a tab-level answer lets a leftover record from a sibling
+   * Runtime speak for a Worker that never subscribed to the topic, and standing
+   * down on that proof stalls the recovery forever (see the call site).
+   *
+   * A legacy record — written before records carried `workerId` — proves only
+   * that *some* Runtime in its tab subscribes, so it contributes to the tab set
+   * and **not** to the worker set. Treating it as the whole tab, which is what
+   * the tab-level reader effectively did, is the conservative-looking choice
+   * that can stall; the cost of the other direction is one redundant
+   * `CONTROL/SUBSCRIBE` to a peer that is about to confirm anyway.
+   */
+  readSubscriberIds(topicKey, workers) {
+    const tabIds = /* @__PURE__ */ new Set();
+    const workerIds = /* @__PURE__ */ new Set();
     if (!this.storage) {
       const topic = this.knownTopics.get(topicKey);
-      return topic && this.subscribedTopics.has(topic) ? [this.tabId] : [];
+      if (topic && this.subscribedTopics.has(topic)) {
+        tabIds.add(this.tabId);
+        workerIds.add(this.workerId);
+      }
+      return { tabIds, workerIds };
     }
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
-    const subscribers = /* @__PURE__ */ new Set();
+    const activeWorkerIds = new Set(workers.map((worker) => worker.workerId));
     for (const { key, value: record } of readAllByPrefix(
       this.storage,
       `${this.subscriberPrefix}${topicKey}:`
     )) {
-      if (!activeTabIds.has(record.tabId)) {
+      if (!this.isSubscriberRecordLive(record, activeTabIds, activeWorkerIds)) {
         this.removeStorage(key);
         continue;
       }
-      subscribers.add(record.tabId);
+      tabIds.add(record.tabId);
+      if (record.workerId !== void 0) workerIds.add(record.workerId);
     }
-    return Array.from(subscribers);
+    return { tabIds, workerIds };
+  }
+  /** Whether a subscriber record still belongs to a live Runtime.
+   *
+   * A record written by this version names its `workerId`, so liveness is the
+   * Worker set the reconcile pass already prunes by — which is what keeps two
+   * Runtimes in one tab independent. A record from an older version carries no
+   * `workerId`; it is honoured while its *tab* lives, the finest identity it
+   * has, and each Runtime replaces its own with a worker-keyed record on its
+   * next write. */
+  isSubscriberRecordLive(record, activeTabIds, activeWorkerIds) {
+    return record.workerId === void 0 ? activeTabIds.has(record.tabId) : activeWorkerIds.has(record.workerId);
   }
   /** Read the current route for `topicKey`. With a storage layer this returns
    * the durable route, or null when none is recorded. Without one (degraded
@@ -1581,19 +1662,31 @@ var WorkerClusterRuntime = class {
       this.removeStorage(key);
     }
   }
-  /** Remove subscriber records for tabs that are no longer active. */
+  /** Remove subscriber records whose owning Runtime (or, for a legacy record,
+   * whose tab) is no longer active. */
   cleanupOrphanedSubscribers(workers) {
     if (!this.storage) return;
     const activeTabIds = new Set(workers.map((worker) => worker.tabId));
+    const activeWorkerIds = new Set(workers.map((worker) => worker.workerId));
     for (const { key, value: record } of readAllByPrefix(this.storage, this.subscriberPrefix)) {
-      if (!activeTabIds.has(record.tabId)) this.removeStorage(key);
+      if (!this.isSubscriberRecordLive(record, activeTabIds, activeWorkerIds)) this.removeStorage(key);
     }
   }
-  /** Persist a subscriber record for this tab on `topicKey`. */
+  /** Persist a subscriber record for this Runtime on `topicKey`.
+   *
+   * Keyed by `workerId`, not `tabId`. A document may run several Runtimes that
+   * share one `tabId` on purpose (the market + notice pattern), and a tab-keyed
+   * record belonged to all of them at once: whichever unsubscribed first deleted
+   * the others' intent, the route then looked orphaned, and the owner dropped a
+   * transport subscription its surviving sibling still needed — a delivery gap
+   * until that sibling's next reconcile tick re-elected an owner. Duplicated
+   * tabs get the same protection even when the identity probe cannot see them,
+   * which is why the fix is here as well as in `isTabIdLiveElsewhere()`. */
   writeSubscriber(topicKey) {
     if (!this.storage) return;
-    writeJson(this.storage, this.subscriberStorageKey(topicKey, this.tabId), {
+    writeJson(this.storage, this.subscriberStorageKey(topicKey, this.workerId), {
       tabId: this.tabId,
+      workerId: this.workerId,
       updatedAt: this.nowMs()
     });
   }
@@ -1667,8 +1760,9 @@ var WorkerClusterRuntime = class {
   routeStorageKey(topicKey) {
     return `${this.routePrefix}${topicKey}`;
   }
-  subscriberStorageKey(topicKey, tabId) {
-    return `${this.subscriberPrefix}${topicKey}:${tabId}`;
+  /** `ownerId` is the Runtime's `workerId`; older versions used the `tabId`. */
+  subscriberStorageKey(topicKey, ownerId) {
+    return `${this.subscriberPrefix}${topicKey}:${ownerId}`;
   }
   removeStorage(key) {
     try {
@@ -2548,7 +2642,7 @@ var SDK_VERSION = (
   // declaration's type is `string | undefined` and the export's is `string`
   // (dropping the conditional is TS2322, measured). Recorded here so the leg reads
   // as a shape the harness cannot reach rather than as a case nobody exercised.
-  true ? "0.21.56" : ""
+  true ? "0.21.58" : ""
 );
 
 // src/core/data-bus.ts
@@ -3801,4 +3895,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-VDCLCCMN.js.map
+//# sourceMappingURL=chunk-X33QQUTG.js.map