@spooky-sync/core 0.0.1-canary.204 → 0.0.1-canary.205

package/dist/tabs-broker-worker.js

@@ -1,6 +1,13 @@
 //#region src/services/tabs/tabs-broker-worker.ts
 const PING_INTERVAL_MS = 5e3;
 const PONG_TIMEOUT_MS = 15e3;
+/** How long a tab has to answer `become-leader` with `leader-ready`. A tab
+*  that hangs mid-promotion sends neither `leader-ready` nor `leader-failed`,
+*  and keeps answering pings, so nothing else here would notice: the
+*  namespace would keep a leader that is not `ready`, mint no follower ports,
+*  and refuse to re-elect (`electIfNeeded` bails while `ns.leader` is set)
+*  until every tab was reloaded. Treat the silence as a failed promotion. */
+const PROMOTION_TIMEOUT_MS = 2e4;
 const FORCE_TAKEOVER_TIMEOUT_MS = 1e3;
 const LEADER_FAILURE_BACKOFF_MS = 1e3;
 const FAILED_CYCLES_BEFORE_MEMORY = 3;
@@ -35,7 +42,8 @@ function getNamespace(fingerprint, bucketId) {
 			failedCycles: 0,
 			electing: false,
 			attachRetry: /* @__PURE__ */ new Map(),
-			tabLockMonitor: null
+			tabLockMonitor: null,
+			promotionTimer: null
 		};
 		namespaces.set(key, ns);
 	}
@@ -63,6 +71,7 @@ function clearLeader(ns, opts) {
 	const leader = ns.leader;
 	if (!leader) return null;
 	ns.leader = null;
+	clearPromotionTimer(ns);
 	ns.tabLockMonitor?.abort();
 	ns.tabLockMonitor = null;
 	const tab = ns.tabs.get(leader.tabId);
@@ -86,6 +95,39 @@ function clearLeader(ns, opts) {
 		workerLock
 	};
 }
