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

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

@@ -0,0 +1,224 @@
+/**
+ * The wire between `SqliteCacheEngine` and the SQLite worker, extracted so the
+ * engine can swap it at runtime without touching any SQL logic. Two shapes:
+ *
+ * - {@link WorkerSqliteTransport}: owns a dedicated Worker (solo mode, and the
+ *   leader tab in shared-tabs mode). Controls the worker's lifecycle and can
+ *   forward follower MessagePorts into it (`add-client`).
+ * - {@link PortSqliteTransport}: speaks the same request/response protocol over
+ *   a MessagePort handed out by the leader (follower tabs). No lifecycle
+ *   control; the port dying surfaces through `onPortDead`.
+ *
+ * Both keep the pending-map semantics the engine had inline before: requests
+ * keyed by a locally-minted numeric id, one resolve/reject per id, `failAll`
+ * rejects everything in flight (worker crash, port loss, role change).
+ */
+import type { Logger } from '../logger/index';
+
+export interface SqliteTransport {
+  readonly kind: 'worker' | 'port';
+  /** True while the transport can carry a request. */
+  readonly connected: boolean;
+  call<T = unknown>(type: string, payload?: unknown): Promise<T>;
+  /** Reject every pending request with `reason`. Safe to call repeatedly. */
+  failAll(reason: string): void;
+  /** failAll + release the underlying channel. Terminal. `err` overrides the
+   *  transport's own error shape — used for a deliberate teardown (role change)
+   *  so callers see a retryable "transport lost", not "the worker crashed". */
+  close(reason?: string, err?: Error): void;
+}
+
+/** Thrown into pending follower calls when the leader (or its port) goes away.
+ *  Callers treat it like a transient error: the op may be retried once a new
+ *  leader is attached; nothing was necessarily executed. */
+export class BrokerPortClosedError extends Error {
+  readonly retryable = true;
+  constructor(reason: string) {
+    super(`sqlite transport lost: ${reason}`);
+    this.name = 'BrokerPortClosedError';
+  }
+}
+
+interface Pending {
+  resolve: (v: any) => void;
+  reject: (e: unknown) => void;
+}
+
+/** Shared request/response bookkeeping over any postMessage-shaped channel. */
+abstract class BaseTransport implements SqliteTransport {
+  abstract readonly kind: 'worker' | 'port';
+  protected pending = new Map<number, Pending>();
+  protected seq = 0;
+  protected closed = false;
+
+  constructor(protected logger: Logger) {}
+
+  get connected(): boolean {
+    return !this.closed;
+  }
+
+  protected abstract post(msg: unknown, transfer?: Transferable[]): void;
+  protected abstract makeError(reason: string): Error;
+
+  protected handleMessage(data: any): void {
+    const { id, ok, error, ...rest } = 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));
+  }
+
+  call<T = unknown>(type: string, payload?: unknown): Promise<T> {
+    if (this.closed) return Promise.reject(this.makeError('transport closed'));
+    const id = ++this.seq;
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      try {
+        this.post({ id, type, payload });
+      } catch (e) {
+        this.pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  failAll(reason: string, err?: Error): void {
+    if (this.pending.size === 0) return;
+    const e = err ?? this.makeError(reason);
+    for (const [, p] of this.pending) p.reject(e);
+    this.pending.clear();
+  }
+
+  close(reason = 'closed', err?: Error): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.failAll(reason, err);
+  }
+}
+
+export class WorkerSqliteTransport extends BaseTransport {
+  readonly kind = 'worker' as const;
+  private worker: Worker;
+  /** Fired when the worker reports it fenced itself after a leadership steal
+   *  (see sqlite-worker.ts). The engine must treat the store as gone. */
+  onLockLost: ((reason: string) => void) | null = null;
+
+  constructor(logger: Logger) {
+    super(logger);
+    // 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.
+    this.worker = new Worker(new URL('./sqlite-worker.ts', import.meta.url), { type: 'module' });
+    this.worker.onmessage = (ev: MessageEvent) => {
+      // Unsolicited worker-initiated notification, not a reply.
+      if (ev.data?.type === 'lock-lost') {
+        this.logger.error(
+          { reason: ev.data.reason, Category: 'sp00ky-client::SqliteCacheEngine::worker' },
+          'SQLite worker fenced after leadership loss'
+        );
+        this.failAll('worker fenced');
+        this.onLockLost?.(String(ev.data.reason ?? 'lock-lost'));
+        return;
+      }
+      this.handleMessage(ev.data);
+    };
+    // Surface a worker crash (wasm abort / OOM) instead of leaving every
+    // pending call hung forever — reject them all with a clear error, AND
+    // close: `failAll` alone left `connected` true, so every later call was
+    // posted to the dead worker and parked in `pending` for good. Closed, the
+    // engine sees `!connected` and spawns a fresh worker on its next open.
+    const crash = (msg: string) => {
+      this.logger.error(
+        { err: this.makeError(msg), Category: 'sp00ky-client::SqliteCacheEngine::worker' },
+        'Worker error'
+      );
+      this.close(msg);
+    };
+    this.worker.onerror = (e: ErrorEvent) => crash(e.message || 'onerror');
+    this.worker.onmessageerror = () => crash('messageerror');
+  }
+
+  protected post(msg: unknown, transfer?: Transferable[]): void {
+    if (transfer) this.worker.postMessage(msg, transfer);
+    else this.worker.postMessage(msg);
+  }
+
+  protected makeError(reason: string): Error {
+    return new Error(`SQLite worker crashed: ${reason}`);
+  }
+
+  /** Forward a follower's MessagePort into the worker as an extra client. */
+  addClientPort(clientId: string, port: MessagePort): Promise<void> {
+    if (this.closed) return Promise.reject(this.makeError('transport closed'));
+    const id = ++this.seq;
+    return new Promise<void>((resolve, reject) => {
+      this.pending.set(id, { resolve: () => resolve(), reject });
+      this.worker.postMessage({ id, type: 'add-client', payload: { clientId } }, [port]);
+    });
+  }
+
+  removeClientPort(clientId: string): Promise<void> {
+    return this.call('remove-client', { clientId }).then(() => undefined);
+  }
+
+  /** Ask the worker to close + pauseVfs + self-close (graceful pagehide). */
+  shutdown(): Promise<void> {
+    return this.call('shutdown').then(() => undefined);
+  }
+
+  close(reason = 'closed', err?: Error): void {
+    if (this.closed) return;
+    super.close(reason, err);
+    this.worker.terminate();
+  }
+}
+
+export class PortSqliteTransport extends BaseTransport {
+  readonly kind = 'port' as const;
+
+  constructor(
+    private port: MessagePort,
+    private onPortDead: (reason: string) => void,
+    logger: Logger
+  ) {
+    super(logger);
+    port.onmessage = (ev: MessageEvent) => this.handleMessage(ev.data);
+    port.onmessageerror = () => this.dead('messageerror');
+    port.start?.();
+  }
+
+  /** The broker/coordinator learned the leader is gone; the port itself has no
+   *  close event, so the coordinator calls this explicitly. */
+  markDead(reason: string): void {
+    this.dead(reason);
+  }
+
+  private dead(reason: string, err?: Error): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.failAll(reason, err);
+    try {
+      this.port.close();
+    } catch {
+      /* ignore */
+    }
+    this.onPortDead(reason);
+  }
+
+  protected post(msg: unknown): void {
+    this.port.postMessage(msg);
+  }
+
+  protected makeError(reason: string): Error {
+    return new BrokerPortClosedError(reason);
+  }
+
+  close(reason = 'closed', err?: Error): void {
+    this.dead(reason, err);
+  }
+}

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

@@ -0,0 +1,437 @@
+/// <reference lib="webworker" />
+/**
+ * Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+ * funnelled through here (the main thread never touches the wasm module), which
+ * is also what the OPFS VFS requires — file access must happen off the main
+ * thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+ * classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+ * headers, so host apps embedding the client need no server changes. When OPFS
+ * is unavailable it retries, then falls back to an in-memory DB and REPORTS the
+ * loss of durability (see `sqlite-open.ts`) instead of degrading silently.
+ *
+ * Message protocol (request/response keyed by `id`; replies go to the channel
+ * the request arrived on):
+ *   { id, type: 'open',   payload: { dbName, useOpfs, workerLockName? } }
+ *        -> { id, ok, persisted, opfsError? }
+ *   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
+ *   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
+ *   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+ *   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
+ *   { id, type: 'close' }
+ *   { id, type: 'shutdown' }                     (owner only: close + pauseVfs + self.close)
+ *   { id, type: 'relock', payload: { workerLockName } }               (owner only)
+ *   { id, type: 'add-client', payload: { clientId } } + ev.ports[0]   (owner only)
+ *   { id, type: 'remove-client', payload: { clientId } }              (owner only)
+ *
+ * Multi-client (shared-tabs mode): the OWNER (the leader tab's engine) speaks
+ * on the worker's own channel and controls the lifecycle. Follower tabs get a
+ * MessagePort each (`add-client`) and may only issue data ops
+ * (exec/run/batch/select). Every op, from any channel, runs through ONE op
+ * chain so an async `select` from one client can never interleave with another
+ * client's `batch` at the VFS layer.
+ *
+ * Leader fencing (shared-tabs mode): `open` may carry `workerLockName`, a Web
+ * Lock this worker acquires BEFORE opening the pool and holds for the DB's
+ * lifetime. The name is unique per leadership, so the lock being gone has
+ * exactly one meaning: the broker stole it because this tab was presumed dead
+ * (usually frozen). When that happens the worker FENCES itself: closes the DB,
+ * releases the OPFS sync access handles (pauseVfs), tells the owner, and
+ * refuses every further op. A frozen-then-thawed ex-leader therefore can never
+ * write the durable file after a new leader took over. The thaw gate below
+ * closes the wake-up ordering race where a queued write could run before the
+ * lock-loss callback fires.
+ *
+ * `select` executes a whole QueryPlan — table creation, base select, the full
+ * `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
+ * round-trip, returning structured-clone row objects. This is the first-load
+ * hot path; the per-statement ops remain for the write/shim paths.
+ */
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { verifyLockStillHeld as verifyLockStillHeldBounded } from './sqlite-lock-verify';
+import {
+  openDb,
+  type OpenDbOptions,
+  type SqliteDbHandle,
+  type SqlitePoolHandle,
+} from './sqlite-open';
+import { executeSelect, type SelectDb } from './sqlite-select';
+
+interface Stmt {
+  sql: string;
+  bind?: unknown[];
+}
+
+interface PostTarget {
+  postMessage: (msg: unknown) => void;
+}
+
+let db: SqliteDbHandle | null = null;
+let pool: SqlitePoolHandle | null = null;
+
+// ==================== leader fencing (worker web lock) ====================
+
+/** Once fenced, every op is refused and the DB stays closed. Terminal. */
+let fenced = false;
+
+interface HeldLock {
+  name: string;
+  /** Release on purpose; the closure-local flag keeps the steal handler from
+   *  mistaking it for a takeover. Idempotent. */
+  release: () => void;
+}
+
+/** The per-leadership lock currently held (null = no fencing active). A
+ *  relock (same-leader re-promotion after a broker restart) briefly holds two
+ *  locks: the new one is installed here first, then the old one's own release
+ *  is called, so there is no window where neither is held. */
+let currentLock: HeldLock | null = null;
+
+function workerLocks(): LockManager | null {
+  const nav = (globalThis as { navigator?: { locks?: LockManager } }).navigator;
+  return nav?.locks && typeof nav.locks.request === 'function' ? nav.locks : null;
+}
+
+/**
+ * Acquire `name` exclusively without waiting. Resolves with a handle when
+ * granted, null when someone else holds it. If the request settles while the
+ * holder still believes it owns the lock, the broker stole it: fence.
+ */
+function acquireWorkerLock(name: string): Promise<HeldLock | null> {
+  const locks = workerLocks();
+  // No Web Locks (non-browser test env): no fencing, behave as before.
+  if (!locks) return Promise.resolve({ name, release() {} });
+  return new Promise<HeldLock | null>((resolve) => {
+    let granted = false;
+    let intentional = false;
+    let releaseGrant: (() => void) | null = null;
+    locks
+      .request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
+        if (!lock) {
+          resolve(null);
+          return;
+        }
+        granted = true;
+        resolve({
+          name,
+          release() {
+            intentional = true;
+            releaseGrant?.();
+          },
+        });
+        return new Promise<void>((release) => {
+          releaseGrant = release;
+        });
+      })
+      .then(
+        () => {
+          if (granted && !intentional) void fence('worker lock stolen');
+        },
+        () => {
+          if (granted && !intentional) void fence('worker lock request failed');
+        }
+      );
+  });
+}
+
+function releaseHeldLock(): void {
+  currentLock?.release();
+  currentLock = null;
+}
+
+/**
+ * Terminal teardown after leadership loss. Closing the DB first makes
+ * pauseVfs legal (it throws while files are open); pausing releases the sync
+ * access handles so the NEW leader's open succeeds without waiting for this
+ * worker to be garbage collected.
+ */
+async function fence(reason: string): Promise<void> {
+  if (fenced) return;
+  fenced = true;
+  // Deliberately console, not a logger: this must be visible in any host app
+  // regardless of its configured log level.
+  // oxlint-disable-next-line no-console
+  console.error(
+    `[sp00ky] sqlite worker fenced (${reason}): leadership was taken over, ` +
+      'closing the database and refusing further ops.'
+  );
+  try {
+    db?.close();
+  } catch {
+    /* already closed */
+  }
+  db = null;
+  try {
+    pool?.pauseVfs?.();
+  } catch {
+    /* pool already torn down or files still open; new leader retries anyway */
+  }
+  pool = null;
+  try {
+    (self as unknown as Worker).postMessage({ type: 'lock-lost', reason });
+  } catch {
+    /* owner gone */
+  }
+  releaseHeldLock();
+  self.close();
+}
+
+// ==================== thaw gate ====================
+
+/**
+ * A frozen tab's worker resumes with its message queue intact, and a queued
+ * write could run BEFORE the lock-steal callback fires. Both the 1s interval
+ * and every op call `noteTick()`; whichever runs first after a long gap kicks
+ * off a lock verification, and ops await it before touching the DB. The gap
+ * threshold must stay BELOW the broker's pong timeout: a freeze shorter than
+ * the threshold cannot have triggered a steal yet, so skipping the check for
+ * small gaps is safe.
+ */
+const FREEZE_SUSPECT_MS = 10_000;
+let lastTickAt = performance.now();
+let thawVerification: Promise<void> | null = null;
+
+function noteTick(): void {
+  const now = performance.now();
+  const gap = now - lastTickAt;
+  lastTickAt = now;
+  if (gap > FREEZE_SUSPECT_MS && currentLock && !fenced && !thawVerification) {
+    thawVerification = verifyLockStillHeld().finally(() => {
+      thawVerification = null;
+    });
+  }
+}
+setInterval(noteTick, 1000);
+
+// Bounded (see sqlite-lock-verify.ts): every op on the chain awaits this, and
+// a `locks.query()` that never answered stopped every reply to every client.
+function verifyLockStillHeld(): Promise<void> {
+  return verifyLockStillHeldBounded(
+    workerLocks() as any,
+    currentLock?.name,
+    (reason) => fence(reason),
+    undefined,
+    (msg) => console.warn(`[sqlite-worker] ${msg}`)
+  );
+}
+
+// ==================== db ops ====================
+
+async function open(
+  dbName: string,
+  useOpfs: boolean,
+  systemTables: readonly string[] = [],
+  workerLockName?: string,
+  openOptions?: OpenDbOptions
+): Promise<{ persisted: boolean; opfsError?: string }> {
+  if (workerLockName) {
+    const handle = await acquireWorkerLock(workerLockName);
+    if (!handle) throw new Error('worker-lock-unavailable');
+    releaseHeldLock();
+    currentLock = handle;
+  }
+  const sqlite3: any = await sqlite3InitModule();
+  // Retry/fallback policy (and the loud report when persistence is lost) lives
+  // in `sqlite-open.ts` so it can be unit tested off-worker.
+  const result = await openDb(sqlite3, dbName, useOpfs, openOptions ?? {});
+  db = result.db;
+  pool = result.pool ?? null;
+  // Physically create the internal `_00_*` tables the client reads before any
+  // write (DEFINE is a noop on this engine, so the migrator can't). Prevents
+  // "no such table: _00_query" on a fresh bucket right after signup.
+  for (const t of systemTables) {
+    db!.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+  }
+  // Retry (rather than instantly failing with SQLITE_BUSY=5) if a lock is held.
+  // Combined with the single-flight op chain, overlap is avoided.
+  // `cache_size` is negated → KiB (here 32 MiB) so SQLite's page cache can't
+  // grow unbounded and starve a wasm-heavy renderer.
+  try {
+    db!.exec({ sql: 'PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;' });
+  } catch {
+    /* pragma best-effort */
+  }
+  return { persisted: result.persisted, opfsError: result.opfsError };
+}
+
+function closeDb(): void {
+  db?.close();
+  db = null;
+  pool = null;
+  selectDb.knownTables.clear();
+  // The lock is scoped to (bucket, leadership); a same-worker bucket switch
+  // closes then reopens under a NEW name, so the old one must go now.
+  releaseHeldLock();
+}
+
+function exec(sql: string, bind?: unknown[]): unknown[] {
+  if (!db) throw new Error('sqlite: DB not open');
+  return db.exec({ sql, bind, rowMode: 'object', returnValue: 'resultRows' }) as unknown[];
+}
+
+function run(sql: string, bind?: unknown[]): void {
+  if (!db) throw new Error('sqlite: DB not open');
+  db.exec({ sql, bind });
+}
+
+function batch(stmts: Stmt[]): void {
+  if (!db) throw new Error('sqlite: DB not open');
+  db.exec({ sql: 'BEGIN' });
+  try {
+    for (const s of stmts) db.exec({ sql: s.sql, bind: s.bind });
+    db.exec({ sql: 'COMMIT' });
+  } catch (e) {
+    try {
+      db.exec({ sql: 'ROLLBACK' });
+    } catch {
+      /* ignore */
+    }
+    throw e;
+  }
+}
+
+// ==================== worker-side plan execution ('select') ====================
+
+/** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
+ *  plan executor). `knownTables` is cleared on open/close, which covers both
+ *  the solo fresh-worker path and the shared-mode same-worker bucket switch. */
+const selectDb: SelectDb = {
+  exec: (sql, bind) => exec(sql, bind) as { data: string }[],
+  run,
+  knownTables: new Set<string>(),
+};
+
+// ==================== dispatch ====================
+
+/** Follower client ports, keyed by the clientId the owner assigned. */
+const clients = new Map<string, MessagePort>();
+
+/** Data ops a follower client port may issue; lifecycle stays owner-only. */
+const CLIENT_OPS = new Set(['exec', 'run', 'batch', 'select']);
+
+/**
+ * ONE chain for every op from every channel. The handlers for `open` and
+ * `select` are async; without this, a follower's select could interleave with
+ * the owner's batch mid-transaction at the VFS layer. (Solo mode kept this
+ * invariant on the main thread via the engine's opQueue; with multiple client
+ * ports only the worker can.)
+ */
+let opChain: Promise<void> = Promise.resolve();
+
+async function handle(type: string, payload: any, source: 'owner' | 'client'): Promise<unknown> {
+  if (fenced) throw new Error('sqlite: fenced, leadership was taken over');
+  if (source === 'client' && !CLIENT_OPS.has(type)) {
+    throw new Error(`sqlite worker: op ${type} is not allowed on a client port`);
+  }
+  switch (type) {
+    case 'open':
+      selectDb.knownTables.clear();
+      {
+        const result = await open(
+          payload.dbName,
+          payload.useOpfs,
+          payload.systemTables,
+          payload.workerLockName,
+          payload.openOptions
+        );
+        // The freshly seeded system tables exist — record them so the select
+        // path doesn't redundantly re-issue CREATE TABLE for each.
+        for (const t of (payload.systemTables ?? []) as string[]) selectDb.knownTables.add(t);
+        return result;
+      }
+    case 'relock': {
+      // Same-leader re-promotion after a broker restart: the DB stays open,
+      // only the per-leadership lock name rolls forward. Acquire the new lock
+      // BEFORE releasing the old one so there is no unfenced window.
+      const handle = await acquireWorkerLock(payload.workerLockName);
+      if (!handle) throw new Error('worker-lock-unavailable');
+      releaseHeldLock();
+      currentLock = handle;
+      return {};
+    }
+    case 'select':
+      return executeSelect(payload.plan, payload.params ?? {}, selectDb);
+    case 'exec':
+      return { rows: exec(payload.sql, payload.bind) };
+    case 'run':
+      run(payload.sql, payload.bind);
+      return {};
+    case 'batch':
+      batch(payload as Stmt[]);
+      return {};
+    case 'close':
+      closeDb();
+      return {};
+    case 'shutdown':
+      // Graceful pagehide path: pausing the VFS releases the sync access
+      // handles NOW instead of whenever this worker gets garbage collected,
+      // so the next leader's open does not race the browser's GC.
+      try {
+        db?.close();
+      } catch {
+        /* ignore */
+      }
+      db = null;
+      try {
+        pool?.pauseVfs?.();
+      } catch {
+        /* ignore */
+      }
+      pool = null;
+      releaseHeldLock();
+      queueMicrotask(() => self.close());
+      return {};
+    case 'remove-client': {
+      const port = clients.get(payload.clientId);
+      port?.close();
+      clients.delete(payload.clientId);
+      return {};
+    }
+    default:
+      throw new Error(`sqlite worker: unknown message ${type}`);
+  }
+}
+
+function dispatch(target: PostTarget, data: any, source: 'owner' | 'client'): void {
+  const { id, type, payload } = data ?? {};
+  noteTick();
+  const t0 = performance.now();
+  const runOp = async () => {
+    try {
+      if (thawVerification) await thawVerification;
+      const result = await handle(type, payload, source);
+      // `wt` (worker time) lets the main thread split a round-trip into actual
+      // DB work vs postMessage/queue overhead (see `__sqliteStats`).
+      target.postMessage({ id, ok: true, wt: performance.now() - t0, ...(result as object) });
+    } catch (err) {
+      target.postMessage({ id, ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+  opChain = opChain.then(runOp, runOp);
+}
+
+self.onmessage = (ev: MessageEvent) => {
+  const data = ev.data ?? {};
+  // `add-client` is handled inline (not on the op chain): it only registers a
+  // port and must not wait behind a long select, or the follower's first ops
+  // (already queued on that port by the time the ack arrives) would deadlock
+  // the attach handshake in the engine.
+  if (data.type === 'add-client') {
+    const port = ev.ports?.[0];
+    const clientId = data.payload?.clientId as string | undefined;
+    if (!port || !clientId) {
+      (self as unknown as Worker).postMessage({
+        id: data.id,
+        ok: false,
+        error: 'sqlite worker: add-client needs a clientId and a transferred port',
+      });
+      return;
+    }
+    clients.get(clientId)?.close();
+    clients.set(clientId, port);
+    port.onmessage = (pe: MessageEvent) => dispatch(port, pe.data, 'client');
+    port.start?.();
+    (self as unknown as Worker).postMessage({ id: data.id, ok: true, wt: 0 });
+    return;
+  }
+  dispatch(self as unknown as Worker, data, 'owner');
+};