bunqueue-dashboard 0.0.32 → 0.0.34

package/agent/db.ts

@@ -18,12 +18,11 @@
  *  - results are streamed with an early break at MAX_ROWS, so a huge or
  *    row-bomb query can't materialize the whole set in agent memory;
  *  - queryWithTimeout() runs it in a disposable Worker raced against a wall
- *    clock, so an O(N^k) scan can't pin the agent's only thread and freeze the
- *    process-control endpoints (falls back to synchronous run if a Worker can't
- *    be spawned, e.g. inside a compiled single-file binary). The timeout aborts
- *    the response, not the query — a synchronous sqlite3_step never yields to
- *    the terminate() request — so live worker threads are counted and capped by
- *    MAX_CONCURRENT_QUERIES instead of accumulating one pinned core per request.
+ *    clock, so an O(N^k) scan can't pin the agent's event loop and freeze the
+ *    process-control endpoints. Worker startup failures surface instead of
+ *    falling back to a synchronous scan. The timeout aborts the response, not
+ *    the query — a synchronous sqlite3_step never yields to terminate() — so
+ *    live worker threads are counted and capped by MAX_CONCURRENT_QUERIES.
  */
 import { existsSync } from 'node:fs';
 import { Database } from 'bun:sqlite';
@@ -34,6 +33,18 @@ export const MAX_ROWS = 500;
 const MAX_CELL = 2000;
 /** Full single-cell fetch (detail view) hard cap — bounds one pathological blob. */
 const MAX_FULL_CELL = 1_000_000;
+/** Full-table CSV export cap. The cursor probes one extra row to report truncation exactly. */
+export const DB_EXPORT_MAX_ROWS = 200_000;
+/** Maximum CSV response body. The exporter writes into one fixed-size buffer. */
+export const DB_EXPORT_MAX_BYTES = 16 * 1024 * 1024;
+/** Refuse pathological schemas before one row can create excessive transient allocations. */
+export const DB_EXPORT_MAX_COLUMNS = 256;
+/** Bound SQL/header construction even for a hostile or corrupt local schema. */
+export const DB_EXPORT_MAX_IDENTIFIER_CHARS = 1024;
+/** Bound a user-supplied filter before it is retained by SQLite for a long export. */
+export const DB_EXPORT_MAX_FILTER_CHARS = 4096;
+/** Response deadline; timed-out SQLite work remains isolated and accounted for in its Worker. */
+export const DB_EXPORT_TIMEOUT_MS = 15_000;
 /** Wall-clock budget for an arbitrary query before it is aborted. */
 export const QUERY_TIMEOUT_MS = 5000;
 
@@ -42,6 +53,12 @@ export class MissingDbError extends Error {
   readonly missing = true;
 }
 
+/** Maps a saturated export worker pool to HTTP 429. */
+export class DbExportBusyError extends Error {}
+
+/** Maps export worker startup/crash/timeout failures to HTTP 503. */
+export class DbExportUnavailableError extends Error {}
+
 export interface DbTableInfo {
   name: string;
   rows: number;
@@ -59,7 +76,7 @@ export interface DbRowsPage {
   columns: string[];
   rows: unknown[][];
   /** rowid per row (null for WITHOUT ROWID tables) — keys the full-cell fetch. */
-  rowids: (number | null)[];
+  rowids: (DbRowId | null)[];
   /** Which cells were truncated server-side, so the UI can flag them. */
   truncatedCells: boolean[][];
   total: number;
@@ -70,6 +87,34 @@ export interface DbRowsPage {
   filter: DbFilter | null;
 }
 
+export type DbExportCap = 'rows' | 'bytes' | null;
+
+/** Bounded CSV generated from one SQLite read transaction. */
+export interface DbCsvExport {
+  table: string;
+  content: Uint8Array<ArrayBuffer>;
+  rowCount: number;
+  bytes: number;
+  cap: DbExportCap;
+}
+
+/** Tests may lower a cap, but callers can never raise the production ceiling. */
+export interface DbExportLimits {
+  maxRows?: number;
+  maxBytes?: number;
+  /** Test synchronization only: runs after the transaction's first read pins its snapshot. */
+  onSnapshot?: () => void;
+}
+
+/** Test synchronization for proving that a browse page is one SQLite snapshot. */
+export interface DbRowsOptions {
+  /** Runs after COUNT, while the same read transaction remains open for SELECT. */
+  afterCount?: () => void;
+}
+
+/** JSON/query-string-safe SQLite rowid. Unsafe integers are represented as decimal strings. */
+export type DbRowId = number | string;
+
 export interface DbColumnInfo {
   name: string;
   type: string;
@@ -165,6 +210,28 @@ function bigintCell(v: bigint): number | string {
     : v.toString();
 }
 
+const MIN_SQLITE_INTEGER = -(1n << 63n);
+const MAX_SQLITE_INTEGER = (1n << 63n) - 1n;
+
+/**
+ * Validate a rowid without converting an unsafe decimal string through Number.
+ * Strings stay strings when bound; SQLite applies INTEGER affinity exactly.
+ */
+function boundRowid(rowid: DbRowId): DbRowId {
+  if (typeof rowid === 'number') {
+    if (!Number.isSafeInteger(rowid)) throw new Error('Invalid rowid');
+    return rowid;
+  }
+  if (rowid.length === 0 || rowid.length > 20 || !/^-?\d+$/.test(rowid)) {
+    throw new Error('Invalid rowid');
+  }
+  const integer = BigInt(rowid);
+  if (integer < MIN_SQLITE_INTEGER || integer > MAX_SQLITE_INTEGER) {
+    throw new Error('Invalid rowid');
+  }
+  return rowid;
+}
+
 /**
  * bun:sqlite exposes Statement.safeIntegers() at runtime but does not type it.
  * Enabled per statement (never connection-wide) so the COUNT(*) reads that are
@@ -225,6 +292,188 @@ function buildFilter(
   };
 }
 
+function boundedExportLimit(value: number | undefined, hardCap: number, label: string): number {
+  if (value === undefined) return hardCap;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${label} must be a positive safe integer`);
+  }
+  return Math.min(value, hardCap);
+}
+
+/** RFC-4180 cell with spreadsheet-formula neutralization for textual values. */
+function csvCell(value: unknown): string {
+  let text: string;
+  let textual = false;
+  if (value == null) text = '';
+  else if (typeof value === 'string') {
+    text = value;
+    textual = true;
+  } else if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'boolean') {
+    text = String(value);
+  } else if (value instanceof Uint8Array) {
+    // The SELECT below converts BLOBs before they cross into JS. Keep this
+    // fallback bounded and deterministic if SQLite changes the expression type.
+    text = `<blob ${value.byteLength} B>`;
+    textual = true;
+  } else {
+    throw new Error('Database export produced an unsupported SQLite value');
+  }
+
+  // Excel and Sheets may execute strings beginning with these characters. A
+  // leading TAB/CR is dangerous too because spreadsheet import strips it first.
+  const safe = textual && /^[=+\-@\t\r]/.test(text) ? `'${text}` : text;
+  return /[",\r\n]/.test(safe) ? `"${safe.replaceAll('"', '""')}"` : safe;
+}
+
+/**
+ * Export one filtered/sorted table view from a single SQLite snapshot.
+ *
+ * The readonly connection and explicit deferred transaction pin sqlite_master,
+ * schema, filter and row iteration to one WAL snapshot. Unlike client-side
+ * OFFSET pagination, concurrent inserts/deletes cannot duplicate or omit rows.
+ * The cursor is streamed into a fixed-size buffer and probes at most one row
+ * beyond the row cap, so both retained output and cardinality are bounded.
+ */
+export function dbExportCsv(
+  path: string,
+  table: string,
+  orderBy?: string,
+  dir: 'asc' | 'desc' = 'asc',
+  filter?: DbFilter,
+  limits: Readonly<DbExportLimits> = {}
+): DbCsvExport {
+  if (typeof table !== 'string' || table.length === 0) throw new Error('Table is required');
+  if (table.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+    throw new Error(`Table name exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+  }
+  if (dir !== 'asc' && dir !== 'desc') throw new Error('Invalid export sort direction');
+  if (filter) {
+    if (
+      typeof filter.column !== 'string' ||
+      !filter.column ||
+      (filter.op !== 'contains' && filter.op !== 'eq' && filter.op !== 'ne') ||
+      typeof filter.value !== 'string'
+    ) {
+      throw new Error('Invalid database export filter');
+    }
+    if (filter.column.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+      throw new Error(`Filter column exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+    }
+    if (filter.value.length > DB_EXPORT_MAX_FILTER_CHARS) {
+      throw new Error(
+        `Database export filter exceeds ${DB_EXPORT_MAX_FILTER_CHARS} characters`
+      );
+    }
+  }
+
+  const maxRows = boundedExportLimit(limits.maxRows, DB_EXPORT_MAX_ROWS, 'Export row limit');
+  const maxBytes = boundedExportLimit(limits.maxBytes, DB_EXPORT_MAX_BYTES, 'Export byte limit');
+  const db = open(path);
+  try {
+    const snapshot = db.transaction((): DbCsvExport => {
+      const name = knownTable(db, table);
+      const columns = (
+        db.query(`PRAGMA table_info(${ident(name)})`).all() as { name: string }[]
+      ).map((column) => column.name);
+      if (columns.length === 0) throw new Error(`Table has no exportable columns: ${name}`);
+      if (columns.length > DB_EXPORT_MAX_COLUMNS) {
+        throw new Error(
+          `Table has ${columns.length} columns; database export supports at most ${DB_EXPORT_MAX_COLUMNS}`
+        );
+      }
+      if (columns.some((column) => column.length > DB_EXPORT_MAX_IDENTIFIER_CHARS)) {
+        throw new Error(
+          `Database export column names must not exceed ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`
+        );
+      }
+      limits.onSnapshot?.();
+
+      let order = '';
+      if (orderBy !== undefined) {
+        if (typeof orderBy !== 'string' || !orderBy) {
+          throw new Error('Invalid database export sort column');
+        }
+        if (orderBy.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+          throw new Error(`Sort column exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+        }
+        const sortColumn = columns.find((column) => column === orderBy);
+        if (!sortColumn) throw new Error(`No such column: ${orderBy}`);
+        order = ` ORDER BY ${ident(sortColumn)} ${dir === 'desc' ? 'DESC' : 'ASC'}`;
+      }
+      const { clause, params } = buildFilter(columns, filter);
+
+      // Generated aliases avoid object-property hazards for legal SQLite column
+      // names such as "__proto__". Text and BLOB expressions ensure one cell
+      // cannot materialize an unbounded JS value before the byte cap is checked.
+      const aliases = columns.map((_, index) => `__bq_export_${index}`);
+      const selected = columns.map((column, index) => {
+        const quoted = ident(column);
+        return (
+          `CASE ` +
+          `WHEN typeof(${quoted}) = 'blob' THEN '<blob ' || length(${quoted}) || ' B>' ` +
+          `WHEN typeof(${quoted}) = 'text' AND length(CAST(${quoted} AS BLOB)) > ${MAX_CELL} ` +
+          `THEN substr(${quoted}, 1, ${MAX_CELL}) || '…' ` +
+          `ELSE ${quoted} END AS ${ident(aliases[index])}`
+        );
+      });
+      const stmt = db.query<Record<string, unknown>, Array<string | number>>(
+        `SELECT ${selected.join(', ')} FROM ${ident(name)}${clause}${order} LIMIT ?`
+      );
+      safeIntegers(stmt);
+
+      const encoder = new TextEncoder();
+      const buffer = new Uint8Array(maxBytes);
+      let used = 0;
+      const append = (text: string): boolean => {
+        const result = encoder.encodeInto(text, buffer.subarray(used));
+        if (result.read !== text.length) return false;
+        used += result.written;
+        return true;
+      };
+      if (!append(columns.map(csvCell).join(','))) {
+        throw new Error(`Database export header exceeds the ${maxBytes}-byte export limit`);
+      }
+
+      let rowCount = 0;
+      let cap: DbExportCap = null;
+      const bindings = [...params, maxRows + 1] as Array<string | number>;
+      const iterator = stmt.iterate(...bindings);
+      try {
+        for (;;) {
+          const next = iterator.next();
+          if (next.done) break;
+          if (rowCount >= maxRows) {
+            cap = 'rows';
+            break;
+          }
+          const line = `\r\n${aliases.map((alias) => csvCell(next.value[alias])).join(',')}`;
+          if (!append(line)) {
+            cap = 'bytes';
+            break;
+          }
+          rowCount++;
+        }
+      } finally {
+        iterator.return?.();
+      }
+
+      // Slice releases the unused portion of the fixed working buffer before
+      // the Response is retained by the HTTP server. Peak memory remains a
+      // small constant multiple of DB_EXPORT_MAX_BYTES, never table size.
+      const content = buffer.slice(0, used);
+      return { table: name, content, rowCount, bytes: content.byteLength, cap };
+    });
+    // On a readonly connection BEGIN DEFERRED is a read transaction. Bun's
+    // wrapper commits on success and rolls back on every thrown validation,
+    // cursor or encoding error.
+    return snapshot.deferred();
+  } catch (error) {
+    throw translateError(error);
+  } finally {
+    db.close();
+  }
+}
+
 /**
  * One page of a table's rows. Table, orderBy and filter-column identifiers are
  * validated against sqlite_master / table_info — never interpolated from raw
@@ -237,7 +486,8 @@ export function dbRows(
   offset: number,
   orderBy?: string,
   dir: 'asc' | 'desc' = 'asc',
-  filter?: DbFilter
+  filter?: DbFilter,
+  options: Readonly<DbRowsOptions> = {}
 ): DbRowsPage {
   const lim = Math.max(1, Math.min(MAX_ROWS, Math.floor(limit) || 50));
   // Non-finite / out-of-range offsets must be clamped here: SQLite rejects a
@@ -247,67 +497,83 @@ export function dbRows(
     : 0;
   const db = open(path);
   try {
-    const name = knownTable(db, table);
-    const columns = (db.query(`PRAGMA table_info(${ident(name)})`).all() as { name: string }[]).map(
-      (c) => c.name
-    );
+    const snapshot = db.transaction((): DbRowsPage => {
+      const name = knownTable(db, table);
+      const columns = (
+        db.query(`PRAGMA table_info(${ident(name)})`).all() as { name: string }[]
+      ).map((c) => c.name);
 
-    let order = '';
-    let sortCol: string | null = null;
-    if (orderBy) {
-      sortCol = columns.find((c) => c === orderBy) ?? null;
-      if (!sortCol) throw new Error(`No such column: ${orderBy}`);
-      order = ` ORDER BY ${ident(sortCol)} ${dir === 'desc' ? 'DESC' : 'ASC'}`;
-    }
+      let order = '';
+      let sortCol: string | null = null;
+      if (orderBy) {
+        sortCol = columns.find((c) => c === orderBy) ?? null;
+        if (!sortCol) throw new Error(`No such column: ${orderBy}`);
+        order = ` ORDER BY ${ident(sortCol)} ${dir === 'desc' ? 'DESC' : 'ASC'}`;
+      }
 
-    const { clause, params, applied } = buildFilter(columns, filter);
+      const { clause, params, applied } = buildFilter(columns, filter);
 
-    const { c: total } = db
-      .query(`SELECT COUNT(*) AS c FROM ${ident(name)}${clause}`)
-      .get(...(params as [])) as { c: number };
+      const { c: total } = db
+        .query(`SELECT COUNT(*) AS c FROM ${ident(name)}${clause}`)
+        .get(...(params as [])) as { c: number };
+      options.afterCount?.();
 
-    // Prefer selecting rowid so the detail view can fetch untruncated cells;
-    // WITHOUT ROWID tables have no rowid column — fall back to a plain select.
-    let rowids: (number | null)[] = [];
-    let rawRows: unknown[][];
-    try {
-      const stmt = db.query(
-        `SELECT rowid AS __rid, * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`
-      );
-      safeIntegers(stmt);
-      const withRowid = stmt.values(...(params as []), lim, off) as unknown[][];
-      rowids = withRowid.map((r) =>
-        typeof r[0] === 'bigint' ? Number(r[0]) : typeof r[0] === 'number' ? r[0] : null
-      );
-      rawRows = withRowid.map((r) => r.slice(1));
-    } catch {
-      const stmt = db.query(`SELECT * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`);
-      safeIntegers(stmt);
-      rawRows = stmt.values(...(params as []), lim, off) as unknown[][];
-      rowids = rawRows.map(() => null);
-    }
+      // Prefer selecting rowid so the detail view can fetch untruncated cells;
+      // WITHOUT ROWID tables have no rowid column — fall back to a plain select.
+      let rowids: (DbRowId | null)[] = [];
+      let rawRows: unknown[][];
+      try {
+        const stmt = db.query(
+          `SELECT rowid AS __rid, * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`
+        );
+        safeIntegers(stmt);
+        const withRowid = stmt.values(...(params as []), lim, off) as unknown[][];
+        rowids = withRowid.map((r) =>
+          typeof r[0] === 'bigint'
+            ? bigintCell(r[0])
+            : typeof r[0] === 'number' && Number.isSafeInteger(r[0])
+              ? r[0]
+              : null
+        );
+        rawRows = withRowid.map((r) => r.slice(1));
+      } catch {
+        const stmt = db.query(`SELECT * FROM ${ident(name)}${clause}${order} LIMIT ? OFFSET ?`);
+        safeIntegers(stmt);
+        rawRows = stmt.values(...(params as []), lim, off) as unknown[][];
+        rowids = rawRows.map(() => null);
+      }
 
-    const truncatedCells = rawRows.map((r) => r.map(isTruncated));
-    return {
-      table: name,
-      columns,
-      rows: sanitize(rawRows),
-      rowids,
-      truncatedCells,
-      total,
-      limit: lim,
-      offset: off,
-      orderBy: sortCol,
-      dir: dir === 'desc' ? 'desc' : 'asc',
-      filter: applied,
-    };
+      const truncatedCells = rawRows.map((r) => r.map(isTruncated));
+      return {
+        table: name,
+        columns,
+        rows: sanitize(rawRows),
+        rowids,
+        truncatedCells,
+        total,
+        limit: lim,
+        offset: off,
+        orderBy: sortCol,
+        dir: dir === 'desc' ? 'desc' : 'asc',
+        filter: applied,
+      };
+    });
+    // COUNT and page SELECT must describe the same live view. Without this read
+    // transaction, a concurrent WAL commit between them could make a valid
+    // response internally contradictory (or shift rows across page boundaries).
+    return snapshot.deferred();
   } finally {
     db.close();
   }
 }
 
 /** Full, untruncated value of a single cell, keyed by rowid (for the detail view). */
-export function dbCell(path: string, table: string, rowid: number, column: string): { value: unknown } {
+export function dbCell(
+  path: string,
+  table: string,
+  rowid: DbRowId,
+  column: string
+): { value: unknown } {
   const db = open(path);
   try {
     const name = knownTable(db, table);
@@ -318,7 +584,7 @@ export function dbCell(path: string, table: string, rowid: number, column: strin
     if (!col) throw new Error(`No such column: ${column}`);
     const stmt = db.query(`SELECT ${ident(col)} AS v FROM ${ident(name)} WHERE rowid = ?`);
     safeIntegers(stmt);
-    const row = stmt.get(rowid) as { v: unknown } | null;
+    const row = stmt.get(boundRowid(rowid)) as { v: unknown } | null;
     if (!row) throw new Error('Row not found');
     let v = row.v;
     if (v instanceof Uint8Array) v = `<blob ${v.byteLength} B — binary, not shown>`;
@@ -517,16 +783,16 @@ function translateError(e: unknown): Error {
 }
 
 /**
- * Time-boxed, off-thread execution of an arbitrary query. Spawns a disposable
- * readonly Worker and races it against QUERY_TIMEOUT_MS so a runaway scan can't
- * freeze the agent's control endpoints.
+ * Shared URL of the disposable database worker. It accepts both arbitrary
+ * query and atomic CSV-export messages; scripts/serve.ts points this at the
+ * secondary embedded entrypoint in compiled builds.
  *
  * The timeout aborts the RESPONSE, not the query: terminate() is delivered to
  * the worker's event loop, which a synchronous sqlite3_step never yields back
  * to, so a runaway scan keeps burning its own thread until SQLite finishes it.
  * That thread is therefore accounted for (a slot is held until the worker really
- * exits) and capped by MAX_CONCURRENT_QUERIES, so N timed-out queries can pin at
- * most MAX_CONCURRENT_QUERIES cores instead of one core per request, forever.
+ * exits) and capped by the respective query/export pool, so abandoned work can
+ * pin only the configured number of cores instead of one new core per request.
  */
 let queryWorkerUrl = new URL('./dbQueryWorker.ts', import.meta.url).href;
 
@@ -560,6 +826,213 @@ export function setQueryWorkerFactory(factory: (() => Worker) | null): void {
   queryWorkerFactory = factory ?? spawnRealWorker;
 }
 
+/** Only one potentially expensive table scan/sort may run at a time. */
+export const MAX_CONCURRENT_EXPORTS = 1;
+let liveExportWorkers = 0;
+
+/** Export workers alive now, including timed-out/aborted SQLite calls still unwinding. */
+export const exportWorkerLoad = (): number => liveExportWorkers;
+
+const spawnRealExportWorker = (): Worker => new Worker(queryWorkerUrl, { type: 'module' });
+let exportWorkerFactory: () => Worker = spawnRealExportWorker;
+
+/** Test-only export-worker factory; pass null to restore the real worker. */
+export function setExportWorkerFactory(factory: (() => Worker) | null): void {
+  exportWorkerFactory = factory ?? spawnRealExportWorker;
+}
+
+function validatedWorkerExport(value: unknown, expectedTable: string): DbCsvExport {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new DbExportUnavailableError('Database export worker returned a malformed result');
+  }
+  const result = value as Record<string, unknown>;
+  if (
+    typeof result.table !== 'string' ||
+    result.table !== expectedTable ||
+    !(result.content instanceof Uint8Array) ||
+    !Number.isSafeInteger(result.rowCount) ||
+    (result.rowCount as number) < 0 ||
+    (result.rowCount as number) > DB_EXPORT_MAX_ROWS ||
+    !Number.isSafeInteger(result.bytes) ||
+    (result.bytes as number) < 1 ||
+    (result.bytes as number) > DB_EXPORT_MAX_BYTES ||
+    result.content.byteLength !== result.bytes ||
+    (result.cap !== null && result.cap !== 'rows' && result.cap !== 'bytes') ||
+    (result.cap === 'rows' && result.rowCount !== DB_EXPORT_MAX_ROWS)
+  ) {
+    throw new DbExportUnavailableError('Database export worker returned a malformed result');
+  }
+  const content =
+    result.content.buffer instanceof ArrayBuffer
+      ? (result.content as Uint8Array<ArrayBuffer>)
+      : Uint8Array.from(result.content);
+  return {
+    table: result.table as string,
+    content,
+    rowCount: result.rowCount as number,
+    bytes: result.bytes as number,
+    cap: result.cap as DbExportCap,
+  };
+}
+
+/**
+ * Run an atomic CSV export off the control-agent event loop.
+ *
+ * A timeout or caller abort abandons the response, not sqlite3_step: the Worker
+ * keeps its only slot until `close`, preventing repeated abandoned scans from
+ * pinning additional cores. Row/cell/byte caps remain enforced inside
+ * dbExportCsv before its ArrayBuffer is transferred back without JSON expansion.
+ */
+export async function exportWithTimeout(
+  path: string,
+  table: string,
+  orderBy?: string,
+  dir: 'asc' | 'desc' = 'asc',
+  filter?: DbFilter,
+  signal?: AbortSignal
+): Promise<DbCsvExport> {
+  signal?.throwIfAborted();
+  if (liveExportWorkers >= MAX_CONCURRENT_EXPORTS) {
+    throw new DbExportBusyError(
+      'A database export is already running. Wait for it to finish, or restart the agent if it was abandoned.'
+    );
+  }
+
+  let worker: Worker;
+  try {
+    worker = exportWorkerFactory();
+  } catch (error) {
+    throw new DbExportUnavailableError(
+      `Database export worker unavailable: ${(error as Error).message ?? String(error)}`
+    );
+  }
+  liveExportWorkers++;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    liveExportWorkers--;
+  };
+
+  try {
+    return await new Promise<DbCsvExport>((resolve, reject) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+      };
+      const abandon = (error: Error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        worker.terminate();
+        // Do NOT release here. A synchronous sqlite3_step may still be running;
+        // the close event is the proof that its thread has really exited.
+        reject(error);
+      };
+      const onAbort = () =>
+        abandon(
+          signal?.reason instanceof Error
+            ? signal.reason
+            : new Error('Database export request was aborted')
+        );
+
+      worker.addEventListener('close', () => {
+        release();
+        if (!settled) {
+          settled = true;
+          cleanup();
+          reject(new DbExportUnavailableError('Database export worker exited unexpectedly'));
+        }
+      });
+      worker.addEventListener('message', (event: MessageEvent) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        release();
+        const data = event.data as
+          | {
+              ok?: unknown;
+              export?: unknown;
+              error?: unknown;
+              missing?: unknown;
+            }
+          | null;
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+          reject(
+            new DbExportUnavailableError('Database export worker returned a malformed response')
+          );
+          return;
+        }
+        const response: {
+          ok?: unknown;
+          export?: unknown;
+          error?: unknown;
+          missing?: unknown;
+        } = data;
+        if (response.ok === true) {
+          try {
+            resolve(validatedWorkerExport(response.export, table));
+          } catch (error) {
+            reject(error);
+          }
+        } else if (response.missing === true) {
+          reject(
+            new MissingDbError(
+              typeof response.error === 'string' ? response.error : 'Database not found'
+            )
+          );
+        } else {
+          reject(
+            new Error(
+              typeof response.error === 'string' ? response.error : 'Database export failed'
+            )
+          );
+        }
+      });
+      worker.addEventListener('error', (event: ErrorEvent) => {
+        if (settled) return;
+        event.preventDefault?.();
+        abandon(
+          new DbExportUnavailableError(
+            `Database export worker failed: ${event.message || 'unknown worker error'}`
+          )
+        );
+      });
+
+      timer = setTimeout(
+        () =>
+          abandon(
+            new DbExportUnavailableError(
+              `Database export exceeded the ${DB_EXPORT_TIMEOUT_MS / 1000}s time limit and was abandoned (SQLite may keep scanning until the worker exits).`
+            )
+          ),
+        DB_EXPORT_TIMEOUT_MS
+      );
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      try {
+        worker.postMessage({ kind: 'export', path, table, orderBy, dir, filter });
+      } catch (error) {
+        settled = true;
+        cleanup();
+        release();
+        reject(
+          new DbExportUnavailableError(
+            `Could not start database export: ${(error as Error).message ?? String(error)}`
+          )
+        );
+      }
+    });
+  } finally {
+    worker.terminate();
+  }
+}
+
 export async function queryWithTimeout(path: string, sql: string): Promise<DbQueryResult> {
   if (liveQueryWorkers >= MAX_CONCURRENT_QUERIES) {
     throw new Error(