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

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";
@@ -2658,16 +2658,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,14 +2685,18 @@ 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);
@@ -3586,6 +3589,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 +3616,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 +4002,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 +4035,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 +4361,7 @@ var DataModule = class DataModule {
 			record: target,
 			tableName
 		};
+		this.invalidatePendingIds();
 		for (const callback of this.mutationCallbacks) callback([mutationEvent]);
 		this.logger.debug({
 			id,
@@ -4374,6 +4415,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 +4461,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 +5114,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 +5164,7 @@ var DownQueue = class {
 				rotated: starvingOthers,
 				Category: "sp00ky-client::DownQueue::next"
 			}, "Failed to process query");
-			throw error;
+			return error;
 		}
 	}
 };
@@ -5452,6 +5529,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 +5681,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 +5800,7 @@ var Sp00kySync = class Sp00kySync {
 	degradeAfterFailures;
 	/** Per-push RPC deadline; see {@link withPushTimeout}. */
 	pushTimeoutMs;
+	downTimeoutMs;
 	consecutiveSyncFailures = 0;
 	syncHealthStatus = "healthy";
 	lastSyncErrorKind;
@@ -5862,6 +5972,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;
 	}
 	/**
@@ -5873,6 +5984,7 @@ var Sp00kySync = class Sp00kySync {
 		if (this.isInit) throw new Error("Sp00kySync is already initialized");
 		this.isInit = true;
 		await this.scheduler.init({ loadOutbox: this.tabRole !== "follower" });
+		if (this.remote.getStatus() !== "connected") this.needsResubscribe = true;
 		this.subscribeToReconnect();
 		this.subscribeToConnectionState();
 		this.scheduler.syncUp();
@@ -6543,6 +6655,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);
@@ -7093,8 +7211,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.202";
-const WASM_VERSION = "0.0.1-canary.202";
+const CORE_VERSION = "0.0.1-canary.204";
+const WASM_VERSION = "0.0.1-canary.204";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7579,26 +7697,44 @@ var DevToolsService = class DevToolsService {
 //#endregion
 //#region src/modules/auth/index.ts
 /**
-* Read the `AC` (access-method name) claim from a SurrealDB record-access
-* JWT without verifying it — we only need the claim, the server enforces the
-* token. Returns null on any malformed input. The in-browser SSP needs this
-* to resolve `$access` in table permission predicates (mirrors the session's
-* `$access` that the server's `fn::query::register` reads).
+* Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+* server still enforces the token on every request; this is only so the client
+* can act on what it already holds before a round trip completes.
+*
+* `AC` is the access-method name — the in-browser SSP needs it to resolve
+* `$access` in table permission predicates (mirrors the session's `$access`
+* that the server's `fn::query::register` reads). `ID` is the `$auth.id` record
+* id, which is what lets a warm boot restore a session locally.
+*
+* Returns nulls on any malformed input.
 */
