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

package/dist/replica-client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ReplicaClient interface and shared helpers for interacting with a replica
+ * (an LTX destination). Mirrors litestream's `replica_client.go`.
+ *
+ * The interface is async/iterable oriented rather than Go's iterator/readcloser
+ * model, but the semantics match:
+ *  - ltxFiles returns LTX file metadata for a level, optionally seeking by TXID.
+ *  - openLtxFile returns a byte stream for a range of an LTX file.
+ *  - writeLtxFile writes an LTX file, preserving its creation timestamp.
+ */
+import type { Readable } from 'node:stream';
+import type { FileInfo, Header, PageIndex, TXID } from './ltx/index.js';
+import { formatFilename, parseFilename, type DecodedPage } from './ltx/index.js';
+import { SqliteJsStreamError } from './errors.js';
+import type { Logger } from './util/logger.js';
+/** Sentinel error to stop early iteration in FindLTXFiles. */
+export declare const ErrStopIter: unique symbol;
+import { SnapshotLevel } from './ltx/constants.js';
+/** SnapshotLevel is the LTX level reserved for full snapshots. */
+export { SnapshotLevel };
+export interface ReplicaClient {
+    /** Type returns the type of client (e.g. "file"). */
+    type(): string;
+    /** Init initializes the replica client connection (idempotent). */
+    init(): Promise<void>;
+    /**
+     * ltxFiles returns all LTX files for a level. If seek is non-zero, only files
+     * with MinTXID >= seek are returned. useMetadata controls timestamp accuracy.
+     */
+    ltxFiles(opts: LTXFilesOptions): AsyncIterable<FileInfo>;
+    /**
+     * openLtxFile returns a reader over an LTX file range. If size is 0 the range
+     * extends to the end of the file. Throws if the file does not exist.
+     */
+    openLtxFile(opts: OpenLTXFileOptions): Promise<Readable>;
+    /** writeLtxFile writes an LTX file to the replica and returns its metadata. */
+    writeLtxFile(opts: WriteLTXFileOptions, body: AsyncIterable<Uint8Array | string>): Promise<FileInfo>;
+    /** deleteLtxFiles deletes one or more LTX files. */
+    deleteLtxFiles(infos: FileInfo[]): Promise<void>;
+    /** deleteAll deletes all files on the replica. */
+    deleteAll(): Promise<void>;
+    /** setLogger sets the logger for the client. */
+    setLogger(logger: Logger): void;
+}
+export interface LTXFilesOptions {
+    level: number;
+    seek: TXID;
+    useMetadata: boolean;
+}
+export interface OpenLTXFileOptions {
+    level: number;
+    minTXID: TXID;
+    maxTXID: TXID;
+    offset: number;
+    size: number;
+}
+export interface WriteLTXFileOptions {
+    level: number;
+    minTXID: TXID;
+    maxTXID: TXID;
+}
+/** LTXDir returns the path to an LTX directory (root/ltx). */
+export declare function ltxDir(root: string): string;
+/** LTXLevelDir returns the path to an LTX level directory. */
+export declare function ltxLevelDir(root: string, level: number): string;
+/** LTXFilePath returns the path to a single LTX file. */
+export declare function ltxFilePath(root: string, level: number, minTXID: TXID, maxTXID: TXID): string;
+/** LTXError wraps errors reading/writing a specific LTX file. */
+export declare class LTXError extends SqliteJsStreamError {
+    readonly op: string;
+    readonly path: string;
+    readonly level: number;
+    readonly minTXID: TXID;
+    readonly maxTXID: TXID;
+    readonly cause: unknown;
+    constructor(op: string, path: string, level: number, minTXID: TXID, maxTXID: TXID, err: unknown);
+}
+/**
+ * FindLTXFiles returns a list of LTX files on a level matching `filter`.
+ * The filter may throw ErrStopIter to end iteration early.
+ */
+export declare function findLtxFiles(_ctx: unknown, client: ReplicaClient, level: number, useMetadata: boolean, filter: (info: FileInfo) => boolean | Promise<boolean>): Promise<FileInfo[]>;
+/** FetchLTXHeader reads & returns the LTX header for the given file info. */
+export declare function fetchLtxHeader(client: ReplicaClient, info: FileInfo): Promise<Header>;
+/** FetchPageIndex decodes the page index from the tail of an LTX file. */
+export declare function fetchPageIndex(client: ReplicaClient, info: FileInfo): Promise<PageIndex>;
+/** Streaming fetchTail for the page index; sizes and reopens as needed. */
+export declare function fetchPageIndexData(client: ReplicaClient, info: FileInfo): Promise<Uint8Array>;
+/** FetchPage fetches and decodes a single page frame from an LTX file. */
+export declare function fetchPage(client: ReplicaClient, level: number, minTXID: TXID, maxTXID: TXID, offset: number, size: number): Promise<DecodedPage>;
+export { formatFilename, parseFilename };
+//# sourceMappingURL=replica-client.d.ts.map

package/dist/replica-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica-client.d.ts","sourceRoot":"","sources":["../src/replica-client.ts"],"names":[],"mappings":"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"}

package/dist/replica-client.js

@@ -0,0 +1,122 @@
+/**
+ * ReplicaClient interface and shared helpers for interacting with a replica
+ * (an LTX destination). Mirrors litestream's `replica_client.go`.
+ *
+ * The interface is async/iterable oriented rather than Go's iterator/readcloser
+ * model, but the semantics match:
+ *  - ltxFiles returns LTX file metadata for a level, optionally seeking by TXID.
+ *  - openLtxFile returns a byte stream for a range of an LTX file.
+ *  - writeLtxFile writes an LTX file, preserving its creation timestamp.
+ */
+import nodePath from 'node:path';
+import { decodePageData, decodePageIndex, formatFilename, HeaderSize, parseFilename, TrailerSize, unmarshalHeader, } from "./ltx/index.js";
+import { ByteReader } from "./ltx/index.js";
+import { LTXFormatError, SqliteJsStreamError } from "./errors.js";
+import { readU64BE } from "./ltx/index.js";
+import { readAll } from "./util/stream.js";
+/** Sentinel error to stop early iteration in FindLTXFiles. */
+export const ErrStopIter = Symbol('stop iterator');
+import { SnapshotLevel } from "./ltx/constants.js";
+/** SnapshotLevel is the LTX level reserved for full snapshots. */
+export { SnapshotLevel };
+/** LTXDir returns the path to an LTX directory (root/ltx). */
+export function ltxDir(root) {
+    return nodePath.join(root, 'ltx');
+}
+/** LTXLevelDir returns the path to an LTX level directory. */
+export function ltxLevelDir(root, level) {
+    return nodePath.join(ltxDir(root), String(level));
+}
+/** LTXFilePath returns the path to a single LTX file. */
+export function ltxFilePath(root, level, minTXID, maxTXID) {
+    return nodePath.join(ltxLevelDir(root, level), formatFilename(minTXID, maxTXID));
+}
+/** LTXError wraps errors reading/writing a specific LTX file. */
+export class LTXError extends SqliteJsStreamError {
+    op;
+    path;
+    level;
+    minTXID;
+    maxTXID;
+    cause;
+    constructor(op, path, level, minTXID, maxTXID, err) {
+        super('ERR_LTX', `${op} ltx file: ${err instanceof Error ? err.message : String(err)}`);
+        this.name = 'LTXError';
+        this.op = op;
+        this.path = path;
+        this.level = level;
+        this.minTXID = minTXID;
+        this.maxTXID = maxTXID;
+        this.cause = err;
+    }
+}
+const DEFAULT_ESTIMATED_PAGE_INDEX_SIZE = 32 * 1024;
+/**
+ * FindLTXFiles returns a list of LTX files on a level matching `filter`.
+ * The filter may throw ErrStopIter to end iteration early.
+ */
+export async function findLtxFiles(_ctx, client, level, useMetadata, filter) {
+    const out = [];
+    for await (const info of client.ltxFiles({ level, seek: 0n, useMetadata })) {
+        const match = await filter(info);
+        if (match)
+            out.push(info);
+    }
+    return out;
+}
+/** FetchLTXHeader reads & returns the LTX header for the given file info. */
+export async function fetchLtxHeader(client, info) {
+    const rc = await client.openLtxFile({
+        level: info.level,
+        minTXID: info.minTXID,
+        maxTXID: info.maxTXID,
+        offset: 0,
+        size: HeaderSize,
+    });
+    const b = await readAll(rc);
+    return unmarshalHeader(b);
+}
+/** FetchPageIndex decodes the page index from the tail of an LTX file. */
+export async function fetchPageIndex(client, info) {
+    const b = await fetchPageIndexData(client, info);
+    const r = new ByteReader(b, 0);
+    return decodePageIndex(r, info.level, info.minTXID, info.maxTXID);
+}
+/** Streaming fetchTail for the page index; sizes and reopens as needed. */
+export async function fetchPageIndexData(client, info) {
+    let offset = info.size - DEFAULT_ESTIMATED_PAGE_INDEX_SIZE;
+    if (offset < 0)
+        offset = 0;
+    const f = await client.openLtxFile({
+        level: info.level,
+        minTXID: info.minTXID,
+        maxTXID: info.maxTXID,
+        offset,
+        size: 0,
+    });
+    const b = await readAll(f);
+    if (b.length < TrailerSize + 8) {
+        throw new LTXFormatError(`ltx file too short to contain a page index: ${b.length} bytes`);
+    }
+    const size = readU64BE(b, b.length - TrailerSize - 8);
+    const relativeStart = b.length - Number(size) - TrailerSize - 8;
+    if (relativeStart > 0) {
+        return b.subarray(relativeStart);
+    }
+    const f2 = await client.openLtxFile({
+        level: info.level,
+        minTXID: info.minTXID,
+        maxTXID: info.maxTXID,
+        offset: info.size - TrailerSize - 8 - Number(size),
+        size: 0,
+    });
+    return readAll(f2);
+}
+/** FetchPage fetches and decodes a single page frame from an LTX file. */
+export async function fetchPage(client, level, minTXID, maxTXID, offset, size) {
+    const f = await client.openLtxFile({ level, minTXID, maxTXID, offset, size });
+    const b = await readAll(f);
+    return decodePageData(b);
+}
+// Re-exported for convenience in the file backend.
+export { formatFilename, parseFilename };

package/dist/replica-url.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Replica URL parsing and replica-client factory registration.
+ * Mirrors litestream's `replica_url.go` (simplified: file scheme only for now).
+ */
+import type { ReplicaClient } from './replica-client.js';
+export type ReplicaClientFactory = (scheme: string, host: string, urlPath: string, query: URLSearchParams | null, userinfo: string | null) => ReplicaClient;
+export interface ParsedReplicaURL {
+    scheme: string;
+    host: string;
+    urlPath: string;
+    query: URLSearchParams | null;
+    userinfo: string | null;
+}
+/** RegisterReplicaClientFactory registers a factory for a URL scheme. */
+export declare function registerReplicaClientFactory(scheme: string, factory: ReplicaClientFactory): void;
+/** NewReplicaClientFromURL creates a ReplicaClient from a URL string. */
+export declare function newReplicaClientFromURL(rawURL: string): ReplicaClient;
+/** ParseReplicaURLWithQuery parses a replica URL into components. */
+export declare function parseReplicaURLWithQuery(s: string): ParsedReplicaURL;
+//# sourceMappingURL=replica-url.d.ts.map

package/dist/replica-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica-url.d.ts","sourceRoot":"","sources":["../src/replica-url.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,MAAM,MAAM,oBAAoB,GAAG,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,GAAG,IAAI,EAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,KACpB,aAAa,CAAC;AAEnB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID,yEAAyE;AACzE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAEhG;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAOrE;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,gBAAgB,CA6BpE"}

package/dist/replica-url.js

@@ -0,0 +1,49 @@
+/**
+ * Replica URL parsing and replica-client factory registration.
+ * Mirrors litestream's `replica_url.go` (simplified: file scheme only for now).
+ */
+import { ReplicaURLError } from "./errors.js";
+const factories = new Map();
+/** RegisterReplicaClientFactory registers a factory for a URL scheme. */
+export function registerReplicaClientFactory(scheme, factory) {
+    factories.set(scheme, factory);
+}
+/** NewReplicaClientFromURL creates a ReplicaClient from a URL string. */
+export function newReplicaClientFromURL(rawURL) {
+    const parsed = parseReplicaURLWithQuery(rawURL);
+    const factory = factories.get(parsed.scheme);
+    if (!factory) {
+        throw new ReplicaURLError(`unsupported replica URL scheme: ${parsed.scheme}`);
+    }
+    return factory(parsed.scheme, parsed.host, parsed.urlPath, parsed.query, parsed.userinfo);
+}
+/** ParseReplicaURLWithQuery parses a replica URL into components. */
+export function parseReplicaURLWithQuery(s) {
+    let u;
+    try {
+        u = new URL(s);
+    }
+    catch (err) {
+        throw new ReplicaURLError(`parse replica url ${JSON.stringify(s)}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const scheme = u.protocol.replace(/:$/, '');
+    if (scheme === 'file') {
+        return {
+            scheme: 'file',
+            host: '',
+            urlPath: u.pathname,
+            query: null,
+            userinfo: null,
+        };
+    }
+    if (scheme === '') {
+        throw new ReplicaURLError(`replica url scheme required: ${s}`);
+    }
+    return {
+        scheme,
+        host: u.host,
+        urlPath: decodeURIComponent(u.pathname),
+        query: u.searchParams,
+        userinfo: u.username ? `${u.username}:${u.password}` : null,
+    };
+}

package/dist/replica.d.ts

@@ -0,0 +1,379 @@
+/**
+ * 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 { CompactionLevels, type FileInfo } from './ltx/index.js';
+import type { ReplicaClient } from './replica-client.js';
+import { type Leaser } from './leaser.js';
+import type { Logger } from './util/logger.js';
+import { SqliteJsStreamError } from './errors.js';
+export interface RestoreOptions {
+    outputPath: string;
+    txID?: bigint;
+    timestamp?: Date;
+}
+/** Options for {@link Replica.follow}, litestream's `restore -f` continuous mode. */
+export interface FollowOptions {
+    /** Output database path to continuously restore into. */
+    outputPath: string;
+    /** Milliseconds between polls for new LTX files. Defaults to 1000. */
+    intervalMs?: number;
+    /** Abort to stop the follow loop. */
+    signal?: AbortSignal;
+    /**
+     * Sidecar file recording the last applied TXID, so a later `follow()` can
+     * resume instead of re-restoring. Defaults to `${outputPath}-txid`. Written
+     * atomically (temp + rename) after each applied batch. `follow()` refuses to
+     * resume when the DB exists but this file is missing (it cannot prove the DB
+     * matches the replica and would otherwise corrupt it).
+     */
+    txidFile?: string;
+}
+/**
+ * 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 declare class FollowError extends SqliteJsStreamError {
+    constructor(code: string, message: string);
+}
+/** The database exists but its `-txid` sidecar is missing, so we can't resume. */
+export declare class FollowMissingTxidError extends FollowError {
+    constructor(message: string);
+}
+/** The `-txid` sidecar is present but does not parse as a TXID. */
+export declare class FollowInvalidTxidError extends FollowError {
+    constructor(message: string);
+}
+/** The saved TXID is ahead of anything the replica holds; re-restore. */
+export declare class FollowAheadOfLatestError extends FollowError {
+    constructor(message: string);
+}
+/** The saved TXID is below the retained window; retention pruned the next file. */
+export declare class FollowDataGapError extends FollowError {
+    constructor(message: string);
+}
+/** Follow was aborted before the initial restore could complete. */
+export declare class FollowAbortedError extends FollowError {
+    constructor(message: string);
+}
+export interface SyncStatus {
+    localTXID: bigint;
+    remoteTXID: bigint;
+    inSync: boolean;
+}
+/**
+ * Default highest LTX compaction level (L0 -> L1 -> ... -> L{max}) for the
+ * legacy {@link CompactOptions.maxLevel} path. Prefer {@link CompactionLevels}.
+ */
+export declare const DefaultMaxCompactionLevel = 3;
+export interface CompactOptions {
+    /**
+     * Destination level to compact into (1..maxLevel). When omitted, the first
+     * level (1..maxLevel) that has pending source files is compacted.
+     */
+    dstLevel?: number;
+}
+/** Retention/GC policy for pruning old snapshots and compacted files. */
+export interface RetentionOptions {
+    /**
+     * Delete level-9 snapshots older than this many milliseconds. The newest
+     * snapshot is always kept. Defaults to 0 (keep all snapshots).
+     */
+    snapshotRetentionMs?: number;
+    /**
+     * Keep at least this many newest level-9 snapshots even if they are older
+     * than {@link snapshotRetentionMs}. Defaults to 1 (always keep the newest).
+     */
+    snapshotRetain?: number;
+    /**
+     * Minimum age (ms) before a level-0 file that has been compacted into level-1
+     * is deleted. Defaults to 0 (no L0 time-based GC).
+     */
+    l0RetentionMs?: number;
+}
+export interface RetentionResult {
+    snapshotsDeleted: number;
+    filesDeleted: number;
+    /** MaxTXID of the last snapshot that was deleted; files below it are removed. */
+    boundary: bigint;
+}
+/** Returned by compaction scheduling when there is nothing to compact. */
+export declare class ErrNoCompactionError extends SqliteJsStreamError {
+    constructor();
+}
+export declare const ErrNoCompaction: ErrNoCompactionError;
+/** Returned when a level was already compacted within its current time bucket. */
+export declare class ErrCompactionTooEarlyError extends SqliteJsStreamError {
+    constructor();
+}
+export declare const ErrCompactionTooEarly: ErrCompactionTooEarlyError;
+/** Raised when a restore/plan cannot find LTX files at or below the target. */
+export declare class NoMatchingBackupError extends SqliteJsStreamError {
+    constructor(message?: string);
+}
+export interface ReplicaRunOptions {
+    /** Milliseconds between syncs. Defaults to 1000. */
+    intervalMs?: number;
+    /** Abort to stop continuous syncing. */
+    signal?: AbortSignal;
+    /**
+     * Per-level compaction schedule. Defaults to {@link defaultCompactionLevels}.
+     * Levels are compacted at most once per wall-clock bucket.
+     */
+    compactionLevels?: CompactionLevels;
+    /**
+     * Legacy: max compaction level when {@link compactionLevels} is not given.
+     * Defaults to {@link DefaultMaxCompactionLevel}.
+     */
+    maxLevel?: number;
+    /**
+     * Legacy: cascade-compact all levels every N ms (disables per-level buckets
+     * when set). Defaults to 0 (disabled).
+     */
+    compactionIntervalMs?: number;
+    /** Legacy: run {@link Replica.enforceRetention} every N ms. Defaults to 0. */
+    retentionIntervalMs?: number;
+    /** Retention policy used by the legacy retention loop. */
+    retention?: RetentionOptions;
+    /**
+     * Milliseconds between level-9 snapshots while running (0 disables).
+     * Defaults to 0.
+     */
+    snapshotIntervalMs?: number;
+    /** Time-based snapshot retention (ms) applied after each snapshot. */
+    snapshotRetentionMs?: number;
+    /** Keep at least this many newest snapshots (default 1). */
+    snapshotRetain?: number;
+    /**
+     * Min age (ms) before a compacted level-0 file is deleted. When > 0 an L0
+     * retention pass runs on {@link l0RetentionCheckIntervalMs}. Defaults to 0.
+     */
+    l0RetentionMs?: number;
+    /** How often (ms) to run the L0 time-retention pass. Defaults to 15s. */
+    l0RetentionCheckIntervalMs?: number;
+}
+/** Replica replicates a single database (by path) to a ReplicaClient. */
+export declare class Replica {
+    readonly path: string;
+    readonly client: ReplicaClient;
+    private logger;
+    private posValue;
+    private db;
+    private compactionLevelsValue;
+    private leaserValue;
+    private leasePrimary;
+    private leaseCurrent;
+    private leaseTimer;
+    private runActive;
+    constructor(path: string, client: ReplicaClient, logger?: Logger, options?: {
+        maxLevel?: number;
+        compactionLevels?: CompactionLevels;
+        leaser?: Leaser;
+    });
+    /** Leaser optionally bounds this replica to a single primary across hosts. */
+    get leaser(): Leaser | null;
+    set leaser(leaser: 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(): boolean;
+    /** @internal Throws if a leaser is set but this replica does not hold it. */
+    private assertCanWrite;
+    /** Per-level compaction schedule. Defaults to {@link defaultCompactionLevels}. */
+    get compactionLevels(): CompactionLevels;
+    set compactionLevels(levels: CompactionLevels);
+    /** Highest non-snapshot compaction level this replica will produce. */
+    get maxCompactionLevel(): number;
+    set maxCompactionLevel(level: number);
+    /** Lazily opens the local database reader (cached). */
+    private localDb;
+    /** Pos returns the current replicated position (max level-0 maxTXID). */
+    pos(): Promise<bigint>;
+    /**
+     * 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).
+     */
+    calcPos(): Promise<bigint>;
+    /** LocalPos returns the local cached position (max local level-0 maxTXID). */
+    localPos(): Promise<bigint>;
+    /**
+     * 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.
+     */
+    sync(): Promise<FileInfo | null>;
+    /** SyncAndWait uploads all pending LTX files; harmless if already synced. */
+    syncAndWait(): Promise<void>;
+    /**
+     * 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.
+     */
+    run(opt?: ReplicaRunOptions): Promise<void>;
+    /**
+     * Schedules the next lease renewal to fire just before expiry, independent of
+     * the run-loop cadence. Reschedules after every successful renewal.
+     */
+    private scheduleLeaseRenewal;
+    /** Renews the lease and reschedules; reverts to follower if we lost it. */
+    private renewLeaseLoop;
+    /** Cancels any pending lease renewal. */
+    private stopLeaseRenewal;
+    /** Snapshot writes and uploads a level-9 full-database LTX file. */
+    snapshot(): Promise<FileInfo | null>;
+    /** SyncStatus reports the local and remote positions. */
+    syncStatus(): Promise<SyncStatus>;
+    /** Uploads a single local LTX file to the client. */
+    private uploadLtxFile;
+    /** EnsureExists restores the local database if it is missing. */
+    ensureExists(): Promise<void>;
+    /** Restore reconstructs a SQLite database at `outputPath` from LTX files. */
+    restore(opt: RestoreOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    follow(opt: FollowOptions): Promise<void>;
+    /**
+     * 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}.)
+     */
+    private validateResumePoint;
+    /**
+     * Waits for the first backup to appear on an empty replica, then restores it
+     * as the follow base. Returns the plan that was applied.
+     */
+    private waitForInitialRestore;
+    /**
+     * 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.
+     */
+    private collectFollowBatch;
+    /**
+     * 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.
+     */
+    private applyFollowBatch;
+    /** Opens a streaming LTX reader over a plan file from the client. */
+    private openStreamReader;
+    /** Close releases any internal database connection. */
+    close(): void;
+    /**
+     * 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.
+     */
+    compact(options?: CompactOptions): Promise<FileInfo | 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}.
+     */
+    compactLevel(dstLevel: number): Promise<FileInfo | null>;
+    /**
+     * 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}).
+     */
+    compactDB(dstLevel: number, now: number): Promise<FileInfo | null>;
+    /**
+     * 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.
+     */
+    compactSnapshot(now: number, intervalMs: number): Promise<FileInfo | null>;
+    /** MaxLTXFileInfo returns the highest-TXID file at a level, or null. */
+    maxLTXFileInfo(level: number): Promise<FileInfo | null>;
+    /**
+     * 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).
+     */
+    enforceRetention(options?: RetentionOptions): Promise<RetentionResult>;
+    /**
+     * 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.
+     */
+    enforceSnapshotRetention(now: number, retentionMs: number, retain?: number): Promise<{
+        deleted: number;
+        boundary: bigint;
+    }>;
+    /**
+     * EnforceRetentionByTXID deletes files at `level` with maxTXID below `txID`,
+     * always keeping at least one file. Returns the number deleted.
+     */
+    enforceRetentionByTXID(level: number, txID: bigint): Promise<number>;
+    /**
+     * 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.
+     */
+    enforceL0RetentionByTime(now: number, l0RetentionMs: number): Promise<number>;
+    /** Returns true if `info` is fully contained in a file at a higher level. */
+    private isCoveredByHigherLevel;
+    /** Lists LTX files at a remote level. */
+    private listRemoteLevel;
+    /** Deletes files from the client and the local cache. */
+    private deleteFiles;
+    /**
+     * 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.
+     */
+    private openSourceReader;
+}
+/**
+ * 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 declare function calcRestorePlan(client: ReplicaClient, txID: bigint): Promise<FileInfo[]>;
+//# sourceMappingURL=replica.d.ts.map