@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/src/services/database/connection-supervisor.ts

@@ -0,0 +1,415 @@
+import type { ConnectionState, ReconnectConfig } from '../../types';
+import { withTimeout } from '../../utils/index';
+import type { Logger } from '../logger/index';
+import type { RemoteDatabaseService } from './remote';
+
+/**
+ * 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.
+ */
+export class ConnectionSupervisor {
+  private readonly logger: Logger;
+  private readonly config: Required<ReconnectConfig>;
+
+  private state: ConnectionState = 'disconnected';
+  private subscribers = new Set<(state: ConnectionState) => void>();
+
+  private started = false;
+  private disposed = false;
+
+  private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatInFlight = false;
+  /** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+  private heartbeatFailures = 0;
+
+  private reviveTimer: ReturnType<typeof setTimeout> | null = null;
+  private reviveAttempts = 0;
+  /** Timestamp of the last wake-triggered probe, for rate limiting. */
+  private lastWakeProbeAt = 0;
+  private reviving = false;
+  /**
+   * 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 = false;
+
+  private teardown: Array<() => void> = [];
+
+  private static readonly REVIVE_BASE_MS = 1_000;
+  /**
+   * How many consecutive heartbeat failures it takes to tear the socket down.
+   *
+   * The probe rides the same serialized queue as every other RPC (deliberately
+   * — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+   * a merely BUSY one. A single slow window (a large sync burst, one heavy
+   * app query) used to be enough to force-close a perfectly healthy socket,
+   * and the resulting reconnect re-registered every active query about a
+   * second later. That self-inflicted teardown manufactured the very reconnect
+   * storms this class exists to survive. A genuinely dead socket still fails
+   * every probe, so it is torn down one interval later than before.
+   */
+  private static readonly FAILURES_BEFORE_TEARDOWN = 2;
+  /** Retry delay after an inconclusive (first) heartbeat failure. */
+  private static readonly HEARTBEAT_RETRY_MS = 5_000;
+  /** Floor between probes triggered by wake events (tab focus, pageshow). */
+  private static readonly WAKE_PROBE_MIN_INTERVAL_MS = 10_000;
+
+  constructor(
+    private readonly remote: RemoteDatabaseService,
+    logger: Logger,
+    config?: Required<ReconnectConfig>
+  ) {
+    this.logger = logger.child({ service: 'ConnectionSupervisor' });
+    this.config = config ?? remote.getReconnectConfig();
+  }
+
+  /** Latest observed transport state. */
+  get connection(): ConnectionState {
+    return this.state;
+  }
+
+  /**
+   * Observe transport state. Fires immediately with the current value and again
+   * on every change. Returns an unsubscribe.
+   */
+  subscribe(cb: (state: ConnectionState) => void): () => void {
+    cb(this.state);
+    this.subscribers.add(cb);
+    return () => {
+      this.subscribers.delete(cb);
+    };
+  }
+
+  /**
+   * Begin supervising. Call once, after the initial {@link
+   * RemoteDatabaseService.connect}. Idempotent.
+   */
+  start(): void {
+    if (this.started || this.disposed) return;
+    this.started = true;
+
+    this.setState(this.remote.getStatus());
+
+    this.teardown.push(
+      this.remote.subscribeConnection('connecting', () => this.setState('connecting')),
+      this.remote.subscribeConnection('reconnecting', () => {
+        this.setState('reconnecting');
+        // The SDK owns the retry from here; ours would fight it for the socket.
+        this.stopHeartbeat();
+      }),
+      this.remote.subscribeConnection('connected', () => {
+        this.reviveAttempts = 0;
+        this.clearReviveTimer();
+        this.setState('connected');
+        this.startHeartbeat();
+      }),
+      this.remote.subscribeConnection('disconnected', () => {
+        this.setState('disconnected');
+        this.stopHeartbeat();
+        // The SDK has stopped trying (exhausted, terminated, or handshake
+        // failure). From here on, reconnecting is entirely our job.
+        this.scheduleRevive();
+      }),
+      this.remote.subscribeConnection('error', (err) => {
+        this.logger.debug(
+          { err, Category: 'sp00ky-client::ConnectionSupervisor::error' },
+          'Transport error'
+        );
+      })
+    );
+
+    this.installWakeTriggers();
+
+    if (this.state === 'connected') this.startHeartbeat();
+    else this.scheduleRevive();
+  }
+
+  /** Stop all timers and listeners. Safe to call more than once. */
+  dispose(): void {
+    this.disposed = true;
+    this.started = false;
+    this.stopHeartbeat();
+    this.clearReviveTimer();
+    for (const off of this.teardown) {
+      try {
+        off();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.teardown = [];
+    this.subscribers.clear();
+  }
+
+  private setState(next: ConnectionState): void {
+    if (this.state === next) return;
+    this.state = next;
+    this.logger.info(
+      { state: next, Category: 'sp00ky-client::ConnectionSupervisor::state' },
+      'Connection state changed'
+    );
+    for (const cb of this.subscribers) {
+      try {
+        cb(next);
+      } catch (err) {
+        this.logger.debug(
+          { err, Category: 'sp00ky-client::ConnectionSupervisor::state' },
+          'Connection subscriber threw'
+        );
+      }
+    }
+  }
+
+  // ---- Revive loop -------------------------------------------------------
+
+  private clearReviveTimer(): void {
+    if (this.reviveTimer !== null) {
+      clearTimeout(this.reviveTimer);
+      this.reviveTimer = null;
+    }
+  }
+
+  /**
+   * Queue the next `connect()` attempt on exponential backoff, capped at
+   * `superviseRetryDelayMaxMs`. Never gives up — the page is expected to
+   * outlive any outage.
+   */
+  private scheduleRevive(): void {
+    if (this.disposed || this.suspended) return;
+    if (this.reviveTimer !== null || this.reviving) return;
+    const delay = Math.min(
+      this.config.superviseRetryDelayMaxMs,
+      ConnectionSupervisor.REVIVE_BASE_MS * 2 ** this.reviveAttempts
+    );
+    this.reviveTimer = setTimeout(() => {
+      this.reviveTimer = null;
+      void this.revive();
+    }, delay);
+  }
+
+  private async revive(): Promise<void> {
+    if (this.disposed || this.suspended || this.reviving) return;
+    // The SDK may have recovered on its own between scheduling and firing.
+    if (this.remote.getStatus() === 'connected') {
+      this.reviveAttempts = 0;
+      return;
+    }
+    this.reviving = true;
+    this.reviveAttempts++;
+    this.setState('reconnecting');
+    this.logger.info(
+      {
+        attempt: this.reviveAttempts,
+        Category: 'sp00ky-client::ConnectionSupervisor::revive',
+      },
+      'Re-opening the remote connection'
+    );
+    try {
+      await this.remote.connect();
+      // Don't reset `reviveAttempts` or start the heartbeat here — the
+      // `connected` handler does both, and it's the only signal that the
+      // handshake (version/use/authenticate) actually completed.
+    } catch (err) {
+      this.logger.warn(
+        {
+          err,
+          attempt: this.reviveAttempts,
+          Category: 'sp00ky-client::ConnectionSupervisor::revive',
+        },
+        'Reconnect attempt failed; will retry'
+      );
+    } finally {
+      this.reviving = false;
+    }
+    if (this.remote.getStatus() !== 'connected') this.scheduleRevive();
+  }
+
+  // ---- Heartbeat watchdog ------------------------------------------------
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer !== null) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    if (this.disposed || this.suspended) return;
+    if (!(this.config.heartbeatIntervalMs > 0)) return;
+    this.heartbeatTimer = setTimeout(
+      () => void this.beat(),
+      this.config.heartbeatIntervalMs
+    );
+  }
+
+  /**
+   * 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 async beat(): Promise<void> {
+    this.heartbeatTimer = null;
+    if (this.disposed || this.suspended) return;
+    if (this.remote.getStatus() !== 'connected') return;
+    if (this.heartbeatInFlight) {
+      this.startHeartbeat();
+      return;
+    }
+    this.heartbeatInFlight = true;
+    try {
+      await withTimeout(
+        this.remote.query('RETURN true'),
+        this.config.heartbeatTimeoutMs,
+        `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`
+      );
+      this.heartbeatFailures = 0;
+      this.startHeartbeat();
+    } catch (err) {
+      this.heartbeatFailures++;
+      if (this.heartbeatFailures < ConnectionSupervisor.FAILURES_BEFORE_TEARDOWN) {
+        // Inconclusive: the probe shares a queue with ordinary traffic, so this
+        // may just be a busy window rather than a dead socket. Re-probe soon
+        // instead of tearing down a connection that is probably fine.
+        this.logger.debug(
+          {
+            err,
+            failures: this.heartbeatFailures,
+            Category: 'sp00ky-client::ConnectionSupervisor::heartbeat',
+          },
+          'Heartbeat failed; re-probing before tearing the socket down'
+        );
+        this.stopHeartbeat();
+        if (!this.disposed && !this.suspended) {
+          this.heartbeatTimer = setTimeout(
+            () => void this.beat(),
+            Math.min(ConnectionSupervisor.HEARTBEAT_RETRY_MS, this.config.heartbeatIntervalMs)
+          );
+        }
+        return;
+      }
+      this.logger.warn(
+        {
+          err,
+          failures: this.heartbeatFailures,
+          Category: 'sp00ky-client::ConnectionSupervisor::heartbeat',
+        },
+        'Heartbeat failed repeatedly; tearing the socket down to force a reconnect'
+      );
+      this.heartbeatFailures = 0;
+      // Force the `close` the transport never delivered. The resulting
+      // `disconnected` event drives the revive loop.
+      await this.remote.forceClose();
+      if (this.remote.getStatus() !== 'connected') this.scheduleRevive();
+    } finally {
+      this.heartbeatInFlight = false;
+    }
+  }
+
+  // ---- Wake triggers -----------------------------------------------------
+
+  /**
+   * 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(): void {
+    if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+      const onOnline = () => {
+        this.suspended = false;
+        this.wake('online');
+      };
+      const onOffline = () => {
+        this.logger.info(
+          { Category: 'sp00ky-client::ConnectionSupervisor::offline' },
+          'Browser reports offline; parking reconnects until online'
+        );
+        this.suspended = true;
+        this.stopHeartbeat();
+        this.clearReviveTimer();
+        this.setState('disconnected');
+      };
+      window.addEventListener('online', onOnline);
+      window.addEventListener('offline', onOffline);
+      this.teardown.push(
+        () => window.removeEventListener('online', onOnline),
+        () => window.removeEventListener('offline', onOffline)
+      );
+      // A tab restored from bfcache keeps its dead socket; `pageshow` is the
+      // only event that fires in that path.
+      const onPageShow = () => this.wake('pageshow');
+      window.addEventListener('pageshow', onPageShow);
+      this.teardown.push(() => window.removeEventListener('pageshow', onPageShow));
+    }
+
+    if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+      const onVisibility = () => {
+        if (document.visibilityState !== 'visible') return;
+        this.wake('visibilitychange');
+      };
+      document.addEventListener('visibilitychange', onVisibility);
+      this.teardown.push(() => document.removeEventListener('visibilitychange', onVisibility));
+    }
+  }
+
+  /**
+   * 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(reason: string): void {
+    if (this.disposed || this.suspended) return;
+    // `visibilitychange` fires on every alt-tab, every window minimise and every
+    // focus change. Probing a connected socket each time meant an ordinary
+    // afternoon of tab-switching issued a steady stream of extra RPCs, each of
+    // which could trip the heartbeat teardown above. A healthy socket does not
+    // become unhealthy because the user looked away for four seconds, so probes
+    // from wake triggers are rate-limited; a genuinely dead socket is still
+    // caught by the regular heartbeat.
+    const now = Date.now();
+    if (
+      this.remote.getStatus() === 'connected' &&
+      now - this.lastWakeProbeAt < ConnectionSupervisor.WAKE_PROBE_MIN_INTERVAL_MS
+    ) {
+      return;
+    }
+    this.lastWakeProbeAt = now;
+    this.logger.debug(
+      { reason, state: this.state, Category: 'sp00ky-client::ConnectionSupervisor::wake' },
+      'Wake trigger; probing the connection'
+    );
+    this.reviveAttempts = 0;
+    if (this.remote.getStatus() === 'connected') {
+      this.stopHeartbeat();
+      void this.beat();
+      return;
+    }
+    // 'reconnecting' means the SDK's own loop owns the socket; don't race it.
+    if (this.remote.getStatus() === 'disconnected') {
+      this.clearReviveTimer();
+      void this.revive();
+    }
+  }
+}

package/src/services/database/database.query-timeout.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { AbstractDatabaseService } from './database';
+import { DatabaseEventTypes, createDatabaseEventSystem } from './events/index';
+import { classifySyncError } from '../../utils/index';
+
+// Every remote query is serialized through one promise chain (to keep the WASM
+// engine's transactions safe), so a call that never settles doesn't just fail —
+// it blocks every later query behind it, including the sync poll's own health
+// probe. That's how a half-open socket wedges the client while health still
+// reports `healthy`: nothing ever throws, so nothing ever degrades.
+
+const silentLogger: any = (() => {
+  const l: any = {
+    child: () => l,
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    trace: () => {},
+  };
+  return l;
+})();
+
+class TestService extends AbstractDatabaseService {
+  protected eventType = DatabaseEventTypes.RemoteQuery;
+  constructor(client: any, timeoutMs: number) {
+    super(client, silentLogger, createDatabaseEventSystem());
+    this.queryTimeoutMs = timeoutMs;
+  }
+  async connect(): Promise<void> {}
+}
+
+describe('AbstractDatabaseService query timeout', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('rejects a never-settling query and classifies it as a network failure', async () => {
+    const client = { query: vi.fn().mockImplementation(() => new Promise(() => {})) };
+    const svc = new TestService(client, 1_000);
+
+    const pending = svc.query('SELECT * FROM thread');
+    const assertion = expect(pending).rejects.toThrow(/timed out/);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await assertion;
+
+    // "timed out" in the message is load-bearing: it routes the failure to
+    // `network`, which makes the sync queues retry instead of rolling the
+    // mutation back as a permanent application error.
+    const err = await pending.catch((e) => e);
+    expect(classifySyncError(err)).toBe('network');
+  });
+
+  it('unblocks the serialized queue so later queries still run', async () => {
+    let calls = 0;
+    const client = {
+      query: vi.fn().mockImplementation(() => {
+        calls++;
+        // First call hangs forever; the second would never be reached at all if
+        // the timeout didn't settle the chain link.
+        if (calls === 1) return new Promise(() => {});
+        return Promise.resolve([['ok']]);
+      }),
+    };
+    const svc = new TestService(client, 1_000);
+
+    const stuck = svc.query('SELECT 1');
+    const next = svc.query('SELECT 2');
+    const stuckAssertion = expect(stuck).rejects.toThrow(/timed out/);
+
+    await vi.advanceTimersByTimeAsync(1_000);
+    await stuckAssertion;
+    await expect(next).resolves.toEqual([['ok']]);
+  });
+
+  it('leaves queries unbounded when the timeout is disabled', async () => {
+    const client = { query: vi.fn().mockResolvedValue([['ok']]) };
+    const svc = new TestService(client, 0);
+
+    await expect(svc.query('SELECT 1')).resolves.toEqual([['ok']]);
+    // No timer was armed, so a slow-but-alive query is never cut off.
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/services/database/database.ts

@@ -1,16 +1,31 @@
-import { Surreal, SurrealTransaction } from 'surrealdb';
-import { createLogger, Logger } from '../logger/index';
-import {
+import type { Surreal, SurrealTransaction } from 'surrealdb';
+import type { Logger } from '../logger/index';
+import type {
   DatabaseEventSystem,
-  DatabaseEventTypes,
-  DatabaseQueryEventPayload,
-} from './events/index';
-import { SealedQuery } from '../../utils/surql';
+  DatabaseEventTypes} from './events/index';
+import type { SealedQuery } from '../../utils/surql';
+import { withTimeout } from '../../utils/index';
 
 export abstract class AbstractDatabaseService {
   protected client: Surreal;
   protected logger: Logger;
   protected events: DatabaseEventSystem;
+  /**
+   * Per-query deadline in ms; `0` disables. The remote service sets it from
+   * `queryTimeoutMs` (see `RemoteDatabaseService`), the local one from
+   * `localOpTimeoutMs` (see `LocalDatabaseService`): a local query can be
+   * legitimately slow, but it must never be endless - every query waits on the
+   * previous link of {@link query}'s chain, and one that never settled wedged
+   * every later local op behind it.
+   */
+  protected queryTimeoutMs = 0;
+
+  /** The error a deadline expiry rejects with; the local service substitutes
+   *  its typed `LocalOpTimeoutError`. "timed out" in the message is
+   *  load-bearing either way: `classifySyncError` keys off it. */
+  protected timeoutError(_query: string): Error {
+    return new Error(`Remote query timed out after ${this.queryTimeoutMs}ms`);
+  }
   protected abstract eventType:
     | typeof DatabaseEventTypes.LocalQuery
     | typeof DatabaseEventTypes.RemoteQuery;
@@ -39,21 +54,34 @@ export abstract class AbstractDatabaseService {
 
   /**
    * 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.
    */
   async query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T> {
     return new Promise((resolve, reject) => {
       this.queryQueue = this.queryQueue
+        // oxlint-disable-next-line promise/always-return
         .then(async () => {
           const startTime = performance.now();
           try {
             this.logger.debug(
-              { query, vars, Category: 'spooky-client::Database::query' },
+              { query, vars, Category: 'sp00ky-client::Database::query' },
               'Executing query'
             );
             const pending = this.client.query(query, vars);
             // In SurrealDB 2.0, .query() collects results by default.
             // We cast to T directly as proper typing depends on the caller knowing the return structure.
-            const result = (await pending) as unknown as T;
+            // "timed out" in the message is load-bearing: `classifySyncError`
+            // keys off it to classify this as `network` so the sync queues
+            // retry rather than rolling the mutation back.
+            const result = (await withTimeout(
+              pending as unknown as Promise<T>,
+              this.queryTimeoutMs,
+              () => this.timeoutError(query)
+            )) as T;
             const duration = performance.now() - startTime;
 
             // Emit query event
@@ -67,7 +95,7 @@ export abstract class AbstractDatabaseService {
 
             resolve(result);
             this.logger.trace(
-              { query, result, Category: 'spooky-client::Database::query' },
+              { query, result, Category: 'sp00ky-client::Database::query' },
               'Query executed successfully'
             );
           } catch (err) {
@@ -84,9 +112,10 @@ export abstract class AbstractDatabaseService {
             });
 
             this.logger.error(
-              { query, vars, err, Category: 'spooky-client::Database::query' },
+              { query, vars, err, Category: 'sp00ky-client::Database::query' },
               'Query execution failed'
             );
+            // oxlint-disable-next-line no-multiple-resolved -- resolve/reject are in try/catch, mutually exclusive
             reject(err);
           }
         })
@@ -102,7 +131,7 @@ export abstract class AbstractDatabaseService {
   }
 
   async close(): Promise<void> {
-    this.logger.info({ Category: 'spooky-client::Database::close' }, 'Closing database connection');
+    this.logger.info({ Category: 'sp00ky-client::Database::close' }, 'Closing database connection');
     await this.client.close();
   }
 }

package/src/services/database/engine-factory.ts

@@ -0,0 +1,33 @@
+import type { Sp00kyConfig } from '../../types';
+import type { Logger } from '../logger/index';
+import type { LocalEngineChoice, LocalStore } from './cache-engine';
+import { SurrealCacheEngine } from './surreal-cache-engine';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+
+/**
+ * Build the local cache engine for the given `localEngine` config choice.
+ *
+ * - `'surrealdb'` / unset → {@link SurrealCacheEngine} (subclass of
+ *   `LocalDatabaseService`; the historical behavior, verbatim).
+ * - `'sqlite'` → {@link SqliteCacheEngine} (SQLite-WASM Worker + OPFS). Backs
+ *   `this.local` through the SurrealQL-vocabulary shim + verb surface.
+ * - a custom object → used as-is (must satisfy {@link LocalStore}).
+ */
+export function createLocalEngine(
+  choice: LocalEngineChoice | undefined,
+  config: Sp00kyConfig<any>['database'],
+  logger: Logger,
+  opts: { shared?: boolean } = {}
+): LocalStore {
+  if (choice === undefined || choice === 'surrealdb') {
+    return new SurrealCacheEngine(config, logger);
+  }
+  if (choice === 'sqlite') {
+    // Mirror the SurrealDB engine's `store` semantics: 'memory' → in-memory
+    // SQLite (transient), 'indexeddb' → OPFS-backed (durable).
+    const useOpfs = (config.store ?? 'memory') !== 'memory';
+    return new SqliteCacheEngine(config, logger, { useOpfs, shared: opts.shared });
+  }
+  // Custom engine instance — trust it to satisfy LocalStore.
+  return choice as unknown as LocalStore;
+}

package/src/services/database/errors.ts

@@ -0,0 +1,34 @@
+/**
+ * A local-store operation that did not answer within its deadline.
+ *
+ * The local write path (`db.create` / `db.update` / `db.delete`, every local
+ * query behind them) used to have no deadline anywhere: the SQLite worker
+ * transport parks a call until the worker replies, the surrealdb engine's
+ * query chain waits on the previous link, and `withRetry` retries without a
+ * clock. One op that never settled (a worker starved behind a long select, a
+ * lock verification awaiting `navigator.locks.query()` forever) left the
+ * caller's promise pending for the tab's lifetime - a chat composer that never
+ * re-enabled, a call that never got past "Connecting".
+ *
+ * The message says "timed out" on purpose: `classifySyncError` keys off it and
+ * treats the failure as transient (re-queue), never as an application error
+ * that rolls the mutation back. `retryable: false` keeps `withRetry` from
+ * spinning on it: the op is still running in the engine, retrying queues a
+ * second copy behind it.
+ */
+export class LocalOpTimeoutError extends Error {
+  override readonly name = 'LocalOpTimeoutError';
+  readonly retryable = false;
+  readonly op: string;
+  readonly timeoutMs: number;
+
+  constructor(op: string, timeoutMs: number) {
+    super(`Local database operation timed out after ${timeoutMs}ms (${op})`);
+    this.op = op;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** Default deadline for one local-store operation. Generous: a cold 4k-row
+ *  select on a throttled tab is seconds, not tens of seconds. */
+export const DEFAULT_LOCAL_OP_TIMEOUT_MS = 30_000;

package/src/services/database/events/index.ts

@@ -1,4 +1,5 @@
-import { createEventSystem, EventDefinition, EventSystem } from '../../../events/index';
+import type { EventDefinition, EventSystem } from '../../../events/index';
+import { createEventSystem } from '../../../events/index';
 
 export const DatabaseEventTypes = {
   LocalQuery: 'DATABASE_LOCAL_QUERY',