@spooky-sync/core 0.0.1-canary.25 → 0.0.1-canary.255

package/dist/types.d.ts

@@ -1,6 +1,5 @@
-import { RecordId } from "surrealdb";
-import { RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
-import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
+import { QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
+import { Level as Level$1, LoggerOptions } from "pino";
 
 //#region src/events/index.d.ts
 /**
@@ -123,35 +122,222 @@ declare class EventSystem<E extends EventTypeMap> {
   private broadcastEvent;
 }
 //#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
+//#region src/utils/surql.d.ts
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
+//#region src/services/database/events/index.d.ts
+declare const DatabaseEventTypes: {
+  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
+  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
 };
-type UpdateEvent = {
-  type: 'update';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  beforeRecord?: Record<string, unknown>;
-  options?: PushEventOptions;
-};
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
+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 UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
+type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
+//#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;
+  /**
+   * Every cached row's `(id, _00_rv)` per table, ids in stable `table:id`
+   * form. The in-browser circuit primes and reconciles itself from this on
+   * boot instead of re-downloading the working set. OPTIONAL: an engine
+   * without it boots the circuit empty, as before.
+   */
+  scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Circuit snapshot storage, keyed. Lives in the same durable store as the
+   * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and
+   * readable by follower tabs over the port transport. OPTIONAL: an engine
+   * without it primes from `scanVersions` alone.
+   */
+  getSnapshot?(key: string): Promise<StoredSnapshot | null>;
+  putSnapshot?(key: string, bytes: Uint8Array, meta: SnapshotMeta): Promise<void>;
+  deleteSnapshot?(key: string): Promise<void>;
+}
+/** Describes a stored circuit snapshot; what decides whether it is usable. */
+interface SnapshotMeta {
+  /** Bump when the wire shape the circuit reads changes. */
+  formatVersion: number;
+  /** Hash of the schema the rows were projected under. */
+  schemaHash: string;
+  savedAt: number;
+  /** Highest `_00_rv` per table at save time (diagnostics). */
+  maxRv?: Record<string, number>;
+  [key: string]: unknown;
+}
+interface StoredSnapshot {
+  bytes: Uint8Array;
+  meta: SnapshotMeta;
+}
+/** 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/types.d.ts
 /**
@@ -192,22 +378,40 @@ 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 {
+  /** Abort a cold preload that is still waiting for the server. */
+  signal?: AbortSignal;
+  /** @deprecated Preload is a registered query now; a warm preload never refetches by itself. Ignored. */
+  refresh?: PreloadRefresh;
+  /** @deprecated Ignored. */
+  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,29 +424,391 @@ 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;
+    /**
+     * Deadline (ms) for every LOCAL store operation (a SQLite worker round trip,
+     * or a query on the in-process surrealdb engine). Local ops are serialized
+     * too, and one that never answered - a worker starved behind a long select,
+     * a lock verification with no clock - left every `db.create`/`db.update`
+     * promise pending for the tab's lifetime. On expiry the call rejects with
+     * `LocalOpTimeoutError` (the op itself keeps running in the engine and is
+     * not retried). `0` disables. Defaults to `30_000`.
+     */
+    localOpTimeoutMs?: 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's store as a snapshot in the local
+   * store, so a reload restores it and only steps in what changed since.
+   * Defaults to `true` under `localEngine: 'sqlite'` (the OPFS-backed store
+   * can hold the bytes) and `false` otherwise.
+   *
+   * Without a snapshot the circuit is primed by reading every cached row back
+   * out of the local store; either way a reload never re-downloads the working
+   * set, which is what an empty circuit used to force: every id in the
+   * server's list_ref classified as missing.
+   *
+   * Snapshots are store-only (views are re-registered per session) and written
+   * on a checkpoint interval ({@link circuitCheckpointMs}) and when the page
+   * goes hidden, never per ingest or per query registration.
+   */
+  persistCircuit?: boolean;
+  /**
+   * Checkpoint interval in milliseconds for {@link persistCircuit}. Defaults to
+   * 30000. Ignored when `persistCircuit` is off.
+   */
+  circuitCheckpointMs?: number;
+  /**
+   * Keep only the fields registered queries evaluate (filter predicates, join
+   * keys, sort keys, plus `id`/`_00_rv`) per row in the in-browser circuit.
+   * Default `true`. The circuit only ever reads those fields; bodies are
+   * rendered from the local store. Measured on 7700 rows with 20 KB bodies:
+   * the wasm heap peak went from ~500 MB to ~24 MB and the snapshot from
+   * 156 MB to 1.2 MB. A query that evaluates a field earlier rows were kept
+   * without has that field merged in from the local store on registration.
+   */
+  circuitProjection?: boolean;
   /** 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;
+  /**
+   * Carry the changed row's body on the LIVE notification instead of going
+   * back for it.
+   *
+   * The client holds exactly one live subscription, on its `_00_list_ref`
+   * table, and today it is a doorbell: the notification is reduced to the
+   * query hash and the row is then pulled with `SELECT * FROM $ids`. The edge
+   * is a real graph edge, so `FETCH out` makes SurrealDB resolve the row into
+   * the notification and the body fetch disappears.
+   *
+   * The push stays advisory: the body is landed exactly the way a fetched body
+   * is (store write, circuit ingest, version recorded), so a notification the
+   * server drops costs nothing but the old round trip. Membership is still
+   * read back; only the body fetch is saved.
+   *
+   * Default `false`. The cost is wire bytes: one edit bumps the edge in every
+   * view holding the row, and under `FETCH` each of those notifications
+   * carries its own full copy of the body.
+   */
+  liveInlineBodies?: 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;
+  /**
+   * Opt in to the raw remote escape hatches (`useRemote`, `remoteQuery`,
+   * `queryRaw`) when the generated schema's `policy.queryAllowlist` is `warn`
+   * or `enforce`. With the allowlist on, the server only accepts query shapes
+   * that `spky generate` collected from the query builder, so a hand-written
+   * SurrealQL string cannot be allowlisted and these methods throw unless this
+   * flag is `true`. Defaults to `false`.
+   */
+  allowRawRemote?: 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;
+  /**
+   * Max time a single down event (`register`/`sync`/`cleanup`) may take before
+   * it is retried. Mirror of {@link pushTimeoutMs} for the read side.
+   * Defaults to 30000; `0` disables the timeout.
+   */
+  downTimeoutMs?: 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;
+/**
+ * One changed row delivered inline on a LIVE notification, when the
+ * subscription was opened with the body joined on (see
+ * {@link Sp00kyConfig.liveInlineBodies}). `version` is the edge's `version`,
+ * i.e. the same number the membership read would have reported for this row.
+ */
+interface InlineRow {
+  id: string;
+  version: number;
+  record: Record<string, unknown>;
+}
 type RecordVersionArray = Array<[string, number]>;
 /**
  * Represents the difference between two record version sets.
@@ -251,16 +817,16 @@ type RecordVersionArray = Array<[string, number]>;
 interface RecordVersionDiff {
   /** List of records added. */
   added: Array<{
-    id: RecordId$1<string>;
+    id: RecordId<string>;
     version: number;
   }>;
   /** List of records updated. */
   updated: Array<{
-    id: RecordId$1<string>;
+    id: RecordId<string>;
     version: number;
   }>;
   /** List of record IDs removed. */
-  removed: RecordId$1<string>[];
+  removed: RecordId<string>[];
 }
 /**
  * Configuration for a specific query instance.
@@ -268,15 +834,53 @@ interface RecordVersionDiff {
  */
 interface QueryConfig {
   /** The unique ID of the query config record. */
-  id: RecordId$1<string>;
+  id: RecordId<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_view` 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.
+   *
+   * On a cold start it is seeded from the durable `_00_view` row when that
+   * row is non-empty, or empty but `confirmed` (the server reported zero rows
+   * for the query). An unconfirmed empty row is ignored, so a device poisoned
+   * by an old client that mirrored unflushed reads still self-heals.
+   */
+  membershipKnown?: boolean;
+  /**
+   * Key of this query's durable `_00_view` 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 +891,39 @@ 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';
+/**
+ * What the server's `_00_query` row says about a view, read alongside its
+ * `_00_list_ref` edges (registration, the poll, a targeted re-read).
+ *
+ * - `present: false`: the row is not there (or not readable). The SSP no
+ *   longer has this view: a TTL sweep, an SSP reset, a scheduler wipe. An
+ *   empty edge set read at the same time is NOT "no rows", it is "no view".
+ * - `state: 'materializing'`: the SSP has (re)computed the set and its edges
+ *   are in flight; an empty read is "not landed yet".
+ * - `state: 'ready'`: the edges are committed (flipped in the same
+ *   transaction), so `rowCount === 0` with no edges is a real empty result.
+ * - `state: null`: a server that predates the marker; only `rowCount` can be
+ *   used, with its `> 0` = flush window / `0` = empty ambiguity.
+ */
+interface ServerViewMeta {
+  present: boolean;
+  /** `_00_query.rowCount`; `null` when unreadable. */
+  rowCount: number | null;
+  state: 'materializing' | 'ready' | null;
+}
+/** Outcome of handing a server id-set to `DataModule.updateQueryRemoteArray`. */
+type MembershipOutcome = 'applied' | 'ignored' | 'view-lost';
 /**
  * Internal state of a live query.
  */
@@ -295,15 +932,112 @@ 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 a server-side membership set has been accepted this session
+   * (`updateQueryRemoteArray`). The `register` down-event is enqueued before
+   * the instant-hydrate, so a hydrate that finishes later must not prime
+   * membership over the authoritative set. Ephemeral. */
+  serverMembership?: boolean;
+  /**
+   * Set when the server's `_00_query` row for this query went missing while
+   * we held membership (TTL sweep, SSP reset, scheduler wipe). The view is
+   * being re-registered; until a readable row comes back, empty reads are
+   * NOT the server's answer and nothing is dropped. Ephemeral.
+   */
+  viewLost?: boolean;
+  /** Last `_00_query.state` read from the server, for DevTools. Ephemeral. */
+  serverState?: 'materializing' | 'ready' | null;
+  /** 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;
+  /** When the last TTL heartbeat for this query was sent (ms epoch); `undefined` before the first. */
+  lastHeartbeatAt?: 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 MutationCallback = (mutations: UpEvent[]) => void;
+type QueryStatusCallback = (status: QueryStatus) => void;
+/**
+ * Observer for a query's authority flips: `true` once server membership is
+ * known for it (registration, poll, durable seed), `false` when it is reset
+ * (bucket switch). What the bindings' `isAuthoritative()` mirrors.
+ */
+type QueryAuthorityCallback = (known: boolean) => void;
+type MutationCallback = (mutations: MutationEvent[]) => void;
 type MutationEventType = 'create' | 'update' | 'delete';
 /**
  * Represents a mutation event (create, update, delete) to be synchronized.
@@ -312,9 +1046,9 @@ interface MutationEvent {
   /** Example: 'create', 'update', or 'delete'. */
   type: MutationEventType;
   /** unique id of the mutation */
-  mutation_id: RecordId$1<string>;
+  mutation_id: RecordId<string>;
   /** The ID of the record being mutated. */
-  record_id: RecordId$1<string>;
+  record_id: RecordId<string>;
   /** The data payload for create/update operations. */
   data?: any;
   /** The full record data (optional context). */
@@ -331,6 +1065,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 +1097,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 { RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, QueryConfig as _, Level$1 as a, QueryState as b, MutationCallback as c, PersistenceClient as d, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, MembershipOutcome as s, ConnectionState as t, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };