@xnetjs/sqlite 0.0.2 → 0.1.0

package/dist/adapters/electron.js

@@ -1,9 +1,159 @@
+import {
+  WorkerScheduler
+} from "../chunk-5HC5V73T.js";
+import {
+  isSQLiteCorruptionError
+} from "../chunk-CBU263LI.js";
 import {
   SCHEMA_DDL,
   SCHEMA_VERSION
-} from "../chunk-HIREU5S5.js";
+} from "../chunk-W3L4FXU5.js";
+
+// src/adapters/reader-pool.ts
+function isHeavyRead(sql) {
+  return /\bMATCH\b|\bGROUP\s+BY\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bjson_extract\s*\(|\bORDER\s+BY\b[\s\S]*\bLIMIT\b\s*\d{3,}/i.test(
+    sql
+  );
+}
+function resolveReaderPoolSize(size, dbPath, availableCores) {
+  if (dbPath === ":memory:" || dbPath === "") return 0;
+  if (size === void 0 || size === 0) return 0;
+  if (size === "auto") return Math.max(0, Math.min(4, availableCores - 2));
+  return Math.max(0, Math.floor(size));
+}
+var ReaderPool = class {
+  readers = [];
+  pending = /* @__PURE__ */ new Map();
+  seq = 0;
+  dispatched = 0;
+  failures = 0;
+  closed = false;
+  constructor(options) {
+    const create = options.createWorker;
+    for (let i = 0; i < options.size; i++) {
+      let worker;
+      try {
+        worker = create(i);
+      } catch {
+        this.failures++;
+        continue;
+      }
+      const reader = { index: i, worker, inFlight: 0, healthy: true };
+      worker.on("message", (msg) => this.onMessage(reader, msg));
+      worker.on("error", () => this.onReaderDown(reader));
+      worker.on("exit", (code) => {
+        if (code !== 0) this.onReaderDown(reader);
+      });
+      this.readers.push(reader);
+    }
+  }
+  /** Whether at least one reader can currently serve requests. */
+  isHealthy() {
+    return !this.closed && this.readers.some((r) => r.healthy);
+  }
+  /** Run a SELECT on the least-busy healthy reader. Rejects if none are healthy. */
+  query(sql, params) {
+    return this.dispatch({ op: "query", sql, params }).then((res) => {
+      if (res.ok && "rows" in res) return res.rows;
+      throw new Error(res.ok ? "reader returned no rows" : res.error);
+    });
+  }
+  /** Run a single-row SELECT on the least-busy healthy reader. */
+  queryOne(sql, params) {
+    return this.dispatch({ op: "queryOne", sql, params }).then((res) => {
+      if (res.ok && "row" in res) return res.row;
+      throw new Error(res.ok ? "reader returned no row" : res.error);
+    });
+  }
+  stats() {
+    return {
+      size: this.readers.length,
+      healthy: this.readers.filter((r) => r.healthy).length,
+      inFlight: this.pending.size,
+      dispatched: this.dispatched,
+      failures: this.failures
+    };
+  }
+  async close() {
+    this.closed = true;
+    for (const reader of this.readers) {
+      reader.healthy = false;
+      try {
+        await reader.worker.terminate();
+      } catch {
+      }
+    }
+    for (const [, p] of this.pending) {
+      p.reject(new Error("reader pool closed"));
+    }
+    this.pending.clear();
+  }
+  dispatch(req) {
+    const reader = this.pickLeastBusy();
+    if (!reader) return Promise.reject(new Error("no healthy reader available"));
+    const id = ++this.seq;
+    const message = { id, ...req };
+    reader.inFlight++;
+    this.dispatched++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, reader });
+      try {
+        reader.worker.postMessage(message);
+      } catch (err) {
+        this.pending.delete(id);
+        reader.inFlight--;
+        this.onReaderDown(reader);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+  pickLeastBusy() {
+    let best = null;
+    for (const reader of this.readers) {
+      if (!reader.healthy) continue;
+      if (!best || reader.inFlight < best.inFlight) best = reader;
+    }
+    return best;
+  }
+  onMessage(reader, msg) {
+    if (msg.id === 0 && "ready" in msg) {
+      if (!msg.ready) this.onReaderDown(reader);
+      return;
+    }
+    const pending = this.pending.get(msg.id);
+    if (!pending) return;
+    this.pending.delete(msg.id);
+    reader.inFlight = Math.max(0, reader.inFlight - 1);
+    pending.resolve(msg);
+  }
+  onReaderDown(reader) {
+    if (!reader.healthy) return;
+    reader.healthy = false;
+    this.failures++;
+    for (const [id, p] of this.pending) {
+      if (p.reader === reader) {
+        this.pending.delete(id);
+        p.reject(new Error(`reader ${reader.index} is unavailable`));
+      }
+    }
+  }
+};
+function workerThreadsFactory(WorkerCtor, dbPath) {
+  const scriptUrl = new URL("./reader-thread.js", import.meta.url);
+  return () => new WorkerCtor(scriptUrl, { workerData: { dbPath } });
+}
 
 // src/adapters/electron.ts
+function readKey(op, sql, params) {
+  return `${op} ${sql} ${params ? JSON.stringify(params) : ""}`;
+}
+var APPLY_NODE_BATCH_CHUNK_ROWS = 250;
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function yieldToEventLoop() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
 var DatabaseConstructor = null;
 async function getBetterSqlite3() {
   if (DatabaseConstructor) return DatabaseConstructor;
@@ -13,10 +163,19 @@ async function getBetterSqlite3() {
 }
 var ElectronSQLiteAdapter = class {
   db = null;
+  /** Optional read-only secondary connection (exploration 0230, Phase 0.5). */
+  readDb = null;
   config = null;
   inTransaction = false;
-  // Cached prepared statements for performance
+  // Cached prepared statements for performance (per connection)
   statementCache = /* @__PURE__ */ new Map();
+  readStatementCache = /* @__PURE__ */ new Map();
+  /** Priority scheduler fronting the writer connection (exploration 0230). */
+  scheduler = null;
+  /** Read-only reader-thread pool for heavy parallel reads (Phase 1). */
+  readerPool = null;
+  /** Monotonic clock of the most recent commit, for read-your-writes routing. */
+  lastCommitAt = 0;
   async open(config) {
     if (this.db) {
       throw new Error("Database already open. Call close() first.");
@@ -38,10 +197,58 @@ var ElectronSQLiteAdapter = class {
     this.db.pragma("synchronous = NORMAL");
     this.db.pragma("cache_size = -64000");
     this.db.pragma("temp_store = MEMORY");
+    try {
+      this.db.pragma("analysis_limit = 400");
+      this.db.pragma("optimize = 0x10002");
+    } catch {
+    }
+    if (config.scheduler !== false) {
+      this.scheduler = new WorkerScheduler();
+    }
+    const fileBacked = config.path !== ":memory:" && config.path !== "";
+    if (config.readonlyReadConnection && fileBacked) {
+      try {
+        this.readDb = new Database(config.path, { readonly: true, fileMustExist: true });
+        this.readDb.pragma("busy_timeout = 5000");
+        this.readDb.pragma("cache_size = -32000");
+        this.readDb.pragma("temp_store = MEMORY");
+      } catch {
+        this.readDb = null;
+      }
+    }
+    if (fileBacked && config.readerPoolSize) {
+      try {
+        const os = await import("os");
+        const cores = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+        const poolSize = resolveReaderPoolSize(config.readerPoolSize, config.path, cores);
+        if (poolSize > 0) {
+          const { Worker } = await import("worker_threads");
+          this.readerPool = new ReaderPool({
+            dbPath: config.path,
+            size: poolSize,
+            createWorker: workerThreadsFactory(Worker, config.path)
+          });
+        }
+      } catch {
+        this.readerPool = null;
+      }
+    }
   }
   async close() {
     if (!this.db) return;
     this.statementCache.clear();
+    this.readStatementCache.clear();
+    if (this.readerPool) {
+      await this.readerPool.close();
+      this.readerPool = null;
+    }
+    if (this.readDb) {
+      try {
+        this.readDb.close();
+      } catch {
+      }
+      this.readDb = null;
+    }
     if (this.config?.walMode !== false) {
       try {
         this.db.pragma("wal_checkpoint(TRUNCATE)");
@@ -51,50 +258,79 @@ var ElectronSQLiteAdapter = class {
     this.db.close();
     this.db = null;
     this.config = null;
+    this.scheduler = null;
+    this.inTransaction = false;
   }
   isOpen() {
     return this.db !== null;
   }
   async query(sql, params) {
     this.ensureOpen();
-    try {
-      const stmt = this.getOrPrepare(sql);
-      const rows = params ? stmt.all(...params) : stmt.all();
-      return rows;
-    } catch (err) {
-      throw this.wrapError(err, sql);
+    if (this.inTransaction) return this.queryRaw(this.db, this.statementCache, sql, params);
+    if (this.shouldUsePool(sql)) {
+      try {
+        return await this.readerPool.query(sql, params);
+      } catch {
+      }
     }
+    const conn = this.readConnection();
+    if (this.scheduler) {
+      return this.scheduler.schedule(
+        "interactive",
+        async () => this.queryRaw(conn.db, conn.cache, sql, params),
+        readKey("query", sql, params),
+        "query"
+      );
+    }
+    return this.queryRaw(conn.db, conn.cache, sql, params);
+  }
+  async queryBatch(reads) {
+    const results = [];
+    for (const read of reads) {
+      results.push(await this.query(read.sql, read.params));
+    }
+    return results;
   }
   async queryOne(sql, params) {
     this.ensureOpen();
-    try {
-      const stmt = this.getOrPrepare(sql);
-      const row = params ? stmt.get(...params) : stmt.get();
-      return row ?? null;
-    } catch (err) {
-      throw this.wrapError(err, sql);
+    if (this.inTransaction) return this.queryOneRaw(this.db, this.statementCache, sql, params);
+    if (this.shouldUsePool(sql)) {
+      try {
+        return await this.readerPool.queryOne(sql, params);
+      } catch {
+      }
+    }
+    const conn = this.readConnection();
+    if (this.scheduler) {
+      return this.scheduler.schedule(
+        "interactive",
+        async () => this.queryOneRaw(conn.db, conn.cache, sql, params),
+        readKey("queryOne", sql, params),
+        "queryOne"
+      );
     }
+    return this.queryOneRaw(conn.db, conn.cache, sql, params);
   }
   async run(sql, params) {
     this.ensureOpen();
-    try {
-      const stmt = this.getOrPrepare(sql);
-      const result = params ? stmt.run(...params) : stmt.run();
-      return {
-        changes: result.changes,
-        lastInsertRowid: BigInt(result.lastInsertRowid)
-      };
-    } catch (err) {
-      throw this.wrapError(err, sql);
+    if (this.inTransaction) return this.runRaw(sql, params);
+    if (this.scheduler) {
+      return this.scheduler.schedule(
+        "write",
+        async () => this.runRaw(sql, params),
+        void 0,
+        "run"
+      );
     }
+    return this.runRaw(sql, params);
   }
   async exec(sql) {
     this.ensureOpen();
-    try {
-      this.db.exec(sql);
-    } catch (err) {
-      throw this.wrapError(err, sql);
+    if (this.inTransaction) return this.execRaw(sql);
+    if (this.scheduler) {
+      return this.scheduler.schedule("write", async () => this.execRaw(sql), void 0, "exec");
     }
+    return this.execRaw(sql);
   }
   async transaction(fn) {
     this.ensureOpen();
@@ -104,10 +340,50 @@ var ElectronSQLiteAdapter = class {
       await this.commit();
       return result;
     } catch (err) {
-      await this.rollback();
+      if (this.inTransaction) {
+        try {
+          await this.rollback();
+        } catch (rollbackErr) {
+          if (isSQLiteCorruptionError(rollbackErr) && !isSQLiteCorruptionError(err)) {
+            throw rollbackErr;
+          }
+        }
+      }
       throw err;
     }
   }
+  async transactionBatch(operations) {
+    this.ensureOpen();
+    if (operations.length === 0) return;
+    const apply = () => {
+      let currentSql = operations[0].sql;
+      try {
+        this.transactionSync(() => {
+          for (const operation of operations) {
+            currentSql = operation.sql;
+            const stmt = this.getOrPrepare(operation.sql);
+            if (operation.params) {
+              stmt.run(...operation.params);
+            } else {
+              stmt.run();
+            }
+          }
+        });
+      } catch (err) {
+        throw this.wrapError(err, currentSql);
+      }
+      this.lastCommitAt = nowMs();
+    };
+    if (this.inTransaction) {
+      apply();
+      return;
+    }
+    if (this.scheduler) {
+      await this.scheduler.schedule("write", async () => apply(), void 0, "transactionBatch");
+      return;
+    }
+    apply();
+  }
   /**
    * Synchronous transaction for performance-critical batch operations.
    * Prefer this over async transaction when the body is synchronous.
@@ -118,6 +394,7 @@ var ElectronSQLiteAdapter = class {
     return txn();
   }
   async beginTransaction() {
+    this.ensureOpen();
     if (this.inTransaction) {
       throw new Error("Transaction already in progress");
     }
@@ -128,15 +405,26 @@ var ElectronSQLiteAdapter = class {
     if (!this.inTransaction) {
       throw new Error("No transaction in progress");
     }
-    this.db.exec("COMMIT");
-    this.inTransaction = false;
+    try {
+      this.db.exec("COMMIT");
+      this.inTransaction = false;
+      this.lastCommitAt = nowMs();
+    } catch (err) {
+      if (isSQLiteCorruptionError(err)) {
+        this.inTransaction = false;
+      }
+      throw err;
+    }
   }
   async rollback() {
     if (!this.inTransaction) {
       return;
     }
-    this.db.exec("ROLLBACK");
-    this.inTransaction = false;
+    try {
+      this.db.exec("ROLLBACK");
+    } finally {
+      this.inTransaction = false;
+    }
   }
   async prepare(sql) {
     this.ensureOpen();
@@ -215,24 +503,362 @@ var ElectronSQLiteAdapter = class {
   }
   async vacuum() {
     this.ensureOpen();
+    if (this.inTransaction) {
+      this.db.exec("VACUUM");
+      return;
+    }
+    if (this.scheduler) {
+      await this.scheduler.schedule(
+        "write",
+        async () => this.db.exec("VACUUM"),
+        void 0,
+        "vacuum"
+      );
+      return;
+    }
     this.db.exec("VACUUM");
   }
+  async incrementalVacuum(maxPages) {
+    this.ensureOpen();
+    const pragma = maxPages !== void 0 && maxPages > 0 ? `incremental_vacuum(${Math.floor(maxPages)})` : "incremental_vacuum";
+    const runIt = () => {
+      const before = this.db.pragma("freelist_count", { simple: true });
+      this.db.pragma(pragma);
+      const after = this.db.pragma("freelist_count", { simple: true });
+      return Math.max(0, before - after);
+    };
+    if (this.inTransaction) {
+      return runIt();
+    }
+    if (this.scheduler) {
+      return this.scheduler.schedule("write", async () => runIt(), void 0, "incremental_vacuum");
+    }
+    return runIt();
+  }
   async checkpoint() {
     return 0;
   }
   getStorageMode() {
     return "opfs";
   }
+  /**
+   * Apply a node-store batch with cooperative yielding (exploration 0230).
+   *
+   * A bulk import is the one synchronous op long enough to head-of-line block
+   * interactive reads on the data-process thread. This splits the batch into
+   * chunks, each its own exclusive transaction, and yields to the event loop
+   * between chunks so a queued interactive read (or a reader-pool read) can
+   * interleave. Whole-batch atomicity is traded for yield points — safe here
+   * because node-batch writes are idempotent LWW upserts.
+   */
+  async applyNodeBatch(input) {
+    this.ensureOpen();
+    const indexed = input.indexMode !== "defer-schema";
+    const invalidatedAt = Date.now();
+    const ops = [];
+    const nodeStmt = () => this.getOrPrepare(
+      `INSERT INTO nodes (id, schema_id, created_at, updated_at, created_by, deleted_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           schema_id = excluded.schema_id,
+           updated_at = excluded.updated_at,
+           deleted_at = excluded.deleted_at`
+    );
+    for (const node of input.nodes) {
+      ops.push(
+        () => nodeStmt().run(
+          node.id,
+          node.schemaId,
+          node.createdAt,
+          node.updatedAt,
+          node.createdBy,
+          node.deletedAt
+        )
+      );
+      if (node.propertyKeys.length === 0) {
+        ops.push(
+          () => this.getOrPrepare("DELETE FROM node_properties WHERE node_id = ?").run(node.id)
+        );
+      } else {
+        const placeholders = node.propertyKeys.map(() => "?").join(", ");
+        ops.push(
+          () => this.getOrPrepare(
+            `DELETE FROM node_properties WHERE node_id = ? AND property_key NOT IN (${placeholders})`
+          ).run(node.id, ...node.propertyKeys)
+        );
+      }
+    }
+    for (const property of input.properties) {
+      ops.push(
+        () => this.getOrPrepare(
+          `INSERT INTO node_properties
+              (node_id, property_key, value, lamport_time, updated_by, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(node_id, property_key) DO UPDATE SET
+              value = excluded.value,
+              lamport_time = excluded.lamport_time,
+              updated_by = excluded.updated_by,
+              updated_at = excluded.updated_at
+            WHERE excluded.lamport_time > node_properties.lamport_time`
+        ).run(
+          property.nodeId,
+          property.propertyKey,
+          property.value,
+          property.lamportTime,
+          property.updatedBy,
+          property.updatedAt
+        )
+      );
+    }
+    if (indexed) {
+      for (const node of input.nodes) {
+        ops.push(
+          () => this.getOrPrepare("DELETE FROM node_property_scalars WHERE node_id = ?").run(node.id)
+        );
+      }
+      for (const row of input.scalarIndexRows) {
+        ops.push(
+          () => this.getOrPrepare(
+            `INSERT INTO node_property_scalars
+                (node_id, schema_id, property_key, value_type, value_text,
+                 value_number, value_boolean, value_hash, updated_at, lamport_time)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          ).run(
+            row.nodeId,
+            row.schemaId,
+            row.propertyKey,
+            row.valueType,
+            row.valueText,
+            row.valueNumber,
+            row.valueBoolean,
+            row.valueHash,
+            row.updatedAt,
+            row.lamportTime
+          )
+        );
+      }
+      for (const nodeId of input.ftsNodeIds) {
+        ops.push(() => this.getOrPrepare("DELETE FROM nodes_fts WHERE node_id = ?").run(nodeId));
+      }
+      for (const row of input.ftsRows) {
+        ops.push(
+          () => this.getOrPrepare("INSERT INTO nodes_fts (node_id, title, content) VALUES (?, ?, ?)").run(
+            row.nodeId,
+            row.title,
+            row.content
+          )
+        );
+      }
+    }
+    for (const change of input.changes) {
+      ops.push(
+        () => this.getOrPrepare(
+          `INSERT OR IGNORE INTO changes
+            (hash, node_id, payload, lamport_time, lamport_peer, wall_time, author, parent_hash, batch_id, signature)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        ).run(
+          change.hash,
+          change.nodeId,
+          change.payload,
+          change.lamportTime,
+          change.lamportPeer,
+          change.wallTime,
+          change.author,
+          change.parentHash,
+          change.batchId,
+          change.signature
+        )
+      );
+    }
+    ops.push(
+      () => this.getOrPrepare(
+        `INSERT INTO sync_state (key, value) VALUES ('lastLamportTime', ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      ).run(String(input.lastLamportTime))
+    );
+    if (indexed) {
+      for (const schemaId of input.affectedSchemaIds) {
+        ops.push(
+          () => this.getOrPrepare(
+            `UPDATE node_query_materializations
+             SET invalidated_at = ?
+             WHERE schema_id = ? AND invalidated_at IS NULL`
+          ).run(invalidatedAt, schemaId)
+        );
+      }
+    }
+    if (this.inTransaction) {
+      for (const op of ops) op();
+    } else {
+      for (let i = 0; i < ops.length; i += APPLY_NODE_BATCH_CHUNK_ROWS) {
+        const chunk = ops.slice(i, i + APPLY_NODE_BATCH_CHUNK_ROWS);
+        await this.runChunkTransaction(() => {
+          for (const op of chunk) op();
+        });
+        if (i + APPLY_NODE_BATCH_CHUNK_ROWS < ops.length) await yieldToEventLoop();
+      }
+    }
+    return {
+      nodeRowsWritten: input.nodes.length,
+      propertyRowsWritten: input.properties.length,
+      changeRowsWritten: input.changes.length,
+      scalarRowsWritten: input.scalarIndexRows.length,
+      ftsRowsWritten: input.ftsRows.length
+    };
+  }
+  /** Scheduler queue depths (diagnostics / desktop perf panel). */
+  getSchedulerSnapshot() {
+    return this.scheduler ? this.scheduler.snapshot() : null;
+  }
+  /** Reader-thread pool occupancy, or null when no pool is configured. */
+  getReaderPoolStats() {
+    return this.readerPool ? this.readerPool.stats() : null;
+  }
+  /**
+   * WAL growth: `-wal` sidecar size + page count. Long-lived readers can pin an
+   * old snapshot and hold back checkpointing; our one-shot reader selects don't,
+   * so this should stay bounded. Surfaced to the diagnostics seam (0230).
+   */
+  async getWalStats() {
+    if (!this.db || this.config?.walMode === false) return null;
+    try {
+      const path = this.config?.path;
+      let walBytes = 0;
+      if (path && path !== ":memory:") {
+        const { statSync } = await import("fs");
+        try {
+          walBytes = statSync(`${path}-wal`).size;
+        } catch {
+          walBytes = 0;
+        }
+      }
+      const page = this.db.pragma("page_count", { simple: true });
+      return { walBytes, pageCount: typeof page === "number" ? page : 0 };
+    } catch {
+      return null;
+    }
+  }
+  /** Run a passive WAL checkpoint; returns frames checkpointed (best-effort). */
+  async checkpointWal() {
+    if (!this.db || this.config?.walMode === false) return 0;
+    return this.scheduler ? this.scheduler.schedule("bulk", async () => this.runCheckpoint(), void 0, "checkpoint") : this.runCheckpoint();
+  }
+  runCheckpoint() {
+    try {
+      const result = this.db.pragma("wal_checkpoint(PASSIVE)");
+      return result?.[0]?.checkpointed ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+  /** Combined point-in-time diagnostics for the desktop diagnostics seam. */
+  async getDiagnostics() {
+    return {
+      scheduler: this.getSchedulerSnapshot(),
+      readerPool: this.getReaderPoolStats(),
+      wal: await this.getWalStats(),
+      readonlyConnection: this.readDb !== null
+    };
+  }
   // ─── Helper Methods ─────────────────────────────────────────────────────
+  /** Whether a heavy, non-transactional read should be offloaded to the pool. */
+  shouldUsePool(sql) {
+    return this.readerPool !== null && this.readerPool.isHealthy() && isHeavyRead(sql) && !this.inReadYourWritesWindow();
+  }
+  /** Reads within the configured window after a commit route to the writer. */
+  inReadYourWritesWindow() {
+    const window = this.config?.readYourWritesWindowMs ?? 0;
+    if (window <= 0) return false;
+    return nowMs() - this.lastCommitAt < window;
+  }
+  /** Pick the connection (+ its statement cache) a plain read should use. */
+  readConnection() {
+    if (this.readDb && !this.inReadYourWritesWindow()) {
+      return { db: this.readDb, cache: this.readStatementCache };
+    }
+    return { db: this.db, cache: this.statementCache };
+  }
   /**
-   * Get a statement from cache or prepare it.
+   * Run `apply` as a single atomic chunk transaction. Scheduled as one write-lane
+   * job so it is indivisible w.r.t. the scheduler — no queued read or write can
+   * interleave mid-chunk — while the surrounding `applyNodeBatch` yields *between*
+   * chunks. `apply` is fully synchronous (no awaits), so `inTransaction` is set
+   * only for its duration and is invisible to other async callers.
+   */
+  runChunkTransaction(apply) {
+    const exec = () => {
+      this.inTransaction = true;
+      try {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+          apply();
+          this.db.exec("COMMIT");
+          this.lastCommitAt = nowMs();
+        } catch (err) {
+          try {
+            this.db.exec("ROLLBACK");
+          } catch {
+          }
+          throw err;
+        }
+      } finally {
+        this.inTransaction = false;
+      }
+    };
+    return this.scheduler ? this.scheduler.schedule("write", async () => exec(), void 0, "applyNodeBatch") : Promise.resolve().then(exec);
+  }
+  queryRaw(db, cache, sql, params) {
+    try {
+      const stmt = this.getOrPrepareOn(db, cache, sql);
+      const rows = params ? stmt.all(...params) : stmt.all();
+      return rows;
+    } catch (err) {
+      throw this.wrapError(err, sql);
+    }
+  }
+  queryOneRaw(db, cache, sql, params) {
+    try {
+      const stmt = this.getOrPrepareOn(db, cache, sql);
+      const row = params ? stmt.get(...params) : stmt.get();
+      return row ?? null;
+    } catch (err) {
+      throw this.wrapError(err, sql);
+    }
+  }
+  runRaw(sql, params) {
+    try {
+      const stmt = this.getOrPrepare(sql);
+      const result = params ? stmt.run(...params) : stmt.run();
+      this.lastCommitAt = nowMs();
+      return {
+        changes: result.changes,
+        lastInsertRowid: BigInt(result.lastInsertRowid)
+      };
+    } catch (err) {
+      throw this.wrapError(err, sql);
+    }
+  }
+  execRaw(sql) {
+    try {
+      this.db.exec(sql);
+      this.lastCommitAt = nowMs();
+    } catch (err) {
+      throw this.wrapError(err, sql);
+    }
+  }
+  /**
+   * Get a statement from cache or prepare it on the writer connection.
    * Statement caching significantly improves performance for repeated queries.
    */
   getOrPrepare(sql) {
-    let stmt = this.statementCache.get(sql);
+    return this.getOrPrepareOn(this.db, this.statementCache, sql);
+  }
+  /** Statement cache keyed per connection (writer + read-only differ). */
+  getOrPrepareOn(db, cache, sql) {
+    let stmt = cache.get(sql);
     if (!stmt) {
-      stmt = this.db.prepare(sql);
-      this.statementCache.set(sql, stmt);
+      stmt = db.prepare(sql);
+      cache.set(sql, stmt);
     }
     return stmt;
   }