@spooky-sync/core 0.0.1-canary.66 → 0.0.1-canary.67

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Logger$1, S as UpdateOptions, T as EventSystem, _ as RunOptions, a as MutationEvent, b as Sp00kyQueryResultPromise, c as PinoTransmit, d as QueryHash, f as QueryState, g as RecordVersionDiff, h as RecordVersionArray, i as MutationCallback, l as QueryConfig, m as QueryUpdateCallback, n as EventSubscriptionOptions, o as MutationEventType, p as QueryTimeToLive, r as Level, s as PersistenceClient, t as DebounceOptions, u as QueryConfigRecord, v as Sp00kyConfig, w as EventDefinition, x as StoreType, y as Sp00kyQueryResult } from "./types.js";
+import { C as UpdateOptions, E as EventSystem, S as StoreType, T as EventDefinition, _ as RecordVersionDiff, a as MutationCallback, b as Sp00kyQueryResult, c as PersistenceClient, d as QueryConfigRecord, f as QueryHash, g as RecordVersionArray, h as QueryUpdateCallback, i as MATERIALIZATION_SAMPLE_WINDOW, l as PinoTransmit, m as QueryTimeToLive, n as EventSubscriptionOptions, o as MutationEvent, p as QueryState, r as Level, s as MutationEventType, t as DebounceOptions, u as QueryConfig, v as RunOptions, w as Logger$1, x as Sp00kyQueryResultPromise, y as Sp00kyConfig } 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";
@@ -97,6 +97,12 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * End-to-end ingest latency for the WASM call that produced this update,
+   * in milliseconds. Populated by StreamProcessorService.ingest. Undefined
+   * for the initial register_view snapshot.
+   */
+  materializationTimeMs?: number;
 }
 type StreamProcessorEvents = {
   stream_update: EventDefinition<'stream_update', StreamUpdate[]>;
@@ -202,33 +208,55 @@ declare class CrdtField {
   private fieldName;
   private doc;
   private pushTimer;
+  private local;
   private remote;
   private recordId;
+  private sessionId;
   private unsubscribe;
   private lastPushTime;
   private lastCursorPushTime;
   private loadedFromCrdt;
   private pushRetryCount;
   private logger;
+  private cursorsEnabled;
+  /** Remote-push debounce. Local writes happen immediately on every Loro
+   *  update; the remote UPSERT is coalesced over this window. Configured
+   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
+  private remoteDebounceMs;
   private _onCursorUpdate;
   private pendingCursorUpdate;
   /** Callback set by the editor to receive remote cursor updates.
    *  Any cursor data that arrived before this callback was set will be replayed. */
   set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
   get onCursorUpdate(): ((data: Uint8Array) => void) | null;
-  constructor(fieldName: string, initialState?: string, logger?: Logger$1 | null);
+  constructor(fieldName: string, cursorsEnabled: boolean, initialState?: Uint8Array, logger?: Logger$1 | null);
   getDoc(): LoroDoc;
   /** Whether the LoroDoc was loaded from saved CRDT state */
   hasContent(): boolean;
-  startSync(remote: RemoteDatabaseService, recordId: string): void;
+  startSync(local: LocalDatabaseService, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
   stopSync(): void;
-  importRemote(base64State: string): void;
-  exportSnapshot(): string;
-  /** Push cursor ephemeral state to _00_crdt as a "_cursor_<fieldName>" entry */
+  importRemote(state: Uint8Array): void;
+  exportSnapshot(): Uint8Array;
+  /** Push this session's cursor blob into the parent row at
+   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
+   *  field — the editor still calls this method optimistically, but
+   *  without `@cursor` on the schema there's nowhere to store the blob.
+   *  The UPDATE itself fires the parent table's LIVE feed, so other
+   *  browsers receive the cursor change without a separate `_00_rv` bump. */
   pushCursorState(encoded: Uint8Array): Promise<void>;
   /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
   importRemoteCursor(base64State: string): void;
-  private schedulePush;
+  private scheduleRemotePush;
+  /** SET path inside a parent row for the current snapshot. `@crdt`-only
+   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
+   *  fields hold a `{ state, cursors }` object so the snapshot lives at
+   *  `<field>.state` next to per-session cursor blobs. */
+  private statePath;
+  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
+   *  every local update and every remote import so reloads (online or
+   *  offline) see the freshest content immediately. Failures are
+   *  swallowed — a stale local write must never block user input. */
+  private persistLocal;
   private pushToRemote;
 }
 //#endregion
@@ -236,16 +264,40 @@ declare class CrdtField {
 /**
  * CrdtManager manages active CrdtField instances and their sync channels.
  *
- * Each open record gets a LIVE SELECT on _00_crdt that delivers remote
- * changes in real time.
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
  */
 declare class CrdtManager {
   private schema;
+  private local;
   private remote;
+  private debounceMs;
   private fields;
-  private liveQueries;
+  private liveByTable;
+  private pendingLive;
   private logger;
-  constructor(schema: SchemaStructure, remote: RemoteDatabaseService, logger: Logger$1);
+  private sessionId;
+  constructor(schema: SchemaStructure, local: LocalDatabaseService, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void;
   /**
    * Open a CRDT field for collaborative editing.
    *
@@ -258,8 +310,32 @@ declare class CrdtManager {
   open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
   close(table: string, recordId: string, field: string): void;
   closeAll(): void;
-  private ensureLiveSelect;
-  private killLiveSelect;
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private ensureTableSubscription;
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void;
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow;
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private fetchAndDispatchRow;
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor;
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot;
+  private killTableSubscription;
   private makeKey;
   /**
    * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
@@ -300,6 +376,12 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   get remoteClient(): surrealdb0.Surreal;
   get localClient(): surrealdb0.Surreal;
   get pendingMutationCount(): number;
+  /** Number of times the initial list_ref LIVE subscription retried on
+   *  the most recent `setCurrentUserId` call. 0 when the SSP's
+   *  pre-emptive user-table creation got there first; >0 when LIVE
+   *  registration hit a "table not found" race. Exposed so the e2e
+   *  suite can guard the pre-emptive path against regression. */
+  get liveRetryCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
   constructor(config: Sp00kyConfig<S>);
   /**
@@ -312,7 +394,8 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   /**
    * Open a CRDT field for collaborative editing.
    * Returns a CrdtField with a LoroDoc that can be bound to any editor.
-   * Also starts a LIVE SELECT on _00_crdt for real-time sync.
+   * Also starts a LIVE SELECT on the parent table for real-time sync;
+   * incoming events trigger a subquery fetch of `_00_crdt` / `_00_cursor`.
    */
   openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
   /**
@@ -334,8 +417,13 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   }>;
   delete(table: string, id: string): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
-  private persistClientId;
-  private loadOrGenerateClientId;
+  /**
+   * Fetch SurrealDB's `session::id()` as a string. Used as a salt for
+   * query-id hashing so two sessions for the same user get distinct
+   * `_00_query` rows. Returns empty string if the query fails (we still
+   * boot, just without session scoping for IDs).
+   */
+  private fetchSessionId;
 }
 //#endregion
 //#region src/utils/index.d.ts
@@ -350,4 +438,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PinoTransmit, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryTimeToLive, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };