@xnetjs/sqlite 0.0.2 → 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 } from '../types-C_aHfRDF.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,21 +13,75 @@ import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '.
  */
 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<{
         sql: string;
         params?: SQLValue[];
     }>): Promise<void>;
+    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'>;
+    /**
+     * Expose this handler on an additional MessagePort.
+     *
+     * Lets another worker (e.g. the data worker from @xnetjs/data-bridge)
+     * talk to this SQLite worker directly without routing every storage call
+     * through the main thread. The port is created on the main thread with
+     * `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,10 +1,38 @@
 import {
-  createWebSQLiteAdapter
-} from "../chunk-BXYZU3OL.js";
-import "../chunk-HIREU5S5.js";
+  WorkerScheduler,
+  firstOpGapFields
+} from "../chunk-5HC5V73T.js";
+import {
+  createWebSQLiteAdapter,
+  resetWebSQLiteOpfsStorage
+} from "../chunk-BBZDKLA3.js";
+import "../chunk-SV475UL5.js";
+import {
+  bootLogMessage
+} from "../chunk-CGI2YBZY.js";
+import "../chunk-CBU263LI.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";
 }
@@ -16,46 +44,197 @@ 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();
+    }
   }
-  async close() {
+  /**
+   * 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) {
       await this.adapter.close();
       this.adapter = null;
     }
+    await resetWebSQLiteOpfsStorage(config);
+  }
+  async close() {
+    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.scheduler.schedule(
+      "write",
+      () => this.adapter.applyNodeBatch(input),
+      void 0,
+      "applyNodeBatch"
+    );
   }
   async getSchemaVersion() {
     if (!this.adapter) throw new Error("Database not open");
@@ -63,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");
@@ -73,7 +273,46 @@ var SQLiteWorkerHandler = class {
     if (!this.adapter) throw new Error("Database not open");
     return this.adapter.getStorageMode();
   }
+  /**
+   * Expose this handler on an additional MessagePort.
+   *
+   * Lets another worker (e.g. the data worker from @xnetjs/data-bridge)
+   * talk to this SQLite worker directly without routing every storage call
+   * through the main thread. The port is created on the main thread with
+   * `WebSQLiteProxy.createMessagePort()` and transferred to the peer.
+   */
+  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...");