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

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,6 +1510,9 @@ 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
@@ -1521,11 +1525,13 @@ var SqliteCacheEngine = class {
 	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;
@@ -1553,6 +1559,40 @@ var SqliteCacheEngine = class {
 	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;
 	}
@@ -1659,14 +1699,16 @@ var SqliteCacheEngine = class {
 		for (const t of SYSTEM_TABLES) this.knownTables.add(t);
 		this.bucketId = bucketId;
 		const fellBack = this.useOpfs && !persisted;
-		this.setStorageHealth({
+		const health = {
 			status: persisted ? "persistent" : "memory",
-			fallback: fellBack,
-			error: fellBack ? opfsError : void 0
-		});
+			fallback: fellBack
+		};
+		if (fellBack && opfsError) health.error = opfsError;
+		this.setStorageHealth(health);
 		const stats = getStats();
 		stats.persisted = persisted;
-		stats.opfsError = fellBack ? opfsError : void 0;
+		if (fellBack && opfsError) stats.opfsError = opfsError;
+		else delete stats.opfsError;
 		if (fellBack) this.logger.error({
 			bucketId,
 			opfsError,
@@ -5088,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.153";
-const WASM_VERSION = "0.0.1-canary.153";
+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 = [];
@@ -5296,6 +5407,69 @@ var DevToolsService = class {
 			}
 		});
 	}
+	/**
+	* 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({
@@ -5319,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;
@@ -5334,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}`);

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,15 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.153",
+  "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.153",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.153",
+    "@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",

package/src/modules/devtools/index.ts

@@ -22,6 +22,7 @@ import {
   parseBackendInfo,
   UNAVAILABLE,
 } from './versions';
+import { walkOpfs, type StorageInfo } from './storage-info';
 
 // Real bundled frontend versions, injected at build time by tsdown's
 // version-define plugin (see tsdown.config.ts). The `typeof` guard keeps these
@@ -330,6 +331,72 @@ export class DevToolsService implements StreamUpdateReceiver {
     });
   }
 
+  /**
+   * 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.
+   */
+  public async getStorageInfo(opts?: { tableCounts?: boolean }): Promise<StorageInfo> {
+    const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+
+    const info: StorageInfo = {
+      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;
+        // Chrome-only per-storage-system breakdown; absent elsewhere.
+        const details = (est as any).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 as any).__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. */
+  public async requestPersistentStorage(): Promise<{ granted: boolean }> {
+    try {
+      const granted = (await navigator.storage?.persist?.()) ?? false;
+      return { granted };
+    } catch {
+      return { granted: false };
+    }
+  }
+
   private notifyDevTools() {
     // No consumer attached → no getState() serialization, no postMessage broadcast.
     if (!this.enabled) return;
@@ -383,6 +450,10 @@ export class DevToolsService implements StreamUpdateReceiver {
       const result: Record<string, any> = {};
       for (const key in data) {
         if (Object.prototype.hasOwnProperty.call(data, key)) {
+          // Skip absent optional fields: recursing them would emit the STRING
+          // 'undefined' (the top-level mapping below), which panels then have
+          // to filter back out (see 3d84fe8a).
+          if (data[key] === undefined) continue;
           result[key] = this.serializeForDevTools(data[key], seen);
         }
       }
@@ -402,6 +473,8 @@ export class DevToolsService implements StreamUpdateReceiver {
           this.notifyDevTools();
         },
         refreshVersions: () => this.refreshBackendVersions(),
+        getStorageInfo: (opts?: { tableCounts?: boolean }) => this.getStorageInfo(opts),
+        requestPersistentStorage: () => this.requestPersistentStorage(),
         getTableData: async (tableName: string) => {
           try {
             // Returns the first statement result as T.

package/src/modules/devtools/storage-info.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { walkOpfs } from './storage-info';
+
+/** Minimal in-memory OPFS: directories are nested objects, files are numbers
+ *  (their size) or 'locked' (getFile() throws, like a live SAHPool handle). */
+type FakeTree = { [name: string]: FakeTree | number | 'locked' };
+
+function makeDirHandle(tree: FakeTree): any {
+  return {
+    kind: 'directory',
+    entries: async function* () {
+      for (const [name, node] of Object.entries(tree)) {
+        if (typeof node === 'object') {
+          yield [name, makeDirHandle(node)];
+        } else {
+          yield [
+            name,
+            {
+              kind: 'file',
+              getFile: async () => {
+                if (node === 'locked') throw new DOMException('locked', 'NoModificationAllowedError');
+                return { size: node };
+              },
+            },
+          ];
+        }
+      }
+    },
+  };
+}
+
+function stubOpfs(tree: FakeTree | null) {
+  vi.stubGlobal('navigator', tree === null ? {} : {
+    storage: { getDirectory: async () => makeDirHandle(tree) },
+  });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('walkOpfs', () => {
+  it('reports unsupported without OPFS APIs', async () => {
+    stubOpfs(null);
+    expect(await walkOpfs()).toEqual({
+      supported: false,
+      entries: [],
+      totalBytes: 0,
+      truncated: false,
+    });
+  });
+
+  it('walks recursively, sums readable sizes, and omits size for locked files', async () => {
+    stubOpfs({
+      '.sp00ky-anon': { '0000000001': 4096, '0000000002': 'locked' },
+      'other.txt': 10,
+    });
+    const res = await walkOpfs();
+    expect(res.supported).toBe(true);
+    expect(res.truncated).toBe(false);
+    // Locked file present but without a size; total counts only readable bytes.
+    expect(res.totalBytes).toBe(4106);
+    expect(res.entries).toEqual([
+      { path: '.sp00ky-anon', kind: 'directory' },
+      { path: '.sp00ky-anon/0000000001', kind: 'file', size: 4096 },
+      { path: '.sp00ky-anon/0000000002', kind: 'file' },
+      { path: 'other.txt', kind: 'file', size: 10 },
+    ]);
+  });
+
+  it('caps the listing and flags truncation', async () => {
+    const big: FakeTree = {};
+    for (let i = 0; i < 10; i++) big[`f${i}`] = 1;
+    stubOpfs(big);
+    const res = await walkOpfs(5);
+    expect(res.truncated).toBe(true);
+    expect(res.entries.length).toBe(5);
+  });
+});

package/src/modules/devtools/storage-info.ts

@@ -0,0 +1,116 @@
+/**
+ * Storage diagnostics for the DevTools Storage tab: what engine backs the
+ * local cache, whether it actually persists, how much of the device's quota
+ * the origin uses, and what is physically sitting in OPFS. Assembled by
+ * `DevToolsService.getStorageInfo()`; everything here is JSON-safe.
+ */
+
+export interface OpfsEntry {
+  /** Path relative to the OPFS root, e.g. `.sp00ky-anon/0000000000000001`. */
+  path: string;
+  kind: 'file' | 'directory';
+  /** Absent when the file's size can't be read (e.g. an exclusive sync access
+   *  handle is held on it — exactly the case during SAHPool contention). */
+  size?: number;
+}
+
+/** Engine-side numbers only the engine can produce (worker round-trips). */
+export 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;
+}
+
+export interface StorageInfo {
+  at: number;
+  engine: { kind: 'surrealdb' | 'sqlite' | 'custom'; store: string; bucketId: string };
+  health: { status: 'unknown' | 'persistent' | 'memory'; fallback: boolean; error?: string };
+  browser: {
+    /** `navigator.storage.persisted()` — whether the origin's storage is
+     *  exempt from eviction (unrelated to the OPFS pool lock). */
+    persisted?: boolean;
+    usage?: number;
+    quota?: number;
+    /** Chrome-only per-system breakdown from `estimate()`. */
+    usageDetails?: Record<string, number>;
+    error?: string;
+  };
+  opfs: {
+    supported: boolean;
+    entries: OpfsEntry[];
+    totalBytes: number;
+    truncated: boolean;
+    error?: string;
+  };
+  /** Snapshot of `globalThis.__sqliteStats` (SQLite engine only). */
+  sqliteStats?: Record<string, unknown>;
+  engineDiagnostics?: EngineStorageDiagnostics;
+}
+
+/**
+ * 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.
+ */
+export async function walkOpfs(maxEntries = 2000, maxDepth = 8): Promise<StorageInfo['opfs']> {
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+  if (!nav?.storage?.getDirectory) {
+    return { supported: false, entries: [], totalBytes: 0, truncated: false };
+  }
+  const entries: OpfsEntry[] = [];
+  let totalBytes = 0;
+  let truncated = false;
+  try {
+    const root = await nav.storage.getDirectory();
+    const walk = async (dir: FileSystemDirectoryHandle, prefix: string, depth: number) => {
+      if (depth > maxDepth) return;
+      // entries() is standard; older lib.dom typings may lack it.
+      for await (const [name, handle] of (dir as any).entries() as AsyncIterable<
+        [string, FileSystemHandle]
+      >) {
+        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 as FileSystemDirectoryHandle, path, depth + 1);
+        } else {
+          let size: number | undefined;
+          try {
+            size = (await (handle as FileSystemFileHandle).getFile()).size;
+            totalBytes += size;
+          } catch {
+            // Locked by an exclusive access handle (e.g. a live SAHPool).
+          }
+          const entry: OpfsEntry = { path, kind: 'file' };
+          if (size !== undefined) 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),
+    };
+  }
+}

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

@@ -2,6 +2,7 @@ import type { QueryPlan, RelationPlan, WhereNode } from '@spooky-sync/query-buil
 import type { SealedQuery } from '../../utils/surql';
 import type { DatabaseEventSystem } from './events/index';
 import type { Sp00kyConfig, StorageHealth } from '../../types';
+import type { EngineStorageDiagnostics } from '../../modules/devtools/storage-info';
 
 /**
  * A materialized row. Keys are field names; values are already decoded to the
@@ -121,6 +122,13 @@ export 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

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

@@ -222,6 +222,78 @@ describe('SqliteCacheEngine storage health', () => {
   });
 });
 
+// Storage numbers for the DevTools Storage tab: DB size via the pragmas, row
+// counts on demand, and the configured-vs-effective workerSelect split. Errors
+// must land in `error` (the worker may be mid bucket-switch), never throw.
+describe('SqliteCacheEngine.getStorageDiagnostics', () => {
+  function makeEngine(execRows: (sql: string) => unknown[]) {
+    const noop = () => {};
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, logger);
+    (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'
+              ? { persisted: true }
+              : msg.type === 'exec'
+                ? { rows: execRows(msg.payload.sql) }
+                : {};
+          const p = (engine as any).pending.get(msg.id);
+          if (!p) return;
+          (engine as any).pending.delete(msg.id);
+          p.resolve(rest);
+        });
+      };
+      return w as unknown as Worker;
+    };
+    return engine;
+  }
+
+  it('reports size, freelist, and per-table counts', async () => {
+    const engine = makeEngine((sql) => {
+      if (sql.includes('pragma_page_count')) return [{ bytes: 40960, freelist: 4096 }];
+      if (sql.includes('sqlite_master')) return [{ name: '_00_query' }, { name: 'game' }];
+      if (sql.includes('COUNT(*)'))
+        return [
+          { t: '_00_query', n: 3 },
+          { t: 'game', n: 12 },
+        ];
+      return [];
+    });
+    await engine.connect('user:abc');
+
+    const diag = await engine.getStorageDiagnostics({ tableCounts: true });
+    expect(diag.engine).toBe('sqlite');
+    expect(diag.bucketId).toBe('user:abc');
+    expect(diag.dbSizeBytes).toBe(40960);
+    expect(diag.freelistBytes).toBe(4096);
+    expect(diag.tableCounts).toEqual([
+      { table: '_00_query', rows: 3 },
+      { table: 'game', rows: 12 },
+    ]);
+    // Default config: workerSelect on, never downgraded.
+    expect(diag.workerSelectConfigured).toBe(true);
+    expect(diag.workerSelectEffective).toBe(true);
+  });
+
+  it('skips table counts unless asked and never throws on a dead worker', async () => {
+    const engine = makeEngine(() => [{ bytes: 8192, freelist: 0 }]);
+    await engine.connect('anon');
+
+    const diag = await engine.getStorageDiagnostics();
+    expect(diag.tableCounts).toBeUndefined();
+
+    // No worker at all → the failure lands in `error`, not as a throw.
+    const cold = makeEngine(() => []);
+    const coldDiag = await cold.getStorageDiagnostics();
+    expect(coldDiag.error).toContain('not connected');
+    expect(coldDiag.bucketId).toBe('anon');
+  });
+});
+
 // `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

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

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);