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

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

@@ -1141,6 +1141,7 @@ function renderRelationFetchSurql(req) {
 var SurrealCacheEngine = class extends LocalDatabaseService {
 	/** SurrealDB needs its SurrealQL schema provisioned locally. */
 	usesSurqlSchema = true;
+	engineKind = "surrealdb";
 	/** {@link LocalCacheEngine} alias for {@link LocalDatabaseService.switchStore}. */
 	switchBucket(bucketId) {
 		return this.switchStore(bucketId);
@@ -1509,15 +1510,28 @@ var SqliteCacheEngine = class {
 	*  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. */
 	workerSelect;
+	/** What `workerSelect` was at construction, so DevTools can tell a runtime
+	*  downgrade (configured true, effective false) from a configured-off. */
+	workerSelectConfigured;
 	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;
+	engineKind = "sqlite";
 	constructor(config, logger, opts = {}) {
 		this.config = config;
 		this.logger = logger;
 		this.useOpfs = opts.useOpfs ?? true;
 		this.workerSelect = opts.workerSelect ?? config.workerSelect ?? true;
+		this.workerSelectConfigured = this.workerSelect;
 	}
 	get epoch() {
 		return this.storeEpoch;
@@ -1525,9 +1539,60 @@ 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;
 	}
+	/**
+	* 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) {
+		const diag = {
+			engine: "sqlite",
+			bucketId: this.bucketId,
+			useOpfs: this.useOpfs,
+			workerSelectConfigured: this.workerSelectConfigured,
+			workerSelectEffective: this.workerSelect
+		};
+		try {
+			const { rows } = await this.call("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("exec", { sql: "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name" });
+				const names = (tables ?? []).map((r) => r.name);
+				if (names.length) {
+					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("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() {
 		return this.events;
 	}
@@ -1625,7 +1690,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 +1698,27 @@ 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;
+		const health = {
+			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 (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. */
@@ -5049,10 +5130,79 @@ function parseBackendInfo(raw) {
 	};
 }
 
+//#endregion
+//#region src/modules/devtools/storage-info.ts
+/**
+* Recursively list the origin's OPFS. Sizes come from `handle.getFile()`,
+* which throws for a file another context holds an exclusive sync access
+* handle on — SAHPool does exactly that for its whole pool, so a locked file
+* (size omitted) is a live "who has the pool" signal, not a failure.
+*/
+async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
+	const nav = typeof navigator !== "undefined" ? navigator : void 0;
+	if (!nav?.storage?.getDirectory) return {
+		supported: false,
+		entries: [],
+		totalBytes: 0,
+		truncated: false
+	};
+	const entries = [];
+	let totalBytes = 0;
+	let truncated = false;
+	try {
+		const root = await nav.storage.getDirectory();
+		const walk = async (dir, prefix, depth) => {
+			if (depth > maxDepth) return;
+			for await (const [name, handle] of dir.entries()) {
+				if (entries.length >= maxEntries) {
+					truncated = true;
+					return;
+				}
+				const path = prefix ? `${prefix}/${name}` : name;
+				if (handle.kind === "directory") {
+					entries.push({
+						path,
+						kind: "directory"
+					});
+					await walk(handle, path, depth + 1);
+				} else {
+					let size;
+					try {
+						size = (await handle.getFile()).size;
+						totalBytes += size;
+					} catch {}
+					const entry = {
+						path,
+						kind: "file"
+					};
+					if (size !== void 0) entry.size = size;
+					entries.push(entry);
+				}
+			}
+		};
+		await walk(root, "", 0);
+		entries.sort((a, b) => a.path.localeCompare(b.path));
+		return {
+			supported: true,
+			entries,
+			totalBytes,
+			truncated
+		};
+	} catch (e) {
+		return {
+			supported: true,
+			entries,
+			totalBytes,
+			truncated,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.152";
-const WASM_VERSION = "0.0.1-canary.152";
+const CORE_VERSION = "0.0.1-canary.154";
+const WASM_VERSION = "0.0.1-canary.154";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5083,6 +5233,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,10 +5399,77 @@ 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
+				}
 			}
 		});
 	}
