@delali/sirannon-db 0.3.6-next.77 → 0.3.6-next.78

package/dist/core/index.mjs

@@ -1,34 +1,36 @@
-import { Transaction, MetricsCollector, readOutcome, failedStatementOutcome, settleLateOutcome, ROW_COUNTS_UNKNOWN, leavesOutcomeUnknown, LWWResolver, REMOTE_ORIGIN_NODE_ID, BatchReader, BatchApplier, recordLocalColumnVersions, writeOutcome, batchWriteOutcome, StatementRecorder, loadPersistedHlc, isWellFormedHlc, HLC_CLOCK_META_KEY, readOneOutcome } from '../chunk-AP4367HK.mjs';
-export { MetricsCollector, Transaction } from '../chunk-AP4367HK.mjs';
-import '../chunk-ZFFUVYYE.mjs';
-import { executeGroup } from '../chunk-ISDT4RBD.mjs';
-import { query, queryRowsForWire, queryOne, asQueryError, runInSavepoint, runWriterTransaction, withoutRowCounts, execute, executeBatchSummary, bindParams, executeBatch, queryMetered, queryForWire, queryOneMetered } from '../chunk-DDIHBUEN.mjs';
-export { execute, executeBatch, query, queryOne } from '../chunk-DDIHBUEN.mjs';
+import { Transaction, MetricsCollector, readOutcome, failedStatementOutcome, settleLateOutcome, ROW_COUNTS_UNKNOWN, leavesOutcomeUnknown, LWWResolver, REMOTE_ORIGIN_NODE_ID, BatchReader, BatchApplier, recordLocalColumnVersions, writeOutcome, batchWriteOutcome, StatementRecorder, loadPersistedHlc, isWellFormedHlc, HLC_CLOCK_META_KEY, readOneOutcome } from '../chunk-VGRAAQX3.mjs';
+export { MetricsCollector, Transaction } from '../chunk-VGRAAQX3.mjs';
+import { executeGroup } from '../chunk-ULUZUBON.mjs';
+import { query, queryRowsForWire, queryOne, asQueryError, runInSavepoint, runWriterTransaction, withoutRowCounts, execute, executeBatchSummary, bindParams, executeBatch, queryMetered, queryForWire, queryOneMetered } from '../chunk-ZWW53O5P.mjs';
+export { execute, executeBatch, query, queryOne } from '../chunk-ZWW53O5P.mjs';
 import { unsupported, findClauses, readSource, readSortTerms, readWindow, readSelectItems } from '../chunk-D3YF2G7X.mjs';
-import { reconcileMigrationChecksums, migrationContentChecksum, resolveDeviceRetentionPolicy, ensureCdcEpoch, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling, DEVICE_SYNC_PUSHED_SEQ_META_KEY, runBulkLoad, parseColumnDefinitions, TransactionGrouper, PrimedSubscription, dropCdcTriggers, ROWID_ALIASES } from '../chunk-SB3MIFLG.mjs';
-export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-SB3MIFLG.mjs';
-import { planBackupRestore, backupPiecesSafeToDelete } from '../chunk-YW7IKQ7T.mjs';
-export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YW7IKQ7T.mjs';
-import { ensureMigrationsTable, prepareUpdateMigrationChecksum, prepareInsertMigration, selectAppliedMigrationsNewestFirst, prepareDeleteMigration, selectAppliedMigrations, selectTableExists, selectMetaValue, upsertMetaValue, SEQ_STRING_RE, replaceMigrationHistory, highestMigrationVersion, selectCountOutboundChanges, ensureMetaTable, ensureChangesTable, ensureBatchApplyTables, ensureStagedPushChangesTable, PkResolver, selectMaxChangeSeq, selectMaxAppliedSourceSeq, tableColumnsWithGenerated, TABLE_XINFO_HIDDEN, selectTableSql, primaryKeyColumns, tableIndexList, upsertMetaMaxChangeSeqSql, updateChangeStampsAboveMetaSeqSql, upsertMetaValueAndMaxChangeSeqSql, insertMetaValueIfAbsent, HLC, selectMaxChangeHlc, setForeignKeysEnabled, IDENTIFIER_RE, validateDdlSafety, ensureStagedChangesTable, upsertStagedChangeSql, selectFirstStagedTransactionEnd, deleteStagedChangesUpToSeq, selectMaxStagedSeq, deleteAllStagedChanges, deleteMetaValue, selectStagedChangesInRange, assertSafeIdentifier } from '../chunk-RPWBYASV.mjs';
+import { reconcileMigrationChecksums, migrationContentChecksum, resolveDeviceRetentionPolicy, ensureCdcEpoch, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling, DEVICE_SYNC_PUSHED_SEQ_META_KEY, runBulkLoad, parseColumnDefinitions, dropMainSchemaTriggers, createMainSchemaTriggers, TransactionGrouper, PrimedSubscription, dropCdcTriggers, escId, ROWID_ALIASES, installKeyChangeCaptureTriggers, dropKeyChangeCaptureTriggers } from '../chunk-2ZQOZFX7.mjs';
+export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-2ZQOZFX7.mjs';
+import { EncryptionKeyring, planBackupRestore, backupPiecesSafeToDelete, resolveEncryptionKey, wipeEncryptionKey } from '../chunk-W74HFQFD.mjs';
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-W74HFQFD.mjs';
+import { ensureMigrationsTable, prepareUpdateMigrationChecksum, prepareInsertMigration, selectAppliedMigrationsNewestFirst, prepareDeleteMigration, selectAppliedMigrations, selectTableExists, selectMetaValue, deleteMetaValue, ensureMetaTable, upsertMetaValue, SEQ_STRING_RE, replaceMigrationHistory, highestMigrationVersion, selectCountOutboundChanges, ensureChangesTable, ensureBatchApplyTables, ensureStagedPushChangesTable, PkResolver, selectMaxChangeSeq, selectMaxAppliedSourceSeq, tableColumnsWithGenerated, TABLE_XINFO_HIDDEN, selectTableSql, primaryKeyColumns, tableIndexList, upsertMetaMaxChangeSeqSql, updateChangeStampsAboveMetaSeqSql, upsertMetaValueAndMaxChangeSeqSql, insertMetaValueIfAbsent, HLC, selectMaxChangeHlc, setForeignKeysEnabled, IDENTIFIER_RE, validateDdlSafety, ensureStagedChangesTable, upsertStagedChangeSql, selectFirstStagedTransactionEnd, deleteStagedChangesUpToSeq, selectMaxStagedSeq, deleteAllStagedChanges, selectStagedChangesInRange, assertSafeIdentifier } from '../chunk-MTOQ6QIS.mjs';
+import '../chunk-5DKWHT6K.mjs';
 import { ReplicationError } from '../chunk-BLMRNSUG.mjs';
-import { MIGRATIONS_TABLE, META_TABLE, CHANGES_TABLE, assertSqlAllowed, LIVE_PROBE_TABLE_PREFIX, eventTimestampToChangedAt, encodeTaggedValues, INTERNAL_TABLE_PREFIX, isReservedIdentifier, decodeTaggedValues, changedAtToEventTimestamp } from '../chunk-JFVEGN7J.mjs';
+import { MIGRATIONS_TABLE, META_TABLE, CHANGES_TABLE, assertSqlAllowed, LIVE_PROBE_TABLE_PREFIX, eventTimestampToChangedAt, encodeTaggedValues, INTERNAL_TABLE_PREFIX, isReservedIdentifier, decodeTaggedValues, changedAtToEventTimestamp, KEY_CHANGE_CAPTURE_PREFIX } from '../chunk-ZAUHAJ4G.mjs';
 import { tokenizeSql, isKeyword, parameterName } from '../chunk-SEL4A4WT.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import { defaultStagingDir } from '../chunk-JAQ2I4OT.mjs';
-export { defineDriver } from '../chunk-JAQ2I4OT.mjs';
-import { startCopyWithoutHoldingWriter } from '../chunk-W67A4H2E.mjs';
+import { defaultStagingDir } from '../chunk-Y4SP7CRF.mjs';
+import { startCopyWithoutHoldingWriter, readMainDatabasePath } from '../chunk-I4JY5QPA.mjs';
 import { lateRowCountsOf, lateGroupOutcomesOf, withoutLateRowCounts, withLateRowCounts } from '../chunk-K43WJORM.mjs';
+export { defineDriver } from '../chunk-A5ULJVK7.mjs';
 import { rowCountsOf, withRowCounts, allMetered } from '../chunk-E2GRX4ZD.mjs';
-import { DEFAULT_SYNCHRONOUS } from '../chunk-YCMB6GR4.mjs';
-export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-YCMB6GR4.mjs';
-import { DEFAULT_CHAIN_NAME } from '../chunk-CZL4D3BM.mjs';
-export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-CZL4D3BM.mjs';
+import { DEFAULT_CHAIN_NAME } from '../chunk-6CABU54O.mjs';
+export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-6CABU54O.mjs';
 import { assertDeadline, randomHex } from '../chunk-BGJ5JVYL.mjs';
 import { invokeCallerCallback } from '../chunk-HO2XTXVX.mjs';
+import { DEFAULT_SYNCHRONOUS } from '../chunk-YCMB6GR4.mjs';
+export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-YCMB6GR4.mjs';
+import { EncryptionError } from '../chunk-5O4J6LQQ.mjs';
+export { EncryptionError } from '../chunk-5O4J6LQQ.mjs';
 import { LAZY_DOWN_SQL, parseMigrationFilename } from '../chunk-VDN6FHU4.mjs';
 export { MIGRATION_FILENAME_PATTERN, parseMigrationFilename } from '../chunk-VDN6FHU4.mjs';
 import { resolveEffectiveBaseline, planPendingMigrations, SQLITE_USER_VERSION_MAX, applyBaselineOption } from '../chunk-BZWDPF4G.mjs';
-import { SirannonError, ConnectionPoolError, MigrationError, ReadOnlyError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, WriteOverloadError, ExtensionError, CDCError, QueryError, TransactionError } from '../chunk-KINDFBQP.mjs';
+import { ConnectionPoolError, SirannonError, MigrationError, ReadOnlyError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, WriteOverloadError, CDCError, QueryError, TransactionError } from '../chunk-KINDFBQP.mjs';
 export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, ForbiddenSqlError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, RequestDeniedError, SirannonError, TransactionError, WriteOverloadError } from '../chunk-KINDFBQP.mjs';
 
 // src/core/connection-pool.ts
@@ -41,53 +43,82 @@ async function closeAllSilently(connections) {
     }
   }
 }
-var ConnectionPool = class _ConnectionPool {
-  writer;
-  readers;
-  readerIndex = 0;
-  closed = false;
-  constructor(writer, readers) {
-    this.writer = writer;
-    this.readers = readers;
+function writerHostOptions(options) {
+  const keyring = options.keyring;
+  if (!keyring?.encrypted) return options.workerHostOptions;
+  return { ...options.workerHostOptions, encryptionKey: () => keyring.freshKeyBytes() };
+}
+async function openWriter(options, keyed) {
+  const { driver, path, walMode = true, synchronous } = options;
+  const writerOptions = {
+    walMode,
+    synchronous,
+    ...options.walAutoCheckpoint === void 0 ? {} : { walAutoCheckpoint: options.walAutoCheckpoint }
+  };
+  if (!options.useWriterWorker) return driver.open(path, { ...writerOptions, ...keyed });
+  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"
+    );
   }
-  static async create(options) {
-    const { driver, path, readOnly = false, readPoolSize = 4, walMode = true, synchronous } = options;
-    const writerOptions = {
-      walMode,
-      synchronous,
-      ...options.walAutoCheckpoint === void 0 ? {} : { walAutoCheckpoint: options.walAutoCheckpoint }
-    };
+  return driver.startWriterHost(path, writerOptions, writerHostOptions(options));
+}
+async function openConnections(options) {
+  const { driver, path, readOnly = false, readPoolSize = 4 } = options;
+  const open = async (keyed) => {
     let writer = null;
     const readers = [];
     try {
-      if (!readOnly) {
-        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, writerOptions, options.workerHostOptions);
-        } else {
-          writer = await driver.open(path, writerOptions);
-        }
-      }
+      if (!readOnly) writer = await openWriter(options, keyed);
       const poolSize = driver.capabilities.multipleConnections ? Math.max(readPoolSize, 1) : 0;
       for (let i = 0; i < poolSize; i++) {
-        const reader = await driver.open(path, { readonly: true, walMode: false });
-        readers.push(reader);
+        readers.push(await driver.open(path, { readonly: true, walMode: false, ...keyed }));
       }
     } catch (err) {
       await closeAllSilently([...readers, writer]);
       throw err;
     }
-    return new _ConnectionPool(writer, readers);
+    return { writer, readers };
+  };
+  return options.keyring ? options.keyring.openWith(open) : open({});
+}
+var ConnectionPool = class _ConnectionPool {
+  constructor(options, opened) {
+    this.options = options;
+    this.writer = opened.writer;
+    this.readers = opened.readers;
   }
-  acquireReader() {
+  writer;
+  readers;
+  readerIndex = 0;
+  closed = false;
+  isSuspended = false;
+  readsInFlight = 0;
+  readsSettled = null;
+  reopenFailure = null;
+  static async create(options) {
+    return new _ConnectionPool(options, await openConnections(options));
+  }
+  ensureAvailable() {
     if (this.closed) {
       throw new ConnectionPoolError("Connection pool is closed");
     }
+    if (this.isSuspended && this.reopenFailure !== null) {
+      if (this.reopenFailure instanceof SirannonError) throw this.reopenFailure;
+      throw new ConnectionPoolError(
+        "The database could not open its connections again after a key change replaced its file; close it and open it again under the new key"
+      );
+    }
+    if (this.isSuspended) {
+      throw new EncryptionError(
+        "The database is replacing its file to finish a key change, so its connections reopen once the replacement ends; retry the call",
+        "ENCRYPTION_CHANGE_IN_PROGRESS"
+      );
+    }
+  }
+  acquireReader() {
+    this.ensureAvailable();
     if (this.readers.length === 0) {
       if (!this.writer) {
         throw new ConnectionPoolError("No connections available");
@@ -99,26 +130,128 @@ var ConnectionPool = class _ConnectionPool {
     return reader;
   }
   acquireWriter() {
-    if (this.closed) {
-      throw new ConnectionPoolError("Connection pool is closed");
-    }
+    this.ensureAvailable();
     if (!this.writer) {
       throw new ConnectionPoolError("No write connection available (database is read-only)");
     }
     return this.writer;
   }
+  /**
+   * Returns the next reader connection and keeps it open until the caller passes the lease back through
+   * {@link ConnectionPool.releaseReader}, so that {@link ConnectionPool.closeReaders} closes no reader under a read.
+   *
+   * @returns The reader connection, which the caller releases exactly once when its read settles.
+   */
+  leaseReader() {
+    const reader = this.acquireReader();
+    this.readsInFlight++;
+    return reader;
+  }
+  /** Ends a lease that {@link ConnectionPool.leaseReader} returned. */
+  releaseReader() {
+    this.readsInFlight--;
+    if (this.readsInFlight === 0) this.readsSettled?.();
+  }
+  /**
+   * Returns what a read on the next reader connection returns, and keeps that connection open until the read settles,
+   * so that {@link ConnectionPool.closeReaders} closes no reader under a read.
+   *
+   * @param read - The read to run on the reader.
+   * @returns The value of the read.
+   */
+  async withReader(read) {
+    const reader = this.leaseReader();
+    try {
+      return await read(reader);
+    } finally {
+      this.releaseReader();
+    }
+  }
   /** Returns the writer and every reader, so that the caller can apply an operation to every connection in the pool. */
   connections() {
-    if (this.closed) {
-      throw new ConnectionPoolError("Connection pool is closed");
-    }
+    this.ensureAvailable();
     return this.writer ? [this.writer, ...this.readers] : [...this.readers];
   }
   get readerCount() {
     return this.readers.length;
   }
   get isReadOnly() {
-    return this.writer === null;
+    return this.options.readOnly === true;
+  }
+  /**
+   * Waits for every read on a reader to settle, then closes every reader and leaves the writer open, so that a
+   * checkpoint on the writer can reach the end of the log. Every acquire fails with `ENCRYPTION_CHANGE_IN_PROGRESS`
+   * until {@link ConnectionPool.reopen} returns.
+   *
+   * @param drainTimeoutMs - How long to wait for the reads to settle.
+   * @throws An `EncryptionError` with `ENCRYPTION_CHANGE_ABORTED` when a read runs past the timeout, which leaves the
+   * readers open and the pool available.
+   */
+  async closeReaders(drainTimeoutMs) {
+    this.isSuspended = true;
+    const readers = this.readers;
+    this.readers = [];
+    if (!await this.readsDrained(drainTimeoutMs)) {
+      this.readers = readers;
+      this.isSuspended = false;
+      throw new EncryptionError(
+        `A read held a reader connection for longer than ${drainTimeoutMs} ms, so the key change stopped before it replaced the file`,
+        "ENCRYPTION_CHANGE_ABORTED"
+      );
+    }
+    await closeAllSilently(readers);
+  }
+  async readsDrained(timeoutMs) {
+    if (this.readsInFlight === 0) return true;
+    let timer;
+    const drained = await Promise.race([
+      new Promise((resolve) => {
+        this.readsSettled = () => resolve(true);
+      }),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+      })
+    ]);
+    clearTimeout(timer);
+    this.readsSettled = null;
+    return drained;
+  }
+  /** Closes the writer after {@link ConnectionPool.closeReaders}. */
+  async closeWriter() {
+    const writer = this.writer;
+    this.writer = null;
+    if (writer) await writer.close();
+  }
+  /** `true` from {@link ConnectionPool.closeReaders} until {@link ConnectionPool.reopen} returns. */
+  get suspended() {
+    return this.isSuspended;
+  }
+  /**
+   * Opens the writer and the readers again, under the key that the pool's keyring holds now, and loads into them
+   * every extension that the database loaded into the connections they replace. When the connections fail to open,
+   * every acquire fails with that error until a later reopen succeeds.
+   */
+  async reopen() {
+    if (this.closed || !this.isSuspended) return;
+    await closeAllSilently([...this.readers, this.writer]);
+    this.readers = [];
+    this.writer = null;
+    let opened;
+    try {
+      opened = await openConnections(this.options);
+    } catch (err) {
+      this.reopenFailure = err;
+      throw err;
+    }
+    this.reopenFailure = null;
+    this.writer = opened.writer;
+    this.readers = opened.readers;
+    this.readerIndex = 0;
+    try {
+      await this.options.prepareReopened?.(opened.writer ? [opened.writer, ...opened.readers] : opened.readers);
+    } finally {
+      this.isSuspended = false;
+    }
   }
   async close() {
     if (this.closed) return;
@@ -322,6 +455,93 @@ function describeBackupCapabilities(capabilities, hasEngine, streams = false) {
   };
 }
 
+// src/core/backup/copy-admission.ts
+var BackupCopyAdmission = class {
+  constructor(runExclusive) {
+    this.runExclusive = runExclusive;
+  }
+  paused = false;
+  running = 0;
+  reopened = Promise.resolve();
+  openAgain = () => {
+  };
+  copiesStopped = null;
+  /**
+   * Runs an operation while no other operation holds the writer, after any key change that stopped copies has ended.
+   *
+   * @param op - The operation to run.
+   */
+  runAdmitted = async (op) => {
+    const admission = { ran: false };
+    while (!admission.ran) {
+      await this.reopened;
+      await this.runExclusive(async () => {
+        if (this.paused) return;
+        admission.ran = true;
+        await op();
+      });
+    }
+  };
+  /**
+   * Returns a connection that calls the pool's writer of the moment on every call, and that counts each copy it
+   * starts until SQLite stops writing that copy, including a copy that the caller stopped waiting for.
+   *
+   * @param acquireWriter - Returns the pool's writer.
+   * @returns The connection for the backup engine to copy through.
+   */
+  writer(acquireWriter) {
+    const track = (copy) => this.track(copy);
+    return {
+      exec: (sql) => acquireWriter().exec(sql),
+      prepare: (sql) => acquireWriter().prepare(sql),
+      transaction: (fn) => acquireWriter().transaction(fn),
+      close: () => acquireWriter().close(),
+      get copyRunsOffCallerThread() {
+        return acquireWriter().copyRunsOffCallerThread;
+      },
+      get copyDatabase() {
+        const writer = acquireWriter();
+        const copy = writer.copyDatabase;
+        if (copy === void 0) return void 0;
+        return (request) => track(copy.call(writer, request));
+      }
+    };
+  }
+  /** Stops new copies from starting, then waits until SQLite has stopped writing every copy that started before. */
+  async pause() {
+    await this.runExclusive(async () => {
+      if (this.paused) return;
+      this.paused = true;
+      this.reopened = new Promise((resolve) => {
+        this.openAgain = resolve;
+      });
+    });
+    while (this.running > 0) {
+      await new Promise((resolve) => {
+        this.copiesStopped = resolve;
+      });
+    }
+  }
+  /** Lets copies start again, on the connections that the pool holds now. */
+  resume() {
+    if (!this.paused) return;
+    this.paused = false;
+    this.openAgain();
+  }
+  track(copy) {
+    this.running++;
+    const stopped = () => {
+      this.running--;
+      if (this.running > 0) return;
+      const copiesStopped = this.copiesStopped;
+      this.copiesStopped = null;
+      copiesStopped?.();
+    };
+    copy.then(stopped, stopped);
+    return copy;
+  }
+};
+
 // src/core/database-backup.ts
 function assertChangeLogCaptureSupported(driver, id, path, walMode, cycle) {
   if (cycle.destinationTimeoutMs !== void 0) assertDeadline(cycle.destinationTimeoutMs, "The destination deadline");
@@ -339,18 +559,23 @@ function assertChangeLogCaptureSupported(driver, id, path, walMode, cycle) {
   }
 }
 var DatabaseBackupController = class {
-  constructor(runExclusive, acquireWriter, driverCapabilities, databaseId, sourcePath, engine) {
+  constructor(runExclusive, acquireWriter, driverCapabilities, databaseId, sourcePath, engine, keyId = () => void 0) {
     this.runExclusive = runExclusive;
     this.acquireWriter = acquireWriter;
     this.driverCapabilities = driverCapabilities;
     this.databaseId = databaseId;
     this.sourcePath = sourcePath;
     this.engine = engine;
+    this.keyId = keyId;
+    this.copies = new BackupCopyAdmission(runExclusive);
+    this.copyWriter = this.copies.writer(acquireWriter);
   }
   cancellers = [];
   cycle = null;
   cycleOptions = null;
   cycleStarted = Promise.resolve();
+  copies;
+  copyWriter;
   require() {
     if (!this.engine) {
       throw new SirannonError(
@@ -379,16 +604,16 @@ var DatabaseBackupController = class {
   async backup(destPath) {
     const engine = this.require();
     const copy = await startCopyWithoutHoldingWriter(
-      this.runExclusive,
-      (onFirstStep) => engine.backup(this.acquireWriter(), destPath, onFirstStep)
+      this.copies.runAdmitted,
+      (onFirstStep) => engine.backup(this.copyWriter, destPath, onFirstStep)
     );
     return { ...copy, databaseId: this.databaseId, sourcePath: this.sourcePath };
   }
   backupTo(options) {
     const engine = this.require();
     return startCopyWithoutHoldingWriter(
-      this.runExclusive,
-      (onFirstStep) => engine.copyToDestination(this.acquireWriter(), {
+      this.copies.runAdmitted,
+      (onFirstStep) => engine.copyToDestination(this.copyWriter, {
         ...options,
         databaseId: this.databaseId,
         sourcePath: this.sourcePath,
@@ -399,11 +624,11 @@ var DatabaseBackupController = class {
   schedule(options) {
     const engine = this.require();
     this.cancellers.push(
-      engine.schedule(this.acquireWriter(), {
+      engine.schedule(this.copyWriter, {
         ...options,
         databaseId: this.databaseId,
         sourcePath: this.sourcePath,
-        runExclusive: this.runExclusive
+        runExclusive: this.copies.runAdmitted
       })
     );
   }
@@ -422,7 +647,8 @@ var DatabaseBackupController = class {
       sourcePath: this.sourcePath,
       runExclusive: this.runExclusive,
       acquireWriter: this.acquireWriter,
-      fullCopy: (copyOptions) => this.backupTo(copyOptions)
+      fullCopy: (copyOptions) => this.backupTo(copyOptions),
+      keyId: this.keyId
     });
     this.cycleStarted = this.cycle.start().catch((err) => {
       const onError = options.onError;
@@ -471,6 +697,46 @@ var DatabaseBackupController = class {
     await this.cycleStarted;
     await cycle.stop();
   }
+  /**
+   * Stops the backup cycle after one last capture, ahead of a key change that replaces the file.
+   *
+   * @returns `true` when a cycle was running, which {@link DatabaseBackupController.resumeCycle} starts again.
+   */
+  async pauseCycle() {
+    if (!this.cycle || !this.cycleOptions) return false;
+    await this.stopCycle();
+    return true;
+  }
+  /**
+   * Stops new backup copies from starting ahead of a key change that replaces the file, and waits until SQLite has
+   * stopped writing every copy that started before, so that no copy reads pages from both files.
+   */
+  pauseCopies() {
+    return this.copies.pause();
+  }
+  /** Lets backup copies start again once a key change has replaced the file or given up. */
+  resumeCopies() {
+    this.copies.resume();
+  }
+  /**
+   * Drops the chain that the paused backup cycle extended, so that the cycle starts a new chain with a full copy
+   * whenever it starts again, including in a process that starts after a crash during the key change.
+   */
+  async forgetPausedChain() {
+    await this.cycle?.forgetChain();
+  }
+  /**
+   * Starts the backup cycle again after a key change, on a new chain whose first piece is a full copy when the file
+   * now holds ciphertext under another key.
+   *
+   * @param options - Whether the cycle starts a new chain.
+   */
+  async resumeCycle(options) {
+    const cycleOptions = this.cycleOptions;
+    if (!cycleOptions) return;
+    if (options.newChain) await this.cycle?.forgetChain();
+    this.startCycle(cycleOptions);
+  }
   cancelAll() {
     for (const cancel of this.cancellers) {
       try {
@@ -669,6 +935,7 @@ var DatabaseCdcController = class {
   stopPolling = null;
   stamper = null;
   epochRequest = null;
+  liveConnectionListeners = /* @__PURE__ */ new Set();
   ensureEpoch() {
     this.epochRequest ??= this.runExclusive(() => ensureCdcEpoch(this.acquireWriter())).catch((err) => {
       this.epochRequest = null;
@@ -693,7 +960,7 @@ var DatabaseCdcController = class {
   async liveConnection() {
     const open = this.openSnapshotConnection;
     if (open === null) {
-      return { conn: this.acquireWriter(), run: this.runExclusive };
+      return { conn: await this.runExclusive(async () => this.acquireWriter()), run: this.runExclusive };
     }
     this.liveConnRequest ??= open().catch((err) => {
       this.liveConnRequest = null;
@@ -708,6 +975,46 @@ var DatabaseCdcController = class {
     await request.then((conn) => conn.close()).catch(() => {
     });
   }
+  /**
+   * Registers a function that the controller calls when a key change closes the live connection to replace the file,
+   * so that each live query plans again on the connection that opens afterwards.
+   *
+   * @param listener - The function to call.
+   * @returns A function that removes the registration.
+   */
+  onLiveConnectionReplaced(listener) {
+    this.liveConnectionListeners.add(listener);
+    return () => {
+      this.liveConnectionListeners.delete(listener);
+    };
+  }
+  /**
+   * Closes the live connection before a key change replaces the file, after telling every live query to plan again
+   * on the connection that the next call opens once the replacement ends. Where live queries read through the
+   * pool's writer, {@link DatabaseCdcController.resumeOnReopenedPool} tells them instead, once that writer exists.
+   */
+  async releaseLiveConnection() {
+    if (this.openSnapshotConnection === null) return;
+    const request = this.liveConnRequest;
+    this.liveConnRequest = null;
+    this.replanLiveQueries();
+    if (request !== null) await request.then((conn) => conn.close()).catch(() => {
+    });
+  }
+  /**
+   * Starts polling again where polling was on, and has every live query that reads through the pool's writer plan
+   * again, after the pool opened its connections to the file that a key change left in place. The key change calls
+   * this while it holds the writer, so no live read reaches the closed writer.
+   */
+  resumeOnReopenedPool() {
+    if (this.openSnapshotConnection === null) this.replanLiveQueries();
+    if (this.stopPolling === null) return;
+    this.stop();
+    this.ensurePolling();
+  }
+  replanLiveQueries() {
+    for (const listener of [...this.liveConnectionListeners]) listener();
+  }
   get subscriptions() {
     return this.subscriptionManager;
   }
@@ -812,7 +1119,7 @@ var DatabaseCdcController = class {
     if (this.stopPolling) return;
     if (!this.tracker || !this.subscriptionManager) return;
     this.stopPolling = startPolling(
-      this.acquireWriter(),
+      () => this.acquireWriter(),
       this.tracker,
       this.subscriptionManager,
       this.pollInterval,
@@ -1526,6 +1833,7 @@ var DatabaseSyncController = class {
     this.cdc = cdc;
   }
   pkResolver = null;
+  cachedOn = null;
   tablesReady = false;
   metaReady = false;
   outboxReader = null;
@@ -1735,24 +2043,31 @@ var DatabaseSyncController = class {
       this.tablesReady = true;
     }
   }
+  resolverOn(writer) {
+    if (this.pkResolver === null || this.cachedOn !== writer) {
+      this.pkResolver = new PkResolver(writer);
+      this.outboxReader = null;
+      this.cachedOn = writer;
+    }
+    return this.pkResolver;
+  }
   async ensureOutboxReader() {
     const writer = this.acquireWriter();
     await this.ensureSyncTables(writer);
     const stamper = await this.cdc.ensureStamper();
-    this.pkResolver ??= new PkResolver(writer);
-    this.outboxReader ??= new BatchReader(writer, stamper.nodeId, CHANGES_TABLE, this.pkResolver, true, true);
+    const pkResolver = this.resolverOn(writer);
+    this.outboxReader ??= new BatchReader(writer, stamper.nodeId, CHANGES_TABLE, pkResolver, true, true);
     return this.outboxReader;
   }
   async ensureApplier() {
     const writer = this.acquireWriter();
     await this.ensureSyncTables(writer);
     const stamper = await this.cdc.ensureStamper();
-    this.pkResolver ??= new PkResolver(writer);
     return new BatchApplier(
       writer,
       stamper.nodeId,
       stamper.hlc,
-      this.pkResolver,
+      this.resolverOn(writer),
       (fromNodeId) => this.lastAppliedSeq(fromNodeId),
       {
         tracker: this.cdc.changeTracker ?? void 0,
@@ -2145,6 +2460,1129 @@ var DatabaseWriteController = class {
   }
 };
 
+// src/core/encryption/key-change-round.ts
+function keyChangeAborted(message, cause) {
+  return new EncryptionError(message, "ENCRYPTION_CHANGE_ABORTED", cause);
+}
+function assertSameWriter(started, current) {
+  if (started !== current) {
+    throw keyChangeAborted(
+      "The database replaced its writer connection during the key change, so writes went unrecorded"
+    );
+  }
+}
+
+// src/core/system-catalog/key-change-capture-tables.ts
+function keyChangeCaptureTables(position, keyColumns) {
+  return {
+    log: `${KEY_CHANGE_CAPTURE_PREFIX}${position}_log`,
+    touched: `${KEY_CHANGE_CAPTURE_PREFIX}${position}_touched`,
+    slots: Array.from({ length: keyColumns }, (_, n) => `k${n}`)
+  };
+}
+function keyChangeCaptureTriggerName(position, kind) {
+  return `${KEY_CHANGE_CAPTURE_PREFIX}${position}_${kind}`;
+}
+async function ensureKeyChangeLogTable(conn, tables) {
+  await conn.exec(`CREATE TEMP TABLE "${escId(tables.log)}" (${tables.slots.join(", ")})`);
+}
+async function selectDistinctKeyChangeLogKeys(conn, tables) {
+  const columns = tables.slots.map(
+    (slot) => `typeof(${slot}) AS t_${slot}, CASE WHEN typeof(${slot}) = 'integer' THEN CAST(${slot} AS TEXT) ELSE ${slot} END AS v_${slot}`
+  ).join(", ");
+  const stmt = await conn.prepare(`SELECT DISTINCT ${columns} FROM temp."${escId(tables.log)}"`);
+  return await stmt.all();
+}
+async function deleteKeyChangeLogKeys(conn, tables) {
+  await conn.exec(`DELETE FROM temp."${escId(tables.log)}"`);
+}
+async function dropKeyChangeLogTable(conn, tables) {
+  await conn.exec(`DROP TABLE IF EXISTS temp."${escId(tables.log)}"`);
+}
+async function ensureEmptyKeyChangeTouchedTable(conn, tables) {
+  await conn.exec(`CREATE TEMP TABLE IF NOT EXISTS "${escId(tables.touched)}" (${tables.slots.join(", ")})`);
+  await conn.exec(`DELETE FROM temp."${escId(tables.touched)}"`);
+}
+function prepareInsertKeyChangeTouchedKey(conn, tables) {
+  const values = tables.slots.map(() => "CASE WHEN ? = 'integer' THEN CAST(? AS INTEGER) ELSE ? END").join(", ");
+  return conn.prepare(`INSERT INTO temp."${escId(tables.touched)}" VALUES (${values})`);
+}
+function selectKeyChangeTouchedKeysSql(tables) {
+  return `SELECT ${tables.slots.join(", ")} FROM temp."${escId(tables.touched)}"`;
+}
+
+// src/core/encryption/key-change-rowids.ts
+var PRIMARY_KEY_INDEX_ORIGIN = "pk";
+function quote(name) {
+  return `"${escId(name)}"`;
+}
+async function readCount(conn, sql, ...params) {
+  const row = await (await conn.prepare(sql)).get(...params);
+  const value = row === void 0 ? void 0 : Object.values(row)[0];
+  const count = typeof value === "bigint" ? Number(value) : value;
+  if (typeof count !== "number" || !Number.isSafeInteger(count)) {
+    throw new EncryptionError(`SQLite returned no count for '${sql}'`, "ENCRYPTION_CHANGE_ABORTED");
+  }
+  return count;
+}
+async function rowidTables(conn) {
+  const rows = await (await conn.prepare(
+    "SELECT name FROM pragma_table_list WHERE schema = 'main' AND type = 'table' AND wr = 0 AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'"
+  )).all();
+  return rows.map((row) => row.name);
+}
+async function rowidIsPrimaryKey(conn, table, columns) {
+  if (!columns.some((column) => Number(column.pk) > 0)) return false;
+  const primaryKeyIndexes = await readCount(
+    conn,
+    "SELECT count(*) FROM pragma_index_list(?, 'main') WHERE origin = ?",
+    table,
+    PRIMARY_KEY_INDEX_ORIGIN
+  );
+  return primaryKeyIndexes === 0;
+}
+function freeRowidAlias(table, columns) {
+  const taken = new Set(columns.map((column) => column.name.toLowerCase()));
+  const name = ROWID_ALIASES.find((candidate) => !taken.has(candidate));
+  if (name === void 0) {
+    throw new EncryptionError(
+      `The table ${table} has columns named rowid, _rowid_, and oid, so the key change cannot address its rows`,
+      "ENCRYPTION_CHANGE_ABORTED"
+    );
+  }
+  return name;
+}
+async function copyWithRowids(conn, table, columns, targetSchema) {
+  const rowid = freeRowidAlias(table, columns);
+  const stored = columns.filter((column) => {
+    const hidden = Number(column.hidden);
+    return hidden !== TABLE_XINFO_HIDDEN.generatedStored && hidden !== TABLE_XINFO_HIDDEN.generatedVirtual;
+  }).map((column) => quote(column.name)).join(", ");
+  const rows = await readCount(conn, `SELECT count(*) FROM main.${quote(table)}`);
+  const changesBefore = await readCount(conn, "SELECT total_changes()");
+  await conn.exec(`DELETE FROM ${targetSchema}.${quote(table)}`);
+  await conn.exec(
+    `INSERT INTO ${targetSchema}.${quote(table)} (${rowid}, ${stored}) SELECT ${rowid}, ${stored} FROM main.${quote(table)}`
+  );
+  const changes = await readCount(conn, "SELECT total_changes()") - changesBefore;
+  if (changes !== rows * 2) {
+    throw new EncryptionError(
+      `Copying the ${rows} rows of the table ${table} with their rowids changed ${changes} rows, so the key change stopped`,
+      "ENCRYPTION_CHANGE_ABORTED"
+    );
+  }
+}
+async function copyRowidsAfterSqlcipherExport(snapshot, targetSchema) {
+  for (const table of await rowidTables(snapshot)) {
+    const columns = await (await snapshot.prepare("SELECT name, pk, hidden FROM pragma_table_xinfo(?, 'main')")).all(table);
+    if (await rowidIsPrimaryKey(snapshot, table, columns)) continue;
+    await copyWithRowids(snapshot, table, columns, targetSchema);
+  }
+}
+
+// src/core/encryption/key-change-copy.ts
+var KEY_CHANGE_SCHEMA = "sirannon_key_change";
+var ROWID_KEEPING_EXPORT = "sirannon_export";
+var SQLCIPHER_EXPORT = "sqlcipher_export";
+var HEX_DIGITS = "0123456789abcdef";
+var QUOTE = 39;
+var LOWER_X = 120;
+function rawKeyspec(key) {
+  const spec = new Uint8Array(key.length * 2 + 3);
+  spec[0] = LOWER_X;
+  spec[1] = QUOTE;
+  for (let i = 0; i < key.length; i++) {
+    spec[2 + i * 2] = HEX_DIGITS.charCodeAt(key[i] >> 4);
+    spec[3 + i * 2] = HEX_DIGITS.charCodeAt(key[i] & 15);
+  }
+  spec[spec.length - 1] = QUOTE;
+  return spec;
+}
+async function attachUnderKey(conn, path, schema, key) {
+  const spec = key === void 0 ? "" : rawKeyspec(key);
+  try {
+    await (await conn.prepare(`ATTACH DATABASE ? AS ${schema} KEY ?`)).run(path, spec);
+  } finally {
+    if (spec instanceof Uint8Array) spec.fill(0);
+  }
+}
+async function readInteger(conn, sql) {
+  const row = await (await conn.prepare(sql)).get();
+  const value = row === void 0 ? void 0 : Object.values(row)[0];
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  throw new EncryptionError(`SQLite returned no integer for '${sql}'`, "ENCRYPTION_CHANGE_ABORTED");
+}
+function readSchemaVersion2(conn) {
+  return readInteger(conn, "PRAGMA main.schema_version");
+}
+async function attachNewFile(snapshot, newPath, key) {
+  await attachUnderKey(snapshot, newPath, KEY_CHANGE_SCHEMA, key);
+  const autoVacuum = await readInteger(snapshot, "PRAGMA main.auto_vacuum");
+  await snapshot.exec(`PRAGMA ${KEY_CHANGE_SCHEMA}.auto_vacuum = ${autoVacuum}`);
+  await snapshot.exec("PRAGMA foreign_keys = OFF");
+}
+async function exportSnapshot(snapshot) {
+  const exportFunction = await (await snapshot.prepare(
+    `SELECT name FROM pragma_function_list WHERE name IN ('${ROWID_KEEPING_EXPORT}', '${SQLCIPHER_EXPORT}') ORDER BY name = '${ROWID_KEEPING_EXPORT}' DESC LIMIT 1`
+  )).get();
+  if (exportFunction?.name !== ROWID_KEEPING_EXPORT && exportFunction?.name !== SQLCIPHER_EXPORT) {
+    throw new EncryptionError(
+      "The SQLite build has no function that copies a database under another key",
+      "ENCRYPTION_UNSUPPORTED"
+    );
+  }
+  await (await snapshot.prepare(`SELECT ${exportFunction.name}('${KEY_CHANGE_SCHEMA}')`)).get();
+  if (exportFunction.name === SQLCIPHER_EXPORT) await copyRowidsAfterSqlcipherExport(snapshot, KEY_CHANGE_SCHEMA);
+  const tables = await (await snapshot.prepare(
+    `SELECT name FROM ${KEY_CHANGE_SCHEMA}.sqlite_schema WHERE type = 'table' AND sql NOT LIKE 'CREATE VIRTUAL%'`
+  )).all();
+  let rowsCopied = 0n;
+  for (const { name } of tables) {
+    rowsCopied += await readInteger(snapshot, `SELECT count(*) FROM ${KEY_CHANGE_SCHEMA}."${escId(name)}"`);
+  }
+  const userVersion = await readInteger(snapshot, "PRAGMA main.user_version");
+  const applicationId = await readInteger(snapshot, "PRAGMA main.application_id");
+  await snapshot.exec(`PRAGMA ${KEY_CHANGE_SCHEMA}.user_version = ${userVersion}`);
+  await snapshot.exec(`PRAGMA ${KEY_CHANGE_SCHEMA}.application_id = ${applicationId}`);
+  return Number(rowsCopied);
+}
+async function detachNewFile(snapshot) {
+  await snapshot.exec(`DETACH DATABASE ${KEY_CHANGE_SCHEMA}`);
+}
+var ORIGINAL_SCHEMA = "sirannon_key_change_original";
+var UNCAPTURED_TABLES = ["sqlite_sequence", "sqlite_stat1", "sqlite_stat4"];
+function attachOriginal(target, path, key) {
+  return attachUnderKey(target, path, ORIGINAL_SCHEMA, key);
+}
+async function detachOriginal(target) {
+  await target.exec(`DETACH DATABASE ${ORIGINAL_SCHEMA}`);
+}
+async function tableExists(conn, schema, name) {
+  const row = await (await conn.prepare(`SELECT 1 FROM ${schema}.sqlite_schema WHERE type = 'table' AND name = ?`)).get(
+    name
+  );
+  return row !== void 0;
+}
+async function copyUncapturedTables(target) {
+  for (const name of UNCAPTURED_TABLES) {
+    const inOriginal = await tableExists(target, ORIGINAL_SCHEMA, name);
+    const inNewFile = await tableExists(target, "main", name);
+    if (inOriginal !== inNewFile) {
+      throw new EncryptionError(
+        `The table ${name} exists in only one of the original and the new file`,
+        "ENCRYPTION_CHANGE_ABORTED"
+      );
+    }
+    if (!inOriginal) continue;
+    await target.exec(`DELETE FROM main.${name}; INSERT INTO main.${name} SELECT * FROM ${ORIGINAL_SCHEMA}.${name}`);
+  }
+}
+
+// src/core/encryption/key-change-trigger-capture.ts
+var SMALL_TRIGGER_ROUND_KEYS = 1024;
+function quoted(name) {
+  return `"${escId(name)}"`;
+}
+async function describeTable(writer, row, position) {
+  const columns = await (await writer.prepare(`PRAGMA main.table_xinfo(${quoted(row.name)})`)).all();
+  const stored = columns.filter((column) => Number(column.hidden) === 0).map((column) => quoted(column.name));
+  const withoutRowid = Number(row.wr) === 1;
+  const alias = withoutRowid ? null : freeRowidAlias(row.name, columns);
+  const keys = alias === null ? columns.filter((column) => Number(column.pk) > 0).sort((a, b) => Number(a.pk) - Number(b.pk)).map((column) => quoted(column.name)) : [alias];
+  return {
+    name: row.name,
+    quoted: quoted(row.name),
+    keys,
+    columns: alias === null ? stored : [alias, ...stored],
+    capture: keyChangeCaptureTables(position, keys.length),
+    triggers: {
+      insert: keyChangeCaptureTriggerName(position, "insert"),
+      update: keyChangeCaptureTriggerName(position, "update"),
+      delete: keyChangeCaptureTriggerName(position, "delete")
+    }
+  };
+}
+async function installCapture(writer, table) {
+  await ensureKeyChangeLogTable(writer, table.capture);
+  await installKeyChangeCaptureTriggers(writer, table.triggers, table.name, table.capture.log, table.keys);
+}
+async function drainTable(writer, table) {
+  const keys = await selectDistinctKeyChangeLogKeys(writer, table.capture);
+  if (keys.length > 0) await deleteKeyChangeLogKeys(writer, table.capture);
+  return keys;
+}
+async function stageKeys(target, table, keys) {
+  await ensureEmptyKeyChangeTouchedTable(target, table.capture);
+  const insert = await prepareInsertKeyChangeTouchedKey(target, table.capture);
+  for (const key of keys) {
+    await insert.run(...table.capture.slots.flatMap((slot) => [key[`t_${slot}`], key[`v_${slot}`], key[`v_${slot}`]]));
+  }
+}
+function touchedRows(table) {
+  return `(${table.keys.join(", ")}) IN (${selectKeyChangeTouchedKeysSql(table.capture)})`;
+}
+async function applyKeys(target, drained) {
+  if (drained.size === 0) return;
+  await target.exec("BEGIN IMMEDIATE");
+  try {
+    for (const [table, keys] of drained) await stageKeys(target, table, keys);
+    for (const table of drained.keys())
+      await target.exec(`DELETE FROM main.${table.quoted} WHERE ${touchedRows(table)}`);
+    for (const table of drained.keys()) {
+      const columns = table.columns.join(", ");
+      await target.exec(
+        `INSERT INTO main.${table.quoted} (${columns}) SELECT ${columns} FROM ${ORIGINAL_SCHEMA}.${table.quoted} WHERE ${touchedRows(table)}`
+      );
+    }
+    await target.exec("COMMIT");
+  } catch (err) {
+    await target.exec("ROLLBACK").catch(() => void 0);
+    if (err instanceof SirannonError) throw err;
+    throw keyChangeAborted("A write committed during the key change could not be applied exactly to the new file", err);
+  }
+}
+async function rowCount(conn, schema, table) {
+  const row = await (await conn.prepare(`SELECT CAST(count(*) AS TEXT) AS n FROM ${schema}.${table}`)).get();
+  return row.n;
+}
+async function copyShadowTables(target, shadows) {
+  for (const shadow of shadows) {
+    await target.exec(
+      `DELETE FROM main.${shadow}; INSERT INTO main.${shadow} SELECT * FROM ${ORIGINAL_SCHEMA}.${shadow}`
+    );
+  }
+}
+async function assertCountsMatch(target, tables) {
+  for (const table of tables) {
+    if (await rowCount(target, "main", table) !== await rowCount(target, ORIGINAL_SCHEMA, table)) {
+      throw keyChangeAborted(
+        `The new file holds a different number of rows in ${table} than the original, because a write removed rows without running its triggers`
+      );
+    }
+  }
+}
+async function startTriggerCapture(writer) {
+  const listed = await (await writer.prepare(
+    "SELECT name, type, wr FROM pragma_table_list WHERE schema = 'main' AND type IN ('table', 'shadow') AND name NOT LIKE 'sqlite_%'"
+  )).all();
+  const regular = listed.filter((row) => row.type === "table");
+  const shadows = listed.filter((row) => row.type === "shadow").map((row) => quoted(row.name));
+  const tables = [];
+  for (const row of regular) tables.push(await describeTable(writer, row, tables.length));
+  const stop = async () => {
+    for (const table of tables) {
+      await dropKeyChangeCaptureTriggers(writer, table.triggers);
+      await dropKeyChangeLogTable(writer, table.capture);
+    }
+  };
+  try {
+    for (const table of tables) await installCapture(writer, table);
+  } catch (err) {
+    await stop().catch(() => void 0);
+    throw err;
+  }
+  return {
+    async drain(current) {
+      assertSameWriter(writer, current);
+      const drained = /* @__PURE__ */ new Map();
+      let total = 0;
+      for (const table of tables) {
+        const keys = await drainTable(writer, table);
+        if (keys.length === 0) continue;
+        drained.set(table, keys);
+        total += keys.length;
+      }
+      return { small: total <= SMALL_TRIGGER_ROUND_KEYS, apply: (target) => applyKeys(target, drained) };
+    },
+    async finish(target) {
+      await copyShadowTables(target, shadows);
+      await assertCountsMatch(target, [...tables.map((table) => table.quoted), ...shadows]);
+    },
+    stop
+  };
+}
+
+// src/core/encryption/key-change-capture.ts
+var SMALL_SESSION_ROUND_BYTES = 256 * 1024;
+async function applySession(target, changes) {
+  if (changes.byteLength === 0) return;
+  const apply = target.applyCapturedChanges;
+  if (!apply) {
+    throw new EncryptionError(
+      "The driver opens connections that cannot apply recorded changes, so a key change cannot run on it",
+      "ENCRYPTION_UNSUPPORTED"
+    );
+  }
+  try {
+    await apply.call(target, changes);
+  } catch (err) {
+    if (err instanceof SirannonError) throw err;
+    throw keyChangeAborted("A write committed during the key change could not be applied exactly to the new file", err);
+  }
+}
+function startSessionCapture(writer, take, stop) {
+  return {
+    async drain(current) {
+      assertSameWriter(writer, current);
+      const changes = await take();
+      return {
+        small: changes.byteLength <= SMALL_SESSION_ROUND_BYTES,
+        apply: (target) => applySession(target, changes)
+      };
+    },
+    finish: async () => void 0,
+    stop
+  };
+}
+async function startKeyChangeCapture(writer) {
+  const { startChangeCapture, takeCapturedChanges, stopChangeCapture } = writer;
+  if (!startChangeCapture || !takeCapturedChanges || !stopChangeCapture) return startTriggerCapture(writer);
+  await startChangeCapture.call(writer);
+  return startSessionCapture(
+    writer,
+    () => takeCapturedChanges.call(writer),
+    () => stopChangeCapture.call(writer)
+  );
+}
+
+// src/core/encryption/key-change-files.ts
+var FILE_IDENTITY_BYTES = 16;
+var NEW_FILE_SUFFIX = ".sirannon-key-change";
+var MARKER_SUFFIX = ".sirannon-key-change-marker";
+var SIDE_FILE_SUFFIXES = ["", "-journal", "-wal", "-shm"];
+function keyChangeFilePath(path) {
+  return `${path}${NEW_FILE_SUFFIX}`;
+}
+function keyChangeMarkerPath(path) {
+  return `${path}${MARKER_SUFFIX}`;
+}
+async function removeKeyChangeFile(files, path) {
+  const newFile = keyChangeFilePath(path);
+  for (const suffix of SIDE_FILE_SUFFIXES) await files.remove(`${newFile}${suffix}`);
+}
+function sameBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+// src/core/encryption/key-change-marker.ts
+var MARKER_TABLE = "key_change_marker";
+var MARKER_JOURNAL_SUFFIX = "-journal";
+var HEX_DIGITS2 = "0123456789abcdef";
+var HEX_BYTE = /^[0-9a-f]{2}$/;
+function hexOf(bytes) {
+  let hex = "";
+  for (const byte of bytes) hex += HEX_DIGITS2[byte >> 4] + HEX_DIGITS2[byte & 15];
+  return hex;
+}
+function bytesOfHex(hex) {
+  if (hex.length % 2 !== 0) return null;
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    const pair = hex.slice(i * 2, i * 2 + 2);
+    if (!HEX_BYTE.test(pair)) return null;
+    bytes[i] = Number.parseInt(pair, 16);
+  }
+  return bytes;
+}
+function openMarker(driver, path, readonly) {
+  return driver.open(keyChangeMarkerPath(path), { readonly, walMode: false, synchronous: "full" });
+}
+async function bumpWrites(conn, setBegun) {
+  const begun = setBegun ? ", replacement_begun = 1" : "";
+  await conn.exec(`UPDATE ${MARKER_TABLE} SET writes = writes + 1${begun}`);
+}
+async function removeKeyChangeMarker(files, path) {
+  const markerPath = keyChangeMarkerPath(path);
+  await files.remove(markerPath);
+  await files.remove(`${markerPath}${MARKER_JOURNAL_SUFFIX}`);
+}
+async function createKeyChangeMarker(driver, path, identity) {
+  const conn = await openMarker(driver, path, false);
+  try {
+    await conn.exec("PRAGMA journal_mode = DELETE");
+    await conn.exec("PRAGMA synchronous = FULL");
+    await conn.exec(
+      `BEGIN IMMEDIATE; CREATE TABLE ${MARKER_TABLE} (identity TEXT NOT NULL, replacement_begun INTEGER NOT NULL, writes INTEGER NOT NULL); INSERT INTO ${MARKER_TABLE} VALUES ('${hexOf(identity)}', 0, 1); COMMIT`
+    );
+  } catch (err) {
+    await conn.close().catch(() => void 0);
+    throw err;
+  }
+  return {
+    recordReplacementBegun: () => bumpWrites(conn, true),
+    flushDirectory: () => bumpWrites(conn, false),
+    close: () => conn.close()
+  };
+}
+async function readKeyChangeMarker(driver, path, readonly) {
+  let conn;
+  try {
+    conn = await openMarker(driver, path, readonly);
+  } catch {
+    return null;
+  }
+  try {
+    const row = await (await conn.prepare(`SELECT identity, replacement_begun FROM ${MARKER_TABLE} LIMIT 1`)).get();
+    if (row === void 0 || typeof row.identity !== "string") return null;
+    const identity = bytesOfHex(row.identity);
+    if (identity === null) return null;
+    return { identity, replacementBegun: Number(row.replacement_begun) === 1 };
+  } catch {
+    return null;
+  } finally {
+    await conn.close().catch(() => void 0);
+  }
+}
+async function flushDirectoryThroughMarker(driver, path) {
+  const conn = await openMarker(driver, path, false);
+  try {
+    await bumpWrites(conn, false);
+  } finally {
+    await conn.close();
+  }
+}
+
+// src/core/encryption/key-metadata.ts
+var ENCRYPTION_KEY_ID_META_KEY = "encryption_key_id";
+var ENCRYPTION_CHANGED_AT_META_KEY = "encryption_changed_at";
+async function readKeyMetadata(conn) {
+  if (!await selectTableExists(conn, META_TABLE)) return {};
+  const keyId = await selectMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY);
+  const changedAt = Number(await selectMetaValue(conn, ENCRYPTION_CHANGED_AT_META_KEY));
+  return {
+    ...keyId === null ? {} : { keyId },
+    ...Number.isSafeInteger(changedAt) && changedAt > 0 ? { changedAt } : {}
+  };
+}
+async function writeKeyId(conn, keyId) {
+  const stored = await selectTableExists(conn, META_TABLE) ? await selectMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY) : null;
+  if ((stored ?? void 0) === keyId) return;
+  if (keyId === void 0) {
+    await deleteMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY);
+    return;
+  }
+  await ensureMetaTable(conn);
+  await upsertMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY, keyId);
+}
+async function writeKeyChange(conn, keyId, changedAt) {
+  await ensureMetaTable(conn);
+  await upsertMetaValue(conn, ENCRYPTION_CHANGED_AT_META_KEY, String(changedAt));
+  if (keyId === void 0) await deleteMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY);
+  else await upsertMetaValue(conn, ENCRYPTION_KEY_ID_META_KEY, keyId);
+}
+
+// src/core/encryption/key-change-job.ts
+var MAX_CATCH_UP_ROUNDS = 16;
+var READ_CONNECTION_DRAIN_TIMEOUT_MS = 3e4;
+async function reopenPool(pool, cdc) {
+  await pool.reopen();
+  cdc.resumeOnReopenedPool();
+}
+async function assertSchemaUnchanged(writer, expected) {
+  if (await readSchemaVersion2(writer) !== expected) {
+    throw keyChangeAborted(
+      "The schema changed while the key change copied the database, so the new file would miss that change"
+    );
+  }
+}
+async function checkpointTruncate(writer) {
+  const row = await (await writer.prepare("PRAGMA wal_checkpoint(TRUNCATE)")).get();
+  const busy = row === void 0 ? 0 : Number(Object.values(row)[0]);
+  if (busy !== 0) {
+    throw keyChangeAborted("Another connection held the write-ahead log open, so the key change could not empty it");
+  }
+}
+function requireFiles(driver, path) {
+  if (driver.files === void 0 || path === ":memory:" || path === "" || path.startsWith("file:")) {
+    throw new EncryptionError(
+      "A key change needs a database file on a driver that supplies file operations",
+      "ENCRYPTION_UNSUPPORTED"
+    );
+  }
+  return driver.files;
+}
+var KeyChangeRun = class {
+  /**
+   * Checks that the database can change its key, without touching any file.
+   *
+   * @param deps - The parts of the open database.
+   * @param target - The key function of the target key, or `null` for a plaintext file.
+   * @param progress - Receives the progress, and reports a close of the database.
+   * @throws An `EncryptionError` with `ENCRYPTION_UNSUPPORTED` when the driver or the path cannot hold a key change.
+   */
+  constructor(deps, target, progress) {
+    this.deps = deps;
+    this.target = target;
+    this.progress = progress;
+    this.files = requireFiles(deps.driver, deps.path);
+    this.newPath = keyChangeFilePath(deps.path);
+    this.targetRing = new EncryptionKeyring(target);
+  }
+  files;
+  newPath;
+  targetRing;
+  snapshot = null;
+  targetConn = null;
+  capture = null;
+  marker = null;
+  triggers = [];
+  schemaVersion = 0n;
+  rounds = 0;
+  connectionsClosed = false;
+  cyclePaused = false;
+  copiesPaused = false;
+  chainForgotten = false;
+  replaced = false;
+  stranded = false;
+  nativePath = "";
+  /**
+   * Runs the key change to the end.
+   *
+   * @returns `null` when every step succeeds, or the failure that came after the new file was in place, which leaves
+   * the change done and the file under the target key.
+   * @throws An `EncryptionError` with `ENCRYPTION_CHANGE_ABORTED` when the change stops, which leaves the database
+   * under the key that it had, or the error of the target key function.
+   */
+  async run() {
+    try {
+      await this.copySnapshot();
+      await this.markNewFile();
+      await this.catchUp();
+      await this.replaceFile();
+      return null;
+    } catch (err) {
+      await this.cleanUp();
+      if (this.replaced) return { cause: err };
+      if (err instanceof SirannonError) throw err;
+      if (this.stranded) {
+        throw keyChangeAborted(
+          "The key change stopped while it moved the new file into place, so the database stays closed until the next open finishes the move",
+          err
+        );
+      }
+      throw keyChangeAborted("The key change stopped, and the database keeps the key that it had", err);
+    }
+  }
+  checkOpen() {
+    if (this.progress.cancelled) throw keyChangeAborted("The database closed while the key change ran");
+  }
+  requireCapture() {
+    if (this.capture === null)
+      throw keyChangeAborted("The key change lost its record of the writes made since the copy");
+    return this.capture;
+  }
+  requireTarget() {
+    if (this.targetConn === null) throw keyChangeAborted("The key change lost its connection to the new file");
+    return this.targetConn;
+  }
+  requireMarker() {
+    if (this.marker === null) throw keyChangeAborted("The key change lost its marker");
+    return this.marker;
+  }
+  async copySnapshot() {
+    const { pool, writerLock, fileConnections, path } = this.deps;
+    await removeKeyChangeFile(this.files, path);
+    await removeKeyChangeMarker(this.files, path);
+    const snapshot = await fileConnections.open({ walMode: false, walAutoCheckpoint: 0 });
+    this.snapshot = snapshot;
+    this.nativePath = await readMainDatabasePath(snapshot);
+    if (this.nativePath === "") throw keyChangeAborted("SQLite returned no path for the database file");
+    const targetKey = this.target === null ? void 0 : await resolveEncryptionKey(this.target);
+    try {
+      await attachNewFile(snapshot, keyChangeFilePath(this.nativePath), targetKey?.bytes);
+    } finally {
+      wipeEncryptionKey(targetKey);
+    }
+    this.schemaVersion = await writerLock.run(async () => {
+      this.capture = await startKeyChangeCapture(pool.acquireWriter());
+      await snapshot.exec("BEGIN");
+      await (await snapshot.prepare("SELECT count(*) FROM sqlite_schema")).get();
+      return readSchemaVersion2(snapshot);
+    });
+    const rowsCopied = await exportSnapshot(snapshot);
+    await snapshot.exec("COMMIT");
+    await detachNewFile(snapshot);
+    this.snapshot = null;
+    await snapshot.close();
+    this.progress.update({ rowsCopied });
+    this.checkOpen();
+  }
+  async markNewFile() {
+    const { driver, path, keyring } = this.deps;
+    const identity = await this.files.readStart(this.newPath, FILE_IDENTITY_BYTES);
+    if (identity === null || identity.length !== FILE_IDENTITY_BYTES) {
+      throw keyChangeAborted("The key change wrote a new file too short to hold a database");
+    }
+    this.marker = await createKeyChangeMarker(driver, path, identity);
+    this.targetConn = await this.targetRing.openWith(
+      (keyed) => driver.open(this.newPath, { walMode: false, synchronous: "full", ...keyed })
+    );
+    await this.targetConn.exec("PRAGMA foreign_keys = OFF");
+    this.triggers = await dropMainSchemaTriggers(this.targetConn);
+    const source = keyring.keySource;
+    const originalKey = source === null ? void 0 : await resolveEncryptionKey(source);
+    try {
+      await attachOriginal(this.targetConn, this.nativePath, originalKey?.bytes);
+    } finally {
+      wipeEncryptionKey(originalKey);
+    }
+  }
+  async catchUp() {
+    const { pool, writerLock } = this.deps;
+    this.progress.update({ state: "catching-up", rounds: 0 });
+    for (let round = 0; round < MAX_CATCH_UP_ROUNDS; round++) {
+      this.checkOpen();
+      const drained = await writerLock.run(async () => {
+        const writer = pool.acquireWriter();
+        await assertSchemaUnchanged(writer, this.schemaVersion);
+        return this.requireCapture().drain(writer);
+      });
+      await drained.apply(this.requireTarget());
+      this.rounds++;
+      this.progress.update({ rounds: this.rounds });
+      if (drained.small) return;
+    }
+  }
+  async replaceFile() {
+    const { backups, fileConnections, writerLock } = this.deps;
+    this.checkOpen();
+    this.progress.update({ state: "swapping" });
+    this.cyclePaused = await backups.pauseCycle();
+    this.copiesPaused = true;
+    await backups.pauseCopies();
+    this.connectionsClosed = true;
+    await fileConnections.closeForReplacement(READ_CONNECTION_DRAIN_TIMEOUT_MS);
+    this.checkOpen();
+    await writerLock.run(() => this.finishWithWritesHeld());
+    this.connectionsClosed = false;
+    await fileConnections.reopenAfterReplacement();
+    this.copiesPaused = false;
+    backups.resumeCopies();
+    if (this.cyclePaused) await backups.resumeCycle({ newChain: true });
+  }
+  async finishNewFile(writer) {
+    const target = this.requireTarget();
+    const capture = this.requireCapture();
+    await assertSchemaUnchanged(writer, this.schemaVersion);
+    await (await capture.drain(writer)).apply(target);
+    this.rounds++;
+    this.progress.update({ rounds: this.rounds });
+    await capture.finish(target);
+    await copyUncapturedTables(target);
+    await createMainSchemaTriggers(target, this.triggers);
+    await detachOriginal(target);
+    await writeKeyChange(target, this.targetRing.keyId, Date.now());
+    this.targetConn = null;
+    await target.close();
+    await capture.stop();
+    this.capture = null;
+  }
+  async finishWithWritesHeld() {
+    const { pool, path, keyring, cdc } = this.deps;
+    const writer = pool.acquireWriter();
+    await this.finishNewFile(writer);
+    const marker = this.requireMarker();
+    await pool.closeReaders(READ_CONNECTION_DRAIN_TIMEOUT_MS);
+    if (this.cyclePaused) {
+      await this.deps.backups.forgetPausedChain();
+      this.chainForgotten = true;
+    }
+    await marker.recordReplacementBegun();
+    try {
+      await checkpointTruncate(writer);
+      await pool.closeWriter();
+      await this.files.remove(`${path}-wal`);
+      await this.files.remove(`${path}-shm`);
+      await this.files.rename(this.newPath, path);
+      this.replaced = true;
+      await marker.flushDirectory();
+    } catch (err) {
+      await this.recoverFromFailedSwap();
+      throw err;
+    }
+    keyring.replace(this.target);
+    await reopenPool(pool, cdc);
+    this.marker = null;
+    await marker.close();
+    await removeKeyChangeMarker(this.files, path);
+  }
+  async recoverFromFailedSwap() {
+    const { pool, path, keyring, cdc } = this.deps;
+    if (!this.replaced && await this.files.readStart(path, 1) === null) {
+      try {
+        await this.files.rename(this.newPath, path);
+        this.replaced = true;
+      } catch {
+        this.stranded = true;
+        return;
+      }
+    }
+    if (this.replaced) keyring.replace(this.target);
+    await reopenPool(pool, cdc);
+  }
+  async cleanUp() {
+    const { pool, writerLock, fileConnections, backups, keyring, path, cdc } = this.deps;
+    const snapshot = this.snapshot;
+    if (snapshot !== null) {
+      await snapshot.exec("ROLLBACK").catch(() => void 0);
+      await detachNewFile(snapshot).catch(() => void 0);
+      await snapshot.close().catch(() => void 0);
+    }
+    await this.targetConn?.close().catch(() => void 0);
+    const capture = this.capture;
+    if (capture !== null) await writerLock.run(() => capture.stop()).catch(() => void 0);
+    await this.marker?.close().catch(() => void 0);
+    this.marker = null;
+    if (this.stranded) {
+      if (this.copiesPaused) backups.resumeCopies();
+      return;
+    }
+    if (this.replaced) keyring.replace(this.target);
+    await writerLock.run(async () => {
+      if (!pool.suspended) return;
+      await reopenPool(pool, cdc);
+    }).catch(() => void 0);
+    if (!this.replaced) {
+      await removeKeyChangeFile(this.files, path).catch(() => void 0);
+      await removeKeyChangeMarker(this.files, path).catch(() => void 0);
+    }
+    if (this.connectionsClosed) await fileConnections.reopenAfterReplacement();
+    if (this.copiesPaused) backups.resumeCopies();
+    if (this.cyclePaused) {
+      await backups.resumeCycle({ newChain: this.replaced || this.chainForgotten }).catch(() => void 0);
+    }
+  }
+};
+
+// src/core/encryption/controller.ts
+var AEGIS_CIPHER_NAME = "aegis";
+var AEGIS_256_ALGORITHM_NAME = "aegis-256";
+function changeInProgress() {
+  return new EncryptionError(
+    "A key change is already running on this database; wait for it to end before you start another",
+    "ENCRYPTION_CHANGE_IN_PROGRESS"
+  );
+}
+function engineDuringChange() {
+  return new EncryptionError(
+    "A key change is replacing the file of this database, so a replication engine would stay on the replaced file; start the engine once the change ends",
+    "ENCRYPTION_CHANGE_IN_PROGRESS"
+  );
+}
+function describeReopenFailure(err) {
+  if (err instanceof SirannonError) return { code: err.code, message: err.message };
+  return {
+    code: "DATABASE_OPEN_FAILED",
+    message: "The database could not open its connections again after the key change put the new file in place; close it and open it with the new key"
+  };
+}
+function invalidChange() {
+  return new EncryptionError(
+    "changeEncryption takes { key }, where key is a function that returns 32 key bytes, or null to remove encryption",
+    "INVALID_ENCRYPTION_KEY"
+  );
+}
+async function readText(conn, sql) {
+  const row = await (await conn.prepare(sql)).get();
+  const value = row === void 0 ? void 0 : Object.values(row)[0];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+async function readCipher(conn) {
+  const hasEngineVersion = await readText(
+    conn,
+    "SELECT 'present' FROM pragma_function_list WHERE name = 'sqlite3mc_version'"
+  );
+  if (hasEngineVersion === void 0) {
+    const sqlcipherVersion = await readText(conn, "PRAGMA cipher_version");
+    return sqlcipherVersion === void 0 ? {} : { cipher: "sqlcipher-4", cipherVersion: sqlcipherVersion };
+  }
+  const engineVersion = await readText(conn, "SELECT sqlite3mc_version()");
+  const cipher = await readText(conn, "PRAGMA cipher");
+  const algorithm = await readText(conn, "PRAGMA algorithm");
+  return {
+    ...cipher === AEGIS_CIPHER_NAME && algorithm === AEGIS_256_ALGORITHM_NAME ? { cipher: "aegis-256" } : {},
+    ...engineVersion === void 0 ? {} : { cipherVersion: engineVersion }
+  };
+}
+var DatabaseEncryptionController = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  change = { state: "idle" };
+  running = null;
+  closing = false;
+  described = null;
+  /** `true` while the database file opens under a key. */
+  get encrypted() {
+    return this.deps.keyring.encrypted;
+  }
+  /**
+   * Returns whether the file is encrypted, the scheme that it is encrypted under, the engine's version, the stored
+   * key identifier and change time, and the current or last key change.
+   *
+   * @returns The status.
+   */
+  async status() {
+    const encrypted = this.deps.keyring.encrypted;
+    if (this.described === null && !this.deps.pool.suspended) this.described = await this.describeFile(encrypted);
+    const described = this.described ?? {};
+    return {
+      encrypted,
+      ...encrypted && described.cipher !== void 0 ? { cipher: described.cipher } : {},
+      ...encrypted && described.cipherVersion !== void 0 ? { cipherVersion: described.cipherVersion } : {},
+      ...encrypted && described.keyId !== void 0 ? { keyId: described.keyId } : {},
+      ...described.changedAt === void 0 ? {} : { changedAt: described.changedAt },
+      change: { ...this.change }
+    };
+  }
+  /**
+   * Encrypts the database, changes its key, or removes encryption, and resolves once the change ends.
+   *
+   * @param change - The target key function, or `null` for a plaintext file.
+   * @returns The status after the change.
+   * @throws `READ_ONLY` on a read-only database, `ENCRYPTION_CHANGE_IN_PROGRESS` while another change runs,
+   * `REPLICATION_ACTIVE` while a replication engine writes to the database, and the error that stopped the change.
+   */
+  async changeKey(change) {
+    if (this.deps.readOnly) throw new ReadOnlyError(this.deps.databaseId);
+    const target = this.targetOf(change);
+    if (this.running !== null) throw changeInProgress();
+    if (!this.deps.driver.capabilities.encryption) {
+      throw new EncryptionError(
+        "The driver that this Sirannon uses cannot encrypt a database, so it cannot change its key",
+        "ENCRYPTION_UNSUPPORTED"
+      );
+    }
+    const endReplacement = this.deps.replicationEngines.beginReplacement("key change", engineDuringChange);
+    try {
+      return await this.runChange(target);
+    } finally {
+      endReplacement();
+    }
+  }
+  async runChange(target) {
+    const isClosing = () => this.closing;
+    const progress = {
+      update: (fields) => {
+        this.change = { ...this.change, ...fields };
+      },
+      get cancelled() {
+        return isClosing();
+      }
+    };
+    const run = new KeyChangeRun(this.deps, target, progress);
+    this.change = { state: "copying", target: target === null ? "plaintext" : "encrypted", startedAt: Date.now() };
+    const outcome = run.run().then(
+      (reopenFailure) => this.finished(target, reopenFailure),
+      (err) => this.failed(err)
+    );
+    this.running = outcome.then(() => void 0);
+    try {
+      const failure = await outcome;
+      if (failure !== null) throw failure;
+    } finally {
+      this.running = null;
+    }
+    return this.status();
+  }
+  /** Stops a running key change at its next step, and waits for it to leave the database as it was. */
+  async cancel() {
+    this.closing = true;
+    await this.running;
+  }
+  targetOf(change) {
+    if (typeof change !== "object" || change === null || !("key" in change)) throw invalidChange();
+    if (change.key === null) return null;
+    if (typeof change.key !== "function") throw invalidChange();
+    return change.key;
+  }
+  finished(target, reopenFailure) {
+    this.change = {
+      ...this.change,
+      state: "done",
+      finishedAt: Date.now(),
+      ...reopenFailure === null ? {} : { reopenError: describeReopenFailure(reopenFailure.cause) }
+    };
+    this.described = null;
+    this.deps.onKeyChanged?.(target);
+    return null;
+  }
+  failed(err) {
+    const code = err instanceof SirannonError ? err.code : "ENCRYPTION_CHANGE_ABORTED";
+    const message = err instanceof Error ? err.message : "The key change stopped";
+    this.change = { ...this.change, state: "failed", finishedAt: Date.now(), error: { code, message } };
+    return err;
+  }
+  async describeFile(encrypted) {
+    const { pool, writerLock } = this.deps;
+    const read = async (conn) => {
+      const metadata = await readKeyMetadata(conn);
+      return { ...metadata, ...encrypted ? await readCipher(conn) : {} };
+    };
+    if (pool.readerCount > 0) return pool.withReader(read);
+    return writerLock.run(() => read(pool.acquireReader()));
+  }
+};
+
+// src/core/encryption/key-change-recovery.ts
+function missingDatabaseFile(path) {
+  return new SirannonError(
+    `The database file ${path} is missing, and the marker of an interrupted key change does not show that the new file can take its place, so Sirannon leaves every file as it is`,
+    "DATABASE_OPEN_FAILED"
+  );
+}
+async function recoverInterruptedKeyChange(driver, path, readOnly) {
+  const files = driver.files;
+  if (files === void 0 || path === ":memory:" || path === "" || path.startsWith("file:")) return null;
+  let markerStart;
+  try {
+    markerStart = await files.readStart(keyChangeMarkerPath(path), FILE_IDENTITY_BYTES);
+  } catch (err) {
+    if (err instanceof EncryptionError && err.code === "ENCRYPTION_UNSUPPORTED") return null;
+    throw err;
+  }
+  if (markerStart === null) {
+    if (!readOnly) await removeKeyChangeFile(files, path);
+    return null;
+  }
+  const marker = await readKeyChangeMarker(driver, path, readOnly);
+  const current = await files.readStart(path, FILE_IDENTITY_BYTES);
+  if (current === null) {
+    const newFile = await files.readStart(keyChangeFilePath(path), FILE_IDENTITY_BYTES);
+    const movable = marker?.replacementBegun === true && newFile !== null && sameBytes(marker.identity, newFile);
+    if (!movable) throw missingDatabaseFile(path);
+    if (readOnly) return "key-after-change";
+    await files.rename(keyChangeFilePath(path), path);
+    await flushDirectoryThroughMarker(driver, path);
+    await removeKeyChangeMarker(files, path);
+    return "key-after-change";
+  }
+  const replaced = marker !== null && current.length === FILE_IDENTITY_BYTES && sameBytes(marker.identity, current);
+  if (readOnly) return replaced ? "key-after-change" : "key-before-change";
+  await removeKeyChangeFile(files, path);
+  await removeKeyChangeMarker(files, path);
+  return replaced ? "key-after-change" : "key-before-change";
+}
+var KEY_ERROR_CODES = /* @__PURE__ */ new Set(["ENCRYPTION_KEY_REJECTED", "ENCRYPTION_KEY_MISSING", "DATABASE_NOT_ENCRYPTED"]);
+function explainKeyAfterInterruptedChange(err, interrupted) {
+  if (!(err instanceof EncryptionError) || !KEY_ERROR_CODES.has(err.code)) return err;
+  const needed = interrupted === "key-after-change" ? "the key from after the change, or no key where the change removed encryption, because the new file replaced the original" : "the key from before the change, or no key where the file was plaintext, because the change stopped before the new file replaced the original";
+  return new EncryptionError(
+    `A key change on this database stopped part way, and the file needs ${needed}`,
+    "ENCRYPTION_KEY_REJECTED",
+    err
+  );
+}
+
+// src/core/file-connections.ts
+var DatabaseFileConnections = class {
+  constructor(driver, path, keyring, extensions) {
+    this.driver = driver;
+    this.path = path;
+    this.keyring = keyring;
+    this.extensions = extensions;
+  }
+  active = 0;
+  holders = /* @__PURE__ */ new Set();
+  replacement = null;
+  drained = null;
+  /**
+   * Opens a connection to the database file, after any file replacement under way has ended.
+   *
+   * @param options - The open settings, without a key, which this method adds.
+   * @returns The connection, which the caller closes.
+   */
+  async open(options) {
+    while (this.replacement !== null) await this.replacement.done;
+    this.active++;
+    let connection;
+    try {
+      connection = await this.extensions.open(
+        () => this.keyring.openWith((keyed) => this.driver.open(this.path, { ...options, ...keyed }))
+      );
+    } catch (err) {
+      this.settle();
+      throw err;
+    }
+    const close = connection.close;
+    let settled = false;
+    connection.close = async () => {
+      if (settled) return close.call(connection);
+      settled = true;
+      try {
+        await close.call(connection);
+      } finally {
+        this.settle();
+      }
+    };
+    return connection;
+  }
+  settle() {
+    this.active--;
+    if (this.active === 0) this.drained?.();
+  }
+  /**
+   * Registers a part of the database that keeps a connection open between calls.
+   *
+   * @param holder - The release and reopen calls of that part.
+   * @returns A function that removes the registration.
+   */
+  hold(holder) {
+    this.holders.add(holder);
+    return () => {
+      this.holders.delete(holder);
+    };
+  }
+  /**
+   * Makes later opens wait, has every holder close its connection, and waits until every other connection to the
+   * file has closed.
+   *
+   * @param timeoutMs - How long to wait for the connections that a call holds for the duration of one read.
+   * @throws An `EncryptionError` with `ENCRYPTION_CHANGE_ABORTED` when a connection stays open past the deadline.
+   */
+  async closeForReplacement(timeoutMs) {
+    let finish = () => {
+    };
+    const done = new Promise((resolve) => {
+      finish = resolve;
+    });
+    this.replacement = { done, finish };
+    for (const holder of [...this.holders]) {
+      await holder.release().catch(() => void 0);
+    }
+    if (this.active === 0) return;
+    let timer;
+    const closed = await Promise.race([
+      new Promise((resolve) => {
+        this.drained = () => resolve(true);
+      }),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+      })
+    ]);
+    clearTimeout(timer);
+    this.drained = null;
+    if (!closed) {
+      throw new EncryptionError(
+        `A read held a connection to the database file for longer than ${timeoutMs} ms, so the key change stopped before it replaced the file`,
+        "ENCRYPTION_CHANGE_ABORTED"
+      );
+    }
+  }
+  /** Lets opens proceed again, and has every holder open its connection to the file that is now in place. */
+  async reopenAfterReplacement() {
+    const replacement = this.replacement;
+    this.replacement = null;
+    replacement?.finish();
+    for (const holder of [...this.holders]) {
+      await holder.reopen().catch(() => void 0);
+    }
+  }
+};
+
 // src/core/hooks/registry.ts
 var HOOK_CONFIG_MAP = {
   onBeforeQuery: "beforeQuery",
@@ -2342,6 +3780,12 @@ var LoadedExtensions = class {
       if (!this.resolvedPaths.includes(resolved)) this.resolvedPaths.push(resolved);
     });
   }
+  /** Loads every recorded extension into connections that replaced the ones that the database loaded them into. */
+  reload(connections) {
+    return this.runInTurn(async () => {
+      for (const connection of connections) await this.loadRecorded(connection);
+    });
+  }
   /**
    * Opens a connection, loads every recorded extension into it, and returns a
    * wrapper that forwards each call to it. Closing the wrapper stops the
@@ -2368,6 +3812,63 @@ var LoadedExtensions = class {
   }
 };
 
+// src/core/replication-engines.ts
+var RegisteredReplicationEngines = class {
+  constructor(databaseId) {
+    this.databaseId = databaseId;
+  }
+  count = 0;
+  replacements = /* @__PURE__ */ new Set();
+  /**
+   * Records one running engine, and returns the call that removes the record, which does nothing after its first
+   * call.
+   *
+   * @returns The call that removes the record.
+   * @throws The error of a file replacement under way, which would leave the engine on the replaced file.
+   */
+  register() {
+    const replacement = this.replacements.values().next();
+    if (replacement.done !== true) throw replacement.value();
+    this.count++;
+    let registered = true;
+    return () => {
+      if (!registered) return;
+      registered = false;
+      this.count--;
+    };
+  }
+  /**
+   * Throws when an engine runs, because the engine's writer connection would stay on the replaced file.
+   *
+   * @param operation - The operation that would replace the file, as the error message states it.
+   * @throws A `ReplicationError` with `REPLICATION_ACTIVE` while an engine runs.
+   */
+  assertNone(operation) {
+    if (this.count === 0) return;
+    throw new ReplicationError(
+      `A replication engine writes to database '${this.databaseId}' through a separate writer connection, and a ${operation} would leave that connection on the replaced file. Stop the engine, run the ${operation}, and then start the engine again.`,
+      "REPLICATION_ACTIVE"
+    );
+  }
+  /**
+   * Refuses the operation while an engine runs, and otherwise refuses every engine that starts before the returned
+   * call ends the replacement.
+   *
+   * @param operation - The operation that replaces the file, as the error message states it.
+   * @param refuseEngine - Builds the error that an engine which starts during the replacement receives.
+   * @returns The call that ends the replacement.
+   * @throws A `ReplicationError` with `REPLICATION_ACTIVE` while an engine runs.
+   */
+  beginReplacement(operation, refuseEngine) {
+    this.assertNone(operation);
+    const refusal = () => refuseEngine();
+    this.replacements.add(refusal);
+    return () => {
+      this.replacements.delete(refusal);
+    };
+  }
+};
+
 // src/core/worker/config.ts
 var DEFAULT_MAX_PENDING_WRITES = 1024;
 var DEFAULT_RETRY_AFTER_MS = 1e3;
@@ -2497,6 +3998,23 @@ function swallow() {
 }
 
 // src/core/database-create.ts
+function encryptionKeyringFor(driver, options) {
+  const encryption = options?.encryption;
+  if (encryption === void 0) return new EncryptionKeyring(null);
+  if (typeof encryption?.key !== "function") {
+    throw new EncryptionError(
+      "The encryption option needs a key function that returns 32 key bytes",
+      "INVALID_ENCRYPTION_KEY"
+    );
+  }
+  if (!driver.capabilities.encryption) {
+    throw new EncryptionError(
+      "The driver that this Sirannon uses cannot encrypt a database, so it cannot open one with the encryption option",
+      "ENCRYPTION_UNSUPPORTED"
+    );
+  }
+  return new EncryptionKeyring(encryption.key);
+}
 async function createDatabaseRuntime(id, path, driver, options, internals) {
   const writerWorker = resolveWriterWorkerConfig(options?.writerWorker);
   const readOnly = options?.readOnly ?? false;
@@ -2509,17 +4027,35 @@ async function createDatabaseRuntime(id, path, driver, options, internals) {
   if (options?.backups && !readOnly) {
     assertChangeLogCaptureSupported(driver, id, path, options.walMode ?? true, options.backups);
   }
-  const pool = await ConnectionPool.create({
-    driver,
-    path,
-    readOnly: options?.readOnly,
-    readPoolSize: options?.readPoolSize ?? 4,
-    walMode: options?.walMode ?? true,
-    synchronous: options?.synchronous,
-    ...options?.backups ? { walAutoCheckpoint: 0 } : {},
-    useWriterWorker: writerWorker.enabled && !readOnly,
-    workerHostOptions: writerWorker.host
-  });
+  const keyring = encryptionKeyringFor(driver, options);
+  const interrupted = await recoverInterruptedKeyChange(driver, path, readOnly);
+  const extensions = new LoadedExtensions(driver);
+  let pool;
+  try {
+    pool = await ConnectionPool.create({
+      driver,
+      path,
+      readOnly: options?.readOnly,
+      readPoolSize: options?.readPoolSize ?? 4,
+      walMode: options?.walMode ?? true,
+      synchronous: options?.synchronous,
+      ...options?.backups ? { walAutoCheckpoint: 0 } : {},
+      useWriterWorker: writerWorker.enabled && !readOnly,
+      workerHostOptions: writerWorker.host,
+      keyring,
+      prepareReopened: (connections) => extensions.reload(connections)
+    });
+  } catch (err) {
+    throw interrupted === null ? err : explainKeyAfterInterruptedChange(err, interrupted);
+  }
+  if (keyring.encrypted && !readOnly) {
+    try {
+      await writeKeyId(pool.acquireWriter(), keyring.keyId);
+    } catch (err) {
+      await pool.close().catch(() => void 0);
+      throw err;
+    }
+  }
   const writeGate = new WriteGate(writerWorker.enabled ? writerWorker.maxPendingWrites : 0, writerWorker.retryAfterMs);
   const writerLock = new WriterLock(driver.createWriterContext?.());
   const hookRegistry = new HookRegistry();
@@ -2536,11 +4072,12 @@ async function createDatabaseRuntime(id, path, driver, options, internals) {
     driver.capabilities,
     id,
     path,
-    driver.createBackupEngine?.(driver)
+    driver.createBackupEngine?.(driver),
+    () => keyring.keyId
   );
   const canOpenSnapshotConnection = driver.capabilities.multipleConnections && path !== ":memory:";
-  const extensions = new LoadedExtensions(driver);
-  const openSnapshotConnection = () => extensions.open(() => driver.open(path, { readonly: true, walMode: false }));
+  const fileConnections = new DatabaseFileConnections(driver, path, keyring, extensions);
+  const openSnapshotConnection = () => fileConnections.open({ readonly: true, walMode: false });
   const cdc = new DatabaseCdcController(
     (op) => writerLock.run(op),
     () => pool.acquireWriter(),
@@ -2584,7 +4121,27 @@ async function createDatabaseRuntime(id, path, driver, options, internals) {
     stamper: () => cdc.activeStamper
   });
   if (options?.backups && !readOnly) backups.startCycle(options.backups);
+  fileConnections.hold({ release: () => cdc.releaseLiveConnection(), reopen: async () => {
+  } });
+  const replicationEngines = new RegisteredReplicationEngines(id);
+  const encryption = new DatabaseEncryptionController({
+    databaseId: id,
+    readOnly,
+    replicationEngines,
+    path,
+    driver,
+    keyring,
+    pool,
+    writerLock,
+    fileConnections,
+    cdc,
+    backups,
+    onKeyChanged: internals?.onEncryptionChanged
+  });
   return {
+    fileConnections,
+    encryption,
+    replicationEngines,
     pool,
     writeGate,
     writerLock,
@@ -2604,6 +4161,7 @@ async function closeDatabaseRuntime(runtime, closeListeners) {
   runtime.cdc.stop();
   runtime.backups.cancelAll();
   const releaseSteps = [
+    () => runtime.encryption.cancel(),
     () => runtime.cdc.closeLiveConnection(),
     () => runtime.writes.drain(),
     () => runtime.writerLock.settle(),
@@ -2913,32 +4471,137 @@ var DatabaseBackups = class extends DatabaseLifecycle {
   }
 };
 
+// src/core/database-encryption.ts
+var DatabaseEncryption = class extends DatabaseBackups {
+  /**
+   * Returns whether the database file holds ciphertext, the version of the encryption engine, the identifier that
+   * came with the current key, the time of the last finished key change, and the progress of the current or last
+   * key change. The status never contains a key.
+   *
+   * @returns The encryption status.
+   */
+  async encryptionStatus() {
+    this.ensureNotClosed();
+    return this.runtime.encryption.status();
+  }
+  /**
+   * Encrypts a plaintext database, gives an encrypted one a new key, or, with `key` set to `null`, stores it as
+   * plaintext, while the database stays open for reads and writes.
+   *
+   * Sirannon copies a snapshot to a new file under the target key, applies the writes committed since the snapshot in
+   * rounds, holds writes only for the last round, and then replaces the file. Until the replacement, the database
+   * keeps its current key. After it, every connection opens under the new key, so open the database under that key
+   * from then on. When the database captures backups, the next capture starts a new chain with a full copy under the
+   * new key.
+   *
+   * On the Expo driver, the change needs expo-file-system 19.0.0 or later. Once an app has called this method, keep
+   * expo-file-system 19.0.0 or later installed in every later build, because the open that recovers from an
+   * interrupted change reads the files beside the database through it. Without it, the open cannot see that a change
+   * stopped part way.
+   *
+   * @param change - The function that returns the target key, or `null` to remove encryption.
+   * @returns The encryption status once the change ends.
+   * @throws An `EncryptionError` with `ENCRYPTION_UNSUPPORTED` on an Expo app without expo-file-system 19.0.0 or
+   * later, before the change writes any file, with `ENCRYPTION_CHANGE_IN_PROGRESS` while another change runs, or with
+   * `ENCRYPTION_CHANGE_ABORTED` when a schema change or a write that the change cannot apply exactly stops it, which
+   * leaves the database under its current key, `READ_ONLY` on a read-only database, and a `ReplicationError` with
+   * `REPLICATION_ACTIVE` while a replication engine writes to the database, which the caller stops before the change
+   * and starts again afterwards.
+   */
+  async changeEncryption(change) {
+    this.ensureOpen();
+    this.ensureWriterCanWait();
+    return this.runtime.encryption.changeKey(change);
+  }
+  /**
+   * Opens a connection to this database's file beyond the pool, under the database's current key, which waits while
+   * a key change replaces the file. The caller closes the connection.
+   *
+   * @param options - The open settings, without a key.
+   * @returns The connection.
+   * @internal
+   */
+  openFileConnection(options) {
+    this.ensureNotClosed();
+    return this.runtime.fileConnections.open(options);
+  }
+  /**
+   * Registers a part of the server that keeps a connection from {@link DatabaseEncryption.openFileConnection} open
+   * between calls, so that a key change can close it before it replaces the file and reopen it afterwards.
+   *
+   * @param holder - The release and reopen calls.
+   * @returns A function that removes the registration.
+   * @internal
+   */
+  holdFileConnection(holder) {
+    return this.runtime.fileConnections.hold(holder);
+  }
+  /**
+   * Returns whether the database file opens under a key, which a replication engine announces to its peers. A key
+   * change can alter it only while no engine runs, so the value holds for an engine's whole run.
+   *
+   * @returns `true` for an encrypted database.
+   * @internal
+   */
+  get encryptedFile() {
+    return this.runtime.encryption.encrypted;
+  }
+  /**
+   * Records a replication engine that writes to this database through a separate writer connection, so that a key
+   * change or a restore refuses to replace the file under that connection while the engine runs.
+   *
+   * @returns A function that removes the record, which the engine calls when it stops.
+   * @throws `ENCRYPTION_CHANGE_IN_PROGRESS` while a key change runs, and `DATABASE_CLOSED` on a closed database.
+   * @internal
+   */
+  registerReplicationEngine() {
+    this.ensureNotClosed();
+    return this.runtime.replicationEngines.register();
+  }
+  /**
+   * Throws while a replication engine writes to this database, because replacing the file would leave the engine's
+   * writer connection on the replaced file.
+   *
+   * @param operation - The operation that would replace the file, as the error message states it.
+   * @throws A `ReplicationError` with `REPLICATION_ACTIVE` while an engine runs.
+   * @internal
+   */
+  assertNoReplicationEngine(operation) {
+    this.runtime.replicationEngines.assertNone(operation);
+  }
+};
+
 // src/core/database-reads.ts
 function readRows(deps, sql, params, options) {
-  if (readsUnobserved(deps)) return query(deps.pool.acquireReader(), sql, params);
+  if (readsUnobserved(deps)) return query(deps.pool.leaseReader(), sql, params, deps.pool);
   return deps.observer.withQueryHooks(
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => queryMetered(conn, sql, params), readOutcome)
+    () => onReadConnection(deps, sql, (conn, leasedFrom) => queryMetered(conn, sql, params, leasedFrom), readOutcome)
   );
 }
 function readWireRows(deps, sql, params, options) {
-  if (readsUnobserved(deps)) return queryRowsForWire(deps.pool.acquireReader(), sql, params);
+  if (readsUnobserved(deps)) return queryRowsForWire(deps.pool.leaseReader(), sql, params, deps.pool);
   return deps.observer.withQueryHooks(
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => queryForWire(conn, sql, params), readOutcome)
+    () => onReadConnection(deps, sql, (conn, leasedFrom) => queryForWire(conn, sql, params, leasedFrom), readOutcome)
   );
 }
 function readOneRow(deps, sql, params, options) {
-  if (readsUnobserved(deps)) return queryOne(deps.pool.acquireReader(), sql, params);
+  if (readsUnobserved(deps)) return queryOne(deps.pool.leaseReader(), sql, params, deps.pool);
   return deps.observer.withQueryHooks(
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => queryOneMetered(conn, sql, params), readOneOutcome)
+    () => onReadConnection(
+      deps,
+      sql,
+      (conn, leasedFrom) => queryOneMetered(conn, sql, params, leasedFrom),
+      readOneOutcome
+    )
   );
 }
 function readsUnobserved(deps) {
@@ -2947,7 +4610,7 @@ function readsUnobserved(deps) {
 async function onReadConnection(deps, sql, op, measure) {
   const refusal = deps.pool.readerCount === 0 ? deps.writerLock.callerRefusal() : null;
   if (refusal !== null) throw refusal;
-  const metered = deps.pool.readerCount === 0 ? await deps.writerLock.run(() => deps.observer.track(sql, () => op(deps.pool.acquireWriter()), measure)) : await deps.observer.track(sql, () => op(deps.pool.acquireReader()), measure);
+  const metered = deps.pool.readerCount === 0 ? await deps.writerLock.run(() => deps.observer.track(sql, () => op(deps.pool.acquireWriter()), measure)) : await deps.observer.track(sql, () => op(deps.pool.leaseReader(), deps.pool), measure);
   return metered.value;
 }
 
@@ -3405,7 +5068,7 @@ var MaintainedLiveQuery = class _MaintainedLiveQuery {
           await this.source.wait(Math.floor(Math.random() * this.source.rereadJitterMs));
         }
         if (this.closed) return;
-        if (this.replanBeforeRead) {
+        if (this.replanBeforeRead || this.source.connectionReplaced) {
           await this.source.replan();
           if (this.closed) return;
           this.replanBeforeRead = false;
@@ -4056,7 +5719,7 @@ function withoutTrailingSemicolon(tokens) {
 var DEFAULT_REREAD_JITTER_MS = 25;
 var DEFAULT_MAX_TRANSACTION_CHANGES = 1e4;
 var MAX_TRANSACTION_BYTES = 16 * 1048576;
-var PRIMARY_KEY_INDEX_ORIGIN = "pk";
+var PRIMARY_KEY_INDEX_ORIGIN2 = "pk";
 var nextProbeTable = 0;
 async function openLiveQuery(deps, sql, params, options) {
   const shape = analyseStatement(sql);
@@ -4093,7 +5756,7 @@ async function planProbe(live, shape, params, meter) {
   }
   const pkColumns = primaryKeyColumns(info);
   const indexes = await run(() => tableIndexList(conn, shape.table));
-  const pkIsRowid = pkColumns.length === 1 && !indexes.some((index) => index.origin === PRIMARY_KEY_INDEX_ORIGIN);
+  const pkIsRowid = pkColumns.length === 1 && !indexes.some((index) => index.origin === PRIMARY_KEY_INDEX_ORIGIN2);
   const plan = buildLivePlan(
     shape,
     {
@@ -4123,8 +5786,21 @@ function generatedExpression(shape, column, definitions) {
   return expression;
 }
 function buildSource(deps, live, shape, params, options, meter, initial) {
-  const delivery = new PrimedLiveDelivery(deps.cdc, live.conn, live.run, shape.table);
+  let liveConnection = live;
+  let delivery = new PrimedLiveDelivery(deps.cdc, live.conn, live.run, shape.table);
   let planned = initial;
+  let connectionReplaced = false;
+  let probeOnClosedConnection = false;
+  let delivering = null;
+  const stopWatchingReplacement = deps.cdc.onLiveConnectionReplaced(() => {
+    connectionReplaced = true;
+    probeOnClosedConnection = true;
+    const current = delivering;
+    delivering = null;
+    if (current === null) return;
+    current.stop();
+    current.onLost();
+  });
   return {
     get plan() {
       return planned.plan;
@@ -4132,24 +5808,46 @@ function buildSource(deps, live, shape, params, options, meter, initial) {
     get probe() {
       return planned.probe;
     },
+    get connectionReplaced() {
+      return connectionReplaced;
+    },
     rereadJitterMs: options?.rereadJitterMs ?? DEFAULT_REREAD_JITTER_MS,
     maxTransactionChanges: options?.maxTransactionChanges ?? DEFAULT_MAX_TRANSACTION_CHANGES,
     maxTransactionBytes: MAX_TRANSACTION_BYTES,
     onError: options?.onError,
     wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     read: () => readAtPosition2(deps.cdc, planned.plan, params, meter),
-    start: (handlers, sinceSeq) => delivery.start(handlers, sinceSeq),
+    async start(handlers, sinceSeq) {
+      const stop = await delivery.start(handlers, sinceSeq);
+      delivering = { stop, onLost: handlers.onLost };
+      return () => {
+        delivering = null;
+        stop();
+      };
+    },
     shapeChanged: (events) => events.some((event) => !capturedWithColumns(event, planned.columns)),
     async replan() {
       const replaced = planned;
       try {
-        planned = await planProbe(live, shape, params, meter);
+        if (connectionReplaced) {
+          liveConnection = await deps.cdc.liveConnection();
+          delivery = new PrimedLiveDelivery(deps.cdc, liveConnection.conn, liveConnection.run, shape.table);
+          connectionReplaced = false;
+          planned = await planProbe(liveConnection, shape, params, meter);
+          probeOnClosedConnection = false;
+          await replaced.probe.close().catch(() => void 0);
+          return;
+        }
+        planned = await planProbe(liveConnection, shape, params, meter);
       } catch (err) {
         throw asQueryError(err, shape.sql);
       }
       await replaced.probe.close();
     },
-    release: () => planned.probe.close()
+    release: () => {
+      stopWatchingReplacement();
+      return probeOnClosedConnection ? Promise.resolve() : planned.probe.close();
+    }
   };
 }
 function capturedWithColumns(event, columns) {
@@ -4188,7 +5886,7 @@ function toHeldRow(plan, row) {
 }
 
 // src/core/database.ts
-var Database = class _Database extends DatabaseBackups {
+var Database = class _Database extends DatabaseEncryption {
   /** @internal */
   static async create(id, path, driver, options, internals) {
     const runtime = await createDatabaseRuntime(id, path, driver, options, internals);
@@ -4847,6 +6545,11 @@ var RegistryMigrationSet = class {
 };
 
 // src/core/registry-defaults.ts
+function rememberEncryptionKey(opened, key) {
+  if (opened === void 0) return;
+  const { encryption: _replaced, ...rest } = opened.options ?? {};
+  opened.options = key === null ? rest : { ...rest, encryption: { key } };
+}
 function withRegistryDefaults(registry, options) {
   const defaults = {};
   if (registry.writerWorker !== void 0 && options?.writerWorker === void 0) {
@@ -4967,7 +6670,8 @@ var Sirannon = class {
       }
       db = await Database.create(id, path, this._driver, resolvedOptions, {
         parentHooks: this._hookRegistry,
-        metrics: this.metricsCollector ?? void 0
+        metrics: this.metricsCollector ?? void 0,
+        onEncryptionChanged: (key) => rememberEncryptionKey(this.openedWith.get(id), key)
       });
     } catch (err) {
       this.opening.delete(id);
@@ -5046,9 +6750,9 @@ var Sirannon = class {
    * Sirannon reopens the database even after a failed action.
    *
    * @param id - The identifier of the database to take offline.
-   * @param action - The function that Sirannon calls with the database file path once the database is closed.
+   * @param action - The function that Sirannon calls with the database file path and its key once the database is closed.
    * @returns Whether the action returned, the value that it returned or the error that it threw, and any error that the reopen threw.
-   * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, or the close error when the close fails.
+   * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, a `ReplicationError` with `REPLICATION_ACTIVE` while a replication engine writes to the database, or the close error when the close fails.
    *
    * @internal
    */
@@ -5058,13 +6762,14 @@ var Sirannon = class {
     const opened = this.openedWith.get(id);
     if (!db || !opened) throw new DatabaseNotFoundError(id);
     if (db.readOnly) throw new ReadOnlyError(id);
+    db.assertNoReplicationEngine("restore");
     this.dbs.delete(id);
     this.opening.add(id);
     this.offline.add(id);
     const work = takeDatabaseOffline({
       database: db,
       path: opened.path,
-      action,
+      action: (path) => action(path, opened.options?.encryption),
       reopen: async () => {
         this.opening.delete(id);
         try {
@@ -5251,4 +6956,4 @@ var NODE_HEALTH_REASONS = [
   "no-group-state"
 ];
 
-export { ConnectionPool, Database, DatabaseBackups, DatabaseLifecycle, HookRegistry, LifecycleManager, MIGRATION_NAME_RE, MigrationRunner, NODE_HEALTH_REASONS, NODE_HEALTH_STATES, Sirannon, createTenantResolver, migrationsFromFiles, operationName, operationRef, readBearerToken, readHeader, readSubprotocolCredential, sanitizeTenantId, tenantPath, toSubprotocolCredential };
+export { ConnectionPool, Database, DatabaseBackups, DatabaseEncryption, DatabaseLifecycle, HookRegistry, LifecycleManager, MIGRATION_NAME_RE, MigrationRunner, NODE_HEALTH_REASONS, NODE_HEALTH_STATES, Sirannon, createTenantResolver, migrationsFromFiles, operationName, operationRef, readBearerToken, readHeader, readSubprotocolCredential, sanitizeTenantId, tenantPath, toSubprotocolCredential };