@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/realtime.ts

@@ -1,7 +1,8 @@
+import { isNative } from "@multiplatform.one/platform";
 import type { ManagerOptions, Socket, SocketOptions } from "socket.io-client";
 import { io } from "socket.io-client";
 import type { AuthConfig } from "./core/types";
-import { isBrowser } from "./util";
+import { isBrowser, isGjs } from "./util";
 
 export type Handler = (payload: unknown) => void;
 
@@ -27,10 +28,30 @@ export interface RealtimeConfig {
    * `/socket.io` to the SocketIO backend.
    */
   socketPort?: number;
+  /**
+   * Frappe site name, used as the Socket.IO namespace.
+   *
+   * Frappe's realtime server is multi-tenant: every site lives on its own
+   * Socket.IO namespace (`/<sitename>`) guarded by the auth middleware, and
+   * server events are only emitted to that namespace.  Connecting to the
+   * root namespace `/` silently succeeds but never receives any events.
+   *
+   * Defaults to the hostname of `baseURL`, which matches Frappe's own
+   * site-name resolution for host-served sites (and the `default_site` of a
+   * standard dev bench on localhost).
+   */
+  siteName?: string;
   platform?: RealtimePlatform;
   socketOptions?: Partial<ManagerOptions & SocketOptions>;
 }
 
