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

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

@@ -18,7 +18,15 @@ 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';
 
 /**
  * The statement result a pure-write op contributes to a query's results array.
@@ -82,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;
@@ -92,6 +100,9 @@ export class SqliteCacheEngine implements LocalStore {
    *  Flipped off at runtime if the worker script predates the `select` op
    *  (stale cached bundle) — degrade to the legacy multi-hop path, don't break. */
   private workerSelect: boolean;
+  /** What `workerSelect` was at construction, so DevTools can tell a runtime
+   *  downgrade (configured true, effective false) from a configured-off. */
+  private workerSelectConfigured: boolean;
   private events: DatabaseEventSystem = createDatabaseEventSystem();
   private bucketId = 'anon';
   /** Durability of the local store, set on every open. A plain Set of callbacks
@@ -102,13 +113,25 @@ export class SqliteCacheEngine implements LocalStore {
   /** Schemaless — tables are created lazily on first write; no migrator. */
   readonly usesSurqlSchema = false;
 
+  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 {
@@ -143,6 +166,51 @@ export class SqliteCacheEngine implements LocalStore {
     return this.config;
   }
 
+  /**
+   * Storage numbers for the DevTools Storage tab. Uses {@link call} so the
+   * reads serialize with regular traffic (no SQLITE_BUSY). Never throws — the
+   * worker may be mid bucket-switch; a failure lands in `error` instead.
+   */
+  async getStorageDiagnostics(opts?: { tableCounts?: boolean }): Promise<EngineStorageDiagnostics> {
+    const diag: EngineStorageDiagnostics = {
+      engine: 'sqlite',
+      bucketId: this.bucketId,
+      useOpfs: this.useOpfs,
+      workerSelectConfigured: this.workerSelectConfigured,
+      workerSelectEffective: this.workerSelect,
+    };
+    try {
+      const { rows } = await this.call<{ rows: { bytes: number; freelist: number }[] }>('exec', {
+        sql:
+          'SELECT (SELECT * FROM pragma_page_count()) * (SELECT * FROM pragma_page_size()) AS bytes, ' +
+          '(SELECT * FROM pragma_freelist_count()) * (SELECT * FROM pragma_page_size()) AS freelist',
+      });
+      diag.dbSizeBytes = rows?.[0]?.bytes;
+      diag.freelistBytes = rows?.[0]?.freelist;
+      if (opts?.tableCounts) {
+        const { rows: tables } = await this.call<{ rows: { name: string }[] }>('exec', {
+          sql: "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+        });
+        const names = (tables ?? []).map((r) => r.name);
+        if (names.length) {
+          // Names come from sqlite_master itself; double-quoting is enough.
+          const sql = names
+            .map((n) => `SELECT '${n.replace(/'/g, "''")}' AS t, COUNT(*) AS n FROM "${n.replace(/"/g, '""')}"`)
+            .join(' UNION ALL ');
+          const { rows: counts } = await this.call<{ rows: { t: string; n: number }[] }>('exec', {
+            sql,
+          });
+          diag.tableCounts = (counts ?? []).map((r) => ({ table: r.t, rows: r.n }));
+        } else {
+          diag.tableCounts = [];
+        }
+      }
+    } catch (e) {
+      diag.error = e instanceof Error ? e.message : String(e);
+    }
+    return diag;
+  }
+
   getEvents(): DatabaseEventSystem {
     return this.events;
   }
@@ -163,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);
@@ -218,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++;
@@ -230,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;
+      }
+    );
   }
 
   /**
@@ -261,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
@@ -281,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);
@@ -290,14 +348,19 @@ export class SqliteCacheEngine implements LocalStore {
     // (the worker also console.errors, since host apps may run pino at `fatal`)
     // and publish it so the app can warn the user.
     const fellBack = this.useOpfs && !persisted;
-    this.setStorageHealth({
+    // Omit `error` rather than setting it to `undefined`: the devtools
+    // serializer renders an undefined value as the STRING 'undefined'.
+    const health: StorageHealth = {
       status: persisted ? 'persistent' : 'memory',
       fallback: fellBack,
-      error: fellBack ? opfsError : undefined,
-    });
+    };
+    if (fellBack && opfsError) health.error = opfsError;
+    if (this.shared) health.role = this.roleLabel;
+    this.setStorageHealth(health);
     const stats = getStats();
     stats.persisted = persisted;
-    stats.opfsError = fellBack ? opfsError : undefined;
+    if (fellBack && opfsError) stats.opfsError = opfsError;
+    else delete stats.opfsError;
     if (fellBack) {
       this.logger.error(
         { bucketId, opfsError, Category: 'sp00ky-client::SqliteCacheEngine::connect' },
@@ -337,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> {
@@ -799,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);
 }