@minnowdb/core 0.2.1 → 0.4.0

package/README.md

@@ -1,42 +1,33 @@
 # @minnowdb/core
 
-Columnar SQL engine for the browser: real SQL over immutable snapshots, durable on IndexedDB or
-OPFS, with
-no WebAssembly to download. It runs in the thread that constructs it (`MinnowDatabase`), or in a
-worker through `MinnowDatabaseClient`, which mirrors the everyday query, write, migration,
-live-query, snapshot, and maintenance APIs.
-
-**[minnowdb.com](https://minnowdb.com)** — documentation, a live console, and benchmarks you
-run yourself.
+A columnar SQL database for the browser. Run PostgreSQL-style SQL over durable IndexedDB or OPFS
+storage with no server and no WebAssembly module.
 
 ```bash
 npm install @minnowdb/core
 ```
 
-- **SQL is the foundation** — parser, planner, optimizer, and a batch-based executor written here,
-  with no SQLite or DuckDB underneath. The supported surface ships as a checked-in feature matrix
-  (`@minnowdb/core/sql-feature-matrix.json`) that the engine is tested against.
-- **One schema, in TypeScript** — `table()`, `column`, and `schema()` declare tables once and
-  `migrate()` evolves them without rewriting stored data.
-- **Full-text search** — `MATCH` / BM25 on any column, with no index DDL to write.
-- **Live queries** — `liveQueries()` hands back a set whose subscribers get a fresh result after
-  any commit that could have changed it, across tabs.
-- **Durable browser storage** — compressed columnar blocks on IndexedDB or OPFS, atomic
-  multi-tab commits,
-  snapshot reads, compaction and GC.
-- **Memory-aware queries** — execution works in batches under a budget you set, and sorts and
-  grouped results can spill to storage. The budget is not a hard heap limit yet.
-- **Subpath exports** — `/storage`, `/storage/toolkit`, `/client`, `/worker`,
-  `/worker-protocol`, `/transactions`, `/plan`, `/block-format`, `/testing`.
-
-Guides, the API reference, and the SQL feature matrix live in the
-[docs](https://minnowdb.com/docs/), which are the single source of truth. Building with an agent?
-[minnowdb.com/agent-rules.md](https://minnowdb.com/agent-rules.md) is a short rules file to drop
-into an `AGENTS.md`, and [llms.txt](https://minnowdb.com/llms.txt) indexes the documentation in
-markdown.
-
-Every `@minnowdb` package shares a major version and moves independently inside it, so install
-them on the same major. See [Versioning](https://minnowdb.com/docs/reference/versioning/).
+- Direct SQL through `MinnowDatabase.query()` and `execute()`.
+- Joins, CTEs, window functions, grouping sets, upserts, `RETURNING`, triggers, exact decimals,
+  JSON/JSONB, arrays, enums, sequences, and savepoints.
+- Compressed column storage, secondary indexes, full-text search, and snapshot reads.
+- Atomic writes across tabs through IndexedDB or OPFS, strict durability by default, and explicit
+  origin-eviction persistence policy.
+- A ready-made worker client with the same everyday database API.
+- TypeScript schema declarations and metadata-only migrations, including SQL domains and
+  composite primary/foreign keys.
+- Batch writes, pull-driven query cursors, live queries, snapshots, compaction, and configurable
+  query memory.
+
+Use [the PostgreSQL compatibility page](https://minnowdb.com/docs/sql/feature-matrix/) for the
+exact SQL surface. Use [the documentation](https://minnowdb.com/docs/) for installation, storage,
+workers, transactions, and API details.
+
+The optional [Kysely dialect](https://minnowdb.com/docs/adapters/kysely/) connects Kysely's
+PostgreSQL compiler to the engine and derives its `DB` types from the same schema declaration.
+
+Every `@minnowdb` package in one application must use the same major version. See
+[Versioning](https://minnowdb.com/docs/reference/versioning/).
 
 ## License
 

package/dist/block-format/block.d.ts

@@ -1,6 +1,6 @@
 import type { BlockDescription, BlockMetadata, ColumnInput, Compression, DecodedBlock, DecodedPhysicalBlock, PhysicalColumnPayload } from "./types.js";
 /**
- * Version 1 layout (all integers little-endian):
+ * Version 2 layout (all integers little-endian):
  *
  *    0  magic "BRDB"
  *    4  envelope checksum: crc32 over bytes [8, headerLength + metadataLength)
@@ -12,35 +12,54 @@ import type { BlockDescription, BlockMetadata, ColumnInput, Compression, Decoded
  *   24  metadata length (u32)
  *   28  encoded length (u32)
  *   32  stored length (u32)
- *   36  payload checksum: crc32 over the uncompressed encoded payload
+ *   36  logical checksum: crc32 over the uncompressed encoded payload
+ *   40  stored checksum: crc32 over the stored payload, before decompression
  *
- * The envelope checksum authenticates every header field and the metadata JSON, so header-only
+ * The envelope checksum integrity-checks every header field and the metadata JSON, so header-only
  * reads (zone-map pruning, block inventories) can trust derived statistics without paying the
  * decompress-and-revalidate cost of the payload.
  */
 /**
- * The block envelope version. Every persisted block carries it, and `readBlock` refuses any
- * value it does not recognize -- so this number is a compatibility contract with every database
- * already sitting in a user's browser, not an internal detail.
+ * The first frozen block envelope version. Every persisted block carries it, and readers dispatch
+ * by this value, so the number is a compatibility contract rather than an internal detail.
  *
- * Changing it means older blocks stop being readable unless a read path for them is kept. Before
- * changing it, run `npm run fixture:format` on the *current* build to freeze what this version
- * writes; format-compatibility.test.ts then holds the new build to still reading it.
+ * Never change v2 decoding in place. A future writer gets a new number and keeps the v2 read path;
+ * format-vectors.test.ts permanently freezes Minnow-owned v2 bytes.
  */
-export declare const BLOCK_FORMAT_VERSION = 1;
+export declare const BLOCK_FORMAT_VERSION = 2;
+export declare const BLOCK_HEADER_LENGTH = 44;
+export declare const MAX_BLOCK_METADATA_BYTE_LENGTH = 1024;
+/** Absolute persisted value ceiling: envelope + metadata + maximum stored payload. */
+export declare const MAX_STORED_BLOCK_BYTE_LENGTH: number;
+/** A codec expanded an otherwise valid physical column beyond the stored block hard limit. */
+export declare class StoredBlockPayloadTooLargeError extends RangeError {
+    readonly byteLength: number;
+    constructor(byteLength: number);
+}
+/** Validates a codec result length without allocating the payload. */
+export declare function assertStoredBlockPayloadByteLength(byteLength: number): void;
 /**
  * Returns a conservative bound for the complete persisted block value: the fixed header, the
  * exact UTF-8 JSON metadata, and the selected codec's maximum stored payload.
  */
 export declare function maximumPhysicalBlockByteLength(encodedByteLength: number, metadata: BlockMetadata, compression: Compression): number;
 export declare function encodeBlock(input: ColumnInput, compression?: Compression): Promise<Uint8Array>;
-/** Encodes physical column bytes after validating their complete version-zero layout. */
+/** Encodes physical column bytes after validating their complete canonical v2 layout. */
 export declare function encodePhysicalBlock(input: PhysicalColumnPayload, compression?: Compression): Promise<Uint8Array>;
 export declare function decodeBlock(bytes: Uint8Array): Promise<DecodedBlock>;
 /**
  * Decompresses and checksum-verifies a block without materializing row values.
- * The returned physical byte array is owned by the result.
+ *
+ * For a raw block, `column.bytes` is a zero-copy view into `bytes`. Both views must be treated as
+ * immutable for the lifetime of the result. Gzip results own a new decompressed allocation.
  */
 export declare function decodePhysicalBlock(bytes: Uint8Array): Promise<DecodedPhysicalBlock>;
+/**
+ * Verifies every stored byte without decompressing or copying the payload.
+ *
+ * Snapshot import and OPFS recovery use this stronger operation before accepting a block.
+ * Planning and pruning should continue to use `inspectBlock`, which deliberately reads only the
+ * fixed header and metadata envelope.
+ */
+export declare function verifyStoredBlock(bytes: Uint8Array): BlockDescription;
 export declare function inspectBlock(bytes: Uint8Array): BlockDescription;
-//# sourceMappingURL=block.d.ts.map

package/dist/block-format/block.js

@@ -1,10 +1,10 @@
 import { crc32 } from "./checksum.js";
-import { decodeColumn, encodeColumn } from "./column.js";
-import { getCodec, getCompressionMemoryBound } from "./codecs.js";
-import { MAX_PHYSICAL_COLUMN_BYTE_LENGTH, validatePhysicalColumn } from "./physical.js";
+import { decodeValidatedColumn, encodeColumn } from "./column.js";
+import { CompressionOutputLimitError, getCodec, getCompressionMemoryBound } from "./codecs.js";
+import { assertBlockRowCount, MAX_PHYSICAL_COLUMN_BYTE_LENGTH, validatePhysicalColumn, } from "./physical.js";
 const MAGIC = Uint8Array.of(0x42, 0x52, 0x44, 0x42);
 /**
- * Version 1 layout (all integers little-endian):
+ * Version 2 layout (all integers little-endian):
  *
  *    0  magic "BRDB"
  *    4  envelope checksum: crc32 over bytes [8, headerLength + metadataLength)
@@ -16,53 +16,64 @@ const MAGIC = Uint8Array.of(0x42, 0x52, 0x44, 0x42);
  *   24  metadata length (u32)
  *   28  encoded length (u32)
  *   32  stored length (u32)
- *   36  payload checksum: crc32 over the uncompressed encoded payload
+ *   36  logical checksum: crc32 over the uncompressed encoded payload
+ *   40  stored checksum: crc32 over the stored payload, before decompression
  *
- * The envelope checksum authenticates every header field and the metadata JSON, so header-only
+ * The envelope checksum integrity-checks every header field and the metadata JSON, so header-only
  * reads (zone-map pruning, block inventories) can trust derived statistics without paying the
  * decompress-and-revalidate cost of the payload.
  */
 /**
- * The block envelope version. Every persisted block carries it, and `readBlock` refuses any
- * value it does not recognize -- so this number is a compatibility contract with every database
- * already sitting in a user's browser, not an internal detail.
+ * The first frozen block envelope version. Every persisted block carries it, and readers dispatch
+ * by this value, so the number is a compatibility contract rather than an internal detail.
  *
- * Changing it means older blocks stop being readable unless a read path for them is kept. Before
- * changing it, run `npm run fixture:format` on the *current* build to freeze what this version
- * writes; format-compatibility.test.ts then holds the new build to still reading it.
+ * Never change v2 decoding in place. A future writer gets a new number and keeps the v2 read path;
+ * format-vectors.test.ts permanently freezes Minnow-owned v2 bytes.
  */
-export const BLOCK_FORMAT_VERSION = 1;
+export const BLOCK_FORMAT_VERSION = 2;
 const VERSION = BLOCK_FORMAT_VERSION;
-const HEADER_LENGTH = 40;
+export const BLOCK_HEADER_LENGTH = 44;
+const HEADER_LENGTH = BLOCK_HEADER_LENGTH;
 const ENVELOPE_CHECKSUM_START = 8;
 const MAX_BLOCK_LENGTH = MAX_PHYSICAL_COLUMN_BYTE_LENGTH;
+export const MAX_BLOCK_METADATA_BYTE_LENGTH = 1_024;
+const MAX_METADATA_LENGTH = MAX_BLOCK_METADATA_BYTE_LENGTH;
+/** Absolute persisted value ceiling: envelope + metadata + maximum stored payload. */
+export const MAX_STORED_BLOCK_BYTE_LENGTH = BLOCK_HEADER_LENGTH + MAX_METADATA_LENGTH + MAX_PHYSICAL_COLUMN_BYTE_LENGTH;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder("utf-8", { fatal: true });
 const typeIds = { boolean: 1, number: 2, string: 3, datetime: 4 };
 const typesById = new Map(Object.entries(typeIds).map(([type, id]) => [id, type]));
-// Codec 1 was run-length encoding, removed because it was both slower and larger than raw on
-// every column shape measured. The ids of the survivors do not move: renumbering would make an
-// old block decode as the wrong codec instead of failing.
+// Codec 1 was a pre-freeze run-length prototype, removed because it was both slower and larger
+// than raw on every measured column shape. Keep the id permanently reserved so it can never be
+// confused with a different codec in diagnostic or development data.
 const codecIds = { raw: 0, gzip: 2 };
 const codecsById = new Map(Object.entries(codecIds).map(([codec, id]) => [id, codec]));
+/** A codec expanded an otherwise valid physical column beyond the stored block hard limit. */
+export class StoredBlockPayloadTooLargeError extends RangeError {
+    byteLength;
+    constructor(byteLength) {
+        super("Stored block payload exceeds maximum byte length");
+        this.byteLength = byteLength;
+        this.name = "StoredBlockPayloadTooLargeError";
+    }
+}
+/** Validates a codec result length without allocating the payload. */
+export function assertStoredBlockPayloadByteLength(byteLength) {
+    if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+        throw new RangeError("Invalid stored payload length");
+    }
+    if (byteLength > MAX_BLOCK_LENGTH)
+        throw new StoredBlockPayloadTooLargeError(byteLength);
+}
 /**
  * Returns a conservative bound for the complete persisted block value: the fixed header, the
  * exact UTF-8 JSON metadata, and the selected codec's maximum stored payload.
  */
 export function maximumPhysicalBlockByteLength(encodedByteLength, metadata, compression) {
     assertLength(encodedByteLength, "encoded payload");
-    let serializedMetadata;
-    try {
-        serializedMetadata = JSON.stringify(metadata);
-    }
-    catch {
-        throw new TypeError("Block metadata must be JSON serializable");
-    }
-    if (typeof serializedMetadata !== "string") {
-        throw new TypeError("Block metadata must be JSON serializable");
-    }
-    const metadataByteLength = textEncoder.encode(serializedMetadata).byteLength;
-    assertLength(metadataByteLength, "metadata");
+    const metadataByteLength = encodeCanonicalMetadata(metadata).byteLength;
+    assertMetadataLength(metadataByteLength);
     const maximumStoredPayloadBytes = getCompressionMemoryBound(compression, encodedByteLength).maximumOutputBytes;
     const total = HEADER_LENGTH + metadataByteLength + maximumStoredPayloadBytes;
     if (!Number.isSafeInteger(total)) {
@@ -71,8 +82,7 @@ export function maximumPhysicalBlockByteLength(encodedByteLength, metadata, comp
     return total;
 }
 export async function encodeBlock(input, compression = "raw") {
-    if (input.values.length > 0xffffffff)
-        throw new RangeError("Too many rows in one block");
+    assertBlockRowCount(input.values.length);
     const encoded = encodeColumn(input);
     return encodeValidatedPhysicalBlock({
         type: input.type,
@@ -82,16 +92,39 @@ export async function encodeBlock(input, compression = "raw") {
         metadata: encoded.metadata,
     }, compression);
 }
-/** Encodes physical column bytes after validating their complete version-zero layout. */
+/** Encodes physical column bytes after validating their complete canonical v2 layout. */
 export async function encodePhysicalBlock(input, compression = "raw") {
     return encodeValidatedPhysicalBlock(validatePhysicalColumn(input), compression);
 }
 async function encodeValidatedPhysicalBlock(input, compression) {
+    // validatePhysicalColumn constructs this exact closed metadata shape. Avoid serializing,
+    // parsing, and serializing it again on every write; the public sizing helper validates its
+    // independently supplied metadata because it has no such provenance.
     const metadata = textEncoder.encode(JSON.stringify(input.metadata));
-    const stored = await getCodec(compression).compress(input.bytes);
-    assertLength(metadata.byteLength, "metadata");
+    // Checksum before the first possible async yield. The gzip codec also takes its input copy
+    // synchronously when called, so caller mutation after encodePhysicalBlock returns cannot make
+    // the checksum and compressed bytes observe different physical payloads.
+    const logicalChecksum = crc32(input.bytes);
+    // Avoid an async yield on raw blocks: validation and the copy into the immutable envelope
+    // complete before a caller can mutate a physical input buffer. The gzip codec takes its own
+    // input copy before yielding to the native stream.
+    let stored;
+    try {
+        stored =
+            compression === "raw"
+                ? input.bytes
+                : await getCodec(compression).compress(input.bytes, MAX_BLOCK_LENGTH);
+    }
+    catch (error) {
+        if (error instanceof CompressionOutputLimitError) {
+            throw new StoredBlockPayloadTooLargeError(error.byteLength);
+        }
+        throw error;
+    }
+    assertMetadataLength(metadata.byteLength);
     assertLength(input.bytes.byteLength, "encoded payload");
-    assertLength(stored.byteLength, "stored payload");
+    assertStoredBlockPayloadByteLength(stored.byteLength);
+    const storedChecksum = compression === "raw" ? logicalChecksum : crc32(stored);
     const output = new Uint8Array(HEADER_LENGTH + metadata.byteLength + stored.byteLength);
     output.set(MAGIC);
     const view = new DataView(output.buffer);
@@ -106,30 +139,51 @@ async function encodeValidatedPhysicalBlock(input, compression) {
     view.setUint32(24, metadata.byteLength, true);
     view.setUint32(28, input.bytes.byteLength, true);
     view.setUint32(32, stored.byteLength, true);
-    view.setUint32(36, crc32(input.bytes), true);
+    view.setUint32(36, logicalChecksum, true);
+    view.setUint32(40, storedChecksum, true);
     output.set(metadata, HEADER_LENGTH);
     output.set(stored, HEADER_LENGTH + metadata.byteLength);
     view.setUint32(4, crc32(output.subarray(ENVELOPE_CHECKSUM_START, HEADER_LENGTH + metadata.byteLength)), true);
     return output;
 }
 export async function decodeBlock(bytes) {
-    const decoded = await decodePhysicalBlock(bytes);
+    // Materialize raw values before the first async yield. Otherwise a caller could mutate the
+    // input after its checksum passes but before decodeColumn reads it. The gzip codec takes an
+    // input copy synchronously, so its awaited path has no equivalent gap.
+    const description = verifyStoredBlock(bytes);
+    const decoded = description.compression === "raw"
+        ? validateDecodedPhysicalBlock(bytes.subarray(description.headerLength + description.metadataLength), description)
+        : await decodeVerifiedPhysicalBlock(bytes, description);
     return {
         description: decoded.description,
-        column: decodeColumn(decoded.description.type, decoded.column.bytes, decoded.description.rowCount),
+        column: decodeValidatedColumn(decoded.column),
     };
 }
 /**
  * Decompresses and checksum-verifies a block without materializing row values.
- * The returned physical byte array is owned by the result.
+ *
+ * For a raw block, `column.bytes` is a zero-copy view into `bytes`. Both views must be treated as
+ * immutable for the lifetime of the result. Gzip results own a new decompressed allocation.
  */
 export async function decodePhysicalBlock(bytes) {
-    const description = inspectBlock(bytes);
-    const metadataLength = bytes.byteLength - HEADER_LENGTH - description.storedLength;
-    const stored = bytes.subarray(HEADER_LENGTH + metadataLength);
+    const description = verifyStoredBlock(bytes);
+    if (description.compression === "raw") {
+        return validateDecodedPhysicalBlock(bytes.subarray(description.headerLength + description.metadataLength), description);
+    }
+    return decodeVerifiedPhysicalBlock(bytes, description);
+}
+async function decodeVerifiedPhysicalBlock(bytes, description) {
+    const stored = bytes.subarray(description.headerLength + description.metadataLength);
     const encoded = await getCodec(description.compression).decompress(stored, description.encodedLength);
-    if (crc32(encoded) !== description.checksum)
-        throw new Error("Block checksum mismatch");
+    // For raw blocks the stored and logical bytes are identical, and inspectBlock requires both
+    // declared checksums to agree. verifyStoredBlock therefore performed the logical check too,
+    // avoiding a second full scan on the default codec.
+    if (description.compression !== "raw" && crc32(encoded) !== description.checksum) {
+        throw new Error("Block logical checksum mismatch");
+    }
+    return validateDecodedPhysicalBlock(encoded, description);
+}
+function validateDecodedPhysicalBlock(encoded, description) {
     const column = validatePhysicalColumn({
         type: description.type,
         rowCount: description.rowCount,
@@ -145,22 +199,49 @@ export async function decodePhysicalBlock(bytes) {
         column,
     };
 }
+/**
+ * Verifies every stored byte without decompressing or copying the payload.
+ *
+ * Snapshot import and OPFS recovery use this stronger operation before accepting a block.
+ * Planning and pruning should continue to use `inspectBlock`, which deliberately reads only the
+ * fixed header and metadata envelope.
+ */
+export function verifyStoredBlock(bytes) {
+    const description = inspectBlock(bytes);
+    const storedStart = bytes.byteLength - description.storedLength;
+    if (crc32(bytes.subarray(storedStart)) !== description.storedChecksum) {
+        throw new Error("Block stored payload checksum mismatch");
+    }
+    return description;
+}
 export function inspectBlock(bytes) {
-    if (bytes.byteLength < HEADER_LENGTH)
+    // Only magic and version are common across versions. Dispatch before interpreting any later
+    // offsets, so future envelopes can grow or replace the v2 header without weakening its reader.
+    if (bytes.byteLength < 10)
         throw new Error("Truncated block header");
     if (!MAGIC.every((byte, index) => bytes[index] === byte))
         throw new Error("Invalid block magic");
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const formatVersion = view.getUint16(8, true);
-    if (formatVersion !== VERSION) {
-        throw new Error(`Unsupported block version ${String(formatVersion)}`);
+    switch (formatVersion) {
+        case 2:
+            return inspectV2Block(bytes);
+        default:
+            throw new Error(`Unsupported block version ${String(formatVersion)}`);
     }
+}
+/** Permanent reader for the frozen v2 envelope. */
+function inspectV2Block(bytes) {
+    if (bytes.byteLength < HEADER_LENGTH)
+        throw new Error("Truncated block header");
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const formatVersion = view.getUint16(8, true);
     if (view.getUint16(10, true) !== HEADER_LENGTH)
         throw new Error("Invalid block header length");
     const metadataLength = view.getUint32(24, true);
     const encodedLength = view.getUint32(28, true);
     const storedLength = view.getUint32(32, true);
-    assertLength(metadataLength, "metadata");
+    assertMetadataLength(metadataLength);
     assertLength(encodedLength, "encoded payload");
     assertLength(storedLength, "stored payload");
     if (HEADER_LENGTH + metadataLength + storedLength !== bytes.byteLength) {
@@ -172,6 +253,8 @@ export function inspectBlock(bytes) {
     if (envelope !== view.getUint32(4, true)) {
         throw new Error("Block envelope checksum mismatch");
     }
+    const rowCount = view.getUint32(16, true);
+    assertBlockRowCount(rowCount);
     const type = typesById.get(view.getUint8(12));
     if (type === undefined)
         throw new Error("Unknown logical type");
@@ -180,41 +263,83 @@ export function inspectBlock(bytes) {
     const codecId = view.getUint8(14);
     const compression = codecsById.get(codecId);
     if (compression === undefined) {
-        throw new Error(codecId === 1
-            ? "Block uses the removed RLE codec; rewrite it as raw or gzip with an older build"
-            : "Unknown compression codec");
+        throw new Error(codecId === 1 ? "Block uses reserved compression codec id 1" : "Unknown compression codec");
     }
     if (view.getUint8(15) !== 0)
         throw new Error("Unsupported mandatory block flags");
-    const rowCount = view.getUint32(16, true);
+    const checksum = view.getUint32(36, true);
+    const storedChecksum = view.getUint32(40, true);
+    if (compression === "raw" && checksum !== storedChecksum) {
+        throw new Error("Raw block checksums do not match");
+    }
+    if (compression === "raw" && encodedLength !== storedLength) {
+        throw new Error("Raw block lengths do not match");
+    }
     const nullCount = view.getUint32(20, true);
     if (nullCount > rowCount)
         throw new Error("Null count exceeds row count");
     let parsedMetadata;
+    let metadataJson;
     try {
-        parsedMetadata = JSON.parse(textDecoder.decode(bytes.subarray(HEADER_LENGTH, HEADER_LENGTH + metadataLength)));
+        metadataJson = textDecoder.decode(bytes.subarray(HEADER_LENGTH, HEADER_LENGTH + metadataLength));
+        parsedMetadata = JSON.parse(metadataJson);
     }
     catch {
         throw new Error("Invalid block metadata");
     }
     const metadata = parseMetadata(parsedMetadata);
+    // There is one canonical metadata representation. Rejecting alternate key order, duplicate
+    // keys, unknown fields, and insignificant whitespace keeps byte fixtures meaningful and avoids
+    // multiple envelopes describing the same block.
+    if (JSON.stringify(metadata) !== metadataJson)
+        throw new Error("Non-canonical block metadata");
     return {
         formatVersion,
+        headerLength: HEADER_LENGTH,
+        metadataLength,
         type,
         compression,
         rowCount,
         nullCount,
         encodedLength,
         storedLength,
-        checksum: view.getUint32(36, true),
+        checksum,
+        storedChecksum,
         metadata,
     };
 }
+function assertMetadataLength(length) {
+    if (!Number.isSafeInteger(length) || length < 0 || length > MAX_METADATA_LENGTH) {
+        throw new RangeError("Invalid metadata length");
+    }
+}
 function assertLength(length, name) {
     if (!Number.isSafeInteger(length) || length < 0 || length > MAX_BLOCK_LENGTH) {
         throw new RangeError(`Invalid ${name} length`);
     }
 }
+function encodeCanonicalMetadata(metadata) {
+    let source;
+    try {
+        source = JSON.stringify(metadata);
+    }
+    catch {
+        throw new TypeError("Block metadata must be canonical JSON");
+    }
+    if (typeof source !== "string")
+        throw new TypeError("Block metadata must be canonical JSON");
+    let canonical;
+    try {
+        canonical = parseMetadata(JSON.parse(source));
+    }
+    catch {
+        throw new TypeError("Block metadata must match the supported canonical shape");
+    }
+    if (JSON.stringify(canonical) !== source) {
+        throw new TypeError("Block metadata must match the supported canonical shape");
+    }
+    return textEncoder.encode(source);
+}
 function parseMetadata(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new Error("Invalid block metadata shape");
@@ -241,4 +366,3 @@ function metadataEquals(left, right) {
     }
     return left.zoneMap.min === right.zoneMap.min && left.zoneMap.max === right.zoneMap.max;
 }
-//# sourceMappingURL=block.js.map

package/dist/block-format/checksum.d.ts

@@ -4,4 +4,5 @@
  * times over, and the tail falls back to single-byte steps.
  */
 export declare function crc32(bytes: Uint8Array): number;
-//# sourceMappingURL=checksum.d.ts.map
+/** Extends an already-finalized CRC-32 without concatenating or retaining the preceding bytes. */
+export declare function crc32Continue(previous: number, bytes: Uint8Array): number;

package/dist/block-format/checksum.js

@@ -20,7 +20,11 @@ for (let slice = 1; slice < 8; slice += 1) {
  * times over, and the tail falls back to single-byte steps.
  */
 export function crc32(bytes) {
-    let checksum = 0xffffffff;
+    return crc32Continue(0, bytes);
+}
+/** Extends an already-finalized CRC-32 without concatenating or retaining the preceding bytes. */
+export function crc32Continue(previous, bytes) {
+    let checksum = (previous ^ 0xffffffff) >>> 0;
     const length = bytes.byteLength;
     const wordEnd = length - (length % 8);
     let index = 0;
@@ -53,4 +57,3 @@ export function crc32(bytes) {
     }
     return (checksum ^ 0xffffffff) >>> 0;
 }
-//# sourceMappingURL=checksum.js.map

package/dist/block-format/codecs.d.ts

@@ -1,9 +1,15 @@
 import type { Compression } from "./types.js";
 export interface CompressionCodec {
     readonly id: Compression;
-    compress(bytes: Uint8Array): Promise<Uint8Array>;
+    compress(bytes: Uint8Array, maximumOutputLength?: number): Promise<Uint8Array>;
     decompress(bytes: Uint8Array, expectedLength: number): Promise<Uint8Array>;
 }
+/** A caller's explicit compressed-output ceiling was reached before an output join/allocation. */
+export declare class CompressionOutputLimitError extends RangeError {
+    readonly byteLength: number;
+    readonly maximumOutputLength: number;
+    constructor(byteLength: number, maximumOutputLength: number);
+}
 export interface CompressionMemoryBound {
     /** Largest returned buffer owned by the caller. */
     readonly maximumOutputBytes: number;
@@ -21,4 +27,3 @@ export declare const rawCodec: CompressionCodec;
 export declare function getCompressionMemoryBound(compression: Compression, inputLength: number): CompressionMemoryBound;
 export declare const gzipCodec: CompressionCodec;
 export declare function getCodec(id: Compression): CompressionCodec;
-//# sourceMappingURL=codecs.d.ts.map