@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/src/sp00ky.ts

@@ -0,0 +1,1693 @@
+import { DataModule } from './modules/data/index';
+import type {
+  Sp00kyConfig,
+  QueryTimeToLive,
+  QueryStatusCallback,
+  Sp00kyQueryResultPromise,
+  PersistenceClient,
+  PreloadOptions,
+  UpdateOptions,
+  RunOptions,
+  SyncHealth,
+  StorageHealth,
+} from './types';
+import {
+  ConnectionSupervisor,
+  LocalMigrator,
+  RemoteDatabaseService,
+  createLocalEngine,
+} from './services/database/index';
+import type { LocalStore } from './services/database/index';
+import { StaleEpochError } from './services/database/index';
+import type { UpEvent } from './modules/sync/index';
+import { Sp00kySync } from './modules/sync/index';
+import type {
+  FinalQuery,
+  GetTable,
+  InnerQuery,
+  QueryOptions,
+  SchemaStructure,
+  TableModel,
+  TableNames,
+  BucketNames,
+  BackendNames,
+  BackendRoutes,
+  RoutePayload,
+} from '@spooky-sync/query-builder';
+import { QueryBuilder } from '@spooky-sync/query-builder';
+
+import { DevToolsService } from './modules/devtools/index';
+import { createLogger } from './services/logger/index';
+import { AuthService } from './modules/auth/index';
+import { StreamProcessorService } from './services/stream-processor/index';
+import { extractSelectPermissions } from './services/stream-processor/permissions';
+import { EventSystem } from './events/index';
+import { CacheModule } from './modules/cache/index';
+import type { RecordWithId } from './modules/cache/index';
+import { CrdtManager, CrdtField } from './modules/crdt/index';
+import { preloadLoro } from './modules/crdt/loro-loader';
+import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
+import type { FeatureFlagOptions, FeatureFlagOverride } from './modules/feature-flag/index';
+import { AppReleaseModule, AppReleaseHandle } from './modules/app-release/index';
+import type { AppReleaseOptions } from './modules/app-release/index';
+import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
+import { ANON_USER_ID, bucketIdForUser } from './modules/ref-tables';
+import { parseQueryParams, encodeRecordId, parseDuration } from './utils/index';
+import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
+import { ResilientPersistenceClient } from './services/persistence/resilient';
+import { detectSharedTabsSupport } from './services/tabs/support';
+import { TabsCoordinator, type CoordinatorHooks } from './services/tabs/coordinator';
+import { computeTabsFingerprint, hash53, type TabRole } from './services/tabs/protocol';
+import type { SqliteCacheEngine } from './services/database/sqlite-cache-engine';
+import type { BlobCache, BlobReadOptions, BlobUrlLease } from './services/blobs/index';
+import { MemoryBlobStore, createBlobCache, resolveBlobBudget } from './services/blobs/index';
+
+import {
+  blurhashSidecarPath,
+  encodeImageToBlurhash,
+  isImagePath,
+  isBlurhashValid,
+  type BlurhashSetting,
+  type BlurhashEncodeOptions,
+} from './utils/blurhash';
+
+/** Coerce whatever the `.get()` RPC hands back into a Blob. */
+export function bucketContentToBlob(content: unknown): Blob | null {
+  if (content == null) return null;
+  if (content instanceof Blob) return content;
+  if (typeof content === 'string') return new Blob([content]);
+  if (content instanceof ArrayBuffer) return new Blob([content]);
+  // Uint8Array and friends. The cast sidesteps `ArrayBufferLike` vs
+  // `ArrayBuffer` (SharedArrayBuffer) in lib.dom's BlobPart.
+  if (ArrayBuffer.isView(content)) return new Blob([content as unknown as BlobPart]);
+  return null;
+}
+
+export interface BucketPutOptions {
+  /** Override the client-level {@link Sp00kyConfig.blurhash} setting for this put. */
+  blurhash?: BlurhashSetting;
+}
+
+export interface BucketPutResult {
+  /** The computed blurhash when the content was a hashable image; else null. */
+  blurhash: string | null;
+}
+
+interface BucketHandleSettings {
+  blurhash?: BlurhashSetting;
+  logger?: { warn: (obj: unknown, msg?: string) => void };
+}
+
+/**
+ * Paths known to have no blurhash sidecar, per tab. The blob cache has no
+ * negative caching, so without this every mount of a hashless image would pay
+ * one serialized remote read. Cleared when a put writes a sidecar or a delete
+ * removes the image. Keyed `${bucket}:${path}` (the image path, not the sidecar).
+ */
+const missingBlurhash = new Set<string>();
+
+export class BucketHandle {
+  constructor(
+    private bucketName: string,
+    private remote: RemoteDatabaseService,
+    /** Absent on the raw handle the cache itself reads through. */
+    private blobs?: BlobCache | null,
+    private settings?: BucketHandleSettings
+  ) {}
+
+  /** Effective blurhash setting: per-call option > client config > default ON. */
+  private resolveBlurhash(option?: BlurhashSetting): BlurhashEncodeOptions | null {
+    const setting = option ?? this.settings?.blurhash ?? true;
+    if (setting === false) return null;
+    return setting === true ? {} : setting;
+  }
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult> {
+    // Start hashing while the upload is in flight; both browser-side costs
+    // overlap and the sidecar put only queues once the main put resolved.
+    const encodeOptions = this.resolveBlurhash(options?.blurhash);
+    const hashPromise =
+      encodeOptions && isImagePath(path)
+        ? encodeImageToBlurhash(content, encodeOptions)
+        : Promise.resolve(null);
+
+    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+    // A path can be overwritten, so anything cached under it is now wrong.
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+
+    // The sidecar is best-effort: a hash or sidecar failure must never fail
+    // the image put that triggered it.
+    let hash: string | null = null;
+    try {
+      hash = await hashPromise;
+      if (hash) {
+        const sidecar = blurhashSidecarPath(path);
+        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, {
+          content: hash,
+        });
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+        missingBlurhash.delete(`${this.bucketName}:${path}`);
+      }
+    } catch (error) {
+      hash = null;
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar put failed');
+    }
+    return { blurhash: hash };
+  }
+
+  /**
+   * The blurhash stored alongside an uploaded image (see
+   * {@link blurhashSidecarPath}), or null when there is none. Reads through the
+   * blob cache, so a warm client answers from OPFS without a network hop, and
+   * misses are remembered per tab so a hashless image costs at most one
+   * serialized remote read per session.
+   */
+  async blurhash(path: string): Promise<string | null> {
+    const cacheKey = `${this.bucketName}:${path}`;
+    if (missingBlurhash.has(cacheKey)) return null;
+    try {
+      const blob = await this.read(blurhashSidecarPath(path), { persist: true });
+      if (!blob) {
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      const hash = (await blob.text()).trim();
+      if (!isBlurhashValid(hash).result) {
+        this.settings?.logger?.warn({ path }, 'blurhash sidecar holds an invalid hash');
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      return hash;
+    } catch (error) {
+      // Transient failure: do NOT negative-cache, the next mount may succeed.
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar read failed');
+      return null;
+    }
+  }
+
+  async get(path: string): Promise<unknown> {
+    const [result] = await this.remote.query<[unknown]>(
+      `RETURN f"${this.bucketName}:/${path}".get();`
+    );
+    return result;
+  }
+
+  /**
+   * Read through the local blob cache: OPFS first, the bucket second. Unlike
+   * {@link get} this survives a reload and works offline. Returns null when the
+   * file exists in neither place.
+   */
+  async read(path: string, options?: BlobReadOptions): Promise<Blob | null> {
+    if (!this.blobs) return bucketContentToBlob(await this.get(path));
+    return this.blobs.read({ bucket: this.bucketName, path }, options);
+  }
+
+  /**
+   * A refcounted object URL for `path`, suitable for `<img src>`. The caller
+   * MUST call `release()` when the URL goes off screen. Returns null when the
+   * file does not exist, or when object URLs are unavailable (non-browser).
+   */
+  async url(path: string, options?: BlobReadOptions): Promise<BlobUrlLease | null> {
+    if (!this.blobs) return null;
+    return this.blobs.acquireUrl({ bucket: this.bucketName, path }, options);
+  }
+
+  /** Exempt `path` from pressure eviction. Pinned bytes never expire. */
+  pin(path: string): void {
+    this.blobs?.setPinned({ bucket: this.bucketName, path }, true);
+  }
+
+  unpin(path: string): void {
+    this.blobs?.setPinned({ bucket: this.bucketName, path }, false);
+  }
+
+  /** Drop `path` from the local cache without touching the remote file. */
+  async evict(path: string): Promise<void> {
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+  }
+
+  /** Warm the cache for offline use. Already-cached paths are skipped. */
+  async prefetch(paths: string[]): Promise<void> {
+    await this.blobs?.prefetch(paths.map((path) => ({ bucket: this.bucketName, path })));
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+    // Symmetry with put: an image's blurhash sidecar dies with it. Best-effort,
+    // the sidecar may simply not exist.
+    if (isImagePath(path)) {
+      const sidecar = blurhashSidecarPath(path);
+      try {
+        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+      } catch {
+        // Nothing to clean up.
+      }
+      missingBlurhash.delete(`${this.bucketName}:${path}`);
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const [result] = await this.remote.query<[boolean]>(
+      `RETURN f"${this.bucketName}:/${path}".exists();`
+    );
+    return result;
+  }
+
+  async head(path: string): Promise<Record<string, unknown>> {
+    const [result] = await this.remote.query<[Record<string, unknown>]>(
+      `RETURN f"${this.bucketName}:/${path}".head();`
+    );
+    return result;
+  }
+
+  async copy(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, {
+      target: targetPath,
+    });
+  }
+
+  async rename(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, {
+      target: targetPath,
+    });
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const p = prefix ?? '';
+    const [result] = await this.remote.query<[string[]]>(
+      `RETURN f"${this.bucketName}:/${p}".list();`
+    );
+    return result;
+  }
+}
+
+/**
+ * Boot hint for which local bucket to open before auth resolves. Written to
+ * PLAIN localStorage (never the configured persistenceClient): the surrealdb
+ * persistence client stores its keys INSIDE a bucket, and the whole point of
+ * the hint is to pick the bucket before any bucket is open. A warm reload of a
+ * signed-in user thus opens their own bucket immediately — zero switches.
+ * Losing the hint is fail-closed: boot lands on the anon bucket and the auth
+ * callback switches to the user's bucket (cache + outbox intact).
+ */
+const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
+
+/** Reported for engines that don't track local-store durability. Frozen so a
+ *  subscriber can't mutate the shared snapshot. */
+const UNKNOWN_STORAGE_HEALTH: StorageHealth = Object.freeze({
+  status: 'unknown',
+  fallback: false,
+});
+
+function readBootBucketHint(): string | null {
+  try {
+    return typeof localStorage !== 'undefined' ? localStorage.getItem(LAST_BUCKET_KEY) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeBootBucketHint(bucketId: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') localStorage.setItem(LAST_BUCKET_KEY, bucketId);
+  } catch {
+    /* private-mode storage errors: boot just falls back to the anon bucket */
+  }
+}
+
+export class Sp00kyClient<S extends SchemaStructure> {
+  private local: LocalStore;
+  private remote: RemoteDatabaseService;
+  private blobs: BlobCache;
+  private connectionSupervisor: ConnectionSupervisor;
+  private persistenceClient: PersistenceClient;
+
+  private migrator: LocalMigrator;
+  private cache: CacheModule;
+  private dataModule: DataModule<S>;
+  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
+  // fetches when the same preload query is requested again (e.g. a list row
+  // re-rendering). Cleared on process/session end only.
+  private preloadedHashes = new Set<number>();
+  // In-flight background init chains (instant-hydrate + register enqueue) keyed
+  // by registration hash. Concurrent mounts of the same query reuse the one
+  // chain instead of double-hydrating and double-enqueuing `register`.
+  // Sequential re-mounts intentionally start a fresh chain — the unconditional
+  // `register` re-enqueue is what freshens a warm preload on use.
+  private pendingQueryInits = new Map<string, Promise<void>>();
+
+  private logger: ReturnType<typeof createLogger>;
+  public auth: AuthService<S>;
+  public streamProcessor: StreamProcessorService;
+
+  // Shared-tabs: non-null when the capability gate passed at construction.
+  // The coordinator owns role state; `sharedActive` flips false if the broker
+  // rejects/times out and this tab permanently falls back to solo.
+  private tabsCoordinator: TabsCoordinator | null = null;
+  private sharedActive = false;
+
+  /** Current shared-tabs role, or null when the feature is off/fell back. */
+  get tabRole(): TabRole | null {
+    return this.sharedActive ? this.tabsCoordinator!.role : null;
+  }
+
+  get remoteClient() {
+    return this.remote.getClient();
+  }
+
+  get localClient() {
+    return this.local.getClient();
+  }
+
+  get pendingMutationCount(): number {
+    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(): number {
+    return this.sync.liveRetryCount;
+  }
+
+  subscribeToPendingMutations(cb: (count: number) => void): () => void {
+    return this.sync.subscribeToPendingMutations(cb);
+  }
+
+  /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+  get syncHealth(): SyncHealth {
+    return this.sync.syncHealth;
+  }
+
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Returns an unsubscribe.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    return this.sync.subscribeToSyncHealth(cb);
+  }
+
+  /** Durability of the local cache. See {@link StorageHealth}. `'unknown'` for
+   *  engines that don't report it. */
+  get storageHealth(): StorageHealth {
+    return this.local.storageHealth ?? UNKNOWN_STORAGE_HEALTH;
+  }
+
+  /**
+   * Observe local-store durability. Fires immediately with the current snapshot
+   * and again on every change (at most once per bucket open in practice).
+   * Returns an unsubscribe.
+   */
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    if (this.local.subscribeToStorageHealth) {
+      return this.local.subscribeToStorageHealth(cb);
+    }
+    cb(UNKNOWN_STORAGE_HEALTH);
+    return () => {};
+  }
+
+  constructor(private config: Sp00kyConfig<S>) {
+    const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit);
+    this.logger = logger.child({ service: 'Sp00kyClient' });
+
+    this.logger.info(
+      {
+        config: { ...config, schema: '[SchemaStructure]' },
+        Category: 'sp00ky-client::Sp00kyClient::constructor',
+      },
+      'Sp00kyClient initialized'
+    );
+
+    // Preload the loro CRDT engine at startup (fetches the chunk on page load)
+    // so the first `openCrdtField` doesn't block on a network round-trip. Left
+    // off, loro is never loaded unless a CRDT field is explicitly opened.
+    if (config.crdt) void preloadLoro();
+
+    // The default ('surrealdb') engine is a SurrealCacheEngine — a drop-in
+    // subclass of LocalDatabaseService that adds the engine-neutral verb surface
+    // with zero behavior change. Alternate engines (e.g. 'sqlite') require the
+    // raw-SurrealQL call-site migration before they can back `this.local`.
+    const tabsSupport = detectSharedTabsSupport(this.config);
+    this.local = createLocalEngine(this.config.localEngine, this.config.database, logger, {
+      shared: tabsSupport.supported,
+    });
+    this.remote = new RemoteDatabaseService(this.config.database, logger);
+    // Owns socket liveness for the life of the client: re-opens the connection
+    // when the SDK's own reconnect gives up, and heartbeats to catch a socket
+    // that died without ever firing a `close` event.
+    this.connectionSupervisor = new ConnectionSupervisor(this.remote, logger);
+
+    // Durable cache for bucket file bytes. Reads go through a raw (uncached)
+    // handle so the cache's own L2 fetch can't recurse back into itself. The
+    // namespace is provisional: `init()` rebinds it to the boot bucket and
+    // reconciles against what is actually on disk.
+    this.blobs = createBlobCache({
+      local: this.local,
+      namespace: ANON_USER_ID,
+      logger,
+      fetchRemote: async (key) =>
+        bucketContentToBlob(await this.rawBucket(key.bucket).get(key.path)),
+      headRemote: (key) => this.rawBucket(key.bucket).head(key.path),
+      maxBytes: this.config.blobCache?.maxBytes,
+      // Opting out keeps the in-tab dedupe and object-URL refcounting that
+      // existed before this cache, and persists nothing.
+      store:
+        this.config.blobCache?.enabled === false ? new MemoryBlobStore(ANON_USER_ID) : undefined,
+    });
+
+    if (config.persistenceClient === 'surrealdb') {
+      this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);
+    } else if (config.persistenceClient === 'localstorage' || !config.persistenceClient) {
+      this.persistenceClient = new LocalStoragePersistenceClient(logger);
+    } else {
+      this.persistenceClient = config.persistenceClient;
+    }
+
+    this.persistenceClient = new ResilientPersistenceClient(this.persistenceClient, logger);
+
+    this.streamProcessor = new StreamProcessorService(
+      new EventSystem(['stream_update']),
+      this.local,
+      logger
+    );
+    // Circuit snapshots are checkpointed, never per-ingest, and on by default
+    // where the store can hold them (the OPFS SQLite engine). See
+    // `persistCircuit` / `circuitProjection` in types.ts.
+    this.streamProcessor.configureCircuitPersistence(
+      config.persistCircuit ?? config.localEngine === 'sqlite',
+      config.circuitCheckpointMs
+    );
+    this.streamProcessor.configureProjection(config.circuitProjection ?? true);
+    this.migrator = new LocalMigrator(this.local, logger);
+
+    this.cache = new CacheModule(
+      this.local,
+      this.streamProcessor,
+      (update) => {
+        // Direct callback from cache to data module
+        this.dataModule.onStreamUpdate(update);
+      },
+      logger
+    );
+
+    // Initialize CRDT Manager. `local` is used to read the initial
+    // `_00_crdt` snapshot when a field opens AND to mirror every local
+    // edit (so reload/offline see the freshest state); `remote` is used
+    // for the debounced outgoing UPSERTs and the parent-table LIVE feed.
+    // The debounce window is configurable via `crdtDebounceMs`.
+    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
+    );
+
+    // Initialize Auth
+    this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
+
+    // Initialize Sync
+    this.sync = new Sp00kySync(
+      this.local,
+      this.remote,
+      this.cache,
+      this.dataModule,
+      this.config.schema,
+      this.logger,
+      {
+        refSyncIntervalMs: this.config.refSyncIntervalMs,
+        anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
+        // `syncHealth: false` (or `{ degradeAfterConsecutiveFailures: 0 }`)
+        // disables degraded reporting; otherwise default to 3.
+        degradeAfterConsecutiveFailures:
+          this.config.syncHealth === false
+            ? 0
+            : (this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3),
+        pushTimeoutMs: this.config.pushTimeoutMs,
+        downTimeoutMs: this.config.downTimeoutMs,
+        // Read-only: sync mirrors the transport state into `SyncHealth`.
+        connectionSupervisor: this.connectionSupervisor,
+      }
+    );
+    this.sync.setPrimeGate(() => this.streamProcessor.whenPrimed());
+
+    // Initialize feature flags. Reuses the down-queue to register SSP plans
+    // on `_00_user_feature` and the auth subscription to re-register handles
+    // when the signed-in user changes.
+    this.featureFlags = new FeatureFlagModule({
+      dataModule: this.dataModule,
+      sync: this.sync,
+      auth: this.auth,
+      logger,
+    });
+
+    // App release announcements (world-readable `_00_app_release`, written by
+    // spky deploy/release). Same shared-live-query design as feature flags.
+    this.appReleases = new AppReleaseModule({
+      dataModule: this.dataModule,
+      sync: this.sync,
+      auth: this.auth,
+      logger,
+    });
+
+    // Initialize DevTools
+    this.devTools = new DevToolsService(
+      this.local,
+      this.remote,
+      logger,
+      this.config.schema,
+      this.auth,
+      this.dataModule
+    );
+
+    // Let the DevTools Access tab read and write local flag overrides. Done
+    // here rather than via the constructor because FeatureFlagModule is built
+    // above and DevToolsService takes its deps positionally.
+    this.devTools.setFeatureFlagOverrides(this.featureFlags);
+
+    // Register DevTools as a receiver for stream updates
+    this.streamProcessor.addReceiver(this.devTools);
+
+    // Wire up callbacks instead of events
+    this.setupCallbacks();
+
+    // Shared-tabs: construct the coordinator last so its hooks can close over
+    // every module. Nothing starts until init() calls coordinator.start().
+    if (tabsSupport.supported) {
+      this.tabsCoordinator = this.buildTabsCoordinator();
+    } else if (this.config.sharedTabs) {
+      this.logger.info(
+        {
+          reason: (tabsSupport as { reason: string }).reason,
+          Category: 'sp00ky-client::Sp00kyClient::tabs',
+        },
+        'sharedTabs requested but unsupported here; running solo'
+      );
+    }
+    // Report shared-tabs state whenever the feature was REQUESTED, active or
+    // not: "asked to share one store, running alone because X" is exactly the
+    // thing you need to see in the panel. Apps that never set the flag report
+    // null and the panel shows no section at all.
+    if (this.config.sharedTabs) {
+      const unsupportedReason = tabsSupport.supported
+        ? undefined
+        : (tabsSupport as { reason: string }).reason;
+      this.devTools.setTabsInfoProvider(() => {
+        const c = this.tabsCoordinator;
+        if (!this.sharedActive || !c) {
+          return { active: false, reason: unsupportedReason ?? 'fell-back' };
+        }
+        const hub = c.syncHub;
+        return {
+          active: true,
+          role: c.role,
+          tabId: c.tabId,
+          leadershipId: c.leadershipId,
+          leaderTabId: c.role === 'leader' ? c.tabId : c.leaderTabId,
+          ...(hub ? { followers: hub.followerCount, relayedBatches: hub.relayedBatches } : {}),
+        };
+      });
+    }
+    this.devTools.setBlobInfoProvider(() => this.blobs.stats());
+  }
+
+  /** The shared-tabs role machinery, wired to this client's modules. */
+  private buildTabsCoordinator(): TabsCoordinator {
+    const engine = this.local as SqliteCacheEngine;
+    const tabId =
+      typeof crypto !== 'undefined' && crypto.randomUUID
+        ? crypto.randomUUID()
+        : `tab_${Math.random().toString(36).slice(2)}`;
+    const hooks: CoordinatorHooks = {
+      adoptOwner: (bucketId, opts) =>
+        engine.adoptOwner(bucketId, {
+          workerLockName: opts.workerLockName,
+          allowMemoryFallback: opts.allowMemoryFallback,
+          resumeHeld: opts.resumeHeld,
+        }),
+      adoptAttached: (dbPort, snapshot) =>
+        engine.adoptAttached(dbPort, snapshot, (reason) => engine.onLeaderLost(reason)),
+      releaseOwnership: () => engine.releaseOwnership(),
+      onLeaderLost: (reason) => engine.onLeaderLost(reason),
+      exposeClientPort: (clientId, port) => engine.exposeClientPort(clientId, port),
+      removeClientPort: (clientId) => engine.removeClientPort(clientId),
+      becomeSyncLeader: (hub) => {
+        this.streamProcessor.setPersistenceEnabled(true);
+        this.cache.setIngestRelay((tuples) => hub.relayIngest(tuples));
+        this.sync.setTabContext('leader', tabId);
+        this.dataModule.setTabId(tabId);
+        this.sync.promoteToLeader(hub);
+      },
+      resumeSyncLeaderDuties: () => this.sync.resumeLeaderDuties(),
+      becomeSyncFollower: (forwarder) => {
+        this.streamProcessor.setPersistenceEnabled(false);
+        // A follower's own mutations go to the leader, which ingests them and
+        // fans them out to the other followers: one hop, no server round-trip.
+        // Only the mutation path relays; this tab's sync fetches are the
+        // leader's data coming back and must not be re-broadcast.
+        this.cache.setIngestRelay((tuples) => forwarder.ingest(tuples), {
+          localWritesOnly: true,
+        });
+        this.sync.setTabContext('follower', tabId);
+        this.dataModule.setTabId(tabId);
+        // Installs the whole syncPort handler: ingest-relay, list_ref relay,
+        // settled writes, rollbacks.
+        this.sync.demoteToFollower(forwarder);
+      },
+      becomeSyncSolo: () => {
+        this.streamProcessor.setPersistenceEnabled(true);
+        this.cache.setIngestRelay(null);
+        this.sync.setTabContext('solo', tabId);
+      },
+      currentStorageHealth: () =>
+        this.local.storageHealth ?? { status: 'unknown', fallback: false },
+    };
+    return new TabsCoordinator({
+      tabId,
+      fingerprint: computeTabsFingerprint({
+        coreVersion:
+          typeof __SP00KY_CORE_VERSION__ !== 'undefined' ? __SP00KY_CORE_VERSION__ : 'unknown',
+        schemaHash: hash53(this.config.schemaSurql),
+        endpoint: this.config.database.endpoint ?? '',
+        namespace: this.config.database.namespace,
+        database: this.config.database.database,
+      }),
+      hooks,
+      logger: this.logger,
+      onLeaderPageHide: () => {
+        void engine.shutdownOwnedWorker();
+      },
+    });
+  }
+
+  /**
+   * Setup direct callbacks instead of event subscriptions
+   */
+  private setupCallbacks() {
+    // Surface query fetch-status changes (idle/fetching) in DevTools. Logs a
+    // discrete event and triggers a state push so the active-queries panel
+    // reflects the flip immediately.
+    this.dataModule.onQueryStatusChange = (queryHash, status) => {
+      this.devTools.logEvent('QUERY_STATUS_CHANGED', { queryHash, status });
+    };
+
+    // Keep an actively-watched query's remote `_00_query.lastActiveAt` fresh so
+    // the server TTL sweep doesn't expire it out from under live subscribers.
+    // DataModule fires this only while the query still has ≥1 subscriber.
+    this.dataModule.onHeartbeat = (queryHash) => {
+      void this.sync.heartbeatQuery(queryHash).catch((err) => {
+        this.logger.warn(
+          { err, queryHash, Category: 'sp00ky-client::Sp00kyClient::onHeartbeat' },
+          'TTL heartbeat failed'
+        );
+      });
+    };
+
+    // Eager teardown of an opt-in deregistered query: enqueue a `cleanup`
+    // down-event so it's serialized after any in-flight register/sync for the
+    // same query (avoids out-of-order delete-before-create).
+    this.dataModule.onDeregister = (queryHash) => {
+      this.sync.enqueueDownEvent({ type: 'cleanup', payload: { hash: queryHash } });
+    };
+
+    // Mutation callback for sync
+    this.dataModule.onMutation((mutations: UpEvent[]) => {
+      // Notify DevTools
+      this.devTools.onMutation(mutations);
+
+      // Enqueue in Sync
+      if (mutations.length > 0) {
+        this.sync.enqueueMutation(mutations);
+      }
+    });
+
+    // Sync events for incoming updates
+    this.sync.events.subscribe('SYNC_QUERY_UPDATED', (event: any) => {
+      this.devTools.logEvent('SYNC_QUERY_UPDATED', event.payload);
+    });
+
+    // Hand list_ref-driven row ingests to the CrdtManager so CRDT body
+    // / cursor updates reach the receiver even when the cross-session
+    // LIVE on the parent table is filtered out by the SurrealDB
+    // permission-LIVE gap. Same-user clients receive these rows via
+    // CrdtManager's own `LIVE SELECT * FROM <table>`; this hook is the
+    // redundant path that fires when only the list_ref bumped.
+    this.sync.engineEvents.subscribe('SYNC_REMOTE_DATA_INGESTED', (event: any) => {
+      try {
+        const records: Array<Record<string, any>> = event.payload?.records ?? [];
+        for (const row of records) {
+          const id = row?.id;
+          const table =
+            id && typeof id === 'object' && id.table !== undefined ? String(id.table) : undefined;
+          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'
+        );
+      }
+    });
+
+    // Database events for DevTools
+    this.local.getEvents().subscribe('DATABASE_LOCAL_QUERY', (event: any) => {
+      this.devTools.logEvent('LOCAL_QUERY', event.payload);
+    });
+
+    this.remote.getEvents().subscribe('DATABASE_REMOTE_QUERY', (event: any) => {
+      this.devTools.logEvent('REMOTE_QUERY', event.payload);
+    });
+  }
+
+  async init() {
+    this.logger.info(
+      { Category: 'sp00ky-client::Sp00kyClient::init' },
+      'Sp00kyClient initialization started'
+    );
+    try {
+      // Open the bucket the last session used (per-user local stores). If auth
+      // resolves to a different user below, the auth callback switches buckets.
+      const bootBucket = readBootBucketHint() ?? ANON_USER_ID;
+      if (this.tabsCoordinator) {
+        // Shared-tabs: the broker assigns this tab's role; the coordinator's
+        // hooks open the store (leader) or attach to the leader's (follower).
+        // Any failure here (no SharedWorker start, election timeout, rejected
+        // fingerprint) falls back to plain solo boot: exactly the flag-off
+        // path, including the second-tab memory fallback + its warning.
+        // A role can still land AFTER start() gave up (the election that timed
+        // out here keeps running), and when it does this tab really is sharing
+        // the leader's store. Track every transition so the reported state is
+        // the current one instead of frozen at whatever boot saw.
+        this.tabsCoordinator.onRoleChange((role) => {
+          this.sharedActive = role !== 'solo';
+          // Surface the transition in DevTools. Reconstructing a failover from
+          // the `database.tabs` snapshot alone is guesswork after the fact; a
+          // discrete event gives `get_events` the leader handover directly.
+          this.devTools.logEvent('TABS_ROLE_CHANGED', {
+            role,
+            tabId: this.tabsCoordinator?.tabId,
+            leadershipId: this.tabsCoordinator?.leadershipId,
+            leaderTabId: this.tabsCoordinator?.leaderTabId,
+            promotionMs: this.tabsCoordinator?.lastPromotionMs,
+          });
+        });
+        try {
+          const role = await this.tabsCoordinator.start(bootBucket);
+          this.sharedActive = true;
+          this.logger.info(
+            { role, bootBucket, Category: 'sp00ky-client::Sp00kyClient::init' },
+            'Shared-tabs role assigned'
+          );
+        } catch (e) {
+          this.logger.warn(
+            { err: e, Category: 'sp00ky-client::Sp00kyClient::init' },
+            'Shared-tabs unavailable; booting solo'
+          );
+          this.sharedActive = false;
+          await this.local.connect(bootBucket);
+        }
+      } else {
+        await this.local.connect(bootBucket);
+      }
+      this.logger.debug(
+        { bootBucket, Category: 'sp00ky-client::Sp00kyClient::init' },
+        'Local database connected'
+      );
+
+      // Schemaless local engines (SQLite) create tables lazily and need no
+      // SurrealQL DDL provisioning.
+      if (this.local.usesSurqlSchema) {
+        await this.migrator.provision(this.config.schemaSurql);
+        this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Schema provisioned');
+      }
+
+      // 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
+      // connect (and the connection supervisor with it) for no benefit. Reads
+      // await `BlobCache.ready` internally, so a bucket read that lands mid-walk
+      // still sees a reconciled manifest. Best-effort: a cold blob cache is a
+      // slow first image, not a broken client.
+      void (async () => {
+        try {
+          this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
+          await this.blobs.start(bootBucket);
+        } catch (e) {
+          this.logger.warn(
+            { err: e, Category: 'sp00ky-client::Sp00kyClient::init' },
+            'Blob cache failed to start; bucket files will not be cached locally'
+          );
+        }
+      })();
+
+      await this.streamProcessor.init();
+      // Seed table `select` permissions from the schema before any query is
+      // registered — otherwise the SSP default-denies every non-`_00_` table.
+      this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
+      // Fill the circuit from the local store in the background (snapshot +
+      // reconcile, or every cached row). Not awaited: first paint reads the
+      // store directly; sync waits on `whenPrimed` before its first diff.
+      void this.primeCircuit();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        'StreamProcessor initialized'
+      );
+
+
+      // 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'
+      );
+
+      // Refresh the salt whenever auth state flips (sign-in, sign-out).
+      // session::id() changes per WebSocket session, and a sign-in spawns
+      // a new authenticated session, so the salt must follow. Also
+      // forward the user id into `DataModule` and `Sp00kySync` so they
+      // can route to per-user `_00_query_user_<id>` /
+      // `_00_list_ref_user_<id>` tables in `RefMode.Dedicated` — the
+      // LIVE subscription on `_00_list_ref_user_<id>` is restarted
+      // under the new auth context inside `Sp00kySync.setCurrentUserId`
+      // since SurrealDB binds the LIVE permission at registration time.
+      //
+      // Sync prefix BEFORE the first `await`: setting `currentUserId`
+      // synchronously here is critical because the AuthProvider's own
+      // subscribe callback runs right after ours and immediately enables
+      // queries that depend on the user id. Any `await` before
+      // `setCurrentUserId` would let those queries register against the
+      // stale (null) user id and hit the wrong `_00_query[_user_*]`
+      // table.
+      this.auth.subscribe(async (userId) => {
+        this.dataModule.setCurrentUserId(userId);
+        // Mirror the server's `fn::query::register` auth injection for the
+        // in-browser SSP: feed the current user's full record id + access
+        // method so `$auth`-gated table permissions (e.g. `thread`) resolve
+        // 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.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));
+        // FIRST await: swap the local store to this user's bucket. Serialized
+        // + latest-target-wins internally; no-op when the bucket already
+        // matches (the boot-hint warm path).
+        await this.ensureLocalBucket(userId);
+        // 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) {
+          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.featureFlags.init();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        'FeatureFlagModule initialized'
+      );
+
+      this.appReleases.init();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        '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 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' },
+        'Sp00kyClient initialization failed'
+      );
+      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.
+   */
+  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();
+  private pendingBucketTarget: string | null = null;
+
+  /**
+   * Ensure the local store is this user's bucket, switching if needed. Called
+   * from the auth listener on every auth flip; concurrent calls are chained
+   * and superseded intermediates are skipped (latest target wins).
+   */
+  private ensureLocalBucket(userId: string | null): Promise<void> {
+    const target = bucketIdForUser(userId);
+    this.pendingBucketTarget = target;
+    // Close the query gate SYNCHRONOUSLY the instant a switch is pending — the
+    // AuthProvider's own auth subscriber fires right after this (same tick) and
+    // enables queries, and `doSwitchBucket` only runs a microtask later on the
+    // chain. Without closing the gate here, that query is issued through the
+    // still-open gate and is in-flight on the local wasm engine when
+    // `switchStore` closes the client — which wedges the engine (every
+    // subsequent query, including provisioning, hangs → no view ever registers).
+    // No-op when already on the target bucket.
+    const needsSwitch = this.local.currentBucketId !== target;
+    const release = needsSwitch ? this.local.beginSwitch() : null;
+    this.bucketSwitchChain = this.bucketSwitchChain.then(async () => {
+      // Superseded by a newer flip, or already on target: reopen the gate we
+      // closed above and skip the switch.
+      if (this.pendingBucketTarget !== target || this.local.currentBucketId === target) {
+        release?.();
+        return;
+      }
+      await this.doSwitchBucket(target, release);
+    });
+    // Isolate chain failures per-caller: a failed switch must not poison every
+    // future switch. The caller (auth listener) logs it. Reopen the gate on
+    // failure so the client never gets stuck closed.
+    const result = this.bucketSwitchChain;
+    this.bucketSwitchChain = this.bucketSwitchChain.catch(() => {
+      release?.();
+    });
+    return result;
+  }
+
+  /**
+   * The bucket-switch choreography: drain → swap → rebind.
+   *
+   * Drain: sync quiesced (poll/LIVE stopped, in-flight round awaited so its
+   * outbox delete lands in the OLD bucket, debounce timers cancelled),
+   * DataModule timers cleared, CRDT fields closed WITHOUT their final flush
+   * (the remote session already belongs to the next user).
+   *
+   * Swap: gate closes so any local query issued mid-switch (sibling auth
+   * subscribers, FeatureFlagModule) waits and then runs against the NEW
+   * bucket; store swaps open-new-before-close-old; schema provisions
+   * (no-op for a returning bucket); stale `_00_query` rows are wiped (dead
+   * sessionId-salted hashes with stale arrays — record bodies stay warm);
+   * SSP resets to a fresh circuit with re-seeded permissions.
+   *
+   * Rebind: auth token re-persisted (the surrealdb persistence client wrote it
+   * into the OLD bucket's `_00_kv` before this listener ran), active queries
+   * re-homed keeping their hashes, sync resumed on the new bucket's own
+   * outbox, and every query re-registered remotely to refill from the server.
+   */
+  private async doSwitchBucket(target: string, gateRelease?: (() => void) | null): Promise<void> {
+    this.logger.info(
+      {
+        target,
+        from: this.local.currentBucketId,
+        Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket',
+      },
+      'Switching local bucket'
+    );
+
+    const leavingBucket = this.local.currentBucketId;
+
+    await this.sync.prepareBucketSwitch();
+    this.dataModule.quiesce();
+    this.crdtManager.closeAll({ flush: false });
+
+    // Reuse the gate the caller (`ensureLocalBucket`) closed synchronously; only
+    // open our own if called without one (keeps the gate continuously closed
+    // from the auth flip through the swap — no window for a racing query).
+    const reopen = gateRelease ?? this.local.beginSwitch();
+    try {
+      if (this.sharedActive && this.tabsCoordinator) {
+        // Shared-tabs: a bucket switch is a namespace move. Leaving the old
+        // namespace re-elects it (if this tab led it); joining the new one
+        // assigns a fresh role, whose hooks open or attach the store. The
+        // leader wipe-on-pool-open replaces the DELETE _00_query below, and a
+        // joining follower must NOT wipe: other tabs' rows there are live.
+        try {
+          await this.tabsCoordinator.moveToBucket(target);
+        } catch (e) {
+          this.logger.warn(
+            { err: e, target, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
+            'Shared-tabs bucket move failed; switching solo'
+          );
+          this.sharedActive = false;
+          this.sync.setTabContext('solo', null);
+          this.cache.setIngestRelay(null);
+          this.streamProcessor.setPersistenceEnabled(true);
+          await this.local.switchStore(target);
+          await this.local.queryUngated('DELETE _00_query;');
+        }
+      } else {
+        await this.local.switchStore(target);
+        if (this.local.usesSurqlSchema) {
+          await this.migrator.provision(this.config.schemaSurql);
+        }
+        await this.local.queryUngated('DELETE _00_query;');
+      }
+      // Cached bytes are namespaced per local bucket, so the switch is a
+      // repoint, not a wipe: signing back in finds the cache warm. Apps that
+      // want the signed-out user's files gone opt in with `clearOnSignOut`.
+      try {
+        if (
+          this.config.blobCache?.clearOnSignOut &&
+          target === ANON_USER_ID &&
+          leavingBucket !== ANON_USER_ID
+        ) {
+          await this.blobs.clear();
+        }
+        await this.blobs.setNamespace(target);
+      } catch (e) {
+        this.logger.warn(
+          { err: e, target, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
+          'Blob cache bucket switch failed'
+        );
+      }
+      await this.streamProcessor.reset();
+      this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
+      this.cache.clearVersionLookups();
+      void this.primeCircuit();
+      // Preload dedup is per-bucket: the `_00_preload` markers + cached rows it
+      // guards live in the local store we just swapped away from. Keeping the
+      // hashes would make `preload()` skip warming the NEW bucket (its store is
+      // empty), so every thread/comment prewarm silently no-ops after login.
+      this.preloadedHashes.clear();
+    } finally {
+      reopen();
+    }
+
+    if (this.auth.token) {
+      try {
+        await this.persistenceClient.set('sp00ky_auth_token', this.auth.token);
+      } catch (e) {
+        this.logger.warn(
+          { error: e, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
+          'Failed to re-persist auth token into the new bucket'
+        );
+      }
+    }
+
+    const hashes = await this.dataModule.rebindAfterBucketSwitch();
+    await this.sync.completeBucketSwitch();
+    for (const hash of hashes) {
+      this.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+    }
+
+    this.logger.info(
+      { target, queries: hashes.length, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
+      'Local bucket switch complete'
+    );
+  }
+
+  async close() {
+    // Before anything else: a live supervisor would read the intentional
+    // `remote.close()` below as a failure and immediately reconnect.
+    this.connectionSupervisor.dispose();
+    await this.featureFlags.closeAll();
+    await this.appReleases.closeAll();
+    this.crdtManager.closeAll();
+    this.crdtManager.dispose();
+    // Flush the blob manifest while the local store is still open — the flush
+    // writes `_00_blob` rows through it — and revoke every object URL.
+    await this.blobs.close().catch(() => {});
+    // Last chance to persist the circuit while the store is still ours.
+    await this.streamProcessor.checkpoint('close').catch(() => {});
+    // Leaving the broker first hands leadership to another tab (and releases
+    // the OPFS handles via the worker shutdown) before the store closes.
+    if (this.tabsCoordinator) await this.tabsCoordinator.stop();
+    await this.local.close();
+    await this.remote.close();
+    // Free the wasm circuit explicitly. V8 cannot see wasm-internal bytes, so
+    // relying on the wasm-bindgen FinalizationRegistry leaves the whole store
+    // resident until a GC that may never come, and a client that is recreated
+    // (provider remount, HMR) would stack circuits.
+    this.streamProcessor.dispose();
+  }
+
+  /**
+   * Subscribe to a feature flag for the current user. Returns a
+   * `FeatureFlagHandle` whose `variant()`, `payload()` and `enabled()`
+   * accessors reflect the latest assignment from `_00_user_feature`,
+   * and whose `subscribe(cb)` fires whenever that assignment changes.
+   *
+   * Permissions are enforced by SurrealDB: a client can only ever see
+   * its own row, and cannot create or modify assignments.
+   */
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle {
+    return this.featureFlags.feature(key, options);
+  }
+
+  /**
+   * Force a feature flag to `variant` in THIS browser only; `null` clears it.
+   *
+   * Nothing is sent to the server — the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage, survives reloads, and applies while signed out. Backs the
+   * DevTools Access tab, and is a convenient hook for tests.
+   *
+   * To change a flag for OTHER users you need admin rights (`spky admin add`)
+   * and the DevTools Access tab, or `spky flag`.
+   */
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void {
+    this.featureFlags.setLocalOverride(key, variant, payload);
+  }
+
+  /** Drop every local feature flag override set via `setFeatureOverride`. */
+  clearFeatureOverrides(): void {
+    this.featureFlags.clearLocalOverrides();
+  }
+
+  /** The local feature flag overrides currently in effect, keyed by flag. */
+  getFeatureOverrides(): Record<string, FeatureFlagOverride> {
+    return this.featureFlags.getLocalOverrides();
+  }
+
+  /**
+   * Observe the announced release of an app (`_00_app_release:<app>`, written
+   * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
+   * announced version plus the cache-bust/mandatory flags, and
+   * `updateAvailable(currentVersion)` compares it semver-wise against the
+   * running build. World-readable; writes are root-only.
+   */
+  appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle {
+    return this.appReleases.release(app, options);
+  }
+
+  authenticate(token: string) {
+    return this.remote.getClient().authenticate(token);
+  }
+
+  /**
+   * 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 the parent table for real-time sync;
+   * incoming events trigger a subquery fetch of `_00_crdt` / `_00_cursor`.
+   */
+  async openCrdtField(
+    table: string,
+    recordId: string,
+    field: string,
+    fallbackText?: string
+  ): Promise<CrdtField> {
+    return this.crdtManager.open(table, recordId, field, fallbackText);
+  }
+
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void {
+    this.crdtManager.close(table, recordId, field);
+  }
+
+  deauthenticate() {
+    return this.remote.getClient().invalidate();
+  }
+
+  query<Table extends TableNames<S>>(
+    table: Table,
+    options: QueryOptions<TableModel<GetTable<S, Table>>, false>,
+    ttl: QueryTimeToLive = '10m'
+  ): QueryBuilder<S, Table, Sp00kyQueryResultPromise> {
+    return new QueryBuilder<S, Table, Sp00kyQueryResultPromise>(
+      this.config.schema,
+      table,
+      async (q) => ({
+        hash: await this.initQuery(table, q, ttl),
+      }),
+      options
+    );
+  }
+
+  private async initQuery<Table extends TableNames<S>>(
+    table: Table,
+    q: InnerQuery<any, any, any>,
+    ttl: QueryTimeToLive
+  ) {
+    const tableSchema = this.config.schema.tables.find((t) => t.name === table);
+    if (!tableSchema) {
+      throw new Error(`Table ${table} not found`);
+    }
+
+    const params = parseQueryParams(tableSchema.columns, q.selectQuery.vars ?? {});
+    const hash = await this.dataModule.query(
+      table,
+      q.selectQuery.query,
+      params,
+      ttl,
+      q.selectQuery.plan
+    );
+
+    // Local-first paint: the hash is returned as soon as the LOCAL registration
+    // above completes — `queryState.records` is already seeded from the local
+    // cache/SSP snapshot, so `useQuery` subscribes and paints from memory with
+    // zero network on the paint path. Instant-hydrate and the `register`
+    // down-event continue in a background chain (hydrate strictly before
+    // enqueue, so a stale one-shot snapshot can never land after the sync's
+    // authoritative `_00_list_ref` overwrite). Concurrent mounts of the same
+    // query share one chain; a sequential re-mount starts a fresh one so its
+    // `register` re-enqueue keeps freshening warm data on use.
+    if (!this.pendingQueryInits.has(hash)) {
+      const chain = this.finishQueryInit(hash, q, params).finally(() => {
+        this.pendingQueryInits.delete(hash);
+      });
+      this.pendingQueryInits.set(hash, chain);
+    }
+
+    return hash;
+  }
+
+  /**
+   * Background tail of {@link initQuery}: instant-hydrate (opt-in via
+   * `config.instantHydrate`, and only when the query is cold) followed by
+   * enqueuing the `register` down-event. Never rejects — both halves catch and
+   * log, so `void`-ing the returned promise can't produce an unhandled
+   * rejection. By default (hydrate off) the register lifecycle is the single
+   * freshness path; the one-shot fetch is an optimization apps enable
+   * explicitly, and it runs regardless of preload state — cache-first delivery
+   * never depends on WHY rows are cached.
+   */
+  private async finishQueryInit(
+    hash: string,
+    q: InnerQuery<any, any, any>,
+    params: Record<string, any>
+  ): Promise<void> {
+    if (this.config.instantHydrate === true && this.dataModule.isCold(hash)) {
+      try {
+        // Fence against bucket switches: rows fetched under the previous
+        // auth context must not hydrate the new bucket's query state — the
+        // rebind's re-registration refills it from the right context.
+        const epoch = this.local.epoch;
+        const [rows] = await this.remote.query<[RecordWithId[]]>(q.selectQuery.query, params);
+        if (epoch === this.local.epoch) {
+          await this.dataModule.applyHydration(hash, rows ?? []);
+        }
+      } catch (err) {
+        if (err instanceof StaleEpochError) {
+          this.logger.debug(
+            { hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
+            'Dropped instant hydrate from before a bucket switch'
+          );
+        } else {
+          this.logger.warn(
+            { err, hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
+            'Instant hydrate failed; proceeding with registration'
+          );
+        }
+      }
+    }
+
+    try {
+      await this.sync.enqueueDownEvent({
+        type: 'register',
+        payload: {
+          hash,
+        },
+      });
+    } catch (err) {
+      this.logger.error(
+        { err, hash, Category: 'sp00ky-client::Sp00kyClient::initQuery' },
+        'Failed to enqueue register down-event'
+      );
+    }
+  }
+
+  /**
+   * Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
+   * live view (NO `_00_query`, NO subscription, NO TTL heartbeat).
+   *
+   * Cache-aware via a durable per-bucket freshness marker (`_00_preload`):
+   * - COLD (never preloaded in this bucket): fetch the query one-shot from the
+   *   remote, persist the rows (+ embedded `.related()` children), stamp the
+   *   marker — and AWAIT it. This is the "smart waiting" first load: callers can
+   *   `await db.preload(...)` to hold the UI until the data is ready.
+   * - WARM (marker present): return instantly — NEVER blocks. `refresh` decides
+   *   whether to also kick a one-time silent refetch (see {@link PreloadOptions}).
+   *   Default `onUse` does nothing; the data freshens when the real `useQuery`
+   *   mounts and registers its live view.
+   *
+   * Best-effort: any fetch failure (offline, etc.) is a no-op warn (no marker
+   * written, so it's retried next load). Deduped per session by query hash.
+   */
+  async preload(
+    finalQuery: FinalQuery<S, any, any, any, any, any>,
+    options?: PreloadOptions
+  ): Promise<void> {
+    const q = finalQuery.innerQuery;
+    if (this.preloadedHashes.has(q.hash)) return;
+
+    const tableName = q.tableName;
+    const tableSchema = this.config.schema.tables.find((t) => t.name === tableName);
+    if (!tableSchema) {
+      throw new Error(`Table ${tableName} not found`);
+    }
+    const params = parseQueryParams(tableSchema.columns, q.selectQuery.vars ?? {});
+    const hashKey = String(q.hash);
+
+    const marker = await this.dataModule.getPreloadMarker(hashKey);
+
+    // COLD → fetch + persist + stamp, awaited so the caller can block on it.
+    if (!marker) {
+      const rowCount = await this.fetchAndPersist(q, tableName, params);
+      if (rowCount >= 0) {
+        await this.dataModule.writePreloadMarker(hashKey, rowCount);
+        this.preloadedHashes.add(q.hash);
+      }
+      return;
+    }
+
+    // WARM → never block. Mark handled for this session, then optionally refresh.
+    this.preloadedHashes.add(q.hash);
+    const refresh = options?.refresh ?? 'onUse';
+    if (refresh === 'onUse') return;
+
+    if (refresh === 'stale') {
+      const maxAgeMs = parseDuration(options?.staleTime ?? '1h');
+      if (Date.now() - marker.fetchedAt <= maxAgeMs) return; // still fresh
+    }
+
+    // `background`, or `stale` past its staleTime → one-time silent refetch.
+    void this.fetchAndPersist(q, tableName, params).then((rowCount) => {
+      if (rowCount >= 0) return this.dataModule.writePreloadMarker(hashKey, rowCount);
+    });
+  }
+
+  /**
+   * One-shot remote fetch + local persist for a preload query. Returns the row
+   * count on success, or -1 on failure (best-effort: logged, never thrown) so
+   * the caller skips stamping the freshness marker and retries next load.
+   */
+  private async fetchAndPersist(
+    q: InnerQuery<any, any, any>,
+    tableName: string,
+    params: Record<string, any>
+  ): Promise<number> {
+    try {
+      const [rows] = await this.remote.query<[RecordWithId[]]>(q.selectQuery.query, params);
+      const list = rows ?? [];
+      await this.dataModule.persistSnapshot(tableName, list);
+      return list.length;
+    } catch (err) {
+      this.logger.warn(
+        { err, hash: q.hash, Category: 'sp00ky-client::Sp00kyClient::preload' },
+        'Preload fetch failed; data will be fetched on demand'
+      );
+      return -1;
+    }
+  }
+
+  async queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive) {
+    const tableName = sql.split('FROM ')[1].split(' ')[0];
+    return this.dataModule.query(tableName, sql, params, ttl);
+  }
+
+  async subscribe(
+    queryHash: string,
+    callback: (records: Record<string, any>[]) => void,
+    options?: { immediate?: boolean }
+  ): Promise<() => void> {
+    return this.dataModule.subscribe(queryHash, callback, options);
+  }
+
+  /**
+   * Opt-in eager teardown for a query whose last subscriber has gone away
+   * (e.g. a viewport-windowed list cancelling an off-screen window). No-op
+   * while any subscriber remains. Tears down the remote `_00_query` view +
+   * local WASM view instead of waiting for the TTL sweep. Default behavior
+   * (no call here) keeps the view resident for cheap re-subscription.
+   */
+  deregisterQuery(queryHash: string): void {
+    this.dataModule.deregisterQuery(queryHash);
+  }
+
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching). With
+   * `{ immediate: true }` the callback fires synchronously with the current
+   * status. Powers the `useQuery` hook's `isFetching()` accessor.
+   */
+  subscribeQueryStatus(
+    queryHash: string,
+    callback: QueryStatusCallback,
+    options?: { immediate?: boolean }
+  ): () => void {
+    return this.dataModule.subscribeStatus(queryHash, callback, options);
+  }
+
+  /**
+   * Report the frontend processing time (ms) a client framework spent applying
+   * an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can
+   * surface the "frontend" phase of the per-query timing breakdown.
+   */
+  reportFrontendTiming(queryHash: string, ms: number): void {
+    this.dataModule.recordFrontendTiming(queryHash, ms);
+  }
+
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B,
+    path: R,
+    payload: RoutePayload<S, B, R>,
+    options?: RunOptions
+  ) {
+    return this.dataModule.run(backend, path, payload, options);
+  }
+
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle {
+    return new BucketHandle(name, this.remote, this.blobs, {
+      blurhash: this.config.blurhash,
+      logger: this.logger,
+    });
+  }
+
+  /** Cache-free handle. The blob cache reads the remote through this, so a
+   *  cache miss can't loop back into the cache. */
+  private rawBucket(name: string): BucketHandle {
+    return new BucketHandle(name, this.remote, null, {
+      blurhash: this.config.blurhash,
+      logger: this.logger,
+    });
+  }
+
+  /** Blob cache counters for DevTools. */
+  getBlobCacheStats() {
+    return this.blobs.stats();
+  }
+
+  create(id: string, data: Record<string, unknown>) {
+    return this.dataModule.create(id, data);
+  }
+
+  update(table: string, id: string, data: Record<string, unknown>, options?: UpdateOptions) {
+    return this.dataModule.update(table, id, data, options);
+  }
+
+  delete(table: string, id: string) {
+    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());
+  }
+
+  /**
+   * 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.
+   */
+  /**
+   * Prime the in-browser circuit from the local store. Builds the context the
+   * stream processor needs: every synced table (the app schema plus the
+   * server-written meta tables that sync down), a schema hash so a snapshot
+   * projected under another schema is not trusted, and the ids whose local
+   * `_00_rv` was bumped by an unsettled mutation.
+   */
+  private async primeCircuit(): Promise<void> {
+    const tables = [
+      ...this.config.schema.tables.map((t) => t.name),
+      '_00_user_feature',
+      '_00_app_release',
+    ];
+    let pendingIds = new Set<string>();
+    try {
+      const pending = await this.dataModule.getPendingRecordIds();
+      pendingIds = new Set([...pending.writes, ...pending.deletes]);
+    } catch {
+      /* no outbox yet: nothing is pending */
+    }
+    await this.streamProcessor.primeFromLocal({
+      tables,
+      schemaHash: String(hash53(this.config.schemaSurql)),
+      pendingIds,
+      onVersions: (_table, entries) => this.cache.primeVersions(entries),
+    });
+  }
+
+  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)}`;
+  }
+}