+function clearPromotionTimer(ns) {
+	if (ns.promotionTimer) clearTimeout(ns.promotionTimer);
+	ns.promotionTimer = null;
+}
+/**
+* A promotion did not work out: back the tab off, clear the leadership, and
+* re-elect. Shared by the tab's own `leader-failed` report and by the
+* {@link PROMOTION_TIMEOUT_MS} deadline, so a tab that hangs mid-promotion
+* costs the namespace the same 1s backoff as one that fails loudly, instead of
+* owning it forever.
+*
+* Every reason counts toward `failedCycles`. Gating that on 'opfs-unavailable'
+* left any other recurring failure (e.g. a tab lock nobody frees) looping at
+* the backoff interval forever, with allowMemoryFallback never granted, so
+* every tab timed out in start() and booted solo - each one then contending
+* for the OPFS pool on its own, which is exactly what shared-tabs exists to
+* stop.
+*/
+function failPromotion(ns, tabId, leadershipId, opts) {
+	if (ns.leader?.tabId !== tabId || ns.leader.leadershipId !== leadershipId) return;
+	ns.failedCycles += 1;
+	ns.failedUntil.set(tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
+	const previous = clearLeader(ns, {
+		demote: false,
+		removeTab: false
+	});
+	const tab = ns.tabs.get(tabId);
+	if (tab) tab.heldLeadership = null;
+	electIfNeeded(ns, opts.timedOut && previous ? {
+		...previous,
+		workerLock: `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:worker:${leadershipId}`
+	} : previous);
+}
 /**
 * Fast crash detection: queue a Web Lock request on the leader's tab lock.
 * Locks release the instant their holder's tab dies, so being GRANTED means
@@ -174,6 +216,11 @@ function electIfNeeded(ns, previous = null) {
 				allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
 				resumeHeld
 			});
+			clearPromotionTimer(ns);
+			ns.promotionTimer = setTimeout(() => {
+				ns.promotionTimer = null;
+				failPromotion(ns, candidate.tabId, leadershipId, { timedOut: true });
+			}, PROMOTION_TIMEOUT_MS);
 		} finally {
 			ns.electing = false;
 		}
@@ -359,6 +406,7 @@ function handleTabMessage(port, msg, ports) {
 			}
 			ns.leader.ready = true;
 			ns.failedCycles = 0;
+			clearPromotionTimer(ns);
 			startTabLockMonitor(ns, msg.leadershipId);
 			const tab = ns.tabs.get(msg.tabId);
 			if (tab) tab.heldLeadership = {
@@ -374,19 +422,9 @@ function handleTabMessage(port, msg, ports) {
 			assignFollowerPorts(ns);
 			break;
 		}
-		case "leader-failed": {
-			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) break;
-			ns.failedCycles += 1;
-			ns.failedUntil.set(msg.tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
-			const previous = clearLeader(ns, {
-				demote: false,
-				removeTab: false
-			});
-			const tab = ns.tabs.get(msg.tabId);
-			if (tab) tab.heldLeadership = null;
-			electIfNeeded(ns, previous);
+		case "leader-failed":
+			failPromotion(ns, msg.tabId, msg.leadershipId, { timedOut: false });
 			break;
-		}
 		case "follower-port-attached":
 			if (ns.leader?.tabId === msg.tabId && ns.leader.leadershipId === msg.leadershipId) followerAttached(ns, msg.followerTabId);
 			break;

package/dist/types.d.ts

@@ -334,6 +334,37 @@ interface LocalStore extends LocalCacheEngine {
   /** Fires immediately with the current snapshot, then on every change.
    *  Returns an unsubscribe function. */
   subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
+  /**
+   * Every cached row's `(id, _00_rv)` per table, ids in stable `table:id`
+   * form. The in-browser circuit primes and reconciles itself from this on
+   * boot instead of re-downloading the working set. OPTIONAL: an engine
+   * without it boots the circuit empty, as before.
+   */
+  scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Circuit snapshot storage, keyed. Lives in the same durable store as the
+   * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and
+   * readable by follower tabs over the port transport. OPTIONAL: an engine
+   * without it primes from `scanVersions` alone.
+   */
+  getSnapshot?(key: string): Promise<StoredSnapshot | null>;
+  putSnapshot?(key: string, bytes: Uint8Array, meta: SnapshotMeta): Promise<void>;
+  deleteSnapshot?(key: string): Promise<void>;
+}
+/** Describes a stored circuit snapshot; what decides whether it is usable. */
+interface SnapshotMeta {
+  /** Bump when the wire shape the circuit reads changes. */
+  formatVersion: number;
+  /** Hash of the schema the rows were projected under. */
+  schemaHash: string;
+  savedAt: number;
+  /** Highest `_00_rv` per table at save time (diagnostics). */
+  maxRv?: Record<string, number>;
+  [key: string]: unknown;
+}
+interface StoredSnapshot {
+  bytes: Uint8Array;
+  meta: SnapshotMeta;
 }
 /** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
 type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
@@ -538,21 +569,19 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    */
   sharedTabs?: boolean;
   /**
-   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
-   * reload can restore it instead of re-materializing. Default `false`, and
-   * that default is deliberate.
+   * Persist the in-browser SSP circuit's store as a snapshot in the local
+   * store, so a reload restores it and only steps in what changed since.
+   * Defaults to `true` under `localEngine: 'sqlite'` (the OPFS-backed store
+   * can hold the bytes) and `false` otherwise.
    *
-   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
-   * source of truth, and every first paint already reads row bodies from it
-   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
-   * for row identity and ordering. A snapshot buys nothing on reload while
-   * costing a full deep clone of every row of every ingested table plus a JSON
-   * encode of the result, `Circuit::save` in the Rust core, mirroring the
-   * server's rule in `ssp-node`: *never per-ingest*.
+   * Without a snapshot the circuit is primed by reading every cached row back
+   * out of the local store; either way a reload never re-downloads the working
+   * set, which is what an empty circuit used to force: every id in the
+   * server's list_ref classified as missing.
    *
-   * When enabled, snapshots are written on a checkpoint interval
-   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
-   * query registration. Enable only for a workload that has measured a win.
+   * Snapshots are store-only (views are re-registered per session) and written
+   * on a checkpoint interval ({@link circuitCheckpointMs}) and when the page
+   * goes hidden, never per ingest or per query registration.
    */
   persistCircuit?: boolean;
   /**
@@ -560,6 +589,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * 30000. Ignored when `persistCircuit` is off.
    */
   circuitCheckpointMs?: number;
