cross-tab-worker-databus 0.20.71 → 0.20.86

package/dist/cjs/centrifuge.cjs

@@ -25,6 +25,145 @@ __export(centrifuge_exports, {
 });
 module.exports = __toCommonJS(centrifuge_exports);
 
+// src/utils/constants.ts
+var WORKER_STATUS = {
+  CONNECTING: "connecting",
+  CONNECTED: "connected",
+  DISCONNECTED: "disconnected",
+  ERROR: "error"
+};
+var WORKER_ROLE = {
+  ACTIVE: "active",
+  STANDBY: "standby"
+};
+var TAB_VISIBILITY = {
+  VISIBLE: "visible",
+  HIDDEN: "hidden"
+};
+var WORKER_MODE = {
+  DEDICATED: "dedicated",
+  SHARED: "shared",
+  AUTO: "auto"
+};
+var WORKER_BACKEND = {
+  DEDICATED: "dedicated",
+  SHARED: "shared",
+  LOCAL: "local"
+};
+var CHANNEL_FALLBACK = {
+  NONE: "none",
+  STORAGE_EVENT: "storage-event"
+};
+var CONTROL_ACTION = {
+  SUBSCRIBE: "SUBSCRIBE",
+  UNSUBSCRIBE: "UNSUBSCRIBE",
+  PUBLISH: "PUBLISH"
+};
+var CLUSTER_MESSAGE_TYPE = {
+  CONTROL: "CONTROL",
+  EVENT: "EVENT",
+  REGISTRY: "REGISTRY",
+  ROUTE_RELEASED: "ROUTE_RELEASED"
+};
+var DEFAULT_STORAGE_PREFIX = "cross-tab-worker-databus";
+var STORAGE_CHANNEL_PREFIX = `${DEFAULT_STORAGE_PREFIX}:channel:`;
+var TAB_ID_STORAGE_KEY = `${DEFAULT_STORAGE_PREFIX}:tab-id`;
+var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
+var TRACE_EVENT_TYPE = {
+  LIFECYCLE: "lifecycle",
+  STATUS: "status",
+  SUBSCRIPTION: "subscription",
+  COORDINATION: "coordination",
+  ERROR: "error",
+  RELIABILITY: "reliability",
+  MESSAGE_METRICS: "message_metrics"
+};
+var TRACE_LIFECYCLE_ACTION = {
+  START: "start",
+  STOP: "stop",
+  SUSPEND: "suspend",
+  RESUME: "resume"
+};
+var INVOKE_LABEL = {
+  DISPATCH: "dispatch",
+  STATUS: "status",
+  ERROR_HANDLER: "error handler"
+};
+var TRACE_MODE = {
+  EVENTS: "events",
+  METRICS: "metrics",
+  ALL: "all"
+};
+var TRACE_ERROR_SOURCE = {
+  TRANSPORT: "transport",
+  OPERATION: "operation"
+};
+var RELIABILITY_OPERATION = {
+  TRANSPORT_RECOVERY: "transport_recovery",
+  ROUTE_ACK: "route_ack",
+  ROUTE_MIGRATION: "route_migration",
+  // A re-election that recovered a stranded unconfirmed handoff (previous
+  // owner gone, ACK never arrived). Distinct from ROUTE_MIGRATION so trace
+  // consumers can tell recoveries apart from routine graceful handoffs.
+  ROUTE_MIGRATION_RECOVERY: "route_migration_recovery",
+  PERSISTENCE_CLEANUP: "persistence_cleanup",
+  PERSISTENCE_RETRY: "persistence_retry",
+  DEDUP_SUPPRESSED: "dedup_suppressed"
+};
+var RECOVERY_OUTCOME = {
+  SCHEDULED: "scheduled",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  EXHAUSTED: "exhausted"
+};
+var SUBSCRIPTION_ACTION = {
+  SUBSCRIBE: "subscribe",
+  UNSUBSCRIBE: "unsubscribe"
+};
+var PRUNE_STRATEGY = {
+  COUNT: "count",
+  AGE: "age",
+  BOTH: "both"
+};
+var PERSISTENCE_OPERATION = {
+  LOAD: "load",
+  APPEND: "append",
+  CLEAR: "clear",
+  CLEAR_TOPIC: "clearTopic",
+  CLEAR_BEFORE: "clearBefore"
+};
+var FAILURE_SOURCE = {
+  TRANSPORT: "transport",
+  PERSISTENCE: "persistence",
+  DISPATCH: "dispatch"
+};
+var HEALTH_STATE = {
+  STOPPED: "stopped",
+  STARTING: "starting",
+  HEALTHY: "healthy",
+  RECOVERING: "recovering",
+  SUSPENDED: "suspended",
+  DEGRADED: "degraded"
+};
+var CENTRIFUGE_INPUT_TYPE = {
+  INIT: "INIT",
+  SUBSCRIBE: "SUBSCRIBE",
+  UNSUBSCRIBE: "UNSUBSCRIBE",
+  PUBLISH: "PUBLISH",
+  PUBLISH_BIN: "PUBLISH_BIN",
+  PING: "PING",
+  STOP: "STOP",
+  TOKEN_RESPONSE: "TOKEN_RESPONSE",
+  TOKEN_ERROR: "TOKEN_ERROR"
+};
+var CENTRIFUGE_OUTPUT_TYPE = {
+  STATUS: "STATUS",
+  MESSAGE: "MESSAGE",
+  MESSAGE_BIN: "MESSAGE_BIN",
+  ERROR: "ERROR",
+  TOKEN_REQUEST: "TOKEN_REQUEST"
+};
+
 // src/core/environment.ts
 function getStorage(name) {
   try {
@@ -40,8 +179,53 @@ function randomId() {
     return Math.random().toString(36).slice(2);
   }
 }
+function createStorageEventChannel(options) {
+  const { name, storage, win } = options;
+  if (!storage || !win) return null;
+  const key = `${STORAGE_CHANNEL_PREFIX}${name}`;
+  const listeners = /* @__PURE__ */ new Set();
+  let sequence = 0;
+  const onStorage = (event) => {
+    if (event.key !== key || event.newValue === null) return;
+    let message;
+    try {
+      const parsed = JSON.parse(event.newValue);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.seq !== "number" || !parsed.message) return;
+      message = parsed.message;
+    } catch {
+      return;
+    }
+    const event_ = { data: message };
+    for (const listener of [...listeners]) listener(event_);
+  };
+  win.addEventListener("storage", onStorage);
+  let closed = false;
+  return {
+    addEventListener(_type, listener) {
+      listeners.add(listener);
+    },
+    removeEventListener(_type, listener) {
+      listeners.delete(listener);
+    },
+    postMessage(message) {
+      if (closed) return;
+      sequence += 1;
+      storage.setItem(key, JSON.stringify({ seq: sequence, message }));
+    },
+    close() {
+      closed = true;
+      win.removeEventListener("storage", onStorage);
+      listeners.clear();
+      try {
+        storage.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
 var tabIdentityInitialized = false;
-function createBrowserEnvironment() {
+function createBrowserEnvironment(options) {
+  const channelFallback = options?.channelFallback ?? CHANNEL_FALLBACK.NONE;
   return {
     storage: getStorage("localStorage"),
     sessionStorage: getStorage("sessionStorage"),
@@ -49,14 +233,18 @@ function createBrowserEnvironment() {
     randomId,
     createChannel: (name) => {
       try {
-        return typeof BroadcastChannel === "undefined" ? null : new BroadcastChannel(name);
+        if (typeof BroadcastChannel !== "undefined") return new BroadcastChannel(name);
       } catch {
-        return null;
       }
+      return channelFallback === CHANNEL_FALLBACK.STORAGE_EVENT ? createStorageEventChannel({
+        name,
+        storage: getStorage("localStorage"),
+        win: typeof window !== "undefined" && typeof window.addEventListener === "function" ? window : null
+      }) : null;
     },
     setInterval: (callback, intervalMs) => globalThis.setInterval(callback, intervalMs),
     clearInterval: (handle) => globalThis.clearInterval(handle),
-    getVisibilityState: () => typeof document !== "undefined" && document.visibilityState === "hidden" ? "hidden" : "visible",
+    getVisibilityState: () => typeof document !== "undefined" && document.visibilityState === TAB_VISIBILITY.HIDDEN ? TAB_VISIBILITY.HIDDEN : TAB_VISIBILITY.VISIBLE,
     addVisibilityChangeListener: (listener) => {
       if (typeof document !== "undefined") document.addEventListener("visibilitychange", listener);
     },
@@ -87,7 +275,7 @@ function canUseStorage(storage, probeKey) {
     return false;
   }
 }
-function getOrCreateTabId(environment, key = "cross-tab-worker-databus:tab-id") {
+function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY) {
   const storage = environment.sessionStorage;
   try {
     const existing = storage?.getItem(key);
@@ -140,21 +328,73 @@ function avalancheMix(self, neighbor) {
 
 // src/core/routing.ts
 var DEFAULT_MAX_ACTIVE_WORKERS = 3;
-function selectLeastLoadedWorker(workers, preferredWorkerId) {
+function effectiveWorkerLoad(worker, options) {
+  const baseLoad = Number.isFinite(worker.load) ? worker.load : 0;
+  const sample = worker.throughput;
+  const messageRateWeight = options?.messageRateWeight ?? 0;
+  const byteRateWeight = options?.byteRateWeight ?? 0;
+  const scheduleLagWeight = options?.scheduleLagWeight ?? 0;
+  if (!sample || !Number.isFinite(sample.windowMs) || sample.windowMs <= 0 || messageRateWeight === 0 && byteRateWeight === 0 && scheduleLagWeight === 0) {
+    return baseLoad;
+  }
+  const windowSeconds = sample.windowMs / 1e3;
+  const messageRate = sample.messageCount / windowSeconds;
+  const byteRate = sample.byteCount / windowSeconds;
+  const scheduleLagRatio = sample.overrunMs / sample.windowMs;
+  const weighted = baseLoad + messageRateWeight * messageRate + byteRateWeight * byteRate + scheduleLagWeight * scheduleLagRatio;
+  return Number.isFinite(weighted) ? weighted : baseLoad;
+}
+function approximatePayloadBytes(payload) {
+  return estimatePayloadBytes(payload, 0);
+}
+var MAX_PAYLOAD_DEPTH = 6;
+function estimatePayloadBytes(payload, depth) {
+  if (payload === null || payload === void 0) return 0;
+  switch (typeof payload) {
+    case "boolean":
+      return 4;
+    case "number":
+    case "bigint":
+      return 8;
+    case "string":
+      return payload.length;
+    case "symbol":
+    case "function":
+      return 0;
+    case "object":
+      break;
+  }
+  if (depth >= MAX_PAYLOAD_DEPTH) return 0;
+  if (payload instanceof ArrayBuffer) return payload.byteLength;
+  if (ArrayBuffer.isView(payload)) return payload.byteLength;
+  if (Array.isArray(payload)) {
+    let sum2 = 8;
+    for (const item of payload) sum2 += estimatePayloadBytes(item, depth + 1);
+    return sum2;
+  }
+  let sum = 0;
+  for (const value of Object.values(payload)) {
+    sum += estimatePayloadBytes(value, depth + 1);
+  }
+  return sum;
+}
+function selectLeastLoadedWorker(workers, preferredWorkerId, options) {
   const preferred = workers.find((worker) => worker.workerId === preferredWorkerId);
   if (preferred) return preferred;
   return workers.reduce((least, worker) => {
     if (!least) return worker;
-    const byLoad = worker.load - least.load;
+    const byLoad = effectiveWorkerLoad(worker, options) - effectiveWorkerLoad(least, options);
     if (byLoad !== 0) return byLoad < 0 ? worker : least;
     if (worker.workerId < least.workerId) return worker;
     return least;
   }, void 0);
 }
 function selectActiveWorkers(workers, maxActiveWorkers = DEFAULT_MAX_ACTIVE_WORKERS) {
-  const healthyWorkers = workers.filter((worker) => worker.status === "connecting" || worker.status === "connected");
+  const healthyWorkers = workers.filter(
+    (worker) => worker.status === WORKER_STATUS.CONNECTING || worker.status === WORKER_STATUS.CONNECTED
+  );
   const availableWorkers = healthyWorkers.length > 0 ? healthyWorkers : [...workers];
-  const visibleWorkers = availableWorkers.filter((worker) => worker.visibilityState === "visible");
+  const visibleWorkers = availableWorkers.filter((worker) => worker.visibilityState === TAB_VISIBILITY.VISIBLE);
   const candidates = visibleWorkers.length > 0 ? visibleWorkers : availableWorkers;
   return candidates.sort(
     (left, right) => left.registeredAt - right.registeredAt || (left.workerId < right.workerId ? -1 : left.workerId > right.workerId ? 1 : 0)
@@ -179,6 +419,7 @@ var BatchingStorageWriter = class {
   constructor(storage) {
     this.storage = storage;
   }
+  storage;
   /** Coalesced write set. A `null` value represents a pending delete. */
   pending = /* @__PURE__ */ new Map();
   /** Per-key retry counter, reset on a successful write. */
@@ -235,7 +476,7 @@ var BatchingStorageWriter = class {
           this.pending.delete(key);
           this.retryCount.delete(key);
           if (typeof console !== "undefined" && typeof console.warn === "function") {
-            console.warn("[cross-tab-worker-databus] storage write gave up after retries, dropping key:", key);
+            console.warn(`[${DEFAULT_STORAGE_PREFIX}] storage write gave up after retries, dropping key:`, key);
           }
           continue;
         }
@@ -295,12 +536,16 @@ var BatchingStorageWriter = class {
   }
 };
 
-// src/core/cluster.ts
-var CLUSTER_PROTOCOL_VERSION = 1;
-var DEFAULT_HEARTBEAT_INTERVAL_MS = 3e3;
-var DEFAULT_WORKER_TTL_MS = 1e4;
-var DEFAULT_STORAGE_PREFIX = "cross-tab-worker-databus";
-var MAX_KNOWN_TOPICS = 500;
+// src/utils/metadata.ts
+function publicationMetadata(messageId, timestamp) {
+  if (messageId === void 0 && timestamp === void 0) return void 0;
+  return {
+    ...messageId === void 0 ? {} : { messageId },
+    ...timestamp === void 0 ? {} : { timestamp }
+  };
+}
+
+// src/utils/storage-utils.ts
 function readJson(storage, key) {
   try {
     const value = storage.getItem(key);
@@ -315,13 +560,6 @@ function writeJson(storage, key, value) {
   } catch {
   }
 }
-function publicationMetadata(messageId, timestamp) {
-  if (messageId === void 0 && timestamp === void 0) return void 0;
-  return {
-    ...messageId === void 0 ? {} : { messageId },
-    ...timestamp === void 0 ? {} : { timestamp }
-  };
-}
 function listKeys(storage, prefix) {
   try {
     return Array.from({ length: storage.length }, (_, index) => storage.key(index)).filter(
@@ -334,6 +572,120 @@ function listKeys(storage, prefix) {
 function readAllByPrefix(storage, prefix) {
   return listKeys(storage, prefix).map((key) => ({ key, value: readJson(storage, key) })).filter((entry) => entry.value !== null);
 }
+
+// src/utils/validation.ts
+function assertPositiveSafeInteger(value, name) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}.`);
+  }
+}
+function assertPositiveFiniteNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive finite number.`);
+  }
+}
+function assertNonNegativeFiniteNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative finite number.`);
+  }
+}
+function assertPruneStrategy(value) {
+  const allowed = [PRUNE_STRATEGY.COUNT, PRUNE_STRATEGY.AGE, PRUNE_STRATEGY.BOTH];
+  if (!allowed.includes(String(value))) {
+    throw new TypeError("pruneStrategy must be count, age, or both.");
+  }
+}
+function assertReplayOptions(replay) {
+  if (!replay) return;
+  if (replay.maxPerTopic !== void 0) assertPositiveSafeInteger(replay.maxPerTopic, "replay.maxPerTopic");
+  if (replay.pruneStrategy !== void 0) assertPruneStrategy(replay.pruneStrategy);
+  if (replay.retentionMs !== void 0) assertPositiveFiniteNumber(replay.retentionMs, "replay.retentionMs");
+  if (replay.retentionSweepMs !== void 0) {
+    assertPositiveFiniteNumber(replay.retentionSweepMs, "replay.retentionSweepMs");
+  }
+  if (replay.persistenceRetry) assertPersistenceRetryOptions(replay.persistenceRetry);
+}
+function assertPersistenceRetryOptions(retry) {
+  if (retry.maxAttempts !== void 0) {
+    assertPositiveSafeInteger(retry.maxAttempts, "replay.persistenceRetry.maxAttempts");
+  }
+  if (retry.backoffMs !== void 0) {
+    assertNonNegativeFiniteNumber(retry.backoffMs, "replay.persistenceRetry.backoffMs");
+  }
+}
+function assertDedupOptions(dedup) {
+  if (!dedup) return;
+  if (dedup.maxEntries !== void 0) assertPositiveSafeInteger(dedup.maxEntries, "dedup.maxEntries");
+  if (dedup.ttlMs !== void 0) assertPositiveFiniteNumber(dedup.ttlMs, "dedup.ttlMs");
+  if (dedup.sweepMs !== void 0) assertPositiveFiniteNumber(dedup.sweepMs, "dedup.sweepMs");
+  const bounds = dedup.adaptiveTtl;
+  if (bounds !== void 0) {
+    const finite = (value) => typeof value === "number" && Number.isFinite(value);
+    if (!finite(bounds.minMs) || !finite(bounds.maxMs) || bounds.minMs <= 0 || bounds.maxMs < bounds.minMs) {
+      throw new TypeError("dedup.adaptiveTtl bounds are invalid.");
+    }
+  }
+}
+function assertRecoveryOptions(recovery) {
+  if (!recovery) return;
+  if (recovery.cooldownMs !== void 0) {
+    assertPositiveFiniteNumber(recovery.cooldownMs, "recovery.cooldownMs");
+  }
+  const maxAttempts = recovery.maxAttempts;
+  if (maxAttempts !== void 0 && !(maxAttempts === Number.POSITIVE_INFINITY || typeof maxAttempts === "number" && Number.isSafeInteger(maxAttempts) && maxAttempts > 0)) {
+    throw new TypeError("recovery.maxAttempts must be a positive safe integer.");
+  }
+}
+function assertLoadWeightingOptions(loadWeighting) {
+  if (!loadWeighting) return;
+  const weights = {
+    messageRateWeight: loadWeighting.messageRateWeight,
+    byteRateWeight: loadWeighting.byteRateWeight,
+    scheduleLagWeight: loadWeighting.scheduleLagWeight
+  };
+  for (const [name, value] of Object.entries(weights)) {
+    if (value !== void 0) assertNonNegativeFiniteNumber(value, `loadWeighting.${name}`);
+  }
+}
+function assertClusterOptions(options) {
+  if (options.maxActiveWorkers !== void 0) {
+    assertPositiveSafeInteger(options.maxActiveWorkers, "maxActiveWorkers");
+  }
+  if (options.heartbeatIntervalMs !== void 0) {
+    assertPositiveFiniteNumber(options.heartbeatIntervalMs, "heartbeatIntervalMs");
+  }
+  if (options.workerTtlMs !== void 0) {
+    assertPositiveFiniteNumber(options.workerTtlMs, "workerTtlMs");
+  }
+  if (options.routeOwnerCacheMax !== void 0) {
+    assertPositiveSafeInteger(options.routeOwnerCacheMax, "routeOwnerCacheMax");
+  }
+  assertLoadWeightingOptions(options.loadWeighting);
+}
+function assertHeartbeatInterval(value) {
+  if (value === Infinity) return;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return;
+  throw new TypeError(
+    `Centrifuge heartbeatIntervalMs must be a positive number or Infinity, got ${String(value)}.`
+  );
+}
+function assertStructuredCloneable(value) {
+  if (typeof structuredClone !== "function") return;
+  try {
+    structuredClone(value);
+  } catch (error) {
+    throw new TypeError(
+      "Centrifuge Worker configuration and published data must be structured-cloneable.",
+      { cause: error }
+    );
+  }
+}
+
+// src/core/cluster.ts
+var CLUSTER_PROTOCOL_VERSION = 1;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 3e3;
+var DEFAULT_WORKER_TTL_MS = 1e4;
+var MAX_KNOWN_TOPICS = 500;
 var WorkerClusterRuntime = class {
   tabId;
   workerId;
@@ -347,6 +699,14 @@ var WorkerClusterRuntime = class {
   routePrefix;
   subscriberPrefix;
   channelName;
+  /** Adaptive load weighting options; undefined keeps legacy topic-count routing. */
+  loadWeighting;
+  /** Rolling traffic accumulator folded into the worker record on writeRecord. */
+  throughputWindow = {
+    startedAt: 0,
+    messageCount: 0,
+    byteCount: 0
+  };
   // Topics this tab has subscribed to (local interest, plaintext).
   subscribedTopics = /* @__PURE__ */ new Set();
   // Topics assigned to this Worker as owner (topicKey → topic). Authoritative:
@@ -382,12 +742,14 @@ var WorkerClusterRuntime = class {
   lifecycleListening = false;
   currentRecord;
   constructor(options) {
+    assertClusterOptions(options);
     this.environment = options.environment ?? createBrowserEnvironment();
     this.handlers = options.handlers;
     this.maxActiveWorkers = options.maxActiveWorkers ?? DEFAULT_MAX_ACTIVE_WORKERS;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     this.routeOwnerCacheMax = options.routeOwnerCacheMax ?? 256;
     this.workerTtlMs = options.workerTtlMs ?? DEFAULT_WORKER_TTL_MS;
+    this.loadWeighting = options.loadWeighting;
     const clusterHash = createOpaqueKey(options.clusterKey || "__default__");
     const prefix = options.storagePrefix ?? DEFAULT_STORAGE_PREFIX;
     const baseKey = `${prefix}:${clusterHash}`;
@@ -404,8 +766,8 @@ var WorkerClusterRuntime = class {
       workerId: this.workerId,
       tabId: this.tabId,
       load: 0,
-      role: "standby",
-      status: "connecting",
+      role: WORKER_ROLE.STANDBY,
+      status: WORKER_STATUS.CONNECTING,
       visibilityState: this.environment.getVisibilityState(),
       heartbeatAt: now,
       registeredAt: now
@@ -458,7 +820,7 @@ var WorkerClusterRuntime = class {
     this.writeRecord(true);
     for (const topic of this.subscribedTopics) {
       const topicKey = this.rememberTopic(topic);
-      if (!this.storage) this.sendControl(this.workerId, "SUBSCRIBE", topic, topicKey);
+      if (!this.storage) this.sendControl(this.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
       else this.writeSubscriber(topicKey);
     }
     this.reconcile();
@@ -486,9 +848,14 @@ var WorkerClusterRuntime = class {
     this.removeStorage(this.workerStorageKey(this.workerId));
     this.flushStorage();
     this.notifyRegistry();
-    this.channel?.close();
+    const channel = this.channel;
     this.channel = null;
     this.handlers.onSuspend?.();
+    if (typeof globalThis.setTimeout === "function") {
+      globalThis.setTimeout(() => channel?.close(), 0);
+    } else {
+      channel?.close();
+    }
   }
   /** Update the worker's connection status and persist the change. */
   setStatus(status) {
@@ -506,7 +873,7 @@ var WorkerClusterRuntime = class {
     this.subscribedTopics.add(topic);
     if (!this.started) return false;
     if (!this.storage) {
-      this.sendControl(this.workerId, "SUBSCRIBE", topic, topicKey);
+      this.sendControl(this.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
       return true;
     }
     this.writeSubscriber(topicKey);
@@ -516,9 +883,9 @@ var WorkerClusterRuntime = class {
       return existingRoute?.workerId === this.workerId;
     }
     const activeWorkers = selectActiveWorkers(workers, this.maxActiveWorkers);
-    const owner = selectLeastLoadedWorker(activeWorkers) ?? this.currentRecord;
+    const owner = selectLeastLoadedWorker(activeWorkers, void 0, this.loadWeighting) ?? this.currentRecord;
     this.writeRoute(topicKey, owner, void 0, (existingRoute?.generation ?? 0) + 1);
-    this.sendControl(owner.workerId, "SUBSCRIBE", topic, topicKey);
+    this.sendControl(owner.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
     this.notifyRegistry();
     return owner.workerId === this.workerId;
   }
@@ -542,7 +909,7 @@ var WorkerClusterRuntime = class {
     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);
+      if (notifyOwner) this.sendControl(route.workerId, CONTROL_ACTION.UNSUBSCRIBE, topic, topicKey);
     }
     return topicKey;
   }
@@ -561,15 +928,17 @@ var WorkerClusterRuntime = class {
         continue;
       }
       const owner = selectLeastLoadedWorker(
-        activeWorkers.map((worker) => ({ ...worker, load: projectedLoads.get(worker.workerId) ?? worker.load }))
+        activeWorkers.map((worker) => ({ ...worker, load: projectedLoads.get(worker.workerId) ?? worker.load })),
+        void 0,
+        this.loadWeighting
       );
       if (!owner) continue;
       projectedLoads.set(owner.workerId, (projectedLoads.get(owner.workerId) ?? owner.load) + 1);
       const generation = (previous?.generation ?? 0) + 1;
       this.writeRoute(topicKey, owner, previous?.workerId, generation);
-      this.handlers.onDiagnostic?.({ operation: "route_migration", topic });
+      this.handlers.onDiagnostic?.({ operation: RELIABILITY_OPERATION.ROUTE_MIGRATION, topic });
       this.flushStorage();
-      this.handlers.onControl("UNSUBSCRIBE", topic);
+      this.handlers.onControl(CONTROL_ACTION.UNSUBSCRIBE, topic);
       this.sendRouteReleased(owner.workerId, topic, topicKey, generation);
     }
   }
@@ -577,22 +946,19 @@ var WorkerClusterRuntime = class {
     const metadata = typeof metadataOrMessageId === "string" ? { messageId: metadataOrMessageId } : metadataOrMessageId;
     const topicKey = this.rememberTopic(topic);
     if (this.assignedTopics.has(topicKey)) {
-      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
+      return this.sendControl(this.workerId, CONTROL_ACTION.PUBLISH, topic, topicKey, data, metadata);
     }
     const cachedPattern = this.wildcardPublishCache.get(topic);
-    if (cachedPattern !== void 0 && cachedPattern !== null && this.assignedTopics.has(cachedPattern)) {
-      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
-    }
     if (cachedPattern === void 0) {
       for (const pattern of this.assignedTopics.values()) {
         if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
           this.wildcardPublishCache.set(topic, pattern);
-          return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
+          return this.sendControl(this.workerId, CONTROL_ACTION.PUBLISH, topic, topicKey, data, metadata);
         }
       }
       this.wildcardPublishCache.set(topic, null);
     }
-    return this.sendControl(this.resolvePublishTarget(topic, topicKey), "PUBLISH", topic, topicKey, data, metadata);
+    return this.sendControl(this.resolvePublishTarget(topic, topicKey), CONTROL_ACTION.PUBLISH, topic, topicKey, data, metadata);
   }
   /**
    * Burst-friendly variant of `publish()`: packs up to N items into a single
@@ -613,19 +979,15 @@ var WorkerClusterRuntime = class {
     }
     const topicKey = this.rememberTopic(topic);
     if (this.assignedTopics.has(topicKey)) {
-      for (const item of items) this.dispatchLocalPublish(topic, topicKey, item.data, item.messageId, item.timestamp);
+      this.dispatchLocalPublishBatch(topic, topicKey, items);
       return true;
     }
     const cachedPattern = this.wildcardPublishCache.get(topic);
-    if (cachedPattern !== void 0 && cachedPattern !== null && this.assignedTopics.has(cachedPattern)) {
-      for (const item of items) this.dispatchLocalPublish(topic, topicKey, item.data, item.messageId, item.timestamp);
-      return true;
-    }
     if (cachedPattern === void 0) {
       for (const pattern of this.assignedTopics.values()) {
         if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
           this.wildcardPublishCache.set(topic, pattern);
-          for (const item of items) this.dispatchLocalPublish(topic, topicKey, item.data, item.messageId, item.timestamp);
+          this.dispatchLocalPublishBatch(topic, topicKey, items);
           return true;
         }
       }
@@ -633,14 +995,14 @@ var WorkerClusterRuntime = class {
     }
     const target = this.resolvePublishTarget(topic, topicKey);
     if (target === this.workerId) {
-      for (const item of items) this.dispatchLocalPublish(topic, topicKey, item.data, item.messageId, item.timestamp);
+      this.dispatchLocalPublishBatch(topic, topicKey, items);
       return true;
     }
     return this.send({
-      type: "CONTROL",
+      type: CLUSTER_MESSAGE_TYPE.CONTROL,
       sourceWorkerId: this.workerId,
       targetWorkerId: target,
-      action: "PUBLISH",
+      action: CONTROL_ACTION.PUBLISH,
       topic,
       topicKey,
       items: items.map((item) => ({
@@ -671,8 +1033,17 @@ var WorkerClusterRuntime = class {
   dispatchLocalPublish(topic, topicKey, data, messageId, timestamp) {
     void topicKey;
     const meta = publicationMetadata(messageId, timestamp);
-    if (meta) this.handlers.onControl("PUBLISH", topic, data, meta.messageId, meta.timestamp);
-    else this.handlers.onControl("PUBLISH", topic, data);
+    if (meta) this.handlers.onControl(CONTROL_ACTION.PUBLISH, topic, data, meta.messageId, meta.timestamp);
+    else this.handlers.onControl(CONTROL_ACTION.PUBLISH, topic, data);
+  }
+  /** Fan out a publication batch to the local onControl path: one
+   * onPublishBatch call when the owner supports it, per-item otherwise. */
+  dispatchLocalPublishBatch(topic, topicKey, items) {
+    if (this.handlers.onPublishBatch) {
+      this.handlers.onPublishBatch(topic, items);
+      return;
+    }
+    for (const item of items) this.dispatchLocalPublish(topic, topicKey, item.data, item.messageId, item.timestamp);
   }
   /** True when `route` exists and its owner worker is among `workers`.
    * Shared by subscribe (skip re-assignment) and publish (route to owner).
@@ -686,7 +1057,39 @@ var WorkerClusterRuntime = class {
    * listeners can attribute the event to its source tab even after fan-out. */
   broadcastEvent(eventType, payload, originTabId) {
     const effectiveOriginTabId = originTabId ?? this.tabId;
-    this.send({ type: "EVENT", sourceWorkerId: this.workerId, eventType, payload, originTabId: effectiveOriginTabId });
+    this.recordTraffic(payload);
+    this.send({ type: CLUSTER_MESSAGE_TYPE.EVENT, sourceWorkerId: this.workerId, eventType, payload, originTabId: effectiveOriginTabId });
+  }
+  /** Count one fan-out unit toward the adaptive load sample. No-op unless
+   * adaptive weighting is configured. */
+  recordTraffic(payload) {
+    if (this.loadWeighting === void 0) return;
+    this.throughputWindow.messageCount += 1;
+    this.throughputWindow.byteCount += approximatePayloadBytes(payload);
+  }
+  /** Convert the accumulated window into a publishable throughput sample and
+   * reset the accumulator. Returns undefined until a full window has elapsed
+   * so the first write does not emit a zero-width sample. */
+  sampleThroughput(now) {
+    if (this.throughputWindow.startedAt === 0) {
+      this.throughputWindow.startedAt = now;
+      return void 0;
+    }
+    const windowMs = now - this.throughputWindow.startedAt;
+    if (windowMs <= 0) return void 0;
+    const sample = {
+      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
+      // positive excess is the scheduling-overrun signal.
+      overrunMs: Math.max(0, windowMs - this.heartbeatIntervalMs),
+      sampledAt: now
+    };
+    this.throughputWindow = { startedAt: now, messageCount: 0, byteCount: 0 };
+    return sample;
   }
   isAssigned(topic) {
     const topicKey = createOpaqueKey(topic);
@@ -776,14 +1179,14 @@ var WorkerClusterRuntime = class {
     const message = event.data;
     if (!message || message.sourceWorkerId === this.workerId) return;
     switch (message.type) {
-      case "CONTROL":
+      case CLUSTER_MESSAGE_TYPE.CONTROL:
         return this.handleControlMessage(message);
-      case "ROUTE_RELEASED":
+      case CLUSTER_MESSAGE_TYPE.ROUTE_RELEASED:
         return this.handleRouteReleasedMessage(message);
-      case "EVENT":
+      case CLUSTER_MESSAGE_TYPE.EVENT:
         this.handlers.onEvent(message.eventType, message.payload, message.sourceWorkerId, message.originTabId);
         return;
-      case "REGISTRY":
+      case CLUSTER_MESSAGE_TYPE.REGISTRY:
         this.reconcile();
         return;
       default: {
@@ -800,19 +1203,23 @@ var WorkerClusterRuntime = class {
     if (message.targetWorkerId !== this.workerId) return;
     this.rememberTopic(message.topic);
     switch (message.action) {
-      case "SUBSCRIBE":
+      case CONTROL_ACTION.SUBSCRIBE:
         this.assignedTopics.set(message.topicKey, message.topic);
         this.confirmRoute(message.topicKey);
         break;
-      case "UNSUBSCRIBE":
+      case CONTROL_ACTION.UNSUBSCRIBE:
         if (this.releaseHandoffOnUnsubscribe(message)) return;
         break;
-      case "PUBLISH":
+      case CONTROL_ACTION.PUBLISH:
         if (message.items && message.items.length > 0) {
+          if (this.handlers.onPublishBatch) {
+            this.handlers.onPublishBatch(message.topic, message.items);
+            return;
+          }
           for (const item of message.items) {
             const itemMeta = publicationMetadata(item.messageId, item.timestamp);
-            if (itemMeta) this.handlers.onControl("PUBLISH", message.topic, item.data, itemMeta.messageId, itemMeta.timestamp);
-            else this.handlers.onControl("PUBLISH", message.topic, item.data);
+            if (itemMeta) this.handlers.onControl(CONTROL_ACTION.PUBLISH, message.topic, item.data, itemMeta.messageId, itemMeta.timestamp);
+            else this.handlers.onControl(CONTROL_ACTION.PUBLISH, message.topic, item.data);
           }
           return;
         }
@@ -829,7 +1236,7 @@ var WorkerClusterRuntime = class {
       metadata.timestamp
     );
     else this.handlers.onControl(message.action, message.topic, message.data);
-    if (message.action !== "PUBLISH") this.updateLoad();
+    if (message.action !== CONTROL_ACTION.PUBLISH) this.updateLoad();
   }
   /**
    * When this worker is the previous owner in a graceful handoff and the new
@@ -841,7 +1248,7 @@ var WorkerClusterRuntime = class {
     this.assignedTopics.delete(message.topicKey);
     const route = this.readRoute(message.topicKey);
     if (route?.handoffFromWorkerId !== this.workerId) return false;
-    this.handlers.onControl("UNSUBSCRIBE", message.topic, void 0);
+    this.handlers.onControl(CONTROL_ACTION.UNSUBSCRIBE, message.topic, void 0);
     this.sendRouteReleased(route.workerId, message.topic, message.topicKey, route.generation);
     this.updateLoad();
     return true;
@@ -850,7 +1257,7 @@ var WorkerClusterRuntime = class {
    * generation so only the matching new owner may act on it. */
   sendRouteReleased(targetWorkerId, topic, topicKey, generation) {
     this.send({
-      type: "ROUTE_RELEASED",
+      type: CLUSTER_MESSAGE_TYPE.ROUTE_RELEASED,
       sourceWorkerId: this.workerId,
       targetWorkerId,
       topic,
@@ -869,14 +1276,24 @@ var WorkerClusterRuntime = class {
     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.handlers.onControl(CONTROL_ACTION.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. */
+   * the release generation is at least as new as ours. A replayed ACK from an
+   * earlier handoff round (e.g. an a↔b ping-pong) carries an older generation
+   * and must not confirm the current round. */
   isStaleRouteRelease(route, message) {
-    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || route.generation < message.generation;
+    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || message.generation < route.generation;
+  }
+  /** True when an unconfirmed handoff route has been stuck longer than a
+   * worker TTL. The ACK for a live handoff is posted synchronously with the
+   * route write, so anything older than the TTL with a dead previous owner
+   * 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;
   }
   /** Full reconciliation cycle: workers, subscriptions, and assigned topics. */
   reconcile() {
@@ -909,20 +1326,39 @@ var WorkerClusterRuntime = class {
    */
   reconcileSubscriptions(workers, activeWorkers) {
     const liveWorkerIds = new Set(workers.map((worker) => worker.workerId));
+    const recoveryProjectedLoads = /* @__PURE__ */ new Map();
     for (const topic of this.subscribedTopics) {
       const topicKey = this.rememberTopic(topic);
       this.writeSubscriber(topicKey);
       const route = this.readRoute(topicKey);
       if (!route || !liveWorkerIds.has(route.workerId)) {
-        const owner = selectLeastLoadedWorker(activeWorkers) ?? this.currentRecord;
+        const owner = selectLeastLoadedWorker(activeWorkers, void 0, this.loadWeighting) ?? this.currentRecord;
         this.writeRoute(topicKey, owner, void 0, (route?.generation ?? 0) + 1);
-        this.sendControl(owner.workerId, "SUBSCRIBE", topic, topicKey);
+        this.sendControl(owner.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
         this.notifyRegistry();
         continue;
       }
       if (route.confirmedAt === void 0) {
         if (!route.handoffFromWorkerId) {
-          this.sendControl(route.workerId, "SUBSCRIBE", topic, topicKey);
+          this.sendControl(route.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
+        } else if (!liveWorkerIds.has(route.handoffFromWorkerId) && this.isStaleHandoff(route)) {
+          const owner = selectLeastLoadedWorker(
+            activeWorkers.map((worker) => ({ ...worker, load: recoveryProjectedLoads.get(worker.workerId) ?? worker.load })),
+            void 0,
+            this.loadWeighting
+          ) ?? 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;
+          }
+          this.writeRoute(topicKey, owner, void 0, route.generation + 1);
+          this.sendControl(owner.workerId, CONTROL_ACTION.SUBSCRIBE, topic, topicKey);
+          this.handlers.onDiagnostic?.({ operation: RELIABILITY_OPERATION.ROUTE_MIGRATION_RECOVERY, topic });
+          this.notifyRegistry();
         }
       }
     }
@@ -933,7 +1369,7 @@ var WorkerClusterRuntime = class {
       const route = this.readRoute(topicKey);
       if (route?.workerId === this.workerId) continue;
       this.assignedTopics.delete(topicKey);
-      this.handlers.onControl("UNSUBSCRIBE", topic, void 0);
+      this.handlers.onControl(CONTROL_ACTION.UNSUBSCRIBE, topic, void 0);
       if (route?.handoffFromWorkerId === this.workerId) {
         this.sendRouteReleased(route.workerId, topic, topicKey, route.generation);
       }
@@ -948,14 +1384,14 @@ var WorkerClusterRuntime = class {
   sendControl(targetWorkerId, action, topic, topicKey, data, metadata) {
     if (targetWorkerId === this.workerId) {
       switch (action) {
-        case "SUBSCRIBE":
+        case CONTROL_ACTION.SUBSCRIBE:
           this.assignedTopics.set(topicKey, topic);
           this.confirmRoute(topicKey);
           break;
-        case "UNSUBSCRIBE":
+        case CONTROL_ACTION.UNSUBSCRIBE:
           this.assignedTopics.delete(topicKey);
           break;
-        case "PUBLISH":
+        case CONTROL_ACTION.PUBLISH:
         default:
           break;
       }
@@ -967,11 +1403,11 @@ var WorkerClusterRuntime = class {
         metadata.timestamp
       );
       else this.handlers.onControl(action, topic, data);
-      if (action !== "PUBLISH") this.updateLoad();
+      if (action !== CONTROL_ACTION.PUBLISH) this.updateLoad();
       return true;
     }
     return this.send({
-      type: "CONTROL",
+      type: CLUSTER_MESSAGE_TYPE.CONTROL,
       sourceWorkerId: this.workerId,
       targetWorkerId,
       action,
@@ -1076,7 +1512,7 @@ var WorkerClusterRuntime = class {
       confirmedAt: this.environment.now()
     });
     const topic = this.knownTopics.get(topicKey);
-    if (topic) this.handlers.onDiagnostic?.({ operation: "route_ack", topic });
+    if (topic) this.handlers.onDiagnostic?.({ operation: RELIABILITY_OPERATION.ROUTE_ACK, topic });
   }
   /** Remove routes whose topic has no subscribers and whose TTL has expired. */
   cleanupOrphanedRoutes(workers) {
@@ -1111,17 +1547,23 @@ var WorkerClusterRuntime = class {
    *   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() };
+    const now = this.environment.now();
+    const sample = this.loadWeighting !== void 0 ? this.sampleThroughput(now) : void 0;
+    this.currentRecord = {
+      ...this.currentRecord,
+      heartbeatAt: now,
+      ...sample ? { throughput: sample } : {}
+    };
     if (this.storage) writeJson(this.storage, this.workerStorageKey(this.workerId), this.currentRecord);
     if (notify) this.notifyRegistry();
   }
   /** Broadcast a REGISTRY message to trigger reconciliation on other tabs. */
   notifyRegistry() {
-    this.send({ type: "REGISTRY", sourceWorkerId: this.workerId });
+    this.send({ type: CLUSTER_MESSAGE_TYPE.REGISTRY, sourceWorkerId: this.workerId });
   }
   /** Recompute whether this worker is active (eligible to own topics) or standby. Returns true when changed. */
   refreshRole(workers) {
-    const role = this.isActiveAmong(workers) ? "active" : "standby";
+    const role = this.isActiveAmong(workers) ? WORKER_ROLE.ACTIVE : WORKER_ROLE.STANDBY;
     if (role === this.currentRecord.role) return false;
     this.currentRecord = { ...this.currentRecord, role };
     return true;
@@ -1219,7 +1661,7 @@ var DataBusTraceReporter = class {
   /** 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;
+    if (!this.enabled || this.intervalHandle || this.mode === TRACE_MODE.EVENTS) return;
     this.stopped = false;
     this.intervalStartedAt = this.now();
     this.intervalHandle = setInterval(() => this.flush(), this.metricsIntervalMs);
@@ -1235,11 +1677,40 @@ var DataBusTraceReporter = class {
     this.stopped = true;
     this.pause();
   }
+  /** Synchronous sink state for diagnostics: whether delivery is async and how
+   * many events are queued behind the microtask flush. A growing queue under
+   * `asyncSink: true` is the first sign of sink back-pressure. */
+  getSinkState() {
+    return { asyncSink: this.asyncSink, pendingEvents: this.pendingEvents.length };
+  }
   /** Record an instantaneous trace event (lifecycle, status, error, etc.). */
   event(event) {
-    if (!this.enabled || this.mode === "metrics") return;
+    if (!this.enabled || this.mode === TRACE_MODE.METRICS) return;
     this.emit({ ...event, timestamp: this.now() });
   }
+  /** Synchronous snapshot of the current metrics window without resetting it.
+   * Returns the same derived counters as a periodic `message_metrics` event,
+   * or null when metrics recording is inactive (disabled or events-only mode).
+   * The window keeps accumulating until the next interval flush. */
+  getMetrics() {
+    if (!this.metricsActive || this.stopped) return null;
+    const timestamp = this.now();
+    const samples = this.latencySamples;
+    return {
+      durationMs: Math.max(0, timestamp - this.intervalStartedAt),
+      received: this.received,
+      dispatched: this.dispatched,
+      topics: this.topics.size,
+      dispatchSamples: samples,
+      dispatchAvgMs: roundMs(samples === 0 ? 0 : this.latencySumMs / samples),
+      dispatchP50Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.5)),
+      dispatchP95Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.95)),
+      dispatchMaxMs: roundMs(percentileMs(this.latencyBuckets, samples, 1)),
+      dedupAccepted: this.dedupAccepted,
+      dedupSuppressed: this.dedupSuppressed,
+      timestamp
+    };
+  }
   /** Record that a message was received on `topic`; stores its timestamp for latency tracking. */
   recordReceived(topic) {
     if (!this.metricsActive) return;
@@ -1297,7 +1768,7 @@ var DataBusTraceReporter = class {
    * 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";
+    return this.enabled && this.mode !== TRACE_MODE.EVENTS;
   }
   /** Emit the accumulated metrics snapshot if the interval is active. */
   flush() {
@@ -1309,7 +1780,7 @@ var DataBusTraceReporter = class {
     if (this.received > 0 || this.dispatched > 0 || this.dedupAccepted > 0 || this.dedupSuppressed > 0) {
       const samples = this.latencySamples;
       this.emit({
-        type: "message_metrics",
+        type: TRACE_EVENT_TYPE.MESSAGE_METRICS,
         durationMs: Math.max(0, timestamp - this.intervalStartedAt),
         received: this.received,
         dispatched: this.dispatched,
@@ -1360,7 +1831,7 @@ var DataBusTraceReporter = class {
       this.sink(event);
     } catch (error) {
       if (typeof console !== "undefined" && typeof console.warn === "function") {
-        console.warn("[cross-tab-worker-databus] trace sink threw:", error);
+        console.warn(`[${DEFAULT_STORAGE_PREFIX}] trace sink threw:`, error);
       }
     }
   }
@@ -1386,160 +1857,600 @@ function roundMs(value) {
   return Math.round(value * 10) / 10;
 }
 
-// src/core/data-bus.ts
-var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
-var SDK_VERSION = "0.20.69";
-var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
+// src/core/replay-pruning.ts
+function pruneReplayHistory(messages, options) {
+  const { maxPerTopic, pruneStrategy, retentionMs, now } = options;
+  const ageEnabled = pruneStrategy !== PRUNE_STRATEGY.COUNT && retentionMs !== void 0;
+  if (!ageEnabled) {
+    return messages.length > maxPerTopic ? messages.slice(-maxPerTopic) : messages;
+  }
+  const cutoff = now - retentionMs;
+  let hasExpired = false;
+  let timestamplessCount = 0;
+  for (const message of messages) {
+    if (message.timestamp === void 0) timestamplessCount += 1;
+    else if (message.timestamp < cutoff) hasExpired = true;
+  }
+  let pruned = hasExpired ? messages.filter((message) => message.timestamp === void 0 || message.timestamp >= cutoff) : messages;
+  if (pruneStrategy === PRUNE_STRATEGY.BOTH) {
+    return pruned.length > maxPerTopic ? pruned.slice(-maxPerTopic) : pruned;
+  }
+  if (timestamplessCount <= maxPerTopic) return pruned;
+  let timestamplessToDrop = timestamplessCount - maxPerTopic;
+  pruned = pruned.filter((message) => {
+    if (message.timestamp === void 0 && timestamplessToDrop > 0) {
+      timestamplessToDrop -= 1;
+      return false;
+    }
+    return true;
+  });
+  return pruned;
+}
+
+// src/core/replay-manager.ts
 var PersistenceRetryCancelledError = class extends Error {
   constructor() {
     super("Persistence retry cancelled by lifecycle transition.");
     this.name = "PersistenceRetryCancelledError";
   }
 };
-var CrossTabDataBus = class {
-  transport;
-  cluster;
-  // Map of topic → set of local subscribers.
-  topicHandlers = /* @__PURE__ */ new Map();
-  // Topics for which the transport has been asked to subscribe (used to avoid
-  // duplicate subscribe calls during reconnection).
-  transportSubscribedTopics = /* @__PURE__ */ new Set();
-  statusHandlers = /* @__PURE__ */ new Set();
-  errorHandlers = /* @__PURE__ */ new Set();
-  // Bounded per-topic ring of recent dispatched publications. Null unless
-  // replay is enabled — buffering is opt-in and must cost nothing otherwise.
-  replayBuffers;
-  replayMaxPerTopic;
-  replayPersistence;
-  replayRetentionMs;
-  replayPruneStrategy;
-  replayRetentionSweepMs;
+var MAX_RETRY_DELAY_MS2 = 1600;
+var ReplayManager = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.buffers = deps.enabled ? /* @__PURE__ */ new Map() : null;
+    this.maxPerTopic = deps.maxPerTopic;
+    this.persistence = deps.persistence ?? null;
+    this.retentionMs = deps.retentionMs;
+    this.pruneStrategy = deps.pruneStrategy;
+    this.retentionSweepMs = deps.retentionSweepMs;
+    this.persistenceRetryMaxAttempts = deps.persistenceRetryMaxAttempts;
+    this.persistenceRetryBackoffMs = deps.persistenceRetryBackoffMs;
+    this.now = deps.now;
+    this.trace = deps.trace;
+    this.onPersistenceError = deps.onPersistenceError;
+    this.onDispatchError = deps.onDispatchError;
+    this.hydration = this.hydrate();
+  }
+  deps;
+  buffers;
+  maxPerTopic;
+  persistence;
+  retentionMs;
+  pruneStrategy;
+  retentionSweepMs;
   persistenceRetryMaxAttempts;
   persistenceRetryBackoffMs;
-  persistenceRetryGeneration = 0;
-  pendingReplayPersistence = [];
-  replayPersistenceFlushScheduled = false;
-  replayHydration;
-  // Retention cleanup is coalesced so a burst of publications does not issue
-  // one IndexedDB read/write transaction per message. The newest cutoff wins.
-  replayRetentionCleanup = null;
-  replayRetentionCutoff = null;
-  replayRetentionTimer = null;
-  initialConfig;
-  hasInitialConfig;
-  trace;
-  dedupMaxEntries;
-  dedupTtlMs;
-  dedupAdaptiveBounds;
-  dedupWindowStartedAt = 0;
-  dedupWindowAccepted = 0;
-  dedupAdaptiveWindowMs = 5e3;
-  dedupSweepMs;
-  dedupSweepTimer = null;
-  dedupEnabled;
   now;
-  seenMessageIds = /* @__PURE__ */ new Map();
-  dedupSuppressed = 0;
-  dedupAccepted = 0;
-  activeConfig;
-  status = "disconnected";
-  started = false;
-  stopping = false;
-  transportReady = false;
-  // Last transport failure, retained so ready() can surface it to callers who
-  // never awaited start() directly. Cleared on the next successful start.
-  lastError = null;
-  lastErrorAt = null;
-  // Gate that serialises start/stop/suspend/resume — only one lifecycle
-  // transition at a time. Resets to null once the operation settles.
-  startPromise = null;
-  // Timestamp of the last automatic transport recovery attempt.
-  // Used to avoid a tight retry loop when the transport fails repeatedly.
-  lastRecoveryAt = 0;
-  // Monotonic attempt number within one runtime recovery sequence; reset once
-  // a transport reopen succeeds so traces can correlate repeated failures.
-  recoveryAttempt = 0;
-  recoveryExhausted = false;
-  /** Monotonic generation incremented on every successful transport open.
-   * Stays in lockstep with `lastSuccessAt` so callers can detect that the
-   * transport has been reopened even if the timestamp window is short. */
-  recoveryGeneration = 0;
-  /** Timestamp of the most recent successful transport open. Null until the
-   * transport has reached the `ready` state at least once. */
-  lastSuccessAt = null;
-  // True while the tab is hidden so an in-flight transport start does not mark
-  // the transport ready after suspendTransport() has stopped it.
-  suspended = false;
-  // Single gate for async transport.stop() cleanup, shared by failed opens and
-  // page-hide suspension. Kept separate from startPromise so ready() still
-  // surfaces a failure while later opens and automatic recovery wait for the
-  // stop to settle.
-  pendingStop = null;
-  // Minimum interval in ms between automatic recovery attempts.
-  recoveryCooldownMs;
-  recoveryMaxAttempts;
-  constructor(options) {
-    const replay = options.replay;
-    if (replay) {
-      const maxPerTopic = replay.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
-      if (!Number.isSafeInteger(maxPerTopic) || maxPerTopic <= 0) {
-        throw new TypeError(
-          `replay.maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`
-        );
-      }
+  trace;
+  onPersistenceError;
+  onDispatchError;
+  /** Bumped on suspend/stop so in-flight persistence retries are cancelled. */
+  retryGeneration = 0;
+  pendingReplayPersistence = [];
+  persistenceFlushScheduled = false;
+  hydration;
+  /** Coalesced retention cleanup: the newest cutoff wins while one is running. */
+  retentionCleanup = null;
+  retentionCutoff = null;
+  retentionTimer = null;
+  /** True when replay buffering is enabled. */
+  get enabled() {
+    return this.buffers !== null;
+  }
+  /** Append a dispatched publication to the topic's replay ring buffer.
+   * No-op when replay is disabled. */
+  record(message) {
+    if (!this.buffers) return;
+    let buffer = this.buffers.get(message.topic);
+    if (!buffer) {
+      buffer = [];
+      this.buffers.set(message.topic, buffer);
+    }
+    buffer.push(message);
+    const pruned = pruneReplayHistory(buffer, {
+      maxPerTopic: this.maxPerTopic,
+      pruneStrategy: this.pruneStrategy,
+      retentionMs: this.retentionMs,
+      now: this.now()
+    });
+    if (pruned !== buffer) {
+      buffer = pruned;
+      this.buffers.set(message.topic, buffer);
+    }
+    if (!this.persistence) return;
+    if (this.persistence.appendBatch) {
+      this.pendingReplayPersistence.push(message);
+      this.schedulePersistenceFlush();
+    } else {
+      void this.withPersistenceRetry(PERSISTENCE_OPERATION.APPEND, () => this.persistence.append(message)).catch((error) => this.onPersistenceError(error));
     }
-    this.replayMaxPerTopic = replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
-    this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
-    this.replayPersistence = replay?.persistence ?? null;
-    this.replayRetentionMs = replay?.retentionMs;
-    this.replayPruneStrategy = replay?.pruneStrategy ?? "count";
-    if (!["count", "age", "both"].includes(this.replayPruneStrategy)) throw new TypeError("replay.pruneStrategy must be count, age, or both.");
-    if (this.replayRetentionMs !== void 0 && (!Number.isFinite(this.replayRetentionMs) || this.replayRetentionMs <= 0)) {
-      throw new TypeError("replay.retentionMs must be a positive finite number.");
+    if (this.retentionMs !== void 0 && this.persistence.clearBefore) {
+      this.scheduleRetentionCleanup(this.now() - this.retentionMs);
     }
-    this.replayRetentionSweepMs = replay?.retentionSweepMs;
-    if (this.replayRetentionSweepMs !== void 0 && (!Number.isFinite(this.replayRetentionSweepMs) || this.replayRetentionSweepMs <= 0)) {
-      throw new TypeError("replay.retentionSweepMs must be a positive finite number.");
+  }
+  /** Deliver buffered history to a newly-registered handler. For an exact
+   * topic this is that topic's ring; for a wildcard subscription every
+   * buffered topic matching the pattern contributes (in buffer insertion
+   * order). Replay deliveries are marked `replayed: true` and are not counted
+   * into trace metrics.
+   *
+   * When a durable persistence backend is present, delivery waits for the
+   * hydration load to settle first; `isHandlerActive` is then consulted so a
+   * handler that unsubscribed during the async load does not receive history.
+   */
+  deliverReplay(topic, replayOption, handler, isHandlerActive) {
+    if (!this.buffers) return;
+    const limit = typeof replayOption === "number" ? Math.min(Math.floor(replayOption), this.maxPerTopic) : this.maxPerTopic;
+    if (this.persistence) {
+      void this.hydration.then(() => {
+        if (isHandlerActive?.() ?? true) this.deliver(topic, limit, handler);
+      });
+      return;
     }
-    this.persistenceRetryMaxAttempts = replay?.persistenceRetry?.maxAttempts ?? 1;
-    this.persistenceRetryBackoffMs = replay?.persistenceRetry?.backoffMs ?? 50;
-    if (!Number.isSafeInteger(this.persistenceRetryMaxAttempts) || this.persistenceRetryMaxAttempts <= 0) {
-      throw new TypeError("replay.persistenceRetry.maxAttempts must be a positive safe integer.");
+    this.deliver(topic, limit, handler);
+  }
+  /** Clean up a topic that lost its last local handler: drop the ring buffer,
+   * filter queued batch flushes (so an in-flight append cannot undo the
+   * clearTopic), and prune durable history. */
+  onTopicUnsubscribed(topic) {
+    if (!this.buffers) return;
+    this.buffers.delete(topic);
+    this.pendingReplayPersistence = this.pendingReplayPersistence.filter((message) => message.topic !== topic);
+    if (this.persistence?.clearTopic) {
+      void this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)).catch((error) => this.onPersistenceError(error));
+    }
+  }
+  /** Clear all in-memory replay buffers and, when supported, durable history.
+   * Reports persistence failures and rethrows, mirroring the public API
+   * contract that callers can observe a failed clear. */
+  async clearAll() {
+    if (!this.buffers) return;
+    this.buffers.clear();
+    this.pendingReplayPersistence = [];
+    if (this.persistence?.clear) {
+      try {
+        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR, () => this.persistence.clear());
+      } catch (error) {
+        this.onPersistenceError(error);
+        throw error;
+      }
     }
-    if (!Number.isFinite(this.persistenceRetryBackoffMs) || this.persistenceRetryBackoffMs < 0) {
-      throw new TypeError("replay.persistenceRetry.backoffMs must be a non-negative finite number.");
+  }
+  /** Clear replay history for one exact topic, including durable storage. */
+  async clearTopic(topic) {
+    if (!this.buffers) return;
+    this.buffers.delete(topic);
+    this.pendingReplayPersistence = this.pendingReplayPersistence.filter((message) => message.topic !== topic);
+    if (this.persistence?.clearTopic) {
+      try {
+        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic));
+      } catch (error) {
+        this.onPersistenceError(error);
+        throw error;
+      }
     }
-    const { autoStart, initialConfig, trace, transport, dedup, recovery, ...clusterOptions } = options;
-    this.recoveryCooldownMs = recovery?.cooldownMs ?? 1e3;
-    this.recoveryMaxAttempts = recovery?.maxAttempts ?? Number.POSITIVE_INFINITY;
-    if (!Number.isFinite(this.recoveryCooldownMs) || this.recoveryCooldownMs <= 0) {
-      throw new TypeError("recovery.cooldownMs must be a positive finite number.");
+  }
+  /** Remove replay entries older than an epoch-millisecond cutoff. */
+  async clearBefore(timestamp) {
+    if (!Number.isFinite(timestamp)) throw new TypeError("timestamp must be finite.");
+    if (this.buffers) {
+      for (const [topic, messages] of this.buffers) {
+        const kept = messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
+        if (kept.length) this.buffers.set(topic, kept);
+        else this.buffers.delete(topic);
+      }
     }
-    if (!(this.recoveryMaxAttempts === Number.POSITIVE_INFINITY || Number.isSafeInteger(this.recoveryMaxAttempts) && this.recoveryMaxAttempts > 0)) {
-      throw new TypeError("recovery.maxAttempts must be a positive safe integer.");
+    this.pendingReplayPersistence = this.pendingReplayPersistence.filter(
+      (message) => message.timestamp === void 0 || message.timestamp >= timestamp
+    );
+    if (this.persistence?.clearBefore) {
+      try {
+        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(timestamp));
+      } catch (error) {
+        this.onPersistenceError(error);
+        throw error;
+      }
     }
-    this.now = dedup?.now ?? Date.now;
-    this.replayHydration = this.hydrateReplay();
-    this.transport = transport;
-    this.initialConfig = initialConfig;
-    this.hasInitialConfig = "initialConfig" in options;
-    this.trace = new DataBusTraceReporter(trace);
-    this.dedupMaxEntries = dedup?.maxEntries ?? 1e3;
-    this.dedupTtlMs = dedup?.ttlMs ?? 6e4;
-    this.dedupAdaptiveBounds = dedup?.adaptiveTtl;
-    if (this.dedupAdaptiveBounds && (this.dedupAdaptiveBounds.minMs <= 0 || this.dedupAdaptiveBounds.maxMs < this.dedupAdaptiveBounds.minMs)) throw new TypeError("dedup.adaptiveTtl bounds are invalid.");
-    this.dedupWindowStartedAt = this.now();
-    this.dedupSweepMs = dedup?.sweepMs;
-    this.dedupEnabled = dedup !== void 0;
-    if (!Number.isSafeInteger(this.dedupMaxEntries) || this.dedupMaxEntries <= 0) {
-      throw new TypeError("dedup.maxEntries must be a positive safe integer.");
-    }
-    if (!Number.isFinite(this.dedupTtlMs) || this.dedupTtlMs <= 0) {
-      throw new TypeError("dedup.ttlMs must be a positive finite number.");
-    }
-    if (this.dedupSweepMs !== void 0 && (!Number.isFinite(this.dedupSweepMs) || this.dedupSweepMs <= 0)) {
-      throw new TypeError("dedup.sweepMs must be a positive finite number.");
+  }
+  /** Start the periodic retention sweep. No-op when no durable retention
+   * config makes it necessary. */
+  start() {
+    if (this.retentionTimer || !this.retentionMs || !this.retentionSweepMs || !this.persistence?.clearBefore) return;
+    this.retentionTimer = setInterval(() => {
+      this.scheduleRetentionCleanup(this.now() - this.retentionMs);
+    }, this.retentionSweepMs);
+  }
+  /** Stop the periodic retention sweep. */
+  stop() {
+    if (this.retentionTimer) clearInterval(this.retentionTimer);
+    this.retentionTimer = null;
+  }
+  /** Suspend the manager: cancel in-flight persistence retries (so a hidden tab
+   * or stopped bus does not keep hammering the store) and stop the sweep. */
+  suspend() {
+    this.retryGeneration += 1;
+    this.stop();
+  }
+  /** Drop all in-memory buffers (used on full teardown). */
+  resetBuffers() {
+    this.buffers?.clear();
+  }
+  /** Buffer occupancy for diagnostics. `bytes` is an approximate in-memory
+   * payload footprint (same heuristic as adaptive load weighting), computed on
+   * demand so the hot append path never pays for it. */
+  getStats() {
+    let messages = 0;
+    let bytes = 0;
+    if (this.buffers) {
+      for (const buffer of this.buffers.values()) {
+        messages += buffer.length;
+        for (const message of buffer) bytes += approximatePayloadBytes(message.data);
+      }
     }
+    return { enabled: this.enabled, topics: this.buffers?.size ?? 0, messages, bytes };
+  }
+  /** Deliver history from one topic's ring to a handler, isolating a throwing
+   * handler so the remaining buffers are still delivered. */
+  deliver(topic, limit, handler) {
+    if (!this.buffers || limit <= 0) return;
+    const deliverBuffer = (buffer2) => {
+      for (const message of buffer2.slice(-limit)) {
+        try {
+          handler({ ...message, replayed: true });
+        } catch (error) {
+          this.onDispatchError(error);
+        }
+      }
+    };
+    if (isWildcardTopic(topic)) {
+      for (const [bufferedTopic, buffer2] of this.buffers) {
+        if (topicMatchesPattern(topic, bufferedTopic)) deliverBuffer(buffer2);
+      }
+      return;
+    }
+    const buffer = this.buffers.get(topic);
+    if (buffer) deliverBuffer(buffer);
+  }
+  /** Coalesce queued persistence appends into a single microtask batch so a
+   * burst of publications does not issue one IndexedDB transaction each.
+   * Only reachable when the backend advertises `appendBatch` (the sole queuer,
+   * `record()`, guards on it), so the batched path is unconditional here. */
+  schedulePersistenceFlush() {
+    if (this.persistenceFlushScheduled) return;
+    this.persistenceFlushScheduled = true;
+    queueMicrotask(() => {
+      this.persistenceFlushScheduled = false;
+      const batch = this.pendingReplayPersistence.splice(0);
+      if (batch.length === 0 || !this.persistence) return;
+      void this.withPersistenceRetry(PERSISTENCE_OPERATION.APPEND, () => this.persistence.appendBatch(batch)).catch((error) => this.onPersistenceError(error));
+    });
+  }
+  /** Load durable history into the in-memory rings once at startup, pruning
+   * entries past the retention window first. Failures are reported but do not
+   * block startup — the bus runs with whatever survived. */
+  async hydrate() {
+    if (!this.buffers || !this.persistence) {
+      return;
+    }
+    try {
+      if (this.retentionMs !== void 0 && this.persistence.clearBefore) {
+        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(this.now() - this.retentionMs));
+      }
+      const loaded = await this.withPersistenceRetry(PERSISTENCE_OPERATION.LOAD, () => this.persistence.load());
+      for (const message of loaded) {
+        let buffer = this.buffers.get(message.topic);
+        if (!buffer) {
+          buffer = [];
+          this.buffers.set(message.topic, buffer);
+        }
+        buffer.push(message);
+      }
+      const hydrationNow = this.now();
+      for (const [topic, buffer] of this.buffers) {
+        const pruned = pruneReplayHistory(buffer, {
+          maxPerTopic: this.maxPerTopic,
+          pruneStrategy: this.pruneStrategy,
+          retentionMs: this.retentionMs,
+          now: hydrationNow
+        });
+        if (pruned !== buffer) this.buffers.set(topic, pruned);
+      }
+    } catch (error) {
+      this.onPersistenceError(error);
+    }
+  }
+  /** Coalesce retention cleanup: the newest cutoff wins while one pass runs,
+   * so a burst of publications issues at most one clearBefore transaction. */
+  scheduleRetentionCleanup(cutoff) {
+    if (!this.persistence?.clearBefore) return;
+    if (this.retentionCutoff === null || cutoff > this.retentionCutoff) {
+      this.retentionCutoff = cutoff;
+    }
+    if (this.retentionCleanup) return;
+    this.retentionCleanup = (async () => {
+      while (this.retentionCutoff !== null) {
+        const nextCutoff = this.retentionCutoff;
+        this.retentionCutoff = null;
+        try {
+          await this.persistence.clearBefore(nextCutoff);
+        } catch (error) {
+          this.onPersistenceError(error);
+        }
+      }
+    })().finally(() => {
+      this.retentionCleanup = null;
+      if (this.retentionCutoff !== null) {
+        this.scheduleRetentionCleanup(this.retentionCutoff);
+      }
+    });
+  }
+  /** Run a persistence operation with exponential backoff on transient failure.
+   * Bumped `retryGeneration` (suspend/stop) cancels the loop early; a
+   * structurally failing operation throws after `persistenceRetryMaxAttempts`,
+   * leaving the ring buffer intact so the bus keeps working. */
+  async withPersistenceRetry(persistenceOperation, operation) {
+    const generation = this.retryGeneration;
+    let attempt = 0;
+    let delay = this.persistenceRetryBackoffMs;
+    while (true) {
+      attempt += 1;
+      try {
+        if (generation !== this.retryGeneration) throw new PersistenceRetryCancelledError();
+        return await operation();
+      } catch (error) {
+        if (error instanceof PersistenceRetryCancelledError || generation !== this.retryGeneration) {
+          throw new PersistenceRetryCancelledError();
+        }
+        if (attempt >= this.persistenceRetryMaxAttempts) throw error;
+        this.trace.event({
+          type: TRACE_EVENT_TYPE.RELIABILITY,
+          operation: RELIABILITY_OPERATION.PERSISTENCE_RETRY,
+          persistenceOperation,
+          attempt
+        });
+        if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+        if (generation !== this.retryGeneration) throw new PersistenceRetryCancelledError();
+        delay = Math.min(delay * 2, MAX_RETRY_DELAY_MS2);
+      }
+    }
+  }
+};
+
+// src/core/dedup-manager.ts
+var ADAPTIVE_WINDOW_MS = 5e3;
+var QUIET_RATE_PER_MS = 0.01;
+var DedupManager = class {
+  enabled;
+  maxEntries;
+  ttlMs;
+  adaptiveBounds;
+  sweepMs;
+  now;
+  trace;
+  seenMessageIds = /* @__PURE__ */ new Map();
+  sweepTimer = null;
+  windowStartedAt = 0;
+  windowAccepted = 0;
+  suppressed = 0;
+  accepted = 0;
+  constructor(options) {
+    this.enabled = options.enabled;
+    this.maxEntries = options.maxEntries;
+    this.ttlMs = options.ttlMs;
+    this.adaptiveBounds = options.adaptiveBounds;
+    this.sweepMs = options.sweepMs;
+    this.now = options.now;
+    this.trace = options.trace;
+    this.windowStartedAt = this.now();
+  }
+  /** 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 ttlMs = this.currentTtl();
+    for (const [id, timestamp] of this.seenMessageIds) {
+      if (now - timestamp > ttlMs) this.seenMessageIds.delete(id);
+    }
+    if (this.seenMessageIds.has(messageId)) {
+      this.suppressed += 1;
+      this.trace.event({
+        type: TRACE_EVENT_TYPE.RELIABILITY,
+        operation: RELIABILITY_OPERATION.DEDUP_SUPPRESSED,
+        topic
+      });
+      this.trace.recordDedupSuppressed();
+      return true;
+    }
+    this.seenMessageIds.set(messageId, now);
+    this.accepted += 1;
+    this.windowAccepted += 1;
+    this.trace.recordDedupAccepted();
+    while (this.seenMessageIds.size > this.maxEntries) {
+      const oldest = this.seenMessageIds.keys().next().value;
+      if (oldest === void 0) break;
+      this.seenMessageIds.delete(oldest);
+    }
+    return false;
+  }
+  /** Start the periodic expiry sweep. No-op when disabled or no sweepMs was
+   * configured (the hot-path opportunistic expiry still bounds the map). */
+  start() {
+    if (this.sweepTimer || !this.enabled || !this.sweepMs) return;
+    this.sweepTimer = setInterval(() => this.pruneExpired(), this.sweepMs);
+  }
+  /** Stop the periodic expiry sweep. */
+  stop() {
+    if (this.sweepTimer) clearInterval(this.sweepTimer);
+    this.sweepTimer = null;
+  }
+  /** Return bounded deduplication counters for diagnostics and health checks. */
+  getStats() {
+    return {
+      enabled: this.enabled,
+      tracked: this.seenMessageIds.size,
+      suppressed: this.suppressed,
+      accepted: this.accepted,
+      ...this.adaptiveBounds ? { ttlMs: this.currentTtl() } : {}
+    };
+  }
+  /** Drop all remembered IDs and reset dedup counters. */
+  reset() {
+    this.seenMessageIds.clear();
+    this.suppressed = 0;
+    this.accepted = 0;
+    this.windowStartedAt = this.now();
+    this.windowAccepted = 0;
+  }
+  /** Remove IDs whose timestamp predates the effective TTL cutoff. */
+  pruneExpired() {
+    const cutoff = this.now() - this.currentTtl();
+    for (const [id, timestamp] of this.seenMessageIds) {
+      if (timestamp < cutoff) this.seenMessageIds.delete(id);
+    }
+  }
+  /** Effective TTL: the fixed `ttlMs` unless adaptive bounds are configured, in
+   * which case a higher recent message rate shortens the window (dedup only
+   * needs to live long enough to bridge duplicate bursts). The window resets
+   * every ADAPTIVE_WINDOW_MS. */
+  currentTtl() {
+    if (!this.adaptiveBounds) return this.ttlMs;
+    const now = this.now();
+    const elapsed = now - this.windowStartedAt;
+    if (elapsed >= ADAPTIVE_WINDOW_MS) {
+      this.windowStartedAt = now;
+      this.windowAccepted = 0;
+      return this.adaptiveBounds.maxMs;
+    }
+    const rate = this.windowAccepted / Math.max(1, elapsed);
+    const factor = Math.min(1, rate / QUIET_RATE_PER_MS);
+    return this.adaptiveBounds.maxMs - (this.adaptiveBounds.maxMs - this.adaptiveBounds.minMs) * factor;
+  }
+};
+
+// src/core/version.ts
+var SDK_VERSION = true ? "0.20.86" : "";
+
+// src/core/data-bus.ts
+var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
+var CrossTabDataBus = class {
+  transport;
+  cluster;
+  // Map of topic → set of local subscribers.
+  topicHandlers = /* @__PURE__ */ new Map();
+  // Topics for which the transport has been asked to subscribe (used to avoid
+  // duplicate subscribe calls during reconnection).
+  transportSubscribedTopics = /* @__PURE__ */ new Set();
+  statusHandlers = /* @__PURE__ */ new Set();
+  errorHandlers = /* @__PURE__ */ new Set();
+  replayManager;
+  initialConfig;
+  hasInitialConfig;
+  trace;
+  dedupManager;
+  now;
+  activeConfig;
+  status = WORKER_STATUS.DISCONNECTED;
+  started = false;
+  stopping = false;
+  transportReady = false;
+  // Last transport failure, retained so ready() can surface it to callers who
+  // never awaited start() directly. Cleared on the next successful start.
+  lastError = null;
+  lastErrorAt = null;
+  // Unified failure ledger for the health summary: the most recent failure of
+  // any source (transport, persistence, dispatch) since the last explicit start.
+  lastFailure = null;
+  persistenceFailureCount = 0;
+  persistenceLastFailureAt = null;
+  persistenceLastErrorMessage = null;
+  // Gate that serialises start/stop/suspend/resume — only one lifecycle
+  // transition at a time. Resets to null once the operation settles.
+  startPromise = null;
+  // Gate for an explicit stop(). Concurrent stop() calls share it, and a
+  // start() received while stopping chains a fresh start after it.
+  stopPromise = null;
+  // A start() requested while an explicit stop() is still settling. Kept
+  // separate from startPromise because stop()'s finally block clears the
+  // ordinary lifecycle gate before the queued start is allowed to run.
+  queuedStart = null;
+  // Lazy readiness view of queuedStart. start() keeps its documented
+  // resolve-on-cancellation contract, while ready() must reject when the
+  // queued intent was superseded by a later stop().
+  queuedStartReady = null;
+  queuedStartReadyToken = 0;
+  // The queued continuation is chained to the stop promise and cannot be
+  // un-scheduled once scheduled. A later stop() therefore invalidates the
+  // current intent by recording its token; a subsequent start() issues a
+  // higher token so the latest lifecycle request still wins.
+  queuedStartToken = 0;
+  canceledQueuedStartToken = 0;
+  // Timestamp of the last automatic transport recovery attempt.
+  // Used to avoid a tight retry loop when the transport fails repeatedly.
+  lastRecoveryAt = 0;
+  // Monotonic attempt number within one runtime recovery sequence; reset once
+  // a transport reopen succeeds so traces can correlate repeated failures.
+  recoveryAttempt = 0;
+  recoveryExhausted = false;
+  /** Monotonic generation incremented on every successful transport open.
+   * Stays in lockstep with `lastSuccessAt` so callers can detect that the
+   * transport has been reopened even if the timestamp window is short. */
+  recoveryGeneration = 0;
+  /** Timestamp of the most recent successful transport open. Null until the
+   * transport has reached the `ready` state at least once. */
+  lastSuccessAt = null;
+  // True while the tab is hidden so an in-flight transport start does not mark
+  // the transport ready after suspendTransport() has stopped it.
+  suspended = false;
+  // Single gate for async transport.stop() cleanup, shared by failed opens and
+  // page-hide suspension. Kept separate from startPromise so ready() still
+  // surfaces a failure while later opens and automatic recovery wait for the
+  // stop to settle.
+  pendingStop = null;
+  // Ownership token for asynchronous transport opens. Every lifecycle
+  // transition invalidates callbacks and failure cleanup from older opens.
+  lifecycleEpoch = 0;
+  // Minimum interval in ms between automatic recovery attempts.
+  recoveryCooldownMs;
+  recoveryMaxAttempts;
+  constructor(options) {
+    const replay = options.replay;
+    assertReplayOptions(replay);
+    const { autoStart, initialConfig, trace, transport, dedup, recovery, ...clusterOptions } = options;
+    assertRecoveryOptions(recovery);
+    this.recoveryCooldownMs = recovery?.cooldownMs ?? 1e3;
+    this.recoveryMaxAttempts = recovery?.maxAttempts ?? Number.POSITIVE_INFINITY;
+    this.now = dedup?.now ?? Date.now;
+    this.transport = transport;
+    this.initialConfig = initialConfig;
+    this.hasInitialConfig = "initialConfig" in options;
+    this.trace = new DataBusTraceReporter(trace);
+    this.replayManager = new ReplayManager({
+      enabled: replay !== void 0,
+      maxPerTopic: replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC,
+      persistence: replay?.persistence ?? null,
+      retentionMs: replay?.retentionMs,
+      pruneStrategy: replay?.pruneStrategy ?? PRUNE_STRATEGY.COUNT,
+      retentionSweepMs: replay?.retentionSweepMs,
+      persistenceRetryMaxAttempts: replay?.persistenceRetry?.maxAttempts ?? 1,
+      persistenceRetryBackoffMs: replay?.persistenceRetry?.backoffMs ?? 50,
+      now: this.now,
+      trace: this.trace,
+      onPersistenceError: (error) => this.reportPersistenceError(error),
+      onDispatchError: (error) => this.reportError(error, FAILURE_SOURCE.DISPATCH)
+    });
+    assertDedupOptions(dedup);
+    this.dedupManager = new DedupManager({
+      enabled: dedup !== void 0,
+      maxEntries: dedup?.maxEntries ?? 1e3,
+      ttlMs: dedup?.ttlMs ?? 6e4,
+      adaptiveBounds: dedup?.adaptiveTtl,
+      sweepMs: dedup?.sweepMs,
+      now: this.now,
+      trace: this.trace
+    });
     this.cluster = new WorkerClusterRuntime({
       ...clusterOptions,
       handlers: {
@@ -1547,26 +2458,36 @@ var CrossTabDataBus = class {
         // control message — meaning the owning Worker has delegated the action to us.
         onControl: (action, topic, data, messageId, timestamp) => {
           switch (action) {
-            case "SUBSCRIBE":
-              if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
+            case CONTROL_ACTION.SUBSCRIBE:
+              if (this.subscribeTransport(topic)) this.traceSubscription(SUBSCRIPTION_ACTION.SUBSCRIBE, topic);
               break;
-            case "UNSUBSCRIBE":
-              if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
+            case CONTROL_ACTION.UNSUBSCRIBE:
+              if (this.unsubscribeTransport(topic)) this.traceSubscription(SUBSCRIPTION_ACTION.UNSUBSCRIBE, topic);
               break;
-            case "PUBLISH":
-              this.runTransport(() => this.transport.publish(
-                topic,
-                data,
-                messageId === void 0 && timestamp === void 0 ? void 0 : {
-                  ...messageId === void 0 ? {} : { messageId },
-                  ...timestamp === void 0 ? {} : { timestamp }
-                }
-              ));
+            case CONTROL_ACTION.PUBLISH:
+              this.runTransport(() => this.transport.publish(topic, data, publicationMetadata(messageId, timestamp)));
               break;
             default:
               break;
           }
         },
+        // Batched variant of the PUBLISH action (CONTROL frames carrying
+        // multiple items, and the local publishBatch fast path). Uses the
+        // transport's one-frame publishBatch when available, preserving
+        // per-item metadata; otherwise falls back to per-item publishes.
+        onPublishBatch: (topic, items) => {
+          if (typeof this.transport.publishBatch === "function") {
+            this.runTransport(() => this.transport.publishBatch(topic, items));
+            return;
+          }
+          for (const item of items) {
+            this.runTransport(() => this.transport.publish(
+              topic,
+              item.data,
+              publicationMetadata(item.messageId, item.timestamp)
+            ));
+          }
+        },
         // The cluster calls `onEvent` when a publication broadcast arrives from
         // another tab. Dispatch locally if we have subscribers. The payload is
         // typed `unknown` at the cluster boundary (the cluster is transport-
@@ -1579,22 +2500,21 @@ var CrossTabDataBus = class {
           if (this.cluster.hasLocalSubscriber(message.topic)) this.dispatch(message);
         },
         onSuspend: () => {
-          if (!this.stopping) this.trace.event({ type: "lifecycle", action: "suspend" });
+          if (!this.stopping) this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.SUSPEND });
           this.trace.pause();
-          this.persistenceRetryGeneration += 1;
+          this.replayManager.suspend();
           this.stopDedupSweep();
-          this.stopReplayRetentionSweep();
           this.suspendTransport();
         },
         onResume: () => {
-          this.trace.event({ type: "lifecycle", action: "resume" });
+          this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.RESUME });
           this.trace.start();
           this.startDedupSweep();
-          this.startReplayRetentionSweep();
+          this.replayManager.start();
           this.resumeTransport();
         },
         onDiagnostic: (event) => {
-          this.trace.event({ type: "reliability", ...event });
+          this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, ...event });
         }
       }
     });
@@ -1604,40 +2524,51 @@ var CrossTabDataBus = class {
    * Start the DataBus with the given transport config.
    *
    * The first call starts the cluster and opens the transport. Concurrent calls
-   * during an in-flight start return the same promise. Once the operation
-   * settles (success or failure) the promise gate is cleared so a subsequent
-   * start() or resumeTransport() can open a fresh lifecycle.
+   * during an in-flight open return the same promise. A call received while an
+   * explicit stop() is settling queues one fresh start after cleanup; a later
+   * stop() before that queued start runs cancels it, so the latest lifecycle
+   * intent wins. Once an operation settles (success or failure) its promise
+   * gate is cleared so a subsequent start() or resumeTransport() can open a
+   * fresh lifecycle.
    */
   start(config) {
-    if (this.startPromise) return this.startPromise;
-    if (this.started) return Promise.resolve();
+    if (this.queuedStart) return this.queuedStart;
+    if (this.stopping) return this.queueStartAfterStop(config);
+    if (this.startPromise && this.startPromise !== this.pendingStop) return this.startPromise;
+    if (this.started) {
+      const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+      if (!transportDown) return Promise.resolve();
+      this.activeConfig = config;
+      this.resetFailureState();
+      return this.reopenTransport();
+    }
     this.started = true;
     this.stopping = false;
     this.suspended = false;
     this.activeConfig = config;
-    this.lastError = null;
-    this.trace.event({ type: "lifecycle", action: "start" });
+    this.resetFailureState();
+    this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.START });
     this.trace.start();
     this.startDedupSweep();
-    this.startReplayRetentionSweep();
-    this.updateStatus("connecting");
+    this.replayManager.start();
+    this.updateStatus(WORKER_STATUS.CONNECTING);
     this.cluster.start();
-    const opening = this.openTransport(config, this.pendingStop ?? Promise.resolve(), true);
+    const lifecycleEpoch = ++this.lifecycleEpoch;
+    const opening = this.openTransport(
+      config,
+      this.pendingStop ?? Promise.resolve(),
+      true,
+      lifecycleEpoch
+    );
     this.startPromise = opening;
     for (const topic of this.topicHandlers.keys()) {
       this.cluster.subscribe(topic);
     }
-    const snapshot = this.cluster.getSnapshot();
-    this.trace.event({
-      type: "coordination",
-      coordinated: snapshot.coordinated,
-      activeWorkers: snapshot.workers.filter((worker) => worker.role === "active").length,
-      workers: snapshot.workers.map(formatWorkerTrace),
-      routes: snapshot.routes.map(formatRouteTrace)
-    });
     void opening.then(
       () => {
-        if (this.startPromise === opening) this.startPromise = null;
+        if (this.startPromise !== opening) return;
+        this.emitCoordinationTrace();
+        this.startPromise = null;
       },
       () => {
         if (this.startPromise === opening) this.startPromise = null;
@@ -1645,25 +2576,81 @@ var CrossTabDataBus = class {
     );
     return opening;
   }
+  /** Return a cancellation-aware readiness view of the current queued start. */
+  getQueuedStartReady() {
+    const queued = this.queuedStart;
+    if (!queued) {
+      return Promise.reject(new Error("No queued start is in flight."));
+    }
+    const token = this.queuedStartToken;
+    if (this.queuedStartReady && this.queuedStartReadyToken === token) {
+      return this.queuedStartReady;
+    }
+    this.queuedStartReadyToken = token;
+    this.queuedStartReady = queued.then(() => {
+      if (token <= this.canceledQueuedStartToken) {
+        throw new Error(
+          "CrossTabDataBus start was canceled by a later stop(); ready() cannot report readiness. Call start() again after stop() resolves."
+        );
+      }
+      if (!this.started || !this.transportReady) {
+        throw new Error("CrossTabDataBus restart completed without a ready transport.");
+      }
+    });
+    return this.queuedStartReady;
+  }
+  /** Queue exactly one fresh start after an in-flight explicit stop settles. */
+  queueStartAfterStop(config) {
+    if (this.queuedStart) return this.queuedStart;
+    const stop = this.stopPromise ?? Promise.resolve();
+    const token = ++this.queuedStartToken;
+    const queued = stop.catch(() => void 0).then(() => {
+      if (this.queuedStart === queued) this.queuedStart = null;
+      if (token <= this.canceledQueuedStartToken) return;
+      return this.start(config);
+    });
+    this.queuedStart = queued;
+    return queued;
+  }
+  /** Reset failure and recovery diagnostics for a new explicit start session. */
+  resetFailureState() {
+    this.lastError = null;
+    this.lastErrorAt = null;
+    this.lastFailure = null;
+    this.persistenceFailureCount = 0;
+    this.persistenceLastFailureAt = null;
+    this.persistenceLastErrorMessage = null;
+    this.recoveryAttempt = 0;
+    this.recoveryExhausted = false;
+    this.lastRecoveryAt = 0;
+  }
   /**
    * Open the transport, chained after `before` to ensure lifecycle ordering.
    * When `stopClusterOnFailure` is true (initial start), a transport failure
    * tears down the cluster as well.
    */
-  openTransport(config, before, stopClusterOnFailure) {
+  openTransport(config, before, stopClusterOnFailure, lifecycleEpoch) {
     this.transportReady = false;
     const chainedPendingStop = this.pendingStop;
+    const isCurrentLifecycle = () => lifecycleEpoch === this.lifecycleEpoch;
     return before.catch(() => void 0).then(() => {
-      if (this.stopping || this.suspended) return;
+      if (!isCurrentLifecycle() || this.stopping || this.suspended) return;
       if (this.pendingStop === chainedPendingStop) this.pendingStop = null;
       return Promise.resolve(
         this.transport.start(config, {
-          onMessage: (message) => this.handleTransportMessage(message),
-          onStatus: (status) => this.updateStatus(status),
-          onError: (error) => this.reportError(error)
+          onMessage: (message) => {
+            if (isCurrentLifecycle()) this.handleTransportMessage(message);
+          },
+          onStatus: (status) => {
+            if (isCurrentLifecycle()) this.updateStatus(status);
+          },
+          onError: (error) => {
+            if (isCurrentLifecycle()) this.reportError(error);
+          }
         })
       ).then(() => {
-        if (this.status === "error") {
+        if (!isCurrentLifecycle()) return;
+        if (this.status === WORKER_STATUS.ERROR) {
           throw new Error("Transport failed during startup.");
         }
         if (!this.suspended && !this.stopping) {
@@ -1673,11 +2660,12 @@ var CrossTabDataBus = class {
         }
       });
     }).catch((error) => {
+      if (!isCurrentLifecycle()) throw error;
       if (stopClusterOnFailure) this.started = false;
       if (!this.pendingStop) {
         this.pendingStop = this.createStopPromise();
       }
-      this.updateStatus("error");
+      this.updateStatus(WORKER_STATUS.ERROR);
       this.reportError(error);
       this.lastError = error;
       this.lastErrorAt = this.now();
@@ -1687,16 +2675,26 @@ var CrossTabDataBus = class {
         this.cluster.stop();
         this.stopping = false;
       }
-      this.startPromise = null;
       throw error;
     });
   }
   /**
    * Await the DataBus to be fully started (lazy init when using initialConfig).
    * Returns a rejected promise when the transport has failed and no start is in
-   * flight — the caller can retry by calling start() or ready() again.
+   * flight — the caller can retry by calling start() or ready() again. While an
+   * explicit stop() is settling, this rejects unless a restart is queued behind
+   * it; false readiness during teardown is never reported.
    */
   ready() {
+    if (this.queuedStart) return this.getQueuedStartReady();
+    if (this.stopping) {
+      return Promise.reject(new Error(
+        "CrossTabDataBus is stopping; ready() cannot report readiness until stop() resolves. Wait for stop() to resolve, then call start() before awaiting ready()."
+      ));
+    }
+    if (!this.started && !this.hasInitialConfig && this.lastError !== null) {
+      return Promise.reject(this.lastError);
+    }
     try {
       this.ensureStarted();
     } catch (error) {
@@ -1712,9 +2710,18 @@ var CrossTabDataBus = class {
   /**
    * Register a handler for `topic`. The handler fires on every publication
    * delivered to this tab, regardless of which tab published it. Returns an
-   * unsubscribe function for convenience.
+   * unsubscribe function for convenience. During an explicit stop() the
+   * registration is rejected through onError and a no-op cleanup is returned,
+   * so a late subscriber cannot leak into a future restart.
    */
   subscribe(topic, handler, options) {
+    if (this.stopping) {
+      this.reportError(new Error(
+        "CrossTabDataBus is stopping; subscribe() was not registered. Wait for stop() to resolve, then call start() before subscribing again."
+      ));
+      return () => {
+      };
+    }
     this.ensureStarted();
     const handlers = this.topicHandlers.get(topic) ?? /* @__PURE__ */ new Set();
     const wasUnused = handlers.size === 0;
@@ -1722,17 +2729,12 @@ var CrossTabDataBus = class {
     this.topicHandlers.set(topic, handlers);
     if (wasUnused) this.cluster.subscribe(topic);
     if (options?.replay) {
-      const limit = Math.min(
-        typeof options.replay === "number" ? Math.floor(options.replay) : this.replayMaxPerTopic,
-        this.replayMaxPerTopic
+      this.replayManager.deliverReplay(
+        topic,
+        options.replay,
+        handler,
+        () => Boolean(this.topicHandlers.get(topic)?.has(handler))
       );
-      if (this.replayPersistence) {
-        void this.replayHydration.then(() => {
-          if (this.topicHandlers.get(topic)?.has(handler)) this.deliverReplay(topic, limit, handler);
-        });
-      } else {
-        this.deliverReplay(topic, limit, handler);
-      }
     }
     return () => this.unsubscribe(topic, handler);
   }
@@ -1747,74 +2749,33 @@ var CrossTabDataBus = class {
     else handlers.clear();
     if (handlers.size > 0) return;
     this.topicHandlers.delete(topic);
-    this.replayBuffers?.delete(topic);
-    if (this.replayPersistence?.clearTopic) {
-      void this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic)).catch((error) => this.reportPersistenceError(error));
-    }
+    this.replayManager.onTopicUnsubscribed(topic);
     this.cluster.unsubscribe(topic);
   }
   /** Clear all in-memory replay buffers and, when supported, durable history. */
   async clearReplay() {
-    this.replayBuffers?.clear();
-    if (this.replayPersistence?.clear) {
-      try {
-        await this.withPersistenceRetry("clear", () => this.replayPersistence.clear());
-      } catch (error) {
-        this.reportPersistenceError(error);
-        throw error;
-      }
-    }
+    await this.replayManager.clearAll();
   }
   /** Clear replay history for one exact topic, including durable storage. */
   async clearReplayTopic(topic) {
-    this.replayBuffers?.delete(topic);
-    if (this.replayPersistence?.clearTopic) {
-      try {
-        await this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic));
-      } catch (error) {
-        this.reportPersistenceError(error);
-        throw error;
-      }
-    }
+    await this.replayManager.clearTopic(topic);
   }
   /** Remove replay entries older than an epoch-millisecond cutoff. */
   async clearReplayBefore(timestamp) {
-    if (!Number.isFinite(timestamp)) throw new TypeError("timestamp must be finite.");
-    if (this.replayBuffers) {
-      for (const [topic, messages] of this.replayBuffers) {
-        const kept = messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
-        if (kept.length) this.replayBuffers.set(topic, kept);
-        else this.replayBuffers.delete(topic);
-      }
-    }
-    if (this.replayPersistence?.clearBefore) {
-      try {
-        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(timestamp));
-      } catch (error) {
-        this.reportPersistenceError(error);
-        throw error;
-      }
-    }
+    await this.replayManager.clearBefore(timestamp);
   }
   /** Return bounded deduplication counters for diagnostics and health checks. */
   getDedupStats() {
-    return {
-      enabled: this.dedupEnabled,
-      tracked: this.seenMessageIds.size,
-      suppressed: this.dedupSuppressed,
-      accepted: this.dedupAccepted,
-      ...this.dedupAdaptiveBounds ? { ttlMs: this.currentDedupTtl() } : {}
-    };
+    return this.dedupManager.getStats();
   }
   /** Drop all remembered IDs and reset dedup counters. */
   resetDedup() {
-    this.seenMessageIds.clear();
-    this.dedupSuppressed = 0;
-    this.dedupAccepted = 0;
+    this.dedupManager.reset();
   }
   /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
   publish(topic, data, options) {
     this.ensureStarted();
+    if (this.rejectPublishDuringStop("publish")) return;
     if (!this.cluster.publish(topic, data, options)) {
       this.reportError(
         new Error("Failed to send the publish control message to the owning worker.")
@@ -1831,6 +2792,7 @@ var CrossTabDataBus = class {
   publishBatch(topic, items) {
     this.ensureStarted();
     if (items.length === 0) return;
+    if (this.rejectPublishDuringStop("publishBatch")) return;
     if (items.length === 1) {
       const first = items[0];
       this.publish(topic, first.data, first.options);
@@ -1838,8 +2800,7 @@ var CrossTabDataBus = class {
     }
     const mapped = items.map((item) => ({
       data: item.data,
-      ...item.options?.messageId !== void 0 ? { messageId: item.options.messageId } : {},
-      ...item.options?.timestamp !== void 0 ? { timestamp: item.options.timestamp } : {}
+      ...publicationMetadata(item.options?.messageId, item.options?.timestamp)
     }));
     if (!this.cluster.publishBatch(topic, mapped)) {
       this.reportError(
@@ -1884,6 +2845,41 @@ var CrossTabDataBus = class {
       lastSuccessAt: this.lastSuccessAt
     };
   }
+  /** Bounded failure counters for the replay persistence backend. */
+  getPersistenceStats() {
+    return {
+      failures: this.persistenceFailureCount,
+      lastFailureAt: this.persistenceLastFailureAt,
+      lastErrorMessage: this.persistenceLastErrorMessage
+    };
+  }
+  /** Compact health verdict for dashboards, readiness probes, and support
+   * bundles. Answers "is the bus usable right now" first, then attaches the
+   * unified failure ledger and recovery context that explains the verdict. */
+  getHealthSummary() {
+    const transport = this.transport;
+    const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+    const state = !this.started ? HEALTH_STATE.STOPPED : this.suspended ? HEALTH_STATE.SUSPENDED : transportDown ? this.recoveryExhausted ? HEALTH_STATE.DEGRADED : this.status === WORKER_STATUS.CONNECTING && this.recoveryAttempt === 0 ? HEALTH_STATE.STARTING : HEALTH_STATE.RECOVERING : HEALTH_STATE.HEALTHY;
+    return {
+      healthy: state === HEALTH_STATE.HEALTHY,
+      state,
+      status: this.status,
+      sdkVersion: SDK_VERSION,
+      started: this.started,
+      suspended: this.suspended,
+      transport: {
+        name: transport.diagnosticsName ?? transport.constructor.name,
+        backend: transport.diagnosticsBackend ?? null,
+        ready: this.transportReady,
+        status: this.status
+      },
+      recovery: this.getRecoveryStats(),
+      lastFailure: this.lastFailure,
+      persistence: this.getPersistenceStats(),
+      metrics: this.trace.getMetrics(),
+      trace: this.trace.getSinkState()
+    };
+  }
   /** 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. */
@@ -1892,8 +2888,7 @@ var CrossTabDataBus = class {
   }
   /** Return a single health snapshot combining lifecycle, recovery, dedup, replay, and cluster state. */
   getDiagnostics() {
-    let messages = 0;
-    if (this.replayBuffers) for (const buffer of this.replayBuffers.values()) messages += buffer.length;
+    const replay = this.replayManager.getStats();
     const cluster = this.cluster.getSnapshot();
     const unknownMessages = this.cluster.getUnknownMessageStats();
     const transport = this.transport;
@@ -1904,26 +2899,62 @@ var CrossTabDataBus = class {
       transportReady: this.transportReady,
       recovery: this.getRecoveryStats(),
       dedup: this.getDedupStats(),
-      replay: { enabled: Boolean(this.replayBuffers), topics: this.replayBuffers?.size ?? 0, messages },
+      replay: { enabled: replay.enabled, topics: replay.topics, messages: replay.messages, bytes: replay.bytes },
+      persistence: this.getPersistenceStats(),
       protocol: { version: cluster.protocolVersion, unknownMessages: unknownMessages.count, lastUnknownMessageType: unknownMessages.lastType, peers: cluster.peerProtocolVersions },
-      transport: { name: transport.diagnosticsName ?? transport.constructor.name, backend: transport.diagnosticsBackend ?? null },
-      cluster
+      transport: {
+        name: transport.diagnosticsName ?? transport.constructor.name,
+        backend: transport.diagnosticsBackend ?? null,
+        status: this.status,
+        suspended: this.suspended
+      },
+      cluster,
+      metrics: this.trace.getMetrics(),
+      trace: this.trace.getSinkState()
     };
   }
+  /** Synchronous snapshot of the current trace metrics window (throughput,
+   * dispatch latency, dedup outcomes), without flushing or resetting it.
+   * Returns null when trace metrics are inactive (disabled or events-only). */
+  getMetrics() {
+    return this.trace.getMetrics();
+  }
   /**
    * Gracefully stop the DataBus: unsubscribe all topics, stop the cluster,
-   * and close the transport. Idempotent.
+   * and close the transport. Concurrent and repeated calls share the in-flight
+   * stop promise. A start() received while stopping runs after this completes,
+   * unless another stop() arrives first and cancels that queued restart.
    */
-  async stop() {
-    if (!this.started) return;
+  stop() {
+    if (this.queuedStart) {
+      this.canceledQueuedStartToken = this.queuedStartToken;
+      this.queuedStart = null;
+    }
+    if (this.stopPromise) return this.stopPromise;
+    if (!this.started && !this.startPromise && !this.pendingStop && !this.transportReady) {
+      return Promise.resolve();
+    }
+    const stopPromise = this.performStop();
+    this.stopPromise = stopPromise;
+    void stopPromise.then(
+      () => {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      },
+      () => {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      }
+    );
+    return stopPromise;
+  }
+  async performStop() {
+    this.lifecycleEpoch += 1;
     this.stopping = true;
-    this.persistenceRetryGeneration += 1;
-    this.trace.event({ type: "lifecycle", action: "stop" });
+    this.replayManager.suspend();
+    this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.STOP });
     this.trace.stop();
     this.stopDedupSweep();
-    this.stopReplayRetentionSweep();
     this.topicHandlers.clear();
-    this.replayBuffers?.clear();
+    this.replayManager.resetBuffers();
     this.cluster.stop();
     try {
       await this.startPromise?.catch(() => void 0);
@@ -1944,7 +2975,7 @@ var CrossTabDataBus = class {
       this.activeConfig = void 0;
       this.recoveryAttempt = 0;
       this.recoveryExhausted = false;
-      this.updateStatus("disconnected");
+      this.updateStatus(WORKER_STATUS.DISCONNECTED);
     }
   }
   /**
@@ -1953,7 +2984,7 @@ var CrossTabDataBus = class {
    * and dispatches locally.
    */
   handleTransportMessage(message) {
-    if (this.isDuplicate(message)) return;
+    if (this.dedupManager.isDuplicate(message.messageId ?? "", message.topic)) return;
     this.trace.recordReceived(message.topic);
     if (!this.cluster.isAssigned(message.topic)) {
       this.trace.recordDiscarded(message.topic);
@@ -1967,55 +2998,13 @@ var CrossTabDataBus = class {
     }
     this.trace.recordDiscarded(message.topic);
   }
-  isDuplicate(message) {
-    if (!this.dedupEnabled || !message.messageId) return false;
-    const now = this.now();
-    for (const [id, timestamp] of this.seenMessageIds) {
-      if (now - timestamp > this.dedupTtlMs) this.seenMessageIds.delete(id);
-    }
-    if (this.seenMessageIds.has(message.messageId)) {
-      this.trace.event({ type: "reliability", operation: "dedup_suppressed", topic: message.topic });
-      this.dedupSuppressed += 1;
-      this.trace.recordDedupSuppressed();
-      return true;
-    }
-    this.seenMessageIds.set(message.messageId, now);
-    this.dedupAccepted += 1;
-    this.dedupWindowAccepted += 1;
-    this.trace.recordDedupAccepted();
-    while (this.seenMessageIds.size > this.dedupMaxEntries) {
-      const oldest = this.seenMessageIds.keys().next().value;
-      if (oldest === void 0) break;
-      this.seenMessageIds.delete(oldest);
-    }
-    return false;
-  }
+  /** Start enqueuing the dedup expiry sweep (delegated to {@link DedupManager}). */
   startDedupSweep() {
-    if (this.dedupSweepTimer || !this.dedupEnabled || !this.dedupSweepMs) return;
-    this.dedupSweepTimer = setInterval(() => this.pruneExpiredDedup(), this.dedupSweepMs);
+    this.dedupManager.start();
   }
+  /** Stop enqueuing the dedup expiry sweep. */
   stopDedupSweep() {
-    if (this.dedupSweepTimer) clearInterval(this.dedupSweepTimer);
-    this.dedupSweepTimer = null;
-  }
-  pruneExpiredDedup() {
-    const cutoff = this.now() - this.currentDedupTtl();
-    for (const [id, timestamp] of this.seenMessageIds) {
-      if (timestamp < cutoff) this.seenMessageIds.delete(id);
-    }
-  }
-  currentDedupTtl() {
-    if (!this.dedupAdaptiveBounds) return this.dedupTtlMs;
-    const now = this.now();
-    const elapsed = now - this.dedupWindowStartedAt;
-    if (elapsed >= this.dedupAdaptiveWindowMs) {
-      this.dedupWindowStartedAt = now;
-      this.dedupWindowAccepted = 0;
-      return this.dedupAdaptiveBounds.maxMs;
-    }
-    const rate = this.dedupWindowAccepted / Math.max(1, elapsed);
-    const factor = Math.min(1, rate / 0.01);
-    return this.dedupAdaptiveBounds.maxMs - (this.dedupAdaptiveBounds.maxMs - this.dedupAdaptiveBounds.minMs) * factor;
+    this.dedupManager.stop();
   }
   /** Deliver a message to every local handler registered for its topic,
    * plus every handler registered with a wildcard subscription that matches
@@ -2028,153 +3017,7 @@ var CrossTabDataBus = class {
         this.invokeHandlers(handlers, (handler) => handler(message));
       }
     }
-    this.recordReplay(message);
-  }
-  /** Append a dispatched publication to the topic's replay ring buffer.
-   * No-op when replay is disabled. */
-  recordReplay(message) {
-    if (!this.replayBuffers) return;
-    let buffer = this.replayBuffers.get(message.topic);
-    if (!buffer) {
-      buffer = [];
-      this.replayBuffers.set(message.topic, buffer);
-    }
-    const storedMessage = message;
-    buffer.push(storedMessage);
-    if (this.replayPruneStrategy !== "age") {
-      while (buffer.length > this.replayMaxPerTopic) buffer.shift();
-    }
-    if (this.replayPruneStrategy !== "count" && this.replayRetentionMs !== void 0) {
-      const cutoff = this.now() - this.replayRetentionMs;
-      while (buffer.length > 0) {
-        const first = buffer[0];
-        if (!first || first.timestamp === void 0 || first.timestamp >= cutoff) break;
-        buffer.shift();
-      }
-    }
-    if (this.replayPersistence) {
-      if (this.replayPersistence.appendBatch) {
-        this.pendingReplayPersistence.push(storedMessage);
-        this.scheduleReplayPersistenceFlush();
-      } else {
-        void this.withPersistenceRetry("append", () => this.replayPersistence.append(storedMessage)).catch((error) => this.reportPersistenceError(error));
-      }
-      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
-        this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
-      }
-    }
-  }
-  scheduleReplayPersistenceFlush() {
-    if (this.replayPersistenceFlushScheduled) return;
-    this.replayPersistenceFlushScheduled = true;
-    queueMicrotask(() => {
-      this.replayPersistenceFlushScheduled = false;
-      const batch = this.pendingReplayPersistence.splice(0);
-      if (batch.length === 0 || !this.replayPersistence) return;
-      const operation = this.replayPersistence.appendBatch ? () => this.replayPersistence.appendBatch(batch) : () => Promise.all(batch.map((message) => this.replayPersistence.append(message))).then(() => void 0);
-      void this.withPersistenceRetry("append", operation).catch((error) => this.reportPersistenceError(error));
-    });
-  }
-  async hydrateReplay() {
-    if (!this.replayBuffers || !this.replayPersistence) {
-      return;
-    }
-    try {
-      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
-        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(this.now() - this.replayRetentionMs));
-      }
-      for (const message of await this.withPersistenceRetry("load", () => this.replayPersistence.load())) {
-        let buffer = this.replayBuffers.get(message.topic);
-        if (!buffer) {
-          buffer = [];
-          this.replayBuffers.set(message.topic, buffer);
-        }
-        buffer.push(message);
-        if (buffer.length > this.replayMaxPerTopic) buffer.shift();
-      }
-    } catch (error) {
-      this.reportPersistenceError(error);
-    }
-  }
-  scheduleReplayRetentionCleanup(cutoff) {
-    if (!this.replayPersistence?.clearBefore) return;
-    if (this.replayRetentionCutoff === null || cutoff > this.replayRetentionCutoff) {
-      this.replayRetentionCutoff = cutoff;
-    }
-    if (this.replayRetentionCleanup) return;
-    this.replayRetentionCleanup = (async () => {
-      while (this.replayRetentionCutoff !== null) {
-        const nextCutoff = this.replayRetentionCutoff;
-        this.replayRetentionCutoff = null;
-        try {
-          await this.replayPersistence.clearBefore(nextCutoff);
-        } catch (error) {
-          this.reportPersistenceError(error);
-        }
-      }
-    })().finally(() => {
-      this.replayRetentionCleanup = null;
-      if (this.replayRetentionCutoff !== null) {
-        this.scheduleReplayRetentionCleanup(this.replayRetentionCutoff);
-      }
-    });
-  }
-  startReplayRetentionSweep() {
-    if (this.replayRetentionTimer || !this.replayRetentionMs || !this.replayRetentionSweepMs || !this.replayPersistence?.clearBefore) return;
-    this.replayRetentionTimer = setInterval(() => {
-      this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
-    }, this.replayRetentionSweepMs);
-  }
-  stopReplayRetentionSweep() {
-    if (this.replayRetentionTimer) clearInterval(this.replayRetentionTimer);
-    this.replayRetentionTimer = null;
-  }
-  async withPersistenceRetry(persistenceOperation, operation) {
-    const generation = this.persistenceRetryGeneration;
-    let attempt = 0;
-    let delay = this.persistenceRetryBackoffMs;
-    while (true) {
-      attempt += 1;
-      try {
-        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
-        return await operation();
-      } catch (error) {
-        if (error instanceof PersistenceRetryCancelledError || generation !== this.persistenceRetryGeneration) {
-          throw new PersistenceRetryCancelledError();
-        }
-        if (attempt >= this.persistenceRetryMaxAttempts) throw error;
-        this.trace.event({
-          type: "reliability",
-          operation: "persistence_retry",
-          persistenceOperation,
-          attempt
-        });
-        if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
-        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
-        delay = Math.min(delay * 2, 1600);
-      }
-    }
-  }
-  /** Deliver buffered history to a newly-registered handler. For an exact
-   * topic this is that topic's ring; for a wildcard subscription every
-   * buffered topic matching the pattern contributes (in buffer insertion
-   * order). Replay deliveries are marked `replayed: true` and are not
-   * counted into trace metrics. */
-  deliverReplay(topic, limit, handler) {
-    if (!this.replayBuffers || limit <= 0) return;
-    const deliver = (buffer2) => {
-      for (const message of buffer2.slice(-limit)) {
-        this.invokeHandlers([handler], (h) => h({ ...message, replayed: true }));
-      }
-    };
-    if (isWildcardTopic(topic)) {
-      for (const [bufferedTopic, buffer2] of this.replayBuffers) {
-        if (topicMatchesPattern(topic, bufferedTopic)) deliver(buffer2);
-      }
-      return;
-    }
-    const buffer = this.replayBuffers.get(topic);
-    if (buffer) deliver(buffer);
+    this.replayManager.record(message);
   }
   /**
    * Propagate a status change to the cluster, trace, and all registered
@@ -2183,13 +3026,13 @@ var CrossTabDataBus = class {
   updateStatus(status) {
     const previousStatus = this.status;
     this.status = status;
-    if (previousStatus !== status) this.trace.event({ type: "status", status });
+    if (previousStatus !== status) this.trace.event({ type: TRACE_EVENT_TYPE.STATUS, status });
     this.cluster.setStatus(status);
-    if (status === "disconnected" || status === "error") this.transportSubscribedTopics.clear();
-    if (status === "connected" && previousStatus !== "connected") {
+    if (status === WORKER_STATUS.DISCONNECTED || status === WORKER_STATUS.ERROR) this.transportSubscribedTopics.clear();
+    if (status === WORKER_STATUS.CONNECTED && previousStatus !== WORKER_STATUS.CONNECTED) {
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
-    if (status === "error" && this.started && !this.stopping) {
+    if (status === WORKER_STATUS.ERROR && this.started && !this.stopping) {
       const now = this.now();
       if (now - this.lastRecoveryAt >= this.recoveryCooldownMs) {
         this.lastRecoveryAt = now;
@@ -2197,37 +3040,67 @@ var CrossTabDataBus = class {
         if (attempt > this.recoveryMaxAttempts) {
           if (!this.recoveryExhausted) {
             this.recoveryExhausted = true;
-            this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: this.recoveryMaxAttempts, outcome: "exhausted" });
+            this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: this.recoveryMaxAttempts, outcome: RECOVERY_OUTCOME.EXHAUSTED });
           }
           return;
         }
-        this.trace.event({ type: "reliability", operation: "transport_recovery", attempt, outcome: "scheduled" });
+        this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt, outcome: RECOVERY_OUTCOME.SCHEDULED });
         setTimeout(() => {
           if (this.stopping || !this.started || this.suspended) return;
-          if (this.status !== "error") return;
+          if (this.status !== WORKER_STATUS.ERROR) return;
           void this.reopenTransport(attempt);
         }, this.recoveryCooldownMs);
       }
     }
     this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
   }
-  reportError(error) {
-    this.trace.event({ type: "error", source: "transport" });
-    this.invokeHandlers(this.errorHandlers, (handler) => handler(error), "error handler");
+  reportError(error, source = FAILURE_SOURCE.TRANSPORT) {
+    this.lastFailure = {
+      source,
+      message: error instanceof Error ? error.message : String(error),
+      at: this.now()
+    };
+    if (source === FAILURE_SOURCE.PERSISTENCE) {
+      this.persistenceFailureCount += 1;
+      this.persistenceLastFailureAt = this.lastFailure.at;
+      this.persistenceLastErrorMessage = this.lastFailure.message;
+    }
+    this.trace.event({
+      type: TRACE_EVENT_TYPE.ERROR,
+      source: source === FAILURE_SOURCE.TRANSPORT ? TRACE_ERROR_SOURCE.TRANSPORT : TRACE_ERROR_SOURCE.OPERATION
+    });
+    this.invokeHandlers(this.errorHandlers, (handler) => handler(error), INVOKE_LABEL.ERROR_HANDLER);
   }
+  /** Report a persistence failure to the trace and the unified failure ledger,
+   * unless it is a {@link PersistenceRetryCancelledError} cancellation from a
+   * lifecycle transition (teardown should stay quiet). */
   reportPersistenceError(error) {
     if (error instanceof PersistenceRetryCancelledError) return;
-    this.trace.event({ type: "reliability", operation: "persistence_cleanup" });
-    this.reportError(error);
+    this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.PERSISTENCE_CLEANUP });
+    this.reportError(error, FAILURE_SOURCE.PERSISTENCE);
   }
   traceSubscription(action, topic) {
     this.trace.event({
-      type: "subscription",
+      type: TRACE_EVENT_TYPE.SUBSCRIPTION,
       action,
       topic,
       activeTopics: this.transportSubscribedTopics.size
     });
   }
+  /** 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. */
+  emitCoordinationTrace() {
+    const snapshot = this.cluster.getSnapshot();
+    this.trace.event({
+      type: TRACE_EVENT_TYPE.COORDINATION,
+      coordinated: snapshot.coordinated,
+      activeWorkers: snapshot.workers.filter((worker) => worker.role === WORKER_ROLE.ACTIVE).length,
+      workers: snapshot.workers.map(formatWorkerTrace),
+      routes: snapshot.routes.map(formatRouteTrace)
+    });
+  }
   /** Ask the transport to subscribe to a topic (idempotent). */
   subscribeTransport(topic) {
     if (this.transportSubscribedTopics.has(topic)) return false;
@@ -2245,17 +3118,17 @@ var CrossTabDataBus = class {
    * 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") {
+  invokeHandlers(handlers, callback, label = INVOKE_LABEL.DISPATCH) {
     for (const handler of handlers) {
       try {
         callback(handler);
       } catch (error) {
-        if (label === "error handler") {
+        if (label === INVOKE_LABEL.ERROR_HANDLER) {
           if (typeof console !== "undefined" && typeof console.warn === "function") {
-            console.warn("[cross-tab-worker-databus] error handler threw:", error);
+            console.warn(`[${DEFAULT_STORAGE_PREFIX}] error handler threw:`, error);
           }
         } else {
-          this.reportError(error);
+          this.reportError(error, FAILURE_SOURCE.DISPATCH);
         }
       }
     }
@@ -2266,10 +3139,11 @@ var CrossTabDataBus = class {
    */
   suspendTransport() {
     if (this.stopping) return;
+    this.lifecycleEpoch += 1;
     this.suspended = true;
     this.transportReady = false;
     this.transportSubscribedTopics.clear();
-    this.updateStatus("disconnected");
+    this.updateStatus(WORKER_STATUS.DISCONNECTED);
     if (this.pendingStop) return;
     const pending = this.startPromise ?? Promise.resolve();
     const stopping = pending.catch(() => void 0).then(() => this.transport.stop()).catch((error) => this.reportError(error));
@@ -2303,22 +3177,26 @@ var CrossTabDataBus = class {
     const traceAttempt = recoveryAttempt ?? (this.recoveryAttempt > 0 ? this.recoveryAttempt : void 0);
     this.started = true;
     this.suspended = false;
-    this.updateStatus("connecting");
+    this.updateStatus(WORKER_STATUS.CONNECTING);
+    const lifecycleEpoch = ++this.lifecycleEpoch;
     const pending = this.startPromise ?? this.pendingStop ?? Promise.resolve();
-    const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false));
+    const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false, lifecycleEpoch));
     this.startPromise = opening;
     void opening.then(
       () => {
+        if (this.startPromise === opening) this.startPromise = null;
+        if (lifecycleEpoch !== this.lifecycleEpoch) return;
         if (traceAttempt !== void 0) {
-          this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: traceAttempt, outcome: "succeeded" });
+          this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: traceAttempt, outcome: RECOVERY_OUTCOME.SUCCEEDED });
           this.recoveryAttempt = 0;
           this.recoveryExhausted = false;
         }
-        if (this.startPromise === opening) this.startPromise = null;
       },
       () => {
+        if (this.startPromise === opening) this.startPromise = null;
+        if (lifecycleEpoch !== this.lifecycleEpoch) return;
         if (traceAttempt !== void 0) {
-          this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: traceAttempt, outcome: "failed" });
+          this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: traceAttempt, outcome: RECOVERY_OUTCOME.FAILED });
         }
       }
     );
@@ -2350,6 +3228,19 @@ var CrossTabDataBus = class {
       return operation();
     }).catch((error) => this.reportError(error));
   }
+  /**
+   * Publications started after teardown begins cannot reach any transport.
+   * Surface that as a normal asynchronous API failure instead of letting
+   * runTransport() return silently. Empty publishBatch() calls remain a no-op
+   * and are filtered by the caller before this check.
+   */
+  rejectPublishDuringStop(operation) {
+    if (!this.stopping) return false;
+    this.reportError(new Error(
+      `CrossTabDataBus is stopping; ${operation}() was not sent. Wait for stop() to resolve, then call start() before publishing again.`
+    ));
+    return true;
+  }
   /**
    * Ensure the DataBus is started, throwing if no initialConfig was provided.
    * Called automatically by subscribe/publish/ready when autoStart is true.
@@ -2397,50 +3288,102 @@ function parseDataBusPublication(value, fallbackTopic) {
   };
 }
 
+// src/utils/error-utils.ts
+function serializeError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      ...error.stack ? { stack: error.stack } : {}
+    };
+  }
+  const context = error === void 0 ? void 0 : error;
+  return {
+    name: "CentrifugeError",
+    message: typeof error === "string" ? error : "Centrifuge worker operation failed.",
+    ...context === void 0 || !isStructuredCloneable(context) ? {} : { context }
+  };
+}
+function isStructuredCloneable(value) {
+  if (typeof structuredClone !== "function") return true;
+  try {
+    structuredClone(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function deserializeWorkerError(error) {
+  const result = new Error(error.message);
+  result.name = error.name;
+  if (error.stack) result.stack = error.stack;
+  if (error.context !== void 0) Object.assign(result, { context: error.context });
+  return result;
+}
+
 // src/centrifuge-session.ts
 var CentrifugeSession = class {
   constructor(sink) {
     this.sink = sink;
   }
+  sink;
   client = null;
   subscriptions = /* @__PURE__ */ new Map();
   transferable = false;
+  tokenBridge = false;
+  nextRequestId = 1;
+  pendingTokenRequests = /* @__PURE__ */ new Map();
   /** Dispatch an incoming Worker message to the matching operation.
    * Unknown message types are ignored rather than thrown, so a future protocol
    * extension adding a new variant cannot crash an older session. */
   handle(message) {
     switch (message.type) {
-      case "INIT":
-        this.initialize(message.url, message.config, message.transferable === true);
+      case CENTRIFUGE_INPUT_TYPE.INIT:
+        this.initialize(message.url, message.config, message.transferable === true, message.tokenBridge === true);
         return;
-      case "SUBSCRIBE":
+      case CENTRIFUGE_INPUT_TYPE.SUBSCRIBE:
         this.subscribe(message.topic);
         return;
-      case "UNSUBSCRIBE":
+      case CENTRIFUGE_INPUT_TYPE.UNSUBSCRIBE:
         this.unsubscribe(message.topic);
         return;
-      case "PUBLISH":
-      case "PUBLISH_BIN":
+      case CENTRIFUGE_INPUT_TYPE.PUBLISH:
+      case CENTRIFUGE_INPUT_TYPE.PUBLISH_BIN:
         this.publish(message.topic, message.data, message.messageId, message.timestamp);
         return;
-      case "STOP":
+      case CENTRIFUGE_INPUT_TYPE.STOP:
         this.stop();
         return;
+      case CENTRIFUGE_INPUT_TYPE.TOKEN_RESPONSE:
+        this.resolveToken(message.requestId, message.token);
+        return;
+      case CENTRIFUGE_INPUT_TYPE.TOKEN_ERROR:
+        this.rejectToken(message.requestId, deserializeWorkerError(message.error));
+        return;
       default:
         return;
     }
   }
   /** Create the Centrifuge client, wire up lifecycle listeners, and connect. */
-  initialize(url, config, transferable) {
+  initialize(url, config, transferable, tokenBridge) {
     if (this.client) return;
     this.transferable = transferable;
-    const client = new import_centrifuge.Centrifuge(url, config);
+    this.tokenBridge = tokenBridge;
+    const clientOptions = tokenBridge ? {
+      ...config,
+      // Route credential fetches back to the main thread, where the
+      // application's credentialProvider lives (config must stay
+      // structured-cloneable, so functions cannot cross the boundary).
+      getToken: () => this.requestToken("token"),
+      getChannelToken: (channel) => this.requestToken("channelToken", channel)
+    } : config;
+    const client = new import_centrifuge.Centrifuge(url, clientOptions);
     this.client = client;
     client.on("state", (context) => {
-      this.post({ type: "STATUS", status: normalizeStatus(context.newState) });
+      this.post({ type: CENTRIFUGE_OUTPUT_TYPE.STATUS, status: normalizeStatus(context.newState) });
     });
-    client.on("connected", () => this.post({ type: "STATUS", status: "connected" }));
-    client.on("disconnected", () => this.post({ type: "STATUS", status: "disconnected" }));
+    client.on("connected", () => this.post({ type: CENTRIFUGE_OUTPUT_TYPE.STATUS, status: WORKER_STATUS.CONNECTED }));
+    client.on("disconnected", () => this.post({ type: CENTRIFUGE_OUTPUT_TYPE.STATUS, status: WORKER_STATUS.DISCONNECTED }));
     client.on("error", (context) => this.postError(context));
     client.on("publication", (context) => {
       const topic = context.channel || getPayloadTopic(context.data);
@@ -2503,25 +3446,56 @@ var CentrifugeSession = class {
   postPublication(topic, data) {
     if (!topic) return;
     if (this.transferable && data instanceof ArrayBuffer) {
-      this.post({ type: "MESSAGE_BIN", topic, data }, [data]);
+      this.post({ type: CENTRIFUGE_OUTPUT_TYPE.MESSAGE_BIN, topic, data }, [data]);
       return;
     }
     const publication = parseDataBusPublication(data, topic);
     if (!publication) return;
     this.post({
-      type: "MESSAGE",
+      type: CENTRIFUGE_OUTPUT_TYPE.MESSAGE,
       topic: publication.topic,
       data: publication.data,
-      ...publication.messageId === void 0 ? {} : { messageId: publication.messageId },
-      ...publication.timestamp === void 0 ? {} : { timestamp: publication.timestamp }
+      ...publicationMetadata(publication.messageId, publication.timestamp)
     });
   }
   /** Disconnect the client and clear all subscriptions. */
   stop() {
+    for (const [, pending] of this.pendingTokenRequests) {
+      pending.reject(new Error("Centrifuge session stopped before the credential was resolved."));
+    }
+    this.pendingTokenRequests.clear();
     this.client?.disconnect();
     this.subscriptions.clear();
     this.client = null;
-    this.post({ type: "STATUS", status: "disconnected" });
+    this.post({ type: CENTRIFUGE_OUTPUT_TYPE.STATUS, status: WORKER_STATUS.DISCONNECTED });
+  }
+  /** Issue a credential request to the main thread and await the response.
+   * Used as Centrifuge's `getToken` / `getChannelToken` when token bridging is
+   * enabled; resolved or rejected by a matching TOKEN_RESPONSE / TOKEN_ERROR. */
+  requestToken(kind, channel) {
+    const requestId = this.nextRequestId;
+    this.nextRequestId += 1;
+    return new Promise((resolve, reject) => {
+      this.pendingTokenRequests.set(requestId, { resolve, reject });
+      this.post({
+        type: CENTRIFUGE_OUTPUT_TYPE.TOKEN_REQUEST,
+        requestId,
+        kind,
+        ...channel === void 0 ? {} : { channel }
+      });
+    });
+  }
+  resolveToken(requestId, token) {
+    const pending = this.pendingTokenRequests.get(requestId);
+    if (!pending) return;
+    this.pendingTokenRequests.delete(requestId);
+    pending.resolve(token);
+  }
+  rejectToken(requestId, error) {
+    const pending = this.pendingTokenRequests.get(requestId);
+    if (!pending) return;
+    this.pendingTokenRequests.delete(requestId);
+    pending.reject(error);
   }
   /** Forward a message to the sink (the transport layer). */
   post(message, transfer) {
@@ -2533,7 +3507,7 @@ var CentrifugeSession = class {
    * Fatal errors are distinguished by the client eventually emitting
    * `disconnected` without a subsequent `connected`. */
   postError(error) {
-    this.post({ type: "ERROR", error: serializeError(error) });
+    this.post({ type: CENTRIFUGE_OUTPUT_TYPE.ERROR, error: serializeError(error) });
   }
 };
 function getPayloadTopic(data) {
@@ -2544,33 +3518,19 @@ function getPayloadTopic(data) {
   const topic = nested ?? payload.channel;
   return typeof topic === "string" ? topic : "";
 }
-var LIVE_STATES = /* @__PURE__ */ new Set(["connecting", "connected"]);
+var LIVE_STATES = /* @__PURE__ */ new Set([WORKER_STATUS.CONNECTING, WORKER_STATUS.CONNECTED]);
 function normalizeStatus(status) {
   return LIVE_STATES.has(status) ? status : "disconnected";
 }
-function serializeError(error) {
-  if (error instanceof Error) {
-    return {
-      name: error.name,
-      message: error.message,
-      ...error.stack ? { stack: error.stack } : {}
-    };
-  }
-  return {
-    name: "CentrifugeError",
-    message: typeof error === "string" ? error : "Centrifuge worker operation failed.",
-    ...error === void 0 ? {} : { context: error }
-  };
-}
 
 // src/worker-mode.ts
 function selectWorkerBackend(mode, availability = {}) {
   const hasDedicated = availability.worker ?? typeof Worker !== "undefined";
   const hasShared = availability.sharedWorker ?? typeof SharedWorker !== "undefined";
-  if (mode === "shared" || mode === "auto") {
-    return hasShared ? "shared" : hasDedicated ? "dedicated" : "local";
+  if (mode === WORKER_MODE.SHARED || mode === WORKER_MODE.AUTO) {
+    return hasShared ? WORKER_BACKEND.SHARED : hasDedicated ? WORKER_BACKEND.DEDICATED : WORKER_BACKEND.LOCAL;
   }
-  return hasDedicated ? "dedicated" : hasShared ? "shared" : "local";
+  return hasDedicated ? WORKER_BACKEND.DEDICATED : hasShared ? WORKER_BACKEND.SHARED : WORKER_BACKEND.LOCAL;
 }
 
 // src/centrifuge-protocol.ts
@@ -2587,6 +3547,7 @@ var CentrifugeWorkerTransport = class {
   heartbeatIntervalMs;
   workerFactory;
   sharedWorkerFactory;
+  credentialProvider;
   backend = null;
   worker = null;
   sharedWorker = null;
@@ -2604,12 +3565,13 @@ var CentrifugeWorkerTransport = class {
     return this.backend ?? "uninitialized";
   }
   constructor(options = {}) {
-    this.workerMode = options.workerMode ?? "dedicated";
+    this.workerMode = options.workerMode ?? WORKER_MODE.DEDICATED;
     this.transferable = options.transferable ?? false;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS2;
     assertHeartbeatInterval(this.heartbeatIntervalMs);
     this.workerFactory = options.workerFactory;
     this.sharedWorkerFactory = options.sharedWorkerFactory;
+    this.credentialProvider = options.credentialProvider;
   }
   /**
    * Start the transport: select a backend, initialise the Worker (or local
@@ -2620,29 +3582,29 @@ var CentrifugeWorkerTransport = class {
     assertStructuredCloneable(config.options ?? {});
     this.handlers = handlers;
     const backend = selectWorkerBackend(this.workerMode, {
-      worker: this.workerFactory !== void 0,
-      sharedWorker: this.sharedWorkerFactory !== void 0
+      worker: this.workerFactory !== void 0 || typeof Worker !== "undefined",
+      sharedWorker: this.sharedWorkerFactory !== void 0 || typeof SharedWorker !== "undefined"
     });
     const input = this.buildInitInput(config);
-    if (backend === "shared") {
+    if (backend === WORKER_BACKEND.SHARED) {
       this.startSharedWorker(input);
-      this.backend = "shared";
+      this.backend = WORKER_BACKEND.SHARED;
       return;
     }
-    if (backend === "dedicated") {
+    if (backend === WORKER_BACKEND.DEDICATED) {
       this.startDedicatedWorker(input);
-      this.backend = "dedicated";
+      this.backend = WORKER_BACKEND.DEDICATED;
       return;
     }
     this.localSession = new CentrifugeSession({ post: this.handleSessionOutput });
     this.localSession.handle(input);
-    this.backend = "local";
+    this.backend = WORKER_BACKEND.LOCAL;
   }
   subscribe(topic) {
-    this.post({ type: "SUBSCRIBE", topic });
+    this.post({ type: CENTRIFUGE_INPUT_TYPE.SUBSCRIBE, topic });
   }
   unsubscribe(topic) {
-    this.post({ type: "UNSUBSCRIBE", topic });
+    this.post({ type: CENTRIFUGE_INPUT_TYPE.UNSUBSCRIBE, topic });
   }
   /**
    * Publish data to `topic`. Binary data (ArrayBuffer) is sent via Transferable
@@ -2650,10 +3612,10 @@ var CentrifugeWorkerTransport = class {
    */
   publish(topic, data, options) {
     if (this.transferable && data instanceof ArrayBuffer) {
-      this.post({ type: "PUBLISH_BIN", topic, data, ...publicationMetadata2(options) }, [data]);
+      this.post({ type: CENTRIFUGE_INPUT_TYPE.PUBLISH_BIN, topic, data, ...publicationMetadata(options?.messageId, options?.timestamp) }, [data]);
       return;
     }
-    this.post({ type: "PUBLISH", topic, data, ...publicationMetadata2(options) });
+    this.post({ type: CENTRIFUGE_INPUT_TYPE.PUBLISH, topic, data, ...publicationMetadata(options?.messageId, options?.timestamp) });
   }
   /**
    * Gracefully stop the transport: send STOP, clean up event listeners, and
@@ -2662,7 +3624,7 @@ var CentrifugeWorkerTransport = class {
   stop() {
     if (!this.backend) return;
     this.generation++;
-    this.post({ type: "STOP" });
+    this.post({ type: CENTRIFUGE_INPUT_TYPE.STOP });
     this.clearHeartbeat();
     if (this.worker) {
       this.worker.removeEventListener("message", this.handleMessage);
@@ -2681,10 +3643,11 @@ var CentrifugeWorkerTransport = class {
    * default-resolution logic kicks in for the common case. */
   buildInitInput(config) {
     return {
-      type: "INIT",
+      type: CENTRIFUGE_INPUT_TYPE.INIT,
       url: config.url,
       config: config.options ?? {},
       ...this.transferable ? { transferable: true } : {},
+      ...this.credentialProvider ? { tokenBridge: true } : {},
       ...this.heartbeatIntervalMs !== DEFAULT_HEARTBEAT_INTERVAL_MS2 ? { heartbeatIntervalMs: this.heartbeatIntervalMs } : {}
     };
   }
@@ -2723,10 +3686,34 @@ var CentrifugeWorkerTransport = class {
    * Shared by the Worker message listener, the SharedWorker port listener,
    * and the local-session sink — all three feed into this single dispatcher. */
   handleOutput(message) {
-    if (message.type === "STATUS") this.handlers?.onStatus(message.status);
-    if (message.type === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata2(message) });
-    if (message.type === "MESSAGE_BIN") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata2(message) });
-    if (message.type === "ERROR") this.handlers?.onError(deserializeWorkerError(message.error));
+    if (message.type === CENTRIFUGE_OUTPUT_TYPE.STATUS) this.handlers?.onStatus(message.status);
+    if (message.type === CENTRIFUGE_OUTPUT_TYPE.MESSAGE) this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata(message.messageId, message.timestamp) });
+    if (message.type === CENTRIFUGE_OUTPUT_TYPE.MESSAGE_BIN) this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata(message.messageId, message.timestamp) });
+    if (message.type === CENTRIFUGE_OUTPUT_TYPE.ERROR) this.handlers?.onError(deserializeWorkerError(message.error));
+    if (message.type === CENTRIFUGE_OUTPUT_TYPE.TOKEN_REQUEST) this.resolveTokenRequest(message.requestId, message.kind, message.channel);
+  }
+  /** Resolve a Worker credential request from the main thread: call the
+   * credentialProvider, then post the fresh token (or a serialized failure)
+   * back to the session that issued the request. */
+  resolveTokenRequest(requestId, kind, channel) {
+    const provider = this.credentialProvider;
+    const value = kind === "channelToken" && provider?.getChannelToken ? provider.getChannelToken(channel ?? "") : provider?.getToken?.();
+    Promise.resolve(value).then(
+      (token) => {
+        if (typeof token !== "string" || token.length === 0) {
+          this.post({
+            type: CENTRIFUGE_INPUT_TYPE.TOKEN_ERROR,
+            requestId,
+            error: serializeError(new Error(`The credential provider returned no ${kind}.`))
+          });
+          return;
+        }
+        this.post({ type: CENTRIFUGE_INPUT_TYPE.TOKEN_RESPONSE, requestId, token });
+      },
+      (error) => {
+        this.post({ type: CENTRIFUGE_INPUT_TYPE.TOKEN_ERROR, requestId, error: serializeError(error) });
+      }
+    );
   }
   /** Handle a Worker-level failure (crash, message decode error). Discards the
    * dead backend so a later start()/reopen can rebuild from scratch, and
@@ -2742,7 +3729,7 @@ var CentrifugeWorkerTransport = class {
     this.clearHeartbeat();
     this.resetBackend();
     this.handlers?.onError(new Error(message));
-    this.handlers?.onStatus("error");
+    this.handlers?.onStatus(WORKER_STATUS.ERROR);
   }
   /** Remove every listener attached to the current SharedWorker and its port. */
   detachSharedWorkerListeners() {
@@ -2755,7 +3742,7 @@ var CentrifugeWorkerTransport = class {
     if (this.heartbeatHandle !== null) return;
     if (this.heartbeatIntervalMs === Infinity) return;
     this.heartbeatHandle = setInterval(() => {
-      this.post({ type: "PING" });
+      this.post({ type: CENTRIFUGE_INPUT_TYPE.PING });
     }, this.heartbeatIntervalMs);
   }
   clearHeartbeat() {
@@ -2806,6 +3793,7 @@ function createCentrifugeDataBus(options) {
   const {
     clusterKey,
     connection,
+    credentialProvider,
     heartbeatIntervalMs,
     sharedWorkerFactory,
     transferable,
@@ -2823,7 +3811,8 @@ function createCentrifugeDataBus(options) {
       ...sharedWorkerFactory ? { sharedWorkerFactory } : {},
       ...transferable === void 0 ? {} : { transferable },
       ...workerMode ? { workerMode } : {},
-      ...heartbeatIntervalMs === void 0 ? {} : { heartbeatIntervalMs }
+      ...heartbeatIntervalMs === void 0 ? {} : { heartbeatIntervalMs },
+      ...credentialProvider ? { credentialProvider } : {}
     })
   });
 }
@@ -2840,7 +3829,7 @@ function createDefaultWorker() {
     );
   }
   return new Worker(workerUrl, {
-    name: "cross-tab-worker-databus",
+    name: DEFAULT_STORAGE_PREFIX,
     type: "module"
   });
 }
@@ -2857,43 +3846,12 @@ function createDefaultSharedWorker() {
     );
   }
   return new SharedWorker(workerUrl, {
-    name: "cross-tab-worker-databus-shared",
+    name: `${DEFAULT_STORAGE_PREFIX}-shared`,
     type: "module"
   });
 }
-function assertHeartbeatInterval(value) {
-  if (value === Infinity) return;
-  if (typeof value === "number" && Number.isFinite(value) && value > 0) return;
-  throw new TypeError(
-    `Centrifuge heartbeatIntervalMs must be a positive number or Infinity, got ${String(value)}.`
-  );
-}
-function assertStructuredCloneable(value) {
-  if (typeof structuredClone !== "function") return;
-  try {
-    structuredClone(value);
-  } catch (error) {
-    throw new TypeError(
-      "Centrifuge Worker configuration and published data must be structured-cloneable.",
-      { cause: error }
-    );
-  }
-}
 function postToPortLike(target, message, transfer) {
   if (transfer) target.postMessage(message, transfer);
   else target.postMessage(message);
 }
-function deserializeWorkerError(error) {
-  const result = new Error(error.message);
-  result.name = error.name;
-  if (error.stack) result.stack = error.stack;
-  if (error.context !== void 0) Object.assign(result, { context: error.context });
-  return result;
-}
-function publicationMetadata2(metadata) {
-  return {
-    ...metadata?.messageId === void 0 ? {} : { messageId: metadata.messageId },
-    ...metadata?.timestamp === void 0 ? {} : { timestamp: metadata.timestamp }
-  };
-}
 //# sourceMappingURL=centrifuge.cjs.map