@spooky-sync/core 0.0.1-canary.161 → 0.0.1-canary.162

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { A as StorageHealthStatus, B as DatabaseEventSystem, C as RecordVersionDiff, D as Sp00kyQueryResult, E as Sp00kyConfig, F as TimingPhase, G as EventSystem, H as Logger$1, I as UpdateOptions, L as UpEvent, M as SyncHealth, N as SyncHealthConfig, O as Sp00kyQueryResultPromise, P as SyncHealthStatus, R as LocalStore, S as RecordVersionArray, T as RunOptions, U as SyncEventSystem, V as DatabaseEventTypes, W as EventDefinition, _ as QueryStatus, a as MutationCallback, b as QueryTimings, c as PersistenceClient, d as PreloadOptions, f as PreloadRefresh, g as QueryState, h as QueryHash, i as MATERIALIZATION_SAMPLE_WINDOW, j as StoreType, k as StorageHealth, l as PhaseStat, m as QueryConfigRecord, n as EventSubscriptionOptions, o as MutationEvent, p as QueryConfig, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryStatusCallback, w as RegistrationTimings, x as QueryUpdateCallback, y as QueryTimeToLive, z as SealedQuery } from "./types.js";
+import { A as Sp00kyQueryResultPromise, B as LocalStore, C as ReconnectConfig, D as RunOptions, E as RegistrationTimings, F as SyncHealthConfig, G as SyncEventSystem, H as DatabaseEventSystem, I as SyncHealthStatus, K as EventDefinition, L as TimingPhase, M as StorageHealthStatus, N as StoreType, O as Sp00kyConfig, P as SyncHealth, R as UpdateOptions, S as QueryUpdateCallback, T as RecordVersionDiff, U as DatabaseEventTypes, V as SealedQuery, W as Logger$1, _ as QueryState, a as MATERIALIZATION_SAMPLE_WINDOW, b as QueryTimeToLive, c as MutationEventType, d as PinoTransmit, f as PreloadOptions, g as QueryHash, h as QueryConfigRecord, i as Level, j as StorageHealth, k as Sp00kyQueryResult, l as PersistenceClient, m as QueryConfig, n as DebounceOptions, o as MutationCallback, p as PreloadRefresh, q as EventSystem, r as EventSubscriptionOptions, s as MutationEvent, t as ConnectionState, u as PhaseStat, v as QueryStatus, w as RecordVersionArray, x as QueryTimings, y as QueryStatusCallback, z as UpEvent } from "./types.js";
 import * as surrealdb0 from "surrealdb";
