@xnetjs/sqlite 0.0.2 → 0.1.0

package/dist/chunk-W3L4FXU5.js

@@ -0,0 +1,415 @@
+// src/schema.ts
+var SCHEMA_VERSION = 7;
+var SCHEMA_DDL_CORE = `
+-- ============================================
+-- Schema Version Tracking
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS _schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL
+);
+
+-- ============================================
+-- Core Tables
+-- ============================================
+
+-- All nodes (Pages, Databases, Rows, Comments, etc.)
+CREATE TABLE IF NOT EXISTS nodes (
+    id TEXT PRIMARY KEY,
+    schema_id TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    created_by TEXT NOT NULL,
+    deleted_at INTEGER
+);
+
+-- Node properties (LWW per-property)
+CREATE TABLE IF NOT EXISTS node_properties (
+    node_id TEXT NOT NULL,
+    property_key TEXT NOT NULL,
+    value BLOB,
+    lamport_time INTEGER NOT NULL,
+    updated_by TEXT NOT NULL,
+    updated_at INTEGER NOT NULL,
+
+    PRIMARY KEY (node_id, property_key),
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Rebuildable scalar property index for query planning.
+CREATE TABLE IF NOT EXISTS node_property_scalars (
+    node_id TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    property_key TEXT NOT NULL,
+    value_type TEXT NOT NULL,
+    value_text TEXT,
+    value_number REAL,
+    value_boolean INTEGER,
+    value_hash TEXT,
+    updated_at INTEGER NOT NULL,
+    lamport_time INTEGER NOT NULL,
+
+    PRIMARY KEY (schema_id, property_key, node_id),
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Query planner telemetry for adaptive read indexes.
+CREATE TABLE IF NOT EXISTS query_descriptor_stats (
+    descriptor_hash TEXT PRIMARY KEY,
+    schema_id TEXT NOT NULL,
+    descriptor_json TEXT NOT NULL,
+    hits INTEGER NOT NULL,
+    total_duration_ms REAL NOT NULL,
+    avg_duration_ms REAL NOT NULL,
+    avg_candidates REAL NOT NULL,
+    last_seen_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS query_index_candidates (
+    index_name TEXT PRIMARY KEY,
+    descriptor_hash TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    property_key TEXT NOT NULL,
+    value_type TEXT NOT NULL,
+    ddl TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    last_used_at INTEGER NOT NULL,
+    estimated_bytes INTEGER NOT NULL DEFAULT 0,
+    estimated_rows INTEGER NOT NULL DEFAULT 0,
+
+    FOREIGN KEY (descriptor_hash) REFERENCES query_descriptor_stats(descriptor_hash)
+        ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS node_query_materializations (
+    view_id TEXT PRIMARY KEY,
+    descriptor_hash TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    descriptor_json TEXT NOT NULL,
+    generated_at INTEGER NOT NULL,
+    invalidated_at INTEGER,
+    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 (
+    view_id TEXT NOT NULL,
+    ordinal INTEGER NOT NULL,
+    node_id TEXT NOT NULL,
+
+    PRIMARY KEY (view_id, ordinal),
+    UNIQUE (view_id, node_id),
+    FOREIGN KEY (view_id) REFERENCES node_query_materializations(view_id)
+        ON DELETE CASCADE,
+    FOREIGN KEY (node_id) REFERENCES nodes(id)
+        ON DELETE CASCADE
+);
+
+-- Change log (event sourcing)
+CREATE TABLE IF NOT EXISTS changes (
+    hash TEXT PRIMARY KEY,
+    node_id TEXT NOT NULL,
+    payload BLOB NOT NULL,
+    lamport_time INTEGER NOT NULL,
+    lamport_peer TEXT NOT NULL,
+    wall_time INTEGER NOT NULL,
+    author TEXT NOT NULL,
+    parent_hash TEXT,
+    batch_id TEXT,
+    signature BLOB NOT NULL,
+
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Y.Doc binary state (for nodes with collaborative content)
+CREATE TABLE IF NOT EXISTS yjs_state (
+    node_id TEXT PRIMARY KEY,
+    state BLOB NOT NULL,
+    updated_at INTEGER NOT NULL,
+
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Y.Doc incremental updates (for sync)
+CREATE TABLE IF NOT EXISTS yjs_updates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id TEXT NOT NULL,
+    update_data BLOB NOT NULL,
+    timestamp INTEGER NOT NULL,
+    origin TEXT,
+
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Yjs snapshots (for document time travel)
+CREATE TABLE IF NOT EXISTS yjs_snapshots (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id TEXT NOT NULL,
+    timestamp INTEGER NOT NULL,
+    snapshot BLOB NOT NULL,
+    doc_state BLOB NOT NULL,
+    byte_size INTEGER NOT NULL,
+
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Blobs (content-addressed)
+CREATE TABLE IF NOT EXISTS blobs (
+    cid TEXT PRIMARY KEY,
+    data BLOB NOT NULL,
+    mime_type TEXT,
+    size INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    reference_count INTEGER DEFAULT 1
+);
+
+-- Documents (for @xnetjs/storage compatibility)
+CREATE TABLE IF NOT EXISTS documents (
+    id TEXT PRIMARY KEY,
+    content BLOB NOT NULL,
+    metadata TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+);
+
+-- Signed updates (for @xnetjs/storage compatibility)
+CREATE TABLE IF NOT EXISTS updates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    doc_id TEXT NOT NULL,
+    update_hash TEXT NOT NULL,
+    update_data TEXT NOT NULL,
+    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+    UNIQUE(doc_id, update_hash)
+);
+
+-- Snapshots (for @xnetjs/storage compatibility)
+CREATE TABLE IF NOT EXISTS snapshots (
+    doc_id TEXT PRIMARY KEY,
+    snapshot_data TEXT NOT NULL,
+    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- Sync metadata
+CREATE TABLE IF NOT EXISTS sync_state (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+-- ============================================
+-- Indexes
+-- ============================================
+
+CREATE INDEX IF NOT EXISTS idx_nodes_schema ON nodes(schema_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_updated ON nodes(updated_at);
+CREATE INDEX IF NOT EXISTS idx_nodes_created_by ON nodes(created_by);
+CREATE INDEX IF NOT EXISTS idx_nodes_deleted ON nodes(deleted_at);
+CREATE INDEX IF NOT EXISTS idx_nodes_live_schema_updated
+    ON nodes(schema_id, updated_at DESC, id)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_nodes_all_schema_updated
+    ON nodes(schema_id, updated_at DESC, id);
+CREATE INDEX IF NOT EXISTS idx_nodes_live_schema_created
+    ON nodes(schema_id, created_at DESC, id)
+    WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_properties_node ON node_properties(node_id);
+CREATE INDEX IF NOT EXISTS idx_properties_lamport ON node_properties(lamport_time);
+
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_text
+    ON node_property_scalars(schema_id, property_key, value_text, node_id)
+    WHERE value_type = 'text';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_number
+    ON node_property_scalars(schema_id, property_key, value_number, node_id)
+    WHERE value_type = 'number';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_boolean
+    ON node_property_scalars(schema_id, property_key, value_boolean, node_id)
+    WHERE value_type = 'boolean';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_null
+    ON node_property_scalars(schema_id, property_key, node_id)
+    WHERE value_type = 'null';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_node
+    ON node_property_scalars(node_id);
+
+CREATE INDEX IF NOT EXISTS idx_query_stats_schema_seen
+    ON query_descriptor_stats(schema_id, last_seen_at DESC);
+CREATE INDEX IF NOT EXISTS idx_query_indexes_schema_property
+    ON query_index_candidates(schema_id, property_key, value_type);
+CREATE INDEX IF NOT EXISTS idx_query_materializations_schema
+    ON node_query_materializations(schema_id, invalidated_at);
+CREATE INDEX IF NOT EXISTS idx_query_materialized_ids_node
+    ON node_query_materialized_ids(node_id);
+
+CREATE INDEX IF NOT EXISTS idx_changes_node ON changes(node_id);
+CREATE INDEX IF NOT EXISTS idx_changes_lamport ON changes(lamport_time);
+CREATE INDEX IF NOT EXISTS idx_changes_wall_time ON changes(wall_time);
+CREATE INDEX IF NOT EXISTS idx_changes_batch ON changes(batch_id);
+CREATE INDEX IF NOT EXISTS idx_changes_node_lamport
+    ON changes(node_id, lamport_time DESC, hash);
+
+CREATE INDEX IF NOT EXISTS idx_yjs_state_updated ON yjs_state(updated_at);
+CREATE INDEX IF NOT EXISTS idx_yjs_updates_node ON yjs_updates(node_id);
+CREATE INDEX IF NOT EXISTS idx_yjs_snapshots_node ON yjs_snapshots(node_id);
+CREATE INDEX IF NOT EXISTS idx_yjs_snapshots_timestamp ON yjs_snapshots(node_id, timestamp);
+
+CREATE INDEX IF NOT EXISTS idx_updates_doc ON updates(doc_id);
+CREATE INDEX IF NOT EXISTS idx_updates_created ON updates(created_at);
+`;
+var SCHEMA_DDL_FTS = `
+-- ============================================
+-- Full-Text Search (FTS5)
+-- ============================================
+
+-- FTS index for searchable node content
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+    node_id,
+    title,
+    content,
+    tokenize='porter unicode61'
+);
+
+-- Triggers to keep FTS in sync will be managed by application layer
+-- since the searchable content is derived from node properties
+`;
+var SCHEMA_DDL = SCHEMA_DDL_CORE + SCHEMA_DDL_FTS;
+var SCHEMA_MIGRATIONS = {
+  2: `
+CREATE TABLE IF NOT EXISTS node_property_scalars (
+    node_id TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    property_key TEXT NOT NULL,
+    value_type TEXT NOT NULL,
+    value_text TEXT,
+    value_number REAL,
+    value_boolean INTEGER,
+    value_hash TEXT,
+    updated_at INTEGER NOT NULL,
+    lamport_time INTEGER NOT NULL,
+
+    PRIMARY KEY (schema_id, property_key, node_id),
+    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_live_schema_updated
+    ON nodes(schema_id, updated_at DESC, id)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_nodes_all_schema_updated
+    ON nodes(schema_id, updated_at DESC, id);
+CREATE INDEX IF NOT EXISTS idx_nodes_live_schema_created
+    ON nodes(schema_id, created_at DESC, id)
+    WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_text
+    ON node_property_scalars(schema_id, property_key, value_text, node_id)
+    WHERE value_type = 'text';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_number
+    ON node_property_scalars(schema_id, property_key, value_number, node_id)
+    WHERE value_type = 'number';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_boolean
+    ON node_property_scalars(schema_id, property_key, value_boolean, node_id)
+    WHERE value_type = 'boolean';
+CREATE INDEX IF NOT EXISTS idx_prop_scalars_null
+    ON node_property_scalars(schema_id, property_key, node_id)
+    WHERE value_type = 'null';
+`,
+  3: `
+CREATE TABLE IF NOT EXISTS query_descriptor_stats (
+    descriptor_hash TEXT PRIMARY KEY,
+    schema_id TEXT NOT NULL,
+    descriptor_json TEXT NOT NULL,
+    hits INTEGER NOT NULL,
+    total_duration_ms REAL NOT NULL,
+    avg_duration_ms REAL NOT NULL,
+    avg_candidates REAL NOT NULL,
+    last_seen_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS query_index_candidates (
+    index_name TEXT PRIMARY KEY,
+    descriptor_hash TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    property_key TEXT NOT NULL,
+    value_type TEXT NOT NULL,
+    ddl TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    last_used_at INTEGER NOT NULL,
+    estimated_bytes INTEGER NOT NULL DEFAULT 0,
+    estimated_rows INTEGER NOT NULL DEFAULT 0,
+
+    FOREIGN KEY (descriptor_hash) REFERENCES query_descriptor_stats(descriptor_hash)
+        ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_query_stats_schema_seen
+    ON query_descriptor_stats(schema_id, last_seen_at DESC);
+CREATE INDEX IF NOT EXISTS idx_query_indexes_schema_property
+    ON query_index_candidates(schema_id, property_key, value_type);
+`,
+  4: `
+ALTER TABLE query_index_candidates
+    ADD COLUMN estimated_bytes INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE query_index_candidates
+    ADD COLUMN estimated_rows INTEGER NOT NULL DEFAULT 0;
+`,
+  5: `
+CREATE TABLE IF NOT EXISTS node_query_materializations (
+    view_id TEXT PRIMARY KEY,
+    descriptor_hash TEXT NOT NULL,
+    schema_id TEXT NOT NULL,
+    descriptor_json TEXT NOT NULL,
+    generated_at INTEGER NOT NULL,
+    invalidated_at INTEGER,
+    row_count INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS node_query_materialized_ids (
+    view_id TEXT NOT NULL,
+    ordinal INTEGER NOT NULL,
+    node_id TEXT NOT NULL,
+
+    PRIMARY KEY (view_id, ordinal),
+    UNIQUE (view_id, node_id),
+    FOREIGN KEY (view_id) REFERENCES node_query_materializations(view_id)
+        ON DELETE CASCADE,
+    FOREIGN KEY (node_id) REFERENCES nodes(id)
+        ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_query_materializations_schema
+    ON node_query_materializations(schema_id, invalidated_at);
+CREATE INDEX IF NOT EXISTS idx_query_materialized_ids_node
+    ON node_query_materialized_ids(node_id);
+`,
+  6: `
+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) {
+  const statements = [];
+  for (let v = fromVersion + 1; v <= toVersion; v++) {
+    const migration = SCHEMA_MIGRATIONS[v];
+    if (migration) {
+      statements.push(migration);
+    }
+  }
+  return statements.join("\n");
+}
+
+export {
+  SCHEMA_VERSION,
+  SCHEMA_DDL_CORE,
+  SCHEMA_DDL_FTS,
+  SCHEMA_DDL,
+  SCHEMA_MIGRATIONS,
+  getMigrationSQL
+};

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { S as SQLValue } from './types-C_aHfRDF.js';
-export { R as RunResult, a as SQLRow, b as SQLiteConfig, c as SchemaVersion } from './types-C_aHfRDF.js';
-import { S as SQLiteAdapter } from './adapter-I7yAV6iu.js';
-export { P as PreparedStatement } from './adapter-I7yAV6iu.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-CjkXTqxn.js';
-export { BrowserSupport, checkBrowserSupport, showUnsupportedBrowserMessage } 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
@@ -156,8 +156,15 @@ interface DatabaseStats {
     walMode: boolean;
     foreignKeys: boolean;
 }
+interface SQLiteRuntimeCapabilities {
+    fts5: boolean;
+    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[]>;
 /**
@@ -180,6 +187,13 @@ declare function getAllTableStats(db: SQLiteAdapter): Promise<TableStats[]>;
  * Get overall database statistics.
  */
 declare function getDatabaseStats(db: SQLiteAdapter): Promise<DatabaseStats>;
+/**
+ * Detect optional SQLite virtual table modules for the active runtime.
+ *
+ * xNet runs against multiple SQLite implementations, so feature availability
+ * must be probed at runtime rather than inferred from platform.
+ */
+declare function detectSQLiteCapabilities(db: SQLiteAdapter): Promise<SQLiteRuntimeCapabilities>;
 /**
  * Run ANALYZE to update query planner statistics.
  */
@@ -204,4 +218,93 @@ declare function timeQuery<T>(db: SQLiteAdapter, sql: string, params?: SQLValue[
     rowCount: number;
 }>;
 
-export { type DatabaseStats, type FTSSearchOptions, type FTSSearchResult, type IndexInfo, type QueryPlanStep, SQLValue, SQLiteAdapter, type TableStats, analyzeQuery, analyzeTable, buildBatchInsert, buildInsert, buildSelect, buildUpdate, checkIntegrity, deleteNodeFTS, escapeLike, explainQuery, extractSearchableContent, extractTextFromTipTap, getAllTableStats, getDatabaseStats, getIndexInfo, optimizeFTS, rebuildFTS, runAnalyze, searchNodes, timeQuery, updateNodeFTS };
+/**
+ * SQLite error classification helpers.
+ */
+/**
+ * Return true when an error represents a malformed or unreadable SQLite file.
+ */
+declare function isSQLiteCorruptionError(error: unknown): boolean;
+
+/**
+ * @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 };