@spooky-sync/core 0.0.1-canary.66 → 0.0.1-canary.67

package/dist/index.js

@@ -5,6 +5,11 @@ import pino from "pino";
 import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
 import { LoroDoc } from "loro-crdt";
 
+//#region src/types.ts
+/** Cap on the rolling materialization-sample window kept per query in memory. */
+const MATERIALIZATION_SAMPLE_WINDOW = 100;
+
+//#endregion
 //#region src/utils/surql.ts
 const surql = {
 	seal(query, options) {
@@ -40,6 +45,9 @@ const surql = {
 	upsert(idVar, dataVar) {
 		return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
 	},
+	upsertMerge(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
+	},
 	updateMerge(idVar, dataVar) {
 		return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
 	},
@@ -216,6 +224,8 @@ var DataModule = class {
 	mutationCallbacks = /* @__PURE__ */ new Set();
 	debounceTimers = /* @__PURE__ */ new Map();
 	logger;
+	sessionId = "";
+	currentUserId = null;
 	constructor(cache, local, schema, logger, streamDebounceTime = 100) {
 		this.cache = cache;
 		this.local = local;
@@ -223,8 +233,35 @@ var DataModule = class {
 		this.streamDebounceTime = streamDebounceTime;
 		this.logger = logger.child({ service: "DataModule" });
 	}
-	async init() {
-		this.logger.info({ Category: "sp00ky-client::DataModule::init" }, "DataModule initialized");
+	async init(sessionId) {
+		this.sessionId = sessionId;
+		this.logger.info({
+			sessionId,
+			Category: "sp00ky-client::DataModule::init"
+		}, "DataModule initialized");
+	}
+	/**
+	* Update the session salt used in query-id hashing. Call this when the
+	* SurrealDB session changes (sign-in, sign-out, reconnect). Subsequently
+	* registered queries will get fresh, session-scoped IDs.
+	*/
+	setSessionId(sessionId) {
+		this.sessionId = sessionId;
+	}
+	/**
+	* Update the authenticated user record id. Pass `null` on sign-out.
+	* Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
+	* the poll route to the same per-user `_00_list_ref_user_<id>` the
+	* SSP writes to.
+	*/
+	setCurrentUserId(userId) {
+		this.currentUserId = userId;
+	}
+	/** Read-only view of the authenticated user id used for per-user
+	* `_00_list_ref` routing. Other modules consult this so they pick the
+	* same table name DataModule does. */
+	getCurrentUserId() {
+		return this.currentUserId;
 	}
 	/**
 	* Register a query and return its hash for subscriptions
@@ -309,7 +346,7 @@ var DataModule = class {
 		} else await this.processStreamUpdate(update);
 	}
 	async processStreamUpdate(update) {
-		const { queryHash, localArray } = update;
+		const { queryHash, localArray, materializationTimeMs } = update;
 		const queryState = this.activeQueries.get(queryHash);
 		if (!queryState) {
 			this.logger.warn({
@@ -318,25 +355,46 @@ var DataModule = class {
 			}, "Received update for unknown query. Skipping...");
 			return;
 		}
+		if (typeof materializationTimeMs === "number") {
+			queryState.materializationSamples.push(materializationTimeMs);
+			if (queryState.materializationSamples.length > MATERIALIZATION_SAMPLE_WINDOW) queryState.materializationSamples.shift();
+			queryState.lastIngestLatencyMs = materializationTimeMs;
+		}
+		const percentiles = this.computeMaterializationPercentiles(queryState.materializationSamples);
 		try {
 			const [records] = await this.local.query(queryState.config.surql, queryState.config.params);
 			const newRecords = records || [];
 			queryState.config.localArray = localArray;
-			await this.local.query(surql.seal(surql.updateSet("id", ["localArray"])), {
-				id: queryState.config.id,
-				localArray
-			});
 			const prevJson = JSON.stringify(queryState.records);
 			const newJson = JSON.stringify(newRecords);
 			queryState.records = newRecords;
-			if (prevJson === newJson) {
+			const recordsChanged = prevJson !== newJson;
+			if (recordsChanged) queryState.updateCount++;
+			await this.local.query(surql.seal(surql.updateSet("id", [
+				"localArray",
+				"rowCount",
+				"updateCount",
+				"lastIngestLatency",
+				"materializationP55",
+				"materializationP90",
+				"materializationP99"
+			])), {
+				id: queryState.config.id,
+				localArray,
+				rowCount: localArray.length,
+				updateCount: queryState.updateCount,
+				lastIngestLatency: queryState.lastIngestLatencyMs,
+				materializationP55: percentiles.p55,
+				materializationP90: percentiles.p90,
+				materializationP99: percentiles.p99
+			});
+			if (!recordsChanged) {
 				this.logger.debug({
 					queryHash,
 					Category: "sp00ky-client::DataModule::onStreamUpdate"
 				}, "Query records unchanged, skipping notification");
 				return;
 			}
-			queryState.updateCount++;
 			const subscribers = this.subscriptions.get(queryHash);
 			if (subscribers) for (const callback of subscribers) callback(queryState.records);
 			this.logger.debug({
@@ -345,14 +403,48 @@ var DataModule = class {
 				Category: "sp00ky-client::DataModule::onStreamUpdate"
 			}, "Query updated from stream");
 		} catch (err) {
+			queryState.errorCount++;
 			this.logger.error({
 				err,
 				queryHash,
 				Category: "sp00ky-client::DataModule::onStreamUpdate"
 			}, "Failed to fetch records for stream update");
+			try {
+				await this.local.query(surql.seal(surql.updateSet("id", ["errorCount"])), {
+					id: queryState.config.id,
+					errorCount: queryState.errorCount
+				});
+			} catch (persistErr) {
+				this.logger.warn({
+					err: persistErr,
+					queryHash,
+					Category: "sp00ky-client::DataModule::onStreamUpdate"
+				}, "Failed to persist incremented errorCount");
+			}
 		}
 	}
 	/**
+	* Compute p55/p90/p99 from a rolling window of materialization samples.
+	* Returns nulls for any percentile that has no samples yet so SurrealDB
+	* `option<float>` columns stay NONE rather than 0 before the first ingest.
+	*/
+	computeMaterializationPercentiles(samples) {
+		if (samples.length === 0) return {
+			p55: null,
+			p90: null,
+			p99: null
+		};
+		const sorted = [...samples].sort((a, b) => a - b);
+		const pick = (q) => {
+			return sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))];
+		};
+		return {
+			p55: pick(.55),
+			p90: pick(.9),
+			p99: pick(.99)
+		};
+	}
+	/**
 	* Get query state (for sync and devtools)
 	*/
 	getQueryByHash(hash) {
@@ -370,6 +462,9 @@ var DataModule = class {
 	getActiveQueries() {
 		return Array.from(this.activeQueries.values());
 	}
+	getActiveQueryHashes() {
+		return Array.from(this.activeQueries.keys());
+	}
 	async updateQueryLocalArray(id, localArray) {
 		const queryState = this.activeQueries.get(id);
 		if (!queryState) {
@@ -644,6 +739,7 @@ var DataModule = class {
 			ttl,
 			tableName
 		});
+		const t0 = performance.now();
 		const { localArray } = this.cache.registerQuery({
 			queryHash: hash,
 			surql: surqlString,
@@ -651,9 +747,16 @@ var DataModule = class {
 			ttl: new Duration(ttl),
 			lastActiveAt: /* @__PURE__ */ new Date()
 		});
-		await withRetry(this.logger, () => this.local.query(surql.seal(surql.updateSet("id", ["localArray"])), {
+		const registrationTime = performance.now() - t0;
+		await withRetry(this.logger, () => this.local.query(surql.seal(surql.updateSet("id", [
+			"localArray",
+			"registrationTime",
+			"rowCount"
+		])), {
 			id: recordId,
-			localArray
+			localArray,
+			registrationTime,
+			rowCount: localArray.length
 		}));
 		this.activeQueries.set(hash, queryState);
 		this.startTTLHeartbeat(queryState);
@@ -678,8 +781,12 @@ var DataModule = class {
 					localArray: [],
 					remoteArray: [],
 					lastActiveAt: /* @__PURE__ */ new Date(),
+					createdAt: /* @__PURE__ */ new Date(),
 					ttl,
-					tableName
+					tableName,
+					updateCount: 0,
+					rowCount: 0,
+					errorCount: 0
 				}
 			}));
 			configRecord = createdRecord;
@@ -699,16 +806,24 @@ var DataModule = class {
 				Category: "sp00ky-client::DataModule::createNewQuery"
 			}, "Failed to load initial cached records");
 		}
+		const persistedUpdateCount = typeof configRecord?.updateCount === "number" ? configRecord.updateCount : 0;
+		const persistedErrorCount = typeof configRecord?.errorCount === "number" ? configRecord.errorCount : 0;
 		return {
 			config,
 			records,
 			ttlTimer: null,
 			ttlDurationMs: parseDuration(ttl),
-			updateCount: 0
+			updateCount: persistedUpdateCount,
+			materializationSamples: [],
+			lastIngestLatencyMs: null,
+			errorCount: persistedErrorCount
 		};
 	}
 	async calculateHash(data) {
-		const content = JSON.stringify(data);
+		const content = JSON.stringify({
+			...data,
+			sessionId: this.sessionId
+		});
 		const msgBuffer = new TextEncoder().encode(content);
 		const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
 		return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -1584,6 +1699,65 @@ function createDiffFromDbOp(op, recordId, version, versions) {
 		removed: [recordId]
 	};
 }
+/**
+* Default cadence for the `_00_list_ref_user_<id>` poll fallback. The
+* poll is the safety net for SurrealDB v3's occasionally-dropped LIVE
+* deliveries; 500ms is aggressive enough to feel real-time on the
+* happy path while keeping the per-session query load bounded.
+*/
+const DEFAULT_LIST_REF_POLL_INTERVAL_MS = 500;
+/**
+* Build the SurrealQL select that powers both the initial-fetch and
+* the periodic poll of `_00_list_ref[_user_<id>]`. The `parent IS NONE`
+* predicate excludes subquery entries (rows with `parent_rel` set)
+* because the client's `RecordVersionArray` only tracks primary rows;
+* including subquery rows would surface them as spurious "added"
+* diffs every tick.
+*/
+function buildListRefSelect(table) {
+	return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NONE`;
+}
+/**
+* Resolve the effective list-ref poll interval. Negative or zero
+* values fall back to the default — accepting them would either
+* disable polling silently or busy-loop the event loop.
+*/
+function resolveListRefPollInterval(opt) {
+	if (typeof opt !== "number" || !Number.isFinite(opt) || opt <= 0) return DEFAULT_LIST_REF_POLL_INTERVAL_MS;
+	return opt;
+}
+/**
+* When the LIVE feed has delivered an event within this window, treat
+* the LIVE subscription as healthy and back the poll off to
+* {@link LIVE_HEALTHY_POLL_INTERVAL_MS}. As soon as LIVE quiets for
+* longer than this, the poll snaps back to the aggressive default.
+*/
+const LIVE_HEALTHY_COOLDOWN_MS = 5e3;
+/**
+* Poll interval while LIVE is delivering events. The aggressive
+* default 500ms costs ~120 queries / minute / session — wasted work
+* when LIVE is already covering us. 5s keeps the safety net in place
+* at 1/10th the load.
+*/
+const LIVE_HEALTHY_POLL_INTERVAL_MS = 5e3;
+/**
+* Pick the next poll delay based on whether LIVE has been healthy
+* recently. If a LIVE event fired within `cooldownMs`, use the slow
+* (`healthyIntervalMs`) cadence; otherwise the fast (`baseIntervalMs`)
+* cadence. Pure so it's unit-testable; `Sp00kySync.startListRefPoll`
+* calls it from a self-rescheduling timer.
+*
+* The healthy interval is clamped to at least `baseIntervalMs` so
+* configuring an aggressive base (e.g. 100ms) never gets implicitly
+* widened by this helper.
+*/
+function nextPollDelayMs(args) {
+	const { now, lastLiveEventAt, baseIntervalMs, cooldownMs = LIVE_HEALTHY_COOLDOWN_MS, healthyIntervalMs = LIVE_HEALTHY_POLL_INTERVAL_MS } = args;
+	if (lastLiveEventAt === null) return baseIntervalMs;
+	const sinceLive = now - lastLiveEventAt;
+	if (sinceLive < 0 || sinceLive >= cooldownMs) return baseIntervalMs;
+	return Math.max(healthyIntervalMs, baseIntervalMs);
+}
 
 //#endregion
 //#region src/modules/sync/engine.ts
@@ -1660,18 +1834,46 @@ var SyncEngine = class {
 	}
 	/**
 	* Handle records that exist locally but not in remote array.
+	*
+	* "Removed" here is a derived signal: the SSP's `_00_list_ref` array no
+	* longer references a record that exists locally. That can mean the row
+	* was genuinely deleted upstream — but it can also be a benign race
+	* (e.g. a record we just created hasn't propagated into the SSP's
+	* incantation list yet). Before deleting locally we verify against
+	* upstream SurrealDB: if the row still exists there, skip the delete.
+	*
+	* On verification failure we skip deletion too. Losing a stale local
+	* row to a later sync round is recoverable; deleting a fresh row that
+	* upstream still has is not.
 	*/
 	async handleRemovedRecords(removed) {
 		this.logger.debug({
 			removed: removed.map((r) => r.toString()),
 			Category: "sp00ky-client::SyncEngine::handleRemovedRecords"
 		}, "Checking removed records");
-		let existingRemoteIds = /* @__PURE__ */ new Set();
+		const byTable = /* @__PURE__ */ new Map();
+		for (const r of removed) {
+			const list = byTable.get(r.table.name) ?? [];
+			list.push(r);
+			byTable.set(r.table.name, list);
+		}
+		let existingRemoteIds;
 		try {
-			const [existingRemote] = await this.remote.query("SELECT id FROM $ids", { ids: removed });
-			existingRemoteIds = new Set(existingRemote.map((r) => encodeRecordId(r.id)));
-		} catch {
-			this.logger.debug({ Category: "sp00ky-client::SyncEngine::handleRemovedRecords" }, "Remote existence check failed, proceeding with deletion");
+			existingRemoteIds = /* @__PURE__ */ new Set();
+			for (const [table, ids] of byTable) {
+				const [existing] = await this.remote.query("SELECT id FROM type::table($table) WHERE id IN $ids", {
+					table,
+					ids
+				});
+				for (const row of existing) existingRemoteIds.add(encodeRecordId(row.id));
+			}
+		} catch (err) {
+			this.logger.warn({
+				err,
+				removed: removed.map((r) => r.toString()),
+				Category: "sp00ky-client::SyncEngine::handleRemovedRecords"
+			}, "Remote existence check failed, skipping deletion to avoid clobbering fresh data");
+			return;
 		}
 		for (const recordId of removed) {
 			const recordIdStr = encodeRecordId(recordId);
@@ -1754,6 +1956,45 @@ var SyncScheduler = class {
 	}
 };
 
+//#endregion
+//#region src/modules/ref-tables.ts
+/**
+* Default ref-storage mode for this client build. Mirrors the SSP's
+* default (`RefMode::Dedicated`) so cross-session sync works out of the
+* box.
+*/
+const DEFAULT_REF_MODE = "dedicated";
+/**
+* Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+* goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+* the id is missing the `user:` prefix or contains characters that
+* aren't valid in a SurrealDB table identifier — the server-side
+* `ssp_protocol::sanitize_user_id` uses the same predicate.
+*
+* Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+* objects (which only stringify cleanly via `.toString()`), since
+* `AuthService` passes the record-id object as-is to its subscribers.
+*/
+function sanitizeUserId(userId) {
+	if (userId === null || userId === void 0) return null;
+	const asString = typeof userId === "string" ? userId : typeof userId.toString === "function" ? userId.toString() : null;
+	if (!asString) return null;
+	const raw = asString.startsWith("user:") ? asString.slice(5) : asString;
+	if (raw.length === 0) return null;
+	if (!/^[A-Za-z0-9_]+$/.test(raw)) return null;
+	return raw;
+}
+/**
+* Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+* back to the global `_00_list_ref` when sanitization fails or in
+* single mode.
+*/
+function listRefTableFor(mode, userId) {
+	if (mode === "single") return "_00_list_ref";
+	const uid = sanitizeUserId(userId);
+	return uid ? `_00_list_ref_user_${uid}` : "_00_list_ref";
+}
+
 //#endregion
 //#region src/modules/sync/sync.ts
 /**
@@ -1763,14 +2004,32 @@ var SyncScheduler = class {
 * @template S The schema structure type.
 */
 var Sp00kySync = class {
-	clientId = "";
 	upQueue;
 	downQueue;
 	isInit = false;
 	logger;
 	syncEngine;
+	/** Engine-level events (e.g. `SYNC_REMOTE_DATA_INGESTED`). Distinct
+	*  from `this.events`, which carries Sp00kySync-level events like
+	*  `SYNC_QUERY_UPDATED` and `SYNC_MUTATION_ROLLED_BACK`. */
+	get engineEvents() {
+		return this.syncEngine.events;
+	}
 	scheduler;
+	wasDisconnected = false;
 	events = createSyncEventSystem();
+	currentUserId = null;
+	refMode = DEFAULT_REF_MODE;
+	currentLiveQueryUuid = null;
+	liveQueryUnsubscribe = null;
+	listRefPollTimer = null;
+	listRefPollRunning = false;
+	refSyncIntervalMs;
+	lastLiveEventAt = null;
+	_liveRetryCount = 0;
+	get liveRetryCount() {
+		return this._liveRetryCount;
+	}
 	get isSyncing() {
 		return this.scheduler.isSyncing;
 	}
@@ -1785,7 +2044,7 @@ var Sp00kySync = class {
 			this.upQueue.events.unsubscribe(id2);
 		};
 	}
-	constructor(local, remote, cache, dataModule, schema, logger) {
+	constructor(local, remote, cache, dataModule, schema, logger, options) {
 		this.local = local;
 		this.remote = remote;
 		this.cache = cache;
@@ -1796,29 +2055,199 @@ var Sp00kySync = class {
 		this.downQueue = new DownQueue(this.local, this.logger);
 		this.syncEngine = new SyncEngine(this.remote, this.cache, this.schema, this.logger);
 		this.scheduler = new SyncScheduler(this.upQueue, this.downQueue, this.processUpEvent.bind(this), this.processDownEvent.bind(this), this.logger, this.handleRollback.bind(this));
+		this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
 	}
 	/**
 	* Initializes the synchronization system.
 	* Starts the scheduler and initiates the initial sync cycles.
-	* @param clientId The unique identifier for this client instance.
 	* @throws Error if already initialized.
 	*/
-	async init(clientId) {
+	async init() {
 		if (this.isInit) throw new Error("Sp00kySync is already initialized");
-		this.clientId = clientId;
 		this.isInit = true;
 		await this.scheduler.init();
+		this.subscribeToReconnect();
 		this.scheduler.syncUp();
 		this.scheduler.syncDown();
-		this.startRefLiveQueries();
+	}
+	/**
+	* Push the authenticated user's record id from the parent client's
+	* auth subscription. Tears down the existing `_00_list_ref` LIVE (if
+	* any) and re-registers it under the new user's dedicated table so
+	* SurrealDB binds the permission rule under the post-flip auth
+	* context. Pass `null` on sign-out.
+	*
+	* The dedicated `_00_list_ref_user_<id>` table is created lazily by
+	* the SSP when the first query registration arrives, which may be
+	* concurrent with this call. We retry the LIVE registration with a
+	* short backoff so a "table not found" race resolves without
+	* surfacing as a permanent auth-loading hang.
+	*/
+	async setCurrentUserId(userId) {
+		if (this.currentUserId === userId) return;
+		this.currentUserId = userId;
+		if (!userId) {
+			await this.killRefLiveQuery();
+			this.stopListRefPoll();
+			return;
+		}
+		this.startListRefPoll();
+		const attemptDelays = [
+			0,
+			250,
+			500,
+			1e3,
+			2e3
+		];
+		for (let i = 0; i < attemptDelays.length; i++) {
+			if (attemptDelays[i] > 0) {
+				this._liveRetryCount++;
+				await new Promise((r) => setTimeout(r, attemptDelays[i]));
+			}
+			try {
+				await this.restartRefLiveQuery();
+				return;
+			} catch (err) {
+				this.logger.debug({
+					err,
+					attempt: i + 1,
+					Category: "sp00ky-client::Sp00kySync::setCurrentUserId"
+				}, "Ref LIVE start failed; relying on periodic poll fallback");
+			}
+		}
+	}
+	startListRefPoll() {
+		if (this.listRefPollRunning) return;
+		this.listRefPollRunning = true;
+		this.logger.debug({
+			intervalMs: this.refSyncIntervalMs,
+			Category: "sp00ky-client::Sp00kySync::startListRefPoll"
+		}, "list_ref poll loop started");
+		const schedule = (delayMs) => {
+			this.listRefPollTimer = setTimeout(async () => {
+				if (!this.listRefPollRunning) return;
+				try {
+					await this.pollListRefForActiveQueries();
+				} finally {
+					if (!this.listRefPollRunning) return;
+					schedule(nextPollDelayMs({
+						now: Date.now(),
+						lastLiveEventAt: this.lastLiveEventAt,
+						baseIntervalMs: this.refSyncIntervalMs
+					}));
+				}
+			}, delayMs);
+		};
+		schedule(this.refSyncIntervalMs);
+	}
+	stopListRefPoll() {
+		this.listRefPollRunning = false;
+		if (this.listRefPollTimer !== null) {
+			clearTimeout(this.listRefPollTimer);
+			this.listRefPollTimer = null;
+		}
+	}
+	async pollListRefForActiveQueries() {
+		const hashes = this.dataModule.getActiveQueryHashes();
+		if (hashes.length === 0) return;
+		for (const hash of hashes) try {
+			await this.refetchListRefForQuery(hash);
+		} catch (err) {
+			this.logger.debug({
+				err: err?.message ?? err,
+				hash,
+				Category: "sp00ky-client::Sp00kySync::pollListRefForActiveQueries"
+			}, "Per-query list_ref poll failed");
+		}
+	}
+	/**
+	* Pull the upstream list_ref entries for `queryHash`, diff them
+	* against the local `remoteArray` cache, sync any added/updated rows
+	* through the SyncEngine, then persist the new remoteArray. This is
+	* the same shape `createRemoteQuery` does for its initial fetch and
+	* what `handleRemoteListRefChange` does per-LIVE-event — we reuse
+	* it on a timer as a fallback for missed LIVE notifications.
+	*/
+	async refetchListRefForQuery(queryHash) {
+		const queryState = this.dataModule.getQueryByHash(queryHash);
+		if (!queryState) return;
+		const listRefTbl = this.listRefTable();
+		const [items] = await this.remote.query(buildListRefSelect(listRefTbl), { in: queryState.config.id });
+		if (!Array.isArray(items)) return;
+		const fresh = items.map((item) => [encodeRecordId(item.out), item.version]);
+		await this.dataModule.updateQueryRemoteArray(queryHash, fresh);
+		try {
+			await this.syncQuery(queryHash);
+		} catch (err) {
+			this.logger.info({
+				err: err?.message ?? err,
+				queryHash,
+				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
+			}, "syncQuery failed during poll");
+		}
+	}
+	/**
+	* Resolve the current `_00_list_ref` table name for the active auth
+	* context. Public so the `createRemoteQuery` initial-fetch path can
+	* read from the right per-user table.
+	*
+	* Reads the user id from `DataModule` rather than the local mirror,
+	* because `DataModule.setCurrentUserId` runs synchronously from the
+	* auth callback (before any `await`), whereas `sync.setCurrentUserId`
+	* is async — the userQuery's initial fetch can fire between those
+	* two points and we need the correct table name immediately.
+	*/
+	listRefTable() {
+		return listRefTableFor(this.refMode, this.dataModule.getCurrentUserId());
+	}
+	async killRefLiveQuery() {
+		if (this.liveQueryUnsubscribe) {
+			try {
+				this.liveQueryUnsubscribe();
+			} catch {}
+			this.liveQueryUnsubscribe = null;
+		}
+		if (this.currentLiveQueryUuid !== null) {
+			try {
+				await this.remote.query("KILL $u", { u: this.currentLiveQueryUuid });
+			} catch (err) {
+				this.logger.debug({
+					err,
+					Category: "sp00ky-client::Sp00kySync::killRefLiveQuery"
+				}, "Prior LIVE KILL failed; continuing");
+			}
+			this.currentLiveQueryUuid = null;
+		}
+	}
+	async restartRefLiveQuery() {
+		await this.killRefLiveQuery();
+		await this.startRefLiveQueries();
+	}
+	subscribeToReconnect() {
+		const client = this.remote.getClient();
+		client.subscribe("disconnected", () => {
+			this.wasDisconnected = true;
+			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onDisconnect" }, "Remote disconnected");
+		});
+		client.subscribe("connected", () => {
+			if (!this.wasDisconnected) return;
+			this.wasDisconnected = false;
+			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onReconnect" }, "Remote reconnected, refetching active queries");
+			for (const hash of this.dataModule.getActiveQueryHashes()) this.scheduler.enqueueDownEvent({
+				type: "register",
+				payload: { hash }
+			});
+		});
 	}
 	async startRefLiveQueries() {
+		const tableName = this.listRefTable();
 		this.logger.debug({
-			clientId: this.clientId,
+			tableName,
 			Category: "sp00ky-client::Sp00kySync::startRefLiveQueries"
 		}, "Starting ref live queries");
-		const [queryUuid] = await this.remote.query("LIVE SELECT * FROM _00_list_ref");
-		(await this.remote.getClient().liveOf(queryUuid)).subscribe((message) => {
+		const [queryUuid] = await this.remote.query(`LIVE SELECT * FROM ${tableName}`);
+		this.currentLiveQueryUuid = queryUuid;
+		this.liveQueryUnsubscribe = (await this.remote.getClient().liveOf(queryUuid)).subscribe((message) => {
 			this.logger.debug({
 				message,
 				Category: "sp00ky-client::Sp00kySync::startRefLiveQueries"
@@ -1833,6 +2262,7 @@ var Sp00kySync = class {
 		});
 	}
 	async handleRemoteListRefChange(action, queryId, recordId, version) {
+		this.lastLiveEventAt = Date.now();
 		if (action === "DELETE") {
 			this.logger.debug({
 				queryId: queryId.toString(),
@@ -2002,13 +2432,13 @@ var Sp00kySync = class {
 			throw new Error("Query to register not found");
 		}
 		await this.remote.query("fn::query::register($config)", { config: {
-			clientId: this.clientId,
 			id: queryState.config.id,
 			surql: queryState.config.surql,
 			params: queryState.config.params,
 			ttl: queryState.config.ttl
 		} });
-		const [items] = await this.remote.query(surql.selectByFieldsAnd("_00_list_ref", ["in"], ["out", "version"]), { in: queryState.config.id });
+		const listRefTbl = this.listRefTable();
+		const [items] = await this.remote.query(buildListRefSelect(listRefTbl), { in: queryState.config.id });
 		this.logger.trace({
 			queryId: encodeRecordId(queryState.config.id),
 			items,
@@ -2555,19 +2985,23 @@ var StreamProcessorService = class {
 		}
 		try {
 			const normalizedRecord = this.normalizeValue(record);
+			const t0 = performance.now();
 			const rawUpdates = this.processor.ingest(table, op, id, normalizedRecord);
+			const materializationTimeMs = performance.now() - t0;
 			this.logger.debug({
 				table,
 				op,
 				id,
 				rawUpdates: rawUpdates.length,
+				materializationTimeMs,
 				Category: "sp00ky-client::StreamProcessorService::ingest"
 			}, "Ingesting into ssp done");
 			if (rawUpdates && Array.isArray(rawUpdates) && rawUpdates.length > 0) {
 				const updates = rawUpdates.map((u) => ({
 					queryHash: u.query_id,
 					localArray: u.result_data,
-					op
+					op,
+					materializationTimeMs
 				}));
 				this.notifyUpdates(updates);
 			}
@@ -2649,6 +3083,7 @@ var StreamProcessorService = class {
 	normalizeValue(value) {
 		if (value === null || value === void 0) return value;
 		if (typeof value === "object") {
+			if (value instanceof Uint8Array || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return null;
 			const hasTable = "table" in value && typeof value.table?.toString === "function";
 			const hasId = "id" in value;
 			const hasToString = typeof value.toString === "function";
@@ -2738,7 +3173,7 @@ var CacheModule = class {
 			});
 			if (!skipDbInsert) {
 				const query = surql.seal(surql.tx(populatedRecords.map((_, i) => {
-					return surql.upsert(`id${i}`, `content${i}`);
+					return surql.upsertMerge(`id${i}`, `content${i}`);
 				})));
 				const params = populatedRecords.reduce((acc, record, i) => {
 					const { id, ...content } = record.record;
@@ -2877,14 +3312,21 @@ function cursorColorFromName(name) {
 var CrdtField = class {
 	doc;
 	pushTimer = null;
+	local = null;
 	remote = null;
 	recordId = null;
+	sessionId = "";
 	unsubscribe = null;
 	lastPushTime = 0;
 	lastCursorPushTime = 0;
 	loadedFromCrdt = false;
 	pushRetryCount = 0;
 	logger;
+	cursorsEnabled;
+	/** Remote-push debounce. Local writes happen immediately on every Loro
+	*  update; the remote UPSERT is coalesced over this window. Configured
+	*  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
+	remoteDebounceMs = 500;
 	_onCursorUpdate = null;
 	pendingCursorUpdate = null;
 	/** Callback set by the editor to receive remote cursor updates.
@@ -2906,13 +3348,21 @@ var CrdtField = class {
 	get onCursorUpdate() {
 		return this._onCursorUpdate;
 	}
-	constructor(fieldName, initialState, logger) {
+	constructor(fieldName, cursorsEnabled, initialState, logger) {
 		this.fieldName = fieldName;
+		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)) throw new Error(`CrdtField: refusing unsafe field identifier '${fieldName}' — must match [a-zA-Z_][a-zA-Z0-9_]*`);
 		this.logger = logger ?? null;
+		this.cursorsEnabled = cursorsEnabled;
 		this.doc = new LoroDoc();
-		if (initialState) {
-			this.doc.import(decodeBase64(initialState));
+		if (initialState && initialState.length > 0) try {
+			this.doc.import(initialState);
 			this.loadedFromCrdt = true;
+		} catch (e) {
+			this.logger?.warn({
+				error: e,
+				fieldName,
+				Category: "sp00ky-client::CrdtField::constructor"
+			}, "Initial CRDT state is not a valid LoroDoc snapshot — starting empty and will seed from fallback text");
 		}
 	}
 	getDoc() {
@@ -2922,11 +3372,15 @@ var CrdtField = class {
 	hasContent() {
 		return this.loadedFromCrdt;
 	}
-	startSync(remote, recordId) {
+	startSync(local, remote, recordId, sessionId, debounceMs) {
+		this.local = local;
 		this.remote = remote;
 		this.recordId = recordId;
+		this.sessionId = sessionId;
+		this.remoteDebounceMs = debounceMs;
 		this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
-			this.schedulePush();
+			this.persistLocal();
+			this.scheduleRemotePush();
 		});
 	}
 	stopSync() {
@@ -2940,10 +3394,11 @@ var CrdtField = class {
 		}
 		if (this.remote && this.recordId) this.pushToRemote();
 	}
-	importRemote(base64State) {
-		if (Date.now() - this.lastPushTime < 500) return;
+	importRemote(state) {
+		if (Date.now() - this.lastPushTime < this.remoteDebounceMs + 200) return;
 		try {
-			this.doc.import(decodeBase64(base64State));
+			this.doc.import(state);
+			this.persistLocal();
 		} catch (e) {
 			this.logger?.warn({
 				error: e,
@@ -2952,18 +3407,23 @@ var CrdtField = class {
 		}
 	}
 	exportSnapshot() {
-		return encodeBase64(this.doc.export({ mode: "snapshot" }));
-	}
-	/** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+		return this.doc.export({ mode: "snapshot" });
+	}
+	/** Push this session's cursor blob into the parent row at
+	*  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
+	*  field — the editor still calls this method optimistically, but
+	*  without `@cursor` on the schema there's nowhere to store the blob.
+	*  The UPDATE itself fires the parent table's LIVE feed, so other
+	*  browsers receive the cursor change without a separate `_00_rv` bump. */
 	async pushCursorState(encoded) {
 		if (!this.remote || !this.recordId) return;
+		if (!this.cursorsEnabled) return;
 		this.lastCursorPushTime = Date.now();
 		try {
 			const state = encodeBase64(encoded);
-			await this.remote.query(`INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
-         ON DUPLICATE KEY UPDATE state = $state`, {
-				rid: parseRecordIdString(this.recordId),
-				field: `_cursor_${this.fieldName}`,
+			await this.remote.query(`UPDATE $id SET ${this.fieldName}.cursors[$sid] = $state RETURN NONE;`, {
+				id: parseRecordIdString(this.recordId),
+				sid: this.sessionId,
 				state
 			});
 		} catch (e) {
@@ -2987,18 +3447,41 @@ var CrdtField = class {
 			}, "Failed to apply remote cursor data");
 		}
 	}
-	schedulePush() {
+	scheduleRemotePush() {
 		if (this.pushTimer) clearTimeout(this.pushTimer);
-		this.pushTimer = setTimeout(() => void this.pushToRemote(), 300);
+		this.pushTimer = setTimeout(() => void this.pushToRemote(), this.remoteDebounceMs);
+	}
+	/** SET path inside a parent row for the current snapshot. `@crdt`-only
+	*  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
+	*  fields hold a `{ state, cursors }` object so the snapshot lives at
+	*  `<field>.state` next to per-session cursor blobs. */
+	statePath() {
+		return this.cursorsEnabled ? `${this.fieldName}.state` : this.fieldName;
+	}
+	/** Mirror the LoroDoc snapshot into the parent row locally. Runs on
+	*  every local update and every remote import so reloads (online or
+	*  offline) see the freshest content immediately. Failures are
+	*  swallowed — a stale local write must never block user input. */
+	async persistLocal() {
+		if (!this.local || !this.recordId) return;
+		try {
+			await this.local.query(`UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`, {
+				id: parseRecordIdString(this.recordId),
+				state: this.exportSnapshot()
+			});
+		} catch (e) {
+			this.logger?.debug({
+				error: e,
+				Category: "sp00ky-client::CrdtField::persistLocal"
+			}, "Local CRDT persist failed (best-effort)");
+		}
 	}
 	async pushToRemote() {
 		if (!this.remote || !this.recordId) return;
 		this.lastPushTime = Date.now();
 		try {
-			await this.remote.query(`INSERT INTO _00_crdt (record_id, field, state) VALUES ($rid, $field, $state)
-         ON DUPLICATE KEY UPDATE state = $state`, {
-				rid: parseRecordIdString(this.recordId),
-				field: this.fieldName,
+			await this.remote.query(`UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`, {
+				id: parseRecordIdString(this.recordId),
 				state: this.exportSnapshot()
 			});
 			this.pushRetryCount = 0;
@@ -3009,7 +3492,7 @@ var CrdtField = class {
 			}, "Failed to push CRDT state to remote");
 			if (this.pushRetryCount < 2) {
 				this.pushRetryCount++;
-				this.schedulePush();
+				this.scheduleRemotePush();
 			}
 		}
 	}
@@ -3037,18 +3520,44 @@ function encodeBase64(bytes) {
 /**
 * CrdtManager manages active CrdtField instances and their sync channels.
 *
-* Each open record gets a LIVE SELECT on _00_crdt that delivers remote
-* changes in real time.
+* Collaborative state lives in two dedicated tables (defined in
+* `apps/cli/src/meta_tables_remote.surql`):
+*   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+*   - `_00_cursor` { record_id, session_id, field, state } — one row per
+*                    (record, session, field)
+*
+* Splitting them off the parent row is what makes offline edits mergeable:
+* each (record, field) gets its own row, so concurrent offline writes don't
+* collide on the parent's last-write-wins semantics.
+*
+* Cross-browser delivery still rides the parent table's existing LIVE feed
+* to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+* (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+* parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+* feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+* via subquery. Permission inheritance happens server-side via
+* `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
 */
 var CrdtManager = class {
 	fields = /* @__PURE__ */ new Map();
-	liveQueries = /* @__PURE__ */ new Map();
+	liveByTable = /* @__PURE__ */ new Map();
+	pendingLive = /* @__PURE__ */ new Map();
 	logger;
-	constructor(schema, remote, logger) {
+	sessionId = "";
+	constructor(schema, local, remote, logger, debounceMs = 500) {
 		this.schema = schema;
+		this.local = local;
 		this.remote = remote;
+		this.debounceMs = debounceMs;
 		this.logger = logger.child({ service: "CrdtManager" });
 	}
+	/** Set the session id that scopes this client's cursor entries. Must be
+	*  called before `open()` for cursors to be pushed under a stable key.
+	*  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+	*  for the data-module salt). */
+	setSessionId(sessionId) {
+		this.sessionId = sessionId;
+	}
 	/**
 	* Open a CRDT field for collaborative editing.
 	*
@@ -3060,24 +3569,25 @@ var CrdtManager = class {
 	*/
 	async open(table, recordId, field, fallbackText) {
 		this.assertCrdtField(table, field);
+		const cursorsEnabled = this.fieldHasCursor(table, field);
 		const key = this.makeKey(table, recordId, field);
 		let crdtField = this.fields.get(key);
 		if (crdtField) return crdtField;
 		let initialCrdtState;
 		try {
-			const [result] = await this.remote.query("SELECT VALUE state FROM _00_crdt WHERE record_id = $rid AND field = $field LIMIT 1", {
-				rid: parseRecordIdString(recordId),
-				field
-			});
-			if (result && result.length > 0 && result[0]) initialCrdtState = result[0];
+			const [result] = await this.local.query(`SELECT VALUE ${field} FROM ONLY $id`, { id: parseRecordIdString(recordId) });
+			const snapshot = this.extractSnapshot(result, cursorsEnabled);
+			if (snapshot) initialCrdtState = snapshot;
 		} catch (e) {
-			this.logger.debug({
-				error: e,
+			this.logger.info({
+				error: String(e),
+				recordId,
+				field,
 				Category: "sp00ky-client::CrdtManager::open"
-			}, "No existing CRDT state found");
+			}, "No existing CRDT state found in local cache (continuing with empty doc)");
 		}
-		crdtField = new CrdtField(field, initialCrdtState, this.logger);
-		crdtField.startSync(this.remote, recordId);
+		crdtField = new CrdtField(field, cursorsEnabled, initialCrdtState, this.logger);
+		crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
 		this.fields.set(key, crdtField);
 		this.logger.info({
 			key,
@@ -3085,7 +3595,8 @@ var CrdtManager = class {
 			hasFallback: !!fallbackText,
 			Category: "sp00ky-client::CrdtManager::open"
 		}, "CrdtField opened");
-		await this.ensureLiveSelect(table, recordId);
+		this.ensureTableSubscription(table);
+		if (!initialCrdtState) this.fetchAndDispatchRow(table, recordId);
 		return crdtField;
 	}
 	close(table, recordId, field) {
@@ -3095,8 +3606,8 @@ var CrdtManager = class {
 			crdtField.stopSync();
 			this.fields.delete(key);
 		}
-		const prefix = `${table}:${recordId}:`;
-		if (!Array.from(this.fields.keys()).some((k) => k !== key && k.startsWith(prefix))) this.killLiveSelect(recordId);
+		const tablePrefix = `${table}:`;
+		if (!Array.from(this.fields.keys()).some((k) => k.startsWith(tablePrefix))) this.killTableSubscription(table);
 		this.logger.debug({
 			key,
 			Category: "sp00ky-client::CrdtManager::close"
@@ -3105,51 +3616,121 @@ var CrdtManager = class {
 	closeAll() {
 		for (const [_, field] of this.fields) field.stopSync();
 		this.fields.clear();
-		for (const recordId of this.liveQueries.keys()) this.killLiveSelect(recordId);
-	}
-	async ensureLiveSelect(table, recordId) {
-		if (this.liveQueries.has(recordId)) return;
+		for (const table of Array.from(this.liveByTable.keys())) this.killTableSubscription(table);
+	}
+	/** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+	*  every open CrdtField on `table`. */
+	async ensureTableSubscription(table) {
+		if (this.liveByTable.has(table)) return;
+		const pending = this.pendingLive.get(table);
+		if (pending) return pending;
+		const start = (async () => {
+			try {
+				const [uuid] = await this.remote.query(`LIVE SELECT * FROM ${table}`);
+				(await this.remote.getClient().liveOf(uuid)).subscribe((message) => {
+					if (message.action === "KILLED") return;
+					if (message.action !== "CREATE" && message.action !== "UPDATE") return;
+					this.dispatchRow(table, message.value);
+				});
+				this.liveByTable.set(table, uuid);
+				this.logger.info({
+					table,
+					Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
+				}, "LIVE SELECT started");
+			} catch (e) {
+				this.logger.warn({
+					error: e,
+					table,
+					Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
+				}, "Failed to start LIVE SELECT");
+			}
+		})();
+		this.pendingLive.set(table, start);
 		try {
-			const [uuid] = await this.remote.query(`LIVE SELECT * FROM _00_crdt WHERE record_id = $rid`, { rid: parseRecordIdString(recordId) });
-			this.liveQueries.set(recordId, {
-				uuid,
-				table
-			});
-			(await this.remote.getClient().liveOf(uuid)).subscribe((message) => {
-				if (message.action === "KILLED") return;
-				if (message.action === "CREATE" || message.action === "UPDATE") {
-					const fieldName = message.value.field;
-					const state = message.value.state;
-					if (!fieldName || !state) return;
-					if (fieldName.startsWith("_cursor_")) {
-						const actualField = fieldName.slice(8);
-						const key = this.makeKey(table, recordId, actualField);
-						const crdtField = this.fields.get(key);
-						if (crdtField) crdtField.importRemoteCursor(state);
-						return;
-					}
-					const key = this.makeKey(table, recordId, fieldName);
-					const crdtField = this.fields.get(key);
-					if (crdtField) crdtField.importRemote(state);
+			await start;
+		} finally {
+			this.pendingLive.delete(table);
+		}
+	}
+	/** Apply a parent-row payload from a non-LIVE source (e.g. the
+	*  list_ref-driven sync engine, when the cross-user LIVE on the
+	*  parent table is filtered out by the SurrealDB cross-session
+	*  permission gap). Same semantics as the internal `dispatchRow`. */
+	applyRow(table, row) {
+		this.dispatchRow(table, row);
+	}
+	/** Dispatch a parent-row LIVE event to every open CrdtField on that
+	*  record. Each open field reads its slice of the row directly — the
+	*  CRDT snapshot is a column on the parent now, so there is no
+	*  follow-up subquery. */
+	dispatchRow(table, row) {
+		const id = row.id != null ? String(row.id) : "";
+		if (!id) return;
+		const rowKeyPrefix = `${table}:${id}:`;
+		for (const [key, crdtField] of this.fields) {
+			if (!key.startsWith(rowKeyPrefix)) continue;
+			const fieldName = key.slice(rowKeyPrefix.length);
+			const cursorsEnabled = this.fieldHasCursor(table, fieldName);
+			const slice = row[fieldName];
+			const snapshot = this.extractSnapshot(slice, cursorsEnabled);
+			if (snapshot) crdtField.importRemote(snapshot);
+			if (cursorsEnabled && slice && typeof slice === "object") {
+				const cursors = slice.cursors;
+				if (cursors && typeof cursors === "object") for (const [sid, blob] of Object.entries(cursors)) {
+					if (sid === this.sessionId) continue;
+					if (typeof blob === "string" && blob.length > 0) crdtField.importRemoteCursor(blob);
 				}
-			});
-			this.logger.info({
-				recordId,
-				Category: "sp00ky-client::CrdtManager::ensureLiveSelect"
-			}, "LIVE SELECT on _00_crdt started");
+			}
+		}
+	}
+	/** One-shot remote fetch for a row whose CRDT field hasn't synced
+	*  locally yet (fresh device, memory-backed local DB after reload, …).
+	*  Used by `open()` when the local read came up empty. Subsequent
+	*  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+	async fetchAndDispatchRow(table, id) {
+		try {
+			const recordId = parseRecordIdString(id);
+			const [row] = await this.remote.query(`SELECT * FROM ONLY $id`, { id: recordId });
+			if (!row || typeof row !== "object") return;
+			this.dispatchRow(table, row);
 		} catch (e) {
 			this.logger.warn({
 				error: e,
-				recordId,
-				Category: "sp00ky-client::CrdtManager::ensureLiveSelect"
-			}, "Failed to start LIVE SELECT on _00_crdt");
+				table,
+				id,
+				Category: "sp00ky-client::CrdtManager::fetchAndDispatchRow"
+			}, "Failed to fetch parent row for CRDT hydration");
 		}
 	}
-	killLiveSelect(recordId) {
-		const entry = this.liveQueries.get(recordId);
-		if (entry) {
-			this.remote.query("KILL $uuid", { uuid: entry.uuid }).catch(() => {});
-			this.liveQueries.delete(recordId);
+	/** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+	*  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+	fieldHasCursor(table, field) {
+		return !!this.schema.tables.find((t) => t.name === table)?.columns[field]?.cursor;
+	}
+	/** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+	*  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+	*  `{ state, cursors }` where `state` carries the snapshot bytes. */
+	extractSnapshot(value, cursorsEnabled) {
+		const asBytes = (v) => {
+			if (v instanceof Uint8Array) return v.length > 0 ? v : void 0;
+			if (v instanceof ArrayBuffer) return new Uint8Array(v);
+			if (ArrayBuffer.isView(v)) {
+				const view = v;
+				return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+			}
+			if (Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === "number")) return Uint8Array.from(v);
+		};
+		if (cursorsEnabled) {
+			if (value && typeof value === "object" && !(value instanceof Uint8Array)) return asBytes(value.state);
+			return;
+		}
+		return asBytes(value);
+	}
+	killTableSubscription(table) {
+		const uuid = this.liveByTable.get(table);
+		if (uuid) {
+			this.remote.query("KILL $uuid", { uuid }).catch(() => {});
+			this.liveByTable.delete(table);
 		}
 	}
 	makeKey(table, recordId, field) {
@@ -3161,6 +3742,7 @@ var CrdtManager = class {
 	* of silently producing a non-CRDT writer.
 	*/
 	assertCrdtField(table, field) {
+		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) throw new Error(`openCrdtField: refusing unsafe field identifier '${field}' — must match [a-zA-Z_][a-zA-Z0-9_]*`);
 		const tableSchema = this.schema.tables.find((t) => t.name === table);
 		if (!tableSchema) throw new Error(`openCrdtField: unknown table '${table}'. Available: ${this.schema.tables.map((t) => t.name).join(", ")}`);
 		const column = tableSchema.columns[field];
@@ -3329,6 +3911,14 @@ var Sp00kyClient = class {
 	get pendingMutationCount() {
 		return this.sync.pendingMutationCount;
 	}
+	/** Number of times the initial list_ref LIVE subscription retried on
+	*  the most recent `setCurrentUserId` call. 0 when the SSP's
+	*  pre-emptive user-table creation got there first; >0 when LIVE
+	*  registration hit a "table not found" race. Exposed so the e2e
+	*  suite can guard the pre-emptive path against regression. */
+	get liveRetryCount() {
+		return this.sync.liveRetryCount;
+	}
 	subscribeToPendingMutations(cb) {
 		return this.sync.subscribeToPendingMutations(cb);
 	}
@@ -3354,10 +3944,10 @@ var Sp00kyClient = class {
 		this.cache = new CacheModule(this.local, this.streamProcessor, (update) => {
 			this.dataModule.onStreamUpdate(update);
 		}, logger);
-		this.crdtManager = new CrdtManager(this.config.schema, this.remote, logger);
+		this.crdtManager = new CrdtManager(this.config.schema, this.local, this.remote, logger, config.crdtDebounceMs ?? 500);
 		this.dataModule = new DataModule(this.cache, this.local, this.config.schema, logger, this.config.streamDebounceTime);
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
-		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger);
+		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, { refSyncIntervalMs: this.config.refSyncIntervalMs });
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
@@ -3373,6 +3963,22 @@ var Sp00kyClient = class {
 		this.sync.events.subscribe("SYNC_QUERY_UPDATED", (event) => {
 			this.devTools.logEvent("SYNC_QUERY_UPDATED", event.payload);
 		});
+		this.sync.engineEvents.subscribe("SYNC_REMOTE_DATA_INGESTED", (event) => {
+			try {
+				const records = event.payload?.records ?? [];
+				for (const row of records) {
+					const id = row?.id;
+					const table = id && typeof id === "object" && id.table !== void 0 ? String(id.table) : void 0;
+					if (!table) continue;
+					this.crdtManager.applyRow(table, row);
+				}
+			} catch (err) {
+				this.logger.debug({
+					err,
+					Category: "sp00ky-client::engineEvents::ingested"
+				}, "applyRow forwarding from sync ingest failed");
+			}
+		});
 		this.local.getEvents().subscribe("DATABASE_LOCAL_QUERY", (event) => {
 			this.devTools.logEvent("LOCAL_QUERY", event.payload);
 		});
@@ -3383,12 +3989,6 @@ var Sp00kyClient = class {
 	async init() {
 		this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization started");
 		try {
-			const clientId = this.config.clientId ?? await this.loadOrGenerateClientId();
-			this.persistClientId(clientId);
-			this.logger.debug({
-				clientId,
-				Category: "sp00ky-client::Sp00kyClient::init"
-			}, "Client ID loaded");
 			await this.local.connect();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Local database connected");
 			await this.migrator.provision(this.config.schemaSurql);
@@ -3399,9 +3999,28 @@ var Sp00kyClient = class {
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "StreamProcessor initialized");
 			await this.auth.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Auth initialized");
-			await this.dataModule.init();
-			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "DataModule initialized");
-			await this.sync.init(clientId);
+			const sessionId = await this.fetchSessionId();
+			await this.dataModule.init(sessionId);
+			this.crdtManager.setSessionId(sessionId);
+			this.logger.debug({
+				sessionId,
+				Category: "sp00ky-client::Sp00kyClient::init"
+			}, "DataModule initialized");
+			this.auth.subscribe(async (userId) => {
+				this.dataModule.setCurrentUserId(userId);
+				const next = await this.fetchSessionId();
+				this.dataModule.setSessionId(next);
+				this.crdtManager.setSessionId(next);
+				try {
+					await this.sync.setCurrentUserId(userId);
+				} catch (e) {
+					this.logger.error({
+						error: e,
+						Category: "sp00ky-client::Sp00kyClient::authChange"
+					}, "sync.setCurrentUserId failed");
+				}
+			});
+			await this.sync.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sync initialized");
 			this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization completed successfully");
 		} catch (e) {
@@ -3423,7 +4042,8 @@ var Sp00kyClient = class {
 	/**
 	* Open a CRDT field for collaborative editing.
 	* Returns a CrdtField with a LoroDoc that can be bound to any editor.
-	* Also starts a LIVE SELECT on _00_crdt for real-time sync.
+	* Also starts a LIVE SELECT on the parent table for real-time sync;
+	* incoming events trigger a subquery fetch of `_00_crdt` / `_00_cursor`.
 	*/
 	async openCrdtField(table, recordId, field, fallbackText) {
 		return this.crdtManager.open(table, recordId, field, fallbackText);
@@ -3475,24 +4095,25 @@ var Sp00kyClient = class {
 	async useRemote(fn) {
 		return fn(this.remote.getClient());
 	}
-	persistClientId(id) {
+	/**
+	* Fetch SurrealDB's `session::id()` as a string. Used as a salt for
+	* query-id hashing so two sessions for the same user get distinct
+	* `_00_query` rows. Returns empty string if the query fails (we still
+	* boot, just without session scoping for IDs).
+	*/
+	async fetchSessionId() {
 		try {
-			this.persistenceClient.set("sp00ky_client_id", id);
+			const [sid] = await this.remote.query("RETURN <string>session::id()");
+			return typeof sid === "string" ? sid : "";
 		} catch (e) {
 			this.logger.warn({
 				error: e,
-				Category: "sp00ky-client::Sp00kyClient::persistClientId"
-			}, "Failed to persist client ID");
+				Category: "sp00ky-client::Sp00kyClient::fetchSessionId"
+			}, "Failed to fetch session::id() — proceeding with empty salt");
+			return "";
 		}
 	}
-	async loadOrGenerateClientId() {
-		const clientId = await this.persistenceClient.get("sp00ky_client_id");
-		if (clientId) return clientId;
-		const newId = generateId();
-		await this.persistClientId(newId);
-		return newId;
-	}
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };