@delali/sirannon-db 0.2.3-next.37 → 0.2.3-next.39

package/dist/core/index.mjs

@@ -1,5 +1,3 @@
-import { planBackupRestore, backupPiecesSafeToDelete } from '../chunk-YNTDOFTN.mjs';
-export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YNTDOFTN.mjs';
 import { Transaction, LWWResolver, REMOTE_ORIGIN_NODE_ID, BatchReader, BatchApplier, recordLocalColumnVersions, HLC, loadPersistedHlc, isWellFormedHlc, HLC_CLOCK_META_KEY } from '../chunk-P2VJYRVY.mjs';
 export { Transaction } from '../chunk-P2VJYRVY.mjs';
 import { executeBatch, executeBatchSummary, execute, bindParams, executeGroup, query, queryForWire, queryOne } from '../chunk-HCCGEIZ2.mjs';
@@ -7,15 +5,19 @@ export { execute, executeBatch, query, queryOne } from '../chunk-HCCGEIZ2.mjs';
 import { tokenizeSql, unsupported, findClauses, readSource, readSortTerms, readWindow, readSelectItems, parameterName } from '../chunk-SBL6GN43.mjs';
 import { reconcileMigrationChecksums, migrationContentChecksum, ensureCdcEpoch, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling, runBulkLoad, TransactionGrouper, PrimedSubscription } from '../chunk-ECEGYTVF.mjs';
 export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-ECEGYTVF.mjs';
+import { planBackupRestore, backupPiecesSafeToDelete } from '../chunk-YNTDOFTN.mjs';
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YNTDOFTN.mjs';
 import { ensureMigrationsTable, prepareUpdateMigrationChecksum, prepareInsertMigration, selectAppliedMigrationsNewestFirst, prepareDeleteMigration, selectAppliedMigrations, tableInfoRows, selectTableSql, selectTableExists, selectMetaValue, upsertMetaValue, SEQ_STRING_RE, replaceMigrationHistory, highestMigrationVersion, selectCountOutboundChanges, ensureMetaTable, ensureChangesTable, ensureBatchApplyTables, PkResolver, selectMaxChangeSeq, selectMaxAppliedSourceSeq, insertMetaValueIfAbsent, selectMaxChangeHlc, updateUnstampedChangeStampsSql, UPSERT_META_VALUE_SQL, setForeignKeysEnabled, IDENTIFIER_RE, validateDdlSafety, ensureStagedChangesTable, upsertStagedChangeSql, selectFirstStagedTransactionEnd, deleteStagedChangesUpToSeq, selectMaxStagedSeq, deleteAllStagedChanges, deleteMetaValue, assertSafeIdentifier, selectStagedChangesInRange } from '../chunk-7FQRQH5Z.mjs';
 import { ReplicationError } from '../chunk-2QLXDHAP.mjs';
 import { MIGRATIONS_TABLE, LIVE_PROBE_TABLE_PREFIX, META_TABLE, CHANGES_TABLE, assertSqlAllowed, INTERNAL_TABLE_PREFIX, encodeTaggedValues, decodeTaggedValues } from '../chunk-7R4ER4FB.mjs';
 import '../chunk-GVCNMPOS.mjs';
-export { defineDriver } from '../chunk-BQFQ65OL.mjs';
-export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-YVF2ZJTE.mjs';
+import { defaultStagingDir } from '../chunk-LXCGPZPA.mjs';
+export { defineDriver } from '../chunk-LXCGPZPA.mjs';
 import { startCopyWithoutHoldingWriter } from '../chunk-W67A4H2E.mjs';
 import { DEFAULT_SYNCHRONOUS } from '../chunk-OUSWVNWT.mjs';
 export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-OUSWVNWT.mjs';
+import { DEFAULT_CHAIN_NAME } from '../chunk-YVF2ZJTE.mjs';
+export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-YVF2ZJTE.mjs';
 import { randomHex } from '../chunk-V5FUJEYY.mjs';
 import { LAZY_DOWN_SQL, parseMigrationFilename } from '../chunk-7C36BCSN.mjs';
 export { MIGRATION_FILENAME_PATTERN, parseMigrationFilename } from '../chunk-7C36BCSN.mjs';
