@platformatic/sqlite-js-stream 0.0.0-stage → 0.1.1

package/dist/replica.js

@@ -0,0 +1,1253 @@
+/**
+ * Replica manages replication of a single SQLite database (identified by its
+ * `path`) to a ReplicaClient.
+ *
+ * It reads the database + WAL directly from disk, writes level-0/level-9 LTX
+ * files into a local cache, uploads them to the client, tracks the replicated
+ * position, and can restore a database by merging LTX files. Mirrors
+ * litestream's `replica.go`, but is agnostic to the SQLite driver the
+ * application uses.
+ *
+ * For snapshot consistency it opens its own **independent read-only** SQLite
+ * connection (never the application's writable one) to pin the WAL while it
+ * reads. A single SQLite connection holds one transaction at a time, so
+ * reusing an application `DatabaseSync` handle would merge the read snapshot
+ * with the app's writes (and could read uncommitted rows). Keep the app's
+ * writer and the library's reader on separate connections to the same file.
+ */
+import { createReadStream } from 'node:fs';
+import { access, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import nodePath from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { lockPgno, StreamLtxReader, StreamingCompactor, CompactionLevels, nextCompactionAt, prevCompactionAt, defaultCompactionLevels, DefaultL0RetentionCheckIntervalMs, } from "./ltx/index.js";
+import { LocalDatabase } from "./db.js";
+import { SnapshotLevel } from "./replica-client.js";
+import { DefaultLeaseRenewalBuffer, ErrLeaseNotHeld, Lease, LeaseExistsError, } from "./leaser.js";
+import { FileSink } from "./util/fs.js";
+import { noopLogger } from "./util/logger.js";
+import { DatabaseError, InvalidArgumentError, LTXFormatError, PageSizeMismatchError, SqliteJsStreamError, } from "./errors.js";
+/**
+ * Base class for errors thrown by {@link Replica.follow}. Carries a stable,
+ * Node-style `code` so callers can branch on the failure without matching
+ * message text, and can be caught via `instanceof`.
+ */
+export class FollowError extends SqliteJsStreamError {
+    constructor(code, message) {
+        super(code, message);
+        this.name = 'FollowError';
+    }
+}
+/** The database exists but its `-txid` sidecar is missing, so we can't resume. */
+export class FollowMissingTxidError extends FollowError {
+    constructor(message) {
+        super('ERR_FOLLOW_DB_WITHOUT_TXID', message);
+        this.name = 'FollowMissingTxidError';
+    }
+}
+/** The `-txid` sidecar is present but does not parse as a TXID. */
+export class FollowInvalidTxidError extends FollowError {
+    constructor(message) {
+        super('ERR_FOLLOW_INVALID_TXID', message);
+        this.name = 'FollowInvalidTxidError';
+    }
+}
+/** The saved TXID is ahead of anything the replica holds; re-restore. */
+export class FollowAheadOfLatestError extends FollowError {
+    constructor(message) {
+        super('ERR_FOLLOW_AHEAD_OF_LATEST', message);
+        this.name = 'FollowAheadOfLatestError';
+    }
+}
+/** The saved TXID is below the retained window; retention pruned the next file. */
+export class FollowDataGapError extends FollowError {
+    constructor(message) {
+        super('ERR_FOLLOW_OLDER_THAN_EARLIEST', message);
+        this.name = 'FollowDataGapError';
+    }
+}
+/** Follow was aborted before the initial restore could complete. */
+export class FollowAbortedError extends FollowError {
+    constructor(message) {
+        super('ERR_FOLLOW_ABORTED', message);
+        this.name = 'FollowAbortedError';
+    }
+}
+/**
+ * Default highest LTX compaction level (L0 -> L1 -> ... -> L{max}) for the
+ * legacy {@link CompactOptions.maxLevel} path. Prefer {@link CompactionLevels}.
+ */
+export const DefaultMaxCompactionLevel = 3;
+/** Returned by compaction scheduling when there is nothing to compact. */
+export class ErrNoCompactionError extends SqliteJsStreamError {
+    constructor() {
+        super('ERR_NO_COMPACTION', 'no files to compact');
+        this.name = 'ErrNoCompactionError';
+    }
+}
+export const ErrNoCompaction = new ErrNoCompactionError();
+/** Returned when a level was already compacted within its current time bucket. */
+export class ErrCompactionTooEarlyError extends SqliteJsStreamError {
+    constructor() {
+        super('ERR_COMPACTION_TOO_EARLY', 'compaction scheduled too early');
+        this.name = 'ErrCompactionTooEarlyError';
+    }
+}
+export const ErrCompactionTooEarly = new ErrCompactionTooEarlyError();
+/** Raised when a restore/plan cannot find LTX files at or below the target. */
+export class NoMatchingBackupError extends SqliteJsStreamError {
+    constructor(message = 'no matching backup files available') {
+        super('ERR_NO_MATCHING_BACKUP', message);
+        this.name = 'NoMatchingBackupError';
+    }
+}
+/** Constant intervals for compaction levels beyond the 4-level default. */
+const HIGHER_LEVEL_INTERVAL_MS = 3_600_000;
+/** Default intervals for levels 1..3 (matches litestream's defaults). */
+const DEFAULT_LEVEL_INTERVALS = [30_000, 300_000, 3_600_000];
+/** Builds a CompactionLevels covering levels 0..max with sane intervals. */
+function compactionLevelsForMax(max) {
+    const arr = [];
+    for (let i = 0; i <= max; i++) {
+        const intervalMs = i === 0 ? 0 : (DEFAULT_LEVEL_INTERVALS[i - 1] ?? HIGHER_LEVEL_INTERVAL_MS);
+        arr.push({ level: i, intervalMs });
+    }
+    return new CompactionLevels(arr);
+}
+/** Replica replicates a single database (by path) to a ReplicaClient. */
+export class Replica {
+    path;
+    client;
+    logger;
+    posValue = null;
+    db = null;
+    compactionLevelsValue = defaultCompactionLevels();
+    leaserValue = null;
+    leasePrimary = true;
+    leaseCurrent = null;
+    leaseTimer = null;
+    runActive = false;
+    constructor(path, client, logger = noopLogger, options = {}) {
+        this.path = path;
+        this.client = client;
+        this.logger = logger;
+        if (options.compactionLevels) {
+            this.compactionLevelsValue = options.compactionLevels;
+        }
+        else if (options.maxLevel !== undefined) {
+            this.maxCompactionLevel = options.maxLevel;
+        }
+        if (options.leaser) {
+            this.leaserValue = options.leaser;
+            // A leaser is not held until acquired, so a fresh replica starts as a
+            // follower until {@link run} (or an explicit acquire) makes it primary.
+            this.leasePrimary = false;
+        }
+    }
+    /** Leaser optionally bounds this replica to a single primary across hosts. */
+    get leaser() {
+        return this.leaserValue;
+    }
+    set leaser(leaser) {
+        this.leaserValue = leaser;
+        // Mirror the constructor: a newly set leaser is not held until acquired.
+        // While running, {@link run} owns the primary state.
+        if (!this.runActive)
+            this.leasePrimary = leaser === null;
+    }
+    /**
+     * IsPrimary reports whether this replica may currently write. Always true
+     * when no {@link Leaser} is configured; false while another host holds the
+     * lease. Updated by {@link run}.
+     */
+    isPrimary() {
+        return this.leasePrimary;
+    }
+    /** @internal Throws if a leaser is set but this replica does not hold it. */
+    assertCanWrite() {
+        if (this.leaserValue !== null && !this.leasePrimary) {
+            throw new ErrLeaseNotHeld();
+        }
+    }
+    /** Per-level compaction schedule. Defaults to {@link defaultCompactionLevels}. */
+    get compactionLevels() {
+        return this.compactionLevelsValue;
+    }
+    set compactionLevels(levels) {
+        this.compactionLevelsValue = levels;
+    }
+    /** Highest non-snapshot compaction level this replica will produce. */
+    get maxCompactionLevel() {
+        return this.compactionLevelsValue.maxLevel();
+    }
+    set maxCompactionLevel(level) {
+        this.compactionLevelsValue = compactionLevelsForMax(level);
+    }
+    /** Lazily opens the local database reader (cached). */
+    async localDb() {
+        if (this.db === null) {
+            this.db = await LocalDatabase.open(this.path);
+        }
+        return this.db;
+    }
+    /** Pos returns the current replicated position (max level-0 maxTXID). */
+    async pos() {
+        if (this.posValue === null) {
+            this.posValue = await this.calcPos();
+        }
+        return this.posValue;
+    }
+    /**
+     * CalcPos finds the maximum TXID on the replica across all levels. Since
+     * compaction moves the newest data to higher levels and prunes level-0, the
+     * position must be derived from every level (and any snapshot).
+     */
+    async calcPos() {
+        let max = 0n;
+        for (let level = 0; level <= SnapshotLevel; level++) {
+            for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+                if (info.maxTXID > max)
+                    max = info.maxTXID;
+            }
+        }
+        return max;
+    }
+    /** LocalPos returns the local cached position (max local level-0 maxTXID). */
+    async localPos() {
+        return (await this.localDb()).pos();
+    }
+    /**
+     * Sync builds a level-0 LTX file locally (if there are new WAL changes) and
+     * uploads any pending local files to the client. Returns the file that was
+     * written locally, or null if there was nothing new to do.
+     */
+    async sync() {
+        this.assertCanWrite();
+        await this.client.init();
+        const db = await this.localDb();
+        const info = await db.sync();
+        const dbPos = await db.pos();
+        const remotePos = await this.pos();
+        for (let txID = remotePos + 1n; txID <= dbPos; txID = (await this.pos()) + 1n) {
+            await this.uploadLtxFile(0, txID, txID);
+            this.posValue = txID;
+        }
+        return info;
+    }
+    /** SyncAndWait uploads all pending LTX files; harmless if already synced. */
+    async syncAndWait() {
+        await this.sync();
+    }
+    /**
+     * Run continuously drives the replica until `signal` is aborted. It syncs on
+     * `intervalMs`, compacts per level on each level's wall-clock bucket, takes
+     * snapshots on `snapshotIntervalMs`, and enforces retention. Errors are logged
+     * and the loop keeps going, so a transient failure does not stop replication.
+     *
+     * Compaction mirrors litestream: each level is compacted at most once per
+     * bucket (see {@link CompactionLevels}); the legacy `compactionIntervalMs`
+     * cascades all levels on a fixed interval instead.
+     */
+    async run(opt = {}) {
+        const { intervalMs = 1000, signal } = opt;
+        if (opt.maxLevel !== undefined)
+            this.maxCompactionLevel = opt.maxLevel;
+        const levels = opt.compactionLevels ?? this.compactionLevels;
+        const useLegacyCompaction = (opt.compactionIntervalMs ?? 0) > 0;
+        const compactionIntervalMs = opt.compactionIntervalMs ?? 0;
+        const retentionIntervalMs = opt.retentionIntervalMs ?? 0;
+        const snapshotIntervalMs = opt.snapshotIntervalMs ?? 0;
+        const l0RetentionMs = opt.l0RetentionMs ?? 0;
+        const l0RetentionCheckIntervalMs = opt.l0RetentionCheckIntervalMs ?? DefaultL0RetentionCheckIntervalMs;
+        // Try to acquire the lease up front. If held by another host we become a
+        // follower and poll until it is available. Without a leaser we are primary.
+        this.runActive = true;
+        const leaser = this.leaserValue;
+        let primary = leaser === null;
+        if (leaser !== null) {
+            try {
+                this.leaseCurrent = await leaser.acquireLease();
+                primary = true;
+                this.scheduleLeaseRenewal();
+            }
+            catch (err) {
+                if (err instanceof LeaseExistsError) {
+                    this.logger.debug('lease held elsewhere; running as follower', err);
+                    primary = false;
+                }
+                else {
+                    this.runActive = false;
+                    throw err;
+                }
+            }
+        }
+        this.leasePrimary = primary;
+        let lastCompaction = 0;
+        let lastRetention = 0;
+        let snapshotNext = snapshotIntervalMs > 0 ? nextCompactionAt(Date.now(), snapshotIntervalMs) : Infinity;
+        let l0RetentionNext = l0RetentionMs > 0 ? Date.now() + l0RetentionCheckIntervalMs : Infinity;
+        // Per-level next-bucket times (litestream-style scheduling).
+        const levelNext = new Map();
+        if (!useLegacyCompaction) {
+            for (const lvl of levels.toArray()) {
+                if (lvl.level > 0 && lvl.intervalMs > 0) {
+                    levelNext.set(lvl.level, nextCompactionAt(Date.now(), lvl.intervalMs));
+                }
+            }
+        }
+        while (!signal?.aborted) {
+            const now = Date.now();
+            // Follower management: poll to acquire the lease. The primary never
+            // renews here — a dedicated timer ({@link scheduleLeaseRenewal}) renews it
+            // independently of the loop cadence, so a large `intervalMs` cannot let the
+            // lease expire.
+            if (leaser !== null && !primary) {
+                try {
+                    this.leaseCurrent = await leaser.acquireLease();
+                    primary = true;
+                    this.leasePrimary = true;
+                    this.scheduleLeaseRenewal();
+                }
+                catch (err) {
+                    if (!(err instanceof LeaseExistsError)) {
+                        this.logger.error('lease acquire error', err);
+                    }
+                    await sleep(intervalMs, undefined, { signal });
+                    continue;
+                }
+            }
+            // Only the primary (or a leaser-less replica) performs writes.
+            if (leaser === null || primary) {
+                try {
+                    await this.sync();
+                }
+                catch (err) {
+                    this.logger.error('replica sync error', err);
+                }
+            }
+            if (signal?.aborted)
+                break;
+            if (leaser !== null && !primary) {
+                await sleep(intervalMs, undefined, { signal });
+                continue;
+            }
+            // Compaction.
+            if (useLegacyCompaction) {
+                if (compactionIntervalMs > 0 && now - lastCompaction >= compactionIntervalMs) {
+                    try {
+                        await this.compact();
+                    }
+                    catch (err) {
+                        this.logger.error('replica compaction error', err);
+                    }
+                    lastCompaction = Date.now();
+                }
+            }
+            else {
+                for (const [level, next] of levelNext) {
+                    if (now >= next) {
+                        try {
+                            await this.compactDB(level, now);
+                        }
+                        catch (err) {
+                            if (err !== ErrNoCompaction && err !== ErrCompactionTooEarly) {
+                                this.logger.error('replica compaction error', err);
+                            }
+                        }
+                        levelNext.set(level, nextCompactionAt(now, levels.level(level).intervalMs));
+                    }
+                }
+            }
+            // Snapshot + snapshot retention.
+            if (snapshotIntervalMs > 0 && now >= snapshotNext) {
+                try {
+                    await this.compactSnapshot(now, snapshotIntervalMs);
+                    const retention = opt.snapshotRetentionMs ?? 0;
+                    if (retention > 0 || (opt.snapshotRetain ?? 0) > 0) {
+                        await this.enforceSnapshotRetention(now, retention, opt.snapshotRetain ?? 0);
+                    }
+                }
+                catch (err) {
+                    this.logger.error('replica snapshot error', err);
+                }
+                snapshotNext = nextCompactionAt(now, snapshotIntervalMs);
+            }
+            // Retention (legacy interval-driven or L0 time-based).
+            if (retentionIntervalMs > 0 && now - lastRetention >= retentionIntervalMs) {
+                try {
+                    await this.enforceRetention(opt.retention ?? {});
+                }
+                catch (err) {
+                    this.logger.error('replica retention error', err);
+                }
+                lastRetention = Date.now();
+            }
+            if (l0RetentionMs > 0 && now >= l0RetentionNext) {
+                try {
+                    await this.enforceL0RetentionByTime(now, l0RetentionMs);
+                }
+                catch (err) {
+                    this.logger.error('replica l0 retention error', err);
+                }
+                l0RetentionNext = now + l0RetentionCheckIntervalMs;
+            }
+            if (signal?.aborted)
+                break;
+            try {
+                await sleep(intervalMs, undefined, { signal });
+            }
+            catch {
+                break; // aborted during the sleep
+            }
+        }
+        // Stop the renewal timer and release the lease so another host can take
+        // over promptly.
+        this.stopLeaseRenewal();
+        if (leaser !== null && this.leaseCurrent !== null) {
+            try {
+                await leaser.releaseLease(this.leaseCurrent);
+            }
+            catch (err) {
+                this.logger.debug('lease release error', err);
+            }
+            this.leaseCurrent = null;
+            this.leasePrimary = false;
+        }
+        this.runActive = false;
+    }
+    /**
+     * Schedules the next lease renewal to fire just before expiry, independent of
+     * the run-loop cadence. Reschedules after every successful renewal.
+     */
+    scheduleLeaseRenewal() {
+        this.stopLeaseRenewal();
+        if (this.leaserValue === null || this.leaseCurrent === null)
+            return;
+        const delay = Math.max(100, this.leaseCurrent.expiresAt - DefaultLeaseRenewalBuffer - Date.now());
+        this.leaseTimer = setTimeout(() => {
+            this.leaseTimer = null;
+            void this.renewLeaseLoop();
+        }, delay);
+    }
+    /** Renews the lease and reschedules; reverts to follower if we lost it. */
+    async renewLeaseLoop() {
+        if (!this.runActive || this.leaserValue === null || this.leaseCurrent === null)
+            return;
+        try {
+            this.leaseCurrent = await this.leaserValue.renewLease(this.leaseCurrent);
+            this.leasePrimary = true;
+            this.scheduleLeaseRenewal();
+        }
+        catch (err) {
+            if (err instanceof ErrLeaseNotHeld) {
+                this.logger.debug('lost lease; reverting to follower', err);
+                this.leasePrimary = false;
+                this.leaseCurrent = null;
+                this.stopLeaseRenewal();
+            }
+            else {
+                // Transient error: retry shortly rather than letting the lease expire.
+                this.logger.error('lease renew error', err);
+                this.scheduleLeaseRenewal();
+            }
+        }
+    }
+    /** Cancels any pending lease renewal. */
+    stopLeaseRenewal() {
+        if (this.leaseTimer !== null) {
+            clearTimeout(this.leaseTimer);
+            this.leaseTimer = null;
+        }
+    }
+    /** Snapshot writes and uploads a level-9 full-database LTX file. */
+    async snapshot() {
+        this.assertCanWrite();
+        const info = await (await this.localDb()).snapshot();
+        if (info) {
+            await this.uploadLtxFile(9, info.minTXID, info.maxTXID);
+        }
+        return info;
+    }
+    /** SyncStatus reports the local and remote positions. */
+    async syncStatus() {
+        const localTXID = await this.localPos();
+        const remoteTXID = await this.calcPos();
+        return { localTXID, remoteTXID, inSync: localTXID === remoteTXID };
+    }
+    /** Uploads a single local LTX file to the client. */
+    async uploadLtxFile(level, minTXID, maxTXID) {
+        const p = (await this.localDb()).ltxPath(level, minTXID, maxTXID);
+        // Stream the local LTX file straight to the client (no whole-file buffer).
+        const body = createReadStream(p);
+        const info = await this.client.writeLtxFile({ level, minTXID, maxTXID }, body);
+        this.logger.debug('ltx file uploaded', { level, minTXID, maxTXID, size: info.size });
+        return info;
+    }
+    /** EnsureExists restores the local database if it is missing. */
+    async ensureExists() {
+        try {
+            await access(this.path);
+            return;
+        }
+        catch {
+            /* missing; restore below */
+        }
+        await this.restore({ outputPath: this.path });
+    }
+    /** Restore reconstructs a SQLite database at `outputPath` from LTX files. */
+    async restore(opt) {
+        if (!opt.outputPath)
+            throw new InvalidArgumentError('output path required');
+        const plan = await calcRestorePlan(this.client, opt.txID ?? 0n);
+        if (plan.length === 0)
+            throw new NoMatchingBackupError();
+        await mkdir(nodePath.dirname(opt.outputPath), { recursive: true });
+        const tmp = `${opt.outputPath}.tmp`;
+        let fh = null;
+        const sources = [];
+        try {
+            fh = await open(tmp, 'w');
+            // The first plan file is the base (a snapshot). Stream its pages
+            // sequentially into the output, then overlay each later file's pages by
+            // offset, so a later version of a page wins. Peak memory stays bounded by
+            // one page buffer + the (small) page index, never the whole DB.
+            const openReader = (info) => this.openStreamReader(info, sources);
+            const base = await openReader(plan[0]);
+            await base.readHeader();
+            const pageSize = base.Header().pageSize;
+            let commit = base.Header().commit;
+            await writeSnapshotToFile(fh, base, pageSize, commit);
+            await base.verify();
+            for (let i = 1; i < plan.length; i++) {
+                const reader = await openReader(plan[i]);
+                await reader.readHeader();
+                const hdr = reader.Header();
+                if (hdr.pageSize !== pageSize) {
+                    throw new PageSizeMismatchError(`mismatched page sizes: ${pageSize} != ${hdr.pageSize}`);
+                }
+                commit = hdr.commit;
+                await overlayPagesToFile(fh, reader, pageSize);
+                await reader.verify();
+            }
+            // The final database size is the last file's committed page count.
+            await fh.truncate(commit * pageSize);
+            await fh.sync();
+            await fh.close();
+            fh = null;
+            await rename(tmp, opt.outputPath);
+        }
+        catch (err) {
+            if (fh !== null)
+                await fh.close().catch(() => { });
+            await rm(tmp, { force: true }).catch(() => { });
+            throw err;
+        }
+        finally {
+            // Release any not-yet-drained input streams (avoids leaking fds/connections
+            // on a corrupt/truncated backup). Destroying an ended stream is a no-op.
+            for (const s of sources) {
+                try {
+                    s.destroy?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    /**
+     * Follow continuously restores new LTX files into {@link FollowOptions.outputPath},
+     * keeping a read-only replica of the database up to date with the primary.
+     *
+     * On the first call (no output DB yet, or the replica is empty) it restores the
+     * latest backup as the base, then polls (every {@link FollowOptions.intervalMs})
+     * and applies any newly replicated LTX files as they appear. It records the
+     * applied TXID in a `-txid` sidecar after each batch so a later `follow()` can
+     * resume, and the loop runs until {@link FollowOptions.signal} is aborted.
+     *
+     * The restored database must only be opened **read-only**; writing to it while
+     * follow runs will conflict with the pages we overlay.
+     */
+    async follow(opt) {
+        const { outputPath, signal } = opt;
+        if (!outputPath)
+            throw new InvalidArgumentError('output path required');
+        const intervalMs = opt.intervalMs ?? 1000;
+        const txidPath = opt.txidFile ?? `${outputPath}-txid`;
+        if (intervalMs < 1)
+            throw new InvalidArgumentError('intervalMs must be >= 1');
+        // Determine the resume point. We must know the last applied TXID so we only
+        // apply files that come strictly after it. If the DB is missing we do a
+        // fresh latest restore; if it exists we require the -txid sidecar to know
+        // where to resume (otherwise we cannot prove the file matches the replica).
+        let currentMax;
+        let pageSize;
+        const dbExists = await statSafe(outputPath);
+        const txidExists = await statSafe(txidPath);
+        if (!dbExists) {
+            const plan = await this.waitForInitialRestore(outputPath, intervalMs, signal);
+            currentMax = plan[plan.length - 1].maxTXID;
+            await writeTxidFile(txidPath, currentMax);
+            pageSize = await readDbPageSize(outputPath);
+        }
+        else {
+            if (!txidExists) {
+                throw new FollowMissingTxidError(`database ${outputPath} exists but ${txidPath} is missing; ` +
+                    'delete the database and re-run follow');
+            }
+            const saved = await readTxidFile(txidPath);
+            if (saved === null)
+                throw new FollowInvalidTxidError(`invalid TXID in ${txidPath}`);
+            currentMax = saved;
+            pageSize = await readDbPageSize(outputPath);
+            await this.validateResumePoint(currentMax, outputPath, txidPath);
+        }
+        // Poll and apply new files until aborted. Batches are applied atomically-ish:
+        // overlay pages, truncate, fsync, THEN advance the -txid sidecar. If we crash
+        // mid-batch the sidecar is stale and the next run re-applies the same files
+        // (LTX files are immutable and page content is deterministic, so this is safe).
+        while (!signal?.aborted) {
+            const batch = await this.collectFollowBatch(currentMax);
+            if (batch.length > 0) {
+                currentMax = await this.applyFollowBatch(outputPath, batch, currentMax, pageSize);
+                await writeTxidFile(txidPath, currentMax);
+            }
+            if (signal?.aborted)
+                break;
+            try {
+                await sleep(intervalMs, undefined, { signal });
+            }
+            catch {
+                break; // aborted during the sleep
+            }
+        }
+    }
+    /**
+     * Guards a follow() resume against an inconsistent state: if the saved TXID is
+     * ahead of every TXID the replica holds, the DB/sidecar cannot be trusted and
+     * must be re-restored. (A saved TXID below the retained window is caught later
+     * as a data gap in {@link collectFollowBatch}.)
+     */
+    async validateResumePoint(saved, outputPath, txidPath) {
+        let latestMax = 0n;
+        for (let level = 0; level <= SnapshotLevel; level++) {
+            for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+                if (info.maxTXID > latestMax)
+                    latestMax = info.maxTXID;
+            }
+        }
+        if (latestMax !== 0n && saved > latestMax) {
+            throw new FollowAheadOfLatestError(`saved TXID ${hexTxid(saved)} is ahead of the latest snapshot ` +
+                `(${hexTxid(latestMax)}); delete ${outputPath} and ${txidPath} then re-restore`);
+        }
+    }
+    /**
+     * Waits for the first backup to appear on an empty replica, then restores it
+     * as the follow base. Returns the plan that was applied.
+     */
+    async waitForInitialRestore(outputPath, intervalMs, signal) {
+        for (;;) {
+            if (signal?.aborted)
+                throw new FollowAbortedError('aborted before the initial restore');
+            try {
+                const plan = await calcRestorePlan(this.client, 0n);
+                await this.restore({ outputPath });
+                return plan;
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                // An empty replica is the only case we retry; anything else is a real error.
+                if (!(err instanceof NoMatchingBackupError)) {
+                    throw err;
+                }
+                await sleep(intervalMs, undefined, { signal });
+            }
+        }
+    }
+    /**
+     * Returns the contiguous run of LTX files (across all compaction levels) that
+     * extend the applied position `currentMax`, in application order. Prefers the
+     * highest (most compacted) level for a range and stops at the first gap. Throws
+     * if the very next file (currentMax + 1) is missing, e.g. retention pruned it.
+     */
+    async collectFollowBatch(currentMax) {
+        const candidates = [];
+        for (let level = 0; level <= SnapshotLevel; level++) {
+            for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+                if (info.maxTXID <= currentMax)
+                    continue;
+                candidates.push(info);
+            }
+        }
+        candidates.sort((a, b) => a.minTXID !== b.minTXID ? (a.minTXID < b.minTXID ? -1 : 1) : b.level - a.level);
+        const batch = [];
+        let cursor = currentMax;
+        const seen = [];
+        for (const info of candidates) {
+            if (info.maxTXID <= cursor)
+                continue;
+            if (info.minTXID > cursor + 1n) {
+                if (batch.length === 0) {
+                    throw new FollowDataGapError(`saved TXID ${hexTxid(currentMax)} is older than the earliest ` +
+                        'retained snapshot; retention has pruned the required history; delete the ' +
+                        'database and re-restore');
+                }
+                break;
+            }
+            if (seen.some(([lo, hi]) => lo <= info.minTXID && info.maxTXID <= hi))
+                continue;
+            batch.push(info);
+            cursor = info.maxTXID;
+            seen.push([info.minTXID, info.maxTXID]);
+        }
+        return batch;
+    }
+    /**
+     * Applies a contiguous batch of LTX files to the existing `outputPath` DB by
+     * overlaying each file's pages (a later page wins) and truncating to the final
+     * commit size. Returns the TXID now applied.
+     */
+    async applyFollowBatch(outputPath, batch, currentMax, pageSize) {
+        const sources = [];
+        let fh = null;
+        let commit = 0;
+        let appliedMax = currentMax;
+        try {
+            fh = await open(outputPath, 'r+');
+            for (const info of batch) {
+                const reader = await this.openStreamReader(info, sources);
+                await reader.readHeader();
+                const hdr = reader.Header();
+                if (hdr.pageSize !== pageSize) {
+                    throw new PageSizeMismatchError(`mismatched page sizes: ${pageSize} != ${hdr.pageSize}`);
+                }
+                commit = hdr.commit;
+                await overlayPagesToFile(fh, reader, pageSize);
+                await reader.verify();
+                appliedMax = info.maxTXID;
+            }
+            await fh.truncate(commit * pageSize);
+            await fh.sync();
+            await fh.close();
+            fh = null;
+        }
+        catch (err) {
+            if (fh !== null)
+                await fh.close().catch(() => { });
+            throw err;
+        }
+        finally {
+            for (const s of sources) {
+                try {
+                    s.destroy?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        return appliedMax;
+    }
+    /** Opens a streaming LTX reader over a plan file from the client. */
+    async openStreamReader(info, sources) {
+        const rc = await this.client.openLtxFile({
+            level: info.level,
+            minTXID: info.minTXID,
+            maxTXID: info.maxTXID,
+            offset: 0,
+            size: 0,
+        });
+        if (sources && typeof rc.destroy === 'function') {
+            sources.push({ destroy: () => rc.destroy() });
+        }
+        return new StreamLtxReader(rc);
+    }
+    /** Close releases any internal database connection. */
+    close() {
+        if (this.db !== null) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+    /**
+     * Compact merges source LTX files into the next level. If `dstLevel` is
+     * given, compacts that level; otherwise compacts the first level (1..max)
+     * that has pending source files. Returns the written file, or null if there
+     * was nothing to compact.
+     */
+    async compact(options = {}) {
+        this.assertCanWrite();
+        if (options.dstLevel !== undefined) {
+            if (options.dstLevel < 1 || options.dstLevel > this.maxCompactionLevel)
+                return null;
+            return this.compactLevel(options.dstLevel);
+        }
+        for (let dst = 1; dst <= this.maxCompactionLevel; dst++) {
+            const info = await this.compactLevel(dst);
+            if (info)
+                return info;
+        }
+        return null;
+    }
+    /**
+     * CompactLevel compacts pending files at `dstLevel - 1` into a single file at
+     * `dstLevel`. It streams readers (local cache preferred, client fallback),
+     * writes the result locally via a file-backed sink, uploads it to the client,
+     * and returns the new file's metadata. Source files are left in place; GC is
+     * performed by {@link enforceRetention}.
+     */
+    async compactLevel(dstLevel) {
+        this.assertCanWrite();
+        if (dstLevel < 1 || dstLevel > this.maxCompactionLevel)
+            return null;
+        const srcLevel = dstLevel - 1;
+        // Determine the max TXID already present at the destination level; only
+        // source files after it remain to be compacted.
+        let dstMax = 0n;
+        for await (const info of this.client.ltxFiles({ level: dstLevel, seek: 0n, useMetadata: false })) {
+            if (info.maxTXID > dstMax)
+                dstMax = info.maxTXID;
+        }
+        const seek = dstMax + 1n;
+        const sources = [];
+        for await (const info of this.client.ltxFiles({ level: srcLevel, seek, useMetadata: false })) {
+            sources.push(info);
+        }
+        if (sources.length === 0)
+            return null;
+        let minTXID = sources[0].minTXID;
+        let maxTXID = sources[0].maxTXID;
+        for (const info of sources) {
+            if (info.minTXID < minTXID)
+                minTXID = info.minTXID;
+            if (info.maxTXID > maxTXID)
+                maxTXID = info.maxTXID;
+        }
+        if (minTXID < seek) {
+            throw new LTXFormatError(`compaction source ${minTXID}..${maxTXID} overlaps the destination max ${dstMax}`);
+        }
+        const cleanup = [];
+        const readers = [];
+        const db = await this.localDb();
+        const outPath = db.ltxPath(dstLevel, minTXID, maxTXID);
+        const tmpPath = `${outPath}.tmp`;
+        await mkdir(nodePath.dirname(outPath), { recursive: true });
+        const fh = await open(tmpPath, 'w');
+        try {
+            for (const info of sources) {
+                readers.push(await this.openSourceReader(info, cleanup));
+            }
+            const sink = new FileSink(fh);
+            const compactor = new StreamingCompactor(sink, readers);
+            await compactor.compact();
+            const cHeader = compactor.Header();
+            if (cHeader.pageSize !== (await this.localDb()).pageSize) {
+                throw new PageSizeMismatchError(`compacted page size ${cHeader.pageSize} does not match database ${(await this.localDb()).pageSize}`);
+            }
+            await sink.flush();
+            await fh.close();
+            await rename(tmpPath, outPath);
+            const size = (await stat(outPath)).size;
+            await this.uploadLtxFile(dstLevel, minTXID, maxTXID);
+            return { level: dstLevel, minTXID, maxTXID, size, createdAt: Date.now() };
+        }
+        catch (err) {
+            await fh.close().catch(() => { });
+            await rm(tmpPath, { force: true }).catch(() => { });
+            throw err;
+        }
+        finally {
+            for (const s of cleanup) {
+                try {
+                    s.destroy?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    /**
+     * CompactDB compacts `dstLevel` if it is time to do so and there is pending
+     * source data. Mirrors litestream's `Store.CompactDB`: it refuses to re-compact
+     * within the level's current time bucket (throws {@link ErrCompactionTooEarly})
+     * and skips when there is nothing to do (throws {@link ErrNoCompaction}).
+     */
+    async compactDB(dstLevel, now) {
+        this.assertCanWrite();
+        if (dstLevel === SnapshotLevel)
+            return this.compactSnapshot(now, 0);
+        const lvl = this.compactionLevels.level(dstLevel);
+        const prevAt = prevCompactionAt(now, lvl.intervalMs);
+        const dstInfo = await this.maxLTXFileInfo(dstLevel);
+        if (dstInfo && dstInfo.createdAt > prevAt)
+            throw ErrCompactionTooEarly;
+        const srcLevel = this.compactionLevels.prevLevel(dstLevel);
+        const srcInfo = await this.maxLTXFileInfo(srcLevel);
+        if (srcInfo && dstInfo && srcInfo.maxTXID <= dstInfo.minTXID)
+            throw ErrNoCompaction;
+        const info = await this.compactLevel(dstLevel);
+        if (info === null)
+            throw ErrNoCompaction;
+        return info;
+    }
+    /**
+     * CompactSnapshot takes a level-9 snapshot if it is time to do so and the
+     * database has advanced past the current snapshot. Mirrors `Store.CompactDB`
+     * for the snapshot level.
+     */
+    async compactSnapshot(now, intervalMs) {
+        this.assertCanWrite();
+        const prevAt = prevCompactionAt(now, intervalMs);
+        const dstInfo = await this.maxLTXFileInfo(SnapshotLevel);
+        if (dstInfo && dstInfo.createdAt > prevAt)
+            throw ErrCompactionTooEarly;
+        const pos = await (await this.localDb()).pos();
+        if (dstInfo && dstInfo.maxTXID !== 0n && dstInfo.maxTXID >= pos)
+            throw ErrNoCompaction;
+        return this.snapshot();
+    }
+    /** MaxLTXFileInfo returns the highest-TXID file at a level, or null. */
+    async maxLTXFileInfo(level) {
+        let max = null;
+        for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+            if (max === null || info.maxTXID > max.maxTXID)
+                max = info;
+        }
+        return max;
+    }
+    /**
+     * EnforceRetention prunes old snapshots and superseded files.
+     *
+     * 1. Snapshots older than `snapshotRetentionMs` are deleted (the newest is
+     *    always kept; `snapshotRetain` may cap how many newest are kept).
+     * 2. The resulting snapshot boundary is cascaded down through levels 0..max:
+     *    any file whose maxTXID is below the oldest retained snapshot's maxTXID
+     *    is deleted (it is superseded by that snapshot).
+     * 3. Level-0 files that have been compacted into a higher level and are older
+     *    than `l0RetentionMs` are deleted (except the newest, the live head).
+     */
+    async enforceRetention(options = {}) {
+        this.assertCanWrite();
+        const now = Date.now();
+        const snapshotRetentionMs = options.snapshotRetentionMs ?? 0;
+        const snapshotRetain = options.snapshotRetain ?? 0;
+        const l0RetentionMs = options.l0RetentionMs ?? 0;
+        const { deleted: snapshotsDeleted, boundary } = await this.enforceSnapshotRetention(now, snapshotRetentionMs, snapshotRetain);
+        let filesDeleted = 0;
+        if (boundary > 0n) {
+            for (let level = 0; level <= this.maxCompactionLevel; level++) {
+                filesDeleted += await this.enforceRetentionByTXID(level, boundary);
+            }
+        }
+        filesDeleted += await this.enforceL0RetentionByTime(now, l0RetentionMs);
+        return { snapshotsDeleted, filesDeleted, boundary };
+    }
+    /**
+     * EnforceSnapshotRetention deletes snapshots older than `retentionMs` and
+     * returns the boundary (max maxTXID of the deleted snapshots). The newest
+     * snapshot is always kept; `retain` may keep additional newest snapshots.
+     */
+    async enforceSnapshotRetention(now, retentionMs, retain = 0) {
+        this.assertCanWrite();
+        const snapshots = await this.listRemoteLevel(SnapshotLevel);
+        snapshots.sort((a, b) => (a.maxTXID < b.maxTXID ? -1 : a.maxTXID > b.maxTXID ? 1 : 0));
+        if (snapshots.length === 0)
+            return { deleted: 0, boundary: 0n };
+        const cutoff = retentionMs > 0 ? now - retentionMs : 0;
+        let retained = snapshots.filter((s) => !(retentionMs > 0 && s.createdAt < cutoff));
+        const newest = snapshots[snapshots.length - 1];
+        if (!retained.includes(newest))
+            retained.push(newest);
+        retained.sort((a, b) => (a.maxTXID < b.maxTXID ? -1 : a.maxTXID > b.maxTXID ? 1 : 0));
+        if (retain > 0 && retained.length > retain)
+            retained = retained.slice(retained.length - retain);
+        const retainedSet = new Set(retained);
+        const deletedFiles = snapshots.filter((s) => !retainedSet.has(s));
+        await this.deleteFiles(deletedFiles);
+        let boundary = 0n;
+        for (const d of deletedFiles)
+            if (d.maxTXID > boundary)
+                boundary = d.maxTXID;
+        return { deleted: deletedFiles.length, boundary };
+    }
+    /**
+     * EnforceRetentionByTXID deletes files at `level` with maxTXID below `txID`,
+     * always keeping at least one file. Returns the number deleted.
+     */
+    async enforceRetentionByTXID(level, txID) {
+        this.assertCanWrite();
+        if (txID <= 0n)
+            return 0;
+        const files = await this.listRemoteLevel(level);
+        files.sort((a, b) => (a.maxTXID < b.maxTXID ? -1 : a.maxTXID > b.maxTXID ? 1 : 0));
+        if (files.length === 0)
+            return 0;
+        const last = files[files.length - 1];
+        const deletedFiles = files.filter((f) => f.maxTXID < txID);
+        if (deletedFiles.length > 0 && deletedFiles[deletedFiles.length - 1] === last) {
+            deletedFiles.pop(); // always keep at least one file
+        }
+        await this.deleteFiles(deletedFiles);
+        return deletedFiles.length;
+    }
+    /**
+     * EnforceL0RetentionByTime deletes level-0 files that have been compacted into
+     * a higher level and are older than `l0RetentionMs`. It never deletes the
+     * newest level-0 file (the live head) and preserves contiguous L0 coverage by
+     * stopping at the first file that is not old enough.
+     */
+    async enforceL0RetentionByTime(now, l0RetentionMs) {
+        this.assertCanWrite();
+        const l0 = await this.listRemoteLevel(0);
+        l0.sort((a, b) => (a.maxTXID < b.maxTXID ? -1 : a.maxTXID > b.maxTXID ? 1 : 0));
+        if (l0.length === 0)
+            return 0;
+        const newest = l0[l0.length - 1];
+        const coverers = [];
+        for (let level = 1; level <= this.maxCompactionLevel; level++) {
+            for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+                coverers.push(info);
+            }
+        }
+        const threshold = now - l0RetentionMs;
+        const deletedFiles = [];
+        for (const info of l0) {
+            if (info === newest)
+                continue; // never delete the live head
+            if (info.createdAt > threshold)
+                break; // preserve contiguous L0 coverage
+            if (this.isCoveredByHigherLevel(info, coverers))
+                deletedFiles.push(info);
+        }
+        await this.deleteFiles(deletedFiles);
+        return deletedFiles.length;
+    }
+    /** Returns true if `info` is fully contained in a file at a higher level. */
+    isCoveredByHigherLevel(info, coverers) {
+        for (const g of coverers) {
+            if (g.level <= info.level)
+                continue;
+            if (g.minTXID <= info.minTXID && info.maxTXID <= g.maxTXID)
+                return true;
+        }
+        return false;
+    }
+    /** Lists LTX files at a remote level. */
+    async listRemoteLevel(level) {
+        const out = [];
+        for await (const info of this.client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+            out.push(info);
+        }
+        return out;
+    }
+    /** Deletes files from the client and the local cache. */
+    async deleteFiles(files) {
+        if (files.length === 0)
+            return;
+        this.logger.debug('deleting ltx files', { count: files.length });
+        await this.client.deleteLtxFiles(files);
+        const db = await this.localDb();
+        for (const f of files) {
+            const p = db.ltxPath(f.level, f.minTXID, f.maxTXID);
+            await rm(p, { force: true }).catch(() => { });
+        }
+    }
+    /**
+     * Opens a streaming LTX reader for a source file, preferring the local cache
+     * and falling back to the client. Collects cleanup callbacks for the streams.
+     */
+    async openSourceReader(info, cleanup) {
+        const db = await this.localDb();
+        const localPath = db.ltxPath(info.level, info.minTXID, info.maxTXID);
+        try {
+            await access(localPath);
+            const s = createReadStream(localPath);
+            cleanup.push({ destroy: () => s.destroy() });
+            return new StreamLtxReader(s);
+        }
+        catch {
+            /* fall back to the client */
+        }
+        const rc = await this.client.openLtxFile({
+            level: info.level,
+            minTXID: info.minTXID,
+            maxTXID: info.maxTXID,
+            offset: 0,
+            size: 0,
+        });
+        if (typeof rc.destroy === 'function') {
+            cleanup.push({ destroy: () => rc.destroy() });
+        }
+        return new StreamLtxReader(rc);
+    }
+}
+/**
+ * CalcRestorePlan returns LTX files to apply, in order, to reconstruct a
+ * database up to `txID` (0 = latest). It prefers the latest level-9 snapshot
+ * before the target as the base, then appends contiguous files across all
+ * compaction levels (0..maxLevel) that extend the range.
+ */
+export async function calcRestorePlan(client, txID) {
+    const plan = [];
+    let currentMax = 0n;
+    // Pick the latest level-9 snapshot at or before the target as the base.
+    let base = null;
+    for await (const info of client.ltxFiles({ level: SnapshotLevel, seek: 0n, useMetadata: false })) {
+        if (txID !== 0n && info.maxTXID > txID)
+            continue;
+        if (!base || info.maxTXID > base.maxTXID)
+            base = info;
+    }
+    if (base) {
+        plan.push(base);
+        currentMax = base.maxTXID;
+    }
+    // Collect candidate files from every compaction level (0..SnapshotLevel-1).
+    // Compaction moves data to higher levels, so a TXID range may be represented
+    // by a file at any level; gather them all and prefer the highest level first.
+    const candidates = [];
+    for (let level = 0; level < SnapshotLevel; level++) {
+        for await (const info of client.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+            if (txID !== 0n && info.maxTXID > txID)
+                continue;
+            candidates.push(info);
+        }
+    }
+    // Order by minTXID, then by higher level (more compacted) first, so a file
+    // at a higher level supersedes lower-level files spanning the same range.
+    candidates.sort((a, b) => {
+        if (a.minTXID !== b.minTXID)
+            return a.minTXID < b.minTXID ? -1 : 1;
+        return b.level - a.level;
+    });
+    const seenRanges = [];
+    for (const info of candidates) {
+        if (info.maxTXID <= currentMax)
+            continue; // covered by the base or earlier
+        if (info.minTXID > currentMax + 1n)
+            break; // non-contiguous gap
+        // Skip a candidate entirely covered by a higher-level file already in the plan.
+        if (seenRanges.some(([lo, hi]) => lo <= info.minTXID && info.maxTXID <= hi))
+            continue;
+        plan.push(info);
+        currentMax = info.maxTXID;
+        seenRanges.push([info.minTXID, info.maxTXID]);
+    }
+    if (plan.length === 0) {
+        throw new NoMatchingBackupError();
+    }
+    if (txID !== 0n && currentMax < txID) {
+        throw new NoMatchingBackupError();
+    }
+    return plan;
+}
+/**
+ * Streams a snapshot's pages (1..commit) into the output file. The lock page
+ * is written as a zeroed page (SQLite requires it to exist but never uses it).
+ */
+async function writeSnapshotToFile(fh, reader, pageSize, commit) {
+    const lockPg = lockPgno(pageSize);
+    const page = new Uint8Array(pageSize);
+    const zero = new Uint8Array(pageSize);
+    for (let pgno = 1; pgno <= commit; pgno++) {
+        if (pgno === lockPg) {
+            await writeAllAt(fh, zero, (pgno - 1) * pageSize);
+            continue;
+        }
+        const hdr = await reader.readPage(page);
+        if (hdr === null)
+            throw new LTXFormatError(`unexpected end of pages at pgno ${pgno}`);
+        if (hdr.pgno !== pgno) {
+            throw new LTXFormatError(`unexpected pgno while decoding page: read ${hdr.pgno}, expected ${pgno}`);
+        }
+        await writeAllAt(fh, page, (pgno - 1) * pageSize);
+    }
+    // Expect one final read to be the end-of-pages marker.
+    if ((await reader.readPage(page)) !== null) {
+        throw new LTXFormatError('unexpected page after end of database');
+    }
+}
+/** Overlays an incremental file's pages into the output file at their offsets. */
+async function overlayPagesToFile(fh, reader, pageSize) {
+    const page = new Uint8Array(pageSize);
+    for (;;) {
+        const hdr = await reader.readPage(page);
+        if (hdr === null)
+            break;
+        await writeAllAt(fh, page, (hdr.pgno - 1) * pageSize);
+    }
+}
+/** Writes all of `bytes` to `handle` at an absolute `position`, looping on partial writes. */
+async function writeAllAt(handle, bytes, position) {
+    let offset = 0;
+    while (offset < bytes.length) {
+        const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset, position + offset);
+        offset += bytesWritten;
+    }
+}
+/** Returns true if `path` exists. */
+async function statSafe(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Encodes a TXID as the 16-char lowercase hex used in LTX filenames. */
+function hexTxid(txid) {
+    return txid.toString(16).padStart(16, '0');
+}
+/** Decodes a (possibly trimmed) 1..16 char hex TXID; null on malformed input. */
+function decodeTxid(s) {
+    const t = s.trim();
+    if (!/^[0-9a-fA-F]{1,16}$/.test(t))
+        return null;
+    try {
+        return BigInt(`0x${t}`);
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads the last applied TXID from a follow sidecar file, or null if absent/invalid. */
+async function readTxidFile(path) {
+    try {
+        return decodeTxid(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically writes the applied TXID to a follow sidecar file (temp + rename). */
+async function writeTxidFile(path, txid) {
+    const tmp = `${path}.tmp`;
+    await mkdir(nodePath.dirname(path), { recursive: true });
+    const fh = await open(tmp, 'w');
+    try {
+        await fh.writeFile(hexTxid(txid) + '\n');
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmp, path);
+}
+/** Reads the SQLite page size from a database file header (offset 16, BE 16-bit). */
+async function readDbPageSize(path) {
+    const fh = await open(path, 'r');
+    try {
+        const buf = Buffer.alloc(4);
+        const { bytesRead } = await fh.read(buf, 0, 4, 16);
+        if (bytesRead !== 4)
+            throw new DatabaseError(`cannot read database header of ${path}`);
+        const raw = buf.readUInt16BE(0);
+        // SQLite encodes a 64 KiB page size as 1.
+        return raw === 1 ? 65536 : raw;
+    }
+    finally {
+        await fh.close();
+    }
+}