@spooky-sync/core 0.0.1-canary.235 → 0.0.1-canary.237

package/src/modules/data/index.ts

@@ -1121,6 +1121,10 @@ export class DataModule<S extends SchemaStructure> {
     const queryState = this.activeQueries.get(hash);
     if (!queryState) return;
     queryState.hydrated = true; // run-once, even when the remote returns nothing
+    // The registration is enqueued BEFORE the hydrate and can land first; its
+    // `_00_list_ref` set is authoritative and this one-shot must not replace
+    // it. Checked again after the await below for the same reason.
+    if (queryState.serverMembership) return;
     if (rows.length === 0) return;
 
     const epoch = this.local.epoch;
@@ -1131,6 +1135,7 @@ export class DataModule<S extends SchemaStructure> {
     // state; the rebind's re-registration refills it. (saveBatch's own epoch
     // fence usually catches this, but the switch can land between it and here.)
     if (epoch !== this.local.epoch) return;
+    if (queryState.serverMembership) return;
 
     // Prime remoteArray from the hydrated id+version pairs: `materializeRecords`
     // renders from it and it feeds the version dedup. Registration later
@@ -1550,6 +1555,7 @@ export class DataModule<S extends SchemaStructure> {
     // the `_00_list_ref` poll both land here), so it is where "we now know the
     // membership" is latched and where the durable mirror is written.
     queryState.config.membershipKnown = true;
+    queryState.serverMembership = true;
     if (remoteArray.length > 0) {
       // Earns the right to believe a later empty set — that transition is a
       // genuine removal and must be honoured, or removed rows resurrect.
@@ -1635,6 +1641,7 @@ export class DataModule<S extends SchemaStructure> {
         }
       }
       queryState.hydrated = false;
+      queryState.serverMembership = false;
       queryState.syncNotified = false;
       queryState.records = [];
       // Via setQueryStatus (not a bare assignment) so status observers see the

package/src/modules/sync/sync.health.test.ts

@@ -21,7 +21,7 @@ function makeSync(hashes: string[]) {
     trace: () => {},
   };
   const remote: any = { query: vi.fn().mockResolvedValue([true]) };
-  const dataModule: any = { getActiveQueryHashes: () => hashes };
+  const dataModule: any = { getActiveQueryHashes: () => hashes, getQueryByHash: () => undefined };
 
   const sync = new Sp00kySync(
     {} as any,
@@ -33,21 +33,28 @@ function makeSync(hashes: string[]) {
     { degradeAfterConsecutiveFailures: 3 }
   );
 
-  // `refetchListRefForQuery` is what the poll calls per active hash; stub it so
-  // the test controls per-cycle reachability. `poll` invokes the private method.
-  const refetch = vi.fn();
-  (sync as any).refetchListRefForQuery = refetch;
+  // The poll reads every chunk of active hashes in one round trip
+  // (`fetchListRefSnapshots`) and lands each query's snapshot separately
+  // (`applyListRefSnapshot`). Stub both so the test controls per-cycle
+  // reachability. `poll` invokes the private method.
+  const fetch = vi.fn();
+  const apply = vi.fn().mockResolvedValue(false);
+  (sync as any).fetchListRefSnapshots = fetch;
+  (sync as any).applyListRefSnapshot = apply;
+  const snapshotsFor = (hs: string[]) =>
+    new Map(hs.map((h) => [h, { primary: [], subquery: [], rowCount: null }]));
+  fetch.mockImplementation(async (hs: string[]) => snapshotsFor(hs));
   const poll = () => (sync as any).pollListRefForActiveQueries() as Promise<boolean>;
 
-  return { sync, remote, refetch, poll };
+  return { sync, remote, fetch, apply, snapshotsFor, poll };
 }
 
 describe('sync health via idle poll', () => {
   beforeEach(() => vi.clearAllMocks());
 
   it('degrades after N consecutive network-failed poll cycles', async () => {
-    const { sync, refetch, poll } = makeSync(['h1']);
-    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    const { sync, fetch, poll } = makeSync(['h1']);
+    fetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
 
     await poll();
     expect(sync.syncHealth.status).toBe('healthy');
@@ -59,22 +66,22 @@ describe('sync health via idle poll', () => {
   });
 
   it('recovers on the next clean poll cycle — no mutation needed', async () => {
-    const { sync, refetch, poll } = makeSync(['h1']);
-    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    const { sync, fetch, snapshotsFor, poll } = makeSync(['h1']);
+    fetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
     await poll();
     await poll();
     await poll();
     expect(sync.syncHealth.status).toBe('degraded');
 
     // Connectivity returns; a plain idle poll (no user action) clears it.
-    refetch.mockResolvedValue(true);
+    fetch.mockImplementation(async (hs: string[]) => snapshotsFor(hs));
     await poll();
     expect(sync.syncHealth.status).toBe('healthy');
   });
 
   it('does not degrade on application errors (server was reached)', async () => {
-    const { sync, refetch, poll } = makeSync(['h1']);
-    refetch.mockRejectedValue(new Error('Permission denied'));
+    const { sync, fetch, poll } = makeSync(['h1']);
+    fetch.mockRejectedValue(new Error('Permission denied'));
     await poll();
     await poll();
     await poll();
@@ -82,22 +89,24 @@ describe('sync health via idle poll', () => {
     expect(sync.syncHealth.status).toBe('healthy');
   });
 
-  it('counts a mixed cycle (one reachable hash) as reached', async () => {
-    const { sync, refetch, poll } = makeSync(['h1', 'h2']);
+  it('counts a cycle whose round trip answered as reached even when a per-query apply fails', async () => {
+    const { sync, fetch, apply, snapshotsFor, poll } = makeSync(['h1', 'h2']);
     // First degrade via all-network cycles.
-    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    fetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
     await poll();
     await poll();
     await poll();
     expect(sync.syncHealth.status).toBe('degraded');
 
-    // Now one hash succeeds, the other still network-fails → reached → healthy.
-    refetch.mockReset();
-    refetch
+    // The batched read answers (server reached); landing one of the two
+    // snapshots then fails on its own network error → still a reached cycle.
+    fetch.mockImplementation(async (hs: string[]) => snapshotsFor(hs));
+    apply
       .mockResolvedValueOnce(true)
       .mockRejectedValueOnce(new Error(CONNECTION_UNAVAILABLE));
-    await poll();
+    await expect(poll()).resolves.toBe(true);
     expect(sync.syncHealth.status).toBe('healthy');
+    expect(fetch).toHaveBeenLastCalledWith(['h1', 'h2']);
   });
 
   it('probes RETURN true when there are no active queries', async () => {
@@ -115,12 +124,12 @@ describe('sync health via idle poll', () => {
   });
 
   it('leaves everConnected false through a cold-start failure run', async () => {
-    const { sync, refetch, poll } = makeSync(['h1']);
+    const { sync, fetch, poll } = makeSync(['h1']);
     expect(sync.syncHealth.everConnected).toBe(false);
 
     // Server never reached: 3 failed cycles degrade, but this is the initial
     // "connecting" phase, not a lost connection — everConnected stays false.
-    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    fetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
     await poll();
     await poll();
     await poll();
@@ -129,17 +138,16 @@ describe('sync health via idle poll', () => {
   });
 
   it('latches everConnected on the first success and keeps it through a later degrade', async () => {
-    const { sync, refetch, poll } = makeSync(['h1']);
+    const { sync, fetch, poll } = makeSync(['h1']);
 
     // First successful round reaches the server: connecting phase is over.
-    refetch.mockResolvedValue(true);
     await poll();
     expect(sync.syncHealth.status).toBe('healthy');
     expect(sync.syncHealth.everConnected).toBe(true);
 
     // Connection later drops: degraded now reflects a REAL lost connection.
-    refetch.mockReset();
-    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    fetch.mockReset();
+    fetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
     await poll();
     await poll();
     await poll();

package/src/modules/sync/sync.ts

@@ -18,16 +18,34 @@ import type { RecordId, Uuid } from 'surrealdb';
 import {
   applyRecordVersionDiff,
   ArraySyncer,
+  buildListRefBatchSelect,
   buildListRefSelect,
+  buildQueryRowCountBatchSelect,
   buildQueryRowCountSelect,
   buildSubqueryListRefSelect,
   createDiffFromDbOp,
   diffRecordVersionArray,
   listRefPollDelayMs,
+  planListRefPollChunks,
   recordVersionArraysEqual,
   resolveListRefPollInterval,
 } from './utils';
 import { SyncEngine } from './engine';
+
+/** One query's server-side `_00_list_ref` state as read by the poll. */
+interface ListRefSnapshot {
+  primary: RecordVersionArray;
+  subquery: RecordVersionArray;
+  /** `_00_query.rowCount`; `null` when the row was not readable. */
+  rowCount: number | null;
+}
+
+interface ListRefEdgeRow {
+  in: RecordId<string>;
+  out: RecordId<string>;
+  version: number;
+  parent?: unknown;
+}
 import { SyncScheduler } from './scheduler';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
 import type { CacheModule } from '../cache/index';
@@ -187,6 +205,10 @@ export class Sp00kySync<S extends SchemaStructure> {
   // on a quiet page, thanks to the cross-session LIVE-permission gap).
   private listRefIdleStreak: number = 0;
 
+  // `queryHash` -> wall-clock ms of its last poll refresh. Drives the per-cycle
+  // plan (`planListRefPollChunks`): oldest first, large views less often.
+  private listRefPolledAt: Map<string, number> = new Map();
+
   // `${queryHash}:${recordId}` -> consecutive rounds the id has been "still
   // remote" (left the query's list_ref but still exists upstream). Used to
   // distinguish a PERSISTENT view-membership disagreement (the `job:` churn,
@@ -865,6 +887,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       this.listRefPollTimer = setTimeout(async () => {
         if (!this.listRefPollRunning) return;
         let changed = false;
+        const startedAt = Date.now();
         const tick = (async () => {
           changed = await this.pollListRefForActiveQueries();
         })();
@@ -883,10 +906,18 @@ export class Sp00kySync<S extends SchemaStructure> {
           // poll after it lands, not after the backoff has grown to the cap.
           const awaitingMembership = this.dataModule.hasSettledWritesPending();
           this.listRefIdleStreak = changed || awaitingMembership ? 0 : this.listRefIdleStreak + 1;
-          const next = listRefPollDelayMs({
-            idleStreak: this.listRefIdleStreak,
-            baseIntervalMs: this.refSyncIntervalMs,
-          });
+          // Never let the poll take more than half the wall clock: a cycle that
+          // took longer than the cadence (many queries, slow link) waits at
+          // least its own duration before the next one, so it cannot occupy
+          // the remote back-to-back the way the old per-query poll did.
+          const cycleMs = Date.now() - startedAt;
+          const next = Math.max(
+            listRefPollDelayMs({
+              idleStreak: this.listRefIdleStreak,
+              baseIntervalMs: this.refSyncIntervalMs,
+            }),
+            cycleMs
+          );
           schedule(next);
         }
       }, delayMs);
@@ -903,9 +934,10 @@ export class Sp00kySync<S extends SchemaStructure> {
   }
 
   /**
-   * One poll cycle: refetch `_00_list_ref` for every active query. Returns
-   * whether ANY query's remoteArray actually changed — the scheduler uses this
-   * to drive the adaptive idle backoff.
+   * One poll cycle: refetch `_00_list_ref` for the active queries that are due,
+   * one round trip per chunk (see `planListRefPollChunks`). Returns whether ANY
+   * query's remoteArray actually changed — the scheduler uses this to drive the
+   * adaptive idle backoff.
    *
    * Also the ONLY health signal that runs while the page is idle. Sync health is
    * otherwise activity-driven (mutations/registrations via the scheduler,
@@ -930,6 +962,20 @@ export class Sp00kySync<S extends SchemaStructure> {
       }
       return false;
     }
+    const now = Date.now();
+    // Forget queries that went away so the map cannot grow with the session.
+    const active = new Set(hashes);
+    for (const hash of this.listRefPolledAt.keys()) {
+      if (!active.has(hash)) this.listRefPolledAt.delete(hash);
+    }
+    const chunks = planListRefPollChunks(
+      hashes.map((hash) => ({
+        hash,
+        rows: this.dataModule.getQueryByHash(hash)?.config.remoteArray?.length ?? 0,
+        lastPolledAt: this.listRefPolledAt.get(hash) ?? 0,
+      })),
+      { now }
+    );
     let anyChanged = false;
     // `reached` = the server answered at least once this cycle (a success, or an
     // *application* error, which still proves reachability). `firstNetworkErr`
@@ -939,9 +985,10 @@ export class Sp00kySync<S extends SchemaStructure> {
     // fault owned by the registration path, not a reachability signal).
     let reached = false;
     let firstNetworkErr: unknown;
-    for (const hash of hashes) {
+    for (const chunk of chunks) {
+      let snapshots: Map<string, ListRefSnapshot>;
       try {
-        if (await this.refetchListRefForQuery(hash)) anyChanged = true;
+        snapshots = await this.fetchListRefSnapshots(chunk);
         reached = true;
       } catch (err) {
         if (classifySyncError(err) === 'network') {
@@ -952,11 +999,29 @@ export class Sp00kySync<S extends SchemaStructure> {
         this.logger.debug(
           {
             err: (err as Error)?.message ?? err,
-            hash,
+            hashes: chunk,
             Category: 'sp00ky-client::Sp00kySync::pollListRefForActiveQueries',
           },
-          'Per-query list_ref poll failed'
+          'list_ref poll round trip failed'
         );
+        continue;
+      }
+      for (const hash of chunk) {
+        const snapshot = snapshots.get(hash);
+        if (!snapshot) continue;
+        this.listRefPolledAt.set(hash, now);
+        try {
+          if (await this.applyListRefSnapshot(hash, snapshot)) anyChanged = true;
+        } catch (err) {
+          this.logger.debug(
+            {
+              err: (err as Error)?.message ?? err,
+              hash,
+              Category: 'sp00ky-client::Sp00kySync::pollListRefForActiveQueries',
+            },
+            'Per-query list_ref poll apply failed'
+          );
+        }
       }
     }
     // Call the private outcome recorder directly rather than routing through the
@@ -971,24 +1036,128 @@ export class Sp00kySync<S extends SchemaStructure> {
   }
 
   /**
-   * Pull the upstream list_ref entries for `queryHash`, diff them
-   * against the local `remoteArray` cache, sync any added/updated rows
-   * through the SyncEngine, then persist the new remoteArray. This is
-   * the same shape `createRemoteQuery` does for its initial fetch and
-   * what `handleRemoteListRefChange` does per-LIVE-event — we reuse
-   * it on a timer as a fallback for missed LIVE notifications.
+   * The server's current `_00_list_ref` state for a chunk of queries in ONE
+   * round trip: primary edges, subquery-child edges and `_00_query.rowCount`.
+   * Every hash whose query still exists gets an entry (empty arrays and
+   * `rowCount: null` when nothing was readable), so a caller can tell "no
+   * edges" from "not asked". A hash is left out only when the select did not
+   * come back as an array at all — the old per-query code skipped the apply in
+   * that case too, since a non-array is not a membership set.
+   *
+   * Guarded against a batch that silently matches nothing: if the select
+   * returned no edge at all while the client holds edges for a query the
+   * server still reports rows for, the batch is not trusted and the chunk is
+   * re-read one query at a time with the single-query select. An empty set
+   * taken at face value would be recorded as the removal of every row.
+   */
+  private async fetchListRefSnapshots(hashes: string[]): Promise<Map<string, ListRefSnapshot>> {
+    const listRefTbl = this.listRefTable();
+    const ids: RecordId<string>[] = [];
+    const hashById = new Map<string, string>();
+    const out = new Map<string, ListRefSnapshot>();
+    for (const hash of hashes) {
+      const queryState = this.dataModule.getQueryByHash(hash);
+      if (!queryState) continue;
+      ids.push(queryState.config.id);
+      hashById.set(encodeRecordId(queryState.config.id), hash);
+    }
+    if (ids.length === 0) return out;
+    if (ids.length === 1) {
+      const hash = hashById.get(encodeRecordId(ids[0]))!;
+      const single = await this.fetchListRefSnapshot(ids[0]);
+      if (single) out.set(hash, single);
+      return out;
+    }
+    const [edges, counts] = await this.remote.query<
+      [ListRefEdgeRow[] | null, ({ id?: RecordId<string>; rowCount?: number | null } | null)[] | null]
+    >(`${buildListRefBatchSelect(listRefTbl)};\n${buildQueryRowCountBatchSelect()}`, { ins: ids });
+    if (!Array.isArray(edges)) return out;
+    for (const hash of hashById.values()) {
+      out.set(hash, { primary: [], subquery: [], rowCount: null });
+    }
+    for (const row of edges) {
+      const hash = hashById.get(encodeRecordId(row.in));
+      if (!hash) continue;
+      const snapshot = out.get(hash)!;
+      const pair: [string, number] = [encodeRecordId(row.out), row.version];
+      if (row.parent == null) snapshot.primary.push(pair);
+      else snapshot.subquery.push(pair);
+    }
+    for (const count of Array.isArray(counts) ? counts : []) {
+      if (!count || !count.id) continue;
+      const hash = hashById.get(encodeRecordId(count.id));
+      if (!hash) continue;
+      out.get(hash)!.rowCount = typeof count.rowCount === 'number' ? count.rowCount : null;
+    }
+    const suspect =
+      edges.length === 0 &&
+      Array.from(out.entries()).some(([hash, snapshot]) => {
+        const held = this.dataModule.getQueryByHash(hash)?.config.remoteArray?.length ?? 0;
+        return held > 0 && (snapshot.rowCount ?? 0) > 0;
+      });
+    if (suspect) {
+      this.logger.warn(
+        { hashes, Category: 'sp00ky-client::Sp00kySync::fetchListRefSnapshots' },
+        'Batched list_ref select returned no edges for queries that hold rows; re-reading one query at a time'
+      );
+      for (const hash of Array.from(out.keys())) {
+        const queryState = this.dataModule.getQueryByHash(hash);
+        if (!queryState) {
+          out.delete(hash);
+          continue;
+        }
+        const single = await this.fetchListRefSnapshot(queryState.config.id);
+        if (single) out.set(hash, single);
+        else out.delete(hash);
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Single-query form of {@link fetchListRefSnapshots}: the selects the
+   * registration path has always used, in one statement batch. `null` when
+   * the primary select did not come back as an array.
+   */
+  private async fetchListRefSnapshot(id: RecordId<string>): Promise<ListRefSnapshot | null> {
+    const listRefTbl = this.listRefTable();
+    const [items, serverRowCount, children] = await this.remote.query<
+      [
+        { out: RecordId<string>; version: number }[] | null,
+        number | null,
+        { out: RecordId<string>; version: number }[] | null,
+      ]
+    >(
+      `${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()};\n${buildSubqueryListRefSelect(listRefTbl)}`,
+      { in: id }
+    );
+    if (!Array.isArray(items)) return null;
+    const toPairs = (rows: { out: RecordId<string>; version: number }[] | null): RecordVersionArray =>
+      Array.isArray(rows) ? rows.map((item) => [encodeRecordId(item.out), item.version]) : [];
+    return {
+      primary: toPairs(items),
+      subquery: toPairs(children),
+      rowCount: typeof serverRowCount === 'number' ? serverRowCount : null,
+    };
+  }
+
+  /**
+   * Land one poll snapshot for `queryHash`: diff the server's edges against the
+   * cached `remoteArray`, sync any added/updated rows through the SyncEngine,
+   * persist the new remoteArray and converge the subquery children. This is
+   * the same shape `createRemoteQuery` does for its initial fetch and what
+   * `handleRemoteListRefChange` does per-LIVE-event — we reuse it on a timer
+   * as a fallback for missed LIVE notifications. Returns whether membership
+   * changed.
    */
-  private async refetchListRefForQuery(queryHash: string): Promise<boolean> {
+  private async applyListRefSnapshot(
+    queryHash: string,
+    snapshot: ListRefSnapshot
+  ): Promise<boolean> {
     const queryState = this.dataModule.getQueryByHash(queryHash);
     if (!queryState) return false;
-    const listRefTbl = this.listRefTable();
-    const [items, serverRowCount] = await this.remote.query<
-      [{ out: RecordId<string>; version: number }[], number | null]
-    >(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()}`, {
-      in: queryState.config.id,
-    });
-    if (!Array.isArray(items)) return false;
-    const fresh: RecordVersionArray = items.map((item) => [encodeRecordId(item.out), item.version]);
+    const fresh = snapshot.primary;
+    const serverRowCount = snapshot.rowCount;
     // Capture which ids LEFT the query's window (present in the cached
     // remoteArray, absent from `fresh`) BEFORE we overwrite remoteArray — these
     // are cross-window deletes (or rows that scrolled out). They drive the
@@ -1026,7 +1195,7 @@ export class Sp00kySync<S extends SchemaStructure> {
         {
           err: (err as Error)?.message ?? err,
           queryHash,
-          Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+          Category: 'sp00ky-client::Sp00kySync::applyListRefSnapshot',
         },
         'syncQuery failed during poll'
       );
@@ -1039,12 +1208,12 @@ export class Sp00kySync<S extends SchemaStructure> {
     // Cross-session fallback for `.related()` child rows: the LIVE-permission
     // gap can drop child-edge notifications, so converge their bodies on the
     // poll too (idempotent — no-op when nothing changed).
-    await this.syncSubqueryChildren(queryHash).catch((err) => {
+    await this.applySubqueryChildren(queryHash, snapshot.subquery).catch((err) => {
       this.logger.info(
         {
           err: (err as Error)?.message ?? err,
           queryHash,
-          Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+          Category: 'sp00ky-client::Sp00kySync::applyListRefSnapshot',
         },
         'Subquery child sync failed during poll'
       );
@@ -1062,7 +1231,7 @@ export class Sp00kySync<S extends SchemaStructure> {
           {
             err: (err as Error)?.message ?? err,
             queryHash,
-            Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery',
+            Category: 'sp00ky-client::Sp00kySync::applyListRefSnapshot',
           },
           'notifyQuerySynced failed during poll-removal re-render'
         );
@@ -2054,6 +2223,18 @@ export class Sp00kySync<S extends SchemaStructure> {
     if (!Array.isArray(items)) return;
 
     const fresh: RecordVersionArray = items.map((item) => [encodeRecordId(item.out), item.version]);
+    await this.applySubqueryChildren(queryHash, fresh);
+  }
+
+  /**
+   * Converge a `.related()` query's child bodies onto `fresh` (the server's
+   * current child edges). Shared by the registration path above and the poll,
+   * which reads the child edges in its batched round trip. See
+   * {@link syncSubqueryChildren} for the deletion-safety rules.
+   */
+  private async applySubqueryChildren(queryHash: string, fresh: RecordVersionArray): Promise<void> {
+    const queryState = this.dataModule.getQueryByHash(queryHash);
+    if (!queryState) return;
     const prev = queryState.config.subqueryRemoteArray ?? [];
     if (recordVersionArraysEqual(fresh, prev)) return; // idempotent: nothing new
 

package/src/modules/sync/utils.test.ts

@@ -9,6 +9,9 @@ import {
   DEFAULT_LIST_REF_POLL_INTERVAL_MS,
   buildListRefSelect,
   buildSubqueryListRefSelect,
+  buildListRefBatchSelect,
+  buildQueryRowCountBatchSelect,
+  planListRefPollChunks,
   nextPollDelayMs,
   listRefPollDelayMs,
   LIST_REF_POLL_MAX_INTERVAL_MS,
@@ -576,3 +579,53 @@ describe('recordVersionArraysEqual', () => {
     expect(recordVersionArraysEqual([], [])).toBe(true);
   });
 });
+
+describe('list_ref poll batching', () => {
+  it('reads many queries in one statement and their rowCounts keyed by id', () => {
+    expect(buildListRefBatchSelect('_00_list_ref_user_abc')).toBe(
+      'SELECT in, out, version, parent FROM _00_list_ref_user_abc WHERE in IN $ins'
+    );
+    expect(buildQueryRowCountBatchSelect()).toBe(
+      'SELECT VALUE { id: id, rowCount: rowCount } FROM $ins'
+    );
+  });
+
+  it('packs due queries oldest-first under the row budget', () => {
+    const chunks = planListRefPollChunks(
+      [
+        { hash: 'a', rows: 600, lastPolledAt: 300 },
+        { hash: 'b', rows: 600, lastPolledAt: 100 },
+        { hash: 'c', rows: 0, lastPolledAt: 0 },
+        { hash: 'd', rows: 900, lastPolledAt: 200 },
+      ],
+      { now: 1_000, rowBudget: 1_400 }
+    );
+    // c (never polled) first, then b, d, a by age; d does not fit next to b.
+    expect(chunks).toEqual([['c', 'b'], ['d'], ['a']]);
+  });
+
+  it('never splits below one query and always refreshes a lone huge view', () => {
+    expect(
+      planListRefPollChunks([{ hash: 'big', rows: 10_000, lastPolledAt: 0 }], {
+        now: 100_000,
+        rowBudget: 100,
+      })
+    ).toEqual([['big']]);
+  });
+
+  it('defers large views until their minimum age has passed', () => {
+    const large = { hash: 'large', rows: 5_000, lastPolledAt: 990_000 };
+    const small = { hash: 'small', rows: 10, lastPolledAt: 990_000 };
+    expect(
+      planListRefPollChunks([large, small], { now: 1_000_000, largeViewRows: 1_000, largeViewMinAgeMs: 15_000 })
+    ).toEqual([['small']]);
+    expect(
+      planListRefPollChunks([large, small], { now: 1_006_000, largeViewRows: 1_000, largeViewMinAgeMs: 15_000 })
+    // Same age: hash order breaks the tie, and the large view fills its own chunk.
+    ).toEqual([['large'], ['small']]);
+  });
+
+  it('returns no chunks when nothing is due', () => {
+    expect(planListRefPollChunks([], { now: 1 })).toEqual([]);
+  });
+});

package/src/modules/sync/utils.ts

@@ -223,6 +223,83 @@ export function buildSubqueryListRefSelect(table: string): string {
   return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
 }
 
+/**
+ * One round trip for the edges of MANY queries: primary and subquery rows
+ * together, split client-side on `parent`. Replaces two selects per query per
+ * poll tick, which on a page with 20+ live queries was ~50 serialized round
+ * trips per cycle and kept the remote busy full-time.
+ */
+export function buildListRefBatchSelect(table: string): string {
+  return `SELECT in, out, version, parent FROM ${table} WHERE in IN $ins`;
+}
+
+/**
+ * `rowCount` for many `_00_query` rows at once, keyed by id so the caller does
+ * not depend on the array order. Same semantics as
+ * {@link buildQueryRowCountSelect}: a row the session cannot read comes back
+ * without an id and must be treated as "unknown".
+ */
+export function buildQueryRowCountBatchSelect(): string {
+  return 'SELECT VALUE { id: id, rowCount: rowCount } FROM $ins';
+}
+
+/** Known edges one poll round trip may carry before the cycle is split. */
+export const LIST_REF_POLL_ROW_BUDGET = 1_500;
+/** A view at or past this many edges is "large": it rides on LIVE and is only
+ *  re-polled every {@link LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS}. */
+export const LIST_REF_POLL_LARGE_VIEW_ROWS = 1_000;
+export const LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS = 15_000;
+
+export interface ListRefPollCandidate {
+  hash: string;
+  /** Edges the client currently holds for the query (`remoteArray.length`). */
+  rows: number;
+  /** When the query was last refreshed by the poll; `0` = never. */
+  lastPolledAt: number;
+}
+
+/**
+ * Split the active queries into the round trips of one poll cycle.
+ *
+ * Every query that is due is refreshed once per cycle, oldest refresh first,
+ * packed greedily into chunks of at most `rowBudget` known edges so one
+ * response never carries a whole page's worth of ids at once. A view with
+ * `largeViewRows` or more edges is only due once `largeViewMinAgeMs` has
+ * passed since its last refresh (LIVE remains its primary path); a chunk
+ * always holds at least one query, so a single huge view still refreshes.
+ */
+export function planListRefPollChunks(
+  candidates: ListRefPollCandidate[],
+  opts: { now: number; rowBudget?: number; largeViewRows?: number; largeViewMinAgeMs?: number }
+): string[][] {
+  const {
+    now,
+    rowBudget = LIST_REF_POLL_ROW_BUDGET,
+    largeViewRows = LIST_REF_POLL_LARGE_VIEW_ROWS,
+    largeViewMinAgeMs = LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS,
+  } = opts;
+  const due = candidates
+    .filter((c) => c.rows < largeViewRows || now - c.lastPolledAt >= largeViewMinAgeMs)
+    .sort(
+      (a, b) => a.lastPolledAt - b.lastPolledAt || (a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0)
+    );
+  const chunks: string[][] = [];
+  let current: string[] = [];
+  let currentRows = 0;
+  for (const c of due) {
+    const cost = Math.max(1, c.rows);
+    if (current.length > 0 && currentRows + cost > rowBudget) {
+      chunks.push(current);
+      current = [];
+      currentRows = 0;
+    }
+    current.push(c.hash);
+    currentRows += cost;
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+
 /**
  * Resolve the effective list-ref poll interval. Negative or zero
  * values fall back to the default — accepting them would either