-import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
+import { Duration, RecordId, Surreal as Surreal$1, SurrealEvents, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import { Logger } from "pino";
 import { LoroDoc } from "loro-crdt";
@@ -10,6 +10,13 @@ declare abstract class AbstractDatabaseService {
   protected client: Surreal$1;
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
+  /**
+   * Per-query deadline in ms; `0` disables. Only the remote service sets this
+   * (see `RemoteDatabaseService`) — a local query can be legitimately slow and
+   * has its own retry ladders, and there is no half-open-socket failure mode
+   * for an in-process engine.
+   */
+  protected queryTimeoutMs: number;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
   constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
@@ -19,6 +26,11 @@ declare abstract class AbstractDatabaseService {
   private queryQueue;
   /**
    * Execute a query with serialized execution to prevent WASM transaction issues.
+   *
+   * Serialization means every query waits on the previous one, so a call that
+   * never settles blocks the whole chain forever. {@link queryTimeoutMs} bounds
+   * each link: on expiry this promise rejects and the chain moves on, even
+   * though the underlying RPC is still parked in the SDK's pending map.
    */
   query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
   execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>): Promise<T>;
@@ -26,18 +38,144 @@ declare abstract class AbstractDatabaseService {
 }
 //#endregion
 //#region src/services/database/remote.d.ts
+/** Transport events the SDK publishes, mapped 1:1 to {@link ConnectionState}. */
+type RemoteConnectionEvent = ConnectionState | 'error';
 declare class RemoteDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_REMOTE_QUERY";
+  private readonly reconnectConfig;
+  /**
+   * In-flight `connect()`, so concurrent callers (boot + supervisor revive +
+   * an `online` event landing at the same moment) share one attempt instead of
+   * racing two sockets. Cleared on settle, so a later call always reconnects.
+   */
+  private connecting;
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
   getConfig(): Sp00kyConfig<any>['database'];
+  /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
+  getReconnectConfig(): Required<ReconnectConfig>;
+  /** Current transport state as reported by the SDK. */
+  getStatus(): ConnectionState;
+  /**
+   * Observe transport events. Thin passthrough so callers (the supervisor,
+   * sync, CRDT) don't have to reach through `getClient()`.
+   */
+  subscribeConnection<K extends RemoteConnectionEvent>(event: K, cb: (...payload: SurrealEvents[K]) => void): () => void;
+  /**
+   * Tear the socket down on purpose. Used by the heartbeat watchdog when a
+   * socket stops answering but never closes: `close()` makes the SDK publish
+   * `disconnected`, which is what drives the supervisor's revive loop.
+   */
+  forceClose(): Promise<void>;
+  /**
+   * Open (or re-open) the remote connection.
+   *
+   * Safe to call repeatedly: concurrent calls share the in-flight attempt, and
+   * a call after a `disconnected` builds a fresh socket. `use()` and
+   * `authenticate()` are re-applied here for the cold path; the SDK also
+   * replays them itself on its own internal reconnects.
+   */
   connect(): Promise<void>;
+  private doConnect;
   signin(params: any): Promise<any>;
   signup(params: any): Promise<any>;
   authenticate(token: string): Promise<any>;
   invalidate(): Promise<void>;
 }
 //#endregion
+//#region src/services/database/connection-supervisor.d.ts
+/**
+ * Keeps the remote WebSocket alive for the whole life of the page.
+ *
+ * The SurrealDB SDK reconnects on its own after a socket `close`, but that
+ * covers only one of three ways the connection dies:
+ *
+ * 1. **Socket closes, SDK recovers.** Handled entirely by the SDK. This
+ *    supervisor only observes it (to report `reconnecting` upward).
+ * 2. **Socket closes, SDK gives up.** With `attempts: -1` this shouldn't happen
+ *    from exhaustion — but the SDK also terminates the engine permanently when
+ *    its post-reconnect handshake throws (it re-runs `version()`, `use()`,
+ *    `authenticate()` on every reconnect and closes the engine on any error).
+ *    One transient hiccup there would otherwise kill the page's connection for
+ *    good. The revive loop re-opens from scratch.
+ * 3. **Socket never closes at all.** A half-open connection: the peer is gone
+ *    (NAT timeout, wifi switch, laptop sleep) but no FIN ever arrives, so
+ *    `readyState` stays OPEN and the SDK's own 30s ping — fire-and-forget, no
+ *    response deadline — never notices. Nothing ever fires a `close` event, so
+ *    nothing ever triggers a reconnect. The heartbeat detects this and forces
+ *    the teardown that case 2's loop then repairs.
+ *
+ * Plus wake triggers: coming back `online` or un-hiding the tab probes
+ * immediately rather than waiting out a backoff that was scheduled while the
+ * network was known-down.
+ */
+declare class ConnectionSupervisor {
+  private readonly remote;
+  private readonly logger;
+  private readonly config;
+  private state;
+  private subscribers;
+  private started;
+  private disposed;
+  private heartbeatTimer;
+  private heartbeatInFlight;
+  private reviveTimer;
+  private reviveAttempts;
+  private reviving;
+  /**
+   * Set while the browser reports itself offline. Retrying a socket against a
+   * down interface only burns backoff, so the loop parks until `online` fires.
+   */
+  private suspended;
+  private teardown;
+  private static readonly REVIVE_BASE_MS;
+  constructor(remote: RemoteDatabaseService, logger: Logger$1, config?: Required<ReconnectConfig>);
+  /** Latest observed transport state. */
+  get connection(): ConnectionState;
+  /**
+   * Observe transport state. Fires immediately with the current value and again
+   * on every change. Returns an unsubscribe.
+   */
+  subscribe(cb: (state: ConnectionState) => void): () => void;
+  /**
+   * Begin supervising. Call once, after the initial {@link
+   * RemoteDatabaseService.connect}. Idempotent.
+   */
+  start(): void;
+  /** Stop all timers and listeners. Safe to call more than once. */
+  dispose(): void;
+  private setState;
+  private clearReviveTimer;
+  /**
+   * Queue the next `connect()` attempt on exponential backoff, capped at
+   * `superviseRetryDelayMaxMs`. Never gives up — the page is expected to
+   * outlive any outage.
+   */
+  private scheduleRevive;
+  private revive;
+  private stopHeartbeat;
+  private startHeartbeat;
+  /**
+   * Probe the server end-to-end. Deliberately goes through
+   * `remote.query` — the same serialized queue every other remote call uses —
+   * so a queue wedged behind a stuck RPC also fails the heartbeat instead of
+   * being invisible to it.
+   */
+  private beat;
+  /**
+   * A restored network or an un-hidden tab is the strongest available hint that
+   * a reconnect will now succeed, so probe immediately instead of waiting out a
+   * backoff scheduled under worse conditions.
+   */
+  private installWakeTriggers;
+  /**
+   * Reset the backoff and act on whichever problem is present: reconnect if the
+   * socket is gone, otherwise probe it (it may be half-open — which is exactly
+   * what a sleep/wake cycle produces).
+   */
+  private wake;
+}
+//#endregion
 //#region src/modules/sync/queue/queue-down.d.ts
 type RegisterEvent = {
   type: 'register';
@@ -488,7 +626,55 @@ declare class DataModule<S extends SchemaStructure> {
    * await so a concurrently-firing timer can't process it twice.
    */
   flushPendingStreamUpdate(queryHash: string): Promise<void>;
+  /**
+   * Materialize a query's result rows from the local store.
+   *
+   * A query's rows are its MEMBERSHIP — the id-set the server put in
+   * `_00_list_ref` (`remoteArray`) — not "every local body that matches the
+   * WHERE". Those two disagree, and the disagreement was the bug: when a row
+   * leaves a query's window but still exists upstream, `handleRemovedRecords`
+   * keeps its local body and never re-fetches it, so a predicate re-scan finds
+   * that stale body still matching and keeps rendering the row. Selecting the
+   * id-set directly is also the only correct thing for a windowed query, where
+   * re-applying `START m` against the shared local store skips the window's own
+   * rows entirely (sparse windowing) and returns nothing.
+   *
+   * The rendered set is:
+   *
+   *     (membership ∪ (pendingWrites ∩ localArray)) − pendingDeletes
+   *
+   * The middle term keeps optimistic writes visible without re-admitting stale
+   * rows. Every local write is fed to the SSP (`cache.saveBatch` →
+   * `ingestMany`), so `localArray` answers "does this row match the predicate
+   * per LOCAL truth". A pending write that moves a row into the window is in
+   * `localArray` and shows; one that moves a row out is absent and does not; a
+   * stale body the server dropped has no pending write at all, so it stays out.
+   * `pendingDeletes` covers the reverse lag — the server still lists a row whose
+   * DELETE is sitting in our outbox.
+   *
+   * Falls back to the predicate scan only when membership has never been
+   * established (a query first run on this device), so an offline first paint
+   * still shows something.
+   */
   private materializeRecords;
+  /**
+   * The materialization itself, without the DevTools timing wrapper. Split out so
+   * cold-start seeding can use it before a `QueryState` exists.
+   */
+  private materializeFromConfig;
+  /**
+   * The authoritative membership list to render from, or `null` when membership
+   * has never been established and the caller must fall back to a scan.
+   *
+   * A windowed query has no usable fallback — re-running its `START m` locally
+   * returns the wrong rows — so it renders from whatever id-set is on hand
+   * (SSP's included) rather than degrading to a scan. That is the pre-existing
+   * behavior for windows and is preserved.
+   */
+  private resolveMembership;
+  /** Apply the pending-write union and pending-delete subtraction, and map to
+   *  RecordIds for the engines' id-set path. */
+  private buildRenderIds;
   private processStreamUpdate;
   /**
    * Compute p55/p90/p99 from a rolling window of materialization samples.
@@ -585,6 +771,32 @@ declare class DataModule<S extends SchemaStructure> {
   } | null>;
   /** Stamp the preload freshness marker after a successful snapshot fetch. */
   writePreloadMarker(hash: string, rowCount: number): Promise<void>;
+  /**
+   * Read the durable membership row, or `null` if this query has never had
+   * authoritative membership on this device. Any read error is treated as
+   * "unknown" so a broken row degrades to the predicate scan rather than
+   * rendering an empty list.
+   */
+  getWindowMembership(key: string): Promise<RecordVersionArray | null>;
+  /** Persist the durable membership row. Best-effort: callers must not fail a
+   *  sync round because the mirror write failed. */
+  writeWindowMembership(key: string, ids: RecordVersionArray): Promise<void>;
+  /**
+   * Record ids with a mutation still in the outbox, split by direction.
+   *
+   * Both halves feed {@link materializeRecords}: `writes` keeps optimistic
+   * creates/updates visible before the server has acknowledged them, and
+   * `deletes` suppresses rows the server still lists because our DELETE hasn't
+   * been processed yet. Reading `_00_pending_mutations` (rather than tracking
+   * ids in memory) is what makes both survive a reload.
+   *
+   * On failure returns empty sets: membership alone then decides, which can
+   * briefly hide an optimistic write but never resurrects a deleted row.
+   */
+  getPendingRecordIds(): Promise<{
+    writes: Set<string>;
+    deletes: Set<string>;
+  }>;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean;
   /**
@@ -679,6 +891,18 @@ declare class DataModule<S extends SchemaStructure> {
   private createAndRegisterQuery;
   private createNewQuery;
   private calculateHash;
+  /**
+   * Session-independent counterpart of {@link calculateHash}: the key for a
+   * query's durable `_00_window` membership row.
+   *
+   * Deliberately the SAME inputs minus the `session::id()` salt, so the two keys
+   * can never drift apart. The salt is right for `_00_query` (two tabs must not
+   * fight over one row) and wrong for membership, which has to be recognizable
+   * after a reload — a reload mints a new session id, and offline the salt is
+   * `''`, so a salted key can never match what the previous session wrote.
+   */
+  private calculateMembershipKey;
+  private sha256;
   private startTTLHeartbeat;
   private replaceRecordInQueries;
 }
@@ -808,6 +1032,13 @@ interface Sp00kySyncOptions {
    * up-queue for the session. Defaults to 30000; `0` disables the timeout.
    */
   pushTimeoutMs?: number;
+  /**
+   * Transport supervisor. Sync reads its state to report `connection` in
+   * {@link SyncHealth} so a UI can show "reconnecting…" the instant the socket
+   * drops, without waiting for the degrade threshold. Optional: omitted in
+   * tests, where `connection` then reports `connected`.
+   */
+  connectionSupervisor?: ConnectionSupervisor;
 }
 /**
  * The main synchronization engine for Sp00ky.
@@ -831,7 +1062,12 @@ declare class Sp00kySync<S extends SchemaStructure> {
    *  `SYNC_QUERY_UPDATED` and `SYNC_MUTATION_ROLLED_BACK`. */
   get engineEvents(): SyncEventSystem;
   private scheduler;
-  private wasDisconnected;
+  /**
+   * Set by any event that means the socket we registered on is gone, so the
+   * next `connected` knows it must re-subscribe rather than treat itself as the
+   * initial connect. See {@link subscribeToReconnect}.
+   */
+  private needsResubscribe;
   events: SyncEventSystem;
   private currentUserId;
   private tabRole;
@@ -866,6 +1102,17 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private selfHealAttempts;
   private static readonly SELF_HEAL_BASE_MS;
   private static readonly SELF_HEAL_MAX_MS;
+  /**
+   * Transport supervisor, when one was supplied. Sync only reads state from it;
+   * it never drives reconnects itself.
+   */
+  private readonly connectionSupervisor?;
+  /**
+   * Mirror of the supervisor's state. Defaults to `connected` so a client
+   * constructed without a supervisor (tests, embedders) reports the same health
+   * shape it always has rather than a permanent false "disconnected".
+   */
+  private connectionState;
   /** Current sync-health snapshot. */
   get syncHealth(): SyncHealth;
   /**
@@ -875,6 +1122,17 @@ declare class Sp00kySync<S extends SchemaStructure> {
    */
   subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
   private emitSyncHealth;
+  /**
+   * Mirror the supervisor's transport state into {@link SyncHealth} and emit on
+   * every change, so a UI can react to a dropped socket immediately instead of
+   * waiting for `degradeAfterFailures` failed rounds. `status` is untouched:
+   * a brief reconnect is not a degradation.
+   *
+   * No explicit unsubscribe: the supervisor is owned by the same client and
+   * drops all subscribers in its own `dispose()`, which `Sp00kyClient.close()`
+   * calls first.
+   */
+  private subscribeToConnectionState;
   /**
    * Fed by the scheduler once per drained sync round. Individual failures are
    * absorbed by the queue's retry; only a run of `degradeAfterFailures`
@@ -999,6 +1257,16 @@ declare class Sp00kySync<S extends SchemaStructure> {
   listRefTable(): string;
   private killRefLiveQuery;
   private restartRefLiveQuery;
+  /**
+   * Drop local LIVE bookkeeping without issuing a `KILL`.
+   *
+   * Called when the socket dies. The server-side subscription is scoped to that
+   * WebSocket session and died with it, so there is nothing left to kill — and
+   * by the time the reconnect handler runs, the client reports `connected`
+   * again, which would otherwise send a `KILL` for a stale uuid on the *new*
+   * session and hold up the restart queued behind it.
+   */
+  private invalidateRefLiveQuery;
   private subscribeToReconnect;
   private startRefLiveQueries;
   private handleRemoteListRefChange;
@@ -1247,9 +1515,30 @@ declare class CrdtManager {
   private fields;
   private liveByTable;
   private pendingLive;
+  private staleTables;
+  private connectionGeneration;
+  private connectionUnsubscribes;
   private logger;
   private sessionId;
   constructor(schema: SchemaStructure, local: LocalStore, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /**
+   * Re-establish table LIVEs after a socket drop.
+   *
+   * A LIVE subscription lives and dies with its WebSocket session, and
+   * `ensureTableSubscription` is memoized on `liveByTable` — so without this,
+   * the first reconnect leaves CRDT realtime permanently dead: the map still
+   * holds a uuid for a subscription the server has forgotten, so every later
+   * `open()` short-circuits and no LIVE is ever re-issued.
+   *
+   * Both drop events matter: the SDK publishes `reconnecting` (not
+   * `disconnected`) when it intends to recover on its own, and `disconnected`
+   * only once it has given up.
+   */
+  private subscribeToReconnect;
+  /** Stop observing transport events. Separate from {@link closeAll}, which also
+   *  runs on a bucket switch where the manager keeps being used. */
+  dispose(): void;
+  private hasOpenFieldFor;
   /** 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()`
@@ -1441,6 +1730,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private config;
   private local;
   private remote;
+  private connectionSupervisor;
   private persistenceClient;
   private migrator;
   private cache;
@@ -1650,4 +1940,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, 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, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };