@pylonsync/sync 0.3.227 → 0.3.229

package/src/multi-tab-orchestrator.ts

@@ -69,8 +69,11 @@ export interface MultiTabOrchestratorHooks {
     removalIds: string[],
     tombstoneSeq: number,
   ): void;
-  /** Replica reset broadcast — identity flip happened on the leader. */
-  onResetReceived(): void;
+  /** Replica reset broadcast from the leader. `wipeMutations` is true
+   *  when the reset was an identity flip (drop the outgoing identity's
+   *  pending offline writes), false for a same-user 410 RESYNC (keep
+   *  them — they survive the snapshot refresh). */
+  onResetReceived(wipeMutations: boolean): void;
   /** Resolved session update from the leader. Engine funnels through
    *  its session chain so concurrent triggers commit in order. */
   onSessionReceived(resolved: ResolvedSession): void;
@@ -112,6 +115,16 @@ export interface MultiTabOrchestratorHooks {
   /** New leader → followers: re-forward your locally-wanted room subs.
    *  Triggered alongside CRDT/reactive replay after a leader change. */
   onReplayRoomSubs?(): void;
+
+  /** Follower → leader: a follower's `useQuery` observed an entity.
+   *  Leader-only. The leader adds it to its reconcile sweep and fetches
+   *  it so a server row the follower never cached is discovered and
+   *  broadcast back as a `reconciled` batch. Without this, a follower's
+   *  view on a never-cached entity stays empty forever. */
+  onEntityObserve?(entity: string, fromTabId: string): void;
+  /** New leader → followers: re-declare your observed entities so the
+   *  new leader's reconcile sweep covers them. */
+  onReplayObservedEntities?(): void;
 }
 
 export interface MultiTabOrchestratorConfig {
@@ -247,8 +260,8 @@ export class MultiTabOrchestrator {
     });
   }
 
-  broadcastReset(): void {
-    this.broadcastRaw({ type: "reset" });
+  broadcastReset(wipeMutations: boolean): void {
+    this.broadcastRaw({ type: "reset", wipeMutations });
   }
 
   broadcastSession(resolved: ResolvedSession): void {
@@ -328,7 +341,7 @@ export class MultiTabOrchestrator {
         break;
       }
       case "reset": {
-        this.hooks.onResetReceived();
+        this.hooks.onResetReceived(msg.wipeMutations === true);
         break;
       }
       case "session": {
@@ -388,6 +401,19 @@ export class MultiTabOrchestrator {
         // so the new leader can rebuild its forwarder sets and resend
         // `room-subscribe` on the WS.
         this.hooks.onReplayRoomSubs?.();
+        // ...and re-declare observed entities so the new leader's
+        // reconcile sweep covers them.
+        this.hooks.onReplayObservedEntities?.();
+        break;
+      }
+      case "entity-observe": {
+        // Follower → leader. Leader-only — a follower receiving this
+        // (own broadcast echo, or stale leader transition) ignores.
+        if (!this._isLeader) return;
+        const entity = msg.entity as string | undefined;
+        if (typeof entity === "string") {
+          this.hooks.onEntityObserve?.(entity, fromTabId);
+        }
         break;
       }
       case "room-sub-register": {

package/src/mutation-queue.ts

@@ -10,13 +10,19 @@
 // instead of re-applying.
 // ---------------------------------------------------------------------------
 
-import type { ClientChange } from "./types";
+import type { ClientChange, Row } from "./types";
 
 export interface PendingMutation {
   id: string;
   change: ClientChange;
   status: "pending" | "applied" | "failed";
   error?: string;
+  /** 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
+   *  the value the server actually holds. `null` = the row didn't exist
+   *  before the mutation; `undefined` = not captured (inserts). */
+  prevRow?: Row | null;
 }
 
 /**
@@ -80,14 +86,14 @@ export 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): string {
+  add(change: ClientChange, prevRow?: Row | null): string {
     const id =
       typeof change.op_id === "string" && change.op_id.length > 0
         ? change.op_id
         : `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
     if (this.queue.some((m) => m.id === id)) return id;
     const changeWithOp: ClientChange = { ...change, op_id: id };
-    this.queue.push({ id, change: changeWithOp, status: "pending" });
+    this.queue.push({ id, change: changeWithOp, status: "pending", prevRow });
     this.flush();
     return id;
   }
@@ -96,6 +102,13 @@ export class MutationQueue {
     return this.queue.filter((m) => m.status === "pending");
   }
 
+  /** Look up a queued mutation by op id (any status). Used by the
+   *  follower's mutations-failed handler to reach the captured
+   *  `prevRow` for rollback. */
+  get(id: string): PendingMutation | undefined {
+    return this.queue.find((m) => m.id === id);
+  }
+
   /**
    * Set of `${entity}/${row_id}` keys for every mutation currently
    * in Pending or Failed state. Used by reconcile() to skip rows
@@ -152,6 +165,22 @@ export class MutationQueue {
     this.flush();
   }
 
+  /**
+   * Drop EVERY mutation — pending, failed, and applied — then flush the
+   * empty queue to disk. Used by the engine's identity-flip reset
+   * (`resetReplica({ wipeMutations: true })`): the queued offline writes
+   * belong to the OUTGOING identity, and replaying them under the new
+   * session would attribute one user's writes to another (or get
+   * policy-rejected on the server). Distinct from `clear()`, which only
+   * prunes already-applied entries and deliberately PRESERVES pending +
+   * failed writes — the 410-RESYNC same-user path relies on that so
+   * offline writes survive a snapshot refresh.
+   */
+  clearAll(): void {
+    this.queue = [];
+    this.flush();
+  }
+
   /** Fire-and-forget persistence write. */
   private flush(): void {
     if (!this.persistence) return;

package/src/persistence.ts

@@ -86,15 +86,47 @@ export class IndexedDBPersistence {
     });
   }
 
-  /** Save a row to IndexedDB. */
-  async saveRow(entity: string, id: string, data: Row): Promise<void> {
-    if (!this.db) return;
+  /** Resolve when a write transaction settles, reporting durability:
+   *  `true` on COMMIT, `false` if it aborts/errors — e.g.
+   *  QuotaExceededError on a storage-pressured device. NEVER rejects or
+   *  hangs: registering only `oncomplete` (the original shape) meant an
+   *  aborted tx never settled, and the engine awaits the persist before
+   *  advancing the cursor in `enqueueApply` — so ONE hung write wedged
+   *  the whole applyQueue and live sync silently died for the session.
+   *
+   *  But "resolve unconditionally" (the first fix) was also wrong: on an
+   *  abort the row never reached disk, yet `enqueueApply` still advanced
+   *  the PERSISTED cursor past it — so on restart the warm-load skipped
+   *  those rows forever (cursor ahead of replica). The boolean lets the
+   *  caller hold the on-disk cursor back when a row write fails, so the
+   *  next cold start re-pulls the gap. Best-effort: log once, keep the
+   *  in-memory replica authoritative, but never persist a cursor ahead of
+   *  what's actually durable. Mirrors the read paths (`getRow`/
+   *  `loadCursor`) which already degrade via `onerror`. */
+  private commit(tx: IDBTransaction, op: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      tx.oncomplete = () => resolve(true);
+      tx.onerror = () => {
+        // eslint-disable-next-line no-console
+        console.warn(`[pylon-sync] IndexedDB ${op} failed; degrading to memory`, tx.error);
+        resolve(false);
+      };
+      tx.onabort = () => {
+        // eslint-disable-next-line no-console
+        console.warn(`[pylon-sync] IndexedDB ${op} aborted; degrading to memory`, tx.error);
+        resolve(false);
+      };
+    });
+  }
+
+  /** Save a row to IndexedDB. Resolves `true` when the write is durable,
+   *  `false` if it degraded (no DB / aborted) — see `commit`. */
+  async saveRow(entity: string, id: string, data: Row): Promise<boolean> {
+    if (!this.db) return false;
     const tx = this.db.transaction(STORE_NAME, "readwrite");
     const store = tx.objectStore(STORE_NAME);
     store.put({ _key: `${entity}:${id}`, entity, id, data });
-    return new Promise((resolve) => {
-      tx.oncomplete = () => resolve();
-    });
+    return this.commit(tx, "saveRow");
   }
 
   /** Fetch a row from IndexedDB by key. Used by `persistChange` on update
@@ -113,15 +145,14 @@ export class IndexedDBPersistence {
     });
   }
 
-  /** Delete a row from IndexedDB. */
-  async deleteRow(entity: string, id: string): Promise<void> {
-    if (!this.db) return;
+  /** Delete a row from IndexedDB. Resolves `true` when durable, `false`
+   *  if it degraded — see `commit`. */
+  async deleteRow(entity: string, id: string): Promise<boolean> {
+    if (!this.db) return false;
     const tx = this.db.transaction(STORE_NAME, "readwrite");
     const store = tx.objectStore(STORE_NAME);
     store.delete(`${entity}:${id}`);
-    return new Promise((resolve) => {
-      tx.oncomplete = () => resolve();
-    });
+    return this.commit(tx, "deleteRow");
   }
 
   /** Load all rows for an entity from IndexedDB. */
@@ -217,15 +248,14 @@ export class IndexedDBPersistence {
     });
   }
 
-  /** Save the sync cursor. */
-  async saveCursor(cursor: SyncCursor): Promise<void> {
-    if (!this.db) return;
+  /** Save the sync cursor. Resolves `true` when durable, `false` if it
+   *  degraded — see `commit`. */
+  async saveCursor(cursor: SyncCursor): Promise<boolean> {
+    if (!this.db) return false;
     const tx = this.db.transaction(CURSOR_STORE, "readwrite");
     const store = tx.objectStore(CURSOR_STORE);
     store.put({ key: "cursor", ...cursor });
-    return new Promise((resolve) => {
-      tx.oncomplete = () => resolve();
-    });
+    return this.commit(tx, "saveCursor");
   }
 
   /** Load the sync cursor. */
@@ -247,25 +277,34 @@ export class IndexedDBPersistence {
     });
   }
 
-  /** Clear all stored data. */
-  async clear(): Promise<void> {
-    if (!this.db) return;
+  /** Clear stored rows + cursor. Deliberately does NOT touch the
+   *  durable mutation queue: `resetReplica` calls this on a 410 RESYNC
+   *  (same user, needs a fresh snapshot) where pending offline writes
+   *  MUST survive. On an IDENTITY flip the old identity's pending
+   *  mutations must instead be discarded — that wipe runs through
+   *  `MutationQueue.clearAll()` (which persists an empty `MUTATIONS_STORE`
+   *  via its own backend), gated on `resetReplica({ wipeMutations })` at
+   *  the token/tenant-flip call sites. Splitting the two stores keeps each
+   *  reset path honest: 410 keeps writes, identity flip drops them. */
+  async clear(): Promise<boolean> {
+    if (!this.db) return false;
     const tx = this.db.transaction([STORE_NAME, CURSOR_STORE], "readwrite");
     tx.objectStore(STORE_NAME).clear();
     tx.objectStore(CURSOR_STORE).clear();
-    return new Promise((resolve) => {
-      tx.oncomplete = () => resolve();
-    });
+    return this.commit(tx, "clear");
   }
 }
 
 /**
- * Apply a change event to IndexedDB persistence.
+ * Apply a change event to IndexedDB persistence. Returns `true` when the
+ * write reached disk durably, `false` when it degraded (so `enqueueApply`
+ * can hold the persisted cursor back rather than skip the row on restart).
+ * A change with no `data` is a no-op and counts as durable.
  */
 export async function persistChange(
   persistence: IndexedDBPersistence,
   change: ChangeEvent
-): Promise<void> {
+): Promise<boolean> {
   switch (change.kind) {
     case "insert":
     case "update":
@@ -274,13 +313,13 @@ export async function persistChange(
         // change's `data` with the post-merge row from memory — so even
         // on update the full row lands here. Overwriting is correct;
         // pre-merge patches would have dropped unpatched columns.
-        await persistence.saveRow(change.entity, change.row_id, change.data);
+        return persistence.saveRow(change.entity, change.row_id, change.data);
       }
-      break;
+      return true;
     case "delete":
-      await persistence.deleteRow(change.entity, change.row_id);
-      break;
+      return persistence.deleteRow(change.entity, change.row_id);
   }
+  return true;
 }
 
 // ---------------------------------------------------------------------------

package/src/round6-codex.test.ts

@@ -326,3 +326,160 @@ describe("codex round-6: peer leaving scrubs forwarded subs", () => {
     expect(engine.serverSubs.has("sub-1")).toBe(false);
   });
 });
+
+describe("sync hardening: multi-tab follower coverage", () => {
+  let env: TestEnv | null = null;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  // FOLLOWER GHOST ROLLBACK. The leader broadcasts `mutations-failed`;
+  // the follower must roll back its OWN optimistic ghost, not just mark
+  // the queue entry failed. Pre-fix onMutationsFailed called markFailed
+  // directly, so the ghost row stuck around in the tab the user sees.
+  test("a mutations-failed for an optimistic insert removes the follower's ghost", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+    const engine = env.engine;
+
+    // Optimistic ghost in the store + a matching queued mutation (as if
+    // this follower had forwarded the insert to the leader).
+    engine.store.optimisticInsertWithId("Todo", "t1", { id: "t1", text: "ghost" });
+    engine.mutations.add({
+      op_id: "op-1",
+      entity: "Todo",
+      row_id: "t1",
+      kind: "insert",
+      data: { id: "t1", text: "ghost" },
+    });
+    expect(engine.store.get("Todo", "t1")).not.toBeNull();
+
+    (engine as unknown as {
+      orchestrator: { handleMessage(msg: unknown, from: string): void };
+    }).orchestrator.handleMessage(
+      { type: "mutations-failed", ops: [{ opId: "op-1", error: "rejected" }] },
+      "leader-tab",
+    );
+
+    // Ghost gone (rolled back), mutation marked failed.
+    expect(engine.store.get("Todo", "t1")).toBeNull();
+  });
+
+  // ENTITY-OBSERVE FORWARDING. A leader that receives a forwarded
+  // `entity-observe` from a follower must add the entity to its reconcile
+  // sweep and fetch it — so a server row the follower never cached is
+  // discovered + broadcast back. Without this a follower's useQuery on a
+  // never-cached entity renders empty forever.
+  test("a leader fetches an entity a follower forwarded via entity-observe", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start(); // solo → this engine is the leader
+    const engine = env.engine;
+
+    // A server row exists for an entity this engine never cached.
+    env.server.insert("Domain", { id: "d1", host: "x.com" });
+    expect(engine.store.list("Domain")).toHaveLength(0);
+
+    (engine as unknown as {
+      orchestrator: { handleMessage(msg: unknown, from: string): void };
+    }).orchestrator.handleMessage(
+      { type: "entity-observe", entity: "Domain" },
+      "follower-tab",
+    );
+    await env.flush();
+
+    expect(engine.store.get("Domain", "d1")).not.toBeNull();
+  });
+
+  // FORWARDED-MUTATION ROLLBACK (pins onMutationsForwarded prevRow
+  // threading). When a follower forwards an update/delete and the leader's
+  // push of it is PERMANENTLY rejected, the leader must restore the
+  // canonical row — NOT delete it. Pre-fix the leader queued the forwarded
+  // op via mutations.add(op.change) WITHOUT prevRow, so failPushedMutation
+  // ran restoreRow(undefined ?? null) → restoreRow(null) → DELETED the
+  // leader's still-valid canonical row. Data loss on every rejected
+  // forwarded edit.
+  test("a rejected forwarded UPDATE keeps the leader's canonical row", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n1", title: "canonical" }]);
+    await env.start(); // solo → leader, holds the canonical row
+    await env.flush();
+    expect(env.engine.store.get("Note", "n1")).not.toBeNull();
+
+    // A follower optimistically edited n1, captured the prior value as
+    // prevRow, and forwarded the update. The leader's push will 403.
+    env.server.primeNextPushOutcome({ kind: "status", status: 403 });
+    (env.engine as unknown as {
+      orchestrator: { handleMessage(msg: unknown, from: string): void };
+    }).orchestrator.handleMessage(
+      {
+        type: "mutations",
+        ops: [
+          {
+            id: "op-u",
+            change: {
+              op_id: "op-u",
+              entity: "Note",
+              row_id: "n1",
+              kind: "update",
+              data: { title: "edited" },
+            },
+            status: "pending",
+            prevRow: { id: "n1", title: "canonical" },
+          },
+        ],
+      },
+      "follower-tab",
+    );
+    // Wait behind the forwarded push (opQueue serializes), then drain.
+    await env.engine.push();
+    await env.flush();
+
+    const row = env.engine.store.get("Note", "n1") as { title?: string } | null;
+    expect(row).not.toBeNull();
+    expect(row?.title).toBe("canonical");
+  });
+
+  test("a rejected forwarded DELETE keeps the leader's canonical row", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n1", title: "keep" }]);
+    await env.start();
+    await env.flush();
+    expect(env.engine.store.get("Note", "n1")).not.toBeNull();
+
+    env.server.primeNextPushOutcome({ kind: "status", status: 403 });
+    (env.engine as unknown as {
+      orchestrator: { handleMessage(msg: unknown, from: string): void };
+    }).orchestrator.handleMessage(
+      {
+        type: "mutations",
+        ops: [
+          {
+            id: "op-d",
+            change: {
+              op_id: "op-d",
+              entity: "Note",
+              row_id: "n1",
+              kind: "delete",
+            },
+            status: "pending",
+            prevRow: { id: "n1", title: "keep" },
+          },
+        ],
+      },
+      "follower-tab",
+    );
+    await env.engine.push();
+    await env.flush();
+
+    // Pre-fix the leader deleted its canonical row on the rejected
+    // forwarded delete; with prevRow threaded it survives.
+    const row = env.engine.store.get("Note", "n1") as { title?: string } | null;
+    expect(row).not.toBeNull();
+    expect(row?.title).toBe("keep");
+  });
+});

