@delali/sirannon-db 0.2.3-next.29 → 0.2.3-next.31

package/dist/backup/index.d.ts

@@ -0,0 +1,30 @@
+import { B as BackupDestination, a as BackupRunReport } from '../report-BFsHdkKt.js';
+export { b as BackupPiece, c as BackupProgress, d as BackupToDestinationOptions } from '../report-BFsHdkKt.js';
+export { B as BackupCapabilities } from '../capabilities-DagBnGk8.js';
+
+/** What one assembled file took to build.
+ * @public
+ */
+interface AssembleResult {
+    /** Bytes the assembly wrote. */
+    bytesWritten: number;
+    /** Pieces the assembly read. */
+    pieceCount: number;
+    /** SHA-256 of the assembled file, where the run recorded one to check it against. */
+    fingerprint?: string;
+}
+/**
+ * Builds a local file from the pieces a destination holds, fetching one piece
+ * at a time and writing it where its index places it, so a piece SQLite never
+ * wrote leaves zeros rather than moving every later byte.
+ *
+ * @param destination - Where the pieces are read from.
+ * @param report - What the run that wrote those pieces recorded, which the assembly checks its result against.
+ * @param destPath - Path the assembled file is written to.
+ * @returns The bytes and pieces the assembly wrote, and the fingerprint it computed.
+ *
+ * @public
+ */
+declare function assembleFromDestination(destination: BackupDestination, report: BackupRunReport, destPath: string): Promise<AssembleResult>;
+
+export { type AssembleResult, BackupDestination, BackupRunReport, assembleFromDestination };

package/dist/backup/index.mjs

@@ -0,0 +1,52 @@
+import { SirannonError } from '../chunk-PBRXXISQ.mjs';
+import { createHash } from 'crypto';
+import { open, rm } from 'fs/promises';
+
+function destinationError(message) {
+  return new SirannonError(message, "BACKUP_DESTINATION_ERROR");
+}
+function assertChainIsWhole(pieces, report) {
+  if (pieces.length === 0) {
+    throw destinationError(`The destination holds no pieces named '${report.destinationName}'`);
+  }
+  for (let expected = 0; expected < report.pieceCount; expected++) {
+    if (pieces[expected]?.index !== expected) {
+      throw destinationError(
+        `The destination is missing piece ${expected} of '${report.destinationName}', so the file cannot be assembled`
+      );
+    }
+  }
+  if (pieces.length > report.pieceCount) {
+    throw destinationError(
+      `The destination holds ${pieces.length} pieces of '${report.destinationName}' where the run wrote ${report.pieceCount}, so a later piece belongs to a different run`
+    );
+  }
+}
+async function assembleFromDestination(destination, report, destPath) {
+  const name = report.destinationName;
+  const pieces = [...await destination.listPieces(name)].sort((a, b) => a.index - b.index);
+  assertChainIsWhole(pieces, report);
+  const digest = report.fingerprint === void 0 ? null : createHash("sha256");
+  const file = await open(destPath, "w");
+  let bytesWritten = 0;
+  try {
+    for (const piece of pieces) {
+      const bytes = await destination.readPiece(name, piece.index);
+      await file.write(bytes, 0, bytes.byteLength, piece.index * report.pieceBytes);
+      digest?.update(bytes);
+      bytesWritten += bytes.byteLength;
+    }
+  } finally {
+    await file.close();
+  }
+  const fingerprint = digest?.digest("hex");
+  const failure = bytesWritten !== report.bytesWritten ? `The pieces of '${name}' hold ${bytesWritten} bytes where the run wrote ${report.bytesWritten}` : fingerprint !== void 0 && fingerprint !== report.fingerprint ? `The pieces of '${name}' do not match the fingerprint the run recorded` : null;
+  if (failure !== null) {
+    await rm(destPath, { force: true }).catch(() => {
+    });
+    throw destinationError(failure);
+  }
+  return { bytesWritten, pieceCount: pieces.length, ...fingerprint ? { fingerprint } : {} };
+}
+
+export { assembleFromDestination };

package/dist/backup-scheduler/index.d.ts

