@pylonsync/sync 0.20.0 → 0.22.0

package/src/index.ts

@@ -55,6 +55,7 @@ export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
 export {
   MutationQueue,
+  MutationRejectedError,
   type MutationQueuePersistence,
   type PendingMutation,
 } from "./mutation-queue";
@@ -272,6 +273,28 @@ export class SyncEngine {
 
   private _initialSyncFallback: ReturnType<typeof setTimeout> | null = null;
 
+  /**
+   * True once a pull completed against the server in this run since the
+   * last replica reset. Unlike `isInitialSyncSettled()`, a warm cache does
+   * not set it and there is no fallback deadline: it stays false while the
+   * replica holds only what IndexedDB had (possibly stale or partial) and
+   * while the server is unreachable. A replica reset (identity or org
+   * switch, 410 resync) clears it until the re-pull lands. Follower tabs
+   * take it from the leader.
+   */
+  private _synced = false;
+  isSynced(): boolean {
+    return this._synced;
+  }
+
+  /** Flip `_synced` true (idempotent), notify, and tell follower tabs. */
+  private markSynced(): void {
+    if (this._synced) return;
+    this._synced = true;
+    this.store.notify();
+    if (this.isMultiTabLeader) this.broadcastToTabs({ type: "synced" });
+  }
+
   /** Flip `_initialSyncSettled` true (idempotent) + notify so `useQuery`
    *  re-reads and drops its loading state. */
   private markInitialSyncSettled(): void {
@@ -876,6 +899,8 @@ export class SyncEngine {
       if (pendingOps.length > 0) {
         this.broadcastToTabs({ type: "mutations", ops: pendingOps });
       }
+      // Ask the leader whether it has synced; it answers with `synced`.
+      this.broadcastToTabs({ type: "sync-status-request" });
       return;
     }
 
@@ -897,7 +922,9 @@ export class SyncEngine {
     // we don't get stuck without a session.
     const bootstrapSession = await sessionPromise;
     if (bootstrapSession !== null) {
-      await this.applySessionTransition(bootstrapSession, /* broadcast */ true);
+      await this.applySessionTransition(bootstrapSession.session, /* broadcast */ true, {
+        token: bootstrapSession.token,
+      });
     } else {
       await this.refreshResolvedSession();
     }
@@ -1037,6 +1064,16 @@ export class SyncEngine {
       onResetReceived: (wipeMutations: boolean) => {
         void this.resetReplicaInner({ wipeMutations });
       },
+      onSyncedReceived: () => {
+        if (this.isMultiTabLeader) return;
+        // Flip after the leader's earlier `applied` batches land here.
+        void this.applyQueue.then(() => this.markSynced());
+      },
+      onSyncStatusRequested: () => {
+        if (this.isMultiTabLeader && this._synced) {
+          this.broadcastToTabs({ type: "synced" });
+        }
+      },
       onSessionReceived: (resolved: ResolvedSession) => {
         // Funnel through the shared session chain so concurrent triggers
         // (broadcast + local notifySessionChanged) commit in arrival
@@ -1054,7 +1091,7 @@ export class SyncEngine {
           // DELETE the leader's still-valid row. The follower's prevRow
           // (its pre-edit value) equals the leader's canonical row, so
           // restoring it is correct on both tabs.
-          this.mutations.add(op.change, op.prevRow);
+          this.mutations.add(op.change, op.prevRow, op.owner, op.ownerPending);
         }
         void this.push();
       },
@@ -1062,7 +1099,14 @@ export class SyncEngine {
         for (const id of opIds) this.mutations.markApplied(id);
         this.mutations.clear();
       },
-      onMutationsFailed: (ops: { opId: string; error: string }[]) => {
+      onMutationsQueued: (opIds: string[]) => {
+        // The leader's push failed transiently; the writes stay queued
+        // and the leader retries them. Release this tab's callers.
+        for (const id of opIds) this.mutations.settleQueued(id);
+      },
+      onMutationsFailed: (
+        ops: { opId: string; error: string; code?: string }[],
+      ) => {
         // The leader pushed this follower's forwarded mutation and the
         // server rejected it. Roll back the follower's OWN optimistic
         // ghost (the leader already rolled back its copy) — calling
@@ -1071,10 +1115,14 @@ export class SyncEngine {
         // update/delete and removes the insert ghost, then marks failed.
         for (const op of ops) {
           const m = this.mutations.get(op.opId);
-          if (m) {
-            this.failPushedMutation(m, op.error);
+          if (op.code === "DISCARDED") {
+            // Another user is signed in: drop it without restoring rows
+            // of the old identity's replica.
+            this.mutations.discard(op.opId);
+          } else if (m) {
+            this.failPushedMutation(m, op.error, op.code);
           } else {
-            this.mutations.markFailed(op.opId, op.error);
+            this.mutations.markFailed(op.opId, op.error, op.code);
           }
         }
       },
@@ -1145,6 +1193,10 @@ export class SyncEngine {
           release();
         }
       },
+      onRoomSubResubscribe: (roomId: string) => {
+        if (!this.isMultiTabLeader) return;
+        this.rooms.resubscribe(roomId);
+      },
       onRoomFanoutSnapshot: (roomId: string, members: unknown) => {
         if (Array.isArray(members)) {
           this.rooms.applySnapshot(roomId, members as RoomMember[]);
@@ -1372,63 +1424,184 @@ export class SyncEngine {
       this.pullHold.push(...changes);
       return Promise.resolve();
     }
-    const prev = this.applyQueue;
-    const next = prev.then(async () => {
-      // 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) {
-        const durable = await this.store.applyChangesAsync(filtered);
+    // Reset fence (see `resetDepth`): live frames from the socket being
+    // replaced. The leader's broadcasts to a follower are NOT fenced:
+    // after its `reset` they already describe the new replica.
+    if (this.resetDepth > 0 && !opts.isPull && !opts.fromBroadcast) {
+      return Promise.resolve();
+    }
+    const epoch = this.replicaEpoch;
+    // Group commit for live frames (WS events, tab broadcasts without a
+    // pull cursor). While an earlier batch is still applying and writing
+    // to IndexedDB, frames that arrive join the next queued batch instead
+    // of queueing one apply + two IDB transactions each. The first frame
+    // after an idle period starts its batch at once, so batching adds no
+    // latency; under load each batch is one store notify and one IDB
+    // transaction (rows + cursor).
+    if (!opts.isPull && targetCursor === undefined) {
+      const fromBroadcast = opts.fromBroadcast === true;
+      const open = this.liveBatch;
+      if (open && open.fromBroadcast === fromBroadcast && open.epoch === epoch) {
+        open.changes.push(...changes);
+        return open.promise;
+      }
+      const batch: LiveBatch = {
+        changes: [...changes],
+        fromBroadcast,
+        epoch,
+        promise: Promise.resolve(),
+      };
+      batch.promise = this.chainApply(() => {
+        // Close the batch when it starts: frames from here on go into
+        // the next one, so each frame is applied exactly once, in order.
+        if (this.liveBatch === batch) this.liveBatch = null;
+        return this.applyBatch(batch.changes, undefined, { fromBroadcast }, epoch);
+      });
+      this.liveBatch = batch;
+      return batch.promise;
+    }
+    return this.chainApply(() => this.applyBatch(changes, targetCursor, opts, epoch));
+  }
+
+  /** Live frames waiting for their apply to start. See `enqueueApply`. */
+  private liveBatch: LiveBatch | null = null;
+
+  /** Bumped by every replica reset. An apply step records the epoch it
+   *  was queued in and drops its work when a reset happened since: its
+   *  changes belong to the replica that was wiped. */
+  private replicaEpoch = 0;
+  /** > 0 while `resetReplicaInner` runs. Live frames that arrive then
+   *  come from the socket of the replica being wiped; the pull that
+   *  follows every reset delivers anything current. */
+  private resetDepth = 0;
+
+  /**
+   * True from a token change until a session refresh says who the new
+   * token belongs to. While true, owned writes are not pushed (the
+   * owner can't be checked) and a push retries the refresh with backoff.
+   */
+  private identityPending = false;
+  /** Bearer token the committed session was fetched with (leader). A
+   *  push whose current token differs holds owned writes: the token may
+   *  belong to someone else. `undefined` until a session is committed. */
+  private sessionToken: string | null | undefined = undefined;
+  private identityRetryTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Delayed push / pull retries scheduled through `later()`. `stop()`
+   *  clears them, so a stopped engine makes no further requests. */
+  private retryTimers = new Set<ReturnType<typeof setTimeout>>();
+  private identityRetryAttempts = 0;
+
+  /** Chain one apply step behind every queued one. Anything chained
+   *  here closes the open live batch first, so later live frames can
+   *  never be applied ahead of it. Errors stay scoped to the step. */
+  private chainApply(step: () => Promise<void>): Promise<void> {
+    if (this.liveBatch) this.liveBatch = null;
+    const next = this.applyQueue.then(step);
+    this.applyQueue = next.catch(() => {});
+    return next;
+  }
+
+  /** Apply one batch: seq-filter, apply to memory, persist rows and the
+   *  advanced cursor, and fan out to follower tabs. Runs on the apply
+   *  queue only. */
+  private async applyBatch(
+    changes: ChangeEvent[],
+    targetCursor: SyncCursor | undefined,
+    opts: { fromBroadcast?: boolean; isPull?: boolean },
+    epoch: number,
+  ): Promise<void> {
+    // Queued before a replica reset: these changes belong to the wiped
+    // replica (another identity, or a cursor the server rejected).
+    if (epoch !== this.replicaEpoch) return;
+    // 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. A live batch holds
+    // frames that used to apply one at a time, so it filters against a
+    // running high mark: a frame at or below an earlier frame's seq is
+    // dropped exactly as it was when that frame had already advanced the
+    // cursor. A pull page keeps every change above the cursor.
+    const live = targetCursor === undefined && !opts.isPull;
+    let high = this.cursor.last_seq;
+    const filtered: ChangeEvent[] = [];
+    for (const c of changes) {
+      if (typeof c.seq !== "number") continue;
+      if (live ? c.seq > high : c.seq > this.cursor.last_seq) {
+        filtered.push(c);
+        if (c.seq > high) high = c.seq;
+      }
+    }
+    // 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
+    // from the last applied seq.
+    const candidate =
+      targetCursor ??
+      (filtered.length > 0
+        ? { last_seq: filtered[filtered.length - 1].seq }
+        : null);
+    const advance =
+      candidate && candidate.last_seq > this.cursor.last_seq ? candidate : null;
+    let cursorOnDisk = false;
+    if (filtered.length > 0) {
+      const persistence = this.persistence;
+      if (persistence?.saveBatch && this.store._persistFn) {
+        // One transaction for the rows and the advanced cursor: they
+        // commit or abort together. Once persistence degraded, the
+        // cursor stays frozen on disk (see `persistDegraded`).
+        const rows = this.store.applyInMemory(filtered);
+        const cursorToSave = advance && !this.persistDegraded ? advance : null;
+        const durable = await persistence.saveBatch(rows, cursorToSave);
+        if (!durable) this.persistDegraded = true;
+        cursorOnDisk = durable && cursorToSave !== null;
+      } else if (this.store._persistFn) {
+        // Row by row, in order. Stop writing once a reset happened: the
+        // reset cleared disk and later rows would land after it.
+        const rows = this.store.applyInMemory(filtered);
+        let durable = true;
+        for (const row of rows) {
+          if (epoch !== this.replicaEpoch) break;
+          const result = this.store._persistFn(row);
+          if (result instanceof Promise && (await result) === false) durable = false;
+        }
         // A row in this batch didn't reach disk (quota / abort). Latch
         // the degraded flag so we never persist a cursor ahead of the
         // durable replica — the next cold start must re-pull this gap.
         if (!durable) this.persistDegraded = true;
+      } else {
+        this.store.applyInMemory(filtered);
       }
-      // 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
-      // from the last applied seq.
-      const candidate =
-        targetCursor ??
-        (filtered.length > 0
-          ? { last_seq: filtered[filtered.length - 1].seq }
-          : null);
-      if (candidate && candidate.last_seq > this.cursor.last_seq) {
-        // In-memory cursor ALWAYS advances — live sync stays correct.
-        this.cursor = candidate;
-        // The on-disk cursor only advances while persistence is healthy.
-        // Once degraded, freezing it keeps disk self-consistent (cursor
-        // never exceeds the rows actually written) so restart re-pulls.
-        if (this.persistence && !this.persistDegraded) {
-          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,
-        });
+    }
+    // A reset ran while this batch was writing: it wiped memory and
+    // disk, so the cursor must not move back up to this batch's seqs.
+    if (epoch !== this.replicaEpoch) return;
+    if (advance) {
+      // In-memory cursor ALWAYS advances — live sync stays correct.
+      this.cursor = advance;
+      // The on-disk cursor only advances while persistence is healthy.
+      // Once degraded, freezing it keeps disk self-consistent (cursor
+      // never exceeds the rows actually written) so restart re-pulls.
+      if (this.persistence && !this.persistDegraded && !cursorOnDisk) {
+        await this.persistence.saveCursor(this.cursor);
       }
-    });
-    // Errors stay scoped to this batch — don't poison the chain for
-    // future applies.
-    this.applyQueue = next.catch(() => {});
-    return next;
+    }
+    // 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,
+      });
+    }
   }
 
   /**
@@ -1446,8 +1619,7 @@ export class SyncEngine {
     tombstoneSeq: number,
     opts: { fromBroadcast?: boolean } = {},
   ): Promise<void> {
-    const prev = this.applyQueue;
-    const next = prev.then(async () => {
+    return this.chainApply(async () => {
       await this.store.applyReconcileBatch(
         entity,
         upserts,
@@ -1468,13 +1640,17 @@ export class SyncEngine {
         });
       }
     });
-    this.applyQueue = next.catch(() => {});
-    return next;
   }
 
   /** Stop the sync engine. */
   stop(): void {
     this.running = false;
+    if (this.identityRetryTimer !== null) {
+      clearTimeout(this.identityRetryTimer);
+      this.identityRetryTimer = null;
+    }
+    for (const timer of this.retryTimers) clearTimeout(timer);
+    this.retryTimers.clear();
     if (this.transport) {
       this.transport.stop();
       this.transport = null;
@@ -1543,12 +1719,9 @@ export class SyncEngine {
     // queued writes should re-push under the user). For any other flip
     // (user A → user B, user → guest) discard them so one identity's
     // unsynced writes never push under another.
-    const isGuestToUser =
-      typeof prev === "string" &&
-      prev.startsWith("guest_") &&
-      typeof now === "string" &&
-      !now.startsWith("guest_");
-    await this.resetReplica({ wipeMutations: !isGuestToUser });
+    // Queued writes stay: each carries its owner, and push holds the ones
+    // of a signed-out user and discards the ones of another user.
+    await this.resetReplica({ wipeMutations: false });
     this.persistReplicaIdentity();
   }
 
@@ -1559,6 +1732,9 @@ export class SyncEngine {
    * the guard treats conservatively (no wipe, re-tag next run).
    */
   private persistReplicaIdentity(): void {
+    // Before /api/auth/me answered, the session is a placeholder: it
+    // says nothing about who owns the replica. Keep the old tag.
+    if (!this.session.hasObserved()) return;
     const id = this.session.resolved().userId;
     this._replicaIdentity = id;
     if (this.persistence && !this.persistDegraded) {
@@ -1578,6 +1754,19 @@ export class SyncEngine {
    */
   private async resetReplicaInner(
     opts: { wipeMutations?: boolean } = {},
+  ): Promise<void> {
+    this.replicaEpoch += 1;
+    this.liveBatch = null;
+    this.resetDepth += 1;
+    try {
+      await this.resetReplicaSteps(opts);
+    } finally {
+      this.resetDepth -= 1;
+    }
+  }
+
+  private async resetReplicaSteps(
+    opts: { wipeMutations?: boolean },
   ): Promise<void> {
     const wipeMutations = opts.wipeMutations === true;
     this.cursor = { last_seq: 0 };
@@ -1594,6 +1783,7 @@ export class SyncEngine {
     // the next line reached nobody. The documented protection above silently
     // did nothing: an org switch dropped straight to the new org's empty list.
     this._initialSyncSettled = false;
+    this._synced = false;
     this.armInitialSyncFallback();
     this.store.clearAll();
     // Disk is about to be wiped + re-pulled from 0, so any prior
@@ -1619,14 +1809,18 @@ export class SyncEngine {
     if (this.persistence) {
       try {
         await this.persistence.clear();
-        await this.persistence.saveCursor(this.cursor);
+        await this.persistence.saveCursor({ last_seq: 0 });
         // clear() wiped the cursor store (identity tag included). The
         // replica is about to be re-pulled for the CURRENT identity, so
         // re-tag it to match — otherwise the on-disk tag reads "unknown"
         // until the next cold-start pull re-records it.
-        const id = this.session.resolved().userId;
-        this._replicaIdentity = id;
-        await this.persistence.saveIdentity(id);
+        if (this.session.hasObserved()) {
+          const id = this.session.resolved().userId;
+          this._replicaIdentity = id;
+          await this.persistence.saveIdentity(id);
+        } else if (this._replicaIdentity !== undefined) {
+          await this.persistence.saveIdentity(this._replicaIdentity);
+        }
       } catch {
         /* best-effort */
       }
@@ -1765,20 +1959,27 @@ export class SyncEngine {
     // the replica from seq=0 under the new identity.
     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. Identity flipped, so
-      // wipe the old identity's pending offline writes.
-      await this.resetReplicaInner({ wipeMutations: true });
-      // 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();
       // The live socket was opened with the OLD token (the bearer rides
       // the WS subprotocol at connect time), so the server keeps
       // fanning out the previous identity's events to it. Cycle the
-      // transport: stop() closes the socket, start() reconnects and
+      // transport BEFORE the reset so no old-identity frame lands in the
+      // new replica: stop() closes the socket, start() reconnects and
       // reads the token fresh. The new socket's onConnected pull sees
       // the token as already observed, so this does not recurse.
       this.cycleTransport();
+      // Until the session refresh below says who the new token belongs
+      // to, owned writes wait (see `pushable`).
+      this.identityPending = true;
+      // We're holding the "pull" slot in the op queue — bypass the
+      // queue's reset path to avoid self-deadlock. Queued writes stay:
+      // each carries its owner, and push drops the ones that belong to
+      // someone else.
+      await this.resetReplicaInner({ wipeMutations: false });
+      // Token flipped → the cached tenant is for the previous user. Pull
+      // the fresh session in parallel with the cursor catch-up below.
+      // This pull already reset the replica and cycled the transport,
+      // so the session refresh must not do either a second time.
+      void this.refreshResolvedSession({ replicaAlreadyReset: true });
     }
 
     // Capture whether this pull started from cursor=0 BEFORE the
@@ -1894,6 +2095,7 @@ export class SyncEngine {
         this.pullHold = null;
         if (held.length > 0) await this.enqueueApply(held);
       }
+      this.markSynced();
     } catch (err) {
       // Settle any in-flight page apply before acting on the error —
       // the 410 path below wipes the replica, and an apply landing
@@ -1951,11 +2153,11 @@ export class SyncEngine {
           console.warn(
             `[pylon] persistent 410 RESYNC_REQUIRED (attempt ${attempt + 1}); backing off ${delayMs}ms`,
           );
-          setTimeout(() => {
+          this.later(delayMs, () => {
             // Retry after the delay; a delta success resets the counter,
             // a repeat 410 extends the backoff (no snapshot).
             void this.pull();
-          }, delayMs);
+          });
         }
       }
     } finally {
@@ -2095,19 +2297,55 @@ export class SyncEngine {
     if (entities === undefined && now - this.lastReconcileAt < minIntervalMs) {
       return;
     }
-    // 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();
-      }
-    });
+    if (entities === undefined) {
+      // Full sweeps coalesce via the queue's keyed dedupe — callers in
+      // the same window share one fetch per entity.
+      return this.opQueue.enqueue("reconcile", async () => {
+        try {
+          await this.reconcileInner();
+        } finally {
+          this.lastReconcileAt = Date.now();
+        }
+      });
+    }
+    // Scoped reconciles batch by entity: every call made before the
+    // batch starts running adds its entities to the batch, and all of
+    // them are fetched in parallel. A call made after the batch started
+    // opens a new batch, so no requested entity is dropped.
+    const open = this.scopedReconcileBatch;
+    if (open) {
+      for (const e of entities) open.entities.add(e);
+      return open.promise;
+    }
+    const batch: { entities: Set<string>; promise: Promise<void> } = {
+      entities: new Set(entities),
+      promise: Promise.resolve(),
+    };
+    this.scopedReconcileBatch = batch;
+    this.scopedReconcileSeq += 1;
+    batch.promise = this.opQueue.enqueue(
+      `reconcile-scoped:${this.scopedReconcileSeq}`,
+      async () => {
+        if (this.scopedReconcileBatch === batch) this.scopedReconcileBatch = null;
+        try {
+          await this.reconcileInner([...batch.entities]);
+        } finally {
+          this.lastReconcileAt = Date.now();
+        }
+      },
+    );
+    return batch.promise;
   }
 
+  /** Scoped reconcile batch that has not started running yet. */
+  private scopedReconcileBatch: {
+    entities: Set<string>;
+    promise: Promise<void>;
+  } | null = null;
+  private scopedReconcileSeq = 0;
+
   private async reconcileInner(entities?: string[]): Promise<void> {
     // Same reasoning as pullInner: the leader reconciles, broadcasts
     // results, and follower replicas converge via the channel.
@@ -2365,14 +2603,19 @@ export class SyncEngine {
    * On tenant flip this also resets the replica — same logic as the
    * token-flip path, for the same reason (visible set changed).
    */
-  async refreshResolvedSession(): Promise<void> {
+  async refreshResolvedSession(
+    opts: { replicaAlreadyReset?: boolean } = {},
+  ): 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;
     const next = await this.fetchSessionBootstrap();
     if (next === null) return;
-    await this.applySessionTransition(next, /* broadcast */ true);
+    await this.applySessionTransition(next.session, /* broadcast */ true, {
+      ...opts,
+      token: next.token,
+    });
   }
 
   /**
@@ -2389,8 +2632,11 @@ export class SyncEngine {
    * caller's next pull cycle (or the WS `session-changed` envelope)
    * will retry. Errors must not abort bootstrap.
    */
-  private async fetchSessionBootstrap(): Promise<ResolvedSession | null> {
+  private async fetchSessionBootstrap(): Promise<
+    { session: ResolvedSession; token: string | null } | null
+  > {
     try {
+      const token = this.currentToken();
       const res = await this.rawFetch("/api/auth/me");
       if (!res.ok) return null;
       const raw = (await res.json()) as {
@@ -2402,11 +2648,14 @@ export class SyncEngine {
       };
       if ((raw.user_id ?? null) === null) this.warnForeignToken();
       return {
-        userId: raw.user_id ?? null,
-        tenantId: raw.tenant_id ?? null,
-        isAdmin: raw.is_admin ?? false,
-        roles: raw.roles ?? [],
-        avatarUrl: raw.avatar_url ?? null,
+        token,
+        session: {
+          userId: raw.user_id ?? null,
+          tenantId: raw.tenant_id ?? null,
+          isAdmin: raw.is_admin ?? false,
+          roles: raw.roles ?? [],
+          avatarUrl: raw.avatar_url ?? null,
+        },
       };
     } catch {
       // Swallow — /api/auth/me errors are transient and the next pull
@@ -2463,6 +2712,7 @@ export class SyncEngine {
   private applySessionTransition(
     next: ResolvedSession,
     broadcast: boolean,
+    opts: { replicaAlreadyReset?: boolean; token?: string | null } = {},
   ): Promise<void> {
     const prev = this.sessionChain;
     // Swallow errors when storing back to the chain so a single
@@ -2476,7 +2726,38 @@ export class SyncEngine {
       // 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) {
+      const prevUserId = this.session.resolved().userId;
+      // USER flip (sign-in, sign-out, account switch) observed on a
+      // session refresh. The rows, the cursor, and the live socket all
+      // belong to the previous identity, and a tenant verdict alone
+      // misses the common case where both sides have no tenant
+      // (anonymous → signed in). Wipe, reconnect as the new identity,
+      // and pull every entity from zero. Always wipes, whatever
+      // `resetOnTenantFlip` says.
+      //
+      // Leader only. A follower hears about the flip from the leader's
+      // `session` message, which arrives AFTER the leader's `reset` and
+      // the re-pulled rows; acting on it again would wipe those rows and
+      // the IndexedDB the tabs share.
+      const userFlipped =
+        this.session.hasObserved() && prevUserId !== next.userId;
+      if (userFlipped && this.isMultiTabLeader) {
+        // Owned writes wait until the new identity is committed below.
+        this.identityPending = true;
+        if (!opts.replicaAlreadyReset) {
+          // Mark the current token as seen so the pull below does not
+          // detect the same flip and reset a second time.
+          this.session.observeToken(this.currentToken());
+          // Close the old identity's socket before the wipe so none of
+          // its frames land in the new replica.
+          this.cycleTransport();
+          // Queued writes stay: each carries its owner, and push drops
+          // the ones that belong to someone else.
+          await this.resetAndPull({ wipeMutations: false });
+        }
+      } else if (userFlipped) {
+        // Follower: the leader's reset already wiped this tab.
+      } else if (verdict.tenantChanged && !opts.replicaAlreadyReset) {
         // `resetOnTenantFlip: false` — the app has declared its read
         // policies MEMBERSHIP-scoped, so the replica is already valid
         // for every org the user belongs to and the wipe would be pure
@@ -2484,21 +2765,20 @@ export class SyncEngine {
         // Only the TENANT verdict honors the flag; user flips (token
         // change, guardReplicaIdentity) always wipe.
         const skipReset = this.config.resetOnTenantFlip === false;
-        if (verdict.replicaInvalidated && !skipReset) {
-          // 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. Identity flipped → wipe the outgoing
-          // identity's pending offline writes too.
-          await this.resetReplica({ wipeMutations: true });
+        // Leader only, like the user flip above: a follower's replica is
+        // wiped by the leader's `reset` message.
+        const reset =
+          verdict.replicaInvalidated && !skipReset && this.isMultiTabLeader;
+        if (reset) {
+          // Reset and re-pull in one op-queue slot (see resetAndPull).
+          // The tenant's view changed → wipe the outgoing tenant's
+          // pending offline writes too.
+          await this.resetAndPull({ wipeMutations: true });
         }
         if (this.isMultiTabLeader) {
           // Only the leader pulls — followers receive subsequent
           // applied broadcasts that close the catch-up window.
-          await this.pull();
+          if (!reset) await this.pull();
           if (skipReset) {
             // No wipe happened, so rows of an org the user only just
             // JOINED aren't in the replica and no change event will
@@ -2510,6 +2790,22 @@ export class SyncEngine {
       }
       const firstResolution = !this.session.hasObserved();
       this.session.commitObservation(next);
+      // The reset above tagged the replica with the outgoing user (the
+      // session was not committed yet). Re-tag it with the new owner.
+      if (userFlipped && this.isMultiTabLeader) this.persistReplicaIdentity();
+      // The session now says who the token belongs to: push writes
+      // that were waiting for it (their owner may be this user).
+      if (this.isMultiTabLeader) {
+        const wasPending = this.identityPending || firstResolution;
+        if (opts.token !== undefined) this.sessionToken = opts.token;
+        // Writes made before any session resolved belong to this one.
+        if (firstResolution) this.mutations.stampPendingOwner(next.userId);
+        this.identityPending = false;
+        this.identityRetryAttempts = 0;
+        if ((wasPending || userFlipped) && this.mutations.pending().length > 0) {
+          void this.push();
+        }
+      }
       if (verdict.identityChanged || firstResolution) {
         // The first answer flips `sessionResolved()` even when the
         // session itself matches the placeholder (anonymous caller).
@@ -2522,6 +2818,76 @@ export class SyncEngine {
     return this.sessionChain;
   }
 
+  /** Reset the replica and pull from zero in ONE op-queue slot, so no
+   *  live frame can move the cursor between the reset and the pull's
+   *  hold (the pull would then run as a delta and miss rows). */
+  private resetAndPull(opts: { wipeMutations: boolean }): Promise<void> {
+    return this.opQueue.enqueue("reset-pull", async () => {
+      await this.resetReplicaInner(opts);
+      await this.pullInner();
+    }).then(() => {
+      if (this.isMultiTabLeader) this.markInitialSyncSettled();
+    });
+  }
+
+  /** The user a write made now belongs to: the resolved session, or,
+   *  before `/api/auth/me` answered this run, the identity the replica
+   *  was tagged with on disk. `undefined` = unknown. */
+  private currentOwner(): string | null | undefined {
+    if (this.session.hasObserved()) return this.session.resolved().userId;
+    return this._replicaIdentity;
+  }
+
+  /**
+   * Decide what push does with a queued write, by its owner:
+   * - `send`: it belongs to the signed-in user (or its owner is unknown,
+   *   an older client's write), or a guest's write after that guest
+   *   signed in (the server merges the guest's rows into the account).
+   * - `hold`: nobody is signed in, or a token change has not resolved
+   *   yet. The write waits for the next identity.
+   * - `discard`: another user is signed in. The write is dropped so one
+   *   user's writes never push as another's.
+   */
+  private pushable(
+    m: PendingMutation,
+    token: string | null,
+  ): "send" | "hold" | "discard" {
+    if (m.ownerPending) return "hold";
+    if (m.owner === undefined) return "send";
+    if (this.identityPending || !this.session.hasObserved()) return "hold";
+    // The token changed since the session was fetched: it may be someone
+    // else's. Hold until a refresh says whose it is.
+    if (this.sessionToken !== undefined && token !== this.sessionToken) {
+      this.identityPending = true;
+      return "hold";
+    }
+    const now = this.session.resolved().userId;
+    if (m.owner === now) return "send";
+    if (now === null) return "hold";
+    if (typeof m.owner === "string" && m.owner.startsWith("guest_") && !now.startsWith("guest_")) {
+      return "send";
+    }
+    return "discard";
+  }
+
+  /** A push found writes waiting on an unresolved token change. Retry the
+   *  session refresh with backoff (1 s, 2 s, ... 30 s) until it answers;
+   *  the refresh then pushes them. */
+  private scheduleIdentityRetry(): void {
+    if (this.identityRetryTimer !== null || !this.running) return;
+    const attempt = this.identityRetryAttempts;
+    this.identityRetryAttempts += 1;
+    const delay = Math.min(30_000, 1000 * 2 ** Math.min(attempt, 5));
+    this.identityRetryTimer = setTimeout(() => {
+      this.identityRetryTimer = null;
+      void this.refreshResolvedSession().then(() => {
+        if (this.identityPending || !this.session.hasObserved()) {
+          this.scheduleIdentityRetry();
+        }
+      });
+    }, delay);
+  }
+
   private async rawFetch(path: string): Promise<Response> {
     const headers: Record<string, string> = {};
     const token = this.currentToken();
@@ -2647,9 +3013,9 @@ export class SyncEngine {
 
   /**
    * Revoke the current session server-side (DELETE /api/auth/session)
-   * and refresh — leaves the caller anonymous. Local sync stops on
-   * the next pull cycle; replica content stays in IndexedDB so a
-   * subsequent sign-in as the same user is instant.
+   * and refresh — leaves the caller anonymous. The refresh sees the
+   * user flip, wipes the replica (memory and IndexedDB), and re-pulls
+   * as the anonymous identity.
    */
   async signOut(): Promise<void> {
     await this.authMutate("/api/auth/session", undefined, "DELETE");
@@ -2743,29 +3109,83 @@ export class SyncEngine {
    *  serializes against pull / reconcile / resetReplica so a push can't
    *  observe a half-reset cursor or a mid-reconcile replica. */
   async push(): Promise<void> {
-    return this.opQueue.enqueue("push", () => this.pushInner());
+    await this.opQueue.enqueue("push", () => this.pushInner());
+    // A call made while a push was already running got that push's
+    // promise, but that push had snapshotted its batch before this
+    // caller's mutation was queued. Send any mutation no push has
+    // attempted yet. Mutations that failed transiently were attempted
+    // and wait for their backoff retry instead.
+    if (this.mutations.pending().some((m) => !this.attemptedOps.has(m.id))) {
+      await this.push();
+    }
   }
 
+  /** Op ids of pending mutations that some push already sent (or
+   *  forwarded to the leader). */
+  private attemptedOps = new Set<string>();
+
   private async pushInner(): Promise<void> {
-    const pending = this.mutations.pending();
-    if (pending.length === 0) return;
+    const queued = this.mutations.pending();
+    // Keep the attempted set bounded to what is still pending.
+    const pendingIds = new Set(queued.map((m) => m.id));
+    for (const id of this.attemptedOps) {
+      if (!pendingIds.has(id)) this.attemptedOps.delete(id);
+    }
+    for (const id of pendingIds) this.attemptedOps.add(id);
+    if (queued.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.
+    // the queue and can ship it ourselves. The leader checks each
+    // write's owner.
     if (!this.isMultiTabLeader) {
-      this.broadcastToTabs({ type: "mutations", ops: pending });
+      this.broadcastToTabs({ type: "mutations", ops: queued });
       return;
     }
 
+    // Owner check (see `pushable`). Discarded writes leave the queue with
+    // code DISCARDED, here and in the tab that made them; their rows were
+    // wiped with the old identity's replica, so nothing is rolled back.
+    // Held writes stay queued; their callers are released.
+    const token = this.currentToken();
+    const pending: PendingMutation[] = [];
+    const discarded: { opId: string; error: string; code: string }[] = [];
+    const held: string[] = [];
+    for (const m of queued) {
+      const verdict = this.pushable(m, token);
+      if (verdict === "send") {
+        pending.push(m);
+      } else if (verdict === "discard") {
+        this.mutations.discard(m.id);
+        discarded.push({ opId: m.id, error: "discarded: another user is signed in", code: "DISCARDED" });
+      } else {
+        this.mutations.settleQueued(m.id);
+        held.push(m.id);
+      }
+    }
+    if (discarded.length > 0) this.broadcastToTabs({ type: "mutations-failed", ops: discarded });
+    if (held.length > 0) {
+      this.broadcastToTabs({ type: "mutations-queued", opIds: held });
+      if (this.identityPending || !this.session.hasObserved()) {
+        this.scheduleIdentityRetry();
+      }
+    }
+    if (pending.length === 0) return;
+
     try {
-      const resp = await this.request<PushResponse>("POST", "/api/sync/push", {
-        changes: pending.map((m) => m.change),
-        client_id: this.clientId,
-      });
+      // Sent with the token the owner check ran against.
+      const resp = await this.request<PushResponse>(
+        "POST",
+        "/api/sync/push",
+        {
+          changes: pending.map((m) => m.change),
+          client_id: this.clientId,
+        },
+        token,
+      );
       // The request reached the server and returned a response — clear
       // the transient-failure backoff counter (success or per-op
       // rejections both mean "we're online and the server answered").
@@ -2787,7 +3207,12 @@ export class SyncEngine {
           const r =
             (m.change.op_id ? byOpId.get(m.change.op_id) : undefined) ??
             resp.results[i];
-          if (!r) continue;
+          if (!r) {
+            // No verdict for this op: it stays queued for the next push.
+            // Release its caller like a transient failure.
+            this.mutations.settleQueued(m.id);
+            continue;
+          }
           // applied: first-time commit at r.seq.
           // replayed: same op_id arrived again after a confirmed apply;
           // r.seq is the original write's seq. Both are terminal-success
@@ -2810,7 +3235,11 @@ export class SyncEngine {
               typeof r.error === "string"
                 ? r.error
                 : r.error?.message ?? "unknown";
-            this.failPushedMutation(m, msg);
+            const code =
+              typeof r.error === "object" && r.error !== null
+                ? r.error.code
+                : undefined;
+            this.failPushedMutation(m, msg, code);
           }
         }
       } else {
@@ -2827,6 +3256,8 @@ export class SyncEngine {
             this.mutations.markApplied(pending[i].id);
           } else if (errors[i - applied]) {
             this.failPushedMutation(pending[i], errors[i - applied]);
+          } else {
+            this.mutations.settleQueued(pending[i].id);
           }
         }
       }
@@ -2839,14 +3270,14 @@ export class SyncEngine {
       // 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 }[] = [];
+      const failedOps: { opId: string; error: string; code?: 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" });
+          failedOps.push({ opId, error: m.error ?? "unknown", code: m.errorCode });
         }
       }
       if (ackedOpIds.length > 0) {
@@ -2878,9 +3309,9 @@ export class SyncEngine {
       // takes the Proceed slot). 250ms is short enough that user
       // perception doesn't notice, long enough to not hot-loop.
       if (hasInFlightDedupe) {
-        setTimeout(() => {
+        this.later(250, () => {
           void this.push();
-        }, 250);
+        });
       }
     } catch (err) {
       // Whole-request failure. CRITICAL distinction:
@@ -2900,13 +3331,14 @@ export class SyncEngine {
       //    roll back the optimistic ghost + surface mutations-failed.
       const msg = err instanceof Error ? err.message : String(err);
       const status = (err as { status?: number })?.status;
+      const code = (err as { code?: string })?.code;
       if (isPermanentPushError(status)) {
-        const failedOps: { opId: string; error: string }[] = [];
+        const failedOps: { opId: string; error: string; code?: string }[] = [];
         for (const m of pending) {
-          this.failPushedMutation(m, msg);
+          this.failPushedMutation(m, msg, code);
           const opId = m.change.op_id;
           if (typeof opId === "string") {
-            failedOps.push({ opId, error: msg });
+            failedOps.push({ opId, error: msg, code });
           }
         }
         if (failedOps.length > 0) {
@@ -2921,6 +3353,16 @@ export class SyncEngine {
         // per-op rejection). A 429 also pushes the WS reconnect out so a
         // rate-limited push doesn't drive a tight loop.
         if (status === 429) this.transport?.bumpReconnect(3);
+        // The writes stay queued and retry below. Release the callers
+        // awaiting them (here and in follower tabs): the optimistic rows
+        // are in place, and a later rejection shows up as a failed
+        // mutation.
+        const queuedOpIds: string[] = [];
+        for (const m of pending) {
+          this.mutations.settleQueued(m.id);
+          queuedOpIds.push(m.id);
+        }
+        this.broadcastToTabs({ type: "mutations-queued", opIds: queuedOpIds });
         const attempt = this.pushFailureCount;
         this.pushFailureCount += 1;
         const delayMs = Math.min(30_000, 1000 * 2 ** Math.min(attempt, 5));
@@ -2928,13 +3370,23 @@ export class SyncEngine {
         console.warn(
           `[sync] /api/sync/push transient failure (status ${status ?? "offline"}); keeping ${pending.length} mutation(s) pending, retrying in ${delayMs}ms`,
         );
-        setTimeout(() => {
+        this.later(delayMs, () => {
           void this.push();
-        }, delayMs);
+        });
       }
     }
   }
 
+  /** Run `fn` after `ms` unless the engine stops first. A retry from a
+   *  stopped engine would otherwise still reach the network. */
+  private later(ms: number, fn: () => void): void {
+    const timer = setTimeout(() => {
+      this.retryTimers.delete(timer);
+      if (this.running) fn();
+    }, ms);
+    this.retryTimers.add(timer);
+  }
+
   /**
    * Mark a pending mutation as failed AND undo its optimistic ghost
    * in the local replica. Without the rollback step, a server-
@@ -2953,7 +3405,11 @@ export class SyncEngine {
    * insert; collaborative-edit is an update with a separate CRDT
    * channel) so insert-only rollback is the right shape to ship now.
    */
-  private failPushedMutation(m: PendingMutation, error: string): void {
+  private failPushedMutation(
+    m: PendingMutation,
+    error: string,
+    code?: string,
+  ): void {
     const { entity, row_id, kind } = m.change;
     if (kind === "insert") {
       // No tombstone — a future legitimate insert of this id must work.
@@ -2972,10 +3428,18 @@ export class SyncEngine {
         this.store.restoreRow(entity, row_id, m.prevRow);
       }
     }
-    this.mutations.markFailed(m.id, error);
+    this.mutations.markFailed(m.id, error, code);
   }
 
   /** Insert a row with optimistic local update.
+   *
+   *  The row is in the local store before this returns a promise. The
+   *  promise resolves with the row id once the server applies the write,
+   *  or once the write is queued because the server could not be reached
+   *  (offline, 5xx); a queued write that the server rejects later shows up
+   *  as a failed mutation. The promise rejects with a
+   *  `MutationRejectedError` when the server rejects the write (policy
+   *  denial, validation); the optimistic row is removed first.
    *
    *  Invariant: the optimistic ghost and the canonical server row
    *  share a single id. The client mints a Pylon-shaped id, threads
@@ -2986,17 +3450,50 @@ export class SyncEngine {
     const id = generateId();
     const dataWithId = { ...data, id };
     this.store.optimisticInsertWithId(entity, id, dataWithId);
-    this.mutations.add({
-      entity,
-      row_id: id,
-      kind: "insert",
-      data: dataWithId,
-    });
-    await this.push();
+    const opId = this.mutations.add(
+      {
+        entity,
+        row_id: id,
+        kind: "insert",
+        data: dataWithId,
+      },
+      undefined,
+      this.currentOwner(),
+      this.currentOwner() === undefined,
+    );
+    await this.sendAndAwait(opId);
     return id;
   }
 
-  /** Update a row with optimistic local update. */
+  /** Push, then wait for the mutation's outcome. The wait starts before
+   *  the push so an outcome that lands during the push is not missed. */
+  private async sendAndAwait(opId: string): Promise<void> {
+    const outcome = this.mutations.waitForOutcome(opId);
+    // Mark the promise handled: push() can settle it before we await it.
+    outcome.catch(() => {});
+    await this.push();
+    if (!this.isMultiTabLeader) {
+      // A follower forwards the write and waits for the leader's verdict.
+      // A frozen or dying leader must not hang the caller: after the
+      // timeout the write counts as queued (a later verdict still rolls it
+      // back and marks it failed).
+      const timer = setTimeout(
+        () => this.mutations.settleQueued(opId),
+        FOLLOWER_OUTCOME_TIMEOUT_MS,
+      );
+      try {
+        await outcome;
+      } finally {
+        clearTimeout(timer);
+      }
+      return;
+    }
+    await outcome;
+  }
+
+  /** Update a row with optimistic local update. Settles like `insert`:
+   *  rejects with a `MutationRejectedError` (after restoring the prior
+   *  value) when the server rejects the write. */
   async update(entity: string, id: string, data: Partial<Row>): Promise<void> {
     // Snapshot the pre-update row BEFORE applying the optimistic merge so
     // a rejected push can restore the exact prior value (see
@@ -3004,7 +3501,7 @@ export class SyncEngine {
     const before = this.store.get(entity, id);
     const prev = before ? { ...before } : null;
     this.store.optimisticUpdate(entity, id, data);
-    this.mutations.add(
+    const opId = this.mutations.add(
       {
         entity,
         row_id: id,
@@ -3012,26 +3509,32 @@ export class SyncEngine {
         data: data as Row,
       },
       prev,
+      this.currentOwner(),
+      this.currentOwner() === undefined,
     );
-    await this.push();
+    await this.sendAndAwait(opId);
   }
 
-  /** Delete a row with optimistic local update. */
+  /** Delete a row with optimistic local update. Settles like `insert`:
+   *  rejects with a `MutationRejectedError` (after restoring the row)
+   *  when the server rejects the delete. */
   async delete(entity: string, id: string): Promise<void> {
     // Snapshot the row before removing it so a rejected delete can bring
     // it back (and clear the optimistic tombstone).
     const before = this.store.get(entity, id);
     const prev = before ? { ...before } : null;
     this.store.optimisticDelete(entity, id);
-    this.mutations.add(
+    const opId = this.mutations.add(
       {
         entity,
         row_id: id,
         kind: "delete",
       },
       prev,
+      this.currentOwner(),
+      this.currentOwner() === undefined,
     );
-    await this.push();
+    await this.sendAndAwait(opId);
   }
 
   // -----------------------------------------------------------------------
@@ -3360,6 +3863,18 @@ export class SyncEngine {
     }
   }
 
+  /** Re-send `room-subscribe` for a room this tab is subscribed to and
+   *  clear its error. Call after rejoining the room over HTTP following a
+   *  `NOT_IN_ROOM` error; the server replies with a fresh snapshot. A
+   *  follower asks the leader, which owns the wire subscription. */
+  resubscribeRoom(roomId: string): void {
+    if (this.isMultiTabLeader) {
+      this.rooms.resubscribe(roomId);
+      return;
+    }
+    this.broadcastToTabs({ type: "room-sub-resubscribe", room: roomId });
+  }
+
   /** Read the current cached members snapshot for `roomId`. Returns
    *  `null` when no snapshot has landed yet (distinct from `[]` for
    *  an empty room). */
@@ -3671,7 +4186,12 @@ export class SyncEngine {
     this.lastCrdtFrames.delete(`${entity}|${rowId}`);
   }
 
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    tokenOverride?: string | null,
+  ): Promise<T> {
     const headers: Record<string, string> = {};
     if (body) headers["Content-Type"] = "application/json";
     // Prefer the token explicitly configured on the engine; fall back to
@@ -3680,9 +4200,11 @@ export class SyncEngine {
     // anonymous caller and gets rate-limited into a 429 reconnect storm
     // once the anon bucket fills.
     const token =
-      this.config.token ??
-      this.storage.get(this.tokenStorageKey()) ??
-      undefined;
+      tokenOverride !== undefined
+        ? tokenOverride ?? undefined
+        : this.config.token ??
+          this.storage.get(this.tokenStorageKey()) ??
+          undefined;
     if (token) headers["Authorization"] = `Bearer ${token}`;
 
     // credentials: "include" so cookie-auth apps (Yapless and any other
@@ -3705,8 +4227,22 @@ export class SyncEngine {
       // loop uses this to decide whether to back off.
       const err = new Error(`Sync request failed: ${res.status}`) as Error & {
         status?: number;
+        code?: string;
       };
       err.status = res.status;
+      // Carry the server's error envelope ({ error: { code, message } })
+      // so a rejected push can tell the caller why.
+      try {
+        const body = (await res.json()) as {
+          error?: { code?: string; message?: string };
+        };
+        if (typeof body?.error?.code === "string") err.code = body.error.code;
+        if (typeof body?.error?.message === "string") {
+          err.message = body.error.message;
+        }
+      } catch {
+        // Not JSON (proxy error page, empty body): keep the status text.
+      }
       throw err;
     }
 
@@ -3718,6 +4254,19 @@ export class SyncEngine {
 // SSR / Hydration types
 // ---------------------------------------------------------------------------
 
+/** How long a follower tab's insert/update/delete waits for the leader's
+ *  verdict before it resolves as queued. */
+const FOLLOWER_OUTCOME_TIMEOUT_MS = 5_000;
+
+/** Live change frames queued for one apply step (see `enqueueApply`). */
+interface LiveBatch {
+  changes: ChangeEvent[];
+  fromBroadcast: boolean;
+  /** `replicaEpoch` when the batch opened. */
+  epoch: number;
+  promise: Promise<void>;
+}
+
 /** Data shape for hydrating the client from server-rendered content. */
 export interface HydrationData {
   /** Map of entity name -> rows fetched on the server. */