@xnetjs/sqlite 0.0.3 → 0.1.0

package/dist/adapters/web-router-worker.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @xnetjs/sqlite - SharedWorker router for multi-tab SQLite (exploration 0263)
+ *
+ * A deliberately tiny message ferry, NOT a database host: SharedWorkers cannot
+ * use OPFS sync access handles, so SQLite itself stays in the leader tab's
+ * dedicated worker. This router only (a) remembers which tab is the current
+ * leader and (b) ferries `MessagePort`s from the leader to follower tabs — the
+ * same role the SharedWorker plays in Notion's and wa-sqlite's (discussion #81)
+ * multi-tab architectures.
+ *
+ * Leadership itself is decided by `navigator.locks` in the tabs (web-leader.ts);
+ * the router never elects anyone. When a tab announces `leader-ready` it simply
+ * replaces the previous leader registration and followers are told to
+ * re-request their DB port.
+ *
+ * The message handler is exported as a pure function over an explicit state
+ * object so it can be unit-tested in Node without a real SharedWorker
+ * (mirroring the reader-thread.ts pattern).
+ */
+/** A follower's request for a DB port, waiting on the leader's response. */
+interface PendingPortRequest {
+    requesterPort: RouterClientPort;
+    requestId: string;
+}
+/** The subset of MessagePort the router needs (test seam). */
+interface RouterClientPort {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+/** Messages a tab sends to the router. */
+type RouterInbound = {
+    t: 'leader-ready';
+} | {
+    t: 'request-db-port';
+    requestId: string;
+} | {
+    t: 'db-port';
+    requestId: string;
+} | {
+    t: 'db-port-failed';
+    requestId: string;
+    error: string;
+};
+/** Messages the router sends to a tab. */
+type RouterOutbound = {
+    t: 'mint-db-port';
+    requestId: string;
+} | {
+    t: 'db-port';
+    requestId: string;
+} | {
+    t: 'db-port-failed';
+    requestId: string;
+    error: string;
+} | {
+    t: 'no-leader';
+    requestId: string;
+} | {
+    t: 'leader-changed';
+};
+interface RouterState {
+    leader: RouterClientPort | null;
+    /** Every connected tab port, for leader-changed broadcasts. */
+    clients: Set<RouterClientPort>;
+    /** Port requests forwarded to the leader, awaiting its minted port. */
+    pending: Map<string, PendingPortRequest>;
+}
+declare function createRouterState(): RouterState;
+/** Register a newly connected tab port. */
+declare function addRouterClient(state: RouterState, port: RouterClientPort): void;
+/**
+ * Dispatch one inbound message. `ports` carries any transferred MessagePorts
+ * (the leader's minted DB port rides `db-port` messages).
+ */
+declare function handleRouterMessage(state: RouterState, sender: RouterClientPort, message: RouterInbound, ports?: readonly Transferable[]): void;
+
+export { type RouterClientPort, type RouterInbound, type RouterOutbound, type RouterState, addRouterClient, createRouterState, handleRouterMessage };

package/dist/adapters/web-router-worker.js

@@ -0,0 +1,91 @@
+// src/adapters/web-router-worker.ts
+function createRouterState() {
+  return { leader: null, clients: /* @__PURE__ */ new Set(), pending: /* @__PURE__ */ new Map() };
+}
+function addRouterClient(state, port) {
+  state.clients.add(port);
+}
+function handleRouterMessage(state, sender, message, ports = []) {
+  switch (message.t) {
+    case "leader-ready": {
+      const previous = state.leader;
+      state.leader = sender;
+      if (previous !== null && previous !== sender) {
+        for (const client of state.clients) {
+          if (client !== sender) {
+            safePost(client, { t: "leader-changed" });
+          }
+        }
+      }
+      return;
+    }
+    case "request-db-port": {
+      if (!state.leader) {
+        safePost(sender, { t: "no-leader", requestId: message.requestId });
+        return;
+      }
+      state.pending.set(message.requestId, { requesterPort: sender, requestId: message.requestId });
+      safePost(state.leader, {
+        t: "mint-db-port",
+        requestId: message.requestId
+      });
+      return;
+    }
+    case "db-port": {
+      const pending = state.pending.get(message.requestId);
+      if (!pending) return;
+      state.pending.delete(message.requestId);
+      const [port] = ports;
+      if (port === void 0) {
+        safePost(pending.requesterPort, {
+          t: "db-port-failed",
+          requestId: message.requestId,
+          error: "leader response carried no port"
+        });
+        return;
+      }
+      pending.requesterPort.postMessage(
+        { t: "db-port", requestId: message.requestId },
+        [port]
+      );
+      return;
+    }
+    case "db-port-failed": {
+      const pending = state.pending.get(message.requestId);
+      if (!pending) return;
+      state.pending.delete(message.requestId);
+      safePost(pending.requesterPort, {
+        t: "db-port-failed",
+        requestId: message.requestId,
+        error: message.error
+      });
+      return;
+    }
+  }
+}
+function safePost(port, message) {
+  try {
+    port.postMessage(message);
+  } catch {
+  }
+}
+function bootstrapRouter() {
+  const scope = globalThis;
+  if (typeof scope.SharedWorkerGlobalScope === "undefined") return;
+  const state = createRouterState();
+  scope.onconnect = (event) => {
+    const port = event.ports[0];
+    if (!port) return;
+    addRouterClient(state, port);
+    port.onmessage = (msg) => {
+      handleRouterMessage(state, port, msg.data, msg.ports);
+    };
+    port.start?.();
+  };
+}
+bootstrapRouter();
+export {
+  addRouterClient,
+  createRouterState,
+  handleRouterMessage
+};

package/dist/adapters/web-worker.d.ts

@@ -1,4 +1,5 @@
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, k as SQLiteNodeBatchApplyInput, l as SQLiteNodeBatchApplyResult } from '../types-DMrj3K4o.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, c as SQLBatchRead, R as RunResult, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult } from '../types-BTabr_VP.js';
+import { S as SchedulerSnapshot, a as SchedulerOpStats } from '../worker-scheduler-D04DqMmR.js';
 
 /**
  * @xnetjs/sqlite - Web Worker entry point for SQLite WASM
@@ -12,12 +13,38 @@ import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, k as SQL
  */
 declare class SQLiteWorkerHandler {
     private adapter;
+    private bootDebug;
+    private openedAtMs;
+    private firstOpReported;
+    private readonly scheduler;
     open(config: SQLiteConfig): Promise<void>;
+    /**
+     * Emit the open-phase split (exploration 0253). Until now the whole open lived
+     * in the boot-timeline's opaque `wasm` bucket (init:start → sqlite:open); this
+     * breaks it into wasm import/init, OPFS VFS install (+ lock retries), capacity
+     * reserve, db open, pragmas and schema apply — so the dominant sub-phase of a
+     * slow open is named in one line. Never throws.
+     */
+    private logOpenPhases;
+    /**
+     * One-shot DB stats at open (exploration 0229): file size, page/freelist
+     * counts, storage mode. File size is the key signal for the bloat hypothesis
+     * (a giant pre-0227 presence blob inflating cold-read cost). Never throws.
+     */
+    private logDbStats;
     resetStorage(config: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
     isOpen(): boolean;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    /**
+     * Execute a batch of reads as ONE scheduled job — one RPC, one queue slot —
+     * instead of one round-trip per query (exploration 0263). The batch runs on
+     * the interactive lane uncoalesced: its members are heterogeneous, so a
+     * batch-level coalesce key would rarely hit, and member-level coalescing
+     * would let other jobs interleave mid-batch.
+     */
+    queryBatch(reads: SQLBatchRead[]): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     transaction(operations: Array<{
@@ -27,6 +54,13 @@ declare class SQLiteWorkerHandler {
     applyNodeBatch(input: SQLiteNodeBatchApplyInput): Promise<SQLiteNodeBatchApplyResult>;
     getSchemaVersion(): Promise<number>;
     vacuum(): Promise<void>;
+    incrementalVacuum(maxPages?: number): Promise<number>;
+    /** Current scheduler queue depths (diagnostics / the perf panel). */
+    getSchedulerSnapshot(): Promise<SchedulerSnapshot>;
+    /** Cumulative per-lane op latency percentiles + coalesce hits (0263). */
+    getSchedulerOpStats(): Promise<SchedulerOpStats>;
+    /** Zero the op-stats counters for a focused before/after measurement. */
+    resetSchedulerOpStats(): Promise<void>;
     getDatabaseSize(): Promise<number>;
     getStorageMode(): Promise<'opfs' | 'memory'>;
     /**
@@ -38,6 +72,16 @@ declare class SQLiteWorkerHandler {
      * `WebSQLiteProxy.createMessagePort()` and transferred to the peer.
      */
     connectPort(port: MessagePort): void;
+    /**
+     * PowerSync-style lease recovery (exploration 0263): a client that died
+     * between a manual BEGIN and its COMMIT leaves the shared connection stuck
+     * in a transaction, wedging every other client's writes. When a NEW client
+     * connects, roll back any transaction that has been idle long enough that
+     * its owner is clearly gone. Batch APIs (`transaction`, `applyNodeBatch`)
+     * are single-RPC and can never be abandoned — this only covers the manual
+     * BEGIN…COMMIT path.
+     */
+    private scheduleAbandonedTransactionRecovery;
 }
 
 export { SQLiteWorkerHandler };

package/dist/adapters/web-worker.js

@@ -1,12 +1,38 @@
+import {
+  WorkerScheduler,
+  firstOpGapFields
+} from "../chunk-5HC5V73T.js";
 import {
   createWebSQLiteAdapter,
   resetWebSQLiteOpfsStorage
-} from "../chunk-DCY4LAUD.js";
+} from "../chunk-BBZDKLA3.js";
+import "../chunk-SV475UL5.js";
+import {
+  bootLogMessage
+} from "../chunk-CGI2YBZY.js";
 import "../chunk-CBU263LI.js";
-import "../chunk-NVD7G7DZ.js";
+import "../chunk-W3L4FXU5.js";
 
 // src/adapters/web-worker.ts
 import * as Comlink from "comlink";
+function readKey(op, sql, params) {
+  return `${op}\0${sql}\0${params ? JSON.stringify(params) : ""}`;
+}
+function emitBootLog(...args) {
+  console.info(...args);
+  try {
+    const scope = self;
+    scope.postMessage(bootLogMessage(args));
+  } catch {
+  }
+}
+function sqlDetail(sql) {
+  const flat = sql.replace(/\s+/g, " ").trim();
+  return flat.length > 160 ? `${flat.slice(0, 157)}\u2026` : flat;
+}
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
 function isDebugEnabled() {
   return typeof self !== "undefined" && typeof localStorage !== "undefined" && localStorage.getItem("xnet:sqlite:debug") === "true";
 }
@@ -18,13 +44,93 @@ function log(...args) {
 log("[SQLiteWorker] Worker script loaded, Comlink imported");
 var SQLiteWorkerHandler = class {
   adapter = null;
+  // Boot diagnostics flag (exploration 0229) — workers have no localStorage, so
+  // the main thread passes this in via the open config.
+  bootDebug = false;
+  // Monotonic time `open()` finished (exploration 0253). Lets the first scheduled
+  // op report how long the worker sat idle after open() before any op arrived
+  // (`idleBeforeFirstOpMs`) — the upstream/transport wait that queueMs/execMs both
+  // miss, and where the 17 s relocated once it left `execMs`.
+  openedAtMs = 0;
+  // One-shot latch so only the FIRST op after open carries the gap measurements.
+  firstOpReported = false;
+  // All storage work funnels through one priority scheduler so a queued write
+  // burst can never starve an interactive read (exploration 0228). The same
+  // handler instance is exposed on every port (main thread + data worker), so
+  // this one scheduler orders work globally across all clients. When boot debug
+  // is on, each op logs its queue-wait vs execution time — the split that
+  // finally localizes the boot stall to a single operation (exploration 0229).
+  scheduler = new WorkerScheduler((report) => {
+    if (!this.bootDebug) return;
+    const firstOp = !this.firstOpReported && this.openedAtMs > 0;
+    if (firstOp) this.firstOpReported = true;
+    emitBootLog("[xNet] sqlite op", report.label ?? report.lane, {
+      lane: report.lane,
+      // The SQL text (params omitted) names which op a long execMs belongs to —
+      // the missing field that kept the cold-open stall unidentified (0249).
+      ...report.detail ? { sql: report.detail } : {},
+      queueMs: Math.round(report.queueMs),
+      execMs: Math.round(report.execMs),
+      ...firstOp ? firstOpGapFields(report, this.openedAtMs) : {}
+    });
+  });
   async open(config) {
     log("[SQLiteWorkerHandler] open() called with config:", config);
     if (this.adapter) {
       throw new Error("Database already open");
     }
+    this.bootDebug = config.bootDebug ?? false;
     this.adapter = await createWebSQLiteAdapter(config);
+    this.openedAtMs = nowMs();
     log("[SQLiteWorkerHandler] open() completed");
+    if (this.bootDebug) {
+      this.logOpenPhases();
+      await this.logDbStats();
+    }
+  }
+  /**
+   * Emit the open-phase split (exploration 0253). Until now the whole open lived
+   * in the boot-timeline's opaque `wasm` bucket (init:start → sqlite:open); this
+   * breaks it into wasm import/init, OPFS VFS install (+ lock retries), capacity
+   * reserve, db open, pragmas and schema apply — so the dominant sub-phase of a
+   * slow open is named in one line. Never throws.
+   */
+  logOpenPhases() {
+    if (!this.adapter) return;
+    try {
+      const phases = this.adapter.getOpenPhaseTimings();
+      if (!phases) return;
+      emitBootLog("[xNet] sqlite open phases", {
+        ...phases,
+        schemaApplyMs: this.adapter.schemaApplyMs,
+        retryAttempts: this.adapter.openRetryAttempts,
+        mode: this.adapter.getStorageMode()
+      });
+    } catch {
+    }
+  }
+  /**
+   * One-shot DB stats at open (exploration 0229): file size, page/freelist
+   * counts, storage mode. File size is the key signal for the bloat hypothesis
+   * (a giant pre-0227 presence blob inflating cold-read cost). Never throws.
+   */
+  async logDbStats() {
+    if (!this.adapter) return;
+    try {
+      const [bytes, mode, pageCount, freelist] = await Promise.all([
+        this.adapter.getDatabaseSize(),
+        this.adapter.getStorageMode(),
+        this.adapter.queryOne("PRAGMA page_count"),
+        this.adapter.queryOne("PRAGMA freelist_count")
+      ]);
+      emitBootLog("[xNet] db stats @ open", {
+        bytes,
+        mode,
+        pageCount: pageCount?.page_count,
+        freelistCount: freelist?.freelist_count
+      });
+    } catch {
+    }
   }
   async resetStorage(config) {
     if (this.adapter) {
@@ -34,41 +140,101 @@ var SQLiteWorkerHandler = class {
     await resetWebSQLiteOpfsStorage(config);
   }
   async close() {
-    if (this.adapter) {
-      await this.adapter.close();
-      this.adapter = null;
-    }
+    if (!this.adapter) return;
+    return this.scheduler.schedule(
+      "write",
+      async () => {
+        if (this.adapter) {
+          await this.adapter.close();
+          this.adapter = null;
+        }
+      },
+      void 0,
+      "close"
+    );
   }
   isOpen() {
     return this.adapter?.isOpen() ?? false;
   }
   async query(sql, params) {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.query(sql, params);
+    return this.scheduler.schedule(
+      "interactive",
+      () => this.adapter.query(sql, params),
+      readKey("query", sql, params),
+      "query",
+      sqlDetail(sql)
+    );
   }
   async queryOne(sql, params) {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.queryOne(sql, params);
+    return this.scheduler.schedule(
+      "interactive",
+      () => this.adapter.queryOne(sql, params),
+      readKey("queryOne", sql, params),
+      "queryOne",
+      sqlDetail(sql)
+    );
+  }
+  /**
+   * Execute a batch of reads as ONE scheduled job — one RPC, one queue slot —
+   * instead of one round-trip per query (exploration 0263). The batch runs on
+   * the interactive lane uncoalesced: its members are heterogeneous, so a
+   * batch-level coalesce key would rarely hit, and member-level coalescing
+   * would let other jobs interleave mid-batch.
+   */
+  async queryBatch(reads) {
+    if (!this.adapter) throw new Error("Database not open");
+    if (reads.length === 0) return [];
+    return this.scheduler.schedule(
+      "interactive",
+      () => this.adapter.queryBatch(reads),
+      void 0,
+      "queryBatch",
+      `${reads.length} reads: ${sqlDetail(reads[0].sql)}`
+    );
   }
   async run(sql, params) {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.run(sql, params);
+    return this.scheduler.schedule(
+      "write",
+      () => this.adapter.run(sql, params),
+      void 0,
+      "run",
+      sqlDetail(sql)
+    );
   }
   async exec(sql) {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.exec(sql);
+    return this.scheduler.schedule(
+      "write",
+      () => this.adapter.exec(sql),
+      void 0,
+      "exec",
+      sqlDetail(sql)
+    );
   }
   async transaction(operations) {
     if (!this.adapter) throw new Error("Database not open");
-    await this.adapter.transaction(async () => {
-      for (const op of operations) {
-        await this.adapter.run(op.sql, op.params);
-      }
-    });
+    return this.scheduler.schedule(
+      "write",
+      () => this.adapter.transaction(async () => {
+        for (const op of operations) {
+          await this.adapter.run(op.sql, op.params);
+        }
+      }),
+      void 0,
+      "transaction"
+    );
   }
   async applyNodeBatch(input) {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.applyNodeBatch(input);
+    return this.scheduler.schedule(
+      "write",
+      () => this.adapter.applyNodeBatch(input),
+      void 0,
+      "applyNodeBatch"
+    );
   }
   async getSchemaVersion() {
     if (!this.adapter) throw new Error("Database not open");
@@ -76,7 +242,28 @@ var SQLiteWorkerHandler = class {
   }
   async vacuum() {
     if (!this.adapter) throw new Error("Database not open");
-    return this.adapter.vacuum();
+    return this.scheduler.schedule("write", () => this.adapter.vacuum(), void 0, "vacuum");
+  }
+  async incrementalVacuum(maxPages) {
+    if (!this.adapter) throw new Error("Database not open");
+    return this.scheduler.schedule(
+      "write",
+      () => this.adapter.incrementalVacuum(maxPages),
+      void 0,
+      "incremental_vacuum"
+    );
+  }
+  /** Current scheduler queue depths (diagnostics / the perf panel). */
+  async getSchedulerSnapshot() {
+    return this.scheduler.snapshot();
+  }
+  /** Cumulative per-lane op latency percentiles + coalesce hits (0263). */
+  async getSchedulerOpStats() {
+    return this.scheduler.opStats();
+  }
+  /** Zero the op-stats counters for a focused before/after measurement. */
+  async resetSchedulerOpStats() {
+    this.scheduler.resetOpStats();
   }
   async getDatabaseSize() {
     if (!this.adapter) throw new Error("Database not open");
@@ -96,8 +283,36 @@ var SQLiteWorkerHandler = class {
    */
   connectPort(port) {
     Comlink.expose(this, port);
+    this.scheduleAbandonedTransactionRecovery();
+  }
+  /**
+   * PowerSync-style lease recovery (exploration 0263): a client that died
+   * between a manual BEGIN and its COMMIT leaves the shared connection stuck
+   * in a transaction, wedging every other client's writes. When a NEW client
+   * connects, roll back any transaction that has been idle long enough that
+   * its owner is clearly gone. Batch APIs (`transaction`, `applyNodeBatch`)
+   * are single-RPC and can never be abandoned — this only covers the manual
+   * BEGIN…COMMIT path.
+   */
+  scheduleAbandonedTransactionRecovery() {
+    void this.scheduler.schedule(
+      "write",
+      async () => {
+        const adapter = this.adapter;
+        if (!adapter || !adapter.isInTransaction()) return;
+        if (adapter.transactionIdleMs() < ABANDONED_TRANSACTION_IDLE_MS) return;
+        console.warn(
+          "[SQLiteWorkerHandler] Rolling back an abandoned transaction \u2014 a client likely died between BEGIN and COMMIT (0263 lease recovery)."
+        );
+        await adapter.rollback();
+      },
+      void 0,
+      "txn-recovery"
+    ).catch(() => {
+    });
   }
 };
+var ABANDONED_TRANSACTION_IDLE_MS = 5e3;
 var handler = new SQLiteWorkerHandler();
 log("[SQLiteWorker] Handler instance created");
 log("[SQLiteWorker] Exposing handler via Comlink...");

package/dist/adapters/web.d.ts

@@ -1,5 +1,5 @@
-import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-t2aqQ__n.js';
-import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, k as SQLiteNodeBatchApplyInput, l as SQLiteNodeBatchApplyResult } from '../types-DMrj3K4o.js';
+import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-imtxkmXZ.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, c as SQLBatchRead, R as RunResult, l as SQLiteNodeBatchApplyInput, m as SQLiteNodeBatchApplyResult } from '../types-BTabr_VP.js';
 
 /**
  * @xnetjs/sqlite - Web SQLite adapter using @sqlite.org/sqlite-wasm
@@ -8,6 +8,30 @@ import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult, k as SQL
  * Must run in a Web Worker for OPFS access.
  */
 
+/**
+ * Per-phase timing of {@link WebSQLiteAdapter.open}. Every prior cold-open
+ * exploration (0204→0249) timed the layer the stall was *in*, so the cost kept
+ * hopping to the next un-timed layer; by the 0253 capture both `queueMs` and
+ * `execMs` read 0 and the ~17 s lived entirely in this `open()` window, which no
+ * timer bracketed. These fields split it so the dominant sub-phase is named in
+ * one boot-log line. All durations are milliseconds, rounded.
+ */
+interface OpenPhaseTimings {
+    /** Dynamic `import('@sqlite.org/sqlite-wasm')` (bundle parse/download). */
+    wasmImportMs: number;
+    /** `sqlite3InitModule()` — WASM instantiate. */
+    wasmInitMs: number;
+    /** `installOpfsSAHPoolVfs()` — acquires the pool's sync access handles; INCLUDES any lock-retry backoff. */
+    vfsInstallMs: number;
+    /** `reserveMinimumCapacity()` — may acquire more handles / grow the pool. */
+    reserveCapacityMs: number;
+    /** `new OpfsSAHPoolDb()` — open the database file in the pool. */
+    dbOpenMs: number;
+    /** All post-open `PRAGMA` settings (page_size/cache/mmap/journal/…). */
+    pragmasMs: number;
+    /** Whole `open()` span (import → last pragma). */
+    totalOpenMs: number;
+}
 /**
  * Remove xNet's OPFS-backed SQLite storage for the supplied database path.
  *
@@ -40,13 +64,53 @@ declare class WebSQLiteAdapter implements SQLiteAdapter {
     private poolUtil;
     private _config;
     private inTransaction;
+    /**
+     * Monotonic time of the open transaction's last operation. Lets the worker
+     * host distinguish a LIVE manual transaction from one abandoned by a client
+     * that died between BEGIN and COMMIT (PowerSync-style lease recovery, 0263).
+     */
+    private lastTransactionActivityAt;
     private storageMode;
+    /**
+     * Per-phase timing of the last {@link open} call, or null until it runs.
+     * Read by the worker host to emit `[xNet] sqlite open phases` (exploration
+     * 0253). Diagnostic only — never affects behaviour.
+     */
+    private openPhaseTimings;
+    /** ms spent in `applySchema()` during {@link createWebSQLiteAdapter}, for the open-phases line. */
+    schemaApplyMs: number;
+    /** How many times the OPFS lock-retry backoff fired during the last {@link open} (0 = first try). */
+    openRetryAttempts: number;
+    /**
+     * Prepared-statement LRU for the hot query/run path (exploration 0263).
+     * `db.exec()` re-parses the SQL on every call; the hot path repeats a small
+     * statement set, so cached `oo1.Stmt` handles skip the parse+prepare cost.
+     * Cleared (finalizing all handles) on {@link exec} — the DDL/script path —
+     * and on {@link close}.
+     */
+    private stmts;
+    /** Per-phase timing of the last {@link open}, or null if it hasn't run. */
+    getOpenPhaseTimings(): OpenPhaseTimings | null;
     open(config: SQLiteConfig): Promise<void>;
     close(): Promise<void>;
     isOpen(): boolean;
     getStorageMode(): 'opfs' | 'memory';
+    /** True while a manual BEGIN…COMMIT/ROLLBACK transaction is open. */
+    isInTransaction(): boolean;
+    /** ms since the open transaction last executed an operation (0 when none). */
+    transactionIdleMs(): number;
+    /** Stamp transaction liveness — called by ops that run inside one. */
+    private touchTransaction;
+    /**
+     * Fetch (or prepare and cache) the statement for `sql`, or null when the SQL
+     * must bypass the cache: `db.prepare()` compiles only the FIRST statement of
+     * a multi-statement string, whereas `db.exec()` runs them all — serving such
+     * SQL from the cache would silently drop statements.
+     */
+    private getCachedStmt;
     query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
     queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    queryBatch(reads: SQLBatchRead[]): Promise<SQLRow[][]>;
     run(sql: string, params?: SQLValue[]): Promise<RunResult>;
     exec(sql: string): Promise<void>;
     private execSync;
@@ -61,12 +125,27 @@ declare class WebSQLiteAdapter implements SQLiteAdapter {
     applySchema(version: number, sql: string): Promise<boolean>;
     getDatabaseSize(): Promise<number>;
     vacuum(): Promise<void>;
+    incrementalVacuum(maxPages?: number): Promise<number>;
     checkpoint(): Promise<number>;
     private ensureOpen;
 }
+/**
+ * Step `PRAGMA incremental_vacuum` to completion (or `maxPages`), returning
+ * the number of pages freed. SQLite frees ONE page per `sqlite3_step` of this
+ * pragma; the oo1 `exec` path steps a statement only once when it collects no
+ * rows, so `exec('PRAGMA incremental_vacuum')` silently freed a single page
+ * per call — the compaction reclaim was a near-no-op (caught by the local
+ * bloat-seed validation, 2026-07-05). Exported for the engine-level test.
+ */
+declare function stepIncrementalVacuumToCompletion(db: {
+    prepare(sql: string): {
+        step(): boolean;
+        finalize(): unknown;
+    };
+}, maxPages?: number): number;
 /**
  * Create a WebSQLiteAdapter with schema applied.
  */
 declare function createWebSQLiteAdapter(config: SQLiteConfig): Promise<WebSQLiteAdapter>;
 
-export { WebSQLiteAdapter, createWebSQLiteAdapter, resetWebSQLiteOpfsStorage };
+export { type OpenPhaseTimings, WebSQLiteAdapter, createWebSQLiteAdapter, resetWebSQLiteOpfsStorage, stepIncrementalVacuumToCompletion };