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

package/dist/{database-fz-8CJBP.d.ts → database-BZ96ZzAx.d.ts}

@@ -1,9 +1,9 @@
-import { C as ChangeTracker, P as PruneBoundarySource } from './change-tracker-Dpo99EI-.js';
-import { D as DatabaseBackupController, B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions } from './database-backup-BwTNiBm2.js';
-import { S as SQLiteDriver, V as SynchronousLevel, aq as WorkerHostOptions, J as SQLiteConnection, ar as ChangeDispatchObserver, as as SubscriptionManager, at as WriterTransactionRunner, T as Transaction, au as StatementMeter, av as WriterContext, M as Migration, X as MigrationResult, Y as RollbackResult, al as QueryHookContext, a5 as ConnectionHookContext, a2 as BeforeSubscribeHook, a1 as BeforeSnapshotHook, a0 as BeforePushHook, ab as HookConfig, b as MetricsCollector, aw as QueryOutcomeMeasure, ax as QueryFailureMeasure, ay as QueryOutcome, az as RowCounts, D as DatabaseOptions, q as BackupFileReport, z as BackupToDestinationOptions, g as BackupRunReport, P as BackupScheduleOptions, h as BackupChain, p as BackupCycleStatus, C as BackupVerifyResult, l as BackupChainRecord, c as BeforeQueryHook, A as AfterQueryHook } from './types-DTmi7pXp.js';
+import { C as ChangeTracker, S as SirannonError, P as PruneBoundarySource } from './errors-DLMAGQFb.js';
+import { J as EncryptionKey, S as SQLiteDriver, X as SynchronousLevel, aw as WorkerHostOptions, L as SQLiteConnection, ax as ChangeDispatchObserver, ay as SubscriptionManager, az as WriterTransactionRunner, T as Transaction, aA as StatementMeter, aB as WriterContext, M as Migration, Z as MigrationResult, _ as RollbackResult, ar as QueryHookContext, a7 as ConnectionHookContext, a4 as BeforeSubscribeHook, a3 as BeforeSnapshotHook, a2 as BeforePushHook, ah as HookConfig, b as MetricsCollector, aC as QueryOutcomeMeasure, aD as QueryFailureMeasure, aE as QueryOutcome, aF as RowCounts, aq as OpenOptions, ag as EncryptionStatus, ae as EncryptionChange, D as DatabaseOptions, q as BackupFileReport, z as BackupToDestinationOptions, g as BackupRunReport, R as BackupScheduleOptions, h as BackupChain, p as BackupCycleStatus, C as BackupVerifyResult, l as BackupChainRecord, c as BeforeQueryHook, A as AfterQueryHook } from './types-BWyv_N18.js';
+import { D as DatabaseBackupController, B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions } from './database-backup-BhM8yJ1A.js';
 import { H as HLCTimestamp, c as ReplicationChange, C as ConflictResolver, A as ApplyResult, R as ReplicationBatch } from './types-BG31TtrQ.js';
 import { c as SubscriptionBuilder, P as Params, Q as QueryOptions, E as ExecuteResult, C as ChangeEvent } from './query-types-5B02ixH0.js';
-import { A as AppliedMigrationRow, c as BulkLoadOptions, a as BulkLoadResult } from './server-options-B9CsAZp5.js';
+import { A as AppliedMigrationRow, c as BulkLoadOptions, a as BulkLoadResult } from './server-options-Bhdlvehe.js';
 import { L as LiveQueryOptions, a as LiveQuery } from './types-CEJG0eFS.js';
 
 interface DeviceRetentionPolicy {
@@ -19,201 +19,69 @@ interface ChangeRetentionOptions extends DeviceRetentionOptions {
 }
 
 /**
- * The base class for every sirannon-db error, which has a machine-readable
- * {@link SirannonError.code}. Extend it to define an error of your own.
+ * A function that returns a database key, such as {@link EncryptionOptions.key}.
  *
- * @public
- */
-declare class SirannonError extends Error {
-    /**
-     * The machine-readable code that the server maps to an HTTP status.
-     */
-    readonly code: string;
-    constructor(message: string, 
-    /**
-     * The machine-readable code that the server maps to an HTTP status.
-     */
-    code: string);
-}
-/**
- * Thrown when the registry has no open database under an identifier, because
- * the database was never opened or is already closed.
- *
- * @public
- */
-declare class DatabaseNotFoundError extends SirannonError {
-    constructor(id: string);
-}
-/**
- * Thrown when a caller opens a database under an identifier that the registry
- * already uses, since each identifier names one database.
- *
- * @public
- */
-declare class DatabaseAlreadyExistsError extends SirannonError {
-    constructor(id: string);
-}
-/**
- * Thrown when a caller writes to a database that is open in read-only mode.
- *
- * @public
- */
-declare class ReadOnlyError extends SirannonError {
-    constructor(id: string);
-}
-/**
- * Thrown when SQLite fails to execute a statement, with that statement in
- * {@link QueryError.sql} for your logs.
- *
- * @public
- */
-declare class QueryError extends SirannonError {
-    /**
-     * The statement that failed.
-     */
-    readonly sql: string;
-    constructor(message: string, 
-    /**
-     * The statement that failed.
-     */
-    sql: string);
-}
-/**
- * Sirannon raises this error when SQLite refuses to commit a transaction whose
- * statements all succeeded, such as on a deferred foreign key; `cause` holds
- * SQLite's own error. The server responds to its `TRANSACTION_ERROR` code with status 400.
- *
- * @public
- */
-declare class TransactionError extends SirannonError {
-    constructor(message: string, cause?: unknown);
-}
-/**
- * Thrown when a migration fails, with the version of that migration in
- * {@link MigrationError.version}.
- *
- * @public
- */
-declare class MigrationError extends SirannonError {
-    /**
-     * The version of the migration that failed.
-     */
-    readonly version: number;
-    constructor(message: string, 
-    /**
-     * The version of the migration that failed.
-     */
-    version: number, code?: string);
-}
-/**
- * An error that a before-hook can throw to reject an operation, which the
- * server responds to with status 403. The message includes the optional
- * `reason`, so that a caller can tell one hook policy from another.
- *
- * @public
- */
-declare class HookDeniedError extends SirannonError {
-    constructor(hookName: string, reason?: string);
-}
-/**
- * Rejects one request with a status of your own; throw it from an authenticate hook or a registered operation.
- *
- * @public
- */
-declare class RequestDeniedError extends SirannonError {
-    /**
-     * The HTTP status that the server responds to the rejected request with.
-     */
-    readonly status: number;
-    constructor(status: number, code: string, message: string);
-}
-/**
- * Thrown when change capture cannot proceed, for example when a caller watches
- * a table that does not exist, when Sirannon cannot read the change-log epoch
- * or the node identity, or when a live query uses a statement that Sirannon
- * cannot keep current.
- *
- * @public
- */
-declare class CDCError extends SirannonError {
-    constructor(message: string);
-}
-/**
- * Thrown when a statement through the query API names a `_sirannon` table,
- * modifies a `sqlite_` table, contains ATTACH or DETACH, or sets
- * `PRAGMA writable_schema`. Sirannon rejects these statements to keep its
- * change log, its replication ledger, and SQLite's schema catalogue out of the
- * caller's reach.
- *
- * @public
- */
-declare class ForbiddenSqlError extends SirannonError {
-    constructor(message: string);
-}
-/**
- * Thrown when a copy to a file or a scheduled backup fails, or when its path,
- * cron expression, or time zone is invalid.
- *
- * @public
+ * @internal
  */
-declare class BackupError extends SirannonError {
-    constructor(message: string);
-}
+type EncryptionKeySource = () => EncryptionKey | Promise<EncryptionKey>;
 /**
- * Thrown when a caller asks a closed or empty connection pool for a connection, asks a
- * read-only pool for the writer, or closes a pool and one of its connections
- * fails to close.
+ * A key that Sirannon copied out of a key function's result, which the caller wipes once the connections that need it
+ * are open.
  *
- * @public
+ * @internal
  */
-declare class ConnectionPoolError extends SirannonError {
-    constructor(message: string);
+interface ResolvedEncryptionKey {
+    /** A copy of the 32 key bytes that no other code holds. */
+    bytes: Uint8Array;
+    /** The identifier that came with the key. */
+    id?: string;
 }
+
 /**
- * Thrown when the lifecycle resolver would open a database past `maxOpen`, and
- * evicting the least recently used database frees no slot. Close a database
- * before you open another one.
+ * The settings that an open passes to the driver for an encrypted database.
  *
- * @public
+ * @internal
  */
-declare class MaxDatabasesError extends SirannonError {
-    constructor(max: number);
+interface KeyedOpenOptions {
+    encryption?: {
+        key: Uint8Array;
+    };
 }
 /**
- * Thrown when more writes are pending than the writer-worker limit allows, so
- * that the database sheds load. The server responds to it with status 503 and
- * a `Retry-After` header.
+ * Holds the key function of one open database, and calls it each time the database opens connections, so that no key
+ * bytes stay in memory between opens.
  *
- * @public
+ * @internal
  */
-declare class WriteOverloadError extends SirannonError {
-    /**
-     * The number of pending writes that the database accepts before it rejects more.
-     */
-    readonly limit: number;
+declare class EncryptionKeyring {
+    private source;
+    private lastKeyId;
+    constructor(source: EncryptionKeySource | null);
+    /** `true` when the database opens under a key. */
+    get encrypted(): boolean;
+    /** The identifier that came with the key that the last open used, or `undefined` when it came with none. */
+    get keyId(): string | undefined;
+    /** The key function that the database currently opens under, or `null` for a plaintext database. */
+    get keySource(): EncryptionKeySource | null;
     /**
-     * The number of milliseconds that the caller should wait before it retries.
+     * Makes the database open every later connection under a new key function, or as plaintext.
+     *
+     * @param source - The key function of the key that the file now holds, or `null` for a plaintext file.
      */
-    readonly retryAfterMs: number;
-    constructor(
+    replace(source: EncryptionKeySource | null): void;
     /**
-     * The number of pending writes that the database accepts before it rejects more.
+     * Calls the key function once, passes the key to the opens, and wipes Sirannon's copy of the key once they settle.
+     *
+     * @param open - Opens the connections with the settings that carry the key.
+     * @returns What `open` returns.
      */
-    limit: number, 
+    openWith<T>(open: (options: KeyedOpenOptions, key: ResolvedEncryptionKey | undefined) => Promise<T>): Promise<T>;
     /**
-     * The number of milliseconds that the caller should wait before it retries.
+     * Calls the key function and returns a copy of the key bytes, which the caller hands to a writer worker and wipes.
+     *
+     * @returns The key bytes.
      */
-    retryAfterMs: number);
-}
-/**
- * Thrown when Sirannon cannot load a compiled SQLite extension. The message
- * names the extension path, and the optional `cause` gives the reason that
- * SQLite or Sirannon reported.
- *
- * @public
- */
-declare class ExtensionError extends SirannonError {
-    constructor(path: string, cause?: string);
+    freshKeyBytes(): Promise<Uint8Array>;
 }
 
 /**
@@ -231,6 +99,8 @@ interface ConnectionPoolOptions {
     walAutoCheckpoint?: number;
     useWriterWorker?: boolean;
     workerHostOptions?: WorkerHostOptions;
+    keyring?: EncryptionKeyring;
+    prepareReopened?: (connections: readonly SQLiteConnection[]) => Promise<void>;
 }
 /**
  * Opens one writer connection and a set of reader connections for a single database file, and returns the readers in rotation.
@@ -238,18 +108,62 @@ interface ConnectionPoolOptions {
  * @internal
  */
 declare class ConnectionPool {
-    private readonly writer;
-    private readonly readers;
+    private readonly options;
+    private writer;
+    private readers;
     private readerIndex;
     private closed;
+    private isSuspended;
+    private readsInFlight;
+    private readsSettled;
+    private reopenFailure;
     private constructor();
     static create(options: ConnectionPoolOptions): Promise<ConnectionPool>;
+    private ensureAvailable;
     acquireReader(): SQLiteConnection;
     acquireWriter(): SQLiteConnection;
+    /**
+     * 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(): SQLiteConnection;
+    /** Ends a lease that {@link ConnectionPool.leaseReader} returned. */
+    releaseReader(): void;
+    /**
+     * 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.
+     */
+    withReader<T>(read: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
     /** Returns the writer and every reader, so that the caller can apply an operation to every connection in the pool. */
     connections(): readonly SQLiteConnection[];
     get readerCount(): number;
     get isReadOnly(): boolean;
+    /**
+     * 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.
+     */
+    closeReaders(drainTimeoutMs: number): Promise<void>;
+    private readsDrained;
+    /** Closes the writer after {@link ConnectionPool.closeReaders}. */
+    closeWriter(): Promise<void>;
+    /** `true` from {@link ConnectionPool.closeReaders} until {@link ConnectionPool.reopen} returns. */
+    get suspended(): boolean;
+    /**
+     * 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.
+     */
+    reopen(): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -360,6 +274,7 @@ declare class DatabaseCdcController {
     private stopPolling;
     private stamper;
     private epochRequest;
+    private readonly liveConnectionListeners;
     constructor(runExclusive: RunExclusive$1, acquireWriter: () => SQLiteConnection, pollInterval: number, retention: number, openSnapshotConnection: (() => Promise<SQLiteConnection>) | null, deviceRetention: DeviceRetentionPolicy, onDispatched?: ChangeDispatchObserver | undefined);
     ensureEpoch(): Promise<string>;
     readAtPositionWith<T>(read: (conn: SQLiteConnection) => Promise<T>): Promise<{
@@ -372,6 +287,27 @@ declare class DatabaseCdcController {
         run: RunExclusive$1;
     }>;
     closeLiveConnection(): Promise<void>;
+    /**
+     * 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: () => void): () => void;
+    /**
+     * 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.
+     */
+    releaseLiveConnection(): Promise<void>;
+    /**
+     * 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(): void;
+    private replanLiveQueries;
     get subscriptions(): SubscriptionManager | null;
     get changeTracker(): ChangeTracker | null;
     watch(table: string): Promise<void>;
@@ -638,6 +574,7 @@ declare class DatabaseSyncController {
     private readonly acquireWriter;
     private readonly cdc;
     private pkResolver;
+    private cachedOn;
     private tablesReady;
     private metaReady;
     private outboxReader;
@@ -668,6 +605,7 @@ declare class DatabaseSyncController {
     private setMetaSeq;
     private ensureMeta;
     private ensureSyncTables;
+    private resolverOn;
     private ensureOutboxReader;
     private ensureApplier;
     private catchUpLocalColumnVersions;
@@ -754,11 +692,212 @@ declare class DatabaseWriteController {
     private runInTransaction;
 }
 
+/**
+ * Counts the replication engines that write to one database through a separate writer connection, so that the
+ * database can refuse an operation that would replace its file under those connections.
+ *
+ * @internal
+ */
+declare class RegisteredReplicationEngines {
+    private readonly databaseId;
+    private count;
+    private readonly replacements;
+    constructor(databaseId: string);
+    /**
+     * 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(): () => void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string, refuseEngine: () => SirannonError): () => void;
+}
+
+/**
+ * Records the resolved path of every compiled extension that a database has
+ * loaded, and tracks every connection that the database opens beyond its pool,
+ * so that each of those connections can call the extensions' functions. SQLite
+ * scopes a loaded extension to the connection that loaded it, and a database
+ * opens a new connection for each consistent snapshot read and one more for its
+ * live queries.
+ *
+ * This class performs loads and opens one at a time, so a connection either
+ * opens after a load and loads that extension as it opens, or opens before the
+ * load and is one of the connections that the load covers.
+ *
+ * @internal
+ */
+declare class LoadedExtensions {
+    private readonly driver;
+    private readonly resolvedPaths;
+    private readonly openedConnections;
+    private queue;
+    constructor(driver: SQLiteDriver);
+    private runInTurn;
+    private loadRecorded;
+    /** Loads an extension into the pool's connections and every tracked connection, then records its resolved path. */
+    load(poolConnections: readonly SQLiteConnection[], extensionPath: string): Promise<void>;
+    /** Loads every recorded extension into connections that replaced the ones that the database loaded them into. */
+    reload(connections: readonly SQLiteConnection[]): Promise<void>;
+    /**
+     * Opens a connection, loads every recorded extension into it, and returns a
+     * wrapper that forwards each call to it. Closing the wrapper stops the
+     * tracking and closes the connection underneath.
+     *
+     * @param openConnection - The function that opens the connection that this database needs.
+     * @returns The wrapper to read and write through.
+     */
+    open(openConnection: () => Promise<SQLiteConnection>): Promise<SQLiteConnection>;
+}
+
+/**
+ * A part of the database that keeps a connection to the file open between calls, and closes and reopens it when a
+ * key change replaces the file.
+ *
+ * @internal
+ */
+interface FileConnectionHolder {
+    /** Closes the held connection and stops the work that uses it. */
+    release(): Promise<void>;
+    /** Opens a new connection to the file that the key change left in place, and resumes the work that uses it. */
+    reopen(): Promise<void>;
+}
+/**
+ * Opens every connection to a database file beyond the pool, under the database's current key and with its loaded
+ * extensions, and tracks each one, so that a key change can close all of them before it replaces the file and open
+ * them again afterwards.
+ *
+ * @internal
+ */
+declare class DatabaseFileConnections {
+    private readonly driver;
+    private readonly path;
+    private readonly keyring;
+    private readonly extensions;
+    private active;
+    private readonly holders;
+    private replacement;
+    private drained;
+    constructor(driver: SQLiteDriver, path: string, keyring: EncryptionKeyring, extensions: LoadedExtensions);
+    /**
+     * 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.
+     */
+    open(options: OpenOptions): Promise<SQLiteConnection>;
+    private settle;
+    /**
+     * 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: FileConnectionHolder): () => void;
+    /**
+     * 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.
+     */
+    closeForReplacement(timeoutMs: number): Promise<void>;
+    /** Lets opens proceed again, and has every holder open its connection to the file that is now in place. */
+    reopenAfterReplacement(): Promise<void>;
+}
+
+/**
+ * The parts of an open database that a key change works through.
+ *
+ * @internal
+ */
+interface KeyChangeDeps {
+    path: string;
+    driver: SQLiteDriver;
+    keyring: EncryptionKeyring;
+    pool: ConnectionPool;
+    writerLock: WriterLock;
+    fileConnections: DatabaseFileConnections;
+    cdc: DatabaseCdcController;
+    backups: DatabaseBackupController;
+}
+
+/**
+ * What the encryption controller needs beyond the parts that a key change works through.
+ *
+ * @internal
+ */
+interface EncryptionControllerDeps extends KeyChangeDeps {
+    databaseId: string;
+    readOnly: boolean;
+    replicationEngines: RegisteredReplicationEngines;
+    onKeyChanged?: (key: EncryptionKeySource | null) => void;
+}
+/**
+ * Reports how a database is encrypted, and runs one key change at a time.
+ *
+ * @internal
+ */
+declare class DatabaseEncryptionController {
+    private readonly deps;
+    private change;
+    private running;
+    private closing;
+    private described;
+    constructor(deps: EncryptionControllerDeps);
+    /** `true` while the database file opens under a key. */
+    get encrypted(): boolean;
+    /**
+     * 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.
+     */
+    status(): Promise<EncryptionStatus>;
+    /**
+     * 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.
+     */
+    changeKey(change: EncryptionChange): Promise<EncryptionStatus>;
+    private runChange;
+    /** Stops a running key change at its next step, and waits for it to leave the database as it was. */
+    cancel(): Promise<void>;
+    private targetOf;
+    private finished;
+    private failed;
+    private describeFile;
+}
+
 interface DatabaseInternals {
     parentHooks?: HookRegistry;
     metrics?: MetricsCollector;
+    onEncryptionChanged?: (key: EncryptionKeySource | null) => void;
 }
 interface DatabaseRuntime {
+    fileConnections: DatabaseFileConnections;
+    encryption: DatabaseEncryptionController;
+    replicationEngines: RegisteredReplicationEngines;
     pool: ConnectionPool;
     writeGate: WriteGate;
     writerLock: WriterLock;
@@ -1003,6 +1142,94 @@ declare class DatabaseBackups extends DatabaseLifecycle {
     backupPiecesSafeToDelete(options?: BackupSafeToDeleteOptions): Promise<BackupChainRecord[]>;
 }
 
+/**
+ * Gives an open database its encryption methods: the status of its key, and the key change that encrypts it, gives it
+ * a new key, or removes encryption while it stays open.
+ *
+ * Open a database through {@link Sirannon.open}, which returns a {@link Database} that extends this class.
+ *
+ * @public
+ */
+declare class DatabaseEncryption 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.
+     */
+    encryptionStatus(): Promise<EncryptionStatus>;
+    /**
+     * 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.
+     */
+    changeEncryption(change: EncryptionChange): Promise<EncryptionStatus>;
+    /**
+     * 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: OpenOptions): Promise<SQLiteConnection>;
+    /**
+     * 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: FileConnectionHolder): () => void;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): () => void;
+    /**
+     * 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: string): void;
+}
+
 /**
  * An open SQLite database, with methods for reads, writes, transactions, migrations, change subscriptions, and live queries.
  *
@@ -1010,7 +1237,7 @@ declare class DatabaseBackups extends DatabaseLifecycle {
  *
  * @public
  */
-declare class Database extends DatabaseBackups {
+declare class Database extends DatabaseEncryption {
     /** @internal */
     static create(id: string, path: string, driver: SQLiteDriver, options?: DatabaseOptions, internals?: DatabaseInternals): Promise<Database>;
     /** @internal */
@@ -1231,4 +1458,4 @@ declare class Database extends DatabaseBackups {
     onAfterQuery(hook: AfterQueryHook): HookDispose;
 }
 
-export { BackupError as B, CDCError as C, Database as D, ExtensionError as E, ForbiddenSqlError as F, HookRegistry as H, MaxDatabasesError as M, type PushHookContext as P, QueryError as Q, ReadOnlyError as R, SirannonError as S, TransactionError as T, WriteOverloadError as W, type HookDispose as a, ConnectionPool as b, ConnectionPoolError as c, type ConnectionPoolOptions as d, DatabaseAlreadyExistsError as e, DatabaseBackups as f, DatabaseLifecycle as g, DatabaseNotFoundError as h, HookDeniedError as i, type HookEvent as j, type HookEventContextMap as k, type HookHandler as l, MigrationError as m, RequestDeniedError as n, type SnapshotHookContext as o, type SubscribeHookContext as p, type DeviceSyncPort as q, HLC as r };
+export { ConnectionPool as C, Database as D, HookRegistry as H, type PushHookContext as P, type SnapshotHookContext as S, type HookDispose as a, type DeviceSyncPort as b, type ConnectionPoolOptions as c, DatabaseBackups as d, DatabaseEncryption as e, DatabaseLifecycle as f, type HookEvent as g, type HookEventContextMap as h, type HookHandler as i, type SubscribeHookContext as j, HLC as k };