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

package/dist/index.d.ts

@@ -1471,6 +1471,24 @@ declare class AuthService<S extends SchemaStructure> {
    */
   subscribe(cb: (userId: string | null) => void): () => void;
   private notifyListeners;
+  /**
+   * 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.
+   */
+  restoreSessionFromToken(): Promise<string | null>;
   /**
    * Check for existing session and validate
    */
@@ -2166,6 +2184,15 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private sync;
   private devTools;
   private 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.
+   */
+  private localReady;
+  private saltUserId;
   private featureFlags;
   private appReleases;
   private preloadedHashes;
@@ -2211,6 +2238,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    */
   private setupCallbacks;
   init(): Promise<void>;
+  /**
+   * 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.
+   */
+  private initRemote;
   private bucketSwitchChain;
   private pendingBucketTarget;
   /**
@@ -2363,14 +2400,38 @@ declare class Sp00kyClient<S extends SchemaStructure> {
     [x: string]: /*elided*/any;
   }>;
   delete(table: string, id: string): Promise<void>;
-  useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
   /**
-   * 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).
+   * Whether the local store is initialized and reads can be served. See the
+   * `localReady` field: this is deliberately independent of connectivity.
    */
-  private fetchSessionId;
+  isLocalReady(): boolean;
+  useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
+  /**
+   * 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.
+   */
+  private sessionAuthId;
+  private mintSessionSalt;
 }
 //#endregion
 //#region src/utils/semver.d.ts

package/dist/index.js

