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

package/dist/ltx/compactor.js

@@ -0,0 +1,137 @@
+/**
+ * LTX Compactor merges multiple LTX files (readers) into a single stream,
+ * where later files override earlier ones for the same page number.
+ *
+ * Mirrors Go's `ltx.Compactor`. Used by restore (snapshot + incremental L0
+ * files) and by multi-level compaction.
+ */
+import { isZeroPageHeader, isContiguous } from "./types.js";
+import { Encoder } from "./encoder.js";
+import { Decoder } from "./decoder.js";
+import { InvalidArgumentError, LTXFormatError, PageSizeMismatchError } from "../errors.js";
+/** Compactor merges LTX readers into a single writer. */
+export class Compactor {
+    enc;
+    inputs = [];
+    _headerFlags = 0;
+    allowNonContiguousTXIDs = false;
+    constructor(sink, readers) {
+        this.enc = new Encoder(sink);
+        for (const r of readers) {
+            const dec = new Decoder(r);
+            dec.setRetainPageIndex(false);
+            this.inputs.push({ dec, hdr: { pgno: 0, flags: 0 }, data: new Uint8Array(0) });
+        }
+    }
+    get headerFlags() {
+        return this._headerFlags;
+    }
+    set headerFlags(flags) {
+        this._headerFlags = flags;
+    }
+    /** AllowNonContiguousTXIDs disables contiguous-TXID validation between inputs. */
+    setAllowNonContiguousTXIDs(v) {
+        this.allowNonContiguousTXIDs = v;
+    }
+    /** Header returns the output header (after Compact). */
+    Header() {
+        return this.enc.Header();
+    }
+    /** Trailer returns the output trailer (after Compact). */
+    Trailer() {
+        return this.enc.Trailer();
+    }
+    /** Compact merges all input readers into a single LTX stream. */
+    compact() {
+        if (this.inputs.length === 0) {
+            throw new InvalidArgumentError('at least one input reader required');
+        }
+        // Read headers from all inputs.
+        for (let i = 0; i < this.inputs.length; i++) {
+            this.inputs[i].dec.decodeHeader();
+        }
+        // Validate page sizes & contiguous TXIDs.
+        for (let i = 1; i < this.inputs.length; i++) {
+            const prevHdr = this.inputs[i - 1].dec.Header();
+            const hdr = this.inputs[i].dec.Header();
+            if (prevHdr.pageSize !== hdr.pageSize) {
+                throw new PageSizeMismatchError(`input files have mismatched page sizes: ${prevHdr.pageSize} != ${hdr.pageSize}`);
+            }
+            if (!this.allowNonContiguousTXIDs &&
+                !isContiguous(prevHdr.maxTXID, hdr.minTXID, hdr.maxTXID)) {
+                throw new LTXFormatError(`non-contiguous transaction ids in input files: (${prevHdr.minTXID},${prevHdr.maxTXID}) -> (${hdr.minTXID},${hdr.maxTXID})`);
+            }
+        }
+        const minHdr = this.inputs[0].dec.Header();
+        const maxHdr = this.inputs[this.inputs.length - 1].dec.Header();
+        this.enc.encodeHeader({
+            version: 3,
+            flags: this.headerFlags,
+            pageSize: minHdr.pageSize,
+            commit: maxHdr.commit,
+            minTXID: minHdr.minTXID,
+            maxTXID: maxHdr.maxTXID,
+            timestamp: maxHdr.timestamp,
+            preApplyChecksum: minHdr.preApplyChecksum,
+            walOffset: 0n,
+            walSize: 0n,
+            walSalt1: 0,
+            walSalt2: 0,
+            nodeID: 0n,
+        });
+        this.writePageBlock();
+        for (const input of this.inputs) {
+            input.dec.close();
+        }
+        const last = this.inputs[this.inputs.length - 1];
+        this.enc.setPostApplyChecksum(last.dec.Trailer().postApplyChecksum);
+        this.enc.close();
+    }
+    writePageBlock() {
+        const pageSize = this.enc.Header().pageSize;
+        for (const input of this.inputs) {
+            input.data = new Uint8Array(pageSize);
+        }
+        for (;;) {
+            const pgno = this.fillPageBuffers();
+            if (pgno === 0)
+                break;
+            this.writePageBuffer(pgno);
+        }
+    }
+    /** Fills input buffers and returns the smallest available page number. */
+    fillPageBuffers() {
+        let pgno = 0;
+        for (const input of this.inputs) {
+            if (isZeroPageHeader(input.hdr)) {
+                const hdr = input.dec.decodePage(input.data);
+                if (hdr === null)
+                    continue; // end of page block for this input
+                input.hdr = hdr;
+            }
+            if (pgno === 0 || input.hdr.pgno < pgno) {
+                pgno = input.hdr.pgno;
+            }
+        }
+        return pgno;
+    }
+    /** Writes the buffer with a matching pgno from the latest input. */
+    writePageBuffer(pgno) {
+        const commit = this.enc.Header().commit;
+        let pageWritten = false;
+        for (let i = this.inputs.length - 1; i >= 0; i--) {
+            const input = this.inputs[i];
+            if (input.hdr.pgno !== pgno)
+                continue;
+            const hdr = input.hdr;
+            const data = input.data;
+            input.hdr = { pgno: 0, flags: 0 };
+            if (pageWritten)
+                continue;
+            if (pgno > commit)
+                continue;
+            pageWritten = true;
+            this.enc.encodePage(hdr, data);
+        }
+    }
+}

package/dist/ltx/constants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * LTX format constants.
+ *
+ * Ground truth: superfly/ltx v0.5.2 (vendored by litestream). The byte layout
+ * here must match Go's `ltx` package exactly so files interoperate.
+ */
+/** Magic is the first 4 bytes of every LTX file. */
+export declare const Magic = "LTX1";
+/** Version is the current version of the LTX file format. */
+export declare const Version = 3;
+/** Size constants. */
+export declare const HeaderSize = 100;
+export declare const PageHeaderSize = 6;
+export declare const TrailerSize = 16;
+/** Checksum size & positions. */
+export declare const ChecksumSize = 8;
+export declare const TrailerChecksumOffset: number;
+/** ChecksumFlag ensures a checksum is non-zero. */
+export declare const ChecksumFlag: bigint;
+/** Entry byte offset of the PENDING_BYTE within a database. */
+export declare const PENDING_BYTE = 1073741824;
+/** Header flags. */
+export declare const HeaderFlagMask = 2;
+export declare const HeaderFlagNoChecksum = 2;
+/** Page header flags. */
+/** PageHeaderFlagSize indicates a 4-byte size field follows the page header. */
+export declare const PageHeaderFlagSize = 1;
+/** MaxPageSize is the maximum allowed SQLite page size. */
+export declare const MaxPageSize = 65536;
+/** SnapshotLevel is the LTX level reserved for full-database snapshots. */
+export declare const SnapshotLevel = 9;
+/** Error messages / codes. */
+export declare const ErrInvalidFile = "invalid LTX file";
+export declare const ErrDecoderClosed = "ltx decoder closed";
+export declare const ErrEncoderClosed = "ltx encoder closed";
+export declare const ErrEncoderAborted = "ltx encoder aborted";
+export declare const ErrNoChecksum = "no file checksum";
+export declare const ErrInvalidChecksumFormat = "invalid file checksum format";
+export declare const ErrChecksumMismatch = "file checksum mismatch";
+/**
+ * LockPgno returns the page number at which the PENDING_BYTE exists.
+ * This page is never part of the LTX payload.
+ */
+export declare function lockPgno(pageSize: number): number;
+/** IsValidPageSize returns true if sz is between 512 and 64K and a power of two. */
+export declare function isValidPageSize(sz: number): boolean;
+/** IsValidHeaderFlags returns true unless flags outside the valid mask are set. */
+export declare function isValidHeaderFlags(flags: number): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/ltx/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/ltx/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oDAAoD;AACpD,eAAO,MAAM,KAAK,SAAS,CAAC;AAE5B,6DAA6D;AAC7D,eAAO,MAAM,OAAO,IAAI,CAAC;AAEzB,sBAAsB;AACtB,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,iCAAiC;AACjC,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,qBAAqB,QAA6B,CAAC;AAEhE,mDAAmD;AACnD,eAAO,MAAM,YAAY,QAAY,CAAC;AAEtC,+DAA+D;AAC/D,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC,oBAAoB;AACpB,eAAO,MAAM,cAAc,IAAa,CAAC;AACzC,eAAO,MAAM,oBAAoB,IAAa,CAAC;AAE/C,yBAAyB;AACzB,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,IAAS,CAAC;AAEzC,2DAA2D;AAC3D,eAAO,MAAM,WAAW,QAAQ,CAAC;AAEjC,2EAA2E;AAC3E,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,8BAA8B;AAC9B,eAAO,MAAM,cAAc,qBAAqB,CAAC;AACjD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AACrD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AACrD,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAChD,eAAO,MAAM,wBAAwB,iCAAiC,CAAC;AACvE,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKnD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/ltx/constants.js

@@ -0,0 +1,58 @@
+/**
+ * LTX format constants.
+ *
+ * Ground truth: superfly/ltx v0.5.2 (vendored by litestream). The byte layout
+ * here must match Go's `ltx` package exactly so files interoperate.
+ */
+/** Magic is the first 4 bytes of every LTX file. */
+export const Magic = 'LTX1';
+/** Version is the current version of the LTX file format. */
+export const Version = 3;
+/** Size constants. */
+export const HeaderSize = 100;
+export const PageHeaderSize = 6;
+export const TrailerSize = 16;
+/** Checksum size & positions. */
+export const ChecksumSize = 8;
+export const TrailerChecksumOffset = TrailerSize - ChecksumSize;
+/** ChecksumFlag ensures a checksum is non-zero. */
+export const ChecksumFlag = 1n << 63n;
+/** Entry byte offset of the PENDING_BYTE within a database. */
+export const PENDING_BYTE = 0x40000000;
+/** Header flags. */
+export const HeaderFlagMask = 0x00000002;
+export const HeaderFlagNoChecksum = 0x00000002;
+/** Page header flags. */
+/** PageHeaderFlagSize indicates a 4-byte size field follows the page header. */
+export const PageHeaderFlagSize = 0x0001;
+/** MaxPageSize is the maximum allowed SQLite page size. */
+export const MaxPageSize = 65536;
+/** SnapshotLevel is the LTX level reserved for full-database snapshots. */
+export const SnapshotLevel = 9;
+/** Error messages / codes. */
+export const ErrInvalidFile = 'invalid LTX file';
+export const ErrDecoderClosed = 'ltx decoder closed';
+export const ErrEncoderClosed = 'ltx encoder closed';
+export const ErrEncoderAborted = 'ltx encoder aborted';
+export const ErrNoChecksum = 'no file checksum';
+export const ErrInvalidChecksumFormat = 'invalid file checksum format';
+export const ErrChecksumMismatch = 'file checksum mismatch';
+/**
+ * LockPgno returns the page number at which the PENDING_BYTE exists.
+ * This page is never part of the LTX payload.
+ */
+export function lockPgno(pageSize) {
+    return Math.floor(PENDING_BYTE / pageSize) + 1;
+}
+/** IsValidPageSize returns true if sz is between 512 and 64K and a power of two. */
+export function isValidPageSize(sz) {
+    for (let i = 512; i <= MaxPageSize; i *= 2) {
+        if (sz === i)
+            return true;
+    }
+    return false;
+}
+/** IsValidHeaderFlags returns true unless flags outside the valid mask are set. */
+export function isValidHeaderFlags(flags) {
+    return flags === (flags & HeaderFlagMask);
+}

package/dist/ltx/crc64.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CRC-64 ISO implementation, byte-compatible with Go's `hash/crc64` using
+ * `crc64.MakeTable(crc64.ISO)`. This is what superfly/ltx uses for all LTX
+ * checksums (page checksums, rolling DB checksum, file checksum).
+ *
+ * NOTE: LTX uses CRC-64 ISO, NOT ECMA. The litestream docs are misleading;
+ * the actual code (`crc64.New(crc64.MakeTable(crc64.ISO))`) uses ISO.
+ *
+ * Algorithm matches Go's reflected `crc64.Update`:
+ *   - init / xorout = all ones (0xFFFFFFFFFFFFFFFF)
+ *   - polynomial register value = 0xD800000000000000
+ *   - table built by right-shifting (reflected), update as
+ *     `tab[byte(crc) ^ v] ^ (crc >> 8)`
+ */
+/**
+ * Crc64 is a streaming CRC-64 hasher, equivalent to Go's `hash/crc64`
+ * (ISO table). Call `update()` with successive byte chunks and `sum64()` to
+ * obtain the running checksum. `reset()` re-initializes the hasher.
+ */
+export declare class Crc64 {
+    private crc;
+    update(buf: Uint8Array): void;
+    reset(): void;
+    /** Returns the digest of all data written so far. */
+    sum64(): bigint;
+}
+/** Convenience: computes the CRC-64 ISO of a single buffer. */
+export declare function crc64ISO(buf: Uint8Array): bigint;
+//# sourceMappingURL=crc64.d.ts.map

package/dist/ltx/crc64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crc64.d.ts","sourceRoot":"","sources":["../../src/ltx/crc64.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoBH;;;;GAIG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAkB;IAE7B,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAQ7B,KAAK,IAAI,IAAI;IAIb,qDAAqD;IACrD,KAAK,IAAI,MAAM;CAGhB;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAIhD"}

package/dist/ltx/crc64.js

@@ -0,0 +1,57 @@
+/**
+ * CRC-64 ISO implementation, byte-compatible with Go's `hash/crc64` using
+ * `crc64.MakeTable(crc64.ISO)`. This is what superfly/ltx uses for all LTX
+ * checksums (page checksums, rolling DB checksum, file checksum).
+ *
+ * NOTE: LTX uses CRC-64 ISO, NOT ECMA. The litestream docs are misleading;
+ * the actual code (`crc64.New(crc64.MakeTable(crc64.ISO))`) uses ISO.
+ *
+ * Algorithm matches Go's reflected `crc64.Update`:
+ *   - init / xorout = all ones (0xFFFFFFFFFFFFFFFF)
+ *   - polynomial register value = 0xD800000000000000
+ *   - table built by right-shifting (reflected), update as
+ *     `tab[byte(crc) ^ v] ^ (crc >> 8)`
+ */
+const ISO_POLY = 0xd800000000000000n;
+const MASK64 = 0xffffffffffffffffn;
+/** Builds the 256-entry CRC table for a reflected polynomial. */
+function makeTable(poly) {
+    const table = new Array(256);
+    for (let i = 0; i < 256; i++) {
+        let crc = BigInt(i);
+        for (let j = 0; j < 8; j++) {
+            crc = (crc & 1n) !== 0n ? (crc >> 1n) ^ poly : crc >> 1n;
+        }
+        table[i] = crc;
+    }
+    return table;
+}
+const ISO_TABLE = makeTable(ISO_POLY);
+/**
+ * Crc64 is a streaming CRC-64 hasher, equivalent to Go's `hash/crc64`
+ * (ISO table). Call `update()` with successive byte chunks and `sum64()` to
+ * obtain the running checksum. `reset()` re-initializes the hasher.
+ */
+export class Crc64 {
+    crc = MASK64;
+    update(buf) {
+        let crc = this.crc;
+        for (let i = 0; i < buf.length; i++) {
+            crc = ISO_TABLE[Number((crc ^ BigInt(buf[i])) & 0xffn)] ^ (crc >> 8n);
+        }
+        this.crc = crc;
+    }
+    reset() {
+        this.crc = MASK64;
+    }
+    /** Returns the digest of all data written so far. */
+    sum64() {
+        return this.crc ^ MASK64;
+    }
+}
+/** Convenience: computes the CRC-64 ISO of a single buffer. */
+export function crc64ISO(buf) {
+    const h = new Crc64();
+    h.update(buf);
+    return h.sum64();
+}

package/dist/ltx/decoder.d.ts

@@ -0,0 +1,55 @@
+/**
+ * LTX decoder.
+ *
+ * Mirrors Go's `ltx.Decoder`. Reads header, page frames, page index, and
+ * trailer from an in-memory buffer, verifying the file checksum and (for
+ * checksum-tracking snapshots) the post-apply rolling checksum.
+ */
+import type { ByteSink } from './sink.js';
+import type { Header, PageHeader, PageIndex, Trailer } from './types.js';
+/** Decoder reads an LTX file from an in-memory buffer. */
+export declare class Decoder {
+    private r;
+    private header;
+    private trailer;
+    private pageIndex;
+    private state;
+    private hash;
+    private pageSeq;
+    private chksum;
+    private pageN;
+    private retainPageIndex;
+    constructor(buf: Uint8Array);
+    /** SetRetainPageIndex controls whether Close materializes the page-index map. */
+    setRetainPageIndex(retain: boolean): void;
+    /** N returns the number of source bytes read. */
+    N(): number;
+    /** PageN returns the number of pages decoded. */
+    PageN(): number;
+    /** Header returns a copy of the header. */
+    Header(): Header;
+    /** Trailer returns the trailer. File checksum valid after Close(). */
+    Trailer(): Trailer;
+    /** PageIndex returns the page index (after Close), or null if not retained. */
+    PageIndex(): PageIndex | null;
+    /** PostApplyPos returns the replication position after applying this file. */
+    PostApplyPos(): {
+        txID: bigint;
+        postApplyChecksum: bigint;
+    };
+    /** DecodeHeader reads and validates the header frame. */
+    decodeHeader(): void;
+    /**
+     * DecodePage reads the next page frame into `data`. Returns the page header,
+     * or null when the end-of-pages marker is reached.
+     */
+    decodePage(data: Uint8Array): PageHeader | null;
+    /** Verify reads the entire file, discarding page data (for validation). */
+    verify(): void;
+    /** DecodeDatabaseTo writes the snapshot as a SQLite database to `sink`. */
+    decodeDatabaseTo(sink: ByteSink): void;
+    /** Close verifies the page index and trailer, then checks the file checksum. */
+    close(): void;
+    private hashPgo;
+}
+//# sourceMappingURL=decoder.d.ts.map

package/dist/ltx/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/ltx/decoder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAmBzE,0DAA0D;AAC1D,qBAAa,OAAO;IAClB,OAAO,CAAC,CAAC,CAAa;IACtB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,OAAO,CAAwD;IACvE,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,eAAe,CAAU;gBAErB,GAAG,EAAE,UAAU;IAK3B,iFAAiF;IACjF,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIzC,iDAAiD;IACjD,CAAC,IAAI,MAAM;IAIX,iDAAiD;IACjD,KAAK,IAAI,MAAM;IAIf,2CAA2C;IAC3C,MAAM,IAAI,MAAM;IAIhB,sEAAsE;IACtE,OAAO,IAAI,OAAO;IAIlB,+EAA+E;IAC/E,SAAS,IAAI,SAAS,GAAG,IAAI;IAI7B,8EAA8E;IAC9E,YAAY;;;;IAOZ,yDAAyD;IACzD,YAAY,IAAI,IAAI;IAWpB;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI;IAkD/C,2EAA2E;IAC3E,MAAM,IAAI,IAAI;IASd,2EAA2E;IAC3E,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IA8BtC,gFAAgF;IAChF,KAAK,IAAI,IAAI;IA0Eb,OAAO,CAAC,OAAO;CAGhB"}

package/dist/ltx/decoder.js

@@ -0,0 +1,236 @@
+/**
+ * LTX decoder.
+ *
+ * Mirrors Go's `ltx.Decoder`. Reads header, page frames, page index, and
+ * trailer from an in-memory buffer, verifying the file checksum and (for
+ * checksum-tracking snapshots) the post-apply rolling checksum.
+ */
+import { ChecksumFlag, HeaderSize, PageHeaderFlagSize, PageHeaderSize, TrailerChecksumOffset, TrailerSize, lockPgno, } from "./constants.js";
+import { Crc64 } from "./crc64.js";
+import { u32BE } from "./bytes.js";
+import { ByteReader } from "./byte-reader.js";
+import { isSnapshot } from "./types.js";
+import { unmarshalHeader, validateHeader } from "./header.js";
+import { unmarshalPageHeader } from "./page.js";
+import { unmarshalTrailer } from "./trailer.js";
+import { parsePageIndex } from "./page-index.js";
+import { decompressBlock } from "./lz4.js";
+import { checksumPage } from "./checksum.js";
+import { LTXFormatError } from "../errors.js";
+const stateHeader = 'header';
+const statePage = 'page';
+const stateClose = 'close';
+const stateClosed = 'closed';
+function noChecksum(h) {
+    return (h.flags & 0x00000002) !== 0;
+}
+/** Decoder reads an LTX file from an in-memory buffer. */
+export class Decoder {
+    r;
+    header;
+    trailer = { postApplyChecksum: 0n, fileChecksum: 0n };
+    pageIndex = null;
+    state = stateHeader;
+    hash = new Crc64();
+    pageSeq = new Crc64();
+    chksum = 0n;
+    pageN = 0;
+    retainPageIndex;
+    constructor(buf) {
+        this.r = new ByteReader(buf);
+        this.retainPageIndex = true;
+    }
+    /** SetRetainPageIndex controls whether Close materializes the page-index map. */
+    setRetainPageIndex(retain) {
+        this.retainPageIndex = retain;
+    }
+    /** N returns the number of source bytes read. */
+    N() {
+        return this.r.pos;
+    }
+    /** PageN returns the number of pages decoded. */
+    PageN() {
+        return this.pageN;
+    }
+    /** Header returns a copy of the header. */
+    Header() {
+        return this.header;
+    }
+    /** Trailer returns the trailer. File checksum valid after Close(). */
+    Trailer() {
+        return this.trailer;
+    }
+    /** PageIndex returns the page index (after Close), or null if not retained. */
+    PageIndex() {
+        return this.pageIndex;
+    }
+    /** PostApplyPos returns the replication position after applying this file. */
+    PostApplyPos() {
+        return {
+            txID: this.header.maxTXID,
+            postApplyChecksum: this.trailer.postApplyChecksum,
+        };
+    }
+    /** DecodeHeader reads and validates the header frame. */
+    decodeHeader() {
+        const b = this.r.readFull(HeaderSize);
+        this.header = unmarshalHeader(b);
+        this.hash.update(b);
+        this.state = statePage;
+        validateHeader(this.header);
+        if (!noChecksum(this.header)) {
+            this.chksum = ChecksumFlag;
+        }
+    }
+    /**
+     * DecodePage reads the next page frame into `data`. Returns the page header,
+     * or null when the end-of-pages marker is reached.
+     */
+    decodePage(data) {
+        if (this.state === stateClosed)
+            throw new LTXFormatError('ltx decoder closed');
+        if (this.state === stateClose)
+            return null;
+        if (this.state !== statePage) {
+            throw new LTXFormatError(`cannot read page header, expected ${this.state}`);
+        }
+        if (data.length !== this.header.pageSize) {
+            throw new LTXFormatError(`invalid page buffer size: ${data.length}, expecting ${this.header.pageSize}`);
+        }
+        const b = this.r.readFull(PageHeaderSize);
+        const hdr = unmarshalPageHeader(b);
+        this.hash.update(b);
+        // An empty page header marks the end of the page block.
+        if (hdr.pgno === 0 && hdr.flags === 0) {
+            this.state = stateClose;
+            return null;
+        }
+        if (hdr.pgno > this.header.commit) {
+            throw new LTXFormatError(`page number ${hdr.pgno} out-of-bounds for commit size ${this.header.commit}`);
+        }
+        if (hdr.flags & PageHeaderFlagSize) {
+            // New block format: read size prefix, then LZ4 block data.
+            const sizeBuf = this.r.readFull(4);
+            this.hash.update(sizeBuf);
+            const dataSize = (sizeBuf[0] << 24 | sizeBuf[1] << 16 | sizeBuf[2] << 8 | sizeBuf[3]) >>> 0;
+            const compressed = this.r.readFull(dataSize);
+            const decompressed = decompressBlock(compressed, this.header.pageSize);
+            data.set(decompressed);
+        }
+        else {
+            throw new LTXFormatError('legacy LZ4 frame format not supported');
+        }
+        this.hash.update(data);
+        this.hashPgo(this.pageSeq, hdr.pgno);
+        this.pageN++;
+        // Track the rolling DB checksum for checksum-tracking snapshots.
+        if (isSnapshot(this.header) && !noChecksum(this.header)) {
+            if (hdr.pgno !== lockPgno(this.header.pageSize)) {
+                this.chksum = ChecksumFlag | (this.chksum ^ checksumPage(hdr.pgno, data));
+            }
+        }
+        return hdr;
+    }
+    /** Verify reads the entire file, discarding page data (for validation). */
+    verify() {
+        this.decodeHeader();
+        const data = new Uint8Array(this.header.pageSize);
+        for (;;) {
+            if (this.decodePage(data) === null)
+                break;
+        }
+        this.close();
+    }
+    /** DecodeDatabaseTo writes the snapshot as a SQLite database to `sink`. */
+    decodeDatabaseTo(sink) {
+        this.decodeHeader();
+        const hdr = this.header;
+        if (!isSnapshot(hdr)) {
+            throw new LTXFormatError('cannot decode non-snapshot LTX file to SQLite database');
+        }
+        const lockPg = lockPgno(hdr.pageSize);
+        const data = new Uint8Array(hdr.pageSize);
+        for (let pgno = 1; pgno <= hdr.commit; pgno++) {
+            if (pgno === lockPg) {
+                sink.write(new Uint8Array(hdr.pageSize));
+                continue;
+            }
+            const ph = this.decodePage(data);
+            if (ph === null) {
+                throw new LTXFormatError(`unexpected end of pages at pgno ${pgno}`);
+            }
+            if (ph.pgno !== pgno) {
+                throw new LTXFormatError(`unexpected pgno while decoding page: read ${ph.pgno}, expected ${pgno}`);
+            }
+            sink.write(data);
+        }
+        // Expect one final read to be the end-of-pages marker.
+        if (this.decodePage(data) !== null) {
+            throw new LTXFormatError('unexpected page after end of database');
+        }
+        this.close();
+    }
+    /** Close verifies the page index and trailer, then checks the file checksum. */
+    close() {
+        if (this.state === stateClosed)
+            return;
+        if (this.state !== stateClose) {
+            throw new LTXFormatError(`cannot close, expected ${this.state}`);
+        }
+        const index = new Map();
+        let n = 0;
+        let nextOffset = HeaderSize;
+        const seq = new Crc64();
+        const self = this;
+        parsePageIndex(this.r, (buf) => self.hash.update(buf), (pgno, offset, size) => {
+            if (pgno > self.header.commit) {
+                throw new LTXFormatError(`page index pgno ${pgno} exceeds commit ${self.header.commit}`);
+            }
+            if (offset < nextOffset) {
+                throw new LTXFormatError(`page index pgno ${pgno} offset ${offset} overlaps previous frame ending at ${nextOffset}`);
+            }
+            if (size <= PageHeaderSize) {
+                throw new LTXFormatError(`page index pgno ${pgno} has invalid frame size ${size}`);
+            }
+            nextOffset = offset + size;
+            n++;
+            self.hashPgo(seq, pgno);
+            if (index) {
+                index.set(pgno, {
+                    level: 0,
+                    minTXID: self.header.minTXID,
+                    maxTXID: self.header.maxTXID,
+                    offset,
+                    size,
+                });
+            }
+        });
+        if (n !== this.pageN) {
+            throw new LTXFormatError(`page index has ${n} entries but ${this.pageN} pages were decoded`);
+        }
+        if (seq.sum64() !== this.pageSeq.sum64()) {
+            throw new LTXFormatError('page index does not match the decoded page numbers');
+        }
+        this.pageIndex = this.retainPageIndex ? index : null;
+        // Read the trailer; everything except the file checksum field is hashed.
+        const t = this.r.readFull(TrailerSize);
+        this.hash.update(t.subarray(0, TrailerChecksumOffset));
+        this.trailer = unmarshalTrailer(t);
+        if (this.r.remaining > 0) {
+            throw new LTXFormatError('unexpected data after trailer');
+        }
+        const computed = ChecksumFlag | this.hash.sum64();
+        if (computed !== this.trailer.fileChecksum) {
+            throw new LTXFormatError('file checksum mismatch');
+        }
+        if (isSnapshot(this.header) && !noChecksum(this.header)) {
+            if (this.trailer.postApplyChecksum !== this.chksum) {
+                throw new LTXFormatError(`post-apply checksum in trailer (${this.trailer.postApplyChecksum.toString(16)}) does not match calculated checksum (${this.chksum.toString(16)})`);
+            }
+        }
+        this.state = stateClosed;
+    }
+    hashPgo(h, pgno) {
+        h.update(u32BE(pgno));
+    }
+}