cross-tab-worker-databus 0.21.43 → 0.21.45

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [0.21.45] - 2026-09-30
+
+A release ten cycles in the making, and the reason it was late is now part of the tooling: the browser benchmark's deferral rule was enforced by a human remembering it, so it slipped. No library behavior, export, option, default, frame or storage key changed; the coverage floors and the zero-count arm ledger are `0.21.44`'s.
+
+### Added
+
+- **The browser benchmark now records the host it ran on, and `bench:compare` refuses to trust a sample the host cannot support.** Every archived report now carries `host: { loadavg1m, cpus, platform, release }`, or `null` where the platform publishes no finite reading. On the baseline path, a newest sample whose load exceeds four times the baseline's own median is refused before any metric is compared: the tool prints both figures and exits non-zero. This closes a hole with a specific shape — all 91 archived reports recorded `userAgent` and timings and **no host state at all**, while the gate judges a report only against the previous five, so a *fast* sample taken on a loaded host entered the baseline and became the reference for the next five readings, with nothing recording that the host was busy. The threshold is a ratio rather than an absolute ceiling because the archive spans machines and a load average means nothing without its core count; it is a refusal to *trust* rather than a claim that the sample is invalid, so the boundary is inclusive and a false positive costs one deferred run. Reports predating the field have nothing to judge and pass through silently, which is every report currently archived — the guard is inert on the existing series, and taking a sample on a busy host is now refused rather than archived.
+- **The shipped release checklist documents it, in both languages.** `docs/release-checklist.md` step 4 already said to defer the sample with its load numbers; it now also says the rule is enforced rather than remembered, and what the refusal looks like.
+
+### Changed
+
+- **Nine documented defaults were pinned by tests that did not exist before, and the audit that found them is now the reason to trust the option table.** `connectTimeoutMs` (30 000), `createWebSocketDataBus`'s and `createCentrifugeDataBus`'s `clusterKey` default, `heartbeatIntervalMs` (3 000) and `workerTtlMs` (10 000) — the pair the architecture guide summarises as the worst-case dead-owner detection time — plus `recovery.maxAttempts` (`Infinity`), the `dedup` pair (60 000 / 1 000), `replay.maxPerTopic` (100), `trace.metricsIntervalMs` (5 000) and `trace.enabled` (`false`). Each is documented in `docs/configuration.md` or `docs/transports.md`; none was named by a test, and the three tiers are worth distinguishing. `maxActiveWorkers` was already pinned. `transferable`, `recovery.cooldownMs`, `pruneStrategy` and `trace.mode` were checked and found already covered, and are recorded alongside the hits because a ledger that logs only hits overstates how much of a surface it has walked.
+- **The method that found them is the transferable part, and it is a kill set rather than a reading.** For each documented default, one `??`-site mutant run against its own file, because *pinned* (a test names the value), *sensitive but unnamed* (a mutant fails cases asserting something else — 2 cases for `heartbeatIntervalMs`, 6 for `workerTtlMs`, 1 for `recovery.maxAttempts`) and *unobserved* (the whole suite stays green — both `dedup` defaults, `maxPerTopic`, `trace.enabled`) are indistinguishable in the source. Twenty-four mutants were run across these changes, each restored, each with its own kill set recorded in `docs/progress.md`.
+
+### Fixed
+
+- **The demo counted a publication before it knew the frame was delivered.** `publish()` and `publishBatch()` return `void`: a frame that is not delivered is reported **only** through `onError`. The demo counted first and reported after, so a refused frame produced a 发布 row *and* an 错误 row for one click and advanced 已发布 anyway, and `publishBatch()` overstated the counter by ten per refused batch. The window is the demo's own — 应用连接 suspends at `await state.bus.stop()` while auto-publish keeps running — and it now labels refusals 未投递, counts only frames the bus took, and does not animate a hop that never happened.
+
+### Verification
+
+- `pnpm check` — 39 test files, **999 tests**, typecheck, build, 5 perf gates; `pnpm lint`; the documentation gate at 25.
+- Twenty-four mutants across the changes above, each applied alone and restored, each with its own named failure recorded in `docs/progress.md`.
+- `pnpm audit --registry=https://registry.npmjs.org` — no known vulnerabilities.
+- `docs/benchmarks.md` and its zh mirror regenerate byte-identical from the 91-report archive, so the generated tables and their committed copies have not drifted; the archive itself is untracked, which is why that is a run rather than a gate.
+- **The browser benchmark was deferred again, with its load numbers, as the checklist's standing decision requires** — 79.78 / 120.85 / 129.80 / 145.31 across six readings on 8 cores at the end of this cycle. The archive's newest report is still `browser-2026-09-24T13-40-52-413Z.json`, and 24 tags have now shipped without a sample. What this release changes is that a loaded host can no longer *silently* produce the sample that ends that streak: the next run either produces a clean sample or is refused with its numbers.
+
+## [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.

package/dist/centrifuge.js

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

package/dist/{chunk-NTMMSR4W.js → chunk-36TEEZQ5.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,
@@ -2509,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.43" : ""
+  true ? "0.21.45" : ""
 );
 
 // src/core/data-bus.ts
@@ -2629,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;
@@ -3688,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 = {}) {
@@ -3749,4 +3793,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-NTMMSR4W.js.map
+//# sourceMappingURL=chunk-36TEEZQ5.js.map