@spooky-sync/core 0.0.1-canary.74 → 0.0.1-canary.76

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Logger$1, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, M as EventSystem, O as TimingPhase, 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 EventDefinition, k as UpdateOptions, 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 { A as UpEvent, C as RunOptions, D as StoreType, E as Sp00kyQueryResultPromise, M as SyncEventSystem, N as EventDefinition, O as TimingPhase, P as EventSystem, 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 Logger$1, k as UpdateOptions, 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 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";
@@ -88,6 +88,33 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
   invalidate(): Promise<void>;
 }
 //#endregion
+//#region src/modules/sync/queue/queue-down.d.ts
+type RegisterEvent = {
+  type: 'register';
+  payload: {
+    hash: string;
+  };
+};
+type SyncEvent = {
+  type: 'sync';
+  payload: {
+    hash: string;
+  };
+};
+type HeartbeatEvent = {
+  type: 'heartbeat';
+  payload: {
+    hash: string;
+  };
+};
+type CleanupEvent = {
+  type: 'cleanup';
+  payload: {
+    hash: string;
+  };
+};
+type DownEvent = RegisterEvent | SyncEvent | HeartbeatEvent | CleanupEvent;
+//#endregion
 //#region src/services/stream-processor/wasm-types.d.ts
 interface WasmStreamUpdate {
   query_id: string;
@@ -159,6 +186,7 @@ declare class StreamProcessorService {
   private receivers;
   private batching;
   private batchBuffer;
+  private sessionAuth;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -213,6 +241,17 @@ declare class StreamProcessorService {
    * 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.
@@ -232,6 +271,483 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
+//#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
+/**
+ * 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.
+ */
+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);
+  /**
+   * Implements StreamUpdateReceiver interface
+   * Called directly by StreamProcessor when views change
+   */
+  onStreamUpdate(update: StreamUpdate): void;
+  lookup(recordId: string): number;
+  /**
+   * Save a single record to local DB and ingest into DBSP
+   * Used by mutations (create/update)
+   */
+  save(cacheRecord: CacheRecord, skipDbInsert?: boolean): Promise<void>;
+  /**
+   * Save multiple records in a batch
+   * More efficient than calling save() multiple times
+   * Used by sync operations
+   */
+  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;
+    };
+  };
+  /**
+   * Unregister a query from DBSP
+   */
+  unregisterQuery(queryHash: string): void;
+}
+//#endregion
+//#region src/modules/data/index.d.ts
+/**
+ * DataModule - Unified query and mutation management
+ *
+ * Merges the functionality of QueryManager and MutationManager.
+ * Uses CacheModule for all storage operations.
+ */
+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;
+}
+/**
+ * Parse update options to generate push event options
+ */
+//#endregion
+//#region src/modules/sync/sync.d.ts
+/**
+ * Tunables for `Sp00kySync` construction.
+ */
+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;
+}
+/**
+ * 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.
+ */
+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 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;
+  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
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
@@ -254,6 +770,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;
@@ -275,6 +798,9 @@ 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>;
 }
@@ -423,6 +949,54 @@ declare class CrdtManager {
   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;
@@ -448,6 +1022,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private sync;
   private devTools;
   private crdtManager;
+  private featureFlags;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
@@ -468,6 +1043,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   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.
@@ -538,4 +1123,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, 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, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+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, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };