@spooky-sync/core 0.0.1-canary.154 → 0.0.1-canary.155

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

@@ -18,6 +18,13 @@ import {
 } from './events/index';
 import { StaleEpochError } from './local';
 import { translateSurql, tableOf, setPath, getPath, type SqlOp } from './surql-translate';
+import {
+  BrokerPortClosedError,
+  PortSqliteTransport,
+  WorkerSqliteTransport,
+  type SqliteTransport,
+} from './sqlite-transport';
+import { PROMOTION_OPEN_OPTIONS } from './sqlite-open';
 import type { EngineTx, Id, LocalStore, OrderBy, RelationFetch, Row } from './cache-engine';
 import type { EngineStorageDiagnostics } from '../../modules/devtools/storage-info';
 
@@ -83,9 +90,9 @@ export function pureWriteOpResult(op: SqlOp): unknown {
  *   oracle E2E in the browser.
  */
 export class SqliteCacheEngine implements LocalStore {
-  private worker: Worker | null = null;
-  private seq = 0;
-  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: any) => void }>();
+  /** The wire to the SQLite worker: an owned dedicated Worker (solo/leader) or
+   *  a MessagePort into another tab's worker (follower). See sqlite-transport. */
+  private transport: SqliteTransport | null = null;
   private storeEpoch = 0;
   private knownTables = new Set<string>();
   private useOpfs: boolean;
