@minnowdb/core 0.3.0 → 0.4.0

package/dist/storage/opfs/rpc.d.ts

@@ -5,8 +5,9 @@
  * for the database plus the leader's instance id) and its `result` or `busy` into the
  * requester's, so block bytes are cloned once, into the tab that asked, rather than into every
  * tab. Correctness never rides on delivery: an operation is acknowledged only after the
- * leader's write-ahead log holds it, a lost message costs a retry, and a dead leader costs a
- * failover arbitrated by the storage lock, not by these messages.
+ * leader's write-ahead log holds it. Reads retry after failover; mutations surface an uncertain
+ * outcome instead of being executed twice. Leadership is arbitrated by the storage lock, not
+ * by these messages.
  */
 export type StoreRpcMessage = 
 /**
@@ -65,6 +66,17 @@ export interface SerializedStoreError {
     domException?: boolean;
     props?: Record<string, unknown>;
 }
+/** One legal maximum payload plus bounded envelope/catalog metadata. */
+export declare const MAX_OPFS_RPC_MESSAGE_BYTES: number;
+export declare const MAX_OPFS_RPC_IDENTIFIER_CHARACTERS = 1024;
+/** Conservative retained/transfer-byte estimate with total depth/cardinality refusal. */
+export declare function estimateRpcValueBytes(value: unknown): number;
+/** Total non-throwing parser for same-origin-but-untrusted BroadcastChannel traffic. */
+export declare function parseStoreRpcMessage(value: unknown, knownMethods: ReadonlySet<string>): StoreRpcMessage | undefined;
+/** Collision-resistant bounded identity; large byte leaves become SHA-256 descriptors. */
+export declare function fingerprintStoreRequest(method: string, args: unknown[]): Promise<{
+    signature: string;
+    retainedBytes: number;
+}>;
 export declare function serializeStoreError(error: unknown): SerializedStoreError;
 export declare function rehydrateStoreError(serialized: SerializedStoreError): Error;
-//# sourceMappingURL=rpc.d.ts.map

package/dist/storage/opfs/rpc.js