@@ -1,8 +1,10 @@
-import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-CXoPBeDM.js';
-import '../query-types-BvkzxKQv.js';
+import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-B1wQuNXV.js';
+import { e as BackupRunRequest, a as BackupRunReport } from '../report-BFsHdkKt.js';
+import '../query-types-Cv8N7pXj.js';
 
 declare class BackupManager {
-    backup(conn: SQLiteConnection, destPath: string): Promise<void>;
+    backup(conn: SQLiteConnection, destPath: string, onFirstStep?: () => void): Promise<void>;
+    copyToDestination(conn: SQLiteConnection, request: BackupRunRequest): Promise<BackupRunReport>;
     generateFilename(): string;
     rotate(dir: string, maxFiles: number): void;
 }

package/dist/backup-scheduler/index.mjs

@@ -1,2 +1,4 @@
-export { BackupScheduler } from '../chunk-VOYGMAU7.mjs';
+export { BackupScheduler } from '../chunk-23HKRYSM.mjs';
+import '../chunk-W67A4H2E.mjs';
+import '../chunk-V5FUJEYY.mjs';
 import '../chunk-PBRXXISQ.mjs';

package/dist/capabilities-DagBnGk8.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What one runtime supports of the backup operations, so a caller learns
+ * before a run rather than at failure time. A runtime that hands over whole
+ * databases only reports no full copy at all.
+ *
+ * @public
+ */
+interface BackupCapabilities {
+    /** Whether this runtime copies an open database while writes continue. */
+    fullCopy: boolean;
+    /** Whether a full copy reaches the destination without a local file. */
+    streamedCopy: boolean;
+    /** Whether a full copy writes a local file and sends that file on. */
+    stagedCopy: boolean;
+    /** Local disk a full copy needs, which the staged route sets to the size of the backup. */
+    localDiskRequired: 'none' | 'equal-to-backup';
+    /** Whether this runtime repeats a full copy on a schedule. */
+    schedule: boolean;
+}
+
+export type { BackupCapabilities as B };

package/dist/{change-tracker-C2Z8UbI0.d.ts → change-tracker-7wXnBjUN.d.ts}

@@ -1,5 +1,5 @@
-import { e as SQLiteConnection } from './types-CXoPBeDM.js';
-import { C as ChangeEvent } from './query-types-BvkzxKQv.js';
+import { e as SQLiteConnection } from './types-B1wQuNXV.js';
+import { C as ChangeEvent } from './query-types-Cv8N7pXj.js';
 
 /**
  * How long a change tracker keeps changes, and how much it reads at a time.

package/dist/{chunk-VOYGMAU7.mjs → chunk-23HKRYSM.mjs}

@@ -1,8 +1,255 @@
-import { BackupError } from './chunk-PBRXXISQ.mjs';
+import { startCopyWithoutHoldingWriter } from './chunk-W67A4H2E.mjs';
+import { randomHex } from './chunk-V5FUJEYY.mjs';
+import { BackupError, SirannonError } from './chunk-PBRXXISQ.mjs';
 import { existsSync, mkdirSync, rmSync, readdirSync, lstatSync } from 'fs';
 import { resolve, dirname, join } from 'path';
+import { createHash } from 'crypto';
+import { mkdtemp, open, rm } from 'fs/promises';
+import { tmpdir } from 'os';
 
+// src/core/backup/report.ts
+var DEFAULT_PIECE_BYTES = 16 * 1024 * 1024;
+
+// src/core/backup/stepped-copy.ts
+var DEFAULT_PAGES_PER_STEP = 256;
+var DEFAULT_RESTART_LIMIT = 3;
+var DEFAULT_STALL_TIMEOUT_MS = 3e4;
+var DEFAULT_NO_PROGRESS_STEP_LIMIT = 256;
+function restartLimitError(restarts, destPath) {
+  return new SirannonError(
+    `The copy to '${destPath}' returned to page one ${restarts} times because another connection wrote to the source database or ran a RESTART or TRUNCATE checkpoint on it. Close any other connection that writes to this file, route its writes through Sirannon, and run the copy again.`,
+    "BACKUP_RESTARTED"
+  );
+}
+function noProgressError(steps, destPath) {
+  return new SirannonError(
+    `The copy to '${destPath}' moved no page it had not already moved across ${steps} steps. Another connection restarts the copy on every step, or the source grows faster than the copy moves it. Close any other connection that writes to this file, or run the copy when the write rate is lower.`,
+    "BACKUP_RESTARTED"
+  );
+}
+function stallError(stallTimeoutMs, destPath) {
+  return new SirannonError(
+    `The copy to '${destPath}' moved no pages for ${stallTimeoutMs}ms. SQLite steps the copy once per turn of the event loop, so a caller that never lets the loop reach its timers and immediates holds the copy still. Let the event loop run between writes, or raise the stall timeout for a host this slow.`,
+    "BACKUP_STALLED"
+  );
+}
+function copiedPages(step) {
+  return step.totalPages - step.remainingPages;
+}
+function hasRestarted(step, previous) {
+  if (!previous) return false;
+  return copiedPages(step) < copiedPages(previous);
+}
+async function copyDatabaseStepwise(conn, options) {
+  if (!conn.copyDatabase) {
+    throw new SirannonError(
+      "This driver opens connections without a stepped copy call, so it cannot copy a database while writes continue",
+      "BACKUP_UNSUPPORTED"
+    );
+  }
+  const restartLimit = options.restartLimit ?? DEFAULT_RESTART_LIMIT;
+  const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+  const noProgressStepLimit = options.noProgressStepLimit ?? DEFAULT_NO_PROGRESS_STEP_LIMIT;
+  let previous = null;
+  let restarts = 0;
+  let furthestCopied = -1;
+  let stepsWithoutProgress = 0;
+  let stopped = null;
+  let stallTimer = null;
+  let reportStall = () => {
+  };
+  const stalled = new Promise((_, reject) => {
+    reportStall = reject;
+  });
+  const armStall = () => {
+    if (stallTimeoutMs <= 0) return;
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      stopped = stallError(stallTimeoutMs, options.destPath);
+      reportStall(stopped);
+    }, stallTimeoutMs);
+    stallTimer.unref?.();
+  };
+  armStall();
+  const copy = conn.copyDatabase({
+    destPath: options.destPath,
+    pagesPerStep: options.pagesPerStep ?? DEFAULT_PAGES_PER_STEP,
+    onStep: (step) => {
+      if (stopped) throw stopped;
+      armStall();
+      if (hasRestarted(step, previous)) {
+        restarts++;
+        if (restarts > restartLimit) {
+          stopped = restartLimitError(restarts, options.destPath);
+          throw stopped;
+        }
+      }
+      if (copiedPages(step) > furthestCopied) {
+        furthestCopied = copiedPages(step);
+        stepsWithoutProgress = 0;
+      } else if (step.remainingPages > 0 && ++stepsWithoutProgress > noProgressStepLimit) {
+        stopped = noProgressError(stepsWithoutProgress, options.destPath);
+        throw stopped;
+      }
+      previous = step;
+      options.onStep?.({ totalPages: step.totalPages, remainingPages: step.remainingPages, restarts });
+    }
+  }).catch((err) => {
+    if (stopped) throw stopped;
+    throw err instanceof SirannonError ? err : new BackupError(`Copy to '${options.destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
+  copy.catch(() => {
+  });
+  try {
+    const final = await Promise.race([copy, stalled]);
+    return { pageCount: final.totalPages, restarts };
+  } catch (err) {
+    options.onCopyLeftRunning?.(copy);
+    throw err;
+  } finally {
+    if (stallTimer) clearTimeout(stallTimer);
+  }
+}
+
+// src/core/backup/staged-copy.ts
+var STAGED_FILE_NAME = "copy.db";
+function destinationError(name, index, err) {
+  return new SirannonError(
+    `The destination refused piece ${index} of '${name}': ${err instanceof Error ? err.message : String(err)}`,
+    "BACKUP_DESTINATION_ERROR"
+  );
+}
+async function readPageSize(conn) {
+  const stmt = await conn.prepare("PRAGMA page_size");
+  const row = await stmt.get();
+  return row ? Number(row.page_size) : 0;
+}
+async function sendPieces(stagedPath, destination, name, pieceBytes, fingerprint, report) {
+  const file = await open(stagedPath, "r");
+  const digest = fingerprint ? createHash("sha256") : null;
+  let index = 0;
+  let bytesWritten = 0;
+  try {
+    const buffer = Buffer.allocUnsafe(pieceBytes);
+    for (; ; ) {
+      let filled = 0;
+      while (filled < pieceBytes) {
+        const { bytesRead } = await file.read(buffer, filled, pieceBytes - filled, index * pieceBytes + filled);
+        if (bytesRead === 0) break;
+        filled += bytesRead;
+      }
+      if (filled === 0) break;
+      const piece = new Uint8Array(filled);
+      piece.set(buffer.subarray(0, filled));
+      digest?.update(piece);
+      try {
+        await destination.writePiece(name, index, piece);
+      } catch (err) {
+        throw destinationError(name, index, err);
+      }
+      index++;
+      bytesWritten += filled;
+      report(index, bytesWritten);
+      if (filled < pieceBytes) break;
+    }
+  } finally {
+    await file.close();
+  }
+  return { pieceCount: index, bytesWritten, ...digest ? { fingerprint: digest.digest("hex") } : {} };
+}
+async function copyToDestinationStaged(conn, request) {
+  const runId = randomHex(8);
+  const name = request.name ?? `backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.db`;
+  const pieceBytes = request.pieceBytes ?? DEFAULT_PIECE_BYTES;
+  if (!Number.isInteger(pieceBytes) || pieceBytes <= 0) {
+    throw new SirannonError(
+      `Piece size must be a positive whole number of bytes, and it was ${pieceBytes}`,
+      "BACKUP_ERROR"
+    );
+  }
+  const startedAt = Date.now();
+  const stagingRoot = await mkdtemp(join(request.stagingDir ?? tmpdir(), "sirannon-backup-"));
+  const stagedPath = join(stagingRoot, STAGED_FILE_NAME);
+  let firstStepSeen = false;
+  let copyLeftRunning = null;
+  const emit = (progress) => request.onProgress?.({ runId, ...progress });
+  try {
+    const pageSize = await readPageSize(conn);
+    const copyStartedAt = Date.now();
+    const copy = await copyDatabaseStepwise(conn, {
+      destPath: stagedPath,
+      ...request.pagesPerStep === void 0 ? {} : { pagesPerStep: request.pagesPerStep },
+      ...request.restartLimit === void 0 ? {} : { restartLimit: request.restartLimit },
+      ...request.stallTimeoutMs === void 0 ? {} : { stallTimeoutMs: request.stallTimeoutMs },
+      ...request.noProgressStepLimit === void 0 ? {} : { noProgressStepLimit: request.noProgressStepLimit },
+      onCopyLeftRunning: (copy2) => {
+        copyLeftRunning = copy2;
+      },
+      onStep: (step) => {
+        if (!firstStepSeen) {
+          firstStepSeen = true;
+          request.onFirstStep?.();
+        }
+        emit({ phase: "copy", ...step, piecesWritten: 0, bytesWritten: 0 });
+      }
+    });
+    const copyMs = Date.now() - copyStartedAt;
+    const transferStartedAt = Date.now();
+    const sent = await sendPieces(
+      stagedPath,
+      request.destination,
+      name,
+      pieceBytes,
+      request.fingerprint ?? true,
+      (piecesWritten, bytesWritten) => emit({
+        phase: "transfer",
+        totalPages: copy.pageCount,
+        remainingPages: 0,
+        restarts: copy.restarts,
+        piecesWritten,
+        bytesWritten
+      })
+    );
+    const transferMs = Date.now() - transferStartedAt;
+    const finishedAt = Date.now();
+    return {
+      runId,
+      databaseId: request.databaseId,
+      sourcePath: request.sourcePath,
+      kind: "full",
+      route: "staged",
+      destinationName: name,
+      startedAt,
+      finishedAt,
+      durationMs: finishedAt - startedAt,
+      copyMs,
+      transferMs,
+      pageCount: copy.pageCount,
+      pageSize,
+      bytesWritten: sent.bytesWritten,
+      pieceCount: sent.pieceCount,
+      pieceBytes,
+      restarts: copy.restarts,
+      ...sent.fingerprint ? { fingerprint: sent.fingerprint } : {}
+    };
+  } finally {
+    const removeStaging = () => rm(stagingRoot, { recursive: true, force: true }).catch(() => {
+    });
+    if (copyLeftRunning) void copyLeftRunning.then(removeStaging, removeStaging);
+    else await removeStaging();
+  }
+}
+
+// src/core/backup/backup.ts
 var BACKUP_FILE_PREFIX = "backup";
+function once(action) {
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    action();
+  };
+}
 function hasControlCharacters(s) {
   for (let i = 0; i < s.length; i++) {
     const code = s.charCodeAt(i);
@@ -11,7 +258,7 @@ function hasControlCharacters(s) {
   return false;
 }
 var BackupManager = class {
-  async backup(conn, destPath) {
+  async backup(conn, destPath, onFirstStep) {
     if (hasControlCharacters(destPath)) {
       throw new BackupError("Backup path contains invalid characters");
     }
@@ -33,17 +280,20 @@ var BackupManager = class {
     if (existsSync(resolved)) {
       throw new BackupError(`Backup destination '${destPath}' already exists`);
     }
-    const escaped = resolved.replace(/'/g, "''");
     try {
-      await conn.exec(`VACUUM INTO '${escaped}'`);
+      await copyDatabaseStepwise(conn, { destPath: resolved, onStep: onFirstStep ? once(onFirstStep) : void 0 });
     } catch (err) {
       try {
         rmSync(resolved, { force: true });
       } catch {
       }
+      if (err instanceof SirannonError) throw err;
       throw new BackupError(`Backup to '${destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  copyToDestination(conn, request) {
+    return copyToDestinationStaged(conn, request);
+  }
   generateFilename() {
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     return `${BACKUP_FILE_PREFIX}-${ts}.db`;
@@ -429,7 +679,10 @@ var BackupScheduler = class {
     const runBackup = async () => {
       try {
         const destPath = join(resolvedDir, this.manager.generateFilename());
-        await runExclusive(() => this.manager.backup(conn, destPath));
+        await startCopyWithoutHoldingWriter(
+          runExclusive,
+          (onFirstStep) => this.manager.backup(conn, destPath, onFirstStep)
+        );
         this.manager.rotate(resolvedDir, maxFiles);
       } catch (err) {
         if (onError) {

package/dist/{chunk-CCZK6LCB.mjs → chunk-7X6E7UUF.mjs}

@@ -1,6 +1,7 @@
 import { tableColumnNames, tablePkColumns, selectMinChangeSeqSql, selectMaxChangeSeq, deleteChangesBeforeUpToSeqSql, deleteChangesBeforeSql, selectTableExists, ensureChangesTable, ensureMetaTable, insertMetaValueIfAbsent, selectMetaValue, selectChangesAfterSeqSql, selectTablesChangesInRangeSql } from './chunk-7FQRQH5Z.mjs';
 import { CHANGES_TABLE, isReservedIdentifier, CDC_TRIGGER_PREFIX, encodeTaggedValues, decodeTaggedValues, SAFE_INT_BOUND_TEXT } from './chunk-7R4ER4FB.mjs';
 import { synchronousPragmaValue } from './chunk-OUSWVNWT.mjs';
+import { randomHex } from './chunk-V5FUJEYY.mjs';
 import { SirannonError, ForbiddenSqlError, CDCError, MigrationError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/bulk-load.ts
@@ -549,13 +550,6 @@ function reconcileMigrationChecksums(migrations, applied) {
   return backfills;
 }
 
-// src/core/random-hex.ts
-function randomHex(byteLength) {
-  const bytes = new Uint8Array(byteLength);
-  globalThis.crypto.getRandomValues(bytes);
-  return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
-}
-
 // src/core/cdc/epoch.ts
 var EPOCH_KEY = "cdc_epoch";
 async function ensureCdcEpoch(conn) {
@@ -855,4 +849,4 @@ var TransactionGrouper = class {
   }
 };
 
-export { ChangeTracker, PrimedSubscription, SubscriptionBuilderImpl, SubscriptionManager, TransactionGrouper, ensureCdcEpoch, filteredChange, isBulkLoadDurability, migrationChecksum, migrationContentChecksum, needsResync, randomHex, reconcileMigrationChecksums, runBulkLoad, startPolling };
+export { ChangeTracker, PrimedSubscription, SubscriptionBuilderImpl, SubscriptionManager, TransactionGrouper, ensureCdcEpoch, filteredChange, isBulkLoadDurability, migrationChecksum, migrationContentChecksum, needsResync, reconcileMigrationChecksums, runBulkLoad, startPolling };

package/dist/{chunk-UPKKSUPA.mjs → chunk-ADBGZA6L.mjs}

@@ -1,12 +1,22 @@
-import { BackupManager, BackupScheduler } from './chunk-VOYGMAU7.mjs';
-import { WORKER_CANCELLED_CODE, deserializeError } from './chunk-4ISB7XMA.mjs';
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { BackupManager, BackupScheduler } from './chunk-23HKRYSM.mjs';
+import { WORKER_CANCELLED_CODE, deserializeError } from './chunk-YLAVDZCS.mjs';
+import { SirannonError, ExtensionError } from './chunk-PBRXXISQ.mjs';
 import { Worker } from 'worker_threads';
 import { existsSync } from 'fs';
 import { resolve, dirname, join, sep } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { AsyncLocalStorage } from 'async_hooks';
 
+// src/core/driver/extension.ts
+async function loadThroughRuntime(extensionPath, load) {
+  try {
+    load();
+  } catch (err) {
+    if (err instanceof SirannonError) throw err;
+    throw new ExtensionError(extensionPath, err instanceof Error ? err.message : String(err));
+  }
+}
+
 // src/core/driver/statement-cache.ts
 var STATEMENT_CACHE_CAPACITY = 128;
 function createStatementCache(prepare) {
@@ -102,6 +112,7 @@ var WriterWorker = class _WriterWorker {
   closed = false;
   fatal = null;
   restarts = 0;
+  loadedExtensions = [];
   connection;
   static async start(entry, path, options, workerOptions) {
     const worker = new _WriterWorker(
@@ -134,11 +145,20 @@ var WriterWorker = class _WriterWorker {
         this.fault(new SirannonError(`Writer worker exited with code ${code}`, "WRITER_WORKER_EXIT"));
       }
     });
-    this.ready = this.send(this.openRequest).then(() => void 0);
+    this.ready = this.send(this.openRequest).then(() => this.reloadExtensionsOntoRestartedConnection());
     this.ready.catch(() => {
     });
   }
+  async reloadExtensionsOntoRestartedConnection() {
+    for (const path of this.loadedExtensions) {
+      await this.send({ kind: "loadExtension", path });
+    }
+  }
   onResponse(res) {
+    if ("kind" in res) {
+      this.onCopyStep(res.id, res.step);
+      return;
+    }
     const entry = this.pending.get(res.id);
     if (!entry) return;
     this.pending.delete(res.id);
@@ -158,6 +178,26 @@ var WriterWorker = class _WriterWorker {
     }
     entry.reject(deserializeError(res.error));
   }
+  onCopyStep(id, step) {
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = this.timeoutMs > 0 ? setTimeout(() => this.onDeadline(id), this.timeoutMs) : null;
+      entry.timer?.unref?.();
+    }
+    try {
+      entry.onStep?.(step);
+    } catch (err) {
+      this.pending.delete(id);
+      clearPendingTimers(entry);
+      try {
+        this.worker?.postMessage({ kind: "cancel", id });
+      } catch {
+      }
+      entry.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
   rejectPending(id, err) {
     const entry = this.pending.get(id);
     if (!entry) return;
@@ -165,7 +205,13 @@ var WriterWorker = class _WriterWorker {
     clearPendingTimers(entry);
     entry.reject(err);
   }
-  unresponsiveError(waitedMs) {
+  unresponsiveError(waitedMs, kind) {
+    if (kind === "copyDatabase") {
+      return new SirannonError(
+        `The writer worker moved no page of the copy for ${waitedMs}ms, so the copy was stopped and nothing it wrote is usable`,
+        "BACKUP_STALLED"
+      );
+    }
     return new SirannonError(
       `Writer worker did not respond within ${waitedMs}ms; the operation's outcome is unknown`,
       "WRITER_WORKER_TIMEOUT"
@@ -180,17 +226,17 @@ var WriterWorker = class _WriterWorker {
     if (!entry) return;
     const worker = this.worker;
     if (!entry.cancellable || !worker) {
-      this.rejectPending(id, this.unresponsiveError(this.timeoutMs));
+      this.rejectPending(id, this.unresponsiveError(this.timeoutMs, entry.kind));
       return;
     }
     try {
       worker.postMessage({ kind: "cancel", id });
     } catch {
-      this.rejectPending(id, this.unresponsiveError(this.timeoutMs));
+      this.rejectPending(id, this.unresponsiveError(this.timeoutMs, entry.kind));
       return;
     }
     entry.graceTimer = setTimeout(() => {
-      this.rejectPending(id, this.unresponsiveError(this.timeoutMs * 2));
+      this.rejectPending(id, this.unresponsiveError(this.timeoutMs * 2, entry.kind));
     }, this.timeoutMs);
     entry.graceTimer.unref?.();
   }
@@ -226,7 +272,7 @@ var WriterWorker = class _WriterWorker {
     }
     this.spawn();
   }
-  send(request) {
+  send(request, onStep) {
     const worker = this.worker;
     if (!worker) {
       return Promise.reject(
@@ -241,8 +287,16 @@ var WriterWorker = class _WriterWorker {
         timer = setTimeout(() => this.onDeadline(id), this.timeoutMs);
         timer.unref?.();
       }
-      const cancellable = request.kind !== "open" && request.kind !== "close";
-      this.pending.set(id, { resolve: resolve2, reject, timer, graceTimer: null, cancellable });
+      const cancellable = request.kind !== "open" && request.kind !== "close" && request.kind !== "loadExtension";
+      this.pending.set(id, {
+        resolve: resolve2,
+        reject,
+        timer,
+        graceTimer: null,
+        cancellable,
+        kind: request.kind,
+        ...onStep ? { onStep } : {}
+      });
       try {
         worker.postMessage(message);
       } catch (err) {
@@ -257,10 +311,10 @@ var WriterWorker = class _WriterWorker {
       }
     });
   }
-  request(request) {
+  request(request, onStep) {
     if (this.fatal) return Promise.reject(this.fatal);
     if (this.closed) return Promise.reject(new SirannonError("Writer worker is closed", "WRITER_WORKER_CLOSED"));
-    return this.ready.then(() => this.send(request)).then((value) => {
+    return this.ready.then(() => this.send(request, onStep)).then((value) => {
       this.restarts = 0;
       return value;
     });
@@ -286,6 +340,14 @@ var WriterWorker = class _WriterWorker {
           }))
         }))
       }),
+      copyDatabase: (request) => this.request(
+        { kind: "copyDatabase", destPath: request.destPath, pagesPerStep: request.pagesPerStep },
+        request.onStep
+      ),
+      loadExtension: async (extensionPath) => {
+        await this.request({ kind: "loadExtension", path: extensionPath });
+        if (!this.loadedExtensions.includes(extensionPath)) this.loadedExtensions.push(extensionPath);
+      },
       transaction: async (fn) => {
         await conn.exec("BEGIN");
         try {
@@ -349,9 +411,10 @@ function nodeBackupEngine() {
   const manager = new BackupManager();
   const scheduler = new BackupScheduler(manager);
   return {
-    backup: (conn, destPath) => manager.backup(conn, destPath),
+    backup: (conn, destPath, onFirstStep) => manager.backup(conn, destPath, onFirstStep),
+    copyToDestination: (conn, request) => manager.copyToDestination(conn, request),
     schedule: (conn, options, runExclusive) => scheduler.schedule(conn, options, runExclusive)
   };
 }
 
-export { WriterWorker, createStatementCache, narrowRowIntegers, narrowRowsIntegers, narrowSafeBigInt, nodeBackupEngine, nodeResolveExtensionPath, nodeWriterContext };
+export { WriterWorker, createStatementCache, loadThroughRuntime, narrowRowIntegers, narrowRowsIntegers, narrowSafeBigInt, nodeBackupEngine, nodeResolveExtensionPath, nodeWriterContext };

package/dist/{chunk-DVWQD3GF.mjs → chunk-GVYLZVUZ.mjs}

@@ -6,6 +6,15 @@ var SirannonError = class extends Error {
     this.name = "SirannonError";
   }
 };
+var ExtensionError = class extends SirannonError {
+  constructor(path, cause) {
+    super(
+      cause ? `Failed to load extension '${path}': ${cause}` : `Failed to load extension '${path}'`,
+      "EXTENSION_ERROR"
+    );
+    this.name = "ExtensionError";
+  }
+};
 
 // src/core/driver/define.ts
 function defineDriver(config) {
@@ -46,4 +55,4 @@ function synchronousPragmaValue(level) {
   return value;
 }
 
-export { defineDriver, synchronousPragmaValue };
+export { ExtensionError, SirannonError, defineDriver, synchronousPragmaValue };

package/dist/chunk-V5FUJEYY.mjs

@@ -0,0 +1,8 @@
+// src/core/random-hex.ts
+function randomHex(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+export { randomHex };