@tanstack/db-sqlite-persistence-core 0.2.21 → 0.4.0

package/dist/esm/broadcast-coordinator.js

@@ -0,0 +1,1689 @@
+import { safeRandomUUID } from "@tanstack/db";
+import { DuplicateRemoteSubsetOwnerError, RetryableRemoteSubsetAcquisitionError, IndeterminateCommitError, toPersistedCollectionDurabilityError, PersistedCollectionDurabilityError } from "./errors.js";
+import { toTransportedLoadSubsetOptions, toProcessLocalLoadSubsetOptions } from "./remote-subset-wire.js";
+import { unloadRemoteSubsetOwner } from "./remote-subset-owner.js";
+const HEARTBEAT_INTERVAL_MS = 3e3;
+const LEADERSHIP_RETRY_DELAY_MS = 200;
+const RPC_TIMEOUT_MS = 1e4;
+const RPC_RETRY_ATTEMPTS = 2;
+const RPC_RETRY_DELAY_MS = 200;
+const REMOTE_SUBSET_REPLAY_RETRY_ATTEMPTS = 2;
+const RPC_DEDUPE_RETENTION_MS = 6e4;
+const WRITER_LOCK_BUSY_RETRY_MS = 50;
+const WRITER_LOCK_MAX_RETRIES = 20;
+class BroadcastCollectionCoordinator {
+  constructor(options) {
+    this.nodeId = safeRandomUUID();
+    this.collectionAdapters = /* @__PURE__ */ new Map();
+    this.remoteSubsetOwners = /* @__PURE__ */ new Map();
+    this.remoteSubsetIds = /* @__PURE__ */ new Map();
+    this.outboundRemoteSubsetAcquisitions = /* @__PURE__ */ new Map();
+    this.inboundRemoteSubsetAcquisitions = /* @__PURE__ */ new Map();
+    this.releasedRemoteSubsetAcquisitionTimes = /* @__PURE__ */ new Map();
+    this.collections = /* @__PURE__ */ new Map();
+    this.pendingRPCs = /* @__PURE__ */ new Map();
+    this.appliedEnvelopes = /* @__PURE__ */ new Map();
+    this.inFlightEnvelopes = /* @__PURE__ */ new Map();
+    this.appliedEnvelopePruneTimer = null;
+    this.rejectDisposed = null;
+    this.disposed = false;
+    this.dbName = options.dbName;
+    this.coordinatorName = options.coordinatorName;
+    this.defaultAdapter = options.adapter ?? null;
+    this.channel = new BroadcastChannel(`tsdb:coord:${this.dbName}`);
+    this.channel.onmessage = (event) => {
+      this.onChannelMessage(event.data);
+    };
+    this.disposedPromise = new Promise((_resolve, reject) => {
+      this.rejectDisposed = reject;
+    });
+    void this.disposedPromise.catch(() => void 0);
+  }
+  /** Method indirection to prevent TypeScript from narrowing `disposed` across awaits */
+  isDisposed() {
+    return this.disposed;
+  }
+  /** Method indirection to re-read leadership participation across awaits. */
+  participatesInLeadership(state) {
+    return state.participatesInLeadership;
+  }
+  requireAdapter(collectionId) {
+    let adapter = this.collectionAdapters.get(collectionId);
+    if (!adapter && this.defaultAdapter) {
+      adapter = this.defaultAdapter;
+      this.collectionAdapters.set(collectionId, adapter);
+    }
+    if (!adapter) {
+      throw new Error(
+        `${this.coordinatorName}: adapter not set for collection "${collectionId}". Call setAdapterForCollection() before using leader-side operations.`
+      );
+    }
+    return adapter;
+  }
+  /**
+   * Set or replace the persistence adapter used for leader-side RPC handling.
+   * Called by a host persistence factory to wire the internally-created adapter.
+   */
+  setAdapter(adapter) {
+    this.defaultAdapter = adapter;
+  }
+  /** Register the persistence adapter that owns one collection. */
+  setAdapterForCollection(collectionId, adapter) {
+    this.collectionAdapters.set(collectionId, adapter);
+  }
+  registerRemoteSubsetOwner(collectionId, owner) {
+    if (this.remoteSubsetOwners.has(collectionId)) {
+      throw new DuplicateRemoteSubsetOwnerError(collectionId);
+    }
+    this.remoteSubsetOwners.set(collectionId, owner);
+    for (const acquisition of this.outboundRemoteSubsetAcquisitions.values()) {
+      if (acquisition.collectionId !== collectionId) continue;
+      acquisition.acquiredLeaderId = null;
+      acquisition.forceReplay = true;
+    }
+    void this.replayRemoteSubsetAcquisitions(collectionId);
+    this.rebindRemoteInboundSubsetAcquisitions(collectionId, owner);
+    return () => {
+      if (this.remoteSubsetOwners.get(collectionId) !== owner) return;
+      this.remoteSubsetOwners.delete(collectionId);
+      this.releaseInboundRemoteSubsetAcquisitions(collectionId, owner);
+    };
+  }
+  // -----------------------------------------------------------------------
+  // PersistedCollectionCoordinator interface
+  // -----------------------------------------------------------------------
+  getNodeId() {
+    return this.nodeId;
+  }
+  subscribe(collectionId, onMessage) {
+    const state = this.ensureCollectionState(collectionId);
+    state.subscribers.add(onMessage);
+    return () => {
+      state.subscribers.delete(onMessage);
+      if (state.subscribers.size === 0) {
+        state.participatesInLeadership = false;
+        this.releaseCollectionIfUnused(collectionId, state);
+      }
+    };
+  }
+  publish(_collectionId, message) {
+    this.channel.postMessage(message);
+  }
+  isLeader(collectionId) {
+    return this.collections.get(collectionId)?.isLeader ?? false;
+  }
+  async ensureLeadership(collectionId) {
+    const state = this.ensureCollectionState(collectionId);
+    if (state.isLeader) return;
+    await this.acquireLeadership(collectionId, state);
+  }
+  async requestEnsureRemoteSubset(collectionId, options) {
+    const transportedOptions = toTransportedLoadSubsetOptions(options);
+    const localOptions = toProcessLocalLoadSubsetOptions(
+      options,
+      transportedOptions
+    );
+    let collectionIds = this.remoteSubsetIds.get(collectionId);
+    if (!collectionIds) {
+      collectionIds = /* @__PURE__ */ new WeakMap();
+      this.remoteSubsetIds.set(collectionId, collectionIds);
+    }
+    let acquisitionId = collectionIds.get(options);
+    let acquisition = acquisitionId ? this.outboundRemoteSubsetAcquisitions.get(
+      remoteSubsetAcquisitionKey(collectionId, acquisitionId)
+    ) : void 0;
+    if (!acquisition) {
+      acquisitionId = safeRandomUUID();
+      collectionIds.set(options, acquisitionId);
+      acquisition = {
+        collectionId,
+        acquisitionId,
+        options: transportedOptions,
+        localOptions,
+        acquiredLeaderId: null,
+        inFlight: null,
+        release: null,
+        releaseRequested: false,
+        forceReplay: false,
+        retryTimer: null,
+        retryAttempts: 0
+      };
+      this.outboundRemoteSubsetAcquisitions.set(
+        remoteSubsetAcquisitionKey(collectionId, acquisitionId),
+        acquisition
+      );
+    }
+    try {
+      await this.acquireRemoteSubset(acquisition);
+    } catch (error) {
+      if (options.signal?.aborted) {
+        acquisition.releaseRequested = true;
+        this.cancelRemoteSubsetReplayRetry(acquisition);
+        this.postRemoteSubsetRelease(acquisition);
+        const key = remoteSubsetAcquisitionKey(
+          collectionId,
+          acquisition.acquisitionId
+        );
+        if (this.outboundRemoteSubsetAcquisitions.get(key) === acquisition) {
+          this.outboundRemoteSubsetAcquisitions.delete(key);
+          collectionIds.delete(options);
+        }
+      }
+      throw error;
+    }
+  }
+  async requestReleaseRemoteSubset(collectionId, options) {
+    const collectionIds = this.remoteSubsetIds.get(collectionId);
+    const acquisitionId = collectionIds?.get(options);
+    if (!acquisitionId) return;
+    const key = remoteSubsetAcquisitionKey(collectionId, acquisitionId);
+    const acquisition = this.outboundRemoteSubsetAcquisitions.get(key);
+    if (!acquisition) return;
+    acquisition.releaseRequested = true;
+    this.cancelRemoteSubsetReplayRetry(acquisition);
+    if (!acquisition.release) {
+      acquisition.release = (async () => {
+        const request = {
+          type: `rpc:releaseRemoteSubset:req`,
+          rpcId: safeRandomUUID(),
+          acquisitionId
+        };
+        const localLeader = this.isLeader(collectionId);
+        let releaseReachedLeader = localLeader;
+        try {
+          const response = localLeader ? await this.handleReleaseRemoteSubset(
+            collectionId,
+            request,
+            this.nodeId
+          ) : await this.sendRPC(
+            collectionId,
+            request
+          );
+          releaseReachedLeader = true;
+          if (!response.ok) {
+            throw new Error(`releaseRemoteSubset failed: ${response.error}`);
+          }
+        } finally {
+          if (releaseReachedLeader && this.outboundRemoteSubsetAcquisitions.get(key) === acquisition) {
+            this.outboundRemoteSubsetAcquisitions.delete(key);
+            collectionIds.delete(options);
+          }
+        }
+      })();
+    }
+    try {
+      await acquisition.release;
+    } finally {
+      acquisition.release = null;
+    }
+  }
+  async acquireRemoteSubset(acquisition) {
+    if (acquisition.inFlight) return acquisition.inFlight;
+    const route = { localOwner: false };
+    let resolveWork;
+    let rejectWork;
+    const work = new Promise((resolve, reject) => {
+      resolveWork = resolve;
+      rejectWork = reject;
+    });
+    acquisition.inFlight = work;
+    const run = async () => {
+      const request = {
+        type: `rpc:ensureRemoteSubset:req`,
+        rpcId: safeRandomUUID(),
+        acquisitionId: acquisition.acquisitionId,
+        options: acquisition.options
+      };
+      const state = this.collections.get(acquisition.collectionId);
+      if (state?.participatesInLeadership && !state.isLeader && state.leaderId === null) {
+        await this.waitForLeadershipRoute(
+          acquisition.collectionId,
+          state,
+          acquisition.localOptions.signal
+        );
+      }
+      route.localOwner = this.isLeader(acquisition.collectionId);
+      let response;
+      try {
+        response = route.localOwner ? await this.handleEnsureRemoteSubset(
+          acquisition.collectionId,
+          request,
+          this.nodeId,
+          acquisition.localOptions
+        ) : await this.sendRPC(
+          acquisition.collectionId,
+          request
+        );
+      } catch (error) {
+        if (route.localOwner || error instanceof RetryableRemoteSubsetAcquisitionError) {
+          throw error;
+        }
+        throw new RetryableRemoteSubsetAcquisitionError(
+          `Remote subset transport failed`,
+          error
+        );
+      }
+      if (!response.ok) {
+        if (response.retryable) {
+          throw new RetryableRemoteSubsetAcquisitionError(response.error);
+        }
+        throw new Error(`ensureRemoteSubset failed: ${response.error}`);
+      }
+      acquisition.acquiredLeaderId = response.leaderId;
+    };
+    void run().then(resolveWork, rejectWork);
+    let acquired = false;
+    try {
+      await work;
+      acquired = true;
+      this.cancelRemoteSubsetReplayRetry(acquisition);
+    } finally {
+      if (acquisition.inFlight === work) acquisition.inFlight = null;
+      const current = this.collections.get(acquisition.collectionId);
+      const currentLeaderId = current?.isLeader ? this.nodeId : current?.leaderId ?? null;
+      const key = remoteSubsetAcquisitionKey(
+        acquisition.collectionId,
+        acquisition.acquisitionId
+      );
+      if (acquired && !acquisition.releaseRequested && this.outboundRemoteSubsetAcquisitions.get(key) === acquisition && (acquisition.forceReplay || currentLeaderId !== null && acquisition.acquiredLeaderId !== currentLeaderId)) {
+        acquisition.forceReplay = false;
+        void this.acquireRemoteSubset(acquisition).catch((error) => {
+          this.scheduleRemoteSubsetReplayRetry(acquisition, error);
+        });
+      }
+    }
+  }
+  async requestEnsurePersistedIndex(collectionId, signature, spec, scopedAdapter, localEnsureCompleted = false) {
+    if (this.isLeader(collectionId)) {
+      if (localEnsureCompleted) return;
+      await (scopedAdapter ?? this.requireAdapter(collectionId)).ensureIndex(
+        collectionId,
+        signature,
+        spec
+      );
+      return;
+    }
+    const response = await this.sendRPC(collectionId, {
+      type: `rpc:ensurePersistedIndex:req`,
+      rpcId: safeRandomUUID(),
+      signature,
+      spec
+    });
+    if (!response.ok) {
+      throw new Error(
+        `ensurePersistedIndex failed: ${response.error ?? `unknown error`}`
+      );
+    }
+  }
+  async requestApplyLocalMutations(collectionId, mutations) {
+    const initialRoute = this.waitForInitialRoute(collectionId);
+    if (initialRoute) await initialRoute;
+    if (this.isLeader(collectionId)) {
+      return this.handleApplyLocalMutations(collectionId, {
+        type: `rpc:applyLocalMutations:req`,
+        rpcId: safeRandomUUID(),
+        envelopeId: safeRandomUUID(),
+        mutations
+      });
+    }
+    return this.sendRPC(collectionId, {
+      type: `rpc:applyLocalMutations:req`,
+      rpcId: safeRandomUUID(),
+      envelopeId: safeRandomUUID(),
+      mutations
+    });
+  }
+  async requestApplyCommittedTx(collectionId, tx, scopedAdapter) {
+    const initialRoute = this.waitForInitialRoute(collectionId);
+    if (initialRoute) await initialRoute;
+    const request = {
+      type: `rpc:applyCommittedTx:req`,
+      rpcId: safeRandomUUID(),
+      envelopeId: safeRandomUUID(),
+      tx
+    };
+    if (this.isLeader(collectionId)) {
+      return this.handleApplyCommittedTx(collectionId, request, scopedAdapter);
+    }
+    return this.sendRPC(collectionId, request);
+  }
+  async pullSince(collectionId, fromRowVersion, scopedAdapter) {
+    if (this.isLeader(collectionId)) {
+      return this.handlePullSince(
+        collectionId,
+        {
+          type: `rpc:pullSince:req`,
+          rpcId: safeRandomUUID(),
+          fromRowVersion
+        },
+        scopedAdapter
+      );
+    }
+    return this.sendRPC(collectionId, {
+      type: `rpc:pullSince:req`,
+      rpcId: safeRandomUUID(),
+      fromRowVersion
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    const disposedError = new Error(`coordinator disposed`);
+    this.rejectDisposed?.(disposedError);
+    this.rejectDisposed = null;
+    for (const acquisition of this.outboundRemoteSubsetAcquisitions.values()) {
+      this.cancelRemoteSubsetReplayRetry(acquisition);
+      this.postRemoteSubsetRelease(acquisition);
+    }
+    this.outboundRemoteSubsetAcquisitions.clear();
+    this.remoteSubsetIds.clear();
+    for (const [collectionId, state] of this.collections) {
+      this.releaseLeadership(collectionId, state);
+    }
+    for (const [, pending] of this.pendingRPCs) {
+      clearTimeout(pending.timer);
+      pending.reject(disposedError);
+    }
+    this.pendingRPCs.clear();
+    if (this.appliedEnvelopePruneTimer !== null) {
+      clearTimeout(this.appliedEnvelopePruneTimer);
+      this.appliedEnvelopePruneTimer = null;
+    }
+    this.channel.close();
+    this.collections.clear();
+    this.collectionAdapters.clear();
+    for (const collectionId of this.remoteSubsetOwners.keys()) {
+      this.releaseInboundRemoteSubsetAcquisitions(collectionId);
+    }
+    this.remoteSubsetOwners.clear();
+    this.inboundRemoteSubsetAcquisitions.clear();
+    this.releasedRemoteSubsetAcquisitionTimes.clear();
+    this.appliedEnvelopes.clear();
+    this.inFlightEnvelopes.clear();
+  }
+  // -----------------------------------------------------------------------
+  // Leadership via Web Locks
+  // -----------------------------------------------------------------------
+  getOrCreateCollectionState(collectionId) {
+    let state = this.collections.get(collectionId);
+    if (!state) {
+      state = {
+        participatesInLeadership: false,
+        isLeader: false,
+        leaderId: null,
+        lockAbortController: null,
+        heartbeatTimer: null,
+        latestTerm: 0,
+        latestSeq: 0,
+        latestRowVersion: 0,
+        subscribers: /* @__PURE__ */ new Set(),
+        routeWaiters: /* @__PURE__ */ new Set()
+      };
+      this.collections.set(collectionId, state);
+    }
+    return state;
+  }
+  ensureCollectionState(collectionId) {
+    const state = this.getOrCreateCollectionState(collectionId);
+    if (!state.participatesInLeadership) {
+      state.participatesInLeadership = true;
+      void this.acquireLeadership(collectionId, state);
+    }
+    return state;
+  }
+  async acquireLeadership(collectionId, state) {
+    if (this.disposed || !state.participatesInLeadership || state.isLeader) {
+      return;
+    }
+    const lockName = `tsdb:leader:${this.dbName}:${collectionId}`;
+    const abortController = new AbortController();
+    state.lockAbortController?.abort();
+    state.lockAbortController = abortController;
+    try {
+      await navigator.locks.request(
+        lockName,
+        { signal: abortController.signal },
+        async () => {
+          if (this.isDisposed() || !this.participatesInLeadership(state) || this.collections.get(collectionId) !== state) {
+            return;
+          }
+          try {
+            const adapter = this.requireAdapter(collectionId);
+            if (adapter.getStreamPosition) {
+              const pos = await adapter.getStreamPosition(collectionId);
+              state.latestTerm = pos.latestTerm;
+              state.latestSeq = pos.latestSeq;
+              state.latestRowVersion = pos.latestRowVersion;
+            }
+            if (this.isDisposed() || !this.participatesInLeadership(state) || this.collections.get(collectionId) !== state || abortController.signal.aborted || state.lockAbortController !== abortController) {
+              return;
+            }
+            state.latestTerm++;
+            state.isLeader = true;
+            state.leaderId = this.nodeId;
+            this.notifyRouteWaiters(state);
+            this.emitHeartbeat(collectionId, state);
+            void this.replayRemoteSubsetAcquisitions(collectionId);
+            state.heartbeatTimer = setInterval(() => {
+              this.emitHeartbeat(collectionId, state);
+            }, HEARTBEAT_INTERVAL_MS);
+            await new Promise((resolve) => {
+              const onAbort = () => {
+                abortController.signal.removeEventListener(`abort`, onAbort);
+                resolve();
+              };
+              if (abortController.signal.aborted) {
+                resolve();
+                return;
+              }
+              abortController.signal.addEventListener(`abort`, onAbort);
+            });
+          } finally {
+            this.releaseInboundRemoteSubsetAcquisitions(collectionId);
+            state.isLeader = false;
+            state.leaderId = null;
+            if (state.heartbeatTimer) {
+              clearInterval(state.heartbeatTimer);
+              state.heartbeatTimer = null;
+            }
+          }
+        }
+      );
+    } catch (error) {
+      if (error instanceof DOMException && error.name === `AbortError`) {
+        return;
+      }
+      console.warn(`Failed to acquire leadership for ${collectionId}:`, error);
+      if (!this.isDisposed() && this.participatesInLeadership(state) && this.collections.get(collectionId) === state) {
+        await sleep(LEADERSHIP_RETRY_DELAY_MS);
+      }
+    } finally {
+      if (state.lockAbortController === abortController) {
+        state.lockAbortController = null;
+      }
+    }
+    if (!this.isDisposed() && this.participatesInLeadership(state) && this.collections.get(collectionId) === state && state.lockAbortController === null) {
+      void this.acquireLeadership(collectionId, state);
+    }
+  }
+  waitForInitialRoute(collectionId) {
+    const state = this.collections.get(collectionId);
+    if (state?.participatesInLeadership && !state.isLeader && state.leaderId === null) {
+      this.channel.postMessage({
+        v: 1,
+        dbName: this.dbName,
+        collectionId,
+        senderId: this.nodeId,
+        ts: Date.now(),
+        payload: { type: `leader:routeRequest` }
+      });
+      return this.waitForLeadershipRoute(
+        collectionId,
+        state,
+        void 0,
+        RPC_TIMEOUT_MS
+      );
+    }
+    return void 0;
+  }
+  waitForLeadershipRoute(collectionId, state, signal, timeoutMs) {
+    if (state.isLeader || state.leaderId !== null) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      let timer;
+      const finish = () => {
+        state.routeWaiters?.delete(onRouteChange);
+        signal?.removeEventListener(`abort`, onAbort);
+        if (timer !== void 0) clearTimeout(timer);
+      };
+      const onAbort = () => {
+        finish();
+        reject(
+          new DOMException(`Remote subset acquisition aborted`, `AbortError`)
+        );
+      };
+      const onRouteChange = () => {
+        if (this.isDisposed() || !state.participatesInLeadership) {
+          finish();
+          reject(
+            new Error(
+              `${this.coordinatorName}: leadership route closed for collection "${collectionId}"`
+            )
+          );
+          return;
+        }
+        if (state.isLeader || state.leaderId !== null) {
+          finish();
+          resolve();
+        }
+      };
+      (state.routeWaiters ??= /* @__PURE__ */ new Set()).add(onRouteChange);
+      if (timeoutMs !== void 0) {
+        timer = setTimeout(() => {
+          finish();
+          reject(
+            new Error(
+              `${this.coordinatorName}: leadership route for collection "${collectionId}" timed out after ${timeoutMs}ms`
+            )
+          );
+        }, timeoutMs);
+      }
+      signal?.addEventListener(`abort`, onAbort, { once: true });
+      if (signal?.aborted) {
+        onAbort();
+      } else {
+        onRouteChange();
+      }
+    });
+  }
+  notifyRouteWaiters(state) {
+    for (const notify of Array.from(state.routeWaiters ?? [])) notify();
+  }
+  releaseLeadership(collectionId, state) {
+    this.releaseInboundRemoteSubsetAcquisitions(collectionId);
+    if (state.lockAbortController) {
+      state.lockAbortController.abort();
+      state.lockAbortController = null;
+    }
+    if (state.heartbeatTimer) {
+      clearInterval(state.heartbeatTimer);
+      state.heartbeatTimer = null;
+    }
+    state.isLeader = false;
+    state.leaderId = null;
+    this.notifyRouteWaiters(state);
+  }
+  releaseCollectionIfUnused(collectionId, state) {
+    if (state.subscribers.size > 0 || this.collections.get(collectionId) !== state) {
+      return;
+    }
+    this.releaseLeadership(collectionId, state);
+    this.collections.delete(collectionId);
+    this.collectionAdapters.delete(collectionId);
+    const prefix = `${JSON.stringify([collectionId]).slice(0, -1)},`;
+    for (const key of this.appliedEnvelopes.keys()) {
+      if (key.startsWith(prefix)) this.appliedEnvelopes.delete(key);
+    }
+    this.pruneAppliedEnvelopes();
+  }
+  postRemoteSubsetRelease(acquisition) {
+    if (acquisition.release) return;
+    const request = {
+      type: `rpc:releaseRemoteSubset:req`,
+      rpcId: safeRandomUUID(),
+      acquisitionId: acquisition.acquisitionId
+    };
+    if (this.isLeader(acquisition.collectionId)) {
+      void this.handleReleaseRemoteSubset(
+        acquisition.collectionId,
+        request,
+        this.nodeId
+      ).catch(() => {
+      });
+      return;
+    }
+    this.channel.postMessage({
+      v: 1,
+      dbName: this.dbName,
+      collectionId: acquisition.collectionId,
+      senderId: this.nodeId,
+      ts: Date.now(),
+      payload: request
+    });
+  }
+  cancelRemoteSubsetReplayRetry(acquisition) {
+    if (acquisition.retryTimer !== null) {
+      clearTimeout(acquisition.retryTimer);
+      acquisition.retryTimer = null;
+    }
+    acquisition.retryAttempts = 0;
+  }
+  scheduleRemoteSubsetReplayRetry(acquisition, error) {
+    const key = remoteSubsetAcquisitionKey(
+      acquisition.collectionId,
+      acquisition.acquisitionId
+    );
+    if (!(error instanceof RetryableRemoteSubsetAcquisitionError) || this.isDisposed() || this.outboundRemoteSubsetAcquisitions.get(key) !== acquisition || acquisition.releaseRequested || acquisition.retryTimer !== null || acquisition.retryAttempts >= REMOTE_SUBSET_REPLAY_RETRY_ATTEMPTS) {
+      return;
+    }
+    acquisition.retryAttempts++;
+    acquisition.retryTimer = setTimeout(() => {
+      acquisition.retryTimer = null;
+      if (this.isDisposed() || this.outboundRemoteSubsetAcquisitions.get(key) !== acquisition || acquisition.releaseRequested) {
+        return;
+      }
+      void this.acquireRemoteSubset(acquisition).catch((retryError) => {
+        this.scheduleRemoteSubsetReplayRetry(acquisition, retryError);
+      });
+    }, RPC_RETRY_DELAY_MS);
+  }
+  async replayRemoteSubsetAcquisitions(collectionId) {
+    if (this.isDisposed()) return;
+    const state = this.collections.get(collectionId);
+    const leaderId = state?.isLeader ? this.nodeId : state?.leaderId;
+    if (!leaderId) return;
+    const replays = [];
+    for (const acquisition of this.outboundRemoteSubsetAcquisitions.values()) {
+      if (acquisition.collectionId !== collectionId || acquisition.releaseRequested || !acquisition.forceReplay && acquisition.acquiredLeaderId === leaderId) {
+        continue;
+      }
+      if (acquisition.inFlight) {
+        acquisition.forceReplay = true;
+        continue;
+      }
+      acquisition.forceReplay = false;
+      replays.push(
+        this.acquireRemoteSubset(acquisition).catch((error) => {
+          this.scheduleRemoteSubsetReplayRetry(acquisition, error);
+        })
+      );
+    }
+    await Promise.all(replays);
+  }
+  emitHeartbeat(collectionId, state) {
+    const envelope = {
+      v: 1,
+      dbName: this.dbName,
+      collectionId,
+      senderId: this.nodeId,
+      ts: Date.now(),
+      payload: {
+        type: `leader:heartbeat`,
+        term: state.latestTerm,
+        leaderId: this.nodeId,
+        latestSeq: state.latestSeq,
+        latestRowVersion: state.latestRowVersion
+      }
+    };
+    this.channel.postMessage(envelope);
+  }
+  // -----------------------------------------------------------------------
+  // BroadcastChannel message handling
+  // -----------------------------------------------------------------------
+  onChannelMessage(data) {
+    if (!isProtocolEnvelope(data)) return;
+    const envelope = data;
+    if (envelope.senderId === this.nodeId) return;
+    const payload = envelope.payload;
+    if (!payload || typeof payload !== `object`) return;
+    const type = payload.type;
+    if (type === `leader:routeRequest`) {
+      const state2 = this.collections.get(envelope.collectionId);
+      if (state2?.isLeader) this.emitHeartbeat(envelope.collectionId, state2);
+      return;
+    }
+    if (type === `leader:heartbeat`) {
+      const heartbeat = payload;
+      if (typeof heartbeat.leaderId === `string` && typeof heartbeat.term === `number` && typeof heartbeat.latestSeq === `number` && typeof heartbeat.latestRowVersion === `number`) {
+        const state2 = this.getOrCreateCollectionState(envelope.collectionId);
+        if (heartbeat.term < state2.latestTerm) return;
+        const changedLeader = state2.leaderId !== heartbeat.leaderId;
+        state2.leaderId = heartbeat.leaderId;
+        state2.latestTerm = Math.max(state2.latestTerm, heartbeat.term);
+        state2.latestSeq = Math.max(state2.latestSeq, heartbeat.latestSeq);
+        state2.latestRowVersion = Math.max(
+          state2.latestRowVersion,
+          heartbeat.latestRowVersion
+        );
+        this.notifyRouteWaiters(state2);
+        if (changedLeader) {
+          void this.replayRemoteSubsetAcquisitions(envelope.collectionId);
+        }
+      }
+    }
+    if (type && type.endsWith(`:res`)) {
+      const rpcId = payload.rpcId;
+      if (rpcId && this.pendingRPCs.has(rpcId)) {
+        const pending = this.pendingRPCs.get(rpcId);
+        this.pendingRPCs.delete(rpcId);
+        clearTimeout(pending.timer);
+        pending.resolve(payload);
+        return;
+      }
+    }
+    if (type && type.endsWith(`:req`)) {
+      if (!isRPCRequest(payload)) return;
+      const collectionId = envelope.collectionId;
+      if (this.isLeader(collectionId)) {
+        void this.handleRPCRequest(collectionId, payload, envelope.senderId);
+      }
+      return;
+    }
+    const state = this.collections.get(envelope.collectionId);
+    if (state) {
+      for (const subscriber of state.subscribers) {
+        subscriber(envelope);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // RPC - Outbound (follower side)
+  // -----------------------------------------------------------------------
+  async sendRPC(collectionId, request) {
+    if (this.isDisposed()) throw new Error(`coordinator disposed`);
+    let lastError;
+    let firstTransportCause;
+    const mutationRequestType = isMutatingRPCRequest(request) ? request.type : void 0;
+    const mutationRoute = mutationRequestType ? this.captureMutationRoute(collectionId) : void 0;
+    for (let attempt = 0; attempt <= RPC_RETRY_ATTEMPTS; attempt++) {
+      if (attempt > 0) {
+        await Promise.race([
+          sleep(RPC_RETRY_DELAY_MS * attempt),
+          this.disposedPromise
+        ]);
+      }
+      if (this.isDisposed()) throw new Error(`coordinator disposed`);
+      if (mutationRoute && mutationRequestType && firstTransportCause !== void 0) {
+        this.assertMutationRouteUnchanged(
+          collectionId,
+          mutationRequestType,
+          mutationRoute,
+          firstTransportCause
+        );
+      }
+      if (this.isLeader(collectionId)) {
+        return await this.dispatchRPCRequest(
+          collectionId,
+          request,
+          this.nodeId
+        );
+      }
+      try {
+        return await this.sendRPCOnce(collectionId, request);
+      } catch (error) {
+        if (this.isDisposed()) throw error;
+        firstTransportCause ??= error;
+        if (mutationRoute && mutationRequestType) {
+          this.assertMutationRouteUnchanged(
+            collectionId,
+            mutationRequestType,
+            mutationRoute,
+            firstTransportCause
+          );
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+    }
+    throw lastError ?? new Error(`RPC failed after retries`);
+  }
+  captureMutationRoute(collectionId) {
+    const state = this.collections.get(collectionId);
+    return {
+      leaderId: state?.isLeader ? this.nodeId : state?.leaderId ?? null,
+      term: state?.latestTerm ?? null
+    };
+  }
+  assertMutationRouteUnchanged(collectionId, requestType, previous, cause) {
+    const current = this.captureMutationRoute(collectionId);
+    if (previous.leaderId !== null && previous.term !== null && current.leaderId === previous.leaderId && current.term === previous.term) {
+      return;
+    }
+    throw new IndeterminateCommitError({
+      collectionId,
+      requestType,
+      previousLeaderId: previous.leaderId,
+      previousTerm: previous.term,
+      currentLeaderId: current.leaderId,
+      currentTerm: current.term,
+      cause
+    });
+  }
+  sendRPCOnce(collectionId, request) {
+    return new Promise((resolve, reject) => {
+      const rpcId = request.rpcId;
+      const timer = setTimeout(() => {
+        this.pendingRPCs.delete(rpcId);
+        reject(
+          new Error(`RPC ${request.type} timed out after ${RPC_TIMEOUT_MS}ms`)
+        );
+      }, RPC_TIMEOUT_MS);
+      this.pendingRPCs.set(rpcId, {
+        resolve,
+        reject,
+        timer
+      });
+      const envelope = {
+        v: 1,
+        dbName: this.dbName,
+        collectionId,
+        senderId: this.nodeId,
+        ts: Date.now(),
+        payload: request
+      };
+      this.channel.postMessage(envelope);
+    });
+  }
+  // -----------------------------------------------------------------------
+  // RPC - Inbound (leader side)
+  // -----------------------------------------------------------------------
+  async handleRPCRequest(collectionId, request, requesterId) {
+    let response;
+    try {
+      response = await this.dispatchRPCRequest(
+        collectionId,
+        request,
+        requesterId
+      );
+    } catch (error) {
+      response = createRPCErrorResponse(request, error);
+    }
+    if (this.isDisposed()) {
+      return;
+    }
+    const envelope = {
+      v: 1,
+      dbName: this.dbName,
+      collectionId,
+      senderId: this.nodeId,
+      ts: Date.now(),
+      payload: response
+    };
+    this.channel.postMessage(envelope);
+  }
+  dispatchRPCRequest(collectionId, request, requesterId) {
+    switch (request.type) {
+      case `rpc:ensureRemoteSubset:req`:
+        return this.handleEnsureRemoteSubset(collectionId, request, requesterId);
+      case `rpc:releaseRemoteSubset:req`:
+        return this.handleReleaseRemoteSubset(
+          collectionId,
+          request,
+          requesterId
+        );
+      case `rpc:ensurePersistedIndex:req`:
+        return this.handleEnsurePersistedIndex(collectionId, request);
+      case `rpc:applyLocalMutations:req`:
+        return this.handleApplyLocalMutations(collectionId, request);
+      case `rpc:applyCommittedTx:req`:
+        return this.handleApplyCommittedTx(collectionId, request);
+      case `rpc:pullSince:req`:
+        return this.handlePullSince(collectionId, request);
+    }
+  }
+  async handleEnsureRemoteSubset(collectionId, request, requesterId, localOptions) {
+    this.pruneReleasedRemoteSubsetAcquisitions();
+    const key = inboundRemoteSubsetAcquisitionKey(
+      collectionId,
+      requesterId,
+      request.acquisitionId
+    );
+    const existing = this.inboundRemoteSubsetAcquisitions.get(key);
+    const awaitingOwner = existing && `awaitingOwner` in existing ? existing : void 0;
+    if (existing) {
+      if (`owner` in existing) {
+        if (!existing.released) {
+          await existing.load;
+          return {
+            type: `rpc:ensureRemoteSubset:res`,
+            rpcId: request.rpcId,
+            ok: true,
+            leaderId: this.nodeId
+          };
+        }
+        await existing.release;
+        if (existing.terminalRelease) {
+          return {
+            type: `rpc:ensureRemoteSubset:res`,
+            rpcId: request.rpcId,
+            ok: true,
+            leaderId: this.nodeId
+          };
+        }
+        if (this.inboundRemoteSubsetAcquisitions.get(key) === existing) {
+          this.inboundRemoteSubsetAcquisitions.delete(key);
+        }
+      } else if (!(`awaitingOwner` in existing)) {
+        return {
+          type: `rpc:ensureRemoteSubset:res`,
+          rpcId: request.rpcId,
+          ok: true,
+          leaderId: this.nodeId
+        };
+      }
+    }
+    const owner = this.remoteSubsetOwners.get(collectionId);
+    if (!owner) {
+      throw new RetryableRemoteSubsetAcquisitionError(
+        `${this.coordinatorName}: no remote subset owner registered for collection "${collectionId}"`
+      );
+    }
+    await this.startRemoteSubsetOwnerAcquisition({
+      collectionId,
+      requesterId,
+      acquisitionId: request.acquisitionId,
+      owner,
+      options: awaitingOwner?.options ?? localOptions ?? request.options,
+      restoreOnSynchronousFailure: awaitingOwner
+    });
+    return {
+      type: `rpc:ensureRemoteSubset:res`,
+      rpcId: request.rpcId,
+      ok: true,
+      leaderId: this.nodeId
+    };
+  }
+  async handleReleaseRemoteSubset(collectionId, request, requesterId) {
+    this.pruneReleasedRemoteSubsetAcquisitions();
+    const key = inboundRemoteSubsetAcquisitionKey(
+      collectionId,
+      requesterId,
+      request.acquisitionId
+    );
+    const acquisition = this.inboundRemoteSubsetAcquisitions.get(key);
+    if (!acquisition) {
+      this.setReleasedRemoteSubsetAcquisition(key, {
+        collectionId,
+        requesterId,
+        acquisitionId: request.acquisitionId,
+        released: true
+      });
+    } else if (`owner` in acquisition) {
+      acquisition.terminalRelease = true;
+      try {
+        await this.releaseRemoteSubsetAcquisition(acquisition);
+      } finally {
+        if (this.inboundRemoteSubsetAcquisitions.get(key) === acquisition) {
+          this.setReleasedRemoteSubsetAcquisition(key, {
+            collectionId,
+            requesterId,
+            acquisitionId: request.acquisitionId,
+            released: true
+          });
+        }
+      }
+    } else if (`awaitingOwner` in acquisition) {
+      this.setReleasedRemoteSubsetAcquisition(key, {
+        collectionId,
+        requesterId,
+        acquisitionId: request.acquisitionId,
+        released: true
+      });
+    }
+    return {
+      type: `rpc:releaseRemoteSubset:res`,
+      rpcId: request.rpcId,
+      ok: true
+    };
+  }
+  releaseRemoteSubsetAcquisition(acquisition) {
+    if (acquisition.release) return acquisition.release;
+    acquisition.released = true;
+    acquisition.release = (async () => {
+      try {
+        await acquisition.load;
+      } catch {
+      }
+      try {
+        if (acquisition.transferred) {
+          await unloadRemoteSubsetOwner(acquisition.owner, acquisition.options);
+        }
+      } finally {
+        if (!acquisition.terminalRelease) {
+          const key = inboundRemoteSubsetAcquisitionKey(
+            acquisition.collectionId,
+            acquisition.requesterId,
+            acquisition.acquisitionId
+          );
+          if (this.inboundRemoteSubsetAcquisitions.get(key) === acquisition) {
+            this.inboundRemoteSubsetAcquisitions.set(key, {
+              collectionId: acquisition.collectionId,
+              requesterId: acquisition.requesterId,
+              acquisitionId: acquisition.acquisitionId,
+              options: acquisition.options,
+              released: true,
+              awaitingOwner: true
+            });
+          }
+        }
+      }
+    })();
+    return acquisition.release;
+  }
+  releaseInboundRemoteSubsetAcquisitions(collectionId, owner) {
+    for (const acquisition of this.inboundRemoteSubsetAcquisitions.values()) {
+      if (!(`owner` in acquisition) || acquisition.collectionId !== collectionId || owner && acquisition.owner !== owner) {
+        continue;
+      }
+      void this.releaseRemoteSubsetAcquisition(acquisition).catch(
+        () => void 0
+      );
+    }
+  }
+  rebindRemoteInboundSubsetAcquisitions(collectionId, owner) {
+    for (const acquisition of this.inboundRemoteSubsetAcquisitions.values()) {
+      if (`awaitingOwner` in acquisition) {
+        if (acquisition.collectionId === collectionId && acquisition.requesterId !== this.nodeId) {
+          void this.bindAwaitingRemoteSubsetAcquisition(
+            acquisition,
+            owner
+          ).catch(() => {
+          });
+        }
+        continue;
+      }
+      if (!(`owner` in acquisition) || acquisition.collectionId !== collectionId || acquisition.requesterId === this.nodeId || !acquisition.released || acquisition.terminalRelease) {
+        continue;
+      }
+      void this.rebindRemoteInboundSubsetAcquisition(acquisition, owner).catch(
+        () => void 0
+      );
+    }
+  }
+  async rebindRemoteInboundSubsetAcquisition(previous, owner) {
+    await previous.release;
+    if (previous.terminalRelease || this.remoteSubsetOwners.get(previous.collectionId) !== owner) {
+      return;
+    }
+    const key = inboundRemoteSubsetAcquisitionKey(
+      previous.collectionId,
+      previous.requesterId,
+      previous.acquisitionId
+    );
+    const current = this.inboundRemoteSubsetAcquisitions.get(key);
+    if (current && current !== previous) {
+      if (`awaitingOwner` in current) {
+        await this.bindAwaitingRemoteSubsetAcquisition(current, owner);
+      }
+      return;
+    }
+    const awaitingOwner = {
+      collectionId: previous.collectionId,
+      requesterId: previous.requesterId,
+      acquisitionId: previous.acquisitionId,
+      options: previous.options,
+      released: true,
+      awaitingOwner: true
+    };
+    this.inboundRemoteSubsetAcquisitions.set(key, awaitingOwner);
+    await this.bindAwaitingRemoteSubsetAcquisition(awaitingOwner, owner);
+  }
+  async bindAwaitingRemoteSubsetAcquisition(awaitingOwner, owner) {
+    if (this.remoteSubsetOwners.get(awaitingOwner.collectionId) !== owner) {
+      return;
+    }
+    const key = inboundRemoteSubsetAcquisitionKey(
+      awaitingOwner.collectionId,
+      awaitingOwner.requesterId,
+      awaitingOwner.acquisitionId
+    );
+    if (this.inboundRemoteSubsetAcquisitions.get(key) !== awaitingOwner) return;
+    await this.startRemoteSubsetOwnerAcquisition({
+      collectionId: awaitingOwner.collectionId,
+      requesterId: awaitingOwner.requesterId,
+      acquisitionId: awaitingOwner.acquisitionId,
+      owner,
+      options: awaitingOwner.options,
+      restoreOnSynchronousFailure: awaitingOwner
+    });
+  }
+  async startRemoteSubsetOwnerAcquisition(options) {
+    const key = inboundRemoteSubsetAcquisitionKey(
+      options.collectionId,
+      options.requesterId,
+      options.acquisitionId
+    );
+    const acquisition = {
+      collectionId: options.collectionId,
+      requesterId: options.requesterId,
+      acquisitionId: options.acquisitionId,
+      owner: options.owner,
+      options: options.options,
+      load: Promise.resolve(),
+      transferred: false,
+      released: false,
+      terminalRelease: false,
+      release: null
+    };
+    this.releasedRemoteSubsetAcquisitionTimes.delete(key);
+    this.inboundRemoteSubsetAcquisitions.set(key, acquisition);
+    let resolveLoad;
+    let rejectLoad;
+    acquisition.load = new Promise((resolve, reject) => {
+      resolveLoad = resolve;
+      rejectLoad = reject;
+    });
+    try {
+      const load = options.owner(acquisition.options);
+      acquisition.transferred = true;
+      void Promise.resolve(load).then(resolveLoad, rejectLoad);
+    } catch (error) {
+      rejectLoad(error);
+    }
+    try {
+      await acquisition.load;
+    } catch (error) {
+      if (!acquisition.transferred) {
+        if (this.inboundRemoteSubsetAcquisitions.get(key) === acquisition) {
+          if (options.restoreOnSynchronousFailure) {
+            this.inboundRemoteSubsetAcquisitions.set(
+              key,
+              options.restoreOnSynchronousFailure
+            );
+          } else {
+            this.inboundRemoteSubsetAcquisitions.delete(key);
+          }
+        }
+      } else {
+        await this.releaseRemoteSubsetAcquisition(acquisition).catch(
+          () => void 0
+        );
+      }
+      throw error;
+    }
+  }
+  async handleEnsurePersistedIndex(collectionId, request) {
+    await this.withScheduledWriterLock(
+      collectionId,
+      (adapter) => adapter.ensureIndex(collectionId, request.signature, request.spec)
+    );
+    return {
+      type: `rpc:ensurePersistedIndex:res`,
+      rpcId: request.rpcId,
+      ok: true
+    };
+  }
+  async handleApplyLocalMutations(collectionId, request) {
+    const envelopeKey = appliedEnvelopeKey(collectionId, request.envelopeId);
+    return this.runDeduplicatedEnvelope({
+      envelopeKey,
+      rpcId: request.rpcId,
+      selectApplied: (envelope) => envelope.requestType === `rpc:applyLocalMutations:req` ? envelope.response : void 0,
+      selectInFlight: (envelope) => envelope.requestType === `rpc:applyLocalMutations:req` ? envelope.response : void 0,
+      conflict: (phase) => ({
+        type: `rpc:applyLocalMutations:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `CONFLICT`,
+        error: `envelope ${request.envelopeId} ${phase}`
+      }),
+      apply: () => this.applyLocalMutationsOnce(collectionId, request),
+      createPending: (response) => ({
+        requestType: request.type,
+        response
+      })
+    });
+  }
+  async applyLocalMutationsOnce(collectionId, request) {
+    const state = this.collections.get(collectionId);
+    if (!state || !state.isLeader) {
+      return {
+        type: `rpc:applyLocalMutations:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `NOT_LEADER`,
+        error: `not the leader for ${collectionId}`
+      };
+    }
+    const rowMetadataMutations = [];
+    for (const mutation of request.mutations) {
+      if (!(`metadataChanged` in mutation) || !mutation.metadataChanged) {
+        continue;
+      }
+      rowMetadataMutations.push(
+        mutation.metadata === void 0 ? { type: `delete`, key: mutation.key } : {
+          type: `set`,
+          key: mutation.key,
+          value: mutation.metadata
+        }
+      );
+    }
+    const pendingTx = {
+      txId: safeRandomUUID(),
+      mutations: request.mutations.map((m) => ({
+        type: m.type,
+        key: m.key,
+        value: m.value,
+        ...`metadataChanged` in m ? { metadata: m.metadata, metadataChanged: m.metadataChanged } : {}
+      })),
+      rowMetadataMutations
+    };
+    const tx = await this.applyDurablyAtNextStreamPosition(
+      collectionId,
+      state,
+      pendingTx
+    );
+    if (tx === null) {
+      return {
+        type: `rpc:applyLocalMutations:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `NOT_LEADER`,
+        error: `not the leader for ${collectionId}`
+      };
+    }
+    const response = {
+      type: `rpc:applyLocalMutations:res`,
+      rpcId: request.rpcId,
+      ok: true,
+      term: tx.term,
+      seq: tx.seq,
+      latestRowVersion: tx.rowVersion,
+      acceptedMutationIds: request.mutations.map((m) => m.mutationId)
+    };
+    if (this.isDisposed() || this.collections.get(collectionId) !== state) {
+      return response;
+    }
+    this.appliedEnvelopes.set(
+      appliedEnvelopeKey(collectionId, request.envelopeId),
+      {
+        appliedAt: Date.now(),
+        requestType: request.type,
+        response
+      }
+    );
+    this.pruneAppliedEnvelopes();
+    const changedRows = request.mutations.filter((m) => m.type !== `delete`).map((m) => ({ key: m.key, value: m.value }));
+    const deletedKeys = request.mutations.filter((m) => m.type === `delete`).map((m) => m.key);
+    const txCommitted = {
+      v: 1,
+      dbName: this.dbName,
+      collectionId,
+      senderId: this.nodeId,
+      ts: Date.now(),
+      payload: {
+        type: `tx:committed`,
+        term: tx.term,
+        seq: tx.seq,
+        txId: tx.txId,
+        latestRowVersion: tx.rowVersion,
+        requiresFullReload: false,
+        changedRows,
+        deletedKeys,
+        rowMetadataMutations
+      }
+    };
+    this.channel.postMessage(txCommitted);
+    for (const subscriber of state.subscribers) {
+      subscriber(txCommitted);
+    }
+    return response;
+  }
+  async handleApplyCommittedTx(collectionId, request, scopedAdapter) {
+    const envelopeKey = appliedEnvelopeKey(collectionId, request.envelopeId);
+    return this.runDeduplicatedEnvelope({
+      envelopeKey,
+      rpcId: request.rpcId,
+      selectApplied: (envelope) => envelope.requestType === `rpc:applyCommittedTx:req` ? envelope.response : void 0,
+      selectInFlight: (envelope) => envelope.requestType === `rpc:applyCommittedTx:req` ? envelope.response : void 0,
+      conflict: (phase) => ({
+        type: `rpc:applyCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `CONFLICT`,
+        error: `envelope ${request.envelopeId} ${phase}`
+      }),
+      apply: () => this.applyCommittedTxOnce(collectionId, request, scopedAdapter),
+      createPending: (response) => ({
+        requestType: request.type,
+        response
+      })
+    });
+  }
+  async runDeduplicatedEnvelope(options) {
+    const appliedEnvelope = this.appliedEnvelopes.get(options.envelopeKey);
+    if (appliedEnvelope) {
+      const response2 = options.selectApplied(appliedEnvelope);
+      return response2 ? { ...response2, rpcId: options.rpcId } : options.conflict(`already applied`);
+    }
+    const inFlightEnvelope = this.inFlightEnvelopes.get(options.envelopeKey);
+    if (inFlightEnvelope) {
+      const pending = options.selectInFlight(inFlightEnvelope);
+      if (!pending) return options.conflict(`is already in flight`);
+      const response2 = await pending;
+      return { ...response2, rpcId: options.rpcId };
+    }
+    const response = options.apply();
+    const pendingEnvelope = options.createPending(response);
+    this.inFlightEnvelopes.set(options.envelopeKey, pendingEnvelope);
+    try {
+      return await response;
+    } finally {
+      if (this.inFlightEnvelopes.get(options.envelopeKey) === pendingEnvelope) {
+        this.inFlightEnvelopes.delete(options.envelopeKey);
+      }
+    }
+  }
+  async applyCommittedTxOnce(collectionId, request, scopedAdapter) {
+    const state = this.collections.get(collectionId);
+    if (!state || !state.isLeader) {
+      return {
+        type: `rpc:applyCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `NOT_LEADER`,
+        error: `not the leader for ${collectionId}`
+      };
+    }
+    const tx = await this.applyDurablyAtNextStreamPosition(
+      collectionId,
+      state,
+      request.tx,
+      scopedAdapter
+    );
+    if (tx === null) {
+      return {
+        type: `rpc:applyCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `NOT_LEADER`,
+        error: `not the leader for ${collectionId}`
+      };
+    }
+    const response = {
+      type: `rpc:applyCommittedTx:res`,
+      rpcId: request.rpcId,
+      ok: true,
+      term: tx.term,
+      seq: tx.seq,
+      latestRowVersion: tx.rowVersion
+    };
+    if (this.isDisposed() || this.collections.get(collectionId) !== state) {
+      return response;
+    }
+    this.appliedEnvelopes.set(
+      appliedEnvelopeKey(collectionId, request.envelopeId),
+      {
+        appliedAt: Date.now(),
+        requestType: request.type,
+        response
+      }
+    );
+    this.pruneAppliedEnvelopes();
+    const committedBase = {
+      type: `tx:committed`,
+      term: tx.term,
+      seq: tx.seq,
+      txId: tx.txId,
+      latestRowVersion: tx.rowVersion
+    };
+    const committedPayload = tx.truncate ? {
+      ...committedBase,
+      requiresFullReload: true
+    } : {
+      ...committedBase,
+      requiresFullReload: false,
+      changedRows: tx.mutations.filter((mutation) => mutation.type !== `delete`).map((mutation) => ({
+        key: mutation.key,
+        value: mutation.value
+      })),
+      deletedKeys: tx.mutations.filter((mutation) => mutation.type === `delete`).map((mutation) => mutation.key),
+      rowMetadataMutations: tx.rowMetadataMutations,
+      collectionMetadataMutations: tx.collectionMetadataMutations
+    };
+    const committed = {
+      v: 1,
+      dbName: this.dbName,
+      collectionId,
+      senderId: this.nodeId,
+      ts: Date.now(),
+      payload: committedPayload
+    };
+    this.channel.postMessage(committed);
+    for (const subscriber of state.subscribers) {
+      subscriber(committed);
+    }
+    return response;
+  }
+  async applyDurablyAtNextStreamPosition(collectionId, state, pendingTx, scopedAdapter) {
+    const expectedTerm = state.latestTerm;
+    return this.withScheduledWriterLock(
+      collectionId,
+      async (adapter) => {
+        if (this.isDisposed() || this.collections.get(collectionId) !== state || !state.isLeader || state.leaderId !== this.nodeId || state.latestTerm !== expectedTerm) {
+          return null;
+        }
+        const tx = {
+          ...pendingTx,
+          term: state.latestTerm,
+          seq: state.latestSeq + 1,
+          rowVersion: state.latestRowVersion + 1
+        };
+        try {
+          await adapter.applyCommittedTx(collectionId, tx);
+        } catch (error) {
+          throw toPersistedCollectionDurabilityError(collectionId, error);
+        }
+        state.latestSeq = tx.seq;
+        state.latestRowVersion = tx.rowVersion;
+        return tx;
+      },
+      scopedAdapter
+    );
+  }
+  async handlePullSince(collectionId, request, scopedAdapter) {
+    const state = this.collections.get(collectionId);
+    const adapter = scopedAdapter ?? this.requireAdapter(collectionId);
+    if (!adapter.pullSince) {
+      return {
+        type: `rpc:pullSince:res`,
+        rpcId: request.rpcId,
+        ok: true,
+        latestTerm: state?.latestTerm ?? 0,
+        latestSeq: state?.latestSeq ?? 0,
+        latestRowVersion: state?.latestRowVersion ?? 0,
+        requiresFullReload: true
+      };
+    }
+    const result = await adapter.pullSince(collectionId, request.fromRowVersion);
+    if (result.requiresFullReload) {
+      return {
+        type: `rpc:pullSince:res`,
+        rpcId: request.rpcId,
+        ok: true,
+        latestTerm: state?.latestTerm ?? 0,
+        latestSeq: state?.latestSeq ?? 0,
+        latestRowVersion: result.latestRowVersion,
+        requiresFullReload: true
+      };
+    }
+    return {
+      type: `rpc:pullSince:res`,
+      rpcId: request.rpcId,
+      ok: true,
+      latestTerm: state?.latestTerm ?? 0,
+      latestSeq: state?.latestSeq ?? 0,
+      latestRowVersion: result.latestRowVersion,
+      requiresFullReload: false,
+      changedKeys: result.changedKeys,
+      deletedKeys: result.deletedKeys
+    };
+  }
+  // -----------------------------------------------------------------------
+  // DB Writer Lock
+  // -----------------------------------------------------------------------
+  withScheduledWriterLock(collectionId, task, scopedAdapter) {
+    if (scopedAdapter) {
+      return this.withWriterLock(() => task(scopedAdapter));
+    }
+    const adapter = this.requireAdapter(collectionId);
+    return adapter.runInRegularScope ? adapter.runInRegularScope(
+      (unscheduledAdapter) => this.withWriterLock(() => task(unscheduledAdapter))
+    ) : this.withWriterLock(() => task(adapter));
+  }
+  async withWriterLock(fn) {
+    const lockName = `tsdb:writer:${this.dbName}`;
+    for (let attempt = 0; attempt <= WRITER_LOCK_MAX_RETRIES; attempt++) {
+      const callbackState = { entered: false };
+      try {
+        return await navigator.locks.request(lockName, async () => {
+          callbackState.entered = true;
+          return fn();
+        });
+      } catch (error) {
+        if (callbackState.entered) {
+          throw error;
+        }
+        if (error instanceof DOMException && error.name === `AbortError`) {
+          throw error;
+        }
+        if (attempt < WRITER_LOCK_MAX_RETRIES) {
+          await sleep(WRITER_LOCK_BUSY_RETRY_MS * Math.min(attempt + 1, 5));
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error(`writer lock acquisition failed`);
+  }
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+  pruneAppliedEnvelopes() {
+    if (this.appliedEnvelopePruneTimer !== null) {
+      clearTimeout(this.appliedEnvelopePruneTimer);
+      this.appliedEnvelopePruneTimer = null;
+    }
+    const cutoff = Date.now() - RPC_DEDUPE_RETENTION_MS;
+    for (const [key, envelope] of this.appliedEnvelopes) {
+      if (envelope.appliedAt <= cutoff) {
+        this.appliedEnvelopes.delete(key);
+      }
+    }
+    if (this.disposed || this.appliedEnvelopes.size === 0) return;
+    let earliestAppliedAt = Number.POSITIVE_INFINITY;
+    for (const envelope of this.appliedEnvelopes.values()) {
+      earliestAppliedAt = Math.min(earliestAppliedAt, envelope.appliedAt);
+    }
+    const delay = Math.max(
+      0,
+      earliestAppliedAt + RPC_DEDUPE_RETENTION_MS - Date.now()
+    );
+    this.appliedEnvelopePruneTimer = setTimeout(() => {
+      this.appliedEnvelopePruneTimer = null;
+      this.pruneAppliedEnvelopes();
+    }, delay);
+  }
+  setReleasedRemoteSubsetAcquisition(key, acquisition) {
+    this.inboundRemoteSubsetAcquisitions.set(key, acquisition);
+    this.releasedRemoteSubsetAcquisitionTimes.set(key, Date.now());
+  }
+  pruneReleasedRemoteSubsetAcquisitions() {
+    const cutoff = Date.now() - RPC_DEDUPE_RETENTION_MS;
+    for (const [key, releasedAt] of this.releasedRemoteSubsetAcquisitionTimes) {
+      if (releasedAt < cutoff) {
+        this.releasedRemoteSubsetAcquisitionTimes.delete(key);
+        this.inboundRemoteSubsetAcquisitions.delete(key);
+      }
+    }
+  }
+}
+function isProtocolEnvelope(data) {
+  if (!data || typeof data !== `object`) return false;
+  const record = data;
+  return record.v === 1 && typeof record.dbName === `string` && typeof record.collectionId === `string` && typeof record.senderId === `string` && typeof record.ts === `number`;
+}
+function isRPCRequest(payload) {
+  if (!payload || typeof payload !== `object`) return false;
+  switch (payload.type) {
+    case `rpc:ensureRemoteSubset:req`:
+    case `rpc:releaseRemoteSubset:req`:
+    case `rpc:ensurePersistedIndex:req`:
+    case `rpc:applyLocalMutations:req`:
+    case `rpc:applyCommittedTx:req`:
+    case `rpc:pullSince:req`:
+      return true;
+    default:
+      return false;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function appliedEnvelopeKey(collectionId, envelopeId) {
+  return JSON.stringify([collectionId, envelopeId]);
+}
+function remoteSubsetAcquisitionKey(collectionId, acquisitionId) {
+  return JSON.stringify([collectionId, acquisitionId]);
+}
+function inboundRemoteSubsetAcquisitionKey(collectionId, requesterId, acquisitionId) {
+  return JSON.stringify([collectionId, requesterId, acquisitionId]);
+}
+function createRPCErrorResponse(request, cause) {
+  const error = cause instanceof Error ? cause.message : String(cause);
+  switch (request.type) {
+    case `rpc:ensureRemoteSubset:req`:
+      return {
+        type: `rpc:ensureRemoteSubset:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        error,
+        ...cause instanceof RetryableRemoteSubsetAcquisitionError ? { retryable: true } : {}
+      };
+    case `rpc:releaseRemoteSubset:req`:
+      return {
+        type: `rpc:releaseRemoteSubset:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        error
+      };
+    case `rpc:ensurePersistedIndex:req`:
+      return {
+        type: `rpc:ensurePersistedIndex:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        error
+      };
+    case `rpc:applyLocalMutations:req`:
+      if (cause instanceof PersistedCollectionDurabilityError) {
+        return {
+          type: `rpc:applyLocalMutations:res`,
+          rpcId: request.rpcId,
+          ok: false,
+          code: `PERSISTENCE_ERROR`,
+          error,
+          ...toSafeDurabilityDetails(cause)
+        };
+      }
+      return {
+        type: `rpc:applyLocalMutations:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `CONFLICT`,
+        error
+      };
+    case `rpc:applyCommittedTx:req`:
+      if (cause instanceof PersistedCollectionDurabilityError) {
+        return {
+          type: `rpc:applyCommittedTx:res`,
+          rpcId: request.rpcId,
+          ok: false,
+          code: `PERSISTENCE_ERROR`,
+          error,
+          ...toSafeDurabilityDetails(cause)
+        };
+      }
+      return {
+        type: `rpc:applyCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `CONFLICT`,
+        error
+      };
+    case `rpc:pullSince:req`:
+      return {
+        type: `rpc:pullSince:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        error
+      };
+  }
+}
+function isMutatingRPCRequest(request) {
+  return request.type === `rpc:applyLocalMutations:req` || request.type === `rpc:applyCommittedTx:req`;
+}
+function toSafeDurabilityDetails(error) {
+  const sourceCode = typeof error.code === `string` || typeof error.code === `number` ? error.code : void 0;
+  const path = typeof error.path === `string` || Array.isArray(error.path) && error.path.every(
+    (part) => typeof part === `string` || typeof part === `number`
+  ) ? error.path : void 0;
+  return {
+    ...sourceCode === void 0 ? {} : { sourceCode },
+    ...path === void 0 ? {} : { path }
+  };
+}
+export {
+  BroadcastCollectionCoordinator
+};
+//# sourceMappingURL=broadcast-coordinator.js.map