@spooky-sync/core 0.0.1-canary.17 → 0.0.1-canary.170

package/dist/index.d.ts

@@ -1,231 +1,240 @@
+import { A as Sp00kyQueryResultPromise, B as LocalStore, C as ReconnectConfig, D as RunOptions, E as RegistrationTimings, F as SyncHealthConfig, G as SyncEventSystem, H as DatabaseEventSystem, I as SyncHealthStatus, K as EventDefinition, L as TimingPhase, M as StorageHealthStatus, N as StoreType, O as Sp00kyConfig, P as SyncHealth, R as UpdateOptions, S as QueryUpdateCallback, T as RecordVersionDiff, U as DatabaseEventTypes, V as SealedQuery, W as Logger$1, _ as QueryState, a as MATERIALIZATION_SAMPLE_WINDOW, b as QueryTimeToLive, c as MutationEventType, d as PinoTransmit, f as PreloadOptions, g as QueryHash, h as QueryConfigRecord, i as Level, j as StorageHealth, k as Sp00kyQueryResult, l as PersistenceClient, m as QueryConfig, n as DebounceOptions, o as MutationCallback, p as PreloadRefresh, q as EventSystem, r as EventSubscriptionOptions, s as MutationEvent, t as ConnectionState, u as PhaseStat, v as QueryStatus, w as RecordVersionArray, x as QueryTimings, y as QueryStatusCallback, z as UpEvent } from "./types.js";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
-import { Level, Level as Level$1, Logger } from "pino";
+import { Duration, RecordId, Surreal as Surreal$1, SurrealEvents, SurrealTransaction } from "surrealdb";
+import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
+import { Logger } from "pino";
+import { LoroDoc } from "loro-crdt";
 
-//#region src/events/index.d.ts
-/**
- * Utility type to define the payload structure of an event.
- * If the payload type P is never, it defines payload as undefined.
- */
-type EventPayloadDefinition<P> = [P] extends [never] ? {
-  payload: undefined;
-} : {
-  payload: P;
-};
-/**
- * Defines the structure of an event with a specific type and payload.
- * @template T The string literal type of the event.
- * @template P The type of the event payload.
- */
-type EventDefinition<T extends string, P> = {
-  type: T;
-} & EventPayloadDefinition<P>;
-/**
- * A map of event types to their definitions.
- * Keys are event names, values are EventDefinitions.
- */
-type EventTypeMap = Record<string, EventDefinition<any, unknown> | EventDefinition<any, never>>;
-/**
- * Options for pushing/emitting events.
- */
-interface PushEventOptions {
-  /** Configuration for debouncing the event. */
-  debounced?: {
-    key: string;
-    delay: number;
-  };
-}
-/**
- * Extracts the full Event object type from the map for a given key.
- */
-type Event<E extends EventTypeMap, T extends EventType<E>> = E[T];
-/**
- * Extracts the payload type from the map for a given key.
- */
-type EventPayload<E extends EventTypeMap, T extends EventType<E>> = E[T]['payload'];
-/**
- * Array of available event type keys.
- */
-type EventTypes<E extends EventTypeMap> = (keyof E)[];
-/**
- * Represents a valid key (event name) from the EventTypeMap.
- */
-type EventType<E extends EventTypeMap> = keyof E;
-/**
- * Function signature for an event handler.
- */
-type EventHandler<E extends EventTypeMap, T extends EventType<E>> = (event: Event<E, T>) => void;
-/**
- * Options when subscribing to an event.
- */
-type EventSubscriptionOptions$1 = {
-  /** If true, the handler will be called immediately with the last emitted event of this type (if any). */
-  immediately?: boolean;
-  /** If true, the subscription will be automatically removed after the first event is handled. */
-  once?: boolean;
-};
-/**
- * A type-safe event system that handles subscription, emission (including debouncing), and buffering of events.
- * @template E The EventTypeMap defining all supported events.
- */
-declare class EventSystem<E extends EventTypeMap> {
-  private _eventTypes;
-  private subscriberId;
-  private isProcessing;
-  private buffer;
-  private subscribers;
-  private subscribersTypeMap;
-  private lastEvents;
-  private debouncedEvents;
-  constructor(_eventTypes: EventTypes<E>);
-  get eventTypes(): EventTypes<E>;
-  /**
-   * Subscribes a handler to a specific event type.
-   * @param type The event type to subscribe to.
-   * @param handler The function to call when the event occurs.
-   * @param options Subscription options (once, immediately).
-   * @returns A subscription ID that can be used to unsubscribe.
-   */
-  subscribe<T extends EventType<E>>(type: T, handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number;
-  /**
-   * Subscribes a handler to multiple event types.
-   * @param types An array of event types to subscribe to.
-   * @param handler The function to call when any of the events occur.
-   * @param options Subscription options.
-   * @returns An array of subscription IDs.
-   */
-  subscribeMany<T extends EventType<E>>(types: T[], handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number[];
-  /**
-   * Unsubscribes a specific subscription by ID.
-   * @param id The subscription ID returned by subscribe().
-   * @returns True if the subscription was found and removed, false otherwise.
-   */
-  unsubscribe(id: number): boolean;
-  /**
-   * Emits an event with the given type and payload.
-   * @param type The type of event to emit.
-   * @param payload The data associated with the event.
-   */
-  emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void;
-  /**
-   * Adds a fully constructed event object to the system.
-   * Similar to emit, but takes the full event object directly.
-   * Supports debouncing if options are provided.
-   * @param event The event object.
-   * @param options Options for the event push (e.g., debouncing).
-   */
-  addEvent<T extends EventType<E>>(event: Event<E, T>, options?: PushEventOptions): void;
-  private handleDebouncedEvent;
-  private scheduleProcessing;
-  private processEvents;
-  private dequeue;
-  private setLastEvent;
-  private broadcastEvent;
-}
-//#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
-//#endregion
-//#region src/services/database/events/index.d.ts
-declare const DatabaseEventTypes: {
-  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
-  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
-};
-interface DatabaseQueryEventPayload {
-  query: string;
-  vars?: Record<string, unknown>;
-  duration: number;
-  success: boolean;
-  error?: string;
-  timestamp: number;
-}
-type DatabaseEventTypeMap = {
-  [DatabaseEventTypes.LocalQuery]: EventDefinition<typeof DatabaseEventTypes.LocalQuery, DatabaseQueryEventPayload>;
-  [DatabaseEventTypes.RemoteQuery]: EventDefinition<typeof DatabaseEventTypes.RemoteQuery, DatabaseQueryEventPayload>;
-};
-type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
-//#endregion
-//#region src/utils/surql.d.ts
-interface SealedQuery<T = void> {
-  readonly sql: string;
-  readonly extract: (results: unknown[]) => T;
-}
-//#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
-  protected client: Surreal;
+  protected client: Surreal$1;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
+  /**
+   * Per-query deadline in ms; `0` disables. Only the remote service sets this
+   * (see `RemoteDatabaseService`) — a local query can be legitimately slow and
+   * has its own retry ladders, and there is no half-open-socket failure mode
+   * for an in-process engine.
+   */
+  protected queryTimeoutMs: number;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
-  constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
+  constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
-  getClient(): Surreal;
+  getClient(): Surreal$1;
   getEvents(): DatabaseEventSystem;
   tx(): Promise<SurrealTransaction>;
   private queryQueue;
   /**
    * Execute a query with serialized execution to prevent WASM transaction issues.
+   *
+   * Serialization means every query waits on the previous one, so a call that
+   * never settles blocks the whole chain forever. {@link queryTimeoutMs} bounds
+   * each link: on expiry this promise rejects and the chain moves on, even
+   * though the underlying RPC is still parked in the SDK's pending map.
    */
   query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
   execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>): Promise<T>;
   close(): Promise<void>;
 }
 //#endregion
-//#region src/services/database/local.d.ts
-declare class LocalDatabaseService extends AbstractDatabaseService {
-  private config;
-  protected eventType: "DATABASE_LOCAL_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
-  connect(): Promise<void>;
-}
-//#endregion
 //#region src/services/database/remote.d.ts
+/** Transport events the SDK publishes, mapped 1:1 to {@link ConnectionState}. */
+type RemoteConnectionEvent = ConnectionState | 'error';
 declare class RemoteDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_REMOTE_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  private readonly reconnectConfig;
+  /**
+   * In-flight `connect()`, so concurrent callers (boot + supervisor revive +
+   * an `online` event landing at the same moment) share one attempt instead of
+   * racing two sockets. Cleared on settle, so a later call always reconnects.
+   */
+  private connecting;
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
+  /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
+  getReconnectConfig(): Required<ReconnectConfig>;
+  /** Current transport state as reported by the SDK. */
+  getStatus(): ConnectionState;
+  /**
+   * Observe transport events. Thin passthrough so callers (the supervisor,
+   * sync, CRDT) don't have to reach through `getClient()`.
+   */
+  subscribeConnection<K extends RemoteConnectionEvent>(event: K, cb: (...payload: SurrealEvents[K]) => void): () => void;
+  /**
+   * Tear the socket down on purpose. Used by the heartbeat watchdog when a
+   * socket stops answering but never closes: `close()` makes the SDK publish
+   * `disconnected`, which is what drives the supervisor's revive loop.
+   */
+  forceClose(): Promise<void>;
+  /**
+   * Open (or re-open) the remote connection.
+   *
+   * Safe to call repeatedly: concurrent calls share the in-flight attempt, and
+   * a call after a `disconnected` builds a fresh socket. `use()` and
+   * `authenticate()` are re-applied here for the cold path; the SDK also
+   * replays them itself on its own internal reconnects.
+   */
   connect(): Promise<void>;