@@ -1,15 +1,237 @@
-import { CompactionJobConflictError, GarbageCollectionJobConflictError, LeaseConflictError, SnapshotManifestMissingError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, } from "../types.js";
+import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsUncertainOutcomeError, PostingBuildConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageFormatVersionError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, SchemaConflictError, } from "../types.js";
+import { dateIsoString } from "../../date-value.js";
+/** One legal maximum payload plus bounded envelope/catalog metadata. */
+export const MAX_OPFS_RPC_MESSAGE_BYTES = 66 * 1024 * 1024;
+export const MAX_OPFS_RPC_IDENTIFIER_CHARACTERS = 1024;
+const MAX_OPFS_RPC_DEPTH = 64;
+const MAX_OPFS_RPC_NODES = 1_100_000;
+function exactKeys(value, keys) {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function boundedRpcString(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_OPFS_RPC_IDENTIFIER_CHARACTERS);
+}
+/** Conservative retained/transfer-byte estimate with total depth/cardinality refusal. */
+export function estimateRpcValueBytes(value) {
+    const seen = new WeakSet();
+    let nodes = 0;
+    const visit = (current, depth) => {
+        nodes += 1;
+        if (nodes > MAX_OPFS_RPC_NODES || depth > MAX_OPFS_RPC_DEPTH) {
+            throw new RangeError("OPFS RPC value exceeds its structural limit");
+        }
+        if (current === null || current === undefined || typeof current === "boolean")
+            return 8;
+        if (typeof current === "number" || typeof current === "bigint")
+            return 16;
+        if (typeof current === "string")
+            return 16 + current.length * 2;
+        if (typeof current !== "object")
+            throw new TypeError("OPFS RPC value is not cloneable data");
+        if (seen.has(current))
+            throw new TypeError("OPFS RPC value must not contain cycles");
+        seen.add(current);
+        if (typeof SharedArrayBuffer !== "undefined" && current instanceof SharedArrayBuffer) {
+            throw new TypeError("OPFS RPC values must not use SharedArrayBuffer");
+        }
+        if (current instanceof ArrayBuffer)
+            return 32 + current.byteLength;
+        if (ArrayBuffer.isView(current)) {
+            if (typeof SharedArrayBuffer !== "undefined" && current.buffer instanceof SharedArrayBuffer) {
+                throw new TypeError("OPFS RPC values must not use SharedArrayBuffer");
+            }
+            return 48 + current.byteLength;
+        }
+        if (current instanceof Date)
+            return 32;
+        let bytes = 32;
+        if (Array.isArray(current)) {
+            for (const item of current)
+                bytes += visit(item, depth + 1);
+        }
+        else {
+            if (Object.getPrototypeOf(current) !== Object.prototype &&
+                Object.getPrototypeOf(current) !== null) {
+                throw new TypeError("OPFS RPC value has an unsupported prototype");
+            }
+            for (const [key, item] of Object.entries(current)) {
+                bytes += key.length * 2 + visit(item, depth + 1);
+            }
+        }
+        if (!Number.isSafeInteger(bytes) || bytes > MAX_OPFS_RPC_MESSAGE_BYTES) {
+            throw new RangeError("OPFS RPC message exceeds its byte limit");
+        }
+        return bytes;
+    };
+    const bytes = visit(value, 0);
+    if (bytes > MAX_OPFS_RPC_MESSAGE_BYTES) {
+        throw new RangeError("OPFS RPC message exceeds its byte limit");
+    }
+    return bytes;
+}
+function validSerializedError(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    const allowed = record.props === undefined
+        ? record.domException === undefined
+            ? ["name", "message"]
+            : ["name", "message", "domException"]
+        : record.domException === undefined
+            ? ["name", "message", "props"]
+            : ["name", "message", "domException", "props"];
+    return (exactKeys(record, allowed) &&
+        boundedRpcString(record.name) &&
+        typeof record.message === "string" &&
+        record.message.length <= MAX_OPFS_RPC_IDENTIFIER_CHARACTERS * 4 &&
+        (record.domException === undefined || record.domException === true) &&
+        (record.props === undefined ||
+            (typeof record.props === "object" && record.props !== null && !Array.isArray(record.props))));
+}
+/** Total non-throwing parser for same-origin-but-untrusted BroadcastChannel traffic. */
+export function parseStoreRpcMessage(value, knownMethods) {
+    try {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return undefined;
+        const record = value;
+        estimateRpcValueBytes(record);
+        switch (record.kind) {
+            case "op":
+                if (!exactKeys(record, ["kind", "requestId", "from", "method", "args"]) ||
+                    !boundedRpcString(record.requestId) ||
+                    !boundedRpcString(record.from) ||
+                    !boundedRpcString(record.method) ||
+                    !knownMethods.has(record.method) ||
+                    !Array.isArray(record.args) ||
+                    estimateRpcValueBytes(record.args) > MAX_OPFS_RPC_MESSAGE_BYTES)
+                    return undefined;
+                return record;
+            case "result":
+                if (!boundedRpcString(record.requestId) || typeof record.ok !== "boolean")
+                    return undefined;
+                if (record.ok) {
+                    if (!exactKeys(record, ["kind", "requestId", "ok", "value"]))
+                        return undefined;
+                    estimateRpcValueBytes(record.value);
+                }
+                else if (!exactKeys(record, ["kind", "requestId", "ok", "error"]) ||
+                    !validSerializedError(record.error))
+                    return undefined;
+                return record;
+            case "busy":
+                return exactKeys(record, ["kind", "requestId"]) && boundedRpcString(record.requestId)
+                    ? record
+                    : undefined;
+            case "leader":
+            case "released":
+                return exactKeys(record, ["kind", "leaderId"]) && boundedRpcString(record.leaderId)
+                    ? record
+                    : undefined;
+            case "ping":
+                return exactKeys(record, ["kind"]) ? record : undefined;
+            case "bid":
+                return exactKeys(record, ["kind", "bidderId", "foreground"]) &&
+                    boundedRpcString(record.bidderId) &&
+                    typeof record.foreground === "boolean"
+                    ? record
+                    : undefined;
+            case "yield":
+                return exactKeys(record, ["kind", "to"]) && boundedRpcString(record.to)
+                    ? record
+                    : undefined;
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+function hex(bytes) {
+    let result = "";
+    for (const byte of bytes)
+        result += byte.toString(16).padStart(2, "0");
+    return result;
+}
+/** Collision-resistant bounded identity; large byte leaves become SHA-256 descriptors. */
+export async function fingerprintStoreRequest(method, args) {
+    const retainedBytes = estimateRpcValueBytes(args);
+    const seen = new WeakSet();
+    const normalize = async (value, depth) => {
+        if (depth > MAX_OPFS_RPC_DEPTH)
+            throw new RangeError("OPFS RPC value exceeds its depth limit");
+        if (typeof value === "bigint")
+            return ["bigint", value.toString()];
+        if (value === undefined)
+            return ["undefined"];
+        if (typeof value === "number") {
+            return ["number", Object.is(value, -0) ? "-0" : String(value)];
+        }
+        if (value === null || typeof value !== "object")
+            return value;
+        if (seen.has(value))
+            throw new TypeError("OPFS RPC value must not contain cycles");
+        seen.add(value);
+        if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+            const { byteLength } = value;
+            let digestInput;
+            if (value instanceof ArrayBuffer)
+                digestInput = value;
+            else if (!(value.buffer instanceof ArrayBuffer)) {
+                throw new TypeError("OPFS RPC values must not use SharedArrayBuffer");
+            }
+            else if (value.byteOffset === 0 && value.byteLength === value.buffer.byteLength) {
+                digestInput = value.buffer;
+            }
+            else {
+                digestInput = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+            }
+            const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", digestInput));
+            return ["bytes", value.constructor.name, byteLength, hex(digest)];
+        }
+        if (value instanceof Date)
+            return ["date", dateIsoString(value)];
+        if (Array.isArray(value)) {
+            return Promise.all(value.map((item) => normalize(item, depth + 1)));
+        }
+        const entries = [];
+        for (const key of Object.keys(value).sort()) {
+            entries.push([key, await normalize(value[key], depth + 1)]);
+        }
+        return ["object", entries];
+    };
+    const canonical = JSON.stringify([method, await normalize(args, 0)]);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical)));
+    return { signature: `${String(retainedBytes)}:${hex(digest)}`, retainedBytes };
+}
 const errorRegistry = new Map([
+    BlockReadBatchTooLargeError,
+    CompactionBacklogError,
     WriteConflictError,
+    SchemaConflictError,
     UniqueKeyConflictError,
     UniqueIndexCoverageError,
     TableRecordConflictError,
     TransactionRecordConflictError,
     LeaseConflictError,
+    LeaseExpiredError,
+    LeaseOwnerConflictError,
     CompactionJobConflictError,
     GarbageCollectionJobConflictError,
+    IndexedDbSchemaUpgradeBlockedError,
     TempOwnerConflictError,
+    StorageResourceLimitError,
+    TableInUseError,
     SnapshotManifestMissingError,
+    SnapshotImportConflictError,
+    UniqueKeyBuildConflictError,
+    PostingBuildConflictError,
+    StorageCorruptionError,
+    StorageFormatVersionError,
+    OpfsUncertainOutcomeError,
 ].map((constructor) => [constructor.name, constructor]));
 export function serializeStoreError(error) {
     if (error instanceof DOMException) {
@@ -56,4 +278,3 @@ export function rehydrateStoreError(serialized) {
         Object.assign(error, serialized.props);
     return error;
 }
-//# sourceMappingURL=rpc.js.map

package/dist/storage/opfs/snapshot-ledger.d.ts

@@ -0,0 +1,40 @@
+import { type SnapshotFrame, type SnapshotFrameKind } from "../types.js";
+import { type Placement } from "../toolkit/extents.js";
+import { OpfsTree } from "./files.js";
+export type SnapshotLedgerKind = "export" | "import" | "completed";
+export interface SnapshotLedgerRecord {
+    readonly sequence: number;
+    readonly kind: SnapshotFrameKind;
+    readonly itemCount: number;
+    readonly key: string | null;
+    readonly payloadLength: number;
+    readonly checksum: number;
+    /** Metadata payloads are inline. Block payloads live once in an extent placement. */
+    readonly payload?: Uint8Array;
+    readonly placement?: Placement;
+}
+export interface SnapshotLedgerRead {
+    readonly record: SnapshotLedgerRecord;
+    readonly offset: number;
+    readonly nextOffset: number;
+}
+export declare function snapshotLedgerPath(kind: SnapshotLedgerKind, id: string): string[];
+/**
+ * Checksummed append-only control file for one snapshot session. A checkpoint stores only the
+ * committed prefix length. Bytes beyond it are unpublished and truncated on recovery, so a
+ * large import/export never creates a database-sized WAL/checkpoint collection.
+ */
+export declare class SnapshotFrameLedger {
+    #private;
+    private constructor();
+    static open(tree: OpfsTree, kind: SnapshotLedgerKind, id: string, committedLength: number, create: boolean): Promise<SnapshotFrameLedger>;
+    get byteLength(): number;
+    append(frame: SnapshotFrame, placement?: Placement): SnapshotLedgerRead;
+    read(offset: number, committedLength?: number): SnapshotLedgerRead;
+    records(committedLength?: number): IterableIterator<SnapshotLedgerRead>;
+    flush(): void;
+    truncate(length: number): void;
+    /** Recovery adopts the next WAL-published prefix without copying or re-appending its bytes. */
+    adoptLength(length: number): void;
+    close(): void;
+}

package/dist/storage/opfs/snapshot-ledger.js

@@ -0,0 +1,281 @@
+import { crc32 } from "../../block-format/checksum.js";
+import { MAX_STORED_BLOCK_BYTE_LENGTH } from "../../block-format/index.js";
+import { MAX_SNAPSHOT_FRAME_ITEMS, MAX_SNAPSHOT_METADATA_FRAME_BYTES, SNAPSHOT_FRAME_KINDS, validateStorageId, } from "../types.js";
+import { assertValidPlacement } from "../toolkit/extents.js";
+import { readFully, writeFully } from "../toolkit/sync-file.js";
+import { encodeSegment } from "./files.js";
+const LEDGER_MAGIC = 0x534c_4731; // SLG1
+const LEDGER_PREFIX_BYTES = 80;
+const MODE_INLINE = 0;
+const MODE_PLACEMENT = 1;
+export function snapshotLedgerPath(kind, id) {
+    validateStorageId(id);
+    return ["snapshots-v1", kind, encodeSegment(id)];
+}
+/**
+ * Checksummed append-only control file for one snapshot session. A checkpoint stores only the
+ * committed prefix length. Bytes beyond it are unpublished and truncated on recovery, so a
+ * large import/export never creates a database-sized WAL/checkpoint collection.
+ */
+export class SnapshotFrameLedger {
+    #handle;
+    #length;
+    #closed = false;
+    constructor(handle, length) {
+        this.#handle = handle;
+        this.#length = length;
+    }
+    static async open(tree, kind, id, committedLength, create) {
+        if (!Number.isSafeInteger(committedLength) || committedLength < 0) {
+            throw new RangeError("Snapshot ledger length is invalid");
+        }
+        const handle = await tree.openHandle(snapshotLedgerPath(kind, id), { create });
+        const size = handle.getSize();
+        if (size < committedLength) {
+            handle.close();
+            throw new Error(`Snapshot ledger is shorter than its committed prefix: ${String(size)} < ` +
+                String(committedLength));
+        }
+        // A checkpoint's committed prefix may have a valid WAL-covered suffix after it. Keep the
+        // physical suffix until recovery either adopts each frame or truncates it after replay.
+        return new SnapshotFrameLedger(handle, committedLength);
+    }
+    get byteLength() {
+        return this.#length;
+    }
+    append(frame, placement) {
+        this.#assertOpen();
+        const encoded = encodeLedgerRecord(frame, placement);
+        const offset = this.#length;
+        const nextOffset = safeLedgerSum(offset, encoded.byteLength, "Snapshot ledger length");
+        writeFully(this.#handle, encoded, offset, "appending snapshot frame ledger");
+        this.#length = nextOffset;
+        return { record: ledgerRecordFromFrame(frame, placement), offset, nextOffset };
+    }
+    read(offset, committedLength = this.#length) {
+        this.#assertOpen();
+        if (!Number.isSafeInteger(offset) ||
+            offset < 0 ||
+            !Number.isSafeInteger(committedLength) ||
+            committedLength < offset ||
+            committedLength > this.#length ||
+            committedLength - offset < LEDGER_PREFIX_BYTES) {
+            throw new RangeError("Snapshot ledger read offset is invalid");
+        }
+        const prefix = new Uint8Array(LEDGER_PREFIX_BYTES);
+        readFully(this.#handle, prefix, offset, "reading snapshot frame ledger prefix");
+        const view = new DataView(prefix.buffer);
+        if (view.getUint32(0, true) !== LEDGER_MAGIC) {
+            throw new Error("Snapshot ledger record marker mismatch");
+        }
+        const recordLength = view.getUint32(4, true);
+        if (recordLength < LEDGER_PREFIX_BYTES ||
+            recordLength > MAX_SNAPSHOT_METADATA_FRAME_BYTES + LEDGER_PREFIX_BYTES + 3_072 ||
+            recordLength > committedLength - offset) {
+            throw new Error("Snapshot ledger record length is invalid");
+        }
+        const encoded = new Uint8Array(recordLength);
+        readFully(this.#handle, encoded, offset, "reading snapshot frame ledger record");
+        const expectedRecordChecksum = new DataView(encoded.buffer).getUint32(76, true);
+        new DataView(encoded.buffer).setUint32(76, 0, true);
+        if (crc32(encoded) !== expectedRecordChecksum) {
+            throw new Error("Snapshot ledger record checksum mismatch");
+        }
+        new DataView(encoded.buffer).setUint32(76, expectedRecordChecksum, true);
+        const record = decodeLedgerRecord(encoded);
+        return {
+            record,
+            offset,
+            nextOffset: safeLedgerSum(offset, recordLength, "Snapshot ledger read offset"),
+        };
+    }
+    *records(committedLength = this.#length) {
+        let offset = 0;
+        while (offset < committedLength) {
+            const read = this.read(offset, committedLength);
+            yield read;
+            offset = read.nextOffset;
+        }
+        if (offset !== committedLength)
+            throw new Error("Snapshot ledger prefix ends mid-record");
+    }
+    flush() {
+        this.#assertOpen();
+        this.#handle.flush();
+    }
+    truncate(length) {
+        this.#assertOpen();
+        if (!Number.isSafeInteger(length) || length < 0 || length > this.#length) {
+            throw new RangeError("Snapshot ledger truncation is invalid");
+        }
+        this.#handle.truncate(length);
+        this.#length = length;
+    }
+    /** Recovery adopts the next WAL-published prefix without copying or re-appending its bytes. */
+    adoptLength(length) {
+        this.#assertOpen();
+        if (!Number.isSafeInteger(length) || length < this.#length || length > this.#handle.getSize()) {
+            throw new RangeError("Snapshot ledger recovery length is invalid");
+        }
+        this.#length = length;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#handle.close();
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error("Snapshot ledger is closed");
+    }
+}
+function encodeLedgerRecord(frame, placement) {
+    validateFrameScalars(frame);
+    const isBlock = frame.kind === "block";
+    if (isBlock !== (placement !== undefined)) {
+        throw new TypeError("Snapshot ledger block placement is inconsistent");
+    }
+    if (placement !== undefined) {
+        assertValidPlacement(placement);
+        if (placement.length !== frame.payload.byteLength || placement.checksum !== frame.checksum) {
+            throw new Error("Snapshot block placement disagrees with its frame");
+        }
+    }
+    const keyBytes = frame.key === null ? new Uint8Array() : new TextEncoder().encode(frame.key);
+    const inlineLength = placement === undefined ? frame.payload.byteLength : 0;
+    const recordLength = safeLedgerSum(LEDGER_PREFIX_BYTES + keyBytes.byteLength, inlineLength, "Snapshot ledger record length");
+    const encoded = new Uint8Array(recordLength);
+    const view = new DataView(encoded.buffer);
+    view.setUint32(0, LEDGER_MAGIC, true);
+    view.setUint32(4, recordLength, true);
+    view.setBigUint64(8, BigInt(frame.sequence), true);
+    view.setUint32(16, SNAPSHOT_FRAME_KINDS.indexOf(frame.kind), true);
+    view.setUint32(20, frame.itemCount, true);
+    view.setUint32(24, keyBytes.byteLength, true);
+    view.setUint32(28, placement === undefined ? MODE_INLINE : MODE_PLACEMENT, true);
+    view.setBigUint64(32, BigInt(frame.payload.byteLength), true);
+    view.setUint32(40, frame.checksum, true);
+    if (placement !== undefined) {
+        view.setBigUint64(44, BigInt(placement.extent), true);
+        view.setBigUint64(52, BigInt(placement.offset), true);
+        view.setBigUint64(60, BigInt(placement.length), true);
+        view.setUint32(68, placement.checksum, true);
+    }
+    // 72..75 are reserved zero; 76..79 is the record checksum itself.
+    encoded.set(keyBytes, LEDGER_PREFIX_BYTES);
+    if (placement === undefined)
+        encoded.set(frame.payload, LEDGER_PREFIX_BYTES + keyBytes.byteLength);
+    view.setUint32(76, 0, true);
+    view.setUint32(76, crc32(encoded), true);
+    return encoded;
+}
+function decodeLedgerRecord(encoded) {
+    const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+    const sequence = Number(view.getBigUint64(8, true));
+    const kind = SNAPSHOT_FRAME_KINDS[view.getUint32(16, true)];
+    const itemCount = view.getUint32(20, true);
+    const keyLength = view.getUint32(24, true);
+    const mode = view.getUint32(28, true);
+    const payloadLength = Number(view.getBigUint64(32, true));
+    const checksum = view.getUint32(40, true);
+    if (kind === undefined ||
+        !Number.isSafeInteger(sequence) ||
+        sequence < 0 ||
+        itemCount < 1 ||
+        itemCount > MAX_SNAPSHOT_FRAME_ITEMS ||
+        !Number.isSafeInteger(payloadLength) ||
+        payloadLength < 1 ||
+        (kind === "block"
+            ? payloadLength > MAX_STORED_BLOCK_BYTE_LENGTH
+            : payloadLength > MAX_SNAPSHOT_METADATA_FRAME_BYTES) ||
+        (mode !== MODE_INLINE && mode !== MODE_PLACEMENT) ||
+        encoded.subarray(72, 76).some((byte) => byte !== 0)) {
+        throw new TypeError("Snapshot ledger record header is invalid");
+    }
+    const inlineLength = mode === MODE_INLINE ? payloadLength : 0;
+    if (LEDGER_PREFIX_BYTES + keyLength + inlineLength !== encoded.byteLength) {
+        throw new Error("Snapshot ledger record body length is invalid");
+    }
+    let key = null;
+    if (keyLength > 0) {
+        try {
+            key = validateStorageId(new TextDecoder("utf-8", { fatal: true }).decode(encoded.subarray(LEDGER_PREFIX_BYTES, LEDGER_PREFIX_BYTES + keyLength)));
+        }
+        catch {
+            throw new TypeError("Snapshot ledger key is not canonical UTF-8");
+        }
+    }
+    if ((kind === "block") !== (key !== null) || (kind === "block") !== (mode === MODE_PLACEMENT)) {
+        throw new TypeError("Snapshot ledger frame identity is inconsistent");
+    }
+    if (mode === MODE_INLINE) {
+        const payload = encoded.slice(LEDGER_PREFIX_BYTES + keyLength);
+        if (crc32(payload) !== checksum)
+            throw new Error("Snapshot ledger payload checksum mismatch");
+        return { sequence, kind, itemCount, key, payloadLength, checksum, payload };
+    }
+    const placement = {
+        extent: Number(view.getBigUint64(44, true)),
+        offset: Number(view.getBigUint64(52, true)),
+        length: Number(view.getBigUint64(60, true)),
+        checksum: view.getUint32(68, true),
+    };
+    assertValidPlacement(placement);
+    if (placement.length !== payloadLength || placement.checksum !== checksum) {
+        throw new Error("Snapshot ledger placement disagrees with its frame");
+    }
+    return { sequence, kind, itemCount, key, payloadLength, checksum, placement };
+}
+function ledgerRecordFromFrame(frame, placement) {
+    return {
+        sequence: frame.sequence,
+        kind: frame.kind,
+        itemCount: frame.itemCount,
+        key: frame.key,
+        payloadLength: frame.payload.byteLength,
+        checksum: frame.checksum,
+        ...(placement === undefined ? { payload: frame.payload } : { placement }),
+    };
+}
+function validateFrameScalars(frame) {
+    if (!Number.isSafeInteger(frame.sequence) ||
+        frame.sequence < 0 ||
+        !SNAPSHOT_FRAME_KINDS.includes(frame.kind) ||
+        !Number.isSafeInteger(frame.itemCount) ||
+        frame.itemCount < 1 ||
+        frame.itemCount > MAX_SNAPSHOT_FRAME_ITEMS ||
+        !(frame.payload instanceof Uint8Array) ||
+        !Number.isSafeInteger(frame.checksum) ||
+        frame.checksum < 0 ||
+        frame.checksum > 0xffff_ffff) {
+        throw new TypeError("Snapshot frame is invalid");
+    }
+    if (crc32(frame.payload) !== frame.checksum) {
+        throw new Error("Snapshot frame checksum mismatch");
+    }
+    if (frame.kind === "block") {
+        if (frame.key === null || frame.itemCount !== 1) {
+            throw new TypeError("Snapshot block frame identity is invalid");
+        }
+        validateStorageId(frame.key);
+        if (frame.payload.byteLength < 1 || frame.payload.byteLength > MAX_STORED_BLOCK_BYTE_LENGTH) {
+            throw new RangeError("Snapshot block frame is too large");
+        }
+    }
+    else if (frame.key !== null ||
+        frame.payload.byteLength < 1 ||
+        frame.payload.byteLength > MAX_SNAPSHOT_METADATA_FRAME_BYTES) {
+        throw new TypeError("Snapshot metadata frame identity is invalid");
+    }
+}
+function safeLedgerSum(left, right, label) {
+    if (!Number.isSafeInteger(left) ||
+        left < 0 ||
+        !Number.isSafeInteger(right) ||
+        right < 0 ||
+        left > Number.MAX_SAFE_INTEGER - right) {
+        throw new RangeError(`${label} exceeds the safe integer range`);
+    }
+    return left + right;
+}