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

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

@@ -8,7 +8,7 @@ import {
   project,
 } from './sqlite-plan-sql';
 import type { Logger } from '../logger/index';
-import type { Sp00kyConfig } from '../../types';
+import type { Sp00kyConfig, StorageHealth } from '../../types';
 import type { SealedQuery } from '../../utils/surql';
 import { resolveRelations, stableKey } from './relation-resolver';
 import {
@@ -19,6 +19,7 @@ import {
 import { StaleEpochError } from './local';
 import { translateSurql, tableOf, setPath, getPath, type SqlOp } from './surql-translate';
 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.
@@ -92,11 +93,21 @@ 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
+   *  rather than a `DatabaseEventSystem` event: this changes at most once per
+   *  open, and the typed event map is about query traffic. */
+  private storageHealthValue: StorageHealth = { status: 'unknown', fallback: false };
+  private storageHealthSubs = new Set<(health: StorageHealth) => void>();
   /** Schemaless — tables are created lazily on first write; no migrator. */
   readonly usesSurqlSchema = false;
 
+  readonly engineKind = 'sqlite' as const;
+
   constructor(
     private config: Sp00kyConfig<any>['database'],
     private logger: Logger,
@@ -104,6 +115,7 @@ export class SqliteCacheEngine implements LocalStore {
   ) {
     this.useOpfs = opts.useOpfs ?? true;
     this.workerSelect = opts.workerSelect ?? config.workerSelect ?? true;
+    this.workerSelectConfigured = this.workerSelect;
   }
 
   get epoch(): number {
@@ -114,10 +126,75 @@ export class SqliteCacheEngine implements LocalStore {
     return this.bucketId;
   }
 
+  get storageHealth(): StorageHealth {
+    return this.storageHealthValue;
+  }
+
+  /** Fires immediately with the current snapshot (the store opens during
+   *  `connect()`, before app components mount, so a late subscriber must still
+   *  learn a fallback happened), then on every change. */
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    cb(this.storageHealthValue);
+    this.storageHealthSubs.add(cb);
+    return () => {
+      this.storageHealthSubs.delete(cb);
+    };
+  }
+
+  private setStorageHealth(health: StorageHealth): void {
+    this.storageHealthValue = health;
+    for (const cb of this.storageHealthSubs) cb(health);
+  }
+
   getConfig(): Sp00kyConfig<any>['database'] {
     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;
   }
@@ -247,7 +324,12 @@ export class SqliteCacheEngine implements LocalStore {
     // "no such table: _00_query" and the client wedged on "Loading database".
     // Creating them inside `open` guarantees any access order is safe without
     // adding ops to the engine's queue.
-    const { persisted } = await this.rawCall<{ persisted: boolean }>('open', {
+    // `opfsError` is absent from a worker bundle older than this field, which
+    // just reads as "no reason given" rather than breaking the open.
+    const { persisted, opfsError } = await this.rawCall<{
+      persisted: boolean;
+      opfsError?: string;
+    }>('open', {
       dbName: bucketId,
       useOpfs: this.useOpfs,
       systemTables: SYSTEM_TABLES,
@@ -255,10 +337,34 @@ export class SqliteCacheEngine implements LocalStore {
     this.knownTables.clear();
     for (const t of SYSTEM_TABLES) this.knownTables.add(t);
     this.bucketId = bucketId;
-    this.logger.info(
-      { bucketId, persisted, Category: 'sp00ky-client::SqliteCacheEngine::connect' },
-      persisted ? 'SQLite OPFS store opened' : 'SQLite in-memory store opened (no OPFS)'
-    );
+    // Durability was requested but could not be had: the store is in RAM, so it
+    // loses local writes on reload and can OOM a wasm-heavy renderer. Report it
+    // (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;
+    // 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,
+    };
+    if (fellBack && opfsError) health.error = opfsError;
+    this.setStorageHealth(health);
+    const stats = getStats();
+    stats.persisted = persisted;
+    if (fellBack && opfsError) stats.opfsError = opfsError;
+    else delete stats.opfsError;
+    if (fellBack) {
+      this.logger.error(
+        { bucketId, opfsError, Category: 'sp00ky-client::SqliteCacheEngine::connect' },
+        'SQLite OPFS persistence failed; store is IN MEMORY and will not survive reload'
+      );
+    } else {
+      this.logger.info(
+        { bucketId, persisted, Category: 'sp00ky-client::SqliteCacheEngine::connect' },
+        persisted ? 'SQLite OPFS store opened' : 'SQLite in-memory store opened (as configured)'
+      );
+    }
   }
 
   /** Enqueue `fn` as a single serialized opQueue entry (mirrors {@link call}'s
@@ -743,6 +849,12 @@ interface SqliteStats {
   bytesParsed: number;
   /** Relation-resolver fan-out fetches (one worker round-trip each). */
   relationFetches: number;
+  /** Whether the open store is OPFS-backed. `false` here with an `opfsError`
+   *  means the whole dataset is sitting in RAM. Optional so it stays absent
+   *  until the first open (and is skipped by the backfill loop below). */
+  persisted?: boolean;
+  /** Why OPFS persistence failed, when it did. */
+  opfsError?: string;
 }
 
 const EMPTY_STATS: SqliteStats = {

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

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { openDb } from './sqlite-open';
+
+class FakeDb {
+  constructor(public arg: unknown) {}
+  exec() {
+    return [];
+  }
+  close() {}
+}
+
+/** Minimal stand-in for the initialized sqlite-wasm module. `install` is the
+ *  `installOpfsSAHPoolVfs` behavior under test; omit it to model a build that
+ *  lacks the SAHPool VFS entirely. */
+function makeSqlite3(install?: (opts: any) => Promise<unknown>) {
+  const sqlite3: any = { oo1: { DB: FakeDb } };
+  if (install) sqlite3.installOpfsSAHPoolVfs = vi.fn(install);
+  return sqlite3;
+}
+
+const pool = { OpfsSAHPoolDb: FakeDb };
+/** What a pool locked by another tab of the app actually throws. */
+function lockedError(): Error {
+  const e = new Error('Access Handles cannot be acquired');
+  e.name = 'NoModificationAllowedError';
+  return e;
+}
+
+const noSleep = () => Promise.resolve();
+
+let errSpy: ReturnType<typeof vi.spyOn>;
+beforeEach(() => {
+  errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+afterEach(() => {
+  errSpy.mockRestore();
+});
+
+// The bare `catch {}` this replaces turned every OPFS failure into a silent
+// full-RAM database: no log, no reason, no way for the app to know its writes
+// die on reload. Each case below pins one half of the fix: keep trying when
+// retrying can plausibly work, and when it can't, say so loudly and hand the
+// reason back.
+describe('openDb', () => {
+  it('opens the OPFS pool on the first attempt', async () => {
+    const sqlite3 = makeSqlite3(async () => pool);
+    const res = await openDb(sqlite3, 'user:abc', true, { sleep: noSleep });
+
+    expect(res.persisted).toBe(true);
+    expect(res.opfsError).toBeUndefined();
+    expect(sqlite3.installOpfsSAHPoolVfs).toHaveBeenCalledTimes(1);
+    // The pool is named per bucket, and the first try must NOT force a re-init
+    // (that would throw away a pool another attempt is legitimately using).
+    expect(sqlite3.installOpfsSAHPoolVfs.mock.calls[0][0]).toEqual({ name: 'sp00ky-user:abc' });
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  // The tab-closing race: the old tab still holds the sync access handles when
+  // the new one boots. Without a retry that tab is stuck in RAM for its whole
+  // lifetime, even though the lock frees milliseconds later.
+  it('retries a locked pool and succeeds, forcing re-init after the first failure', async () => {
+    let calls = 0;
+    const sqlite3 = makeSqlite3(async () => {
+      if (++calls < 3) throw lockedError();
+      return pool;
+    });
+    const res = await openDb(sqlite3, 'main', true, { sleep: noSleep });
+
+    expect(res.persisted).toBe(true);
+    expect(res.opfsError).toBeUndefined();
+    expect(sqlite3.installOpfsSAHPoolVfs).toHaveBeenCalledTimes(3);
+    // sqlite-wasm caches the first rejection against the VFS name, so retries
+    // that don't ask for a real re-init just replay it.
+    const [first, second, third] = sqlite3.installOpfsSAHPoolVfs.mock.calls.map((c: any[]) => c[0]);
+    expect(first.forceReinitIfPreviouslyFailed).toBeUndefined();
+    expect(second.forceReinitIfPreviouslyFailed).toBe(true);
+    expect(third.forceReinitIfPreviouslyFailed).toBe(true);
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it('falls back loudly after exhausting the retries, keeping the reason', async () => {
+    const sqlite3 = makeSqlite3(async () => {
+      throw lockedError();
+    });
+    const res = await openDb(sqlite3, 'main', true, { sleep: noSleep });
+
+    expect(res.persisted).toBe(false);
+    // The DOMException name is the diagnostic part: it names the lock.
+    expect(res.opfsError).toContain('NoModificationAllowedError');
+    expect(sqlite3.installOpfsSAHPoolVfs).toHaveBeenCalledTimes(3);
+    expect(errSpy).toHaveBeenCalledTimes(1);
+    expect(String(errSpy.mock.calls[0][0])).toContain('IN MEMORY');
+    // Still a usable handle: losing durability must not break the app.
+    expect(res.db).toBeDefined();
+  });
+
+  // An insecure context has no sync access handles at all, so retrying just
+  // adds boot latency to a foregone conclusion.
+  it('does not retry when the OPFS APIs are missing entirely', async () => {
+    const sqlite3 = makeSqlite3(async () => {
+      throw new Error('Missing required OPFS APIs.');
+    });
+    const res = await openDb(sqlite3, 'main', true, { sleep: noSleep });
+
+    expect(res.persisted).toBe(false);
+    expect(res.opfsError).toContain('Missing required OPFS APIs');
+    expect(sqlite3.installOpfsSAHPoolVfs).toHaveBeenCalledTimes(1);
+    expect(errSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports a build without the SAHPool VFS without calling anything', async () => {
+    const sqlite3 = makeSqlite3();
+    const res = await openDb(sqlite3, 'main', true, { sleep: noSleep });
+
+    expect(res.persisted).toBe(false);
+    expect(res.opfsError).toContain('installOpfsSAHPoolVfs');
+    expect(errSpy).toHaveBeenCalledTimes(1);
+  });
+
+  // `store: 'memory'` is a configuration choice, not a degradation, so it must
+  // stay silent and carry no error for the UI to warn about.
+  it('opens in memory quietly when persistence was not requested', async () => {
+    const sqlite3 = makeSqlite3(async () => pool);
+    const res = await openDb(sqlite3, 'main', false, { sleep: noSleep });
+
+    expect(res.persisted).toBe(false);
+    expect(res.opfsError).toBeUndefined();
+    expect(sqlite3.installOpfsSAHPoolVfs).not.toHaveBeenCalled();
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it('honors maxAttempts and waits the configured backoff between tries', async () => {
+    const slept: number[] = [];
+    const sqlite3 = makeSqlite3(async () => {
+      throw lockedError();
+    });
+    const res = await openDb(sqlite3, 'main', true, {
+      maxAttempts: 4,
+      backoffMs: [10, 20],
+      sleep: async (ms) => {
+        slept.push(ms);
+      },
+    });
+
+    expect(res.persisted).toBe(false);
+    expect(sqlite3.installOpfsSAHPoolVfs).toHaveBeenCalledTimes(4);
+    // One sleep per gap (never after the last attempt), last delay repeating.
+    expect(slept).toEqual([10, 20, 20]);
+  });
+});

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

@@ -0,0 +1,129 @@
+/**
+ * Opening the worker's SQLite handle: the OPFS SAHPool VFS when durable
+ * storage was asked for, an in-memory DB only as a last resort. Extracted from
+ * `sqlite-worker.ts` (which imports the wasm module at module scope and so
+ * can't be loaded in a unit test) to keep the retry/fallback policy testable
+ * off-worker, the same split as `sqlite-select.ts`.
+ *
+ * Why retry: SAHPool holds an EXCLUSIVE sync access handle on every file in
+ * its pool, so only one client per pool name can have it open. A second tab of
+ * the same app therefore fails init, and `installOpfsSAHPoolVfs` CACHES that
+ * rejection per VFS name, so a later call only gets a real second chance when
+ * it passes `forceReinitIfPreviouslyFailed`. Retrying with that flag turns the
+ * common "the other tab is still closing" race into a success instead of a
+ * permanent in-memory session.
+ *
+ * Why the noise: `:memory:` holds the whole dataset in RAM (the
+ * OOM-on-wasm-heavy-pages failure mode the OPFS store exists to avoid) and
+ * drops every local write on reload. Host apps run pino at their own level,
+ * some at `fatal`, so the fallback ALSO writes to `console.error` from inside
+ * the worker, and the reason travels back to the engine as `opfsError` for the
+ * app to surface.
+ */
+
+/** The DB surface the worker uses (a `sqlite3.oo1.DB` or an `OpfsSAHPoolDb`). */
+export interface SqliteDbHandle {
+  exec: (opts: { sql: string; bind?: unknown[]; rowMode?: string; returnValue?: string }) => unknown;
+  close: () => void;
+}
+
+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;
+}
+
+export interface OpenDbOptions {
+  /** Total OPFS init attempts, including the first. Default 3. */
+  maxAttempts?: number;
+  /** Delay before each retry; the last entry repeats. Default [250, 500]. */
+  backoffMs?: number[];
+  /** Injectable for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Bounded on purpose: this runs on the boot path, before the first query. */
+const DEFAULT_BACKOFF_MS = [250, 500];
+
+/** 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'];
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** Keep the DOMException name (e.g. `NoModificationAllowedError` for a pool
+ *  locked by another tab): it is the most diagnostic part of the failure. */
+function errMessage(e: unknown): string {
+  if (e instanceof Error) return e.name && e.name !== 'Error' ? `${e.name}: ${e.message}` : e.message;
+  return String(e);
+}
+
+function fallbackToMemory(
+  sqlite3: any,
+  dbName: string,
+  reason: string,
+  attempts: number
+): OpenDbResult {
+  const tried = attempts > 0 ? ` after ${attempts} attempt${attempts === 1 ? '' : 's'}` : '';
+  // Deliberately console, not the logger: host apps configure pino's level (some
+  // run `fatal`), and losing durability must never be filtered into silence.
+  // oxlint-disable-next-line no-console
+  console.error(
+    `[sp00ky] OPFS persistence unavailable for "${dbName}"${tried}: ${reason}. The local SQLite ` +
+      'cache is running IN MEMORY, which keeps the whole dataset in RAM and loses every local ' +
+      'write on reload. The usual cause is another tab of this app holding the storage lock, so ' +
+      'closing the other tabs and reloading restores persistence.'
+  );
+  return { db: new sqlite3.oo1.DB(':memory:', 'c'), persisted: false, opfsError: reason };
+}
+
+/**
+ * Open `dbName`'s handle. Never throws for a storage problem: a caller that
+ * asked for persistence and can't have it gets a working in-memory handle plus
+ * `persisted: false` and an `opfsError` to report.
+ */
+export async function openDb(
+  sqlite3: any,
+  dbName: string,
+  useOpfs: boolean,
+  opts: OpenDbOptions = {}
+): Promise<OpenDbResult> {
+  // Memory was the configured choice (`store: 'memory'`), not a failure, so no
+  // error and no noise.
+  if (!useOpfs) return { db: new sqlite3.oo1.DB(':memory:', 'c'), persisted: false };
+
+  if (!sqlite3.installOpfsSAHPoolVfs) {
+    return fallbackToMemory(sqlite3, dbName, 'sqlite-wasm build has no installOpfsSAHPoolVfs', 0);
+  }
+
+  const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+  const backoffMs = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+  const sleep = opts.sleep ?? defaultSleep;
+
+  let lastError = 'unknown error';
+  let attempts = 0;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    attempts = attempt;
+    try {
+      // `initialCapacity` stays at the sqlite-wasm default (6 files): one pool
+      // per bucket holds a single DB plus its journals, so preallocating more
+      // OPFS files would only be waste. A "SAH pool is full" error still
+      // reaches the caller verbatim via `opfsError`.
+      const pool = await sqlite3.installOpfsSAHPoolVfs({
+        name: `sp00ky-${dbName}`,
+        // The first failure is cached against the VFS name, so a retry that
+        // 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 };
+    } 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);
+    }
+  }
+  return fallbackToMemory(sqlite3, dbName, lastError, attempts);
+}

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

@@ -5,11 +5,12 @@
  * 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. Falls back
- * to an in-memory DB when OPFS is unavailable.
+ * 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`):
- *   { id, type: 'open',   payload: { dbName, useOpfs } }
+ *   { id, type: 'open',   payload: { dbName, useOpfs } } -> { 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)
@@ -22,6 +23,7 @@
  * hot path; the per-statement ops remain for the write/shim paths.
  */
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { openDb, type SqliteDbHandle } from './sqlite-open';
 import { executeSelect, type SelectDb } from './sqlite-select';
 
 interface Stmt {
@@ -29,28 +31,18 @@ interface Stmt {
   bind?: unknown[];
 }
 
-let db: {
-  exec: (opts: { sql: string; bind?: unknown[]; rowMode?: string; returnValue?: string }) => unknown;
-  close: () => void;
-} | null = null;
+let db: SqliteDbHandle | null = null;
 
 async function open(
   dbName: string,
   useOpfs: boolean,
   systemTables: readonly string[] = []
-): Promise<{ persisted: boolean }> {
+): Promise<{ persisted: boolean; opfsError?: string }> {
   const sqlite3: any = await sqlite3InitModule();
-  let persisted = false;
-  if (useOpfs && sqlite3.installOpfsSAHPoolVfs) {
-    try {
-      const pool = await sqlite3.installOpfsSAHPoolVfs({ name: `sp00ky-${dbName}` });
-      db = new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`);
-      persisted = true;
-    } catch {
-      // fall through to in-memory
-    }
-  }
-  if (!db) db = new sqlite3.oo1.DB(':memory:', 'c');
+  // 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 { db: handle, persisted, opfsError } = await openDb(sqlite3, dbName, useOpfs);
+  db = handle;
   // 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.
@@ -66,7 +58,7 @@ async function open(
   } catch {
     /* pragma best-effort */
   }
-  return { persisted };
+  return { persisted, opfsError };
 }
 
 function exec(sql: string, bind?: unknown[]): unknown[] {

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

@@ -31,6 +31,8 @@ export class SurrealCacheEngine extends LocalDatabaseService implements LocalCac
   /** SurrealDB needs its SurrealQL schema provisioned locally. */
   readonly usesSurqlSchema = true;
 
+  readonly engineKind = 'surrealdb' as const;
+
   /** {@link LocalCacheEngine} alias for {@link LocalDatabaseService.switchStore}. */
   switchBucket(bucketId: string): Promise<void> {
     return this.switchStore(bucketId);

package/src/sp00ky.ts

@@ -8,7 +8,8 @@ import type {
   PreloadOptions,
   UpdateOptions,
   RunOptions,
-  SyncHealth} from './types';
+  SyncHealth,
+  StorageHealth} from './types';
 import {
   LocalMigrator,
   RemoteDatabaseService,
@@ -106,6 +107,13 @@ export class BucketHandle {
  */
 const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
 
+/** Reported for engines that don't track local-store durability. Frozen so a
+ *  subscriber can't mutate the shared snapshot. */
+const UNKNOWN_STORAGE_HEALTH: StorageHealth = Object.freeze({
+  status: 'unknown',
+  fallback: false,
+});
+
 function readBootBucketHint(): string | null {
   try {
     return typeof localStorage !== 'undefined' ? localStorage.getItem(LAST_BUCKET_KEY) : null;
@@ -188,6 +196,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.sync.subscribeToSyncHealth(cb);
   }
 
+  /** Durability of the local cache. See {@link StorageHealth}. `'unknown'` for
+   *  engines that don't report it. */
+  get storageHealth(): StorageHealth {
+    return this.local.storageHealth ?? UNKNOWN_STORAGE_HEALTH;
+  }
+
+  /**
+   * Observe local-store durability. Fires immediately with the current snapshot
+   * and again on every change (at most once per bucket open in practice).
+   * Returns an unsubscribe.
+   */
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    if (this.local.subscribeToStorageHealth) {
+      return this.local.subscribeToStorageHealth(cb);
+    }
+    cb(UNKNOWN_STORAGE_HEALTH);
+    return () => {};
+  }
+
   constructor(private config: Sp00kyConfig<S>) {
     const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit);
     this.logger = logger.child({ service: 'Sp00kyClient' });

package/src/types.ts

@@ -247,6 +247,33 @@ export interface SyncHealth {
   everConnected: boolean;
 }
 
+export type StorageHealthStatus = 'unknown' | 'persistent' | 'memory';
+
+/**
+ * Durability of the LOCAL cache, delivered to `subscribeToStorageHealth`
+ * subscribers. Separate from {@link SyncHealth}: that one is about reaching the
+ * server, this one is about whether the local store survives a reload.
+ *
+ * Under `localEngine: 'sqlite'` the durable store is the OPFS SAHPool VFS,
+ * which only one client per bucket can hold open. When it can't be opened (a
+ * second tab of the app already has it, an insecure context, a full pool) the
+ * engine keeps working against an in-memory DB, which holds the whole dataset
+ * in RAM and loses local writes on reload. `fallback` marks exactly that case,
+ * so a UI can warn about it.
+ */
+export interface StorageHealth {
+  /** `'unknown'` until the local cache has opened, or for engines that don't report. */
+  status: StorageHealthStatus;
+  /**
+   * `true` only when durable storage was REQUESTED and could not be opened.
+   * Stays `false` for a configured-in-memory store (`store: 'memory'`), which
+   * is a choice rather than a failure, so a UI can key off this alone.
+   */
+  fallback: boolean;
+  /** Reason durable storage failed (only set while `fallback` is `true`). */
+  error?: string;
+}
+
 export type QueryHash = string;
 
 // Flat array format: [[record-id, version], [record-id, version], ...]