@delali/sirannon-db 0.1.6 → 0.1.7

package/dist/core/index.mjs

@@ -1,13 +1,15 @@
-import { SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling } from '../chunk-UTO3ZAFS.mjs';
-export { ChangeTracker } from '../chunk-UTO3ZAFS.mjs';
-export { defineDriver } from '../chunk-74UN4DIE.mjs';
-import { BackupManager, BackupScheduler } from '../chunk-PXKAKK2V.mjs';
-export { BackupManager, BackupScheduler } from '../chunk-PXKAKK2V.mjs';
-import { Transaction, query, queryOne, execute, executeBatch } from '../chunk-3MCMONVP.mjs';
-export { Transaction, execute, executeBatch, query, queryOne } from '../chunk-3MCMONVP.mjs';
-import '../chunk-GS7T5YMI.mjs';
-import { ConnectionPoolError, MigrationError, ReadOnlyError, SirannonError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError } from '../chunk-O7BHI3CF.mjs';
-export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, SirannonError, TransactionError } from '../chunk-O7BHI3CF.mjs';
+import { runBulkLoad, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling } from '../chunk-HHRMRFFR.mjs';
+export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-HHRMRFFR.mjs';
+export { defineDriver } from '../chunk-BNUTBHHH.mjs';
+import { DEFAULT_SYNCHRONOUS } from '../chunk-CJLYFDP5.mjs';
+export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-CJLYFDP5.mjs';
+import { Transaction } from '../chunk-TKGHYWQ6.mjs';
+export { Transaction } from '../chunk-TKGHYWQ6.mjs';
+import { query, queryForWire, queryOne, executeBatch, executeBatchSummary, execute, bindParams, executeGroup } from '../chunk-CW6S3WL5.mjs';
+export { execute, executeBatch, query, queryOne } from '../chunk-CW6S3WL5.mjs';
+import { MIGRATIONS_TABLE } from '../chunk-GEZUUIKV.mjs';
+import { SirannonError, ConnectionPoolError, MigrationError, ReadOnlyError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, WriteOverloadError, ExtensionError } from '../chunk-YPYVQJ4C.mjs';
+export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, ForbiddenSqlError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, SirannonError, TransactionError, WriteOverloadError } from '../chunk-YPYVQJ4C.mjs';
 
 // src/core/connection-pool.ts
 async function closeAllSilently(connections) {
@@ -29,12 +31,22 @@ var ConnectionPool = class _ConnectionPool {
     this.readers = readers;
   }
   static async create(options) {
-    const { driver, path, readOnly = false, readPoolSize = 4, walMode = true } = options;
+    const { driver, path, readOnly = false, readPoolSize = 4, walMode = true, synchronous } = options;
     let writer = null;
     const readers = [];
     try {
       if (!readOnly) {
-        writer = await driver.open(path, { walMode });
+        if (options.useWriterWorker) {
+          if (!driver.startWriterHost) {
+            throw new SirannonError(
+              "writerWorker is enabled but the driver does not carry a worker entry; use a driver that supports it or disable writerWorker",
+              "WRITER_WORKER_UNSUPPORTED"
+            );
+          }
+          writer = await driver.startWriterHost(path, { walMode, synchronous }, options.workerHostOptions);
+        } else {
+          writer = await driver.open(path, { walMode, synchronous });
+        }
       }
       const poolSize = driver.capabilities.multipleConnections ? Math.max(readPoolSize, 1) : 0;
       for (let i = 0; i < poolSize; i++) {
@@ -120,6 +132,48 @@ async function applyDdlSideEffects(tracker, writerConn, sql) {
     await tracker.pruneDroppedTables(writerConn, [dropped]);
   }
 }
+function applyDdlSideEffectsIfRelevant(tracker, writerConn, sql) {
+  if (!tracker || !isCdcRelevantDdl(sql)) {
+    return Promise.resolve();
+  }
+  return applyDdlSideEffects(tracker, writerConn, sql);
+}
+
+// src/core/database-backup.ts
+var DatabaseBackupController = class {
+  constructor(runExclusive, acquireWriter, engine) {
+    this.runExclusive = runExclusive;
+    this.acquireWriter = acquireWriter;
+    this.engine = engine;
+  }
+  cancellers = [];
+  require() {
+    if (!this.engine) {
+      throw new SirannonError(
+        "Backups need a driver that can write files; this driver does not provide one",
+        "BACKUP_UNSUPPORTED"
+      );
+    }
+    return this.engine;
+  }
+  backup(destPath) {
+    const engine = this.require();
+    return this.runExclusive(() => engine.backup(this.acquireWriter(), destPath));
+  }
+  schedule(options) {
+    const engine = this.require();
+    this.cancellers.push(engine.schedule(this.acquireWriter(), options, this.runExclusive));
+  }
+  cancelAll() {
+    for (const cancel of this.cancellers) {
+      try {
+        cancel();
+      } catch {
+      }
+    }
+    this.cancellers.length = 0;
+  }
+};
 
 // src/core/cdc/cdc-aware-transaction.ts
 var CdcAwareTransaction = class extends Transaction {
@@ -148,9 +202,169 @@ var CdcAwareTransaction = class extends Transaction {
   }
 };
 
+// src/core/database-cdc.ts
+var DatabaseCdcController = class {
+  constructor(runExclusive, acquireWriter, pollInterval, retention) {
+    this.runExclusive = runExclusive;
+    this.acquireWriter = acquireWriter;
+    this.pollInterval = pollInterval;
+    this.retention = retention;
+  }
+  tracker = null;
+  subscriptions = null;
+  stopPolling = null;
+  get changeTracker() {
+    return this.tracker;
+  }
+  async watch(table) {
+    const { tracker } = this.ensure();
+    await this.runExclusive(() => tracker.watch(this.acquireWriter(), table));
+    this.ensurePolling();
+  }
+  async unwatch(table) {
+    const tracker = this.tracker;
+    if (!tracker) return;
+    await this.runExclusive(() => tracker.unwatch(this.acquireWriter(), table));
+    if (tracker.watchedTables.size === 0) {
+      this.stop();
+    }
+  }
+  on(table) {
+    const { subscriptions } = this.ensure();
+    return new SubscriptionBuilderImpl(table, subscriptions);
+  }
+  async runTransaction(writer, fn) {
+    const tracker = this.tracker;
+    if (!tracker) {
+      return Transaction.run(writer, fn);
+    }
+    const state = { sawDdl: false, droppedTables: [] };
+    const result = await writer.transaction((txConn) => fn(new CdcAwareTransaction(txConn, tracker, state)));
+    if (state.sawDdl && state.droppedTables.length > 0) {
+      await tracker.pruneDroppedTables(writer, state.droppedTables);
+    }
+    return result;
+  }
+  stop() {
+    if (this.stopPolling) {
+      this.stopPolling();
+      this.stopPolling = null;
+    }
+  }
+  ensure() {
+    const tracker = this.tracker ?? new ChangeTracker({ retention: this.retention });
+    const subscriptions = this.subscriptions ?? new SubscriptionManager();
+    this.tracker = tracker;
+    this.subscriptions = subscriptions;
+    return { tracker, subscriptions };
+  }
+  ensurePolling() {
+    if (this.stopPolling) return;
+    if (!this.tracker || !this.subscriptions) return;
+    this.stopPolling = startPolling(
+      this.acquireWriter(),
+      this.tracker,
+      this.subscriptions,
+      this.pollInterval,
+      void 0,
+      this.runExclusive
+    );
+  }
+};
+
+// src/core/hooks/query-hooks.ts
+function fireBeforeQueryHooks(parentHooks, localHooks, databaseId, sql, params, options) {
+  const hasParent = parentHooks?.has("beforeQuery");
+  const hasLocal = localHooks.has("beforeQuery");
+  if (!hasParent && !hasLocal) return;
+  const ctx = {
+    databaseId,
+    sql,
+    params,
+    writeConcern: options?.writeConcern,
+    readConcern: options?.readConcern
+  };
+  parentHooks?.invokeSync("beforeQuery", ctx);
+  localHooks.invokeSync("beforeQuery", ctx);
+}
+function fireAfterQueryHooks(parentHooks, localHooks, databaseId, sql, params, durationMs) {
+  const hasParent = parentHooks?.has("afterQuery");
+  const hasLocal = localHooks.has("afterQuery");
+  if (!hasParent && !hasLocal) return;
+  const ctx = { databaseId, sql, params, durationMs };
+  try {
+    parentHooks?.invokeSync("afterQuery", ctx);
+  } catch {
+  }
+  try {
+    localHooks.invokeSync("afterQuery", ctx);
+  } catch {
+  }
+}
+
+// src/core/database-observability.ts
+var DatabaseObserver = class {
+  constructor(databaseId, localHooks, parentHooks, metrics) {
+    this.databaseId = databaseId;
+    this.localHooks = localHooks;
+    this.parentHooks = parentHooks;
+    this.metrics = metrics;
+  }
+  /** False lets a caller skip the timing calls on a path where nothing would read them. */
+  get observesQueries() {
+    return this.metrics !== null || this.localHooks.has("beforeQuery") || this.localHooks.has("afterQuery") || (this.parentHooks?.has("beforeQuery") ?? false) || (this.parentHooks?.has("afterQuery") ?? false);
+  }
+  async withQueryHooks(sql, params, options, op) {
+    this.fireBefore(sql, params, options);
+    const start = performance.now();
+    try {
+      return await op();
+    } finally {
+      this.fireAfter(sql, params, performance.now() - start);
+    }
+  }
+  track(sql, op) {
+    if (!this.metrics) return op();
+    return this.metrics.trackQuery(op, { databaseId: this.databaseId, sql });
+  }
+  /**
+   * Reports each statement separately, since a hook filtering on SQL has no other
+   * way to see them. They share the transaction's duration because the group runs
+   * them back to back under one commit and no statement has a duration of its own,
+   * which is already what a grouped {@link Database.execute} reports.
+   */
+  async withTransactionHooks(statements, op) {
+    for (const statement of statements) this.fireBefore(statement.sql, statement.params);
+    const start = performance.now();
+    try {
+      return await this.trackEach(statements, op);
+    } finally {
+      const durationMs = performance.now() - start;
+      for (const statement of statements) this.fireAfter(statement.sql, statement.params, durationMs);
+    }
+  }
+  trackEach(statements, op) {
+    const metrics = this.metrics;
+    if (!metrics) return op();
+    let run = op;
+    for (const statement of statements) {
+      const inner = run;
+      const sql = statement.sql;
+      run = () => metrics.trackQuery(inner, { databaseId: this.databaseId, sql });
+    }
+    return run();
+  }
+  fireBefore(sql, params, options) {
+    fireBeforeQueryHooks(this.parentHooks, this.localHooks, this.databaseId, sql, params, options);
+  }
+  fireAfter(sql, params, durationMs) {
+    fireAfterQueryHooks(this.parentHooks, this.localHooks, this.databaseId, sql, params, durationMs);
+  }
+};
+
 // src/core/extension-loader.ts
 async function loadExtension(driver, writer, extensionPath) {
-  if (!driver.capabilities.extensions) {
+  if (!driver.capabilities.extensions || !driver.resolveExtensionPath) {
     throw new ExtensionError(extensionPath, "Extensions are not supported by the current driver");
   }
   if (!extensionPath || extensionPath.includes("\0")) {
@@ -165,8 +379,7 @@ async function loadExtension(driver, writer, extensionPath) {
   if (segments.includes("..")) {
     throw new ExtensionError(extensionPath, "Extension path must not contain directory traversal segments");
   }
-  const { resolve } = await import('path');
-  const resolved = resolve(extensionPath);
+  const resolved = driver.resolveExtensionPath(extensionPath);
   try {
     const escaped = resolved.replace(/'/g, "''");
     await writer.exec(`SELECT load_extension('${escaped}')`);
@@ -175,6 +388,137 @@ async function loadExtension(driver, writer, extensionPath) {
   }
 }
 
+// src/core/group-committer.ts
+var DEFAULT_MAX_GROUP_SIZE = 1e3;
+var DML_PREFIX_RE = /^\s*(?:INSERT|UPDATE|DELETE|REPLACE)\b/i;
+function isGroupable(sql) {
+  return DML_PREFIX_RE.test(sql);
+}
+function canGroupTransaction(statements) {
+  for (const statement of statements) {
+    if (!isGroupable(statement.sql)) return false;
+  }
+  return true;
+}
+var GroupCommitter = class {
+  constructor(writerLock, hooks, maxGroup = DEFAULT_MAX_GROUP_SIZE) {
+    this.writerLock = writerLock;
+    this.hooks = hooks;
+    this.maxGroup = maxGroup;
+  }
+  pending = [];
+  running = false;
+  scheduled = false;
+  loopPromise = Promise.resolve();
+  submit(sql, params) {
+    return new Promise((resolve, reject) => {
+      this.pending.push({
+        statements: [{ sql, params }],
+        resolve: (values) => resolve(values[0]),
+        reject
+      });
+      this.schedule();
+    });
+  }
+  submitTransaction(statements) {
+    return new Promise((resolve, reject) => {
+      this.pending.push({ statements, resolve, reject });
+      this.schedule();
+    });
+  }
+  async drain() {
+    while (this.running || this.pending.length > 0) {
+      if (!this.running) this.schedule();
+      await this.loopPromise;
+    }
+  }
+  runUngrouped(sql, params) {
+    return this.writerLock.run(() => this.runSingle({ sql, params }));
+  }
+  schedule() {
+    if (this.running || this.scheduled) return;
+    this.scheduled = true;
+    queueMicrotask(() => {
+      this.scheduled = false;
+      this.writerLock.detached(() => this.runLoop());
+    });
+  }
+  runLoop() {
+    if (this.running) return;
+    this.running = true;
+    this.loopPromise = (async () => {
+      try {
+        while (this.pending.length > 0) {
+          await this.flush(this.takeBatch());
+        }
+      } finally {
+        this.running = false;
+        if (this.pending.length > 0) this.schedule();
+      }
+    })();
+  }
+  takeBatch() {
+    const pending = this.pending;
+    if (!canGroupTransaction(pending[0].statements)) return pending.splice(0, 1);
+    let n = 1;
+    let statements = pending[0].statements.length;
+    while (n < pending.length && canGroupTransaction(pending[n].statements)) {
+      const size = pending[n].statements.length;
+      if (statements + size > this.maxGroup) break;
+      statements += size;
+      n++;
+    }
+    return pending.splice(0, n);
+  }
+  async flush(batch) {
+    const lone = batch[0];
+    if (batch.length === 1 && lone.statements.length === 1) {
+      try {
+        lone.resolve([await this.writerLock.run(() => this.runSingle(lone.statements[0]))]);
+      } catch (err) {
+        lone.reject(err);
+      }
+      return;
+    }
+    let outcomes;
+    try {
+      outcomes = await this.writerLock.run(() => this.runGroup(batch));
+    } catch (err) {
+      for (const job of batch) job.reject(err);
+      return;
+    }
+    for (let i = 0; i < batch.length; i++) {
+      const outcome = outcomes[i];
+      if (outcome.ok) batch[i].resolve(outcome.values);
+      else batch[i].reject(outcome.error);
+    }
+  }
+  async runSingle(statement) {
+    const writer = this.hooks.acquireWriter();
+    const result = await execute(writer, statement.sql, statement.params);
+    await this.hooks.afterCommit(writer, statement.sql);
+    return result;
+  }
+  async runGroup(batch) {
+    const writer = this.hooks.acquireWriter();
+    const units = batch.map((job) => ({
+      statements: job.statements.map((statement) => ({ sql: statement.sql, params: bindParams(statement.params) }))
+    }));
+    if (writer.runGroup) {
+      const raw = await writer.runGroup(units);
+      return raw.map(
+        (outcome) => outcome.ok ? { ok: true, values: outcome.results } : { ok: false, error: toError(outcome.error) }
+      );
+    }
+    return executeGroup(writer, units);
+  }
+};
+function toError(error) {
+  const err = error.code ? new SirannonError(error.message, error.code) : new Error(error.message);
+  if (error.name) err.name = error.name;
+  return err;
+}
+
 // src/core/hooks/registry.ts
 var HOOK_CONFIG_MAP = {
   onBeforeQuery: "beforeQuery",
@@ -259,7 +603,7 @@ var HookRegistry = class {
 
 // src/core/migrations/runner.ts
 var CREATE_TRACKING_TABLE = `
-  CREATE TABLE IF NOT EXISTS _sirannon_migrations (
+  CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
     version INTEGER PRIMARY KEY,
     name TEXT NOT NULL,
     applied_at REAL NOT NULL DEFAULT (unixepoch('subsec'))
@@ -276,7 +620,7 @@ var MigrationRunner = class _MigrationRunner {
     }
     const appliedEntries = [];
     await conn.transaction(async (txConn) => {
-      const insertStmt = await txConn.prepare("INSERT INTO _sirannon_migrations (version, name) VALUES (?, ?)");
+      const insertStmt = await txConn.prepare(`INSERT INTO ${MIGRATIONS_TABLE} (version, name) VALUES (?, ?)`);
       for (const migration of pending) {
         try {
           if (typeof migration.up === "string") {
@@ -310,7 +654,7 @@ var MigrationRunner = class _MigrationRunner {
       );
     }
     await conn.exec(CREATE_TRACKING_TABLE);
-    const selectStmt = await conn.prepare("SELECT version, name FROM _sirannon_migrations ORDER BY version DESC");
+    const selectStmt = await conn.prepare(`SELECT version, name FROM ${MIGRATIONS_TABLE} ORDER BY version DESC`);
     const appliedRows = await selectStmt.all();
     if (appliedRows.length === 0) {
       return { rolledBack: [] };
@@ -337,7 +681,7 @@ var MigrationRunner = class _MigrationRunner {
     }
     const rolledBackEntries = [];
     await conn.transaction(async (txConn) => {
-      const deleteStmt = await txConn.prepare("DELETE FROM _sirannon_migrations WHERE version = ?");
+      const deleteStmt = await txConn.prepare(`DELETE FROM ${MIGRATIONS_TABLE} WHERE version = ?`);
       for (const entry of rollbackSet) {
         const migration = downByVersion.get(entry.version);
         if (!migration) {
@@ -408,12 +752,90 @@ var MigrationRunner = class _MigrationRunner {
     return [...migrations].sort((a, b) => a.version - b.version);
   }
   static async getAppliedVersions(conn) {
-    const stmt = await conn.prepare("SELECT version FROM _sirannon_migrations ORDER BY version");
+    const stmt = await conn.prepare(`SELECT version FROM ${MIGRATIONS_TABLE} ORDER BY version`);
     const rows = await stmt.all();
     return new Set(rows.map((r) => r.version));
   }
 };
 
+// src/core/worker/config.ts
+var DEFAULT_MAX_PENDING_WRITES = 1024;
+var DEFAULT_RETRY_AFTER_MS = 1e3;
+function requireCount(value, name, min) {
+  if (!Number.isInteger(value) || value < min) {
+    throw new SirannonError(`writerWorker.${name} must be an integer >= ${min}`, "INVALID_WRITER_WORKER");
+  }
+  return value;
+}
+function resolveWriterWorkerConfig(option) {
+  if (!option) {
+    return { enabled: false, maxPendingWrites: 0, retryAfterMs: DEFAULT_RETRY_AFTER_MS, host: {} };
+  }
+  const opts = option === true ? {} : option;
+  const host = {};
+  if (opts.writeTimeoutMs !== void 0) host.writeTimeoutMs = requireCount(opts.writeTimeoutMs, "writeTimeoutMs", 0);
+  if (opts.maxRestarts !== void 0) host.maxRestarts = requireCount(opts.maxRestarts, "maxRestarts", 0);
+  const maxPendingWrites = opts.maxPendingWrites === void 0 ? DEFAULT_MAX_PENDING_WRITES : requireCount(opts.maxPendingWrites, "maxPendingWrites", 1);
+  return { enabled: true, maxPendingWrites, retryAfterMs: DEFAULT_RETRY_AFTER_MS, host };
+}
+
+// src/core/worker/gate.ts
+var WriteGate = class {
+  constructor(limit, retryAfterMs) {
+    this.limit = limit;
+    this.retryAfterMs = retryAfterMs;
+  }
+  inFlight = 0;
+  run(op) {
+    if (this.limit > 0 && this.inFlight >= this.limit) {
+      return Promise.reject(new WriteOverloadError(this.limit, this.retryAfterMs));
+    }
+    this.inFlight++;
+    return op().finally(() => {
+      this.inFlight--;
+    });
+  }
+};
+
+// src/core/writer-lock.ts
+var UNTRACKED = {
+  run: (operation) => operation(),
+  isActive: () => false,
+  exit: (operation) => operation()
+};
+var WriterLock = class {
+  tail = Promise.resolve();
+  context;
+  constructor(context) {
+    this.context = context ?? UNTRACKED;
+  }
+  run(operation) {
+    if (this.context.isActive()) {
+      return operation();
+    }
+    const enter = () => this.context.run(operation);
+    const ticket = this.tail.then(enter, enter);
+    this.tail = ticket.then(swallow, swallow);
+    return ticket;
+  }
+  isHeld() {
+    return this.context.isActive();
+  }
+  async settle() {
+    await this.run(() => Promise.resolve());
+  }
+  /**
+   * Work scheduled from inside a held operation inherits it, so shared
+   * machinery must detach or it runs every caller's work inside one caller's
+   * transaction.
+   */
+  detached(operation) {
+    return this.context.exit(operation);
+  }
+};
+function swallow() {
+}
+
 // src/core/database.ts
 var Database = class _Database {
   id;
@@ -421,184 +843,252 @@ var Database = class _Database {
   readOnly;
   pool;
   driver;
+  synchronous;
+  walMode;
+  writerLock;
+  writeGate;
+  groupCommitter;
   closeListeners = [];
   _closed = false;
-  changeTracker = null;
-  subscriptionManager = null;
-  stopCdcPolling = null;
-  cdcPollInterval;
-  cdcRetention;
+  cdc;
   hookRegistry = new HookRegistry();
-  parentHooks;
-  metricsCollector;
-  backupManager = new BackupManager();
-  backupScheduler = new BackupScheduler(this.backupManager);
-  scheduledBackupCancellers = [];
-  constructor(id, path, pool, driver, options, internals) {
+  observer;
+  backups;
+  constructor(id, path, pool, driver, writeGate, options, internals) {
     this.id = id;
     this.path = path;
     this.pool = pool;
     this.driver = driver;
+    this.writeGate = writeGate;
+    this.writerLock = new WriterLock(driver.createWriterContext?.());
+    this.backups = new DatabaseBackupController(
+      (op) => this.writerLock.run(op),
+      () => this.pool.acquireWriter(),
+      driver.createBackupEngine?.()
+    );
     this.readOnly = options?.readOnly ?? false;
-    this.cdcPollInterval = options?.cdcPollInterval ?? 50;
-    this.cdcRetention = options?.cdcRetention ?? 36e5;
-    this.parentHooks = internals?.parentHooks ?? null;
-    this.metricsCollector = internals?.metrics ?? null;
+    this.synchronous = options?.synchronous ?? DEFAULT_SYNCHRONOUS;
+    this.walMode = options?.walMode ?? true;
+    this.observer = new DatabaseObserver(
+      id,
+      this.hookRegistry,
+      internals?.parentHooks ?? null,
+      internals?.metrics ?? null
+    );
+    this.cdc = new DatabaseCdcController(
+      (op) => this.writerLock.run(op),
+      () => this.pool.acquireWriter(),
+      options?.cdcPollInterval ?? 50,
+      options?.cdcRetention ?? 36e5
+    );
+    this.groupCommitter = new GroupCommitter(this.writerLock, {
+      acquireWriter: () => this.pool.acquireWriter(),
+      afterCommit: (writer, sql) => applyDdlSideEffectsIfRelevant(this.cdc.changeTracker, writer, sql)
+    });
   }
   static async create(id, path, driver, options, internals) {
+    const writerWorker = resolveWriterWorkerConfig(options?.writerWorker);
+    const readOnly = options?.readOnly ?? false;
+    if (writerWorker.enabled && !readOnly && !driver.startWriterHost) {
+      throw new SirannonError(
+        `writerWorker is enabled for database '${id}' but the driver does not carry a worker entry; use a driver that supports worker offload or disable writerWorker`,
+        "WRITER_WORKER_UNSUPPORTED"
+      );
+    }
     const pool = await ConnectionPool.create({
       driver,
       path,
       readOnly: options?.readOnly,
       readPoolSize: options?.readPoolSize ?? 4,
-      walMode: options?.walMode ?? true
+      walMode: options?.walMode ?? true,
+      synchronous: options?.synchronous,
+      useWriterWorker: writerWorker.enabled && !readOnly,
+      workerHostOptions: writerWorker.host
     });
-    return new _Database(id, path, pool, driver, options, internals);
+    const writeGate = new WriteGate(writerWorker.enabled ? writerWorker.maxPendingWrites : 0, writerWorker.retryAfterMs);
+    return new _Database(id, path, pool, driver, writeGate, options, internals);
   }
   async query(sql, params, options) {
     this.ensureOpen();
-    this.fireBeforeQueryHooks(sql, params, options);
-    const start = performance.now();
-    try {
-      const reader = this.pool.acquireReader();
-      if (this.metricsCollector) {
-        return await this.metricsCollector.trackQuery(() => query(reader, sql, params), {
-          databaseId: this.id,
-          sql
-        });
-      }
-      return await query(reader, sql, params);
-    } finally {
-      this.fireAfterQueryHooks(sql, params, performance.now() - start);
-    }
+    return this.observer.withQueryHooks(
+      sql,
+      params,
+      options,
+      () => this.runRead(sql, (conn) => query(conn, sql, params))
+    );
+  }
+  /**
+   * 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.
+   */
+  async queryForWire(sql, params, options) {
+    this.ensureOpen();
+    return this.observer.withQueryHooks(
+      sql,
+      params,
+      options,
+      () => this.runRead(sql, (conn) => queryForWire(conn, sql, params))
+    );
   }
   async queryOne(sql, params, options) {
     this.ensureOpen();
-    this.fireBeforeQueryHooks(sql, params, options);
-    const start = performance.now();
-    try {
-      const reader = this.pool.acquireReader();
-      if (this.metricsCollector) {
-        return await this.metricsCollector.trackQuery(() => queryOne(reader, sql, params), {
-          databaseId: this.id,
-          sql
-        });
-      }
-      return await queryOne(reader, sql, params);
-    } finally {
-      this.fireAfterQueryHooks(sql, params, performance.now() - start);
+    return this.observer.withQueryHooks(
+      sql,
+      params,
+      options,
+      () => this.runRead(sql, (conn) => queryOne(conn, sql, params))
+    );
+  }
+  /**
+   * 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.
+   */
+  runRead(sql, op) {
+    if (this.pool.readerCount === 0) {
+      return this.writerLock.run(() => this.observer.track(sql, () => op(this.pool.acquireWriter())));
     }
+    return this.observer.track(sql, () => op(this.pool.acquireReader()));
   }
   async execute(sql, params, options) {
     this.ensureOpen();
     if (this.readOnly) throw new ReadOnlyError(this.id);
-    this.fireBeforeQueryHooks(sql, params, options);
-    const start = performance.now();
-    try {
-      const writer = this.pool.acquireWriter();
-      const result = this.metricsCollector ? await this.metricsCollector.trackQuery(() => execute(writer, sql, params), {
-        databaseId: this.id,
-        sql
-      }) : await execute(writer, sql, params);
-      await this.maybeApplyDdlSideEffects(writer, sql);
-      return result;
-    } finally {
-      this.fireAfterQueryHooks(sql, params, performance.now() - start);
-    }
+    return this.observer.withQueryHooks(
+      sql,
+      params,
+      options,
+      () => this.writeGate.run(
+        () => this.observer.track(
+          sql,
+          () => this.writerLock.isHeld() ? this.groupCommitter.runUngrouped(sql, params) : this.groupCommitter.submit(sql, params)
+        )
+      )
+    );
   }
   async executeBatch(sql, paramsBatch, options) {
     this.ensureOpen();
     if (this.readOnly) throw new ReadOnlyError(this.id);
-    this.fireBeforeQueryHooks(sql, void 0, options);
-    const start = performance.now();
-    try {
-      const writer = this.pool.acquireWriter();
-      const batchFn = () => writer.transaction(async (txConn) => executeBatch(txConn, sql, paramsBatch));
-      const results = this.metricsCollector ? await this.metricsCollector.trackQuery(batchFn, {
-        databaseId: this.id,
-        sql
-      }) : await batchFn();
-      await this.maybeApplyDdlSideEffects(writer, sql);
-      return results;
-    } finally {
-      this.fireAfterQueryHooks(sql, void 0, performance.now() - start);
-    }
+    return this.observer.withQueryHooks(
+      sql,
+      void 0,
+      options,
+      () => this.writeGate.run(
+        () => this.writerLock.run(
+          () => this.runInTransaction(this.pool.acquireWriter(), sql, (txConn) => executeBatch(txConn, sql, paramsBatch))
+        )
+      )
+    );
+  }
+  async runInTransaction(writer, sql, run) {
+    const result = await this.observer.track(sql, () => writer.transaction(run));
+    await applyDdlSideEffectsIfRelevant(this.cdc.changeTracker, writer, sql);
+    return result;
   }
-  async transaction(fn) {
+  /**
+   * 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.
+   */
+  async bulkLoad(sql, paramsBatch, options) {
     this.ensureOpen();
     if (this.readOnly) throw new ReadOnlyError(this.id);
-    const writer = this.pool.acquireWriter();
-    const tracker = this.changeTracker;
-    if (!tracker) {
-      return Transaction.run(writer, fn);
-    }
-    const state = { sawDdl: false, droppedTables: [] };
-    const result = await writer.transaction(async (txConn) => {
-      const tx = new CdcAwareTransaction(txConn, tracker, state);
-      return fn(tx);
+    return this.observer.withQueryHooks(
+      sql,
+      void 0,
+      void 0,
+      () => this.writeGate.run(
+        () => this.writerLock.run(() => {
+          const writer = this.pool.acquireWriter();
+          return runBulkLoad({
+            writer,
+            configuredSynchronous: this.synchronous,
+            walMode: this.walMode,
+            durability: options?.durability,
+            checkpoint: options?.checkpoint ?? true,
+            loadRows: () => this.runInTransaction(writer, sql, (txConn) => executeBatchSummary(txConn, sql, paramsBatch))
+          });
+        })
+      )
+    );
+  }
+  /**
+   * 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.
+   */
+  async executeTransaction(statements) {
+    this.ensureOpen();
+    if (this.readOnly) throw new ReadOnlyError(this.id);
+    if (statements.length === 0) return [];
+    const owned = statements.map((statement) => ({ sql: statement.sql, params: statement.params }));
+    const run = canGroupTransaction(owned) ? () => this.writeGate.run(() => this.groupCommitter.submitTransaction(owned)) : () => this.runStatementsAlone(owned);
+    if (!this.observer.observesQueries) return run();
+    return this.observer.withTransactionHooks(owned, run);
+  }
+  runStatementsAlone(statements) {
+    return this.transaction(async (tx) => {
+      const results = new Array(statements.length);
+      for (let i = 0; i < statements.length; i++) {
+        results[i] = await tx.execute(statements[i].sql, statements[i].params);
+      }
+      return results;
     });
-    if (state.sawDdl && state.droppedTables.length > 0) {
-      await tracker.pruneDroppedTables(writer, state.droppedTables);
-    }
-    return result;
   }
-  async maybeApplyDdlSideEffects(writer, sql) {
-    const tracker = this.changeTracker;
-    if (!tracker) return;
-    if (!isCdcRelevantDdl(sql)) return;
-    await applyDdlSideEffects(tracker, writer, sql);
+  async transaction(fn) {
+    this.ensureOpen();
+    if (this.readOnly) throw new ReadOnlyError(this.id);
+    return this.writeGate.run(() => this.writerLock.run(() => this.cdc.runTransaction(this.pool.acquireWriter(), fn)));
   }
   async watch(table) {
     this.ensureOpen();
     if (this.readOnly) {
       throw new ReadOnlyError(this.id);
     }
-    this.ensureCdc();
-    const writer = this.pool.acquireWriter();
-    await this.changeTracker?.watch(writer, table);
-    this.ensureCdcPolling();
+    await this.cdc.watch(table);
+  }
+  /**
+   * 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`.
+   */
+  async runCdcMaintenance(op) {
+    if (this._closed) return;
+    await this.writerLock.run(() => op(this.pool.acquireWriter()));
   }
   async unwatch(table) {
     this.ensureOpen();
-    if (!this.changeTracker) return;
-    const writer = this.pool.acquireWriter();
-    await this.changeTracker.unwatch(writer, table);
-    if (this.changeTracker.watchedTables.size === 0) {
-      this.stopCdcPollingLoop();
-    }
+    await this.cdc.unwatch(table);
   }
   on(table) {
     this.ensureOpen();
-    this.ensureCdc();
-    const manager = this.subscriptionManager;
-    if (!manager) throw new Error("subscriptionManager not initialized");
-    return new SubscriptionBuilderImpl(table, manager);
+    return this.cdc.on(table);
   }
   async migrate(migrations) {
     this.ensureOpen();
-    const writer = this.pool.acquireWriter();
-    return MigrationRunner.run(writer, migrations);
+    return this.writerLock.run(() => MigrationRunner.run(this.pool.acquireWriter(), migrations));
   }
   async rollback(migrations, version) {
     this.ensureOpen();
-    const writer = this.pool.acquireWriter();
-    return MigrationRunner.rollback(writer, migrations, version);
+    return this.writerLock.run(() => MigrationRunner.rollback(this.pool.acquireWriter(), migrations, version));
   }
   async backup(destPath) {
     this.ensureOpen();
-    const writer = this.pool.acquireWriter();
-    await this.backupManager.backup(writer, destPath);
+    await this.backups.backup(destPath);
   }
   scheduleBackup(options) {
     this.ensureOpen();
-    const writer = this.pool.acquireWriter();
-    const cancel = this.backupScheduler.schedule(writer, options);
-    this.scheduledBackupCancellers.push(cancel);
+    this.backups.schedule(options);
   }
   async loadExtension(extensionPath) {
     this.ensureOpen();
-    const writer = this.pool.acquireWriter();
-    await loadExtension(this.driver, writer, extensionPath);
+    await this.writerLock.run(() => loadExtension(this.driver, this.pool.acquireWriter(), extensionPath));
   }
   onBeforeQuery(hook) {
     this.hookRegistry.register("beforeQuery", hook);
@@ -613,16 +1103,12 @@ var Database = class _Database {
   async close() {
     if (this._closed) return;
     this._closed = true;
-    this.stopCdcPollingLoop();
-    for (const cancel of this.scheduledBackupCancellers) {
-      try {
-        cancel();
-      } catch {
-      }
-    }
-    this.scheduledBackupCancellers.length = 0;
+    this.cdc.stop();
+    this.backups.cancelAll();
     let poolError;
     try {
+      await this.groupCommitter.drain();
+      await this.writerLock.settle();
       await this.pool.close();
     } catch (err) {
       poolError = err;
@@ -648,54 +1134,6 @@ var Database = class _Database {
       throw new SirannonError(`Database '${this.id}' is closed`, "DATABASE_CLOSED");
     }
   }
-  ensureCdc() {
-    if (!this.changeTracker) {
-      this.changeTracker = new ChangeTracker({ retention: this.cdcRetention });
-    }
-    if (!this.subscriptionManager) {
-      this.subscriptionManager = new SubscriptionManager();
-    }
-  }
-  ensureCdcPolling() {
-    if (this.stopCdcPolling) return;
-    if (!this.changeTracker || !this.subscriptionManager) return;
-    const writer = this.pool.acquireWriter();
-    this.stopCdcPolling = startPolling(writer, this.changeTracker, this.subscriptionManager, this.cdcPollInterval);
-  }
-  stopCdcPollingLoop() {
-    if (this.stopCdcPolling) {
-      this.stopCdcPolling();
-      this.stopCdcPolling = null;
-    }
-  }
-  fireBeforeQueryHooks(sql, params, options) {
-    const hasParent = this.parentHooks?.has("beforeQuery");
-    const hasLocal = this.hookRegistry.has("beforeQuery");
-    if (!hasParent && !hasLocal) return;
-    const ctx = {
-      databaseId: this.id,
-      sql,
-      params,
-      writeConcern: options?.writeConcern,
-      readConcern: options?.readConcern
-    };
-    this.parentHooks?.invokeSync("beforeQuery", ctx);
-    this.hookRegistry.invokeSync("beforeQuery", ctx);
-  }
-  fireAfterQueryHooks(sql, params, durationMs) {
-    const hasParent = this.parentHooks?.has("afterQuery");
-    const hasLocal = this.hookRegistry.has("afterQuery");
-    if (!hasParent && !hasLocal) return;
-    const ctx = { databaseId: this.id, sql, params, durationMs };
-    try {
-      this.parentHooks?.invokeSync("afterQuery", ctx);
-    } catch {
-    }
-    try {
-      this.hookRegistry.invokeSync("afterQuery", ctx);
-    } catch {
-    }
-  }
 };
 
 // src/core/lifecycle/manager.ts
@@ -950,7 +1388,7 @@ var Sirannon = class {
       if (this.hookRegistry.has("beforeConnect")) {
         this.hookRegistry.invokeSync("beforeConnect", { databaseId: id, path });
       }
-      db = await Database.create(id, path, this._driver, options, {
+      db = await Database.create(id, path, this._driver, this.withRegistryDefaults(options), {
         parentHooks: this.hookRegistry,
         metrics: this.metricsCollector ?? void 0
       });
@@ -1000,6 +1438,11 @@ var Sirannon = class {
     });
     return db;
   }
+  withRegistryDefaults(options) {
+    const fallback = this.options.writerWorker;
+    if (fallback === void 0 || options?.writerWorker !== void 0) return options;
+    return { ...options, writerWorker: fallback };
+  }
   async close(id) {
     this.ensureRunning();
     const db = this.dbs.get(id);