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

package/dist/index.js

@@ -1616,6 +1616,21 @@ var SurrealCacheEngine = class extends LocalDatabaseService {
 		if (typeof id !== "string") return id;
 		return new RecordId(table, id.startsWith(`${table}:`) ? id.slice(table.length + 1) : id);
 	}
+	/**
+	* `(id, _00_rv)` of every row per table. Runs on the main thread against the
+	* embedded engine (no worker here), which is why the circuit prime caps how
+	* much it is willing to read through this path.
+	*/
+	async scanVersions(tables) {
+		const out = {};
+		for (const table of tables) try {
+			const [rows] = await this.query(`SELECT id, _00_rv FROM ${table};`);
+			out[table] = (rows ?? []).map((r) => [stableKey(r.id), Number(r._00_rv) || 0]);
+		} catch {
+			out[table] = [];
+		}
+		return out;
+	}
 	async getById(table, id) {
 		const [row] = await this.query("SELECT * FROM ONLY $__id;", { __id: this.toRecordId(table, id) });
 		return row && typeof row === "object" ? row : null;
@@ -2136,8 +2151,10 @@ var PortSqliteTransport = class extends BaseTransport {
 * on a fresh bucket throws "no such table". Keep in sync with the systemSchema
 * block in `local-migrator.ts`.
 */
+const SNAPSHOT_TABLE = "_00_circuit_snapshot";
 const SYSTEM_TABLES = [
 	"_00_stream_processor_state",
+	"_00_circuit_snapshot",
 	"_00_query",
 	"_00_preload",
 	"_00_window",
@@ -2259,7 +2276,7 @@ var SqliteCacheEngine = class {
 			diag.freelistBytes = rows?.[0]?.freelist;
 			if (opts?.tableCounts) {
 				const { rows: tables } = await this.call("exec", { sql: "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name" });
-				const names = (tables ?? []).map((r) => r.name);
+				const names = (tables ?? []).map((r) => r.name).filter((n) => n !== SNAPSHOT_TABLE);
 				if (names.length) {
 					const sql = names.map((n) => `SELECT '${n.replace(/'/g, "''")}' AS t, COUNT(*) AS n FROM "${n.replace(/"/g, "\"\"")}"`).join(" UNION ALL ");
 					const { rows: counts } = await this.call("exec", { sql });
@@ -2702,6 +2719,57 @@ var SqliteCacheEngine = class {
 		await this.ensureTable(table);
 		return (await this.execRows(`SELECT data FROM "${table}" WHERE id = ?`, [stableKey(id)]))[0] ?? null;
 	}
+	/**
+	* `(id, _00_rv)` of every row per table, straight off the worker: no body
+	* parse, one round trip per table. A table that does not exist yet reads as
+	* empty rather than failing the whole scan.
+	*/
+	async scanVersions(tables) {
+		const out = {};
+		for (const table of tables) try {
+			const { rows } = await this.call("exec", { sql: `SELECT id, json_extract(data, '$._00_rv') AS rv FROM "${table.replace(/"/g, "\"\"")}"` });
+			out[table] = (rows ?? []).map((r) => [r.id, Number(r.rv) || 0]);
+		} catch {
+			out[table] = [];
+		}
+		return out;
+	}
+	async getSnapshot(key) {
+		const { rows } = await this.call("exec", {
+			sql: `SELECT id, data FROM "${SNAPSHOT_TABLE}" WHERE id IN (?, ?)`,
+			bind: [key, `${key}:meta`]
+		});
+		let bytes = null;
+		let meta = null;
+		for (const r of rows ?? []) if (r.id === key) {
+			if (r.data instanceof Uint8Array) bytes = r.data;
+			else if (r.data instanceof ArrayBuffer) bytes = new Uint8Array(r.data);
+			else if (typeof r.data === "string") bytes = new TextEncoder().encode(r.data);
+		} else if (typeof r.data === "string") try {
+			meta = JSON.parse(r.data);
+		} catch {
+			meta = null;
+		}
+		return bytes && meta ? {
+			bytes,
+			meta
+		} : null;
+	}
+	async putSnapshot(key, bytes, meta) {
+		await this.call("batch", [{
+			sql: `INSERT OR REPLACE INTO "${SNAPSHOT_TABLE}" (id, data) VALUES (?, ?)`,
+			bind: [key, bytes]
+		}, {
+			sql: `INSERT OR REPLACE INTO "${SNAPSHOT_TABLE}" (id, data) VALUES (?, ?)`,
+			bind: [`${key}:meta`, JSON.stringify(meta)]
+		}]);
+	}
+	async deleteSnapshot(key) {
+		await this.call("run", {
+			sql: `DELETE FROM "${SNAPSHOT_TABLE}" WHERE id IN (?, ?)`,
+			bind: [key, `${key}:meta`]
+		});
+	}
 	async upsert(table, id, data, mode) {
 		await this.ensureTable(table);
 		const key = stableKey(id);
@@ -3253,12 +3321,6 @@ function phaseStatOf(samples, lastMs) {
 		count: samples.length
 	};
 }
-/**
-* DataModule - Unified query and mutation management
-*
-* Merges the functionality of QueryManager and MutationManager.
-* Uses CacheModule for all storage operations.
-*/
 var DataModule = class DataModule {
 	/** Tab identity baked into mutation ids (shared-tabs rollback routing);
 	*  undefined in solo mode, where mutation-id falls back to a session id. */
@@ -3962,23 +4024,42 @@ var DataModule = class DataModule {
 	* authoritative membership on this device. Any read error is treated as
 	* "unknown" so a broken row degrades to the predicate scan rather than
 	* rendering an empty list.
+	*
+	* `confirmed` is true only for rows written after the server itself vouched
+	* for the set (a non-empty id-set, or an empty one it reported a row count of
+	* zero for, or an empty one that followed a non-empty one in the same
+	* session). Rows written before the marker existed, including the `[]` rows a
+	* pre-`ea56f50e` client mirrored from an unflushed read, read as unconfirmed.
 	*/
 	async getWindowMembership(key) {
 		try {
 			const row = await this.local.getById("_00_window", new RecordId("_00_window", key));
 			if (!row || typeof row !== "object") return null;
 			const ids = row.ids;
-			return Array.isArray(ids) ? ids : null;
+			if (!Array.isArray(ids)) return null;
+			return {
+				ids,
+				confirmed: row.confirmed === true
+			};
 		} catch {
 			return null;
 		}
 	}
-	/** Persist the durable membership row. Best-effort: callers must not fail a
-	*  sync round because the mirror write failed. */
-	async writeWindowMembership(key, ids) {
+	/**
+	* Persist the durable membership row. Best-effort: callers must not fail a
+	* sync round because the mirror write failed.
+	*
+	* `confirmed` says whether a cold start may trust this row even when it is
+	* empty. A confirmed empty is a real answer ("the server says this query has
+	* no rows") and stays empty across a reload; an unconfirmed empty is the
+	* retry budget's guess and falls back to the predicate scan on the next boot,
+	* exactly as every empty row did before the marker existed.
+	*/
+	async writeWindowMembership(key, ids, confirmed) {
 		try {
 			await this.local.upsert("_00_window", new RecordId("_00_window", key), {
 				ids,
+				confirmed,
 				updatedAt: Date.now()
 			}, "replace");
 		} catch (err) {
@@ -4137,9 +4218,12 @@ var DataModule = class DataModule {
 			}, "Query to update remote array not found");
 			return;
 		}
+		let confirmed = remoteArray.length > 0 || queryState.config.remoteSeen === true;
 		if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
 			const serverRowCount = opts?.serverRowCount;
-			if (!(serverRowCount === 0)) {
+			const knownEmpty = serverRowCount === 0;
+			confirmed = knownEmpty;
+			if (!knownEmpty) {
 				const emptyReads = (queryState.config.emptyReads ?? 0) + 1;
 				queryState.config.emptyReads = emptyReads;
 				if (!(serverRowCount === null || serverRowCount === void 0 ? emptyReads >= EMPTY_MEMBERSHIP_CONFIRMATIONS : false)) {
@@ -4160,7 +4244,7 @@ var DataModule = class DataModule {
 			queryState.config.remoteSeen = true;
 			queryState.config.emptyReads = 0;
 		}
-		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
+		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray, confirmed);
 		try {
 			await this.local.query(surql.seal(surql.updateSet("id", ["remoteArray"])), {
 				id: queryState.config.id,
@@ -4213,8 +4297,8 @@ var DataModule = class DataModule {
 			config.emptyReads = 0;
 			if (config.membershipKey) {
 				const durable = await this.getWindowMembership(config.membershipKey);
-				if (durable?.length) {
-					config.remoteArray = durable;
+				if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+					config.remoteArray = durable.ids;
 					config.membershipKnown = true;
 				}
 			}
@@ -4644,8 +4728,8 @@ var DataModule = class DataModule {
 		};
 		if (membershipKey && !config.remoteArray?.length) {
 			const durable = await this.getWindowMembership(membershipKey);
-			if (durable?.length) {
-				config.remoteArray = durable;
+			if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+				config.remoteArray = durable.ids;
 				config.membershipKnown = true;
 			}
 		} else if (config.remoteArray?.length) config.membershipKnown = true;
@@ -5394,6 +5478,8 @@ function recordVersionArraysEqual(a, b) {
 
 //#endregion
 //#region src/modules/sync/engine.ts
+/** 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.
@@ -5424,51 +5510,59 @@ var SyncEngine = class {
 		}, "SyncEngine.syncRecords diff");
 		let stillRemoteIds = [];
 		if (removed.length > 0) stillRemoteIds = await this.handleRemovedRecords(removed);
-		const toFetch = [...added, ...updated];
-		const idsToFetch = toFetch.map((x) => x.id);
-		if (idsToFetch.length === 0) return {
+		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
 		};
 		const versionMap = /* @__PURE__ */ new Map();
 		for (const item of toFetch) versionMap.set(encodeRecordId(item.id), item.version);
-		const remoteFetchStart = performance.now();
-		const [remoteResults] = await this.remote.query("SELECT * FROM $idsToFetch", { idsToFetch });
-		const remoteFetchMs = performance.now() - remoteFetchStart;
-		const cacheBatch = [];
-		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;
+		const addedIds = new Set(added.map((item) => encodeRecordId(item.id)));
+		let remoteFetchMs = 0;
+		const remoteResults = [];
+		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("SELECT * FROM $idsToFetch", { idsToFetch });
+			remoteFetchMs += performance.now() - remoteFetchStart;
+			const cacheBatch = [];
+			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,
+					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,
-				version
-			});
+			if (cacheBatch.length > 0) await this.cache.saveBatch(cacheBatch);
 		}
-		if (cacheBatch.length > 0) await this.cache.saveBatch(cacheBatch);
 		this.events.emit(SyncEventTypes.RemoteDataIngested, { records: remoteResults });
 		return {
 			remoteFetchMs,
@@ -6005,14 +6099,37 @@ var Sp00kySync = class Sp00kySync {
 		this.tabRole = role;
 		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. */
-	async promoteToLeader(hub) {
+	/** In-flight {@link resumeLeaderDuties}, so a second call joins the first
+	*  instead of double-draining the outbox. */
+	leaderDutiesInFlight = 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. */
+	primeGate = () => 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. */
+	settledPrime = null;
+	setPrimeGate(gate) {
+		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.
+	*/
+	promoteToLeader(hub) {
 		this.tabRole = "leader";
 		this.hub = hub;
 		this.forwarder = null;
+		this.leaderDutiesInFlight = null;
 		hub.onFollowerMessage = (tabId, msg) => {
 			switch (msg.type) {
 				case "sync-hello": break;
@@ -6024,7 +6141,17 @@ var Sp00kySync = class Sp00kySync {
 					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. */
+	resumeLeaderDuties() {
+		if (this.leaderDutiesInFlight) return this.leaderDutiesInFlight;
+		const run = (async () => {
+			if (!this.isInit || this.tabRole !== "leader") return;
 			await this.upQueue.loadFromDatabase();
 			this.scheduler.syncUp();
 			if (this.currentUserId || this.anonLiveEnabled) {
@@ -6032,11 +6159,15 @@ var Sp00kySync = class Sp00kySync {
 				await this.restartRefLiveQuery().catch((err) => {
 					this.logger.warn({
 						err,
-						Category: "sp00ky-client::Sp00kySync::promoteToLeader"
+						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
 	*  leader; everything else (registration, per-query sync, poll) runs
@@ -6045,6 +6176,7 @@ var Sp00kySync = class Sp00kySync {
 		this.tabRole = "follower";
 		this.hub = null;
 		this.forwarder = forwarder;
+		this.leaderDutiesInFlight = null;
 		this.killRefLiveQuery();
 		forwarder.onLeaderMessage = (msg) => {
 			switch (msg.type) {
@@ -6694,6 +6826,16 @@ var Sp00kySync = class Sp00kySync {
 	* means the single resulting UI update lands after this completes.
 	*/
 	async runSyncForQuery(hash, diff) {
+		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;
+		}
 		if (diff.added.length > 0 || diff.updated.length > 0) {
 			const pendingDeletes = await this.getPendingDeleteIds();
 			if (pendingDeletes.size > 0) diff = {
@@ -7211,8 +7353,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.204";
-const WASM_VERSION = "0.0.1-canary.204";
+const CORE_VERSION = "0.0.1-canary.206";
+const WASM_VERSION = "0.0.1-canary.206";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7313,6 +7455,9 @@ var DevToolsService = class DevToolsService {
 				data: q.records,
 				localArray: q.config.localArray,
 				remoteArray: q.config.remoteArray,
+				membershipKnown: q.config.membershipKnown === true,
+				remoteSeen: q.config.remoteSeen === true,
+				emptyReads: q.config.emptyReads ?? 0,
 				timings: this.dataManager.phaseTimings(q)
 			});
 		});
@@ -7406,7 +7551,7 @@ var DevToolsService = class DevToolsService {
 			const info = this.unwrapInfo(res);
 			this.localTablesAt = Date.now();
 			if (info && info.tables) {
-				const names = Object.keys(info.tables);
+				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]);
 				this.localTables = names;
 				if (changed) this.notifyDevTools();
@@ -7936,13 +8081,29 @@ var AuthService = class {
 
 //#endregion
 //#region src/services/stream-processor/index.ts
-/**
-* Read a circuit snapshot out of the pre-`persistCircuit` persisted shape
-* (`[[{ state }]]`, a raw SurrealDB result). Returns null for anything else.
-*/
-function extractLegacyState(result) {
-	if (Array.isArray(result) && Array.isArray(result[0]) && typeof result[0][0]?.state === "string") return result[0][0].state;
-	return null;
+/** Storage key of the circuit snapshot inside the local store. */
+const CIRCUIT_SNAPSHOT_KEY = "circuit";
+/** Bump when the bytes `load_store_state` reads change shape. */
+const CIRCUIT_SNAPSHOT_FORMAT = 1;
+/** Rows per `ingest_many` call. Bounds the transient the wasm side allocates
+*  to parse a batch (measured: one 7700-row call of 20 KB bodies peaked at
+*  500 MB, 128-row chunks at 335 MB, and under projection at 24 MB). */
+const INGEST_CHUNK = 128;
+/** Ids per `selectByIds` when priming bodies out of the local store. */
+const PRIME_CHUNK = 256;
+/** Rows the SurrealDB (main-thread, IndexedDB) engine is allowed to prime
+*  through; above this the circuit boots empty as it always did. */
+const SURREAL_PRIME_ROW_CAP = 2e4;
+/** Below this many changed rows the checkpoint timer stays quiet. */
+const CHECKPOINT_MIN_ROWS = 50;
+/** Stable `table:id` for a row id that may already be a string. */
+function idString(id) {
+	return typeof id === "string" ? id : encodeRecordId(id);
+}
+function chunks(items, size) {
+	const out = [];
+	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+	return out;
 }
 var StreamProcessorService = class {
 	logger;
@@ -7955,18 +8116,23 @@ var StreamProcessorService = class {
 		authId: "",
 		access: ""
 	};
-	stateKeySuffix = "";
 	stateGeneration = 0;
 	persistState = true;
 	persistCircuit = false;
 	checkpointMs = 3e4;
 	checkpointTimer = null;
 	snapshotDirty = false;
-	pagehideHandler = null;
-	constructor(events, db, persistenceClient, logger) {
+	dirtyRows = 0;
+	hideHandler = null;
+	checkpointInFlight = null;
+	projection = true;
+	primed = Promise.resolve();
+	schemaHash = null;
+	widenQueue = Promise.resolve();
+	widenPending = /* @__PURE__ */ new Map();
+	constructor(events, db, logger) {
 		this.events = events;
 		this.db = db;
-		this.persistenceClient = persistenceClient;
 		this.logger = logger.child({ name: "StreamProcessorService" });
 	}
 	/**
@@ -7998,31 +8164,41 @@ var StreamProcessorService = class {
 		for (const update of updates) for (const receiver of this.receivers) receiver.onStreamUpdate(update);
 	}
 	/**
-	* Ingest a batch of record changes as a single bulk operation, firing only
-	* one coalesced `StreamUpdate` per affected query once every record has been
-	* ingested (instead of one update per record). Use this whenever multiple
-	* records land at once — e.g. sync fetching N missing rows — so a list query
-	* re-runs and the UI re-renders once for the whole batch rather than
-	* row-by-row.
+	* Ingest a batch of record changes, firing one coalesced `StreamUpdate` per
+	* affected query once every record has been ingested. Use this whenever
+	* multiple records land at once (sync fetching N rows, the boot prime).
+	*
+	* The batch is fed to the wasm side in chunks of {@link INGEST_CHUNK}: one
+	* circuit step per chunk (a step walks every registered view, so per-record
+	* ingest paid that fixed cost N times), but never the whole batch at once,
+	* because the wasm side has to hold every parsed row of a call at the same
+	* time and wasm32 dlmalloc never returns that peak.
 	*
-	* Internally opens a coalescing window, ingests each record, then flushes;
-	* processor state is persisted once for the whole batch. No-op for an empty
-	* batch.
+	* Returns the records that were ingested. A chunk that fails is reported
+	* and skipped, not retried (a retry would double-apply whatever the failed
+	* step already committed), and the remaining chunks still run.
 	*/
 	ingestMany(records) {
-		if (records.length === 0) return;
+		if (records.length === 0) return [];
 		if (!this.processor) {
 			this.logger.warn({ Category: "sp00ky-client::StreamProcessorService::ingestMany" }, "Not initialized, skipping ingest");
-			return;
+			return [];
 		}
 		const bulkIngest = this.processor.ingest_many;
-		if (typeof bulkIngest === "function") {
-			this.logger.debug({
-				count: records.length,
-				Category: "sp00ky-client::StreamProcessorService::ingestMany"
-			}, "Ingesting batch into ssp");
+		if (typeof bulkIngest !== "function") {
+			this.beginCoalescing();
 			try {
-				const items = records.map((record) => ({
+				for (const record of records) this.ingest(record.table, record.op, record.id, record.record);
+			} finally {
+				this.flushCoalescing();
+			}
+			return records;
+		}
+		const ingested = [];
+		this.beginCoalescing();
+		try {
+			for (const chunk of chunks(records, INGEST_CHUNK)) try {
+				const items = chunk.map((record) => ({
 					table: record.table,
 					op: record.op,
 					id: record.id,
@@ -8031,13 +8207,7 @@ var StreamProcessorService = class {
 				const t0 = performance.now();
 				const rawUpdates = bulkIngest.call(this.processor, items) ?? [];
 				const materializationTimeMs = performance.now() - t0;
-				this.logger.debug({
-					count: records.length,
-					rawUpdates: rawUpdates.length,
-					materializationTimeMs,
-					Category: "sp00ky-client::StreamProcessorService::ingestMany"
-				}, "Ingesting batch into ssp done");
-				if (rawUpdates.length > 0) this.dispatchUpdates(rawUpdates.map((u) => ({
+				if (rawUpdates.length > 0) this.notifyUpdates(rawUpdates.map((u) => ({
 					queryHash: u.query_id,
 					localArray: u.result_data,
 					op: "CREATE",
@@ -8046,22 +8216,24 @@ var StreamProcessorService = class {
 					circuitStepMs: u.timing_circuit_step_ms,
 					transformMs: u.timing_transform_ms
 				})));
+				ingested.push(...chunk);
 			} catch (e) {
 				this.logger.error({
 					error: e,
-					count: records.length,
+					count: chunk.length,
 					Category: "sp00ky-client::StreamProcessorService::ingestMany"
-				}, "Ingesting batch into ssp failed");
+				}, "Ingesting chunk into ssp failed");
 			}
-			this.markSnapshotDirty();
-			return;
-		}
-		this.beginCoalescing();
-		try {
-			for (const record of records) this.ingest(record.table, record.op, record.id, record.record);
 		} finally {
 			this.flushCoalescing();
 		}
+		this.logger.debug({
+			count: records.length,
+			ingested: ingested.length,
+			Category: "sp00ky-client::StreamProcessorService::ingestMany"
+		}, "Ingested batch into ssp");
+		this.markSnapshotDirty(ingested.length);
+		return ingested;
 	}
 	/**
 	* Open a coalescing window. While open, the per-record stream updates
@@ -8088,7 +8260,6 @@ var StreamProcessorService = class {
 		const buffered = Array.from(this.batchBuffer.values());
 		this.batchBuffer.clear();
 		if (buffered.length > 0) this.dispatchUpdates(buffered);
-		this.markSnapshotDirty();
 	}
 	/**
 	* Initialize the WASM module and processor.
@@ -8100,7 +8271,7 @@ var StreamProcessorService = class {
 		try {
 			await init();
 			this.processor = new Sp00kyProcessor();
-			await this.loadState();
+			this.applyProjection();
 			this.isInitialized = true;
 			this.logger.info({ Category: "sp00ky-client::StreamProcessorService::init" }, "Initialized successfully");
 		} catch (e) {
@@ -8111,21 +8282,16 @@ var StreamProcessorService = class {
 			throw e;
 		}
 	}
-	/** Route the persisted circuit snapshot to a per-bucket key. */
-	setStateKeySuffix(bucketId) {
-		this.stateKeySuffix = bucketId;
-	}
-	stateKey() {
-		return this.stateKeySuffix ? `_00_stream_processor_state:${this.stateKeySuffix}` : "_00_stream_processor_state";
-	}
 	/**
 	* Drop the current WASM processor and start a fresh, empty circuit. Used on
 	* local-bucket switches: the old circuit holds the previous user's rows AND
 	* views registered with the previous `$auth` context, so neither may survive.
-	* Deliberately does NOT `loadState()` — a persisted snapshot references views
-	* under a dead sessionId salt; the DataModule rebind re-registers every live
-	* view against this fresh processor. Caller must re-seed `setPermissions`
-	* afterwards (a fresh circuit default-denies every table).
+	* Deliberately loads nothing: the snapshot in the store being swapped away
+	* from belongs to the previous bucket; the caller primes the new bucket's
+	* circuit (`primeFromLocal`) once its store is open, and the DataModule
+	* rebind re-registers every live view against this fresh processor. Caller
+	* must re-seed `setPermissions` afterwards (a fresh circuit default-denies
+	* every table).
 	*/
 	async reset() {
 		if (!this.isInitialized) return;
@@ -8133,8 +8299,11 @@ var StreamProcessorService = class {
 		this.batching = false;
 		this.batchBuffer.clear();
 		this.snapshotDirty = false;
+		this.dirtyRows = 0;
+		this.widenPending.clear();
 		const previous = this.processor;
 		this.processor = new Sp00kyProcessor();
+		this.applyProjection();
 		this.freeProcessor(previous);
 		this.logger.info({ Category: "sp00ky-client::StreamProcessorService::reset" }, "Stream processor reset (fresh circuit)");
 	}
@@ -8174,9 +8343,9 @@ var StreamProcessorService = class {
 		if (!enabled) this.stopCheckpoints();
 	}
 	/**
-	* Opt into snapshot persistence (`persistCircuit`). Off by default: see the
-	* `persistCircuit` field comment for why per-ingest snapshots were removed.
-	* Must be called before `init()` for a snapshot to be restored at boot.
+	* Snapshot persistence (`persistCircuit`). When on, the circuit's store is
+	* written to the local store on a checkpoint interval and when the page
+	* goes hidden, and restored by {@link primeFromLocal} on the next boot.
 	*/
 	configureCircuitPersistence(enabled, checkpointMs) {
 		this.persistCircuit = enabled;
@@ -8184,59 +8353,291 @@ var StreamProcessorService = class {
 		if (!enabled) this.stopCheckpoints();
 	}
 	/**
-	* Record that the circuit changed. Cheap and O(1), the expensive snapshot is
-	* deferred to the checkpoint timer, and skipped entirely when
-	* `persistCircuit` is off (the default).
+	* Field projection (`circuitProjection`, default on). Takes effect on the
+	* next processor (`init`/`reset`) and on rows written after that.
 	*/
-	markSnapshotDirty() {
+	configureProjection(enabled) {
+		this.projection = enabled;
+		this.applyProjection();
+	}
+	applyProjection() {
+		if (!this.processor || typeof this.processor.set_projection !== "function") return;
+		try {
+			this.processor.set_projection(this.projection);
+		} catch (e) {
+			this.logger.warn({
+				error: e,
+				Category: "sp00ky-client::StreamProcessorService::applyProjection"
+			}, "set_projection failed");
+		}
+	}
+	/** Resolves once the boot-time prime has finished (or was skipped). */
+	whenPrimed() {
+		return this.primed;
+	}
+	/**
+	* Fill the circuit from the LOCAL store, in the background.
+	*
+	* With a usable snapshot: install it under whatever views have registered
+	* meanwhile (`load_store_state` re-primes them), then `reconcile` each table
+	* against the store's `(id, rv)` list so rows deleted since the checkpoint
+	* are stepped out and only rows added or changed since are read back and
+	* ingested. Without one: read every row and ingest it, chunked.
+	*
+	* Either way the circuit ends up equal to the local store without touching
+	* the network, so the first sync diff is a real delta rather than "fetch
+	* everything". The returned promise never rejects; `whenPrimed` gates on it.
+	*/
+	primeFromLocal(ctx) {
+		this.schemaHash = ctx.schemaHash;
+		const run = this.runPrime(ctx).catch((e) => {
+			this.logger.warn({
+				error: e,
+				Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+			}, "Circuit prime failed; the circuit fills from sync instead");
+		});
+		this.primed = run;
+		return run;
+	}
+	async runPrime(ctx) {
+		const processor = this.processor;
+		if (!processor || typeof this.db.scanVersions !== "function") return;
+		const generation = this.stateGeneration;
+		const epoch = this.db.epoch;
+		const alive = () => this.processor === processor && generation === this.stateGeneration && epoch === this.db.epoch;
+		const t0 = performance.now();
+		let restored = false;
+		if (this.persistCircuit && typeof this.db.getSnapshot === "function" && typeof processor.load_store_state === "function") {
+			const snapshot = await this.db.getSnapshot(CIRCUIT_SNAPSHOT_KEY);
+			if (!alive()) return;
+			if (snapshot) {
+				const { meta } = snapshot;
+				if (meta.formatVersion !== CIRCUIT_SNAPSHOT_FORMAT || meta.schemaHash !== ctx.schemaHash) this.logger.info({
+					meta,
+					Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+				}, "Circuit snapshot is from another format or schema; priming from rows");
+				else try {
+					const tLoad = performance.now();
+					const updates = processor.load_store_state(snapshot.bytes);
+					this.dispatchWasmUpdates(updates);
+					restored = true;
+					this.logger.info({
+						bytes: snapshot.bytes.byteLength,
+						views: updates.length,
+						loadMs: Math.round(performance.now() - tLoad),
+						Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+					}, "Circuit snapshot restored");
+				} catch (e) {
+					this.logger.warn({
+						error: e,
+						Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+					}, "Circuit snapshot unreadable; priming from rows");
+				}
+			}
+		}
+		const versions = await this.db.scanVersions(ctx.tables);
+		if (!alive()) return;
+		const total = Object.values(versions).reduce((n, v) => n + v.length, 0);
+		if (!restored && this.db.engineKind !== "sqlite" && total > SURREAL_PRIME_ROW_CAP) {
+			this.logger.warn({
+				total,
+				cap: SURREAL_PRIME_ROW_CAP,
+				Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+			}, "Too many cached rows to prime through the main-thread engine; circuit fills from sync");
+			return;
+		}
+		let ingested = 0;
+		let fetched = 0;
+		let deleted = 0;
+		for (const table of ctx.tables) {
+			const entries = versions[table] ?? [];
+			let toFetch;
+			if (restored && typeof processor.reconcile === "function") {
+				const result = processor.reconcile(table, entries);
+				this.dispatchWasmUpdates(result.updates);
+				deleted += result.deleted;
+				toFetch = result.fetch;
+			} else toFetch = entries.map(([id]) => id);
+			for (const chunk of chunks(toFetch, PRIME_CHUNK)) {
+				const rows = await this.db.selectByIds(table, chunk);
+				if (!alive()) return;
+				fetched += rows.length;
+				ingested += this.ingestMany(rows.map((row) => ({
+					table,
+					op: "CREATE",
+					id: idString(row.id),
+					record: row
+				}))).length;
+			}
+			if (entries.length > 0) ctx.onVersions?.(table, entries.filter(([id]) => !ctx.pendingIds.has(id)));
+		}
+		if (!restored && ingested > 0) this.markSnapshotDirty(Math.max(ingested, CHECKPOINT_MIN_ROWS));
+		this.logger.info({
+			restored,
+			rows: total,
+			fetched,
+			ingested,
+			deleted,
+			ms: Math.round(performance.now() - t0),
+			Category: "sp00ky-client::StreamProcessorService::primeFromLocal"
+		}, "Circuit primed from the local store");
+	}
+	/** Publish wasm updates produced outside an ingest (restore, reconcile). */
+	dispatchWasmUpdates(updates) {
+		if (!updates || updates.length === 0) return;
+		this.dispatchUpdates(updates.map((u) => ({
+			queryHash: u.query_id,
+			localArray: u.result_data,
+			op: "CREATE"
+		})));
+	}
+	/**
+	* Record that the circuit changed by `rows` rows. Cheap; the snapshot is
+	* deferred to the checkpoint timer and skipped entirely when `persistCircuit`
+	* is off.
+	*/
+	markSnapshotDirty(rows = 1) {
 		if (!this.persistCircuit || !this.persistState) return;
 		this.snapshotDirty = true;
+		this.dirtyRows += rows;
 		this.startCheckpoints();
 	}
 	startCheckpoints() {
 		if (this.checkpointTimer) return;
 		this.checkpointTimer = setInterval(() => {
-			if (!this.snapshotDirty) return;
-			this.snapshotDirty = false;
-			this.saveState();
+			if (!this.snapshotDirty || this.dirtyRows < CHECKPOINT_MIN_ROWS) return;
+			this.checkpoint("interval");
 		}, this.checkpointMs);
-		if (typeof window !== "undefined" && !this.pagehideHandler) {
-			this.pagehideHandler = () => {
+		if (typeof window !== "undefined" && !this.hideHandler) {
+			this.hideHandler = () => {
 				if (!this.snapshotDirty) return;
-				this.snapshotDirty = false;
-				this.saveState();
+				if (typeof document !== "undefined" && document.visibilityState === "visible") return;
+				this.checkpoint("hidden");
 			};
-			window.addEventListener("pagehide", this.pagehideHandler);
+			window.addEventListener("visibilitychange", this.hideHandler);
+			window.addEventListener("pagehide", this.hideHandler);
 		}
 	}
-	/** Stop checkpointing and drop the `pagehide` listener. */
+	/** Stop checkpointing and drop the visibility listeners. */
 	stopCheckpoints() {
 		if (this.checkpointTimer) {
 			clearInterval(this.checkpointTimer);
 			this.checkpointTimer = null;
 		}
-		if (this.pagehideHandler && typeof window !== "undefined") window.removeEventListener("pagehide", this.pagehideHandler);
-		this.pagehideHandler = null;
+		if (this.hideHandler && typeof window !== "undefined") {
+			window.removeEventListener("visibilitychange", this.hideHandler);
+			window.removeEventListener("pagehide", this.hideHandler);
+		}
+		this.hideHandler = null;
 		this.snapshotDirty = false;
+		this.dirtyRows = 0;
+	}
+	/**
+	* Write the circuit's store to the local store as a snapshot. Compacts the
+	* row arena first when dead bytes outweigh live ones. Serialised: a second
+	* call while one is in flight joins it. No-op unless persistence is on, this
+	* tab owns the store, and the engine can hold a snapshot.
+	*/
+	checkpoint(reason = "manual") {
+		if (this.checkpointInFlight) return this.checkpointInFlight;
+		const run = this.runCheckpoint(reason).finally(() => {
+			this.checkpointInFlight = null;
+		});
+		this.checkpointInFlight = run;
+		return run;
 	}
-	async loadState() {
-		if (!this.processor || !this.persistState || !this.persistCircuit) return;
+	async runCheckpoint(reason) {
+		const processor = this.processor;
+		if (!processor || !this.persistState || !this.persistCircuit || !this.schemaHash) return;
+		if (typeof this.db.putSnapshot !== "function" || typeof processor.save_store_state !== "function") return;
+		const generation = this.stateGeneration;
+		const epoch = this.db.epoch;
+		const rows = this.dirtyRows;
+		this.snapshotDirty = false;
+		this.dirtyRows = 0;
 		try {
-			const result = await this.persistenceClient.get(this.stateKey());
-			const state = typeof result === "string" ? result : extractLegacyState(result);
-			if (state) {
-				this.logger.info({
-					stateLength: state.length,
-					Category: "sp00ky-client::StreamProcessorService::loadState"
-				}, "Loading state from DB");
-				if (typeof this.processor.load_state === "function") this.processor.load_state(state);
-				else this.logger.warn({ Category: "sp00ky-client::StreamProcessorService::loadState" }, "load_state method not found on processor");
-			} else this.logger.info({ Category: "sp00ky-client::StreamProcessorService::loadState" }, "No saved state found");
+			const t0 = performance.now();
+			let reclaimed = 0;
+			if (typeof processor.compact === "function" && typeof processor.dead_bytes === "function" && typeof processor.live_bytes === "function") {
+				const dead = processor.dead_bytes();
+				if (dead > 1e6 && dead > processor.live_bytes()) reclaimed = processor.compact();
+			}
+			const bytes = processor.save_store_state();
+			const meta = {
+				formatVersion: CIRCUIT_SNAPSHOT_FORMAT,
+				schemaHash: this.schemaHash,
+				savedAt: Date.now(),
+				maxRv: typeof processor.max_row_versions === "function" ? processor.max_row_versions() : void 0
+			};
+			if (generation !== this.stateGeneration || epoch !== this.db.epoch) return;
+			await this.db.putSnapshot(CIRCUIT_SNAPSHOT_KEY, bytes, meta);
+			this.logger.info({
+				reason,
+				rows,
+				bytes: bytes.byteLength,
+				reclaimed,
+				ms: Math.round(performance.now() - t0),
+				Category: "sp00ky-client::StreamProcessorService::checkpoint"
+			}, "Circuit snapshot written");
 		} catch (e) {
-			this.logger.error({
+			this.logger.warn({
 				error: e,
-				Category: "sp00ky-client::StreamProcessorService::loadState"
-			}, "Failed to load state");
+				reason,
+				Category: "sp00ky-client::StreamProcessorService::checkpoint"
+			}, "Circuit snapshot failed");
+		}
+	}
+	/**
+	* Projection widening: a newly registered view evaluates fields that rows
+	* already in the circuit were stored without. Merge just those fields in,
+	* table by table, from the local store. The view registered against what
+	* was present and converges as the merges step through.
+	*/
+	scheduleWiden(missing) {
+		for (const [table, fields] of Object.entries(missing)) {
+			const set = this.widenPending.get(table) ?? /* @__PURE__ */ new Set();
+			for (const f of fields) set.add(f);
+			this.widenPending.set(table, set);
+		}
+		this.widenQueue = this.widenQueue.then(() => this.runWiden()).catch((e) => {
+			this.logger.warn({
+				error: e,
+				Category: "sp00ky-client::StreamProcessorService::widen"
+			}, "Projection widening failed");
+		});
+	}
+	async runWiden() {
+		const processor = this.processor;
+		if (!processor || typeof this.db.scanVersions !== "function") {
+			this.widenPending.clear();
+			return;
+		}
+		const generation = this.stateGeneration;
+		const epoch = this.db.epoch;
+		while (this.widenPending.size > 0) {
+			const [table, fields] = this.widenPending.entries().next().value;
+			this.widenPending.delete(table);
+			const select = Array.from(fields);
+			const versions = await this.db.scanVersions([table]);
+			if (this.processor !== processor || generation !== this.stateGeneration || epoch !== this.db.epoch) return;
+			const ids = (versions[table] ?? []).map(([id]) => id);
+			let merged = 0;
+			for (const chunk of chunks(ids, PRIME_CHUNK)) {
+				const rows = await this.db.selectByIds(table, chunk, { select });
+				if (this.processor !== processor || generation !== this.stateGeneration || epoch !== this.db.epoch) return;
+				merged += this.ingestMany(rows.map((row) => ({
+					table,
+					op: "MERGE",
+					id: idString(row.id),
+					record: row
+				}))).length;
+			}
+			this.logger.info({
+				table,
+				fields: select,
+				merged,
+				Category: "sp00ky-client::StreamProcessorService::widen"
+			}, "Widened projected rows with newly evaluated fields");
 		}
 	}
 	/**
@@ -8277,25 +8678,6 @@ var StreamProcessorService = class {
 			Category: "sp00ky-client::StreamProcessorService::setSessionAuth"
 		}, "Session auth context updated");
 	}
-	async saveState() {
-		if (!this.processor || !this.persistState || !this.persistCircuit) return;
-		const generation = this.stateGeneration;
-		try {
-			if (typeof this.processor.save_state === "function") {
-				const state = this.processor.save_state();
-				if (generation !== this.stateGeneration) return;
-				if (state) {
-					await this.persistenceClient.set(this.stateKey(), state);
-					this.logger.trace({ Category: "sp00ky-client::StreamProcessorService::saveState" }, "State saved");
-				}
-			}
-		} catch (e) {
-			this.logger.error({
-				error: e,
-				Category: "sp00ky-client::StreamProcessorService::saveState"
-			}, "Failed to save state");
-		}
-	}
 	/**
 	* Ingest a record change into the processor.
 	* Emits 'stream_update' event if materialized views are affected.
@@ -8329,7 +8711,7 @@ var StreamProcessorService = class {
 				const updates = rawUpdates.map((u) => ({
 					queryHash: u.query_id,
 					localArray: u.result_data,
-					op,
+					op: op === "MERGE" ? "UPDATE" : op,
 					materializationTimeMs,
 					storeApplyMs: u.timing_store_apply_ms,
 					circuitStepMs: u.timing_circuit_step_ms,
@@ -8390,7 +8772,7 @@ var StreamProcessorService = class {
 					snapshotMs: initialUpdate.timing_snapshot_ms ?? 0
 				}
 			};
-			this.markSnapshotDirty();
+			if (initialUpdate.missing_fields && Object.keys(initialUpdate.missing_fields).length > 0) this.scheduleWiden(initialUpdate.missing_fields);
 			this.logger.debug({
 				queryHash: queryPlan.queryHash,
 				surql: queryPlan.surql,
@@ -8413,7 +8795,6 @@ var StreamProcessorService = class {
 		if (!this.processor) return;
 		try {
 			this.processor.unregister_view(queryHash);
-			this.markSnapshotDirty();
 		} catch (e) {
 			this.logger.error({
 				error: e,
@@ -8544,6 +8925,16 @@ var CacheModule = class {
 	lookup(recordId) {
 		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.
+	*/
+	primeVersions(entries) {
+		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. */
 	clearVersionLookups() {
@@ -8592,9 +8983,10 @@ var CacheModule = class {
 				await this.local.execute(query, params, { epoch });
 			}
 			if (this.local.epoch !== epoch) throw new StaleEpochError();
+			const versionOf = /* @__PURE__ */ new Map();
 			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,
@@ -8602,8 +8994,9 @@ var CacheModule = class {
 					record: record.record
 				};
 			});
-			this.streamProcessor.ingestMany(bulk);
-			this.ingestRelay?.(bulk);
+			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);
 			this.logger.debug({
 				count: records.length,
 				Category: "sp00ky-client::CacheModule::saveBatch"
@@ -8638,7 +9031,12 @@ var CacheModule = class {
 			if (!skipDbDelete) await this.local.query("DELETE $id", { id: parseRecordIdString(id) }, { epoch });
 			if (this.local.epoch !== epoch) throw new StaleEpochError();
 			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",
@@ -10228,6 +10626,10 @@ var TabsCoordinator = class {
 	leadershipId = 0;
 	leaderTabId = null;
 	brokerRole = "pending";
+	/** Wall time from `become-leader` to `leader-ready` on the last promotion.
+	*  Reported in the DevTools role-change event: a slow store adopt (OPFS pool
+	*  contention after the previous leader died) shows up here as seconds. */
+	lastPromotionMs = null;
 	fingerprint;
 	bucketId;
 	broker;
@@ -10278,6 +10680,7 @@ var TabsCoordinator = class {
 			this.deps.logger.info({
 				role,
 				leadershipId: this.leadershipId,
+				promotionMs: role === "leader" ? this.lastPromotionMs : void 0,
 				Category: "sp00ky-client::TabsCoordinator"
 			}, "Tab role changed");
 			for (const cb of this.roleListeners) cb(role);
@@ -10354,6 +10757,7 @@ var TabsCoordinator = class {
 		if (this.closed) return;
 		if (msg.leadershipId <= this.leadershipId && !msg.resumeHeld) return;
 		const previousRole = this.role;
+		const startedAt = Date.now();
 		try {
 			if (previousRole === "follower") this.teardownFollower("promoted");
 			this.leadershipId = msg.leadershipId;
@@ -10375,7 +10779,8 @@ var TabsCoordinator = class {
 				resumeHeld: msg.resumeHeld
 			});
 			this.hub = new LeaderSyncHub(msg.leadershipId, this.deps.logger);
-			await this.deps.hooks.becomeSyncLeader(this.hub);
+			this.deps.hooks.becomeSyncLeader(this.hub);
+			this.lastPromotionMs = Date.now() - startedAt;
 			this.setRole("leader");
 			this.broker.send({
 				type: "leader-ready",
@@ -10383,6 +10788,12 @@ var TabsCoordinator = class {
 				bucketId: this.bucketId,
 				leadershipId: msg.leadershipId
 			});
+			this.deps.hooks.resumeSyncLeaderDuties().catch((e) => {
+				this.deps.logger.error({
+					err: e,
+					Category: "sp00ky-client::TabsCoordinator"
+				}, "Leader duties failed after promotion");
+			});
 		} catch (e) {
 			const reason = e instanceof Error ? e.message : String(e);
 			this.deps.logger.error({
@@ -11821,8 +12232,9 @@ var Sp00kyClient = class {
 		else if (config.persistenceClient === "localstorage" || !config.persistenceClient) this.persistenceClient = new LocalStoragePersistenceClient(logger);
 		else this.persistenceClient = config.persistenceClient;
 		this.persistenceClient = new ResilientPersistenceClient(this.persistenceClient, logger);
-		this.streamProcessor = new StreamProcessorService(new EventSystem(["stream_update"]), this.local, this.persistenceClient, logger);
-		this.streamProcessor.configureCircuitPersistence(config.persistCircuit ?? false, config.circuitCheckpointMs);
+		this.streamProcessor = new StreamProcessorService(new EventSystem(["stream_update"]), this.local, logger);
+		this.streamProcessor.configureCircuitPersistence(config.persistCircuit ?? config.localEngine === "sqlite", config.circuitCheckpointMs);
+		this.streamProcessor.configureProjection(config.circuitProjection ?? true);
 		this.migrator = new LocalMigrator(this.local, logger);
 		this.cache = new CacheModule(this.local, this.streamProcessor, (update) => {
 			this.dataModule.onStreamUpdate(update);
@@ -11838,6 +12250,7 @@ var Sp00kyClient = class {
 			downTimeoutMs: this.config.downTimeoutMs,
 			connectionSupervisor: this.connectionSupervisor
 		});
+		this.sync.setPrimeGate(() => this.streamProcessor.whenPrimed());
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: this.dataModule,
 			sync: this.sync,
@@ -11890,7 +12303,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.204",
+				coreVersion: "0.0.1-canary.206",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11907,13 +12320,14 @@ var Sp00kyClient = class {
 				onLeaderLost: (reason) => engine.onLeaderLost(reason),
 				exposeClientPort: (clientId, port) => engine.exposeClientPort(clientId, port),
 				removeClientPort: (clientId) => engine.removeClientPort(clientId),
-				becomeSyncLeader: async (hub) => {
+				becomeSyncLeader: (hub) => {
 					this.streamProcessor.setPersistenceEnabled(true);
 					this.cache.setIngestRelay((tuples) => hub.relayIngest(tuples));
 					this.sync.setTabContext("leader", tabId);
 					this.dataModule.setTabId(tabId);
-					await this.sync.promoteToLeader(hub);
+					this.sync.promoteToLeader(hub);
 				},
+				resumeSyncLeaderDuties: () => this.sync.resumeLeaderDuties(),
 				becomeSyncFollower: (forwarder) => {
 					this.streamProcessor.setPersistenceEnabled(false);
 					this.cache.setIngestRelay(null);
@@ -12007,6 +12421,13 @@ var Sp00kyClient = class {
 			if (this.tabsCoordinator) {
 				this.tabsCoordinator.onRoleChange((role) => {
 					this.sharedActive = role !== "solo";
+					this.devTools.logEvent("TABS_ROLE_CHANGED", {
+						role,
+						tabId: this.tabsCoordinator?.tabId,
+						leadershipId: this.tabsCoordinator?.leadershipId,
+						leaderTabId: this.tabsCoordinator?.leaderTabId,
+						promotionMs: this.tabsCoordinator?.lastPromotionMs
+					});
 				});
 				try {
 					const role = await this.tabsCoordinator.start(bootBucket);
@@ -12044,9 +12465,9 @@ var Sp00kyClient = class {
 					}, "Blob cache failed to start; bucket files will not be cached locally");
 				}
 			})();
-			this.streamProcessor.setStateKeySuffix(bootBucket);
 			await this.streamProcessor.init();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
+			this.primeCircuit();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "StreamProcessor initialized");
 			const restoredUserId = await this.auth.restoreSessionFromToken();
 			const sessionId = this.mintSessionSalt();
@@ -12215,10 +12636,10 @@ var Sp00kyClient = class {
 					Category: "sp00ky-client::Sp00kyClient::doSwitchBucket"
 				}, "Blob cache bucket switch failed");
 			}
-			this.streamProcessor.setStateKeySuffix(target);
 			await this.streamProcessor.reset();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
 			this.cache.clearVersionLookups();
+			this.primeCircuit();
 			this.preloadedHashes.clear();
 		} finally {
 			reopen();
@@ -12250,6 +12671,7 @@ var Sp00kyClient = class {
 		this.crdtManager.closeAll();
 		this.crdtManager.dispose();
 		await this.blobs.close().catch(() => {});
+		await this.streamProcessor.checkpoint("close").catch(() => {});
 		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();
@@ -12537,6 +12959,31 @@ var Sp00kyClient = class {
 	* the former to `encodeRecordId` reads `.table` off a string and throws
 	* during boot.
 	*/
+	/**
+	* Prime the in-browser circuit from the local store. Builds the context the
+	* stream processor needs: every synced table (the app schema plus the
+	* server-written meta tables that sync down), a schema hash so a snapshot
+	* projected under another schema is not trusted, and the ids whose local
+	* `_00_rv` was bumped by an unsettled mutation.
+	*/
+	async primeCircuit() {
+		const tables = [
+			...this.config.schema.tables.map((t) => t.name),
+			"_00_user_feature",
+			"_00_app_release"
+		];
+		let pendingIds = /* @__PURE__ */ new Set();
+		try {
+			const pending = await this.dataModule.getPendingRecordIds();
+			pendingIds = new Set([...pending.writes, ...pending.deletes]);
+		} catch {}
+		await this.streamProcessor.primeFromLocal({
+			tables,
+			schemaHash: String(hash53(this.config.schemaSurql)),
+			pendingIds,
+			onVersions: (_table, entries) => this.cache.primeVersions(entries)
+		});
+	}
 	sessionAuthId() {
 		const id = this.auth.currentUser?.id;
 		if (!id) return null;