@spooky-sync/core 0.0.1-canary.208 → 0.0.1-canary.209

package/src/modules/devtools/index.ts

@@ -63,6 +63,10 @@ export class DevToolsService implements StreamUpdateReceiver {
   private static readonly NOTIFY_MIN_INTERVAL_MS = 250;
   private notifyTimer: ReturnType<typeof setTimeout> | null = null;
   private lastNotifyAt = 0;
+  /** How many ids a pushed state carries per view; the rest is on demand. */
+  private static readonly STATE_IDS_CAP = 200;
+  /** devtools numeric hash -> the query's `_00_query` id, for on-demand rows. */
+  private hashToQuery = new Map<number, unknown>();
 
   /** Shared-tabs snapshot for the panel, wired by Sp00kyClient whenever the
    *  feature was REQUESTED (so an inactive/degraded tab still reports why). */
@@ -123,6 +127,7 @@ export class DevToolsService implements StreamUpdateReceiver {
         const type = (e.data as { type?: string } | undefined)?.type;
         if (type === 'SP00KY_DEVTOOLS_CONNECT') {
           this.enabled = true;
+          this.refreshLocalTables();
           this.notifyDevTools();
         } else if (type === 'SP00KY_DEVTOOLS_DISCONNECT') {
           this.enabled = false;
@@ -189,6 +194,9 @@ export class DevToolsService implements StreamUpdateReceiver {
         q.config.lastActiveAt instanceof Date
           ? q.config.lastActiveAt.getTime()
           : new Date(q.config.lastActiveAt || Date.now()).getTime();
+      this.hashToQuery.set(queryHash, q.config.id);
+      const localArray = q.config.localArray ?? [];
+      const remoteArray = q.config.remoteArray ?? [];
       result.set(queryHash, {
         queryHash,
         status: 'active',
@@ -205,9 +213,18 @@ export class DevToolsService implements StreamUpdateReceiver {
         query: q.config.surql,
         variables: q.config.params || {},
         dataSize: q.records?.length || 0,
-        data: q.records,
-        localArray: q.config.localArray,
-        remoteArray: q.config.remoteArray,
+        // Counts and (capped) ids only. The rows themselves used to ride along
+        // here: every push then deep-cloned every view's records twice
+        // (serialize + postMessage), on a 4k-row client dataset up to four
+        // times a second, from inside the ingest call stack. The panel pulls
+        // rows on demand through `getQueryRows` instead.
+        localCount: localArray.length,
+        remoteCount: remoteArray.length,
+        localIds: localArray.slice(0, DevToolsService.STATE_IDS_CAP).map(([id]) => id),
+        remoteIds: remoteArray.slice(0, DevToolsService.STATE_IDS_CAP).map(([id]) => id),
+        idsTruncated:
+          localArray.length > DevToolsService.STATE_IDS_CAP ||
+          remoteArray.length > DevToolsService.STATE_IDS_CAP,
         // Membership state, so "why is this list empty" is answerable from
         // the panel: is the server's set known, has a non-empty one been seen
         // this session, how many empty reads were ignored.
@@ -250,18 +267,28 @@ export class DevToolsService implements StreamUpdateReceiver {
 
     this.addEvent('QUERY_UPDATED', {
       queryHash,
-      data: payload.records,
+      recordCount: Array.isArray(payload.records) ? payload.records.length : 0,
     });
     this.notifyDevTools();
   }
 
   public onStreamUpdate(update: StreamUpdate) {
+    // A synthetic re-materialize is not an ingest (DataModule.scheduleRematerialize).
+    if (update.synthetic) return;
     this.logger.debug(
-      { update, Category: 'sp00ky-client::DevToolsService::onStreamUpdate' },
+      { queryHash: update.queryHash, Category: 'sp00ky-client::DevToolsService::onStreamUpdate' },
       'StreamUpdate'
     );
+    // Counts and timings, not the `localArray` itself: that is one [id, version]
+    // pair per row of the view, serialized on every single update.
     this.addEvent('STREAM_UPDATE', {
-      updates: [update],
+      queryHash: update.queryHash,
+      op: update.op,
+      localCount: update.localArray?.length ?? 0,
+      materializationTimeMs: update.materializationTimeMs,
+      storeApplyMs: update.storeApplyMs,
+      circuitStepMs: update.circuitStepMs,
+      transformMs: update.transformMs,
     });
     this.notifyDevTools();
   }
@@ -271,8 +298,10 @@ export class DevToolsService implements StreamUpdateReceiver {
     payloads.forEach((p) => {
       this.addEvent('MUTATION_REQUEST_EXECUTION', {
         mutation: {
-          type: 'create', // simplifying
-          data: 'data' in p ? p.data : undefined,
+          type: p.type ?? 'create',
+          // Field names only; a payload body (a PGN, a document) is not
+          // something to clone on every write.
+          fields: 'data' in p && p.data && typeof p.data === 'object' ? Object.keys(p.data) : [],
           selector: encodeRecordId(p.record_id),
         },
       });
@@ -325,7 +354,7 @@ export class DevToolsService implements StreamUpdateReceiver {
   private refreshLocalTables(): void {
     if (this.localTablesFetching) return;
     const now = Date.now();
-    if (now - this.localTablesAt < 3000) return;
+    if (now - this.localTablesAt < 30_000) return;
     this.localTablesFetching = true;
     void this.databaseService
       .query<any>('INFO FOR DB')
@@ -351,9 +380,12 @@ export class DevToolsService implements StreamUpdateReceiver {
       });
   }
 
-  private getState() {
-    // Keep the full local-table list fresh (throttled, non-blocking).
-    this.refreshLocalTables();
+  private getState(opts: { refreshTables?: boolean } = {}) {
+    // The local-table list (`INFO FOR DB`, a local round trip) is refreshed on
+    // an explicit pull only, never by the push path: pushes follow every sync
+    // event, and a local query per push competed with the app's own writes for
+    // the single local op queue.
+    if (opts.refreshTables) this.refreshLocalTables();
     return this.serializeForDevTools({
       eventsHistory: [...this.eventsHistory],
       activeQueries: Object.fromEntries(this.getActiveQueries()),
@@ -481,16 +513,17 @@ export class DevToolsService implements StreamUpdateReceiver {
     // A trailing push is already queued; it will carry this change too.
     if (this.notifyTimer !== null) return;
 
+    // Always a macrotask, never inline: this is called from inside the ingest
+    // and mutation call stacks (onStreamUpdate / onMutation), i.e. inside the
+    // `await db.create(...)` the app is waiting on. A push that serializes the
+    // state right there charged every write for the panel's refresh.
     const waited = Date.now() - this.lastNotifyAt;
-    if (waited >= DevToolsService.NOTIFY_MIN_INTERVAL_MS) {
-      this.flushNotify();
-      return;
-    }
+    const delay = Math.max(0, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
     this.notifyTimer = setTimeout(() => {
       this.notifyTimer = null;
       // Still gated on `enabled`: the panel may have disconnected while queued.
       if (this.enabled) this.flushNotify();
-    }, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
+    }, delay);
   }
 
   private flushNotify() {
@@ -569,7 +602,21 @@ export class DevToolsService implements StreamUpdateReceiver {
     if (typeof window !== 'undefined') {
       (window as any).__00__ = {
         version: this.version,
-        getState: () => this.getState(),
+        getState: () => this.getState({ refreshTables: true }),
+        // The rows of ONE view, on demand. The pushed state carries counts and
+        // capped ids only (see getActiveQueries); the panel's Data tab and the
+        // MCP fetch the rows here when somebody actually looks at them.
+        getQueryRows: (queryHash: number) => {
+          const id = this.hashToQuery.get(Number(queryHash));
+          const q = id !== undefined ? this.dataManager?.getQueryById(id as any) : undefined;
+          if (!q) return null;
+          return this.serializeForDevTools({
+            queryHash: Number(queryHash),
+            data: q.records,
+            localArray: q.config.localArray,
+            remoteArray: q.config.remoteArray,
+          });
+        },
         // ---- Feature flags (Access tab) --------------------------------
         // Remote reads/writes are admin-gated by SurrealDB, not here: a
         // non-admin gets an empty flag list, and the `fn::feature::*` calls

package/src/modules/devtools/notify-throttle.test.ts

@@ -74,9 +74,13 @@ afterEach(() => {
 });
 
 describe('DevToolsService state-push coalescing', () => {
-  it('pushes once immediately on connect', () => {
+  it('pushes once on connect, on the next macrotask', () => {
     vi.useFakeTimers();
     const { statePushes } = harness();
+    // Never inline: a push serializes the state, and the request can come
+    // from inside an ingest or a mutation the app is awaiting.
+    expect(statePushes().length).toBe(0);
+    vi.advanceTimersByTime(0);
     expect(statePushes().length).toBe(1);
   });
 
@@ -117,6 +121,7 @@ describe('DevToolsService state-push coalescing', () => {
     // straight away, so the panel never waits on a quiet app.
     vi.advanceTimersByTime(1000);
     (service as any).logEvent('C', {});
+    vi.advanceTimersByTime(0);
     expect(statePushes().length).toBe(before + 3);
   });
 

package/src/modules/devtools/state-shape.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DevToolsService } from './index';
+
+/**
+ * The pushed state used to carry every view's full record set (and both
+ * membership arrays), deep-cloned once by the serializer and again by
+ * postMessage, on every sync event, from inside the ingest call stack. On a
+ * client holding a few thousand rows that is what the main thread was doing
+ * instead of finishing the write the app was awaiting. Pushes now carry counts
+ * and capped ids; rows are pulled per view on demand.
+ */
+function harness(recordCount = 500) {
+  const posted: any[] = [];
+  const listeners: ((e: any) => void)[] = [];
+  const fakeWindow: any = {
+    postMessage: (msg: any) => posted.push(msg),
+    addEventListener: (_type: string, cb: (e: any) => void) => listeners.push(cb),
+    dispatchEvent: () => true,
+  };
+  fakeWindow.self = fakeWindow;
+  vi.stubGlobal('window', fakeWindow);
+  vi.stubGlobal('CustomEvent', class {
+    type: string;
+    constructor(type: string) {
+      this.type = type;
+    }
+  });
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  const infoQueries: string[] = [];
+  const local: any = {
+    query: async (sql: string) => {
+      infoQueries.push(sql);
+      return [];
+    },
+    getConfig: () => ({ store: 'memory' }),
+    currentBucketId: 'anon',
+    storageHealth: { status: 'memory', fallback: false },
+  };
+  const remote: any = { query: async () => [] };
+  const auth: any = { isAuthenticated: false, currentUser: undefined, eventSystem: { subscribe: noop } };
+  const records = Array.from({ length: recordCount }, (_, i) => ({ id: `game:${i}`, pgn: 'x' }));
+  const localArray = records.map((r) => [r.id, 1] as [string, number]);
+  const id = new RecordId('_00_query', 'q1');
+  const query = {
+    config: { id, params: {}, localArray, remoteArray: localArray, surql: 'SELECT * FROM game' },
+    status: 'idle',
+    records,
+    updateCount: 1,
+  };
+  const dataManager: any = {
+    getActiveQueries: () => [query],
+    getQueryById: (rid: RecordId<string>) => (String(rid) === String(id) ? query : undefined),
+    phaseTimings: () => ({}),
+  };
+  const service = new DevToolsService(local, remote, logger, { tables: [] } as any, auth, dataManager);
+  for (const cb of listeners) cb({ source: fakeWindow, data: { type: 'SP00KY_DEVTOOLS_CONNECT' } });
+  const statePushes = () => posted.filter((m) => m.type === 'SP00KY_STATE_CHANGED');
+  return { service, statePushes, posted, fakeWindow, infoQueries };
+}
+
+describe('DevTools pushed state shape', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('carries counts and capped ids, never the rows', async () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness(500);
+    service.onQueryUpdated({ queryId: 'x', records: [] });
+    await vi.advanceTimersByTimeAsync(300);
+    const push = statePushes().at(-1);
+    expect(push).toBeDefined();
+    const q: any = Object.values(push.state.activeQueries)[0];
+    expect(q.data).toBeUndefined();
+    expect(q.localArray).toBeUndefined();
+    expect(q.remoteArray).toBeUndefined();
+    expect(q.dataSize).toBe(500);
+    expect(q.localCount).toBe(500);
+    expect(q.remoteCount).toBe(500);
+    expect(q.localIds).toHaveLength(200);
+    expect(q.idsTruncated).toBe(true);
+  });
+
+  it('never pushes synchronously inside the call that requested it', async () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness(5);
+    // Connect already queued one push; drain it so the next request is "idle".
+    await vi.advanceTimersByTimeAsync(300);
+    const before = statePushes().length;
+    service.onStreamUpdate({ queryHash: 'q1', localArray: [], op: 'CREATE' });
+    expect(statePushes().length).toBe(before);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(statePushes().length).toBe(before + 1);
+  });
+
+  it('serves the rows of one view on demand', () => {
+    const { service, fakeWindow } = harness(3);
+    void service;
+    const state = fakeWindow.__00__.getState();
+    const hash = Number(Object.keys(state.activeQueries)[0]);
+    const rows = fakeWindow.__00__.getQueryRows(hash);
+    expect(rows.data).toHaveLength(3);
+    expect(rows.localArray).toHaveLength(3);
+    expect(fakeWindow.__00__.getQueryRows(12345)).toBeNull();
+  });
+
+  it('records a stream update as counts, not the membership array', async () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness(2);
+    service.onStreamUpdate({ queryHash: 'q1', localArray: [['a', 1], ['b', 1]], op: 'UPDATE' });
+    await vi.advanceTimersByTimeAsync(300);
+    const push = statePushes().at(-1);
+    const ev = push.state.eventsHistory.find((e: any) => e.eventType === 'STREAM_UPDATE');
+    expect(ev.payload.localCount).toBe(2);
+    expect(ev.payload.updates).toBeUndefined();
+    expect(ev.payload.localArray).toBeUndefined();
+  });
+
+  it('ignores a synthetic re-materialize', async () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness(1);
+    await vi.advanceTimersByTimeAsync(300);
+    const before = statePushes().length;
+    service.onStreamUpdate({ queryHash: 'q1', localArray: [], op: 'UPDATE', synthetic: true });
+    await vi.advanceTimersByTimeAsync(300);
+    expect(statePushes().length).toBe(before);
+  });
+
+  it('refreshes the table list on an explicit pull, not on a push', async () => {
+    vi.useFakeTimers();
+    const { service, fakeWindow, infoQueries } = harness(1);
+    const connectRefreshes = infoQueries.filter((q) => q.includes('INFO FOR DB')).length;
+    for (let i = 0; i < 10; i++) {
+      service.onStreamUpdate({ queryHash: 'q1', localArray: [], op: 'UPDATE' });
+      await vi.advanceTimersByTimeAsync(300);
+    }
+    expect(infoQueries.filter((q) => q.includes('INFO FOR DB')).length).toBe(connectRefreshes);
+    vi.setSystemTime(Date.now() + 60_000);
+    fakeWindow.__00__.getState();
+    expect(infoQueries.filter((q) => q.includes('INFO FOR DB')).length).toBe(connectRefreshes + 1);
+  });
+});

package/src/modules/sync/sync.live-removal.test.ts

@@ -44,6 +44,7 @@ function makeSync(opts: { membershipKnown?: boolean } = {}) {
   });
   const notifyQuerySynced = vi.fn().mockResolvedValue(undefined);
   const dataModule: any = {
+    scheduleRematerialize: vi.fn(),
     getQueryById: vi.fn().mockReturnValue(queryState),
     getQueryByHash: vi.fn().mockReturnValue(queryState),
     updateQueryRemoteArray,

package/src/modules/sync/sync.ts

@@ -1017,6 +1017,11 @@ export class Sp00kySync<S extends SchemaStructure> {
         'syncQuery failed during poll'
       );
     }
+    // Membership moved but a row may have needed no fetch (this client wrote
+    // it, so the engine already holds it at the published version): nothing
+    // then re-materializes the query. Ask for one; it is a no-op behind a
+    // stream update that a fetch above already queued.
+    if (changed) this.dataModule.scheduleRematerialize(queryHash);
     // Cross-session fallback for `.related()` child rows: the LIVE-permission
     // gap can drop child-edge notifications, so converge their bodies on the
     // poll too (idempotent — no-op when nothing changed).
@@ -1351,6 +1356,11 @@ export class Sp00kySync<S extends SchemaStructure> {
     // path already does for its own removals (`refetchListRefForQuery`).
     if (diff.removed.length > 0 && diff.added.length === 0 && diff.updated.length === 0) {
       await this.dataModule.notifyQuerySynced(hash);
+    } else if (diff.added.length === 0 && diff.updated.length === 0) {
+      // Empty diff: the circuit already holds the row at this version (this
+      // tab wrote it), so no fetch and no stream update - but the membership
+      // recorded above is new, and the subscribers have to hear about it.
+      this.dataModule.scheduleRematerialize(hash);
     }
   }
 

package/src/services/database/database.ts

@@ -11,12 +11,21 @@ export abstract class AbstractDatabaseService {
   protected logger: Logger;
   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.
+   * 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;
@@ -71,7 +80,7 @@ export abstract class AbstractDatabaseService {
             const result = (await withTimeout(
               pending as unknown as Promise<T>,
               this.queryTimeoutMs,
-              `Remote query timed out after ${this.queryTimeoutMs}ms`
+              () => this.timeoutError(query)
             )) as T;
             const duration = performance.now() - startTime;
 

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/local.ts

@@ -1,4 +1,5 @@
 import type { Diagnostic} from 'surrealdb';
+import { DEFAULT_LOCAL_OP_TIMEOUT_MS, LocalOpTimeoutError } from './errors';
 import { applyDiagnostics, DateTime, RecordId, Surreal } from 'surrealdb';
 import type { Sp00kyConfig } from '../../types';
 import type { Logger } from '../logger/index';
@@ -110,6 +111,11 @@ export class LocalDatabaseService extends AbstractDatabaseService {
     // engine-backed client (built lazily) before any query is issued.
     super(createBareSurrealClient(), logger, events);
     this.config = config;
+    this.queryTimeoutMs = Math.max(0, config.localOpTimeoutMs ?? DEFAULT_LOCAL_OP_TIMEOUT_MS);
+  }
+
+  protected override timeoutError(query: string): Error {
+    return new LocalOpTimeoutError(query.slice(0, 80), this.queryTimeoutMs);
   }
 
   getConfig(): Sp00kyConfig<any>['database'] {

package/src/services/database/sqlite-cache-engine.timeout.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import { LocalOpTimeoutError } from './errors';
+import { withRetry } from '../../utils/index';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+/**
+ * The worker transport parks a call until the worker replies. A worker that
+ * never did (starved, or wedged on an unbounded lock check) left every caller
+ * waiting forever. Each round trip now has a deadline.
+ */
+describe('SqliteCacheEngine local op deadline', () => {
+  afterEach(() => vi.useRealTimers());
+
+  async function openEngine(handler: (type: string, payload: any) => unknown) {
+    const engine = new SqliteCacheEngine(
+      { namespace: 'n', database: 'd', localOpTimeoutMs: 50 } as any,
+      makeLogger()
+    );
+    stubTransport(engine, handler);
+    await engine.connect('bucket-a');
+    return engine;
+  }
+
+  it('rejects a call that never answers with LocalOpTimeoutError and keeps the queue moving', async () => {
+    vi.useFakeTimers();
+    let hang = false;
+    const engine = await openEngine((type) => {
+      if (hang && type !== 'open') return new Promise(() => {});
+      return { rows: [], result: [] };
+    });
+    hang = true;
+    const stuck = engine.query('SELECT * FROM game');
+    const settled = stuck.then(
+      () => 'resolved',
+      (e) => e
+    );
+    await vi.advanceTimersByTimeAsync(60);
+    const err = await settled;
+    expect(err).toBeInstanceOf(LocalOpTimeoutError);
+    expect((err as Error).message).toMatch(/timed out/);
+    // The next op runs; the transport is not torn down for a slow worker.
+    hang = false;
+    await expect(engine.query('SELECT * FROM game')).resolves.toBeDefined();
+  });
+
+  it('is not retried by withRetry', async () => {
+    const attempts = vi.fn(async () => {
+      throw new LocalOpTimeoutError('run', 5);
+    });
+    await expect(withRetry(makeLogger(), attempts)).rejects.toBeInstanceOf(LocalOpTimeoutError);
+    expect(attempts).toHaveBeenCalledTimes(1);
+  });
+});

package/src/services/database/sqlite-cache-engine.ts

@@ -1,4 +1,6 @@
 import { applyPatch, type Operation } from 'fast-json-patch';
+import { DEFAULT_LOCAL_OP_TIMEOUT_MS, LocalOpTimeoutError } from './errors';
+import { withTimeout } from '../../utils/index';
 import type { QueryPlan, RelationPlan, WhereNode } from '@spooky-sync/query-builder';
 import {
   renderOrderSql,
@@ -117,6 +119,8 @@ export class SqliteCacheEngine implements LocalStore {
   private workerSelectConfigured: boolean;
   private events: DatabaseEventSystem = createDatabaseEventSystem();
   private bucketId = 'anon';
+  /** Deadline for one worker round trip; see `localOpTimeoutMs`. */
+  private readonly localOpTimeoutMs: number;
   /** Durability of the local store, set on every open. A plain Set of callbacks
    *  rather than a `DatabaseEventSystem` event: this changes at most once per
    *  open, and the typed event map is about query traffic. */
@@ -140,6 +144,7 @@ export class SqliteCacheEngine implements LocalStore {
     private logger: Logger,
     opts: { useOpfs?: boolean; workerSelect?: boolean; shared?: boolean } = {}
   ) {
+    this.localOpTimeoutMs = Math.max(0, config.localOpTimeoutMs ?? DEFAULT_LOCAL_OP_TIMEOUT_MS);
     this.useOpfs = opts.useOpfs ?? true;
     this.workerSelect = opts.workerSelect ?? config.workerSelect ?? true;
     this.workerSelectConfigured = this.workerSelect;
@@ -322,7 +327,19 @@ export class SqliteCacheEngine implements LocalStore {
       this.inFlightCalls.delete(tracked);
       settle();
     };
-    const result = this.transport.call<T>(type, payload).then(
+    // Deadline per op. The transport parks a call until the worker replies,
+    // and a worker starved behind a long op (or wedged on an unbounded lock
+    // check) answered never; every caller up the stack then waited forever.
+    // Reject the CALLER only: the op is still queued in the worker and its
+    // late reply is dropped by the transport (no pending entry left to
+    // resolve). Deliberately no teardown here - a slow worker is not a dead
+    // one, and killing it mid-write would cost more than the wait.
+    const timeoutMs = this.localOpTimeoutMs;
+    const result = withTimeout(
+      this.transport.call<T>(type, payload),
+      timeoutMs,
+      () => new LocalOpTimeoutError(type, timeoutMs)
+    ).then(
       (v: T) => {
         finish();
         s.inFlight--;
@@ -338,6 +355,13 @@ export class SqliteCacheEngine implements LocalStore {
       (e: unknown) => {
         finish();
         s.inFlight--;
+        if (e instanceof LocalOpTimeoutError) {
+          s.timeouts = (s.timeouts ?? 0) + 1;
+          this.logger.error(
+            { type, timeoutMs, Category: 'sp00ky-client::SqliteCacheEngine::rawCall' },
+            'Local store op did not answer within its deadline; rejecting the caller'
+          );
+        }
         throw e;
       }
     );
@@ -1224,6 +1248,8 @@ interface SqliteStats {
   inFlight: number;
   maxInFlight: number;
   byType: Record<string, number>;
+  /** Worker round trips that hit `localOpTimeoutMs` (see rawCall). */
+  timeouts?: number;
   /** Time ops spent waiting behind the opQueue before dispatch. */
   queueWaitMs: number;
   /** Time inside the worker's message handler (actual SQLite work). */

package/src/services/database/sqlite-lock-verify.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi } from 'vitest';
+import { verifyLockStillHeld } from './sqlite-lock-verify';
+
+describe('verifyLockStillHeld', () => {
+  it('fences when the lock is no longer held', async () => {
+    const fence = vi.fn(async () => {});
+    await verifyLockStillHeld({ query: async () => ({ held: [] }) }, 'lock-a', fence, 50);
+    expect(fence).toHaveBeenCalledWith('lock missing after suspected freeze');
+  });
+
+  it('does nothing when the lock is still held', async () => {
+    const fence = vi.fn(async () => {});
+    await verifyLockStillHeld({ query: async () => ({ held: [{ name: 'lock-a' }] }) }, 'lock-a', fence, 50);
+    expect(fence).not.toHaveBeenCalled();
+  });
+
+  it('resolves within the bound when the lock query never answers, without fencing', async () => {
+    const fence = vi.fn(async () => {});
+    const warn = vi.fn();
+    const started = Date.now();
+    await verifyLockStillHeld({ query: () => new Promise(() => {}) }, 'lock-a', fence, 30, warn);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(fence).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('is a no-op without a lock or a query API', async () => {
+    const fence = vi.fn(async () => {});
+    await verifyLockStillHeld(null, 'x', fence);
+    await verifyLockStillHeld({ query: async () => ({}) }, undefined, fence);
+    expect(fence).not.toHaveBeenCalled();
+  });
+});

package/src/services/database/sqlite-lock-verify.ts

@@ -0,0 +1,45 @@
+/**
+ * "Do we still hold the OPFS lock?" - asked by the SQLite worker after a gap
+ * in its ticks long enough that the tab may have been frozen and the broker
+ * may have handed the lock to another tab.
+ *
+ * Bounded. `navigator.locks.query()` has no deadline of its own, and every op
+ * on the worker's chain awaits this verification: one query that never
+ * resolves stopped every reply to every client for good. On timeout we resolve
+ * WITHOUT fencing - the steal callback registered on the lock request remains
+ * the backstop that fences a genuinely stolen lock - and say so.
+ */
+export interface LockQueryLike {
+  query(): Promise<{ held?: { name?: string }[] }>;
+}
+
+export const LOCK_VERIFY_TIMEOUT_MS = 2_000;
+
+export async function verifyLockStillHeld(
+  locks: LockQueryLike | null | undefined,
+  name: string | undefined,
+  fence: (reason: string) => Promise<void> | void,
+  timeoutMs = LOCK_VERIFY_TIMEOUT_MS,
+  warn: (msg: string) => void = () => {}
+): Promise<void> {
+  if (!locks || !name || typeof locks.query !== 'function') return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const state = await Promise.race([
+      locks.query(),
+      new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), timeoutMs);
+      }),
+    ]);
+    if (state === null) {
+      warn(`lock verification did not answer within ${timeoutMs}ms; trusting the steal callback`);
+      return;
+    }
+    const stillHeld = (state.held ?? []).some((l) => l.name === name);
+    if (!stillHeld) await fence('lock missing after suspected freeze');
+  } catch {
+    /* query unavailable: fall back to the steal callback */
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}