@minnowdb/core 0.3.0 → 0.4.1

package/README.md

@@ -11,11 +11,13 @@ npm install @minnowdb/core
 - 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.
+- 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, live queries, snapshots, compaction, and configurable query memory.
+- 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,

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

package/dist/block-format/codecs.js

@@ -1,3 +1,14 @@
+/** A caller's explicit compressed-output ceiling was reached before an output join/allocation. */
+export class CompressionOutputLimitError extends RangeError {
+    byteLength;
+    maximumOutputLength;
+    constructor(byteLength, maximumOutputLength) {
+        super("Compressed payload exceeds caller output ceiling");
+        this.byteLength = byteLength;
+        this.maximumOutputLength = maximumOutputLength;
+        this.name = "CompressionOutputLimitError";
+    }
+}
 /**
  * The raw codec returns its input view unchanged in both directions: callers treat compressed
  * and decompressed payloads as read-only (encode copies the payload into the block envelope,
@@ -7,8 +18,14 @@
  */
 export const rawCodec = {
     id: "raw",
-    compress(bytes) {
-        return Promise.resolve(bytes);
+    async compress(bytes, maximumOutputLength) {
+        if (maximumOutputLength !== undefined) {
+            assertCallerOutputLength(maximumOutputLength);
+            if (bytes.byteLength > maximumOutputLength) {
+                throw new CompressionOutputLimitError(bytes.byteLength, maximumOutputLength);
+            }
+        }
+        return bytes;
     },
     decompress(bytes, expectedLength) {
         if (bytes.byteLength !== expectedLength)
@@ -43,19 +60,25 @@ export function getCompressionMemoryBound(compression, inputLength) {
         }
     }
 }
-async function transform(bytes, stream, maximumOutputLength = Number.POSITIVE_INFINITY, boundErrorMessage = "Decompressed payload exceeds declared length") {
+async function transform(bytes, stream, maximumOutputLength = Number.POSITIVE_INFINITY, boundErrorMessage = "Decompressed payload exceeds declared length", outputLimitError) {
     const write = (async () => {
         const writer = stream.writable.getWriter();
         await writer.write(new Uint8Array(bytes));
         await writer.close();
     })();
-    const [, result] = await Promise.all([
+    const [writeResult, readResult] = await Promise.allSettled([
         write,
-        readBounded(stream.readable, maximumOutputLength, boundErrorMessage),
+        readBounded(stream.readable, maximumOutputLength, boundErrorMessage, outputLimitError),
     ]);
-    return result;
+    // A reader-side bound failure intentionally cancels the writer. Preserve that precise error
+    // instead of racing it against the writer rejection caused by the cancellation.
+    if (readResult.status === "rejected")
+        throw readResult.reason;
+    if (writeResult.status === "rejected")
+        throw writeResult.reason;
+    return readResult.value;
 }
-async function readBounded(readable, maximumLength, boundErrorMessage) {
+async function readBounded(readable, maximumLength, boundErrorMessage, outputLimitError) {
     const reader = readable.getReader();
     const chunks = [];
     let length = 0;
@@ -65,8 +88,14 @@ async function readBounded(readable, maximumLength, boundErrorMessage) {
             break;
         length += value.byteLength;
         if (length > maximumLength) {
-            await reader.cancel(boundErrorMessage);
-            throw new Error(boundErrorMessage);
+            const error = outputLimitError?.(length) ?? new Error(boundErrorMessage);
+            try {
+                await reader.cancel(error);
+            }
+            catch {
+                // Cancellation is cleanup. The deterministic bound error remains the operation result.
+            }
+            throw error;
         }
         chunks.push(value);
     }
@@ -80,9 +109,17 @@ async function readBounded(readable, maximumLength, boundErrorMessage) {
 }
 export const gzipCodec = {
     id: "gzip",
-    async compress(bytes) {
+    async compress(bytes, maximumOutputLength) {
         const { maximumOutputBytes } = getCompressionMemoryBound("gzip", bytes.byteLength);
-        return transform(bytes, new CompressionStream("gzip"), maximumOutputBytes, "Gzip payload exceeds compression bound");
+        if (maximumOutputLength !== undefined)
+            assertCallerOutputLength(maximumOutputLength);
+        const outputLimit = Math.min(maximumOutputBytes, maximumOutputLength ?? maximumOutputBytes);
+        const callerLimited = outputLimit < maximumOutputBytes;
+        return transform(bytes, new CompressionStream("gzip"), outputLimit, callerLimited
+            ? "Compressed payload exceeds caller output ceiling"
+            : "Gzip payload exceeds compression bound", callerLimited
+            ? (byteLength) => new CompressionOutputLimitError(byteLength, outputLimit)
+            : undefined);
     },
     async decompress(bytes, expectedLength) {
         const output = await transform(bytes, new DecompressionStream("gzip"), expectedLength);
@@ -91,6 +128,11 @@ export const gzipCodec = {
         return output;
     },
 };
+function assertCallerOutputLength(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("Invalid compression output ceiling");
+    }
+}
 export function getCodec(id) {
     switch (id) {
         case "raw":
@@ -99,4 +141,3 @@ export function getCodec(id) {
             return gzipCodec;
     }
 }
-//# sourceMappingURL=codecs.js.map

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

@@ -1,8 +1,9 @@
-import type { BlockMetadata, ColumnInput, DecodedColumn, LogicalType } from "./types.js";
+import type { BlockMetadata, ColumnInput, DecodedColumn, LogicalType, ValidatedPhysicalColumn } from "./types.js";
 export declare function encodeColumn(input: ColumnInput): {
     bytes: Uint8Array;
     metadata: BlockMetadata;
     nullCount: number;
 };
 export declare function decodeColumn<T extends LogicalType>(type: T, bytes: Uint8Array, rowCount: number): DecodedColumn<T>;
-//# sourceMappingURL=column.d.ts.map
+/** Package-internal row materialization after the physical payload was already validated. */
+export declare function decodeValidatedColumn<T extends LogicalType>(column: ValidatedPhysicalColumn<T>): DecodedColumn<T>;