@@ -108,14 +115,23 @@ export class SqliteCacheEngine implements LocalStore {
 
   readonly engineKind = 'sqlite' as const;
 
+  /** Shared-tabs mode: the engine's transport is swapped at runtime by the
+   *  TabsCoordinator (owner worker as leader, leader's port as follower). */
+  private shared: boolean;
+  /** Leaderless parking (shared mode): ops entering the opQueue await this
+   *  gate until a new role lands or the timeout rejects them. */
+  private roleGate: { promise: Promise<void>; release: () => void } | null = null;
+  private roleGateTimer: ReturnType<typeof setTimeout> | null = null;
+
   constructor(
     private config: Sp00kyConfig<any>['database'],
     private logger: Logger,
-    opts: { useOpfs?: boolean; workerSelect?: boolean } = {}
+    opts: { useOpfs?: boolean; workerSelect?: boolean; shared?: boolean } = {}
   ) {
     this.useOpfs = opts.useOpfs ?? true;
     this.workerSelect = opts.workerSelect ?? config.workerSelect ?? true;
     this.workerSelectConfigured = this.workerSelect;
+    this.shared = opts.shared ?? false;
   }
 
   get epoch(): number {
@@ -215,47 +231,19 @@ export class SqliteCacheEngine implements LocalStore {
 
   // ---- worker plumbing -----------------------------------------------------
 
-  private spawnWorker(): Worker {
-    // Source references the `.ts` so the monorepo's src-bundling consumers
-    // (e.g. the example app, which aliases `@spooky-sync/core` to `src`) resolve
-    // it — Vite handles `.ts` workers. For the published package, the tsdown
-    // build rewrites this to `./sqlite-worker.js` (the top-level emitted entry;
-    // see tsdown.config.ts), which the flat `dist/index.js` resolves. The worker
-    // (+ `@sqlite.org/sqlite-wasm`) still loads lazily — only when `localEngine:
-    // 'sqlite'` is used.
-    const worker = new Worker(new URL('./sqlite-worker.ts', import.meta.url), { type: 'module' });
-    worker.onmessage = (ev: MessageEvent) => {
-      const { id, ok, error, ...rest } = ev.data ?? {};
-      const p = this.pending.get(id);
-      if (!p) return;
-      this.pending.delete(id);
-      if (ok) p.resolve(rest);
-      else p.reject(new Error(error));
-    };
-    // Surface a worker crash (wasm abort / OOM) instead of leaving every pending
-    // call hung forever — reject them all with a clear error.
-    const failAll = (msg: string) => {
-      const err = new Error(`SQLite worker crashed: ${msg}`);
-      this.logger.error(
-        { err, Category: 'sp00ky-client::SqliteCacheEngine::worker' },
-        'Worker error'
-      );
-      for (const [, p] of this.pending) p.reject(err);
-      this.pending.clear();
-    };
-    worker.onerror = (e: ErrorEvent) => failAll(e.message || 'onerror');
-    worker.onmessageerror = () => failAll('messageerror');
-    return worker;
-  }
-
   /** Serializes every worker op so reads/writes never overlap at the VFS layer
    *  (overlapping ops trip SQLITE_BUSY). Mirrors the SurrealDB engine's
-   *  single-flight query queue. */
+   *  single-flight query queue. (The worker keeps its own chain too, for
+   *  multi-client mode; this one additionally provides the queue-wait stat and
+   *  the boot/switch atomicity below.) */
   private opQueue: Promise<unknown> = Promise.resolve();
 
   private call<T = any>(type: string, payload?: unknown): Promise<T> {
     const enqueuedAt = performance.now();
-    const run = () => {
+    const run = async () => {
+      // Leaderless window (shared mode): park behind the role gate instead of
+      // failing; a new leader releases it, the timeout rejects it.
+      if (this.roleGate) await this.roleGate.promise;
       // Time spent waiting behind other ops in the queue, not doing work.
       getStats().queueWaitMs += performance.now() - enqueuedAt;
       return this.rawCall<T>(type, payload);
@@ -270,8 +258,7 @@ export class SqliteCacheEngine implements LocalStore {
   }
 
   private rawCall<T = any>(type: string, payload?: unknown): Promise<T> {
-    if (!this.worker) throw new Error('SqliteCacheEngine: not connected');
-    const id = ++this.seq;
+    if (!this.transport) throw new Error('SqliteCacheEngine: not connected');
     // --- instrumentation: live, inspectable via `globalThis.__sqliteStats` ---
     const s = getStats();
     s.roundTrips++;
@@ -282,30 +269,25 @@ export class SqliteCacheEngine implements LocalStore {
     }
     s.inFlight++;
     s.maxInFlight = Math.max(s.maxInFlight, s.inFlight);
-    const done = () => {
-      s.inFlight--;
-    };
+    if (this.transport.kind === 'port') s.proxiedOps = (s.proxiedOps ?? 0) + 1;
     const sentAt = performance.now();
-    return new Promise<T>((resolve, reject) => {
-      this.pending.set(id, {
-        resolve: (v: T) => {
-          done();
-          // Split the round-trip: `wt` is time inside the worker's handler,
-          // the remainder is postMessage + scheduling overhead.
-          const wt = (v as { wt?: unknown } | null)?.wt;
-          if (typeof wt === 'number') {
-            s.workerMs += wt;
-            s.rpcOverheadMs += Math.max(0, performance.now() - sentAt - wt);
-          }
-          resolve(v);
-        },
-        reject: (e: unknown) => {
-          done();
-          reject(e);
-        },
-      });
-      this.worker!.postMessage({ id, type, payload });
-    });
+    return this.transport.call<T>(type, payload).then(
+      (v: T) => {
+        s.inFlight--;
+        // Split the round-trip: `wt` is time inside the worker's handler,
+        // the remainder is postMessage + scheduling overhead.
+        const wt = (v as { wt?: unknown } | null)?.wt;
+        if (typeof wt === 'number') {
+          s.workerMs += wt;
+          s.rpcOverheadMs += Math.max(0, performance.now() - sentAt - wt);
+        }
+        return v;
+      },
+      (e: unknown) => {
+        s.inFlight--;
+        throw e;
+      }
+    );
   }
 
   /**
@@ -313,8 +295,30 @@ export class SqliteCacheEngine implements LocalStore {
    * {@link call}) so it can run as the body of an already-queued opQueue entry
    * without re-queuing onto itself. Callers must run it through the opQueue.
    */
-  private async openInternal(bucketId: string): Promise<void> {
-    this.worker = this.spawnWorker();
+  /** Seam for tests: swap in a fake transport instead of a real Worker. */
+  protected createTransport(): SqliteTransport {
+    return new WorkerSqliteTransport(this.logger);
+  }
+
+  private async openInternal(
+    bucketId: string,
+    extras?: {
+      workerLockName?: string;
+      openOptions?: { maxAttempts?: number; backoffMs?: number[]; disallowMemoryFallback?: boolean };
+    }
+  ): Promise<void> {
+    if (!this.transport || this.transport.kind !== 'worker' || !this.transport.connected) {
+      this.transport = this.createTransport();
+      if (this.transport instanceof WorkerSqliteTransport) {
+        // The worker fencing itself (leadership stolen from a frozen tab that
+        // thawed) is a leader-loss: park ops until the broker re-adopts us.
+        this.transport.onLockLost = (reason) => {
+          this.transport = null;
+          this.storeEpoch++;
+          this.openRoleGate(`worker fenced: ${reason}`);
+        };
+      }
+    }
     // Seed the `_00_*` system tables as part of `open` (worker-side, one round
     // trip). The LocalMigrator DEFINEs them, but `translateSurql` lowers every
     // DEFINE to a noop on this engine (SQLite has no DDL vocabulary), so
@@ -333,6 +337,8 @@ export class SqliteCacheEngine implements LocalStore {
       dbName: bucketId,
       useOpfs: this.useOpfs,
       systemTables: SYSTEM_TABLES,
+      ...(extras?.workerLockName ? { workerLockName: extras.workerLockName } : {}),
+      ...(extras?.openOptions ? { openOptions: extras.openOptions } : {}),
     });
     this.knownTables.clear();
     for (const t of SYSTEM_TABLES) this.knownTables.add(t);
@@ -349,6 +355,7 @@ export class SqliteCacheEngine implements LocalStore {
       fallback: fellBack,
     };
     if (fellBack && opfsError) health.error = opfsError;
+    if (this.shared) health.role = this.roleLabel;
     this.setStorageHealth(health);
     const stats = getStats();
     stats.persisted = persisted;
@@ -393,28 +400,230 @@ export class SqliteCacheEngine implements LocalStore {
     // As a single entry, every other op runs fully before the close or after
     // the reopen — never against a closed DB.
     await this.enqueue(async () => {
-      if (this.worker) {
+      if (this.transport) {
         try {
           await this.rawCall('close');
         } catch {
           /* ignore */
         }
-        this.worker.terminate();
-        this.worker = null;
+        this.transport.close('bucket switch');
+        this.transport = null;
       }
       await this.openInternal(bucketId);
     });
   }
 
   async close(): Promise<void> {
-    if (!this.worker) return;
+    if (!this.transport) return;
     try {
       await this.call('close');
     } catch {
       /* ignore */
     }
-    this.worker.terminate();
-    this.worker = null;
+    this.transport.close('engine closed');
+    this.transport = null;
+  }
+
+  // ---- shared-tabs role modes ------------------------------------------------
+  // The TabsCoordinator drives these; solo mode never touches them. The engine
+  // object is never replaced across role changes, so `storeEpoch` stays one
+  // monotonic per-tab counter and every existing fencing consumer keeps
+  // working unchanged.
+
+  /** Which role the current transport represents, for StorageHealth. */
+  private roleLabel: 'leader' | 'follower' | 'solo' = 'solo';
+  /** True once this engine has had a usable store at least once; role changes
+   *  after that point invalidate in-flight reads and must bump the epoch. */
+  private hadStore = false;
+
+  /**
+   * Role transitions run on their OWN chain, never on the opQueue: parked ops
+   * sit INSIDE opQueue entries waiting for the role gate, so a transition
+   * queued behind them could never run to release them (deadlock). Transitions
+   * are safe off-queue because in-flight ops on a dead transport were already
+   * rejected, parked ops only resume after the transition completes, and the
+   * worker serializes everything worker-side anyway.
+   */
+  private transitionChain: Promise<unknown> = Promise.resolve();
+
+  private chainTransition<T>(fn: () => Promise<T>): Promise<T> {
+    const result = this.transitionChain.then(fn, fn);
+    this.transitionChain = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+
+  private openRoleGate(reason: string): void {
+    if (this.roleGate) return;
+    let release!: () => void;
+    let rejectFn!: (e: Error) => void;
+    const promise = new Promise<void>((res, rej) => {
+      release = res;
+      rejectFn = rej;
+    });
+    // Swallow the timeout rejection for waiters that already resolved.
+    promise.catch(() => {});
+    this.roleGate = { promise, release };
+    this.roleGateTimer = setTimeout(() => {
+      // Nothing adopted us in time: reject the parked ops (retryable) and drop
+      // the gate so later calls fail fast with 'not connected'.
+      rejectFn(new BrokerPortClosedError(`no leader adopted this tab: ${reason}`));
+      this.roleGate = null;
+      this.roleGateTimer = null;
+    }, 20_000);
+  }
+
+  private closeRoleGate(): void {
+    if (this.roleGateTimer) clearTimeout(this.roleGateTimer);
+    this.roleGateTimer = null;
+    this.roleGate?.release();
+    this.roleGate = null;
+  }
+
+  /**
+   * Become the store owner (leader). Boot and failover share this path; a
+   * failover (a previous transport existed) bumps the epoch FIRST so every
+   * in-flight chain that captured the old epoch fences itself. `resumeHeld`
+   * keeps the live worker after a broker restart and only rolls the
+   * per-leadership lock forward.
+   */
+  async adoptOwner(
+    bucketId: string,
+    opts: {
+      workerLockName: string;
+      allowMemoryFallback: boolean;
+      resumeHeld: boolean;
+    }
+  ): Promise<StorageHealth> {
+    this.roleLabel = 'leader';
+    return this.chainTransition(async () => {
+      if (
+        opts.resumeHeld &&
+        this.transport?.kind === 'worker' &&
+        this.transport.connected &&
+        this.bucketId === bucketId
+      ) {
+        await this.rawCall('relock', { workerLockName: opts.workerLockName });
+        this.closeRoleGate();
+        return this.storageHealthValue;
+      }
+      if (this.hadStore) this.storeEpoch++;
+      if (this.transport) {
+        try {
+          if (this.transport.kind === 'worker') await this.rawCall('close');
+        } catch {
+          /* ignore */
+        }
+        this.transport.close('adopting ownership');
+        this.transport = null;
+      }
+      await this.openInternal(bucketId, {
+        workerLockName: opts.workerLockName,
+        openOptions: {
+          ...PROMOTION_OPEN_OPTIONS,
+          disallowMemoryFallback: !opts.allowMemoryFallback,
+        },
+      });
+      // Leader wipe-on-pool-open: local `_00_query` rows from earlier sessions
+      // are dead (query hashes are session-salted) and this is the one moment
+      // no other tab is attached, so clearing here replaces the per-switch
+      // DELETE that solo mode does in doSwitchBucket. Followers never wipe.
+      try {
+        await this.rawCall('run', { sql: 'DELETE FROM "_00_query"' });
+      } catch {
+        /* fresh bucket: table just seeded, nothing to wipe */
+      }
+      getStats().roleChanges = (getStats().roleChanges ?? 0) + 1;
+      this.hadStore = true;
+      this.closeRoleGate();
+      return this.storageHealthValue;
+    });
+  }
+
+  /** Attach to a leader's worker through `dbPort` (follower). */
+  async adoptAttached(
+    dbPort: MessagePort,
+    snapshot: { bucketId: string; storageHealth: StorageHealth },
+    onPortDead: (reason: string) => void
+  ): Promise<void> {
+    this.roleLabel = 'follower';
+    return this.chainTransition(async () => {
+      if (this.hadStore) this.storeEpoch++;
+      this.transport?.close('adopting leader port');
+      this.transport = new PortSqliteTransport(dbPort, onPortDead, this.logger);
+      this.bucketId = snapshot.bucketId;
+      // The shared store exists and is seeded; mirror the owner's bookkeeping.
+      this.knownTables.clear();
+      for (const t of SYSTEM_TABLES) this.knownTables.add(t);
+      const health: StorageHealth = { ...snapshot.storageHealth, role: 'follower' };
+      this.setStorageHealth(health);
+      const stats = getStats();
+      stats.persisted = snapshot.storageHealth.status === 'persistent';
+      stats.roleChanges = (stats.roleChanges ?? 0) + 1;
+      delete stats.opfsError;
+      this.hadStore = true;
+      this.closeRoleGate();
+    });
+  }
+
+  /** Demoted while owning the store (zombie thaw, stale promotion): tear the
+   *  worker down so its OPFS handles free up, then park until re-adopted. */
+  async releaseOwnership(): Promise<void> {
+    await this.chainTransition(async () => {
+      if (this.transport) {
+        try {
+          if (this.transport.kind === 'worker') {
+            await (this.transport as WorkerSqliteTransport).shutdown();
+          }
+        } catch {
+          /* worker may already be fenced/dead */
+        }
+        this.transport.close('ownership released');
+        this.transport = null;
+      }
+      this.storeEpoch++;
+      this.openRoleGate('ownership released');
+    });
+  }
+
+  /** The leader (or its port) died. Called from the port-dead callback and the
+   *  coordinator; NOT enqueued, so in-flight ops reject immediately instead of
+   *  waiting behind whatever is stuck. */
+  onLeaderLost(reason: string): void {
+    if (this.transport?.kind === 'port') {
+      this.transport.close(reason);
+      this.transport = null;
+    }
+    this.storeEpoch++;
+    this.openRoleGate(reason);
+  }
+
+  /** Leader side: forward a follower's dbPort into the owned worker. */
+  async exposeClientPort(clientId: string, port: MessagePort): Promise<void> {
+    if (this.transport?.kind !== 'worker') {
+      throw new Error('SqliteCacheEngine: not the store owner');
+    }
+    await (this.transport as WorkerSqliteTransport).addClientPort(clientId, port);
+  }
+
+  async removeClientPort(clientId: string): Promise<void> {
+    if (this.transport?.kind !== 'worker') return;
+    await (this.transport as WorkerSqliteTransport).removeClientPort(clientId);
+  }
+
+  /** Graceful pagehide as owner: release OPFS handles NOW so the next leader
+   *  does not race the browser's worker GC. */
+  async shutdownOwnedWorker(): Promise<void> {
+    if (this.transport?.kind !== 'worker') return;
+    try {
+      await (this.transport as WorkerSqliteTransport).shutdown();
+    } catch {
+      /* ignore */
+    }
+    this.transport.close('shutdown');
+    this.transport = null;
   }
 
   private async ensureTable(table: string): Promise<void> {
@@ -855,6 +1064,10 @@ interface SqliteStats {
   persisted?: boolean;
   /** Why OPFS persistence failed, when it did. */
   opfsError?: string;
+  /** Shared-tabs follower: ops that crossed the leader's MessagePort. */
+  proxiedOps?: number;
+  /** Times this tab's engine changed hands (promotions + attachments). */
+  roleChanges?: number;
 }
 
 const EMPTY_STATS: SqliteStats = {

package/src/services/database/sqlite-open.ts

@@ -27,12 +27,22 @@ export interface SqliteDbHandle {
   close: () => void;
 }
 
+/** The slice of the OpfsSAHPoolUtil the worker needs for teardown. */
+export interface SqlitePoolHandle {
+  /** Unregisters the VFS and releases every sync access handle, leaving the
+   *  files intact, so another worker can open the pool without waiting for
+   *  this worker to be garbage collected. Throws while files are open. */
+  pauseVfs?: () => unknown;
+}
+
 export interface OpenDbResult {
   db: SqliteDbHandle;
   /** True only when the handle is backed by OPFS and survives a reload. */
   persisted: boolean;
   /** Why persistence failed. Set only when OPFS was requested and fell back. */
   opfsError?: string;
+  /** Pool util, present only for an OPFS-backed handle. */
+  pool?: SqlitePoolHandle;
 }
 
 export interface OpenDbOptions {
@@ -40,6 +50,14 @@ export interface OpenDbOptions {
   maxAttempts?: number;
   /** Delay before each retry; the last entry repeats. Default [250, 500]. */
   backoffMs?: number[];
+  /**
+   * Throw (`opfs-unavailable: <reason>`) instead of falling back to memory.
+   * Used by shared-tabs leader promotion: a silently-in-memory LEADER would
+   * put every tab's data in RAM, so promotion prefers failing the election
+   * (the broker retries, possibly on another tab) over degrading. The broker
+   * grants an explicit memory fallback only after repeated failed cycles.
+   */
+  disallowMemoryFallback?: boolean;
   /** Injectable for tests. */
   sleep?: (ms: number) => Promise<void>;
 }
@@ -48,6 +66,17 @@ const DEFAULT_MAX_ATTEMPTS = 3;
 /** Bounded on purpose: this runs on the boot path, before the first query. */
 const DEFAULT_BACKOFF_MS = [250, 500];
 
+/**
+ * Leader-promotion profile (~5.8s worst case). A dead leader's sync access
+ * handles release when the browser garbage-collects its worker, typically
+ * well under a second but not synchronously with the Web Lock release the
+ * election observed, so promotion retries longer than a cold boot.
+ */
+export const PROMOTION_OPEN_OPTIONS: Pick<OpenDbOptions, 'maxAttempts' | 'backoffMs'> = {
+  maxAttempts: 10,
+  backoffMs: [50, 100, 200, 400, 800, 1000],
+};
+
 /** Failures no retry can fix: the APIs aren't there at all (insecure context,
  *  or a browser without sync access handles). Fall back immediately. */
 const UNRETRYABLE = ['Missing required OPFS APIs'];
@@ -96,6 +125,9 @@ export async function openDb(
   if (!useOpfs) return { db: new sqlite3.oo1.DB(':memory:', 'c'), persisted: false };
 
   if (!sqlite3.installOpfsSAHPoolVfs) {
+    if (opts.disallowMemoryFallback) {
+      throw new Error('opfs-unavailable: sqlite-wasm build has no installOpfsSAHPoolVfs');
+    }
     return fallbackToMemory(sqlite3, dbName, 'sqlite-wasm build has no installOpfsSAHPoolVfs', 0);
   }
 
@@ -118,12 +150,15 @@ export async function openDb(
         // doesn't ask for a real re-init just replays the same rejection.
         ...(attempt > 1 ? { forceReinitIfPreviouslyFailed: true } : {}),
       });
-      return { db: new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`), persisted: true };
+      return { db: new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`), persisted: true, pool };
     } catch (e) {
       lastError = errMessage(e);
       if (attempt === maxAttempts || UNRETRYABLE.some((m) => lastError.includes(m))) break;
       await sleep(backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 0);
     }
   }
+  if (opts.disallowMemoryFallback) {
+    throw new Error(`opfs-unavailable: ${lastError} (after ${attempts} attempts)`);
+  }
   return fallbackToMemory(sqlite3, dbName, lastError, attempts);
 }

package/src/services/database/sqlite-select.test.ts

@@ -3,6 +3,7 @@ import { RecordId } from 'surrealdb';
 import type { QueryPlan } from '@spooky-sync/query-builder';
 import { executeSelect, type SelectDb } from './sqlite-select';
 import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
 import { stableKey } from './relation-resolver';
 import type { Row } from './cache-engine';
 
@@ -87,52 +88,18 @@ function makeEngine(opts: {
     makeLogger(),
     { useOpfs: false, workerSelect: opts.workerSelect }
   );
-  (engine as any).spawnWorker = () => {
-    const w: any = {
-      onerror: null,
-      onmessageerror: null,
-      terminate() {},
-      postMessage(msg: any) {
-        calls.push({
-          type: msg.type,
-          sql: msg.payload?.sql,
-          bind: msg.payload?.bind,
-          payload: msg.payload,
-        });
-        Promise.resolve().then(async () => {
-          let ok = true;
-          let error: string | undefined;
-          let rest: Record<string, unknown> = {};
-          try {
-            if (msg.type === 'open') rest = { persisted: false };
-            else if (msg.type === 'exec') rest = { rows: respond(msg.payload.sql, msg.payload.bind ?? []) };
-            else if (msg.type === 'run' || msg.type === 'batch' || msg.type === 'close') rest = {};
-            else if (msg.type === 'select') {
-              if (!opts.answerSelect) throw new Error(`sqlite worker: unknown message ${msg.type}`);
-              const dbCalls: { sql: string; bind?: unknown[] }[] = [];
-              rest = await executeSelect(
-                msg.payload.plan,
-                msg.payload.params ?? {},
-                makeSelectDb(FIXTURE, dbCalls)
-              );
-            } else throw new Error(`sqlite worker: unknown message ${msg.type}`);
-          } catch (e) {
-            ok = false;
-            error = e instanceof Error ? e.message : String(e);
-          }
-          (engine as any).worker &&
-            (engine as any).pending.get(msg.id) &&
-            ((): void => {
-              const p = (engine as any).pending.get(msg.id);
-              (engine as any).pending.delete(msg.id);
-              if (ok) p.resolve(rest);
-              else p.reject(new Error(error));
-            })();
-        });
-      },
-    };
-    return w;
-  };
+  stubTransport(engine, async (type, payload) => {
+    calls.push({ type, sql: payload?.sql, bind: payload?.bind, payload });
+    if (type === 'open') return { persisted: false };
+    if (type === 'exec') return { rows: respond(payload.sql, payload.bind ?? []) };
+    if (type === 'run' || type === 'batch' || type === 'close') return {};
+    if (type === 'select') {
+      if (!opts.answerSelect) throw new Error(`sqlite worker: unknown message ${type}`);
+      const dbCalls: { sql: string; bind?: unknown[] }[] = [];
+      return executeSelect(payload.plan, payload.params ?? {}, makeSelectDb(FIXTURE, dbCalls));
+    }
+    throw new Error(`sqlite worker: unknown message ${type}`);
+  });
   return { engine, calls };
 }
 

package/src/services/database/sqlite-transport.fixture.ts

@@ -0,0 +1,30 @@
+/**
+ * Test-only helper: stubs `SqliteCacheEngine.createTransport` with a fake
+ * transport driven by a plain handler function, replacing the old pattern of
+ * faking a whole Worker plus the engine's pending-map wiring. Not exported
+ * from the package; imported only by *.test.ts files.
+ */
+import type { SqliteTransport } from './sqlite-transport';
+
+export type FakeTransportHandler = (type: string, payload: any) => unknown | Promise<unknown>;
+
+/** Replace the engine's transport factory. Each open spawns a fresh fake, like
+ *  the real factory spawns a fresh Worker. The handler returns the reply rest
+ *  (without id/ok/wt) or throws to produce an error reply. */
+export function stubTransport(engine: unknown, handler: FakeTransportHandler): void {
+  (engine as { createTransport: () => SqliteTransport }).createTransport = () => {
+    let closed = false;
+    return {
+      kind: 'worker',
+      get connected() {
+        return !closed;
+      },
+      call: <T>(type: string, payload?: unknown) =>
+        Promise.resolve().then(() => handler(type, payload)) as Promise<T>,
+      failAll() {},
+      close() {
+        closed = true;
+      },
+    } as SqliteTransport;
+  };
+}