cross-tab-worker-databus 0.21.42 → 0.21.44

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.21.44] - 2026-09-26
+
+`0.21.43` guarded one clock; enumerating the rest found that the same input reached durable state, where the consequence is not a wrong number but a sentinel. No API, option, default, frame or storage key changed; the coverage floors and the zero-count arm ledger are `0.21.43`'s.
+
+### Fixed
+
+- **A non-finite environment clock was written into localStorage as `null`, and `null` coerces to `0`.** `ClusterEnvironment.now` is a required field whose documented hazard is a *backwards* step, which every `now - stamped > ttl` site already reads as "not yet expired" — but a missing reading is outside that contract, and it did not degrade one field: the durable worker, route and subscriber records were written with `"updatedAt": null`, because `JSON.stringify(NaN)` is `null`. That is worse than a wrong number rather than merely different, because `null` coerces to `0` in the TTL arithmetic, so **the first tick after the clock recovered would read every record as ancient and prune the whole cluster at once**. A poisoned in-memory comparison heals when the clock recovers; a poisoned record does not. The cluster now holds the last finite reading across its ten read sites, and the bus normalizes once at the single place it binds a clock — which covers its own stamps *and* the dedup manager it hands the same function to, the site `0.21.43` guarded at its own boundary.
+- **Both guards are pinned by cases that had to be rewritten to measure anything.** The cluster case first filtered records with `typeof reading !== 'number'`, and the value this bug leaves is `null`, whose `typeof` is `"object"` — the predicate skipped exactly what it existed to catch, and the guard's own mutation passed it. The bus case only read fields the broken window never touches, so it passed the unguarded binding too; driving a rewrite under the broken clock is what made it a check. Each mutation now dies at one test: `stored a non-finite heartbeatAt`, and `the recovery ledger stamps a finite time`.
+
+## [0.21.43] - 2026-09-26
+
+Two claims about the storage boundary turned out to be narrower than the storage was, and a public clock could report `NaN` into the health summary. No library behavior, export, option, default, frame or storage key changed beyond the one guard; the coverage floors and the zero-count arm ledger are `0.21.42`'s.
+
+### Fixed
+
+- **A caller-injected dedup clock that returns a non-finite number poisoned every comparison that reads it.** `dedup.now` is a public option, and a non-wall-clock host is exactly what it exists for — one whose reading can be *missing* rather than merely unusual. Since every comparison in the dedup manager is arithmetic on a timestamp, a single `NaN` reading did not degrade one field: the adaptive window's `elapsed >= ADAPTIVE_WINDOW_MS` never fired, the hot path's `now - timestamp > ttlMs` became `NaN > ttlMs` (false, so nothing expired), the periodic sweep pruned nothing, and `getDedupStats().ttlMs` reported **`NaN`** — which `JSON.stringify` writes as **`null`**, so a health summary or a diagnostics log carried a null where a duration belongs. Measured on the pre-fix class: `ttlMs` → `NaN`, serialized → `{"ttlMs":null}`, and a message ID stayed suppressed for as long as it stayed in the map. The manager now holds the last finite reading, which is the degradation that changes least — time stands still, expiry pauses, the adaptive window keeps its last value — where substituting `Date.now()` would silently mix two clocks and zeroing would expire the whole map on the next call. The guard sits at the clock rather than at each comparison, which is the shape this repository already uses for the same class of input in `trace.ts`, `websocket.ts` and `replay-manager.ts`. Pinned by two cases whose legs fail apart: removing the guard fails both, while removing only the constructor's fallback — the one site with no previous reading to hold — fails the second alone, because a `NaN` baseline would make every later `elapsed` non-finite too. `docs/api.md` and its Chinese mirror state the guarantee where `dedup.now` is documented.
+
+### Added
+
+- **The storage boundary is now stated where it was widest, not only where it was found.** `docs/configuration.md` and `docs/architecture.md` each said the coordination records are isolated per `clusterKey` and that Topic plaintext reaches a durable store only through two named opt-ins; the architecture guide carried that claim in a *dedicated* section ("Two DataBus instances with different `clusterKey` values … operate on completely isolated storage namespaces") and as an absolute above its key listing ("All keys are isolated by `createOpaqueKey(clusterKey)`"). Both now name the exception the second opt-in introduces — its IndexedDB object store is keyed by the plaintext Topic and its database name defaults to the storage prefix, so it is not partitioned by `clusterKey` at all, and `dbName` per cluster is what separates them — in both languages.
+- **The key/plaintext pairing rule is now described the way the code enforces it.** The protocol table's row "`topicKey === createOpaqueKey(topic)`" became unconditionally true in `0.21.42`, but the prose beneath it still said only that a pair which *disagrees* is a substitution — which reads as a rule about mismatches and leaves a frame carrying no `topicKey` sounding like a tolerated legacy shape, which is the reading that once kept a guard in place. The shipped text now says the comparison is unconditional, that a missing field is a disagreement of the same kind, and that a custom environment should always send the field. Both languages.
+
 ## [0.21.42] - 2026-09-26
 
 The library's central privacy claim — that a topic's plaintext never reaches localStorage — was enforced on keys by accident and on values by nothing, and the guard that protects the coordination plane's key/topic pair was written to tolerate a missing field it never had to tolerate. Both halves of that sentence were found by re-auditing claims rather than code: the first by measuring which mutations anything noticed, the second by enumerating the readers of a pair. One behavioral change, no API, option, default, frame or storage-key change.

package/dist/centrifuge.js

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

package/dist/{chunk-VWVYUSIN.js → chunk-QPM2OGBB.js}

@@ -645,6 +645,10 @@ var WorkerClusterRuntime = class {
   channelName;
   /** Adaptive load weighting options; undefined keeps legacy topic-count routing. */
   loadWeighting;
+  /** The most recent finite reading of the environment's clock, and the fallback for
+   * a broken one — see {@link nowMs}. Seeded to 0 because a clock that has never
+   * produced a finite reading leaves nothing to hold. */
+  lastFiniteNow = 0;
   /** Rolling traffic accumulator folded into the worker record on writeRecord. */
   throughputWindow = {
     startedAt: 0,
@@ -706,7 +710,7 @@ var WorkerClusterRuntime = class {
     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.workerId = options.workerId ?? `worker-${this.tabId}-${this.environment.randomId()}`;
-    const now = this.environment.now();
+    const now = this.nowMs();
     this.currentRecord = {
       protocolVersion: CLUSTER_PROTOCOL_VERSION,
       workerId: this.workerId,
@@ -719,6 +723,33 @@ var WorkerClusterRuntime = class {
       registeredAt: now
     };
   }
+  /**
+   * The environment's clock, normalized.
+   *
+   * `ClusterEnvironment.now` is a required field, and the documented hazard is a
+   * *backwards* step rather than a missing reading — the library's own subtraction
+   * sites tolerate one, since every `now - stamped > ttl` reads a backwards clock as
+   * "not yet expired". A non-finite reading is outside that contract, and it does not
+   * degrade one field: measured before this guard, a `NaN` clock was written straight
+   * into durable state — the worker, route and subscriber records all carried
+   * `"updatedAt": null`, because `JSON.stringify(NaN)` is `null` — and that is worse
+   * than a wrong number rather than merely different, because `null` coerces to `0`
+   * in the TTL arithmetic, so the first tick after the clock recovered would read
+   * every record as ancient and prune the whole cluster at once.
+   *
+   * Holding the last finite reading is the same treatment `data-bus.ts` applies to
+   * `dedup.now` and `DedupManager` applies to its own boundary: a paused clock, not a
+   * poisoned one. It is a helper rather than nine conditions because the broken input
+   * is the clock, not any particular comparison.
+   */
+  nowMs() {
+    const reading = this.environment.now();
+    if (Number.isFinite(reading)) {
+      this.lastFiniteNow = reading;
+      return reading;
+    }
+    return this.lastFiniteNow;
+  }
   /** Start the cluster: register, listen for lifecycle events, and begin heartbeats. */
   start() {
     if (this.started) return;
@@ -775,7 +806,7 @@ var WorkerClusterRuntime = class {
       return;
     }
     this.channel?.addEventListener("message", this.handleMessage);
-    const now = this.environment.now();
+    const now = this.nowMs();
     this.currentRecord = {
       ...this.currentRecord,
       heartbeatAt: now,
@@ -1261,7 +1292,7 @@ var WorkerClusterRuntime = class {
    * will never complete — while a fresh unconfirmed route may simply be
    * waiting out its confirmation flush and must be left alone. */
   isStaleHandoff(route) {
-    return this.environment.now() - route.updatedAt > this.workerTtlMs;
+    return this.nowMs() - route.updatedAt > this.workerTtlMs;
   }
   /** Full reconciliation cycle: workers, subscriptions, and assigned topics. */
   reconcile() {
@@ -1446,7 +1477,7 @@ var WorkerClusterRuntime = class {
   /** Read all live worker records from storage, pruning stale entries past the TTL. */
   readWorkers() {
     if (!this.storage) return [this.currentRecord];
-    const now = this.environment.now();
+    const now = this.nowMs();
     const workers = [];
     for (const { key, value: worker } of readAllByPrefix(this.storage, this.workerPrefix)) {
       if (worker.workerId !== this.workerId && now - worker.heartbeatAt > this.workerTtlMs) {
@@ -1498,7 +1529,7 @@ var WorkerClusterRuntime = class {
       topicKey,
       workerId: this.workerId,
       tabId: this.tabId,
-      updatedAt: this.environment.now(),
+      updatedAt: this.nowMs(),
       generation: 1
     };
   }
@@ -1515,7 +1546,7 @@ var WorkerClusterRuntime = class {
       topicKey,
       workerId: owner.workerId,
       tabId: owner.tabId,
-      updatedAt: this.environment.now(),
+      updatedAt: this.nowMs(),
       generation,
       ...handoffFromWorkerId ? { handoffFromWorkerId } : {}
     };
@@ -1527,7 +1558,7 @@ var WorkerClusterRuntime = class {
     if (!route || route.workerId !== this.workerId || route.confirmedAt !== void 0) return;
     writeJson(this.storage, this.routeStorageKey(topicKey), {
       ...route,
-      confirmedAt: this.environment.now()
+      confirmedAt: this.nowMs()
     });
     const topic = this.knownTopics.get(topicKey);
     if (topic) this.handlers.onDiagnostic?.({ operation: RELIABILITY_OPERATION.ROUTE_ACK, topic });
@@ -1535,7 +1566,7 @@ var WorkerClusterRuntime = class {
   /** Remove routes whose topic has no subscribers and whose TTL has expired. */
   cleanupOrphanedRoutes(workers) {
     if (!this.storage) return;
-    const now = this.environment.now();
+    const now = this.nowMs();
     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;
@@ -1555,7 +1586,7 @@ var WorkerClusterRuntime = class {
     if (!this.storage) return;
     writeJson(this.storage, this.subscriberStorageKey(topicKey, this.tabId), {
       tabId: this.tabId,
-      updatedAt: this.environment.now()
+      updatedAt: this.nowMs()
     });
   }
   /** Persist the current worker record with an updated heartbeat timestamp.
@@ -1566,7 +1597,7 @@ var WorkerClusterRuntime = class {
    *   status, visibility and load changes pass true; the heartbeat tick and a
    *   role change pass false. */
   writeRecord(notify) {
-    const now = this.environment.now();
+    const now = this.nowMs();
     const sample = this.loadWeighting !== void 0 ? this.sampleThroughput(now) : void 0;
     this.currentRecord = {
       ...this.currentRecord,
@@ -2366,6 +2397,8 @@ var DedupManager = class {
   seenMessageIds = /* @__PURE__ */ new Map();
   sweepTimer = null;
   windowStartedAt = 0;
+  /** The most recent finite reading of `now`, and the fallback for a broken one. */
+  lastFiniteNow = 0;
   windowAccepted = 0;
   suppressed = 0;
   accepted = 0;
@@ -2377,14 +2410,46 @@ var DedupManager = class {
     this.sweepMs = options.sweepMs;
     this.now = options.now;
     this.trace = options.trace;
-    this.windowStartedAt = this.now();
+    this.lastFiniteNow = Number.isFinite(this.now()) ? this.now() : 0;
+    this.windowStartedAt = this.lastFiniteNow;
+  }
+  /**
+   * The injected clock, normalized.
+   *
+   * `dedup.now` is a public option and a non-wall-clock host is exactly the case it
+   * exists for — one whose reading can be *missing* rather than merely unusual. Every
+   * comparison this class makes is arithmetic on a timestamp, so a single non-finite
+   * reading does not degrade one field: `now - timestamp > ttlMs` becomes
+   * `NaN > ttlMs` (false, so nothing expires), the adaptive window's
+   * `elapsed >= ADAPTIVE_WINDOW_MS` never fires, and `getStats().ttlMs` reports
+   * `NaN` — which `JSON.stringify` turns into `null`, so a health summary or a
+   * diagnostics log would carry a null where a duration belongs. Measured on the
+   * pre-fix class: `getStats().ttlMs` → `NaN`, serialized → `null`, and an id
+   * stayed suppressed for as long as it stayed in the map.
+   *
+   * Holding the last finite reading is the degradation that changes least: time
+   * stands still, expiry pauses, and the adaptive window keeps the value it last
+   * computed. Substituting `Date.now()` would be worse — it silently mixes two
+   * clocks — and zeroing would expire the whole map on the next call. This is the
+   * same class of guard `trace.ts` carries on its own public clock, and that
+   * `websocket.ts` and `replay-manager.ts` apply to their numeric options; it is one
+   * helper rather than a condition per site because the broken input is the *clock*,
+   * not any particular comparison.
+   */
+  nowMs() {
+    const reading = this.now();
+    if (Number.isFinite(reading)) {
+      this.lastFiniteNow = reading;
+      return reading;
+    }
+    return this.lastFiniteNow;
   }
   /** True when a publication carrying `messageId` was already seen. Records the
    * ID and updates counters/trace on acceptance. Disabled or ID-less messages
    * always pass through. */
   isDuplicate(messageId, topic) {
     if (!this.enabled || !messageId) return false;
-    const now = this.now();
+    const now = this.nowMs();
     const ttlMs = this.currentTtl();
     for (const [id, timestamp] of this.seenMessageIds) {
       if (now - timestamp > ttlMs) this.seenMessageIds.delete(id);
@@ -2435,12 +2500,12 @@ var DedupManager = class {
     this.seenMessageIds.clear();
     this.suppressed = 0;
     this.accepted = 0;
-    this.windowStartedAt = this.now();
+    this.windowStartedAt = this.nowMs();
     this.windowAccepted = 0;
   }
   /** Remove IDs whose timestamp predates the effective TTL cutoff. */
   pruneExpired() {
-    const cutoff = this.now() - this.currentTtl();
+    const cutoff = this.nowMs() - this.currentTtl();
     for (const [id, timestamp] of this.seenMessageIds) {
       if (timestamp < cutoff) this.seenMessageIds.delete(id);
     }
@@ -2451,7 +2516,7 @@ var DedupManager = class {
    * every ADAPTIVE_WINDOW_MS. */
   currentTtl() {
     if (!this.adaptiveBounds) return this.ttlMs;
-    const now = this.now();
+    const now = this.nowMs();
     const elapsed = now - this.windowStartedAt;
     if (elapsed >= ADAPTIVE_WINDOW_MS) {
       this.windowStartedAt = now;
@@ -2475,7 +2540,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.42" : ""
+  true ? "0.21.44" : ""
 );
 
 // src/core/data-bus.ts
@@ -2595,7 +2660,7 @@ var CrossTabDataBus = class {
     assertRecoveryOptions(recovery);
     this.recoveryCooldownMs = recovery?.cooldownMs ?? 1e3;
     this.recoveryMaxAttempts = recovery?.maxAttempts ?? Number.POSITIVE_INFINITY;
-    this.now = dedup?.now ?? Date.now;
+    this.now = holdLastFinite(dedup?.now ?? Date.now);
     this.transport = transport;
     this.initialConfig = initialConfig;
     this.hasInitialConfig = "initialConfig" in options;
@@ -3654,6 +3719,19 @@ function formatWorkerTrace(worker) {
 function formatRouteTrace(route) {
   return `${route.topicKey}@${route.workerId}|confirmed=${route.confirmedAt !== void 0}`;
 }
+function holdLastFinite(source) {
+  let last = 0;
+  let primed = false;
+  return () => {
+    const reading = source();
+    if (Number.isFinite(reading)) {
+      last = reading;
+      primed = true;
+      return reading;
+    }
+    return primed ? last : 0;
+  };
+}
 
 // src/worker-mode.ts
 function selectWorkerBackend(mode, availability = {}) {
@@ -3715,4 +3793,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-VWVYUSIN.js.map
+//# sourceMappingURL=chunk-QPM2OGBB.js.map