@pylonsync/sync 0.22.43 → 0.22.46

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,34 +710,41 @@ export declare class SyncEngine {
      */
     observeEntity(entity: string): void;
     reconcile(entities?: string[]): Promise<void>;
-    /** Entities a server hint (`sync-reconcile`) asked to reconcile that
-     *  have not reconciled yet. */
-    private hintPending;
-    private hintTimer;
-    private hintRetries;
-    private lastHintReconcileAt;
+    /** 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 HINT_DEBOUNCE_MS;
+    private static readonly PENDING_RECONCILE_DEBOUNCE_MS;
     /** At most one hinted reconcile per this interval. */
-    private static readonly HINT_MIN_INTERVAL_MS;
+    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 HINT_RETRY_BASE_MS;
-    private static readonly HINT_RETRY_MAX_MS;
+    private static readonly PENDING_RECONCILE_RETRY_BASE_MS;
+    private static readonly PENDING_RECONCILE_RETRY_MAX_MS;
     /**
-     * The server said a change elsewhere (a share, an unshare, a folder
-     * membership) changed which rows of `entities` this user may read
-     * (`sync-reconcile`). No other event will tell this replica, so the
-     * entities stay pending until a reconcile of them completes: hints are
-     * merged, run at most once a second, and an entity whose fetch raced a
-     * newer change is retried with backoff until it lands or the engine
-     * stops.
+     * 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 queueHintReconcile;
-    private scheduleHintReconcile;
-    private flushHintReconcile;
-    /** `reconcile`, resolving with the entities skipped because the cursor
-     *  moved during their fetch. */
+    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;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.43",
+  "version": "0.22.46",
   "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,12 +1662,7 @@ export class SyncEngine {
   /** Stop the sync engine. */
   stop(): void {
     this.running = false;
-    if (this.hintTimer !== null) {
-      clearTimeout(this.hintTimer);
-      this.hintTimer = null;
-    }
-    this.hintPending.clear();
-    this.hintRetries = 0;
+    this.cancelPendingReconcile();
     if (this.identityRetryTimer !== null) {
       clearTimeout(this.identityRetryTimer);
       this.identityRetryTimer = null;
@@ -1698,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.
@@ -2309,75 +2317,123 @@ export class SyncEngine {
   }
 
   async reconcile(entities?: string[]): Promise<void> {
-    await this.reconcileReportingSkips(entities);
+    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 a server hint (`sync-reconcile`) asked to reconcile that
-   *  have not reconciled yet. */
-  private hintPending = new Set<string>();
-  private hintTimer: ReturnType<typeof setTimeout> | null = null;
-  private hintRetries = 0;
-  private lastHintReconcileAt = 0;
+  /** 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 HINT_DEBOUNCE_MS = 100;
+  private static readonly PENDING_RECONCILE_DEBOUNCE_MS = 100;
   /** At most one hinted reconcile per this interval. */
-  private static readonly HINT_MIN_INTERVAL_MS = 1_000;
+  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 HINT_RETRY_BASE_MS = 250;
-  private static readonly HINT_RETRY_MAX_MS = 10_000;
+  private static readonly PENDING_RECONCILE_RETRY_BASE_MS = 250;
+  private static readonly PENDING_RECONCILE_RETRY_MAX_MS = 10_000;
 
   /**
-   * The server said a change elsewhere (a share, an unshare, a folder
-   * membership) changed which rows of `entities` this user may read
-   * (`sync-reconcile`). No other event will tell this replica, so the
-   * entities stay pending until a reconcile of them completes: hints are
-   * merged, run at most once a second, and an entity whose fetch raced a
-   * newer change is retried with backoff until it lands or the engine
-   * stops.
+   * 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 queueHintReconcile(entities: string[]): void {
-    for (const e of entities) this.hintPending.add(e);
-    this.scheduleHintReconcile(SyncEngine.HINT_DEBOUNCE_MS);
+  private queuePendingReconcile(entities: string[]): void {
+    for (const e of entities) this.pendingReconcile.set(e, ++this.pendingReconcileSeq);
+    this.schedulePendingReconcile(SyncEngine.PENDING_RECONCILE_DEBOUNCE_MS);
   }
 
-  private scheduleHintReconcile(delayMs: number): void {
-    if (this.hintTimer !== null || !this.running) return;
-    const wait = Math.max(delayMs, this.lastHintReconcileAt + SyncEngine.HINT_MIN_INTERVAL_MS - Date.now());
-    this.hintTimer = setTimeout(() => {
-      this.hintTimer = null;
-      void this.flushHintReconcile();
+  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 flushHintReconcile(): Promise<void> {
-    if (!this.running || this.hintPending.size === 0) return;
-    const entities = [...this.hintPending];
-    this.hintPending.clear();
-    this.lastHintReconcileAt = Date.now();
+  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 {
-      skipped = await this.reconcileReportingSkips(entities);
+      // 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;
     }
-    for (const e of skipped) this.hintPending.add(e);
-    this.hintRetries = skipped.length > 0 ? this.hintRetries + 1 : 0;
-    if (this.hintPending.size === 0) return;
+    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.HINT_RETRY_BASE_MS * 2 ** (this.hintRetries - 1), SyncEngine.HINT_RETRY_MAX_MS)
-        : SyncEngine.HINT_DEBOUNCE_MS;
-    this.scheduleHintReconcile(delay);
+        ? 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 skipped because the cursor
-   *  moved during their fetch. */
-  private async reconcileReportingSkips(entities?: string[]): Promise<string[]> {
+  /** `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.
@@ -2401,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<string[]> } = {
+    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;
@@ -2424,14 +2480,15 @@ export class SyncEngine {
   /** Scoped reconcile batch that has not started running yet. */
   private scopedReconcileBatch: {
     entities: Set<string>;
-    promise: Promise<string[]>;
+    promise: Promise<ReconcileOutcome>;
   } | null = null;
   private scopedReconcileSeq = 0;
 
-  private async reconcileInner(entities?: string[]): Promise<string[]> {
+  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
@@ -2439,8 +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.
@@ -2495,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) {
@@ -2521,6 +2580,7 @@ export class SyncEngine {
             }
             this.reconcile403Streak.delete(entity);
             await this.dropEntity(entity, tombstoneSeq);
+            done.push(entity);
             return;
           }
           // Not reconciled (offline, a 5xx): reported, so a server hint
@@ -2538,7 +2598,7 @@ export class SyncEngine {
           // entity; reconcile() is triggered again on visibility-change
           // and reconnect, and the WS event already carried the latest
           // state for the affected row. Reported, so a server hint can
-          // retry (flushHintReconcile).
+          // retry (flushPendingReconcile).
           skipped.push(entity);
           return;
         }
@@ -2556,9 +2616,10 @@ export class SyncEngine {
           tombstoneSeq,
           fetchTruncated,
         );
+        done.push(entity);
       }),
     );
-    return skipped;
+    return { done, skipped, startedAt };
   }
 
   /** Fetch every row for an entity. Uses cursor pagination so big tables
@@ -4190,7 +4251,7 @@ export class SyncEngine {
     // 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.queueHintReconcile(entities);
+      if (entities.length > 0) this.queuePendingReconcile(entities);
       return;
     }
 

package/src/reconcile.test.ts

@@ -684,7 +684,7 @@ describe("sync-reconcile hint", () => {
     dispatchInboundMessage(m: Record<string, unknown>): void;
     running: boolean;
     cursor: { last_seq: number };
-    hintPending: Set<string>;
+    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);
@@ -742,13 +742,13 @@ describe("sync-reconcile hint", () => {
     await sleep(250);
     expect(fetches()).toBe(1);
     expect(engine.store.list("Document")).toEqual([]);
-    expect([...inner(engine).hintPending]).toEqual(["Document"]);
+    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).hintPending.size).toBe(0);
+    expect(inner(engine).pendingReconcile.size).toBe(0);
     engine.stop();
   });
 
@@ -760,7 +760,7 @@ describe("sync-reconcile hint", () => {
     engine.stop();
     await sleep(250);
     expect(fetches()).toBe(0);
-    expect(inner(engine).hintPending.size).toBe(0);
+    expect(inner(engine).pendingReconcile.size).toBe(0);
   });
 
   test("ignores a hint without entity names", async () => {
@@ -795,7 +795,7 @@ describe("sync-reconcile hint after a failed fetch", () => {
     const engine = makeEngine();
     const inner = engine as unknown as {
       running: boolean;
-      hintPending: Set<string>;
+      pendingReconcile: Map<string, number>;
       dispatchInboundMessage(m: Record<string, unknown>): void;
     };
     inner.running = true;
@@ -804,7 +804,7 @@ describe("sync-reconcile hint after a failed fetch", () => {
     inner.dispatchInboundMessage({ type: "sync-reconcile", entities: ["Document"] });
     await new Promise((r) => setTimeout(r, 250));
     expect(fetches).toBe(1);
-    expect([...inner.hintPending]).toEqual(["Document"]);
+    expect([...inner.pendingReconcile.keys()]).toEqual(["Document"]);
     expect(engine.store.list("Document").length).toBe(1);
 
     await new Promise((r) => setTimeout(r, 1200));
@@ -813,3 +813,207 @@ describe("sync-reconcile hint after a failed fetch", () => {
     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();
+  }
+});