-function decodeAccessFromToken(token) {
+function decodeTokenClaims(token) {
 	try {
 		const payload = token.split(".")[1];
-		if (!payload) return null;
+		if (!payload) return {
+			access: null,
+			userId: null
+		};
 		let b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
 		b64 += "=".repeat((4 - b64.length % 4) % 4);
 		const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("binary");
 		const claims = JSON.parse(json);
 		const ac = claims.AC ?? claims.ac;
-		return typeof ac === "string" ? ac : null;
+		const id = claims.ID ?? claims.id;
+		return {
+			access: typeof ac === "string" ? ac : null,
+			userId: typeof id === "string" ? id : null
+		};
 	} catch {
-		return null;
+		return {
+			access: null,
+			userId: null
+		};
 	}
 }
+function decodeAccessFromToken(token) {
+	return decodeTokenClaims(token).access;
+}
 var AuthService = class {
 	token = null;
 	currentUser = null;
@@ -7645,6 +7781,39 @@ var AuthService = class {
 		this.events.emit(AuthEventTypes.AuthStateChanged, userId);
 	}
 	/**
+	* Restore a session from the locally cached JWT, with NO network.
+	*
+	* This is what makes a warm boot paint instantly and what makes an offline
+	* boot possible at all: the token is in local storage, and it already carries
+	* both the access method and the `$auth.id` record id. Everything the client
+	* needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+	* permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+	* available before a socket exists.
+	*
+	* The session is OPTIMISTIC: the token is unverified here. `check()` runs
+	* afterwards in the background and downgrades to a real sign-out if the
+	* server rejects it. Nothing is trusted that the server has not also seen -
+	* the local store only ever holds rows the server previously sent.
+	*
+	* Returns the restored user id, or null when there is no usable token.
+	*/
+	async restoreSessionFromToken() {
+		const token = await this.persistenceClient.get("sp00ky_auth_token");
+		if (!token) return null;
+		const { access, userId } = decodeTokenClaims(token);
+		if (!userId) return null;
+		this.token = token;
+		this.currentUser = { id: userId };
+		this.isAuthenticated = true;
+		this.access = access ?? this.defaultAccessName();
+		this.notifyListeners();
+		this.logger.debug({
+			userId,
+			Category: "sp00ky-client::AuthService::restoreSessionFromToken"
+		}, "Session restored optimistically from cached token");
+		return userId;
+	}
+	/**
 	* Check for existing session and validate
 	*/
 	async check(accessToken) {
@@ -7685,12 +7854,18 @@ var AuthService = class {
 				}
 			}
 		} catch (error) {
-			this.logger.error({
+			if (classifySyncError(error) === "network") this.logger.warn({
 				error,
-				stack: error.stack,
 				Category: "sp00ky-client::AuthService::check"
-			}, "Auth check failed");
-			await this.signOut();
+			}, "Auth check unreachable; keeping the cached session and retrying later");
+			else {
+				this.logger.error({
+					error,
+					stack: error.stack,
+					Category: "sp00ky-client::AuthService::check"
+				}, "Auth check failed");
+				await this.signOut();
+			}
 		} finally {
 			this.isLoading = false;
 		}
@@ -7836,6 +8011,51 @@ var StreamProcessorService = class {
 	*/
 	ingestMany(records) {
 		if (records.length === 0) return;
+		if (!this.processor) {
+			this.logger.warn({ Category: "sp00ky-client::StreamProcessorService::ingestMany" }, "Not initialized, skipping ingest");
+			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");
+			try {
+				const items = records.map((record) => ({
+					table: record.table,
+					op: record.op,
+					id: record.id,
+					record: this.normalizeValue(record.record)
+				}));
+				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) => ({
+					queryHash: u.query_id,
+					localArray: u.result_data,
+					op: "CREATE",
+					materializationTimeMs,
+					storeApplyMs: u.timing_store_apply_ms,
+					circuitStepMs: u.timing_circuit_step_ms,
+					transformMs: u.timing_transform_ms
+				})));
+			} catch (e) {
+				this.logger.error({
+					error: e,
+					count: records.length,
+					Category: "sp00ky-client::StreamProcessorService::ingestMany"
+				}, "Ingesting batch into ssp failed");
+			}
+			this.markSnapshotDirty();
+			return;
+		}
 		this.beginCoalescing();
 		try {
 			for (const record of records) this.ingest(record.table, record.op, record.id, record.record);
@@ -8363,14 +8583,12 @@ var CacheModule = class {
 				const query = surql.seal(surql.tx(populatedRecords.map((_, i) => {
 					return surql.upsertMerge(`id${i}`, `content${i}`);
 				})));
-				const params = populatedRecords.reduce((acc, record, i) => {
-					const { id, ...content } = record.record;
-					return {
-						...acc,
-						[`id${i}`]: id,
-						[`content${i}`]: content
-					};
-				}, {});
+				const params = {};
+				for (let i = 0; i < populatedRecords.length; i++) {
+					const { id, ...content } = populatedRecords[i].record;
+					params[`id${i}`] = id;
+					params[`content${i}`] = content;
+				}
 				await this.local.execute(query, params, { epoch });
 			}
 			if (this.local.epoch !== epoch) throw new StaleEpochError();
@@ -11506,6 +11724,15 @@ var Sp00kyClient = class {
 	sync;
 	devTools;
 	crdtManager;
+	/**
+	* True once the LOCAL half of boot is done and the client can serve reads
+	* from the local store. Distinct from being connected: `syncHealth` covers
+	* reaching the server and `storageHealth` covers whether the local store is
+	* durable, but neither says "usable". Consumers gate their first paint on
+	* this, which is what makes a warm boot instant and an offline boot possible.
+	*/
+	localReady = false;
+	saltUserId = null;
 	featureFlags;
 	appReleases;
 	preloadedHashes = /* @__PURE__ */ new Set();
@@ -11608,6 +11835,7 @@ 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.featureFlags = new FeatureFlagModule({
@@ -11662,7 +11890,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.202",
+				coreVersion: "0.0.1-canary.204",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11805,9 +12033,6 @@ var Sp00kyClient = class {
 				await this.migrator.provision(this.config.schemaSurql);
 				this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Schema provisioned");
 			}
-			await this.remote.connect();
-			this.connectionSupervisor.start();
-			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Remote database connected");
 			(async () => {
 				try {
 					this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
@@ -11823,23 +12048,31 @@ var Sp00kyClient = class {
 			await this.streamProcessor.init();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "StreamProcessor initialized");
-			await this.auth.init();
-			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Auth initialized");
-			const sessionId = await this.fetchSessionId();
+			const restoredUserId = await this.auth.restoreSessionFromToken();
+			const sessionId = this.mintSessionSalt();
+			this.saltUserId = restoredUserId;
 			await this.dataModule.init(sessionId);
 			this.crdtManager.setSessionId(sessionId);
+			if (restoredUserId) {
+				this.dataModule.setCurrentUserId(restoredUserId);
+				this.streamProcessor.setSessionAuth(this.sessionAuthId(), this.auth.access);
+			}
 			this.logger.debug({
 				sessionId,
 				Category: "sp00ky-client::Sp00kyClient::init"
 			}, "DataModule initialized");
 			this.auth.subscribe(async (userId) => {
 				this.dataModule.setCurrentUserId(userId);
-				this.streamProcessor.setSessionAuth(this.auth.currentUser?.id ? encodeRecordId(this.auth.currentUser.id) : null, this.auth.access);
+				this.streamProcessor.setSessionAuth(this.sessionAuthId(), this.auth.access);
 				writeBootBucketHint(bucketIdForUser(userId));
 				await this.ensureLocalBucket(userId);
-				const next = await this.fetchSessionId();
-				this.dataModule.setSessionId(next);
-				this.crdtManager.setSessionId(next);
+				const saltFor = this.sessionAuthId();
+				if (saltFor !== this.saltUserId) {
+					this.saltUserId = saltFor;
+					const next = this.mintSessionSalt();
+					this.dataModule.setSessionId(next);
+					this.crdtManager.setSessionId(next);
+				}
 				try {
 					await this.sync.setCurrentUserId(userId);
 				} catch (e) {
@@ -11855,7 +12088,9 @@ var Sp00kyClient = class {
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "FeatureFlagModule initialized");
 			this.appReleases.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "AppReleaseModule initialized");
-			this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization completed successfully");
+			this.localReady = true;
+			this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient local initialization completed; connecting in the background");
+			this.initRemote();
 		} catch (e) {
 			this.logger.error({
 				error: e,
@@ -11864,6 +12099,36 @@ var Sp00kyClient = class {
 			throw e;
 		}
 	}
+	/**
+	* The network half of boot: connect, verify the restored session, and let the
+	* sync engine catch up. Runs in the background after `init()` has already
+	* resolved, so nothing here is on the paint path.
+	*
+	* Every step is best-effort. A failure leaves the client in exactly the state
+	* a warm offline boot is in - local reads working, writes queued in the
+	* outbox - and the connection supervisor keeps retrying underneath.
+	*/
+	async initRemote() {
+		try {
+			await this.remote.connect();
+			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::initRemote" }, "Remote database connected");
+		} catch (e) {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::Sp00kyClient::initRemote"
+			}, "Remote connect failed; running from the local store and retrying in the background");
+		}
+		this.connectionSupervisor.start();
+		try {
+			await this.auth.init();
+			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::initRemote" }, "Auth verified");
+		} catch (e) {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::Sp00kyClient::initRemote"
+			}, "Auth verification failed; keeping the restored session");
+		}
+	}
 	bucketSwitchChain = Promise.resolve();
 	pendingBucketTarget = null;
 	/**
@@ -12238,26 +12503,49 @@ var Sp00kyClient = class {
 	delete(table, id) {
 		return this.dataModule.delete(table, id);
 	}
+	/**
+	* Whether the local store is initialized and reads can be served. See the
+	* `localReady` field: this is deliberately independent of connectivity.
+	*/
+	isLocalReady() {
+		return this.localReady;
+	}
 	async useRemote(fn) {
 		return fn(this.remote.getClient());
 	}
 	/**
-	* 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 {
-			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::fetchSessionId"
-			}, "Failed to fetch session::id() — proceeding with empty salt");
-			return "";
-		}
+	* Mint the salt used for query-id hashing, so two sessions registering the
+	* same logical query get distinct `_00_query` rows.
+	*
+	* Generated LOCALLY, deliberately. This used to be `RETURN <string>session::id()`,
+	* which cost a serial round trip on the critical boot path and resolved to
+	* `''` offline. The value never needed to come from the server: the server
+	* derives its own `clientId` inside `fn::query::register` and *ignores*
+	* whatever the caller passed, and the permission rules that matter gate on
+	* `auth_id = $auth.id` rather than the session (`_00_list_ref`). Session
+	* scoping via `clientId = session::id()` was in fact removed upstream because
+	* it broke a user with two tabs open. All this value has to be is unique per
+	* browser session, which `randomUUID` gives us for free and offline.
+	*/
+	/**
+	* The current principal as the `"table:id"` string the in-browser SSP wants
+	* for `$auth.id`, or null when signed out.
+	*
+	* Tolerates BOTH shapes `currentUser.id` can take, which is the point:
+	* a session restored from the cached token carries a plain string (the JWT's
+	* `ID` claim), while one verified by the server carries a RecordId. Passing
+	* the former to `encodeRecordId` reads `.table` off a string and throws
+	* during boot.
+	*/
+	sessionAuthId() {
+		const id = this.auth.currentUser?.id;
+		if (!id) return null;
+		return typeof id === "string" ? id : encodeRecordId(id);
+	}
+	mintSessionSalt() {
+		const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+		if (c?.randomUUID) return c.randomUUID();
+		return `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
 	}
 };