@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.320

package/dist/types.d.ts

@@ -1,7 +1,142 @@
-import { RecordId } from "surrealdb";
-import { RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
+import { AccessDefinition, ColumnSchema, QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, TypeNameToTypeMap, WhereNode } from "@spooky-sync/query-builder";
+import { RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
 import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
 
+//#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/impersonation-banner.d.ts
+/**
+ * Restyling of the built-in banner. Every field is optional; anything unset
+ * keeps the default. Colours are plain CSS values, so a project can pass its
+ * own tokens (`var(--brand-warning)`) as long as they resolve at the document
+ * level.
+ */
+interface ImpersonationBannerTheme {
+  /** Height of the warning bar above the page. */
+  heightPx?: number;
+  /** Gutter left, right and below the page. `0` frames only from the top. */
+  insetPx?: number;
+  /** Radius of the framed page's corners. `0` squares them off. */
+  radiusPx?: number;
+  /** The backdrop behind the page. Any CSS `background` value. */
+  background?: string;
+  /** Colour of the warning text on the backdrop. */
+  text?: string;
+  /** Background of the Stop button. */
+  accent?: string;
+  /** Text colour of the Stop button. */
+  accentText?: string;
+  /** Label for the Stop button. Defaults to `Stop`. */
+  stopLabel?: string;
+  /** The warning sentence. Defaults to `Impersonating <target> as <admin>`.
+   *  Wrap a run in `**` to emphasise it; the result is text, never markup. */
+  label?: (info: ImpersonationInfo) => string;
+  /** Keep the bar but leave the page's own layout completely alone. The CSS
+   *  variable is still published, so the app can do its own offset. */
+  noPageShift?: boolean;
+}
+interface ImpersonationBannerConfig {
+  /**
+   * - `'default'` renders the built-in banner.
+   * - `'custom'` leaves the page alone so the app can render its own from
+   *   `useImpersonation()` / `auth.subscribeImpersonation`. Acknowledge it
+   *   with `client.acknowledgeImpersonationBanner()` while it is on screen;
+   *   if nothing acknowledges within {@link CUSTOM_BANNER_GRACE_MS}, the
+   *   built-in banner appears, on the assumption that the custom one failed
+   *   to render rather than that nobody should be warned.
+   * - `'none'` renders nothing, ever. The app takes over responsibility for
+   *   telling whoever is looking at the page that it is not their session.
+   */
+  mode?: 'default' | 'custom' | 'none';
+  /** Restyle the built-in banner (also used if `custom` falls back). */
+  theme?: ImpersonationBannerTheme;
+}
+//#endregion
 //#region src/events/index.d.ts
 /**
  * Utility type to define the payload structure of an event.
@@ -123,35 +258,1083 @@ declare class EventSystem<E extends EventTypeMap> {
   private broadcastEvent;
 }
 //#endregion
+//#region src/utils/surql.d.ts
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+//#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/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;
+  /**
+   * Delete a bucket's persisted store. Never the open one. OPTIONAL and
+   * best-effort: used to remove an impersonated user's data from the admin's
+   * device once the impersonation ends.
+   */
+  dropBucket?(bucketId: string): Promise<void>;
+  /** 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/services/logger/index.d.ts
 type Logger$1 = Logger;
+/** One line the logger wrote, as the DevTools Logs tab and the MCP read it. */
+interface CapturedLog {
+  /** Monotonic for the page's lifetime; a reader resumes after the last one it holds. */
+  seq: number;
+  time: number;
+  /** Pino's numeric level: 10 trace … 60 fatal. */
+  level: number;
+  msg: string;
+  /** The whole log object as JSON (what the console printed), capped at {@link LogTap.LINE_MAX}. */
+  line: string;
+}
+interface LogRead {
+  entries: CapturedLog[];
+  /** `seq` of the newest captured line; pass it back as `after` to resume. */
+  head: number;
+  /** Lines after `after` the ring overwrote before they were read (cleared ones excluded). */
+  dropped: number;
+  consoleLevel: Level;
+  captureLevel: Level;
+}
+/**
+ * JSON for a log object that can never throw into the call site: Errors keep
+ * their message and stack (plain `JSON.stringify` prints `{}`), bigints become
+ * strings, and a cycle prints `[Circular]` instead of throwing.
+ */
+
+/**
+ * The page-side log buffer behind the DevTools Logs tab. Always on and
+ * bounded: a line costs the JSON the console write produces anyway, and a
+ * panel opened after boot still sees the boot.
+ *
+ * It also owns the logger's level. The console prints at the configured level
+ * only; `setCaptureLevel` changes what is RECORDED (debug without flooding the
+ * console), live on every child logger, and keeps it for this tab's session so
+ * a reload captures its boot at that level too.
+ */
+declare class LogTap {
+  readonly consoleLevel: Level;
+  static readonly CAPACITY = 500;
+  static readonly LINE_MAX = 4000;
+  private readonly ring;
+  private seq;
+  /** `seq` at the last `clear()`: lines up to here are gone on purpose, not dropped. */
+  private clearedThrough;
+  private readonly listeners;
+  private readonly loggers;
+  private captureLevelValue;
+  constructor(consoleLevel: Level);
+  /** `seq` of the newest captured line. */
+  get head(): number;
+  get captureLevel(): Level;
+  /** What pino has to produce for both the console and the buffer. */
+  get effectiveLevel(): Level;
+  /** Whether the console prints a line at this numeric level. */
+  printsToConsole(level: number): boolean;
+  /** Remember a logger (the root and every child) so a level change reaches it. */
+  track(logger: Logger$1): void;
+  setCaptureLevel(level: Level): void;
+  record(o: Record<string, unknown>, line: string): void;
+  /** Lines after `after` (0 = everything still buffered), oldest first. */
+  read(after?: number, limit?: number): LogRead;
+  clear(): void;
+  /** Called synchronously inside the log call: keep it cheap, never log from it. */
+  subscribe(cb: () => void): () => void;
+}
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
+//#region src/services/database/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>;
+  /**
+   * 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/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";
+  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;
+  /**
+   * Every `session::id()` this page's sockets have had, oldest first.
+   *
+   * The server stamps a view's `subscribers` entry with the session that
+   * registered or heartbeated it, and every socket (an SDK reconnect, a
+   * supervisor revive) is a new session. The pagehide release goes over HTTP,
+   * whose own session id matches none of them, so it names these instead. Kept
+   * for the page, not the socket: a view registered before a reconnect still
+   * carries the old id until its next heartbeat.
+   */
+  private sessionIdsSeen;
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  /** See {@link sessionIdsSeen}. */
+  sessionIds(): readonly string[];
+  /**
+   * Ask the socket that just connected for its session id. Straight to the
+   * SDK: it needs no namespace or identity, so it need not wait behind an
+   * in-flight connect or take a slot from the query queue.
+   */
+  private recordSessionId;
+  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.
+   *
+   * The statement runs in a fresh HTTP session: `session::id()` there is a new
+   * id, not this page's socket's, so anything keyed on it must be passed the
+   * ids from {@link sessionIds} instead.
+   */
+  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/modules/auth/events/index.d.ts
+declare const AuthEventTypes: {
+  readonly AuthStateChanged: "AUTH_STATE_CHANGED";
+  readonly ImpersonationChanged: "IMPERSONATION_CHANGED";
 };
-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 AuthEventTypeMap = {
+  [AuthEventTypes.AuthStateChanged]: EventDefinition<typeof AuthEventTypes.AuthStateChanged, string | null>;
+  [AuthEventTypes.ImpersonationChanged]: EventDefinition<typeof AuthEventTypes.ImpersonationChanged, ImpersonationInfo | null>;
 };
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
+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;
+}
+/** What a sign-out hook sees: the session that is about to end. */
+interface SignOutContext {
+  /** `table:id` of the signed-in record, or null. */
+  userId: string | null;
+  token: string | null;
+  /** The session is an admin impersonation (its token is the target's). */
+  impersonating: boolean;
+}
+type SignOutHook = (ctx: SignOutContext) => Promise<void> | void;
+/** Upper bound on the before-sign-out hooks, so a dead socket never holds a sign-out. */
+declare const SIGN_OUT_HOOK_TIMEOUT_MS = 2000;
+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;
+declare class AuthService<S extends SchemaStructure> {
+  private schema;
+  private remote;
+  private persistenceClient;
+  private logger;
+  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;
+  private signOutHooks;
+  /** 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;
+  /** The way back to the admin in flight. The Stop button, the session poll,
+   *  a refused renewal and a rejected check can all end an impersonation, and
+   *  they share this one: a second stop running beside the first found the
+   *  admin token already taken and signed the admin out. */
+  private stopping;
+  /** A token renewal in flight, which a stop waits out (see `renewImpersonation`). */
+  private renewing;
+  private impersonationTimers;
+  get eventSystem(): AuthEventSystem;
+  constructor(schema: S, remote: RemoteDatabaseService, persistenceClient: PersistenceClient, logger: Logger$1);
+  init(): Promise<void>;
+  getAccessDefinition<Name extends keyof S['access']>(name: Name): AccessDefinition | undefined;
+  /**
+   * Subscribe to auth state changes.
+   * callback is called immediately with current value and whenever validation status changes.
+   */
+  subscribe(cb: (userId: string | null) => void): () => void;
+  /**
+   * Run `hook` at the start of every sign-out, while the token and the socket
+   * still belong to the leaving user (Web Push removes this device's
+   * subscription here). Hooks are best-effort: they run in parallel, errors
+   * are swallowed, and the sign-out goes on after
+   * {@link SIGN_OUT_HOOK_TIMEOUT_MS} whatever they are doing. Returns a disposer.
+   */
+  onBeforeSignOut(hook: SignOutHook): () => void;
+  private runSignOutHooks;
+  /**
+   * The signed-in user as subscribers see it: the raw `table:id` string, the
+   * way the token's `ID` claim spells it. `currentUser.id` is that string while
+   * the session is restored from the token and the server's `RecordId` once
+   * `check()` has answered, and the two must announce as the same user: every
+   * subscriber that compares ids (feature flags, app release) took the switch
+   * for a new principal and reset, so flag-gated UI blinked off and back on a
+   * few seconds into every reload. A `RecordId`'s own `toString()` will not do
+   * either, as it escapes ids like `user:⟨5abc⟩` that the claim spells raw.
+   */
+  private announcedUserId;
+  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>;
+  private leaveImpersonation;
+  /** Re-sign the impersonation token before it expires. */
+  renewImpersonation(): Promise<void>;
+  private applyRenewal;
+  /** 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>;
+  /** Hold a session the server accepted without its user row: the id comes
+   *  from the token, as on a warm boot. A token naming no user is refused. */
+  private keepAcceptedSession;
+  /**
+   * 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/push/types.d.ts
+/**
+ * Web Push wire types shared by the page (`db.webPush`), the service worker
+ * bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+ * dependency-free helpers, safe in any context.
+ *
+ * `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+ * `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+ */
+/** Payload format version this build understands. */
+declare const PUSH_PAYLOAD_VERSION = 1;
+type PushPayloadKind = 'rule' | 'message';
+type PushOp = 'create' | 'update' | 'delete';
+type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+/** One button on a notification (`NotificationAction` plus a per-action `url`). */
+interface PushNotificationAction {
+  action: string;
+  title: string;
+  icon?: string;
+  /** Opened instead of the notification's `url` when this action is clicked. */
+  url?: string;
+  [key: string]: unknown;
+}
+/**
+ * What a content push shows. Every key other than `title` and `url` is passed
+ * to `showNotification` as is, unknown ones included (`vibrate`, `timestamp`,
+ * whatever a browser adds later).
+ */
+interface PushNotification {
+  title?: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  lang?: string;
+  dir?: string;
+  /** Defaults to the push's `topic`. */
+  tag?: string;
+  /** Opened (or focused) on click. */
+  url?: string;
+  requireInteraction?: boolean;
+  renotify?: boolean;
+  silent?: boolean;
+  actions?: PushNotificationAction[];
+  /** Merged into the notification's `data` next to the bridge's own keys. */
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * The JSON every push carries (then RFC 8291 encrypted). `notification`
+ * present: a content push the service worker shows as is. Absent: a
+ * content-free nudge, the app renders from its own data.
+ */
+interface PushPayload {
+  v: number;
+  kind: PushPayloadKind;
+  /** Rule name (`kind: 'rule'`). */
+  rule?: string;
+  /** `_00_push_message` id (`kind: 'message'`). */
+  message?: string;
+  /** The row that fired the rule. */
+  table?: string;
+  id?: string;
+  op?: PushOp;
+  topic?: string;
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  /** Epoch ms when the engine built it. */
+  ts: number;
+}
+/** Page -> service worker: the session to use for live rendering. */
+interface BridgeTokenMessage {
+  type: 'sp00ky:token';
+  token: string;
+  userId: string;
+  /** The SurrealDB endpoint (`wss://host/rpc`), not the push endpoint. */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /** VAPID public key (base64url) the page subscribed with, for `pushsubscriptionchange`. */
+  publicKey?: string;
+  /** This browser's push endpoint, when subscribed. */
+  pushEndpoint?: string;
+}
+/** Page -> service worker: forget the session and close every notification. */
+interface BridgeSignOutMessage {
+  type: 'sp00ky:signout';
+}
+/** Service worker -> page messages. */
+type WebPushClientMessage = /** A push arrived while this page was visible, so nothing was shown. */
+{
+  type: 'sp00ky:push';
+  payload: PushPayload;
+}
+/** A notification was clicked and the bridge was told to route in-app. */ | {
+  type: 'sp00ky:navigate';
+  url: string;
+  payload?: PushPayload;
+  action?: string;
+}
+/** The browser rotated the push subscription; the page should `sync()`. */ | {
+  type: 'sp00ky:subscriptionchange';
+  endpoint?: string;
 };
-type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+
+/** A payload this build can act on (`v` known, `kind` set). */
+declare function isPushPayload(value: unknown): value is PushPayload;
+//#endregion
+//#region src/modules/web-push/index.d.ts
+/**
+ * `db.webPush`: this browser's Web Push subscription, on the page.
+ *
+ * Every server call is a `fn::push::*` function over the client's remote
+ * connection (see `apps/cli/src/push_tables.surql`). Nothing here touches a
+ * browser API at import time, and every method answers "unsupported" instead
+ * of throwing where there is no window, service worker or push manager
+ * (SSR, Node, workers, iOS Safari outside a home-screen app).
+ */
+interface WebPushConfig {
+  /**
+   * Registered with `navigator.serviceWorker.register(url)` when the page has
+   * no service worker yet. Leave unset when the app (or vite-plugin-pwa)
+   * registers its own.
+   */
+  serviceWorkerUrl?: string;
+  /**
+   * Reconcile this browser's subscription after sign-in (see `sync()`): a
+   * rotated key, a browser that dropped the subscription or a server row that
+   * went away are repaired without a prompt. Default `true`.
+   */
+  autoSync?: boolean;
+  /**
+   * Let `sync()` subscribe a signed-in user whenever notification permission
+   * is already granted, even if they never subscribed on this browser.
+   * Default `false`: only a user who called `subscribe()` here is restored.
+   */
+  autoResubscribe?: boolean;
+  /**
+   * Remove this device's subscription for the user on `signOut()` (before the
+   * token is dropped, bounded by a short timeout). Default `true`.
+   */
+  unsubscribeOnSignOut?: boolean;
+  /**
+   * Post the session token to the app's service worker whenever it changes,
+   * while notifications are allowed, so `@spooky-sync/core/sw` can render from
+   * live data. Never posts an impersonation token. Default `true`.
+   */
+  bridge?: boolean;
+}
+type WebPushUnsupportedReason = 'no-window' | 'insecure-context' | 'no-service-worker' | 'no-push-manager' | 'no-notification' | 'ios-not-installed';
+interface WebPushSupport {
+  supported: boolean;
+  permission: NotificationPermission | 'unsupported';
+  reason?: WebPushUnsupportedReason;
+}
+interface WebPushInfo {
+  /** A host with push on has published its key. */
+  enabled: boolean;
+  /** VAPID public key (base64url), the browser's `applicationServerKey`. */
+  publicKey?: string;
+  /** Id of that key. */
+  kid?: string;
+  /**
+   * Every kind of device the project reaches: `web` once a VAPID key is
+   * published, `apns` / `fcm` when `push.apns` / `push.fcm` are configured.
+   */
+  providers?: PushDeviceKind[];
+}
+/** How a device is reached: a browser (Web Push), APNs or FCM. */
+type PushDeviceKind = 'web' | 'apns' | 'fcm';
+interface WebPushDevice {
+  /** `_00_push_subscription:<id>` */
+  id: string;
+  /** Web: the push service URL. Native: `<kind>:<token>`. */
+  endpoint: string;
+  /** Rows the Flutter / native side registered are `apns` or `fcm`. */
+  kind: PushDeviceKind;
+  /** `web`, `ios`, `android` or `macos`. */
+  platform?: string;
+  /** Native: bundle id / package name. */
+  appId?: string;
+  /** APNs: `sandbox` or `production`. */
+  environment?: string;
+  /** Key id a web device subscribed under (empty for native ones). */
+  kid: string;
+  label?: string;
+  userAgent?: string;
+  /** Rule names this device receives; undefined = every rule. */
+  rules?: string[];
+  meta?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+  lastOkAt?: Date;
+  lastError?: string;
+  failures: number;
+  disabledAt?: Date;
+  disabledReason?: string;
+  /** Subscribed under the current key (pushes reach it). Undefined when unknown. */
+  current?: boolean;
+  /** This browser. */
+  thisDevice: boolean;
+}
+interface WebPushSubscribeOptions {
+  /** Defaults to the page's service worker registration (`serviceWorker.ready`). */
+  registration?: ServiceWorkerRegistration;
+  /** Shown in the device list ("Work laptop"). */
+  label?: string;
+  /** Rule names this device wants. Omitted or empty: every rule. */
+  rules?: string[];
+  /** Free-form app data about the device. */
+  meta?: Record<string, unknown>;
+  /** Ask for notification permission when it is still `default`. Default `true`. Call from a user gesture. */
+  requestPermission?: boolean;
+}
+interface WebPushUnsubscribeOptions {
+  /** Remove every device of the user, not only this one. */
+  all?: boolean;
+  /** Keep the browser's PushSubscription (only the server row goes). */
+  keepBrowserSubscription?: boolean;
+}
+interface WebPushSyncOptions {
+  registration?: ServiceWorkerRegistration;
+  /** Overrides `webPush.autoResubscribe` for this call. */
+  autoResubscribe?: boolean;
+}
+/**
+ * What `sync()` did. `ok`: nothing to repair. `resubscribed`: the browser
+ * subscription was (re)created. `registered`: the server row was re-created.
+ * The rest say why nothing happened.
+ */
+type WebPushSyncStatus = 'ok' | 'resubscribed' | 'registered' | 'unsupported' | 'signed-out' | 'impersonating' | 'permission-default' | 'permission-denied' | 'not-subscribed' | 'disabled' | 'no-registration' | 'error';
+interface WebPushUpdateOptions {
+  label?: string;
+  /** Rule names; `null` or `[]` resets the device to every rule. */
+  rules?: string[] | null;
+  meta?: Record<string, unknown>;
+}
+/** A push to yourself (`fn::push::notify`). */
+interface WebPushMessageInput {
+  /** Omit for a content-free nudge. */
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  topic?: string;
+  urgency?: PushUrgency;
+  /** Push-service TTL, seconds. */
+  ttl?: number;
+  /** In the future: scheduled. */
+  sendAt?: Date | string | number;
+}
+interface WebPushMessage {
+  /** `_00_push_message:<id>` */
+  id: string;
+  status: string;
+  sendAt?: Date;
+  createdAt?: Date;
+}
+type WebPushErrorCode = 'unsupported' | 'signed-out' | 'impersonating' | 'disabled' | 'permission-denied' | 'permission-default' | 'no-registration' | 'not-subscribed' | 'subscribe-failed' | 'server';
+declare class WebPushError extends Error {
+  readonly code: WebPushErrorCode;
+  readonly cause?: unknown | undefined;
+  constructor(code: WebPushErrorCode, message: string, cause?: unknown | undefined);
+}
+interface WebPushAuthPort {
+  readonly token: string | null;
+  readonly currentUser: {
+    id?: unknown;
+  } | null;
+  readonly isAuthenticated: boolean;
+  readonly impersonation: unknown;
+  subscribe(cb: (userId: unknown) => void): () => void;
+  onBeforeSignOut(hook: (ctx: SignOutContext) => Promise<void> | void): () => void;
+}
+interface WebPushRemotePort {
+  query<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+}
+/** Browser globals, read at call time. Injectable for tests. */
+interface WebPushGlobals {
+  window?: unknown;
+  navigator?: Navigator & {
+    standalone?: boolean;
+  };
+  Notification?: {
+    permission: NotificationPermission;
+    requestPermission(cb?: (p: NotificationPermission) => void): Promise<NotificationPermission> | void;
+  };
+  isSecureContext?: boolean;
+  matchMedia?: (query: string) => {
+    matches: boolean;
+  };
+  PushManager?: unknown;
+}
+interface WebPushModuleDeps {
+  remote: WebPushRemotePort;
+  auth: WebPushAuthPort;
+  persistence: PersistenceClient;
+  logger: Logger$1;
+  database: {
+    endpoint?: string;
+    namespace: string;
+    database: string;
+  };
+  /** Transport state; auto-sync waits for `connected`. */
+  connection?: {
+    subscribe(cb: (state: string) => void): () => void;
+  };
+  config?: WebPushConfig;
+  globals?: () => WebPushGlobals;
+}
+declare const PUSH_ENDPOINT_KEY = "sp00ky_push_endpoint";
+/** `table:id` of a record id value, without the SDK's escaping. */
+
+/** Where Web Push can work, from the given globals. */
+declare function detectWebPushSupport(g: WebPushGlobals): WebPushSupport;
+declare class WebPushModule {
+  private readonly deps;
+  private readonly logger;
+  private readonly config;
+  private readonly globals;
+  private infoCache;
+  private lastInfo;
+  private readonly bridges;
+  private readonly disposers;
+  private syncedFor;
+  private syncTimer;
+  private attached;
+  constructor(deps: WebPushModuleDeps);
+  /**
+   * Wire sign-out, auto-sync and the token bridge. Called by the client once;
+   * a no-op beyond the sign-out hook where push is unsupported.
+   */
+  attach(): () => void;
+  dispose(): void;
+  support(): WebPushSupport;
+  /** Is push on for this deployment, and with which key. Cached; `refresh` re-reads. */
+  info(options?: {
+    refresh?: boolean;
+  }): Promise<WebPushInfo>;
+  /** This browser holds a push subscription registered for the signed-in user. No server round trip. */
+  isSubscribed(): Promise<boolean>;
+  /** The user's devices, this one marked. */
+  devices(): Promise<WebPushDevice[]>;
+  /**
+   * Ask for permission (when still `default`), subscribe this browser with the
+   * deployment's key and register it for the signed-in user. Call it from a
+   * click handler: permission prompts need a user gesture.
+   */
+  subscribe(options?: WebPushSubscribeOptions): Promise<WebPushDevice>;
+  /** Remove this device (or every device, `all`) for the signed-in user. Returns how many rows went. */
+  unsubscribe(options?: WebPushUnsubscribeOptions): Promise<number>;
+  /**
+   * Reconcile after sign-in (runs by itself with `autoSync`). Needs granted
+   * permission and a user who subscribed on this browser (or
+   * `autoResubscribe`). Repairs a missing browser subscription, one made with
+   * a rotated key, and a missing, disabled or stale server row. Never throws.
+   */
+  sync(options?: WebPushSyncOptions): Promise<WebPushSyncStatus>;
+  /** Change this device's label, rule filter or meta. */
+  update(options: WebPushUpdateOptions): Promise<WebPushDevice | null>;
+  /** Push to yourself, now or at `sendAt` (reminders). Omit `notification` for a nudge. */
+  notify(message: WebPushMessageInput): Promise<WebPushMessage>;
+  /** Cancel a scheduled message. `true` when it was still pending. */
+  cancel(id: string | RecordId$1): Promise<boolean>;
+  /** A visible test notification to every device of the user. */
+  test(options?: {
+    title?: string;
+    body?: string;
+  }): Promise<WebPushMessage>;
+  /**
+   * Post the session to the service worker now and whenever the token
+   * changes (`{ type: 'sp00ky:token', token, userId, endpoint, namespace,
+   * database }`). Never posts an impersonation token. Returns a disposer.
+   * With `webPush.bridge` (the default) this already runs while notification
+   * permission is granted.
+   */
+  bridge(registration?: ServiceWorkerRegistration): () => void;
+  /** Messages from the push service worker (`sp00ky:push` while visible, `sp00ky:navigate`, ...). */
+  onMessage(cb: (message: WebPushClientMessage) => void): () => void;
+  private userId;
+  private assertSignedIn;
+  private assertNotImpersonating;
+  private call;
+  private listRaw;
+  private register;
+  private readStored;
+  private writeStored;
+  /** The page's registration: given, existing, registered from config, or `ready` within `waitMs`. */
+  private registration;
+  /** This browser's subscription, without waiting for a worker. */
+  private currentSubscription;
+  private thisEndpoint;
+  private postToWorker;
+  private startBridge;
+  private refreshBridges;
+  private tokenMessage;
+  /** Sign-out hook: tell the worker, and drop this device's row for the user. Bounded. */
+  private beforeSignOut;
+}
 //#endregion
 //#region src/types.d.ts
 /**
@@ -192,6 +1375,24 @@ 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.
  */
@@ -220,29 +1421,412 @@ interface Sp00kyConfig<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;
+  /**
+   * How the "you are impersonating" warning is shown while an admin acts as
+   * another user. The built-in one (hazard stripes at the top, the page
+   * shifted down onto them) needs no configuration; this is for restyling it,
+   * or replacing it with the app's own.
+   *
+   * See `ImpersonationBannerConfig`. Replacing it does not mean "no warning":
+   * if the app has not acknowledged its own banner shortly after impersonation
+   * starts, the built-in one appears anyway.
+   */
+  impersonationBanner?: ImpersonationBannerConfig;
+  /**
+   * 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;
+  /**
+   * Web Push on this page (`client.webPush`, `db.webPush`). Everything is
+   * optional and the defaults need no service worker configuration here:
+   * `autoSync` (repair this browser's subscription after sign-in),
+   * `unsubscribeOnSignOut` (drop this device's subscription on `signOut()`),
+   * `bridge` (post the session to the service worker for live rendering) are
+   * on; `serviceWorkerUrl` registers a worker when the app does not.
+   * See the `push-notifications` docs page.
+   */
+  webPush?: WebPushConfig;
+}
+/** 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 +1835,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 +1852,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 +1909,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 +1950,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 +2064,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 +2083,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.
@@ -354,6 +2113,20 @@ interface DebounceOptions {
   key?: 'recordId' | 'recordId_x_fields';
   /** The debounce delay in milliseconds. */
   delay?: number;
+  /**
+   * Keep the pending patch across a reload or a closed tab. Default `true`.
+   *
+   * Every call also writes the merged patch to `_00_pending_writes`, in the
+   * same local transaction as the row itself. When the page is hidden (tab
+   * switch, reload, close, app sent to the background) every pending patch is
+   * moved into the outbox and pushed at once instead of waiting out `delay`.
+   * A page that dies before that finishes leaves the patch in the store, and
+   * the next boot moves it into the outbox.
+   *
+   * `false` keeps the patch in memory only, so whatever is still inside its
+   * delay is lost on reload. Meant for throwaway state like a cursor position.
+   */
+  flushOnHide?: boolean;
 }
 //#endregion
-export { Logger$1 as C, UpdateOptions as S, EventSystem as T, RunOptions as _, MutationEvent as a, Sp00kyQueryResultPromise 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, Sp00kyConfig as v, EventDefinition as w, StoreType as x, Sp00kyQueryResult as y };
+export { WebPushSubscribeOptions as $, RunOptions as A, Logger$1 as At, SyncHealthStatus as B, SESSION_POLL_MS as Bt, QueryTimeToLive as C, SignOutHook as Ct, RecordVersionArray as D, createAuthEventSystem as Dt, ReconnectConfig as E, AuthEventTypes as Et, StorageHealth as F, IMPERSONATION_ACCESS as Ft, WebPushConfig as G, sameImpersonation as Gt, UpdateOptions as H, decodeTokenClaims as Ht, StorageHealthStatus as I, ImpersonationInfo as It, WebPushErrorCode as J, WebPushDevice as K, StoreType as L, ImpersonationTimerHost as Lt, Sp00kyConfig as M, SealedQuery as Mt, Sp00kyQueryResult as N, EventDefinition as Nt, RecordVersionDiff as O, RemoteDatabaseService as Ot, Sp00kyQueryResultPromise as P, EventSystem as Pt, WebPushModule as Q, SyncHealth as R, ImpersonationTimers as Rt, QueryStatusCallback as S, SignOutContext as St, QueryUpdateCallback as T, AuthEventTypeMap as Tt, PUSH_ENDPOINT_KEY as U, impersonationFromToken as Ut, TimingPhase as V, TokenClaims as Vt, PushDeviceKind as W, renewDelayMs as Wt, WebPushMessage as X, WebPushInfo as Y, WebPushMessageInput as Z, QueryConfig as _, isPushPayload as _t, Level$1 as a, WebPushUpdateOptions as at, QueryState as b, ImpersonationCandidate as bt, MutationCallback as c, BridgeTokenMessage as ct, PersistenceClient as d, PushNotificationAction as dt, WebPushSupport as et, PhaseStat as f, PushOp as ft, QueryAuthorityCallback as g, WebPushClientMessage as gt, PreloadRefresh as h, PushUrgency as ht, InlineRow as i, WebPushUnsupportedReason as it, ServerViewMeta as j, LocalStore as jt, RegistrationTimings as k, LogTap as kt, MutationEvent as l, PUSH_PAYLOAD_VERSION as lt, PreloadOptions as m, PushPayloadKind as mt, DebounceOptions as n, WebPushSyncStatus as nt, MATERIALIZATION_SAMPLE_WINDOW as o, detectWebPushSupport as ot, PinoTransmit as p, PushPayload as pt, WebPushError as q, EventSubscriptionOptions as r, WebPushUnsubscribeOptions as rt, MembershipOutcome as s, BridgeSignOutMessage as st, ConnectionState as t, WebPushSyncOptions as tt, MutationEventType as u, PushNotification as ut, QueryConfigRecord as v, ActiveImpersonation as vt, QueryTimings as w, AuthEventSystem as wt, QueryStatus as x, SIGN_OUT_HOOK_TIMEOUT_MS as xt, QueryHash as y, AuthService as yt, SyncHealthConfig as z, ORIGIN_TOKEN_KEY as zt };