cross-tab-worker-databus 0.21.12 → 0.21.13

package/dist/{chunk-TSTV3SDC.js → chunk-4HW6PYIR.js}

@@ -23,7 +23,7 @@ import {
   WORKER_MODE,
   WORKER_ROLE,
   WORKER_STATUS
-} from "./chunk-2TTJ7LGZ.js";
+} from "./chunk-NPFTD7YE.js";
 
 // src/core/environment.ts
 function getStorage(name) {
@@ -479,8 +479,8 @@ var BatchingStorageWriter = class {
   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. */
+   * Test-only as a reader: `flush()` tests `pending.size` directly rather than
+   * going through this getter, so it is not part of the drain decision. */
   get pendingSize() {
     return this.pending.size;
   }
@@ -654,8 +654,9 @@ var WorkerClusterRuntime = class {
   // Topics this tab has subscribed to (local interest, plaintext).
   subscribedTopics = /* @__PURE__ */ new Set();
   // Topics assigned to this Worker as owner (topicKey → topic). Authoritative:
-  // membership drives isAssigned() and load. Grows only via CONTROL/SUBSCRIBE
-  // (or local self-subscribe), never via the reverse cache.
+  // membership drives isAssigned() and load. Grown by exactly three writers —
+  // CONTROL/SUBSCRIBE, ROUTE_RELEASED (completing a handoff this worker accepted),
+  // and local self-subscribe — and never by the reverse cache.
   assignedTopics = /* @__PURE__ */ new Map();
   routeOwnerCache = /* @__PURE__ */ new Map();
   routeOwnerCacheMax;
@@ -1049,9 +1050,12 @@ var WorkerClusterRuntime = class {
       windowMs,
       messageCount: this.throughputWindow.messageCount,
       byteCount: this.throughputWindow.byteCount,
-      // How much later the heartbeat landed than its nominal interval. This
-      // window is anchored at the previous writeRecord (one heartbeat tick),
-      // so a starved event loop stretches windowMs past the interval and the
+      // How much later the last record write landed relative to a nominal
+      // heartbeat interval. The window is anchored at the previous writeRecord,
+      // which the heartbeat tick causes but activation, a status change, a
+      // visibility change and a load update also cause — so a worker writing on
+      // any of those shorter paths yields a small window and a clamped zero.
+      // A starved event loop stretches the window past the interval, and the
       // positive excess is the scheduling-overrun signal.
       overrunMs: Math.max(0, windowMs - this.heartbeatIntervalMs),
       sampledAt: now
@@ -1216,11 +1220,13 @@ var WorkerClusterRuntime = class {
     else this.handlers.onControl(message.action, message.topic, message.data);
     if (message.action !== CONTROL_ACTION.PUBLISH) this.updateLoad();
   }
-  /**
-   * When this worker is the previous owner in a graceful handoff and the new
-   * owner asks us to unsubscribe, release the old transport subscription and
-   * ACK the handoff with ROUTE_RELEASED. Returns true when the message was a
-   * handoff release (the generic CONTROL dispatch must not run as well).
+  /** Drop this worker's ownership of the topic, then — only when this worker is
+   * the previous owner in a graceful handoff and the new owner is asking us to
+   * unsubscribe — release the old transport subscription and ACK the handoff with
+   * ROUTE_RELEASED. The ownership delete runs for *every* CONTROL/UNSUBSCRIBE,
+   * before the handoff test; the handoff legs below do not gate it. Returns true
+   * when the message was a handoff release (the generic CONTROL dispatch must not
+   * run as well).
    */
   releaseHandoffOnUnsubscribe(message) {
     this.assignedTopics.delete(message.topicKey);
@@ -1442,7 +1448,10 @@ var WorkerClusterRuntime = class {
     }
     return Array.from(subscribers);
   }
-  /** Read the current route for `topicKey`, returning null when no storage layer exists. */
+  /** Read the current route for `topicKey`. With a storage layer this returns
+   * the durable route, or null when none is recorded. Without one (degraded
+   * mode) it returns the synthesized local route from `buildLocalRoute`, which
+   * is itself null unless this worker actually holds the topic. */
   readRoute(topicKey) {
     if (!this.storage) return this.buildLocalRoute(topicKey);
     return readJson(this.storage, this.routeStorageKey(topicKey));
@@ -1523,8 +1532,9 @@ var WorkerClusterRuntime = class {
    * @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. */
+   *   avoid a REGISTRY storm every 3 s. Which sites pass what: activation,
+   *   status, visibility and load changes pass true; the heartbeat tick and a
+   *   role change pass false. */
   writeRecord(notify) {
     const now = this.environment.now();
     const sample = this.loadWeighting !== void 0 ? this.sampleThroughput(now) : void 0;
@@ -1560,10 +1570,15 @@ var WorkerClusterRuntime = class {
    * Despite the name, this is NOT a cache lookup — it unconditionally writes
    * the `topicKey → topic` pair. Hashing is cheap enough that a caller needing
    * the key should always call this rather than check `knownTopics` first;
-   * the cache's FIFO eviction below keeps it bounded. Only `isAssigned`
-   * deliberately bypasses this (it must not pollute the cache on a read-only
-   * query), so if you add a new call site, prefer `rememberTopic` unless you
-   * have the same "read-only query" reason.
+   * the cache's FIFO eviction below keeps it bounded. Two sites deliberately
+   * bypass it, and for the same kind of reason — neither may write a plaintext
+   * into the reverse cache before it is authorized: `isAssigned` re-derives the
+   * key as a read-only query, and the `ROUTE_RELEASED` handler hashes the
+   * frame's own `topic` only to compare it against `topicKey`, on a channel
+   * where that field is attacker-controlled until the comparison passes. (The
+   * `CONTROL` handler performs the same re-derivation but then *does* call this
+   * method, so it is not a bypass.) If you add a new call site, prefer
+   * `rememberTopic` unless you have one of those reasons.
    */
   rememberTopic(topic) {
     const topicKey = createOpaqueKey(topic);
@@ -1637,8 +1652,10 @@ var DataBusTraceReporter = class {
     this.asyncSink = options?.asyncSink ?? false;
     this.now = now;
   }
-  /** Start the periodic metrics flush interval. No-op when mode is 'events'
-   * (no metrics to emit), when disabled, or when already running. */
+  /** Start the periodic metrics flush interval. Only the `!enabled` return is a
+   * true no-op: in 'events' mode, or with an interval already armed, it returns
+   * without arming anything but has already cleared `stopped` one statement
+   * earlier — which is what re-opens the event stream after a `stop()`. */
   start() {
     if (!this.enabled) return;
     this.stopped = false;
@@ -1745,9 +1762,11 @@ var DataBusTraceReporter = class {
   recordDedupSuppressed() {
     if (this.metricsActive) this.dedupSuppressed += 1;
   }
-  /** 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. */
+  /** True when metrics recording is active: enabled, not stopped, and the mode
+   * includes metrics. Extracted so the seven readers — `getMetrics`, the five
+   * `record*` methods and `flush` — share one guard instead of repeating it.
+   * The `!stopped` term is part of the contract, not a bonus: `event()` does not
+   * go through this getter and gates on `stopped` itself. */
   get metricsActive() {
     return this.enabled && !this.stopped && this.mode !== TRACE_MODE.EVENTS;
   }
@@ -2011,7 +2030,8 @@ var ReplayManager = class {
       }
     }
   }
-  /** Clear replay history for one exact topic, including durable storage. */
+  /** Clear replay history for one exact topic, and for its durable history when
+   * the injected adapter provides the optional `clearTopic`. */
   async clearTopic(topic) {
     if (!this.buffers) return;
     const clearing = this.persistence?.clearTopic ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)) : null;
@@ -2390,7 +2410,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.21.12" : "";
+var SDK_VERSION = true ? "0.21.13" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2921,7 +2941,10 @@ var CrossTabDataBus = class {
   async clearReplay() {
     await this.replayManager.clearAll();
   }
-  /** Clear replay history for one exact topic, including durable storage. */
+  /** Clear replay history for one exact topic and, when the persistence adapter
+   * implements `clearTopic`, its durable history too — an adapter without that
+   * optional method leaves the persisted rows in place, exactly as `clearReplay`
+   * does. */
   async clearReplayTopic(topic) {
     await this.replayManager.clearTopic(topic);
   }
@@ -3316,9 +3339,14 @@ var CrossTabDataBus = class {
     });
   }
   /** Emit the coordination trace snapshot from the current cluster state.
-   * Called after a transport opens (start and recovery), when the role and
-   * route picture has settled — the synchronous pre-open snapshot would see no
-   * routes because their writes are still coalesced in the batch writer. */
+   * Called once per successful `start()`: `reopenTransport()`'s settle arms do not
+   * emit, so a recovery produces no second snapshot. It runs after the opening
+   * resolves — and not because a pre-open read would see no routes, which is the
+   * wrong mechanism and was the shipped claim until it was measured: a snapshot
+   * taken with the opening still unresolved already listed the route, its
+   * confirmation and both tabs' worker records, because
+   * `BatchingStorageWriter` serves pending writes on read (`storage-batch.ts:79-82`
+   * for `getItem`, `:143-155` for the `keys()` union that `readAllByPrefix` uses). */
   emitCoordinationTrace() {
     const snapshot = this.cluster.getSnapshot();
     this.trace.event({
@@ -3512,7 +3540,13 @@ var CrossTabDataBus = class {
   }
   /**
    * Ensure the DataBus is started, throwing if no initialConfig was provided.
-   * Called automatically by subscribe/publish/ready when autoStart is true.
+   * subscribe/publish/ready call this *unconditionally*: the gate is the
+   * `hasInitialConfig` check below, not the `autoStart` option. `autoStart`
+   * participates in exactly one place, the constructor's
+   * `if (autoStart ?? this.hasInitialConfig)`, where it overrides the default rather
+   * than enabling a later path — so `autoStart: true` with no `initialConfig` throws
+   * from the constructor. `docs/configuration.md`'s "`true` when `initialConfig` is
+   * provided" row describes that single site.
    */
   ensureStarted() {
     if (this.started) return;
@@ -3592,4 +3626,4 @@ export {
   parseDataBusPublication,
   selectWorkerBackend
 };
-//# sourceMappingURL=chunk-TSTV3SDC.js.map
+//# sourceMappingURL=chunk-4HW6PYIR.js.map