@xnetjs/sqlite 0.0.3 → 0.1.0

package/dist/chunk-SV475UL5.js

@@ -0,0 +1,44 @@
+// src/adapters/opfs-capability.ts
+function resolveScope(scope) {
+  if (scope) return scope;
+  const g = globalThis;
+  return g;
+}
+function supportsOpfs(scope) {
+  return typeof resolveScope(scope).navigator?.storage?.getDirectory === "function";
+}
+function supportsSyncAccessHandle(scope) {
+  const s = resolveScope(scope);
+  if (typeof s.FileSystemSyncAccessHandle !== "undefined") return true;
+  const proto = s.FileSystemFileHandle?.prototype;
+  return Boolean(proto && "createSyncAccessHandle" in proto);
+}
+function isCrossOriginIsolated(scope) {
+  const s = resolveScope(scope);
+  return typeof s.SharedArrayBuffer !== "undefined" && s.crossOriginIsolated === true;
+}
+function detectOpfsCapability(scope) {
+  const opfs = supportsOpfs(scope);
+  const syncAccessHandle = supportsSyncAccessHandle(scope);
+  const crossOriginIsolated = isCrossOriginIsolated(scope);
+  let mode;
+  let reason;
+  if (!opfs) {
+    mode = "memory";
+    reason = "OPFS is unavailable in this context (private browsing or an unsupported engine); local data will not persist across reloads.";
+  } else if (syncAccessHandle) {
+    mode = "sync-access-handle";
+    reason = "OPFS sync access handles available \u2014 using the durable opfs-sahpool fast path.";
+  } else {
+    mode = "async-opfs";
+    reason = "OPFS is available but sync access handles are not (iOS 15.2\u201316.3 or an older WebView); falling back to the slower async OPFS backend. Data still persists.";
+  }
+  return { opfs, syncAccessHandle, crossOriginIsolated, mode, reason };
+}
+
+export {
+  supportsOpfs,
+  supportsSyncAccessHandle,
+  isCrossOriginIsolated,
+  detectOpfsCapability
+};

package/dist/{chunk-NVD7G7DZ.js → chunk-W3L4FXU5.js}

@@ -1,5 +1,5 @@
 // src/schema.ts
-var SCHEMA_VERSION = 6;
+var SCHEMA_VERSION = 7;
 var SCHEMA_DDL_CORE = `
 -- ============================================
 -- Schema Version Tracking
@@ -89,7 +89,12 @@ CREATE TABLE IF NOT EXISTS node_query_materializations (
     descriptor_json TEXT NOT NULL,
     generated_at INTEGER NOT NULL,
     invalidated_at INTEGER,
-    row_count INTEGER NOT NULL
+    row_count INTEGER NOT NULL,
+    -- Authorization fingerprint the view was materialized under (exploration
+    -- 0226). NULL when authz is off; a mismatch forces an 'authz-changed'
+    -- refresh so a cached id list can never serve rows the viewer can no
+    -- longer read.
+    auth_fingerprint TEXT
 );
 
 CREATE TABLE IF NOT EXISTS node_query_materialized_ids (
@@ -383,6 +388,10 @@ CREATE INDEX IF NOT EXISTS idx_prop_scalars_node
     ON node_property_scalars(node_id);
 CREATE INDEX IF NOT EXISTS idx_changes_node_lamport
     ON changes(node_id, lamport_time DESC, hash);
+`,
+  7: `
+ALTER TABLE node_query_materializations
+    ADD COLUMN auth_fingerprint TEXT;
 `
 };
 function getMigrationSQL(fromVersion, toVersion) {

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { S as SQLValue } from './types-DMrj3K4o.js';
-export { R as RunResult, a as SQLRow, b as SQLiteConfig, k as SQLiteNodeBatchApplyInput, l as SQLiteNodeBatchApplyResult, h as SQLiteNodeBatchChangeRow, j as SQLiteNodeBatchFtsRow, e as SQLiteNodeBatchIndexMode, f as SQLiteNodeBatchNodeRow, g as SQLiteNodeBatchPropertyRow, i as SQLiteNodeBatchScalarIndexRow, d as SQLiteOperationStats, c as SchemaVersion } from './types-DMrj3K4o.js';
-import { S as SQLiteAdapter } from './adapter-t2aqQ__n.js';
-export { P as PreparedStatement } from './adapter-t2aqQ__n.js';
-export { a as SCHEMA_DDL, b as SCHEMA_DDL_CORE, c as SCHEMA_DDL_FTS, d as SCHEMA_MIGRATIONS, S as SCHEMA_VERSION, g as getMigrationSQL } from './schema-BEgIA-rZ.js';
-export { BrowserSupport, PersistentStorageRequestOptions, PersistentStorageStatus, checkBrowserSupport, checkPersistentStorage, isSilentPersistRequestSafe, requestPersistentStorage, showUnsupportedBrowserMessage, watchPersistentStoragePermission } from './browser-support.js';
+import { S as SQLValue } from './types-BTabr_VP.js';
+export { E as ElectronSQLiteDiagnostics, R as RunResult, c as SQLBatchRead, a as SQLRow, b as SQLiteConfig, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult, i as SQLiteNodeBatchChangeRow, k as SQLiteNodeBatchFtsRow, f as SQLiteNodeBatchIndexMode, g as SQLiteNodeBatchNodeRow, h as SQLiteNodeBatchPropertyRow, j as SQLiteNodeBatchScalarIndexRow, e as SQLiteOperationStats, d as SchemaVersion } from './types-BTabr_VP.js';
+import { S as SQLiteAdapter } from './adapter-imtxkmXZ.js';
+export { P as PreparedStatement } from './adapter-imtxkmXZ.js';
+export { a as SCHEMA_DDL, b as SCHEMA_DDL_CORE, c as SCHEMA_DDL_FTS, d as SCHEMA_MIGRATIONS, S as SCHEMA_VERSION, g as getMigrationSQL } from './schema-C4gufY3B.js';
+export { BrowserSupport, PersistentStorageRequestOptions, PersistentStorageStatus, checkBrowserSupport, checkPersistentStorage, getMemoryFallbackSessionCount, isSilentPersistRequestSafe, recordMemoryFallbackSession, requestPersistentStorage, showUnsupportedBrowserMessage, watchPersistentStoragePermission } from './browser-support.js';
 
 /**
  * @xnetjs/sqlite - SQL query building helpers
@@ -161,7 +161,10 @@ interface SQLiteRuntimeCapabilities {
     rtree: boolean;
 }
 /**
- * Get information about all indexes in the database.
+ * Get information about all indexes in the database. Cached per adapter and keyed
+ * on `PRAGMA schema_version`, so repeated calls between DDL changes pay one cheap
+ * version probe instead of `sqlite_master` + N `PRAGMA index_info` round-trips
+ * (exploration 0253).
  */
 declare function getIndexInfo(db: SQLiteAdapter): Promise<IndexInfo[]>;
 /**
@@ -223,4 +226,85 @@ declare function timeQuery<T>(db: SQLiteAdapter, sql: string, params?: SQLValue[
  */
 declare function isSQLiteCorruptionError(error: unknown): boolean;
 
-export { type DatabaseStats, type FTSSearchOptions, type FTSSearchResult, type IndexInfo, type QueryPlanStep, SQLValue, SQLiteAdapter, type SQLiteRuntimeCapabilities, type TableStats, analyzeQuery, analyzeTable, buildBatchInsert, buildInsert, buildSelect, buildUpdate, checkIntegrity, deleteNodeFTS, detectSQLiteCapabilities, escapeLike, explainQuery, extractSearchableContent, extractTextFromTipTap, getAllTableStats, getDatabaseStats, getIndexInfo, isSQLiteCorruptionError, optimizeFTS, rebuildFTS, runAnalyze, searchNodes, timeQuery, updateNodeFTS };
+/**
+ * @xnetjs/sqlite — OPFS capability detection (exploration 0238)
+ *
+ * The web adapter persists through the Origin Private File System. Which OPFS
+ * backend is reachable depends on the runtime, and the difference matters most
+ * inside a **mobile webview**:
+ *
+ * - `opfs-sahpool` (the fast path) needs synchronous access handles —
+ *   `FileSystemSyncAccessHandle` — which land in **iOS 16.4+** and Chromium 108+
+ *   (Android System WebView). This is what {@link WebSQLiteAdapter} installs.
+ * - Below that (iOS 15.2–16.3, older WebViews) only the **async** OPFS VFS
+ *   (`sqlite3.oo1.OpfsDb`) works — still durable, just slower I/O.
+ * - With no OPFS at all (private mode, ancient engines) the adapter falls back
+ *   to a non-durable in-memory database.
+ *
+ * The web adapter already walks that fallback chain at `open()`; this module
+ * makes the decision *legible* — a pure, injectable predicate the adapter uses
+ * to emit an accurate "why are we on the slow/no-persistence path" diagnostic,
+ * and that the host app / tests can call directly to branch on capability.
+ */
+/** The durable OPFS backend a context can support, best first. */
+type OpfsPersistenceMode = 'sync-access-handle' | 'async-opfs' | 'memory';
+/** Structured capability report for the current (or an injected) scope. */
+interface OpfsCapability {
+    /** OPFS root is reachable (`navigator.storage.getDirectory`). */
+    opfs: boolean;
+    /**
+     * Synchronous access handles exist → the `opfs-sahpool` fast path is usable
+     * (iOS 16.4+, Chromium 108+). When false on an OPFS-capable engine we are on
+     * an older iOS/WebView and must use the async OPFS VFS.
+     */
+    syncAccessHandle: boolean;
+    /**
+     * `SharedArrayBuffer` is present *and* the context is cross-origin isolated.
+     * Required by the highest-performance sqlite-wasm mode; in a webview this is
+     * what `capacitor://localhost` + COOP/COEP unlocks (exploration 0238).
+     */
+    crossOriginIsolated: boolean;
+    /** Best durable backend this context supports. */
+    mode: OpfsPersistenceMode;
+    /** Human-readable explanation, useful for the iOS <16.4 async-fallback case. */
+    reason: string;
+}
+/**
+ * The slice of global APIs capability detection reads. Injectable so the
+ * shared (non-isolated) `unit` test pool can probe synthetic environments
+ * without mutating real globals.
+ */
+interface OpfsCapabilityScope {
+    navigator?: {
+        storage?: {
+            getDirectory?: unknown;
+        };
+    } | undefined;
+    FileSystemSyncAccessHandle?: unknown;
+    FileSystemFileHandle?: {
+        prototype?: Record<string, unknown>;
+    } | undefined;
+    SharedArrayBuffer?: unknown;
+    crossOriginIsolated?: unknown;
+}
+/** True when the context exposes OPFS via `navigator.storage.getDirectory`. */
+declare function supportsOpfs(scope?: OpfsCapabilityScope): boolean;
+/**
+ * True when synchronous access handles are available — the gate for the
+ * `opfs-sahpool` fast path (iOS 16.4+, Chromium 108+). Checks both the global
+ * constructor and the `createSyncAccessHandle` method on the file-handle
+ * prototype, since engines have shipped one or the other.
+ */
+declare function supportsSyncAccessHandle(scope?: OpfsCapabilityScope): boolean;
+/**
+ * True when a `SharedArrayBuffer` can actually be used — present *and* the
+ * context is cross-origin isolated (the browser ungated SAB behind COI).
+ */
+declare function isCrossOriginIsolated(scope?: OpfsCapabilityScope): boolean;
+/**
+ * Report the best durable OPFS backend the given scope supports, with a reason.
+ * Pure and synchronous — safe to call before any sqlite-wasm import.
+ */
+declare function detectOpfsCapability(scope?: OpfsCapabilityScope): OpfsCapability;
+
+export { type DatabaseStats, type FTSSearchOptions, type FTSSearchResult, type IndexInfo, type OpfsCapability, type OpfsCapabilityScope, type OpfsPersistenceMode, type QueryPlanStep, SQLValue, SQLiteAdapter, type SQLiteRuntimeCapabilities, type TableStats, analyzeQuery, analyzeTable, buildBatchInsert, buildInsert, buildSelect, buildUpdate, checkIntegrity, deleteNodeFTS, detectOpfsCapability, detectSQLiteCapabilities, escapeLike, explainQuery, extractSearchableContent, extractTextFromTipTap, getAllTableStats, getDatabaseStats, getIndexInfo, isCrossOriginIsolated, isSQLiteCorruptionError, optimizeFTS, rebuildFTS, runAnalyze, searchNodes, supportsOpfs, supportsSyncAccessHandle, timeQuery, updateNodeFTS };

package/dist/index.js

@@ -1,3 +1,19 @@
+import {
+  checkBrowserSupport,
+  checkPersistentStorage,
+  getMemoryFallbackSessionCount,
+  isSilentPersistRequestSafe,
+  recordMemoryFallbackSession,
+  requestPersistentStorage,
+  showUnsupportedBrowserMessage,
+  watchPersistentStoragePermission
+} from "./chunk-S6MT6KCI.js";
+import {
+  detectOpfsCapability,
+  isCrossOriginIsolated,
+  supportsOpfs,
+  supportsSyncAccessHandle
+} from "./chunk-SV475UL5.js";
 import {
   isSQLiteCorruptionError
 } from "./chunk-CBU263LI.js";
@@ -8,15 +24,7 @@ import {
   SCHEMA_MIGRATIONS,
   SCHEMA_VERSION,
   getMigrationSQL
-} from "./chunk-NVD7G7DZ.js";
-import {
-  checkBrowserSupport,
-  checkPersistentStorage,
-  isSilentPersistRequestSafe,
-  requestPersistentStorage,
-  showUnsupportedBrowserMessage,
-  watchPersistentStoragePermission
-} from "./chunk-2OK46ZBU.js";
+} from "./chunk-W3L4FXU5.js";
 
 // src/query-builder.ts
 function buildInsert(table, columns, options) {
@@ -62,7 +70,21 @@ function buildBatchInsert(table, columns, rowCount) {
 }
 
 // src/diagnostics.ts
+var indexInfoCache = /* @__PURE__ */ new WeakMap();
+async function readSchemaVersion(db) {
+  try {
+    const row = await db.queryOne("PRAGMA schema_version");
+    return Number(row?.schema_version ?? 0);
+  } catch {
+    return 0;
+  }
+}
 async function getIndexInfo(db) {
+  const schemaVersion = await readSchemaVersion(db);
+  const cached = indexInfoCache.get(db);
+  if (cached && cached.schemaVersion === schemaVersion) {
+    return cached.indexes;
+  }
   const indexes = await db.query(
     "SELECT name, tbl_name, sql FROM sqlite_master WHERE type='index' AND name NOT LIKE 'sqlite_%'"
   );
@@ -77,6 +99,7 @@ async function getIndexInfo(db) {
       partial: idx.sql?.includes("WHERE") ?? false
     });
   }
+  indexInfoCache.set(db, { schemaVersion, indexes: result });
   return result;
 }
 async function analyzeQuery(db, sql, params) {
@@ -390,6 +413,7 @@ export {
   checkIntegrity,
   checkPersistentStorage,
   deleteNodeFTS,
+  detectOpfsCapability,
   detectSQLiteCapabilities,
   escapeLike,
   explainQuery,
@@ -398,15 +422,20 @@ export {
   getAllTableStats,
   getDatabaseStats,
   getIndexInfo,
+  getMemoryFallbackSessionCount,
   getMigrationSQL,
+  isCrossOriginIsolated,
   isSQLiteCorruptionError,
   isSilentPersistRequestSafe,
   optimizeFTS,
   rebuildFTS,
+  recordMemoryFallbackSession,
   requestPersistentStorage,
   runAnalyze,
   searchNodes,
   showUnsupportedBrowserMessage,
+  supportsOpfs,
+  supportsSyncAccessHandle,
   timeQuery,
   updateNodeFTS,
   watchPersistentStoragePermission

package/dist/schema-C4gufY3B.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @xnetjs/sqlite - Unified SQLite schema for xNet
+ */
+/**
+ * Current schema version.
+ * Increment this when making schema changes.
+ */
+declare const SCHEMA_VERSION = 7;
+/**
+ * Core SQLite schema for xNet (without FTS5).
+ * This schema works on all platforms including sql.js.
+ */
+declare const SCHEMA_DDL_CORE = "\n-- ============================================\n-- Schema Version Tracking\n-- ============================================\n\nCREATE TABLE IF NOT EXISTS _schema_version (\n    version INTEGER PRIMARY KEY,\n    applied_at INTEGER NOT NULL\n);\n\n-- ============================================\n-- Core Tables\n-- ============================================\n\n-- All nodes (Pages, Databases, Rows, Comments, etc.)\nCREATE TABLE IF NOT EXISTS nodes (\n    id TEXT PRIMARY KEY,\n    schema_id TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    updated_at INTEGER NOT NULL,\n    created_by TEXT NOT NULL,\n    deleted_at INTEGER\n);\n\n-- Node properties (LWW per-property)\nCREATE TABLE IF NOT EXISTS node_properties (\n    node_id TEXT NOT NULL,\n    property_key TEXT NOT NULL,\n    value BLOB,\n    lamport_time INTEGER NOT NULL,\n    updated_by TEXT NOT NULL,\n    updated_at INTEGER NOT NULL,\n\n    PRIMARY KEY (node_id, property_key),\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Rebuildable scalar property index for query planning.\nCREATE TABLE IF NOT EXISTS node_property_scalars (\n    node_id TEXT NOT NULL,\n    schema_id TEXT NOT NULL,\n    property_key TEXT NOT NULL,\n    value_type TEXT NOT NULL,\n    value_text TEXT,\n    value_number REAL,\n    value_boolean INTEGER,\n    value_hash TEXT,\n    updated_at INTEGER NOT NULL,\n    lamport_time INTEGER NOT NULL,\n\n    PRIMARY KEY (schema_id, property_key, node_id),\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Query planner telemetry for adaptive read indexes.\nCREATE TABLE IF NOT EXISTS query_descriptor_stats (\n    descriptor_hash TEXT PRIMARY KEY,\n    schema_id TEXT NOT NULL,\n    descriptor_json TEXT NOT NULL,\n    hits INTEGER NOT NULL,\n    total_duration_ms REAL NOT NULL,\n    avg_duration_ms REAL NOT NULL,\n    avg_candidates REAL NOT NULL,\n    last_seen_at INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS query_index_candidates (\n    index_name TEXT PRIMARY KEY,\n    descriptor_hash TEXT NOT NULL,\n    schema_id TEXT NOT NULL,\n    property_key TEXT NOT NULL,\n    value_type TEXT NOT NULL,\n    ddl TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    last_used_at INTEGER NOT NULL,\n    estimated_bytes INTEGER NOT NULL DEFAULT 0,\n    estimated_rows INTEGER NOT NULL DEFAULT 0,\n\n    FOREIGN KEY (descriptor_hash) REFERENCES query_descriptor_stats(descriptor_hash)\n        ON DELETE CASCADE\n);\n\nCREATE TABLE IF NOT EXISTS node_query_materializations (\n    view_id TEXT PRIMARY KEY,\n    descriptor_hash TEXT NOT NULL,\n    schema_id TEXT NOT NULL,\n    descriptor_json TEXT NOT NULL,\n    generated_at INTEGER NOT NULL,\n    invalidated_at INTEGER,\n    row_count INTEGER NOT NULL,\n    -- Authorization fingerprint the view was materialized under (exploration\n    -- 0226). NULL when authz is off; a mismatch forces an 'authz-changed'\n    -- refresh so a cached id list can never serve rows the viewer can no\n    -- longer read.\n    auth_fingerprint TEXT\n);\n\nCREATE TABLE IF NOT EXISTS node_query_materialized_ids (\n    view_id TEXT NOT NULL,\n    ordinal INTEGER NOT NULL,\n    node_id TEXT NOT NULL,\n\n    PRIMARY KEY (view_id, ordinal),\n    UNIQUE (view_id, node_id),\n    FOREIGN KEY (view_id) REFERENCES node_query_materializations(view_id)\n        ON DELETE CASCADE,\n    FOREIGN KEY (node_id) REFERENCES nodes(id)\n        ON DELETE CASCADE\n);\n\n-- Change log (event sourcing)\nCREATE TABLE IF NOT EXISTS changes (\n    hash TEXT PRIMARY KEY,\n    node_id TEXT NOT NULL,\n    payload BLOB NOT NULL,\n    lamport_time INTEGER NOT NULL,\n    lamport_peer TEXT NOT NULL,\n    wall_time INTEGER NOT NULL,\n    author TEXT NOT NULL,\n    parent_hash TEXT,\n    batch_id TEXT,\n    signature BLOB NOT NULL,\n\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Y.Doc binary state (for nodes with collaborative content)\nCREATE TABLE IF NOT EXISTS yjs_state (\n    node_id TEXT PRIMARY KEY,\n    state BLOB NOT NULL,\n    updated_at INTEGER NOT NULL,\n\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Y.Doc incremental updates (for sync)\nCREATE TABLE IF NOT EXISTS yjs_updates (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    node_id TEXT NOT NULL,\n    update_data BLOB NOT NULL,\n    timestamp INTEGER NOT NULL,\n    origin TEXT,\n\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Yjs snapshots (for document time travel)\nCREATE TABLE IF NOT EXISTS yjs_snapshots (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    node_id TEXT NOT NULL,\n    timestamp INTEGER NOT NULL,\n    snapshot BLOB NOT NULL,\n    doc_state BLOB NOT NULL,\n    byte_size INTEGER NOT NULL,\n\n    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE\n);\n\n-- Blobs (content-addressed)\nCREATE TABLE IF NOT EXISTS blobs (\n    cid TEXT PRIMARY KEY,\n    data BLOB NOT NULL,\n    mime_type TEXT,\n    size INTEGER NOT NULL,\n    created_at INTEGER NOT NULL,\n    reference_count INTEGER DEFAULT 1\n);\n\n-- Documents (for @xnetjs/storage compatibility)\nCREATE TABLE IF NOT EXISTS documents (\n    id TEXT PRIMARY KEY,\n    content BLOB NOT NULL,\n    metadata TEXT NOT NULL,\n    version INTEGER NOT NULL DEFAULT 1\n);\n\n-- Signed updates (for @xnetjs/storage compatibility)\nCREATE TABLE IF NOT EXISTS updates (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    doc_id TEXT NOT NULL,\n    update_hash TEXT NOT NULL,\n    update_data TEXT NOT NULL,\n    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),\n    UNIQUE(doc_id, update_hash)\n);\n\n-- Snapshots (for @xnetjs/storage compatibility)\nCREATE TABLE IF NOT EXISTS snapshots (\n    doc_id TEXT PRIMARY KEY,\n    snapshot_data TEXT NOT NULL,\n    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- Sync metadata\nCREATE TABLE IF NOT EXISTS sync_state (\n    key TEXT PRIMARY KEY,\n    value TEXT NOT NULL\n);\n\n-- ============================================\n-- Indexes\n-- ============================================\n\nCREATE INDEX IF NOT EXISTS idx_nodes_schema ON nodes(schema_id);\nCREATE INDEX IF NOT EXISTS idx_nodes_updated ON nodes(updated_at);\nCREATE INDEX IF NOT EXISTS idx_nodes_created_by ON nodes(created_by);\nCREATE INDEX IF NOT EXISTS idx_nodes_deleted ON nodes(deleted_at);\nCREATE INDEX IF NOT EXISTS idx_nodes_live_schema_updated\n    ON nodes(schema_id, updated_at DESC, id)\n    WHERE deleted_at IS NULL;\nCREATE INDEX IF NOT EXISTS idx_nodes_all_schema_updated\n    ON nodes(schema_id, updated_at DESC, id);\nCREATE INDEX IF NOT EXISTS idx_nodes_live_schema_created\n    ON nodes(schema_id, created_at DESC, id)\n    WHERE deleted_at IS NULL;\n\nCREATE INDEX IF NOT EXISTS idx_properties_node ON node_properties(node_id);\nCREATE INDEX IF NOT EXISTS idx_properties_lamport ON node_properties(lamport_time);\n\nCREATE INDEX IF NOT EXISTS idx_prop_scalars_text\n    ON node_property_scalars(schema_id, property_key, value_text, node_id)\n    WHERE value_type = 'text';\nCREATE INDEX IF NOT EXISTS idx_prop_scalars_number\n    ON node_property_scalars(schema_id, property_key, value_number, node_id)\n    WHERE value_type = 'number';\nCREATE INDEX IF NOT EXISTS idx_prop_scalars_boolean\n    ON node_property_scalars(schema_id, property_key, value_boolean, node_id)\n    WHERE value_type = 'boolean';\nCREATE INDEX IF NOT EXISTS idx_prop_scalars_null\n    ON node_property_scalars(schema_id, property_key, node_id)\n    WHERE value_type = 'null';\nCREATE INDEX IF NOT EXISTS idx_prop_scalars_node\n    ON node_property_scalars(node_id);\n\nCREATE INDEX IF NOT EXISTS idx_query_stats_schema_seen\n    ON query_descriptor_stats(schema_id, last_seen_at DESC);\nCREATE INDEX IF NOT EXISTS idx_query_indexes_schema_property\n    ON query_index_candidates(schema_id, property_key, value_type);\nCREATE INDEX IF NOT EXISTS idx_query_materializations_schema\n    ON node_query_materializations(schema_id, invalidated_at);\nCREATE INDEX IF NOT EXISTS idx_query_materialized_ids_node\n    ON node_query_materialized_ids(node_id);\n\nCREATE INDEX IF NOT EXISTS idx_changes_node ON changes(node_id);\nCREATE INDEX IF NOT EXISTS idx_changes_lamport ON changes(lamport_time);\nCREATE INDEX IF NOT EXISTS idx_changes_wall_time ON changes(wall_time);\nCREATE INDEX IF NOT EXISTS idx_changes_batch ON changes(batch_id);\nCREATE INDEX IF NOT EXISTS idx_changes_node_lamport\n    ON changes(node_id, lamport_time DESC, hash);\n\nCREATE INDEX IF NOT EXISTS idx_yjs_state_updated ON yjs_state(updated_at);\nCREATE INDEX IF NOT EXISTS idx_yjs_updates_node ON yjs_updates(node_id);\nCREATE INDEX IF NOT EXISTS idx_yjs_snapshots_node ON yjs_snapshots(node_id);\nCREATE INDEX IF NOT EXISTS idx_yjs_snapshots_timestamp ON yjs_snapshots(node_id, timestamp);\n\nCREATE INDEX IF NOT EXISTS idx_updates_doc ON updates(doc_id);\nCREATE INDEX IF NOT EXISTS idx_updates_created ON updates(created_at);\n";
+/**
+ * FTS5 schema for full-text search.
+ * This is applied separately because sql.js doesn't support FTS5.
+ */
+declare const SCHEMA_DDL_FTS = "\n-- ============================================\n-- Full-Text Search (FTS5)\n-- ============================================\n\n-- FTS index for searchable node content\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n    node_id,\n    title,\n    content,\n    tokenize='porter unicode61'\n);\n\n-- Triggers to keep FTS in sync will be managed by application layer\n-- since the searchable content is derived from node properties\n";
+/**
+ * Unified SQLite schema for xNet.
+ * This schema is shared across all platforms (with FTS5).
+ * Use SCHEMA_DDL_CORE for platforms without FTS5 support (sql.js).
+ */
+declare const SCHEMA_DDL: string;
+/**
+ * Schema for future versions (migrations).
+ * Each key is the version number, value is the upgrade SQL.
+ */
+declare const SCHEMA_MIGRATIONS: Record<number, string>;
+/**
+ * Get the SQL to upgrade from one version to another.
+ */
+declare function getMigrationSQL(fromVersion: number, toVersion: number): string;
+
+export { SCHEMA_VERSION as S, SCHEMA_DDL as a, SCHEMA_DDL_CORE as b, SCHEMA_DDL_FTS as c, SCHEMA_MIGRATIONS as d, getMigrationSQL as g };

package/dist/types-BTabr_VP.d.ts

@@ -0,0 +1,225 @@
+/**
+ * @xnetjs/sqlite - Type definitions for unified SQLite adapter
+ */
+/**
+ * SQL parameter types that can be bound to statements.
+ */
+type SQLValue = string | number | bigint | Uint8Array | null;
+/**
+ * Row type for query results.
+ */
+type SQLRow = Record<string, SQLValue>;
+/**
+ * One read of a {@link SQLiteAdapter.queryBatch} call: a SELECT plus its
+ * bound parameters. Results come back positionally, one row array per read.
+ */
+interface SQLBatchRead {
+    sql: string;
+    params?: SQLValue[];
+}
+/**
+ * Result of a mutation query (INSERT, UPDATE, DELETE).
+ */
+interface RunResult {
+    /** Number of rows affected by the query */
+    changes: number;
+    /** Last inserted row ID (for INSERT with AUTOINCREMENT) */
+    lastInsertRowid: bigint;
+}
+/**
+ * Configuration options for SQLite database.
+ */
+interface SQLiteConfig {
+    /** Database file path or name */
+    path: string;
+    /** Enable WAL mode (default: true) */
+    walMode?: boolean;
+    /** Enable foreign keys (default: true) */
+    foreignKeys?: boolean;
+    /** Busy timeout in milliseconds (default: 5000) */
+    busyTimeout?: number;
+    /**
+     * Emit boot diagnostics from the worker: a per-operation queue/exec timing
+     * trace and a one-shot DB-stats line at open (exploration 0229). Set by the
+     * main thread, which can read the `xnet:boot:debug` flag — the worker can't
+     * (`localStorage` is unavailable in workers).
+     */
+    bootDebug?: boolean;
+    /**
+     * Per-attempt timeout (ms) for the web worker's `open()` before the worker is
+     * terminated and retried with a fresh one (default: 15000). A cold
+     * `installOpfsSAHPoolVfs()` on a large DB file can intermittently exceed this —
+     * usually because a prior boot leaked a worker still holding the file's
+     * exclusive OPFS handle; terminating + retrying clears that contention rather
+     * than hard-failing the boot (exploration 0253). Web adapter only.
+     */
+    openTimeoutMs?: number;
+    /**
+     * Multi-tab leadership routing (exploration 0263). When Web Locks and
+     * SharedWorker are available, tabs elect a leader that owns the SQLite
+     * worker; other tabs route their storage RPCs to it instead of losing the
+     * OPFS handle race and silently falling back to a non-durable `:memory:`
+     * database (exploration 0204). Default: `true` where supported — set `false`
+     * to force the previous per-tab behaviour. Web proxy only.
+     */
+    multiTab?: boolean;
+    /**
+     * Front every storage operation with the priority scheduler so a queued write
+     * burst can't head-of-line block an interactive read, and a manual transaction
+     * holds the connection exclusively (`BEGIN`…`COMMIT` can't be interleaved).
+     * Default: `true`. Has no effect on the WASM/web adapters, which schedule in
+     * their worker host instead.
+     */
+    scheduler?: boolean;
+    /**
+     * Open a second, **read-only** `better-sqlite3` connection so plain reads use
+     * a different connection than the writer (no contention with write locks).
+     * Ignored for `:memory:` databases (each connection would be a separate DB).
+     * Default: `false`.
+     */
+    readonlyReadConnection?: boolean;
+    /**
+     * Spawn a pool of read-only `better-sqlite3` reader threads so **heavy** reads
+     * (FTS, large aggregates, big scans) run in parallel on other cores instead of
+     * blocking the data-process thread. `'auto'` sizes the pool to the host's core
+     * count (capped). `0` / `undefined` disables it. Ignored for `:memory:`.
+     * Default: disabled.
+     */
+    readerPoolSize?: number | 'auto';
+    /**
+     * Reads issued within this many milliseconds of the most recent commit route
+     * to the writer connection (read-your-writes safety) instead of the read-only
+     * connection / reader pool. WAL already makes committed writes visible across
+     * in-process connections, so the default `0` trusts WAL; raise it only if a
+     * platform shows stale cross-connection reads.
+     */
+    readYourWritesWindowMs?: number;
+}
+/**
+ * Point-in-time diagnostics for the Electron SQLite adapter (exploration 0230):
+ * scheduler queue depth, reader-pool occupancy, and WAL growth. Surfaced to the
+ * desktop diagnostics seam.
+ */
+interface ElectronSQLiteDiagnostics {
+    /** Scheduler lane depths + in-flight flag, or null when the scheduler is off. */
+    scheduler: {
+        interactive: number;
+        bulk: number;
+        write: number;
+        inFlight: boolean;
+    } | null;
+    /** Reader-thread pool occupancy, or null when no pool is configured. */
+    readerPool: {
+        size: number;
+        healthy: number;
+        inFlight: number;
+        dispatched: number;
+        failures: number;
+    } | null;
+    /** WAL file growth, or null when unavailable / not in WAL mode. */
+    wal: {
+        walBytes: number;
+        pageCount: number;
+    } | null;
+    /** Whether a read-only secondary connection is open. */
+    readonlyConnection: boolean;
+}
+/**
+ * Schema version information.
+ */
+interface SchemaVersion {
+    version: number;
+    appliedAt: number;
+}
+/**
+ * Runtime operation counters for diagnosing SQLite import performance.
+ *
+ * Counts are cumulative until reset by the adapter. Proxy-backed adapters can
+ * use `workerRequestCount` to show serialization-boundary pressure separately
+ * from the SQL statements executed by SQLite.
+ */
+interface SQLiteOperationStats {
+    /** SELECT statements returning many rows. */
+    queryCount: number;
+    /** SELECT statements returning at most one row. */
+    queryOneCount: number;
+    /** INSERT, UPDATE, DELETE, or other mutation statements. */
+    runCount: number;
+    /** Raw SQL executions, often schema or transaction control statements. */
+    execCount: number;
+    /** Callback transactions requested through this adapter. */
+    transactionCount: number;
+    /** Batch transactions requested through this adapter. */
+    transactionBatchCount: number;
+    /** SQL operations included in batch transactions. */
+    transactionBatchOperationCount: number;
+    /** Comlink or postMessage requests crossing into a worker. */
+    workerRequestCount: number;
+}
+type SQLiteNodeBatchIndexMode = 'eager' | 'touched' | 'defer-schema';
+interface SQLiteNodeBatchNodeRow {
+    id: string;
+    schemaId: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+    deletedAt: number | null;
+    propertyKeys: string[];
+}
+interface SQLiteNodeBatchPropertyRow {
+    nodeId: string;
+    propertyKey: string;
+    value: Uint8Array | null;
+    lamportTime: number;
+    updatedBy: string;
+    updatedAt: number;
+}
+interface SQLiteNodeBatchChangeRow {
+    hash: string;
+    nodeId: string;
+    payload: Uint8Array;
+    lamportTime: number;
+    lamportPeer: string;
+    wallTime: number;
+    author: string;
+    parentHash: string | null;
+    batchId: string | null;
+    signature: Uint8Array;
+}
+interface SQLiteNodeBatchScalarIndexRow {
+    nodeId: string;
+    schemaId: string;
+    propertyKey: string;
+    valueType: string;
+    valueText: string | null;
+    valueNumber: number | null;
+    valueBoolean: number | null;
+    valueHash: string | null;
+    updatedAt: number;
+    lamportTime: number;
+}
+interface SQLiteNodeBatchFtsRow {
+    nodeId: string;
+    title: string;
+    content: string;
+}
+interface SQLiteNodeBatchApplyInput {
+    nodes: SQLiteNodeBatchNodeRow[];
+    properties: SQLiteNodeBatchPropertyRow[];
+    changes: SQLiteNodeBatchChangeRow[];
+    scalarIndexRows: SQLiteNodeBatchScalarIndexRow[];
+    ftsNodeIds: string[];
+    ftsRows: SQLiteNodeBatchFtsRow[];
+    affectedSchemaIds: string[];
+    lastLamportTime: number;
+    indexMode: SQLiteNodeBatchIndexMode;
+}
+interface SQLiteNodeBatchApplyResult {
+    nodeRowsWritten: number;
+    propertyRowsWritten: number;
+    changeRowsWritten: number;
+    scalarRowsWritten: number;
+    ftsRowsWritten: number;
+}
+
+export type { ElectronSQLiteDiagnostics as E, RunResult as R, SQLValue as S, SQLRow as a, SQLiteConfig as b, SQLBatchRead as c, SchemaVersion as d, SQLiteOperationStats as e, SQLiteNodeBatchIndexMode as f, SQLiteNodeBatchNodeRow as g, SQLiteNodeBatchPropertyRow as h, SQLiteNodeBatchChangeRow as i, SQLiteNodeBatchScalarIndexRow as j, SQLiteNodeBatchFtsRow as k, SQLiteNodeBatchApplyInput as l, SQLiteNodeBatchApplyResult as m };

package/dist/worker-scheduler-D04DqMmR.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @xnetjs/sqlite - Priority scheduler for the single SQLite worker
+ *
+ * The web app funnels every storage operation — interactive reads, background
+ * writes, sync-apply batches — through ONE SQLite worker thread (exploration
+ * 0227). With no scheduling, the worker serves Comlink calls in arrival order,
+ * so an interactive read can be stuck behind a burst of queued writes. 0227
+ * fixed the one pathological 18s op; this scheduler generalises the fix so that
+ * *no* queued operation can starve an interactive read (exploration 0228).
+ *
+ * It does NOT add parallelism — a single OPFS connection is inherently serial
+ * (the `opfs-sahpool` VFS holds exclusive file handles, so multiple reader
+ * workers on the same DB are impossible). What it adds is **ordering**: queued
+ * work drains highest-priority-lane first, and identical concurrent reads are
+ * coalesced into a single execution.
+ *
+ * Safety: jobs run strictly one-at-a-time (no preemption of an in-flight op),
+ * which matches SQLite's single-connection serialization — operations on one
+ * connection are never truly concurrent anyway. A job already executing always
+ * completes before the next is dequeued.
+ */
+/** Priority lanes, drained in this order: interactive → bulk → write. */
+type SchedulerLane = 'interactive' | 'bulk' | 'write';
+/** Point-in-time view of scheduler depth (for diagnostics / the perf panel). */
+interface SchedulerSnapshot {
+    interactive: number;
+    bulk: number;
+    write: number;
+    /** Whether a job is currently executing. */
+    inFlight: boolean;
+}
+/** Aggregated per-lane op latency (exploration 0263). All ms values rounded. */
+interface SchedulerLaneOpStats {
+    /** Ops executed on this lane since open/reset. */
+    ops: number;
+    queueP50Ms: number;
+    queueP95Ms: number;
+    execP50Ms: number;
+    execP95Ms: number;
+    /** Worst single execution — the head-of-line-blocking amplitude. */
+    maxExecMs: number;
+}
+/**
+ * Cumulative scheduler statistics: how many ops ran, how many duplicate reads
+ * were served without executing (coalesced), and per-lane latency percentiles.
+ * This is the "p50/p95 per-query worker time" measurement of exploration 0263 —
+ * the number that says whether the statement cache / batch RPC actually moved
+ * anything, without wading through per-op boot-log lines.
+ */
+interface SchedulerOpStats {
+    ops: number;
+    coalescedHits: number;
+    lanes: Record<SchedulerLane, SchedulerLaneOpStats>;
+}
+
+export type { SchedulerSnapshot as S, SchedulerOpStats as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/sqlite",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Unified SQLite adapter for xNet across all platforms",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,10 @@
       "import": "./dist/adapters/web-worker.js",
       "types": "./dist/adapters/web-worker.d.ts"
     },
+    "./web-router-worker": {
+      "import": "./dist/adapters/web-router-worker.js",
+      "types": "./dist/adapters/web-router-worker.d.ts"
+    },
     "./browser-support": {
       "import": "./dist/browser-support.js",
       "types": "./dist/browser-support.d.ts"