@@ -202,6 +204,7 @@ var DatabaseBackupController = class {
   }
   cancellers = [];
   cycle = null;
+  cycleOptions = null;
   cycleStarted = Promise.resolve();
   require() {
     if (!this.engine) {
@@ -215,7 +218,7 @@ var DatabaseBackupController = class {
   requireCycle() {
     if (!this.cycle) {
       throw new SirannonError(
-        `Database '${this.databaseId}' opened without the backups option, so it captures no change log and holds no chain`,
+        `Database '${this.databaseId}' opened without the backups option, so it captures no change log and extends no chain`,
         "BACKUP_UNSUPPORTED"
       );
     }
@@ -228,12 +231,13 @@ var DatabaseBackupController = class {
       this.engine?.streamsToDestination() ?? false
     );
   }
-  backup(destPath) {
+  async backup(destPath) {
     const engine = this.require();
-    return startCopyWithoutHoldingWriter(
+    const copy = await startCopyWithoutHoldingWriter(
       this.runExclusive,
       (onFirstStep) => engine.backup(this.acquireWriter(), destPath, onFirstStep)
     );
+    return { ...copy, databaseId: this.databaseId, sourcePath: this.sourcePath };
   }
   backupTo(options) {
     const engine = this.require();
@@ -249,7 +253,14 @@ var DatabaseBackupController = class {
   }
   schedule(options) {
     const engine = this.require();
-    this.cancellers.push(engine.schedule(this.acquireWriter(), options, this.runExclusive));
+    this.cancellers.push(
+      engine.schedule(this.acquireWriter(), {
+        ...options,
+        databaseId: this.databaseId,
+        sourcePath: this.sourcePath,
+        runExclusive: this.runExclusive
+      })
+    );
   }
   /**
    * Builds the cycle and starts it in the background. Its first turn copies the
@@ -258,6 +269,7 @@ var DatabaseBackupController = class {
    */
   startCycle(options) {
     const engine = this.require();
+    this.cycleOptions = options;
     this.cycle = engine.createCycle({
       ...options,
       databaseId: this.databaseId,
@@ -281,6 +293,27 @@ var DatabaseBackupController = class {
   chains() {
     return this.requireCycle().chains();
   }
+  status() {
+    return this.requireCycle().status();
+  }
+  location() {
+    const options = this.cycleOptions;
+    if (!options) {
+      throw new SirannonError(
+        `Database '${this.databaseId}' opened without the backups option, so it captures no change log and extends no chain`,
+        "BACKUP_UNSUPPORTED"
+      );
+    }
+    return {
+      destination: options.destination,
+      chainName: options.chainName ?? DEFAULT_CHAIN_NAME,
+      stagingDir: options.stagingDir ?? defaultStagingDir(this.sourcePath),
+      ...options.destinationTimeoutMs === void 0 ? {} : { destinationTimeoutMs: options.destinationTimeoutMs }
+    };
+  }
+  verify(name) {
+    return this.requireCycle().verify(name);
+  }
   async restorePlan(moment) {
     return planBackupRestore(await this.chains(), moment);
   }
@@ -2138,10 +2171,11 @@ var DatabaseBackups = class extends DatabaseLifecycle {
    * runs in the gap between two steps rather than waiting for the whole copy.
    *
    * @param destPath - Path the copy is written to.
+   * @returns The run identifier, the timings, the pages it moved, and the bytes the file holds.
    */
   async backup(destPath) {
     this.ensureOpen();
-    await this.runtime.backups.backup(destPath);
+    return this.runtime.backups.backup(destPath);
   }
   /**
    * Copies this database to a destination you supply, in fixed-size pieces,
@@ -2175,7 +2209,7 @@ var DatabaseBackups = class extends DatabaseLifecycle {
   /**
    * Starts repeating backups on a cron schedule, keeping a bounded number of files.
    *
-   * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+   * @param options - Cron expression, destination directory, retention, and time zone, along with the callbacks Sirannon calls after each finished copy and after each failure.
    */
   scheduleBackup(options) {
     this.ensureOpen();
@@ -2205,6 +2239,54 @@ var DatabaseBackups = class extends DatabaseLifecycle {
     this.ensureNotClosed();
     return this.runtime.backups.chains();
   }
+  /**
+   * Reads what this database's backup cycle is doing at this moment, and what
+   * its recent turns produced.
+   *
+   * A caller that triggers a turn with {@link DatabaseBackups.captureBackupChanges}
+   * without waiting on it would read this until that turn finishes. A full copy
+   * of a large database reports its pages as SQLite moves them.
+   *
+   * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
+   */
+  backupStatus() {
+    this.ensureNotClosed();
+    return this.runtime.backups.status();
+  }
+  /**
+   * Reads one of this database's backups back out of the destination and
+   * compares it against the record the backup that wrote it left behind.
+   *
+   * A restore would fail on a damaged piece only once that restore had already
+   * begun, so name the backup here beforehand. Sirannon then fetches every
+   * piece in order and folds a SHA-256 over the bytes as they arrive, and it
+   * compares that digest and the byte count against the record. Only one piece
+   * is in memory at any moment, so a check over a large full copy needs no
+   * local storage of its own.
+   *
+   * A missing piece, a byte count that differs from the recorded one, and a
+   * digest that differs from the recorded one will each fail with
+   * `BACKUP_DESTINATION_ERROR`.
+   *
+   * @param name - Name the backup is stored under, which every entry {@link DatabaseBackups.backupChain} returns states.
+   * @returns The pieces read, the bytes they add up to, and the digest where the backup recorded one.
+   */
+  async verifyBackup(name) {
+    this.ensureNotClosed();
+    return this.runtime.backups.verify(name);
+  }
+  /**
+   * Reads where this database's backups are stored.
+   *
+   * `restoreBackup` accepts what you get back, and it then rebuilds this
+   * database from its own backups at whatever path you name.
+   *
+   * @returns The destination, the name its chains are listed under, and the directory Sirannon stages captures in.
+   */
+  backupLocation() {
+    this.ensureNotClosed();
+    return this.runtime.backups.location();
+  }
   /**
    * Works out what a restore to a given moment has to read.
    *
@@ -3858,17 +3940,85 @@ function migrationsFromFiles(files, options) {
   return applyBaselineOption(migrations, options?.baseline);
 }
 
+// src/core/migrations/registry-set.ts
+var RegistryMigrationSet = class {
+  constructor(source) {
+    this.source = source;
+  }
+  loading = null;
+  /**
+   * Reads the set, loading it where a function supplies it.
+   *
+   * @returns The migrations, which is an empty list where the registry has none.
+   * @throws When the function returns anything but a list.
+   */
+  load() {
+    const source = this.source;
+    if (source === void 0 || Array.isArray(source)) {
+      return Promise.resolve(source ?? []);
+    }
+    if (this.loading) return this.loading;
+    const loading = (async () => {
+      const set = await source();
+      if (!Array.isArray(set)) {
+        throw new MigrationError(
+          "The migrations source must return an array of migrations",
+          0,
+          "MIGRATION_SOURCE_INVALID"
+        );
+      }
+      return set;
+    })();
+    loading.catch(() => {
+      if (this.loading === loading) this.loading = null;
+    });
+    this.loading = loading;
+    return loading;
+  }
+  /**
+   * Applies the set to one database. A database that refuses writes takes none.
+   *
+   * @param db - The database to migrate.
+   */
+  async applyTo(db) {
+    if (this.source === void 0 || db.readOnly) return;
+    const migrations = await this.load();
+    if (migrations.length === 0) return;
+    await db.migrate(migrations);
+  }
+};
+
+// src/core/sirannon-offline.ts
+async function takeDatabaseOffline(offline) {
+  await offline.database.close();
+  let outcome;
+  try {
+    outcome = { ok: true, value: await offline.action(offline.path) };
+  } catch (err) {
+    outcome = { ok: false, failure: err };
+  }
+  try {
+    await offline.reopen();
+  } catch (err) {
+    outcome.reopenFailure = err;
+  }
+  return outcome;
+}
+
 // src/core/sirannon.ts
 var Sirannon = class {
   dbs = /* @__PURE__ */ new Map();
+  openedWith = /* @__PURE__ */ new Map();
+  offline = /* @__PURE__ */ new Set();
+  offlineWork = /* @__PURE__ */ new Set();
   opening = /* @__PURE__ */ new Set();
   resolving = /* @__PURE__ */ new Map();
-  migrationSet = null;
   _shutdown = false;
   _driver;
   hookRegistry;
   metricsCollector;
   lifecycleManager;
+  migrations;
   /** The driver, hooks, metrics, lifecycle, migrations, and writer-worker default this registry was built with. */
   options;
   /**
@@ -3880,6 +4030,7 @@ var Sirannon = class {
     this.options = options;
     this._driver = options.driver;
     this.hookRegistry = new HookRegistry(options.hooks);
+    this.migrations = new RegistryMigrationSet(options.migrations);
     this.metricsCollector = options.metrics ? new MetricsCollector(options.metrics) : null;
     this.lifecycleManager = options.lifecycle ? new LifecycleManager(options.lifecycle, {
       open: (id, path, opts) => this.open(id, path, opts),
@@ -3902,17 +4053,18 @@ var Sirannon = class {
    * @throws When the identifier is already registered.
    */
   async open(id, path, options) {
-    this.ensureRunning();
+    this.ensureOpenAllowed(id);
     if (this.dbs.has(id) || this.opening.has(id)) {
       throw new DatabaseAlreadyExistsError(id);
     }
     this.opening.add(id);
+    const resolvedOptions = this.withRegistryDefaults(options);
     let db;
     try {
       if (this.hookRegistry.has("beforeConnect")) {
         this.hookRegistry.invokeSync("beforeConnect", { databaseId: id, path });
       }
-      db = await Database.create(id, path, this._driver, this.withRegistryDefaults(options), {
+      db = await Database.create(id, path, this._driver, resolvedOptions, {
         parentHooks: this.hookRegistry,
         metrics: this.metricsCollector ?? void 0
       });
@@ -3925,7 +4077,7 @@ var Sirannon = class {
       );
     }
     try {
-      await this.applyRegistryMigrations(db);
+      await this.migrations.applyTo(db);
     } catch (err) {
       await db.close().catch(() => {
       });
@@ -3937,13 +4089,14 @@ var Sirannon = class {
     } finally {
       this.opening.delete(id);
     }
-    if (this._shutdown) {
+    if (this._shutdown && !this.offline.has(id)) {
       await db.close().catch(() => {
       });
       throw new SirannonError("Sirannon has been shut down", "SHUTDOWN");
     }
     db.addCloseListener(() => {
       this.dbs.delete(id);
+      this.openedWith.delete(id);
       this.lifecycleManager?.untrack(id);
       if (this.hookRegistry.has("databaseClose")) {
         try {
@@ -3959,6 +4112,7 @@ var Sirannon = class {
       });
     });
     this.dbs.set(id, db);
+    this.openedWith.set(id, resolvedOptions === void 0 ? { path } : { path, options: resolvedOptions });
     this.lifecycleManager?.markActive(id);
     if (this.hookRegistry.has("databaseOpen")) {
       try {
@@ -3992,6 +4146,52 @@ var Sirannon = class {
     }
     await db.close();
   }
+  /**
+   * Closes one database, calls an action against the file behind it, and then
+   * opens that database again under the same identifier with the settings it
+   * had before.
+   *
+   * A restore rebuilds a database at the path it already occupies, so no
+   * connection may be open on that file while Sirannon replaces its bytes. The
+   * identifier answers nothing until that database is open again, though an
+   * action that failed still leaves a database open at the end.
+   *
+   * @param id - Identifier of the database to take offline.
+   * @param action - Runs with the database closed, and receives its file path.
+   * @returns Whether the action returned, what it produced or threw, and what a failed reopen threw.
+   * @throws When no database is open under the identifier, when it refuses writes, or when the close fails.
+   *
+   * @internal
+   */
+  async withDatabaseOffline(id, action) {
+    this.ensureRunning();
+    const db = this.dbs.get(id);
+    const opened = this.openedWith.get(id);
+    if (!db || !opened) throw new DatabaseNotFoundError(id);
+    if (db.readOnly) throw new ReadOnlyError(id);
+    this.dbs.delete(id);
+    this.opening.add(id);
+    this.offline.add(id);
+    const work = takeDatabaseOffline({
+      database: db,
+      path: opened.path,
+      action,
+      reopen: async () => {
+        this.opening.delete(id);
+        try {
+          return await this.open(id, opened.path, opened.options);
+        } finally {
+          this.offline.delete(id);
+        }
+      }
+    }).finally(() => {
+      this.opening.delete(id);
+      this.offline.delete(id);
+      this.offlineWork.delete(work);
+    });
+    this.offlineWork.add(work);
+    return work;
+  }
   /**
    * Returns an already-open database.
    *
@@ -4011,7 +4211,7 @@ var Sirannon = class {
   async resolve(id) {
     const db = this.get(id);
     if (db) return db;
-    if (this._shutdown) return void 0;
+    if (this._shutdown || this.offline.has(id)) return void 0;
     const manager = this.lifecycleManager;
     if (!manager) return void 0;
     const pending = this.resolving.get(id);
@@ -4024,38 +4224,7 @@ var Sirannon = class {
   }
   /** @internal */
   registryMigrations() {
-    return this.loadMigrationSet();
-  }
-  async applyRegistryMigrations(db) {
-    if (this.options.migrations === void 0 || db.readOnly) return;
-    const migrations = await this.loadMigrationSet();
-    if (migrations.length === 0) return;
-    await db.migrate(migrations);
-  }
-  loadMigrationSet() {
-    const source = this.options.migrations;
-    if (source === void 0 || Array.isArray(source)) {
-      return Promise.resolve(source ?? []);
-    }
-    if (this.migrationSet) return this.migrationSet;
-    const loading = (async () => {
-      const set = await source();
-      if (!Array.isArray(set)) {
-        throw new MigrationError(
-          "The migrations source must return an array of migrations",
-          0,
-          "MIGRATION_SOURCE_INVALID"
-        );
-      }
-      return set;
-    })();
-    loading.catch(() => {
-      if (this.migrationSet === loading) {
-        this.migrationSet = null;
-      }
-    });
-    this.migrationSet = loading;
-    return loading;
+    return this.migrations.load();
   }
   /**
    * Reports whether a database is open under an identifier.
@@ -4076,10 +4245,17 @@ var Sirannon = class {
   }
   /**
    * Closes every open database and stops the lifecycle timers.
+   *
+   * A database whose file Sirannon is replacing delays the shutdown until that
+   * work finishes, since a process that exits part-way through would leave the
+   * path with no database on it at all.
    */
   async shutdown() {
     if (this._shutdown) return;
     this._shutdown = true;
+    while (this.offlineWork.size > 0) {
+      await Promise.allSettled([...this.offlineWork]);
+    }
     this.lifecycleManager?.dispose();
     const errors = [];
     const snapshot = [...this.dbs.values()];
@@ -4140,6 +4316,10 @@ var Sirannon = class {
       throw new SirannonError("Sirannon has been shut down", "SHUTDOWN");
     }
   }
+  ensureOpenAllowed(id) {
+    if (this.offline.has(id)) return;
+    this.ensureRunning();
+  }
 };
 
 // src/core/operation-registry.ts

package/dist/{database-955qag_W.d.ts → database-BlhUdJAO.d.ts}

@@ -1,9 +1,9 @@
-import { B as BackupCapabilities, a as BackupRestorePlan, b as BackupSafeToDeleteOptions } from './chain-queries-D5aZ-8v2.js';
-import { a as SQLiteDriver, F as SynchronousLevel, aa as WorkerHostOptions, i as SQLiteConnection, X as DriverCapabilities, ab as BackupEngine, v as BackupToDestinationOptions, k as BackupRunReport, E as BackupScheduleOptions, n as BackupCycleOptions, g as BackupChain, h as BackupChainRecord, T as Transaction, ac as WriterContext, M as Migration, G as MigrationResult, R as RollbackResult, a5 as QueryHookContext, Q as ConnectionHookContext, K as BeforeSubscribeHook, Z as HookConfig, $ as MetricsConfig, a6 as QueryMetrics, U as ConnectionMetrics, O as CDCMetrics, D as DatabaseOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-Xb0L3o3w.js';
-import { C as ChangeTracker } from './change-tracker-DXHPFe9J.js';
+import { D as DatabaseBackupController, B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions } from './database-backup-C090lMHc.js';
+import { S as SQLiteDriver, U as SynchronousLevel, ak as WorkerHostOptions, I as SQLiteConnection, T as Transaction, al as WriterContext, M as Migration, W as MigrationResult, X as RollbackResult, af as QueryHookContext, a2 as ConnectionHookContext, $ as BeforeSubscribeHook, a7 as HookConfig, a9 as MetricsConfig, ag as QueryMetrics, a3 as ConnectionMetrics, a0 as CDCMetrics, D as DatabaseOptions, p as BackupFileReport, y as BackupToDestinationOptions, f as BackupRunReport, O as BackupScheduleOptions, g as BackupChain, o as BackupCycleStatus, z as BackupVerifyResult, k as BackupChainRecord, b as BeforeQueryHook, A as AfterQueryHook } from './types-DApb7dvw.js';
+import { C as ChangeTracker } from './change-tracker-uG9gWvsY.js';
 import { C as ChangeEvent, S as Subscription, c as SubscriptionBuilder, P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-Cv8N7pXj.js';
 import { H as HLCTimestamp, c as ReplicationChange, C as ConflictResolver, A as ApplyResult, R as ReplicationBatch } from './types-CjhxcjhA.js';
-import { h as AppliedMigrationRow, b as BulkLoadOptions, a as BulkLoadResult } from './server-options-D4VmfTHw.js';
+import { h as AppliedMigrationRow, b as BulkLoadOptions, a as BulkLoadResult } from './server-options-DeK6ZG8u.js';
 import { L as LiveQueryOptions, a as LiveQuery } from './types-BCejqzNA.js';
 
 /**
@@ -43,39 +43,6 @@ declare class ConnectionPool {
     close(): Promise<void>;
 }
 
-type RunExclusive$2 = (op: () => Promise<void>) => Promise<void>;
-declare class DatabaseBackupController {
-    private readonly runExclusive;
-    private readonly acquireWriter;
-    private readonly driverCapabilities;
-    private readonly databaseId;
-    private readonly sourcePath;
-    private readonly engine?;
-    private readonly cancellers;
-    private cycle;
-    private cycleStarted;
-    constructor(runExclusive: RunExclusive$2, acquireWriter: () => SQLiteConnection, driverCapabilities: DriverCapabilities, databaseId: string, sourcePath: string, engine?: BackupEngine | undefined);
-    private require;
-    private requireCycle;
-    capabilities(): BackupCapabilities;
-    backup(destPath: string): Promise<void>;
-    backupTo(options: BackupToDestinationOptions): Promise<BackupRunReport>;
-    schedule(options: BackupScheduleOptions): void;
-    /**
-     * Builds the cycle and starts it in the background. Its first turn copies the
-     * whole database, and an open cannot wait on that. A failure reaches the
-     * caller through the cycle's own error callback.
-     */
-    startCycle(options: BackupCycleOptions): void;
-    captureChanges(): Promise<BackupRunReport | undefined>;
-    chains(): Promise<BackupChain[]>;
-    restorePlan(moment: number): Promise<BackupRestorePlan>;
-    piecesSafeToDelete(options?: BackupSafeToDeleteOptions): Promise<BackupChainRecord[]>;
-    /** Stops the cycle, capturing the log one final time so nothing written since the previous turn is lost. */
-    stopCycle(): Promise<void>;
-    cancelAll(): void;
-}
-
 declare class SubscriptionManager {
     private nextId;
     private readonly subscriptions;
@@ -645,8 +612,9 @@ declare class DatabaseBackups extends DatabaseLifecycle {
      * runs in the gap between two steps rather than waiting for the whole copy.
      *
      * @param destPath - Path the copy is written to.
+     * @returns The run identifier, the timings, the pages it moved, and the bytes the file holds.
      */
-    backup(destPath: string): Promise<void>;
+    backup(destPath: string): Promise<BackupFileReport>;
     /**
      * Copies this database to a destination you supply, in fixed-size pieces,
      * while it stays open for reads and writes.
@@ -674,7 +642,7 @@ declare class DatabaseBackups extends DatabaseLifecycle {
     /**
      * Starts repeating backups on a cron schedule, keeping a bounded number of files.
      *
-     * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+     * @param options - Cron expression, destination directory, retention, and time zone, along with the callbacks Sirannon calls after each finished copy and after each failure.
      */
     scheduleBackup(options: BackupScheduleOptions): void;
     /**
@@ -695,6 +663,45 @@ declare class DatabaseBackups extends DatabaseLifecycle {
      * @returns One entry per chain, newest first, each with its full copy and its change pieces in order.
      */
     backupChain(): Promise<BackupChain[]>;
+    /**
+     * Reads what this database's backup cycle is doing at this moment, and what
+     * its recent turns produced.
+     *
+     * A caller that triggers a turn with {@link DatabaseBackups.captureBackupChanges}
+     * without waiting on it would read this until that turn finishes. A full copy
+     * of a large database reports its pages as SQLite moves them.
+     *
+     * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
+     */
+    backupStatus(): BackupCycleStatus;
+    /**
+     * Reads one of this database's backups back out of the destination and
+     * compares it against the record the backup that wrote it left behind.
+     *
+     * A restore would fail on a damaged piece only once that restore had already
+     * begun, so name the backup here beforehand. Sirannon then fetches every
+     * piece in order and folds a SHA-256 over the bytes as they arrive, and it
+     * compares that digest and the byte count against the record. Only one piece
+     * is in memory at any moment, so a check over a large full copy needs no
+     * local storage of its own.
+     *
+     * A missing piece, a byte count that differs from the recorded one, and a
+     * digest that differs from the recorded one will each fail with
+     * `BACKUP_DESTINATION_ERROR`.
+     *
+     * @param name - Name the backup is stored under, which every entry {@link DatabaseBackups.backupChain} returns states.
+     * @returns The pieces read, the bytes they add up to, and the digest where the backup recorded one.
+     */
+    verifyBackup(name: string): Promise<BackupVerifyResult>;
+    /**
+     * Reads where this database's backups are stored.
+     *
+     * `restoreBackup` accepts what you get back, and it then rebuilds this
+     * database from its own backups at whatever path you name.
+     *
+     * @returns The destination, the name its chains are listed under, and the directory Sirannon stages captures in.
+     */
+    backupLocation(): BackupChainLocation;
     /**
      * Works out what a restore to a given moment has to read.
      *

package/dist/{chain-queries-D5aZ-8v2.d.ts → database-backup-C090lMHc.d.ts}

@@ -1,4 +1,4 @@
-import { e as BackupChainBase, f as BackupChainChange, g as BackupChain, h as BackupChainRecord } from './types-Xb0L3o3w.js';
+import { h as BackupChainBase, i as BackupChainChange, g as BackupChain, k as BackupChainRecord, B as BackupDestination, I as SQLiteConnection, P as DriverCapabilities, Q as BackupEngine, p as BackupFileReport, y as BackupToDestinationOptions, f as BackupRunReport, O as BackupScheduleOptions, n as BackupCycleOptions, o as BackupCycleStatus, z as BackupVerifyResult } from './types-DApb7dvw.js';
 
 /**
  * What one runtime supports of the backup operations, so a caller learns
@@ -88,4 +88,54 @@ declare function planBackupRestore(chains: readonly BackupChain[], moment: numbe
  */
 declare function backupPiecesSafeToDelete(chains: readonly BackupChain[], options?: BackupSafeToDeleteOptions): BackupChainRecord[];
 
-export { type BackupCapabilities as B, type BackupRestorePlan as a, type BackupSafeToDeleteOptions as b, backupPiecesSafeToDelete as c, planBackupRestore as p };
+type RunExclusive = (op: () => Promise<void>) => Promise<void>;
+/** Where one database's backups are stored, and what a restore of that database reads.
+ * @public
+ */
+interface BackupChainLocation {
+    /** The destination its pieces and its chain records go to. */
+    destination: BackupDestination;
+    /** Name that destination lists its chains under. */
+    chainName: string;
+    /** Directory the cycle stages each capture in before that capture goes out. */
+    stagingDir: string;
+    /** Deadline the operator set on every call to that destination, where they set one. */
+    destinationTimeoutMs?: number;
+}
+declare class DatabaseBackupController {
+    private readonly runExclusive;
+    private readonly acquireWriter;
+    private readonly driverCapabilities;
+    private readonly databaseId;
+    private readonly sourcePath;
+    private readonly engine?;
+    private readonly cancellers;
+    private cycle;
+    private cycleOptions;
+    private cycleStarted;
+    constructor(runExclusive: RunExclusive, acquireWriter: () => SQLiteConnection, driverCapabilities: DriverCapabilities, databaseId: string, sourcePath: string, engine?: BackupEngine | undefined);
+    private require;
+    private requireCycle;
+    capabilities(): BackupCapabilities;
+    backup(destPath: string): Promise<BackupFileReport>;
+    backupTo(options: BackupToDestinationOptions): Promise<BackupRunReport>;
+    schedule(options: BackupScheduleOptions): void;
+    /**
+     * Builds the cycle and starts it in the background. Its first turn copies the
+     * whole database, and an open cannot wait on that. A failure reaches the
+     * caller through the cycle's own error callback.
+     */
+    startCycle(options: BackupCycleOptions): void;
+    captureChanges(): Promise<BackupRunReport | undefined>;
+    chains(): Promise<BackupChain[]>;
+    status(): BackupCycleStatus;
+    location(): BackupChainLocation;
+    verify(name: string): Promise<BackupVerifyResult>;
+    restorePlan(moment: number): Promise<BackupRestorePlan>;
+    piecesSafeToDelete(options?: BackupSafeToDeleteOptions): Promise<BackupChainRecord[]>;
+    /** Stops the cycle, capturing the log one final time so nothing written since the previous turn is lost. */
+    stopCycle(): Promise<void>;
+    cancelAll(): void;
+}
+
+export { type BackupCapabilities as B, DatabaseBackupController as D, type BackupChainLocation as a, type BackupRestorePlan as b, type BackupSafeToDeleteOptions as c, backupPiecesSafeToDelete as d, planBackupRestore as p };

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

@@ -1,4 +1,4 @@
-import { a as SQLiteDriver } from '../types-Xb0L3o3w.js';
+import { S as SQLiteDriver } from '../types-DApb7dvw.js';
 import '../query-types-Cv8N7pXj.js';
 
 /**

package/dist/driver/better-sqlite3.mjs

@@ -1,12 +1,15 @@
-import { nodeResolveExtensionPath, nodeWriterContext, nodeBackupEngine, nodeStreamingSupport, WriterWorker, createStatementCache, loadThroughRuntime, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-ZKDBGX7H.mjs';
-import '../chunk-72I5UI5C.mjs';
-import '../chunk-BQTVNI5H.mjs';
-import '../chunk-GBM4AU24.mjs';
-import { defineDriver } from '../chunk-BQFQ65OL.mjs';
-import '../chunk-YVF2ZJTE.mjs';
+import { nodeResolveExtensionPath, nodeWriterContext, nodeBackupEngine, nodeStreamingSupport, WriterWorker, createStatementCache, loadThroughRuntime, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-OJQHM4MT.mjs';
+import '../chunk-7SC2TZAS.mjs';
+import '../chunk-DXXCLTFF.mjs';
+import { defineDriver } from '../chunk-LXCGPZPA.mjs';
 import '../chunk-W67A4H2E.mjs';
 import '../chunk-YLAVDZCS.mjs';
+import '../chunk-W77EEVOT.mjs';
+import '../chunk-U445A3C4.mjs';
+import '../chunk-2QCPVE67.mjs';
+import '../chunk-DVS4QSIZ.mjs';
 import { synchronousPragmaValue } from '../chunk-OUSWVNWT.mjs';
+import '../chunk-YVF2ZJTE.mjs';
 import '../chunk-V5FUJEYY.mjs';
 import { BackupError } from '../chunk-PBRXXISQ.mjs';