@delali/sirannon-db 0.1.6 → 0.1.7

package/dist/core/writer-worker.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/core/writer-worker.mjs

@@ -0,0 +1,107 @@
+import { serializeError } from '../chunk-DJLX6CAE.mjs';
+import { executeGroup } from '../chunk-CW6S3WL5.mjs';
+import '../chunk-GEZUUIKV.mjs';
+import { SirannonError } from '../chunk-YPYVQJ4C.mjs';
+import { parentPort } from 'worker_threads';
+
+var STATEMENT_CACHE_CAPACITY = 128;
+if (!parentPort) {
+  throw new SirannonError("Writer worker started outside a worker thread", "WRITER_WORKER_NO_PORT");
+}
+var port = parentPort;
+var connection = null;
+var statements = /* @__PURE__ */ new Map();
+function requireConnection() {
+  if (!connection) {
+    throw new SirannonError(
+      "Writer worker received a command before the connection was opened",
+      "WRITER_WORKER_NOT_OPEN"
+    );
+  }
+  return connection;
+}
+async function statementFor(sql) {
+  const conn = requireConnection();
+  const cached = statements.get(sql);
+  if (cached) {
+    statements.delete(sql);
+    statements.set(sql, cached);
+    return cached;
+  }
+  const stmt = await conn.prepare(sql);
+  statements.set(sql, stmt);
+  if (statements.size > STATEMENT_CACHE_CAPACITY) {
+    const oldest = statements.keys().next().value;
+    if (oldest !== void 0) statements.delete(oldest);
+  }
+  return stmt;
+}
+async function open(entry, path, options) {
+  const module = await import(entry.specifier);
+  const factory = module[entry.exportName ?? "default"];
+  if (typeof factory !== "function") {
+    throw new SirannonError(
+      `Driver worker entry '${entry.specifier}' has no callable export '${entry.exportName ?? "default"}'`,
+      "WRITER_WORKER_BAD_ENTRY"
+    );
+  }
+  const driver = factory(entry.config);
+  connection = await driver.open(path, options);
+}
+async function dispatch(req) {
+  switch (req.kind) {
+    case "open":
+      await open(req.entry, req.path, req.options);
+      return void 0;
+    case "exec":
+      await requireConnection().exec(req.sql);
+      return void 0;
+    case "run":
+      return (await statementFor(req.sql)).run(...req.params);
+    case "get":
+      return (await statementFor(req.sql)).get(...req.params);
+    case "all":
+      return (await statementFor(req.sql)).all(...req.params);
+    case "allRaw": {
+      const stmt = await statementFor(req.sql);
+      return stmt.allRaw ? stmt.allRaw(...req.params) : stmt.all(...req.params);
+    }
+    case "runBatch": {
+      const conn = requireConnection();
+      if (conn.runBatch) return conn.runBatch(req.sql, req.paramsBatch);
+      const stmt = await statementFor(req.sql);
+      return Promise.all(req.paramsBatch.map((params) => stmt.run(...params)));
+    }
+    case "runBatchSummary": {
+      const conn = requireConnection();
+      if (conn.runBatchSummary) return conn.runBatchSummary(req.sql, req.paramsBatch);
+      const stmt = await statementFor(req.sql);
+      let changes = 0;
+      for (const params of req.paramsBatch) changes += (await stmt.run(...params)).changes;
+      return { rowsLoaded: req.paramsBatch.length, changes };
+    }
+    case "runGroup": {
+      const outcomes = await executeGroup(requireConnection(), req.units);
+      return outcomes.map(
+        (outcome) => outcome.ok ? { ok: true, results: outcome.values } : { ok: false, error: serializeError(outcome.error) }
+      );
+    }
+    case "close":
+      if (connection) await connection.close();
+      connection = null;
+      statements.clear();
+      return void 0;
+  }
+}
+async function handle(req) {
+  try {
+    const value = await dispatch(req);
+    port.postMessage({ id: req.id, ok: true, value });
+  } catch (err) {
+    port.postMessage({ id: req.id, ok: false, error: serializeError(err) });
+  }
+}
+var tail = Promise.resolve();
+port.on("message", (req) => {
+  tail = tail.then(() => handle(req));
+});

package/dist/{database-BVY1GqE7.d.ts → database-DuGp0Rtr.d.ts}

@@ -1,6 +1,5 @@
-import { S as SQLiteDriver } from './types-BFSsG77t.js';
-import { Q as QueryHookContext, f as ConnectionHookContext, g as BeforeSubscribeHook, H as HookConfig, M as MetricsConfig, h as QueryMetrics, i as ConnectionMetrics, j as CDCMetrics, D as DatabaseOptions, P as Params, k as QueryOptions, E as ExecuteResult, T as Transaction, l as SubscriptionBuilder, m as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-D-74JiXb.js';
-import { M as Migration, a as MigrationResult, R as RollbackResult } from './types-BeozgNPr.js';
+import { Q as QueryHookContext, k as ConnectionHookContext, l as BeforeSubscribeHook, H as HookConfig, M as MetricsConfig, m as QueryMetrics, n as ConnectionMetrics, o as CDCMetrics, a as SQLiteDriver, D as DatabaseOptions, P as Params, p as QueryOptions, E as ExecuteResult, q as BulkLoadOptions, h as BulkLoadResult, T as Transaction, e as SQLiteConnection, r as SubscriptionBuilder, f as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-D_hQW1hr.js';
+import { M as Migration, a as MigrationResult, R as RollbackResult } from './types-D4p4UyDK.js';
 
 type HookEvent = 'beforeQuery' | 'afterQuery' | 'beforeConnect' | 'databaseOpen' | 'databaseClose' | 'beforeSubscribe';
 type SubscribeHookContext = Parameters<BeforeSubscribeHook>[0];
@@ -49,28 +48,66 @@ declare class Database {
     readonly readOnly: boolean;
     private readonly pool;
     private readonly driver;
+    private readonly synchronous;
+    private readonly walMode;
+    private readonly writerLock;
+    private readonly writeGate;
+    private readonly groupCommitter;
     private readonly closeListeners;
     private _closed;
-    private changeTracker;
-    private subscriptionManager;
-    private stopCdcPolling;
-    private readonly cdcPollInterval;
-    private readonly cdcRetention;
+    private readonly cdc;
     private readonly hookRegistry;
-    private readonly parentHooks;
-    private readonly metricsCollector;
-    private readonly backupManager;
-    private readonly backupScheduler;
-    private readonly scheduledBackupCancellers;
+    private readonly observer;
+    private readonly backups;
     private constructor();
     static create(id: string, path: string, driver: SQLiteDriver, options?: DatabaseOptions, internals?: DatabaseInternals): Promise<Database>;
     query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Returns query rows already encoded for the wire (safe-range integers as
+     * plain numbers, larger integers and BLOBs as tagged envelopes) in a single
+     * pass. The server response path uses this so a read walks its values once
+     * rather than narrowing on the driver and re-scanning to tag.
+     */
+    queryForWire(sql: string, params?: Params, options?: QueryOptions): Promise<unknown[]>;
     queryOne<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T | undefined>;
+    /**
+     * On a single-connection driver the reader is the writer, so serialise the
+     * read through the writer lock to avoid a bulk load's uncommitted rows.
+     */
+    private runRead;
     execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
     executeBatch(sql: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    private runInTransaction;
+    /**
+     * Load rows with relaxed writer durability. The load holds the writer lock
+     * for its whole duration, so no other write commits under the relaxed level
+     * and no two loads race on the shared `synchronous` setting; the configured
+     * level is restored before this resolves, whether the load succeeds or
+     * fails. The load runs in one transaction, so one commit and one durability
+     * barrier cover the whole batch. Rows are summed rather than returned
+     * per-row to bound memory on large loads. Like `execute` and `transaction`,
+     * this writes only to the local database; under replication the server routes
+     * loads through the engine, not through this method.
+     */
+    bulkLoad(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+    /**
+     * Takes the statements up front rather than a callback, since a group cannot wait on an
+     * arbitrary caller-supplied callback without delaying every transaction beside it.
+     */
+    executeTransaction(statements: readonly {
+        sql: string;
+        params?: Params;
+    }[]): Promise<ExecuteResult[]>;
+    private runStatementsAlone;
     transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
-    private maybeApplyDdlSideEffects;
     watch(table: string): Promise<void>;
+    /**
+     * Runs a CDC maintenance write (change-log pruning) on the shared writer
+     * under the writer lock. Serialising it with application writes keeps it
+     * from becoming a second writer that contends for SQLite's single write
+     * lock and stalls the event loop on `busy_timeout`.
+     */
+    runCdcMaintenance(op: (writer: SQLiteConnection) => Promise<unknown>): Promise<void>;
     unwatch(table: string): Promise<void>;
     on(table: string): SubscriptionBuilder;
     migrate(migrations: Migration[]): Promise<MigrationResult>;
@@ -85,11 +122,6 @@ declare class Database {
     get closed(): boolean;
     get readerCount(): number;
     private ensureOpen;
-    private ensureCdc;
-    private ensureCdcPolling;
-    private stopCdcPollingLoop;
-    private fireBeforeQueryHooks;
-    private fireAfterQueryHooks;
 }
 
 export { Database as D, type HookDispose as H, MetricsCollector as M, type SubscribeHookContext as S, type HookEvent as a, type HookEventContextMap as b, type HookHandler as c, HookRegistry as d };

package/dist/driver/better-sqlite3.d.ts

@@ -1,4 +1,4 @@
-import { S as SQLiteDriver } from '../types-BFSsG77t.js';
+import { a as SQLiteDriver } from '../types-D_hQW1hr.js';
 
 interface BetterSqlite3Options {
     busyTimeout?: number;

package/dist/driver/better-sqlite3.mjs

@@ -1,8 +1,13 @@
-import { defineDriver } from '../chunk-74UN4DIE.mjs';
-import '../chunk-O7BHI3CF.mjs';
+import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, WriterWorker, createStatementCache, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-4IGMIJQK.mjs';
+import { defineDriver } from '../chunk-BNUTBHHH.mjs';
+import '../chunk-DJLX6CAE.mjs';
+import { synchronousPragmaValue } from '../chunk-CJLYFDP5.mjs';
+import '../chunk-VLTICJOD.mjs';
+import '../chunk-YPYVQJ4C.mjs';
 
 // src/drivers/better-sqlite3/index.ts
 function createConnection(db) {
+  const batchStatementFor = createStatementCache((sql) => db.prepare(sql));
   const conn = {
     async exec(sql) {
       db.exec(sql);
@@ -11,20 +16,43 @@ function createConnection(db) {
       const stmt = db.prepare(sql);
       return {
         async all(...params) {
+          return narrowRowsIntegers(stmt.all(...params));
+        },
+        async allRaw(...params) {
           return stmt.all(...params);
         },
         async get(...params) {
-          return stmt.get(...params);
+          return narrowRowIntegers(stmt.get(...params));
         },
         async run(...params) {
           const result = stmt.run(...params);
           return {
-            changes: result.changes,
-            lastInsertRowId: result.lastInsertRowid
+            changes: Number(result.changes),
+            lastInsertRowId: narrowSafeBigInt(result.lastInsertRowid)
           };
         }
       };
     },
+    async runBatch(sql, paramsBatch) {
+      const stmt = batchStatementFor(sql);
+      const results = new Array(paramsBatch.length);
+      for (let i = 0; i < paramsBatch.length; i++) {
+        const result = stmt.run(...paramsBatch[i]);
+        results[i] = {
+          changes: Number(result.changes),
+          lastInsertRowId: narrowSafeBigInt(result.lastInsertRowid)
+        };
+      }
+      return results;
+    },
+    async runBatchSummary(sql, paramsBatch) {
+      const stmt = batchStatementFor(sql);
+      let changes = 0;
+      for (let i = 0; i < paramsBatch.length; i++) {
+        changes += Number(stmt.run(...paramsBatch[i]).changes);
+      }
+      return { rowsLoaded: paramsBatch.length, changes };
+    },
     async transaction(fn) {
       await conn.exec("BEGIN");
       try {
@@ -46,13 +74,23 @@ function createConnection(db) {
   return conn;
 }
 function betterSqlite3(driverOptions) {
+  const workerEntry = { specifier: import.meta.url, exportName: "betterSqlite3", config: driverOptions };
   return defineDriver({
     capabilities: { multipleConnections: true, extensions: true },
+    worker: workerEntry,
+    startWriterHost: async (path, options, hostOptions) => {
+      const host = await WriterWorker.start(workerEntry, path, options, hostOptions);
+      return host.connection;
+    },
+    createWriterContext: nodeWriterContext,
+    createBackupEngine: nodeBackupEngine,
+    resolveExtensionPath: nodeResolveExtensionPath,
     async open(path, options) {
       const Database = (await import('better-sqlite3')).default;
       const db = new Database(path, { readonly: options?.readonly ?? false });
+      db.defaultSafeIntegers(true);
       if (options?.walMode !== false) db.pragma("journal_mode = WAL");
-      db.pragma("synchronous = NORMAL");
+      db.pragma(`synchronous = ${synchronousPragmaValue(options?.synchronous)}`);
       db.pragma("foreign_keys = ON");
       db.pragma(`busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
       return createConnection(db);

package/dist/driver/bun.mjs

@@ -1,4 +1,30 @@
-import { defineDriver } from '../chunk-FB2U2Q3Y.mjs';
+import { defineDriver, synchronousPragmaValue } from '../chunk-DVWQD3GF.mjs';
+
+// src/core/driver/values.ts
+var SAFE_INT_BOUND = 9007199254740991n;
+function narrowSafeBigInt(value) {
+  if (typeof value === "bigint" && value >= -SAFE_INT_BOUND && value <= SAFE_INT_BOUND) {
+    return Number(value);
+  }
+  return value;
+}
+function narrowRowIntegers(row) {
+  if (row === null || typeof row !== "object") return row;
+  const obj = row;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (typeof value === "bigint" && value >= -SAFE_INT_BOUND && value <= SAFE_INT_BOUND) {
+      obj[key] = Number(value);
+    }
+  }
+  return row;
+}
+function narrowRowsIntegers(rows) {
+  for (const row of rows) {
+    narrowRowIntegers(row);
+  }
+  return rows;
+}
 
 // src/drivers/bun/index.ts
 function bunSqlite(driverOptions) {
@@ -6,9 +32,9 @@ function bunSqlite(driverOptions) {
     capabilities: { multipleConnections: true, extensions: true },
     async open(path, options) {
       const { Database } = await import('bun:sqlite');
-      const db = new Database(path, { readonly: options?.readonly ?? false });
+      const db = new Database(path, { readonly: options?.readonly ?? false, safeIntegers: true });
       if (options?.walMode !== false) db.run("PRAGMA journal_mode = WAL");
-      db.run("PRAGMA synchronous = NORMAL");
+      db.run(`PRAGMA synchronous = ${synchronousPragmaValue(options?.synchronous)}`);
       db.run("PRAGMA foreign_keys = ON");
       db.run(`PRAGMA busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
       const conn = {
@@ -19,18 +45,21 @@ function bunSqlite(driverOptions) {
           const stmt = db.query(sql);
           return {
             async all(...params) {
+              return narrowRowsIntegers(stmt.all(...params));
+            },
+            async allRaw(...params) {
               return stmt.all(...params);
             },
             async get(...params) {
-              return stmt.get(...params) ?? void 0;
+              return narrowRowIntegers(stmt.get(...params) ?? void 0);
             },
             async run(...params) {
               stmt.run(...params);
               const changesStmt = db.query("SELECT changes() AS changes, last_insert_rowid() AS lastId");
               const info = changesStmt.get();
               return {
-                changes: info.changes,
-                lastInsertRowId: info.lastId
+                changes: Number(info.changes),
+                lastInsertRowId: narrowSafeBigInt(info.lastId)
               };
             }
           };

package/dist/driver/expo.mjs

@@ -1,4 +1,4 @@
-import { defineDriver } from '../chunk-FB2U2Q3Y.mjs';
+import { defineDriver, synchronousPragmaValue } from '../chunk-DVWQD3GF.mjs';
 
 // src/drivers/expo/index.ts
 function expoSqlite() {
@@ -10,7 +10,7 @@ function expoSqlite() {
         readOnly: options?.readonly
       });
       if (options?.walMode !== false) await db.execAsync("PRAGMA journal_mode = WAL");
-      await db.execAsync("PRAGMA synchronous = NORMAL");
+      await db.execAsync(`PRAGMA synchronous = ${synchronousPragmaValue(options?.synchronous)}`);
       await db.execAsync("PRAGMA foreign_keys = ON");
       const buildConnectionFromHandle = (dbHandle) => ({
         async exec(sql) {

package/dist/driver/node.d.ts

@@ -1,4 +1,4 @@
-import { S as SQLiteDriver } from '../types-BFSsG77t.js';
+import { a as SQLiteDriver } from '../types-D_hQW1hr.js';
 
 interface NodeSqliteOptions {
     busyTimeout?: number;

package/dist/driver/node.mjs

@@ -1,39 +1,82 @@
-import { defineDriver } from '../chunk-74UN4DIE.mjs';
-import '../chunk-O7BHI3CF.mjs';
+import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, createStatementCache, WriterWorker, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-4IGMIJQK.mjs';
+import { defineDriver } from '../chunk-BNUTBHHH.mjs';
+import '../chunk-DJLX6CAE.mjs';
+import { synchronousPragmaValue } from '../chunk-CJLYFDP5.mjs';
+import '../chunk-VLTICJOD.mjs';
+import '../chunk-YPYVQJ4C.mjs';
 
 // src/drivers/node/index.ts
 function nodeSqlite(driverOptions) {
+  const workerEntry = { specifier: import.meta.url, exportName: "nodeSqlite", config: driverOptions };
   return defineDriver({
     capabilities: { multipleConnections: true, extensions: true },
+    worker: workerEntry,
+    startWriterHost: async (path, options, hostOptions) => {
+      const host = await WriterWorker.start(workerEntry, path, options, hostOptions);
+      return host.connection;
+    },
+    createWriterContext: nodeWriterContext,
+    createBackupEngine: nodeBackupEngine,
+    resolveExtensionPath: nodeResolveExtensionPath,
     async open(path, options) {
       const { DatabaseSync } = await import('node:sqlite');
       const db = new DatabaseSync(path, { readOnly: options?.readonly ?? false });
       if (options?.walMode !== false) db.exec("PRAGMA journal_mode = WAL");
-      db.exec("PRAGMA synchronous = NORMAL");
+      db.exec(`PRAGMA synchronous = ${synchronousPragmaValue(options?.synchronous)}`);
       db.exec("PRAGMA foreign_keys = ON");
       db.exec(`PRAGMA busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
+      const batchStatementFor = createStatementCache((sql) => {
+        const stmt = db.prepare(sql);
+        stmt.setReadBigInts(true);
+        return stmt;
+      });
       const conn = {
         async exec(sql) {
           db.exec(sql);
         },
         async prepare(sql) {
           const stmt = db.prepare(sql);
+          stmt.setReadBigInts(true);
           return {
             async all(...params) {
+              return narrowRowsIntegers(stmt.all(...params));
+            },
+            async allRaw(...params) {
               return stmt.all(...params);
             },
             async get(...params) {
-              return stmt.get(...params);
+              return narrowRowIntegers(stmt.get(...params));
             },
             async run(...params) {
               const result = stmt.run(...params);
               return {
                 changes: Number(result.changes),
-                lastInsertRowId: result.lastInsertRowid
+                lastInsertRowId: narrowSafeBigInt(result.lastInsertRowid)
               };
             }
           };
         },
+        async runBatch(sql, paramsBatch) {
+          const stmt = batchStatementFor(sql);
+          const results = new Array(paramsBatch.length);
+          for (let i = 0; i < paramsBatch.length; i++) {
+            const result = stmt.run(...paramsBatch[i]);
+            results[i] = {
+              changes: Number(result.changes),
+              lastInsertRowId: narrowSafeBigInt(result.lastInsertRowid)
+            };
+          }
+          return results;
+        },
+        async runBatchSummary(sql, paramsBatch) {
+          const stmt = batchStatementFor(sql);
+          let changes = 0;
+          for (let i = 0; i < paramsBatch.length; i++) {
+            const result = stmt.run(...paramsBatch[i]);
+            changes += Number(result.changes);
+          }
+          return { rowsLoaded: paramsBatch.length, changes };
+        },
         async transaction(fn) {
           await conn.exec("BEGIN");
           try {

package/dist/driver/wa-sqlite.d.ts

@@ -1,29 +1,138 @@
+/** Options for scheduled backups. */
+interface BackupScheduleOptions {
+    /** Cron expression (e.g., '0 * * * *' for hourly). */
+    cron: string;
+    /** Directory to store backup files. */
+    destDir: string;
+    /** Maximum number of backup files to keep. Default: 5. */
+    maxFiles?: number;
+    /**
+     * Sirannon evaluates the cron expression in this IANA time zone (e.g. 'America/New_York').
+     * When omitted, it uses the host's local time zone, which also sets the daylight saving rules that apply.
+     */
+    timezone?: string;
+    /** Called when a scheduled backup fails. Without this, errors are silently discarded. */
+    onError?: (error: Error) => void;
+}
+
+interface WorkerHostOptions {
+    writeTimeoutMs?: number;
+    maxRestarts?: number;
+}
+
 interface RunResult {
     changes: number;
     lastInsertRowId: number | bigint;
 }
+/**
+ * Tells a caller running inside the operation that holds the writer from one
+ * merely waiting on it. A runtime without async context tracking cannot answer
+ * this, and answering it wrongly runs one caller's writes inside another
+ * caller's transaction.
+ */
+interface WriterContext {
+    run<T>(operation: () => T): T;
+    isActive(): boolean;
+    exit<T>(operation: () => T): T;
+}
+interface BackupEngine {
+    backup(conn: SQLiteConnection, destPath: string): Promise<void>;
+    schedule(conn: SQLiteConnection, options: BackupScheduleOptions, runExclusive: (op: () => Promise<void>) => Promise<void>): () => void;
+}
+interface BatchSummary {
+    rowsLoaded: number;
+    changes: number;
+}
 interface SQLiteStatement {
     all<T = unknown>(...params: unknown[]): Promise<T[]>;
     get<T = unknown>(...params: unknown[]): Promise<T | undefined>;
     run(...params: unknown[]): Promise<RunResult>;
+    /**
+     * Like {@link all} but skips the safe-range BigInt narrowing, leaving every
+     * integer as a BigInt. The server wire path narrows and tags in one pass, so
+     * feeding it raw rows avoids a second walk. Optional: a driver that omits it
+     * falls back to {@link all}, still correct but with the extra narrowing walk.
+     */
+    allRaw?<T = unknown>(...params: unknown[]): Promise<T[]>;
 }
+interface GroupRunError {
+    message: string;
+    name?: string;
+    code?: string;
+}
+type GroupRunOutcome = {
+    ok: true;
+    results: RunResult[];
+} | {
+    ok: false;
+    error: GroupRunError;
+};
 interface SQLiteConnection {
     exec(sql: string): Promise<void>;
     prepare(sql: string): Promise<SQLiteStatement>;
     transaction<T>(fn: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
     close(): Promise<void>;
+    runBatch?(sql: string, paramsBatch: readonly unknown[][]): Promise<RunResult[]>;
+    runBatchSummary?(sql: string, paramsBatch: readonly unknown[][]): Promise<BatchSummary>;
+    /**
+     * Runs several independent units in one transaction, one outcome per unit in
+     * order. A unit is one write or one whole transaction, and a unit that fails
+     * must not disturb the others.
+     */
+    runGroup?(units: readonly {
+        statements: readonly {
+            sql: string;
+            params?: readonly unknown[];
+        }[];
+    }[]): Promise<GroupRunOutcome[]>;
 }
+/**
+ * SQLite `PRAGMA synchronous` level applied to a connection. `normal` is safe
+ * from corruption in WAL mode but can lose the most recent commits on power
+ * loss; `full` fsyncs every commit; `extra` adds a directory sync after the
+ * rollback journal is unlinked in DELETE journal mode and equals `full` in
+ * WAL mode; `off` hands writes to the OS without syncing and is sanctioned
+ * only for re-runnable bulk loads.
+ */
+type SynchronousLevel = 'off' | 'normal' | 'full' | 'extra';
 interface OpenOptions {
     readonly?: boolean;
     walMode?: boolean;
+    synchronous?: SynchronousLevel;
 }
 interface DriverCapabilities {
     multipleConnections: boolean;
     extensions: boolean;
 }
+/**
+ * Lets a worker thread rebuild the driver, since the driver's `open` function
+ * cannot cross the thread boundary. `specifier` must be importable from the
+ * worker and `config` must survive a structured clone; the worker imports the
+ * module and calls its `exportName` factory (default export otherwise) with it.
+ */
+interface DriverWorkerEntry {
+    specifier: string;
+    exportName?: string;
+    config?: unknown;
+}
 interface SQLiteDriver {
     readonly capabilities: DriverCapabilities;
     open(path: string, options?: OpenOptions): Promise<SQLiteConnection>;
+    readonly worker?: DriverWorkerEntry;
+    /**
+     * Offloads writes to a worker thread. Only a driver whose runtime has
+     * threads implements this, which is what keeps the thread machinery out of
+     * bundles built for runtimes that do not.
+     */
+    startWriterHost?(path: string, options: OpenOptions, hostOptions?: WorkerHostOptions): Promise<SQLiteConnection>;
+    createWriterContext?(): WriterContext;
+    createBackupEngine?(): BackupEngine;
+    /**
+     * Makes an extension path absolute. Passing a bare name to `load_extension`
+     * would let the dynamic linker search its own paths and open a different
+     * library than the operator named.
+     */
+    resolveExtensionPath?(extensionPath: string): string;
 }
 
 interface WaSqliteOptions {

package/dist/driver/wa-sqlite.mjs

@@ -12,12 +12,40 @@ function defineDriver(config) {
   if (!config.capabilities || typeof config.open !== "function") {
     throw new SirannonError("Driver must define capabilities and open()", "INVALID_DRIVER");
   }
+  if (config.worker !== void 0 && typeof config.worker.specifier !== "string") {
+    throw new SirannonError("Driver worker entry must define a string specifier", "INVALID_DRIVER");
+  }
   return Object.freeze({
     capabilities: Object.freeze({ ...config.capabilities }),
-    open: config.open
+    open: config.open,
+    ...config.worker ? { worker: Object.freeze({ ...config.worker }) } : {},
+    ...config.startWriterHost ? { startWriterHost: config.startWriterHost } : {},
+    ...config.createWriterContext ? { createWriterContext: config.createWriterContext } : {},
+    ...config.createBackupEngine ? { createBackupEngine: config.createBackupEngine } : {},
+    ...config.resolveExtensionPath ? { resolveExtensionPath: config.resolveExtensionPath } : {}
   });
 }
 
+// src/core/driver/synchronous.ts
+var DEFAULT_SYNCHRONOUS = "normal";
+var SYNCHRONOUS_PRAGMA_VALUES = {
+  off: "OFF",
+  normal: "NORMAL",
+  full: "FULL",
+  extra: "EXTRA"
+};
+function synchronousPragmaValue(level) {
+  const resolved = level ?? DEFAULT_SYNCHRONOUS;
+  const value = SYNCHRONOUS_PRAGMA_VALUES[resolved];
+  if (value === void 0) {
+    throw new SirannonError(
+      `Invalid synchronous level '${String(resolved)}': expected 'off', 'normal', 'full', or 'extra'`,
+      "INVALID_SYNCHRONOUS"
+    );
+  }
+  return value;
+}
+
 // src/drivers/wa-sqlite/index.ts
 function waSqlite(driverOptions) {
   return defineDriver({
@@ -46,7 +74,7 @@ function waSqlite(driverOptions) {
         } catch {
         }
       }
-      await sqlite3.exec(db, "PRAGMA synchronous = NORMAL");
+      await sqlite3.exec(db, `PRAGMA synchronous = ${synchronousPragmaValue(options?.synchronous)}`);
       await sqlite3.exec(db, "PRAGMA foreign_keys = ON");
       async function execStatements(sql, params) {
         const columns = [];