+  private doConnect;
   signin(params: any): Promise<any>;
   signup(params: any): Promise<any>;
   authenticate(token: string): Promise<any>;
   invalidate(): Promise<void>;
 }
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
+//#region src/services/database/connection-supervisor.d.ts
+/**
+ * Keeps the remote WebSocket alive for the whole life of the page.
+ *
+ * The SurrealDB SDK reconnects on its own after a socket `close`, but that
+ * covers only one of three ways the connection dies:
+ *
+ * 1. **Socket closes, SDK recovers.** Handled entirely by the SDK. This
+ *    supervisor only observes it (to report `reconnecting` upward).
+ * 2. **Socket closes, SDK gives up.** With `attempts: -1` this shouldn't happen
+ *    from exhaustion — but the SDK also terminates the engine permanently when
+ *    its post-reconnect handshake throws (it re-runs `version()`, `use()`,
+ *    `authenticate()` on every reconnect and closes the engine on any error).
+ *    One transient hiccup there would otherwise kill the page's connection for
+ *    good. The revive loop re-opens from scratch.
+ * 3. **Socket never closes at all.** A half-open connection: the peer is gone
+ *    (NAT timeout, wifi switch, laptop sleep) but no FIN ever arrives, so
+ *    `readyState` stays OPEN and the SDK's own 30s ping — fire-and-forget, no
+ *    response deadline — never notices. Nothing ever fires a `close` event, so
+ *    nothing ever triggers a reconnect. The heartbeat detects this and forces
+ *    the teardown that case 2's loop then repairs.
+ *
+ * Plus wake triggers: coming back `online` or un-hiding the tab probes
+ * immediately rather than waiting out a backoff that was scheduled while the
+ * network was known-down.
+ */
+declare class ConnectionSupervisor {
+  private readonly remote;
+  private readonly logger;
+  private readonly config;
+  private state;
+  private subscribers;
+  private started;
+  private disposed;
+  private heartbeatTimer;
+  private heartbeatInFlight;
+  /** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+  private heartbeatFailures;
+  private reviveTimer;
+  private reviveAttempts;
+  /** Timestamp of the last wake-triggered probe, for rate limiting. */
+  private lastWakeProbeAt;
+  private reviving;
+  /**
+   * Set while the browser reports itself offline. Retrying a socket against a
+   * down interface only burns backoff, so the loop parks until `online` fires.
+   */
+  private suspended;
+  private teardown;
+  private static readonly REVIVE_BASE_MS;
+  /**
+   * How many consecutive heartbeat failures it takes to tear the socket down.
+   *
+   * The probe rides the same serialized queue as every other RPC (deliberately
+   * — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+   * a merely BUSY one. A single slow window (a large sync burst, one heavy
+   * app query) used to be enough to force-close a perfectly healthy socket,
+   * and the resulting reconnect re-registered every active query about a
+   * second later. That self-inflicted teardown manufactured the very reconnect
+   * storms this class exists to survive. A genuinely dead socket still fails
+   * every probe, so it is torn down one interval later than before.
+   */
+  private static readonly FAILURES_BEFORE_TEARDOWN;
+  /** Retry delay after an inconclusive (first) heartbeat failure. */
+  private static readonly HEARTBEAT_RETRY_MS;
+  /** Floor between probes triggered by wake events (tab focus, pageshow). */
+  private static readonly WAKE_PROBE_MIN_INTERVAL_MS;
+  constructor(remote: RemoteDatabaseService, logger: Logger$1, config?: Required<ReconnectConfig>);
+  /** Latest observed transport state. */
+  get connection(): ConnectionState;
+  /**
+   * Observe transport state. Fires immediately with the current value and again
+   * on every change. Returns an unsubscribe.
+   */
+  subscribe(cb: (state: ConnectionState) => void): () => void;
+  /**
+   * Begin supervising. Call once, after the initial {@link
+   * RemoteDatabaseService.connect}. Idempotent.
+   */
+  start(): void;
+  /** Stop all timers and listeners. Safe to call more than once. */
+  dispose(): void;
+  private setState;
+  private clearReviveTimer;
+  /**
+   * Queue the next `connect()` attempt on exponential backoff, capped at
+   * `superviseRetryDelayMaxMs`. Never gives up — the page is expected to
+   * outlive any outage.
+   */
+  private scheduleRevive;
+  private revive;
+  private stopHeartbeat;
+  private startHeartbeat;
+  /**
+   * Probe the server end-to-end. Deliberately goes through
+   * `remote.query` — the same serialized queue every other remote call uses —
+   * so a queue wedged behind a stuck RPC also fails the heartbeat instead of
+   * being invisible to it.
+   */
+  private beat;
+  /**
+   * A restored network or an un-hidden tab is the strongest available hint that
+   * a reconnect will now succeed, so probe immediately instead of waiting out a
+   * backoff scheduled under worse conditions.
+   */
+  private installWakeTriggers;
+  /**
+   * Reset the backoff and act on whichever problem is present: reconnect if the
+   * socket is gone, otherwise probe it (it may be half-open — which is exactly
+   * what a sleep/wake cycle produces).
+   */
+  private wake;
+}
+//#endregion
+//#region src/modules/sync/queue/queue-down.d.ts
+type RegisterEvent = {
+  type: 'register';
+  payload: {
+    hash: string;
+  };
 };
