@pylonsync/sync 0.3.202 → 0.3.203

package/src/index.ts

@@ -14,7 +14,18 @@ import {
   type TransportConfig,
 } from "./transport";
 import { LocalStore } from "./local-store";
-import { MutationQueue } from "./mutation-queue";
+import { MutationQueue, type PendingMutation } from "./mutation-queue";
+import { MultiTabOrchestrator } from "./multi-tab-orchestrator";
+import { OpQueue } from "./op-queue";
+import { ServerSubscriptions } from "./server-subscriptions";
+import { SessionResolver } from "./session-resolver";
+import { SubscriptionCoordinator } from "./subscription-coordinator";
+import {
+  createTransport,
+  type Transport,
+  type TransportHost,
+  type TransportKind,
+} from "./transports";
 import { generateClientId, generateId } from "./ids";
 export { IndexedDBPersistence, persistChange } from "./persistence";
 export {
@@ -126,6 +137,15 @@ export interface SyncEngineConfig {
    * edge proxy to forward to the dual-thread listener instead.
    */
   pingIntervalMs?: number;
+  /**
+   * Multi-tab coordination via BroadcastChannel. When multiple tabs of
+   * the same origin run the engine, one is elected leader and owns
+   * the WebSocket, pull/push/reconcile, and IndexedDB writes;
+   * follower tabs mirror state via cross-tab broadcasts. Default
+   * `true` in browsers. Set `false` to force every tab to behave as
+   * its own leader (the pre-multi-tab semantics).
+   */
+  multiTab?: boolean;
 }
 
 /**
@@ -156,13 +176,13 @@ export class SyncEngine {
   private config: SyncEngineConfig;
   private cursor: SyncCursor = { last_seq: 0 };
   private running = false;
-  private ws: WebSocket | null = null;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Real-time transport — owns its own socket / timers / backoff.
+   *  The engine just calls start/stop/send and consumes inbound events
+   *  via the TransportHost callbacks (set up below in `transportHost`).
+   *  Constructed in start() because followers don't open a transport
+   *  at all and SSR-only consumers never reach start(). */
+  private transport: Transport | null = null;
   private _connectionStatus: SyncConnectionStatus = "offline";
-  /** Monotonic attempt counter for exponential backoff. Reset to 0 on a
-   *  successful connection so the next reconnect starts fresh rather than
-   *  inheriting the previous storm's cooldown. */
-  private reconnectAttempts = 0;
   private persistence: import("./persistence").IndexedDBPersistence | null = null;
 
   /**
@@ -203,38 +223,34 @@ export class SyncEngine {
    * changes — so the cursor from the previous identity is meaningless.
    * Compared on every pull; a mismatch triggers an automatic resync.
    *
-   * Uses `undefined` as the "never observed" sentinel so we can distinguish
-   * "first pull ever" from "explicitly anonymous". A first pull doesn't
-   * reset (nothing to reset), but every later transition — including
-   * null→token → does.
-   */
-  private lastSeenToken: string | null | undefined = undefined;
-
-  /**
-   * Latest server-resolved auth/session state. Refreshed on every pull()
-   * by fetching /api/auth/me in parallel. Exposed to consumers via
-   * `resolvedSession` so React hooks can subscribe via the store.
+   * Owns the resolved session, the last-seen token, the last-seen
+   * tenant, and the null→X / X→Y / token-flip verdicts that used to
+   * be inlined across pull / refresh / reconcile. The engine acts on
+   * the verdicts (reset, pull, notify); the resolver decides nothing
+   * on its own. See session-resolver.ts.
    *
-   * Subscribers re-render when this updates — we reuse the store's
-   * notifier rather than introduce a second pub/sub so every change the
-   * app cares about goes through one channel.
+   * Exposed (read-only) so tests and plugins can inspect or simulate
+   * identity transitions without re-implementing the comparison.
    */
-  private _resolvedSession: ResolvedSession = {
-    userId: null,
-    tenantId: null,
-    isAdmin: false,
-    roles: [],
-  };
-  private lastSeenTenant: string | null | undefined = undefined;
+  readonly session: SessionResolver = new SessionResolver();
 
   /**
-   * Timer for the "stable connection" check. On `onopen` we start a 5s
-   * timer; if the socket stays up that long we reset reconnectAttempts.
-   * If it closes first, the timer gets cleared and the backoff grows so
-   * the client can't hammer the server on auth failures.
-   */
-  private wsStableTimer: ReturnType<typeof setTimeout> | null = null;
-  private pingTimer: ReturnType<typeof setInterval> | null = null;
+   * Multi-tab orchestrator — owns the cross-tab protocol: broker
+   * lifecycle, election, inbound message dispatch, outbound broadcasts.
+   * Engine receives inbound events via hooks (see `multiTabHooks()`).
+   *
+   * Constructed lazily in `start()` because SSR-only consumers that
+   * never reach start() shouldn't pay for the broker. */
+  private orchestrator: MultiTabOrchestrator | null = null;
+  /** Mirror of `orchestrator.isLeader()` kept on the engine for the
+   *  many `if (this.isMultiTabLeader)` gates throughout the codebase.
+   *  Updated via the orchestrator's onInitialLeader / onLatePromote /
+   *  onDemote hooks. Defaults to false so a tab joining an existing
+   *  election stays a passive follower until the orchestrator
+   *  explicitly promotes us — a `true` default would let a late
+   *  joiner whose orchestrator never fires onPromote (because it was
+   *  never leader) silently run as a leader. */
+  private isMultiTabLeader = false;
 
   /**
    * Serialized apply queue. Every change-event apply — from WS onmessage,
@@ -247,6 +263,27 @@ export class SyncEngine {
    */
   private applyQueue: Promise<void> = Promise.resolve();
 
+  /**
+   * Serialized channel for outbound network ops (pull, push, reconcile,
+   * refresh, resetReplica). Replaces the per-op `inFlightX` mutexes +
+   * the fire-and-forget `void refreshResolvedSession()` calls that used
+   * to race against in-flight pulls and reconciles. Apply stays
+   * separate (see `applyQueue` above) so WS events don't block on a
+   * pull's HTTP round-trip.
+   */
+  private opQueue: OpQueue = new OpQueue();
+
+  /**
+   * Serialized chain for session-transition application. Multiple
+   * concurrent triggers (`refreshResolvedSession` from app code +
+   * a `session-changed` envelope landing over WS + a multi-tab
+   * `session` broadcast) all enqueue here. Without it, two
+   * inspect-then-commit pairs interleave on the microtask queue
+   * and the older session can commit AFTER the newer, leaving the
+   * engine pinned to a stale tenant.
+   */
+  private sessionChain: Promise<void> = Promise.resolve();
+
   /**
    * Registered consumers for binary WebSocket frames. SyncEngine itself
    * doesn't decode binary — it just owns the WS connection and routes
@@ -262,34 +299,23 @@ export class SyncEngine {
   private binaryHandlers: Set<(bytes: Uint8Array) => void> = new Set();
 
   /**
-   * Active CRDT subscriptions, keyed `${entity}\x00${rowId}`. Tracked
-   * here so a WS reconnect can re-send the same subscriptions to the
-   * fresh socket — the server clears its per-client subscription state
-   * on disconnect (in `WsHub::handle_ws_connection`'s Close path), so
-   * without re-sending the binary frames would stop arriving on the
-   * new connection.
-   *
-   * Refcount-aware via `crdtSubscribers` so two `useLoroDoc` callers on
-   * the same row don't unsubscribe each other when one unmounts.
+   * Server-side ephemeral subscriptions (CRDT row subs, reactive query
+   * subs, future kinds). Owns the WS replay bookkeeping — each kind
+   * registers the message that re-creates its server-side state, and
+   * `ws.onopen` replays the bundle on reconnect. Kind-specific concerns
+   * (CRDT refcount, reactive handler routing) stay below as their own
+   * maps. See server-subscriptions.ts.
    */
-  private crdtSubscriptions: Set<string> = new Set();
-  private crdtSubscribers: Map<string, number> = new Map();
+  private serverSubs!: ServerSubscriptions;
 
-  /**
-   * Reactive query subscriptions registered via `subscribeReactive`.
-   * Two maps:
-   *  - `reactiveSpecs`: sub_id → {fn_name, args} for re-registration
-   *    on WS reconnect. Server-side state evaporates on disconnect.
-   *  - `reactiveHandlers`: sub_id → handler that receives result + error
-   *    pushes. The React hook owns these handlers and unsubscribes on
-   *    unmount.
-   *
-   * Both maps are keyed by the same client-minted `sub_id` so they
-   * stay in sync. Cleared together by `unsubscribeReactive`.
-   */
-  private reactiveSpecs: Map<string, ReactiveSpec> = new Map();
-  private reactiveHandlers: Map<string, (msg: ReactiveMessage) => void> =
-    new Map();
+  /** Coordinator for every "this tab wants live updates" subscription —
+   *  CRDT row subs + reactive query subs, leader bookkeeping + follower
+   *  forwarding. The engine delegates `subscribeCrdt` / `unsubscribeCrdt`
+   *  / `subscribeReactive` / `unsubscribeReactive` to it, and routes
+   *  inbound multi-tab `sub-register` / `sub-unregister` / `reactive-msg`
+   *  envelopes through it. Constructed lazily in start() because
+   *  serverSubs isn't built until then. */
+  private subscriptions!: SubscriptionCoordinator;
 
   /**
    * Listeners notified when the server signals a per-subscriber row
@@ -319,7 +345,7 @@ export class SyncEngine {
 
   /** Read the cached resolved session. Null user = anonymous. */
   resolvedSession(): ResolvedSession {
-    return this._resolvedSession;
+    return this.session.resolved();
   }
 
   /**
@@ -352,6 +378,22 @@ export class SyncEngine {
     this.mutations = new MutationQueue();
     this.storage = config.storage ?? defaultStorage();
     this.clientId = generateClientId(this.storage);
+    // ServerSubscriptions defers sending until the WS is open (the
+    // sendWs helper short-circuits otherwise) so registering before
+    // start() is safe — the spec gets replayed on `ws.onopen`.
+    this.serverSubs = new ServerSubscriptions((msg) => this.sendWs(msg));
+    this.subscriptions = new SubscriptionCoordinator(this.serverSubs, {
+      isLeader: () => this.isMultiTabLeader,
+      broadcastToTabs: (payload) => this.broadcastToTabs(payload),
+    });
+    // When multi-tab coordination is explicitly disabled, this engine
+    // is always its own sole leader — even before start(). Tests that
+    // construct an engine and call reconcile()/pull() directly without
+    // start() rely on this. The dynamic election paths (broker-driven
+    // promote/demote) only matter when multiTab is enabled.
+    if (this.config.multiTab === false) {
+      this.isMultiTabLeader = true;
+    }
   }
 
   /**
@@ -465,10 +507,33 @@ export class SyncEngine {
     // into a permanent "Loading…" state.
     this._hydrated = true;
 
+    // Multi-tab coordination: elect a leader before deciding whether
+    // to open the WS / pull / poll. Followers stay passive and mirror
+    // applied changes broadcast by the leader. The election settles
+    // in ~250ms; if the broker is unavailable (no BroadcastChannel)
+    // every tab is implicitly its own leader.
+    await this.initMultiTab();
+
+    if (!this.isMultiTabLeader) {
+      // Follower path: rely on the leader's broadcasts for session +
+      // applied changes. Nothing else to do here — the broker is
+      // wired to forward inbound messages into the engine.
+      return;
+    }
+
+    // Leader path. If any subscribeCrdt / subscribeReactive call came
+    // in before start() (or before initMultiTab settled), it took the
+    // default-follower branch and tried to broadcast to a not-yet-
+    // running broker. Now that we know we ARE the leader, populate
+    // serverSubs from local interest so the WS subscribe frames go
+    // out on the next connect. Idempotent w.r.t. subscribe calls that
+    // happen later through the normal leader branch.
+    this.seedServerSubsFromLocalInterest();
+
     // Seed the server-resolved session before the first pull so
-    // `useSession` subscribers see the right tenant from frame one, and
-    // `lastSeenTenant` is populated before any subsequent flip can race
-    // with it.
+    // `useSession` subscribers see the right tenant from frame one,
+    // and the resolver's lastSeenTenant is populated before any
+    // subsequent flip can race with it.
     await this.refreshResolvedSession();
 
     // Pull from server, then connect real-time transport.
@@ -505,16 +570,179 @@ export class SyncEngine {
     // webhook on a sibling Fly machine" / "missed WS event" gap.
     this.attachVisibilityListener();
 
-    const transport = this.config.transport ?? "websocket";
-    if (transport === "websocket") {
-      this.connectWs();
-    } else if (transport === "sse") {
-      this.connectSse();
-    } else if (transport === "poll") {
-      this.startPolling();
+    this.transport = createTransport(this.transportKind(), this.transportHost());
+    this.transport.start();
+  }
+
+  /**
+   * Multi-tab election. Brings up the orchestrator and runs the
+   * initial election. Sets `isMultiTabLeader` via the orchestrator's
+   * hooks (onInitialLeader / onLatePromote / onDemote).
+   *
+   * On platforms without BroadcastChannel (Node, jsdom, very old
+   * Safari) the orchestrator declares self leader and returns
+   * immediately.
+   */
+  private async initMultiTab(): Promise<void> {
+    this.orchestrator = new MultiTabOrchestrator(
+      {
+        enabled: this.config.multiTab !== false,
+        appName: this.config.appName,
+      },
+      this.subscriptions,
+      this.multiTabHooks(),
+    );
+    await this.orchestrator.init();
+  }
+
+  /** Hooks the orchestrator calls back into for inbound multi-tab
+   *  events that need engine state. Cases that only touch
+   *  subscriptions are dispatched directly by the orchestrator. */
+  private multiTabHooks() {
+    return {
+      onInitialLeader: () => {
+        this.isMultiTabLeader = true;
+      },
+      onLatePromote: () => {
+        this.isMultiTabLeader = true;
+        void this.onMultiTabPromoted();
+      },
+      onDemote: () => {
+        this.isMultiTabLeader = false;
+        this.onMultiTabDemoted();
+      },
+      onAppliedReceived: (
+        changes: ChangeEvent[],
+        targetCursor: SyncCursor | undefined,
+      ) => {
+        // `fromBroadcast: true` suppresses re-broadcast in case a
+        // promotion lands between this enqueue and the apply.
+        if (changes.length > 0) {
+          void this.enqueueApply(changes, targetCursor, { fromBroadcast: true });
+        } else if (targetCursor && targetCursor.last_seq > this.cursor.last_seq) {
+          this.cursor = targetCursor;
+        }
+      },
+      onReconciledReceived: (
+        entity: string,
+        upserts: Row[],
+        removalIds: string[],
+        tombstoneSeq: number,
+      ) => {
+        void this.enqueueReconcile(entity, upserts, removalIds, tombstoneSeq, {
+          fromBroadcast: true,
+        });
+      },
+      onResetReceived: () => {
+        void this.resetReplicaInner();
+      },
+      onSessionReceived: (resolved: ResolvedSession) => {
+        // Funnel through the shared session chain so concurrent triggers
+        // (broadcast + local notifySessionChanged) commit in arrival
+        // order. Without that the older tenant could win and pin the
+        // engine to a stale session.
+        void this.applySessionTransition(resolved, /* broadcast */ false);
+      },
+      onMutationsForwarded: (ops: PendingMutation[]) => {
+        for (const op of ops) {
+          this.mutations.add(op.change);
+        }
+        void this.push();
+      },
+      onMutationsAcked: (opIds: string[]) => {
+        for (const id of opIds) this.mutations.markApplied(id);
+        this.mutations.clear();
+      },
+      onMutationsFailed: (ops: { opId: string; error: string }[]) => {
+        for (const op of ops) {
+          this.mutations.markFailed(op.opId, op.error);
+        }
+      },
+      onBinaryReceived: (bytes: Uint8Array) => {
+        for (const h of this.binaryHandlers) {
+          try {
+            h(bytes);
+          } catch (err) {
+            console.warn("[sync] binary handler threw:", err);
+          }
+        }
+      },
+      onPeerLeft: (_tabId: string) => {
+        // Orchestrator already scrubbed subscription state for the
+        // departed tab. The engine has no additional cleanup, but the
+        // hook exists for future needs (e.g., per-peer presence).
+      },
+    };
+  }
+
+  /** Seed serverSubs with every subscription this tab currently wants.
+   *  Called from both the initial-leader path (subscribes that
+   *  happened before start() took the follower branch and broadcast
+   *  to a not-yet-running broker, so the registers were lost) and the
+   *  late-promotion path (the previous leader owned the subs and we
+   *  need to claim them). */
+  private seedServerSubsFromLocalInterest(): void {
+    this.subscriptions.seedFromLocalInterest();
+  }
+
+  /** Late promotion: the previous leader dropped while we were
+   *  running as a follower. Take over network ops now AND drain any
+   *  pending mutations through push() — a mutation we'd forwarded to
+   *  the previous leader may have died with it before the server
+   *  acked, and we need to ship it ourselves. op_id makes the
+   *  server-side retry idempotent: a previously-applied op returns
+   *  `replayed` and we just mark it applied locally. */
+  private async onMultiTabPromoted(): Promise<void> {
+    if (!this.running) return;
+    try {
+      // Re-register every locally-wanted server subscription with our
+      // own serverSubs. Previous leader had these; now we own the WS,
+      // so we need to send the subscribe frames on the next connect.
+      this.seedServerSubsFromLocalInterest();
+      // Ask the rest of the tabs to re-forward their subs so we can
+      // serve them from our new WS. They'll respond via `sub-register`.
+      this.broadcastToTabs({ type: "request-sub-replay" });
+
+      await this.refreshResolvedSession();
+      await this.pull();
+      // Drain the queue — replay every pending op that was either
+      // forwarded to a now-dead leader or queued locally while we
+      // were a follower. The server's op_id dedupe absorbs duplicates.
+      if (this.mutations.pending().length > 0) {
+        void this.push();
+      }
+      this.attachVisibilityListener();
+      // Late promotion: build a transport (if one doesn't exist yet — a
+      // tab might have spent its whole life as follower with no
+      // transport at all) and start it.
+      if (!this.transport) {
+        this.transport = createTransport(this.transportKind(), this.transportHost());
+      }
+      this.transport.start();
+    } catch {
+      /* best-effort — next reconnect cycle catches up */
+    }
+  }
+
+  /** Demotion: another tab took over as leader. Tear down our
+   *  transport (WS socket, ping timer, reconnect timer, poll timer —
+   *  whichever applies) and stop driving network ops; the new leader
+   *  will broadcast applied changes that our followers-mirror path
+   *  picks up. */
+  private onMultiTabDemoted(): void {
+    if (this.transport) {
+      this.transport.stop();
+      this.transport = null;
     }
   }
 
+  /** Broadcast a payload to other tabs in this origin. Delegates to
+   *  the orchestrator; no-op when the orchestrator isn't running
+   *  (SSR-only consumers that never reach `start()`). */
+  private broadcastToTabs(payload: unknown): void {
+    this.orchestrator?.broadcastRaw(payload);
+  }
+
   private visibilityHandler: (() => void) | null = null;
   private attachVisibilityListener(): void {
     if (this.config.reconcileOnVisibility === false) return;
@@ -525,16 +753,16 @@ export class SyncEngine {
       if (!this.running) return;
       // Reconcile fires only on tab-becomes-visible; the debounce in
       // reconcile() collapses bursts from rapid background/foreground
-      // flips. Pull runs alongside so cursor catches up to anything
-      // emitted while the tab was hidden.
+      // flips. Pull is enqueued FIRST so the opQueue runs it before
+      // reconcile — that way reconcile sees the fresh cursor and
+      // doesn't duplicate the cursor-catch-up work pull is already
+      // doing. They're serial via the queue, not concurrent.
       void this.pull();
       void this.reconcile();
     };
     document.addEventListener("visibilitychange", this.visibilityHandler);
   }
 
-  private pollTimer: ReturnType<typeof setInterval> | null = null;
-
   /**
    * Serialize a batch of change applies behind any in-flight applies, and
    * advance the cursor monotonically when the batch lands. Both the WS
@@ -550,40 +778,21 @@ export class SyncEngine {
    */
   private enqueueApply(
     changes: ChangeEvent[],
-    options:
-      | SyncCursor
-      | { targetCursor?: SyncCursor; skipSeqGuard?: boolean; advanceCursor?: boolean } = {},
+    targetCursor?: SyncCursor,
+    opts: { fromBroadcast?: boolean } = {},
   ): Promise<void> {
-    // Back-compat: callers that pass a SyncCursor positional arg get
-    // the same semantics as before. New callers can pass an options
-    // object — `skipSeqGuard` lets reconcile bypass the seq filter
-    // (its synthetic events fabricate seqs that don't fit the natural
-    // monotonic order), and `advanceCursor: false` keeps the cursor
-    // pinned where it was so reconcile doesn't fake-advance past the
-    // server's real position.
-    const opts: { targetCursor?: SyncCursor; skipSeqGuard?: boolean; advanceCursor?: boolean } =
-      options && typeof options === "object" && "last_seq" in options
-        ? { targetCursor: options as SyncCursor }
-        : (options as {
-            targetCursor?: SyncCursor;
-            skipSeqGuard?: boolean;
-            advanceCursor?: boolean;
-          });
-    const skipSeqGuard = opts.skipSeqGuard ?? false;
-    const advanceCursor = opts.advanceCursor ?? true;
-    const targetCursor = opts.targetCursor;
-
     const prev = this.applyQueue;
     const next = prev.then(async () => {
-      const filtered = skipSeqGuard
-        ? changes
-        : changes.filter(
-            (c) => typeof c.seq === "number" && c.seq > this.cursor.last_seq,
-          );
+      // Per-event monotonic filter: re-applies of an already-seen seq
+      // are skipped before touching the store. Without that, a
+      // retransmit (WS + pull window overlap) would have us run
+      // applyChange twice against the local store.
+      const filtered = changes.filter(
+        (c) => typeof c.seq === "number" && c.seq > this.cursor.last_seq,
+      );
       if (filtered.length > 0) {
         await this.store.applyChangesAsync(filtered);
       }
-      if (!advanceCursor) return;
       // Pick the cursor target. Explicit `targetCursor` (from pull) wins
       // — pull's response carries the server's authoritative current_seq
       // even when no changes landed in this window. Otherwise derive
@@ -599,6 +808,23 @@ export class SyncEngine {
           await this.persistence.saveCursor(this.cursor);
         }
       }
+      // Multi-tab: leader fans the batch out so follower replicas
+      // converge without their own WS. Skip when we ourselves
+      // RECEIVED this batch from another tab — otherwise a tab that
+      // was promoted between receiving and applying would re-broadcast
+      // its own copy, and even though the seq filter dedupes on
+      // arrival the round-trip is wasted bandwidth.
+      if (
+        this.isMultiTabLeader &&
+        !opts.fromBroadcast &&
+        filtered.length > 0
+      ) {
+        this.broadcastToTabs({
+          type: "applied",
+          changes: filtered,
+          targetCursor: candidate ?? undefined,
+        });
+      }
     });
     // Errors stay scoped to this batch — don't poison the chain for
     // future applies.
@@ -606,369 +832,65 @@ export class SyncEngine {
     return next;
   }
 
-  private startPolling(): void {
-    const interval = this.config.pollInterval ?? 1000;
-    this.pollTimer = setInterval(() => {
-      this.push().then(() => this.pull());
-    }, interval);
+  /**
+   * Reconcile path. Routes through the same applyQueue as WS/pull so
+   * a reconcile batch can't interleave with a fresher change event
+   * mid-apply — but reconcile carries no real seqs, so the seq filter
+   * and cursor advance from `enqueueApply` are deliberately absent.
+   * Pending mutations are protected upstream (in applyEntityReconcile)
+   * before the batch is ever built.
+   */
+  private enqueueReconcile(
+    entity: string,
+    upserts: Row[],
+    removalIds: string[],
+    tombstoneSeq: number,
+    opts: { fromBroadcast?: boolean } = {},
+  ): Promise<void> {
+    const prev = this.applyQueue;
+    const next = prev.then(async () => {
+      await this.store.applyReconcileBatch(
+        entity,
+        upserts,
+        removalIds,
+        tombstoneSeq,
+      );
+      // Leader fans the reconcile batch out so each follower can
+      // converge without its own fetch. Suppress when we ourselves
+      // received this batch via the channel (promotion mid-flight
+      // would otherwise echo it).
+      if (this.isMultiTabLeader && !opts.fromBroadcast) {
+        this.broadcastToTabs({
+          type: "reconciled",
+          entity,
+          upserts,
+          removalIds,
+          tombstoneSeq,
+        });
+      }
+    });
+    this.applyQueue = next.catch(() => {});
+    return next;
   }
 
   /** Stop the sync engine. */
   stop(): void {
     this.running = false;
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-    }
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    if (this.pollTimer) {
-      clearInterval(this.pollTimer);
-      this.pollTimer = null;
-    }
-    if (this.pingTimer) {
-      clearInterval(this.pingTimer);
-      this.pingTimer = null;
+    if (this.transport) {
+      this.transport.stop();
+      this.transport = null;
     }
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
     }
-    this.setConnectionStatus("offline");
-  }
-
-  /** Connect to the WebSocket server for real-time updates. */
-  private connectWs(): void {
-    if (!this.running) return;
-
-    const wsUrl = this.config.wsUrl ?? this.deriveWsUrl();
-    // Browser WebSocket has no header API — the server accepts the token
-    // as a `bearer.<percent-encoded-token>` subprotocol (RFC 6455 §1.9).
-    // Native clients can still set Authorization: Bearer via headers.
-    const token =
-      this.config.token ??
-      this.storage.get(this.tokenStorageKey()) ??
-      undefined;
-    try {
-      if (token) {
-        const proto = `bearer.${encodeURIComponent(token)}`;
-        this.ws = new WebSocket(wsUrl, proto);
-      } else {
-        this.ws = new WebSocket(wsUrl);
-      }
-    } catch {
-      this.scheduleReconnect();
-      return;
-    }
-
-    // Backoff reset is delayed — a socket that opens then closes inside
-    // a few seconds (auth failure, server 1008) would otherwise let the
-    // reconnect loop fire at ~2/sec forever. Only call the connection
-    // "stable" after it's stayed up long enough to have been doing work.
-    this.ws.onopen = () => {
-      // We only flip to "connected" once the socket actually opens.
-      // The 5s stable-window timer below decides when to RESET the
-      // backoff; status flips immediately because UI consumers want
-      // to clear the "reconnecting" indicator the moment data starts
-      // flowing again.
-      this.setConnectionStatus("connected");
-      if (this.wsStableTimer) clearTimeout(this.wsStableTimer);
-      this.wsStableTimer = setTimeout(() => {
-        this.reconnectAttempts = 0;
-        this.wsStableTimer = null;
-      }, 5_000);
-      // Client-side keepalive ping. Default 25s — pure liveness, since
-      // the dedicated :port+1 server uses a dual-thread design that
-      // wakes the writer instantly on every broadcast (no mutex
-      // contention with the reader, no ping-bounded latency).
-      //
-      // The HTTP-multiplexed `/api/sync/ws` fallback path is still
-      // single-threaded (tiny_http's CustomStream hides the TcpStream
-      // so we can't set a kernel-level read timeout). On that path,
-      // broadcast latency IS bounded by this interval — apps that
-      // can't route to the :port+1 listener can pass
-      // `init({ pingIntervalMs: 200 })` to trade traffic for latency.
-      const pingIntervalMs = this.config.pingIntervalMs ?? 25_000;
-      if (this.pingTimer) clearInterval(this.pingTimer);
-      this.pingTimer = setInterval(() => {
-        if (this.ws?.readyState !== WebSocket.OPEN) return;
-        try {
-          this.ws.send('{"type":"ping"}');
-        } catch {
-          // ignore — onclose will trigger reconnect
-        }
-      }, pingIntervalMs);
-      // Re-send any active CRDT subscriptions across the new socket.
-      // The server purged them on disconnect (`unsubscribe_all`), so
-      // without this resync a tab that was subscribed before a network
-      // blip would silently stop receiving binary CRDT frames.
-      for (const key of this.crdtSubscriptions) {
-        const [entity, rowId] = key.split("\x00");
-        this.sendWs({ type: "crdt-subscribe", entity, rowId });
-      }
-      // Re-register every reactive subscription on the fresh socket.
-      // The server's ReactiveRegistry tears down on disconnect (via
-      // `disconnect_client`) so without this resync the handlers
-      // would silently stop receiving result pushes.
-      for (const [sub_id, spec] of this.reactiveSpecs) {
-        this.sendWs({
-          type: "reactive-subscribe",
-          sub_id,
-          fn_name: spec.fn_name,
-          args: spec.args,
-        });
-      }
-      // Pull-on-open catches every event broadcast in the gap between
-      // the prior `pull()` returning and this socket actually opening.
-      // The WS has no replay-on-connect (it's just a fanout), so events
-      // emitted to other live clients during that window would otherwise
-      // be lost forever to this tab. Reconcile fires after the pull
-      // since pull is the cheap incremental path; reconcile is the
-      // server-truth backstop for anything pull couldn't replay.
-      void this.pull().then(() => this.reconcile());
-    };
-
-    // Bind binaryType BEFORE installing the handler so the first
-    // server-pushed binary frame (CRDT snapshot or update) decodes
-    // correctly. Default in browsers is "blob"; we want raw bytes
-    // synchronously available so the binary-handler closure doesn't
-    // need to await a Blob.arrayBuffer() round-trip.
-    this.ws.binaryType = "arraybuffer";
-
-    this.ws.onmessage = (event) => {
-      // Binary frame: route to whatever consumer registered via
-      // onBinaryFrame(). Pylon's CRDT broadcast (server-side
-      // notify_crdt) ships every CRDT-mode write as a binary
-      // [type|entity|row_id|payload] frame; @pylonsync/loro is the
-      // intended decoder. SyncEngine itself stays binary-agnostic so
-      // the next binary use case (file streaming, video chunks…)
-      // can register without churning this layer.
-      if (event.data instanceof ArrayBuffer) {
-        for (const handler of this.binaryHandlers) {
-          try {
-            handler(new Uint8Array(event.data));
-          } catch (err) {
-            console.warn("[sync] binary handler threw:", err);
-          }
-        }
-        return;
-      }
-
-      try {
-        const msg = JSON.parse(event.data as string);
-
-        // Sync change event. Persist BEFORE advancing the cursor so a
-        // crash can't leave `last_seq` ahead of the replica on disk.
-        // The shared apply queue serializes WS messages with each other
-        // AND with concurrent pull() calls, so seq order is preserved
-        // and the cursor only advances monotonically.
-        if (msg.seq && msg.entity && msg.kind) {
-          const change = msg as ChangeEvent;
-          void this.enqueueApply([change]);
-          return;
-        }
-
-        // Presence event.
-        if (msg.type === "presence") {
-          this.store.notify();
-          return;
-        }
-
-        // Server-driven revocation: a subscriber whose read policy
-        // was revoked mid-session for a specific row. Drop the row
-        // from the local replica at the current cursor seq so the
-        // tombstone supersedes any racing late-arriving WS update
-        // for the same row, and notify any LoroDoc subscriber
-        // (registered via `addRowEvictionListener`) so collaborative
-        // doc handles unmount cleanly.
-        //
-        // Distinct from a regular Delete change event because this
-        // envelope has no global seq — the row's underlying data
-        // hasn't been deleted, only the recipient's visibility of
-        // it. Other subscribers (with matching policy) keep their
-        // row intact.
-        if (
-          msg.type === "row-revoked" &&
-          typeof msg.entity === "string" &&
-          typeof msg.row_id === "string"
-        ) {
-          // Server includes its current high-water seq when known —
-          // use it as the tombstone seq so an in-flight stale frame
-          // with `seq <= server_seq` is filtered locally. A
-          // legitimate re-grant at a higher seq still lands.
-          const revokeSeq =
-            typeof msg.seq === "number" && msg.seq > 0
-              ? msg.seq
-              : this.cursor.last_seq;
-          this.handleRowRevocation(msg.entity, msg.row_id, revokeSeq);
-          return;
-        }
-
-        // Session mutated server-side. Fires for select-org / clear-org
-        // / session revoke — every tab connected as this user gets the
-        // envelope (cross-machine too via the cluster bus). Trigger
-        // a fresh /api/auth/me read which updates the cached session
-        // AND, on tenant flip, resets the replica so stale rows from
-        // the previous tenant disappear. App code calling
-        // /api/auth/select-org via raw fetch no longer needs the
-        // manual `notifySessionChanged()` step.
-        if (msg.type === "session-changed") {
-          void this.refreshResolvedSession();
-          return;
-        }
-
-        // Reactive query push: the server-side ReactiveRegistry re-ran
-        // a subscribed handler and the result hash changed. Route to
-        // the handler registered by `subscribeReactive` so the React
-        // hook re-renders.
-        if (msg.type === "reactive-result" && typeof msg.sub_id === "string") {
-          const handler = this.reactiveHandlers.get(msg.sub_id);
-          if (handler) {
-            handler({ kind: "result", result: msg.result });
-          }
-          return;
-        }
-        if (msg.type === "reactive-error" && typeof msg.sub_id === "string") {
-          const handler = this.reactiveHandlers.get(msg.sub_id);
-          if (handler) {
-            handler({
-              kind: "error",
-              code: typeof msg.code === "string" ? msg.code : "REACTIVE_ERROR",
-              message: typeof msg.message === "string" ? msg.message : "",
-            });
-          }
-          return;
-        }
-      } catch {
-        // Ignore malformed messages.
-      }
-    };
-
-    this.ws.onclose = () => {
-      this.ws = null;
-      // Socket closed before the stable-window timer fired — treat this
-      // as an unstable connection and DO NOT reset reconnectAttempts.
-      // The growing backoff protects the server from a tight loop.
-      if (this.wsStableTimer) {
-        clearTimeout(this.wsStableTimer);
-        this.wsStableTimer = null;
-      }
-      if (this.pingTimer) {
-        clearInterval(this.pingTimer);
-        this.pingTimer = null;
-      }
-      // Surface the disconnect to UI consumers immediately. If
-      // `running` flipped to false (engine stopped), `stop()` already
-      // set "offline" — don't override that.
-      if (this.running) {
-        this.setConnectionStatus("reconnecting");
-      }
-      this.scheduleReconnect();
-    };
-
-    this.ws.onerror = () => {
-      // onclose will fire after this.
-    };
-  }
-
-  private scheduleReconnect(): void {
-    if (!this.running) return;
-    this.reconnectAttempts += 1;
-    const delay = this.computeBackoff();
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      // Pull any missed changes, then reconnect.
-      this.pull().then(() => this.connectWs());
-    }, delay);
-  }
-
-  /**
-   * Exponential backoff with full jitter for reconnects.
-   *
-   * Thundering-herd fix: when the server restarts, every connected client
-   * fires `onclose` at nearly the same instant. Without jitter they all
-   * reconnect at `baseDelay` and hammer the newly-booted server; after a
-   * few cycles the reconnect waves align and the server never recovers.
-   *
-   * Full-jitter (`delay = random(0, exp)`) spreads clients evenly across
-   * the backoff window so the second-wave load is flat, not spiky.
-   * Algorithm from AWS Architecture Blog "Exponential Backoff and Jitter"
-   * — the "Full Jitter" variant, which has the lowest collision rate.
-   *
-   * The `reconnectDelay` config value seeds the exponential base. Max
-   * delay caps at 30s so users don't wait minutes on a long outage.
-   */
-  private computeBackoff(): number {
-    const base = this.config.reconnectDelay ?? 1000;
-    const maxDelay = 30_000;
-    // exp = base * 2^(attempts-1), clamped to maxDelay
-    const attempt = Math.max(1, this.reconnectAttempts);
-    const exp = Math.min(maxDelay, base * Math.pow(2, attempt - 1));
-    // Full jitter: delay is uniform random in [0, exp].
-    return Math.floor(Math.random() * exp);
-  }
-
-  /** Connect via Server-Sent Events. */
-  private connectSse(): void {
-    if (!this.running) return;
-
-    const base = this.config.baseUrl;
-    const url = new URL(base);
-    const port = parseInt(url.port || "4321", 10);
-    const sseUrl = `http://${url.hostname}:${port + 2}/events`;
-
-    try {
-      const es = new EventSource(sseUrl);
-      es.onmessage = (event) => {
-        try {
-          const msg = JSON.parse(event.data);
-          if (msg.seq && msg.entity && msg.kind) {
-            const change = msg as ChangeEvent;
-            void this.enqueueApply([change]);
-          }
-        } catch {
-          // Ignore malformed events.
-        }
-      };
-      es.onerror = () => {
-        es.close();
-        // Same jittered backoff as the WS path so SSE clients don't form
-        // a second reconnect wave on server restart.
-        this.reconnectAttempts += 1;
-        setTimeout(() => {
-          if (this.running) {
-            this.pull().then(() => this.connectSse());
-          }
-        }, this.computeBackoff());
-      };
-    } catch {
-      // EventSource not available — fall back to polling.
-      this.startPolling();
+    if (this.orchestrator) {
+      this.orchestrator.stop();
+      this.orchestrator = null;
     }
+    this.setConnectionStatus("offline");
   }
 
-  private deriveWsUrl(): string {
-    const base = this.config.baseUrl;
-    const url = new URL(base);
-    const scheme = url.protocol === "https:" ? "wss" : "ws";
-
-    // Always multiplex WS on the same origin via `/api/sync/ws`. The
-    // Pylon runtime accepts the Upgrade on its main HTTP port (4321),
-    // so any reverse proxy that already forwards `/api/*` carries the
-    // WebSocket through too (Vite's `ws: true` proxy, Next.js rewrites,
-    // CDNs with WS support).
-    //
-    // The legacy port+1 fallback (`:4322` for a `:4321` API) is still
-    // available on the runtime, but we don't derive it client-side
-    // anymore: any setup where the page origin (e.g. Vite on :3000)
-    // wasn't equal to the API origin would compute ws://localhost:3001
-    // — which doesn't exist and bypasses the dev-server proxy. The
-    // `/api/sync/ws` path goes through whatever proxies `/api/*`,
-    // which is the same code path prod already relies on.
-    return `${scheme}://${url.host}/api/sync/ws`;
-  }
 
   /**
    * Drop local cursor + store + notify. Safe to call from any state.
@@ -988,6 +910,13 @@ export class SyncEngine {
    * in-memory state could fix.
    */
   async resetReplica(): Promise<void> {
+    // Public callers go through the queue so a reset can't race with
+    // an in-flight pull / push / reconcile. Internal callers that
+    // already hold the queue slot use `resetReplicaInner` directly.
+    return this.opQueue.enqueue("reset", () => this.resetReplicaInner());
+  }
+
+  private async resetReplicaInner(): Promise<void> {
     this.cursor = { last_seq: 0 };
     this.store.clearAll();
     if (this.persistence) {
@@ -998,6 +927,12 @@ export class SyncEngine {
         /* best-effort */
       }
     }
+    // Leader broadcasts the reset so follower replicas wipe their
+    // own copies in lockstep — otherwise a follower keeps stale
+    // rows under the old identity until its own pull catches up.
+    if (this.isMultiTabLeader) {
+      this.broadcastToTabs({ type: "reset" });
+    }
   }
 
   /**
@@ -1081,24 +1016,35 @@ export class SyncEngine {
     );
   }
 
-  /** Pull changes from the server. */
+  /** Pull changes from the server. Coalesces concurrent callers via
+   *  the op queue and serializes against push / reconcile / reset, so
+   *  the cursor can't be read mid-reset and the change-log delta can't
+   *  interleave with a sweeping reconcile. The 410 RESYNC retry path
+   *  recurses into `pullInner` directly to avoid self-deadlock on the
+   *  queue. */
   async pull(): Promise<void> {
+    return this.opQueue.enqueue("pull", () => this.pullInner());
+  }
+
+  private async pullInner(): Promise<void> {
+    // Followers don't talk to the network — the leader broadcasts
+    // every applied change over the multi-tab channel, and our local
+    // applyQueue picks it up there.
+    if (!this.isMultiTabLeader) return;
     // Identity change detection. If the token flipped since the last pull
     // (anonymous → signed in, user A → user B, signed in → signed out),
     // the server's visible set changed under us and the cursor we saved
     // reflects the previous identity. Reset before pulling so we rebuild
     // the replica from seq=0 under the new identity.
-    const tokenNow = this.currentToken();
-    if (
-      this.lastSeenToken !== undefined &&
-      this.lastSeenToken !== tokenNow
-    ) {
-      await this.resetReplica();
+    const { tokenChanged } = this.session.observeToken(this.currentToken());
+    if (tokenChanged) {
+      // We're holding the "pull" slot in the op queue — bypass the
+      // queue's reset path to avoid self-deadlock.
+      await this.resetReplicaInner();
       // Token flipped → the cached tenant is for the previous user. Pull
       // the fresh session in parallel with the cursor catch-up below.
       void this.refreshResolvedSession();
     }
-    this.lastSeenToken = tokenNow;
 
     try {
       // Snapshot pagination: when the cursor is 0 and the server's
@@ -1142,7 +1088,11 @@ export class SyncEngine {
       // tight loop that the server reads as abuse.
       const status = (err as { status?: number })?.status;
       if (status === 429) {
-        this.reconnectAttempts += 3;
+        // Push the next reconnect noticeably further out so a rate-
+        // limited pull doesn't drive a tight 429 / reconnect / pull
+        // / 429 loop the server reads as abuse. The +3 attempts skips
+        // straight to a longer backoff window.
+        this.transport?.bumpReconnect(3);
       }
       // 410 RESYNC_REQUIRED: cursor is from a previous server lifetime, or
       // it fell off the retention window. Drop local state + cursor and
@@ -1158,8 +1108,11 @@ export class SyncEngine {
         const attempt = this.consecutive_410s;
         this.consecutive_410s += 1;
         if (attempt === 0) {
-          await this.resetReplica();
-          await this.pull();
+          // Bypass the queue here — we ARE the pull op holding the
+          // queue slot. Calling the public pull() would re-enqueue and
+          // share our own promise back to us (deadlock).
+          await this.resetReplicaInner();
+          await this.pullInner();
         } else {
           // Already retried once and still 410. Stop. Schedule a
           // back-off retry tied to the WS reconnect path so we don't
@@ -1190,11 +1143,6 @@ export class SyncEngine {
    *  entity twice within seconds. Configurable via `reconcileMinIntervalMs`. */
   private lastReconcileAt = 0;
 
-  /** In-flight reconcile promise — coalesces concurrent callers so a
-   *  visibility-change firing during an in-progress reconcile doesn't
-   *  double the work. */
-  private inFlightReconcile: Promise<void> | null = null;
-
   /**
    * Reconcile the local replica against server truth.
    *
@@ -1231,21 +1179,28 @@ export class SyncEngine {
    * no arg, every entity with local rows is checked.
    */
   async reconcile(entities?: string[]): Promise<void> {
-    if (this.inFlightReconcile) return this.inFlightReconcile;
     const minIntervalMs = this.config.reconcileMinIntervalMs ?? 2_000;
     const now = Date.now();
     if (entities === undefined && now - this.lastReconcileAt < minIntervalMs) {
       return;
     }
-    const work = this.reconcileInner(entities).finally(() => {
-      this.inFlightReconcile = null;
-      this.lastReconcileAt = Date.now();
+    // Coalesce concurrent reconciles to a single op via the queue's
+    // keyed dedupe — multiple callers in the same tick share one fetch.
+    // Reconcile waits behind any in-flight pull / refresh / push so it
+    // can't apply rows captured under a stale session.
+    return this.opQueue.enqueue("reconcile", async () => {
+      try {
+        await this.reconcileInner(entities);
+      } finally {
+        this.lastReconcileAt = Date.now();
+      }
     });
-    this.inFlightReconcile = work;
-    return work;
   }
 
   private async reconcileInner(entities?: string[]): Promise<void> {
+    // Same reasoning as pullInner: the leader reconciles, broadcasts
+    // results, and follower replicas converge via the channel.
+    if (!this.isMultiTabLeader) return;
     const names = entities ?? this.store.entityNames();
     if (names.length === 0) return;
     // Tombstone seq for any local row the server doesn't return. Using
@@ -1275,7 +1230,7 @@ export class SyncEngine {
       //      (triggered by session-changed envelope) will re-fetch
       //      under the new context.
       const cursorBeforeFetch = this.cursor.last_seq;
-      const sessionBeforeFetch = sessionSignature(this._resolvedSession);
+      const sessionBeforeFetch = this.session.signature();
       let serverRows: Row[];
       try {
         serverRows = await this.fetchEntityRows(entity);
@@ -1300,7 +1255,7 @@ export class SyncEngine {
         // state for the affected row.
         continue;
       }
-      if (sessionSignature(this._resolvedSession) !== sessionBeforeFetch) {
+      if (this.session.signature() !== sessionBeforeFetch) {
         // Session changed (token flipped, tenant switched, user
         // signed out → in, etc.). The rows we fetched reflect the
         // OLD session's policy view; applying them now would
@@ -1342,92 +1297,40 @@ export class SyncEngine {
     tombstoneSeq: number,
   ): Promise<void> {
     // Invariant: rows with in-flight or failed mutations are
-    // off-limits to reconcile. Neither the "server row missing from
-    // local snapshot" apply branch nor the "local row missing from
-    // server snapshot" tombstone branch may touch them. A hydrated
-    // offline mutation that hasn't been pushed yet would otherwise
-    // look like a phantom local-only row and get tombstoned before
-    // push has a chance to ship it.
+    // off-limits to reconcile. Neither the upsert branch nor the
+    // tombstone branch may touch them. A hydrated offline mutation
+    // that hasn't been pushed yet would otherwise look like a phantom
+    // local-only row and get tombstoned before push has a chance to
+    // ship it.
     // Test: `hydrated_offline_mutations_survive_startup_reconcile`.
     const pendingKeys = this.mutations.pendingRowKeys();
     const serverIds = new Set<string>();
-    const changes: ChangeEvent[] = [];
+    const upserts: Row[] = [];
     for (const row of serverRows) {
       const id = (row as { id?: unknown }).id;
       if (typeof id !== "string" || id.length === 0) continue;
       serverIds.add(id);
-      // Skip any row whose canonical state is still being decided
-      // by an in-flight mutation — applying the server snapshot
-      // would clobber the user's pending edit.
       if (pendingKeys.has(`${entity}/${id}`)) continue;
       const local = this.store.get(entity, id);
-      if (!local) {
-        changes.push({
-          seq: tombstoneSeq + 1,
-          entity,
-          row_id: id,
-          kind: "insert",
-          data: row,
-          timestamp: "",
-        });
-      } else if (rowsDiffer(local, row)) {
-        changes.push({
-          seq: tombstoneSeq + 1,
-          entity,
-          row_id: id,
-          kind: "update",
-          data: row,
-          timestamp: "",
-        });
+      if (!local || rowsDiffer(local, row)) {
+        upserts.push(row);
       }
     }
-    if (changes.length > 0) {
-      // Reconcile applies route through the same serialized queue as
-      // WS/pull so a stale reconcile response can't interleave with a
-      // newer WS/pull update mid-batch. The synthetic seqs reconcile
-      // fabricates (tombstoneSeq + 1) collide with WS-issued seqs so
-      // we skip the monotonic guard and don't advance the cursor —
-      // the cursor still reflects the server's last_seq, not our
-      // fabricated reconcile seqs.
-      await this.enqueueApply(changes, {
-        skipSeqGuard: true,
-        advanceCursor: false,
-      });
-    }
     // Removals: every local row whose id isn't in the server set is
-    // stale. Tombstone with the current cursor so future legitimate
-    // re-creations still flow through. Synthesize Delete events for
-    // each removal and route through the apply queue so the order
-    // relative to WS/pull updates is preserved — a removal here is
-    // really "server says this row is gone as of tombstoneSeq", which
-    // matters if a later WS update reinstates it on the same row id.
-    const locals = this.store.list(entity);
-    const removalChanges: ChangeEvent[] = [];
-    for (const local of locals) {
+    // stale. The reconcile primitive tombstones at `tombstoneSeq` so
+    // future legitimate re-creations (with strictly greater seqs)
+    // still flow through.
+    const removalIds: string[] = [];
+    for (const local of this.store.list(entity)) {
       const id = (local as { id?: unknown }).id;
       if (typeof id !== "string") continue;
-      // Pending mutations protect the row from the removal pass too
-      // — a queued insert that hasn't been pushed yet would otherwise
-      // look like a phantom local-only row and get tombstoned, only
-      // for push() to later resurrect it.
       if (pendingKeys.has(`${entity}/${id}`)) continue;
-      if (!serverIds.has(id)) {
-        removalChanges.push({
-          seq: tombstoneSeq,
-          entity,
-          row_id: id,
-          kind: "delete",
-          data: undefined,
-          timestamp: "",
-        });
-      }
-    }
-    if (removalChanges.length > 0) {
-      await this.enqueueApply(removalChanges, {
-        skipSeqGuard: true,
-        advanceCursor: false,
-      });
+      if (!serverIds.has(id)) removalIds.push(id);
     }
+    if (upserts.length === 0 && removalIds.length === 0) return;
+    // Route through the apply queue so a reconcile batch can't
+    // interleave with a fresher WS/pull change event mid-apply.
+    await this.enqueueReconcile(entity, upserts, removalIds, tombstoneSeq);
   }
 
   private async dropEntity(
@@ -1454,7 +1357,9 @@ export class SyncEngine {
   }
 
   /**
-   * Fetch `/api/auth/me` and update the cached `_resolvedSession`. Callers:
+   * Fetch `/api/auth/me` and feed the result into the SessionResolver,
+   * acting on the verdict it returns (reset replica + pull on a real
+   * tenant flip, notify subscribers if any field changed). Callers:
    *   - `start()` — initial load
    *   - the token-flip branch in `pull()`
    *   - `notifySessionChanged()` — app code invokes this after it mutates
@@ -1466,6 +1371,11 @@ export class SyncEngine {
    * token-flip path, for the same reason (visible set changed).
    */
   async refreshResolvedSession(): Promise<void> {
+    // Followers don't fetch /api/auth/me — the leader does and
+    // broadcasts the result, which `handleMultiTabMessage` routes
+    // into the resolver.
+    if (!this.isMultiTabLeader) return;
+    let next: ResolvedSession;
     try {
       const res = await this.rawFetch("/api/auth/me");
       if (!res.ok) return;
@@ -1475,66 +1385,71 @@ export class SyncEngine {
         is_admin?: boolean;
         roles?: string[];
       };
-      const next: ResolvedSession = {
+      next = {
         userId: raw.user_id ?? null,
         tenantId: raw.tenant_id ?? null,
         isAdmin: raw.is_admin ?? false,
         roles: raw.roles ?? [],
       };
-      const tenantNow = next.tenantId;
-      // First observation seeds lastSeenTenant without a reset — we have
-      // nothing to invalidate yet. Subsequent changes flip the replica
-      // AND immediately re-pull so subscribers see the new tenant's
-      // rows. Without the re-pull, resetReplica() leaves the store
-      // empty until the next periodic poll, and `db.useQuery` returns
-      // [] for the entire interval — exactly the "I switched orgs
-      // but the dashboard is empty" symptom the cloud team reported.
-      // The 410 RESYNC_REQUIRED path (see ~line 1499) does the same
-      // dance for the same reason.
-      if (
-        this.lastSeenTenant !== undefined &&
-        this.lastSeenTenant !== tenantNow
-      ) {
-        // Two flavors of "tenant changed":
-        //
-        //   - null → X  : session first-resolution. The engine started
-        //                 before the app called /api/auth/select-org;
-        //                 /api/auth/me returned tenant_id=null at start
-        //                 and is only now reporting the real value.
-        //                 The cached IndexedDB rows ARE for tenant X
-        //                 (that's where the user's data lives), so
-        //                 wiping them would tombstone valid state and
-        //                 produce the "rows render then flash away"
-        //                 symptom multi-tenant apps were hitting. Skip
-        //                 the reset; pull under the new tenant fills
-        //                 any gaps via the existing cursor catch-up.
-        //
-        //   - X → Y     : actual org switch. Cached rows belong to
-        //                 the OLD tenant and must not bleed into the
-        //                 new context, so resetReplica is correct.
-        const firstResolution = this.lastSeenTenant === null && tenantNow !== null;
-        if (!firstResolution) {
+    } catch {
+      // Swallow — /api/auth/me errors are transient and the next pull
+      // will retry. Don't take down the sync loop for this.
+      return;
+    }
+    await this.applySessionTransition(next, /* broadcast */ true);
+  }
+
+  /**
+   * Apply a freshly-observed session through the resolver and act on
+   * the verdict. Serialized via `sessionChain` so concurrent triggers
+   * (refreshResolvedSession from app code + multi-tab `session`
+   * broadcast + WS `session-changed` envelope) run in arrival order
+   * and the latest tenant wins — without this, two interleaved
+   * inspect-then-commit pairs could commit an older session AFTER
+   * the newer one.
+   */
+  private applySessionTransition(
+    next: ResolvedSession,
+    broadcast: boolean,
+  ): Promise<void> {
+    const prev = this.sessionChain;
+    // Swallow errors when storing back to the chain so a single
+    // thrown transition doesn't poison the FIFO for everyone after.
+    // Callers receive the swallowed chain — they shouldn't see (or
+    // need to handle) errors from a session refresh.
+    this.sessionChain = prev.then(async () => {
+      // Defer the null→X / X→Y / first-resolution distinction to the
+      // resolver, but DON'T commit the new resolved session until
+      // after the engine has finished acting on the verdict — that
+      // closes the brief window where useSession would report the
+      // new tenant while useQuery still has the old tenant's rows.
+      const verdict = this.session.inspectSession(next);
+      if (verdict.tenantChanged) {
+        if (verdict.replicaInvalidated) {
+          // Route reset through the public (queued) method so the
+          // wipe serializes against in-flight pulls / WS-event
+          // applies / pushes. sessionChain serializes session
+          // transitions but NOT the apply queue — without queuing
+          // the reset, a concurrent applyChangesAsync could write
+          // rows AFTER we clear the store, leaving stale data under
+          // the new identity.
           await this.resetReplica();
         }
-        await this.pull();
+        if (this.isMultiTabLeader) {
+          // Only the leader pulls — followers receive subsequent
+          // applied broadcasts that close the catch-up window.
+          await this.pull();
+        }
       }
-      this.lastSeenTenant = tenantNow;
-      const prev = this._resolvedSession;
-      const changed =
-        prev.userId !== next.userId ||
-        prev.tenantId !== next.tenantId ||
-        prev.isAdmin !== next.isAdmin ||
-        prev.roles.join(",") !== next.roles.join(",");
-      if (changed) {
-        this._resolvedSession = next;
-        // Piggy-back on the store notifier so `useSession` re-renders via
-        // useSyncExternalStore without a second pub/sub channel.
+      this.session.commitObservation(next);
+      if (verdict.identityChanged) {
         this.store.notify();
       }
-    } catch {
-      // Swallow — /api/auth/me errors are transient and the next pull
-      // will retry. Don't take down the sync loop for this.
-    }
+      if (broadcast && this.isMultiTabLeader) {
+        this.broadcastToTabs({ type: "session", resolved: next });
+      }
+    }).catch(() => {});
+    return this.sessionChain;
   }
 
   private async rawFetch(path: string): Promise<Response> {
@@ -1716,34 +1631,32 @@ export class SyncEngine {
     return parsed;
   }
 
-  /**
-   * In-flight push promise. Used as a mutex so a slow push can't be restarted
-   * by the poll timer or a user mutation, which would resend the same batch
-   * and cause duplicate writes on the server. The mutation `op_id` keeps
-   * that safe at the protocol level (the server deduplicates), but shipping
-   * the same batch twice is still wasted bandwidth — hold them instead.
-   *
-   * Callers always get the SAME promise while a push is running; chain a
-   * `.then(() => next push)` if you need a follow-up push after this one.
-   */
-  private inFlightPush: Promise<void> | null = null;
-
-  /** Push pending mutations to the server. Coalesces concurrent callers. */
+  /** Push pending mutations to the server. Coalesces concurrent callers
+   *  via the op queue's keyed dedupe — a slow push can't be restarted
+   *  by the poll timer or a user mutation, which would resend the same
+   *  batch (the mutation `op_id` keeps that safe at the protocol level,
+   *  but shipping the same batch twice is still wasted bandwidth). Also
+   *  serializes against pull / reconcile / resetReplica so a push can't
+   *  observe a half-reset cursor or a mid-reconcile replica. */
   async push(): Promise<void> {
-    if (this.inFlightPush) {
-      return this.inFlightPush;
-    }
-    const work = this.pushInner().finally(() => {
-      this.inFlightPush = null;
-    });
-    this.inFlightPush = work;
-    return work;
+    return this.opQueue.enqueue("push", () => this.pushInner());
   }
 
   private async pushInner(): Promise<void> {
     const pending = this.mutations.pending();
     if (pending.length === 0) return;
 
+    // Multi-tab follower: we don't own the network. Forward the
+    // pending batch to the leader and let it push. The leader
+    // broadcasts `mutations-acked` when the server confirms; that
+    // path clears our queue. Note we don't clear locally here — if
+    // the leader dies before pushing, on promotion we still have
+    // the queue and can ship it ourselves.
+    if (!this.isMultiTabLeader) {
+      this.broadcastToTabs({ type: "mutations", ops: pending });
+      return;
+    }
+
     try {
       const resp = await this.request<PushResponse>("POST", "/api/sync/push", {
         changes: pending.map((m) => m.change),
@@ -1808,6 +1721,31 @@ export class SyncEngine {
         }
       }
 
+      // Broadcast per-op outcomes BEFORE clearing locally so followers
+      // can update their queue status. Filter strictly by current
+      // status — pending[i] is the LIVE PendingMutation that markApplied
+      // / markFailed just mutated, so `m.status` tells us exactly what
+      // happened. Ops that stayed "pending" (server-side in-flight
+      // dedupe) get neither — the leader will retry, and a later push
+      // will broadcast a real ack.
+      const ackedOpIds: string[] = [];
+      const failedOps: { opId: string; error: string }[] = [];
+      for (const m of pending) {
+        const opId = m.change.op_id;
+        if (typeof opId !== "string") continue;
+        if (m.status === "applied") {
+          ackedOpIds.push(opId);
+        } else if (m.status === "failed") {
+          failedOps.push({ opId, error: m.error ?? "unknown" });
+        }
+      }
+      if (ackedOpIds.length > 0) {
+        this.broadcastToTabs({ type: "mutations-acked", opIds: ackedOpIds });
+      }
+      if (failedOps.length > 0) {
+        this.broadcastToTabs({ type: "mutations-failed", ops: failedOps });
+      }
+
       this.mutations.clear();
 
       // Catch-up pull: if the server confirmed an apply at a seq
@@ -1974,9 +1912,11 @@ export class SyncEngine {
     return { ...this.cursor };
   }
 
-  /** Whether the WebSocket is currently connected. */
+  /** Whether the real-time transport is currently open. True for an
+   *  open WebSocket / EventSource and for a running poll loop; false
+   *  for a follower tab (no transport) or before start() / after stop(). */
   get connected(): boolean {
-    return this.ws?.readyState === WebSocket.OPEN;
+    return this.transport?.isOpen() ?? false;
   }
 
   // -----------------------------------------------------------------------
@@ -2016,13 +1956,7 @@ export class SyncEngine {
    * intervening unsubscribe just bumps the refcount.
    */
   subscribeCrdt(entity: string, rowId: string): void {
-    const key = `${entity}\x00${rowId}`;
-    const prev = this.crdtSubscribers.get(key) ?? 0;
-    this.crdtSubscribers.set(key, prev + 1);
-    if (prev === 0) {
-      this.crdtSubscriptions.add(key);
-      this.sendWs({ type: "crdt-subscribe", entity, rowId });
-    }
+    this.subscriptions.subscribeCrdt(entity, rowId);
   }
 
   /**
@@ -2035,16 +1969,7 @@ export class SyncEngine {
    * invocation in dev from over-decrementing past zero.
    */
   unsubscribeCrdt(entity: string, rowId: string): void {
-    const key = `${entity}\x00${rowId}`;
-    const prev = this.crdtSubscribers.get(key) ?? 0;
-    if (prev <= 0) return;
-    if (prev === 1) {
-      this.crdtSubscribers.delete(key);
-      this.crdtSubscriptions.delete(key);
-      this.sendWs({ type: "crdt-unsubscribe", entity, rowId });
-    } else {
-      this.crdtSubscribers.set(key, prev - 1);
-    }
+    this.subscriptions.unsubscribeCrdt(entity, rowId);
   }
 
   // -----------------------------------------------------------------------
@@ -2079,24 +2004,183 @@ export class SyncEngine {
     args: unknown,
     handler: (msg: ReactiveMessage) => void,
   ): void {
-    this.reactiveSpecs.set(sub_id, { fn_name, args });
-    this.reactiveHandlers.set(sub_id, handler);
-    this.sendWs({ type: "reactive-subscribe", sub_id, fn_name, args });
+    this.subscriptions.subscribeReactive(sub_id, fn_name, args, handler);
   }
 
   /** Tear down a reactive subscription. Sends the unsubscribe to the
    *  server and clears local state. No-op for unknown sub_ids — React
    *  StrictMode double-unmount won't error. */
   unsubscribeReactive(sub_id: string): void {
-    if (!this.reactiveSpecs.has(sub_id)) return;
-    this.reactiveSpecs.delete(sub_id);
-    this.reactiveHandlers.delete(sub_id);
-    this.sendWs({ type: "reactive-unsubscribe", sub_id });
+    this.subscriptions.unsubscribeReactive(sub_id);
   }
 
+  /** Send a JSON message via the active transport. No-op when no
+   *  transport exists (follower tab) or the transport doesn't support
+   *  uplink (SSE, polling). Subscribe / presence / topic / ping frames
+   *  all route here. */
   private sendWs(msg: unknown): void {
-    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify(msg));
+    this.transport?.send(msg);
+  }
+
+  /** Resolved transport kind, with the websocket default applied. */
+  private transportKind(): TransportKind {
+    return this.config.transport ?? "websocket";
+  }
+
+  /** Build the host surface the transport calls back into. One object
+   *  shared across transport lifetime — the engine fields it reads (
+   *  config, transport state, callbacks) are stable references. */
+  private transportHost(): TransportHost {
+    return {
+      baseUrl: this.config.baseUrl,
+      wsUrl: this.config.wsUrl,
+      pingIntervalMs: this.config.pingIntervalMs,
+      reconnectDelayMs: this.config.reconnectDelay,
+      pollIntervalMs: this.config.pollInterval,
+      getToken: () => this.currentToken() ?? undefined,
+      isLeader: () => this.isMultiTabLeader,
+      isRunning: () => this.running,
+      onChangeEvent: (ev) => {
+        void this.enqueueApply([ev]);
+      },
+      onJsonMessage: (msg) => this.dispatchInboundMessage(msg),
+      onBinaryFrame: (bytes) => this.dispatchBinaryFrame(bytes),
+      onConnected: () => {
+        // Re-send every active server-subscription (CRDT rows,
+        // reactive queries, future kinds) across the new socket. The
+        // server purges per-client subscription state on disconnect,
+        // so without this resync the subscriber's first event would
+        // never arrive.
+        this.serverSubs.replay();
+        // Pull-on-open catches every event broadcast in the gap
+        // between the prior pull() returning and the socket actually
+        // opening. Reconcile fires after the pull since pull is the
+        // cheap incremental path; reconcile is the server-truth
+        // backstop for anything pull couldn't replay.
+        void this.pull().then(() => this.reconcile());
+      },
+      onDisconnected: () => {
+        /* Engine has no work on disconnect — the transport's own
+         *  reconnect loop drives the recovery. The connection-status
+         *  flip already happened inside the transport. */
+      },
+      setStatus: (s) => this.setConnectionStatus(s),
+      performPollTick: async () => {
+        await this.push().then(() => this.pull());
+      },
+      performReconnectPull: async () => {
+        // Wrapped in try so a transient pull failure doesn't kill the
+        // reconnect chain; the next attempt will retry.
+        try {
+          await this.pull();
+        } catch {
+          /* best-effort */
+        }
+      },
+    };
+  }
+
+  /** Dispatch a typed JSON envelope inbound from the transport. The
+   *  transport already filtered out ChangeEvents (those go through
+   *  onChangeEvent → enqueueApply). Anything else lands here. */
+  private dispatchInboundMessage(msg: Record<string, unknown>): void {
+    // Presence event.
+    if (msg.type === "presence") {
+      this.store.notify();
+      return;
+    }
+
+    // Server-driven revocation: a subscriber whose read policy was
+    // revoked mid-session for a specific row. Drop the row from the
+    // local replica at the current cursor seq so the tombstone
+    // supersedes any racing late-arriving WS update for the same
+    // row, and notify any LoroDoc subscriber (registered via
+    // `addRowEvictionListener`) so collaborative doc handles unmount
+    // cleanly.
+    //
+    // Distinct from a regular Delete change event because this
+    // envelope has no global seq — the row's underlying data hasn't
+    // been deleted, only the recipient's visibility of it. Other
+    // subscribers (with matching policy) keep their row intact.
+    if (
+      msg.type === "row-revoked" &&
+      typeof msg.entity === "string" &&
+      typeof msg.row_id === "string"
+    ) {
+      const revokeSeq =
+        typeof msg.seq === "number" && msg.seq > 0
+          ? (msg.seq as number)
+          : this.cursor.last_seq;
+      this.handleRowRevocation(msg.entity, msg.row_id, revokeSeq);
+      return;
+    }
+
+    // Session mutated server-side. Fires for select-org / clear-org
+    // / session revoke — every tab connected as this user gets the
+    // envelope (cross-machine too via the cluster bus). Trigger a
+    // fresh /api/auth/me read which updates the cached session AND,
+    // on tenant flip, resets the replica so stale rows from the
+    // previous tenant disappear.
+    if (msg.type === "session-changed") {
+      void this.refreshResolvedSession();
+      return;
+    }
+
+    // Reactive query push: the server-side ReactiveRegistry re-ran a
+    // subscribed handler and the result hash changed. Route to the
+    // local handler if we own the subscription AND forward to follower
+    // tabs via the multi-tab channel so a follower's
+    // `useReactiveQuery` handler fires too.
+    if (msg.type === "reactive-result" && typeof msg.sub_id === "string") {
+      const payload = { kind: "result" as const, result: msg.result };
+      this.subscriptions.handleReactiveMessage(msg.sub_id, payload);
+      this.broadcastToTabs({
+        type: "reactive-msg",
+        sub_id: msg.sub_id,
+        payload,
+      });
+      return;
+    }
+    if (msg.type === "reactive-error" && typeof msg.sub_id === "string") {
+      const errPayload = {
+        kind: "error" as const,
+        code: typeof msg.code === "string" ? msg.code : "REACTIVE_ERROR",
+        message: typeof msg.message === "string" ? msg.message : "",
+      };
+      this.subscriptions.handleReactiveMessage(msg.sub_id, errPayload);
+      this.broadcastToTabs({
+        type: "reactive-msg",
+        sub_id: msg.sub_id,
+        payload: errPayload,
+      });
+      return;
+    }
+  }
+
+  /** Route a binary frame to local consumers AND, when at least one
+   *  follower tab forwarded a CRDT sub, mirror over the multi-tab
+   *  channel so followers see Loro updates too. */
+  private dispatchBinaryFrame(bytes: Uint8Array): void {
+    for (const handler of this.binaryHandlers) {
+      try {
+        handler(bytes);
+      } catch (err) {
+        console.warn("[sync] binary handler threw:", err);
+      }
+    }
+    // Forward to follower tabs ONLY when at least one follower is
+    // currently forwarded for a CRDT row. The engine is binary-
+    // agnostic — it can't peek inside the frame to route per-row —
+    // so this is a tab-level gate: no forwarders = no broadcast.
+    // Saves bandwidth in the common single-tab case.
+    //
+    // Trade-off: when ANY follower has forwarded a CRDT sub on ANY
+    // key, we broadcast EVERY binary frame regardless of which row
+    // it's for. Acceptable for now; the lever to pull if it shows
+    // up in profiling is a binaryRoutes map keyed by the Loro doc
+    // id parsed from the frame header.
+    if (this.subscriptions.hasCrdtForwarders()) {
+      this.broadcastToTabs({ type: "binary", bytes });
     }
   }
 
@@ -2212,19 +2296,6 @@ function rowsDiffer(a: Row, b: Row): boolean {
   return stableStringify(a) !== stableStringify(b);
 }
 
-/**
- * Compact, comparable fingerprint of a resolved session. Used by
- * reconcile() to detect mid-fetch identity flips — if the signature
- * differs, the rows we just fetched were policy-filtered under a
- * stale auth context and applying them would tombstone rows visible
- * under the new context. Roles array is sorted+joined so insertion
- * order doesn't trip the equality check.
- */
-function sessionSignature(s: ResolvedSession): string {
-  const roles = (s.roles ?? []).slice().sort().join(",");
-  return `${s.userId ?? ""}|${s.tenantId ?? ""}|${s.isAdmin ? "1" : "0"}|${roles}`;
-}
-
 function stableStringify(value: unknown): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) {