@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/types-Dc8oWlxj.d.ts

@@ -0,0 +1,1580 @@
+import { P as Params, W as WriteConcern, R as ReadConcern, b as ChangeOperation, E as ExecuteResult, a as ReadConcernLevel } from './query-types-5B02ixH0.js';
+
+/** One piece of a backup file at a destination.
+ * @public
+ */
+interface BackupPiece {
+    /** The position of this piece in the file, counted in whole pieces from zero. */
+    index: number;
+    /** The size of this piece, in bytes. */
+    byteLength: number;
+}
+/**
+ * The storage that Sirannon writes backup bytes to and reads them back from.
+ * Sirannon includes no storage client, so you supply the three required
+ * operations and connect object storage, another machine, or any other store
+ * of bytes. Every piece except the last holds the same number of bytes, and
+ * Sirannon can write the pieces in any order, because SQLite writes page one
+ * last. A backup chain uses several
+ * names, since Sirannon stores its full copy, each change piece, and the list
+ * of its records under names of their own.
+ *
+ * @public
+ */
+interface BackupDestination {
+    /**
+     * Stores one piece of a named file. A second write to the same name and index
+     * must replace the piece already there, because when Sirannon stops between
+     * storing a piece and recording it, it stores that piece again when it
+     * resumes.
+     */
+    writePiece(name: string, index: number, bytes: Uint8Array): Promise<void>;
+    /**
+     * Stores one piece only where no piece exists at that name and index, and
+     * resolves to true when this call stored it. Sirannon claims each index in
+     * its list of chains through this method, so that two nodes writing at the
+     * same moment keep both of their chains. When you leave it out, Sirannon
+     * writes the record and reads it back, which loses a chain when the other
+     * node writes between those two calls.
+     */
+    writePieceIfAbsent?(name: string, index: number, bytes: Uint8Array): Promise<boolean>;
+    /** Returns one piece of a named file. */
+    readPiece(name: string, index: number): Promise<Uint8Array>;
+    /** Returns every piece of a named file, in any order. */
+    listPieces(name: string): Promise<BackupPiece[]>;
+}
+
+/** The default name that Sirannon stores the list of chains under at a destination.
+ * @public
+ */
+declare const DEFAULT_CHAIN_NAME = "sirannon-backup-chain";
+/** The range of write-ahead log frames that one change piece holds.
+ * @public
+ */
+interface BackupChainPosition {
+    /** The checkpoint sequence of the log that holds these frames. SQLite adds one to it each time it restarts the log. */
+    logSequence: number;
+    /** The first salt of that log. Together with `salt2`, it identifies the generation of the log that holds the frames. */
+    salt1: number;
+    /** The second salt of that log. */
+    salt2: number;
+    /** The first frame in the piece, counted from one. */
+    firstFrame: number;
+    /** The last frame in the piece. */
+    lastFrame: number;
+}
+/**
+ * The full copy at the head of a chain. Sirannon restores from this copy and
+ * then applies the change pieces on top of it.
+ *
+ * @public
+ */
+interface BackupChainBase {
+    /** The kind of record. */
+    kind: 'full';
+    /** The chain that this copy begins. */
+    chainId: string;
+    /** The name that Sirannon stores the pieces of this copy under at the destination. */
+    name: string;
+    /** The identifier that Sirannon reports the progress of this copy under. */
+    runId: string;
+    /** The moment, in epoch milliseconds, that the copy finished. A restore to any earlier moment needs an older chain. */
+    finishedAt: number;
+    /** The number of pieces that Sirannon stores the copy in. */
+    pieceCount: number;
+    /** The size of one whole piece, in bytes. */
+    pieceBytes: number;
+    /** The number of bytes that Sirannon stores at the destination. */
+    bytesWritten: number;
+    /** The SHA-256 of the copy, present while fingerprinting is on. */
+    fingerprint?: string;
+}
+/**
+ * One change piece, which holds the log frames that a database writes between
+ * the previous capture and this one.
+ *
+ * @public
+ */
+interface BackupChainChange {
+    /** The kind of record. */
+    kind: 'change';
+    /** The chain that this piece extends, which identifies the full copy that the piece applies on top of. */
+    chainId: string;
+    /** The name that Sirannon stores this piece under at the destination. */
+    name: string;
+    /** The identifier that Sirannon reports the progress of this capture under. */
+    runId: string;
+    /** The position of this piece in its chain, counted from one. */
+    sequence: number;
+    /** The range of log frames that this piece holds. */
+    position: BackupChainPosition;
+    /** The moment, in epoch milliseconds, that Sirannon captured the frames. A restore stops at a capture time such as this one. */
+    capturedAt: number;
+    /** The number of log frames in this piece. */
+    frameCount: number;
+    /** The number of destination pieces that Sirannon stores these frames in. */
+    pieceCount: number;
+    /** The size of one whole piece, in bytes. */
+    pieceBytes: number;
+    /** The number of bytes that Sirannon stores at the destination. */
+    bytesWritten: number;
+    /** Whether the checkpoint after this capture emptied the log. */
+    checkpointed: boolean;
+    /** The SHA-256 of the frames, present while fingerprinting is on. */
+    fingerprint?: string;
+}
+/** Either the full copy at the head of a chain or one change piece along it.
+ * @public
+ */
+type BackupChainRecord = BackupChainBase | BackupChainChange;
+/** One full copy and every change piece that Sirannon captures after it.
+ * @public
+ */
+interface BackupChain {
+    /** The identifier of this chain. */
+    chainId: string;
+    /** The moment, in epoch milliseconds, that Sirannon started the chain. */
+    startedAt: number;
+    /** The identifier of the previous chain, where this chain replaces one. */
+    previousChainId?: string;
+    /**
+     * The full copy that the chain starts from. After someone deletes that
+     * record, this field is absent, so no restore can use the chain.
+     */
+    base?: BackupChainBase;
+    /** The change pieces, oldest first. */
+    changes: BackupChainChange[];
+}
+/**
+ * Returns the name that Sirannon stores the records of one chain under. Each
+ * chain has a name of its own, so deleting an old chain leaves every other
+ * chain in place.
+ *
+ * @param chainName - The name that Sirannon stores the list of chains under.
+ * @param chainId - The identifier of the chain.
+ * @returns The name to read and write the records of that chain under.
+ *
+ * @public
+ */
+declare function chainLogName(chainName: string, chainId: string): string;
+/**
+ * Returns every chain at a destination, with its full copy and its change
+ * pieces. It reads only the destination, so you can call it on a fresh machine
+ * before any database exists.
+ *
+ * @param destination - The destination that holds the backups and their records.
+ * @param chainName - The name that Sirannon stores the list of chains under. Defaults to `sirannon-backup-chain`.
+ * @returns The chains, newest first, each with its own records oldest first.
+ *
+ * @public
+ */
+declare function readBackupChains(destination: BackupDestination, chainName?: string): Promise<BackupChain[]>;
+
+/**
+ * The node of a replication group that takes its backups.
+ *
+ * With `'replica'`, Sirannon picks an eligible replica, and it picks the
+ * primary where the group has no eligible replica. With `'primary'`, Sirannon
+ * picks the primary, and no node takes backups while the primary is not
+ * eligible. An object names one node directly, and each node compares its own
+ * identifier against that name without reading the membership.
+ *
+ * @public
+ */
+type BackupNodePreference = 'replica' | 'primary' | {
+    nodeId: string;
+};
+/**
+ * The primary of a replication group, and the nodes that hold data current
+ * enough to back up.
+ *
+ * @public
+ */
+interface BackupGroupMembership {
+    /** The identifier of the primary, or null while the group has no primary. */
+    primaryNodeId: string | null;
+    /** The identifiers of the nodes that are eligible to take the backup. */
+    nodeIds: string[];
+}
+/**
+ * The source of the identity of this node and the membership of its
+ * replication group. Without a group source, the cycle backs up the database on
+ * every turn, as a single-node deployment needs.
+ *
+ * `coordinatorBackupGroup` in the replication entry point builds a group source
+ * from a cluster coordinator. Write your own where another system holds the
+ * membership.
+ *
+ * @public
+ */
+interface BackupGroupSource {
+    /** The identifier of this node within the group. */
+    readonly nodeId: string;
+    /**
+     * Reads the current membership of the group.
+     *
+     * @returns The primary of the group, and the nodes that are eligible.
+     */
+    readMembership(): Promise<BackupGroupMembership>;
+}
+/**
+ * The reason that one turn of the cycle writes nothing.
+ *
+ * `'not-preferred'` means that another node, or no node, takes the backups of
+ * this group. `'group-unavailable'` means that Sirannon cannot read the
+ * membership of the group. `'previous-run-active'` means that the previous turn
+ * is still in progress.
+ *
+ * @public
+ */
+type BackupSkipReason = 'not-preferred' | 'group-unavailable' | 'previous-run-active';
+/**
+ * One turn that the cycle skips, and the reason for the skip.
+ *
+ * @public
+ */
+interface BackupSkip {
+    /** The condition that applies. */
+    reason: BackupSkipReason;
+    /** A sentence for the log of the operator that describes the skip. */
+    message: string;
+    /** The identifier of this node, where a group source supplies one. */
+    nodeId?: string;
+    /** The identifier of the node that takes the backups, where Sirannon picks one. */
+    preferredNodeId?: string;
+    /**
+     * The size in bytes of the write-ahead log on this node at the skip. An alert
+     * on this value as it rises warns you that the log on a node is growing, well
+     * before `maxUncapturedLogBytes` ends its chain.
+     */
+    uncapturedLogBytes?: number;
+}
+
+/**
+ * The position of the write-ahead log of a database at one moment.
+ *
+ * A full copy records this position, so that you can tell which generation of
+ * the log the database was on when the copy finished. SQLite restarts the log
+ * after a checkpoint that empties it, and it writes a new pair of salts into
+ * the log at each restart.
+ *
+ * The backup cycle runs a checkpoint after each capture and none between a full
+ * copy and the first change piece of its chain, so those two records hold the
+ * same salts. A change piece holds later salts than the piece before it
+ * whenever the checkpoint between the two empties the log. A reader can keep a
+ * checkpoint from emptying the log, which leaves the log on its current
+ * generation, so two consecutive change pieces can hold the same salts.
+ *
+ * @public
+ */
+interface BackupLogPosition {
+    /** The checkpoint sequence of the log. SQLite adds one to it each time it restarts the log. */
+    logSequence: number;
+    /** The first salt of that log. Together with `salt2`, it identifies the generation of the log. */
+    salt1: number;
+    /** The second salt of that log. */
+    salt2: number;
+    /** The last frame that commits a transaction, counted from one, or zero where the log holds no such frame. */
+    lastFrame: number;
+}
+/** The progress of one backup, which Sirannon reports after each step of the copy and after each piece that it stores.
+ * @public
+ */
+interface BackupProgress {
+    /** The identifier of the backup that this progress describes. */
+    runId: string;
+    /** Whether Sirannon is copying pages or sending pieces. */
+    phase: 'copy' | 'transfer';
+    /** The total number of pages to copy. For a change piece, this is the number of log frames in the piece. */
+    totalPages: number;
+    /**
+     * The number of pages left to copy. On the staged route, every report of the
+     * transfer phase states zero, since the copy finishes before the transfer
+     * starts. On the streamed route, the two phases overlap, so a transfer report
+     * states the pages left at the latest step.
+     */
+    remainingPages: number;
+    /** The number of times so far that SQLite restarts the copy from page one. A change piece reports zero, since Sirannon reads the log for it and copies no pages. */
+    restarts: number;
+    /** The number of pieces stored at the destination so far. */
+    piecesWritten: number;
+    /** The number of bytes stored at the destination so far. */
+    bytesWritten: number;
+}
+/** The report of one finished backup to a destination.
+ * @public
+ */
+interface BackupRunReport {
+    /** The identifier that Sirannon reports the progress of this backup under. */
+    runId: string;
+    /** The identifier of the source database. */
+    databaseId: string;
+    /** The path of the source database file. */
+    sourcePath: string;
+    /** Whether the backup holds the whole database or the log frames written since the previous capture. */
+    kind: 'full' | 'change';
+    /** The chain that this backup is part of. A full copy begins a chain, and every later change piece extends it. */
+    chainId: string;
+    /** Whether Sirannon sends the bytes through a local file, which is `staged`, or without one, which is `streamed`. */
+    route: 'staged' | 'streamed';
+    /**
+     * The name that Sirannon stores the pieces under at the destination. Sirannon
+     * writes only this name at the destination, because the journal that SQLite
+     * opens next to a copy stays on local disk.
+     */
+    destinationName: string;
+    /** The moment, in epoch milliseconds, that the backup started. */
+    startedAt: number;
+    /** The moment, in epoch milliseconds, that the backup finished. */
+    finishedAt: number;
+    /** The length of the whole backup, in milliseconds. */
+    durationMs: number;
+    /** The time, in milliseconds, that SQLite spends copying pages. */
+    copyMs: number;
+    /** The time, in milliseconds, that Sirannon spends storing pieces at the destination. */
+    transferMs: number;
+    /** The number of pages that SQLite copies. */
+    pageCount: number;
+    /** The size of one page, in bytes. */
+    pageSize: number;
+    /** The number of bytes that Sirannon stores at the destination. */
+    bytesWritten: number;
+    /** The number of pieces that Sirannon stores at the destination. */
+    pieceCount: number;
+    /** The size of one whole piece, in bytes. */
+    pieceBytes: number;
+    /** The number of times that SQLite restarts the copy from page one. */
+    restarts: number;
+    /** The range of log frames that a change piece holds. A full copy leaves this field out. */
+    position?: BackupChainPosition;
+    /**
+     * The position of the write-ahead log when a full copy finishes. Sirannon
+     * reads the log after SQLite copies the last page, so if a writer commits
+     * between those two steps, this position can include a frame that the copy
+     * lacks. A change piece states its range of log frames in
+     * {@link BackupRunReport.position}, and a database without a write-ahead log
+     * leaves out both fields.
+     */
+    logPosition?: BackupLogPosition;
+    /** The SHA-256 of the copied file, present while fingerprinting is on. */
+    fingerprint?: string;
+}
+/** The report of one finished copy to a local file.
+ * @public
+ */
+interface BackupFileReport {
+    /** The identifier of this copy. */
+    runId: string;
+    /** The identifier of the source database. */
+    databaseId: string;
+    /** The path of the source database file. */
+    sourcePath: string;
+    /** The absolute path of the copy. */
+    destPath: string;
+    /** The moment, in epoch milliseconds, that the copy started. */
+    startedAt: number;
+    /** The moment, in epoch milliseconds, that the copy finished. */
+    finishedAt: number;
+    /** The length of the copy, in milliseconds. */
+    durationMs: number;
+    /** The number of pages that SQLite copies. */
+    pageCount: number;
+    /** The size of one page, in bytes. */
+    pageSize: number;
+    /** The size of the copy, in bytes. */
+    byteLength: number;
+    /** The number of times that SQLite restarts the copy from page one. */
+    restarts: number;
+}
+/**
+ * The result of one copy to a local file. The controller for the database adds
+ * the database identifier and the source path to build a
+ * {@link BackupFileReport}.
+ *
+ * @internal
+ */
+type BackupFileCopy = Omit<BackupFileReport, 'databaseId' | 'sourcePath'>;
+/** The settings for one backup to a destination that the caller supplies.
+ * @public
+ */
+interface BackupToDestinationOptions {
+    /** The destination that stores the pieces, and that a restore reads them from. */
+    destination: BackupDestination;
+    /** The name to store the pieces under. Defaults to a name with a timestamp. */
+    name?: string;
+    /** The chain that this copy begins. Defaults to a random identifier. */
+    chainId?: string;
+    /**
+     * The size of one whole piece, in bytes. Defaults to 16 MiB. For a streamed
+     * copy, the size must divide by 512, because Sirannon passes SQLite whole
+     * 512-byte blocks.
+     */
+    pieceBytes?: number;
+    /** The number of pages that SQLite copies in one step. */
+    pagesPerStep?: number;
+    /** The number of restarts from page one that Sirannon allows before it fails the copy. */
+    restartLimit?: number;
+    /** The number of milliseconds that can pass without a completed step before Sirannon fails the copy. */
+    stallTimeoutMs?: number;
+    /** The number of milliseconds that one call to the destination can take before Sirannon fails the backup. Defaults to 10 minutes, and zero removes the deadline. */
+    destinationTimeoutMs?: number;
+    /** The number of steps that can pass without SQLite copying a new page before Sirannon fails the copy. */
+    noProgressStepLimit?: number;
+    /** The directory that the staged route writes its local file in. Defaults to the temporary directory of the system. */
+    stagingDir?: string;
+    /**
+     * Whether Sirannon computes the SHA-256 of the backup. Defaults to true. For a
+     * streamed copy, Sirannon reads every piece back from the destination to
+     * compute it, because it never holds the whole file, so you pay for that
+     * extra read from remote storage.
+     */
+    fingerprint?: boolean;
+    /** Called after each step of the copy and after each piece that Sirannon stores. */
+    onProgress?: (progress: BackupProgress) => void;
+}
+/** The options of the caller for one backup, plus the details of the source database and the first-step callback.
+ * @internal
+ */
+interface BackupRunRequest extends BackupToDestinationOptions {
+    /** The identifier of the source database. */
+    databaseId: string;
+    /** The path of the source database file. */
+    sourcePath: string;
+    /** Called once after the first step of the copy, so that the caller can release the writer. */
+    onFirstStep?: () => void;
+}
+
+/**
+ * The settings for the cycle that captures the write-ahead log of a database
+ * and then checkpoints it.
+ *
+ * When a database has these options, Sirannon turns off the automatic
+ * checkpoints of SQLite, because a checkpoint lets SQLite overwrite log frames
+ * that Sirannon has yet to capture, and SQLite reports success either way.
+ *
+ * @public
+ */
+interface BackupCycleOptions {
+    /** The destination that stores the full copy, the change pieces, and the chain records. */
+    destination: BackupDestination;
+    /**
+     * The interval between captures, in milliseconds. Defaults to 60000. A
+     * shorter interval keeps the log smaller and leaves fewer writes outside any
+     * backup after an unclean stop. At zero, the cycle takes a turn only when you
+     * call `runOnce`.
+     */
+    intervalMs?: number;
+    /**
+     * The age of a chain, in milliseconds, at which a new full copy starts a new
+     * chain. Defaults to 24 hours. A restore applies every change piece since the
+     * full copy, so this interval sets the upper limit on the time that a restore
+     * takes.
+     */
+    fullCopyIntervalMs?: number;
+    /** The name to store the list of chains under. Defaults to `sirannon-backup-chain`. */
+    chainName?: string;
+    /** The prefix of backup names at the destination. Defaults to `sirannon-backup`. */
+    namePrefix?: string;
+    /** The size of one whole piece, in bytes. Defaults to 16 MiB. */
+    pieceBytes?: number;
+    /** Whether to compute the SHA-256 of each backup. Defaults to true. */
+    fingerprint?: boolean;
+    /**
+     * The directory that holds a capture before Sirannon sends it. Defaults to a
+     * directory next to the database file, so that a capture that Sirannon has
+     * yet to send stays on disk across a restart. When you set it, the staged
+     * full copy also writes its local file here.
+     */
+    stagingDir?: string;
+    /** The number of pages that SQLite copies in one step of the full copy. */
+    pagesPerStep?: number;
+    /** The number of restarts from page one that Sirannon allows before it fails the full copy. */
+    restartLimit?: number;
+    /** The number of milliseconds that can pass without a completed step before Sirannon fails the full copy. */
+    stallTimeoutMs?: number;
+    /** The number of milliseconds that one call to the destination can take before Sirannon fails it. Defaults to 10 minutes, and zero removes the deadline. */
+    destinationTimeoutMs?: number;
+    /**
+     * The largest size in bytes that the write-ahead log can reach while the
+     * cycle captures nothing. By default there is no limit, which keeps the chain
+     * whole and lets the log grow for as long as the captures stop.
+     *
+     * Set it where free disk space matters more than an unbroken chain. Sirannon
+     * measures the log after any turn that captures nothing. Once the log passes
+     * this size, Sirannon empties it and reports `BACKUP_CHAIN_BROKEN`, so no
+     * backup holds the writes from that log, and the next turn that the node takes
+     * starts a new chain with a full copy.
+     */
+    maxUncapturedLogBytes?: number;
+    /** The number of steps that can pass without SQLite copying a new page before Sirannon fails the full copy. */
+    noProgressStepLimit?: number;
+    /**
+     * The source of the identity of this node and the membership of its
+     * replication group. Every node of a group has the same cycle, and each turn
+     * reads this source before it copies anything. Leave it out on a single-node
+     * deployment, where that one node takes every turn.
+     */
+    replicationGroup?: BackupGroupSource;
+    /**
+     * The node of that group that takes its backups. Defaults to `'replica'`, so
+     * that the primary keeps its capacity for writes. When the group has no
+     * eligible replica, Sirannon picks the primary.
+     */
+    preferredNode?: BackupNodePreference;
+    /** Called with the report of every backup that the cycle finishes. */
+    onRun?: (report: BackupRunReport) => void;
+    /**
+     * Called after each step of the copy and after each stored piece, with the
+     * counters of the turn in progress. The cycle also records the latest
+     * counters in its status, so use this callback when you want every step, and
+     * read the status when you want the current figure.
+     */
+    onProgress?: (progress: BackupProgress) => void;
+    /**
+     * Called with every turn that the cycle skips, and the reason for the skip. A
+     * node that takes none of the backups of its group reports a skip on every
+     * turn.
+     */
+    onSkip?: (skip: BackupSkip) => void;
+    /**
+     * Called when a capture, a transfer, or a checkpoint fails. Set this
+     * callback, because when turns keep failing while writes continue, the log
+     * grows without limit, and this callback reports each failure as it happens.
+     */
+    onError?: (error: Error) => void;
+}
+/** The settings of the operator, plus the database details and callbacks that the cycle needs.
+ * @internal
+ */
+interface BackupCycleRequest extends BackupCycleOptions {
+    /** The identifier of the database to capture from. */
+    databaseId: string;
+    /** The path of its file. */
+    sourcePath: string;
+    /** Runs an operation while no other operation holds the writer. */
+    runExclusive: (op: () => Promise<void>) => Promise<void>;
+    /** Returns the writer connection, which is the only connection that may checkpoint. */
+    acquireWriter: () => SQLiteConnection;
+    /** Copies the whole database to the destination as the full copy that starts each chain. */
+    fullCopy: (options: BackupToDestinationOptions) => Promise<BackupRunReport>;
+}
+
+/** A failure of one turn of the cycle.
+ * @public
+ */
+interface BackupCycleError {
+    /** The error code, which a caller matches on. */
+    code: string;
+    /** A sentence for the log of the operator that describes the failure. */
+    message: string;
+    /** The moment, in epoch milliseconds, that Sirannon recorded the failure. */
+    at: number;
+    /** The time from the start of the turn to the failure, in milliseconds. */
+    durationMs: number;
+    /** The chain that the cycle held when the failure occurred, where it held one. */
+    chainId?: string;
+    /**
+     * The progress of the backup at the failure. Sirannon leaves this field out
+     * for a failure before the copy begins. For a failure part-way through, it
+     * records the backup identifier, the pages left to copy, and the pieces and
+     * bytes already stored at the destination.
+     */
+    progress?: BackupProgress;
+}
+/** What the cycle is doing now, and the outcome of its recent turns.
+ * @public
+ */
+interface BackupCycleStatus {
+    /** Whether a turn is in progress. */
+    running: boolean;
+    /** The chain that the cycle extends, where it holds one. */
+    chainId?: string;
+    /** The progress of the current turn, which Sirannon clears between turns. */
+    progress?: BackupProgress;
+    /** The report of the most recent backup that the cycle finished. */
+    lastRun?: BackupRunReport;
+    /** The most recent skipped turn, and the reason for the skip. */
+    lastSkip?: BackupSkip;
+    /** The most recent failure of a turn. */
+    lastError?: BackupCycleError;
+}
+
+/** The result of reading one stored backup from a destination and checking it against its record.
+ * @public
+ */
+interface BackupVerifyResult {
+    /** The name that Sirannon stores the pieces under. */
+    name: string;
+    /** The chain that holds this record. */
+    chainId: string;
+    /** Whether this is the full copy at the head of that chain or one change piece along it. */
+    kind: 'full' | 'change';
+    /** The number of pieces at the destination. */
+    pieceCount: number;
+    /** The total size of those pieces, in bytes. */
+    bytesRead: number;
+    /** The SHA-256 that Sirannon computes over the bytes that it reads, present where the record holds a fingerprint to compare against. */
+    fingerprint?: string;
+}
+/**
+ * Reads one backup from the destination and checks it against its record in
+ * the chain.
+ *
+ * A restore finds a damaged piece only after it has begun, so call this
+ * beforehand to find the damage early. Sirannon fetches every piece in order
+ * and computes a SHA-256 over the bytes as it reads them, then compares that
+ * fingerprint and the byte count against the record. Sirannon holds one piece
+ * in memory at a time and writes nothing to disk, so a check of a large full
+ * copy needs no local storage.
+ *
+ * A missing piece, a byte count that differs from the record, and a
+ * fingerprint that differs from the record each throw
+ * `BACKUP_DESTINATION_ERROR`. Where fingerprinting was off for the backup,
+ * Sirannon compares only the piece listing and the byte count, and the result
+ * has no fingerprint. A name that no chain records throws
+ * `BACKUP_CHAIN_BROKEN`.
+ *
+ * @param destination - The destination that holds the pieces.
+ * @param chains - The chains at that destination, as {@link readBackupChains} returns them.
+ * @param name - The name that Sirannon stores the backup under, which its chain record states.
+ * @returns The number of pieces read, their total size in bytes, and the fingerprint where the record holds one.
+ *
+ * @public
+ */
+declare function verifyBackupRecord(destination: BackupDestination, chains: readonly BackupChain[], name: string): Promise<BackupVerifyResult>;
+
+/**
+ * Captures the write-ahead log of a database and then checkpoints it, on the
+ * interval that the operator sets.
+ *
+ * The capture must come first, because a checkpoint lets SQLite overwrite
+ * frames that Sirannon has yet to capture, and SQLite reports success either
+ * way. A failed capture therefore also skips the checkpoint after it.
+ *
+ * Sirannon creates the cycle for a database from its `backups` option.
+ *
+ * @public
+ */
+declare class BackupCycle {
+    private readonly chainName;
+    private readonly namePrefix;
+    private readonly stagingDir;
+    private readonly logPath;
+    private readonly intervalMs;
+    private readonly fullCopyIntervalMs;
+    private readonly preferredNode;
+    private readonly timer;
+    private state;
+    private queued;
+    private readonly turns;
+    private started;
+    private verified;
+    private busy;
+    private captured;
+    private sendRefused;
+    private stopped;
+    private readonly request;
+    private readonly turnLog;
+    /** @internal */
+    constructor(request: BackupCycleRequest);
+    /**
+     * Resumes the chain that the state file records, or starts a new chain with a
+     * full copy, and then repeats the turn on the interval. On a resumed chain,
+     * Sirannon takes an ordinary turn straight away, so it sends the frames written
+     * while this node was down to the destination before the first interval ends.
+     */
+    start(): Promise<void>;
+    /**
+     * Takes one turn now. In a turn, Sirannon sends any staged capture, reads the
+     * frames written since the previous turn, and then checkpoints the log.
+     *
+     * At most one turn waits in the queue. A call during a turn in progress
+     * queues one turn after it, and every later call returns that queued turn,
+     * which reads the log when it begins and so captures the writes of every one
+     * of those callers. Without that limit, repeated calls during a long full
+     * copy would build a queue of turns with nothing left to capture.
+     *
+     * On a node whose replication group takes its backups from another node, a
+     * turn writes nothing and reports a skip.
+     *
+     * @returns The report of what the turn writes, or undefined where it writes nothing.
+     */
+    runOnce(): Promise<BackupRunReport | undefined>;
+    /**
+     * Stops the cycle after one final turn, so that Sirannon sends the writes
+     * made since the previous turn to the destination before the database closes.
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns every chain at the destination.
+     *
+     * @returns Every chain, newest first, each with its full copy and its change pieces.
+     */
+    chains(): Promise<BackupChain[]>;
+    /**
+     * Returns what the cycle is doing now and the outcome of its recent turns.
+     *
+     * It returns straight away, both during a long full copy and between turns.
+     *
+     * @returns Whether a turn is in progress, the progress of that turn, and the last run, skip, and failure.
+     */
+    status(): BackupCycleStatus;
+    /**
+     * Reads one backup from the destination and checks it against its record in
+     * the chains at that destination.
+     *
+     * @param name - The name that Sirannon stores the backup under.
+     * @returns The number of pieces read, their total size in bytes, and the fingerprint where the record holds one.
+     */
+    verify(name: string): Promise<BackupVerifyResult>;
+    /**
+     * Runs one turn and reports to the operator any error that stops it. Some
+     * deeper steps report a failure themselves before they throw it, so this
+     * reports an error only where no step has reported it already, and the
+     * operator receives each failure once. When the turn captures nothing and the
+     * log has grown past the limit, Sirannon then empties the log, and the
+     * resulting report of the writes that no backup holds replaces any failure
+     * that the turn recorded.
+     */
+    private runTurn;
+    /** The callbacks and paths that the stand-down code uses to release the chain of this cycle. */
+    private get standDownRequest();
+    /** Empties the log when this turn captures nothing from it and it has grown past the limit that the operator sets. */
+    private releaseLogPastLimit;
+    /**
+     * Returns whether this node takes the turn that it is starting. Where the
+     * replication group takes its backups from another node, this node stands
+     * down from its chain and empties its log. Where Sirannon cannot read the
+     * group, this node keeps its chain and its log as they are, because no backup
+     * holds the frames that it has yet to capture.
+     */
+    private takesTheTurn;
+    /** Reports a skipped turn when the decision carries a reason for it. */
+    private reportSkip;
+    private tick;
+    private verifyChain;
+    private discardState;
+    /**
+     * Runs one turn. When the turn fails with `BACKUP_LOG_REWOUND` or
+     * `BACKUP_CHAIN_BROKEN`, no later piece can extend the chain, so this starts a
+     * new chain. The caller still receives the error, because no backup holds the
+     * lost writes. Where the new chain also fails to start, Sirannon records that
+     * second failure against the broken chain, because the cycle holds no chain by
+     * then and the operator needs the status to name the chain that they lost.
+     */
+    private turnOrStartOver;
+    private turn;
+    /**
+     * Reports a failure to the operator and records it as the outcome of the
+     * turn, against the chain that the cycle holds now.
+     *
+     * @param err - The error that stops the turn.
+     */
+    private report;
+    /** Records a failure against a chain that the cycle may already have released. */
+    private reportAgainstChain;
+    private replaceChain;
+    private captureAndCheckpoint;
+    /**
+     * Sends the capture staged against the chain that this cycle holds. Once the
+     * destination refuses a capture, Sirannon skips the send for the rest of the
+     * turn, because a second try would wait out the destination deadline again
+     * and delay every turn queued after it.
+     */
+    private sendWaitingCapture;
+}
+
+/** The context that Sirannon passes to each query hook.
+ * @public
+ */
+interface QueryHookContext {
+    /** The identifier of the database that the statement executes against. */
+    databaseId: string;
+    /** The statement that is about to execute, or the one that has finished executing. */
+    sql: string;
+    /** The parameters bound to the statement. */
+    params?: Params;
+    /** Values for the hooks to read. */
+    metadata?: Record<string, unknown>;
+    /** The write concern that the caller set on the statement. */
+    writeConcern?: WriteConcern;
+    /** The read concern that the caller set on the statement. */
+    readConcern?: ReadConcern;
+}
+/** A hook that Sirannon calls synchronously before it executes each statement; throw from it to reject the statement. Sirannon also fails the statement when the hook returns a promise.
+ * @public
+ */
+type BeforeQueryHook = (ctx: QueryHookContext) => void;
+/** The context that Sirannon passes to each after-query hook, which adds the statement's duration and outcome to the query context.
+ * @public
+ */
+interface AfterQueryHookContext extends QueryHookContext {
+    /** The number of milliseconds from the start of the statement to its return, including any time that it waited for the writer. */
+    durationMs: number;
+    /** The error that the statement threw, which the caller also receives, or undefined when the statement succeeded. Every statement of a failed transaction receives that transaction's error. */
+    error?: unknown;
+}
+/** A hook that Sirannon calls synchronously after each statement returns or throws. Sirannon ignores an error that the hook throws and a promise that it returns, and calls the next hook either way.
+ * @public
+ */
+type AfterQueryHook = (ctx: AfterQueryHookContext) => void;
+/** The context that Sirannon passes to each connection hook.
+ * @public
+ */
+interface ConnectionHookContext {
+    /** The identifier of the database that Sirannon is opening or closing. */
+    databaseId: string;
+    /** The file path of the SQLite database. */
+    path: string;
+}
+/** A hook that Sirannon calls synchronously before it opens a database; throw from it to stop the open. Sirannon also fails the open when the hook returns a promise.
+ * @public
+ */
+type BeforeConnectHook = (ctx: ConnectionHookContext) => void;
+/** A hook that Sirannon calls synchronously once a database is open. Sirannon ignores an error that the hook throws and a promise that it returns, and calls the next hook either way.
+ * @public
+ */
+type DatabaseOpenHook = (ctx: ConnectionHookContext) => void;
+/** A hook that Sirannon calls synchronously once a database is closed. Sirannon ignores an error that the hook throws and a promise that it returns, and calls the next hook either way.
+ * @public
+ */
+type DatabaseCloseHook = (ctx: ConnectionHookContext) => void;
+/** A hook that the server calls before it creates a change subscription; throw from it to reject the subscription. A server with `acceptSql` off serves a table subscription only when the registry has this hook.
+ * @public
+ */
+type BeforeSubscribeHook = (ctx: {
+    /** The identifier of the database that the subscription is on. */
+    databaseId: string;
+    /** The table that the subscription is on. */
+    table: string;
+    /** The column values that a changed row must have for Sirannon to deliver the change to the subscriber. */
+    filter?: Record<string, unknown>;
+    /** The identity that the `authenticate` hook returned for the connection, or undefined when the hook returned none. */
+    identity?: unknown;
+    /** The identifier of the device that the subscription syncs, or undefined for a subscription without a device. */
+    deviceId?: string;
+}) => void | Promise<void>;
+/** A hook that the server calls before it reads each table into a snapshot; throw from it to reject the snapshot.
+ * @public
+ */
+type BeforeSnapshotHook = (ctx: {
+    /** The identifier of the database that the server copies into the snapshot. */
+    databaseId: string;
+    /** The table that the server is about to read. */
+    table: string;
+    /** The identity that the `authenticate` hook returned for the request, or undefined when the hook returned none. */
+    identity?: unknown;
+}) => void | Promise<void>;
+/** A hook that the server calls before it writes a batch that a device pushed, once for each table in the batch; throw from it to reject the whole batch.
+ * @public
+ */
+type BeforePushHook = (ctx: {
+    /** The identifier of the database that the server writes the batch to. */
+    databaseId: string;
+    /** The table that the server writes these changes to. */
+    table: string;
+    /** The identifier of the device that sent the batch. */
+    deviceId: string;
+    /** The identity that the `authenticate` hook returned for the request, or undefined when the hook returned none. */
+    identity?: unknown;
+}) => void | Promise<void>;
+/** The hooks that Sirannon calls for every database in a registry, keyed by event.
+ * @public
+ */
+interface HookConfig {
+    /** Sirannon calls this before each statement; throw from it to reject the statement. */
+    onBeforeQuery?: BeforeQueryHook | BeforeQueryHook[];
+    /** Sirannon calls this after each statement, with the statement's duration. */
+    onAfterQuery?: AfterQueryHook | AfterQueryHook[];
+    /** Sirannon calls this before it opens a database. */
+    onBeforeConnect?: BeforeConnectHook | BeforeConnectHook[];
+    /** Sirannon calls this once a database is open. */
+    onDatabaseOpen?: DatabaseOpenHook | DatabaseOpenHook[];
+    /** Sirannon calls this once a database is closed. */
+    onDatabaseClose?: DatabaseCloseHook | DatabaseCloseHook[];
+    /** The server calls this before it creates a change subscription; throw from it to reject the subscription. */
+    onBeforeSubscribe?: BeforeSubscribeHook | BeforeSubscribeHook[];
+    /** The server calls this before it reads each table into a snapshot; throw from it to reject the snapshot. */
+    onBeforeSnapshot?: BeforeSnapshotHook | BeforeSnapshotHook[];
+    /** The server calls this before it writes a batch that a device pushed; throw from it to reject the batch. */
+    onBeforePush?: BeforePushHook | BeforePushHook[];
+}
+
+/** The metrics that Sirannon reports after each statement finishes.
+ * @public
+ */
+interface QueryMetrics {
+    /** The identifier of the database that the statement executed against. */
+    databaseId: string;
+    /** The statement that executed. */
+    sql: string;
+    /** The statement's duration, in milliseconds. */
+    durationMs: number;
+    /** The number of rows that a read returns, and absent for a write or a failed statement. */
+    rowsReturned?: number;
+    /** The number of rows that a write changes, and absent for a read or a failed statement. */
+    changes?: number;
+    /** True when the statement threw. */
+    error?: boolean;
+}
+/** The metrics that Sirannon reports when the registry opens or closes a database.
+ * @public
+ */
+interface ConnectionMetrics {
+    /** The identifier of the database that the registry opened or closed. */
+    databaseId: string;
+    /** The file path of the SQLite database. */
+    path: string;
+    /** The number of read connections in the database's pool, which is 0 on close. */
+    readerCount: number;
+    /** Whether the registry opened or closed the database. */
+    event: 'open' | 'close';
+}
+/** The metrics for one change event and its delivery to subscribers.
+ * @public
+ */
+interface CDCMetrics {
+    /** The identifier of the database that the change comes from. */
+    databaseId: string;
+    /** The table that contains the changed row. */
+    table: string;
+    /** Whether the change inserted, updated, or deleted the row. */
+    operation: ChangeOperation;
+    /** The number of subscribers whose filter matches the event and that Sirannon delivers it to, which is zero when none matches. */
+    subscriberCount: number;
+}
+/** The callbacks that receive Sirannon's metrics.
+ * @public
+ */
+interface MetricsConfig {
+    /** Sirannon calls this once each statement finishes, whether the statement succeeded or threw. */
+    onQueryComplete?: (metrics: QueryMetrics) => void;
+    /** Sirannon calls this when the registry opens a database. */
+    onConnectionOpen?: (metrics: ConnectionMetrics) => void;
+    /** Sirannon calls this when the registry closes a database. */
+    onConnectionClose?: (metrics: ConnectionMetrics) => void;
+    /** The callback for each change event that Sirannon dispatches to a database's subscribers, both those of `Database.on` and those of a server's WebSocket connections. */
+    onCDCEvent?: (metrics: CDCMetrics) => void;
+}
+
+/**
+ * Executes statements inside one transaction; Sirannon passes it to the function that you give {@link Database.transaction}.
+ *
+ * @public
+ */
+declare class Transaction {
+    private readonly conn;
+    private _lastInsertRowId;
+    constructor(conn: SQLiteConnection);
+    /**
+     * Executes a read inside this transaction.
+     *
+     * @param sql - The statement to execute.
+     * @param params - The values to bind to the statement, named or positional.
+     * @returns The rows that the statement returns.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: Params): Promise<T[]>;
+    /**
+     * Executes one write inside this transaction.
+     *
+     * @param sql - The statement to execute.
+     * @param params - The values to bind to the statement, named or positional.
+     * @returns The number of rows that the statement changed, and the row id of the last inserted row.
+     */
+    execute(sql: string, params?: Params): Promise<ExecuteResult>;
+    /**
+     * Executes one statement once for each parameter set, inside this transaction.
+     *
+     * @param sql - The statement to execute for each parameter set.
+     * @param paramsBatch - One parameter set for each execution.
+     * @returns One result per parameter set, in order.
+     */
+    executeBatch(sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
+    /**
+     * The row id that SQLite assigned to the last row that this transaction inserted.
+     */
+    get lastInsertRowId(): number | bigint;
+    /** @internal */
+    static run<T>(conn: SQLiteConnection, fn: (tx: Transaction) => Promise<T>): Promise<T>;
+}
+
+/** Matches a valid migration name, which uses only letters, digits, and underscores.
+ * @public
+ */
+declare const MIGRATION_NAME_RE: RegExp;
+/**
+ * Marks a migration as a baseline, which a new database runs in place of every
+ * version up to and including `through`. A database that already has migration
+ * history skips the baseline and applies only the versions that it lacks.
+ *
+ * @public
+ */
+interface MigrationBaseline {
+    /** The highest earlier version that a new database skips in favour of the baseline. */
+    through: number;
+}
+/** Describes one schema change, with the statements that apply it and the statements that undo it.
+ * @public
+ */
+interface Migration {
+    /** The version number, which sets the ascending order in which the runner applies migrations. */
+    version: number;
+    /** The migration's name, which uses only letters, digits, and underscores. */
+    name: string;
+    /** The SQL that applies the change, or a function that applies it inside the migration's transaction. */
+    up: string | ((tx: Transaction) => void | Promise<void>);
+    /** The SQL that undoes the change, or a function that undoes it. Rollback throws a `MIGRATION_NO_DOWN` error for a migration without it. */
+    down?: string | ((tx: Transaction) => void | Promise<void>);
+    /** Marks this migration as a baseline, which a new database runs in place of the earlier versions. */
+    baseline?: MigrationBaseline;
+}
+/** The migrations to apply, as an array or as a function that returns one.
+ * @public
+ */
+type MigrationSource = Migration[] | (() => Migration[] | Promise<Migration[]>);
+/** Identifies one migration in a migration or rollback result.
+ * @public
+ */
+interface AppliedMigrationEntry {
+    /** The migration's version number. */
+    version: number;
+    /** The migration's name. */
+    name: string;
+}
+/** Describes the outcome of one migrate call.
+ * @public
+ */
+interface MigrationResult {
+    /** The migrations that this call applied, in the order that it applied them. */
+    applied: AppliedMigrationEntry[];
+    /** The number of input migrations that this call skipped, because the database already had them or a baseline replaces them. */
+    skipped: number;
+}
+/** Describes the outcome of one rollback call.
+ * @public
+ */
+interface RollbackResult {
+    /** The migrations that this call undid, newest first. */
+    rolledBack: AppliedMigrationEntry[];
+}
+
+/** One node that a client can read from, and the read concerns that the node meets now.
+ * @public
+ */
+interface ClusterReadEndpointInfo {
+    /** The identifier of the node at this endpoint. */
+    nodeId: string;
+    /** The address that a client sends its reads to. */
+    endpoint: string;
+    /** The read concerns that this node meets now. */
+    readConcerns: ReadConcernLevel[];
+}
+/** Every value that a node can report as its health state.
+ * @public
+ */
+declare const NODE_HEALTH_STATES: readonly ["healthy", "degraded", "failing_over", "repairing", "syncing", "unavailable"];
+/** The word that names what a node can do now.
+ * @public
+ */
+type NodeHealthState = (typeof NODE_HEALTH_STATES)[number];
+/** The condition behind a {@link NodeHealthState}.
+ * @public
+ */
+type NodeHealthReason = (typeof NODE_HEALTH_REASONS)[number];
+/** Every value that a node can report as the reason for its health state.
+ * @public
+ */
+declare const NODE_HEALTH_REASONS: readonly ["in-sync", "lagging", "coordinator-unreachable", "draining", "repairing", "faulted", "sync-pending", "no-group-state"];
+/**
+ * The health of the one node that reports it.
+ *
+ * `canRead` and `canWrite` are true when that node accepts reads and writes
+ * now, and `state` and `reason` name the condition behind them.
+ *
+ * @public
+ */
+interface NodeHealth {
+    /** What the node can do now. */
+    state: NodeHealthState;
+    /** The condition behind that state. */
+    reason: NodeHealthReason;
+    /** Whether the node serves reads now. */
+    canRead: boolean;
+    /** Whether the node accepts writes now. */
+    canWrite: boolean;
+}
+/** What one node reports about its replication group, which `GET /db/{id}/cluster` returns.
+ * @public
+ */
+interface ClusterStatusInfo {
+    /** The identifier of the database that this status describes. */
+    databaseId: string;
+    /** The identifier of the node's replication group. */
+    replicationGroupId?: string;
+    /** Whether this node is the primary, which accepts writes, or a replica, which serves reads. */
+    role?: 'primary' | 'replica';
+    /** The primary that this node reports as current, or null when the node reports none. */
+    currentPrimary?: {
+        nodeId: string;
+        endpoint?: string;
+    } | null;
+    /** The primary term that this node reports as current. */
+    primaryTerm?: bigint;
+    /** Every node that a client can read from, with the read concerns that each one meets. */
+    readEndpoints?: ClusterReadEndpointInfo[];
+    /** What this node can do now. */
+    health: NodeHealthState;
+    /** The condition behind that health state. */
+    healthReason: NodeHealthReason;
+}
+/** The settings for opening and closing databases automatically.
+ * @public
+ */
+interface LifecycleConfig {
+    /** Opens a database the first time that a caller asks {@link Sirannon.resolve} for an identifier that has no open database. */
+    autoOpen?: {
+        resolver: (id: string) => {
+            path: string;
+            options?: DatabaseOptions;
+        } | undefined;
+    };
+    /** The number of idle milliseconds after which the registry closes a database; 0 turns idle closing off. */
+    idleTimeout?: number;
+    /** The most databases open at once before an automatic open evicts the least recently used one; 0 sets no limit. */
+    maxOpen?: number;
+}
+/** The options for opening one database.
+ * @public
+ */
+interface DatabaseOptions {
+    /** Whether to open the database in read-only mode. */
+    readOnly?: boolean;
+    /** The number of read connections in the pool; the default is 4. */
+    readPoolSize?: number;
+    /** Whether to open the database in WAL mode; the default is true. */
+    walMode?: boolean;
+    /**
+     * The writer's `PRAGMA synchronous` level; the default is 'normal'. Sirannon
+     * restores this level after every bulk load.
+     */
+    synchronous?: SynchronousLevel;
+    /** How often Sirannon polls the change log, in milliseconds; the default is 50. */
+    cdcPollInterval?: number;
+    /** How long Sirannon keeps change-log entries, in milliseconds; the default is 3_600_000, one hour. */
+    cdcRetention?: number;
+    /**
+     * How long, in milliseconds, Sirannon keeps changes for a device's cursor.
+     * Sirannon drops the cursor when the cursor goes this long without an update,
+     * or when the oldest change that the device still needs reaches this age. The
+     * default is 2_592_000_000, 30 days.
+     */
+    deviceCursorRetention?: number;
+    /**
+     * The most changes that Sirannon keeps for one device's cursor. Sirannon
+     * drops the cursor of a device that falls further behind than this, and that
+     * device then downloads the database again when it reconnects. 0 sets no
+     * limit, and the default is 0.
+     */
+    maxChangesHeldForDevice?: number;
+    /**
+     * Whether to execute writes on a dedicated worker thread, so that disk
+     * flushes never block the thread that serves connections, while reads stay
+     * on the calling thread. The driver needs a worker entry, which the
+     * `better-sqlite3` and `node` drivers have, and with any other driver the open
+     * throws `WRITER_WORKER_UNSUPPORTED`. The default is off.
+     */
+    writerWorker?: boolean | WriterWorkerOptions;
+    /**
+     * Captures this database's write-ahead log to a destination that you supply,
+     * on an interval. Apart from the full copies, each capture sends only the log
+     * frames written since the previous capture, so its size follows how much
+     * the database changed.
+     *
+     * With this option, Sirannon turns off SQLite's automatic checkpoint and
+     * checkpoints the log itself after each capture, because a checkpoint lets
+     * SQLite overwrite log frames that no capture has read yet. The default is
+     * off.
+     */
+    backups?: BackupCycleOptions;
+}
+/** The limits and recovery settings for the writer worker thread.
+ * @public
+ */
+interface WriterWorkerOptions {
+    /** The number of writes allowed in flight before Sirannon rejects new writes with a `WriteOverloadError`; the default is 1024. */
+    maxPendingWrites?: number;
+    /** The deadline for each operation, in milliseconds; the default is 30000, and 0 turns it off. At the deadline, Sirannon asks the worker to cancel the operation, and when the worker gives no answer within a second deadline, Sirannon rejects the caller's promise while the worker continues, so the outcome of that write is unknown. */
+    writeTimeoutMs?: number;
+    /** How many times Sirannon restarts the worker after the worker crashes on its own, before writes fail permanently; the default is 5. */
+    maxRestarts?: number;
+}
+/** The options for a Sirannon database registry.
+ * @public
+ */
+interface SirannonOptions {
+    /** The SQLite driver that opens every database in this registry. */
+    driver: SQLiteDriver;
+    /** The hooks that Sirannon calls for every database in this registry. */
+    hooks?: HookConfig;
+    /** The callbacks that receive Sirannon's metrics. */
+    metrics?: MetricsConfig;
+    /** The settings for automatic opening, idle closing, and the limit on open databases. */
+    lifecycle?: LifecycleConfig;
+    /** The migrations that Sirannon applies to each writable database in this registry as it opens. */
+    migrations?: MigrationSource;
+    /** The default writer-worker setting for the databases that this registry opens. */
+    writerWorker?: boolean | WriterWorkerOptions;
+    /** The default change-log retention, in milliseconds, for the databases that this registry opens. */
+    cdcRetention?: number;
+    /** The default device-cursor retention, in milliseconds, for the databases that this registry opens. */
+    deviceCursorRetention?: number;
+    /** The default limit on the changes that Sirannon keeps for one device's cursor, for the databases that this registry opens. */
+    maxChangesHeldForDevice?: number;
+}
+/** The options for scheduled backups.
+ * @public
+ */
+interface BackupScheduleOptions {
+    /** The cron expression, such as '0 * * * *' for every hour. */
+    cron: string;
+    /** The directory that Sirannon writes the backup files to. */
+    destDir: string;
+    /** The most backup files that Sirannon keeps; the default is 5. */
+    maxFiles?: number;
+    /**
+     * The IANA time zone, such as 'America/New_York', in which Sirannon evaluates
+     * the cron expression. When you omit it, Sirannon uses the host's local time
+     * zone and its daylight saving rules.
+     */
+    timezone?: string;
+    /**
+     * Sirannon calls this after each copy that the schedule finishes, with the
+     * file that it wrote and the copy's report. Use it to send the file to durable
+     * storage, or to record that the schedule is still working.
+     *
+     * Sirannon awaits the promise that this returns and deletes the older files
+     * only once that promise settles, so that it deletes no copy that your code
+     * is still uploading. Sirannon passes a failure of this callback, like a
+     * failed copy, to {@link BackupScheduleOptions.onError}, and
+     * {@link BackupScheduleOptions.onBackupTimeoutMs} limits the wait.
+     */
+    onBackup?: (report: BackupFileReport) => void | Promise<void>;
+    /**
+     * How many milliseconds {@link BackupScheduleOptions.onBackup} may take
+     * before Sirannon stops waiting for it; the default is 600_000, ten minutes,
+     * and 0 waits with no limit.
+     *
+     * Sirannon deletes the older files and takes the next copy once the callback
+     * settles or this deadline passes, so a callback that hangs on a socket
+     * delays the schedule by this long at most. Past the deadline, Sirannon
+     * reports the timeout through {@link BackupScheduleOptions.onError} and
+     * continues the schedule while your callback keeps working. Sirannon then
+     * counts that copy among the files that it may delete, so set this longer
+     * than your slowest upload.
+     */
+    onBackupTimeoutMs?: number;
+    /** Sirannon calls this when a scheduled backup fails, and discards the error when you omit it. */
+    onError?: (error: Error) => void;
+}
+
+/** Runs an operation while no other operation holds the writer, so that the copy has the writer connection to itself.
+ * @public
+ */
+type RunExclusive = (op: () => Promise<void>) => Promise<void>;
+/**
+ * The options of one repeating backup, plus the database details that Sirannon
+ * puts in every report of that backup.
+ *
+ * @public
+ */
+interface BackupScheduleRequest extends BackupScheduleOptions {
+    /** The identifier of the database that Sirannon copies. Defaults to the name of the source file without its extension. */
+    databaseId?: string;
+    /** The file that Sirannon copies. Defaults to the file that SQLite has open on the connection. */
+    sourcePath?: string;
+    /** Runs each copy while no other operation holds the writer. By default, Sirannon runs each copy without a lock. */
+    runExclusive?: RunExclusive;
+}
+
+interface WorkerHostOptions {
+    writeTimeoutMs?: number;
+    maxRestarts?: number;
+}
+
+/** Describes the result of one write through the driver.
+ * @public
+ */
+interface RunResult {
+    /** The number of rows that the statement inserted, updated, or deleted. */
+    changes: number;
+    /** The rowid that SQLite assigned to the last inserted row. */
+    lastInsertRowId: number | bigint;
+}
+/**
+ * Distinguishes a caller that runs inside the operation holding the writer
+ * from a caller that waits for the writer. A runtime needs async context
+ * tracking to make that distinction, and a wrong answer would run one
+ * caller's writes inside another caller's transaction.
+ */
+interface WriterContext {
+    /** Runs an operation and marks it as the one that holds the writer. */
+    run<T>(operation: () => T): T;
+    /** Returns `true` when the caller runs inside the operation that holds the writer. */
+    isActive(): boolean;
+    /** Runs an operation outside the held writer's context, so that its writes stay out of that transaction. */
+    exit<T>(operation: () => T): T;
+}
+/**
+ * Copies a database to a file or a destination, and schedules repeating copies.
+ *
+ * @internal
+ */
+interface BackupEngine {
+    /** Copies the connection's database to a destination path. */
+    backup(conn: SQLiteConnection, destPath: string, onFirstStep?: () => void): Promise<BackupFileCopy>;
+    /** Copies the connection's database to a destination that the caller supplies. */
+    copyToDestination(conn: SQLiteConnection, request: BackupRunRequest): Promise<BackupRunReport>;
+    /** Returns `true` when a full copy streams to the destination without a local file. */
+    streamsToDestination(): boolean;
+    /** Returns a backup cycle that captures the write-ahead log and then checkpoints it. */
+    createCycle(request: BackupCycleRequest): BackupCycle;
+    /** Starts a repeating backup and returns a function that stops it. */
+    schedule(conn: SQLiteConnection, request: BackupScheduleRequest): () => void;
+}
+/** Describes the progress after one step of a stepped database copy.
+ * @public
+ */
+interface DatabaseCopyStep {
+    /** The total number of pages to copy. */
+    totalPages: number;
+    /** The number of pages left to copy. */
+    remainingPages: number;
+}
+/** Describes the copy that Sirannon requests from a driver, and the number of pages in each step.
+ * @public
+ */
+interface DatabaseCopyRequest {
+    /** The path of the copy's destination file. */
+    destPath: string;
+    /** The number of pages that the driver copies in one step. */
+    pagesPerStep: number;
+    /**
+     * The driver calls this function after every step with that step's page
+     * counts. The function returns the number of pages for the next step, which
+     * a driver passes on when its runtime accepts a new count for each step. A
+     * return of zero pauses the copy until the caller catches up.
+     */
+    onStep?: (step: DatabaseCopyStep) => number;
+    /**
+     * The number of milliseconds without a step after which the caller stops
+     * waiting for the copy. A driver that steps the copy on another thread waits
+     * this long for that thread, so a longer timeout keeps a slow copy running.
+     * Zero removes the limit.
+     */
+    stallTimeoutMs?: number;
+}
+/** Holds the totals for one statement that the driver applies over many parameter sets.
+ * @public
+ */
+interface BatchSummary {
+    /** The number of parameter sets that the driver applied. */
+    rowsLoaded: number;
+    /** The number of rows that those statements inserted, updated, or deleted. */
+    changes: number;
+}
+/** A prepared statement that a driver returns, which you can run many times.
+ * @public
+ */
+interface SQLiteStatement {
+    /** Runs the statement and returns every row. */
+    all<T = unknown>(...params: unknown[]): Promise<T[]>;
+    /** Runs the statement and returns the first row, or undefined when the result is empty. */
+    get<T = unknown>(...params: unknown[]): Promise<T | undefined>;
+    /** Runs the statement as a write and returns the number of changed rows and the last inserted rowid. */
+    run(...params: unknown[]): Promise<RunResult>;
+    /**
+     * Runs the statement and returns every row with each integer as a `bigint`,
+     * skipping the narrowing that {@link SQLiteStatement.all} applies. The
+     * server's wire encoder narrows and tags integers in one pass, so reading raw
+     * rows saves the server a second pass over the data. When a driver omits this method,
+     * Sirannon calls {@link SQLiteStatement.all}, which gives the same result
+     * with the extra pass.
+     */
+    allRaw?<T = unknown>(...params: unknown[]): Promise<T[]>;
+}
+/**
+ * Describes the error from one failed unit of a grouped write.
+ *
+ * @internal
+ */
+interface GroupRunError {
+    /** The message that SQLite or the driver raised. */
+    message: string;
+    /** The name of the error class. */
+    name?: string;
+    /** The machine-readable code, when the driver supplies one. */
+    code?: string;
+}
+/**
+ * Describes the outcome of one unit in a grouped write.
+ *
+ * @internal
+ */
+type GroupRunOutcome = {
+    ok: true;
+    results: RunResult[];
+} | {
+    ok: false;
+    error: GroupRunError;
+};
+/** One open connection to a SQLite database.
+ * @public
+ */
+interface SQLiteConnection {
+    /** Runs one or more statements and returns no rows. */
+    exec(sql: string): Promise<void>;
+    /** Compiles a statement, so that the caller can run it many times. */
+    prepare(sql: string): Promise<SQLiteStatement>;
+    /** Runs a function inside one transaction, committing when it returns and rolling back when it throws. */
+    transaction<T>(fn: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
+    /** Closes the connection. */
+    close(): Promise<void>;
+    /**
+     * Loads a compiled SQLite extension into this connection through the
+     * runtime's own loading function, so that queries on this connection can
+     * call the extension's functions. SQLite registers those functions on the
+     * loading connection alone, so load the extension on every connection that
+     * calls them. When the runtime has no loading function, the returned promise
+     * rejects with an error that names the runtime.
+     */
+    loadExtension?(extensionPath: string): Promise<void>;
+    /**
+     * Copies this connection's database to a file through SQLite's stepped
+     * backup interface, so that writes on this connection can run between
+     * steps. SQLite restarts the copy whenever another connection writes to the
+     * source, so call this method on the writer connection. The driver throws a
+     * `BackupError` when a transaction is open on this connection, because
+     * SQLite would copy no pages and still report success. When the runtime has
+     * no stepped backup function, the method should reject with a
+     * `SirannonError` whose code is `BACKUP_UNSUPPORTED` and whose message names
+     * the runtime, as the Node driver does.
+     */
+    copyDatabase?(request: DatabaseCopyRequest): Promise<DatabaseCopyStep>;
+    /**
+     * `true` when the runtime steps this connection's copy on a thread other
+     * than the caller's. A copy on its own thread can pause until the caller
+     * catches up, while a pause on the caller's thread would block the only
+     * thread.
+     */
+    readonly copyRunsOffCallerThread?: boolean;
+    /** Runs one statement once for each parameter set and returns one result for each set. */
+    runBatch?(sql: string, paramsBatch: readonly unknown[][]): Promise<RunResult[]>;
+    /** Runs one statement once for each parameter set and returns only the totals. */
+    runBatchSummary?(sql: string, paramsBatch: readonly unknown[][]): Promise<BatchSummary>;
+    /**
+     * Runs several independent units in one transaction and returns one outcome
+     * for each unit, in order. A unit is one write or one whole transaction. A
+     * failed unit should leave the other units' writes intact.
+     */
+    runGroup?(units: readonly {
+        statements: readonly {
+            sql: string;
+            params?: readonly unknown[];
+            trusted?: boolean;
+        }[];
+    }[]): Promise<GroupRunOutcome[]>;
+}
+/**
+ * The SQLite `PRAGMA synchronous` level for a connection. In WAL mode,
+ * `normal` keeps the database free of corruption, but a power loss can lose
+ * the most recent commits. `full` syncs every commit to disk. `extra` also
+ * syncs the directory after SQLite deletes the rollback journal in DELETE
+ * journal mode, and it behaves like `full` in WAL mode. `off` passes writes to
+ * the operating system without syncing, so use it only for a bulk load that
+ * you can run again.
+ *
+ * @public
+ */
+type SynchronousLevel = 'off' | 'normal' | 'full' | 'extra';
+/** Settings with which a driver opens one database file.
+ * @public
+ */
+interface OpenOptions {
+    /** `true` to open the file for reads only. */
+    readonly?: boolean;
+    /** Puts the database in write-ahead logging mode unless set to `false`. */
+    walMode?: boolean;
+    /** The writer durability level for the connection. */
+    synchronous?: SynchronousLevel;
+    /**
+     * The number of frames in the write-ahead log at which SQLite checkpoints it
+     * automatically. Set it to zero when Sirannon captures the database's own
+     * log, because an automatic checkpoint lets SQLite overwrite frames that the
+     * backup has yet to capture.
+     *
+     * SQLite keeps this setting per connection, so a driver applies it on every
+     * open, including after a writer worker restarts.
+     */
+    walAutoCheckpoint?: number;
+}
+/** Describes what a driver's runtime supports.
+ * @public
+ */
+interface DriverCapabilities {
+    /** `true` when the runtime can open more than one connection to the same file. */
+    multipleConnections: boolean;
+    /** `true` when the runtime can load SQLite extensions. */
+    extensions: boolean;
+    /** `true` when the runtime can copy an open database through SQLite's stepped backup interface. */
+    steppedCopy: boolean;
+}
+/**
+ * Describes how a worker thread rebuilds the driver, since a function such as
+ * the driver's `open` cannot pass to another thread. The worker imports
+ * `specifier` and calls the factory named `exportName`, or the default export,
+ * with `config`. `specifier` should be importable from the worker, and
+ * `config` should be a value that `structuredClone` accepts.
+ *
+ * @public
+ */
+interface DriverWorkerEntry {
+    /** The module that the worker imports to rebuild the driver. */
+    specifier: string;
+    /** The name of the factory export that the worker calls, or the default export when unset. */
+    exportName?: string;
+    /** The value that the worker passes to that factory, which has to be a value that `structuredClone` accepts. */
+    config?: unknown;
+}
+/** Describes how Sirannon opens SQLite on one runtime.
+ * @public
+ */
+interface SQLiteDriver {
+    /** The features that this driver's runtime supports. */
+    readonly capabilities: DriverCapabilities;
+    /** Opens a database file and returns a connection to it. */
+    open(path: string, options?: OpenOptions): Promise<SQLiteConnection>;
+    /** The entry through which a worker thread rebuilds this driver. */
+    readonly worker?: DriverWorkerEntry;
+    /**
+     * Starts a worker thread for writes and returns a connection whose calls run
+     * on that thread. Only a driver whose runtime has threads implements this
+     * method, so a bundle for a runtime without threads leaves out the worker code.
+     */
+    startWriterHost?(path: string, options: OpenOptions, hostOptions?: WorkerHostOptions): Promise<SQLiteConnection>;
+    /** Returns the `WriterContext` that distinguishes the caller holding the writer from a caller waiting for it. */
+    createWriterContext?(): WriterContext;
+    /**
+     * Returns the engine that copies a database to a file. Sirannon passes the
+     * driver back in, so that the engine can open its own connection for a
+     * streamed copy, which loads the extension that moves the bytes.
+     */
+    createBackupEngine?(driver: SQLiteDriver): BackupEngine;
+    /**
+     * Returns an extension path in absolute form. When `load_extension` receives
+     * a bare name, the dynamic linker searches its own paths and can open a
+     * different library from the one that the operator named.
+     */
+    resolveExtensionPath?(extensionPath: string): string;
+}
+
+export { type BeforePushHook as $, type AfterQueryHook as A, type BackupDestination as B, DEFAULT_CHAIN_NAME as C, type DatabaseOptions as D, chainLogName as E, readBackupChains as F, verifyBackupRecord as G, type ClusterStatusInfo as H, type SQLiteConnection as I, type BackupFileCopy as J, type BackupRunRequest as K, type BackupScheduleRequest as L, type Migration as M, type NodeHealth as N, type BackupScheduleOptions as O, type DriverCapabilities as P, type BackupEngine as Q, type RunExclusive as R, type SQLiteDriver as S, Transaction as T, type SynchronousLevel as U, type LifecycleConfig as V, type MigrationResult as W, type RollbackResult as X, type AfterQueryHookContext as Y, type AppliedMigrationEntry as Z, type BatchSummary as _, type SirannonOptions as a, type BeforeSnapshotHook as a0, type BeforeSubscribeHook as a1, type CDCMetrics as a2, type ClusterReadEndpointInfo as a3, type ConnectionHookContext as a4, type ConnectionMetrics as a5, type DatabaseCopyRequest as a6, type DatabaseCopyStep as a7, type DriverWorkerEntry as a8, type HookConfig as a9, MIGRATION_NAME_RE as aa, type MetricsConfig as ab, type MigrationBaseline as ac, type MigrationSource as ad, NODE_HEALTH_REASONS as ae, NODE_HEALTH_STATES as af, type NodeHealthReason as ag, type NodeHealthState as ah, type OpenOptions as ai, type QueryHookContext as aj, type QueryMetrics as ak, type RunResult as al, type SQLiteStatement as am, type WriterWorkerOptions as an, type WorkerHostOptions as ao, type WriterContext as ap, type BeforeQueryHook as b, type BeforeConnectHook as c, type DatabaseOpenHook as d, type DatabaseCloseHook as e, type BackupRunReport as f, type BackupChain as g, type BackupChainBase as h, type BackupChainChange as i, type BackupChainPosition as j, type BackupChainRecord as k, BackupCycle as l, type BackupCycleError as m, type BackupCycleOptions as n, type BackupCycleStatus as o, type BackupFileReport as p, type BackupGroupMembership as q, type BackupGroupSource as r, type BackupLogPosition as s, type BackupNodePreference as t, type BackupPiece as u, type BackupProgress as v, type BackupSkip as w, type BackupSkipReason as x, type BackupToDestinationOptions as y, type BackupVerifyResult as z };