@spooky-sync/core 0.0.1-canary.26 → 0.0.1-canary.261

package/dist/index.d.ts

@@ -1,81 +1,411 @@
-import { C as Logger$1, S as UpdateOptions, T as EventSystem, _ as RunOptions, a as MutationEvent, b as SpookyQueryResultPromise, c as PinoTransmit, d as QueryHash, f as QueryState, g as RecordVersionDiff, h as RecordVersionArray, i as MutationCallback, l as QueryConfig, m as QueryUpdateCallback, n as EventSubscriptionOptions, o as MutationEventType, p as QueryTimeToLive, r as Level, s as PersistenceClient, t as DebounceOptions, u as QueryConfigRecord, v as SpookyConfig, w as EventDefinition, x as StoreType, y as SpookyQueryResult } from "./types.js";
+import { A as RunOptions, B as SyncHealthStatus, C as QueryTimeToLive, D as RecordVersionArray, E as ReconnectConfig, F as StorageHealth, G as DatabaseEventTypes, H as UpdateOptions, I as StorageHealthStatus, J as EventSystem, K as SealedQuery, L as StoreType, M as Sp00kyConfig, N as Sp00kyQueryResult, O as RecordVersionDiff, P as Sp00kyQueryResultPromise, R as SyncHealth, S as QueryStatusCallback, T as QueryUpdateCallback, U as LocalStore, V as TimingPhase, W as DatabaseEventSystem, _ as QueryConfig, a as Level, b as QueryState, c as MutationCallback, d as PersistenceClient, f as PhaseStat, g as QueryAuthorityCallback, h as PreloadRefresh, i as InlineRow, j as ServerViewMeta, k as RegistrationTimings, l as MutationEvent, m as PreloadOptions, n as DebounceOptions, o as MATERIALIZATION_SAMPLE_WINDOW, p as PinoTransmit, q as EventDefinition, r as EventSubscriptionOptions, s as MembershipOutcome, t as ConnectionState, u as MutationEventType, v as QueryConfigRecord, w as QueryTimings, x as QueryStatus, y as QueryHash, z as SyncHealthConfig } from "./types.js";
+import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RecordId, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
-import { Logger } from "pino";
+import { Duration, RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
+import { Level as Level$1, Logger } from "pino";
+import { decode, encode, isBlurhashValid } from "blurhash";
+import { LoroDoc } from "loro-crdt";
 
-//#region src/services/database/events/index.d.ts
-declare const DatabaseEventTypes: {
-  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
-  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
+//#region src/services/tabs/protocol.d.ts
+
+type TabId = string;
+type TabRole$1 = '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';
+}
+/** An optimistic write this follower committed to the SHARED store and
+ *  ingested into its own circuit. The leader ingests it (no DB write, the
+ *  row is already there) and fans it out to every OTHER follower as
+ *  `ingest-relay`, so a follower's write lands in every tab in one hop
+ *  instead of after the server round-trip. */ | {
+  type: 'ingest';
+  tuples: IngestTuple[];
 };
-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 LeaderToFollowerMessage = {
+  type: 'db-ready';
+  leadershipId: number;
+  bucketId: string;
+  storageHealth: StorageHealth;
+}
+/** 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;
+}
+/** The leader's drain pushed a mutation and deleted its outbox row from the
+ *  SHARED store. Every follower keeps the row in its overlay until its
+ *  `_00_list_ref` membership arrives. */ | {
+  type: 'mutation-settled';
+  mutationId: string;
+  recordId: string;
+  eventType: 'create' | 'update' | 'delete';
+}
+/** The leader's LIVE saw edges of these queries change; followers re-read
+ *  membership for the ones they hold. */ | {
+  type: 'membership-dirty';
+  hashes: string[];
+}
+/** The failed-writes tray changed size on the shared store. */ | {
+  type: 'failed-mutations-changed';
+  count: number;
 };
-type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
 //#endregion
-//#region src/utils/surql.d.ts
-interface SealedQuery<T = void> {
-  readonly sql: string;
-  readonly extract: (results: unknown[]) => T;
-}
+//#region src/services/logger/index.d.ts
+type Logger$1 = Logger;
 //#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
   protected client: Surreal;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
+  /**
+   * Per-query deadline in ms; `0` disables. The remote service sets it from
+   * `queryTimeoutMs` (see `RemoteDatabaseService`), the local one from
+   * `localOpTimeoutMs` (see `LocalDatabaseService`): a local query can be
+   * legitimately slow, but it must never be endless - every query waits on the
+   * previous link of {@link query}'s chain, and one that never settled wedged
+   * every later local op behind it.
+   */
+  protected queryTimeoutMs: number;
+  /** The error a deadline expiry rejects with; the local service substitutes
+   *  its typed `LocalOpTimeoutError`. "timed out" in the message is
+   *  load-bearing either way: `classifySyncError` keys off it. */
+  protected timeoutError(_query: string): Error;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
   constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
   getClient(): Surreal;
   getEvents(): DatabaseEventSystem;
   tx(): Promise<SurrealTransaction>;
-  private queryQueue;
   /**
-   * Execute a query with serialized execution to prevent WASM transaction issues.
+   * How many statements may be in flight at once.
+   *
+   * `1` serializes every statement behind the previous one. The local engines
+   * need that: overlapping ops trip the WASM / SQLite transaction layer. The
+   * remote service raises it (`RemoteDatabaseService`): a SurrealDB socket
+   * multiplexes requests by id, and serializing them capped the client at one
+   * statement per round trip (~5/s at 170ms RTT), so the `_00_list_ref` poll
+   * alone could hold every registration behind it and one slow one-shot read
+   * stalled the whole client. The scheduler's `MAX_CONCURRENT_DOWN` only means
+   * something when this is above 1.
+   */
+  protected maxConcurrentQueries: number;
+  private inFlightQueries;
+  private queryWaiters;
+  /** FIFO slot acquisition, so `maxConcurrentQueries = 1` keeps strict order. */
+  private acquireQuerySlot;
+  private releaseQuerySlot;
+  /**
+   * Hook run right before a statement is sent, inside its slot. The remote
+   * service uses it to hold statements while a connect is in flight, so a
+   * query never runs on a socket that is open but has not had its namespace
+   * and token applied yet. The default does nothing.
+   */
+  protected beforeQuery(): Promise<void>;
+  /**
+   * Execute a statement under {@link maxConcurrentQueries}.
+   *
+   * A statement that never settles would hold its slot forever, and with a
+   * limit of 1 that blocks every later statement behind it. {@link
+   * queryTimeoutMs} bounds each one: on expiry this promise rejects and the
+   * slot is released, 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>;
+  /**
+   * Like {@link query} but never rejects on a statement error: every
+   * statement answers on its own as `{ status: 'OK', result }` or
+   * `{ status: 'ERR', error }`. This is what lets a batched outbox push judge
+   * each mutation separately.
+   */
+  queryResponses(query: string, vars?: Record<string, unknown>): Promise<Array<{
+    status: 'OK';
+    result: unknown;
+  } | {
+    status: 'ERR';
+    error: string;
+  }>>;
+  private runStatement;
   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;
+  /**
+   * The token to re-authenticate a freshly opened socket with, kept current by
+   * {@link setAuthToken}.
+   *
+   * `config.token` is fixed at construction and most apps never set it: they
+   * sign in later, which authenticates the socket that happens to be open at
+   * the time. That is enough for the SDK's OWN reconnects (it replays
+   * `version`/`use`/`authenticate` itself), but not for the supervisor's revive
+   * loop, which builds a socket from scratch. Without this the revived socket
+   * came back UNAUTHENTICATED and stayed that way for the life of the page,
+   * while the client's `currentUserId` — restored from local storage — kept
+   * reporting the user as signed in.
+   *
+   * The visible damage is silent and total: `fn::query::register` sends
+   * `<string>($auth.id OR '')`, so every view registered afterwards is stamped
+   * with an empty identity, and every `$auth.id` predicate in it resolves
+   * false. Public tables keep returning rows while everything owned by the user
+   * returns nothing, on a page that still looks signed in.
+   */
+  private authToken;
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
+  /**
+   * Send one SurrealQL statement so that it survives the page going away.
+   *
+   * A WebSocket `send()` during `pagehide` is not guaranteed to flush — the
+   * browser may tear the socket down first, and the frame is simply lost.
+   * Measured: an unload-time release over the live socket reached the server
+   * zero times out of one. `fetch` with `keepalive` is the primitive the
+   * platform actually guarantees here, so this goes over SurrealDB's HTTP
+   * `/sql` endpoint instead of the RPC socket.
+   *
+   * Best-effort by design: no await, no retry, errors swallowed. Every caller
+   * must have a server-side fallback that makes a lost beacon a non-event.
+   */
+  beaconSql(sql: string): void;
+  /**
+   * Record the token every future connect should authenticate with, or `null`
+   * on sign-out. See {@link authToken}.
+   *
+   * Does not touch the CURRENT socket: callers authenticate that themselves
+   * (sign-in and session restore both already do). This only makes the next
+   * from-scratch connect reproduce that state.
+   */
+  setAuthToken(token: string | null): void;
+  /** 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>;
+  /**
+   * Hold statements while a connect is in flight.
+   *
+   * `connect()` opens the socket, then selects the namespace/database, then
+   * authenticates - three round trips. The SDK considers the connection ready
+   * after the first, so a query queued during the other two ran on a socket
+   * with no namespace ("Specify a namespace to use") or, worse, no identity.
+   * Seen 2026-09-06 after the supervisor rebuilt a socket: a collection
+   * recount failed with exactly that error. Waiting on the in-flight connect
+   * costs nothing when no connect is running; a failed connect is not
+   * swallowed here - the query then fails on its own, as before.
+   */
+  protected beforeQuery(): 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/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/services/database/local-migrator.d.ts
+declare class LocalMigrator {
+  private localDb;
+  private logger;
+  constructor(localDb: LocalStore, logger: Logger$1);
+  provision(schemaSurql: string): Promise<void>;
+  private isSchemaUpToDate;
+  private recreateDatabase;
+  private splitStatements;
+  private createHashRecord;
+}
+//#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
@@ -96,6 +426,33 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * Client-internal: not from the circuit. A membership-only change that
+   * needed no fetch is re-materialized through this same path so it cannot
+   * race a real update (DataModule.scheduleRematerialize). Carries the last
+   * known `localArray`; consumers that describe an INGEST (persist, metrics,
+   * devtools events) skip it.
+   */
+  synthetic?: boolean;
+  /**
+   * 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[]>;
@@ -107,34 +464,204 @@ type StreamProcessorEvents = {
 interface StreamUpdateReceiver {
   onStreamUpdate(update: StreamUpdate): void;
 }
+/** One row change in the shape `ingestMany` consumes. */
+interface IngestRecord {
+  table: string;
+  /** `MERGE` overlays the given fields on the stored row (projection widening). */
+  op: 'CREATE' | 'UPDATE' | 'DELETE' | 'MERGE';
+  id: string;
+  record: any;
+}
+/**
+ * What the boot-time prime needs from the client: which tables to walk, how
+ * to recognise a snapshot written under a different schema, and which rows'
+ * local `_00_rv` must not be reported as the server's.
+ */
+interface CircuitPrimeContext {
+  tables: string[];
+  schemaHash: string;
+  /** Encoded ids with an unsettled local mutation (their `_00_rv` was bumped
+   *  locally and may exceed the server's next version). */
+  pendingIds: Set<string>;
+  /** Receives every `(id, rv)` the prime put into the circuit, per table, so
+   *  the sync layer can skip re-downloading bodies it already has. */
+  onVersions?: (table: string, entries: [string, number][]) => void;
+}
+/** Storage key of the circuit snapshot inside the local store. */
+
 declare class StreamProcessorService {
   events: EventSystem<StreamProcessorEvents>;
   private db;
-  private persistenceClient;
   private logger;
   private processor;
   private isInitialized;
   private receivers;
-  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
+  private batching;
+  private batchBuffer;
+  private sessionAuth;
+  private stateGeneration;
+  private persistState;
+  private persistCircuit;
+  private checkpointMs;
+  private checkpointTimer;
+  private snapshotDirty;
+  private dirtyRows;
+  private hideHandler;
+  private checkpointInFlight;
+  private projection;
+  private primed;
+  private schemaHash;
+  private widenQueue;
+  private widenPending;
+  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, 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, firing one coalesced `StreamUpdate` per
+   * affected query once every record has been ingested. Use this whenever
+   * multiple records land at once (sync fetching N rows, the boot prime).
+   *
+   * The batch is fed to the wasm side in chunks of {@link INGEST_CHUNK}: one
+   * circuit step per chunk (a step walks every registered view, so per-record
+   * ingest paid that fixed cost N times), but never the whole batch at once,
+   * because the wasm side has to hold every parsed row of a call at the same
+   * time and wasm32 dlmalloc never returns that peak.
+   *
+   * Returns the records that were ingested. A chunk that fails is reported
+   * and skipped, not retried (a retry would double-apply whatever the failed
+   * step already committed), and the remaining chunks still run.
+   */
+  ingestMany(records: IngestRecord[]): IngestRecord[];
+  /**
+   * 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>;
-  loadState(): Promise<void>;
-  saveState(): Promise<void>;
+  /**
+   * 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 loads nothing: the snapshot in the store being swapped away
+   * from belongs to the previous bucket; the caller primes the new bucket's
+   * circuit (`primeFromLocal`) once its store is open, and 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;
+  /**
+   * Snapshot persistence (`persistCircuit`). When on, the circuit's store is
+   * written to the local store on a checkpoint interval and when the page
+   * goes hidden, and restored by {@link primeFromLocal} on the next boot.
+   */
+  configureCircuitPersistence(enabled: boolean, checkpointMs?: number): void;
+  /**
+   * Field projection (`circuitProjection`, default on). Takes effect on the
+   * next processor (`init`/`reset`) and on rows written after that.
+   */
+  configureProjection(enabled: boolean): void;
+  private applyProjection;
+  /** Resolves once the boot-time prime has finished (or was skipped). */
+  whenPrimed(): Promise<void>;
+  /**
+   * Fill the circuit from the LOCAL store, in the background.
+   *
+   * With a usable snapshot: install it under whatever views have registered
+   * meanwhile (`load_store_state` re-primes them), then `reconcile` each table
+   * against the store's `(id, rv)` list so rows deleted since the checkpoint
+   * are stepped out and only rows added or changed since are read back and
+   * ingested. Without one: read every row and ingest it, chunked.
+   *
+   * Either way the circuit ends up equal to the local store without touching
+   * the network, so the first sync diff is a real delta rather than "fetch
+   * everything". The returned promise never rejects; `whenPrimed` gates on it.
+   */
+  primeFromLocal(ctx: CircuitPrimeContext): Promise<void>;
+  private runPrime;
+  /** Publish wasm updates produced outside an ingest (restore, reconcile). */
+  private dispatchWasmUpdates;
+  /**
+   * Record that the circuit changed by `rows` rows. Cheap; the snapshot is
+   * deferred to the checkpoint timer and skipped entirely when `persistCircuit`
+   * is off.
+   */
+  private markSnapshotDirty;
+  private startCheckpoints;
+  /** Stop checkpointing and drop the visibility listeners. */
+  stopCheckpoints(): void;
+  /**
+   * Write the circuit's store to the local store as a snapshot. Compacts the
+   * row arena first when dead bytes outweigh live ones. Serialised: a second
+   * call while one is in flight joins it. No-op unless persistence is on, this
+   * tab owns the store, and the engine can hold a snapshot.
+   */
+  checkpoint(reason?: string): Promise<void>;
+  private runCheckpoint;
+  /**
+   * Projection widening: a newly registered view evaluates fields that rows
+   * already in the circuit were stored without. Merge just those fields in,
+   * table by table, from the local store. The view registered against what
+   * was present and converges as the merges step through.
+   */
+  private scheduleWiden;
+  private runWiden;
+  /**
+   * 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;
   /**
    * Ingest a record change into the processor.
    * Emits 'stream_update' event if materialized views are affected.
    * @param isOptimistic true = local mutation (increment versions), false = remote sync (keep versions)
    */
-  ingest(table: string, op: 'CREATE' | 'UPDATE' | 'DELETE', id: string, record: any): WasmStreamUpdate[];
+  ingest(table: string, op: IngestRecord['op'], id: string, record: any): WasmStreamUpdate[];
   /**
    * Register a new query plan.
    * Emits 'stream_update' with the initial result.
@@ -147,17 +674,120 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
+//#region src/modules/auth/impersonation.d.ts
+/**
+ * Admin impersonation, client side.
+ *
+ * The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+ * an admin calls `fn::_00_impersonate::start`, receives a token for the
+ * `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+ * the target user. Everything here is state and timers around that:
+ *
+ * - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+ *   reload in between) can return to it;
+ * - the impersonation state is derived from the token's claims, never stored
+ *   separately, so it cannot disagree with the session actually in use;
+ * - the token is re-signed before it expires, and the session is polled so a
+ *   stop or revocation made elsewhere reaches an open WebSocket quickly.
+ */
+/** Access method impersonation tokens are issued for. */
+declare const IMPERSONATION_ACCESS = "_00_impersonate";
+/** Persistence key holding the admin's own token while impersonating. */
+declare const ORIGIN_TOKEN_KEY = "sp00ky_auth_token_origin";
+/** How often an active impersonation re-checks its session on the server. */
+declare const SESSION_POLL_MS = 60000;
+interface ImpersonationInfo {
+  /** `_00_impersonation:<id>` the session is bound to. */
+  session: string;
+  /** Record id being impersonated. */
+  target: string;
+  /** Record id of the admin. */
+  admin: string;
+  /** When the current token expires (it is renewed before then). */
+  tokenExpiresAt: Date | null;
+}
+interface TokenClaims {
+  access: string | null;
+  userId: string | null;
+  exp: number | null;
+  impersonation: {
+    session: string;
+    admin: string;
+  } | null;
+}
+/**
+ * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+ * server still enforces the token on every request; this is only so the client
+ * can act on what it already holds before a round trip completes.
+ *
+ * Returns nulls on any malformed input.
+ */
+declare function decodeTokenClaims(token: string): TokenClaims;
+/** The impersonation a token represents, or null for a regular session. */
+declare function impersonationFromToken(token: string | null): ImpersonationInfo | null;
+/** Same impersonation, for change detection (renewals only move the expiry). */
+declare function sameImpersonation(a: ImpersonationInfo | null, b: ImpersonationInfo | null): boolean;
+/**
+ * When to renew a token expiring at `expSecs`: at 80% of its remaining life,
+ * never sooner than 5s from now, and immediately once it is inside that.
+ */
+declare function renewDelayMs(expSecs: number, nowMs: number): number;
+interface ImpersonationTimerHost {
+  /** Current impersonation, or null. */
+  current(): ImpersonationInfo | null;
+  /** Re-sign the token. Rejects when the session has ended. */
+  renew(): Promise<void>;
+  /** Whether the server still considers the session live. */
+  stillActive(): Promise<boolean>;
+  /** Leave the impersonation because the server ended it. */
+  endedRemotely(reason: string): Promise<void>;
+  /** Whether a failure was a reachability problem (retry) rather than an answer. */
+  isNetworkError(error: unknown): boolean;
+}
+/**
+ * The two timers an active impersonation needs. `sync()` is called whenever
+ * the auth state changes and arms or clears them to match.
+ */
+declare class ImpersonationTimers {
+  private host;
+  private renewTimer;
+  private pollTimer;
+  private armedFor;
+  constructor(host: ImpersonationTimerHost);
+  sync(): void;
+  clear(): void;
+  private renew;
+  private poll;
+}
+//#endregion
 //#region src/modules/auth/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
+  readonly ImpersonationChanged: "IMPERSONATION_CHANGED";
 };
 type AuthEventTypeMap = {
   [AuthEventTypes.AuthStateChanged]: EventDefinition<typeof AuthEventTypes.AuthStateChanged, string | null>;
+  [AuthEventTypes.ImpersonationChanged]: EventDefinition<typeof AuthEventTypes.ImpersonationChanged, ImpersonationInfo | null>;
 };
 type AuthEventSystem = EventSystem<AuthEventTypeMap>;
 declare function createAuthEventSystem(): AuthEventSystem;
 //#endregion
 //#region src/modules/auth/index.d.ts
+/** What `fn::_00_impersonate::list_users` returns per row. */
+interface ImpersonationCandidate {
+  id: string;
+  is_admin: boolean;
+  [field: string]: unknown;
+}
+/** An open session, as `fn::_00_impersonate::active` lists it. */
+interface ActiveImpersonation {
+  session: string;
+  target: string;
+  admin: string;
+  reason: string;
+  started_at: unknown;
+  expires_at: unknown;
+}
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 type MapColumnType<T extends ColumnSchema> = T['optional'] extends true ? TypeNameToTypeMap[T['type']] | undefined : TypeNameToTypeMap[T['type']];
 type ExtractAccessParams<S extends SchemaStructure, Name extends keyof S['access'], Method extends 'signIn' | 'signup'> = S['access'] extends undefined ? never : S['access'][Name] extends AccessDefinition ? Prettify<{ [K in keyof S['access'][Name][Method]['params']]: MapColumnType<S['access'][Name][Method]['params'][K]> }> : never;
@@ -169,8 +799,21 @@ 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;
+  /** The impersonation last announced, for change detection. */
+  private announcedImpersonation;
+  /** Target of an impersonation that just ended, until the client purges its
+   *  local bucket (see `consumeEndedImpersonation`). */
+  private endedImpersonationTarget;
+  private impersonationTimers;
   get eventSystem(): AuthEventSystem;
   constructor(schema: S, remote: RemoteDatabaseService, persistenceClient: PersistenceClient, logger: Logger$1);
   init(): Promise<void>;
@@ -181,26 +824,1559 @@ declare class AuthService<S extends SchemaStructure> {
    */
   subscribe(cb: (userId: string | null) => void): () => void;
   private notifyListeners;
+  /**
+   * The impersonation the current session is, or null. Derived from the
+   * token in use, so it always describes the identity the server sees.
+   */
+  get impersonation(): ImpersonationInfo | null;
+  /** Subscribe to impersonation changes; called immediately with the current value. */
+  subscribeImpersonation(cb: (info: ImpersonationInfo | null) => void): () => void;
+  /**
+   * Act as `targetId` (a record id such as `user:abc`). Admins only, and only
+   * when the project enabled `impersonation` in sp00ky.yml: the server refuses
+   * everything else. `reason` is recorded in the audit log.
+   *
+   * The admin's session is kept aside and restored by
+   * {@link stopImpersonating}. Local data switches to the target's bucket
+   * exactly as on a sign-in, and that bucket is removed on stop.
+   */
+  impersonate(targetId: string, reason: string): Promise<ImpersonationInfo>;
+  /**
+   * Return to the admin session. Always leaves the impersonated identity,
+   * even when the server cannot be reached: the admin token is restored
+   * locally first and verified afterwards, and a rejected admin token ends in
+   * a full sign-out rather than staying on the target.
+   */
+  stopImpersonating(opts?: {
+    serverEnded?: boolean;
+  }): Promise<void>;
+  /** Re-sign the impersonation token before it expires. */
+  renewImpersonation(): Promise<void>;
+  /** Users an admin may pick from. Admin-only on the server. */
+  searchImpersonationTargets(search: string): Promise<ImpersonationCandidate[]>;
+  /** Open impersonation sessions. Admin-only on the server. */
+  listActiveImpersonations(): Promise<ActiveImpersonation[]>;
+  /**
+   * The target of an impersonation that ended, once. The bucket switch calls
+   * this after leaving a bucket so it can delete that user's local data.
+   */
+  consumeEndedImpersonation(): string | null;
+  /**
+   * Restore a session from the locally cached JWT, with NO network.
+   *
+   * This is what makes a warm boot paint instantly and what makes an offline
+   * boot possible at all: the token is in local storage, and it already carries
+   * both the access method and the `$auth.id` record id. Everything the client
+   * needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+   * permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+   * available before a socket exists.
+   *
+   * The session is OPTIMISTIC: the token is unverified here. `check()` runs
+   * afterwards in the background and downgrades to a real sign-out if the
+   * server rejects it. Nothing is trusted that the server has not also seen -
+   * the local store only ever holds rows the server previously sent.
+   *
+   * Returns the restored user id, or null when there is no usable token.
+   */
+  restoreSessionFromToken(): Promise<string | null>;
   /**
    * Check for existing session and validate
    */
   check(accessToken?: string): Promise<void>;
   /**
-   * Sign out and clear session
+   * The server refused `token`. A refused impersonation token (stopped,
+   * expired, or revoked) returns to the admin session instead of signing the
+   * admin out; anything else signs out.
+   */
+  private rejectToken;
+  /**
+   * Sign out and clear session. While impersonating this ends the
+   * impersonation and signs the admin out too.
    */
   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;
+}
+/** The slice of the query engine this module drives: register a live query
+ *  locally, ask for its remote registration, subscribe to its rows. */
+interface LiveQueryPort$1 {
+  query(table: string, surql: string, params: Record<string, unknown>, ttl: QueryTimeToLive): Promise<string>;
+  subscribe(hash: string, cb: (records: Record<string, any>[]) => void, options?: {
+    immediate?: boolean;
+  }): () => void;
+}
+interface RemoteRegisterPort$1 {
+  enqueueDownEvent(event: {
+    type: 'register';
+    payload: {
+      hash: string;
+    };
+  }): void;
+}
+interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: LiveQueryPort$1;
+  sync: RemoteRegisterPort$1;
+  auth: Pick<AuthService<S>, 'subscribe'>;
+  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;
+}
+/** The slice of the query engine this module drives: register a live query
+ *  locally, ask for its remote registration, subscribe to its rows. */
+interface LiveQueryPort {
+  query(table: string, surql: string, params: Record<string, unknown>, ttl: QueryTimeToLive): Promise<string>;
+  subscribe(hash: string, cb: (records: Record<string, any>[]) => void, options?: {
+    immediate?: boolean;
+  }): () => void;
+}
+interface RemoteRegisterPort {
+  enqueueDownEvent(event: {
+    type: 'register';
+    payload: {
+      hash: string;
+    };
+  }): void;
+}
+interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: LiveQueryPort;
+  sync: RemoteRegisterPort;
+  auth: Pick<AuthService<S>, 'subscribe'>;
+  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/kernel/events.d.ts
+/**
+ * Inbound events. Everything that can start a saga arrives as one of these
+ * through the runtime router: public API calls, adapter callbacks, timers,
+ * and `dispatch` effects from other sagas.
+ */
+type RuntimeEvent = {
+  type: 'EnsureRegistered';
+  requireAuth?: boolean;
+  attempt?: number;
+} | {
+  type: 'RegisterRemote';
+  hash: QueryHash;
+  retry?: boolean;
+} | {
+  type: 'SyncOutcome';
+  ok: boolean;
+  error?: unknown;
+} | {
+  type: 'AckPrune';
+} | {
+  type: 'ReadDirtyMembership';
+} | {
+  type: 'RecoverLostView';
+  hash: QueryHash;
+} | {
+  type: 'ReadMembership';
+  hashes: QueryHash[];
+} | {
+  type: 'FetchRows';
+} | {
+  type: 'Materialize';
+  hash: QueryHash;
+} | {
+  type: 'MaterializeDirty';
+} | {
+  type: 'LifecycleTick';
+} | {
+  type: 'GcTick';
+} | {
+  type: 'Drain';
+} | {
+  type: 'FlushWrite';
+  key: string;
+} | {
+  type: 'PollTick';
+} | {
+  type: 'SelfHealTick';
+} | {
+  type: 'HeartbeatNow';
+} | {
+  type: 'StartRemote';
+} | {
+  type: 'PrimeCircuit';
+} | {
+  type: 'VersionsPrimed';
+  entries: Array<readonly [string, number]>;
+} | {
+  type: 'WarmBlobs';
+} | {
+  type: 'AuthFlip';
+  userId: string | null;
+} | {
+  type: 'BucketSwitch';
+  target: string;
+} | {
+  type: 'PageHide';
+} | {
+  type: 'ConnectionChanged';
+  state: ConnectionState;
+} | {
+  type: 'StreamUpdate';
+  update: StreamUpdate;
+} | {
+  type: 'LiveStart';
+} | {
+  type: 'LiveChange';
+  hashes: QueryHash[];
+  rows?: InlineRow[];
+} | {
+  type: 'TabRole';
+  role: 'solo' | 'leader' | 'follower';
+} | {
+  type: 'TabMessage';
+  message: unknown;
+};
+type OutEvent = {
+  type: 'query:records';
+  hash: QueryHash;
+  records: ReadonlyArray<Record<string, unknown>>;
+} | {
+  type: 'query:status';
+  hash: QueryHash;
+  status: QueryStatus;
+} | {
+  type: 'query:authority';
+  hash: QueryHash;
+  known: boolean;
+} | {
+  type: 'query:view-lost';
+  hash: QueryHash;
+} | {
+  type: 'query:evicted';
+  hash: QueryHash;
+} | {
+  type: 'mutation:event';
+  event: unknown;
+} | {
+  type: 'mutation:settled';
+  mutationId: string;
+  recordId: string;
+  eventType: string;
+} | {
+  type: 'mutation:rolled-back';
+  mutationId: string;
+  recordId: string;
+  eventType: string;
+  error: string;
+} | {
+  type: 'tray:changed';
+  count: number;
+} | {
+  type: 'health:changed';
+  health: SyncHealth;
+} | {
+  type: 'activity:changed';
+  fetching: number;
+  pending: number;
+} | {
+  type: 'tabs:broadcast';
+  message: unknown;
+} | {
+  type: 'tabs:sendTo';
+  tabId: string;
+  message: unknown;
+} | {
+  type: 'devtools';
+  name: string;
+  data?: unknown;
+} | {
+  type: 'log';
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  data?: unknown;
+};
+//#endregion
+//#region src/state/lifecycle.d.ts
+/**
+ * The query lifecycle as one explicit machine.
+ *
+ * `phase` answers "where do this query's rows come from":
+ * - `cold`      never resolved on this device: rows come from a local
+ *               predicate scan (or the SSP local window), bindings show a loader.
+ * - `cached`    a durable `_00_view` row was found: rows come from that id-set.
+ * - `live`      a server membership set was accepted this session.
+ * - `view-lost` the server's `_00_query` row vanished while we held
+ *               membership; rows are kept, a re-registration is under way.
+ *
+ * `remote` tracks the server-side registration, `fetchDepth` is the refcount
+ * behind `status: 'fetching'`, `notified` says whether subscribers received
+ * at least one materialization this registration.
+ */
+type QueryPhase = 'cold' | 'cached' | 'live' | 'view-lost';
+type RemotePhase = 'unregistered' | 'registering' | 'registered' | 'failed';
+interface QueryLifecycle {
+  readonly phase: QueryPhase;
+  readonly remote: RemotePhase;
+  readonly fetchDepth: number;
+  readonly notified: boolean;
+}
+//#endregion
+//#region src/kernel/effects.d.ts
+type Vars = Record<string, unknown>;
+/** What the in-browser SSP needs to build a local view. */
+interface RegisterPlan {
+  queryHash: string;
+  surql: string;
+  params: Vars;
+  ttl: string;
+  tableName: string;
+  involvedTables?: string[];
+}
+/** One statement's outcome of a multi-statement remote request. */
+type StatementResult = {
+  status: 'OK';
+  result: unknown;
+} | {
+  status: 'ERR';
+  error: string;
+};
+/** One entry of an `all` fan-out result (allSettled semantics). */
+
+/**
+ * Effects are data. A saga yields one and gets its result back on the next
+ * `next()`; the interpreter (client/runtime) is the only place they execute.
+ */
+type Effect = {
+  kind: 'local.query';
+  sql: string;
+  vars?: Vars;
+  epoch?: number;
+} | {
+  kind: 'local.select';
+  plan: QueryPlan;
+  params?: Vars;
+} | {
+  kind: 'local.execute';
+  query: SealedQuery<unknown>;
+  vars?: Vars;
+  epoch?: number;
+} | {
+  kind: 'local.getById';
+  table: string;
+  id: unknown;
+} | {
+  kind: 'local.upsert';
+  table: string;
+  id: unknown;
+  data: Record<string, unknown>;
+  mode: 'replace' | 'merge';
+} | {
+  kind: 'local.delete';
+  table: string;
+  id: unknown;
+} | {
+  kind: 'local.epoch';
+} | {
+  kind: 'remote.query';
+  sql: string;
+  vars?: Vars;
+  timeoutMs?: number;
+} | {
+  kind: 'remote.live';
+  table: string;
+} | {
+  kind: 'remote.kill';
+  uuid: string;
+} | {
+  kind: 'ssp.register';
+  plan: RegisterPlan;
+} | {
+  kind: 'ssp.unregister';
+  hash: string;
+} | {
+  kind: 'ssp.ingest';
+  records: IngestRecord[];
+} | {
+  kind: 'timer.set';
+  key: string;
+  ms: number;
+  event: RuntimeEvent;
+} | {
+  kind: 'timer.clear';
+  key: string;
+} | {
+  kind: 'state.read';
+  select: (s: ClientState) => unknown;
+} | {
+  kind: 'state.update';
+  fn: (s: ClientState) => ClientState;
+} | {
+  kind: 'state.wait';
+  until: (s: ClientState) => boolean;
+} | {
+  kind: 'now';
+} | {
+  kind: 'id';
+  scope: 'mutation' | 'salt';
+} | {
+  kind: 'hash';
+  input: string;
+} | {
+  kind: 'emit';
+  event: OutEvent;
+} | {
+  kind: 'dispatch';
+  event: RuntimeEvent;
+} | {
+  kind: 'all';
+  effects: Effect[];
+} | {
+  kind: 'service';
+  name: ServiceName;
+  args: unknown[];
+};
+/**
+ * Calls into the legacy services that are adapters, not state: auth, tabs,
+ * blobs, migrator, crdt, persistence, the SSP lifecycle, the remote socket.
+ * A saga names the call; the runtime binds it to the real service.
+ */
+interface ServiceCalls {
+  'hint.read': () => string | null;
+  'hint.write': (bucketId: string) => void;
+  'local.connect': (bucketId: string) => Promise<void>;
+  'local.switchStore': (bucketId: string) => Promise<void>;
+  'local.beginSwitch': () => () => void;
+  'local.currentBucketId': () => string;
+  'local.usesSurqlSchema': () => boolean;
+  'local.dropBucket': (bucketId: string) => Promise<void>;
+  'migrator.provision': () => Promise<void>;
+  'blobs.start': (bucketId: string) => Promise<void>;
+  'blobs.setNamespace': (bucketId: string) => Promise<void>;
+  'blobs.clear': () => Promise<void>;
+  'ssp.init': () => Promise<void>;
+  'ssp.setPermissions': () => void;
+  'ssp.setSessionAuth': (authId: string | null, access: string | null) => void;
+  'ssp.prime': (pendingIds: string[]) => Promise<void>;
+  'ssp.reset': () => Promise<void>;
+  'ssp.setPersistence': (enabled: boolean) => void;
+  'auth.restoreSession': () => Promise<string | null>;
+  'auth.init': () => Promise<void>;
+  'auth.sessionAuthId': () => string | null;
+  'auth.access': () => string | null;
+  'auth.token': () => string | null;
+  'auth.currentUser': () => Record<string, unknown> | null;
+  'auth.consumeEndedImpersonation': () => string | null;
+  'remote.connect': () => Promise<void>;
+  'remote.releaseViews': (ids: unknown[]) => void;
+  'supervisor.start': () => void;
+  'tabs.start': (bucketId: string) => Promise<'solo' | 'leader' | 'follower'>;
+  'tabs.moveToBucket': (bucketId: string) => Promise<'solo' | 'leader' | 'follower'>;
+  'crdt.setSessionId': (sessionId: string) => void;
+  'crdt.closeAll': (flush: boolean) => void;
+  'persistence.set': (key: string, value: unknown) => Promise<void>;
+  'features.init': () => void;
+  'releases.init': () => void;
+  'window.attach': () => void;
+}
+type ServiceName = keyof ServiceCalls;
+/** Typed constructors. Each is one line so the saga reads like the plan. */
+//#endregion
+//#region src/kernel/saga.d.ts
+/**
+ * A saga is a generator that yields effects and receives their results. It
+ * holds no references to adapters or state, so it can be driven by the real
+ * interpreter or by `testing/run-pure` with canned results.
+ */
+type Saga<R> = Generator<Effect, R, any>;
+/**
+ * Lanes bound concurrency without a queue object per lane:
+ * - `serial`: runs strictly one at a time per key, in arrival order.
+ * - `dedupe`: a request while one run is active joins that run instead of
+ *   starting another.
+ * The bookkeeping is a pure value so the policy is unit-testable; the runtime
+ * owns the promises.
+ */
+type Lane = {
+  kind: 'serial';
+  key: string;
+} | {
+  kind: 'dedupe';
+  key: string;
+};
+interface LaneState {
+  readonly running: ReadonlySet<string>;
+  readonly waiting: ReadonlyMap<string, number>;
+}
+//#endregion
+//#region src/state/client-state.d.ts
+type Row = Record<string, unknown>;
+/** Everything a query is, minus anything that changes after registration. */
+interface QueryDefinition {
+  /** Session-salted `_00_query:<hash>` record id: the remote view id. */
+  readonly id: RecordId<string>;
+  readonly hash: QueryHash;
+  /** Unsalted `sha256({surql, params})`: key of the durable `_00_view` row. */
+  readonly viewKey: string;
+  readonly surql: string;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly plan?: QueryPlan;
+  readonly ttl: QueryTimeToLive;
+  readonly ttlMs: number;
+  readonly tableName: string;
+  readonly createdAt: number;
+}
+type ServerViewState = 'materializing' | 'ready' | null;
+interface QueryTelemetry {
+  readonly updateCount: number;
+  readonly errorCount: number;
+  readonly lastUpdatedAt: number | null;
+  readonly materializationSamples: ReadonlyArray<number>;
+  readonly lastIngestLatencyMs: number | null;
+  readonly phaseSamples: Readonly<Record<string, ReadonlyArray<number>>>;
+  readonly phaseLast: Readonly<Record<string, number | null>>;
+  readonly registrationTimings: RegistrationTimings;
+}
+interface QueryEntry {
+  readonly def: QueryDefinition;
+  readonly lifecycle: QueryLifecycle;
+  /** Server membership (ids + versions) or the durable seed. */
+  readonly remoteArray: RecordVersionArray;
+  /** The in-browser SSP view's id-set: local truth for "does this row match". */
+  readonly localArray: RecordVersionArray;
+  readonly subqueryRemoteArray: RecordVersionArray;
+  readonly records: ReadonlyArray<Row>;
+  readonly serverState: ServerViewState;
+  readonly subscribers: number;
+  readonly lastSubscriberLeftAt: number | null;
+  readonly lastHeartbeatAt: number | null;
+  readonly lastPolledAt: number | null;
+  readonly registerAttempts: number;
+  /**
+   * Re-registrations issued because the `_00_query` row read as gone, since
+   * the row was last seen. Paces the next one (see `applyMembership`).
+   */
+  readonly viewLostCount: number;
+  /** When the paced re-registration is due; null when none is pending. */
+  readonly viewLostRetryAt: number | null;
+  readonly telemetry: QueryTelemetry;
+}
+type OutboxStatus = 'pending' | 'acked';
+/** In-memory mirror of one `_00_pending_mutations` row plus its push progress. */
+interface OutboxItem {
+  readonly id: string;
+  readonly type: MutationEventType;
+  readonly recordId: string;
+  readonly table: string;
+  readonly status: OutboxStatus;
+  readonly ackedAt: number | null;
+  readonly attempts: number;
+}
+type TabRole = 'solo' | 'leader' | 'follower';
+/** A debounced update accumulating locally until its flush writes the outbox row. */
+interface PendingWrite {
+  readonly key: string;
+  readonly table: string;
+  readonly recordId: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly before: Readonly<Record<string, unknown>> | null;
+  readonly firstAt: number;
+}
+interface SyncSlice {
+  readonly health: SyncHealth;
+  readonly consecutiveFailures: number;
+  readonly hasSyncedOnce: boolean;
+  readonly selfHealAttempts: number;
+  readonly pollIdleStreak: number;
+  readonly lastReconnectRefetchAt: number | null;
+  readonly needsResubscribe: boolean;
+  readonly fetchAttempts: number;
+  readonly liveUuid: string | null;
+  readonly liveTable: string | null;
+  readonly lanes: LaneState;
+}
+interface ClientState {
+  readonly sessionId: string | null;
+  readonly userId: string | null;
+  /** The principal the current session salt was minted for. */
+  readonly saltUserId: string | null;
+  /** Latest bucket-switch target; an older switch that wakes up to a newer target skips. */
+  readonly pendingBucket: string | null;
+  readonly tabId: string;
+  readonly tabRole: TabRole;
+  readonly bucketId: string | null;
+  readonly localReady: boolean;
+  readonly primed: boolean;
+  readonly queries: ReadonlyMap<QueryHash, QueryEntry>;
+  /** Hashes whose local registration is in flight (dedupes concurrent `query()` calls). */
+  readonly registering: ReadonlySet<QueryHash>;
+  /** Re-read attempts per hash while the server reports a view as `materializing`. */
+  readonly membershipReread: ReadonlyMap<QueryHash, number>;
+  /** Local body versions (`_00_rv`) by encoded record id. */
+  readonly versions: ReadonlyMap<string, number>;
+  readonly outbox: ReadonlyArray<OutboxItem>;
+  readonly pendingWrites: ReadonlyMap<string, PendingWrite>;
+  readonly failedCount: number;
+  /** Queries whose render inputs changed since their last materialization. */
+  readonly dirty: ReadonlySet<QueryHash>;
+  /** Queries whose server membership must be re-read. */
+  readonly membershipDirty: ReadonlySet<QueryHash>;
+  readonly sync: SyncSlice;
+}
+//#endregion
+//#region src/modules/ref-tables.d.ts
+type RefMode = 'single' | 'dedicated';
+/**
+ * Sentinel user id for unauthenticated clients when anonymous live queries are
+ * enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+ * so it can never collide with a real user id (those arrive as `user:<id>`);
+ * both sides resolve it to the shared `_00_list_ref_anon` table.
+ */
+//#endregion
+//#region src/query/env.d.ts
+/**
+ * Static configuration the sagas read. Plain data, built once by the runtime
+ * from `Sp00kyConfig`; sagas never see the config object itself.
+ */
+interface SagaEnv {
+  readonly schema: SchemaStructure;
+  readonly refMode: RefMode;
+  readonly anonLive: boolean;
+  readonly remoteTimeoutMs: number;
+  readonly pushTimeoutMs: number;
+  readonly outboxBatchSize: number;
+  readonly degradeAfter: number;
+  readonly materializeDebounceMs: number;
+  readonly pollBaseMs: number;
+  readonly defaultTtlMs: number;
+}
+//#endregion
+//#region src/mutation/rows.d.ts
+interface FailedMutationRow {
+  id: string;
+  mutationType: MutationEventType;
+  recordId: string;
+  tableName: string;
+  data?: Record<string, unknown>;
+  beforeRecord?: Record<string, unknown> | null;
+  error: {
+    message: string;
+    kind: 'application' | 'unreplayable';
+  };
+  attempts: number;
+  createdAt: number;
+  failedAt: number;
+  revert: 'full' | 'partial' | 'none';
+}
+/**
+ * Parse a record id READ BACK FROM THE STORE, stripping SurrealDB's `⟨⟩`
+ * escaping (outbox ids contain `_`, so they come back escaped).
+ */
+//#endregion
+//#region src/kernel/interpreter.d.ts
+/** The five adapters plus the pure ports, as the interpreter sees them. */
+interface Adapters {
+  local: Pick<LocalStore, 'query' | 'execute' | 'select' | 'getById' | 'upsert' | 'delete'> & {
+    readonly epoch: number;
+  };
+  remote: {
+    queryResponses(sql: string, vars?: Record<string, unknown>): Promise<StatementResult[]>;
+    /**
+     * Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the
+     * changed query hashes, plus the changed rows themselves when the
+     * subscription was opened with the body joined on (`liveInlineBodies`).
+     */
+    live(table: string, onChange: (hashes: string[], rows?: InlineRow[]) => void): Promise<string>;
+    kill(uuid: string): Promise<void>;
+  };
+  ssp: {
+    registerQueryPlan(plan: {
+      queryHash: string;
+      surql: string;
+      params: Record<string, unknown>;
+      ttl: Duration;
+      lastActiveAt: Date;
+      localArray: [];
+      remoteArray: [];
+      meta: {
+        tableName: string;
+        involvedTables?: string[];
+      };
+    }): StreamUpdate | undefined;
+    unregisterQueryPlan(hash: string): void;
+    ingestMany(records: IngestRecord[]): unknown;
+  };
+  timers: {
+    set(key: string, ms: number, fire: () => void): void;
+    clear(key: string): void;
+  };
+  clock: {
+    now(): number;
+  };
+  ids: {
+    mutation(): string;
+    salt(): string;
+  };
+  hash(input: string): Promise<string>;
+  services: ServiceCalls;
+}
+/** What the interpreter needs from the runtime: state, waiting, emitting, dispatching. */
+//#endregion
+//#region src/client/runtime.d.ts
+interface RuntimeOptions {
+  env: SagaEnv;
+  adapters: Adapters;
+  logger: Logger$1;
+  tabId: string;
+  initialState?: ClientState;
+}
+/**
+ * The one effectful object of the engine: holds the state, runs sagas on
+ * lanes, fires timers, fans events out to subscribers and schedules
+ * materialization for dirty queries. No decision logic lives here.
+ */
+declare class Runtime {
+  private stateValue;
+  private readonly interpret;
+  private readonly env;
+  private readonly adapters;
+  private readonly logger;
+  private readonly serialLanes;
+  private readonly dedupeLanes;
+  private readonly waiters;
+  private readonly recordSubs;
+  private readonly statusSubs;
+  private readonly authoritySubs;
+  private readonly lastStatus;
+  private readonly listeners;
+  private readonly scheduledMaterialize;
+  private readonly timerKeys;
+  private lastActivity;
+  private lastHealth;
+  private disposed;
+  constructor(opts: RuntimeOptions);
+  get state(): ClientState;
+  /** Run a saga, optionally on a lane. Rejections propagate to the caller. */
+  run<R>(saga: Saga<R>, opts?: {
+    lane?: Lane;
+    signal?: AbortSignal;
+  }): Promise<R>;
+  /** Route an event to its saga. Never rejects: failures are logged. */
+  dispatch(event: RuntimeEvent): Promise<void>;
+  private setState;
+  waitFor(until: (s: ClientState) => boolean, signal?: AbortSignal): Promise<void>;
+  /** Deliver an outbound event to its subscribers and listeners. */
+  emit(event: OutEvent): void;
+  private notify;
+  private safely;
+  /** Observe outbound events by type (`'*'` for all). */
+  on(type: OutEvent['type'] | '*', cb: (event: OutEvent) => void): () => void;
+  subscribe(hash: QueryHash, cb: QueryUpdateCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  subscribeStatus(hash: QueryHash, cb: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  subscribeAuthority(hash: QueryHash, cb: QueryAuthorityCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /** Apply a reducer outside a saga (facade conveniences such as timing reports). */
+  update(reducer: (s: ClientState) => ClientState): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/services/tabs/coordinator.d.ts
+interface CoordinatorHooks {
+  /** Become the store owner: spawn the worker, open the pool under the given
+   *  per-leadership lock. Returns the resulting health for db-ready relays.
+   *  `resumeHeld` = keep the existing live worker (broker-restart path). */
+  adoptOwner(bucketId: string, opts: {
+    workerLockName: string;
+    allowMemoryFallback: boolean;
+    forceTakeover: boolean;
+    resumeHeld: boolean;
+  }): Promise<StorageHealth>;
+  /** Attach to a leader's worker through `dbPort`. */
+  adoptAttached(dbPort: MessagePort, snapshot: {
+    bucketId: string;
+    storageHealth: StorageHealth;
+    leadershipId: number;
+  }): Promise<void>;
+  /** We were leader and got demoted (zombie thaw / stale promotion): tear the
+   *  owned worker down so its SAH handles free up. */
+  releaseOwnership(): Promise<void>;
+  /** The leader (or its port) is gone; queue/park ops until a new role lands. */
+  onLeaderLost(reason: string): void;
+  /** Leader side: forward a follower's dbPort into the owned worker. */
+  exposeClientPort(clientId: string, port: MessagePort): Promise<void>;
+  removeClientPort(clientId: string): Promise<void>;
+  /** Sync layer role changes (implemented in the sync module). */
+  /** Synchronous leader WIRING. Must not block: the role is published and
+   *  `leader-ready` is sent right after it returns. */
+  becomeSyncLeader(hub: LeaderSyncHub): void;
+  /** The blocking half of the leader handover (outbox drain, LIVE restart),
+   *  run in the background once the tab is already a working leader. */
+  resumeSyncLeaderDuties(): Promise<void>;
+  becomeSyncFollower(forwarder: SyncForwarder): void;
+  becomeSyncSolo(): void;
+  /** Current storage health, for db-ready sent to late-joining followers. */
+  currentStorageHealth(): StorageHealth;
+}
+/** 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;
+  /** An optimistic write this tab just ingested. Deliberately NOT queued while
+   *  detached: a new leader primes its circuit from the shared store, which
+   *  already holds the row, and replaying a stale tuple at it later would put
+   *  an older `_00_rv` in its version memo. */
+  ingest(tuples: IngestTuple[]): void;
+  requestPoll(): void;
+}
+declare class TabsCoordinator {
+  private deps;
+  role: TabRole$1;
+  leadershipId: number;
+  leaderTabId: TabId | null;
+  brokerRole: 'pending' | TabRole$1;
+  /** Wall time from `become-leader` to `leader-ready` on the last promotion.
+   *  Reported in the DevTools role-change event: a slow store adopt (OPFS pool
+   *  contention after the previous leader died) shows up here as seconds. */
+  lastPromotionMs: number | null;
+  private fingerprint;
+  private bucketId;
+  private broker;
+  private hub;
+  private forwarder;
+  private roleListeners;
+  private startResolve;
+  private startReject;
+  /** Ports received before start() resolves or between roles. */
+  private promotionChain;
+  private closed;
+  constructor(deps: {
+    tabId: TabId;
+    fingerprint: string;
+    hooks: CoordinatorHooks;
+    logger: Logger$1;
+    /** Fired on pagehide while this tab leads: last-chance OPFS release. */
+    onLeaderPageHide?: () => void;
+  });
+  /** Serialize role transitions; each is small but async (worker opens). */
+  private enqueue;
+  onRoleChange(cb: (role: TabRole$1) => void): () => void;
+  private setRole;
+  /** Connect the broker and resolve once this tab has a usable store role.
+   *  Rejects when no role lands in time; the caller then boots solo. */
+  start(bucketId: string): Promise<TabRole$1>;
+  /** Bucket switch: leave the old namespace, join the new one. Resolves when
+   *  a role lands in the new namespace. */
+  moveToBucket(bucketId: string): Promise<TabRole$1>;
+  private promote;
+  private demote;
+  private tabLock;
+  private teardownLeader;
+  private teardownFollower;
+  private serveFollower;
+  private attachToLeader;
+  private handleLeaderGone;
+  private fallbackToSolo;
+  get syncHub(): LeaderSyncHub | null;
+  get syncForwarder(): SyncForwarder | null;
+  get tabId(): TabId;
+  stop(): Promise<void>;
+}
+//#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/client/services.d.ts
+/** Everything the facade talks to besides the runtime. */
+interface Services<S extends SchemaStructure> {
+  logger: Logger$1;
+  local: LocalStore;
+  remote: RemoteDatabaseService;
+  connectionSupervisor: ConnectionSupervisor;
+  blobs: BlobCache;
+  persistence: PersistenceClient;
+  streamProcessor: StreamProcessorService;
+  migrator: LocalMigrator;
+  crdt: CrdtManager;
+  auth: AuthService<S>;
+  tabs: TabsCoordinator | null;
+  tabsUnsupportedReason: string | undefined;
+  tabId: string;
+}
+/** What the services need back from the runtime once it exists. */
+//#endregion
+//#region src/utils/blurhash.d.ts
+/**
+ * Blurhash generation settings. `true` enables with the defaults below, `false`
+ * disables. Resolution order for a put: per-call option > client config >
+ * default ON. See {@link Sp00kyConfig.blurhash}.
+ */
+type BlurhashSetting = boolean | BlurhashEncodeOptions;
+interface BlurhashEncodeOptions {
+  /** Horizontal detail components, 1-9. Defaults to 4. */
+  componentX?: number;
+  /** Vertical detail components, 1-9. Defaults to 3. */
+  componentY?: number;
+}
+/**
+ * Where an image's blurhash lives: a tiny sidecar object in the same bucket.
+ * Buckets have no per-object metadata channel (`put` is just `.put($content)`),
+ * so the hash for `covers/x_t.webp` is the text object `covers/x_t.webp.bh`.
+ */
+declare function blurhashSidecarPath(path: string): string;
+/** Extensions `bucket.put` treats as images worth hashing. */
+declare const BLURHASH_IMAGE_EXTENSIONS: readonly ["webp", "png", "jpg", "jpeg", "gif", "avif", "bmp"];
+declare function isImagePath(path: string): boolean;
+/**
+ * Decode `content` as an image and compute its blurhash. Browser-only: returns
+ * null (never throws) when image decoding is unavailable (node, workers without
+ * canvas), when the bytes are not a decodable image, or on any other failure —
+ * a missing hash must never break the upload that triggered it.
+ */
+declare function encodeImageToBlurhash(content: string | Uint8Array | Blob, options?: BlurhashEncodeOptions): Promise<string | null>;
+//#endregion
+//#region src/client/bucket-handle.d.ts
+/** Coerce whatever the `.get()` RPC hands back into a Blob. */
+declare function bucketContentToBlob(content: unknown): Blob | null;
+interface BucketPutOptions {
+  /** Override the client-level {@link Sp00kyConfig.blurhash} setting for this put. */
+  blurhash?: BlurhashSetting;
+}
+interface BucketPutResult {
+  /** The computed blurhash when the content was a hashable image; else null. */
+  blurhash: string | null;
+}
+interface BucketHandleSettings {
+  blurhash?: BlurhashSetting;
+  logger?: {
+    warn: (obj: unknown, msg?: string) => void;
+  };
+}
 declare class BucketHandle {
   private bucketName;
   private remote;
-  constructor(bucketName: string, remote: RemoteDatabaseService);
-  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  /** Absent on the raw handle the cache itself reads through. */
+  private blobs?;
+  private settings?;
+  constructor(bucketName: string, remote: RemoteDatabaseService, /** Absent on the raw handle the cache itself reads through. */
+  blobs?: (BlobCache | null) | undefined, settings?: BucketHandleSettings | undefined);
+  /** Effective blurhash setting: per-call option > client config > default ON. */
+  private resolveBlurhash;
+  put(path: string, content: string | Uint8Array | Blob, options?: BucketPutOptions): Promise<BucketPutResult>;
+  /**
+   * The blurhash stored alongside an uploaded image (see
+   * {@link blurhashSidecarPath}), or null when there is none. Reads through the
+   * blob cache, so a warm client answers from OPFS without a network hop, and
+   * misses are remembered per tab so a hashless image costs at most one
+   * serialized remote read per session.
+   */
+  blurhash(path: string): Promise<string | null>;
   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>>;
@@ -208,55 +2384,153 @@ declare class BucketHandle {
   rename(sourcePath: string, targetPath: string): Promise<void>;
   list(prefix?: string): Promise<string[]>;
 }
-declare class SpookyClient<S extends SchemaStructure> {
-  private config;
-  private local;
-  private remote;
-  private persistenceClient;
-  private migrator;
-  private cache;
-  private dataModule;
-  private sync;
-  private devTools;
-  private logger;
-  auth: AuthService<S>;
-  streamProcessor: StreamProcessorService;
-  get remoteClient(): Surreal;
-  get localClient(): Surreal;
-  get pendingMutationCount(): number;
-  subscribeToPendingMutations(cb: (count: number) => void): () => void;
-  constructor(config: SpookyConfig<S>);
-  /**
-   * Setup direct callbacks instead of event subscriptions
-   */
-  private setupCallbacks;
+//#endregion
+//#region src/client/sp00ky-client.d.ts
+interface Sp00kyClientDeps<S extends SchemaStructure> {
+  services?: Services<S>;
+  runtime?: Runtime;
+  env?: Partial<SagaEnv>;
+}
+/**
+ * The public client. Every method is a thin translation into a saga run, a
+ * state read, or a subscription on the runtime; the engine's behaviour lives
+ * in the sagas.
+ */
+declare class Sp00kyClient<S extends SchemaStructure> {
+  private readonly config;
+  readonly auth: AuthService<S>;
+  readonly streamProcessor: StreamProcessorService;
+  private readonly services;
+  private readonly env;
+  private readonly runtime;
+  private readonly featureFlags;
+  private readonly appReleases;
+  /** Teardown for subscriptions the client itself owns. */
+  private readonly disposers;
+  private readonly devTools;
+  private hub;
+  private forwarder;
+  private detachWindow;
+  private sharedActive;
+  constructor(config: Sp00kyConfig<S>, deps?: Sp00kyClientDeps<S>);
+  /** Adapter callbacks become runtime events; runtime events reach the legacy services. */
+  private wireAdapters;
+  private forwardToDevTools;
   init(): Promise<void>;
   close(): Promise<void>;
-  authenticate(token: string): Promise<surrealdb0.Tokens>;
-  deauthenticate(): Promise<void>;
-  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, SpookyQueryResultPromise>;
+  isLocalReady(): boolean;
+  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
+  private registerInput;
   private initQuery;
+  /**
+   * The raw remote escape hatches bypass the query builder, so their shapes
+   * can never be on the server's query allowlist. When the generated schema
+   * says the allowlist is on, refuse them unless the app opted in explicitly.
+   */
+  private assertRawRemoteAllowed;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
+  /**
+   * Preload = register a query nobody subscribes to. Resolved before on this
+   * device: returns at once. Never resolved: resolves when the server's
+   * membership and every body are local. `signal` aborts the wait.
+   */
+  preload(finalQuery: FinalQuery<S, any, any, any, any, any>, options?: PreloadOptions): Promise<void>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
   }): Promise<() => void>;
+  deregisterQuery(queryHash: string): void;
+  subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  subscribeQueryAuthority(queryHash: string, callback: QueryAuthorityCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  reportFrontendTiming(queryHash: string, ms: number): void;
+  create<T extends Record<string, unknown>>(id: string, data: T): Promise<T>;
+  update<T extends Record<string, unknown>>(_table: string, id: string, data: Partial<T>, options?: UpdateOptions): Promise<T>;
+  delete(_table: string, id: string): Promise<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;
-  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>;
+  get failedMutationCount(): number;
+  subscribeToFailedMutations(cb: (count: number) => void): () => void;
+  listFailedMutations(): Promise<FailedMutationRow[]>;
+  retryFailedMutation(mutationId: string): Promise<boolean>;
+  discardFailedMutation(mutationId: string): Promise<boolean>;
+  get tabRole(): TabRole$1 | null;
+  get remoteClient(): Surreal;
+  get localClient(): unknown;
+  get pendingMutationCount(): number;
+  /** Kept for the e2e suite; the saga core has no LIVE retry ladder. */
+  get liveRetryCount(): number;
+  subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  get fetchingQueryCount(): number;
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void;
+  get syncHealth(): SyncHealth;
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  get storageHealth(): StorageHealth;
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void;
+  /** The engine state, read-only. For tests and DevTools. */
+  get state(): ClientState;
+  /** Feed an event into the engine. For adapters, tests and DevTools. */
+  dispatch(event: RuntimeEvent): Promise<void>;
+  authenticate(token: string): Promise<surrealdb0.Tokens>;
+  deauthenticate(): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
-  private persistClientId;
-  private loadOrGenerateClientId;
+  remoteQuery<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearFeatureOverrides(): void;
+  getFeatureOverrides(): Record<string, FeatureFlagOverride>;
+  appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle;
+  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  closeCrdtField(table: string, recordId: string, field: string): void;
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle;
+  getBlobCacheStats(): BlobCacheStats;
+}
+//#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/services/database/errors.d.ts
+/**
+ * A local-store operation that did not answer within its deadline.
+ *
+ * The local write path (`db.create` / `db.update` / `db.delete`, every local
+ * query behind them) used to have no deadline anywhere: the SQLite worker
+ * transport parks a call until the worker replies, the surrealdb engine's
+ * query chain waits on the previous link, and `withRetry` retries without a
+ * clock. One op that never settled (a worker starved behind a long select, a
+ * lock verification awaiting `navigator.locks.query()` forever) left the
+ * caller's promise pending for the tab's lifetime - a chat composer that never
+ * re-enabled, a call that never got past "Connecting".
+ *
+ * The message says "timed out" on purpose: `classifySyncError` keys off it and
+ * treats the failure as transient (re-queue), never as an application error
+ * that rolls the mutation back. `retryable: false` keeps `withRetry` from
+ * spinning on it: the op is still running in the engine, retrying queues a
+ * second copy behind it.
+ */
+declare class LocalOpTimeoutError extends Error {
+  readonly name = "LocalOpTimeoutError";
+  readonly retryable = false;
+  readonly op: string;
+  readonly timeoutMs: number;
+  constructor(op: string, timeoutMs: number);
 }
+/** Default deadline for one local-store operation. Generous: a cold 4k-row
+ *  select on a throttled tab is seconds, not tens of seconds. */
+declare const DEFAULT_LOCAL_OP_TIMEOUT_MS = 30000;
 //#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, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { ActiveImpersonation, AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, IMPERSONATION_ACCESS, ImpersonationCandidate, ImpersonationInfo, ImpersonationTimerHost, ImpersonationTimers, InlineRow, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, ORIGIN_TOKEN_KEY, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, SESSION_POLL_MS, ServerViewMeta, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, TokenClaims, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, renewDelayMs, sameImpersonation, semverGt, textToHtml };