-type UpdateEvent = {
-  type: 'update';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  beforeRecord?: Record<string, unknown>;
-  options?: PushEventOptions;
+type SyncEvent = {
+  type: 'sync';
+  payload: {
+    hash: string;
+  };
 };
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
+type HeartbeatEvent = {
+  type: 'heartbeat';
+  payload: {
+    hash: string;
+  };
 };
-type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
+type CleanupEvent = {
+  type: 'cleanup';
+  payload: {
+    hash: string;
+  };
+};
+type DownEvent = RegisterEvent | SyncEvent | HeartbeatEvent | CleanupEvent;
 //#endregion
 //#region src/services/stream-processor/wasm-types.d.ts
 interface WasmStreamUpdate {
   query_id: string;
   result_hash: string;
   result_data: RecordVersionArray;
+  timing_store_apply_ms?: number;
+  timing_circuit_step_ms?: number;
+  timing_transform_ms?: number;
+  timing_parse_ms?: number;
+  timing_plan_ms?: number;
+  timing_snapshot_ms?: number;
 }
 //#endregion
 //#region src/services/stream-processor/index.d.ts
@@ -246,6 +255,25 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * End-to-end ingest latency for the WASM call that produced this update,
+   * in milliseconds. Populated by StreamProcessorService.ingest. Undefined
+   * for the initial register_view snapshot.
+   */
+  materializationTimeMs?: number;
+  /** SSP internal sub-phase timings (ms) for this ingest, from the WASM binding. */
+  storeApplyMs?: number;
+  circuitStepMs?: number;
+  transformMs?: number;
+  /**
+   * One-shot registration timings (ms). Only set on the StreamUpdate returned
+   * by `registerQueryPlan` (the register_view snapshot), not on ingest updates.
+   */
+  registration?: {
+    parseMs: number;
+    planMs: number;
+    snapshotMs: number;
+  };
 }
 type StreamProcessorEvents = {
   stream_update: EventDefinition<'stream_update', StreamUpdate[]>;
@@ -265,19 +293,123 @@ declare class StreamProcessorService {
   private processor;
   private isInitialized;
   private receivers;
-  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
+  private batching;
+  private batchBuffer;
+  private sessionAuth;
+  private stateKeySuffix;
+  private stateGeneration;
+  private persistState;
+  private persistCircuit;
+  private checkpointMs;
+  private checkpointTimer;
+  private snapshotDirty;
+  private pagehideHandler;
+  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
    * Multiple receivers can be registered (DataManager, DevTools, etc.)
    */
   addReceiver(receiver: StreamUpdateReceiver): void;
   private notifyUpdates;
+  private dispatchUpdates;
+  /**
+   * Ingest a batch of record changes as a single bulk operation, firing only
+   * one coalesced `StreamUpdate` per affected query once every record has been
+   * ingested (instead of one update per record). Use this whenever multiple
+   * records land at once — e.g. sync fetching N missing rows — so a list query
+   * re-runs and the UI re-renders once for the whole batch rather than
+   * row-by-row.
+   *
+   * Internally opens a coalescing window, ingests each record, then flushes;
+   * processor state is persisted once for the whole batch. No-op for an empty
+   * batch.
+   */
+  ingestMany(records: Array<{
+    table: string;
+    op: 'CREATE' | 'UPDATE' | 'DELETE';
+    id: string;
+    record: any;
+  }>): void;
+  /**
+   * Open a coalescing window. While open, the per-record stream updates
+   * emitted by `ingest` are buffered (one entry per queryHash) instead of
+   * dispatched. Always paired with `flushCoalescing()` in a try/finally by
+   * `ingestMany` so the window always closes — otherwise the processor stays
+   * stuck buffering forever.
+   *
+   * No-op if a window is already open (nested batches aren't expected here).
+   */
+  private beginCoalescing;
+  /**
+   * Close the coalescing window and flush: dispatch one coalesced
+   * `StreamUpdate` per buffered queryHash, then persist processor state once
+   * for the whole batch (instead of once per ingest).
+   */
+  private flushCoalescing;
   /**
    * Initialize the WASM module and processor.
    * This must be called before using other methods.
    */
   init(): Promise<void>;
+  /** Route the persisted circuit snapshot to a per-bucket key. */
+  setStateKeySuffix(bucketId: string): void;
+  private stateKey;
+  /**
+   * Drop the current WASM processor and start a fresh, empty circuit. Used on
+   * local-bucket switches: the old circuit holds the previous user's rows AND
+   * views registered with the previous `$auth` context, so neither may survive.
+   * Deliberately does NOT `loadState()` — a persisted snapshot references views
+   * under a dead sessionId salt; the DataModule rebind re-registers every live
+   * view against this fresh processor. Caller must re-seed `setPermissions`
+   * afterwards (a fresh circuit default-denies every table).
+   */
+  reset(): Promise<void>;
+  /**
+   * Release the wasm circuit and stop checkpointing. Call when the client is
+   * torn down; a recreated client (provider remount, HMR) would otherwise stack
+   * one full circuit per instance.
+   */
+  dispose(): void;
+  /**
+   * Explicitly run the wasm-bindgen destructor. Guarded: stale wasm builds may
+   * not expose `free`, and a double free must not take the app down.
+   */
+  private freeProcessor;
+  /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
+  setPersistenceEnabled(enabled: boolean): void;
+  /**
+   * Opt into snapshot persistence (`persistCircuit`). Off by default: see the
+   * `persistCircuit` field comment for why per-ingest snapshots were removed.
+   * Must be called before `init()` for a snapshot to be restored at boot.
+   */
+  configureCircuitPersistence(enabled: boolean, checkpointMs?: number): void;
+  /**
+   * Record that the circuit changed. Cheap and O(1), the expensive snapshot is
+   * deferred to the checkpoint timer, and skipped entirely when
+   * `persistCircuit` is off (the default).
+   */
+  private markSnapshotDirty;
+  private startCheckpoints;
+  /** Stop checkpointing and drop the `pagehide` listener. */
+  stopCheckpoints(): void;
   loadState(): Promise<void>;
+  /**
+   * Seed per-table `select` permission predicates ({ [table]: whereText }).
+   * Must run after the processor exists and before any `register_view`, else
+   * non-`_00_` tables are default-denied and registration fails.
+   */
+  setPermissions(permissions: Record<string, string>): void;
+  /**
+   * Set the current session's auth identity for permission injection,
+   * mirroring the server's `fn::query::register`
+   * (`object::extend(params, { auth: { id: $auth.id }, access: $access })`).
+   * Stored as strings (empty when logged out) and applied to every
+   * `register_view` in {@link registerQueryPlan}. Must be set before a
+   * `$auth`-gated query registers (and re-set on auth state changes), or the
+   * in-browser SSP's `permission_inject` rejects it with
+   * "requires $auth but registration params lack it".
+   */
+  setSessionAuth(authId: string | null, access: string | null): void;
   saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
@@ -297,203 +429,960 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
-//#region src/types.d.ts
-/**
- * The type of storage backend to use for the local database.
- * - 'memory': In-memory storage (transient).
- * - 'indexeddb': IndexedDB storage (persistent).
- */
-type StoreType = 'memory' | 'indexeddb';
+//#region src/modules/cache/types.d.ts
+type RecordWithId = Record<string, any> & {
+  id: RecordId<string>;
+};
+interface QueryConfig$1 {
+  queryHash: string;
+  surql: string;
+  params: Record<string, any>;
+  ttl: QueryTimeToLive | Duration;
+  lastActiveAt: Date;
+}
+interface CacheRecord {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  record: RecordWithId;
+  version: number;
+}
+//#endregion
+//#region src/modules/cache/index.d.ts
 /**
- * Interface for a custom persistence client.
- * Allows providing a custom storage mechanism for the local database.
+ * CacheModule - Centralized storage and DBSP ingestion
+ *
+ * Single responsibility: Handle all local storage operations and DBSP ingestion.
+ * This module acts as the bridge between data operations and persistence.
  */
-interface PersistenceClient {
+/** One ingested change, in exactly the shape `ingestMany` consumes. Shared
+ *  with the tabs protocol so a leader can relay its ingests to followers. */
+interface CacheIngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  id: string;
+  record: Record<string, unknown>;
+}
+declare class CacheModule implements StreamUpdateReceiver {
+  private local;
+  private streamProcessor;
+  private logger;
+  private streamUpdateCallback;
+  private versionLookups;
+  /** Shared-tabs leader: fan every committed ingest out to follower circuits.
+   *  Fired AFTER the local tx (the rows are already in the shared store, so a
+   *  follower only needs the circuit feed). Never set on followers. */
+  private ingestRelay;
+  constructor(local: LocalStore, streamProcessor: StreamProcessorService, streamUpdateCallback: (update: StreamUpdate) => void, logger: Logger$1);
   /**
-   * Sets a value in the storage.
-   * @param key The key to set.
-   * @param value The value to store.
+   * Implements StreamUpdateReceiver interface
+   * Called directly by StreamProcessor when views change
    */
-  set<T>(key: string, value: T): Promise<void>;
+  onStreamUpdate(update: StreamUpdate): void;
+  setIngestRelay(cb: ((tuples: CacheIngestTuple[]) => void) | null): void;
   /**
-   * Gets a value from the storage.
-   * @param key The key to retrieve.
-   * @returns The stored value or null if not found.
+   * Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
+   * The rows are already in the shared store (the leader wrote them), so no
+   * local write happens here; the normal chain then runs: SSP -> stream update
+   * -> DataModule debounce -> materializeRecords (re-reads via the port
+   * transport) -> this tab's subscriptions fire with this tab's hashes.
    */
-  get<T>(key: string): Promise<T | null>;
+  applyRelayedIngest(tuples: CacheIngestTuple[]): void;
+  lookup(recordId: string): number;
+  /** Drop the version cache on a bucket switch — a stale version would make
+   *  the sync diff skip fetching a body the new bucket legitimately needs. */
+  clearVersionLookups(): void;
   /**
-   * Removes a value from the storage.
-   * @param key The key to remove.
+   * Save a single record to local DB and ingest into DBSP
+   * Used by mutations (create/update)
    */
-  remove(key: string): Promise<void>;
-}
-/**
- * Supported Time-To-Live (TTL) values for cached queries.
- * Format: number + unit (m=minutes, h=hours, d=days).
- */
-type QueryTimeToLive = '1m' | '5m' | '10m' | '15m' | '20m' | '25m' | '30m' | '1h' | '2h' | '3h' | '4h' | '5h' | '6h' | '7h' | '8h' | '9h' | '10h' | '11h' | '12h' | '1d';
-/**
- * Result object returned when a query is registered or executed.
- */
-interface SpookyQueryResult {
-  /** The unique hash identifier for the query. */
-  hash: string;
-}
-type SpookyQueryResultPromise = Promise<SpookyQueryResult>;
-interface EventSubscriptionOptions {
-  priority?: number;
-}
-/**
- * Configuration options for the Spooky client.
- * @template S The schema structure type.
- */
-interface SpookyConfig<S extends SchemaStructure> {
-  /** Database connection configuration. */
-  database: {
-    /** The SurrealDB endpoint URL. */
-    endpoint?: string;
-    /** The namespace to use. */
-    namespace: string;
-    /** The database name. */
-    database: string;
-    /** The local store type implementation. */
-    store?: StoreType;
-    /** Authentication token. */
-    token?: string;
-  };
-  /** Unique client identifier. If not provided, one will be generated. */
-  clientId?: string;
-  /** The schema definition. */
-  schema: S;
-  /** The compiled SURQL schema string. */
-  schemaSurql: string;
-  /** Logging level. */
-  logLevel: Level$1;
+  save(cacheRecord: CacheRecord, skipDbInsert?: boolean): Promise<void>;
+  /**
+   * Save multiple records in a batch
+   * More efficient than calling save() multiple times
+   * Used by sync operations
+   */
+  saveBatch(records: CacheRecord[], skipDbInsert?: boolean): Promise<void>;
   /**
-   * Persistence client to use.
-   * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
+   * Delete a record from local DB and ingest deletion into DBSP
    */
-  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint for telemetry data. */
-  otelEndpoint?: string;
+  delete(table: string, id: string, skipDbDelete?: boolean, recordData?: Record<string, any>): Promise<void>;
+  /**
+   * Register a query with DBSP to create a materialized view
+   * Returns the initial result array
+   */
+  registerQuery(config: QueryConfig$1): {
+    localArray: RecordVersionArray;
+    registrationTimings?: {
+      parseMs: number;
+      planMs: number;
+      snapshotMs: number;
+    };
+  };
   /**
-   * Debounce time in milliseconds for stream updates.
-   * Defaults to 100ms.
+   * Unregister a query from DBSP
    */
-  streamDebounceTime?: number;
+  unregisterQuery(queryHash: string): void;
 }
-type QueryHash = string;
-type RecordVersionArray = Array<[string, number]>;
+//#endregion
+//#region src/modules/data/index.d.ts
 /**
- * Represents the difference between two record version sets.
- * Used for synchronizing local and remote states.
+ * DataModule - Unified query and mutation management
+ *
+ * Merges the functionality of QueryManager and MutationManager.
+ * Uses CacheModule for all storage operations.
  */
-interface RecordVersionDiff {
-  /** List of records added. */
-  added: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of records updated. */
-  updated: Array<{
-    id: RecordId$1<string>;
-    version: number;
+declare class DataModule<S extends SchemaStructure> {
+  private cache;
+  private local;
+  private schema;
+  private streamDebounceTime;
+  /** Tab identity baked into mutation ids (shared-tabs rollback routing);
+   *  undefined in solo mode, where mutation-id falls back to a session id. */
+  private tabId;
+  private activeQueries;
+  private pendingQueries;
+  private subscriptions;
+  private statusSubscriptions;
+  private mutationCallbacks;
+  private debounceTimers;
+  private pendingStreamUpdates;
+  private fetchDepth;
+  private logger;
+  /**
+   * Optional observer notified whenever a query's fetch status changes.
+   * Wired by Sp00kyClient to push status changes into DevTools. Kept as a
+   * settable field (rather than a constructor arg) because DevTools is
+   * constructed after DataModule.
+   */
+  onQueryStatusChange?: (hash: QueryHash, status: QueryStatus) => void;
+  /**
+   * Optional observer invoked when a still-subscribed query's TTL heartbeat
+   * fires (~90% of the TTL). Wired by Sp00kyClient to
+   * `Sp00kySync.heartbeatQuery`, which refreshes the remote `_00_query`
+   * row's `lastActiveAt` so an actively-watched query never expires. Settable
+   * field (not a constructor arg) because the sync engine is wired after
+   * DataModule is constructed — mirrors `onQueryStatusChange`.
+   */
+  onHeartbeat?: (hash: QueryHash) => void;
+  /**
+   * Optional hook fired by {@link deregisterQuery} when an opt-in query (e.g. a
+   * viewport-windowed list cancelling an off-screen window) loses its last
+   * subscriber. Wired by Sp00kyClient to enqueue a `cleanup` down-event, which
+   * tears the remote `_00_query` view down (releasing its `_00_list_ref` edges)
+   * instead of leaving it for the TTL sweep. The local view + state are freed in
+   * {@link finalizeDeregister} only after that remote delete, so a fast
+   * re-subscribe (scroll back) can abort/heal the teardown — see `cleanupQuery`.
+   */
+  onDeregister?: (hash: QueryHash) => void;
+  private sessionId;
+  private currentUserId;
+  constructor(cache: CacheModule, local: LocalStore, schema: S, logger: Logger$1, streamDebounceTime?: number);
+  init(sessionId: string): Promise<void>;
+  /**
+   * Update the session salt used in query-id hashing. Call this when the
+   * SurrealDB session changes (sign-in, sign-out, reconnect). Subsequently
+   * registered queries will get fresh, session-scoped IDs.
+   */
+  setSessionId(sessionId: string): void;
+  /** Shared-tabs: bake this tab's identity into mutation ids so a rollback of
+   *  a follower's mutation routes back to the tab that made it. */
+  setTabId(tabId: string): void;
+  /**
+   * Update the authenticated user record id. Pass `null` on sign-out.
+   * Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
+   * the poll route to the same per-user `_00_list_ref_user_<id>` the
+   * SSP writes to.
+   */
+  setCurrentUserId(userId: string | null): void;
+  /** Read-only view of the authenticated user id used for per-user
+   * `_00_list_ref` routing. Other modules consult this so they pick the
+   * same table name DataModule does. */
+  getCurrentUserId(): string | null;
+  /**
+   * Register a query and return its hash for subscriptions
+   */
+  query<T extends TableNames<S>>(tableName: T, surqlString: string, params: Record<string, any>, ttl: QueryTimeToLive, plan?: QueryPlan): Promise<QueryHash>;
+  /**
+   * Subscribe to query updates
+   */
+  subscribe(queryHash: string, callback: QueryUpdateCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching).
+   * With `{ immediate: true }` the callback fires synchronously with the
+   * current status (defaults to `idle` if the query isn't registered yet).
+   */
+  subscribeStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Set a query's fetch status and notify status observers (DevTools +
+   * `subscribeStatus` listeners). No-op when the status is unchanged or the
+   * query is unknown.
+   */
+  setQueryStatus(queryHash: string, status: QueryStatus): void;
+  /**
+   * Enter a fetch cycle for a query. Refcounted: registration and concurrent
+   * poll/LIVE sync rounds can overlap on the same hash, and only the OUTERMOST
+   * cycle may flip the status — 0→1 emits `fetching`, and `endFetching`'s 1→0
+   * emits `idle`. Always pair with `endFetching` in a `finally`.
+   */
+  beginFetching(queryHash: string): void;
+  /** Leave a fetch cycle started with {@link beginFetching}; emits `idle` on the last exit. */
+  endFetching(queryHash: string): void;
+  /**
+   * Subscribe to mutations (for sync)
+   */
+  onMutation(callback: MutationCallback): () => void;
+  /**
+   * Handle stream updates from DBSP (via CacheModule)
+   */
+  onStreamUpdate(update: StreamUpdate): Promise<void>;
+  /**
+   * Process a query's pending (debounced) stream update NOW instead of on the
+   * trailing edge. Called by the sync engine before it flips a query back to
+   * `idle`, so the status change never races ahead of the rows it fetched.
+   * No-op when nothing is pending. The pending entry is removed before the
+   * await so a concurrently-firing timer can't process it twice.
+   */
+  flushPendingStreamUpdate(queryHash: string): Promise<void>;
+  /**
+   * Materialize a query's result rows from the local store.
+   *
+   * A query's rows are its MEMBERSHIP — the id-set the server put in
+   * `_00_list_ref` (`remoteArray`) — not "every local body that matches the
+   * WHERE". Those two disagree, and the disagreement was the bug: when a row
+   * leaves a query's window but still exists upstream, `handleRemovedRecords`
+   * keeps its local body and never re-fetches it, so a predicate re-scan finds
+   * that stale body still matching and keeps rendering the row. Selecting the
+   * id-set directly is also the only correct thing for a windowed query, where
+   * re-applying `START m` against the shared local store skips the window's own
+   * rows entirely (sparse windowing) and returns nothing.
+   *
+   * The rendered set is:
+   *
+   *     (membership ∪ (pendingWrites ∩ localArray)) − pendingDeletes
+   *
+   * The middle term keeps optimistic writes visible without re-admitting stale
+   * rows. Every local write is fed to the SSP (`cache.saveBatch` →
+   * `ingestMany`), so `localArray` answers "does this row match the predicate
+   * per LOCAL truth". A pending write that moves a row into the window is in
+   * `localArray` and shows; one that moves a row out is absent and does not; a
+   * stale body the server dropped has no pending write at all, so it stays out.
+   * `pendingDeletes` covers the reverse lag — the server still lists a row whose
+   * DELETE is sitting in our outbox.
+   *
+   * Falls back to the predicate scan only when membership has never been
+   * established (a query first run on this device), so an offline first paint
+   * still shows something.
+   */
+  private materializeRecords;
+  /**
+   * The materialization itself, without the DevTools timing wrapper. Split out so
+   * cold-start seeding can use it before a `QueryState` exists.
+   */
+  private materializeFromConfig;
+  /**
+   * The authoritative membership list to render from, or `null` when membership
+   * has never been established and the caller must fall back to a scan.
+   *
+   * A windowed query has no usable fallback — re-running its `START m` locally
+   * returns the wrong rows — so it renders from whatever id-set is on hand
+   * (SSP's included) rather than degrading to a scan. That is the pre-existing
+   * behavior for windows and is preserved.
+   */
+  private resolveMembership;
+  /** Apply the pending-write union and pending-delete subtraction, and map to
+   *  RecordIds for the engines' id-set path. */
+  private buildRenderIds;
+  private processStreamUpdate;
+  /**
+   * Compute p55/p90/p99 from a rolling window of materialization samples.
+   * Returns nulls for any percentile that has no samples yet so SurrealDB
+   * `option<float>` columns stay NONE rather than 0 before the first ingest.
+   */
+  private computeMaterializationPercentiles;
+  /** Record a per-phase timing sample (ms) on a query's rolling window. */
+  private recordPhase;
+  /** Record the remote record-fetch time (ms) for a query. Called by the sync engine. */
+  recordRemoteFetch(hash: string, ms: number): void;
+  /**
+   * Record the frontend reconcile time (ms) for a query. Called from `useQuery`
+   * via `Sp00kyClient.reportFrontendTiming` after it applies an update to its store.
+   */
+  recordFrontendTiming(hash: string, ms: number): void;
+  /**
+   * Build the per-query processing-time breakdown surfaced to the DevTools panel
+   * and the MCP. `ssp` is the WASM-ingest wall time (from `materializationSamples`);
+   * the rest come from the per-phase rolling windows + one-shot registration timings.
+   */
+  phaseTimings(q: QueryState): QueryTimings;
+  /**
+   * Get query state (for sync and devtools)
+   */
+  getQueryByHash(hash: string): QueryState | undefined;
+  /**
+   * Cold-query guard for instant-hydrate: true when the query exists, hasn't been
+   * hydrated, and has NOT yet fetched its server result (`remoteArray` empty).
+   * We gate on `remoteArray`, not local `records`: a windowed query is often
+   * partially pre-seeded from the circuit (e.g. the dashboard's 5-row preview),
+   * but it still hasn't loaded its own full window from the server — so it should
+   * still hydrate. A warm re-subscribe (remoteArray already populated) is skipped.
+   */
+  isCold(hash: string): boolean;
+  /**
+   * Walk a hydrated record's fields and append any EMBEDDED child records to
+   * `batch` (recursing for nested related fields). An embedded child is a
+   * value that is itself a record — a non-null object whose `id` is a
+   * `RecordId` — or an array of such records (one-to-many vs one-to-one). A
+   * bare `RecordId` (a foreign-key reference) or any other value is skipped,
+   * so this never mistakes a FK column for an embedded body. Children are
+   * keyed by their own `record.id.table`, versioned by `_00_rv`, and cleaned
+   * to their table's real columns (which strips the alias/related fields).
+   * `seen` dedupes within the batch.
+   */
+  private collectEmbeddedChildren;
+  /**
+   * Prepare a subquery-bearing row (preload / hydration) for the schemafull
+   * local store: replace an embedded FORWARD-relation object (`author = { id, … }`)
+   * with its RecordId so a `record<…>` field coerces, and DROP reverse-subquery
+   * ARRAYS (`comments = [ … ]`) since their rows are cached separately as their
+   * own bodies. A flat record — as the live `SELECT * FROM $ids` sync returns,
+   * with relations already RecordIds — passes through unchanged.
+   */
+  private flattenRelationsForStorage;
+  /**
+   * Instant-hydrate: ingest rows fetched one-shot from the remote (the query's own
+   * surql run directly) so the query DISPLAYS immediately, while the full realtime
+   * registration proceeds in the background. Ingests with versions (`_00_rv`) so the
+   * later `syncRecords` dedup skips re-pulling unchanged bodies, and seeds
+   * `remoteArray` so windowed queries materialize the correct window (no sparse
+   * local-circuit issue). Runs at most once per query (the `hydrated` flag).
+   */
+  applyHydration(hash: string, rows: RecordWithId[]): Promise<void>;
+  /**
+   * Build the cache batch for a set of one-shot rows and persist it to the
+   * local DB + in-browser SSP. Maps each row to a `CREATE` op on its own table
+   * and extracts EMBEDDED related children (any nesting depth) as their own
+   * records — a `.related()` query returns its children embedded, and a later
+   * correlated re-materialization needs them present as standalone rows.
+   * Shared by `applyHydration` (live registration) and `persistSnapshot`
+   * (preload).
+   */
+  private buildAndSaveCacheBatch;
+  /**
+   * Preload/prewarm: persist one-shot rows (and their embedded related children)
+   * into the local cache WITHOUT registering a query — no `activeQueries` entry,
+   * no `_00_query` view, no TTL heartbeat. The rows live in the local DB as
+   * ordinary bodies (never GC'd on their own) so a later `useQuery` seeds its
+   * first paint from them instantly, then registers a live view to freshen.
+   */
+  persistSnapshot(tableName: string, rows: RecordWithId[]): Promise<void>;
+  /**
+   * Read the durable preload freshness marker for a query hash, or null if this
+   * query was never preloaded in the current bucket. Co-located with the cached
+   * rows (per-bucket `_00_preload` table) so a bucket switch that clears the
+   * data also clears the marker — a stale marker can't claim "warm" when the
+   * rows are gone. Any read error is treated as cold.
+   */
+  getPreloadMarker(hash: string): Promise<{
+    fetchedAt: number;
+    rowCount: number;
+  } | null>;
+  /** Stamp the preload freshness marker after a successful snapshot fetch. */
+  writePreloadMarker(hash: string, rowCount: number): Promise<void>;
+  /**
+   * Read the durable membership row, or `null` if this query has never had
+   * authoritative membership on this device. Any read error is treated as
+   * "unknown" so a broken row degrades to the predicate scan rather than
+   * rendering an empty list.
+   */
+  getWindowMembership(key: string): Promise<RecordVersionArray | null>;
+  /** Persist the durable membership row. Best-effort: callers must not fail a
+   *  sync round because the mirror write failed. */
+  writeWindowMembership(key: string, ids: RecordVersionArray): Promise<void>;
+  /**
+   * Record ids with a mutation still in the outbox, split by direction.
+   *
+   * Both halves feed {@link materializeRecords}: `writes` keeps optimistic
+   * creates/updates visible before the server has acknowledged them, and
+   * `deletes` suppresses rows the server still lists because our DELETE hasn't
+   * been processed yet. Reading `_00_pending_mutations` (rather than tracking
+   * ids in memory) is what makes both survive a reload.
+   *
+   * On failure returns empty sets: membership alone then decides, which can
+   * briefly hide an optimistic write but never resurrects a deleted row.
+   */
+  getPendingRecordIds(): Promise<{
+    writes: Set<string>;
+    deletes: Set<string>;
   }>;
-  /** List of record IDs removed. */
-  removed: RecordId$1<string>[];
+  /** True while ≥1 live subscriber is watching this query (refcount guard). */
+  hasSubscribers(hash: string): boolean;
+  /**
+   * Opt-in eager teardown for a query whose LAST subscriber just left — used by
+   * viewport-windowed lists to cancel off-screen windows instead of leaving
+   * their remote views to expire on the TTL sweep. No-op while any subscriber
+   * remains (refcount). Only enqueues the remote cleanup here; the local WASM
+   * view + in-memory state are freed in {@link finalizeDeregister} after the
+   * remote delete completes, so a re-subscribe in between aborts/heals it.
+   *
+   * NOTE: most queries should NOT use this — the default keep-alive on
+   * unsubscribe avoids re-registration churn on navigation.
+   */
+  deregisterQuery(hash: string): void;
+  /**
+   * Final local teardown after the remote `_00_query` row was deleted: free the
+   * WASM view, heartbeat timer, debounce timer, and in-memory state. Caller
+   * (`cleanupQuery`) guarantees no subscriber remains.
+   */
+  finalizeDeregister(hash: string): void;
+  /**
+   * Get query state by id (for sync and devtools)
+   */
+  getQueryById(id: RecordId<string>): QueryState | undefined;
+  /**
+   * Get all active queries (for devtools)
+   */
+  getActiveQueries(): QueryState[];
+  getActiveQueryHashes(): QueryHash[];
+  updateQueryLocalArray(id: string, localArray: RecordVersionArray): Promise<void>;
+  updateQueryRemoteArray(hash: string, remoteArray: RecordVersionArray): Promise<void>;
+  /**
+   * Cancel every armed timer ahead of a local-bucket switch: stream-update
+   * debounce timers (their pending updates carry the OLD bucket's id-sets) and
+   * per-query TTL heartbeats (they'd refresh the previous user's remote
+   * `_00_query` rows under the new session). The rebind re-arms heartbeats.
+   */
+  quiesce(): void;
+  /**
+   * Re-home every active query in a freshly-opened bucket, KEEPING its hash —
+   * `useQuery` subscriptions are keyed by hash and don't re-register on auth
+   * changes, so the hooks must stay attached. Per query:
+   *   1. reset the sync arrays + hydration flag and drop the previous user's
+   *      records, notifying subscribers with the new-bucket materialization
+   *      (usually empty) so their rows leave the UI immediately;
+   *   2. recreate the `_00_query` row in the new bucket;
+   *   3. re-register the SSP view on the (fresh, post-reset) processor — this
+   *      also rebinds the view to the NEW `$auth` context;
+   *   4. restart the TTL heartbeat.
+   * Returns the hashes so the caller can enqueue remote re-registration, which
+   * refills records from the server via the normal register→sync→notify path.
+   */
+  rebindAfterBucketSwitch(): Promise<QueryHash[]>;
+  /**
+   * Called after a query's initial sync completes.
+   * Ensures subscribers are notified even if no stream updates fired (e.g. empty result set).
+   */
+  notifyQuerySynced(queryHash: string): Promise<void>;
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, data: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  /**
+   * Build the outbox job record + resolve its table for a backend route.
+   *
+   * Every job is a single execution. Recurring work is declared server-side
+   * (`schedules:` in sp00ky.yml) and the scheduler creates a fresh row per cycle,
+   * so nothing here needs to know about schedules.
+   */
+  private buildJobRecord;
+  /**
+   * Create a new record
+   */
+  create<T extends Record<string, unknown>>(id: string, data: T): Promise<T>;
+  /**
+   * Update an existing record
+   */
+  update<T extends Record<string, unknown>>(table: string, id: string, data: Partial<T>, options?: UpdateOptions): Promise<T>;
+  /**
+   * Delete a record
+   */
+  delete(table: string, id: string): Promise<void>;
+  /**
+   * Rollback a failed optimistic create by deleting the record locally
+   */
+  rollbackCreate(recordId: RecordId, tableName: string): Promise<void>;
+  /**
+   * Rollback a failed optimistic update by restoring the previous record state
+   */
+  rollbackUpdate(recordId: RecordId, tableName: string, beforeRecord: Record<string, unknown>): Promise<void>;
+  /**
+   * Remove a record from all active query states and notify subscribers
+   */
+  private removeRecordFromQueries;
+  private createAndRegisterQuery;
+  private createNewQuery;
+  private calculateHash;
+  /**
+   * Session-independent counterpart of {@link calculateHash}: the key for a
+   * query's durable `_00_window` membership row.
+   *
+   * Deliberately the SAME inputs minus the `session::id()` salt, so the two keys
+   * can never drift apart. The salt is right for `_00_query` (two tabs must not
+   * fight over one row) and wrong for membership, which has to be recognizable
+   * after a reload — a reload mints a new session id, and offline the salt is
+   * `''`, so a salted key can never match what the previous session wrote.
+   */
+  private calculateMembershipKey;
+  private sha256;
+  private startTTLHeartbeat;
+  private replaceRecordInQueries;
 }
 /**
- * Configuration for a specific query instance.
- * Stores metadata about the query's state, parameters, and versioning.
+ * Parse update options to generate push event options
  */
-interface QueryConfig {
-  /** The unique ID of the query config record. */
-  id: RecordId$1<string>;
-  /** The SURQL query string. */
-  surql: string;
-  /** Parameters used in the query. */
-  params: Record<string, any>;
-  /** The version array representing the local state of results. */
-  localArray: RecordVersionArray;
-  /** The version array representing the remote (server) state of results. */
-  remoteArray: RecordVersionArray;
-  /** Time-To-Live for this query. */
-  ttl: QueryTimeToLive;
-  /** Timestamp when the query was last accessed/active. */
-  lastActiveAt: Date;
-  /** The name of the table this query targets (if applicable). */
-  tableName: string;
-}
-type QueryConfigRecord = QueryConfig & {
+//#endregion
+//#region src/services/tabs/protocol.d.ts
+type TabId = string;
+type TabRole = 'solo' | 'leader' | 'follower';
+/** Broker pings every tab at this cadence. */
+
+/** Matches `CacheIngestTuple` (modules/cache): exactly what `ingestMany`
+ *  consumes, so relayed batches feed follower circuits without reshaping. */
+interface IngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
   id: string;
+  record: Record<string, unknown>;
+}
+type FollowerToLeaderMessage = {
+  type: 'sync-hello';
+  tabId: TabId;
+}
+/** The follower committed an outbox row (through the shared store) and the
+ *  leader should drain it. Idempotent; a new leader's loadFromDatabase is
+ *  the backstop for a notify lost in a failover window. */ | {
+  type: 'mutation-enqueued';
+  mutationId: string;
+} | {
+  type: 'request-poll';
 };
-/**
- * Internal state of a live query.
- */
-interface QueryState {
-  /** The configuration for this query. */
-  config: QueryConfig;
-  /** The current cached records for this query. */
-  records: Record<string, any>[];
-  /** Timer for TTL expiration. */
-  ttlTimer: NodeJS.Timeout | null;
-  /** TTL duration in milliseconds. */
-  ttlDurationMs: number;
-  /** Number of times the query has been updated. */
-  updateCount: number;
-}
-type QueryUpdateCallback = (records: Record<string, any>[]) => void;
-type MutationCallback = (mutations: UpEvent[]) => void;
-type MutationEventType = 'create' | 'update' | 'delete';
-/**
- * Represents a mutation event (create, update, delete) to be synchronized.
- */
-interface MutationEvent {
-  /** Example: 'create', 'update', or 'delete'. */
-  type: MutationEventType;
-  /** unique id of the mutation */
-  mutation_id: RecordId$1<string>;
-  /** The ID of the record being mutated. */
-  record_id: RecordId$1<string>;
-  /** The data payload for create/update operations. */
-  data?: any;
-  /** The full record data (optional context). */
-  record?: any;
-  /** Options for the mutation event (e.g., debounce settings). */
-  options?: PushEventOptions;
-  /** Timestamp when the event was created. */
-  createdAt: Date;
+type LeaderToFollowerMessage = {
+  type: 'db-ready';
+  leadershipId: number;
+  bucketId: string;
+  storageHealth: StorageHealth;
 }
-/**
- * Options for run operations.
- */
-interface RunOptions {
-  assignedTo?: string;
-  max_retries?: number;
-  retry_strategy?: 'linear' | 'exponential';
+/** Every ingest the leader's CacheModule committed, so follower circuits
+ *  stay live without their own fetch. seq detects gaps. */ | {
+  type: 'ingest-relay';
+  tuples: IngestTuple[];
+  leadershipId: number;
+  seq: number;
+}
+/** A `_00_list_ref` LIVE event, relayed verbatim. Each follower resolves the
+ *  queryId against its own DataModule and ignores foreign queries. */ | {
+  type: 'list-ref-change';
+  action: 'CREATE' | 'UPDATE' | 'DELETE';
+  queryId: string;
+  recordId: string;
+  version: number;
+  parent: boolean;
 }
+/** The leader's drain rolled back a mutation owned by this tab. */ | {
+  type: 'mutation-rolled-back';
+  mutationId: string;
+  recordId: string;
+  eventType: 'create' | 'update' | 'delete';
+  error: string;
+};
+//#endregion
+//#region src/services/tabs/coordinator.d.ts
+/** Leader-side fan-out surface handed to the sync layer. The sync router
+ *  (modules/sync/tab-router.ts) registers itself as the message handler. */
+declare class LeaderSyncHub {
+  readonly leadershipId: number;
+  private logger;
+  private followers;
+  private seq;
+  onFollowerMessage: ((tabId: TabId, msg: FollowerToLeaderMessage) => void) | null;
+  onFollowerDetached: ((tabId: TabId) => void) | null;
+  constructor(leadershipId: number, logger: Logger$1);
+  attach(tabId: TabId, port: MessagePort): void;
+  detach(tabId: TabId): void;
+  detachAll(): void;
+  sendTo(tabId: TabId, msg: LeaderToFollowerMessage): void;
+  broadcast(msg: LeaderToFollowerMessage, exceptTabId?: TabId): void;
+  /** Stamped ingest relay; seq lets followers detect gaps. */
+  relayIngest(tuples: IngestTuple[], exceptTabId?: TabId): void;
+  get followerCount(): number;
+  get relayedBatches(): number;
+}
+/** Follower half of the syncPort. Queues while detached (leaderless window)
+ *  and flushes on rebind; a lost-in-flight mutation notify is additionally
+ *  backstopped by the new leader reloading the shared outbox from the store. */
+declare class SyncForwarder {
+  private tabId;
+  private port;
+  private queued;
+  onLeaderMessage: ((msg: LeaderToFollowerMessage) => void) | null;
+  constructor(tabId: TabId);
+  rebind(port: MessagePort): void;
+  unbind(): void;
+  private post;
+  mutationEnqueued(mutationId: string): void;
+  requestPoll(): void;
+}
+//#endregion
+//#region src/modules/sync/sync.d.ts
 /**
- * Options for update operations.
+ * Tunables for `Sp00kySync` construction.
  */
-interface UpdateOptions {
+interface Sp00kySyncOptions {
+  /**
+   * Cadence (ms) for the `_00_list_ref` poll fallback that catches
+   * cross-session UPDATEs the LIVE-permission gap drops. Non-positive
+   * values fall back to the default; see
+   * {@link resolveListRefPollInterval}.
+   */
+  refSyncIntervalMs?: number;
+  /**
+   * Enable realtime sync for unauthenticated clients against the shared
+   * `_00_list_ref_anon` table. See {@link Sp00kyConfig.enableAnonymousLiveQueries}.
+   * Defaults to `false`.
+   */
+  anonymousLiveQueries?: boolean;
   /**
-   * Debounce configuration for the update.
-   * If boolean, enables default debounce behavior.
+   * Consecutive failed sync rounds before sync health flips to `degraded`.
+   * `0` disables degraded reporting. See {@link Sp00kyConfig.syncHealth}.
+   * Defaults to `3`.
    */
-  debounced?: boolean | DebounceOptions;
+  degradeAfterConsecutiveFailures?: number;
+  /**
+   * Max time a single mutation push may take before it is treated as a network
+   * failure and retried. Guards against an RPC that never settles wedging the
+   * up-queue for the session. Defaults to 30000; `0` disables the timeout.
+   */
+  pushTimeoutMs?: number;
+  /**
+   * Transport supervisor. Sync reads its state to report `connection` in
+   * {@link SyncHealth} so a UI can show "reconnecting…" the instant the socket
+   * drops, without waiting for the degrade threshold. Optional: omitted in
+   * tests, where `connection` then reports `connected`.
+   */
+  connectionSupervisor?: ConnectionSupervisor;
 }
 /**
- * Configuration options for debouncing updates.
+ * The main synchronization engine for Sp00ky.
+ * Handles the bidirectional synchronization between the local database and the remote backend.
+ * Uses a queue-based architecture with 'up' (local to remote) and 'down' (remote to local) queues.
+ * @template S The schema structure type.
  */
-interface DebounceOptions {
+declare class Sp00kySync<S extends SchemaStructure> {
+  private local;
+  private remote;
+  private cache;
+  private dataModule;
+  private schema;
+  private upQueue;
+  private downQueue;
+  private isInit;
+  private logger;
+  private syncEngine;
+  /** Engine-level events (e.g. `SYNC_REMOTE_DATA_INGESTED`). Distinct
+   *  from `this.events`, which carries Sp00kySync-level events like
+   *  `SYNC_QUERY_UPDATED` and `SYNC_MUTATION_ROLLED_BACK`. */
+  get engineEvents(): SyncEventSystem;
+  private scheduler;
+  /**
+   * Set by any event that means the socket we registered on is gone, so the
+   * next `connected` knows it must re-subscribe rather than treat itself as the
+   * initial connect. See {@link subscribeToReconnect}.
+   */
+  private needsResubscribe;
+  /** When the last reconnect-driven full refetch ran, for burst coalescing. */
+  private lastReconnectRefetchAt;
+  /**
+   * Minimum gap between reconnect-driven full refetches. Long enough to absorb
+   * a flapping socket (the SDK reconnect ladder starts at 1s), short enough
+   * that a genuine drop minutes later still refetches.
+   */
+  private static readonly RECONNECT_REFETCH_COOLDOWN_MS;
+  events: SyncEventSystem;
+  private currentUserId;
+  private tabRole;
+  private tabId;
+  private hub;
+  private forwarder;
+  private refMode;
+  private readonly anonLiveEnabled;
+  private currentLiveQueryUuid;
+  private liveQueryUnsubscribe;
+  private listRefPollTimer;
+  private listRefPollRunning;
+  private listRefPollInFlight;
+  readonly refSyncIntervalMs: number;
+  private listRefIdleStreak;
+  private stillRemoteStreaks;
+  private lastLiveEventAt;
+  private _liveRetryCount;
+  get liveRetryCount(): number;
+  get isSyncing(): boolean;
+  get pendingMutationCount(): number;
+  subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  private readonly degradeAfterFailures;
+  /** Per-push RPC deadline; see {@link withPushTimeout}. */
+  private readonly pushTimeoutMs;
+  private consecutiveSyncFailures;
+  private syncHealthStatus;
+  private lastSyncErrorKind;
+  private lastSyncErrorMessage;
+  private hasSyncedOnce;
+  private selfHealTimer;
+  private selfHealAttempts;
+  private static readonly SELF_HEAL_BASE_MS;
+  private static readonly SELF_HEAL_MAX_MS;
+  /**
+   * Transport supervisor, when one was supplied. Sync only reads state from it;
+   * it never drives reconnects itself.
+   */
+  private readonly connectionSupervisor?;
+  /**
+   * Mirror of the supervisor's state. Defaults to `connected` so a client
+   * constructed without a supervisor (tests, embedders) reports the same health
+   * shape it always has rather than a permanent false "disconnected".
+   */
+  private connectionState;
+  /** Current sync-health snapshot. */
+  get syncHealth(): SyncHealth;
+  /**
+   * Observe sync health. The callback fires immediately with the current
+   * status and again on every healthy↔degraded transition. Returns an
+   * unsubscribe. Mirrors {@link subscribeToPendingMutations}.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  private emitSyncHealth;
+  /**
+   * Mirror the supervisor's transport state into {@link SyncHealth} and emit on
+   * every change, so a UI can react to a dropped socket immediately instead of
+   * waiting for `degradeAfterFailures` failed rounds. `status` is untouched:
+   * a brief reconnect is not a degradation.
+   *
+   * No explicit unsubscribe: the supervisor is owned by the same client and
+   * drops all subscribers in its own `dispose()`, which `Sp00kyClient.close()`
+   * calls first.
+   */
+  private subscribeToConnectionState;
+  /**
+   * Fed by the scheduler once per drained sync round. Individual failures are
+   * absorbed by the queue's retry; only a run of `degradeAfterFailures`
+   * consecutive failures flips the status to `degraded`, and the next clean
+   * round flips it back. No-op when reporting is disabled (`degradeAfterFailures`
+   * is 0).
+   */
+  private recordSyncOutcome;
+  /**
+   * Begin self-heal retries (no-op if already running). Started on the
+   * healthy→degraded transition; {@link recordSyncOutcome} stops it on recovery.
+   */
+  private startSelfHeal;
+  private scheduleSelfHeal;
+  private stopSelfHeal;
+  constructor(local: LocalStore, remote: RemoteDatabaseService, cache: CacheModule, dataModule: DataModule<S>, schema: S, logger: Logger$1, options?: Sp00kySyncOptions);
+  /**
+   * Initializes the synchronization system.
+   * Starts the scheduler and initiates the initial sync cycles.
+   * @throws Error if already initialized.
+   */
+  init(): Promise<void>;
+  /** Set BEFORE init(): shapes what init boots (a follower loads no outbox and
+   *  never starts LIVE; its own registration/poll paths stay untouched). */
+  setTabContext(role: 'solo' | 'leader' | 'follower', tabId: string | null): void;
+  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+   *  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
+   *  boot-time leader; a runtime promotion (failover) reloads the outbox,
+   *  which now holds EVERY tab's rows, and restarts LIVE under this session. */
+  promoteToLeader(hub: LeaderSyncHub): Promise<void>;
+  /** Follower duties: no outbox drain, no LIVE. Mutations forward to the
+   *  leader; everything else (registration, per-query sync, poll) runs
+   *  against this tab's own remote session as usual. */
+  demoteToFollower(forwarder: SyncForwarder): void;
+  /**
+   * A pending mutation was discarded because it can never be sent.
+   *
+   * This is a lost write, so it must not stay invisible. Every failure in this
+   * chain used to be a `logger.error` an app running `logLevel: 'fatal'` never
+   * shows, which is how an outbox could sit undrained for hours with the UI
+   * reporting nothing. Surfaces as a rollback event (the mutation will never
+   * apply, which is what a subscriber needs to know) and degrades sync health.
+   */
+  private onMutationDropped;
+  /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
+  enqueueForwardedMutation(mutationId: string): Promise<void>;
+  /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
+   *  and run the exact same handling the LIVE subscription would have. */
+  private applyRelayedListRefChange;
+  /** One immediate poll cycle (failover convergence). */
+  forcePollRound(): Promise<void>;
+  /**
+   * Quiesce all sync activity ahead of a local-bucket switch. After this
+   * resolves, nothing in the sync module writes to the local store: the poll
+   * loop is stopped AND its in-flight tick awaited, LIVE is killed, debounce
+   * timers are cancelled (their outbox rows are already persisted), and the
+   * scheduler has drained its in-flight queue item — including that item's
+   * outbox-row delete, which must land in the OLD bucket. Queued down-events
+   * are dropped (they reference old-bucket query rows; the post-switch rebind
+   * re-enqueues registrations). The old user's un-pushed outbox is deliberately
+   * NOT drained: the remote session already belongs to the next user.
+   */
+  prepareBucketSwitch(): Promise<void>;
+  /**
+   * Resume syncing against the freshly-opened bucket: reload the mutation
+   * outbox from ITS `_00_pending_mutations` (the new user's own un-pushed
+   * offline work) and restart the scheduler. LIVE + the list_ref poll restart
+   * via the `setCurrentUserId` call that follows in the auth listener.
+   */
+  completeBucketSwitch(): Promise<void>;
+  /**
+   * Push the authenticated user's record id from the parent client's
+   * auth subscription. Tears down the existing `_00_list_ref` LIVE (if
+   * any) and re-registers it under the new user's dedicated table so
+   * SurrealDB binds the permission rule under the post-flip auth
+   * context. Pass `null` on sign-out.
+   *
+   * The dedicated `_00_list_ref_user_<id>` table is created lazily by
+   * the SSP when the first query registration arrives, which may be
+   * concurrent with this call. We retry the LIVE registration with a
+   * short backoff so a "table not found" race resolves without
+   * surfacing as a permanent auth-loading hang.
+   */
+  setCurrentUserId(userId: string | null): Promise<void>;
+  private startListRefPoll;
+  private stopListRefPoll;
+  /**
+   * One poll cycle: refetch `_00_list_ref` for every active query. Returns
+   * whether ANY query's remoteArray actually changed — the scheduler uses this
+   * to drive the adaptive idle backoff.
+   *
+   * Also the ONLY health signal that runs while the page is idle. Sync health is
+   * otherwise activity-driven (mutations/registrations via the scheduler,
+   * reconnect re-registration, self-heal), so on a quiet page a stale `degraded`
+   * would linger until the next mutation and a genuine idle drop would be
+   * invisible. We fold the cycle's aggregate reachability into `recordSyncOutcome`
+   * so idle health self-recovers (and self-degrades) with no user action. A clean
+   * cycle is idempotent when already healthy (`recordSyncOutcome` early-returns at
+   * `consecutiveSyncFailures === 0`), so a healthy idle page pays nothing.
+   */
+  private pollListRefForActiveQueries;
+  /**
+   * Pull the upstream list_ref entries for `queryHash`, diff them
+   * against the local `remoteArray` cache, sync any added/updated rows
+   * through the SyncEngine, then persist the new remoteArray. This is
+   * the same shape `createRemoteQuery` does for its initial fetch and
+   * what `handleRemoteListRefChange` does per-LIVE-event — we reuse
+   * it on a timer as a fallback for missed LIVE notifications.
+   */
+  private refetchListRefForQuery;
+  /**
+   * Resolve the current `_00_list_ref` table name for the active auth
+   * context. Public so the `createRemoteQuery` initial-fetch path can
+   * read from the right per-user table.
+   *
+   * Reads the user id from `DataModule` rather than the local mirror,
+   * because `DataModule.setCurrentUserId` runs synchronously from the
+   * auth callback (before any `await`), whereas `sync.setCurrentUserId`
+   * is async — the userQuery's initial fetch can fire between those
+   * two points and we need the correct table name immediately.
+   */
+  listRefTable(): string;
+  private killRefLiveQuery;
+  private restartRefLiveQuery;
+  /**
+   * Drop local LIVE bookkeeping without issuing a `KILL`.
+   *
+   * Called when the socket dies. The server-side subscription is scoped to that
+   * WebSocket session and died with it, so there is nothing left to kill — and
+   * by the time the reconnect handler runs, the client reports `connected`
+   * again, which would otherwise send a `KILL` for a stale uuid on the *new*
+   * session and hold up the restart queued behind it.
+   */
+  private invalidateRefLiveQuery;
+  private subscribeToReconnect;
+  private startRefLiveQueries;
+  private handleRemoteListRefChange;
   /**
-   * The key to use for debouncing.
-   * - 'recordId': Debounce based on the specific record ID. WARNING: IT WILL ONLY ACCEPT THE LATEST CHANGE AND DOES *NOT* MERGE THE PREVIOUS ONCES. IF YOU ARE UNSURE JUST USE 'recordId_x_fields'.
-   * - 'recordId_x_fields': Debounce based on record ID and specific fields.
+   * Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
+   * `parent` set) for a `.related()` query. Unlike primary rows, child rows
+   * must NOT touch the query's `localArray`/`remoteArray`/`rowCount`; we only
+   * keep the child BODY fresh in the local cache so the in-browser SSP's
+   * subquery-table dependency re-materializes the parent view.
+   *
+   * CREATE/UPDATE fetch+upsert the child body. DELETE is intentionally a
+   * no-op: a child leaving this query's set must not delete a body another
+   * query may still show (see `syncSubqueryChildren` deletion-safety note);
+   * a genuine record delete propagates via the normal delete path.
    */
-  key?: 'recordId' | 'recordId_x_fields';
-  /** The debounce delay in milliseconds. */
-  delay?: number;
+  private handleRemoteSubqueryChange;
+  /**
+   * Enqueues a 'down' event (from remote to local) for processing.
+   * @param event The DownEvent to enqueue.
+   */
+  enqueueDownEvent(event: DownEvent): void;
+  /**
+   * Bound a mutation push so it always settles.
+   *
+   * `SyncScheduler.syncUp` early-returns while `isSyncingUp` is true, and that
+   * flag only clears in the `finally` of the drain loop. A push whose RPC never
+   * settles (socket dropped mid-flight, response lost) therefore wedges the
+   * up-queue for the rest of the session: no retry, no error, no further
+   * mutation ever sent. A timeout turns that into an ordinary network failure,
+   * which `UpQueue.next` re-queues for the next trigger. The message deliberately
+   * contains "timed out" so `classifySyncError` treats it as `network` and
+   * retries rather than rolling the mutation back.
+   */
+  private withPushTimeout;
+  private processUpEvent;
+  private handleRollback;
+  private processDownEvent;
+  /**
+   * Synchronizes a specific query by hash.
+   * Compares local and remote version arrays and fetches differences.
+   * @param hash The hash of the query to sync.
+   */
+  syncQuery(hash: string): Promise<void>;
+  /**
+   * Run a sync for a single query while reflecting its fetch status. Marks the
+   * query `fetching` for the duration when the diff actually pulls records
+   * (added/updated), then resets to `idle` in a `finally` so a failed sync
+   * never leaves a query stuck `fetching`. Part A's notification coalescing
+   * means the single resulting UI update lands after this completes.
+   */
+  private runSyncForQuery;
+  /**
+   * Record ids with a pending local DELETE in the outbox (`_00_pending_mutations`).
+   * Sync must not re-fetch/re-insert these — the remote delete is async, so the
+   * server's `_00_list_ref` still lists them until it's processed, and the diff
+   * would otherwise resurrect a just-deleted record.
+   */
+  private getPendingDeleteIds;
+  /**
+   * Enqueues a list of mutations (up events) to be sent to the remote.
+   * @param mutations Array of UpEvents (create/update/delete) to enqueue.
+   */
+  enqueueMutation(mutations: UpEvent[]): Promise<void>;
+  private registerQuery;
+  private createRemoteQuery;
+  /**
+   * Sync the BODIES of a `.related()` query's subquery child rows into the
+   * local cache, separately from the primary window array. The SSP writes
+   * each matched child as a `_00_list_ref` edge tagged `parent`/`parent_rel`;
+   * `buildSubqueryListRefSelect` pulls those `out`+`version` pairs (any
+   * nesting depth). We diff against the in-memory `subqueryRemoteArray` and
+   * fetch added/updated bodies through the SyncEngine — which `saveBatch`s
+   * them into the local DB AND the in-browser SSP, whose subquery-table
+   * dependency then re-materializes the parent view (no explicit notify).
+   *
+   * Deletion safety: we pass `removed: []` deliberately. A child body can be
+   * shared by other queries; letting `handleRemovedRecords` delete one that
+   * merely left THIS query's child set would clobber data another query still
+   * shows. Genuine record deletes flow through the normal delete path; a
+   * lingering orphan body is invisible (the correlated WHERE stops matching).
+   *
+   * Kept off `runSyncForQuery` on purpose so child fetches never flip the
+   * query to `fetching` or skew its DevTools timings.
+   */
+  private syncSubqueryChildren;
+  heartbeatQuery(queryHash: string): Promise<void>;
+  private cleanupQuery;
 }
 //#endregion
 //#region src/modules/auth/events/index.d.ts
@@ -518,6 +1407,13 @@ declare class AuthService<S extends SchemaStructure> {
   token: string | null;
   currentUser: any | null;
   isAuthenticated: boolean;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  access: string | null;
   isLoading: boolean;
   private events;
   get eventSystem(): AuthEventSystem;
@@ -539,17 +1435,617 @@ declare class AuthService<S extends SchemaStructure> {
    */
   signOut(): Promise<void>;
   private setSession;
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName;
   signUp<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signup'>): Promise<void>;
   signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
 }
 //#endregion
-//#region src/spooky.d.ts
+//#region src/modules/crdt/crdt-field.d.ts
+declare const CURSOR_COLORS: string[];
+declare function cursorColorFromName(name: string): string;
+declare class CrdtField {
+  private fieldName;
+  private doc;
+  private pushTimer;
+  private local;
+  private remote;
+  private recordId;
+  private sessionId;
+  private unsubscribe;
+  private lastPushTime;
+  private lastCursorPushTime;
+  private loadedFromCrdt;
+  private pushRetryCount;
+  private logger;
+  private cursorsEnabled;
+  /** Remote-push debounce. Local writes happen immediately on every Loro
+   *  update; the remote UPSERT is coalesced over this window. Configured
+   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
+  private remoteDebounceMs;
+  private _onCursorUpdate;
+  private pendingCursorUpdate;
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
+  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
+  /**
+   * @param LoroDocClass the `LoroDoc` constructor, injected by the caller after
+   *   awaiting {@link loadLoro} — keeps `loro-crdt` out of this module's static
+   *   import graph so it only ships to apps that use CRDT fields.
+   */
+  constructor(fieldName: string, cursorsEnabled: boolean, LoroDocClass: typeof LoroDoc, initialState?: Uint8Array, logger?: Logger$1 | null);
+  getDoc(): LoroDoc;
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean;
+  startSync(local: LocalStore, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
+  /**
+   * Stop syncing this field. Flushes one final remote push by default so the
+   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
+   * the remote session already belongs to the NEXT user, and pushing this
+   * (previous user's) snapshot under it would clobber the record remotely.
+   */
+  stopSync(options?: {
+    flush?: boolean;
+  }): void;
+  importRemote(state: Uint8Array): void;
+  exportSnapshot(): Uint8Array;
+  /** Push this session's cursor blob into the parent row at
+   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
+   *  field — the editor still calls this method optimistically, but
+   *  without `@cursor` on the schema there's nowhere to store the blob.
+   *  The UPDATE itself fires the parent table's LIVE feed, so other
+   *  browsers receive the cursor change without a separate `_00_rv` bump. */
+  pushCursorState(encoded: Uint8Array): Promise<void>;
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void;
+  private scheduleRemotePush;
+  /** SET path inside a parent row for the current snapshot. `@crdt`-only
+   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
+   *  fields hold a `{ state, cursors }` object so the snapshot lives at
+   *  `<field>.state` next to per-session cursor blobs. */
+  private statePath;
+  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
+   *  every local update and every remote import so reloads (online or
+   *  offline) see the freshest content immediately. Failures are
+   *  swallowed — a stale local write must never block user input. */
+  private persistLocal;
+  private pushToRemote;
+}
+//#endregion
+//#region src/modules/crdt/index.d.ts
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ */
+declare class CrdtManager {
+  private schema;
+  private local;
+  private remote;
+  private debounceMs;
+  private fields;
+  private liveByTable;
+  private pendingLive;
+  private staleTables;
+  private connectionGeneration;
+  private connectionUnsubscribes;
+  private logger;
+  private sessionId;
+  constructor(schema: SchemaStructure, local: LocalStore, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /**
+   * Re-establish table LIVEs after a socket drop.
+   *
+   * A LIVE subscription lives and dies with its WebSocket session, and
+   * `ensureTableSubscription` is memoized on `liveByTable` — so without this,
+   * the first reconnect leaves CRDT realtime permanently dead: the map still
+   * holds a uuid for a subscription the server has forgotten, so every later
+   * `open()` short-circuits and no LIVE is ever re-issued.
+   *
+   * Both drop events matter: the SDK publishes `reconnecting` (not
+   * `disconnected`) when it intends to recover on its own, and `disconnected`
+   * only once it has given up.
+   */
+  private subscribeToReconnect;
+  /** Stop observing transport events. Separate from {@link closeAll}, which also
+   *  runs on a bucket switch where the manager keeps being used. */
+  dispose(): void;
+  private hasOpenFieldFor;
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void;
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  close(table: string, recordId: string, field: string): void;
+  /**
+   * Close every open field + table LIVE. Fields flush a final remote push by
+   * default; pass `{ flush: false }` on a bucket switch, where that flush
+   * would push the previous user's snapshot under the next user's session.
+   */
+  closeAll(options?: {
+    flush?: boolean;
+  }): void;
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private ensureTableSubscription;
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void;
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow;
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private fetchAndDispatchRow;
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor;
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot;
+  private killTableSubscription;
+  private makeKey;
+  /**
+   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
+   * typos, removed annotations, and stale schema codegen at the call site instead
+   * of silently producing a non-CRDT writer.
+   */
+  private assertCrdtField;
+}
+//#endregion
+//#region src/modules/feature-flag/index.d.ts
+interface FeatureFlagSnapshot {
+  variant: string | undefined;
+  payload: unknown | undefined;
+}
+interface FeatureFlagOptions {
+  fallback?: string;
+  ttl?: QueryTimeToLive;
+}
+/**
+ * A locally forced variant. Applies to THIS browser only and is never sent to
+ * the server — the assignment in `_00_user_feature` is untouched, so clearing
+ * the override restores whatever the server says.
+ */
+interface FeatureFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
+declare class FeatureFlagHandle {
+  readonly key: string;
+  readonly fallback: string | undefined;
+  private latest;
+  private listeners;
+  private unsubscribeFn;
+  private onCloseFn;
+  private closed;
+  constructor(key: string, fallback: string | undefined);
+  attach(unsubscribe: () => void): void;
+  detach(): void;
+  set(snapshot: FeatureFlagSnapshot): void;
+  variant(): string | undefined;
+  payload<T = unknown>(): T | undefined;
+  enabled(): boolean;
+  subscribe(cb: (s: FeatureFlagSnapshot) => void): () => void;
+  onClose(cb: () => void): void;
+  close(): void;
+}
+interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger$1;
+}
+declare class FeatureFlagModule<S extends SchemaStructure> {
+  private deps;
+  private logger;
+  private handles;
+  private authUnsubscribe;
+  private lastUserId;
+  private querySubscription;
+  private starting;
+  private ttl;
+  private snapshots;
+  private loaded;
+  private overrides;
+  constructor(deps: FeatureFlagModuleDeps<S>);
+  init(): void;
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  closeAll(): Promise<void>;
+  /** Auth changed: drop the old user's query/snapshots and re-observe. */
+  private refresh;
+  private teardownQuery;
+  /** Start the single shared live query (idempotent; no-op with no handles). */
+  private ensureStarted;
+  /** Live query result → per-key snapshots → push to every active handle. */
+  private applyRecords;
+  /**
+   * Force `key` to `variant` in THIS browser. Pass `null` to clear.
+   *
+   * Nothing is written to the server: the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage on the page origin, so it survives a reload.
+   */
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearLocalOverrides(): void;
+  getLocalOverrides(): Record<string, FeatureFlagOverride>;
+  /** The assignment for `key`, with any local override taking precedence. */
+  private resolve;
+  private pushAll;
+  private loadOverrides;
+  private persistOverrides;
+}
+//#endregion
+//#region src/modules/app-release/index.d.ts
+interface AppReleaseSnapshot {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  version: string | undefined;
+  /** Clients should clear SW/caches when reloading onto this version. */
+  cacheBust: boolean;
+  /** Clients should reload/update immediately instead of asking. */
+  mandatory: boolean;
+  releasedAt: string | undefined;
+}
+interface AppReleaseOptions {
+  ttl?: QueryTimeToLive;
+}
+declare class AppReleaseHandle {
+  readonly app: string;
+  private latest;
+  private listeners;
+  private onCloseFn;
+  private closed;
+  constructor(app: string);
+  set(snapshot: AppReleaseSnapshot): void;
+  snapshot(): AppReleaseSnapshot;
+  version(): string | undefined;
+  /** True when the announced version is semver-newer than `currentVersion`. */
+  updateAvailable(currentVersion: string): boolean;
+  subscribe(cb: (s: AppReleaseSnapshot) => void): () => void;
+  onClose(cb: () => void): void;
+  close(): void;
+}
+interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger$1;
+}
+declare class AppReleaseModule<S extends SchemaStructure> {
+  private deps;
+  private logger;
+  private handles;
+  private authUnsubscribe;
+  private lastUserId;
+  private querySubscription;
+  private starting;
+  private ttl;
+  private snapshots;
+  private loaded;
+  constructor(deps: AppReleaseModuleDeps<S>);
+  init(): void;
+  release(app: string, options?: AppReleaseOptions): AppReleaseHandle;
+  closeAll(): Promise<void>;
+  private refresh;
+  private teardownQuery;
+  private ensureStarted;
+  private applyRecords;
+}
+//#endregion
+//#region src/services/blobs/blob-store.d.ts
+/**
+ * Byte storage for cached bucket files.
+ *
+ * The default implementation is OPFS. Bucket files never arrive over HTTP in
+ * this client — `BucketHandle.get()` is a SurrealQL RPC on the sync socket — so
+ * neither the browser's HTTP cache nor the Cache API can hold them. We persist
+ * the bytes ourselves, and OPFS is the cheapest place to put them: a read is
+ * `getFile()` → a disk-backed lazy `File` that `URL.createObjectURL` can serve
+ * without ever moving the bytes through the JS heap.
+ *
+ * Layout is real nested directories rather than one hashed filename:
+ *
+ *   sp00ky-blobs/<namespace>/<bucket>/<...path segments>
+ *
+ * That costs a `getDirectoryHandle` per segment on write, and buys the property
+ * the whole orphan story rests on: the full `(bucket, path)` key is recoverable
+ * from a directory walk alone. The `_00_blob` manifest can therefore be wiped
+ * (memory fallback, SQLite pool wipe, IndexedDB corruption recovery) and be
+ * rebuilt from disk instead of taking the cached bytes down with it.
+ */
+/** Identifies one cached file: the bucket it lives in and its path within. */
+interface BlobKey {
+  bucket: string;
+  path: string;
+}
+/** What a directory walk can tell us about a stored file, with no manifest. */
+interface BlobStat {
+  key: BlobKey;
+  size: number;
+  /** File mtime. Seeds `lastAccess` when a manifest row has to be rebuilt. */
+  mtime: number;
+}
+interface BlobStore {
+  /** False for {@link MemoryBlobStore} and for OPFS-less environments: the
+   *  cache still dedupes and serves within a tab, but nothing survives reload. */
+  readonly persistent: boolean;
+  /** Namespace (the local bucketId) all keys are resolved under. */
+  readonly namespace: string;
+  read(key: BlobKey): Promise<Blob | null>;
+  /** Returns the number of bytes written. Throws on quota exhaustion. */
+  write(key: BlobKey, bytes: Blob): Promise<number>;
+  remove(key: BlobKey): Promise<void>;
+  /** Every committed file under the current namespace. Sweeps torn writes. */
+  list(): Promise<BlobStat[]>;
+  /** Drop the whole namespace (sign-out with `clearOnSignOut`, or a reset). */
+  clear(): Promise<void>;
+  /** Point at another namespace. Does not touch the bytes of the old one. */
+  setNamespace(namespace: string): void;
+}
+//#endregion
+//#region src/services/blobs/blob-manifest.d.ts
+interface BlobEntry {
+  /** `${bucket}/${path}` — also the `_00_blob` row id. */
+  id: string;
+  bucket: string;
+  path: string;
+  size: number;
+  contentType: string;
+  createdAt: number;
+  lastAccess: number;
+  hits: number;
+  /** Exempt from pressure eviction. Never expires on its own. */
+  pinned: boolean;
+}
+declare class BlobManifest {
+  private local;
+  private entries;
+  /** Ids whose in-memory state has not been written back yet. */
+  private dirty;
+  private removed;
+  private flushing;
+  constructor(local: LocalStore);
+  /**
+   * Hydrate from the rows matching `keys`. Ids come from the OPFS listing, so
+   * this never needs a full-table scan (and therefore never needs a QueryPlan).
+   * Any read failure yields an empty manifest: reconcile then rebuilds every
+   * row from disk, which is exactly the desired degradation.
+   */
+  load(ids: string[]): Promise<void>;
+  get(key: BlobKey): BlobEntry | undefined;
+  getById(id: string): BlobEntry | undefined;
+  all(): BlobEntry[];
+  totalBytes(): number;
+  pinnedBytes(): number;
+  put(entry: BlobEntry): void;
+  touch(id: string, now: number): void;
+  setPinned(id: string, pinned: boolean): boolean;
+  remove(id: string): void;
+  /** Forget everything without scheduling deletes — for a bucket switch, where
+   *  the rows belong to the store we are leaving and must stay put. */
+  reset(): void;
+  hasPendingWrites(): boolean;
+  /**
+   * Write back pending changes. Serialized: a second concurrent flush awaits
+   * the first rather than racing it into the same rows. Failures are swallowed
+   * on purpose — a lost metadata write costs an LRU timestamp, and the entry is
+   * rebuilt from disk on the next reconcile.
+   */
+  flush(): Promise<void>;
+  private doFlush;
+}
+//#endregion
+//#region src/services/blobs/blob-cache.d.ts
+interface BlobUrlLease {
+  url: string;
+  release(): void;
+}
+interface BlobReadOptions {
+  /** Write through to L1 on a miss. Default true. */
+  persist?: boolean;
+  /** Mark the entry exempt from pressure eviction. */
+  pin?: boolean;
+  /**
+   * Default `'never'`: a bucket path is treated as immutable, which is how the
+   * client writes them (`crypto.randomUUID() + ext`). `'head'` spends a remote
+   * `head()` to compare sizes before trusting L1.
+   */
+  revalidate?: 'never' | 'head';
+  /** Skip L0/L1 entirely and refill from remote. Backs `refetch()`. */
+  reload?: boolean;
+}
+interface BlobCacheStats {
+  entries: number;
+  totalBytes: number;
+  budgetBytes: number;
+  pinnedBytes: number;
+  evictedEntries: number;
+  evictedBytes: number;
+  reconciledEntries: number;
+  hits: number;
+  misses: number;
+  persistent: boolean;
+  /** True when pinned bytes alone exceed the budget: new entries stop being
+   *  written rather than pinned ones being thrown away. */
+  persistPaused: boolean;
+}
+interface BlobCacheOptions {
+  store: BlobStore;
+  manifest: BlobManifest;
+  /** L2 read. Resolves to null when the file does not exist remotely. */
+  fetchRemote(key: BlobKey): Promise<Blob | null>;
+  /** L2 metadata, for `revalidate: 'head'`. */
+  headRemote?(key: BlobKey): Promise<Record<string, unknown> | null>;
+  logger: Logger$1;
+  maxBytes: number;
+  now?: () => number;
+  /** Injected so the URL layer is exercisable off a DOM (node tests). */
+  urls?: {
+    create(blob: Blob): string;
+    revoke(url: string): void;
+  };
+}
+declare class BlobCache {
+  private readonly store;
+  private readonly manifest;
+  private readonly fetchRemote;
+  private readonly headRemote?;
+  private readonly logger;
+  private readonly now;
+  private readonly urlFactory;
+  private maxBytes;
+  private persistPaused;
+  /** Set after a quota failure survives one forced eviction. */
+  private persistDisabled;
+  private readonly urls;
+  /** Ids at zero references, oldest first — the hot-URL window. */
+  private idleUrls;
+  private readonly inflight;
+  private flushTimer;
+  private readonly onPageHide;
+  /**
+   * Resolves once the manifest has been reconciled against disk. Reads await
+   * it, so `start()` does NOT have to be awaited on the boot path — blocking
+   * boot on an OPFS directory walk delayed the WebSocket connect (and with it
+   * the connection supervisor) for no benefit.
+   */
+  private ready;
+  private hits;
+  private misses;
+  private evictedEntries;
+  private evictedBytes;
+  private reconciledEntries;
+  constructor(opts: BlobCacheOptions);
+  /** Coalesce manifest write-back. Metadata only, so losing the tail costs an
+   *  LRU timestamp that reconcile reseeds from the file mtime. */
+  private scheduleFlush;
+  /**
+   * Resolve the bytes for `key`, filling L1 on the way when `persist` is on.
+   * Returns null when the file does not exist remotely and is not cached.
+   */
+  read(key: BlobKey, options?: BlobReadOptions): Promise<Blob | null>;
+  /**
+   * An object URL for `key`, refcounted. Callers MUST `release()`; the URL is
+   * revoked once the last holder lets go and it falls out of the hot window.
+   */
+  acquireUrl(key: BlobKey, options?: BlobReadOptions): Promise<BlobUrlLease | null>;
+  private lease;
+  private releaseUrl;
+  private revokeUrl;
+  /** L1 lookup with the size check that catches torn and cross-tab writes. */
+  private readLocal;
+  /** True when the remote agrees with the cached size, or cannot be reached. */
+  private headMatches;
+  private fetchDeduped;
+  private persist;
+  private writeThrough;
+  /** Forget one path everywhere. Called on `bucket.put()`/`bucket.delete()`. */
+  invalidate(key: BlobKey): Promise<void>;
+  private dropLocal;
+  setPinned(key: BlobKey, pinned: boolean): void;
+  /**
+   * Bring total bytes under budget by dropping the least recently used
+   * entries. Pinned entries and anything with a live object URL are skipped —
+   * evicting bytes that a mounted `<img>` is displaying would blank it.
+   */
+  private enforceBudget;
+  /** Evict LRU-first until at or below `target`. Returns the resulting total. */
+  private evictTo;
+  /**
+   * Rebuild the manifest from what is actually on disk. OPFS wins on existence
+   * in both directions: files with no row get a row (seeded from mtime), rows
+   * are only loaded for files that exist, and torn `.part-` writes are swept by
+   * the walk itself.
+   *
+   * Rows whose file vanished outside our control (a browser origin eviction)
+   * are left in `_00_blob`. They are inert — `load()` only ever asks for ids it
+   * found on disk — and are overwritten if that path is cached again.
+   */
+  reconcile(): Promise<void>;
+  /** Warm the cache for offline use. Skips anything already cached. */
+  prefetch(keys: BlobKey[]): Promise<void>;
+  /** Bind to the boot bucket and hydrate the manifest from disk. Separate from
+   *  {@link setNamespace} because boot must reconcile even when the namespace
+   *  it lands on is the one the store was constructed with. */
+  start(namespace: string): Promise<void>;
+  /** Repoint at another local bucket. The bytes of the old one stay on disk so
+   *  switching back (or signing back in) is still warm. */
+  setNamespace(namespace: string): Promise<void>;
+  setMaxBytes(maxBytes: number): void;
+  /** Delete every cached byte in the current namespace. */
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  /** Flush metadata and drop every object URL. Must run before the local store
+   *  closes — the flush writes through it. */
+  close(): Promise<void>;
+  stats(): BlobCacheStats;
+}
+//#endregion
+//#region src/sp00ky.d.ts
+/** Coerce whatever the `.get()` RPC hands back into a Blob. */
+declare function bucketContentToBlob(content: unknown): Blob | null;
 declare class BucketHandle {
   private bucketName;
   private remote;
-  constructor(bucketName: string, remote: RemoteDatabaseService);
+  /** Absent on the raw handle the cache itself reads through. */
+  private blobs?;
+  constructor(bucketName: string, remote: RemoteDatabaseService, /** Absent on the raw handle the cache itself reads through. */
+  blobs?: (BlobCache | null) | undefined);
   put(path: string, content: string | Uint8Array | Blob): Promise<void>;
   get(path: string): Promise<unknown>;
+  /**
+   * 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.
+   */
+  read(path: string, options?: BlobReadOptions): Promise<Blob | null>;
+  /**
+   * 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).
+   */
+  url(path: string, options?: BlobReadOptions): Promise<BlobUrlLease | null>;
+  /** Exempt `path` from pressure eviction. Pinned bytes never expire. */
+  pin(path: string): void;
+  unpin(path: string): void;
+  /** Drop `path` from the local cache without touching the remote file. */
+  evict(path: string): Promise<void>;
+  /** Warm the cache for offline use. Already-cached paths are skipped. */
+  prefetch(paths: string[]): Promise<void>;
   delete(path: string): Promise<void>;
   exists(path: string): Promise<boolean>;
   head(path: string): Promise<Record<string, unknown>>;
@@ -557,55 +2053,240 @@ declare class BucketHandle {
   rename(sourcePath: string, targetPath: string): Promise<void>;
   list(prefix?: string): Promise<string[]>;
 }
-declare class SpookyClient<S extends SchemaStructure> {
+declare class Sp00kyClient<S extends SchemaStructure> {
   private config;
   private local;
   private remote;
+  private blobs;
+  private connectionSupervisor;
   private persistenceClient;
   private migrator;
   private cache;
   private dataModule;
   private sync;
   private devTools;
+  private crdtManager;
+  private featureFlags;
+  private appReleases;
+  private preloadedHashes;
+  private pendingQueryInits;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
-  get remoteClient(): Surreal;
-  get localClient(): Surreal;
+  private tabsCoordinator;
+  private sharedActive;
+  /** Current shared-tabs role, or null when the feature is off/fell back. */
+  get tabRole(): TabRole | null;
+  get remoteClient(): surrealdb0.Surreal;
+  get localClient(): unknown;
   get pendingMutationCount(): number;
+  /** 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;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
-  constructor(config: SpookyConfig<S>);
+  /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+  get syncHealth(): 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;
+  /** Durability of the local cache. See {@link StorageHealth}. `'unknown'` for
+   *  engines that don't report it. */
+  get storageHealth(): StorageHealth;
+  /**
+   * 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;
+  constructor(config: Sp00kyConfig<S>);
+  /** The shared-tabs role machinery, wired to this client's modules. */
+  private buildTabsCoordinator;
   /**
    * Setup direct callbacks instead of event subscriptions
    */
   private setupCallbacks;
   init(): Promise<void>;
+  private bucketSwitchChain;
+  private pendingBucketTarget;
+  /**
+   * 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;
+  /**
+   * 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 doSwitchBucket;
   close(): Promise<void>;
+  /**
+   * 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;
+  /**
+   * 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 Flags 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 Flags tab, or `spky flag`.
+   */
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
+  /** Drop every local feature flag override set via `setFeatureOverride`. */
+  clearFeatureOverrides(): void;
+  /** The local feature flag overrides currently in effect, keyed by flag. */
+  getFeatureOverrides(): Record<string, FeatureFlagOverride>;
+  /**
+   * 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;
   authenticate(token: string): Promise<surrealdb0.Tokens>;
+  /**
+   * 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`.
+   */
+  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void;
   deauthenticate(): Promise<void>;
-  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, SpookyQueryResultPromise>;
+  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
+  /**
+   * 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 finishQueryInit;
+  /**
+   * 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.
+   */
+  preload(finalQuery: FinalQuery<S, any, any, any, any, any>, options?: PreloadOptions): Promise<void>;
+  /**
+   * 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 fetchAndPersist;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
   }): Promise<() => void>;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
+  /** Cache-free handle. The blob cache reads the remote through this, so a
+   *  cache miss can't loop back into the cache. */
+  private rawBucket;
+  /** Blob cache counters for DevTools. */
+  getBlobCacheStats(): BlobCacheStats;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
   update(table: string, id: string, data: Record<string, unknown>, options?: UpdateOptions): Promise<{
     [x: string]: /*elided*/any;
   }>;
   delete(table: string, id: string): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
-  private persistClientId;
-  private loadOrGenerateClientId;
+  /**
+   * 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).
+   */
+  private fetchSessionId;
 }
 //#endregion
+//#region src/utils/semver.d.ts
+/** True when `a` is a valid version strictly greater than valid version `b`. */
+declare function semverGt(a: unknown, b: unknown): boolean;
+//#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+declare function textToHtml(text: string): string;
 /**
  * Helper for retrying DB operations with exponential backoff
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, DebounceOptions, EventSubscriptionOptions, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };