@spooky-sync/core 0.0.1-canary.9 → 0.0.1-canary.91

package/dist/index.d.ts

@@ -1,132 +1,10 @@
+import { A as SyncHealthStatus, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, F as SyncEventSystem, I as EventDefinition, L as EventSystem, M as UpdateOptions, N as UpEvent, O as SyncHealth, P as Logger$1, S as RegistrationTimings, T as Sp00kyQueryResult, _ as QueryTimeToLive, a as MutationCallback, b as RecordVersionArray, c as PersistenceClient, d as QueryConfig, f as QueryConfigRecord, g as QueryStatusCallback, h as QueryStatus, i as MATERIALIZATION_SAMPLE_WINDOW, j as TimingPhase, k as SyncHealthConfig, l as PhaseStat, m as QueryState, n as EventSubscriptionOptions, o as MutationEvent, p as QueryHash, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryTimings, w as Sp00kyConfig, x as RecordVersionDiff, y as QueryUpdateCallback } from "./types.js";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal, SurrealTransaction } from "surrealdb";
-import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RecordId as RecordId$1, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
-import { Level, Level as Level$1, Logger } from "pino";
+import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
+import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, GetTable, QueryBuilder, QueryOptions, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
+import { Logger } from "pino";
+import { LoroDoc } from "loro-crdt";
 
-//#region src/events/index.d.ts
-/**
- * Utility type to define the payload structure of an event.
- * If the payload type P is never, it defines payload as undefined.
- */
-type EventPayloadDefinition<P> = [P] extends [never] ? {
-  payload: undefined;
-} : {
-  payload: P;
-};
-/**
- * Defines the structure of an event with a specific type and payload.
- * @template T The string literal type of the event.
- * @template P The type of the event payload.
- */
-type EventDefinition<T extends string, P> = {
-  type: T;
-} & EventPayloadDefinition<P>;
-/**
- * A map of event types to their definitions.
- * Keys are event names, values are EventDefinitions.
- */
-type EventTypeMap = Record<string, EventDefinition<any, unknown> | EventDefinition<any, never>>;
-/**
- * Options for pushing/emitting events.
- */
-interface PushEventOptions {
-  /** Configuration for debouncing the event. */
-  debounced?: {
-    key: string;
-    delay: number;
-  };
-}
-/**
- * Extracts the full Event object type from the map for a given key.
- */
-type Event<E extends EventTypeMap, T extends EventType<E>> = E[T];
-/**
- * Extracts the payload type from the map for a given key.
- */
-type EventPayload<E extends EventTypeMap, T extends EventType<E>> = E[T]['payload'];
-/**
- * Array of available event type keys.
- */
-type EventTypes<E extends EventTypeMap> = (keyof E)[];
-/**
- * Represents a valid key (event name) from the EventTypeMap.
- */
-type EventType<E extends EventTypeMap> = keyof E;
-/**
- * Function signature for an event handler.
- */
-type EventHandler<E extends EventTypeMap, T extends EventType<E>> = (event: Event<E, T>) => void;
-/**
- * Options when subscribing to an event.
- */
-type EventSubscriptionOptions$1 = {
-  /** If true, the handler will be called immediately with the last emitted event of this type (if any). */
-  immediately?: boolean;
-  /** If true, the subscription will be automatically removed after the first event is handled. */
-  once?: boolean;
-};
-/**
- * A type-safe event system that handles subscription, emission (including debouncing), and buffering of events.
- * @template E The EventTypeMap defining all supported events.
- */
-declare class EventSystem<E extends EventTypeMap> {
-  private _eventTypes;
-  private subscriberId;
-  private isProcessing;
-  private buffer;
-  private subscribers;
-  private subscribersTypeMap;
-  private lastEvents;
-  private debouncedEvents;
-  constructor(_eventTypes: EventTypes<E>);
-  get eventTypes(): EventTypes<E>;
-  /**
-   * Subscribes a handler to a specific event type.
-   * @param type The event type to subscribe to.
-   * @param handler The function to call when the event occurs.
-   * @param options Subscription options (once, immediately).
-   * @returns A subscription ID that can be used to unsubscribe.
-   */
-  subscribe<T extends EventType<E>>(type: T, handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number;
-  /**
-   * Subscribes a handler to multiple event types.
-   * @param types An array of event types to subscribe to.
-   * @param handler The function to call when any of the events occur.
-   * @param options Subscription options.
-   * @returns An array of subscription IDs.
-   */
-  subscribeMany<T extends EventType<E>>(types: T[], handler: EventHandler<E, T>, options?: EventSubscriptionOptions$1): number[];
-  /**
-   * Unsubscribes a specific subscription by ID.
-   * @param id The subscription ID returned by subscribe().
-   * @returns True if the subscription was found and removed, false otherwise.
-   */
-  unsubscribe(id: number): boolean;
-  /**
-   * Emits an event with the given type and payload.
-   * @param type The type of event to emit.
-   * @param payload The data associated with the event.
-   */
-  emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void;
-  /**
-   * Adds a fully constructed event object to the system.
-   * Similar to emit, but takes the full event object directly.
-   * Supports debouncing if options are provided.
-   * @param event The event object.
-   * @param options Options for the event push (e.g., debouncing).
-   */
-  addEvent<T extends EventType<E>>(event: Event<E, T>, options?: PushEventOptions): void;
-  private handleDebouncedEvent;
-  private scheduleProcessing;
-  private processEvents;
-  private dequeue;
-  private setLastEvent;
-  private broadcastEvent;
-}
-//#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
-//#endregion
 //#region src/services/database/events/index.d.ts
 declare const DatabaseEventTypes: {
   readonly LocalQuery: "DATABASE_LOCAL_QUERY";
@@ -154,13 +32,13 @@ interface SealedQuery<T = void> {
 //#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
-  protected client: Surreal;
+  protected client: Surreal$1;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
-  constructor(client: Surreal, logger: Logger$1, events: DatabaseEventSystem);
+  constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
-  getClient(): Surreal;
+  getClient(): Surreal$1;
   getEvents(): DatabaseEventSystem;
   tx(): Promise<SurrealTransaction>;
   private queryQueue;
@@ -176,17 +54,33 @@ declare abstract class AbstractDatabaseService {
 declare class LocalDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_LOCAL_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
+  private unloadCloseRegistered;
+  /**
+   * Close the local DB on page unload so the SurrealDB-WASM worker releases its
+   * IndexedDB connection cleanly. Without this, the previous page's connection
+   * lingers; the next load's `client.connect` opens the store but the first
+   * write transaction in `client.use` hits an "IndexedDB error" — which then
+   * (mis)triggered the corrupt-store recovery and WIPED the cache on every
+   * reload, making warm loads as slow as cold ones. `pagehide` is the reliable
+   * unload signal (fires on bfcache + normal navigation); `close()` is async but
+   * the WASM worker initiates the IndexedDB connection teardown synchronously.
+   */
+  private registerUnloadClose;
+  private openStore;
 }
+/** True for the SurrealDB-WASM error raised when its IndexedDB-backed key-value
+ *  store can't be opened (corrupt / version-incompatible / blocked). Exported
+ *  for unit testing the error-message match. */
 //#endregion
 //#region src/services/database/remote.d.ts
 declare class RemoteDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_REMOTE_QUERY";
-  constructor(config: SpookyConfig<any>['database'], logger: Logger$1);
-  getConfig(): SpookyConfig<any>['database'];
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  getConfig(): Sp00kyConfig<any>['database'];
   connect(): Promise<void>;
   signin(params: any): Promise<any>;
   signup(params: any): Promise<any>;
@@ -194,38 +88,44 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
   invalidate(): Promise<void>;
 }
 //#endregion
-//#region src/modules/sync/queue/queue-up.d.ts
-type CreateEvent = {
-  type: 'create';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  tableName?: string;
-  options?: PushEventOptions;
+//#region src/modules/sync/queue/queue-down.d.ts
+type RegisterEvent = {
+  type: 'register';
+  payload: {
+    hash: string;
+  };
 };
-type UpdateEvent = {
-  type: 'update';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  data: Record<string, unknown>;
-  record?: Record<string, unknown>;
-  beforeRecord?: Record<string, unknown>;
-  options?: PushEventOptions;
+type SyncEvent = {
+  type: 'sync';
+  payload: {
+    hash: string;
+  };
+};
+type HeartbeatEvent = {
+  type: 'heartbeat';
+  payload: {
+    hash: string;
+  };
 };
-type DeleteEvent = {
-  type: 'delete';
-  mutation_id: RecordId;
-  record_id: RecordId;
-  options?: PushEventOptions;
+type CleanupEvent = {
+  type: 'cleanup';
+  payload: {
+    hash: string;
+  };
 };
-type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
+type DownEvent = RegisterEvent | SyncEvent | HeartbeatEvent | CleanupEvent;
 //#endregion
 //#region src/services/stream-processor/wasm-types.d.ts
 interface WasmStreamUpdate {
   query_id: string;
   result_hash: string;
   result_data: RecordVersionArray;
+  timing_store_apply_ms?: number;
+  timing_circuit_step_ms?: number;
+  timing_transform_ms?: number;
+  timing_parse_ms?: number;
+  timing_plan_ms?: number;
+  timing_snapshot_ms?: number;
 }
 //#endregion
 //#region src/services/stream-processor/index.d.ts
@@ -246,6 +146,25 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * End-to-end ingest latency for the WASM call that produced this update,
+   * in milliseconds. Populated by StreamProcessorService.ingest. Undefined
+   * for the initial register_view snapshot.
+   */
+  materializationTimeMs?: number;
+  /** SSP internal sub-phase timings (ms) for this ingest, from the WASM binding. */
+  storeApplyMs?: number;
+  circuitStepMs?: number;
+  transformMs?: number;
+  /**
+   * One-shot registration timings (ms). Only set on the StreamUpdate returned
+   * by `registerQueryPlan` (the register_view snapshot), not on ingest updates.
+   */
+  registration?: {
+    parseMs: number;
+    planMs: number;
+    snapshotMs: number;
+  };
 }
 type StreamProcessorEvents = {
   stream_update: EventDefinition<'stream_update', StreamUpdate[]>;
@@ -265,6 +184,9 @@ declare class StreamProcessorService {
   private processor;
   private isInitialized;
   private receivers;
+  private batching;
+  private batchBuffer;
+  private sessionAuth;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -272,12 +194,64 @@ declare class StreamProcessorService {
    */
   addReceiver(receiver: StreamUpdateReceiver): void;
   private notifyUpdates;
+  private dispatchUpdates;
+  /**
+   * Ingest a batch of record changes as a single bulk operation, firing only
+   * one coalesced `StreamUpdate` per affected query once every record has been
+   * ingested (instead of one update per record). Use this whenever multiple
+   * records land at once — e.g. sync fetching N missing rows — so a list query
+   * re-runs and the UI re-renders once for the whole batch rather than
+   * row-by-row.
+   *
+   * Internally opens a coalescing window, ingests each record, then flushes;
+   * processor state is persisted once for the whole batch. No-op for an empty
+   * batch.
+   */
+  ingestMany(records: Array<{
+    table: string;
+    op: 'CREATE' | 'UPDATE' | 'DELETE';
+    id: string;
+    record: any;
+  }>): void;
+  /**
+   * Open a coalescing window. While open, the per-record stream updates
+   * emitted by `ingest` are buffered (one entry per queryHash) instead of
+   * dispatched. Always paired with `flushCoalescing()` in a try/finally by
+   * `ingestMany` so the window always closes — otherwise the processor stays
+   * stuck buffering forever.
+   *
+   * No-op if a window is already open (nested batches aren't expected here).
+   */
+  private beginCoalescing;
+  /**
+   * Close the coalescing window and flush: dispatch one coalesced
+   * `StreamUpdate` per buffered queryHash, then persist processor state once
+   * for the whole batch (instead of once per ingest).
+   */
+  private flushCoalescing;
   /**
    * Initialize the WASM module and processor.
    * This must be called before using other methods.
    */
   init(): Promise<void>;
   loadState(): Promise<void>;
+  /**
+   * Seed per-table `select` permission predicates ({ [table]: whereText }).
+   * Must run after the processor exists and before any `register_view`, else
+   * non-`_00_` tables are default-denied and registration fails.
+   */
+  setPermissions(permissions: Record<string, string>): void;
+  /**
+   * Set the current session's auth identity for permission injection,
+   * mirroring the server's `fn::query::register`
+   * (`object::extend(params, { auth: { id: $auth.id }, access: $access })`).
+   * Stored as strings (empty when logged out) and applied to every
+   * `register_view` in {@link registerQueryPlan}. Must be set before a
+   * `$auth`-gated query registers (and re-set on auth state changes), or the
+   * in-browser SSP's `permission_inject` rejects it with
+   * "requires $auth but registration params lack it".
+   */
+  setSessionAuth(authId: string | null, access: string | null): void;
   saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
@@ -297,203 +271,527 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
-//#region src/types.d.ts
-/**
- * The type of storage backend to use for the local database.
- * - 'memory': In-memory storage (transient).
- * - 'indexeddb': IndexedDB storage (persistent).
- */
-type StoreType = 'memory' | 'indexeddb';
+//#region src/modules/cache/types.d.ts
+type RecordWithId = Record<string, any> & {
+  id: RecordId<string>;
+};
+interface QueryConfig$1 {
+  queryHash: string;
+  surql: string;
+  params: Record<string, any>;
+  ttl: QueryTimeToLive | Duration;
+  lastActiveAt: Date;
+}
+interface CacheRecord {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  record: RecordWithId;
+  version: number;
+}
+//#endregion
+//#region src/modules/cache/index.d.ts
 /**
- * Interface for a custom persistence client.
- * Allows providing a custom storage mechanism for the local database.
+ * CacheModule - Centralized storage and DBSP ingestion
+ *
+ * Single responsibility: Handle all local storage operations and DBSP ingestion.
+ * This module acts as the bridge between data operations and persistence.
  */
-interface PersistenceClient {
+declare class CacheModule implements StreamUpdateReceiver {
+  private local;
+  private streamProcessor;
+  private logger;
+  private streamUpdateCallback;
+  private versionLookups;
+  constructor(local: LocalDatabaseService, streamProcessor: StreamProcessorService, streamUpdateCallback: (update: StreamUpdate) => void, logger: Logger$1);
   /**
-   * Sets a value in the storage.
-   * @param key The key to set.
-   * @param value The value to store.
+   * Implements StreamUpdateReceiver interface
+   * Called directly by StreamProcessor when views change
    */
-  set<T>(key: string, value: T): Promise<void>;
+  onStreamUpdate(update: StreamUpdate): void;
+  lookup(recordId: string): number;
   /**
-   * Gets a value from the storage.
-   * @param key The key to retrieve.
-   * @returns The stored value or null if not found.
+   * Save a single record to local DB and ingest into DBSP
+   * Used by mutations (create/update)
    */
-  get<T>(key: string): Promise<T | null>;
+  save(cacheRecord: CacheRecord, skipDbInsert?: boolean): Promise<void>;
   /**
-   * Removes a value from the storage.
-   * @param key The key to remove.
+   * Save multiple records in a batch
+   * More efficient than calling save() multiple times
+   * Used by sync operations
    */
-  remove(key: string): Promise<void>;
-}
-/**
- * Supported Time-To-Live (TTL) values for cached queries.
- * Format: number + unit (m=minutes, h=hours, d=days).
- */
-type QueryTimeToLive = '1m' | '5m' | '10m' | '15m' | '20m' | '25m' | '30m' | '1h' | '2h' | '3h' | '4h' | '5h' | '6h' | '7h' | '8h' | '9h' | '10h' | '11h' | '12h' | '1d';
-/**
- * Result object returned when a query is registered or executed.
- */
-interface SpookyQueryResult {
-  /** The unique hash identifier for the query. */
-  hash: string;
-}
-type SpookyQueryResultPromise = Promise<SpookyQueryResult>;
-interface EventSubscriptionOptions {
-  priority?: number;
-}
-/**
- * Configuration options for the Spooky client.
- * @template S The schema structure type.
- */
-interface SpookyConfig<S extends SchemaStructure> {
-  /** Database connection configuration. */
-  database: {
-    /** The SurrealDB endpoint URL. */
-    endpoint?: string;
-    /** The namespace to use. */
-    namespace: string;
-    /** The database name. */
-    database: string;
-    /** The local store type implementation. */
-    store?: StoreType;
-    /** Authentication token. */
-    token?: string;
+  saveBatch(records: CacheRecord[], skipDbInsert?: boolean): Promise<void>;
+  /**
+   * Delete a record from local DB and ingest deletion into DBSP
+   */
+  delete(table: string, id: string, skipDbDelete?: boolean, recordData?: Record<string, any>): Promise<void>;
+  /**
+   * Register a query with DBSP to create a materialized view
+   * Returns the initial result array
+   */
+  registerQuery(config: QueryConfig$1): {
+    localArray: RecordVersionArray;
+    registrationTimings?: {
+      parseMs: number;
+      planMs: number;
+      snapshotMs: number;
+    };
   };
-  /** Unique client identifier. If not provided, one will be generated. */
-  clientId?: string;
-  /** The schema definition. */
-  schema: S;
-  /** The compiled SURQL schema string. */
-  schemaSurql: string;
-  /** Logging level. */
-  logLevel: Level$1;
-  /**
-   * Persistence client to use.
-   * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
-   */
-  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
-  /** OpenTelemetry collector endpoint for telemetry data. */
-  otelEndpoint?: string;
-  /**
-   * Debounce time in milliseconds for stream updates.
-   * Defaults to 100ms.
-   */
-  streamDebounceTime?: number;
-}
-type QueryHash = string;
-type RecordVersionArray = Array<[string, number]>;
-/**
- * Represents the difference between two record version sets.
- * Used for synchronizing local and remote states.
- */
-interface RecordVersionDiff {
-  /** List of records added. */
-  added: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of records updated. */
-  updated: Array<{
-    id: RecordId$1<string>;
-    version: number;
-  }>;
-  /** List of record IDs removed. */
-  removed: RecordId$1<string>[];
-}
-/**
- * Configuration for a specific query instance.
- * Stores metadata about the query's state, parameters, and versioning.
- */
-interface QueryConfig {
-  /** The unique ID of the query config record. */
-  id: RecordId$1<string>;
-  /** The SURQL query string. */
-  surql: string;
-  /** Parameters used in the query. */
-  params: Record<string, any>;
-  /** The version array representing the local state of results. */
-  localArray: RecordVersionArray;
-  /** The version array representing the remote (server) state of results. */
-  remoteArray: RecordVersionArray;
-  /** Time-To-Live for this query. */
-  ttl: QueryTimeToLive;
-  /** Timestamp when the query was last accessed/active. */
-  lastActiveAt: Date;
-  /** The name of the table this query targets (if applicable). */
-  tableName: string;
-}
-type QueryConfigRecord = QueryConfig & {
-  id: string;
-};
-/**
- * Internal state of a live query.
- */
-interface QueryState {
-  /** The configuration for this query. */
-  config: QueryConfig;
-  /** The current cached records for this query. */
-  records: Record<string, any>[];
-  /** Timer for TTL expiration. */
-  ttlTimer: NodeJS.Timeout | null;
-  /** TTL duration in milliseconds. */
-  ttlDurationMs: number;
-  /** Number of times the query has been updated. */
-  updateCount: number;
+  /**
+   * Unregister a query from DBSP
+   */
+  unregisterQuery(queryHash: string): void;
 }
-type QueryUpdateCallback = (records: Record<string, any>[]) => void;
-type MutationCallback = (mutations: UpEvent[]) => void;
-type MutationEventType = 'create' | 'update' | 'delete';
+//#endregion
+//#region src/modules/data/index.d.ts
 /**
- * Represents a mutation event (create, update, delete) to be synchronized.
+ * DataModule - Unified query and mutation management
+ *
+ * Merges the functionality of QueryManager and MutationManager.
+ * Uses CacheModule for all storage operations.
  */
-interface MutationEvent {
-  /** Example: 'create', 'update', or 'delete'. */
-  type: MutationEventType;
-  /** unique id of the mutation */
-  mutation_id: RecordId$1<string>;
-  /** The ID of the record being mutated. */
-  record_id: RecordId$1<string>;
-  /** The data payload for create/update operations. */
-  data?: any;
-  /** The full record data (optional context). */
-  record?: any;
-  /** Options for the mutation event (e.g., debounce settings). */
-  options?: PushEventOptions;
-  /** Timestamp when the event was created. */
-  createdAt: Date;
+declare class DataModule<S extends SchemaStructure> {
+  private cache;
+  private local;
+  private schema;
+  private streamDebounceTime;
+  private activeQueries;
+  private pendingQueries;
+  private subscriptions;
+  private statusSubscriptions;
+  private mutationCallbacks;
+  private debounceTimers;
+  private logger;
+  /**
+   * Optional observer notified whenever a query's fetch status changes.
+   * Wired by Sp00kyClient to push status changes into DevTools. Kept as a
+   * settable field (rather than a constructor arg) because DevTools is
+   * constructed after DataModule.
+   */
+  onQueryStatusChange?: (hash: QueryHash, status: QueryStatus) => void;
+  /**
+   * Optional observer invoked when a still-subscribed query's TTL heartbeat
+   * fires (~90% of the TTL). Wired by Sp00kyClient to
+   * `Sp00kySync.heartbeatQuery`, which refreshes the remote `_00_query`
+   * row's `lastActiveAt` so an actively-watched query never expires. Settable
+   * field (not a constructor arg) because the sync engine is wired after
+   * DataModule is constructed — mirrors `onQueryStatusChange`.
+   */
+  onHeartbeat?: (hash: QueryHash) => void;
+  /**
+   * Optional hook fired by {@link deregisterQuery} when an opt-in query (e.g. a
+   * viewport-windowed list cancelling an off-screen window) loses its last
+   * subscriber. Wired by Sp00kyClient to enqueue a `cleanup` down-event, which
+   * tears the remote `_00_query` view down (releasing its `_00_list_ref` edges)
+   * instead of leaving it for the TTL sweep. The local view + state are freed in
+   * {@link finalizeDeregister} only after that remote delete, so a fast
+   * re-subscribe (scroll back) can abort/heal the teardown — see `cleanupQuery`.
+   */
+  onDeregister?: (hash: QueryHash) => void;
+  private sessionId;
+  private currentUserId;
+  constructor(cache: CacheModule, local: LocalDatabaseService, schema: S, logger: Logger$1, streamDebounceTime?: number);
+  init(sessionId: string): Promise<void>;
+  /**
+   * Update the session salt used in query-id hashing. Call this when the
+   * SurrealDB session changes (sign-in, sign-out, reconnect). Subsequently
+   * registered queries will get fresh, session-scoped IDs.
+   */
+  setSessionId(sessionId: string): void;
+  /**
+   * Update the authenticated user record id. Pass `null` on sign-out.
+   * Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
+   * the poll route to the same per-user `_00_list_ref_user_<id>` the
+   * SSP writes to.
+   */
+  setCurrentUserId(userId: string | null): void;
+  /** Read-only view of the authenticated user id used for per-user
+   * `_00_list_ref` routing. Other modules consult this so they pick the
+   * same table name DataModule does. */
+  getCurrentUserId(): string | null;
+  /**
+   * Register a query and return its hash for subscriptions
+   */
+  query<T extends TableNames<S>>(tableName: T, surqlString: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<QueryHash>;
+  /**
+   * Subscribe to query updates
+   */
+  subscribe(queryHash: string, callback: QueryUpdateCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching).
+   * With `{ immediate: true }` the callback fires synchronously with the
+   * current status (defaults to `idle` if the query isn't registered yet).
+   */
+  subscribeStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Set a query's fetch status and notify status observers (DevTools +
+   * `subscribeStatus` listeners). No-op when the status is unchanged or the
+   * query is unknown.
+   */
+  setQueryStatus(queryHash: string, status: QueryStatus): void;
+  /**
+   * Subscribe to mutations (for sync)
+   */
+  onMutation(callback: MutationCallback): () => void;
+  /**
+   * Handle stream updates from DBSP (via CacheModule)
+   */
+  onStreamUpdate(update: StreamUpdate): Promise<void>;
+  private materializeRecords;
+  private processStreamUpdate;
+  /**
+   * Compute p55/p90/p99 from a rolling window of materialization samples.
+   * Returns nulls for any percentile that has no samples yet so SurrealDB
+   * `option<float>` columns stay NONE rather than 0 before the first ingest.
+   */
+  private computeMaterializationPercentiles;
+  /** Record a per-phase timing sample (ms) on a query's rolling window. */
+  private recordPhase;
+  /** Record the remote record-fetch time (ms) for a query. Called by the sync engine. */
+  recordRemoteFetch(hash: string, ms: number): void;
+  /**
+   * Record the frontend reconcile time (ms) for a query. Called from `useQuery`
+   * via `Sp00kyClient.reportFrontendTiming` after it applies an update to its store.
+   */
+  recordFrontendTiming(hash: string, ms: number): void;
+  /**
+   * Build the per-query processing-time breakdown surfaced to the DevTools panel
+   * and the MCP. `ssp` is the WASM-ingest wall time (from `materializationSamples`);
+   * the rest come from the per-phase rolling windows + one-shot registration timings.
+   */
+  phaseTimings(q: QueryState): QueryTimings;
+  /**
+   * Get query state (for sync and devtools)
+   */
+  getQueryByHash(hash: string): QueryState | undefined;
+  /**
+   * Cold-query guard for instant-hydrate: true when the query exists, hasn't been
+   * hydrated, and has NOT yet fetched its server result (`remoteArray` empty).
+   * We gate on `remoteArray`, not local `records`: a windowed query is often
+   * partially pre-seeded from the circuit (e.g. the dashboard's 5-row preview),
+   * but it still hasn't loaded its own full window from the server — so it should
+   * still hydrate. A warm re-subscribe (remoteArray already populated) is skipped.
+   */
+  isCold(hash: string): boolean;
+  /**
+   * Walk a hydrated record's fields and append any EMBEDDED child records to
+   * `batch` (recursing for nested related fields). An embedded child is a
+   * value that is itself a record — a non-null object whose `id` is a
+   * `RecordId` — or an array of such records (one-to-many vs one-to-one). A
+   * bare `RecordId` (a foreign-key reference) or any other value is skipped,
+   * so this never mistakes a FK column for an embedded body. Children are
+   * keyed by their own `record.id.table`, versioned by `_00_rv`, and cleaned
+   * to their table's real columns (which strips the alias/related fields).
+   * `seen` dedupes within the batch.
+   */
+  private collectEmbeddedChildren;
+  /**
+   * Instant-hydrate: ingest rows fetched one-shot from the remote (the query's own
+   * surql run directly) so the query DISPLAYS immediately, while the full realtime
+   * registration proceeds in the background. Ingests with versions (`_00_rv`) so the
+   * later `syncRecords` dedup skips re-pulling unchanged bodies, and seeds
+   * `remoteArray` so windowed queries materialize the correct window (no sparse
+   * local-circuit issue). Runs at most once per query (the `hydrated` flag).
+   */
+  applyHydration(hash: string, rows: RecordWithId[]): Promise<void>;
+  /** True while ≥1 live subscriber is watching this query (refcount guard). */
+  hasSubscribers(hash: string): boolean;
+  /**
+   * Opt-in eager teardown for a query whose LAST subscriber just left — used by
+   * viewport-windowed lists to cancel off-screen windows instead of leaving
+   * their remote views to expire on the TTL sweep. No-op while any subscriber
+   * remains (refcount). Only enqueues the remote cleanup here; the local WASM
+   * view + in-memory state are freed in {@link finalizeDeregister} after the
+   * remote delete completes, so a re-subscribe in between aborts/heals it.
+   *
+   * NOTE: most queries should NOT use this — the default keep-alive on
+   * unsubscribe avoids re-registration churn on navigation.
+   */
+  deregisterQuery(hash: string): void;
+  /**
+   * Final local teardown after the remote `_00_query` row was deleted: free the
+   * WASM view, heartbeat timer, debounce timer, and in-memory state. Caller
+   * (`cleanupQuery`) guarantees no subscriber remains.
+   */
+  finalizeDeregister(hash: string): void;
+  /**
+   * Get query state by id (for sync and devtools)
+   */
+  getQueryById(id: RecordId<string>): QueryState | undefined;
+  /**
+   * Get all active queries (for devtools)
+   */
+  getActiveQueries(): QueryState[];
+  getActiveQueryHashes(): QueryHash[];
+  updateQueryLocalArray(id: string, localArray: RecordVersionArray): Promise<void>;
+  updateQueryRemoteArray(hash: string, remoteArray: RecordVersionArray): Promise<void>;
+  /**
+   * Called after a query's initial sync completes.
+   * Ensures subscribers are notified even if no stream updates fired (e.g. empty result set).
+   */
+  notifyQuerySynced(queryHash: string): Promise<void>;
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, data: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  /**
+   * Create a new record
+   */
+  create<T extends Record<string, unknown>>(id: string, data: T): Promise<T>;
+  /**
+   * Update an existing record
+   */
+  update<T extends Record<string, unknown>>(table: string, id: string, data: Partial<T>, options?: UpdateOptions): Promise<T>;
+  /**
+   * Delete a record
+   */
+  delete(table: string, id: string): Promise<void>;
+  /**
+   * Rollback a failed optimistic create by deleting the record locally
+   */
+  rollbackCreate(recordId: RecordId, tableName: string): Promise<void>;
+  /**
+   * Rollback a failed optimistic update by restoring the previous record state
+   */
+  rollbackUpdate(recordId: RecordId, tableName: string, beforeRecord: Record<string, unknown>): Promise<void>;
+  /**
+   * Remove a record from all active query states and notify subscribers
+   */
+  private removeRecordFromQueries;
+  private createAndRegisterQuery;
+  private createNewQuery;
+  private calculateHash;
+  private startTTLHeartbeat;
+  private replaceRecordInQueries;
 }
 /**
- * Options for run operations.
+ * Parse update options to generate push event options
  */
-interface RunOptions {
-  assignedTo?: string;
-  max_retries?: number;
-  retry_strategy?: 'linear' | 'exponential';
-}
+//#endregion
+//#region src/modules/sync/sync.d.ts
 /**
- * Options for update operations.
+ * Tunables for `Sp00kySync` construction.
  */
-interface UpdateOptions {
+interface Sp00kySyncOptions {
+  /**
+   * Cadence (ms) for the `_00_list_ref` poll fallback that catches
+   * cross-session UPDATEs the LIVE-permission gap drops. Non-positive
+   * values fall back to the default; see
+   * {@link resolveListRefPollInterval}.
+   */
+  refSyncIntervalMs?: number;
+  /**
+   * Enable realtime sync for unauthenticated clients against the shared
+   * `_00_list_ref_anon` table. See {@link Sp00kyConfig.enableAnonymousLiveQueries}.
+   * Defaults to `false`.
+   */
+  anonymousLiveQueries?: boolean;
   /**
-   * Debounce configuration for the update.
-   * If boolean, enables default debounce behavior.
+   * Consecutive failed sync rounds before sync health flips to `degraded`.
+   * `0` disables degraded reporting. See {@link Sp00kyConfig.syncHealth}.
+   * Defaults to `3`.
    */
-  debounced?: boolean | DebounceOptions;
+  degradeAfterConsecutiveFailures?: number;
 }
 /**
- * Configuration options for debouncing updates.
+ * The main synchronization engine for Sp00ky.
+ * Handles the bidirectional synchronization between the local database and the remote backend.
+ * Uses a queue-based architecture with 'up' (local to remote) and 'down' (remote to local) queues.
+ * @template S The schema structure type.
  */
-interface DebounceOptions {
+declare class Sp00kySync<S extends SchemaStructure> {
+  private local;
+  private remote;
+  private cache;
+  private dataModule;
+  private schema;
+  private upQueue;
+  private downQueue;
+  private isInit;
+  private logger;
+  private syncEngine;
+  /** Engine-level events (e.g. `SYNC_REMOTE_DATA_INGESTED`). Distinct
+   *  from `this.events`, which carries Sp00kySync-level events like
+   *  `SYNC_QUERY_UPDATED` and `SYNC_MUTATION_ROLLED_BACK`. */
+  get engineEvents(): SyncEventSystem;
+  private scheduler;
+  private wasDisconnected;
+  events: SyncEventSystem;
+  private currentUserId;
+  private refMode;
+  private readonly anonLiveEnabled;
+  private currentLiveQueryUuid;
+  private liveQueryUnsubscribe;
+  private listRefPollTimer;
+  private listRefPollRunning;
+  readonly refSyncIntervalMs: number;
+  private listRefIdleStreak;
+  private stillRemoteStreaks;
+  private lastLiveEventAt;
+  private _liveRetryCount;
+  get liveRetryCount(): number;
+  get isSyncing(): boolean;
+  get pendingMutationCount(): number;
+  subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  private readonly degradeAfterFailures;
+  private consecutiveSyncFailures;
+  private syncHealthStatus;
+  private lastSyncErrorKind;
+  private lastSyncErrorMessage;
+  private selfHealTimer;
+  private selfHealAttempts;
+  private static readonly SELF_HEAL_BASE_MS;
+  private static readonly SELF_HEAL_MAX_MS;
+  /** Current sync-health snapshot. */
+  get syncHealth(): SyncHealth;
+  /**
+   * Observe sync health. The callback fires immediately with the current
+   * status and again on every healthy↔degraded transition. Returns an
+   * unsubscribe. Mirrors {@link subscribeToPendingMutations}.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  private emitSyncHealth;
+  /**
+   * Fed by the scheduler once per drained sync round. Individual failures are
+   * absorbed by the queue's retry; only a run of `degradeAfterFailures`
+   * consecutive failures flips the status to `degraded`, and the next clean
+   * round flips it back. No-op when reporting is disabled (`degradeAfterFailures`
+   * is 0).
+   */
+  private recordSyncOutcome;
   /**
-   * The key to use for debouncing.
-   * - 'recordId': Debounce based on the specific record ID. WARNING: IT WILL ONLY ACCEPT THE LATEST CHANGE AND DOES *NOT* MERGE THE PREVIOUS ONCES. IF YOU ARE UNSURE JUST USE 'recordId_x_fields'.
-   * - 'recordId_x_fields': Debounce based on record ID and specific fields.
+   * Begin self-heal retries (no-op if already running). Started on the
+   * healthy→degraded transition; {@link recordSyncOutcome} stops it on recovery.
    */
-  key?: 'recordId' | 'recordId_x_fields';
-  /** The debounce delay in milliseconds. */
-  delay?: number;
+  private startSelfHeal;
+  private scheduleSelfHeal;
+  private stopSelfHeal;
+  constructor(local: LocalDatabaseService, remote: RemoteDatabaseService, cache: CacheModule, dataModule: DataModule<S>, schema: S, logger: Logger$1, options?: Sp00kySyncOptions);
+  /**
+   * Initializes the synchronization system.
+   * Starts the scheduler and initiates the initial sync cycles.
+   * @throws Error if already initialized.
+   */
+  init(): Promise<void>;
+  /**
+   * Push the authenticated user's record id from the parent client's
+   * auth subscription. Tears down the existing `_00_list_ref` LIVE (if
+   * any) and re-registers it under the new user's dedicated table so
+   * SurrealDB binds the permission rule under the post-flip auth
+   * context. Pass `null` on sign-out.
+   *
+   * The dedicated `_00_list_ref_user_<id>` table is created lazily by
+   * the SSP when the first query registration arrives, which may be
+   * concurrent with this call. We retry the LIVE registration with a
+   * short backoff so a "table not found" race resolves without
+   * surfacing as a permanent auth-loading hang.
+   */
+  setCurrentUserId(userId: string | null): Promise<void>;
+  private startListRefPoll;
+  private stopListRefPoll;
+  /**
+   * One poll cycle: refetch `_00_list_ref` for every active query. Returns
+   * whether ANY query's remoteArray actually changed — the scheduler uses this
+   * to drive the adaptive idle backoff.
+   */
+  private pollListRefForActiveQueries;
+  /**
+   * Pull the upstream list_ref entries for `queryHash`, diff them
+   * against the local `remoteArray` cache, sync any added/updated rows
+   * through the SyncEngine, then persist the new remoteArray. This is
+   * the same shape `createRemoteQuery` does for its initial fetch and
+   * what `handleRemoteListRefChange` does per-LIVE-event — we reuse
+   * it on a timer as a fallback for missed LIVE notifications.
+   */
+  private refetchListRefForQuery;
+  /**
+   * Resolve the current `_00_list_ref` table name for the active auth
+   * context. Public so the `createRemoteQuery` initial-fetch path can
+   * read from the right per-user table.
+   *
+   * Reads the user id from `DataModule` rather than the local mirror,
+   * because `DataModule.setCurrentUserId` runs synchronously from the
+   * auth callback (before any `await`), whereas `sync.setCurrentUserId`
+   * is async — the userQuery's initial fetch can fire between those
+   * two points and we need the correct table name immediately.
+   */
+  listRefTable(): string;
+  private killRefLiveQuery;
+  private restartRefLiveQuery;
+  private subscribeToReconnect;
+  private startRefLiveQueries;
+  private handleRemoteListRefChange;
+  /**
+   * Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
+   * `parent` set) for a `.related()` query. Unlike primary rows, child rows
+   * must NOT touch the query's `localArray`/`remoteArray`/`rowCount`; we only
+   * keep the child BODY fresh in the local cache so the in-browser SSP's
+   * subquery-table dependency re-materializes the parent view.
+   *
+   * CREATE/UPDATE fetch+upsert the child body. DELETE is intentionally a
+   * no-op: a child leaving this query's set must not delete a body another
+   * query may still show (see `syncSubqueryChildren` deletion-safety note);
+   * a genuine record delete propagates via the normal delete path.
+   */
+  private handleRemoteSubqueryChange;
+  /**
+   * Enqueues a 'down' event (from remote to local) for processing.
+   * @param event The DownEvent to enqueue.
+   */
+  enqueueDownEvent(event: DownEvent): void;
+  private processUpEvent;
+  private handleRollback;
+  private processDownEvent;
+  /**
+   * Synchronizes a specific query by hash.
+   * Compares local and remote version arrays and fetches differences.
+   * @param hash The hash of the query to sync.
+   */
+  syncQuery(hash: string): Promise<void>;
+  /**
+   * Run a sync for a single query while reflecting its fetch status. Marks the
+   * query `fetching` for the duration when the diff actually pulls records
+   * (added/updated), then resets to `idle` in a `finally` so a failed sync
+   * never leaves a query stuck `fetching`. Part A's notification coalescing
+   * means the single resulting UI update lands after this completes.
+   */
+  private runSyncForQuery;
+  /**
+   * Record ids with a pending local DELETE in the outbox (`_00_pending_mutations`).
+   * Sync must not re-fetch/re-insert these — the remote delete is async, so the
+   * server's `_00_list_ref` still lists them until it's processed, and the diff
+   * would otherwise resurrect a just-deleted record.
+   */
+  private getPendingDeleteIds;
+  /**
+   * Enqueues a list of mutations (up events) to be sent to the remote.
+   * @param mutations Array of UpEvents (create/update/delete) to enqueue.
+   */
+  enqueueMutation(mutations: UpEvent[]): Promise<void>;
+  private registerQuery;
+  private createRemoteQuery;
+  /**
+   * Sync the BODIES of a `.related()` query's subquery child rows into the
+   * local cache, separately from the primary window array. The SSP writes
+   * each matched child as a `_00_list_ref` edge tagged `parent`/`parent_rel`;
+   * `buildSubqueryListRefSelect` pulls those `out`+`version` pairs (any
+   * nesting depth). We diff against the in-memory `subqueryRemoteArray` and
+   * fetch added/updated bodies through the SyncEngine — which `saveBatch`s
+   * them into the local DB AND the in-browser SSP, whose subquery-table
+   * dependency then re-materializes the parent view (no explicit notify).
+   *
+   * Deletion safety: we pass `removed: []` deliberately. A child body can be
+   * shared by other queries; letting `handleRemovedRecords` delete one that
+   * merely left THIS query's child set would clobber data another query still
+   * shows. Genuine record deletes flow through the normal delete path; a
+   * lingering orphan body is invisible (the correlated WHERE stops matching).
+   *
+   * Kept off `runSyncForQuery` on purpose so child fetches never flip the
+   * query to `fetching` or skew its DevTools timings.
+   */
+  private syncSubqueryChildren;
+  heartbeatQuery(queryHash: string): Promise<void>;
+  private cleanupQuery;
 }
 //#endregion
 //#region src/modules/auth/events/index.d.ts
@@ -518,6 +816,13 @@ declare class AuthService<S extends SchemaStructure> {
   token: string | null;
   currentUser: any | null;
   isAuthenticated: boolean;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  access: string | null;
   isLoading: boolean;
   private events;
   get eventSystem(): AuthEventSystem;
@@ -539,11 +844,206 @@ declare class AuthService<S extends SchemaStructure> {
    */
   signOut(): Promise<void>;
   private setSession;
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName;
   signUp<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signup'>): Promise<void>;
   signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
 }
 //#endregion
-//#region src/spooky.d.ts
+//#region src/modules/crdt/crdt-field.d.ts
+declare const CURSOR_COLORS: string[];
+declare function cursorColorFromName(name: string): string;
+declare class CrdtField {
+  private fieldName;
+  private doc;
+  private pushTimer;
+  private local;
+  private remote;
+  private recordId;
+  private sessionId;
+  private unsubscribe;
+  private lastPushTime;
+  private lastCursorPushTime;
+  private loadedFromCrdt;
+  private pushRetryCount;
+  private logger;
+  private cursorsEnabled;
+  /** Remote-push debounce. Local writes happen immediately on every Loro
+   *  update; the remote UPSERT is coalesced over this window. Configured
+   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
+  private remoteDebounceMs;
+  private _onCursorUpdate;
+  private pendingCursorUpdate;
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
+  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
+  constructor(fieldName: string, cursorsEnabled: boolean, initialState?: Uint8Array, logger?: Logger$1 | null);
+  getDoc(): LoroDoc;
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean;
+  startSync(local: LocalDatabaseService, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
+  stopSync(): void;
+  importRemote(state: Uint8Array): void;
+  exportSnapshot(): Uint8Array;
+  /** Push this session's cursor blob into the parent row at
+   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
+   *  field — the editor still calls this method optimistically, but
+   *  without `@cursor` on the schema there's nowhere to store the blob.
+   *  The UPDATE itself fires the parent table's LIVE feed, so other
+   *  browsers receive the cursor change without a separate `_00_rv` bump. */
+  pushCursorState(encoded: Uint8Array): Promise<void>;
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void;
+  private scheduleRemotePush;
+  /** SET path inside a parent row for the current snapshot. `@crdt`-only
+   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
+   *  fields hold a `{ state, cursors }` object so the snapshot lives at
+   *  `<field>.state` next to per-session cursor blobs. */
+  private statePath;
+  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
+   *  every local update and every remote import so reloads (online or
+   *  offline) see the freshest content immediately. Failures are
+   *  swallowed — a stale local write must never block user input. */
+  private persistLocal;
+  private pushToRemote;
+}
+//#endregion
+//#region src/modules/crdt/index.d.ts
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ */
+declare class CrdtManager {
+  private schema;
+  private local;
+  private remote;
+  private debounceMs;
+  private fields;
+  private liveByTable;
+  private pendingLive;
+  private logger;
+  private sessionId;
+  constructor(schema: SchemaStructure, local: LocalDatabaseService, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void;
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  close(table: string, recordId: string, field: string): void;
+  closeAll(): void;
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private ensureTableSubscription;
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void;
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow;
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private fetchAndDispatchRow;
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor;
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot;
+  private killTableSubscription;
+  private makeKey;
+  /**
+   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
+   * typos, removed annotations, and stale schema codegen at the call site instead
+   * of silently producing a non-CRDT writer.
+   */
+  private assertCrdtField;
+}
+//#endregion
+//#region src/modules/feature-flag/index.d.ts
+interface FeatureFlagSnapshot {
+  variant: string | undefined;
+  payload: unknown | undefined;
+}
+interface FeatureFlagOptions {
+  fallback?: string;
+  ttl?: QueryTimeToLive;
+}
+declare class FeatureFlagHandle {
+  readonly key: string;
+  readonly fallback: string | undefined;
+  private latest;
+  private listeners;
+  private unsubscribeFn;
+  private onCloseFn;
+  private closed;
+  constructor(key: string, fallback: string | undefined);
+  attach(unsubscribe: () => void): void;
+  detach(): void;
+  set(snapshot: FeatureFlagSnapshot): void;
+  variant(): string | undefined;
+  payload<T = unknown>(): T | undefined;
+  enabled(): boolean;
+  subscribe(cb: (s: FeatureFlagSnapshot) => void): () => void;
+  onClose(cb: () => void): void;
+  close(): void;
+}
+interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger$1;
+}
+declare class FeatureFlagModule<S extends SchemaStructure> {
+  private deps;
+  private logger;
+  private active;
+  private authUnsubscribe;
+  private lastUserId;
+  constructor(deps: FeatureFlagModuleDeps<S>);
+  init(): void;
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  closeAll(): Promise<void>;
+  private refreshAll;
+  private register;
+}
+//#endregion
+//#region src/sp00ky.d.ts
 declare class BucketHandle {
   private bucketName;
   private remote;
@@ -557,7 +1057,7 @@ declare class BucketHandle {
   rename(sourcePath: string, targetPath: string): Promise<void>;
   list(prefix?: string): Promise<string[]>;
 }
-declare class SpookyClient<S extends SchemaStructure> {
+declare class Sp00kyClient<S extends SchemaStructure> {
   private config;
   private local;
   private remote;
@@ -567,28 +1067,86 @@ declare class SpookyClient<S extends SchemaStructure> {
   private dataModule;
   private sync;
   private devTools;
+  private crdtManager;
+  private featureFlags;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
-  get remoteClient(): Surreal;
-  get localClient(): Surreal;
+  get remoteClient(): surrealdb0.Surreal;
+  get localClient(): surrealdb0.Surreal;
   get pendingMutationCount(): number;
+  /** Number of times the initial list_ref LIVE subscription retried on
+   *  the most recent `setCurrentUserId` call. 0 when the SSP's
+   *  pre-emptive user-table creation got there first; >0 when LIVE
+   *  registration hit a "table not found" race. Exposed so the e2e
+   *  suite can guard the pre-emptive path against regression. */
+  get liveRetryCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
-  constructor(config: SpookyConfig<S>);
+  /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
+  get syncHealth(): SyncHealth;
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Returns an unsubscribe.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  constructor(config: Sp00kyConfig<S>);
   /**
    * Setup direct callbacks instead of event subscriptions
    */
   private setupCallbacks;
   init(): Promise<void>;
   close(): Promise<void>;
+  /**
+   * Subscribe to a feature flag for the current user. Returns a
+   * `FeatureFlagHandle` whose `variant()`, `payload()` and `enabled()`
+   * accessors reflect the latest assignment from `_00_user_feature`,
+   * and whose `subscribe(cb)` fires whenever that assignment changes.
+   *
+   * Permissions are enforced by SurrealDB: a client can only ever see
+   * its own row, and cannot create or modify assignments.
+   */
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
   authenticate(token: string): Promise<surrealdb0.Tokens>;
+  /**
+   * Open a CRDT field for collaborative editing.
+   * Returns a CrdtField with a LoroDoc that can be bound to any editor.
+   * Also starts a LIVE SELECT on the parent table for real-time sync;
+   * incoming events trigger a subquery fetch of `_00_crdt` / `_00_cursor`.
+   */
+  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
+  /**
+   * Close a CRDT field when editing is done.
+   */
+  closeCrdtField(table: string, recordId: string, field: string): void;
   deauthenticate(): Promise<void>;
-  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, SpookyQueryResultPromise>;
+  query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: {
     immediate?: boolean;
   }): Promise<() => void>;
+  /**
+   * Opt-in eager teardown for a query whose last subscriber has gone away
+   * (e.g. a viewport-windowed list cancelling an off-screen window). No-op
+   * while any subscriber remains. Tears down the remote `_00_query` view +
+   * local WASM view instead of waiting for the TTL sweep. Default behavior
+   * (no call here) keeps the view resident for cheap re-subscription.
+   */
+  deregisterQuery(queryHash: string): void;
+  /**
+   * Subscribe to a query's fetch-status changes (idle/fetching). With
+   * `{ immediate: true }` the callback fires synchronously with the current
+   * status. Powers the `useQuery` hook's `isFetching()` accessor.
+   */
+  subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /**
+   * Report the frontend processing time (ms) a client framework spent applying
+   * an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can
+   * surface the "frontend" phase of the per-query timing breakdown.
+   */
+  reportFrontendTiming(queryHash: string, ms: number): void;
   run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   create(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -597,15 +1155,25 @@ declare class SpookyClient<S extends SchemaStructure> {
   }>;
   delete(table: string, id: string): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
-  private persistClientId;
-  private loadOrGenerateClientId;
+  /**
+   * Fetch SurrealDB's `session::id()` as a string. Used as a salt for
+   * query-id hashing so two sessions for the same user get distinct
+   * `_00_query` rows. Returns empty string if the query fails (we still
+   * boot, just without session scoping for IDs).
+   */
+  private fetchSessionId;
 }
 //#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+declare function textToHtml(text: string): string;
 /**
  * Helper for retrying DB operations with exponential backoff
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, DebounceOptions, EventSubscriptionOptions, type Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, SpookyClient, SpookyConfig, SpookyQueryResult, SpookyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, fileToUint8Array };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };