cry-synced-db-client 0.1.145 → 0.1.147

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 ## Unreleased
 
+### Auto-eviction co-located with sync — one round-trip total
+
+When `evictStaleRecordsEveryHrs > 0` and the interval has elapsed, the
+scope-exit eviction queries now ride along on sync's existing
+`findNewerManyStream` call instead of issuing a separate `findNewerMany`
+afterwards. Saves one server round-trip per "due" sync.
+
+- `SyncedDb.sync()` pre-computes the eviction plan (Dexie scan + spec
+  build) before invoking `SyncEngine.sync()`, hands the spec list as
+  `extras`, and applies the deletes in `finally`. The old post-sync
+  `maybeAutoEvict()` call is gone.
+- New `SyncExtras` type on `I_SyncEngine.sync(calledFrom?, extras?)`:
+  appends caller-supplied `findNewerMany` specs (each tagged with a
+  unique `specId`) to the same streamed call. Chunks for those specs
+  are routed via `extras.onChunk(specId, items)` and never enter
+  positive-sync conflict resolution.
+- Sync-lifecycle callbacks (`onSyncStart`/`onSyncEnd`/`onServerSyncStart`/
+  `onServerSyncEnd`/`onSyncProgress`/`onFindNewerManyCall`/
+  `onFindNewerManyResult`) are deliberately scoped to positive sync —
+  they do **not** count or report scope-exit specs. Eviction lifecycle
+  stays observable via `onEvictionStart` / `onEviction`.
+- Manual `evictOutOfScopeRecordsAll("manual")` keeps the standalone
+  `findNewerMany` round-trip behavior unchanged.
+- Internal refactor: `evictOutOfScopeRecordsAll` split into
+  `_collectScopeExitPlan` (phase 1), `_applyScopeExitChunkToPlan`
+  (server result handling, shared with sync's onChunk dispatch), and
+  `_applyScopeExitPlan` (phase 3 — deletes + EvictionInfo + onEviction).
+
+### `GetNewerSpec.specId` — disambiguate duplicate-collection specs
+
+New optional field on `GetNewerSpec` mirrors the cry-db ≥ 2.4.32 API
+addition: when set, results for that spec are keyed by `specId` in
+`findNewerMany` responses (and emitted as the third `onChunk` arg in
+`findNewerManyStream`) instead of `collection`. Lets a single batched
+request carry multiple specs against the same collection without
+`Record<key, items[]>` collisions.
+
+- Backwards compatible — specs without `specId` keep collection-keyed
+  behavior.
+- `RestProxy.parseStreamingResponse` learned a new wire frame type
+  `0x02`: `[type:1=0x02][nameLen:2][name:N][specIdLen:2][specId:M][dataLen:4][payload]`,
+  emitted by rdb2 when any spec sets `specId`. Type `0x01` unchanged
+  for back-compat.
+- All mocks (`MockRestInterfaceFake`, `MockRestInterfaceReal`,
+  `MockRestInterface`) honor `specId` in both the non-streaming and
+  streaming variants.
+
+### Eviction batched via `findNewerMany` + `onEvictionStart` lifecycle
+
+- `evictOutOfScopeRecordsAll`'s server-assisted pass collapses N
+  per-collection round-trips into **one** `findNewerMany` call, with
+  per-(collection × CHUNK_SIZE-id-batch) specs disambiguated via
+  `specId = "<collection>#<chunkIndex>"`. `findServerSideScopeExits`
+  (single-collection helper) similarly bundles all chunks into one call.
+- New `onEvictionStart(info: EvictionStartInfo)` callback fires before
+  phase 1 with `{ trigger, collectionCount, collections[] }` so consumers
+  see a debug breadcrumb of which collections will be scanned.
+- Extended `EvictionCollectionInfo` with `localEvictedCount`,
+  `serverEvictedCount`, `serverCandidateCount` — split by source so
+  debug output distinguishes "cached state failed" from "server
+  reported out of scope".
+- Extended `EvictionInfo` with `totalLocalEvicted`, `totalServerEvicted`,
+  `totalServerCandidates`, `serverRounds`, `serverFailed` — aggregate
+  counters for the batched pass.
+
+  **Type addition (non-breaking for producers, possibly breaking for
+  consumers constructing literals):** the new fields are required on
+  the public `EvictionCollectionInfo` / `EvictionInfo` types since the
+  library always populates them. Downstream code that constructs mock
+  literals (e.g. tests) needs the new fields.
+
 ### Fix: filtered-sync tombstone (scope-exit from other writers)
 
 When a collection has `syncConfig.query` (e.g. `{ status: { $ne: "obsolete" } }`)
@@ -108,6 +179,36 @@ Signature is identical. No other callback changes.
   - Noop when offline or on writeOnly collections.
   - Ignored on `find` / `findOne` (use `referToServer` there).
 
+## 0.1.146 (2026-04-25)
+
+### Fix: INITIAL SYNC re-fetched whole dataset on every reload (cursor race)
+
+`syncMetaCache` was populated lazily inside `loadCollectionToInMem` — one
+collection at a time, only after that collection's records finished hydrating
+into in-memory state. When `ConnectionManager.tryGoOnline` fired
+`sync("INITIAL SYNC")` on WS connect (or `setSyncOnlyTheseCollections`
+expanded the allowed set under a fresh login), the sync engine read
+`syncMetaCache.get(collection)?.lastSyncTs` for each collection — and for
+collections whose hydration hadn't completed yet, it found nothing and fell
+back to `timestamp: 0` (`SyncEngine.ts:94`). The server then returned every
+matching row since epoch, not a delta.
+
+In one observed reproducer with 62 sync'd collections, 58 of them arrived at
+the server with `timestamp: 0` and the server replied with 60 131 rows on a
+session that already had 58 745 rows cached locally — i.e. ~full re-fetch
+every reload, regardless of how recently the client had synced.
+
+`init()` now eagerly preloads sync cursors for every registered collection
+into `syncMetaCache` before `connectionManager.startTimers()` runs, via a
+parallel fan-out of `getSyncMeta` reads. Cursor cache availability is
+decoupled from in-mem record hydration: a sync triggered the moment WS comes
+up reads a fully populated cache, regardless of where hydration is. One Dexie
+point-lookup per registered collection — cheap.
+
+The lazy populate inside `loadCollectionToInMem` is retained as a defensive
+overwrite for collections registered after init (e.g. via dynamic
+`addCollection`).
+
 ## 0.1.145 (2026-04-25)
 
 ### Fix: `onSyncProgress` back-track during initial sync

package/dist/index.js

@@ -2435,8 +2435,13 @@ var _SyncEngine = class _SyncEngine {
   /**
    * Execute full sync cycle.
    * Called by SyncedDb which handles locking.
+   *
+   * `extras` lets the caller append additional `findNewerMany` specs
+   * (each with a unique `specId`) onto the same streamed call. Chunks
+   * for those specs are routed via `extras.onChunk(specId, items)` and
+   * never enter the positive-sync processing path.
    */
-  async sync(calledFrom) {
+  async sync(calledFrom, extras) {
     var _a, _b;
     const startTime = Date.now();
     let receivedCount = 0;
@@ -2481,10 +2486,15 @@ var _SyncEngine = class _SyncEngine {
       }
       try {
         const completedCollections = /* @__PURE__ */ new Set();
+        const allSpecs = extras && extras.specs.length > 0 ? [...syncSpecs, ...extras.specs] : syncSpecs;
         await this.deps.withSyncTimeout(
           this.restInterface.findNewerManyStream(
-            syncSpecs,
-            async (collection, items) => {
+            allSpecs,
+            async (collection, items, specId) => {
+              if (specId !== void 0) {
+                if (extras) extras.onChunk(specId, items);
+                return;
+              }
               const config = configMap.get(collection);
               if (!config) return;
               const state = collectionState.get(collection);
@@ -3521,6 +3531,7 @@ var _SyncedDb = class _SyncedDb {
     this.onWsNotification = config.onWsNotification;
     this.onCrossTabSync = config.onCrossTabSync;
     this.onWakeSync = config.onWakeSync;
+    this.onEvictionStart = config.onEvictionStart;
     this.onEviction = config.onEviction;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     for (const col of config.collections) {
@@ -3801,6 +3812,7 @@ var _SyncedDb = class _SyncedDb {
       }
     }
     await this.pendingChanges.recoverPendingWrites();
+    await this.preloadAllSyncMetas();
     const allowedColls = [...this.collections.keys()].filter((n) => this.isSyncAllowed(n));
     await this.loadCollectionsToInMem(allowedColls, "init");
     this.leaderElection.init();
@@ -4476,8 +4488,26 @@ var _SyncedDb = class _SyncedDb {
       }
       this.syncing = true;
       this.crossTabSync.startServerSync();
+      let evictionPlan;
+      let evictionServerFailed = false;
+      if (await this._isAutoEvictionDue()) {
+        try {
+          evictionPlan = await this._collectScopeExitPlan("auto");
+        } catch (err) {
+          console.error(
+            "[evict] phase 1 failed (skipping bundled eviction):",
+            err
+          );
+        }
+      }
+      const evictionExtras = evictionPlan && evictionPlan.specs.length > 0 ? {
+        specs: evictionPlan.specs,
+        onChunk: (specId, items) => {
+          this._applyScopeExitChunkToPlan(evictionPlan, specId, items);
+        }
+      } : void 0;
       try {
-        await this.syncEngine.sync(calledFrom);
+        await this.syncEngine.sync(calledFrom, evictionExtras);
         if (!this.syncOnlyCollections) {
           const now = /* @__PURE__ */ new Date();
           if (!this._lastFullSyncDate) {
@@ -4489,14 +4519,24 @@ var _SyncedDb = class _SyncedDb {
             console.error("Failed to persist lastFullSync:", err);
           });
         }
+      } catch (err) {
+        if (evictionExtras) evictionServerFailed = true;
+        throw err;
       } finally {
         this.syncing = false;
         this.crossTabSync.endServerSync();
         await this.processQueuedWsUpdates();
-        try {
-          await this.maybeAutoEvict();
-        } catch (err) {
-          console.error("Auto-eviction failed:", err);
+        if (evictionPlan) {
+          try {
+            await this._applyScopeExitPlan(
+              evictionPlan,
+              evictionServerFailed,
+              evictionExtras ? 1 : 0
+            );
+            await this._persistEvictionTimestamp();
+          } catch (err) {
+            console.error("[evict] phase 3 failed:", err);
+          }
         }
       }
     } finally {
@@ -4725,7 +4765,15 @@ var _SyncedDb = class _SyncedDb {
     const syncQuery = (_a = config.syncConfig) == null ? void 0 : _a.query;
     const query = typeof syncQuery === "function" ? syncQuery() : syncQuery;
     if (!query) {
-      return { collection, evictedCount: 0, dirtySkipped: 0, scannedCount: 0 };
+      return {
+        collection,
+        evictedCount: 0,
+        localEvictedCount: 0,
+        serverEvictedCount: 0,
+        dirtySkipped: 0,
+        scannedCount: 0,
+        serverCandidateCount: 0
+      };
     }
     await this.pendingChanges.flushForCollection(collection);
     const dirtyItems = await this.dexieDb.getDirty(collection);
@@ -4754,6 +4802,8 @@ var _SyncedDb = class _SyncedDb {
         }
       }
     );
+    const localEvictedCount = evictIds.length;
+    let serverEvictedCount = 0;
     if (serverAssisted && serverCandidateIds.length > 0) {
       let scopeExitTimestamp;
       const lookbehindMs = opts == null ? void 0 : opts.outOfWindowLookbehindMs;
@@ -4773,6 +4823,7 @@ var _SyncedDb = class _SyncedDb {
           scopeExitTimestamp
         );
         for (const id of serverExits) evictIds.push(id);
+        serverEvictedCount = serverExits.length;
       } catch (err) {
         console.error(
           `[evict] server-assisted pass failed for ${collection} (proceeding with local-only):`,
@@ -4791,7 +4842,15 @@ var _SyncedDb = class _SyncedDb {
       }
       this.crossTabSync.broadcastReload([collection]);
     }
-    return { collection, evictedCount: evictIds.length, dirtySkipped, scannedCount };
+    return {
+      collection,
+      evictedCount: evictIds.length,
+      localEvictedCount,
+      serverEvictedCount,
+      dirtySkipped,
+      scannedCount,
+      serverCandidateCount: serverCandidateIds.length
+    };
   }
   /**
    * Ask the server which of the given IDs no longer match the positive
@@ -4800,9 +4859,10 @@ var _SyncedDb = class _SyncedDb {
    * out of scope by other writers that the filtered delta feed would
    * never report.
    *
-   * Chunks `candidateIds` into `$in`-sized batches to keep the request
-   * payload bounded. Uses `project: { _id: 1 }` to keep the response
-   * payload minimal.
+   * Bundles all id chunks into a single `findNewerMany` call, keyed by
+   * `specId = "<chunkIndex>"` so multiple specs against the same
+   * collection don't collide on the response. One round-trip regardless
+   * of `candidateIds.length`.
    *
    * @param timestamp - `findNewer` timestamp cursor. Only records with
    *   `_ts > timestamp` are examined. Caller decides the window (usually
@@ -4812,24 +4872,31 @@ var _SyncedDb = class _SyncedDb {
    *   `NOT query`). These are candidates for local-only eviction.
    */
   async findServerSideScopeExits(collection, positiveQuery, candidateIds, timestamp) {
+    var _a;
+    if (candidateIds.length === 0) return [];
     const CHUNK_SIZE = 500;
-    const scopeExits = [];
     const negated = { $nor: [positiveQuery] };
+    const specs = [];
     for (let i = 0; i < candidateIds.length; i += CHUNK_SIZE) {
       const chunk = candidateIds.slice(i, i + CHUNK_SIZE);
-      const scopedNegation = {
-        $and: [negated, { _id: { $in: chunk } }]
-      };
-      const results = await this.connectionManager.withRestTimeout(
-        this.restInterface.findNewer(
-          collection,
-          timestamp,
-          scopedNegation,
-          { project: { _id: 1 } }
-        ),
-        "evictOutOfScopeRecords.serverAssisted"
-      );
-      for (const item of results) {
+      specs.push({
+        collection,
+        timestamp,
+        query: {
+          $and: [negated, { _id: { $in: chunk } }]
+        },
+        opts: { project: { _id: 1 } },
+        specId: `${collection}#${i / CHUNK_SIZE}`
+      });
+    }
+    const results = await this.connectionManager.withRestTimeout(
+      this.restInterface.findNewerMany(specs),
+      "evictOutOfScopeRecords.serverAssisted"
+    );
+    const scopeExits = [];
+    for (const spec of specs) {
+      const items = (_a = results[spec.specId]) != null ? _a : [];
+      for (const item of items) {
         const id = item._id;
         if (id !== void 0) scopeExits.push(String(id));
       }
@@ -4839,37 +4906,231 @@ var _SyncedDb = class _SyncedDb {
   /**
    * Evict out-of-scope records for all collections.
    * Skips writeOnly and collections without syncConfig.query.
-   * Fires onEviction callback.
+   * Fires onEvictionStart before phase 1 and onEviction at the end.
+   *
+   * Three phases:
+   *  1. Local pass per eligible collection — Dexie scan, partition into
+   *     locally-failing (immediate evict candidates) vs locally-matching
+   *     (server-check candidates). Dirty records are skipped.
+   *  2. Server-assisted pass — a single `findNewerMany` call carrying
+   *     one spec per (collection × CHUNK_SIZE-id-batch), disambiguated
+   *     via `specId`. Collapses the prior N-per-collection round-trips
+   *     into one server round-trip total.
+   *  3. Apply evictions per collection (Dexie + in-mem deletes,
+   *     cross-tab reload broadcast).
+   *
+   * Server-assisted is automatic when the collection is online and not
+   * writeOnly — same default as `evictOutOfScopeRecords`. On batch
+   * failure, local evictions are still applied; remaining server rounds
+   * are skipped (logged, not thrown), and `serverFailed=true` is reported
+   * on the EvictionInfo.
    */
   async evictOutOfScopeRecordsAll(trigger = "manual") {
-    var _a;
+    const plan = await this._collectScopeExitPlan(trigger);
+    let serverFailed = false;
+    let serverRounds = 0;
+    if (plan.specs.length > 0) {
+      try {
+        const results = await this.connectionManager.withRestTimeout(
+          this.restInterface.findNewerMany(plan.specs),
+          "evictOutOfScopeRecordsAll.serverAssisted"
+        );
+        serverRounds = 1;
+        for (const [specId, items] of Object.entries(results)) {
+          this._applyScopeExitChunkToPlan(plan, specId, items);
+        }
+      } catch (err) {
+        serverFailed = true;
+        console.error(
+          "[evict] server-assisted batch failed (proceeding with local-only):",
+          err
+        );
+      }
+    }
+    return this._applyScopeExitPlan(plan, serverFailed, serverRounds);
+  }
+  /**
+   * Phase 1 of eviction: pre-filter eligible collections, fire
+   * `onEvictionStart`, scan Dexie per collection to partition records
+   * into local-fail (immediate evict) vs server-check (candidates), and
+   * build the `findNewerMany` spec list (each spec tagged with a unique
+   * `specId`).
+   *
+   * Returns a plan object that can be:
+   *  - Sent to the server as a standalone `findNewerMany` call (manual eviction),
+   *  - Bundled into sync's `findNewerManyStream` via `SyncExtras` (auto eviction),
+   *  - Or applied with empty server results when offline/writeOnly.
+   *
+   * Always fires `onEvictionStart` (even with collectionCount=0) so the
+   * callback is a reliable lifecycle marker.
+   */
+  async _collectScopeExitPlan(trigger) {
+    var _a, _b, _c;
     const startTime = Date.now();
-    const collectionResults = [];
-    let totalEvicted = 0;
+    const eligible = [];
     for (const [name, config] of this.collections) {
       if (config.writeOnly) continue;
       const syncQuery = (_a = config.syncConfig) == null ? void 0 : _a.query;
       const query = typeof syncQuery === "function" ? syncQuery() : syncQuery;
       if (!query) continue;
-      const result = await this.evictOutOfScopeRecords(name);
-      collectionResults.push(result);
-      totalEvicted += result.evictedCount;
+      eligible.push({ name, config, query });
+    }
+    this.safeCallback(this.onEvictionStart, {
+      trigger,
+      collectionCount: eligible.length,
+      collections: eligible.map((e) => e.name)
+    });
+    const pending = [];
+    let totalServerCandidates = 0;
+    for (const { name, config, query } of eligible) {
+      await this.pendingChanges.flushForCollection(name);
+      const dirtyItems = await this.dexieDb.getDirty(name);
+      const dirtyIds = new Set(dirtyItems.map((d) => String(d._id)));
+      const serverAssisted = !config.writeOnly && this.connectionManager.isOnline();
+      let scannedCount = 0;
+      let dirtySkipped = 0;
+      const evictIds = [];
+      const serverCandidateIds = [];
+      await this.dexieDb.forEachBatch(
+        name,
+        2e3,
+        async (items) => {
+          for (const item of items) {
+            scannedCount++;
+            const id = String(item._id);
+            if (dirtyIds.has(id)) {
+              dirtySkipped++;
+              continue;
+            }
+            if (!matchesQuery(item, query)) {
+              evictIds.push(id);
+            } else if (serverAssisted) {
+              serverCandidateIds.push(id);
+            }
+          }
+        }
+      );
+      totalServerCandidates += serverCandidateIds.length;
+      pending.push({
+        collection: name,
+        config,
+        query,
+        timestamp: (_c = (_b = this.syncMetaCache.get(name)) == null ? void 0 : _b.lastSyncTs) != null ? _c : 0,
+        evictIds,
+        localEvictedCount: evictIds.length,
+        serverEvictedCount: 0,
+        serverCandidateIds,
+        dirtySkipped,
+        scannedCount,
+        serverAssisted
+      });
+    }
+    const CHUNK_SIZE = 500;
+    const specs = [];
+    const ownersBySpecId = /* @__PURE__ */ new Map();
+    for (const p of pending) {
+      if (!p.serverAssisted) continue;
+      for (let i = 0; i < p.serverCandidateIds.length; i += CHUNK_SIZE) {
+        const chunk = p.serverCandidateIds.slice(i, i + CHUNK_SIZE);
+        const specId = `${p.collection}#${i / CHUNK_SIZE}`;
+        specs.push({
+          collection: p.collection,
+          timestamp: p.timestamp,
+          query: {
+            $and: [{ $nor: [p.query] }, { _id: { $in: chunk } }]
+          },
+          opts: { project: { _id: 1 } },
+          specId
+        });
+        ownersBySpecId.set(specId, p);
+      }
+    }
+    return {
+      startTime,
+      trigger,
+      pending,
+      specs,
+      ownersBySpecId,
+      totalServerCandidates
+    };
+  }
+  /**
+   * Append server-confirmed scope-exit IDs to a plan's pending entries.
+   * Called either with the response of a standalone `findNewerMany`
+   * (manual eviction) or per-chunk during sync's `findNewerManyStream`
+   * (auto eviction bundled with sync).
+   */
+  _applyScopeExitChunkToPlan(plan, specId, items) {
+    const owner = plan.ownersBySpecId.get(specId);
+    if (!owner) return;
+    for (const item of items) {
+      const id = item._id;
+      if (id !== void 0) {
+        owner.evictIds.push(String(id));
+        owner.serverEvictedCount++;
+      }
+    }
+  }
+  /**
+   * Phase 3 of eviction: apply accumulated evict IDs (Dexie + in-mem
+   * deletes), broadcast cross-tab reload, build EvictionInfo, fire
+   * `onEviction`. Idempotent on empty plans — produces a zero-eviction
+   * info and still fires the callback so consumers see a lifecycle event.
+   */
+  async _applyScopeExitPlan(plan, serverFailed, serverRounds) {
+    const collectionResults = [];
+    let totalEvicted = 0;
+    let totalLocalEvicted = 0;
+    let totalServerEvicted = 0;
+    for (const p of plan.pending) {
+      const uniqueEvictIds = p.evictIds.length > 0 ? Array.from(new Set(p.evictIds)) : p.evictIds;
+      if (uniqueEvictIds.length > 0) {
+        await this.dexieDb.deleteMany(p.collection, uniqueEvictIds);
+        if (!p.config.writeOnly) {
+          this.inMemManager.writeBatch(
+            p.collection,
+            uniqueEvictIds.map((id) => ({ _id: id })),
+            "delete"
+          );
+        }
+        this.crossTabSync.broadcastReload([p.collection]);
+      }
+      collectionResults.push({
+        collection: p.collection,
+        evictedCount: uniqueEvictIds.length,
+        localEvictedCount: p.localEvictedCount,
+        serverEvictedCount: p.serverEvictedCount,
+        dirtySkipped: p.dirtySkipped,
+        scannedCount: p.scannedCount,
+        serverCandidateCount: p.serverCandidateIds.length
+      });
+      totalEvicted += uniqueEvictIds.length;
+      totalLocalEvicted += p.localEvictedCount;
+      totalServerEvicted += p.serverEvictedCount;
     }
     const info = {
       totalEvicted,
-      durationMs: Date.now() - startTime,
-      trigger,
+      totalLocalEvicted,
+      totalServerEvicted,
+      totalServerCandidates: plan.totalServerCandidates,
+      serverRounds,
+      serverFailed,
+      durationMs: Date.now() - plan.startTime,
+      trigger: plan.trigger,
       collections: collectionResults
     };
     this.safeCallback(this.onEviction, info);
     return info;
   }
   /**
-   * Check if auto-eviction should run and execute if interval has elapsed.
-   * Called after sync() and at end of init().
+   * Whether auto-eviction is due to run on the next sync. Mirrors the
+   * gating logic of the old `maybeAutoEvict` (interval check + persisted
+   * `__lastEviction` cursor) but split out so `sync()` can pre-compute
+   * the eviction plan BEFORE issuing the streamed `findNewerMany` —
+   * letting scope-exit specs ride along on the same call.
    */
-  async maybeAutoEvict() {
-    if (this.evictStaleRecordsEveryHrs <= 0) return;
+  async _isAutoEvictionDue() {
+    if (this.evictStaleRecordsEveryHrs <= 0) return false;
     const intervalMs = this.evictStaleRecordsEveryHrs * 36e5;
     if (!this._lastEvictionDate) {
       const meta = await this.dexieDb.getSyncMeta("__lastEviction");
@@ -4878,9 +5139,15 @@ var _SyncedDb = class _SyncedDb {
       }
     }
     if (this._lastEvictionDate && Date.now() - this._lastEvictionDate.getTime() < intervalMs) {
-      return;
+      return false;
     }
-    await this.evictOutOfScopeRecordsAll("auto");
+    return true;
+  }
+  /**
+   * Persist the current time as the last successful eviction.
+   * Called from sync() after phase 3 completes.
+   */
+  async _persistEvictionTimestamp() {
     this._lastEvictionDate = /* @__PURE__ */ new Date();
     await this.dexieDb.setSyncMeta(
       "__lastEviction",
@@ -5019,6 +5286,25 @@ var _SyncedDb = class _SyncedDb {
     }
     return allItems.length;
   }
+  /**
+   * Bulk-read sync cursors for every registered collection into syncMetaCache.
+   * Called once during init() before sync can fire. Decouples cursor cache
+   * availability from in-mem record hydration, eliminating the race where a
+   * sync triggered by ConnectionManager.tryGoOnline (or by setSyncOnlyTheseCollections
+   * expanding the allowed set) reads an unpopulated cache and sends timestamp:0
+   * for un-hydrated collections.
+   */
+  async preloadAllSyncMetas() {
+    const names = [...this.collections.keys()];
+    const results = await Promise.all(
+      names.map(
+        (name) => this.dexieDb.getSyncMeta(name).then((meta) => ({ name, meta }))
+      )
+    );
+    for (const { name, meta } of results) {
+      if (meta) this.syncMetaCache.set(name, meta);
+    }
+  }
   assertCollection(name) {
     if (!this.collections.has(name)) {
       throw new Error(`SyncedDb: Collection "${(name == null ? void 0 : name.toString()) || "?"}" not configured`);
@@ -7884,10 +8170,14 @@ var RestProxy = class {
   }
   /**
    * Parse streaming response. Auto-detects format:
-   * - Streaming: first byte is 0x00 (end) or 0x01 (data chunk)
+   * - Streaming: first byte is 0x00 (end), 0x01 (data chunk), or 0x02 (data chunk with specId)
    * - Legacy msgpack: first byte is msgpack type marker (0x80+ for map, etc.)
    *
-   * Streaming chunk format: [type:1][nameLen:2][name:N][dataLen:4][msgpack(items[]):M]
+   * Frame variants (rdb2 ≥ specId support):
+   *   0x01: [type:1][nameLen:2][name:N][dataLen:4][msgpack(items[]):M]
+   *   0x02: [type:1][nameLen:2][name:N][specIdLen:2][specId:M][dataLen:4][msgpack(items[]):K]
+   *
+   * `onChunk` receives `specId` as the third arg for type-0x02 frames; `undefined` otherwise.
    */
   async parseStreamingResponse(response, onChunk, onActivity) {
     const reader = response.body.getReader();
@@ -7904,7 +8194,7 @@ var RestProxy = class {
       if (!await readMore()) return;
     }
     const firstByte = buffer.at(0);
-    if (firstByte !== 0 && firstByte !== 1) {
+    if (firstByte !== 0 && firstByte !== 1 && firstByte !== 2) {
       while (await readMore()) {
       }
       const result = unpack2(buffer.subarray(0, buffer.length));
@@ -7919,28 +8209,61 @@ var RestProxy = class {
       while (buffer.length < 1) {
         if (!await readMore()) return;
       }
-      if (buffer.at(0) === 0) return;
+      const type = buffer.at(0);
+      if (type === 0) return;
       while (buffer.length < 3) {
         if (!await readMore())
           throw new Error("Unexpected end of stream in chunk header");
       }
       const nameLen = buffer.at(1) << 8 | buffer.at(2);
-      const headerSize = 1 + 2 + nameLen + 4;
-      while (buffer.length < headerSize) {
-        if (!await readMore())
-          throw new Error("Unexpected end of stream in chunk header");
-      }
-      const collection = decoder2.decode(buffer.subarray(3, 3 + nameLen));
-      const dataOffset = 3 + nameLen;
-      const dataLen = buffer.at(dataOffset) << 24 | buffer.at(dataOffset + 1) << 16 | buffer.at(dataOffset + 2) << 8 | buffer.at(dataOffset + 3);
-      const totalChunkSize = headerSize + dataLen;
-      while (buffer.length < totalChunkSize) {
-        if (!await readMore())
-          throw new Error("Unexpected end of stream in chunk data");
+      if (type === 1) {
+        const headerSize = 1 + 2 + nameLen + 4;
+        while (buffer.length < headerSize) {
+          if (!await readMore())
+            throw new Error("Unexpected end of stream in chunk header");
+        }
+        const collection = decoder2.decode(buffer.subarray(3, 3 + nameLen));
+        const dataOffset = 3 + nameLen;
+        const dataLen = buffer.at(dataOffset) << 24 | buffer.at(dataOffset + 1) << 16 | buffer.at(dataOffset + 2) << 8 | buffer.at(dataOffset + 3);
+        const totalChunkSize = headerSize + dataLen;
+        while (buffer.length < totalChunkSize) {
+          if (!await readMore())
+            throw new Error("Unexpected end of stream in chunk data");
+        }
+        const items = unpack2(buffer.subarray(headerSize, totalChunkSize));
+        buffer.consume(totalChunkSize);
+        await onChunk(collection, items);
+      } else if (type === 2) {
+        const minSize = 1 + 2 + nameLen + 2;
+        while (buffer.length < minSize) {
+          if (!await readMore())
+            throw new Error("Unexpected end of stream in specId chunk header");
+        }
+        const collection = decoder2.decode(buffer.subarray(3, 3 + nameLen));
+        const specIdLenOffset = 3 + nameLen;
+        const specIdLen = buffer.at(specIdLenOffset) << 8 | buffer.at(specIdLenOffset + 1);
+        const headerSize = minSize + specIdLen + 4;
+        while (buffer.length < headerSize) {
+          if (!await readMore())
+            throw new Error("Unexpected end of stream in specId chunk header");
+        }
+        const specIdOffset = specIdLenOffset + 2;
+        const specId = decoder2.decode(
+          buffer.subarray(specIdOffset, specIdOffset + specIdLen)
+        );
+        const dataOffset = specIdOffset + specIdLen;
+        const dataLen = buffer.at(dataOffset) << 24 | buffer.at(dataOffset + 1) << 16 | buffer.at(dataOffset + 2) << 8 | buffer.at(dataOffset + 3);
+        const totalChunkSize = headerSize + dataLen;
+        while (buffer.length < totalChunkSize) {
+          if (!await readMore())
+            throw new Error("Unexpected end of stream in specId chunk data");
+        }
+        const items = unpack2(buffer.subarray(headerSize, totalChunkSize));
+        buffer.consume(totalChunkSize);
+        await onChunk(collection, items, specId);
+      } else {
+        throw new Error(`Unknown stream chunk type: 0x${type.toString(16)}`);
       }
-      const items = unpack2(buffer.subarray(headerSize, totalChunkSize));
-      buffer.consume(totalChunkSize);
-      await onChunk(collection, items);
     }
   }
   // Sync - pošiljanje lokalnih sprememb na server

package/dist/src/db/RestProxy.d.ts

@@ -116,17 +116,21 @@ export declare class RestProxy implements I_RestInterface {
      *   [type:1][nameLen:2][name:N][dataLen:4][msgpack(items[]):M]
      *   type=0x01 for data, type=0x00 for end-of-stream.
      */
-    findNewerManyStream<T>(spec: GetNewerSpec<T>[], onChunk: (collection: string, items: T[]) => Promise<void>, options?: {
+    findNewerManyStream<T>(spec: GetNewerSpec<T>[], onChunk: (collection: string, items: T[], specId?: string) => Promise<void>, options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
         activityTimeoutMs?: number;
     }): Promise<void>;
     /**
      * Parse streaming response. Auto-detects format:
-     * - Streaming: first byte is 0x00 (end) or 0x01 (data chunk)
+     * - Streaming: first byte is 0x00 (end), 0x01 (data chunk), or 0x02 (data chunk with specId)
      * - Legacy msgpack: first byte is msgpack type marker (0x80+ for map, etc.)
      *
-     * Streaming chunk format: [type:1][nameLen:2][name:N][dataLen:4][msgpack(items[]):M]
+     * Frame variants (rdb2 ≥ specId support):
+     *   0x01: [type:1][nameLen:2][name:N][dataLen:4][msgpack(items[]):M]
+     *   0x02: [type:1][nameLen:2][name:N][specIdLen:2][specId:M][dataLen:4][msgpack(items[]):K]
+     *
+     * `onChunk` receives `specId` as the third arg for type-0x02 frames; `undefined` otherwise.
      */
     private parseStreamingResponse;
     deleteOne<T>(collection: string, query: QuerySpec<T>): Promise<T>;

package/dist/src/db/SyncedDb.d.ts

@@ -50,6 +50,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onWsNotification?;
     private readonly onCrossTabSync?;
     private readonly onWakeSync?;
+    private readonly onEvictionStart?;
     private readonly onEviction?;
     private readonly evictStaleRecordsEveryHrs;
     private _lastEvictionDate?;
@@ -228,9 +229,10 @@ export declare class SyncedDb implements I_SyncedDb {
      * out of scope by other writers that the filtered delta feed would
      * never report.
      *
-     * Chunks `candidateIds` into `$in`-sized batches to keep the request
-     * payload bounded. Uses `project: { _id: 1 }` to keep the response
-     * payload minimal.
+     * Bundles all id chunks into a single `findNewerMany` call, keyed by
+     * `specId = "<chunkIndex>"` so multiple specs against the same
+     * collection don't collide on the response. One round-trip regardless
+     * of `candidateIds.length`.
      *
      * @param timestamp - `findNewer` timestamp cursor. Only records with
      *   `_ts > timestamp` are examined. Caller decides the window (usually
@@ -243,14 +245,69 @@ export declare class SyncedDb implements I_SyncedDb {
     /**
      * Evict out-of-scope records for all collections.
      * Skips writeOnly and collections without syncConfig.query.
-     * Fires onEviction callback.
+     * Fires onEvictionStart before phase 1 and onEviction at the end.
+     *
+     * Three phases:
+     *  1. Local pass per eligible collection — Dexie scan, partition into
+     *     locally-failing (immediate evict candidates) vs locally-matching
+     *     (server-check candidates). Dirty records are skipped.
+     *  2. Server-assisted pass — a single `findNewerMany` call carrying
+     *     one spec per (collection × CHUNK_SIZE-id-batch), disambiguated
+     *     via `specId`. Collapses the prior N-per-collection round-trips
+     *     into one server round-trip total.
+     *  3. Apply evictions per collection (Dexie + in-mem deletes,
+     *     cross-tab reload broadcast).
+     *
+     * Server-assisted is automatic when the collection is online and not
+     * writeOnly — same default as `evictOutOfScopeRecords`. On batch
+     * failure, local evictions are still applied; remaining server rounds
+     * are skipped (logged, not thrown), and `serverFailed=true` is reported
+     * on the EvictionInfo.
      */
     evictOutOfScopeRecordsAll(trigger?: "auto" | "manual"): Promise<EvictionInfo>;
     /**
-     * Check if auto-eviction should run and execute if interval has elapsed.
-     * Called after sync() and at end of init().
+     * Phase 1 of eviction: pre-filter eligible collections, fire
+     * `onEvictionStart`, scan Dexie per collection to partition records
+     * into local-fail (immediate evict) vs server-check (candidates), and
+     * build the `findNewerMany` spec list (each spec tagged with a unique
+     * `specId`).
+     *
+     * Returns a plan object that can be:
+     *  - Sent to the server as a standalone `findNewerMany` call (manual eviction),
+     *  - Bundled into sync's `findNewerManyStream` via `SyncExtras` (auto eviction),
+     *  - Or applied with empty server results when offline/writeOnly.
+     *
+     * Always fires `onEvictionStart` (even with collectionCount=0) so the
+     * callback is a reliable lifecycle marker.
+     */
+    private _collectScopeExitPlan;
+    /**
+     * Append server-confirmed scope-exit IDs to a plan's pending entries.
+     * Called either with the response of a standalone `findNewerMany`
+     * (manual eviction) or per-chunk during sync's `findNewerManyStream`
+     * (auto eviction bundled with sync).
+     */
+    private _applyScopeExitChunkToPlan;
+    /**
+     * Phase 3 of eviction: apply accumulated evict IDs (Dexie + in-mem
+     * deletes), broadcast cross-tab reload, build EvictionInfo, fire
+     * `onEviction`. Idempotent on empty plans — produces a zero-eviction
+     * info and still fires the callback so consumers see a lifecycle event.
+     */
+    private _applyScopeExitPlan;
+    /**
+     * Whether auto-eviction is due to run on the next sync. Mirrors the
+     * gating logic of the old `maybeAutoEvict` (interval check + persisted
+     * `__lastEviction` cursor) but split out so `sync()` can pre-compute
+     * the eviction plan BEFORE issuing the streamed `findNewerMany` —
+     * letting scope-exit specs ride along on the same call.
      */
-    private maybeAutoEvict;
+    private _isAutoEvictionDue;
+    /**
+     * Persist the current time as the last successful eviction.
+     * Called from sync() after phase 3 completes.
+     */
+    private _persistEvictionTimestamp;
     getObjectMetadata<M>(collection: string, _id: Id): M | undefined;
     getObjectsMetadata<M>(collection: string, _ids: Id[]): (M | undefined)[];
     setObjectMetadata<M>(collection: string, _id: Id, metadata: M): void;
@@ -291,6 +348,15 @@ export declare class SyncedDb implements I_SyncedDb {
      */
     private loadCollectionsToInMem;
     private loadCollectionToInMem;
+    /**
+     * Bulk-read sync cursors for every registered collection into syncMetaCache.
+     * Called once during init() before sync can fire. Decouples cursor cache
+     * availability from in-mem record hydration, eliminating the race where a
+     * sync triggered by ConnectionManager.tryGoOnline (or by setSyncOnlyTheseCollections
+     * expanding the allowed set) reads an unpopulated cache and sends timestamp:0
+     * for un-hydrated collections.
+     */
+    private preloadAllSyncMetas;
     private assertCollection;
     private static readonly STRINGIFIED_FALSY;
     /** Stringify an Id parameter (ObjectId → hex string). */

package/dist/src/db/sync/SyncEngine.d.ts

@@ -7,7 +7,7 @@
  * - Uploading dirty items to server
  */
 import type { LocalDbEntity } from "../../types/DbEntity";
-import type { I_SyncEngine, SyncEngineConfig } from "../types/managers";
+import type { I_SyncEngine, SyncEngineConfig, SyncExtras } from "../types/managers";
 import type { UploadResult } from "../types/internal";
 export declare class SyncEngine implements I_SyncEngine {
     private readonly tenant;
@@ -21,8 +21,13 @@ export declare class SyncEngine implements I_SyncEngine {
     /**
      * Execute full sync cycle.
      * Called by SyncedDb which handles locking.
+     *
+     * `extras` lets the caller append additional `findNewerMany` specs
+     * (each with a unique `specId`) onto the same streamed call. Chunks
+     * for those specs are routed via `extras.onChunk(specId, items)` and
+     * never enter the positive-sync processing path.
      */
-    sync(calledFrom?: string): Promise<void>;
+    sync(calledFrom?: string, extras?: SyncExtras): Promise<void>;
     /**
      * Upload dirty items for all collections.
      */

package/dist/src/db/types/managers.d.ts

@@ -283,9 +283,29 @@ export interface SyncEngineConfig {
     callbacks: SyncEngineCallbacks;
     deps: SyncEngineDeps;
 }
+/**
+ * Optional extras passed to `SyncEngine.sync()`. Lets a caller piggyback
+ * additional `findNewerMany` specs (each tagged with a unique `specId`)
+ * onto the same streamed server call that fetches positive sync deltas —
+ * saving the round-trip that those specs would otherwise cost.
+ *
+ * Used today by SyncedDb to bundle scope-exit eviction queries into the
+ * positive sync stream when auto-eviction is due.
+ *
+ * Contract:
+ * - Each spec MUST set `specId` to a string unique within the call.
+ * - Positive sync specs do NOT set `specId`; chunks for them arrive
+ *   with `specId === undefined` and are processed normally.
+ * - Extra spec chunks are routed to `onChunk(specId, items)` and never
+ *   touch the conflict-resolution / Dexie write path.
+ */
+export interface SyncExtras {
+    specs: import("../../types/I_RestInterface").GetNewerSpec<any>[];
+    onChunk: (specId: string, items: any[]) => void;
+}
 export interface I_SyncEngine {
     /** Execute full sync cycle. */
-    sync(calledFrom?: string): Promise<void>;
+    sync(calledFrom?: string, extras?: SyncExtras): Promise<void>;
     /** Upload dirty items for all collections. */
     uploadDirtyItems(calledFrom?: string): Promise<UploadResult>;
     /** Upload dirty items for a specific collection. */

package/dist/src/types/I_RestInterface.d.ts

@@ -59,6 +59,18 @@ export interface GetNewerSpec<T> {
     timestamp: number | Date | string | Timestamp;
     query?: QuerySpec<T>;
     opts?: QueryOpts;
+    /**
+     * Optional disambiguator. When set, results for this spec are keyed
+     * by `specId` in the `findNewerMany` response (and emitted as the
+     * `specId` arg to `onChunk` in the streaming variant) instead of
+     * `collection`. Lets a single batched request carry multiple specs
+     * against the same `collection` without `Record<key, items[]>`
+     * collisions. Backwards-compatible: specs without `specId` are keyed
+     * by `collection` exactly as before.
+     *
+     * Server support: cry-db ≥ 2.4.32 (specId honored).
+     */
+    specId?: string;
 }
 /**
  * Request to batch update a collection, used to sync data
@@ -90,8 +102,12 @@ export interface I_RestInterface {
     findByIds<T>(collection: string, ids: Id[]): Promise<T[]>;
     findNewer<T>(collection: string, timestamp: Timestamp | number | string | Date, query?: QuerySpec<T>, opts?: QueryOpts): Promise<T[]>;
     findNewerMany<T>(spec?: GetNewerSpec<T>[]): Promise<Record<string, any[]>>;
-    /** Streaming variant of findNewerMany. Calls onChunk for each batch of items as they arrive. */
-    findNewerManyStream<T>(spec: GetNewerSpec<T>[], onChunk: (collection: string, items: T[]) => Promise<void>, options?: {
+    /**
+     * Streaming variant of findNewerMany. Calls onChunk for each batch of items as they arrive.
+     * `specId` is forwarded as the third arg when the originating spec set one — `undefined` otherwise.
+     * Old two-arg `onChunk` callbacks keep working unchanged (the third arg is ignored).
+     */
+    findNewerManyStream<T>(spec: GetNewerSpec<T>[], onChunk: (collection: string, items: T[], specId?: string) => Promise<void>, options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<void>;

package/dist/src/types/I_SyncedDb.d.ts

@@ -232,17 +232,42 @@ export interface SyncInfo {
 export interface EvictionCollectionInfo {
     /** Collection name. */
     collection: string;
-    /** Records removed from Dexie + in-mem. */
+    /** Records removed from Dexie + in-mem (local + server-confirmed). */
     evictedCount: number;
+    /** Records evicted by the local pass (cached state failed the query). */
+    localEvictedCount: number;
+    /** Records evicted by the server-assisted pass (server reports out-of-scope). */
+    serverEvictedCount: number;
     /** Records skipped because they have pending dirty changes. */
     dirtySkipped: number;
     /** Total records scanned in this collection. */
     scannedCount: number;
+    /** IDs sent to the server for scope-exit confirmation (0 if not server-assisted). */
+    serverCandidateCount: number;
+}
+/** Reported to onEvictionStart before the eviction passes begin. */
+export interface EvictionStartInfo {
+    /** Whether this run is an auto or manual trigger. */
+    trigger: "auto" | "manual";
+    /** Number of eligible collections (writeOnly and queryless skipped). */
+    collectionCount: number;
+    /** Names of the eligible collections, in iteration order. */
+    collections: string[];
 }
 /** Eviction result reported to the onEviction callback. */
 export interface EvictionInfo {
-    /** Total records evicted across all collections. */
+    /** Total records evicted across all collections (local + server). */
     totalEvicted: number;
+    /** Sum of records evicted by local-pass alone across all collections. */
+    totalLocalEvicted: number;
+    /** Sum of records evicted by server-assisted pass alone across all collections. */
+    totalServerEvicted: number;
+    /** Sum of `serverCandidateCount` across all collections — IDs we asked the server about. */
+    totalServerCandidates: number;
+    /** Number of `findNewerMany` round-trips issued during the server-assisted pass. */
+    serverRounds: number;
+    /** Whether the server-assisted pass aborted mid-flight (still applies local evictions). */
+    serverFailed: boolean;
     /** Wall-clock duration of the eviction operation in ms. */
     durationMs: number;
     /** Whether this was triggered automatically or by manual call. */
@@ -525,7 +550,17 @@ export interface SyncedDbConfig {
      * Default: 0 (disabled).
      */
     evictStaleRecordsEveryHrs?: number;
-    /** Callback fired after each eviction run (manual or auto). Errors are swallowed. */
+    /**
+     * Callback fired before each eviction run begins, after the eligible
+     * collection list has been resolved. Useful as a debug breadcrumb to
+     * confirm a tick fired and which collections will be scanned.
+     * Errors are swallowed.
+     */
+    onEvictionStart?: (info: EvictionStartInfo) => void;
+    /**
+     * Callback fired after each eviction run completes (manual or auto).
+     * Receives full per-collection and aggregate stats. Errors are swallowed.
+     */
     onEviction?: (info: EvictionInfo) => void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.145",
+  "version": "0.1.147",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,7 +36,7 @@
     "vitest": "^4.1.2"
   },
   "dependencies": {
-    "cry-db": "^2.4.31",
+    "cry-db": "^2.4.32",
     "cry-helpers": "^2.1.193",
     "msgpackr": "^1.11.9",
     "notepack": "^0.0.2",