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

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { RecordId } from "surrealdb";
-import { RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
+import { QueryPlan, QueryPlan as QueryPlan$1, RecordId as RecordId$1, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
 import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
 
 //#region src/events/index.d.ts
@@ -123,9 +123,223 @@ declare class EventSystem<E extends EventTypeMap> {
   private broadcastEvent;
 }
 //#endregion
+//#region src/modules/sync/events/index.d.ts
+declare const SyncEventTypes: {
+  readonly QueryUpdated: "SYNC_QUERY_UPDATED";
+  readonly RemoteDataIngested: "SYNC_REMOTE_DATA_INGESTED";
+  readonly MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK";
+  readonly SyncHealthChanged: "SYNC_HEALTH_CHANGED";
+};
+type SyncEventTypeMap = {
+  [SyncEventTypes.QueryUpdated]: EventDefinition<typeof SyncEventTypes.QueryUpdated, {
+    queryId: any;
+    localHash?: string;
+    localArray?: RecordVersionArray;
+    remoteHash?: string;
+    remoteArray?: RecordVersionArray;
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.RemoteDataIngested]: EventDefinition<typeof SyncEventTypes.RemoteDataIngested, {
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.MutationRolledBack]: EventDefinition<typeof SyncEventTypes.MutationRolledBack, {
+    eventType: string;
+    recordId: string;
+    error: string;
+  }>;
+  [SyncEventTypes.SyncHealthChanged]: EventDefinition<typeof SyncEventTypes.SyncHealthChanged, SyncHealth>;
+};
+type SyncEventSystem = EventSystem<SyncEventTypeMap>;
+//#endregion
 //#region src/services/logger/index.d.ts
 type Logger$1 = Logger;
 //#endregion
+//#region src/services/database/events/index.d.ts
+declare const DatabaseEventTypes: {
+  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
+  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
+};
+interface DatabaseQueryEventPayload {
+  query: string;
+  vars?: Record<string, unknown>;
+  duration: number;
+  success: boolean;
+  error?: string;
+  timestamp: number;
+}
+type DatabaseEventTypeMap = {
+  [DatabaseEventTypes.LocalQuery]: EventDefinition<typeof DatabaseEventTypes.LocalQuery, DatabaseQueryEventPayload>;
+  [DatabaseEventTypes.RemoteQuery]: EventDefinition<typeof DatabaseEventTypes.RemoteQuery, DatabaseQueryEventPayload>;
+};
+type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
+//#endregion
+//#region src/utils/surql.d.ts
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+//#endregion
+//#region src/modules/devtools/storage-info.d.ts
+/** Engine-side numbers only the engine can produce (worker round-trips). */
+interface EngineStorageDiagnostics {
+  engine: 'sqlite';
+  bucketId: string;
+  useOpfs: boolean;
+  workerSelectConfigured: boolean;
+  /** `false` while configured `true` means the runtime downgraded to the
+   *  legacy multi-hop select (stale cached worker bundle). */
+  workerSelectEffective: boolean;
+  /** page_count * page_size. */
+  dbSizeBytes?: number;
+  /** freelist_count * page_size — reclaimable via VACUUM. */
+  freelistBytes?: number;
+  tableCounts?: {
+    table: string;
+    rows: number;
+  }[];
+  error?: string;
+}
+/**
+ * Shared-tabs coordination state. Reported ONLY when `sharedTabs: true` was
+ * configured (apps that never asked for it get `null`, so the panel shows
+ * nothing). `active: false` with a `reason` is itself the useful signal: the
+ * app asked to share one store and this tab is not, so it owns or contends for
+ * the OPFS pool alone.
+ */
+//#endregion
+//#region src/services/database/cache-engine.d.ts
+/**
+ * A materialized row. Keys are field names; values are already decoded to the
+ * client's runtime shapes (RecordId stays a RecordId, bytes a Uint8Array, …) so
+ * every backend hands `DataModule` the same shape SurrealDB does today.
+ */
+type Row = Record<string, unknown>;
+/** A record identifier — a `RecordId` or its stable string form (`table:id`). */
+type Id = unknown;
+/** How an order clause is expressed everywhere in the engine layer. */
+type OrderBy = [field: string, direction: 'asc' | 'desc'][];
+/**
+ * Batched relation fetch: "give me every row of `table` whose `matchField` is
+ * one of `keys`, filtered by `where`, ordered by `orderBy`". This is the single
+ * primitive relation decomposition (§3) leans on — implemented as
+ * `SELECT … WHERE <matchField> IN (…)` on SQLite, `SELECT … FROM $keys` /
+ * `WHERE <matchField> IN $keys` on SurrealDB, or an index scan elsewhere. Order
+ * here is a hint; the resolver re-applies order+limit PER PARENT after grouping.
+ */
+interface RelationFetch {
+  table: string;
+  matchField: string;
+  keys: Id[];
+  where?: WhereNode[];
+  orderBy?: OrderBy;
+  select?: string[];
+}
+/**
+ * The read side of an engine, minus relation resolution — the surface a
+ * {@link RelationResolver} needs. Kept separate so the resolver can be unit
+ * tested against an in-memory fake without a full engine.
+ */
+interface RowFetcher {
+  /** Batched fan-out fetch. See {@link RelationFetch}. */
+  fetchRelation(req: RelationFetch): Promise<Row[]>;
+}
+/** A transaction handle — the same verbs as the engine, but atomic. */
+interface EngineTx {
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+/**
+ * A pluggable local cache backend. SurrealDB (the default) and SQLite both
+ * implement this; the rest of the client talks verbs, never SurrealQL.
+ *
+ * Reactivity is NOT part of this contract: the local cache is passive. The SSP
+ * (remote) drives change; `DataModule` writes rows here and re-reads them. The
+ * `epoch` field preserves the existing bucket-switch fencing (see
+ * `LocalDatabaseService.epoch`): an async chain captures it at start and its
+ * write is dropped if the epoch moved (a bucket switch) in between.
+ */
+interface LocalCacheEngine extends RowFetcher {
+  /** Monotonic store generation; bumped on every bucket switch. */
+  readonly epoch: number;
+  connect(bucketId: string): Promise<void>;
+  switchBucket(bucketId: string): Promise<void>;
+  close(): Promise<void>;
+  /** Run `fn` inside a single atomic transaction. */
+  transaction<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T>;
+  /**
+   * Materialize a query, including its `.related()` tree (via §3
+   * decomposition). Params bind `where` `paramRef`s and any windowing id-set.
+   */
+  select(plan: QueryPlan$1, params?: Record<string, unknown>): Promise<Row[]>;
+  /** Fetch rows by primary id, preserving `ids` order; missing ids are skipped. */
+  selectByIds(table: string, ids: Id[], opts?: {
+    select?: string[];
+    orderBy?: OrderBy;
+  }): Promise<Row[]>;
+  /** Single-record read by primary id, or `null`. */
+  getById(table: string, id: Id): Promise<Row | null>;
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+/**
+ * The full surface the client's `this.local` field depends on: the
+ * engine-neutral {@link LocalCacheEngine} verbs PLUS the legacy
+ * SurrealQL/lifecycle methods the not-yet-migrated call sites still use.
+ * `SurrealCacheEngine` (subclass of `LocalDatabaseService`) and
+ * `SqliteCacheEngine` (via a SurrealQL-vocabulary shim) both satisfy this, so
+ * either can back `this.local`.
+ *
+ * `getClient()` returns the underlying SurrealDB `Surreal` handle where one
+ * exists (SurrealDB backend); backends without one (SQLite) throw — it is only
+ * used by advanced/DevTools paths, never on the hot path.
+ */
+interface LocalStore extends LocalCacheEngine {
+  /**
+   * Whether this engine needs SurrealQL schema provisioning (`DEFINE TABLE`,
+   * `DEFINE FIELD`, …) run against it at init / bucket switch. SurrealDB → true;
+   * schemaless engines (SQLite creates tables lazily) → false, so the client
+   * skips the `LocalMigrator` entirely for them.
+   */
+  readonly usesSurqlSchema: boolean;
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  queryUngated<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+  switchStore(bucketId: string): Promise<void>;
+  beginSwitch(): () => void;
+  getEvents(): DatabaseEventSystem;
+  getClient(): unknown;
+  getConfig(): Sp00kyConfig<any>['database'];
+  readonly currentBucketId: string;
+  /** Which built-in backend this is. OPTIONAL: absent (custom engines) is
+   *  reported as `'custom'` by DevTools. More robust than `instanceof` for
+   *  engines constructed outside this package. */
+  readonly engineKind?: 'surrealdb' | 'sqlite';
+  /** Engine-specific storage numbers for DevTools (DB file size, per-table
+   *  row counts). OPTIONAL: only engines with something to report implement it. */
+  getStorageDiagnostics?(opts?: {
+    tableCounts?: boolean;
+  }): Promise<EngineStorageDiagnostics>;
+  /**
+   * Durability of this engine's local store. OPTIONAL: engines that don't
+   * report it (SurrealDB, custom engines) are treated as `'unknown'` by the
+   * client facade, so adding this needs no change on their side.
+   */
+  readonly storageHealth?: StorageHealth;
+  /** Fires immediately with the current snapshot, then on every change.
+   *  Returns an unsubscribe function. */
+  subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
+}
+/** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
+type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+ *  a guard against a cyclic schema producing unbounded fan-out. */
+//#endregion
 //#region src/modules/sync/queue/queue-up.d.ts
 type CreateEvent = {
   type: 'create';
@@ -192,22 +406,38 @@ interface PersistenceClient {
  * Format: number + unit (m=minutes, h=hours, d=days).
  */
 type QueryTimeToLive = '1m' | '5m' | '10m' | '15m' | '20m' | '25m' | '30m' | '1h' | '2h' | '3h' | '4h' | '5h' | '6h' | '7h' | '8h' | '9h' | '10h' | '11h' | '12h' | '1d';
+/**
+ * Refresh behavior for `preload` when the data is already cached locally (warm).
+ * The FIRST load (cold) always fetches + blocks regardless.
+ * - `onUse` (default): do nothing when warm — the data freshens on use, when the
+ *   real `useQuery` mounts and registers its live view. No network on load.
+ * - `background`: return instantly, but kick a one-time silent refetch.
+ * - `stale`: like `background`, but only if the cached copy is older than
+ *   `staleTime`.
+ */
+type PreloadRefresh = 'onUse' | 'background' | 'stale';
+interface PreloadOptions {
+  /** How to refresh when the query is already cached locally. Default `onUse`. */
+  refresh?: PreloadRefresh;
+  /** For `refresh: 'stale'` — max age before a warm copy is refetched. Default `1h`. */
+  staleTime?: QueryTimeToLive;
+}
 /**
  * Result object returned when a query is registered or executed.
  */
-interface SpookyQueryResult {
+interface Sp00kyQueryResult {
   /** The unique hash identifier for the query. */
   hash: string;
 }
-type SpookyQueryResultPromise = Promise<SpookyQueryResult>;
+type Sp00kyQueryResultPromise = Promise<Sp00kyQueryResult>;
 interface EventSubscriptionOptions {
   priority?: number;
 }
 /**
- * Configuration options for the Spooky client.
+ * Configuration options for the Sp00ky client.
  * @template S The schema structure type.
  */
-interface SpookyConfig<S extends SchemaStructure> {
+interface Sp00kyConfig<S extends SchemaStructure> {
   /** Database connection configuration. */
   database: {
     /** The SurrealDB endpoint URL. */
@@ -220,27 +450,325 @@ interface SpookyConfig<S extends SchemaStructure> {
     store?: StoreType;
     /** Authentication token. */
     token?: string;
+    /**
+     * SQLite engine only: execute `select` plans (base rows + relation tree +
+     * row parsing) inside the worker as ONE round-trip instead of one hop per
+     * table/relation level. Defaults to true; set false to force the legacy
+     * multi-hop path (escape hatch while the worker-side path beds in).
+     */
+    workerSelect?: boolean;
+    /**
+     * WebSocket reconnect + liveness tuning. All fields optional; the defaults
+     * keep the connection alive indefinitely without configuration. See
+     * {@link ReconnectConfig}.
+     */
+    reconnect?: ReconnectConfig;
+    /**
+     * Deadline (ms) for every remote RPC. Remote queries are serialized through
+     * a single promise chain, so one call that never settles (half-open socket:
+     * the WebSocket looks open, the peer is gone, no `close` event fires) would
+     * otherwise wedge ALL later remote traffic behind it — including the sync
+     * poll's own health probe, leaving health pinned at `healthy` with no
+     * banner and no self-heal. The deadline turns that into an ordinary network
+     * failure the queue retries. `0` disables. Defaults to `60_000`.
+     */
+    queryTimeoutMs?: number;
   };
-  /** Unique client identifier. If not provided, one will be generated. */
-  clientId?: string;
   /** The schema definition. */
   schema: S;
   /** The compiled SURQL schema string. */
   schemaSurql: string;
   /** Logging level. */
-  logLevel: Level;
+  logLevel: Level$1;
   /**
    * Persistence client to use.
    * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
    */
   persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
+  /**
+   * Local cache engine backend. `'surrealdb'` (default) uses the in-browser
+   * SurrealDB-WASM store; `'sqlite'` uses official SQLite-WASM in a Worker with
+   * OPFS persistence; or pass a custom {@link LocalCacheEngine}. The local cache
+   * is a passive queryable store — reactivity is driven by the remote SSP, not
+   * this engine. See `services/database/cache-engine.ts`.
+   */
+  localEngine?: LocalEngineChoice;
+  /**
+   * Durable cache for bucket file bytes, in OPFS. Enabled by default wherever
+   * OPFS is writable; elsewhere the cache degrades to per-tab memory, which is
+   * how bucket reads behaved before it existed.
+   *
+   * Nothing in this cache expires on a timer — an image whose row is still in
+   * the local store has to stay available offline. Bytes are only dropped when
+   * the app invalidates the path (`bucket.put`/`bucket.delete`), when boot
+   * reconcile finds no file behind a row, or when the cache is over budget, in
+   * which case the least-recently-used unpinned entries go first. See
+   * `services/blobs/blob-cache.ts`.
+   */
+  blobCache?: {
+    /** Default `true`. `false` restores per-tab, non-persistent caching. */
+    enabled?: boolean;
+    /** Byte budget. Defaults to `min(512 MB, quota × 0.25)` from
+     *  `navigator.storage.estimate()`. */
+    maxBytes?: number;
+    /**
+     * Delete the signed-out user's cached bytes on `signOut()`. Default
+     * `false`, matching the local store: cached files are namespaced per local
+     * bucket, so signing back in is warm and no user can read another's cache.
+     * Turn on for shared devices.
+     */
+    clearOnSignOut?: boolean;
+  };
+  /**
+   * Share ONE durable local store across all tabs of this origin (default
+   * `false`). Requires `localEngine: 'sqlite'`. A SharedWorker broker elects a
+   * leader tab per bucket via Web Locks; the leader owns the OPFS SQLite
+   * worker and the sync loop, and follower tabs read/write the same store over
+   * MessagePorts, so every tab is durable instead of only the first one.
+   *
+   * Falls back to solo mode (exactly the flag-off behavior, including the
+   * later-tabs in-memory fallback reported via {@link StorageHealth}) whenever
+   * SharedWorker, Web Locks, or MessageChannel are unavailable, the engine is
+   * not sqlite, or the broker rejects the tab (mixed app versions).
+   *
+   * Failover: when the leader tab closes or freezes, a follower is promoted
+   * within seconds; queries briefly refetch and mutations are never lost once
+   * their local write resolved (the shared outbox survives in the store).
+   * Inspect via `window.__00__.getState().database.tabs` and `__sqliteStats`.
+   */
+  sharedTabs?: boolean;
+  /**
+   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
+   * reload can restore it instead of re-materializing. Default `false`, and
+   * that default is deliberate.
+   *
+   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
+   * source of truth, and every first paint already reads row bodies from it
+   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
+   * for row identity and ordering. A snapshot buys nothing on reload while
+   * costing a full deep clone of every row of every ingested table plus a JSON
+   * encode of the result, `Circuit::save` in the Rust core, mirroring the
+   * server's rule in `ssp-node`: *never per-ingest*.
+   *
+   * When enabled, snapshots are written on a checkpoint interval
+   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
+   * query registration. Enable only for a workload that has measured a win.
+   */
+  persistCircuit?: boolean;
+  /**
+   * Checkpoint interval in milliseconds for {@link persistCircuit}. Defaults to
+   * 30000. Ignored when `persistCircuit` is off.
+   */
+  circuitCheckpointMs?: number;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
-   * Debounce time in milliseconds for stream updates.
-   * Defaults to 100ms.
+   * Debounce time in milliseconds for stream updates (the client-side SSP
+   * aggregation throttle — coalesces the in-browser StreamProcessor's
+   * per-record updates per query before notifying readers).
+   * Defaults to 50ms.
    */
   streamDebounceTime?: number;
+  /**
+   * Debounce time in milliseconds for syncing collaborative (CRDT) field
+   * changes to the remote database. Local writes happen immediately on
+   * every keystroke (so reload/offline works), but the remote UPSERT is
+   * coalesced over this window. Lower = snappier remote propagation +
+   * more network traffic; higher = less traffic + more lag for other
+   * collaborators. Defaults to 500ms.
+   */
+  crdtDebounceMs?: number;
+  /**
+   * Enable collaborative CRDT fields. When `true`, the `loro-crdt` engine is
+   * preloaded at client startup (fetched as a separate chunk on page load) so
+   * the first `openCrdtField` is instant. When omitted/`false`, loro is never
+   * loaded unless a CRDT field is explicitly opened — keeping the loro chunk
+   * out of apps that don't use collaboration. Defaults to `false`.
+   */
+  crdt?: boolean;
+  /**
+   * Cadence (ms) for the `_00_list_ref` poll that catches cross-session
+   * UPDATEs the SurrealDB v3 LIVE-permission gap drops. Lower = faster
+   * convergence + more query load; higher = the inverse. Non-positive
+   * values fall back to the default (500ms).
+   */
+  refSyncIntervalMs?: number;
+  /**
+   * OPT-IN instant-hydrate for cold queries: when enabled and a query is
+   * registered with no server result yet, its surql also runs directly on the
+   * remote (one-shot, in the background, OFF the paint path) so rows can land
+   * before the full register lifecycle completes. Hydrated rows carry their
+   * `_00_rv` versions so the registration's `syncRecords` skips re-pulling
+   * unchanged bodies. Regardless of this flag, `useQuery` always resolves and
+   * paints from the local cache immediately — however the rows got there
+   * (preload, prior sync). Default `false`: the register lifecycle
+   * (`fn::query::register` → `_00_list_ref` → record sync) is the single
+   * freshness path and no duplicate one-shot fetches are made.
+   */
+  instantHydrate?: boolean;
+  /**
+   * Enable realtime sync while signed out. When `true`, the client starts its
+   * `_00_list_ref` poll (and a LIVE subscription) against the shared
+   * `_00_list_ref_anon` table even with no authenticated user, so a logged-out
+   * page gets live `useQuery` updates over world-readable tables. Requires the
+   * server to be deployed with `anonymousLiveQueries: true` in `sp00ky.yml`
+   * (this flag must match it). Defaults to `false`: anonymous clients can read
+   * one-shot but never sync live.
+   */
+  enableAnonymousLiveQueries?: boolean;
+  /**
+   * Surface sustained sync failures as a "degraded" health status that the app
+   * can observe via `subscribeToSyncHealth` (or the client-solid
+   * `useSyncStatus` hook) to render a "can't reach the server" banner.
+   *
+   * Individual failures — a transient remote 500 on query registration, a
+   * dropped WebSocket, etc. — are always swallowed and retried; they never
+   * throw at the app. This only controls when a *run* of consecutive failures
+   * is reported. Status flips back to `healthy` on the next successful sync
+   * round. Defaults to `{ degradeAfterConsecutiveFailures: 3 }`; pass `false`
+   * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
+   */
+  syncHealth?: SyncHealthConfig | false;
+  /**
+   * Automatic blurhash placeholders for bucket image uploads. On every
+   * `bucket.put` of an image path (by extension: webp/png/jpg/jpeg/gif/avif/bmp)
+   * the client computes a blurhash and stores it as a tiny sidecar object
+   * `<path>.bh` in the same bucket, best-effort. Read it back with
+   * `bucket.blurhash(path)` (or the client-solid `useBucketImage`/`BucketImage`
+   * helpers) to paint a placeholder until the image is decoded.
+   *
+   * `true` (the default) enables with 4x3 components; pass
+   * `{ componentX, componentY }` to tune detail, or `false` to disable.
+   * A per-call `put(path, content, { blurhash })` option overrides this.
+   */
+  blurhash?: boolean | {
+    componentX?: number;
+    componentY?: number;
+  };
+  /**
+   * Deadline (ms) for a single outgoing mutation push. Tighter than
+   * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains
+   * one mutation at a time behind an `isSyncingUp` flag: a push that never
+   * settles stops every later mutation for the session, with no retry and no
+   * error. On expiry the push is treated as a network failure and re-queued.
+   * `0` disables. Defaults to `30_000`.
+   */
+  pushTimeoutMs?: number;
+}
+/** Tunables for sync-health reporting. See {@link Sp00kyConfig.syncHealth}. */
+interface SyncHealthConfig {
+  /**
+   * Number of consecutive failed sync rounds (up or down) before the status
+   * flips from `healthy` to `degraded`. A single transient failure is absorbed
+   * by the retry; only a sustained run trips the banner. Defaults to `3`. `0`
+   * disables degraded reporting entirely.
+   */
+  degradeAfterConsecutiveFailures?: number;
+}
+/**
+ * Tunables for WebSocket reconnect and liveness detection. See
+ * {@link Sp00kyConfig.database.reconnect}.
+ *
+ * Two independent mechanisms cooperate here. The SurrealDB SDK reconnects on
+ * its own after a socket `close` (`attempts` / `retryDelayMax`), and a
+ * supervisor above it re-opens the connection from scratch whenever the SDK
+ * gives up or its post-reconnect handshake fails — the SDK terminates the
+ * engine permanently in that case, so a supervisor is required, not optional.
+ * The heartbeat covers the third case: a socket that never closes at all.
+ */
+interface ReconnectConfig {
+  /**
+   * SDK reconnect attempts after a socket close. `-1` retries forever.
+   * Defaults to `-1` (the SDK's own default is `5`, which caps recovery at a
+   * ~62s outage and then gives up for the life of the page).
+   */
+  attempts?: number;
+  /** Cap on the SDK's exponential backoff delay. Defaults to `15_000`. */
+  retryDelayMax?: number;
+  /**
+   * Cadence of the application-level liveness probe (`RETURN true`) that
+   * detects a half-open socket the transport never reports as closed.
+   * `0` disables the heartbeat. Defaults to `20_000`.
+   */
+  heartbeatIntervalMs?: number;
+  /**
+   * Deadline for a heartbeat response. Exceeding it means the socket is dead
+   * regardless of what its `readyState` claims, so the connection is torn down
+   * and rebuilt. Defaults to `10_000`.
+   */
+  heartbeatTimeoutMs?: number;
+  /**
+   * Cap on the supervisor's own backoff between `connect()` retries once the
+   * SDK has given up. Defaults to `15_000`.
+   */
+  superviseRetryDelayMaxMs?: number;
+}
+/**
+ * Transport-level connection state, independent of {@link SyncHealthStatus}.
+ *
+ * These answer different questions: `connection` is about the socket,
+ * `status` is about whether sync rounds are succeeding. A `connected` socket
+ * can still be `degraded` (server erroring), and a `reconnecting` socket is
+ * usually still `healthy` for the first few seconds.
+ */
+type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+type SyncHealthStatus = 'healthy' | 'degraded';
+/** Snapshot of sync health delivered to `subscribeToSyncHealth` subscribers. */
+interface SyncHealth {
+  /** `'degraded'` once consecutive failures cross the configured threshold. */
+  status: SyncHealthStatus;
+  /** Consecutive failed sync rounds at the moment of this report. */
+  consecutiveFailures: number;
+  /** Classification of the most recent failure (only set while `degraded`). */
+  kind?: 'network' | 'application';
+  /** Message of the most recent failure (only set while `degraded`). */
+  error?: string;
+  /**
+   * `true` once at least one sync round has succeeded this session. Lets a UI
+   * distinguish a first-time "connecting" phase (never reached the server yet,
+   * so a cold-start failure run is expected) from a real lost connection after
+   * a working session. Never resets back to `false` once set.
+   */
+  everConnected: boolean;
+  /**
+   * Live transport state of the remote WebSocket. Distinct from `status`: this
+   * one flips the instant the socket drops, whereas `status` only degrades
+   * after a sustained run of failed sync rounds. Use it to show "reconnecting…"
+   * immediately without waiting for the degrade threshold.
+   */
+  connection: ConnectionState;
+}
+type StorageHealthStatus = 'unknown' | 'persistent' | 'memory';
+/**
+ * Durability of the LOCAL cache, delivered to `subscribeToStorageHealth`
+ * subscribers. Separate from {@link SyncHealth}: that one is about reaching the
+ * server, this one is about whether the local store survives a reload.
+ *
+ * Under `localEngine: 'sqlite'` the durable store is the OPFS SAHPool VFS,
+ * which only one client per bucket can hold open. When it can't be opened (a
+ * second tab of the app already has it, an insecure context, a full pool) the
+ * engine keeps working against an in-memory DB, which holds the whole dataset
+ * in RAM and loses local writes on reload. `fallback` marks exactly that case,
+ * so a UI can warn about it.
+ */
+interface StorageHealth {
+  /** `'unknown'` until the local cache has opened, or for engines that don't report. */
+  status: StorageHealthStatus;
+  /**
+   * `true` only when durable storage was REQUESTED and could not be opened.
+   * Stays `false` for a configured-in-memory store (`store: 'memory'`), which
+   * is a choice rather than a failure, so a UI can key off this alone.
+   */
+  fallback: boolean;
+  /** Reason durable storage failed (only set while `fallback` is `true`). */
+  error?: string;
+  /**
+   * Shared-tabs role, set only when `sharedTabs` is active: `'leader'` owns
+   * the OPFS worker, `'follower'` shares it over a MessagePort (its data IS
+   * durable, hence `status: 'persistent'`), `'solo'` fell back to the
+   * single-tab behavior. Absent entirely when the feature is off.
+   */
+  role?: 'leader' | 'follower' | 'solo';
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;
@@ -271,12 +799,68 @@ interface QueryConfig {
   id: RecordId$1<string>;
   /** The SURQL query string. */
   surql: string;
+  /**
+   * Engine-neutral plan for `surql` (in-memory only; not persisted to
+   * `_00_query`). Present when the query came from the query-builder. Non-
+   * SurrealQL local engines (SQLite) materialize via `engine.select(plan)`
+   * instead of re-running `surql`, which they cannot parse.
+   */
+  plan?: QueryPlan;
   /** Parameters used in the query. */
   params: Record<string, any>;
   /** The version array representing the local state of results. */
   localArray: RecordVersionArray;
   /** The version array representing the remote (server) state of results. */
   remoteArray: RecordVersionArray;
+  /**
+   * In-memory only (never persisted to `_00_query`): version array of the
+   * subquery CHILD rows pulled via `parent IS NOT NONE` edges, so the
+   * child-body sync is idempotent across polls. Kept separate from
+   * `remoteArray` so related child rows never enter the primary window /
+   * `rowCount` / `localArray`.
+   */
+  subqueryRemoteArray?: RecordVersionArray;
+  /**
+   * Whether authoritative membership (`remoteArray`) has ever been established
+   * for this query — either fetched from `_00_list_ref` this session, or read
+   * back from the durable `_00_window` row on a cold start.
+   *
+   * Tri-state matters: "known and empty" must render an empty list, while
+   * "never established" has to fall back to a predicate scan of the local store
+   * so a query first run on this device still paints offline. A
+   * `remoteArray.length === 0` check cannot tell those apart.
+   */
+  membershipKnown?: boolean;
+  /**
+   * Whether a NON-EMPTY id-set has arrived from the server for this query in
+   * this session. Gates whether an empty read may be believed.
+   *
+   * The server publishes `_00_list_ref` asynchronously — the SSP queues a
+   * view's initial edges to a coalescing flusher and returns from
+   * `fn::query::register` before they land — so an empty read right after
+   * registration says nothing about the query being empty. Believing it (and
+   * mirroring it to the durable `_00_window` row) blanked lists and kept them
+   * blank across reloads. Once a real set has been seen, a later empty one is a
+   * genuine transition and must be honoured, or removed rows resurrect.
+   *
+   * In-memory only: a fresh session must re-earn the right to believe empties.
+   */
+  remoteSeen?: boolean;
+  /**
+   * Consecutive empty id-sets read from the server while `remoteSeen` is still
+   * false. Bounds how long an unconfirmed empty may be ignored, so a window
+   * that genuinely emptied while this device was away is believed on the second
+   * read instead of rendering stale rows forever. Reset by any non-empty set.
+   * In-memory only.
+   */
+  emptyReads?: number;
+  /**
+   * Key of this query's durable `_00_window` membership row: a hash of
+   * `{surql, params}` WITHOUT the `session::id()` salt that `id` carries, so it
+   * survives a reload (which mints a new session id) and a bucket switch.
+   * In-memory only.
+   */
+  membershipKey?: string;
   /** Time-To-Live for this query. */
   ttl: QueryTimeToLive;
   /** Timestamp when the query was last accessed/active. */
@@ -287,6 +871,17 @@ interface QueryConfig {
 type QueryConfigRecord = QueryConfig & {
   id: string;
 };
+/**
+ * Runtime fetch status of a live query.
+ * - `idle`: registered, initial sync completed, and not currently fetching
+ *   missing records — the materialized rows are authoritative (a windowed
+ *   query's short result really is the end of the list).
+ * - `fetching`: the query is registering (a query is born `fetching` until its
+ *   initial remote sync completes) or the sync engine is fetching/ingesting
+ *   missing records for it. Any pending debounced result is flushed BEFORE the
+ *   flip back to `idle`, so idle status never races ahead of the rows.
+ */
+type QueryStatus = 'idle' | 'fetching';
 /**
  * Internal state of a live query.
  */
@@ -295,14 +890,89 @@ interface QueryState {
   config: QueryConfig;
   /** The current cached records for this query. */
   records: Record<string, any>[];
+  /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
+   * path fires at most once per query (see DataModule.isCold/applyHydration). */
+  hydrated?: boolean;
+  /** Set once `notifyQuerySynced` has emitted for this registration lifetime.
+   * Ephemeral (unlike the persisted `updateCount`), so a re-registered query
+   * always emits at least once even when its records are unchanged — otherwise
+   * an empty re-registered window would never notify and stay "loading". */
+  syncNotified?: boolean;
   /** Timer for TTL expiration. */
   ttlTimer: NodeJS.Timeout | null;
   /** TTL duration in milliseconds. */
   ttlDurationMs: number;
   /** Number of times the query has been updated. */
   updateCount: number;
+  /** Timestamp (ms) of the last user-visible update, or null before the first
+   * one. Surfaced to DevTools as `lastUpdate` — must NOT be stamped on read. */
+  lastUpdatedAt: number | null;
+  /**
+   * Rolling window of the most recent materialization-step latencies (ms).
+   * Capped at MATERIALIZATION_SAMPLE_WINDOW; used to recompute p55/p90/p99
+   * before each persist to `_00_query`. Samples themselves are not persisted.
+   */
+  materializationSamples: number[];
+  /** Most recent end-to-end ingest latency in ms, or null until the first ingest. */
+  lastIngestLatencyMs: number | null;
+  /** Cumulative count of ingest/materialization errors observed for this query. */
+  errorCount: number;
+  /**
+   * Ephemeral runtime fetch status. Not persisted to `_00_query`; observable
+   * via DevTools and the `useQuery` hook. `fetching` while the sync engine is
+   * pulling missing records for this query, otherwise `idle`.
+   */
+  status: QueryStatus;
+  /**
+   * Rolling per-phase timing samples (ms), in addition to `materializationSamples`
+   * (which holds the SSP whole-ingest wall time). Keyed by `TimingPhase` minus
+   * `ssp`. Not persisted — surfaced live to DevTools + MCP via `phaseTimings`.
+   */
+  phaseSamples: Record<string, number[]>;
+  /** Most recent sample (ms) per phase, or null. */
+  phaseLast: Record<string, number | null>;
+  /** One-shot SSP registration timings (ms). */
+  registrationTimings: RegistrationTimings;
+}
+/** Cap on the rolling materialization-sample window kept per query in memory. */
+declare const MATERIALIZATION_SAMPLE_WINDOW = 100;
+/** Timed processing phases surfaced per query. `ssp` is the WASM-ingest wall
+ *  time; the `ssp*` phases are its internal breakdown from the SSP binding. */
+type TimingPhase = 'ssp' | 'sspStoreApply' | 'sspCircuitStep' | 'sspTransform' | 'localFetch' | 'remoteFetch' | 'frontend';
+/** One-shot registration timings (ms), captured once when a query registers. */
+interface RegistrationTimings {
+  /** SSP surql→plan parse + permission injection. */
+  parseMs: number | null;
+  /** SSP operator-DAG build. */
+  planMs: number | null;
+  /** SSP initial snapshot evaluation. */
+  snapshotMs: number | null;
+  /** Wall time of `cache.registerQuery` (register_view round-trip). */
+  wallMs: number | null;
+}
+/** Percentile summary for one timed phase, surfaced to DevTools + MCP. */
+interface PhaseStat {
+  lastMs: number | null;
+  p50: number | null;
+  p90: number | null;
+  p99: number | null;
+  count: number;
+}
+/** Per-query processing-time breakdown surfaced via DevTools panel + MCP. */
+interface QueryTimings {
+  ssp: PhaseStat;
+  sspStoreApply: PhaseStat;
+  sspCircuitStep: PhaseStat;
+  sspTransform: PhaseStat;
+  localFetch: PhaseStat;
+  remoteFetch: PhaseStat;
+  frontend: PhaseStat;
+  registration: RegistrationTimings;
+  updateCount: number;
+  errorCount: number;
 }
 type QueryUpdateCallback = (records: Record<string, any>[]) => void;
+type QueryStatusCallback = (status: QueryStatus) => void;
 type MutationCallback = (mutations: UpEvent[]) => void;
 type MutationEventType = 'create' | 'update' | 'delete';
 /**
@@ -331,6 +1001,13 @@ interface RunOptions {
   assignedTo?: string;
   max_retries?: number;
   retry_strategy?: 'linear' | 'exponential';
+  /** Timeout in seconds for the backend HTTP call. Only used if the backend allows timeout override. */
+  timeout?: number;
+  /**
+   * Minimum delay in milliseconds before the job is eligible to run. While
+   * delayed the job stays pending (enqueued) and can still be killed.
+   */
+  delay?: number;
 }
 /**
  * Options for update operations.
@@ -356,4 +1033,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { Logger$1 as C, UpdateOptions as S, EventSystem as T, RunOptions as _, MutationEvent as a, SpookyQueryResultPromise as b, PinoTransmit as c, QueryHash as d, QueryState as f, RecordVersionDiff as g, RecordVersionArray as h, MutationCallback as i, QueryConfig as l, QueryUpdateCallback as m, EventSubscriptionOptions as n, MutationEventType as o, QueryTimeToLive as p, Level$1 as r, PersistenceClient as s, DebounceOptions as t, QueryConfigRecord as u, SpookyConfig as v, EventDefinition as w, StoreType as x, SpookyQueryResult as y };
+export { Sp00kyQueryResultPromise as A, LocalStore as B, ReconnectConfig as C, RunOptions as D, RegistrationTimings as E, SyncHealthConfig as F, SyncEventSystem as G, DatabaseEventSystem as H, SyncHealthStatus as I, EventDefinition as K, TimingPhase as L, StorageHealthStatus as M, StoreType as N, Sp00kyConfig as O, SyncHealth as P, UpdateOptions as R, QueryUpdateCallback as S, RecordVersionDiff as T, DatabaseEventTypes as U, SealedQuery as V, Logger$1 as W, QueryState as _, MATERIALIZATION_SAMPLE_WINDOW as a, QueryTimeToLive as b, MutationEventType as c, PinoTransmit as d, PreloadOptions as f, QueryHash as g, QueryConfigRecord as h, Level$1 as i, StorageHealth as j, Sp00kyQueryResult as k, PersistenceClient as l, QueryConfig as m, DebounceOptions as n, MutationCallback as o, PreloadRefresh as p, EventSystem as q, EventSubscriptionOptions as r, MutationEvent as s, ConnectionState as t, PhaseStat as u, QueryStatus as v, RecordVersionArray as w, QueryTimings as x, QueryStatusCallback as y, UpEvent as z };