@@ -5873,6 +5873,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();
@@ -7093,8 +7094,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.201";
-const WASM_VERSION = "0.0.1-canary.201";
+const CORE_VERSION = "0.0.1-canary.203";
+const WASM_VERSION = "0.0.1-canary.203";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7579,26 +7580,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 +7664,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 +7737,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 +7894,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 +8466,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 +11607,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();
@@ -11662,7 +11772,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.201",
+				coreVersion: "0.0.1-canary.203",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11805,9 +11915,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 +11930,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 +11970,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 +11981,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 +12385,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)}`;
 	}
 };
 

package/package.json

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

package/src/modules/auth/auth.local-first.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from 'vitest';
+import { AuthService } from './index';
+
+// A SurrealDB record-access JWT carries the access method as `AC` and the
+// `$auth.id` record id as `ID`. Only the payload matters here - nothing in the
+// client verifies the signature, the server does.
+function jwt(claims: Record<string, unknown>): string {
+  const b64 = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `header.${b64}.signature`;
+}
+
+const silentLogger = () =>
+  ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), child: () => silentLogger() }) as any;
+
+function makeAuth(opts: { token?: string | null; query?: any; authenticate?: any } = {}) {
+  const store = new Map<string, unknown>();
+  if (opts.token) store.set('sp00ky_auth_token', opts.token);
+  const persistence = {
+    get: vi.fn(async (k: string) => store.get(k) ?? null),
+    set: vi.fn(async (k: string, v: unknown) => void store.set(k, v)),
+    remove: vi.fn(async (k: string) => void store.delete(k)),
+  } as any;
+  const remote = {
+    query: opts.query ?? vi.fn(async () => [[]]),
+    getClient: () => ({ authenticate: opts.authenticate ?? vi.fn(async () => undefined) }),
+  } as any;
+  return { auth: new AuthService({} as any, remote, persistence, silentLogger()), remote, persistence, store };
+}
+
+describe('restoreSessionFromToken', () => {
+  it('restores the session from the cached token with NO network', async () => {
+    const { auth, remote } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+
+    const userId = await auth.restoreSessionFromToken();
+
+    expect(userId).toBe('user:abc');
+    expect(auth.isAuthenticated).toBe(true);
+    expect(auth.currentUser?.id).toBe('user:abc');
+    expect(auth.access).toBe('account');
+    // The whole point: this is what makes a warm/offline boot paint.
+    expect(remote.query).not.toHaveBeenCalled();
+  });
+
+  it('notifies subscribers so query routing can be set before any registration', async () => {
+    const { auth } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+    const seen: (string | null)[] = [];
+    auth.subscribe((uid) => seen.push(uid));
+
+    await auth.restoreSessionFromToken();
+
+    expect(seen).toContain('user:abc');
+  });
+
+  it('returns null when there is no token, and when the token carries no id', async () => {
+    expect(await makeAuth().auth.restoreSessionFromToken()).toBeNull();
+    const noId = makeAuth({ token: jwt({ AC: 'account' }) });
+    expect(await noId.auth.restoreSessionFromToken()).toBeNull();
+    expect(noId.auth.isAuthenticated).toBe(false);
+  });
+
+  it('survives a malformed token rather than throwing', async () => {
+    const { auth } = makeAuth({ token: 'not-a-jwt' });
+    expect(await auth.restoreSessionFromToken()).toBeNull();
+  });
+});
+
+describe('check() error handling', () => {
+  const token = jwt({ AC: 'account', ID: 'user:abc' });
+
+  it('KEEPS the cached session when the server is unreachable', async () => {
+    const { auth, persistence, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the underlying connection');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    // A blip must not log the user out - that is what makes offline possible.
+    expect(auth.isAuthenticated).toBe(true);
+    expect(store.get('sp00ky_auth_token')).toBe(token);
+    expect(persistence.remove).not.toHaveBeenCalled();
+  });
+
+  it('signs out for real when the server REJECTS the token', async () => {
+    const { auth, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the database: Invalid token');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    expect(auth.isAuthenticated).toBe(false);
+    expect(store.get('sp00ky_auth_token')).toBeUndefined();
+  });
+});

package/src/modules/auth/index.ts

@@ -9,6 +9,7 @@ import type { Logger } from '../../services/logger/index';
 export * from './events/index';
 import { AuthEventTypes, createAuthEventSystem } from './events/index';
 import type { PersistenceClient } from '../../types';
+import { classifySyncError } from '../../utils/error-classification';
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -36,28 +37,41 @@ type ExtractAccessParams<
     : never;
 
 /**
- * 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: string): string | null {
+function decodeTokenClaims(token: string): { access: string | null; userId: string | null } {
   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) as Record<string, unknown>;
     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: string): string | null {
+  return decodeTokenClaims(token).access;
+}
+
 export class AuthService<S extends SchemaStructure> {
   // State
   public token: string | null = null;
@@ -115,6 +129,44 @@ export class AuthService<S extends SchemaStructure> {
     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(): Promise<string | null> {
+    const token = await this.persistenceClient.get<string>('sp00ky_auth_token');
+    if (!token) return null;
+    const { access, userId } = decodeTokenClaims(token);
+    if (!userId) return null;
+
+    this.token = token;
+    // Only the id: the full row is not in the token. It lands from the local
+    // cache when the app's own `user` query paints, and is replaced wholesale
+    // by `check()` once the server answers.
+    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
    */
@@ -180,11 +232,23 @@ export class AuthService<S extends SchemaStructure> {
         }
       }
     } catch (error) {
-      this.logger.error(
-        { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
-        'Auth check failed'
-      );
-      await this.signOut();
+      // A REACHABILITY failure is not a rejected token. This catch used to call
+      // signOut() unconditionally, which deletes `sp00ky_auth_token` - so a
+      // blip on boot silently logged the user out, and an offline boot could
+      // never stay signed in. Only an application error (the server answered,
+      // and the answer was "no") ends the session.
+      if (classifySyncError(error) === 'network') {
+        this.logger.warn(
+          { error, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check unreachable; keeping the cached session and retrying later'
+        );
+      } else {
+        this.logger.error(
+          { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check failed'
+        );
+        await this.signOut();
+      }
     } finally {
       this.isLoading = false;
     }

package/src/modules/cache/index.ts

@@ -151,17 +151,18 @@ export class CacheModule implements StreamUpdateReceiver {
           )
         );
 
-        const params = populatedRecords.reduce(
-          (acc, record, i) => {
-            const { id, ...content } = record.record;
-            return {
-              ...acc,
-              [`id${i}`]: id,
-              [`content${i}`]: content,
-            };
-          },
-          {} as Record<string, any>
-        );
+        // Filled in place, NOT with a spread-per-iteration reduce: spreading the
+        // accumulator copies every key written so far on each record, which is
+        // O(n^2) in the batch size. On a cold start that batches thousands of
+        // rows (a game library, a player-name registry) it was the single
+        // biggest main-thread cost of the whole boot - ~36% of samples, seconds
+        // of blocking - for a loop that does no real work.
+        const params: Record<string, any> = {};
+        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 });
       }

package/src/modules/sync/sync.ts

@@ -473,6 +473,13 @@ export class Sp00kySync<S extends SchemaStructure> {
     if (this.isInit) throw new Error('Sp00kySync is already initialized');
     this.isInit = true;
     await this.scheduler.init({ loadOutbox: this.tabRole !== 'follower' });
+    // Boot is local-first now, so init() routinely runs BEFORE the socket is
+    // up. Treat that as "the socket we registered on is gone": otherwise the
+    // first `connected` takes the initial-connect branch, returns early, and
+    // never re-enqueues `register` for queries that registered while offline.
+    // They would still heal via the down-queue backoff, but slowly and only
+    // because every query happens to enqueue its own register.
+    if (this.remote.getStatus() !== 'connected') this.needsResubscribe = true;
     this.subscribeToReconnect();
     this.subscribeToConnectionState();
     void this.scheduler.syncUp();

package/src/services/stream-processor/index.ts

@@ -204,6 +204,72 @@ export class StreamProcessorService {
   ): void {
     if (records.length === 0) return;
 
+    if (!this.processor) {
+      this.logger.warn(
+        { Category: 'sp00ky-client::StreamProcessorService::ingestMany' },
+        'Not initialized, skipping ingest'
+      );
+      return;
+    }
+
+    // One circuit step for the whole batch when the WASM build offers it. A
+    // step walks every registered view, so the per-record path pays that fixed
+    // cost N times: a cold sync landing a few thousand rows spent seconds of
+    // main-thread time almost entirely on step overhead. Older builds have no
+    // `ingest_many`, hence the loop below.
+    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) {
+          // `op: 'CREATE'` for the same reason the coalesced flush uses it: the
+          // batch's update takes DataModule's immediate (non-debounced) path.
+          this.dispatchUpdates(
+            rawUpdates.map((u: WasmStreamUpdate) => ({
+              queryHash: u.query_id,
+              localArray: u.result_data,
+              op: 'CREATE' as const,
+              materializationTimeMs,
+              storeApplyMs: u.timing_store_apply_ms,
+              circuitStepMs: u.timing_circuit_step_ms,
+              transformMs: u.timing_transform_ms,
+            }))
+          );
+        }
+      } catch (e) {
+        // Same contract as the single-record path: report and move on rather
+        // than re-running the batch, which would double-apply whatever the
+        // failed step already committed to the store.
+        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) {

package/src/services/stream-processor/stream-processor.batch.test.ts

@@ -133,4 +133,64 @@ describe('StreamProcessor ingestMany bulk insert', () => {
     svc.ingest('user', 'CREATE', 'user:1', { id: 'user:1', _00_rv: 1 });
     expect(receiver.received).toHaveLength(1);
   });
+
+  // A WASM build that exposes `ingest_many` takes one circuit step for the whole
+  // batch. The per-record loop above stays as the fallback for older builds.
+  describe('with a WASM build that supports bulk ingest', () => {
+    function makeBulkService() {
+      const svc = new StreamProcessorService(
+        {} as any,
+        {} as any,
+        { get: async () => undefined, set: async () => {} } as any,
+        makeLogger()
+      );
+      const calls: { items: any[] }[] = [];
+      const mockProcessor: Partial<WasmProcessor> = {
+        ingest: () => {
+          throw new Error('per-record ingest must not be used when ingest_many exists');
+        },
+        ingest_many: (items): WasmStreamUpdate[] => {
+          calls.push({ items });
+          return [
+            {
+              query_id: 'q1',
+              result_data: items.map((i) => [i.id, 1] as [string, number]),
+              timing_circuit_step_ms: 4,
+            } as WasmStreamUpdate,
+          ];
+        },
+      };
+      (svc as any).processor = mockProcessor;
+      return { svc, calls };
+    }
+
+    it('takes a single bulk call and dispatches one update per affected query', () => {
+      const { svc, calls } = makeBulkService();
+      svc.addReceiver(receiver);
+
+      svc.ingestMany([
+        { table: 'user', op: 'CREATE', id: 'user:1', record: { id: 'user:1', _00_rv: 1 } },
+        { table: 'user', op: 'CREATE', id: 'user:2', record: { id: 'user:2', _00_rv: 1 } },
+        { table: 'user', op: 'CREATE', id: 'user:3', record: { id: 'user:3', _00_rv: 1 } },
+      ]);
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].items.map((i) => i.id)).toEqual(['user:1', 'user:2', 'user:3']);
+      expect(receiver.received).toHaveLength(1);
+      expect(receiver.received[0].queryHash).toBe('q1');
+      expect(receiver.received[0].localArray).toHaveLength(3);
+      expect(receiver.received[0].op).toBe('CREATE');
+      expect(receiver.received[0].circuitStepMs).toBe(4);
+    });
+
+    it('never calls the bulk path for an empty batch', () => {
+      const { svc, calls } = makeBulkService();
+      svc.addReceiver(receiver);
+
+      svc.ingestMany([]);
+
+      expect(calls).toHaveLength(0);
+      expect(receiver.received).toHaveLength(0);
+    });
+  });
 });

package/src/services/stream-processor/wasm-types.ts

@@ -34,6 +34,10 @@ export interface WasmIngestItem {
 // Interface matching the Sp00kyProcessor class from WASM
 export interface WasmProcessor {
   ingest(table: string, op: string, id: string, record: any): WasmStreamUpdate[];
+  // Bulk ingest: ONE circuit step for the whole array, returning the coalesced
+  // updates. Optional because a stale WASM build won't have it — callers guard
+  // with `typeof x === 'function'` and fall back to a loop over `ingest`.
+  ingest_many?(items: WasmIngestItem[]): WasmStreamUpdate[];
   register_view(config: WasmQueryConfig): WasmStreamUpdate | undefined;
   unregister_view(id: string): void;
   // Seed per-table `select` permission predicates ({ [table]: whereText }) so

package/src/sp00ky.local-first.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Structural guard, in the spirit of sp00ky.init-query.test.ts: the paint path
+// must stay network-free. `init()` resolves as soon as the LOCAL store is
+// usable, and every consumer gates its first render on that, so anything that
+// reaches the network belongs in `initRemote()` instead.
+//
+// This is the invariant that makes a warm reload instant and an offline boot
+// possible at all. It is easy to undo by adding one innocent-looking `await`,
+// hence a test rather than a comment.
+const source = readFileSync(join(__dirname, 'sp00ky.ts'), 'utf8');
+
+function methodBody(name: string): string {
+  const re = new RegExp(`(?:private )?async ${name}\\([^)]*\\)[^{]*\\{[\\s\\S]*?\\n  \\}`);
+  const m = re.exec(source);
+  if (!m) throw new Error(`could not locate ${name}()`);
+  return m[0];
+}
+
+describe('local-first boot', () => {
+  const init = methodBody('init');
+
+  it('init() never awaits the remote', () => {
+    expect(init).not.toMatch(/await this\.remote\./);
+    expect(init).not.toMatch(/await this\.auth\.init\(\)/);
+  });
+
+  it('init() hands the network half off without awaiting it', () => {
+    expect(init).toMatch(/void this\.initRemote\(\)/);
+  });
+
+  it('init() restores the session locally and marks the client ready', () => {
+    expect(init).toMatch(/await this\.auth\.restoreSessionFromToken\(\)/);
+    expect(init).toMatch(/this\.localReady = true/);
+  });
+
+  it('the query-id salt is minted locally, not fetched from the server', () => {
+    // No remaining CALL - the surviving mentions are comments explaining why.
+    expect(source).not.toMatch(/query[^\n]*RETURN <string>session::id\(\)/);
+    expect(init).toMatch(/this\.mintSessionSalt\(\)/);
+  });
+
+  it('permissions are seeded before anything can register a view', () => {
+    const perms = init.indexOf('setPermissions(');
+    const restore = init.indexOf('restoreSessionFromToken');
+    expect(perms).toBeGreaterThan(-1);
+    expect(perms).toBeLessThan(restore);
+  });
+
+  it('initRemote() tolerates an unreachable server and still supervises', () => {
+    const remote = methodBody('initRemote');
+    // connect is wrapped, not fatal
+    expect(remote).toMatch(/try\s*\{[\s\S]*await this\.remote\.connect\(\)[\s\S]*\}\s*catch/);
+    // and the supervisor starts regardless, or a boot-time failure never heals
+    const connectCatchEnd = remote.indexOf('connectionSupervisor.start()');
+    expect(connectCatchEnd).toBeGreaterThan(-1);
+  });
+});

package/src/sp00ky.ts

@@ -334,6 +334,17 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private sync: Sp00kySync<S>;
   private devTools: DevToolsService;
   private crdtManager: 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.
+   */
+  private localReady = false;
+  // Principal the current query-id salt was minted for (`null` = signed out).
+  // Rotated only on a real auth flip: see the call sites in `init`.
+  private saltUserId: string | null = null;
   private featureFlags!: FeatureFlagModule<S>;
   private appReleases!: AppReleaseModule<S>;
   // Query hashes already preloaded this session — skip redundant one-shot
@@ -831,16 +842,6 @@ export class Sp00kyClient<S extends SchemaStructure> {
         this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Schema provisioned');
       }
 
-      await this.remote.connect();
-      // Start supervising only after the first connect succeeds, so a boot-time
-      // failure surfaces as a thrown init() rather than being silently absorbed
-      // into a background retry loop.
-      this.connectionSupervisor.start();
-      this.logger.debug(
-        { Category: 'sp00ky-client::Sp00kyClient::init' },
-        'Remote database connected'
-      );
-
       // Warm the blob cache in the background. Deliberately NOT awaited, and
       // deliberately after `remote.connect()`: this walks the OPFS directory to
       // rebuild the manifest, and awaiting it ahead of the socket delayed the
@@ -870,26 +871,31 @@ export class Sp00kyClient<S extends SchemaStructure> {
         'StreamProcessor initialized'
       );
 
-      await this.auth.init();
-      this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Auth initialized');
 
-      // Salt query-id hashing with the SurrealDB session id so two browsers
-      // for the same user don't collide on shared `_00_query` rows. The same
-      // session id is the `session_id` key in `_00_cursor` rows, so the
-      // CrdtManager needs it too.
-      //
-      // Deliberately NOT refreshed on reconnect, even though `session::id()`
-      // does change with every WebSocket session. The salt keys `_00_query`
-      // rows and local cache entries, so rotating it would invalidate every
-      // query hash and force a full re-register plus a cache-key migration on
-      // each blip. Those rows stay valid because the TTL heartbeat keeps them
-      // alive, not because the session that created them is still open — so a
-      // stable salt across reconnects is the correct behavior. Auth flips are
-      // the one case that must rotate it (below): a sign-in is a different
-      // principal, not the same session on a new socket.
-      const sessionId = await this.fetchSessionId();
+      // Restore the session from the cached JWT, with no network. This is what
+      // lets the rest of the boot - and the app on top of it - proceed as a
+      // signed-in user before a socket exists. `initRemote()` verifies the
+      // token afterwards and signs out for real if the server rejects it.
+      const restoredUserId = await this.auth.restoreSessionFromToken();
+
+      // Salt for query-id hashing, minted locally (see `mintSessionSalt`). It
+      // is stable for the life of this client: the salt keys `_00_query` rows
+      // and local cache entries, so rotating it would invalidate every query
+      // hash and force a full re-register. Auth flips are the one case that
+      // must rotate it - a sign-in is a different principal.
+      const sessionId = this.mintSessionSalt();
+      this.saltUserId = restoredUserId;
       await this.dataModule.init(sessionId);
       this.crdtManager.setSessionId(sessionId);
+
+      // Route queries and satisfy `$auth`-gated permission predicates from the
+      // restored identity, BEFORE anything can register. Without this a query
+      // registering pre-verification would target the wrong
+      // `_00_query_user_<id>` table and register a permission-dead SSP view.
+      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'
@@ -920,10 +926,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
         // locally instead of being rejected. Set synchronously BEFORE the
         // first `await` (like `setCurrentUserId` above) so queries that
         // re-register on this auth flip see the fresh context, not a stale one.
-        this.streamProcessor.setSessionAuth(
-          this.auth.currentUser?.id ? encodeRecordId(this.auth.currentUser.id) : null,
-          this.auth.access
-        );
+        this.streamProcessor.setSessionAuth(this.sessionAuthId(), this.auth.access);
         // Record the target bucket synchronously (still before the first
         // `await`) so a reload mid-switch boots straight into the right store.
         writeBootBucketHint(bucketIdForUser(userId));
@@ -931,9 +934,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
         // + latest-target-wins internally; no-op when the bucket already
         // matches (the boot-hint warm path).
         await this.ensureLocalBucket(userId);
-        const next = await this.fetchSessionId();
-        this.dataModule.setSessionId(next);
-        this.crdtManager.setSessionId(next);
+        // Only rotate the salt when the PRINCIPAL actually changed: a sign-in or
+        // sign-out is a different principal and must not keep the old
+        // principal's query ids, but the first fire of this callback after boot
+        // carries the same user the salt was already minted for, and rotating
+        // there would invalidate every query hash for no change in value.
+        // Canonicalize with the SAME encoding the restore path used, NOT
+        // String(): after background verification this callback carries a
+        // RecordId, while a session restored from the token carries the plain
+        // "table:id" string. Comparing their raw stringifications made every
+        // warm boot look like a principal change, which rotated the salt and
+        // re-registered every mounted query - the list painted from cache and
+        // then emptied a second later.
+        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) {
@@ -959,10 +978,21 @@ export class Sp00kyClient<S extends SchemaStructure> {
         'AppReleaseModule initialized'
       );
 
+      // LOCAL BOOT IS DONE — the client can serve reads. Consumers gate their
+      // UI on this resolving, so everything above must stay network-free.
+      this.localReady = true;
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kyClient::init' },
-        'Sp00kyClient initialization completed successfully'
+        'Sp00kyClient local initialization completed; connecting in the background'
       );
+
+      // The network half, deliberately NOT awaited. Nothing above needed it:
+      // queries paint from the local store, `sync.init()` tolerates a closed
+      // socket, and the session was restored from the cached token. Awaiting
+      // this was the entire reason a warm reload sat on a loading screen for
+      // seconds over data the browser already had on disk - and the reason an
+      // offline boot never completed at all.
+      void this.initRemote();
     } catch (e) {
       this.logger.error(
         { error: e, Category: 'sp00ky-client::Sp00kyClient::init' },
@@ -972,6 +1002,54 @@ export class Sp00kyClient<S extends SchemaStructure> {
     }
   }
 
+  /**
+   * 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.
+   */
+  private async initRemote(): Promise<void> {
+    try {
+      await this.remote.connect();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::initRemote' },
+        'Remote database connected'
+      );
+    } catch (e) {
+      // NOT fatal. This used to throw out of init() and leave the consuming app
+      // on its loading screen forever with no network. The supervisor (started
+      // unconditionally below) owns the retry from here.
+      this.logger.warn(
+        { err: e, Category: 'sp00ky-client::Sp00kyClient::initRemote' },
+        'Remote connect failed; running from the local store and retrying in the background'
+      );
+    }
+
+    // Started whether or not the first connect succeeded - it is the thing that
+    // revives the socket, so gating it on a successful connect would mean a
+    // boot-time failure never recovered.
+    this.connectionSupervisor.start();
+
+    try {
+      // Verifies the optimistically restored token against the server. On a
+      // rejected token this signs out for real; on an unreachable server it
+      // keeps the cached session (see AuthService.check).
+      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'
+      );
+    }
+  }
+
   // Serializes bucket switches from rapid auth flips; `pendingBucketTarget`
   // makes intermediate targets collapse (A→anon→B never opens the anon bucket).
   private bucketSwitchChain: Promise<void> = Promise.resolve();
@@ -1518,26 +1596,53 @@ export class Sp00kyClient<S extends SchemaStructure> {
     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(): boolean {
+    return this.localReady;
+  }
+
   async useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T> {
     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).
+   * 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.
    */
-  private async fetchSessionId(): Promise<string> {
-    try {
-      const [sid] = await this.remote.query<[string]>('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 '';
-    }
+  /**
+   * 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.
+   */
+  private sessionAuthId(): string | null {
+    const id = this.auth.currentUser?.id;
+    if (!id) return null;
+    return typeof id === 'string' ? id : encodeRecordId(id);
+  }
+
+  private mintSessionSalt(): string {
+    const c: Crypto | undefined =
+      typeof globalThis !== 'undefined' ? (globalThis as { crypto?: Crypto }).crypto : undefined;
+    if (c?.randomUUID) return c.randomUUID();
+    // Older browsers / non-secure contexts: uniqueness is all that is required.
+    return `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
   }
 }