@pylonsync/sync 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { ReplicaPersistence } from "./persistence";
 export { buildRequest, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
 export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
-export { MutationQueue, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
+export { MutationQueue, MutationRejectedError, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
 export { generateId } from "./ids";
 export type { ChangeEvent, ClientChange, PullResponse, PushOpResult, PushResponse, ReactiveMessage, ReactiveSpec, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType, } from "./types";
 export { defaultStorage, createWriteThroughStorage, type Storage, } from "./storage";
@@ -171,6 +171,19 @@ export declare class SyncEngine {
     private _initialSyncSettled;
     isInitialSyncSettled(): boolean;
     private _initialSyncFallback;
+    /**
+     * 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;
+    isSynced(): boolean;
+    /** Flip `_synced` true (idempotent), notify, and tell follower tabs. */
+    private markSynced;
     /** Flip `_initialSyncSettled` true (idempotent) + notify so `useQuery`
      *  re-reads and drops its loading state. */
     private markInitialSyncSettled;
@@ -502,6 +515,39 @@ export declare class SyncEngine {
      * against the local store.
      */
     private enqueueApply;
+    /** Live frames waiting for their apply to start. See `enqueueApply`. */
+    private liveBatch;
+    /** 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 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;
+    /**
+     * 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;
+    /** 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;
+    private identityRetryTimer;
+    /** Delayed push / pull retries scheduled through `later()`. `stop()`
+     *  clears them, so a stopped engine makes no further requests. */
+    private retryTimers;
+    private identityRetryAttempts;
+    /** 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;
+    /** 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 applyBatch;
     /**
      * Reconcile path. Routes through the same applyQueue as WS/pull so
      * a reconcile batch can't interleave with a fresher change event
@@ -561,6 +607,7 @@ export declare class SyncEngine {
      *   replayed as the incoming one (cross-identity write leak).
      */
     private resetReplicaInner;
+    private resetReplicaSteps;
     /**
      * localStorage key for the auth token, namespaced by appName. Matches
      * the key the React package's `configureClient` writes to so the sync
@@ -698,6 +745,9 @@ export declare class SyncEngine {
      */
     observeEntity(entity: string): void;
     reconcile(entities?: string[]): Promise<void>;
+    /** Scoped reconcile batch that has not started running yet. */
+    private scopedReconcileBatch;
+    private scopedReconcileSeq;
     private reconcileInner;
     /** Fetch every row for an entity. Uses cursor pagination so big tables
      *  don't blow past server-side limits; loops until `has_more` is false
@@ -721,7 +771,9 @@ export declare class SyncEngine {
      * On tenant flip this also resets the replica — same logic as the
      * token-flip path, for the same reason (visible set changed).
      */
-    refreshResolvedSession(): Promise<void>;
+    refreshResolvedSession(opts?: {
+        replicaAlreadyReset?: boolean;
+    }): Promise<void>;
     /**
      * Pure HTTP fetch of /api/auth/me → ResolvedSession. Unlike
      * `refreshResolvedSession`, this does NOT gate on `isMultiTabLeader`
@@ -763,6 +815,29 @@ export declare class SyncEngine {
      * the newer one.
      */
     private applySessionTransition;
+    /** 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;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
     private rawFetch;
     /**
      * Public alias for `refreshResolvedSession`. Almost never needed by
@@ -829,9 +904,9 @@ export declare class SyncEngine {
     clearOrg(): Promise<void>;
     /**
      * 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.
      */
     signOut(): Promise<void>;
     /** Relay mode: fetch a fresh signed connect target from the machine
@@ -853,7 +928,13 @@ export declare class SyncEngine {
      *  serializes against pull / reconcile / resetReplica so a push can't
      *  observe a half-reset cursor or a mid-reconcile replica. */
     push(): Promise<void>;
+    /** Op ids of pending mutations that some push already sent (or
+     *  forwarded to the leader). */
+    private attemptedOps;
     private pushInner;
+    /** Run `fn` after `ms` unless the engine stops first. A retry from a
+     *  stopped engine would otherwise still reach the network. */
+    private later;
     /**
      * Mark a pending mutation as failed AND undo its optimistic ghost
      * in the local replica. Without the rollback step, a server-
@@ -874,6 +955,14 @@ export declare class SyncEngine {
      */
     private failPushedMutation;
     /** 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
@@ -881,9 +970,16 @@ export declare class SyncEngine {
      *  canonical insert. Test:
      *  `insert_optimistic_ghost_and_server_row_share_id`. */
     insert(entity: string, data: Row): Promise<string>;
-    /** 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 sendAndAwait;
+    /** 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. */
     update(entity: string, id: string, data: Partial<Row>): Promise<void>;
-    /** 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. */
     delete(entity: string, id: string): Promise<void>;
     /** Load a page of data from an entity with cursor-based pagination. */
     loadPage(entity: string, options?: {
@@ -1012,6 +1108,11 @@ export declare class SyncEngine {
      *  `room-unsubscribe`. Used by the `useRoom` hook's manual `leave()`
      *  action so a deliberate exit propagates to the server immediately. */
     unsubscribeRoom(roomId: string): void;
+    /** 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;
     /** Read the current cached members snapshot for `roomId`. Returns
      *  `null` when no snapshot has landed yet (distinct from `[]` for
      *  an empty room). */

package/dist/local-store.d.ts

@@ -76,6 +76,13 @@ export declare class LocalStore {
      *  a cursor after — otherwise a crash can save the cursor before
      *  rows hit disk, causing permanent missed changes on restart. */
     applyChanges(changes: ChangeEvent[]): void;
+    /**
+     * Apply to memory and notify once, WITHOUT persisting. Returns each
+     * change with `data` set to the full merged row (deletes unchanged),
+     * ready to write to disk. The engine uses it to write a whole batch in
+     * one transaction (`ReplicaPersistence.saveBatch`).
+     */
+    applyInMemory(changes: ChangeEvent[]): ChangeEvent[];
     /**
      * Apply + persist, awaiting disk writes before returning. Callers
      * that are about to advance a cursor based on `changes` MUST use

package/dist/multi-tab-orchestrator.d.ts

@@ -40,7 +40,17 @@ export interface MultiTabOrchestratorHooks {
     onMutationsFailed(ops: {
         opId: string;
         error: string;
+        code?: string;
     }[]): void;
+    /** Leader → followers: the leader completed a pull (see
+     *  `SyncEngine.isSynced`). */
+    onSyncedReceived(): void;
+    /** Follower → leader: a tab that just started asks whether the leader
+     *  has synced. */
+    onSyncStatusRequested(): void;
+    /** Leader → followers: the leader's push failed transiently and
+     *  these op ids stay queued for retry. */
+    onMutationsQueued(opIds: string[]): void;
     /** Leader → follower: a binary frame from the WS. Engine routes
      *  to its local binary handlers. */
     onBinaryReceived(bytes: Uint8Array): void;
@@ -56,6 +66,9 @@ export interface MultiTabOrchestratorHooks {
      *  `room-unsubscribe` when both the local refcount and the forwarder
      *  set are empty. */
     onRoomSubUnregister?(roomId: string, fromTabId: string): void;
+    /** Follower → leader: the follower rejoined a room after a
+     *  `NOT_IN_ROOM` error; resend the wire `room-subscribe`. */
+    onRoomSubResubscribe?(roomId: string): void;
     /** Leader → followers: a room-snapshot landed on the WS. Followers
      *  apply it to their local room registry so their subscribers fire. */
     onRoomFanoutSnapshot?(roomId: string, members: unknown): void;
@@ -123,6 +136,7 @@ export declare class MultiTabOrchestrator {
     broadcastMutationsFailed(ops: {
         opId: string;
         error: string;
+        code?: string;
     }[]): void;
     /** Leader → followers: a reactive-result / reactive-error landed on
      *  the WS. Routed by sub_id to whatever tab owns the local handler. */

package/dist/mutation-queue.d.ts

@@ -1,9 +1,42 @@
 import type { ClientChange, Row } from "./types";
+/**
+ * Thrown by `SyncEngine.insert` / `update` / `delete` when the server
+ * rejects the write (policy denial, validation, conflict). The optimistic
+ * change is rolled back before the promise rejects.
+ *
+ * `code` is the server's error code when it sent one (`POLICY_DENIED`,
+ * `VALIDATION_FAILED`, ...). `DISCARDED` means the write never reached the
+ * server: an identity change dropped it from the queue.
+ */
+export declare class MutationRejectedError extends Error {
+    readonly code: string;
+    readonly opId: string;
+    readonly entity: string;
+    readonly rowId: string;
+    readonly kind: "insert" | "update" | "delete";
+    constructor(message: string, opts: {
+        code?: string;
+        opId: string;
+        entity: string;
+        rowId: string;
+        kind: "insert" | "update" | "delete";
+    });
+}
 export interface PendingMutation {
     id: string;
     change: ClientChange;
     status: "pending" | "applied" | "failed";
     error?: string;
+    /** Server error code for a failed mutation, when the server sent one. */
+    errorCode?: string;
+    /** User id the write was made as (`null` = anonymous). Persisted with
+     *  the queue so a write is only ever pushed as the user who made it.
+     *  `undefined` = unknown (queued by an older client). */
+    owner?: string | null;
+    /** The write was made before this run knew who is signed in (no
+     *  resolved session and no saved identity). It is held until the first
+     *  session resolves, which stamps `owner`. */
+    ownerPending?: boolean;
     /** Pre-mutation snapshot of the affected row, captured at optimistic-
      *  apply time for `update`/`delete`. On a server rejection,
      *  `failPushedMutation` restores this so the local replica reverts to
@@ -23,6 +56,9 @@ export interface MutationQueuePersistence {
 export declare class MutationQueue {
     private queue;
     private persistence?;
+    /** Callers waiting for a mutation's outcome, by op id. Memory-only:
+     *  a promise cannot outlive the page that created it. */
+    private waiters;
     constructor(persistence?: MutationQueuePersistence);
     /**
      * Attach a persistence backend after construction. The SyncEngine
@@ -41,7 +77,7 @@ export declare class MutationQueue {
      *  entry with the same op_id is already queued — a follower
      *  retrying its forward of the same op shouldn't double-queue on
      *  the leader. */
-    add(change: ClientChange, prevRow?: Row | null): string;
+    add(change: ClientChange, prevRow?: Row | null, owner?: string | null, ownerPending?: boolean): string;
     pending(): PendingMutation[];
     /** Look up a queued mutation by op id (any status). Used by the
      *  follower's mutations-failed handler to reach the captured
@@ -61,13 +97,32 @@ export declare class MutationQueue {
      * the user is still trying to push.
      */
     pendingRowKeys(): Set<string>;
+    /**
+     * Resolve once the server applies the mutation or the mutation is
+     * queued behind a transient failure (`settleQueued`); reject with a
+     * `MutationRejectedError` once the server rejects it. Settles at once
+     * when the mutation already reached a terminal state.
+     */
+    waitForOutcome(id: string): Promise<void>;
+    /** Resolve the waiters of a mutation that stays queued after a
+     *  transient push failure (offline, 5xx). The mutation stays pending
+     *  and is retried; a later rejection shows up as `status: "failed"`. */
+    settleQueued(id: string): void;
     markApplied(id: string): void;
-    markFailed(id: string, error: string): void;
+    markFailed(id: string, error: string, errorCode?: string): void;
+    private resolveWaiters;
     /**
      * Prune applied mutations. Failed mutations are KEPT so the UI can
      * surface them to the user and so retries are possible.
      */
     clear(): void;
+    /** Stamp every write whose owner was pending with the user the first
+     *  resolved session names. */
+    stampPendingOwner(owner: string | null): void;
+    /** Drop one mutation that must never be pushed (it belongs to another
+     *  identity) and reject its waiters with code `DISCARDED`. Does not
+     *  touch the local store. */
+    discard(id: string): void;
     /** Remove a specific mutation by id. Used by the UI after user
      *  ack of failures. */
     remove(id: string): void;

package/dist/persistence.d.ts

@@ -20,6 +20,14 @@ export interface ReplicaPersistence {
     saveRow(entity: string, id: string, data: Row): Promise<boolean>;
     deleteRow(entity: string, id: string): Promise<boolean>;
     clear(): Promise<boolean>;
+    /**
+     * Optional: write a batch of row changes, in order, and (when given) the
+     * cursor in ONE atomic transaction. Resolves `true` when the whole batch
+     * committed, `false` when it did not (nothing, cursor included, may be
+     * assumed on disk). The engine uses it to commit many live change frames
+     * at once; without it the engine writes row by row, then the cursor.
+     */
+    saveBatch?(changes: ChangeEvent[], cursor: SyncCursor | null): Promise<boolean>;
 }
 /**
  * IndexedDB-backed persistence for the sync store.
@@ -56,6 +64,10 @@ export declare class IndexedDBPersistence implements ReplicaPersistence {
     /** Save a row to IndexedDB. Resolves `true` when the write is durable,
      *  `false` if it degraded (no DB / aborted) — see `commit`. */
     saveRow(entity: string, id: string, data: Row): Promise<boolean>;
+    /** Write row puts/deletes in order plus the cursor in ONE readwrite
+     *  transaction. Rows and cursor commit or abort together, so the
+     *  on-disk cursor can never get ahead of the on-disk rows. */
+    saveBatch(changes: ChangeEvent[], cursor: SyncCursor | null): Promise<boolean>;
     /** Fetch a row from IndexedDB by key. Used by `persistChange` on update
      *  events to merge the patch against what's already on disk. */
     getRow(entity: string, id: string): Promise<Row | null>;

package/dist/room-subscriptions.d.ts

@@ -102,6 +102,11 @@ export declare class RoomSubscriptions {
     /** Every room currently tracked. Used by `replay()` and by the
      *  multi-tab seed-on-promotion. */
     roomIds(): string[];
+    /** Clear a room's error and resend its `room-subscribe`. Used after
+     *  the caller rejoined the room over HTTP following a `NOT_IN_ROOM`
+     *  reply: the server answers the new subscribe with a snapshot. No-op
+     *  for a room with no local subscriber. */
+    resubscribe(roomId: string): void;
     /** Resend `room-subscribe` for every active room. Called by the
      *  engine's `onConnected` hook after the WS reopens — the server
      *  forgets per-client subs across disconnects, so without this

package/dist/test-harness/server.d.ts

@@ -126,6 +126,13 @@ export declare class TestServer {
      *  reset) or an HTTP `status` (e.g. 403 permanent rejection, 503
      *  transient). Lets tests exercise the transient-vs-permanent
      *  classification in pushInner. */
+    /** When set, `/api/sync/push` waits for this promise before it
+     *  answers. Lets a test queue a write while a push is in flight. */
+    pushGate: Promise<void> | null;
+    /** Entities whose pushed writes are rejected per op, like a write
+     *  policy denial on the real server (HTTP 200 with a per-op error). */
+    private deniedWrites;
+    denyWrites(entity: string, code?: string, message?: string): void;
     private nextPushOutcome;
     primeNextPushOutcome(o: {
         kind: "network";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/bootstrap-speedup.test.ts

@@ -314,18 +314,21 @@ describe("Fix C: race election || auth/me", () => {
     const result = await (
       engine as unknown as {
         fetchSessionBootstrap(): Promise<{
-          userId: string | null;
-          tenantId: string | null;
-          isAdmin: boolean;
-          roles: string[];
+          session: {
+            userId: string | null;
+            tenantId: string | null;
+            isAdmin: boolean;
+            roles: string[];
+          };
+          token: string | null;
         } | null>;
       }
     ).fetchSessionBootstrap();
 
     expect(authMeHits).toBe(1);
     expect(result).not.toBeNull();
-    expect(result?.userId).toBe("u1");
-    expect(result?.tenantId).toBe("org-x");
+    expect(result?.session.userId).toBe("u1");
+    expect(result?.session.tenantId).toBe("org-x");
   });
 
   test("fetchSessionBootstrap returns null on non-ok response", async () => {

package/src/idb-warm-load.test.ts

@@ -504,8 +504,10 @@ describe("IDB warm-load hydration", () => {
       // so we assert it does NOT advance to 50 below.
       const onDiskBefore = (await persistence.loadCursor())?.last_seq ?? 0;
 
-      // Abort the next ENTITIES (row) readwrite, leaving the separate
-      // CURSOR-store tx alone — mirrors a quota abort on a row write.
+      // Abort the next readwrite that writes rows — mirrors a quota abort
+      // on a row write. The batch path writes rows and cursor in one
+      // transaction, so the cursor write aborts with it; a separate
+      // cursor-only transaction is left alone.
       const db = persistence.connection!;
       const realTx = db.transaction.bind(db);
       let armed = true;
@@ -517,15 +519,7 @@ describe("IDB warm-load hydration", () => {
         const touchesEntities = Array.isArray(stores)
           ? stores.includes("entities")
           : stores === "entities";
-        const touchesCursors = Array.isArray(stores)
-          ? stores.includes("cursors")
-          : stores === "cursors";
-        if (
-          armed &&
-          String(args[1]) === "readwrite" &&
-          touchesEntities &&
-          !touchesCursors
-        ) {
+        if (armed && String(args[1]) === "readwrite" && touchesEntities) {
           armed = false;
           queueMicrotask(() => {
             try {

package/src/identity-reset-safety.test.ts

@@ -0,0 +1,174 @@
+// Identity changes must not wipe a follower twice, let the old socket's
+// frames into the new replica, or throw away a signed-out user's offline
+// writes. Found in review of the sign-in re-sync fix.
+
+import "fake-indexeddb/auto";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { IndexedDBPersistence, SyncEngine, type ChangeEvent } from "./index";
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+const session = (userId: string | null) => ({
+  userId,
+  tenantId: null,
+  isAdmin: false,
+  roles: [],
+  avatarUrl: null,
+});
+
+describe("identity reset safety", () => {
+  let env: TestEnv | null = null;
+  const realFetch = globalThis.fetch;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+    globalThis.fetch = realFetch;
+  });
+
+  test("a follower keeps the leader's re-pulled rows when the session broadcast arrives", async () => {
+    const engine = new SyncEngine({ baseUrl: "http://test.invalid", persist: false, multiTab: false });
+    const internals = engine as unknown as {
+      isMultiTabLeader: boolean;
+      multiTabHooks: () => { onSessionReceived: (s: unknown) => void };
+      sessionChain: Promise<void>;
+      enqueueApply: (c: unknown[], t?: unknown, o?: unknown) => Promise<void>;
+    };
+    internals.isMultiTabLeader = false;
+    const hooks = internals.multiTabHooks();
+    hooks.onSessionReceived(session(null));
+    await internals.sessionChain;
+    // The leader reset, re-pulled, and broadcast the rows...
+    await internals.enqueueApply(
+      [{ seq: 5, entity: "Deal", row_id: "d1", kind: "insert", data: { id: "d1" }, timestamp: "" }],
+      { last_seq: 5 },
+      { fromBroadcast: true },
+    );
+    // ...then its session.
+    hooks.onSessionReceived(session("u1"));
+    await internals.sessionChain;
+    await new Promise((r) => setTimeout(r, 20));
+    expect(engine.store.list("Deal")).toHaveLength(1);
+    expect(engine.getCursor().last_seq).toBe(5);
+    expect(engine.resolvedSession().userId).toBe("u1");
+  });
+
+  test("a frame from the old socket during a reset does not land in the new replica", async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      const body = url.includes("/api/sync/pull")
+        ? { changes: [], cursor: { last_seq: 0 }, has_more: false }
+        : url.includes("/api/auth/me")
+          ? { user_id: "uA" }
+          : {};
+      return new Response(JSON.stringify(body), { status: 200 });
+    }) as typeof fetch;
+    const persistence = new IndexedDBPersistence(`leak-${Math.random().toString(36).slice(2)}`);
+    const engine = new SyncEngine({
+      baseUrl: "http://test.invalid",
+      persistence,
+      multiTab: false,
+      transport: "poll",
+      pollInterval: 1e9,
+      reconcileOnVisibility: false,
+    });
+    await engine.start();
+    const host = (engine as unknown as {
+      transportHost(): { onChangeEvent(ev: ChangeEvent): void };
+    }).transportHost();
+    // A batch that starts before the reset and is still writing when it runs.
+    host.onChangeEvent({ seq: 800, entity: "Secret", row_id: "s0", kind: "insert", data: { id: "s0" }, timestamp: "" });
+    // Hold the reset inside its disk clear so the next frame arrives while
+    // it runs.
+    let releaseClear!: () => void;
+    const clearGate = new Promise<void>((r) => (releaseClear = r));
+    const realClear = persistence.clear.bind(persistence);
+    let clearStarted = false;
+    persistence.clear = async () => {
+      clearStarted = true;
+      await clearGate;
+      return realClear();
+    };
+    const reset = engine.resetReplica({ wipeMutations: true });
+    while (!clearStarted) await new Promise((r) => setTimeout(r, 1));
+    host.onChangeEvent({ seq: 900, entity: "Secret", row_id: "s1", kind: "insert", data: { id: "s1" }, timestamp: "" });
+    releaseClear();
+    await reset;
+    await new Promise((r) => setTimeout(r, 50));
+    expect(engine.store.list("Secret")).toHaveLength(0);
+    expect(engine.getCursor().last_seq).toBe(0);
+    const disk = await persistence.loadSnapshot();
+    expect(disk.entities.Secret ?? []).toHaveLength(0);
+    expect(disk.cursor?.last_seq ?? 0).toBe(0);
+    engine.stop();
+  });
+
+  test("an expired session holds offline writes; the same user signing back in pushes them", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.server.primeNextPushOutcome({ kind: "network" });
+    const id = await env.engine.insert("Note", { title: "offline draft" });
+    expect(env.engine.pendingCount()).toBe(1);
+
+    // The token expires: /api/auth/me now answers anonymous.
+    if (env.token) env.server.revoke(env.token);
+    await env.engine.notifySessionChanged();
+    await env.flush();
+    expect(env.engine.resolvedSession().userId).toBeNull();
+    expect(env.engine.pendingCount()).toBe(1);
+    await env.engine.push();
+    expect(env.server.receivedPushKeys.filter((k) => k === `Note/${id}`)).toHaveLength(1);
+
+    env.signIn({ userId: "u1" });
+    await env.engine.notifySessionChanged();
+    await env.flush(50);
+    expect(env.engine.pendingCount()).toBe(0);
+    expect(env.server.receivedPushKeys.filter((k) => k === `Note/${id}`)).toHaveLength(2);
+  });
+
+  test("a different user signing in after an expired session discards the held writes", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.server.primeNextPushOutcome({ kind: "network" });
+    await env.engine.insert("Note", { title: "u1 draft" });
+    if (env.token) env.server.revoke(env.token);
+    await env.engine.notifySessionChanged();
+    await env.flush();
+
+    env.signIn({ userId: "u2" });
+    await env.engine.notifySessionChanged();
+    await env.flush(50);
+    expect(env.engine.pendingCount()).toBe(0);
+    expect(env.server.receivedPushKeys.filter((k) => k.startsWith("Note/"))).toHaveLength(1);
+  });
+
+  test("a follower's write resolves as queued when the leader never answers", async () => {
+    const engine = new SyncEngine({ baseUrl: "http://test.invalid", persist: false, multiTab: false });
+    const internals = engine as unknown as {
+      isMultiTabLeader: boolean;
+      broadcastToTabs: (p: unknown) => void;
+    };
+    internals.isMultiTabLeader = false;
+    internals.broadcastToTabs = () => {};
+    const started = Date.now();
+    const id = await engine.insert("Note", { title: "x" });
+    expect(typeof id).toBe("string");
+    expect(Date.now() - started).toBeGreaterThanOrEqual(4_900);
+    expect(engine.store.get("Note", id)).not.toBeNull();
+  }, 10_000);
+
+  test("an op the server returns no result for resolves as queued", async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("/api/sync/push")) {
+        return new Response(JSON.stringify({ applied: 0, errors: [], results: [], cursor: { last_seq: 0 } }), { status: 200 });
+      }
+      return new Response("{}", { status: 200 });
+    }) as typeof fetch;
+    const engine = new SyncEngine({ baseUrl: "http://test.invalid", persist: false, multiTab: false });
+    const id = await engine.insert("Note", { title: "x" });
+    expect(engine.store.get("Note", id)).not.toBeNull();
+    expect(engine.pendingCount()).toBe(1);
+  });
+});