+type DocRoom = { doctype: string; name: string };
+type ListRoom = { doctype: string; filters?: Record<string, unknown> };
+
+function docRoomKey(doctype: string, name: string) {
+  return `${doctype}\0${name}`;
+}
+
 export class RealtimeModule {
   private socket: Socket | undefined;
   private handlerMap = new Map<string, Set<Handler>>();
@@ -38,9 +59,16 @@ export class RealtimeModule {
   private attachedSocketEvents = new Set<string>();
   /** Stored socket event handler references for proper cleanup. */
   private socketEventHandlers = new Map<string, (payload: unknown) => void>();
+  /** Active doc rooms — re-emitted on every (re)connect. */
+  private docRooms = new Map<string, DocRoom>();
+  /** Active list rooms — re-emitted on every (re)connect. */
+  private listRooms = new Map<string, ListRoom>();
   private socketHealthy = false;
   private isConnecting = false;
+  private healthyWaiters = new Set<(ok: boolean) => void>();
   private config: RealtimeConfig;
+  /** In-flight credential re-resolution (deduped across triggers). */
+  private authRefreshInflight?: Promise<void>;
 
   constructor(config: RealtimeConfig) {
     this.config = {
@@ -50,28 +78,76 @@ export class RealtimeModule {
   }
 
   private detectPlatform() {
-    if (!isBrowser()) return RealtimePlatform.Node;
-    if (typeof navigator !== "undefined" && navigator.userAgent?.includes("ReactNative")) {
+    // GJS (GNOME desktop) FIRST: isBrowser() is true there (the sync engine
+    // runs), but the Web classification would be wrong — GJS has no XHR for
+    // a polling-first handshake, and its WebSocket comes from an
+    // entry-installed libsoup polyfill that DOES accept custom handshake
+    // headers (RN-style `{ headers }` third argument). Classify like Node:
+    // websocket-first transports + the extraHeaders auth path.
+    if (isGjs()) return RealtimePlatform.Node;
+    // React Native next: RN sets navigator.product === "ReactNative" but no
+    // userAgent, so a UA-only sniff misclassifies RN as Web — skipping the
+    // extraHeaders auth path (sid cookie / Origin) and connecting cookie-auth
+    // sockets as guest. The platform package's static isNative flag is the
+    // canonical signal; the navigator checks are runtime fallbacks (kept for
+    // environments that fake a RN UA, e.g. tests).
+    if (
+      isNative ||
+      (typeof navigator !== "undefined" &&
+        (navigator.product === "ReactNative" || navigator.userAgent?.includes("ReactNative")))
+    ) {
       return RealtimePlatform.ReactNative;
     }
+    if (!isBrowser()) return RealtimePlatform.Node;
     return RealtimePlatform.Web;
   }
 
   private getSocketURL(): string {
     const base = this.config.baseURL.replace(/\/$/, "");
-    if (!this.config.socketPort) return base;
     try {
       const url = new URL(base);
-      url.port = String(this.config.socketPort);
-      return url.toString().replace(/\/$/, "");
+      // Assemble origin from parts instead of mutating url.port and reading
+      // url.origin: minimal URL polyfills (e.g. the GJS/react-gnome shim)
+      // parse host at construction and never recompute origin from a port
+      // assignment — which silently dropped socketPort and pointed the
+      // socket at the web server.
+      const port = this.config.socketPort ? String(this.config.socketPort) : url.port;
+      const host = port ? `${url.hostname}:${port}` : url.hostname;
+      // The path portion of the URL passed to io() is the Socket.IO
+      // namespace — frappe requires it to be the site name (see siteName).
+      const siteName = this.config.siteName || url.hostname;
+      return `${url.protocol}//${host}/${siteName}`;
     } catch {
-      // Fallback: replace port via regex when URL constructor isn't available
-      return base.replace(/(:\d+)/, `:${this.config.socketPort}`);
+      // Fallback: string manipulation when URL constructor isn't available
+      let result = base;
+      if (this.config.socketPort) {
+        result = result.replace(/(:\d+)/, `:${this.config.socketPort}`);
+      }
+      const siteName = this.config.siteName || result.replace(/^https?:\/\//, "").split(/[/:]/)[0];
+      return `${result}/${siteName}`;
     }
   }
 
   private async getAuthOptions(): Promise<Partial<ManagerOptions & SocketOptions>> {
     const authOptions: Partial<ManagerOptions & SocketOptions> = {};
+    if (this.config.platform !== RealtimePlatform.Web) {
+      // Non-browser clients must send an Origin header themselves: frappe's
+      // socketio middleware rejects mismatched Origin/Host hostnames AND uses
+      // the Origin as the base URL for its can_subscribe_* permission
+      // callbacks to the web server — so it must point at the WEB base URL
+      // (baseURL), not the socketio port. The Web platform must NEVER set it:
+      // Origin is a forbidden header in browsers (they always send the page
+      // origin themselves), and attempting it makes engine.io's XHR transport
+      // log "Attempt to set a forbidden header was denied: Origin" on every
+      // polling request. Browser-like TEST runtimes (happy-dom/jsdom over
+      // node transports) that need a bench-pointing Origin opt in via
+      // `platform: RealtimePlatform.Node` or `socketOptions.extraHeaders`.
+      try {
+        authOptions.extraHeaders = { Origin: new URL(this.config.baseURL).origin };
+      } catch {
+        authOptions.extraHeaders = { Origin: this.config.baseURL.replace(/\/$/, "") };
+      }
+    }
     if (this.config.platform !== RealtimePlatform.Web && this.config.auth?.sessionId) {
       const sessionId =
         typeof this.config.auth.sessionId === "function"
@@ -79,40 +155,125 @@ export class RealtimeModule {
           : this.config.auth.sessionId;
       const Cookie = `sid=${sessionId}`;
       authOptions.extraHeaders = {
+        ...authOptions.extraHeaders,
         Cookie,
       };
-      authOptions.transportOptions = {
-        websocket: {
-          extraHeaders: {
-            Cookie,
-          },
-        },
-        polling: {
-          extraHeaders: {
-            Cookie,
-          },
-        },
-      };
     }
     if (this.config.auth?.useToken && this.config.auth.token) {
       const token =
         typeof this.config.auth.token === "function"
           ? await this.config.auth.token()
           : this.config.auth.token;
-      const authType = this.config.auth.type || "Bearer";
-      if (!authOptions.extraHeaders) authOptions.extraHeaders = {};
-      authOptions.extraHeaders.Authorization =
-        authType === "Bearer" ? `Bearer ${token}` : `token ${token}`;
+      // Skip when the getter resolves empty (signed out): a bare
+      // "Bearer " header would fail frappe's auth instead of falling
+      // back to guest.
+      if (token) {
+        const authType = this.config.auth.type || "Bearer";
+        if (!authOptions.extraHeaders) authOptions.extraHeaders = {};
+        authOptions.extraHeaders.Authorization =
+          authType === "Bearer" ? `Bearer ${token}` : `token ${token}`;
+      }
+    }
+    if (authOptions.extraHeaders) {
+      // Mirror headers into per-transport options: node websocket reads
+      // transportOptions.websocket.extraHeaders, browser polling reads the
+      // top-level extraHeaders — covering both keeps every handshake
+      // (initial, upgrade, reconnect) authenticated.
+      authOptions.transportOptions = {
+        websocket: { extraHeaders: { ...authOptions.extraHeaders } },
+        polling: { extraHeaders: { ...authOptions.extraHeaders } },
+      };
     }
     return authOptions;
   }
 
+  /**
+   * Re-resolve credentials (token function / session id) and swap them into
+   * the LIVE manager options in place. Socket.IO constructs a fresh engine
+   * from `manager.opts` on every (re)connect attempt, so mutating the opts
+   * makes the next handshake carry the refreshed token — without tearing
+   * down handlers or room subscriptions. Called on disconnect and before
+   * reconnect attempts so a token that rotated mid-session (e.g. Keycloak
+   * refresh) never strands the socket in an auth-rejected retry loop.
+   */
+  private refreshSocketAuth(): Promise<void> {
+    const socket = this.socket;
+    if (!socket) return Promise.resolve();
+    if (this.authRefreshInflight) return this.authRefreshInflight;
+    this.authRefreshInflight = (async () => {
+      try {
+        const authOptions = await this.getAuthOptions();
+        const manager = (socket as { io?: { opts?: Record<string, unknown> } }).io;
+        if (manager?.opts) Object.assign(manager.opts, authOptions);
+      } catch {
+        // Keep the previous credentials; the next disconnect/reconnect
+        // cycle retries the refresh.
+      } finally {
+        this.authRefreshInflight = undefined;
+      }
+    })();
+    return this.authRefreshInflight;
+  }
+
+  private resolveHealthyWaiters(ok: boolean) {
+    for (const resolve of this.healthyWaiters) resolve(ok);
+    this.healthyWaiters.clear();
+  }
+
+  private waitUntilHealthy(timeoutMs = 20_000): Promise<boolean> {
+    if (this.socketHealthy && this.socket?.connected) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.healthyWaiters.delete(onReady);
+        resolve(false);
+      }, timeoutMs);
+      const onReady = (ok: boolean) => {
+        clearTimeout(timer);
+        resolve(ok);
+      };
+      this.healthyWaiters.add(onReady);
+    });
+  }
+
+  private async ensureConnected(): Promise<void> {
+    if (this.socketHealthy && this.socket?.connected) return;
+    if (!this.socket && !this.isConnecting) {
+      await this.connect();
+    }
+    await this.waitUntilHealthy();
+  }
+
+  private resubscribeRooms(): void {
+    if (!this.socket || !this.socketHealthy) return;
+    // Frappe's socketio handlers take POSITIONAL args (doctype, docname) —
+    // not an object payload — and list-level subscription is doctype_subscribe.
+    for (const room of this.docRooms.values()) {
+      this.socket.emit("doc_subscribe", room.doctype, room.name);
+    }
+    for (const room of this.listRooms.values()) {
+      this.socket.emit("doctype_subscribe", room.doctype);
+    }
+  }
+
   private async connect() {
     if (this.socket || this.isConnecting) return;
     this.isConnecting = true;
     try {
       const authOptions = await this.getAuthOptions();
       const socketURL = this.getSocketURL();
+      // Browsers always handshake over polling first (Socket.IO's default
+      // ordering): custom headers only attach to the XHR handshake (token
+      // auth), session-cookie auth and reverse-proxy-injected Authorization
+      // only apply to HTTP requests, and ws-upgrade-hostile dev proxies
+      // (e.g. Vite in middleware mode — the Storybook dev server) hang raw
+      // websocket upgrades forever, so a websocket-first browser client
+      // stalls ~20s per attempt and never connects. Socket.IO upgrades the
+      // established session to websocket when the path supports it.
+      // Everywhere else (Node, React Native) websocket-first is fine.
+      const transports =
+        this.config.platform === RealtimePlatform.Web
+          ? ["polling", "websocket"]
+          : ["websocket", "polling"];
       this.socket = io(socketURL, {
         autoConnect: false,
         path: "/socket.io",
@@ -122,7 +283,7 @@ export class RealtimeModule {
         reconnectionDelay: 1000,
         reconnectionDelayMax: 5000,
         timeout: 20000,
-        transports: ["websocket", "polling"],
+        transports,
         withCredentials: true,
         ...authOptions,
         ...this.config.socketOptions,
@@ -131,10 +292,31 @@ export class RealtimeModule {
       this.socket.connect();
     } catch (err) {
       this.isConnecting = false;
+      this.resolveHealthyWaiters(false);
       throw err;
     }
   }
 
+  /**
+   * Tear down the socket without clearing app handlers or room subscriptions.
+   * Used by auth refresh so listeners/rooms survive credential rotation.
+   */
+  private softDisconnect(): void {
+    if (this.socket) {
+      // Prefer removeAllListeners when available (real socket.io); mocks may omit it.
+      if (typeof this.socket.removeAllListeners === "function") {
+        this.socket.removeAllListeners();
+      }
+      this.socket.disconnect();
+      this.socket = undefined;
+    }
+    this.attachedSocketEvents.clear();
+    this.socketEventHandlers.clear();
+    this.socketHealthy = false;
+    this.isConnecting = false;
+    this.resolveHealthyWaiters(false);
+  }
+
   private initHandlers(): void {
     if (!this.socket) return;
     // New socket instance: reset attached event tracking so listeners are re-registered fresh
@@ -143,14 +325,31 @@ export class RealtimeModule {
     this.socket.on("connect", () => {
       this.isConnecting = false;
       this.socketHealthy = true;
+      this.resubscribeRooms();
       this.emitToHandlers("connected", { sid: this.socket?.id });
+      this.resolveHealthyWaiters(true);
     });
     this.socket.on("disconnect", (reason) => {
       this.socketHealthy = false;
+      // Refresh credentials right away so the first reconnect attempt
+      // (>=1s later) already handshakes with a fresh token.
+      void this.refreshSocketAuth();
       this.emitToHandlers("disconnect", { reason });
     });
-    this.socket.on("connect_error", (_error) => {
+    this.socket.on("connect_error", (error) => {
       this.isConnecting = false;
+      // Auth-rejected handshakes (e.g. expired token) land here rather than
+      // in "disconnect" — refresh before the manager's next retry.
+      void this.refreshSocketAuth();
+      this.emitToHandlers("connect_error", error);
+      this.resolveHealthyWaiters(false);
+    });
+    // Manager-level safety net: re-resolve before every scheduled reconnect
+    // attempt (covers timeouts and transport errors that skip the socket
+    // level events above). Mock sockets in tests may not expose `.io`.
+    const manager = (this.socket as { io?: { on?: (ev: string, fn: () => void) => void } }).io;
+    manager?.on?.("reconnect_attempt", () => {
+      void this.refreshSocketAuth();
     });
     // Attach listeners for existing handler events, avoiding duplicates
     for (const event of this.handlerMap.keys()) {
@@ -201,10 +400,14 @@ export class RealtimeModule {
       this.handlerMap.set(event, handlerSet);
     }
     handlerSet.add(handler);
-    if (!this.socket && !this.isConnecting) {
-      await this.connect();
-    }
-    // Attach socket listener for this event (safe to call multiple times)
+    // Registering a handler does NOT open the socket. The socket lifecycle
+    // is driven by room membership (subscribeDoc/subscribeList →
+    // ensureConnected): handlers registered before the first room join are
+    // attached by initHandlers() when that join connects. Connecting here
+    // meant merely CONSTRUCTING the sync engine (which registers its event
+    // handlers up front) booted a socket that nothing would ever close —
+    // against an unreachable host that is an infinite reconnect-poll loop
+    // surviving unmount (the fixture/mock-story socket leak).
     this.attachSocketListener(event);
   }
 
@@ -219,28 +422,61 @@ export class RealtimeModule {
   }
 
   async subscribeDoc(doctype: string, name: string): Promise<void> {
-    if (!this.socket) await this.connect();
+    this.docRooms.set(docRoomKey(doctype, name), { doctype, name });
+    await this.ensureConnected();
     if (this.socket && this.socketHealthy) {
-      this.socket.emit("doc_subscribe", { doctype, name });
+      // Positional args — frappe's handler signature is (doctype, docname).
+      this.socket.emit("doc_subscribe", doctype, name);
     }
   }
 
   unsubscribeDoc(doctype: string, name: string): void {
+    this.docRooms.delete(docRoomKey(doctype, name));
     if (this.socket && this.socketHealthy) {
-      this.socket.emit("doc_unsubscribe", { doctype, name });
+      this.socket.emit("doc_unsubscribe", doctype, name);
     }
+    this.teardownWhenIdle();
   }
 
+  /**
+   * Subscribe to list-level updates for a doctype (`list_update` events).
+   *
+   * `filters` are tracked client-side only: frappe's realtime server has a
+   * single room per doctype (`doctype_subscribe`) and does not support
+   * filtered list rooms.
+   */
   async subscribeList(doctype: string, filters?: Record<string, unknown>): Promise<void> {
-    if (!this.socket) await this.connect();
+    this.listRooms.set(doctype, { doctype, filters });
+    await this.ensureConnected();
     if (this.socket && this.socketHealthy) {
-      this.socket.emit("list_subscribe", { doctype, filters });
+      this.socket.emit("doctype_subscribe", doctype);
     }
   }
+
   unsubscribeList(doctype: string): void {
+    this.listRooms.delete(doctype);
     if (this.socket && this.socketHealthy) {
-      this.socket.emit("list_unsubscribe", { doctype });
+      this.socket.emit("doctype_unsubscribe", doctype);
     }
+    this.teardownWhenIdle();
+  }
+
+  /**
+   * Tears the socket down when the last room is released. Room membership is
+   * the socket's reason to exist: while any subscription holds a room, the
+   * infinite Socket.IO reconnection loop is the reconnect catch-up protocol
+   * working as designed — but once nothing is subscribed, that same loop is
+   * a leak (unmounted consumers leaving a dead-host socket reconnect-polling
+   * forever). Handlers and any re-added rooms survive: the next
+   * subscribeDoc/subscribeList reconnects and re-attaches everything.
+   */
+  private teardownWhenIdle(): void {
+    if (this.docRooms.size > 0 || this.listRooms.size > 0) return;
+    if (!this.socket && !this.isConnecting) return;
+    // Surface the teardown to lifecycle listeners (connection indicators)
+    // before the listeners are detached from the socket.
+    this.emitToHandlers("disconnect", { reason: "idle-teardown" });
+    this.softDisconnect();
   }
 
   isHealthy() {
@@ -248,21 +484,23 @@ export class RealtimeModule {
   }
 
   disconnect(): void {
-    if (this.socket) {
-      this.socket.disconnect();
-      this.socket = undefined;
-    }
+    this.softDisconnect();
     this.handlerMap.clear();
-    this.attachedSocketEvents.clear();
-    this.socketEventHandlers.clear();
-    this.socketHealthy = false;
-    this.isConnecting = false;
+    this.docRooms.clear();
+    this.listRooms.clear();
   }
 
   async updateAuth(auth: AuthConfig) {
     this.config.auth = auth;
-    this.disconnect();
-    if (this.handlerMap.size > 0) {
+    // Reconnect only when room subscriptions exist — rooms are what the
+    // socket serves. Handlers alone (registered eagerly by the sync engine)
+    // don't warrant a socket: an idle module stays idle across credential
+    // rotation, and the next room join connects with the fresh auth.
+    const shouldReconnect = this.docRooms.size > 0 || this.listRooms.size > 0;
+    // Soft disconnect preserves handlers + rooms; hard disconnect() would wipe them
+    // and make the post-check always false (previous production bug).
+    this.softDisconnect();
+    if (shouldReconnect) {
       await this.connect();
     }
   }

package/src/sync/backfill.spec.ts

@@ -532,6 +532,49 @@ describe("BackfillManager", () => {
       expect(mockDb.getDocList).toHaveBeenCalled();
       expect(subscription.testProgressiveCache.docIds.length).toBeGreaterThan(0);
     });
+
+    const mockEndlessCdcPages = () => {
+      // Server always reports truncation with an advancing checkpoint, so
+      // only the page cap can stop the drain.
+      let page = 0;
+      (mockDb.backfill as any).mockImplementation(async () => {
+        page += 1;
+        return {
+          rows: [
+            { name: `cdc-doc-${page}`, modified: new Date(2024, 0, 2, 0, 0, page).toISOString() },
+          ],
+          deleted: [],
+          checkpoint: `2024-01-02 00:00:${String(page).padStart(2, "0")}.000000|cdc-doc-${page}`,
+          has_more: true,
+        };
+      });
+    };
+
+    it("should stop draining at the configured maxPages cap", async () => {
+      const cappedManager = new BackfillManager(mockDb, mockNormalizedCache, {
+        pageSize: 50,
+        maxPages: 2,
+      });
+      const subscription = createMockSubscription({
+        checkpoint: new Date(2024, 0, 1).toISOString(),
+      });
+      mockEndlessCdcPages();
+
+      await cappedManager.backfill(subscription, BackfillReason.Periodic);
+
+      expect(mockDb.backfill).toHaveBeenCalledTimes(2);
+    });
+
+    it("should default the drain cap to 20 pages when maxPages is not set", async () => {
+      const subscription = createMockSubscription({
+        checkpoint: new Date(2024, 0, 1).toISOString(),
+      });
+      mockEndlessCdcPages();
+
+      await backfillManager.backfill(subscription, BackfillReason.Periodic);
+
+      expect(mockDb.backfill).toHaveBeenCalledTimes(20);
+    });
   });
 
   describe("cursor-based fetching", () => {

package/src/sync/backfill.ts

@@ -63,17 +63,26 @@ export interface BackfillOptions {
   pageSize?: number;
   retryDelay?: number;
   batchSize?: number;
+  /**
+   * Max CDC pages drained per incremental backfill when the server reports
+   * has_more (default: 20). Fed from SyncOptions.backfillMaxPages so one
+   * knob bounds both drain paths.
+   */
+  maxPages?: number;
 }
 
 export class BackfillManager {
   private activeBackfills = new Map<string, Promise<void>>();
   private backfillQueue = new Map<string, BackfillReason[]>();
-
-  constructor(
-    private db: DbModule,
-    private normalizedCache: NormalizedCache,
-    private options: BackfillOptions = {},
-  ) {}
+  private db: DbModule;
+  private normalizedCache: NormalizedCache;
+  private options: BackfillOptions;
+
+  constructor(db: DbModule, normalizedCache: NormalizedCache, options: BackfillOptions = {}) {
+    this.db = db;
+    this.normalizedCache = normalizedCache;
+    this.options = options;
+  }
 
   async backfill(subscription: VirtualSubscription, reason: BackfillReason): Promise<void> {
     const subscriptionId = subscription.id;
@@ -250,45 +259,56 @@ export class BackfillManager {
     }
 
     try {
-      // Use CDC backfill API
-      const response = await this.db.backfill({
-        doctype: subscription.query.doctype,
-        fields: subscription.query.fields,
-        filters: subscription.query.filters,
-        modifiedAfter: subscription.checkpoint,
-        limit: this.options.pageSize || 200,
-      });
+      // Drain CDC pages while the server reports truncation (bounded) so
+      // catch-up after a long gap is complete, not one page deep.
+      const maxPages = this.options.maxPages ?? 20;
+      for (let page = 0; page < maxPages; page++) {
+        const response = await this.db.backfill({
+          doctype: subscription.query.doctype,
+          fields: subscription.query.fields,
+          filters: subscription.query.filters,
+          modifiedAfter: subscription.checkpoint,
+          limit: this.options.pageSize || 200,
+        });
 
-      // Process deletions using shared utility
-      if ("deleted" in response && Array.isArray(response.deleted)) {
-        const deletedDocIds = (response.deleted as any[])
-          .filter((deletion) => deletion?.name)
-          .map((deletion) => deletion.name);
+        // Process deletions using shared utility
+        if ("deleted" in response && Array.isArray(response.deleted)) {
+          const deletedDocIds = (response.deleted as any[])
+            .filter((deletion) => deletion?.name)
+            .map((deletion) => deletion.name);
 
-        if (deletedDocIds.length > 0) {
-          subscription.removeDocuments(deletedDocIds, this.normalizedCache);
+          if (deletedDocIds.length > 0) {
+            subscription.removeDocuments(deletedDocIds, this.normalizedCache);
+          }
         }
-      }
 
-      // Process updates and creates
-      for (const doc of response.rows) {
-        const exists = subscription.getProgressiveCache().docIds.includes(doc.name);
-        const matches = matchesFilters(doc as FrappeDoc<FrappeDocData>, subscription.query.filters);
-
-        if (exists && !matches) {
-          // Remove - no longer matches
-          subscription.removeDocuments([doc.name], this.normalizedCache);
-        } else if (!exists && matches) {
-          // Add - now matches (but we don't know where)
-          subscription.needsRehydration = true;
-        } else if (exists) {
-          // Update existing
-          this.normalizedCache.upsert(doc);
+        // Process updates and creates
+        for (const doc of response.rows) {
+          const exists = subscription.getProgressiveCache().docIds.includes(doc.name);
+          const matches = matchesFilters(
+            doc as FrappeDoc<FrappeDocData>,
+            subscription.query.filters,
+          );
+
+          if (exists && !matches) {
+            // Remove - no longer matches
+            subscription.removeDocuments([doc.name], this.normalizedCache);
+          } else if (!exists && matches) {
+            // Add - now matches (but we don't know where)
+            subscription.needsRehydration = true;
+          } else if (exists) {
+            // Update existing
+            this.normalizedCache.upsert(doc);
+          }
         }
-      }
 
-      // Update checkpoint
-      subscription.checkpoint = calculateCheckpointFromDocs(response.rows);
+        // Advance the checkpoint: prefer the server's exact resume cursor
+        // ("ts|name"); fall back to the max modified for older servers.
+        subscription.checkpoint = response.checkpoint ?? calculateCheckpointFromDocs(response.rows);
+
+        const madeProgress = response.rows.length > 0 || (response.deleted?.length ?? 0) > 0;
+        if (!response.has_more || !response.checkpoint || !madeProgress) break;
+      }
     } catch (error) {
       console.error("Incremental backfill failed:", error);
       // Fall back to full refresh