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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as renderWhereSql, c as resolveRelations, i as renderOrderSql, l as stableKey, o as reviveRow, r as project, s as serializeRow, t as PROMOTION_OPEN_OPTIONS } from "./sqlite-open.js";
+import { a as renderOrderSql, c as serializeRow, i as projectedDataSql, l as resolveRelations, o as renderWhereSql, r as project, s as reviveRow, t as PROMOTION_OPEN_OPTIONS, u as stableKey } from "./sqlite-open.js";
 import { DateTime, Duration, RecordId, Surreal, Uuid, applyDiagnostics, createRemoteEngines } from "surrealdb";
 import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query-builder";
 import pino from "pino";
@@ -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 });
@@ -2658,16 +2675,15 @@ var SqliteCacheEngine = class {
 		}
 		await this.ensureTable(plan.table);
 		const bind = [];
-		let sql = `SELECT data FROM "${plan.table}"`;
+		let sql = `SELECT ${plan.select ? projectedDataSql(plan.select, bind) : "data"} FROM "${plan.table}"`;
 		if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
 		if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
 		else sql += ` ORDER BY id`;
 		if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
 		if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
 		const rows = await this.execRows(sql, bind);
-		const projected = plan.select ? rows.map((r) => project(r, plan.select)) : rows;
-		await resolveRelations(projected, plan.relations, this);
-		return projected;
+		await resolveRelations(rows, plan.relations, this);
+		return rows;
 	}
 	async fetchRelation(req) {
 		getStats().relationFetches++;
@@ -2686,19 +2702,74 @@ var SqliteCacheEngine = class {
 		if (ids.length === 0) return [];
 		await this.ensureTable(table);
 		const keys = ids.map(stableKey);
-		let sql = `SELECT data FROM "${table}" WHERE id IN (${keys.map(() => "?").join(", ")})`;
+		const placeholders = keys.map(() => "?").join(", ");
+		const bind = [];
+		const dataCol = opts?.select ? projectedDataSql(opts.select, bind) : "data";
+		bind.push(...keys);
+		let sql = `SELECT ${dataCol} FROM "${table}" WHERE id IN (${placeholders})`;
 		if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
-		let rows = await this.execRows(sql, keys);
+		let rows = await this.execRows(sql, bind);
 		if (!opts?.orderBy || opts.orderBy.length === 0) {
 			const pos = new Map(keys.map((k, i) => [k, i]));
 			rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
 		}
-		return opts?.select ? rows.map((r) => project(r, opts.select)) : rows;
+		return rows;
 	}
 	async getById(table, id) {
 		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);
@@ -3586,6 +3657,15 @@ var DataModule = class DataModule {
 	}
 	settledWrites = /* @__PURE__ */ new Map();
 	settledDeletes = /* @__PURE__ */ new Map();
+	pendingIds = null;
+	pendingIdsAt = 0;
+	pendingIdsInflight = null;
+	static PENDING_IDS_TTL_MS = 250;
+	/** Drop the cached outbox ids. Cheap; call it on anything that could change
+	*  `_00_pending_mutations`. */
+	invalidatePendingIds() {
+		this.pendingIds = null;
+	}
 	/**
 	* Grace period for a settled write. Long enough to cover an SSP round trip
 	* that is running slowly (seconds, not milliseconds, when the edge path is
@@ -3604,6 +3684,7 @@ var DataModule = class DataModule {
 	* disappear immediately, which is what makes this safe.
 	*/
 	noteWriteSettled(recordId, mutationType) {
+		this.invalidatePendingIds();
 		const until = Date.now() + DataModule.SETTLED_WRITE_GRACE_MS;
 		if (mutationType === "delete") this.settledDeletes.set(recordId, until);
 		else this.settledWrites.set(recordId, until);
@@ -3989,6 +4070,24 @@ var DataModule = class DataModule {
 	* briefly hide an optimistic write but never resurrects a deleted row.
 	*/
 	async getPendingRecordIds() {
+		const now = Date.now();
+		const cached = this.pendingIds;
+		if (cached && now - this.pendingIdsAt < DataModule.PENDING_IDS_TTL_MS) return {
+			writes: new Set(cached.writes),
+			deletes: new Set(cached.deletes)
+		};
+		if (!this.pendingIdsInflight) this.pendingIdsInflight = this.readPendingRecordIds().finally(() => {
+			this.pendingIdsInflight = null;
+		});
+		const fresh = await this.pendingIdsInflight;
+		return {
+			writes: new Set(fresh.writes),
+			deletes: new Set(fresh.deletes)
+		};
+	}
+	/** The uncached read. Also the reload path after an invalidation, so the ids
+	*  still survive a reload exactly as before. */
+	async readPendingRecordIds() {
 		const writes = /* @__PURE__ */ new Set();
 		const deletes = /* @__PURE__ */ new Set();
 		try {
@@ -4004,7 +4103,16 @@ var DataModule = class DataModule {
 				err,
 				Category: "sp00ky-client::DataModule::getPendingRecordIds"
 			}, "Failed to read pending mutations; optimistic writes may be briefly hidden");
+			return {
+				writes,
+				deletes
+			};
 		}
+		this.pendingIds = {
+			writes,
+			deletes
+		};
+		this.pendingIdsAt = Date.now();
 		return {
 			writes,
 			deletes
@@ -4321,6 +4429,7 @@ var DataModule = class DataModule {
 			record: target,
 			tableName
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -4374,6 +4483,7 @@ var DataModule = class DataModule {
 			beforeRecord: beforeRecord || void 0,
 			options: pushEventOptions
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -4419,6 +4529,7 @@ var DataModule = class DataModule {
 			mutation_id: mutationId,
 			record_id: rid
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -5071,9 +5182,43 @@ var DownQueue = class {
 	}
 	async next(fn) {
 		const event = this.queue.shift();
-		if (event) try {
+		if (!event) return;
+		const error = await this.run(event, fn);
+		if (error !== void 0) throw error;
+	}
+	/**
+	* The next event whose hash is NOT already being processed, or `undefined`
+	* when every remaining event is blocked on a busy hash.
+	*
+	* Ordering only ever mattered PER HASH — a `cleanup` must not overtake the
+	* `register` for the same query — but the queue enforced it globally, so one
+	* registration RPC at a time was the ceiling for the whole client. An event
+	* for a busy hash keeps its place here (it is skipped, not reordered), so
+	* per-hash ordering is preserved exactly while independent hashes proceed
+	* concurrently.
+	*/
+	takeNext(busy) {
+		for (let i = 0; i < this.queue.length; i++) {
+			const event = this.queue[i];
+			if (busy.has(event.payload.hash)) continue;
+			this.queue.splice(i, 1);
+			return event;
+		}
+	}
+	/**
+	* Process one event, applying the re-head / rotate failure policy.
+	*
+	* NEVER rejects: it RETURNS the error instead (`undefined` on success). A
+	* concurrent drain has other work in flight when one event fails, and a
+	* rejection would either take that work down with it or have to be caught at
+	* every call site. `next` reinstates the throwing contract for the serial
+	* callers that still want it.
+	*/
+	async run(event, fn) {
+		try {
 			await fn(event);
 			this.failures.delete(event);
+			return;
 		} catch (error) {
 			const attempts = (this.failures.get(event) ?? 0) + 1;
 			this.failures.set(event, attempts);
@@ -5087,7 +5232,7 @@ var DownQueue = class {
 				rotated: starvingOthers,
 				Category: "sp00ky-client::DownQueue::next"
 			}, "Failed to process query");
-			throw error;
+			return error;
 		}
 	}
 };
@@ -5317,6 +5462,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.
@@ -5347,51 +5494,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,
@@ -5452,6 +5607,17 @@ var SyncEngine = class {
 */
 /** Backoff for re-draining a queue that halted on an error. */
 const RETRY_BASE_MS = 500;
+/**
+* How many down events may be in flight at once.
+*
+* The down queue was strictly serial: one `register`/`sync`/`cleanup` RPC at a
+* time for the WHOLE client. Measured in production that drained at roughly one
+* event per 8.8s, so a list that registers a query per scrolled-to window took
+* minutes to fill — the rows were already cached, only the registration lagged.
+* Ordering is a per-hash requirement, not a global one (see `takeNext`), so
+* independent hashes can go in parallel. Bounded to stay polite to the SSP.
+*/
+const MAX_CONCURRENT_DOWN = 4;
 const RETRY_MAX_MS = 15e3;
 var SyncScheduler = class {
 	isSyncingUp = false;
@@ -5593,14 +5759,35 @@ var SyncScheduler = class {
 		}
 		this.isSyncingDown = true;
 		let processedAny = false;
+		const busy = /* @__PURE__ */ new Set();
+		const inFlight = /* @__PURE__ */ new Set();
+		let failure;
 		try {
-			while (this.downQueue.size > 0 && !this.paused) {
-				if (this.upQueue.size > 0) break;
-				await this.downQueue.next(this.onProcessDown);
-				processedAny = true;
+			for (;;) {
+				if (this.paused) break;
+				const yieldToUp = this.upQueue.size > 0;
+				while (failure === void 0 && !yieldToUp && inFlight.size < MAX_CONCURRENT_DOWN) {
+					const event = this.downQueue.takeNext(busy);
+					if (!event) break;
+					const hash = event.payload.hash;
+					busy.add(hash);
+					processedAny = true;
+					const task = this.downQueue.run(event, this.onProcessDown).then((error) => {
+						if (error !== void 0 && failure === void 0) failure = error;
+					}).finally(() => {
+						busy.delete(hash);
+						inFlight.delete(task);
+					});
+					inFlight.add(task);
+				}
+				if (inFlight.size === 0) break;
+				await Promise.race(inFlight);
+				if (yieldToUp && inFlight.size === 0) break;
 			}
+			if (failure !== void 0) throw failure;
 			if (processedAny) this.onSyncOutcome?.(true);
 			this.downRetryAttempt = 0;
+			if (this.downQueue.size > 0) this.scheduleDownRetry(RETRY_BASE_MS);
 		} catch (error) {
 			this.onSyncOutcome?.(false, error);
 			this.scheduleDownRetry();
@@ -5691,6 +5878,7 @@ var Sp00kySync = class Sp00kySync {
 	degradeAfterFailures;
 	/** Per-push RPC deadline; see {@link withPushTimeout}. */
 	pushTimeoutMs;
+	downTimeoutMs;
 	consecutiveSyncFailures = 0;
 	syncHealthStatus = "healthy";
 	lastSyncErrorKind;
@@ -5862,6 +6050,7 @@ var Sp00kySync = class Sp00kySync {
 		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 		this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
 		this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 3e4);
+		this.downTimeoutMs = Math.max(0, options?.downTimeoutMs ?? 3e4);
 		this.connectionSupervisor = options?.connectionSupervisor;
 	}
 	/**
@@ -5894,14 +6083,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;
@@ -5913,7 +6125,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) {
@@ -5921,11 +6143,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
@@ -5934,6 +6160,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) {
@@ -6544,6 +6771,12 @@ var Sp00kySync = class Sp00kySync {
 			event,
 			Category: "sp00ky-client::Sp00kySync::processDownEvent"
 		}, "Processing down event");
+		return this.withDownTimeout(this.runDownEvent(event), `${event.type} ${event.payload.hash}`);
+	}
+	withDownTimeout(promise, label) {
+		return withTimeout(promise, this.downTimeoutMs, `Down event timed out after ${this.downTimeoutMs}ms (${label})`);
+	}
+	async runDownEvent(event) {
 		switch (event.type) {
 			case "register": return this.registerQuery(event.payload.hash);
 			case "sync": return this.syncQuery(event.payload.hash);
@@ -6577,6 +6810,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 = {
@@ -7094,8 +7337,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.203";
-const WASM_VERSION = "0.0.1-canary.203";
+const CORE_VERSION = "0.0.1-canary.205";
+const WASM_VERSION = "0.0.1-canary.205";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7289,7 +7532,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();
@@ -7819,13 +8062,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;
@@ -7838,18 +8097,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" });
 	}
 	/**
@@ -7881,31 +8145,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,
@@ -7914,13 +8188,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",
@@ -7929,22 +8197,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
@@ -7971,7 +8241,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.
@@ -7983,7 +8252,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) {
@@ -7994,21 +8263,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;
@@ -8016,8 +8280,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)");
 	}
@@ -8057,9 +8324,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;
@@ -8067,59 +8334,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.
+	*/
+	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() {
+	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");
 		}
 	}
 	/**
@@ -8160,25 +8659,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.
@@ -8212,7 +8692,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,
@@ -8273,7 +8753,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,
@@ -8296,7 +8776,6 @@ var StreamProcessorService = class {
 		if (!this.processor) return;
 		try {
 			this.processor.unregister_view(queryHash);
-			this.markSnapshotDirty();
 		} catch (e) {
 			this.logger.error({
 				error: e,
@@ -8427,6 +8906,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() {
@@ -8475,9 +8964,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,
@@ -8485,8 +8975,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"
@@ -8521,7 +9012,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",
@@ -10111,6 +10607,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;
@@ -10161,6 +10661,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);
@@ -10237,6 +10738,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;
@@ -10258,7 +10760,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",
@@ -10266,6 +10769,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({
@@ -11704,8 +12213,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);
@@ -11718,8 +12228,10 @@ var Sp00kyClient = class {
 			anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
 			degradeAfterConsecutiveFailures: this.config.syncHealth === false ? 0 : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3,
 			pushTimeoutMs: this.config.pushTimeoutMs,
+			downTimeoutMs: this.config.downTimeoutMs,
 			connectionSupervisor: this.connectionSupervisor
 		});
+		this.sync.setPrimeGate(() => this.streamProcessor.whenPrimed());
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: this.dataModule,
 			sync: this.sync,
@@ -11772,7 +12284,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.203",
+				coreVersion: "0.0.1-canary.205",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11789,13 +12301,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);
@@ -11889,6 +12402,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);
@@ -11926,9 +12446,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();
@@ -12097,10 +12617,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();
@@ -12132,6 +12652,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();
@@ -12419,6 +12940,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;