@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.131

package/dist/types.d.ts

@@ -0,0 +1,746 @@
+import { RecordId } from "surrealdb";
+import { QueryPlan, QueryPlan as QueryPlan$1, RecordId as RecordId$1, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
+import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
+
+//#region src/events/index.d.ts
+/**
+ * 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/modules/sync/events/index.d.ts
+declare const SyncEventTypes: {
+  readonly QueryUpdated: "SYNC_QUERY_UPDATED";
+  readonly RemoteDataIngested: "SYNC_REMOTE_DATA_INGESTED";
+  readonly MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK";
+  readonly SyncHealthChanged: "SYNC_HEALTH_CHANGED";
+};
+type SyncEventTypeMap = {
+  [SyncEventTypes.QueryUpdated]: EventDefinition<typeof SyncEventTypes.QueryUpdated, {
+    queryId: any;
+    localHash?: string;
+    localArray?: RecordVersionArray;
+    remoteHash?: string;
+    remoteArray?: RecordVersionArray;
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.RemoteDataIngested]: EventDefinition<typeof SyncEventTypes.RemoteDataIngested, {
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.MutationRolledBack]: EventDefinition<typeof SyncEventTypes.MutationRolledBack, {
+    eventType: string;
+    recordId: string;
+    error: string;
+  }>;
+  [SyncEventTypes.SyncHealthChanged]: EventDefinition<typeof SyncEventTypes.SyncHealthChanged, SyncHealth>;
+};
+type SyncEventSystem = EventSystem<SyncEventTypeMap>;
+//#endregion
+//#region src/services/logger/index.d.ts
+type Logger$1 = Logger;
+//#endregion
+//#region src/services/database/events/index.d.ts
+declare const DatabaseEventTypes: {
+  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
+  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
+};
+interface DatabaseQueryEventPayload {
+  query: string;
+  vars?: Record<string, unknown>;
+  duration: number;
+  success: boolean;
+  error?: string;
+  timestamp: number;
+}
+type DatabaseEventTypeMap = {
+  [DatabaseEventTypes.LocalQuery]: EventDefinition<typeof DatabaseEventTypes.LocalQuery, DatabaseQueryEventPayload>;
+  [DatabaseEventTypes.RemoteQuery]: EventDefinition<typeof DatabaseEventTypes.RemoteQuery, DatabaseQueryEventPayload>;
+};
+type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
+//#endregion
+//#region src/utils/surql.d.ts
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+//#endregion
+//#region src/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;
+}
+/** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
+type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+ *  a guard against a cyclic schema producing unbounded fan-out. */
+//#endregion
+//#region src/modules/sync/queue/queue-up.d.ts
+type CreateEvent = {
+  type: 'create';
+  mutation_id: RecordId;
+  record_id: RecordId;
+  data: Record<string, unknown>;
+  record?: Record<string, unknown>;
+  tableName?: string;
+  options?: PushEventOptions;
+};
+type UpdateEvent = {
+  type: 'update';
+  mutation_id: RecordId;
+  record_id: RecordId;
+  data: Record<string, unknown>;
+  record?: Record<string, unknown>;
+  beforeRecord?: Record<string, unknown>;
+  options?: PushEventOptions;
+};
+type DeleteEvent = {
+  type: 'delete';
+  mutation_id: RecordId;
+  record_id: RecordId;
+  options?: PushEventOptions;
+};
+type UpEvent = CreateEvent | UpdateEvent | DeleteEvent;
+//#endregion
+//#region src/types.d.ts
+/**
+ * A pino browser transmit object for forwarding logs to an external sink (e.g. OpenTelemetry).
+ */
+type PinoTransmit = NonNullable<NonNullable<LoggerOptions['browser']>['transmit']>;
+/**
+ * The type of storage backend to use for the local database.
+ * - 'memory': In-memory storage (transient).
+ * - 'indexeddb': IndexedDB storage (persistent).
+ */
+type StoreType = 'memory' | 'indexeddb';
+/**
+ * Interface for a custom persistence client.
+ * Allows providing a custom storage mechanism for the local database.
+ */
+interface PersistenceClient {
+  /**
+   * Sets a value in the storage.
+   * @param key The key to set.
+   * @param value The value to store.
+   */
+  set<T>(key: string, value: T): Promise<void>;
+  /**
+   * Gets a value from the storage.
+   * @param key The key to retrieve.
+   * @returns The stored value or null if not found.
+   */
+  get<T>(key: string): Promise<T | null>;
+  /**
+   * Removes a value from the storage.
+   * @param key The key to remove.
+   */
+  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';
+/**
+ * Refresh behavior for `preload` when the data is already cached locally (warm).
+ * The FIRST load (cold) always fetches + blocks regardless.
+ * - `onUse` (default): do nothing when warm — the data freshens on use, when the
+ *   real `useQuery` mounts and registers its live view. No network on load.
+ * - `background`: return instantly, but kick a one-time silent refetch.
+ * - `stale`: like `background`, but only if the cached copy is older than
+ *   `staleTime`.
+ */
+type PreloadRefresh = 'onUse' | 'background' | 'stale';
+interface PreloadOptions {
+  /** How to refresh when the query is already cached locally. Default `onUse`. */
+  refresh?: PreloadRefresh;
+  /** For `refresh: 'stale'` — max age before a warm copy is refetched. Default `1h`. */
+  staleTime?: QueryTimeToLive;
+}
+/**
+ * Result object returned when a query is registered or executed.
+ */
+interface Sp00kyQueryResult {
+  /** The unique hash identifier for the query. */
+  hash: string;
+}
+type Sp00kyQueryResultPromise = Promise<Sp00kyQueryResult>;
+interface EventSubscriptionOptions {
+  priority?: number;
+}
+/**
+ * Configuration options for the Sp00ky client.
+ * @template S The schema structure type.
+ */
+interface Sp00kyConfig<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;
+  };
+  /** 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';
+  /**
+   * 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;
+  /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
+  otelTransmit?: PinoTransmit;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * Instant-hydrate cold queries: when a query is registered with no server
+   * result yet, run its surql directly on the remote (one-shot) and display
+   * the result as soon as it lands, while the full realtime registration
+   * proceeds in the background. The hydrated rows are ingested with their
+   * versions so the registration's `syncRecords` skips re-pulling unchanged
+   * bodies. The fetch runs OFF the paint path — `useQuery` resolves and paints
+   * from the local cache immediately, and hydrate only fills in what's
+   * missing. Skipped entirely when the query was `preload()`ed recently (its
+   * rows are already local and fresh; the registration re-syncs them), so a
+   * preloaded screen costs zero duplicate fetches. Defaults to `true`.
+   */
+  instantHydrate?: boolean;
+  /**
+   * Enable realtime sync while signed out. When `true`, the client starts its
+   * `_00_list_ref` poll (and a LIVE subscription) against the shared
+   * `_00_list_ref_anon` table even with no authenticated user, so a logged-out
+   * page gets live `useQuery` updates over world-readable tables. Requires the
+   * server to be deployed with `anonymousLiveQueries: true` in `sp00ky.yml`
+   * (this flag must match it). Defaults to `false`: anonymous clients can read
+   * one-shot but never sync live.
+   */
+  enableAnonymousLiveQueries?: boolean;
+  /**
+   * Surface sustained sync failures as a "degraded" health status that the app
+   * can observe via `subscribeToSyncHealth` (or the client-solid
+   * `useSyncStatus` hook) to render a "can't reach the server" banner.
+   *
+   * Individual failures — a transient remote 500 on query registration, a
+   * dropped WebSocket, etc. — are always swallowed and retried; they never
+   * throw at the app. This only controls when a *run* of consecutive failures
+   * is reported. Status flips back to `healthy` on the next successful sync
+   * round. Defaults to `{ degradeAfterConsecutiveFailures: 3 }`; pass `false`
+   * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
+   */
+  syncHealth?: SyncHealthConfig | false;
+}
+/** 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;
+}
+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;
+}
+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;
+  /**
+   * 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;
+  /** 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;
+};
+/**
+ * Runtime fetch status of a live query.
+ * - `idle`: registered, initial sync completed, and not currently fetching
+ *   missing records — the materialized rows are authoritative (a windowed
+ *   query's short result really is the end of the list).
+ * - `fetching`: the query is registering (a query is born `fetching` until its
+ *   initial remote sync completes) or the sync engine is fetching/ingesting
+ *   missing records for it. Any pending debounced result is flushed BEFORE the
+ *   flip back to `idle`, so idle status never races ahead of the rows.
+ */
+type QueryStatus = 'idle' | 'fetching';
+/**
+ * Internal state of a live query.
+ */
+interface QueryState {
+  /** The configuration for this query. */
+  config: QueryConfig;
+  /** The current cached records for this query. */
+  records: Record<string, any>[];
+  /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
+   * path fires at most once per query (see DataModule.isCold/applyHydration). */
+  hydrated?: boolean;
+  /** Set once `notifyQuerySynced` has emitted for this registration lifetime.
+   * Ephemeral (unlike the persisted `updateCount`), so a re-registered query
+   * always emits at least once even when its records are unchanged — otherwise
+   * an empty re-registered window would never notify and stay "loading". */
+  syncNotified?: boolean;
+  /** Timer for TTL expiration. */
+  ttlTimer: NodeJS.Timeout | null;
+  /** TTL duration in milliseconds. */
+  ttlDurationMs: number;
+  /** Number of times the query has been updated. */
+  updateCount: number;
+  /** Timestamp (ms) of the last user-visible update, or null before the first
+   * one. Surfaced to DevTools as `lastUpdate` — must NOT be stamped on read. */
+  lastUpdatedAt: number | null;
+  /**
+   * Rolling window of the most recent materialization-step latencies (ms).
+   * Capped at MATERIALIZATION_SAMPLE_WINDOW; used to recompute p55/p90/p99
+   * before each persist to `_00_query`. Samples themselves are not persisted.
+   */
+  materializationSamples: number[];
+  /** Most recent end-to-end ingest latency in ms, or null until the first ingest. */
+  lastIngestLatencyMs: number | null;
+  /** Cumulative count of ingest/materialization errors observed for this query. */
+  errorCount: number;
+  /**
+   * Ephemeral runtime fetch status. Not persisted to `_00_query`; observable
+   * via DevTools and the `useQuery` hook. `fetching` while the sync engine is
+   * pulling missing records for this query, otherwise `idle`.
+   */
+  status: QueryStatus;
+  /**
+   * Rolling per-phase timing samples (ms), in addition to `materializationSamples`
+   * (which holds the SSP whole-ingest wall time). Keyed by `TimingPhase` minus
+   * `ssp`. Not persisted — surfaced live to DevTools + MCP via `phaseTimings`.
+   */
+  phaseSamples: Record<string, number[]>;
+  /** Most recent sample (ms) per phase, or null. */
+  phaseLast: Record<string, number | null>;
+  /** One-shot SSP registration timings (ms). */
+  registrationTimings: RegistrationTimings;
+}
+/** Cap on the rolling materialization-sample window kept per query in memory. */
+declare const MATERIALIZATION_SAMPLE_WINDOW = 100;
+/** Timed processing phases surfaced per query. `ssp` is the WASM-ingest wall
+ *  time; the `ssp*` phases are its internal breakdown from the SSP binding. */
+type TimingPhase = 'ssp' | 'sspStoreApply' | 'sspCircuitStep' | 'sspTransform' | 'localFetch' | 'remoteFetch' | 'frontend';
+/** One-shot registration timings (ms), captured once when a query registers. */
+interface RegistrationTimings {
+  /** SSP surql→plan parse + permission injection. */
+  parseMs: number | null;
+  /** SSP operator-DAG build. */
+  planMs: number | null;
+  /** SSP initial snapshot evaluation. */
+  snapshotMs: number | null;
+  /** Wall time of `cache.registerQuery` (register_view round-trip). */
+  wallMs: number | null;
+}
+/** Percentile summary for one timed phase, surfaced to DevTools + MCP. */
+interface PhaseStat {
+  lastMs: number | null;
+  p50: number | null;
+  p90: number | null;
+  p99: number | null;
+  count: number;
+}
+/** Per-query processing-time breakdown surfaced via DevTools panel + MCP. */
+interface QueryTimings {
+  ssp: PhaseStat;
+  sspStoreApply: PhaseStat;
+  sspCircuitStep: PhaseStat;
+  sspTransform: PhaseStat;
+  localFetch: PhaseStat;
+  remoteFetch: PhaseStat;
+  frontend: PhaseStat;
+  registration: RegistrationTimings;
+  updateCount: number;
+  errorCount: number;
+}
+type QueryUpdateCallback = (records: Record<string, any>[]) => void;
+type QueryStatusCallback = (status: QueryStatus) => void;
+type MutationCallback = (mutations: UpEvent[]) => void;
+type MutationEventType = 'create' | 'update' | 'delete';
+/**
+ * Represents a mutation event (create, update, delete) to be synchronized.
+ */
+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;
+}
+/**
+ * Options for run operations.
+ */
+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;
+  /**
+   * Interval in milliseconds for a RECURRING job (see `runRecurring`). When set,
+   * the job re-runs `interval` ms after each run COMPLETES (drift-free from
+   * completion, not wall-clock). Ignored by the plain `run`.
+   */
+  interval?: number;
+}
+/**
+ * Options for update operations.
+ */
+interface UpdateOptions {
+  /**
+   * Debounce configuration for the update.
+   * If boolean, enables default debounce behavior.
+   */
+  debounced?: boolean | DebounceOptions;
+}
+/**
+ * Configuration options for debouncing updates.
+ */
+interface DebounceOptions {
+  /**
+   * 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.
+   */
+  key?: 'recordId' | 'recordId_x_fields';
+  /** The debounce delay in milliseconds. */
+  delay?: number;
+}
+//#endregion
+export { SyncHealth as A, Logger$1 as B, RecordVersionDiff as C, Sp00kyQueryResult as D, Sp00kyConfig as E, UpEvent as F, EventDefinition as H, LocalStore as I, SealedQuery as L, SyncHealthStatus as M, TimingPhase as N, Sp00kyQueryResultPromise as O, UpdateOptions as P, DatabaseEventSystem as R, RecordVersionArray as S, RunOptions as T, EventSystem as U, SyncEventSystem as V, QueryStatus as _, MutationCallback as a, QueryTimings as b, PersistenceClient as c, PreloadOptions as d, PreloadRefresh as f, QueryState as g, QueryHash as h, MATERIALIZATION_SAMPLE_WINDOW as i, SyncHealthConfig as j, StoreType as k, PhaseStat as l, QueryConfigRecord as m, EventSubscriptionOptions as n, MutationEvent as o, QueryConfig as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryStatusCallback as v, RegistrationTimings as w, QueryUpdateCallback as x, QueryTimeToLive as y, DatabaseEventTypes as z };