@spooky-sync/core 0.0.1-canary.73 → 0.0.1-canary.75

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;
@@ -232,6 +259,438 @@ 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  heartbeatQuery(queryHash: string): Promise<void>;
+  private cleanupQuery;
+}
+//#endregion
 //#region src/modules/auth/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
@@ -423,6 +882,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 +955,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private sync;
   private devTools;
   private crdtManager;
+  private featureFlags;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
@@ -468,6 +976,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 +1056,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 };

package/dist/index.js

@@ -3171,8 +3171,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.73";
-const WASM_VERSION = "0.0.1-canary.73";
+const CORE_VERSION = "0.0.1-canary.75";
+const WASM_VERSION = "0.0.1-canary.75";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -4626,6 +4626,135 @@ var CrdtManager = class {
 	}
 };
 
+//#endregion
+//#region src/modules/feature-flag/index.ts
+const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature WHERE key = $key";
+var FeatureFlagHandle = class {
+	latest = {
+		variant: void 0,
+		payload: void 0
+	};
+	listeners = /* @__PURE__ */ new Set();
+	unsubscribeFn = null;
+	onCloseFn = null;
+	closed = false;
+	constructor(key, fallback) {
+		this.key = key;
+		this.fallback = fallback;
+	}
+	attach(unsubscribe) {
+		this.unsubscribeFn?.();
+		this.unsubscribeFn = unsubscribe;
+	}
+	detach() {
+		this.unsubscribeFn?.();
+		this.unsubscribeFn = null;
+	}
+	set(snapshot) {
+		if (this.closed) return;
+		this.latest = snapshot;
+		for (const cb of this.listeners) cb(snapshot);
+	}
+	variant() {
+		return this.latest.variant ?? this.fallback;
+	}
+	payload() {
+		return this.latest.payload;
+	}
+	enabled() {
+		const v = this.variant();
+		return v !== void 0 && v !== "off";
+	}
+	subscribe(cb) {
+		this.listeners.add(cb);
+		cb({
+			variant: this.variant(),
+			payload: this.latest.payload
+		});
+		return () => {
+			this.listeners.delete(cb);
+		};
+	}
+	onClose(cb) {
+		this.onCloseFn = cb;
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.listeners.clear();
+		this.detach();
+		this.onCloseFn?.();
+	}
+};
+var FeatureFlagModule = class {
+	logger;
+	active = /* @__PURE__ */ new Set();
+	authUnsubscribe = null;
+	lastUserId = null;
+	constructor(deps) {
+		this.deps = deps;
+		this.logger = deps.logger.child({ service: "FeatureFlagModule" });
+	}
+	init() {
+		if (this.authUnsubscribe) return;
+		this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+			if (userId === this.lastUserId) return;
+			this.lastUserId = userId;
+			this.refreshAll();
+		});
+	}
+	feature(key, options = {}) {
+		const handle = new FeatureFlagHandle(key, options.fallback);
+		const entry = {
+			handle,
+			ttl: options.ttl ?? "10m"
+		};
+		this.active.add(entry);
+		handle.onClose(() => this.active.delete(entry));
+		this.register(entry);
+		return handle;
+	}
+	async closeAll() {
+		this.authUnsubscribe?.();
+		this.authUnsubscribe = null;
+		for (const entry of [...this.active]) entry.handle.close();
+	}
+	async refreshAll() {
+		for (const entry of this.active) {
+			entry.handle.detach();
+			entry.handle.set({
+				variant: void 0,
+				payload: void 0
+			});
+			await this.register(entry);
+		}
+	}
+	async register(entry) {
+		const { handle, ttl } = entry;
+		try {
+			const hash = await this.deps.dataModule.query("_00_user_feature", FEATURE_QUERY, { key: handle.key }, ttl);
+			this.deps.sync.enqueueDownEvent({
+				type: "register",
+				payload: { hash }
+			});
+			const unsub = this.deps.dataModule.subscribe(hash, (records) => {
+				const row = records[0];
+				handle.set({
+					variant: row?.variant,
+					payload: row?.payload
+				});
+			}, { immediate: true });
+			handle.attach(unsub);
+		} catch (err) {
+			this.logger.warn({
+				err,
+				key: handle.key,
+				Category: "sp00ky-client::FeatureFlagModule::register"
+			}, "Failed to register feature flag query");
+		}
+	}
+};
+
 //#endregion
 //#region src/services/persistence/localstorage.ts
 var LocalStoragePersistenceClient = class {
@@ -4780,6 +4909,7 @@ var Sp00kyClient = class {
 	sync;
 	devTools;
 	crdtManager;
+	featureFlags;
 	logger;
 	auth;
 	streamProcessor;
@@ -4829,6 +4959,12 @@ var Sp00kyClient = class {
 		this.dataModule = new DataModule(this.cache, this.local, this.config.schema, logger, this.config.streamDebounceTime);
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
 		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, { refSyncIntervalMs: this.config.refSyncIntervalMs });
+		this.featureFlags = new FeatureFlagModule({
+			dataModule: this.dataModule,
+			sync: this.sync,
+			auth: this.auth,
+			logger
+		});
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
@@ -4925,6 +5061,8 @@ var Sp00kyClient = class {
 			});
 			await this.sync.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sync initialized");
+			this.featureFlags.init();
+			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "FeatureFlagModule initialized");
 			this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization completed successfully");
 		} catch (e) {
 			this.logger.error({
@@ -4935,10 +5073,23 @@ var Sp00kyClient = class {
 		}
 	}
 	async close() {
+		await this.featureFlags.closeAll();
 		this.crdtManager.closeAll();
 		await this.local.close();
 		await this.remote.close();
 	}
+	/**
+	* 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, options) {
+		return this.featureFlags.feature(key, options);
+	}
 	authenticate(token) {
 		return this.remote.getClient().authenticate(token);
 	}
@@ -5056,4 +5207,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/dist/types.d.ts

@@ -123,6 +123,32 @@ declare class EventSystem<E extends EventTypeMap> {
   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";
+};
+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;
+  }>;
+};
+type SyncEventSystem = EventSystem<SyncEventTypeMap>;
+//#endregion
 //#region src/services/logger/index.d.ts
 type Logger$1 = Logger;
 //#endregion
@@ -457,4 +483,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { Logger$1 as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, EventSystem as M, TimingPhase as O, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, EventDefinition as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };
+export { UpEvent as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SyncEventSystem as M, EventDefinition as N, TimingPhase as O, EventSystem as P, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, Logger$1 as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.73",
+  "version": "0.0.1-canary.75",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.73",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.73",
+    "@spooky-sync/query-builder": "0.0.1-canary.75",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.75",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/index.ts

@@ -2,4 +2,10 @@ export * from './types';
 export * from './sp00ky';
 export * from './modules/auth/index';
 export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export {
+  FeatureFlagModule,
+  FeatureFlagHandle,
+  type FeatureFlagOptions,
+  type FeatureFlagSnapshot,
+} from './modules/feature-flag/index';
 export { fileToUint8Array, textToHtml } from './utils/index';

package/src/modules/feature-flag/index.ts

@@ -0,0 +1,166 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { DataModule } from '../data/index';
+import type { Sp00kySync } from '../sync/index';
+import type { AuthService } from '../auth/index';
+import type { Logger } from '../../services/logger/index';
+import type { QueryTimeToLive } from '../../types';
+
+const FEATURE_QUERY =
+  'SELECT key, variant, payload FROM _00_user_feature WHERE key = $key';
+
+export interface FeatureFlagSnapshot {
+  variant: string | undefined;
+  payload: unknown | undefined;
+}
+
+export interface FeatureFlagOptions {
+  fallback?: string;
+  ttl?: QueryTimeToLive;
+}
+
+export class FeatureFlagHandle {
+  private latest: FeatureFlagSnapshot = { variant: undefined, payload: undefined };
+  private listeners = new Set<(s: FeatureFlagSnapshot) => void>();
+  private unsubscribeFn: (() => void) | null = null;
+  private onCloseFn: (() => void) | null = null;
+  private closed = false;
+
+  constructor(
+    public readonly key: string,
+    public readonly fallback: string | undefined,
+  ) {}
+
+  attach(unsubscribe: () => void): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = unsubscribe;
+  }
+
+  detach(): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = null;
+  }
+
+  set(snapshot: FeatureFlagSnapshot): void {
+    if (this.closed) return;
+    this.latest = snapshot;
+    for (const cb of this.listeners) cb(snapshot);
+  }
+
+  variant(): string | undefined {
+    return this.latest.variant ?? this.fallback;
+  }
+
+  payload<T = unknown>(): T | undefined {
+    return this.latest.payload as T | undefined;
+  }
+
+  enabled(): boolean {
+    const v = this.variant();
+    return v !== undefined && v !== 'off';
+  }
+
+  subscribe(cb: (s: FeatureFlagSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    cb({ variant: this.variant(), payload: this.latest.payload });
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  onClose(cb: () => void): void {
+    this.onCloseFn = cb;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.detach();
+    this.onCloseFn?.();
+  }
+}
+
+export interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger;
+}
+
+interface ActiveHandle {
+  handle: FeatureFlagHandle;
+  ttl: QueryTimeToLive;
+}
+
+export class FeatureFlagModule<S extends SchemaStructure> {
+  private logger: Logger;
+  private active = new Set<ActiveHandle>();
+  private authUnsubscribe: (() => void) | null = null;
+  private lastUserId: string | null = null;
+
+  constructor(private deps: FeatureFlagModuleDeps<S>) {
+    this.logger = deps.logger.child({ service: 'FeatureFlagModule' });
+  }
+
+  init(): void {
+    if (this.authUnsubscribe) return;
+    this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+      if (userId === this.lastUserId) return;
+      this.lastUserId = userId;
+      void this.refreshAll();
+    });
+  }
+
+  feature(key: string, options: FeatureFlagOptions = {}): FeatureFlagHandle {
+    const handle = new FeatureFlagHandle(key, options.fallback);
+    const entry: ActiveHandle = { handle, ttl: options.ttl ?? '10m' };
+    this.active.add(entry);
+    handle.onClose(() => this.active.delete(entry));
+    void this.register(entry);
+    return handle;
+  }
+
+  async closeAll(): Promise<void> {
+    this.authUnsubscribe?.();
+    this.authUnsubscribe = null;
+    for (const entry of [...this.active]) entry.handle.close();
+  }
+
+  private async refreshAll(): Promise<void> {
+    for (const entry of this.active) {
+      entry.handle.detach();
+      entry.handle.set({ variant: undefined, payload: undefined });
+      await this.register(entry);
+    }
+  }
+
+  private async register(entry: ActiveHandle): Promise<void> {
+    const { handle, ttl } = entry;
+    try {
+      const hash = await this.deps.dataModule.query(
+        '_00_user_feature' as any,
+        FEATURE_QUERY,
+        { key: handle.key },
+        ttl,
+      );
+
+      this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+
+      const unsub = this.deps.dataModule.subscribe(
+        hash,
+        (records) => {
+          const row = records[0] as { variant?: string; payload?: unknown } | undefined;
+          handle.set({ variant: row?.variant, payload: row?.payload });
+        },
+        { immediate: true },
+      );
+
+      handle.attach(unsub);
+    } catch (err) {
+      this.logger.warn(
+        { err, key: handle.key, Category: 'sp00ky-client::FeatureFlagModule::register' },
+        'Failed to register feature flag query',
+      );
+    }
+  }
+}

package/src/sp00ky.ts

@@ -38,6 +38,8 @@ import { EventSystem } from './events/index';
 import { CacheModule } from './modules/cache/index';
 import type { RecordWithId } from './modules/cache/index';
 import { CrdtManager, CrdtField } from './modules/crdt/index';
+import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
+import type { FeatureFlagOptions } from './modules/feature-flag/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
 import { parseParams } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
@@ -95,6 +97,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private sync: Sp00kySync<S>;
   private devTools: DevToolsService;
   private crdtManager: CrdtManager;
+  private featureFlags!: FeatureFlagModule<S>;
 
   private logger: ReturnType<typeof createLogger>;
   public auth: AuthService<S>;
@@ -203,6 +206,16 @@ export class Sp00kyClient<S extends SchemaStructure> {
       { refSyncIntervalMs: this.config.refSyncIntervalMs }
     );
 
+    // Initialize feature flags. Reuses the down-queue to register SSP plans
+    // on `_00_user_feature` and the auth subscription to re-register handles
+    // when the signed-in user changes.
+    this.featureFlags = new FeatureFlagModule({
+      dataModule: this.dataModule,
+      sync: this.sync,
+      auth: this.auth,
+      logger,
+    });
+
     // Initialize DevTools
     this.devTools = new DevToolsService(
       this.local,
@@ -384,6 +397,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
       await this.sync.init();
       this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Sync initialized');
 
+      this.featureFlags.init();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        'FeatureFlagModule initialized'
+      );
+
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kyClient::init' },
         'Sp00kyClient initialization completed successfully'
@@ -398,11 +417,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   async close() {
+    await this.featureFlags.closeAll();
     this.crdtManager.closeAll();
     await this.local.close();
     await this.remote.close();
   }
 
+  /**
+   * 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 {
+    return this.featureFlags.feature(key, options);
+  }
+
   authenticate(token: string) {
     return this.remote.getClient().authenticate(token);
   }