package/src/scenarios.test.ts

@@ -487,6 +487,190 @@ describe("sync scenarios", () => {
     expect(env.server.snapshotPullCount - before).toBe(1);
   });
 
+  // EMPTY-ENTITY RECONCILE GAP (pins observeEntity). A server row in an
+  // entity the local replica has NEVER cached stays invisible: useQuery
+  // reads the empty local store, a delta pull can't recover a row
+  // created before the cursor, and the no-arg reconcile sweeps only
+  // entities with ≥1 local row (store.entityNames()) — so it skips the
+  // empty entity entirely. The user hit this as "I attached the domain
+  // but the Domains list is empty"; clearing IndexedDB (cursor→0→
+  // snapshot) was the only recovery. observeEntity (called by useQuery
+  // on mount) adds the entity to the sweep + fires a one-shot fetch.
+  test("observing an entity recovers a server row the local cache never had", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    // Client has rows for Note, but none for Domain.
+    env.server.seed("Note", [{ id: "n1", title: "x" }]);
+    await env.start();
+    await env.flush();
+    expect(env.engine.store.list("Domain")).toHaveLength(0);
+
+    // A Domain row exists server-side but was never delivered to this
+    // client (created on another surface / a missed insert). Inserted
+    // after start so the initial snapshot didn't include it; poll
+    // transport means no auto-delivery.
+    env.server.insert("Domain", { id: "d1", host: "chat.example.com" });
+
+    // A no-arg reconcile sweeps only entities with local rows (Note),
+    // so it never touches Domain — the row stays invisible. The bug.
+    await env.engine.reconcile(["Note"]);
+    await env.flush();
+    expect(env.engine.store.get("Domain", "d1")).toBeNull();
+
+    // observeEntity (what useQuery now calls on mount) adds Domain to
+    // the sweep and fires a one-shot scoped reconcile — the row appears
+    // without a cache clear.
+    env.engine.observeEntity("Domain");
+    await env.flush();
+    expect(env.engine.store.get("Domain", "d1")).not.toBeNull();
+  });
+
+  // TAIL-PULL DEADLOCK (pins index.ts:1310). When a delta pull reports
+  // has_more (the catch-up exceeds the server's per-pull limit), pullInner
+  // drains the tail by recursing. Pre-fix it called the PUBLIC pull(),
+  // which re-enters the op queue under key "pull" and coalesces onto the
+  // promise it's currently running inside → permanent self-deadlock that
+  // bricks the whole pull path. Post-fix it recurses into pullInner().
+  test("delta pull with has_more drains the tail without self-deadlocking", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n1", title: "a" }]);
+    await env.start();
+    await env.flush();
+
+    // A later change exists; the next delta pull reports has_more once,
+    // forcing the tail recursion.
+    env.server.insert("Note", { id: "n2", title: "b" });
+    env.server.primeNextPullHasMore();
+
+    // Must complete, not hang. Pre-fix the pull never resolves and the
+    // race rejects with "pull deadlocked".
+    const e = env;
+    await Promise.race([
+      e.engine.pull().then(() => e.flush()),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error("pull deadlocked")), 3000),
+      ),
+    ]);
+    expect(env.engine.store.get("Note", "n2")).not.toBeNull();
+  });
+
+  // OFFLINE WRITES (pins the transient/permanent split in pushInner).
+  // A push that fails with a NETWORK error (offline — fetch rejects, no
+  // HTTP status) must keep the mutation `pending` and the optimistic
+  // ghost intact, then re-send on reconnect. Pre-fix every transport
+  // failure marked the mutation `failed` + rolled back the ghost, so an
+  // offline insert vanished and was never re-sent.
+  test("offline push keeps the mutation pending and the ghost intact (not failed)", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    await env.flush();
+
+    env.server.primeNextPushOutcome({ kind: "network" });
+    const id = await env.engine.insert("Note", { title: "offline" });
+    await env.flush();
+
+    // Offline (network throw, no status): the ghost survives and the
+    // mutation stays PENDING — not `failed`. Pre-fix it was marked failed
+    // and the ghost rolled back, so the offline write vanished and (being
+    // `failed`, not `pending`) was never re-sent. Pending is exactly what
+    // makes the standard reconnect push re-ship it. (insert() returns the
+    // ROW id; match the mutation by row_id, not its op_id.)
+    expect(env.engine.store.get("Note", id)).not.toBeNull();
+    const mine = (env.engine.mutations as unknown as {
+      queue: { change: { row_id: string }; status: string }[];
+    }).queue.filter((m) => m.change.row_id === id);
+    expect(mine).toHaveLength(1);
+    expect(mine[0]!.status).toBe("pending");
+  });
+
+  // FAILED UPDATE ROLLBACK (pins failPushedMutation update path). A
+  // PERMANENT rejection (403) of an update must restore the row to its
+  // pre-update value. Pre-fix only inserts rolled back; a rejected update
+  // left the local row permanently wrong.
+  test("a permanently-rejected update restores the prior value", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n1", title: "original" }]);
+    await env.start();
+    await env.flush();
+
+    env.server.primeNextPushOutcome({ kind: "status", status: 403 });
+    await env.engine.update("Note", "n1", { title: "edited" });
+    await env.flush();
+
+    const row = env.engine.store.get("Note", "n1") as { title?: string } | null;
+    expect(row?.title).toBe("original");
+  });
+
+  // FAILED DELETE ROLLBACK (pins failPushedMutation delete path). A
+  // rejected delete must bring the row back AND clear the optimistic
+  // tombstone, so a later server insert of the same id isn't fenced out.
+  // Pre-fix the row vanished and the tombstone blocked re-creation
+  // forever.
+  test("a permanently-rejected delete restores the row and un-fences it", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n1", title: "keep" }]);
+    await env.start();
+    await env.flush();
+
+    env.server.primeNextPushOutcome({ kind: "status", status: 403 });
+    await env.engine.delete("Note", "n1");
+    await env.flush();
+    expect(env.engine.store.get("Note", "n1")).not.toBeNull();
+
+    // Un-fenced: a server insert of the same id now lands.
+    env.server.insert("Note", { id: "n1", title: "server-updated" });
+    await env.engine.pull();
+    await env.flush();
+    const row = env.engine.store.get("Note", "n1") as { title?: string } | null;
+    expect(row?.title).toBe("server-updated");
+  });
+
+  // CROSS-IDENTITY MUTATION WIPE (pins resetReplica wipeMutations). An
+  // identity flip (token / tenant change) must DROP the outgoing
+  // identity's pending offline writes — replaying them under the new
+  // session would attribute one user's writes to another. A same-user 410
+  // RESYNC must KEEP them (they survive the snapshot refresh).
+  test("an identity-flip reset wipes the outgoing identity's pending writes", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    await env.flush();
+
+    // Queue an offline write — network failure keeps it pending.
+    env.server.primeNextPushOutcome({ kind: "network" });
+    await env.engine.insert("Note", { title: "draft" });
+    await env.flush();
+    const queue = (env.engine.mutations as unknown as { queue: unknown[] }).queue;
+    expect(queue.length).toBeGreaterThan(0);
+
+    // Identity flip → wipe.
+    await env.engine.resetReplica({ wipeMutations: true });
+    expect((env.engine.mutations as unknown as { queue: unknown[] }).queue).toHaveLength(0);
+  });
+
+  test("a same-user 410 resync PRESERVES pending offline writes", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    await env.flush();
+
+    env.server.primeNextPushOutcome({ kind: "network" });
+    await env.engine.insert("Note", { title: "draft" });
+    await env.flush();
+    const before = (env.engine.mutations as unknown as { queue: unknown[] }).queue.length;
+    expect(before).toBeGreaterThan(0);
+
+    // 410 RESYNC path is the default (wipeMutations omitted) — KEEP writes.
+    await env.engine.resetReplica();
+    expect(
+      (env.engine.mutations as unknown as { queue: unknown[] }).queue.length,
+    ).toBe(before);
+  });
+
   // Row-revoked envelope: server pushes `row-revoked` to a
   // subscriber whose read policy was revoked for a specific row.
   // The engine must drop the row from the local replica and