@pylonsync/sync 0.22.41 → 0.22.44

package/dist/index.d.ts

@@ -106,29 +106,6 @@ export interface SyncEngineConfig {
      */
     multiTab?: boolean;
 }
-/**
- * Generate a stable client_id. Prefers a persisted id from `storage`
- * (so a reload keeps the same identifier) and falls back to a fresh UUID.
- */
-/**
- * Generate a Pylon-shaped row id (40-char lowercase hex).
- *
- * Mirrors the runtime's `generate_id` shape: 32 hex of milliseconds
- * since epoch (extended to nanos so it lex-sorts alongside server-
- * generated ids) + 8 hex of a per-tab counter. Lex-sortable, monotonic
- * within a tab, statistically unique across tabs (the timestamp
- * disambiguates almost every cross-tab collision; the counter handles
- * the rest within a single tick).
- *
- * Used by `useMutation({ optimistic })` to mint client-side ids that
- * the runtime will accept verbatim — so the optimistic ghost and the
- * canonical row share the same `row_id` and the WS broadcast is an
- * idempotent merge instead of a delete-then-replace flash.
- *
- * Apps can call this directly when they need a stable id earlier than
- * the mutation (e.g. to reference the row from another optimistic
- * insert in the same gesture).
- */
 export declare class SyncEngine {
     private config;
     private cursor;
@@ -733,6 +710,42 @@ export declare class SyncEngine {
      */
     observeEntity(entity: string): void;
     reconcile(entities?: string[]): Promise<void>;
+    /** Entities to reconcile that have not reconciled yet: named by a server
+     *  hint (`sync-reconcile`), or skipped by an earlier reconcile. */
+    private pendingReconcile;
+    /** Numbers each pending request, so a pass clears only older ones. */
+    private pendingReconcileSeq;
+    private pendingReconcileTimer;
+    private pendingReconcileRetries;
+    /** Bumped by stop() and resetReplica(): pending work queued before it
+     *  does not run. */
+    private pendingReconcileEpoch;
+    private lastPendingReconcileAt;
+    /** Hints that arrive this close together share one reconcile. */
+    private static readonly PENDING_RECONCILE_DEBOUNCE_MS;
+    /** At most one hinted reconcile per this interval. */
+    private static readonly PENDING_RECONCILE_MIN_INTERVAL_MS;
+    /** Backoff for entities whose fetch raced a newer change: doubling from
+     *  the base, capped. */
+    private static readonly PENDING_RECONCILE_RETRY_BASE_MS;
+    private static readonly PENDING_RECONCILE_RETRY_MAX_MS;
+    /**
+     * Keep `entities` pending until a reconcile of them completes. Used for
+     * server hints (`sync-reconcile`: a share, an unshare, a folder
+     * membership changed which rows this user may read, and no other event
+     * will tell this replica) and for entities an earlier reconcile skipped.
+     * Requests are merged, run at most once a second, and an entity whose
+     * fetch failed or raced a newer change is retried with backoff until it
+     * lands or the engine stops.
+     */
+    private queuePendingReconcile;
+    private schedulePendingReconcile;
+    private flushPendingReconcile;
+    /** Drop pending reconciles, including queued ones (stop, replica reset). */
+    private cancelPendingReconcile;
+    /** `reconcile`, resolving with the entities it reconciled and the ones
+     *  it skipped (the fetch failed, or the cursor moved during it). */
+    private reconcileReportingSkips;
     /** Scoped reconcile batch that has not started running yet. */
     private scopedReconcileBatch;
     private scopedReconcileSeq;

package/package.json

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

package/src/index.ts

@@ -230,6 +230,17 @@ export interface SyncEngineConfig {
  * insert in the same gesture).
  */
 
+/** What a reconcile pass did per entity. */
+interface ReconcileOutcome {
+  /** Reconciled: the replica matches the server for these. */
+  done: string[];
+  /** Not reconciled: the fetch failed, or a newer change raced it. */
+  skipped: string[];
+  /** The pending-request sequence when the pass began fetching. Callers
+   *  that share the pass clear only requests at or below it. */
+  startedAt: number;
+}
+
 export class SyncEngine {
   private config: SyncEngineConfig;
   private cursor: SyncCursor = { last_seq: 0 };
@@ -1651,6 +1662,7 @@ export class SyncEngine {
   /** Stop the sync engine. */
   stop(): void {
     this.running = false;
+    this.cancelPendingReconcile();
     if (this.identityRetryTimer !== null) {
       clearTimeout(this.identityRetryTimer);
       this.identityRetryTimer = null;
@@ -1692,6 +1704,8 @@ export class SyncEngine {
    * in-memory state could fix.
    */
   async resetReplica(opts: { wipeMutations?: boolean } = {}): Promise<void> {
+    // Rows fetched for the old replica must not land in the new one.
+    this.cancelPendingReconcile();
     // Public callers go through the queue so a reset can't race with
     // an in-flight pull / push / reconcile. Internal callers that
     // already hold the queue slot use `resetReplicaInner` directly.
@@ -2303,10 +2317,123 @@ export class SyncEngine {
   }
 
   async reconcile(entities?: string[]): Promise<void> {
+    const epoch = this.pendingReconcileEpoch;
+    const { done, skipped, startedAt } = await this.reconcileReportingSkips(entities);
+    // stop() or resetReplica() ran meanwhile: leave pending work alone.
+    if (epoch !== this.pendingReconcileEpoch) return;
+    // An entity skipped because its fetch failed or raced a newer change
+    // stays pending until a reconcile of it completes. Otherwise a row that
+    // became readable while this replica was away (a share, a new folder)
+    // stays missing until the next focus or reconnect.
+    // Clear only requests this pass covers: one made after it started (a
+    // hint during the fetch) may name rows its response does not hold.
+    for (const e of done) {
+      const requestedAt = this.pendingReconcile.get(e);
+      if (requestedAt !== undefined && requestedAt <= startedAt) this.pendingReconcile.delete(e);
+    }
+    if (skipped.length > 0) this.queuePendingReconcile(skipped);
+  }
+
+  /** Entities to reconcile that have not reconciled yet: named by a server
+   *  hint (`sync-reconcile`), or skipped by an earlier reconcile. */
+  private pendingReconcile = new Map<string, number>();
+  /** Numbers each pending request, so a pass clears only older ones. */
+  private pendingReconcileSeq = 0;
+  private pendingReconcileTimer: ReturnType<typeof setTimeout> | null = null;
+  private pendingReconcileRetries = 0;
+  /** Bumped by stop() and resetReplica(): pending work queued before it
+   *  does not run. */
+  private pendingReconcileEpoch = 0;
+  private lastPendingReconcileAt = 0;
+  /** Hints that arrive this close together share one reconcile. */
+  private static readonly PENDING_RECONCILE_DEBOUNCE_MS = 100;
+  /** At most one hinted reconcile per this interval. */
+  private static readonly PENDING_RECONCILE_MIN_INTERVAL_MS = 1_000;
+  /** Backoff for entities whose fetch raced a newer change: doubling from
+   *  the base, capped. */
+  private static readonly PENDING_RECONCILE_RETRY_BASE_MS = 250;
+  private static readonly PENDING_RECONCILE_RETRY_MAX_MS = 10_000;
+
+  /**
+   * Keep `entities` pending until a reconcile of them completes. Used for
+   * server hints (`sync-reconcile`: a share, an unshare, a folder
+   * membership changed which rows this user may read, and no other event
+   * will tell this replica) and for entities an earlier reconcile skipped.
+   * Requests are merged, run at most once a second, and an entity whose
+   * fetch failed or raced a newer change is retried with backoff until it
+   * lands or the engine stops.
+   */
+  private queuePendingReconcile(entities: string[]): void {
+    for (const e of entities) this.pendingReconcile.set(e, ++this.pendingReconcileSeq);
+    this.schedulePendingReconcile(SyncEngine.PENDING_RECONCILE_DEBOUNCE_MS);
+  }
+
+  private schedulePendingReconcile(delayMs: number): void {
+    if (this.pendingReconcileTimer !== null || !this.running) return;
+    const wait = Math.max(delayMs, this.lastPendingReconcileAt + SyncEngine.PENDING_RECONCILE_MIN_INTERVAL_MS - Date.now());
+    this.pendingReconcileTimer = setTimeout(() => {
+      this.pendingReconcileTimer = null;
+      void this.flushPendingReconcile();
+    }, wait);
+  }
+
+  private async flushPendingReconcile(): Promise<void> {
+    if (!this.running || this.pendingReconcile.size === 0) return;
+    const epoch = this.pendingReconcileEpoch;
+    const entities = [...this.pendingReconcile.keys()];
+    this.pendingReconcile.clear();
+    this.lastPendingReconcileAt = Date.now();
+    let skipped: string[];
+    try {
+      // Queued like any reconcile, and dropped if stop() or resetReplica()
+      // ran while it waited.
+      const result = await this.opQueue.enqueue(`reconcile-pending:${epoch}:${Date.now()}`, async () => {
+        if (epoch !== this.pendingReconcileEpoch || !this.running) return null;
+        try {
+          return await this.reconcileInner(entities);
+        } finally {
+          this.lastReconcileAt = Date.now();
+        }
+      });
+      if (result === null) return;
+      skipped = result.skipped;
+    } catch {
+      skipped = entities;
+    }
+    if (epoch !== this.pendingReconcileEpoch) return;
+    for (const e of skipped) {
+      if (!this.pendingReconcile.has(e)) this.pendingReconcile.set(e, ++this.pendingReconcileSeq);
+    }
+    this.pendingReconcileRetries = skipped.length > 0 ? this.pendingReconcileRetries + 1 : 0;
+    if (this.pendingReconcile.size === 0) return;
+    const delay =
+      skipped.length > 0
+        ? Math.min(
+            SyncEngine.PENDING_RECONCILE_RETRY_BASE_MS * 2 ** (this.pendingReconcileRetries - 1),
+            SyncEngine.PENDING_RECONCILE_RETRY_MAX_MS,
+          )
+        : SyncEngine.PENDING_RECONCILE_DEBOUNCE_MS;
+    this.schedulePendingReconcile(delay);
+  }
+
+  /** Drop pending reconciles, including queued ones (stop, replica reset). */
+  private cancelPendingReconcile(): void {
+    this.pendingReconcileEpoch += 1;
+    if (this.pendingReconcileTimer !== null) {
+      clearTimeout(this.pendingReconcileTimer);
+      this.pendingReconcileTimer = null;
+    }
+    this.pendingReconcile.clear();
+    this.pendingReconcileRetries = 0;
+  }
+
+  /** `reconcile`, resolving with the entities it reconciled and the ones
+   *  it skipped (the fetch failed, or the cursor moved during it). */
+  private async reconcileReportingSkips(entities?: string[]): Promise<ReconcileOutcome> {
     const minIntervalMs = this.config.reconcileMinIntervalMs ?? 2_000;
     const now = Date.now();
     if (entities === undefined && now - this.lastReconcileAt < minIntervalMs) {
-      return;
+      return { done: [], skipped: [], startedAt: this.pendingReconcileSeq };
     }
     // Reconcile waits behind any in-flight pull / refresh / push so it
     // can't apply rows captured under a stale session.
@@ -2315,7 +2442,7 @@ export class SyncEngine {
       // the same window share one fetch per entity.
       return this.opQueue.enqueue("reconcile", async () => {
         try {
-          await this.reconcileInner();
+          return await this.reconcileInner();
         } finally {
           this.lastReconcileAt = Date.now();
         }
@@ -2330,9 +2457,9 @@ export class SyncEngine {
       for (const e of entities) open.entities.add(e);
       return open.promise;
     }
-    const batch: { entities: Set<string>; promise: Promise<void> } = {
+    const batch: { entities: Set<string>; promise: Promise<ReconcileOutcome> } = {
       entities: new Set(entities),
-      promise: Promise.resolve(),
+      promise: Promise.resolve({ done: [], skipped: [], startedAt: this.pendingReconcileSeq }),
     };
     this.scopedReconcileBatch = batch;
     this.scopedReconcileSeq += 1;
@@ -2341,7 +2468,7 @@ export class SyncEngine {
       async () => {
         if (this.scopedReconcileBatch === batch) this.scopedReconcileBatch = null;
         try {
-          await this.reconcileInner([...batch.entities]);
+          return await this.reconcileInner([...batch.entities]);
         } finally {
           this.lastReconcileAt = Date.now();
         }
@@ -2353,14 +2480,15 @@ export class SyncEngine {
   /** Scoped reconcile batch that has not started running yet. */
   private scopedReconcileBatch: {
     entities: Set<string>;
-    promise: Promise<void>;
+    promise: Promise<ReconcileOutcome>;
   } | null = null;
   private scopedReconcileSeq = 0;
 
-  private async reconcileInner(entities?: string[]): Promise<void> {
+  private async reconcileInner(entities?: string[]): Promise<ReconcileOutcome> {
+    const startedAt = this.pendingReconcileSeq;
     // Same reasoning as pullInner: the leader reconciles, broadcasts
     // results, and follower replicas converge via the channel.
-    if (!this.isMultiTabLeader) return;
+    if (!this.isMultiTabLeader) return { done: [], skipped: [], startedAt };
     // Sweep entities with local rows PLUS entities the app has observed
     // via useQuery (even when empty locally). Without the observed set,
     // a server row in a never-cached entity is never reconciled and
@@ -2368,7 +2496,9 @@ export class SyncEngine {
     const names =
       entities ??
       [...new Set([...this.store.entityNames(), ...this.observedEntities])];
-    if (names.length === 0) return;
+    if (names.length === 0) return { done: [], skipped: [], startedAt };
+    const skipped: string[] = [];
+    const done: string[] = [];
     // Tombstone seq for any local row the server doesn't return. Using
     // the current cursor means future inserts (which have higher seqs)
     // bypass the tombstone — re-creation server-side still propagates.
@@ -2423,6 +2553,7 @@ export class SyncEngine {
             // Entity removed from the manifest — definitive. Drop its rows.
             this.reconcile403Streak.delete(entity);
             await this.dropEntity(entity, tombstoneSeq);
+            done.push(entity);
             return;
           }
           if (status === 403) {
@@ -2444,11 +2575,17 @@ export class SyncEngine {
             const streak = (this.reconcile403Streak.get(entity) ?? 0) + 1;
             if (streak < 2) {
               this.reconcile403Streak.set(entity, streak);
+              skipped.push(entity);
               return;
             }
             this.reconcile403Streak.delete(entity);
             await this.dropEntity(entity, tombstoneSeq);
+            done.push(entity);
+            return;
           }
+          // Not reconciled (offline, a 5xx): reported, so a server hint
+          // stays pending and retries.
+          skipped.push(entity);
           return;
         }
         // Successful fetch — the entity is readable, so any prior 403 streak
@@ -2460,7 +2597,9 @@ export class SyncEngine {
           // for a row our snapshot just captured. Bail out for this
           // entity; reconcile() is triggered again on visibility-change
           // and reconnect, and the WS event already carried the latest
-          // state for the affected row.
+          // state for the affected row. Reported, so a server hint can
+          // retry (flushPendingReconcile).
+          skipped.push(entity);
           return;
         }
         if (this.session.signature() !== sessionBeforeFetch) {
@@ -2477,8 +2616,10 @@ export class SyncEngine {
           tombstoneSeq,
           fetchTruncated,
         );
+        done.push(entity);
       }),
     );
+    return { done, skipped, startedAt };
   }
 
   /** Fetch every row for an entity. Uses cursor pagination so big tables
@@ -4105,6 +4246,15 @@ export class SyncEngine {
     // fresh /api/auth/me read which updates the cached session AND,
     // on tenant flip, resets the replica so stale rows from the
     // previous tenant disappear.
+    // A change elsewhere (a share, an unshare, a folder membership)
+    // changed which rows of these entities this user may read, without a
+    // change event for the rows themselves. Reconcile them.
+    if (msg.type === "sync-reconcile" && Array.isArray(msg.entities)) {
+      const entities = msg.entities.filter((e): e is string => typeof e === "string");
+      if (entities.length > 0) this.queuePendingReconcile(entities);
+      return;
+    }
+
     if (msg.type === "session-changed") {
       void this.refreshResolvedSession();
       return;

package/src/reconcile.test.ts

@@ -668,3 +668,352 @@ describe("SyncEngine cookie auth", () => {
     expect(notifications).toBe(1);
   });
 });
+
+// The server sends `sync-reconcile` when a row of another entity changed
+// which rows of these entities the user may read (a share, an unshare):
+// no change event of the rows themselves will come.
+describe("sync-reconcile hint", () => {
+  let restore: (() => void) | null = null;
+
+  afterEach(() => {
+    restore?.();
+    restore = null;
+  });
+
+  type Internals = {
+    dispatchInboundMessage(m: Record<string, unknown>): void;
+    running: boolean;
+    cursor: { last_seq: number };
+    pendingReconcile: Map<string, number>;
+  };
+  const inner = (engine: SyncEngine) => engine as unknown as Internals;
+  const deliver = (engine: SyncEngine, msg: Record<string, unknown>) => inner(engine).dispatchInboundMessage(msg);
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  function documentServer(onFetch: (n: number) => void = () => {}) {
+    let fetches = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Document/cursor")) {
+        fetches += 1;
+        onFetch(fetches);
+        return {
+          status: 200,
+          body: { data: [{ id: "shared", title: "Now shared" }], next_cursor: null, has_more: false },
+        };
+      }
+      return { status: 404, body: {} };
+    });
+    return () => fetches;
+  }
+
+  test("reconciles the named entities: the shared row arrives, the unshared one leaves", async () => {
+    const fetches = documentServer();
+    const engine = makeEngine();
+    inner(engine).running = true;
+    seedStore(engine, "Document", [{ id: "unshared", title: "No longer shared" }]);
+
+    deliver(engine, { type: "sync-reconcile", entities: ["Document"] });
+    await sleep(250);
+
+    expect(fetches()).toBe(1);
+    expect(engine.store.list("Document").map((r) => (r as { id: string }).id)).toEqual(["shared"]);
+    engine.stop();
+  });
+
+  test("hints that arrive together share one fetch", async () => {
+    const fetches = documentServer();
+    const engine = makeEngine();
+    inner(engine).running = true;
+    for (let i = 0; i < 5; i++) deliver(engine, { type: "sync-reconcile", entities: ["Document"] });
+    await sleep(250);
+    expect(fetches()).toBe(1);
+    engine.stop();
+  });
+
+  test("keeps retrying while newer changes race the fetch, then lands", async () => {
+    const engine = makeEngine();
+    // The first two fetches race a change event: the cursor moves.
+    const fetches = documentServer((n) => {
+      if (n <= 2) inner(engine).cursor.last_seq += 1;
+    });
+    inner(engine).running = true;
+
+    deliver(engine, { type: "sync-reconcile", entities: ["Document"] });
+    await sleep(250);
+    expect(fetches()).toBe(1);
+    expect(engine.store.list("Document")).toEqual([]);
+    expect([...inner(engine).pendingReconcile.keys()]).toEqual(["Document"]);
+
+    // Retries run at most once a second.
+    await sleep(2300);
+    expect(fetches()).toBe(3);
+    expect(engine.store.list("Document").map((r) => (r as { id: string }).id)).toEqual(["shared"]);
+    expect(inner(engine).pendingReconcile.size).toBe(0);
+    engine.stop();
+  });
+
+  test("stop drops pending hints", async () => {
+    const fetches = documentServer();
+    const engine = makeEngine();
+    inner(engine).running = true;
+    deliver(engine, { type: "sync-reconcile", entities: ["Document"] });
+    engine.stop();
+    await sleep(250);
+    expect(fetches()).toBe(0);
+    expect(inner(engine).pendingReconcile.size).toBe(0);
+  });
+
+  test("ignores a hint without entity names", async () => {
+    const fetches = documentServer();
+    const engine = makeEngine();
+    inner(engine).running = true;
+    deliver(engine, { type: "sync-reconcile", entities: [42, null] });
+    deliver(engine, { type: "sync-reconcile" });
+    await sleep(250);
+    expect(fetches()).toBe(0);
+    engine.stop();
+  });
+});
+
+describe("sync-reconcile hint after a failed fetch", () => {
+  let restore: (() => void) | null = null;
+  afterEach(() => {
+    restore?.();
+    restore = null;
+  });
+
+  test("a 5xx keeps the hint pending and the retry lands", async () => {
+    let fetches = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Document/cursor")) {
+        fetches += 1;
+        if (fetches === 1) return { status: 503, body: {} };
+        return { status: 200, body: { data: [], next_cursor: null, has_more: false } };
+      }
+      return { status: 404, body: {} };
+    });
+    const engine = makeEngine();
+    const inner = engine as unknown as {
+      running: boolean;
+      pendingReconcile: Map<string, number>;
+      dispatchInboundMessage(m: Record<string, unknown>): void;
+    };
+    inner.running = true;
+    seedStore(engine, "Document", [{ id: "unshared", title: "No longer shared" }]);
+
+    inner.dispatchInboundMessage({ type: "sync-reconcile", entities: ["Document"] });
+    await new Promise((r) => setTimeout(r, 250));
+    expect(fetches).toBe(1);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Document"]);
+    expect(engine.store.list("Document").length).toBe(1);
+
+    await new Promise((r) => setTimeout(r, 1200));
+    expect(fetches).toBe(2);
+    expect(engine.store.list("Document")).toEqual([]);
+    engine.stop();
+  });
+});
+
+// Any reconcile, not only a hinted one: an entity skipped because its fetch
+// raced a newer change is retried, so a row that became readable while the
+// page was away (a new folder, a share) still arrives.
+describe("a skipped reconcile retries", () => {
+  let restore: (() => void) | null = null;
+  afterEach(() => {
+    restore?.();
+    restore = null;
+  });
+
+  test("a startup reconcile that raced a change lands on the retry", async () => {
+    const engine = makeEngine();
+    const inner = engine as unknown as { running: boolean; cursor: { last_seq: number }; pendingReconcile: Set<string> };
+    let fetches = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Folder/cursor")) {
+        fetches += 1;
+        if (fetches === 1) inner.cursor.last_seq += 1;
+        return { status: 200, body: { data: [{ id: "f1", name: "Team" }], next_cursor: null, has_more: false } };
+      }
+      return { status: 404, body: {} };
+    });
+    inner.running = true;
+
+    await engine.reconcile(["Folder"]);
+    expect(engine.store.list("Folder")).toEqual([]);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Folder"]);
+
+    await new Promise((r) => setTimeout(r, 1300));
+    expect(fetches).toBe(2);
+    expect(engine.store.list("Folder").map((r) => (r as { id: string }).id)).toEqual(["f1"]);
+    engine.stop();
+  });
+});
+
+describe("pending reconciles end when they should", () => {
+  let restore: (() => void) | null = null;
+  afterEach(() => {
+    restore?.();
+    restore = null;
+  });
+
+  type Internals = {
+    running: boolean;
+    pendingReconcile: Map<string, number>;
+    opQueue: { enqueue<T>(key: string, fn: () => Promise<T>): Promise<T> };
+    dispatchInboundMessage(m: Record<string, unknown>): void;
+  };
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  function server(status: () => number) {
+    let fetches = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Document/cursor")) {
+        fetches += 1;
+        const s = status();
+        if (s !== 200) return { status: s, body: {} };
+        return { status: 200, body: { data: [], next_cursor: null, has_more: false } };
+      }
+      return { status: 404, body: {} };
+    });
+    return () => fetches;
+  }
+
+  test("a later successful reconcile clears the pending retry", async () => {
+    let failing = true;
+    const fetches = server(() => (failing ? 503 : 200));
+    const engine = makeEngine();
+    const inner = engine as unknown as Internals;
+    inner.running = true;
+    await engine.reconcile(["Document"]);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Document"]);
+    failing = false;
+    await engine.reconcile(["Document"]);
+    expect(inner.pendingReconcile.size).toBe(0);
+    await sleep(1300);
+    expect(fetches()).toBe(2);
+    engine.stop();
+  });
+
+  test("stop cancels a retry already waiting in the queue", async () => {
+    const fetches = server(() => 200);
+    const engine = makeEngine();
+    const inner = engine as unknown as Internals;
+    inner.running = true;
+    // A slow operation holds the queue while the retry's timer fires.
+    void inner.opQueue.enqueue("slow", () => sleep(400));
+    inner.dispatchInboundMessage({ type: "sync-reconcile", entities: ["Document"] });
+    await sleep(200);
+    engine.stop();
+    await sleep(400);
+    expect(fetches()).toBe(0);
+  });
+
+  test("a replica reset drops pending retries", async () => {
+    const fetches = server(() => 503);
+    const engine = makeEngine();
+    const inner = engine as unknown as Internals;
+    inner.running = true;
+    await engine.reconcile(["Document"]);
+    expect(fetches()).toBe(1);
+    await engine.resetReplica();
+    expect(inner.pendingReconcile.size).toBe(0);
+    await sleep(1300);
+    expect(fetches()).toBe(1);
+    engine.stop();
+  });
+});
+
+describe("pending reconciles and newer requests", () => {
+  let restore: (() => void) | null = null;
+  afterEach(() => {
+    restore?.();
+    restore = null;
+  });
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+  type Internals = {
+    running: boolean;
+    pendingReconcile: Map<string, number>;
+    dispatchInboundMessage(m: Record<string, unknown>): void;
+  };
+
+  test("a hint that arrives during a fetch survives that fetch", async () => {
+    const engine = makeEngine();
+    const inner = engine as unknown as Internals;
+    let fetches = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Document/cursor")) {
+        fetches += 1;
+        // The server already built this response when the share lands.
+        if (fetches === 1) inner.dispatchInboundMessage({ type: "sync-reconcile", entities: ["Document"] });
+        return { status: 200, body: { data: [], next_cursor: null, has_more: false } };
+      }
+      return { status: 404, body: {} };
+    });
+    inner.running = true;
+    await engine.reconcile(["Document"]);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Document"]);
+    await sleep(1300);
+    expect(fetches).toBe(2);
+    engine.stop();
+  });
+
+  test("a reconcile in flight during a reset does not bring retries back", async () => {
+    const engine = makeEngine();
+    const inner = engine as unknown as Internals;
+    let fetches = 0;
+    let release: () => void = () => {};
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Document/cursor")) {
+        fetches += 1;
+        if (fetches === 1) await new Promise<void>((r) => (release = r));
+        return { status: 503, body: {} };
+      }
+      return { status: 404, body: {} };
+    });
+    inner.running = true;
+    const pass = engine.reconcile(["Document"]);
+    await sleep(20);
+    const reset = engine.resetReplica();
+    release();
+    await pass;
+    await reset;
+    expect(inner.pendingReconcile.size).toBe(0);
+    await sleep(1300);
+    expect(fetches).toBe(1);
+    engine.stop();
+  });
+});
+
+test("two callers sharing one full reconcile keep a hint that arrived between them", async () => {
+  const engine = makeEngine();
+  const inner = engine as unknown as {
+    running: boolean;
+    pendingReconcile: Map<string, number>;
+    store: { applyChange(ev: ChangeEvent): void };
+    dispatchInboundMessage(m: Record<string, unknown>): void;
+  };
+  seedStore(engine, "Document", [{ id: "d0", title: "seed" }]);
+  let fetches = 0;
+  let release: () => void = () => {};
+  const restore = installFetch(async (url) => {
+    if (url.includes("/api/entities/Document/cursor")) {
+      fetches += 1;
+      if (fetches === 1) await new Promise<void>((r) => (release = r));
+      return { status: 200, body: { data: [{ id: "d0", title: "seed" }], next_cursor: null, has_more: false } };
+    }
+    return { status: 404, body: {} };
+  });
+  try {
+    inner.running = true;
+    const first = engine.reconcile();
+    await new Promise((r) => setTimeout(r, 20));
+    inner.dispatchInboundMessage({ type: "sync-reconcile", entities: ["Document"] });
+    const second = engine.reconcile();
+    release();
+    await Promise.all([first, second]);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Document"]);
+  } finally {
+    engine.stop();
+    restore();
+  }
+});