+  /**
+   * Keep only the fields registered queries evaluate (filter predicates, join
+   * keys, sort keys, plus `id`/`_00_rv`) per row in the in-browser circuit.
+   * Default `true`. The circuit only ever reads those fields; bodies are
+   * rendered from the local store. Measured on 7700 rows with 20 KB bodies:
+   * the wasm heap peak went from ~500 MB to ~24 MB and the snapshot from
+   * 156 MB to 1.2 MB. A query that evaluates a field earlier rows were kept
+   * without has that field merged in from the local store on registration.
+   */
+  circuitProjection?: boolean;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.204",
+  "version": "0.0.1-canary.205",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.204",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.204",
+    "@spooky-sync/query-builder": "0.0.1-canary.205",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.205",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/modules/cache/index.ts

@@ -88,6 +88,19 @@ export class CacheModule implements StreamUpdateReceiver {
     return this.versionLookups[recordId] ?? 0;
   }
 
+  /**
+   * Seed the version memo from rows the circuit was primed with out of the
+   * local store, so the first post-reload sync diff does not re-download
+   * bodies the browser already has. Only rows the prime actually put into the
+   * circuit belong here: a memo entry with no circuit row would make the diff
+   * flag the id forever while nothing ever fetches it.
+   */
+  public primeVersions(entries: [string, number][]): void {
+    for (const [id, rv] of entries) {
+      if (rv > (this.versionLookups[id] ?? 0)) this.versionLookups[id] = rv;
+    }
+  }
+
   /** Drop the version cache on a bucket switch — a stale version would make
    *  the sync diff skip fetching a body the new bucket legitimately needs. */
   public clearVersionLookups(): void {
@@ -174,13 +187,17 @@ export class CacheModule implements StreamUpdateReceiver {
       // ingestMany coalesces the per-record stream updates into a single
       // notification per affected query — the UI then updates once, after the
       // whole batch is ingested, instead of row-by-row.
+      const versionOf = new Map<string, number>();
       const bulk = populatedRecords.map((record) => {
         const recordId = encodeRecordId(record.record.id);
-        this.versionLookups[recordId] = record.version;
+        versionOf.set(recordId, record.version);
         return { table: record.table, op: record.op, id: recordId, record: record.record };
       });
-      this.streamProcessor.ingestMany(bulk);
-      this.ingestRelay?.(bulk as CacheIngestTuple[]);
+      // Memo and relay only what the circuit actually took: a chunk that
+      // failed mid-batch is neither "known" here nor fanned out to followers.
+      const ingested = this.streamProcessor.ingestMany(bulk);
+      for (const t of ingested) this.versionLookups[t.id] = versionOf.get(t.id) ?? 0;
+      if (ingested.length > 0) this.ingestRelay?.(ingested as CacheIngestTuple[]);
 
       this.logger.debug(
         { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
@@ -221,7 +238,7 @@ export class CacheModule implements StreamUpdateReceiver {
 
       // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
-      this.streamProcessor.ingest(table, 'DELETE', id, recordData);
+      this.streamProcessor.ingestMany([{ table, op: 'DELETE', id, record: recordData }]);
       this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
 
       this.logger.debug(

package/src/modules/devtools/index.ts

@@ -327,7 +327,9 @@ export class DevToolsService implements StreamUpdateReceiver {
         const info = this.unwrapInfo(res);
         this.localTablesAt = Date.now();
         if (info && info.tables) {
-          const names = Object.keys(info.tables);
+          // The circuit snapshot table holds a BLOB, not JSON rows; the
+          // explorer cannot render it and has nothing to show for it.
+          const names = Object.keys(info.tables).filter((n) => n !== '_00_circuit_snapshot');
           const changed =
             names.length !== this.localTables.length ||
             names.some((n, i) => n !== this.localTables[i]);

package/src/modules/sync/engine.ts

@@ -8,6 +8,9 @@ import { SyncEventTypes, createSyncEventSystem } from './events/index';
 import { encodeRecordId } from '../../utils/index';
 import { cleanRecord } from '../../utils/parser';
 
+/** Ids per remote `SELECT * FROM $ids` round trip. */
+const FETCH_CHUNK = 500;
+
 /**
  * SyncEngine handles the core sync operations: fetching remote records,
  * caching them locally, and ingesting into DBSP.
@@ -55,10 +58,16 @@ export class SyncEngine {
       stillRemoteIds = await this.handleRemovedRecords(removed);
     }
 
-    // Fetch added/updated records from remote
-    const toFetch = [...added, ...updated];
-    const idsToFetch = toFetch.map((x) => x.id);
-    if (idsToFetch.length === 0) {
+    // Fetch added/updated records from remote. Skip ids whose body the local
+    // store already holds at this version (the circuit prime seeded the memo
+    // from `_00_rv`): after a reload every id in the server's list_ref used to
+    // classify as `added` against an empty circuit, and this fetched the
+    // whole working set again.
+    const toFetch = [...added, ...updated].filter((item) => {
+      const localVersion = this.cache.lookup(encodeRecordId(item.id));
+      return !(localVersion && item.version <= localVersion);
+    });
+    if (toFetch.length === 0) {
       return { remoteFetchMs: 0, stillRemoteIds };
     }
 
@@ -67,66 +76,75 @@ export class SyncEngine {
     for (const item of toFetch) {
       versionMap.set(encodeRecordId(item.id), item.version);
     }
+    const addedIds = new Set(added.map((item) => encodeRecordId(item.id)));
 
     // Fetch records from remote — avoid SELECT *, <subquery> FROM $param
     // pattern which drops the * fields in SurrealDB v3 (known bug).
     // Versions are already known from the diff's list_ref data.
-    const remoteFetchStart = performance.now();
-    const [remoteResults] = await this.remote.query<[RecordWithId[]]>(
-      'SELECT * FROM $idsToFetch',
-      { idsToFetch }
-    );
-    const remoteFetchMs = performance.now() - remoteFetchStart;
-
-    // Prepare batch for cache (which handles both DB and DBSP)
-    const cacheBatch: CacheRecord[] = [];
-
-    for (const record of remoteResults) {
-      if (!record?.id) {
-        this.logger.warn(
-          {
-            record,
-            idsToFetch,
-            Category: 'sp00ky-client::SyncEngine::syncRecords',
-          },
-          'Remote record has no id (possibly deleted). Skipping record'
-        );
-        continue;
-      }
-      const fullId = encodeRecordId(record.id);
-      const table = record.id.table.toString();
-      const isAdded = added.some((item) => encodeRecordId(item.id) === fullId);
-      const version = versionMap.get(fullId) ?? 0;
-
-      const localVersion = this.cache.lookup(fullId);
-      if (localVersion && version <= localVersion) {
-        this.logger.info(
-          {
-            recordId: fullId,
-            version,
-            localVersion,
-            Category: 'sp00ky-client::SyncEngine::syncRecords',
-          },
-          'Local version is higher than remote version. Skipping record'
-        );
-        continue;
+    //
+    // Chunked so a genuinely cold load lands progressively: one response
+    // holding thousands of bodies, then one transaction MERGEing all of them,
+    // was a single main-thread stall and a memory spike on top of it.
+    let remoteFetchMs = 0;
+    const remoteResults: RecordWithId[] = [];
+    for (let i = 0; i < toFetch.length; i += FETCH_CHUNK) {
+      const idsToFetch = toFetch.slice(i, i + FETCH_CHUNK).map((x) => x.id);
+      const remoteFetchStart = performance.now();
+      const [chunkResults] = await this.remote.query<[RecordWithId[]]>(
+        'SELECT * FROM $idsToFetch',
+        { idsToFetch }
+      );
+      remoteFetchMs += performance.now() - remoteFetchStart;
+
+      // Prepare batch for cache (which handles both DB and DBSP)
+      const cacheBatch: CacheRecord[] = [];
+      for (const record of chunkResults ?? []) {
+        if (!record?.id) {
+          this.logger.warn(
+            {
+              record,
+              idsToFetch,
+              Category: 'sp00ky-client::SyncEngine::syncRecords',
+            },
+            'Remote record has no id (possibly deleted). Skipping record'
+          );
+          continue;
+        }
+        remoteResults.push(record);
+        const fullId = encodeRecordId(record.id);
+        const table = record.id.table.toString();
+        const version = versionMap.get(fullId) ?? 0;
+
+        const localVersion = this.cache.lookup(fullId);
+        if (localVersion && version <= localVersion) {
+          this.logger.info(
+            {
+              recordId: fullId,
+              version,
+              localVersion,
+              Category: 'sp00ky-client::SyncEngine::syncRecords',
+            },
+            'Local version is higher than remote version. Skipping record'
+          );
+          continue;
+        }
+        const tableSchema = this.schema.tables.find((t) => t.name === table);
+        const cleanedRecord = tableSchema
+          ? cleanRecord(tableSchema.columns, record)
+          : record;
+
+        cacheBatch.push({
+          table,
+          op: addedIds.has(fullId) ? 'CREATE' : 'UPDATE',
+          record: cleanedRecord as RecordWithId,
+          version,
+        });
       }
-      const tableSchema = this.schema.tables.find((t) => t.name === table);
-      const cleanedRecord = tableSchema
-        ? cleanRecord(tableSchema.columns, record)
-        : record;
-
-      cacheBatch.push({
-        table,
-        op: isAdded ? 'CREATE' : 'UPDATE',
-        record: cleanedRecord as RecordWithId,
-        version,
-      });
-    }
 
-    // Use CacheModule to handle both local DB and DBSP ingestion
-    if (cacheBatch.length > 0) {
-      await this.cache.saveBatch(cacheBatch);
+      // Use CacheModule to handle both local DB and DBSP ingestion
+      if (cacheBatch.length > 0) {
+        await this.cache.saveBatch(cacheBatch);
+      }
     }
 
     this.events.emit(SyncEventTypes.RemoteDataIngested, {

package/src/modules/sync/sync.ts

@@ -527,14 +527,40 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.tabId = tabId;
   }
 
-  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
-   *  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
-   *  boot-time leader; a runtime promotion (failover) reloads the outbox,
-   *  which now holds EVERY tab's rows, and restarts LIVE under this session. */
-  public async promoteToLeader(hub: LeaderSyncHub): Promise<void> {
+  /** In-flight {@link resumeLeaderDuties}, so a second call joins the first
+   *  instead of double-draining the outbox. */
+  private leaderDutiesInFlight: Promise<void> | null = null;
+
+  /** Resolves once the in-browser circuit has been primed from the local
+   *  store. Every sync diff waits on it: diffing against an empty circuit
+   *  classifies the whole working set as missing and re-downloads it. */
+  private primeGate: () => Promise<void> = () => Promise.resolve();
+  /** The prime we last waited on. `whenPrimed` hands out one promise per
+   *  prime, so a new identity means a new prime (boot, bucket switch) ran. */
+  private settledPrime: Promise<void> | null = null;
+
+  setPrimeGate(gate: () => Promise<void>): void {
+    this.primeGate = gate;
+    this.settledPrime = null;
+  }
+
+  /**
+   * Leader WIRING only, and deliberately synchronous.
+   *
+   * The coordinator publishes the leader role and tells the broker
+   * `leader-ready` the moment the store is adopted, and the broker can mint a
+   * follower's ports on the very next tick. So the follower-message handler
+   * has to be live before this returns, or a mutation forwarded in that window
+   * is dropped. Everything that can block (outbox reload, LIVE restart) moved
+   * to {@link resumeLeaderDuties}: a promotion that waits on the network holds
+   * `leader-ready` back, and a broker whose leader never reports ready serves
+   * no follower ports and re-elects no one, which wedges the whole namespace.
+   */
+  public promoteToLeader(hub: LeaderSyncHub): void {
     this.tabRole = 'leader';
     this.hub = hub;
     this.forwarder = null;
+    this.leaderDutiesInFlight = null;
     hub.onFollowerMessage = (tabId, msg) => {
       void tabId;
       switch (msg.type) {
@@ -548,19 +574,34 @@ export class Sp00kySync<S extends SchemaStructure> {
           break;
       }
     };
-    if (this.isInit) {
+  }
+
+  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+   *  relay LIVE events and rollbacks to followers. Idempotent for a boot-time
+   *  leader; a runtime promotion (failover) reloads the outbox, which now
+   *  holds EVERY tab's rows, and restarts LIVE under this session. Runs in the
+   *  background off the promotion path, so however long it takes (or if it
+   *  never finishes) the tab is already a working leader. */
+  public resumeLeaderDuties(): Promise<void> {
+    if (this.leaderDutiesInFlight) return this.leaderDutiesInFlight;
+    const run = (async () => {
+      if (!this.isInit || this.tabRole !== 'leader') return;
       await this.upQueue.loadFromDatabase();
       void this.scheduler.syncUp();
       if (this.currentUserId || this.anonLiveEnabled) {
         this.startListRefPoll();
         await this.restartRefLiveQuery().catch((err) => {
           this.logger.warn(
-            { err, Category: 'sp00ky-client::Sp00kySync::promoteToLeader' },
+            { err, Category: 'sp00ky-client::Sp00kySync::resumeLeaderDuties' },
             'LIVE restart failed on promotion; poll fallback covers it'
           );
         });
       }
-    }
+    })();
+    this.leaderDutiesInFlight = run;
+    return run.finally(() => {
+      if (this.leaderDutiesInFlight === run) this.leaderDutiesInFlight = null;
+    });
   }
 
   /** Follower duties: no outbox drain, no LIVE. Mutations forward to the
@@ -570,6 +611,9 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.tabRole = 'follower';
     this.hub = null;
     this.forwarder = forwarder;
+    // A still-running resumeLeaderDuties self-cancels on its `tabRole` guard;
+    // drop the handle so a later re-promotion starts a fresh drain.
+    this.leaderDutiesInFlight = null;
     void this.killRefLiveQuery();
     forwarder.onLeaderMessage = (msg) => {
       switch (msg.type) {
@@ -1531,6 +1575,19 @@ export class Sp00kySync<S extends SchemaStructure> {
    * means the single resulting UI update lands after this completes.
    */
   private async runSyncForQuery(hash: string, diff: RecordVersionDiff): Promise<void> {
+    // The diff was computed against whatever the circuit held at call time; if
+    // the boot prime is still filling it, wait and recompute from the primed
+    // `localArray` so the delta is real rather than "everything".
+    const prime = this.primeGate();
+    if (prime !== this.settledPrime) {
+      await prime;
+      this.settledPrime = prime;
+      const fresh = this.dataModule.getQueryByHash(hash);
+      if (!fresh) return;
+      const recomputed = new ArraySyncer(fresh.config.localArray, fresh.config.remoteArray).nextSet();
+      if (!recomputed) return;
+      diff = recomputed;
+    }
     // Don't let sync re-add a record the user just deleted locally. The remote
     // delete is queued in the outbox, so until it's processed the server's
     // `_00_list_ref` still lists the record — the diff then classifies it as

package/src/services/database/cache-engine.ts

@@ -138,6 +138,39 @@ export interface LocalStore extends LocalCacheEngine {
   /** Fires immediately with the current snapshot, then on every change.
    *  Returns an unsubscribe function. */
   subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
+  /**
+   * Every cached row's `(id, _00_rv)` per table, ids in stable `table:id`
+   * form. The in-browser circuit primes and reconciles itself from this on
+   * boot instead of re-downloading the working set. OPTIONAL: an engine
+   * without it boots the circuit empty, as before.
+   */
+  scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Circuit snapshot storage, keyed. Lives in the same durable store as the
+   * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and
+   * readable by follower tabs over the port transport. OPTIONAL: an engine
+   * without it primes from `scanVersions` alone.
+   */
+  getSnapshot?(key: string): Promise<StoredSnapshot | null>;
+  putSnapshot?(key: string, bytes: Uint8Array, meta: SnapshotMeta): Promise<void>;
+  deleteSnapshot?(key: string): Promise<void>;
+}
+
+/** Describes a stored circuit snapshot; what decides whether it is usable. */
+export interface SnapshotMeta {
+  /** Bump when the wire shape the circuit reads changes. */
+  formatVersion: number;
+  /** Hash of the schema the rows were projected under. */
+  schemaHash: string;
+  savedAt: number;
+  /** Highest `_00_rv` per table at save time (diagnostics). */
+  maxRv?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+export interface StoredSnapshot {
+  bytes: Uint8Array;
+  meta: SnapshotMeta;
 }
 
 /** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */

package/src/services/database/sqlite-cache-engine.test.ts

@@ -556,3 +556,61 @@ describe('create() tx result shaping (fast path parity)', () => {
     expect(outboxRow.data).toEqual(payload);
   });
 });
+
+
+// The circuit snapshot + version scan the boot-time prime reads through this
+// engine. Bytes and meta must round-trip as ONE batch (a reader must never see
+// new bytes with old meta) and a table that does not exist yet scans as empty.
+describe('SqliteCacheEngine circuit snapshot + scanVersions', () => {
+  it('stores bytes and meta in one batch and reads them back', async () => {
+    const stored = new Map<string, unknown>();
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    const types: string[] = [];
+    stubTransport(engine, (type: string, payload: any) => {
+      types.push(type);
+      if (type === 'open') return { persisted: true };
+      if (type === 'batch') {
+        for (const stmt of payload as { sql: string; bind: unknown[] }[]) {
+          stored.set(stmt.bind[0] as string, stmt.bind[1]);
+        }
+        return {};
+      }
+      if (type === 'exec') {
+        const ids = (payload.bind ?? []) as string[];
+        return { rows: ids.filter((id) => stored.has(id)).map((id) => ({ id, data: stored.get(id) })) };
+      }
+      return {};
+    });
+    await engine.connect('anon');
+
+    expect(await engine.getSnapshot('circuit')).toBeNull();
+    const bytes = new Uint8Array([1, 2, 3]);
+    await engine.putSnapshot('circuit', bytes, { formatVersion: 1, schemaHash: 'h', savedAt: 5 });
+    expect(types.filter((t) => t === 'batch')).toHaveLength(1);
+    const snap = await engine.getSnapshot('circuit');
+    expect(snap?.bytes).toEqual(bytes);
+    expect(snap?.meta).toEqual({ formatVersion: 1, schemaHash: 'h', savedAt: 5 });
+  });
+
+  it('scans (id, rv) per table and reads a missing table as empty', async () => {
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    stubTransport(engine, (type: string, payload: any) => {
+      if (type === 'open') return { persisted: true };
+      if (type === 'exec') {
+        if (String(payload.sql).includes('"thing"')) {
+          return { rows: [{ id: 'thing:a', rv: 3 }, { id: 'thing:b', rv: null }] };
+        }
+        throw new Error('no such table');
+      }
+      return {};
+    });
+    await engine.connect('anon');
+    expect(await engine.scanVersions(['thing', 'ghost'])).toEqual({
+      thing: [
+        ['thing:a', 3],
+        ['thing:b', 0],
+      ],
+      ghost: [],
+    });
+  });
+});