+	/**
+	* Full storage diagnostics for the DevTools Storage tab. Every section is
+	* gathered independently and failures land in that section's `error` field,
+	* so one broken source (a mid-switch worker, a browser without OPFS) never
+	* blanks the whole panel.
+	*/
+	async getStorageInfo(opts) {
+		const nav = typeof navigator !== "undefined" ? navigator : void 0;
+		const info = {
+			at: Date.now(),
+			engine: {
+				kind: this.databaseService.engineKind ?? "custom",
+				store: this.databaseService.getConfig()?.store ?? "memory",
+				bucketId: this.databaseService.currentBucketId
+			},
+			health: this.databaseService.storageHealth ?? {
+				status: "unknown",
+				fallback: false
+			},
+			browser: {},
+			opfs: {
+				supported: false,
+				entries: [],
+				totalBytes: 0,
+				truncated: false
+			}
+		};
+		try {
+			if (nav?.storage?.estimate) {
+				const est = await nav.storage.estimate();
+				info.browser.usage = est.usage;
+				info.browser.quota = est.quota;
+				const details = est.usageDetails;
+				if (details && typeof details === "object") info.browser.usageDetails = details;
+			}
+			if (nav?.storage?.persisted) info.browser.persisted = await nav.storage.persisted();
+		} catch (e) {
+			info.browser.error = e instanceof Error ? e.message : String(e);
+		}
+		info.opfs = await walkOpfs();
+		const stats = globalThis.__sqliteStats;
+		if (stats && typeof stats === "object") info.sqliteStats = {
+			...stats,
+			byType: { ...stats.byType ?? {} }
+		};
+		try {
+			info.engineDiagnostics = await this.databaseService.getStorageDiagnostics?.(opts);
+		} catch (e) {
+			this.logger.warn({
+				err: e,
+				Category: "sp00ky-client::DevToolsService::getStorageInfo"
+			}, "Engine storage diagnostics failed");
+		}
+		return this.serializeForDevTools(info);
+	}
+	/** Ask the browser to exempt this origin's storage from eviction. */
+	async requestPersistentStorage() {
+		try {
+			return { granted: await navigator.storage?.persist?.() ?? false };
+		} catch {
+			return { granted: false };
+		}
+	}
 	notifyDevTools() {
 		if (!this.enabled) return;
 		if (typeof window !== "undefined") window.postMessage({
@@ -5275,7 +5493,10 @@ var DevToolsService = class {
 			if (seen.has(data)) return "[Circular Object]";
 			seen.add(data);
 			const result = {};
-			for (const key in data) if (Object.prototype.hasOwnProperty.call(data, key)) result[key] = this.serializeForDevTools(data[key], seen);
+			for (const key in data) if (Object.prototype.hasOwnProperty.call(data, key)) {
+				if (data[key] === void 0) continue;
+				result[key] = this.serializeForDevTools(data[key], seen);
+			}
 			return result;
 		}
 		return data;
@@ -5290,6 +5511,8 @@ var DevToolsService = class {
 					this.notifyDevTools();
 				},
 				refreshVersions: () => this.refreshBackendVersions(),
+				getStorageInfo: (opts) => this.getStorageInfo(opts),
+				requestPersistentStorage: () => this.requestPersistentStorage(),
 				getTableData: async (tableName) => {
 					try {
 						const result = await this.databaseService.query(`SELECT * FROM ${tableName}`);
@@ -7159,6 +7382,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 +7448,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

@@ -179,6 +179,27 @@ interface SealedQuery<T = void> {
   readonly extract: (results: unknown[]) => T;
 }
 //#endregion
+//#region src/modules/devtools/storage-info.d.ts
+/** Engine-side numbers only the engine can produce (worker round-trips). */
+interface EngineStorageDiagnostics {
+  engine: 'sqlite';
+  bucketId: string;
+  useOpfs: boolean;
+  workerSelectConfigured: boolean;
+  /** `false` while configured `true` means the runtime downgraded to the
+   *  legacy multi-hop select (stale cached worker bundle). */
+  workerSelectEffective: boolean;
+  /** page_count * page_size. */
+  dbSizeBytes?: number;
+  /** freelist_count * page_size — reclaimable via VACUUM. */
+  freelistBytes?: number;
+  tableCounts?: {
+    table: string;
+    rows: number;
+  }[];
+  error?: string;
+}
+//#endregion
 //#region src/services/database/cache-engine.d.ts
 /**
  * A materialized row. Keys are field names; values are already decoded to the
@@ -288,6 +309,24 @@ interface LocalStore extends LocalCacheEngine {
   getClient(): unknown;
   getConfig(): Sp00kyConfig<any>['database'];
   readonly currentBucketId: string;
+  /** Which built-in backend this is. OPTIONAL: absent (custom engines) is
+   *  reported as `'custom'` by DevTools. More robust than `instanceof` for
+   *  engines constructed outside this package. */
+  readonly engineKind?: 'surrealdb' | 'sqlite';
+  /** Engine-specific storage numbers for DevTools (DB file size, per-table
+   *  row counts). OPTIONAL: only engines with something to report implement it. */
+  getStorageDiagnostics?(opts?: {
+    tableCounts?: boolean;
+  }): Promise<EngineStorageDiagnostics>;
+  /**
+   * 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 +569,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 +816,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.152",
+  "version": "0.0.1-canary.154",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.152",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.152",
+    "@spooky-sync/query-builder": "0.0.1-canary.154",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.154",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",