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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as SyncHealth, B as Logger$1, C as RecordVersionDiff, D as Sp00kyQueryResult, E as Sp00kyConfig, F as UpEvent, H as EventDefinition, I as LocalStore, L as SealedQuery, M as SyncHealthStatus, N as TimingPhase, O as Sp00kyQueryResultPromise, P as UpdateOptions, R as DatabaseEventSystem, S as RecordVersionArray, T as RunOptions, U as EventSystem, V as SyncEventSystem, _ as QueryStatus, a as MutationCallback, b as QueryTimings, c as PersistenceClient, d as PreloadOptions, f as PreloadRefresh, g as QueryState, h as QueryHash, i as MATERIALIZATION_SAMPLE_WINDOW, j as SyncHealthConfig, k as StoreType, l as PhaseStat, m as QueryConfigRecord, n as EventSubscriptionOptions, o as MutationEvent, p as QueryConfig, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryStatusCallback, w as RegistrationTimings, x as QueryUpdateCallback, y as QueryTimeToLive, z as DatabaseEventTypes } from "./types.js";
+import { A as StorageHealthStatus, B as DatabaseEventSystem, C as RecordVersionDiff, D as Sp00kyQueryResult, E as Sp00kyConfig, F as TimingPhase, G as EventSystem, H as Logger$1, I as UpdateOptions, L as UpEvent, M as SyncHealth, N as SyncHealthConfig, O as Sp00kyQueryResultPromise, P as SyncHealthStatus, R as LocalStore, S as RecordVersionArray, T as RunOptions, U as SyncEventSystem, V as DatabaseEventTypes, W as EventDefinition, _ as QueryStatus, a as MutationCallback, b as QueryTimings, c as PersistenceClient, d as PreloadOptions, f as PreloadRefresh, g as QueryState, h as QueryHash, i as MATERIALIZATION_SAMPLE_WINDOW, j as StoreType, k as StorageHealth, l as PhaseStat, m as QueryConfigRecord, n as EventSubscriptionOptions, o as MutationEvent, p as QueryConfig, r as Level, s as MutationEventType, t as DebounceOptions, u as PinoTransmit, v as QueryStatusCallback, w as RegistrationTimings, x as QueryUpdateCallback, y as QueryTimeToLive, z as SealedQuery } from "./types.js";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
@@ -1265,6 +1265,15 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * on every healthy↔degraded transition. Returns an unsubscribe.
    */
   subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void;
+  /** Durability of the local cache. See {@link StorageHealth}. `'unknown'` for
+   *  engines that don't report it. */
+  get storageHealth(): StorageHealth;
+  /**
+   * 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;
   constructor(config: Sp00kyConfig<S>);
   /**
    * Setup direct callbacks instead of event subscriptions
@@ -1428,4 +1437,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };

package/dist/index.js

@@ -1511,6 +1511,14 @@ var SqliteCacheEngine = class {
 	workerSelect;
 	events = createDatabaseEventSystem();
 	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. */
+	storageHealthValue = {
+		status: "unknown",
+		fallback: false
+	};
+	storageHealthSubs = /* @__PURE__ */ new Set();
 	/** Schemaless — tables are created lazily on first write; no migrator. */
 	usesSurqlSchema = false;
 	constructor(config, logger, opts = {}) {
@@ -1525,6 +1533,23 @@ var SqliteCacheEngine = class {
 	get currentBucketId() {
 		return this.bucketId;
 	}
+	get 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) {
+		cb(this.storageHealthValue);
+		this.storageHealthSubs.add(cb);
+		return () => {
+			this.storageHealthSubs.delete(cb);
+		};
+	}
+	setStorageHealth(health) {
+		this.storageHealthValue = health;
+		for (const cb of this.storageHealthSubs) cb(health);
+	}
 	getConfig() {
 		return this.config;
 	}
@@ -1625,7 +1650,7 @@ var SqliteCacheEngine = class {
 	*/
 	async openInternal(bucketId) {
 		this.worker = this.spawnWorker();
-		const { persisted } = await this.rawCall("open", {
+		const { persisted, opfsError } = await this.rawCall("open", {
 			dbName: bucketId,
 			useOpfs: this.useOpfs,
 			systemTables: SYSTEM_TABLES
@@ -1633,11 +1658,25 @@ var SqliteCacheEngine = class {
 		this.knownTables.clear();
 		for (const t of SYSTEM_TABLES) this.knownTables.add(t);
 		this.bucketId = bucketId;
-		this.logger.info({
+		const fellBack = this.useOpfs && !persisted;
+		this.setStorageHealth({
+			status: persisted ? "persistent" : "memory",
+			fallback: fellBack,
+			error: fellBack ? opfsError : void 0
+		});
+		const stats = getStats();
+		stats.persisted = persisted;
+		stats.opfsError = fellBack ? opfsError : void 0;
+		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 (no OPFS)");
+		}, persisted ? "SQLite OPFS store opened" : "SQLite in-memory store opened (as configured)");
 	}
 	/** Enqueue `fn` as a single serialized opQueue entry (mirrors {@link call}'s
 	*  chaining) so it can't interleave with reads/writes at the worker. */
@@ -5051,8 +5090,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.151";
-const WASM_VERSION = "0.0.1-canary.151";
+const CORE_VERSION = "0.0.1-canary.153";
+const WASM_VERSION = "0.0.1-canary.153";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5083,6 +5122,7 @@ var DevToolsService = class {
 			if (this.authService.isAuthenticated && this.backendInfo.versions.ssp === UNAVAILABLE) this.refreshBackendVersions();
 			else this.notifyDevTools();
 		});
+		this.databaseService.subscribeToStorageHealth?.(() => this.notifyDevTools());
 		this.refreshBackendVersions();
 		this.logger.debug({ Category: "sp00ky-client::DevToolsService::init" }, "Service initialized");
 	}
@@ -5248,7 +5288,11 @@ var DevToolsService = class {
 			},
 			database: {
 				tables: this.localTables.length ? this.localTables : this.schema.tables.map((t) => t.name),
-				tableData: {}
+				tableData: {},
+				storage: this.databaseService.storageHealth ?? {
+					status: "unknown",
+					fallback: false
+				}
 			}
 		});
 	}
@@ -7159,6 +7203,12 @@ var BucketHandle = class {
 * callback switches to the user's bucket (cache + outbox intact).
 */
 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 = Object.freeze({
+	status: "unknown",
+	fallback: false
+});
 function readBootBucketHint() {
 	try {
 		return typeof localStorage !== "undefined" ? localStorage.getItem(LAST_BUCKET_KEY) : null;
@@ -7219,6 +7269,21 @@ var Sp00kyClient = class {
 	subscribeToSyncHealth(cb) {
 		return this.sync.subscribeToSyncHealth(cb);
 	}
+	/** Durability of the local cache. See {@link StorageHealth}. `'unknown'` for
+	*  engines that don't report it. */
+	get 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) {
+		if (this.local.subscribeToStorageHealth) return this.local.subscribeToStorageHealth(cb);
+		cb(UNKNOWN_STORAGE_HEALTH);
+		return () => {};
+	}
 	constructor(config) {
 		this.config = config;
 		const logger = createLogger(config.logLevel ?? "info", config.otelTransmit);

package/dist/sqlite-worker.js

@@ -1,6 +1,65 @@
 import { i as reviveRow, n as renderOrderSql, o as resolveRelations, r as renderWhereSql, s as stableKey, t as project } from "./sqlite-plan-sql.js";
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 
+//#region src/services/database/sqlite-open.ts
+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) => new Promise((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) {
+	if (e instanceof Error) return e.name && e.name !== "Error" ? `${e.name}: ${e.message}` : e.message;
+	return String(e);
+}
+function fallbackToMemory(sqlite3, dbName, reason, attempts) {
+	const tried = attempts > 0 ? ` after ${attempts} attempt${attempts === 1 ? "" : "s"}` : "";
+	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.
+*/
+async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
+	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 {
+			return {
+				db: new (await (sqlite3.installOpfsSAHPoolVfs({
+					name: `sp00ky-${dbName}`,
+					...attempt > 1 ? { forceReinitIfPreviouslyFailed: true } : {}
+				}))).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);
+}
+
+//#endregion
 //#region src/services/database/sqlite-select.ts
 function ensureTable(db, table) {
 	if (db.knownTables.has(table)) return;
@@ -79,11 +138,12 @@ async function executeSelect(plan, params, db) {
 * 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)
@@ -97,18 +157,16 @@ async function executeSelect(plan, params, db) {
 */
 let db = null;
 async function open(dbName, useOpfs, systemTables = []) {
-	const sqlite3 = await sqlite3InitModule();
-	let persisted = false;
-	if (useOpfs && sqlite3.installOpfsSAHPoolVfs) try {
-		db = new (await (sqlite3.installOpfsSAHPoolVfs({ name: `sp00ky-${dbName}` }))).OpfsSAHPoolDb(`/${dbName}.sqlite3`);
-		persisted = true;
-	} catch {}
-	if (!db) db = new sqlite3.oo1.DB(":memory:", "c");
+	const { db: handle, persisted, opfsError } = await openDb(await sqlite3InitModule(), dbName, useOpfs);
+	db = handle;
 	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
 	try {
 		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
 	} catch {}
-	return { persisted };
+	return {
+		persisted,
+		opfsError
+	};
 }
 function exec(sql, bind) {
 	if (!db) throw new Error("sqlite: DB not open");

package/dist/types.d.ts

@@ -288,6 +288,15 @@ interface LocalStore extends LocalCacheEngine {
   getClient(): unknown;
   getConfig(): Sp00kyConfig<any>['database'];
   readonly currentBucketId: string;
+  /**
+   * Durability of this engine's local store. OPTIONAL: engines that don't
+   * report it (SurrealDB, custom engines) are treated as `'unknown'` by the
+   * client facade, so adding this needs no change on their side.
+   */
+  readonly storageHealth?: StorageHealth;
+  /** Fires immediately with the current snapshot, then on every change.
+   *  Returns an unsubscribe function. */
+  subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
 }
 /** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
 type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
@@ -530,6 +539,31 @@ interface SyncHealth {
    */
   everConnected: boolean;
 }
+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.
+ */
+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;
+}
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;
 /**
@@ -752,4 +786,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { SyncHealth as A, Logger$1 as B, RecordVersionDiff as C, Sp00kyQueryResult as D, Sp00kyConfig as E, UpEvent as F, EventDefinition as H, LocalStore as I, SealedQuery as L, SyncHealthStatus as M, TimingPhase as N, Sp00kyQueryResultPromise as O, UpdateOptions as P, DatabaseEventSystem as R, RecordVersionArray as S, RunOptions as T, EventSystem as U, SyncEventSystem as V, QueryStatus as _, MutationCallback as a, QueryTimings as b, PersistenceClient as c, PreloadOptions as d, PreloadRefresh as f, QueryState as g, QueryHash as h, MATERIALIZATION_SAMPLE_WINDOW as i, SyncHealthConfig as j, StoreType as k, PhaseStat as l, QueryConfigRecord as m, EventSubscriptionOptions as n, MutationEvent as o, QueryConfig as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryStatusCallback as v, RegistrationTimings as w, QueryUpdateCallback as x, QueryTimeToLive as y, DatabaseEventTypes as z };
+export { StorageHealthStatus as A, DatabaseEventSystem as B, RecordVersionDiff as C, Sp00kyQueryResult as D, Sp00kyConfig as E, TimingPhase as F, EventSystem as G, Logger$1 as H, UpdateOptions as I, UpEvent as L, SyncHealth as M, SyncHealthConfig as N, Sp00kyQueryResultPromise as O, SyncHealthStatus as P, LocalStore as R, RecordVersionArray as S, RunOptions as T, SyncEventSystem as U, DatabaseEventTypes as V, EventDefinition as W, QueryStatus as _, MutationCallback as a, QueryTimings as b, PersistenceClient as c, PreloadOptions as d, PreloadRefresh as f, QueryState as g, QueryHash as h, MATERIALIZATION_SAMPLE_WINDOW as i, StoreType as j, StorageHealth as k, PhaseStat as l, QueryConfigRecord as m, EventSubscriptionOptions as n, MutationEvent as o, QueryConfig as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryStatusCallback as v, RegistrationTimings as w, QueryUpdateCallback as x, QueryTimeToLive as y, SealedQuery as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.151",
+  "version": "0.0.1-canary.153",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.151",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.151",
+    "@spooky-sync/query-builder": "0.0.1-canary.153",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.153",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/devtools/index.ts

@@ -96,6 +96,11 @@ export class DevToolsService implements StreamUpdateReceiver {
       }
     });
 
+    // Push state when the local store reports its durability (the open happens
+    // during connect, typically before a panel attaches, so this mostly matters
+    // for a later bucket switch that loses OPFS).
+    this.databaseService.subscribeToStorageHealth?.(() => this.notifyDevTools());
+
     // Fire-and-forget backend version discovery; re-push state when it lands.
     void this.refreshBackendVersions();
 
@@ -318,6 +323,9 @@ export class DevToolsService implements StreamUpdateReceiver {
           ? this.localTables
           : this.schema.tables.map((t) => t.name),
         tableData: {},
+        // Durability of the local store. `fallback: true` means persistence was
+        // requested but the dataset is actually sitting in RAM.
+        storage: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },
       },
     });
   }

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

@@ -1,7 +1,7 @@
 import type { QueryPlan, RelationPlan, WhereNode } from '@spooky-sync/query-builder';
 import type { SealedQuery } from '../../utils/surql';
 import type { DatabaseEventSystem } from './events/index';
-import type { Sp00kyConfig } from '../../types';
+import type { Sp00kyConfig, StorageHealth } from '../../types';
 
 /**
  * A materialized row. Keys are field names; values are already decoded to the
@@ -121,6 +121,15 @@ export interface LocalStore extends LocalCacheEngine {
   getClient(): unknown;
   getConfig(): Sp00kyConfig<any>['database'];
   readonly currentBucketId: string;
+  /**
+   * Durability of this engine's local store. OPTIONAL: engines that don't
+   * report it (SurrealDB, custom engines) are treated as `'unknown'` by the
+   * client facade, so adding this needs no change on their side.
+   */
+  readonly storageHealth?: StorageHealth;
+  /** Fires immediately with the current snapshot, then on every change.
+   *  Returns an unsubscribe function. */
+  subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
 }
 
 /** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */

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

@@ -135,6 +135,93 @@ describe('SqliteCacheEngine system-table seeding', () => {
   });
 });
 
+// The worker's `persisted`/`opfsError` reply used to die in a `logger.info`
+// line, so a host app running pino at `fatal` (whitepawn does) could not tell a
+// disk-backed store from a full-RAM one. It now lands on the engine as
+// observable state the app can render.
+describe('SqliteCacheEngine storage health', () => {
+  /** Engine wired to a worker whose `open` replies with `openReply`. */
+  function makeEngine(openReply: Record<string, unknown>, opts?: { useOpfs?: boolean }) {
+    const logs: { level: string; msg: string; meta: any }[] = [];
+    const logger: any = {};
+    for (const level of ['debug', 'info', 'warn', 'error', 'trace']) {
+      logger[level] = (meta: any, msg: string) => logs.push({ level, msg, meta });
+    }
+    logger.child = () => logger;
+
+    const engine = new SqliteCacheEngine(
+      { namespace: 'n', database: 'd' } as any,
+      logger,
+      opts ?? {}
+    );
+    (engine as any).spawnWorker = () => {
+      const w: any = { onmessage: null, onerror: null, onmessageerror: null, terminate() {} };
+      w.postMessage = (msg: any) => {
+        Promise.resolve().then(() => {
+          const rest = msg.type === 'open' ? openReply : {};
+          const { id, ok, error, ...payload } = { id: msg.id, ok: true, error: undefined, ...rest };
+          const p = (engine as any).pending.get(id);
+          if (!p) return;
+          (engine as any).pending.delete(id);
+          if (ok) p.resolve(payload);
+          else p.reject(new Error(error));
+        });
+      };
+      return w as unknown as Worker;
+    };
+    return { engine, logs };
+  }
+
+  it('publishes a persistent store and logs no error', async () => {
+    const { engine, logs } = makeEngine({ persisted: true });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({
+      status: 'persistent',
+      fallback: false,
+      error: undefined,
+    });
+    expect(logs.some((l) => l.level === 'error')).toBe(false);
+  });
+
+  it('publishes the fallback, its reason, and an error log when OPFS is lost', async () => {
+    const { engine, logs } = makeEngine({ persisted: false, opfsError: 'NoModificationAllowedError: locked' });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({
+      status: 'memory',
+      fallback: true,
+      error: 'NoModificationAllowedError: locked',
+    });
+    const err = logs.find((l) => l.level === 'error');
+    expect(err?.msg).toContain('IN MEMORY');
+    expect(err?.meta.opfsError).toBe('NoModificationAllowedError: locked');
+    // Inspectable from the console without any logging configured.
+    expect((globalThis as any).__sqliteStats.persisted).toBe(false);
+  });
+
+  // A subscriber almost always attaches AFTER connect() (components mount
+  // later), so an immediate fire is the only way it learns about a fallback.
+  it('fires a late subscriber with the current snapshot', async () => {
+    const { engine } = makeEngine({ persisted: false, opfsError: 'boom' });
+    await engine.connect('user:abc');
+
+    const seen: any[] = [];
+    const unsub = engine.subscribeToStorageHealth((h) => seen.push(h));
+    expect(seen).toEqual([{ status: 'memory', fallback: true, error: 'boom' }]);
+    unsub();
+  });
+
+  // `store: 'memory'` asked for RAM, so it is not a fallback and must not warn.
+  it('does not flag a configured in-memory store as a fallback', async () => {
+    const { engine, logs } = makeEngine({ persisted: false }, { useOpfs: false });
+    await engine.connect('user:abc');
+
+    expect(engine.storageHealth).toEqual({ status: 'memory', fallback: false, error: undefined });
+    expect(logs.some((l) => l.level === 'error')).toBe(false);
+  });
+});
+
 // `pureWriteOpResult` is the single source of truth for what a pure-write op
 // contributes to a query's per-statement results. The batched fast path in
 // `query()` and the per-op `execOp` path BOTH route through it, so a caller that

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 {
@@ -94,6 +94,11 @@ export class SqliteCacheEngine implements LocalStore {
   private workerSelect: 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;
 
@@ -114,6 +119,26 @@ 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;
   }
@@ -247,7 +272,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 +285,30 @@ 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;
+    this.setStorageHealth({
+      status: persisted ? 'persistent' : 'memory',
+      fallback: fellBack,
+      error: fellBack ? opfsError : undefined,
+    });
+    const stats = getStats();
+    stats.persisted = persisted;
+    stats.opfsError = fellBack ? opfsError : undefined;
+    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 +793,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/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], ...]