@minnowdb/core 0.2.1 → 0.4.0

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>;

package/dist/block-format/column.js

@@ -1,3 +1,6 @@
+import { dateMilliseconds } from "../date-value.js";
+import { physicalColumnByteLength, validatePhysicalColumn } from "./physical.js";
+import { wellFormedUtf8ByteLength } from "./unicode.js";
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder("utf-8", { fatal: true });
 // The on-disk format is little-endian; bulk Float64 writes use platform order when they match.
@@ -17,37 +20,74 @@ export function encodeColumn(input) {
     // the validity bitmap from the value payload and persist a corrupt block. A hole reads as
     // undefined and is rejected like any other non-value.
     const rowCount = input.values.length;
-    const validity = new Uint8Array(bitmapLength(rowCount));
-    let nullCount = 0;
-    for (let index = 0; index < rowCount; index += 1) {
-        const value = input.values[index];
-        if (value === undefined)
-            throw new TypeError("Column values cannot be undefined");
-        if (value !== null)
-            setBit(validity, index);
-        else
-            nullCount += 1;
+    // Validate the fixed portion before allocation. Its format-level row cap bounds the largest
+    // fixed-width allocation to about 8 MiB, so boolean, number, and datetime columns validate and
+    // encode each accessor value in one pass. Reading them twice would both waste a full scan and
+    // introduce a needless time-of-check/time-of-use boundary for accessor-backed inputs.
+    physicalColumnByteLength(input.type, rowCount);
+    let stringContentByteLength = 0;
+    if (input.type === "string") {
+        // Variable-width output still needs an exact sizing pass before allocation. The encode pass
+        // below revalidates the local value it writes, so a changing accessor cannot smuggle invalid
+        // UTF-16 or make offsets disagree with the content buffer.
+        for (let index = 0; index < rowCount; index += 1) {
+            const value = input.values[index];
+            if (value === undefined)
+                throw new TypeError("Column values cannot be undefined");
+            if (value !== null) {
+                if (typeof value !== "string") {
+                    throw new TypeError("String columns accept only strings or null");
+                }
+                stringContentByteLength += wellFormedUtf8ByteLength(value);
+                if (!Number.isSafeInteger(stringContentByteLength)) {
+                    throw new RangeError("Invalid string content byte length");
+                }
+            }
+        }
     }
+    physicalColumnByteLength(input.type, rowCount, stringContentByteLength);
+    const validity = new Uint8Array(bitmapLength(rowCount));
     switch (input.type) {
         case "boolean": {
             const values = new Uint8Array(bitmapLength(rowCount));
+            let nullCount = 0;
             for (let index = 0; index < rowCount; index += 1) {
-                if (input.values[index] === true)
-                    setBit(values, index);
+                const value = input.values[index];
+                if (value === undefined)
+                    throw new TypeError("Column values cannot be undefined");
+                if (value !== null && typeof value !== "boolean") {
+                    throw new TypeError("Boolean columns accept only booleans or null");
+                }
+                if (value === null)
+                    nullCount += 1;
+                else {
+                    setBit(validity, index);
+                    if (value)
+                        setBit(values, index);
+                }
             }
             return { bytes: join(validity, values), metadata: {}, nullCount };
         }
         case "number": {
             const values = new Float64Array(rowCount);
             const view = PLATFORM_LITTLE_ENDIAN ? undefined : new DataView(values.buffer);
+            let nullCount = 0;
             let min = Number.POSITIVE_INFINITY;
             let max = Number.NEGATIVE_INFINITY;
             for (let index = 0; index < rowCount; index += 1) {
                 const value = input.values[index];
-                if (value === null || value === undefined)
+                if (value === undefined)
+                    throw new TypeError("Column values cannot be undefined");
+                if (value === null) {
+                    nullCount += 1;
                     continue;
+                }
+                if (typeof value !== "number") {
+                    throw new TypeError("Number columns accept only numbers or null");
+                }
                 if (!Number.isFinite(value))
                     throw new TypeError("Number values must be finite");
+                setBit(validity, index);
                 if (view === undefined)
                     values[index] = value;
                 else
@@ -61,15 +101,24 @@ export function encodeColumn(input) {
         case "datetime": {
             const values = new Float64Array(rowCount);
             const view = PLATFORM_LITTLE_ENDIAN ? undefined : new DataView(values.buffer);
+            let nullCount = 0;
             let min = Number.POSITIVE_INFINITY;
             let max = Number.NEGATIVE_INFINITY;
             for (let index = 0; index < rowCount; index += 1) {
                 const value = input.values[index];
-                if (value === null || value === undefined)
+                if (value === undefined)
+                    throw new TypeError("Column values cannot be undefined");
+                if (value === null) {
+                    nullCount += 1;
                     continue;
-                const milliseconds = value.getTime();
+                }
+                if (!(value instanceof Date)) {
+                    throw new TypeError("Datetime columns accept only Date objects or null");
+                }
+                const milliseconds = dateMilliseconds(value);
                 if (!Number.isFinite(milliseconds))
                     throw new TypeError("Datetime values must be valid Dates");
+                setBit(validity, index);
                 if (view === undefined)
                     values[index] = milliseconds;
                 else
@@ -81,25 +130,40 @@ export function encodeColumn(input) {
             return { bytes: join(validity, new Uint8Array(values.buffer)), metadata, nullCount };
         }
         case "string": {
-            // Every value UTF-8-encodes once, directly into a shared worst-case scratch (three bytes
-            // per UTF-16 code unit bounds any UTF-8 expansion) instead of allocating a throwaway
-            // buffer per string and copying it into place afterwards.
-            let capacity = 0;
-            for (let index = 0; index < rowCount; index += 1) {
-                const value = input.values[index];
-                if (value !== null && value !== undefined)
-                    capacity += value.length * 3;
-            }
+            // Measure exactly without allocating, both to reject lossy unpaired surrogates and to avoid
+            // the former 3x worst-case scratch for ASCII-heavy data. The complete 64 MiB format bound is
+            // checked before the content or offset arrays are allocated.
             const offsets = new Uint32Array(rowCount + 1);
-            const content = new Uint8Array(capacity);
+            // Some native encodeInto implementations stop at an internal chunk boundary when the
+            // destination has exactly two or three bytes left, even though the final code point fits.
+            // Three bytes of non-persisted tail room keeps the native fast path reliable; the returned
+            // physical payload still contains exactly `contentByteLength` content bytes.
+            const content = new Uint8Array(stringContentByteLength + 3);
             let offset = 0;
+            let nullCount = 0;
             for (let index = 0; index < rowCount; index += 1) {
                 const value = input.values[index];
-                if (value !== null && value !== undefined) {
-                    offset += textEncoder.encodeInto(value, content.subarray(offset)).written;
+                if (value === undefined)
+                    throw new TypeError("Column values cannot be undefined");
+                if (value === null)
+                    nullCount += 1;
+                else {
+                    if (typeof value !== "string") {
+                        throw new TypeError("String columns accept only strings or null");
+                    }
+                    const localByteLength = wellFormedUtf8ByteLength(value);
+                    setBit(validity, index);
+                    const result = textEncoder.encodeInto(value, content.subarray(offset));
+                    if (result.read !== value.length)
+                        throw new Error("UTF-8 output sizing mismatch");
+                    if (result.written !== localByteLength)
+                        throw new Error("UTF-8 output sizing mismatch");
+                    offset += result.written;
                 }
                 offsets[index + 1] = offset;
             }
+            if (offset !== stringContentByteLength)
+                throw new Error("UTF-8 output sizing mismatch");
             return {
                 bytes: join(validity, new Uint8Array(offsets.buffer), content.subarray(0, offset)),
                 metadata: {},
@@ -109,9 +173,12 @@ export function encodeColumn(input) {
     }
 }
 export function decodeColumn(type, bytes, rowCount) {
+    return decodeValidatedColumn(validatePhysicalColumn({ type, bytes, rowCount }));
+}
+/** Package-internal row materialization after the physical payload was already validated. */
+export function decodeValidatedColumn(column) {
+    const { type, bytes, rowCount } = column;
     const validityLength = bitmapLength(rowCount);
-    if (bytes.byteLength < validityLength)
-        throw new Error("Truncated validity bitmap");
     const validity = bytes.subarray(0, validityLength);
     const payload = bytes.subarray(validityLength);
     const values = [];
@@ -163,4 +230,3 @@ function join(...parts) {
     }
     return output;
 }
-//# sourceMappingURL=column.js.map

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

@@ -1,7 +1,7 @@
 export * from "./block.js";
 export * from "./checksum.js";
 export * from "./codecs.js";
-export * from "./column.js";
+export { decodeColumn, encodeColumn } from "./column.js";
 export * from "./physical.js";
 export * from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./unicode.js";

package/dist/block-format/index.js

@@ -1,7 +1,7 @@
 export * from "./block.js";
 export * from "./checksum.js";
 export * from "./codecs.js";
-export * from "./column.js";
+export { decodeColumn, encodeColumn } from "./column.js";
 export * from "./physical.js";
 export * from "./types.js";
-//# sourceMappingURL=index.js.map
+export * from "./unicode.js";

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

@@ -1,7 +1,12 @@
 import type { LogicalType, PhysicalColumnMeasurement, PhysicalColumnPayload, PhysicalColumnRange, ValidatedPhysicalColumn } from "./types.js";
 export declare const MAX_PHYSICAL_COLUMN_BYTE_LENGTH: number;
+/**
+ * Hard row ceiling for one physical block. Bitmap columns otherwise fit 268 million rows under
+ * the byte limit, which would require an unsafe decoded JS array even for a valid block.
+ */
+export declare const MAX_BLOCK_ROW_COUNT = 1048576;
 export declare function physicalBitmapByteLength(rowCount: number): number;
-/** Returns the exact encoded byte length for a version-zero physical column. */
+/** Returns the exact encoded byte length for the canonical v2 physical column. */
 export declare function physicalColumnByteLength(type: LogicalType, rowCount: number, stringContentByteLength?: number): number;
 /**
  * Validates a physical payload without copying its bytes or materializing row
@@ -17,4 +22,5 @@ export declare function measurePhysicalColumnRanges<T extends LogicalType>(type:
 export declare function buildPhysicalColumnFromRanges<T extends LogicalType>(type: T, ranges: ReadonlyArray<PhysicalColumnRange<T>>): ValidatedPhysicalColumn<T>;
 export declare function slicePhysicalColumn<T extends LogicalType>(column: PhysicalColumnPayload<T>, start: number, end: number): ValidatedPhysicalColumn<T>;
 export declare function concatenatePhysicalColumns<T extends LogicalType>(type: T, columns: ReadonlyArray<PhysicalColumnPayload<T>>): ValidatedPhysicalColumn<T>;
-//# sourceMappingURL=physical.d.ts.map
+/** Validates the shared persisted-block row ceiling without allocating a physical payload. */
+export declare function assertBlockRowCount(rowCount: number): void;

package/dist/block-format/physical.js

@@ -1,10 +1,15 @@
 export const MAX_PHYSICAL_COLUMN_BYTE_LENGTH = 64 * 1024 * 1024;
+/**
+ * Hard row ceiling for one physical block. Bitmap columns otherwise fit 268 million rows under
+ * the byte limit, which would require an unsafe decoded JS array even for a valid block.
+ */
+export const MAX_BLOCK_ROW_COUNT = 1_048_576;
 const MAX_DATETIME_MILLISECONDS = 8_640_000_000_000_000;
 export function physicalBitmapByteLength(rowCount) {
     assertRowCount(rowCount);
     return Math.ceil(rowCount / 8);
 }
-/** Returns the exact encoded byte length for a version-zero physical column. */
+/** Returns the exact encoded byte length for the canonical v2 physical column. */
 export function physicalColumnByteLength(type, rowCount, stringContentByteLength = 0) {
     assertLogicalType(type);
     const validityByteLength = physicalBitmapByteLength(rowCount);
@@ -254,8 +259,7 @@ function preparePhysicalColumn(type, ranges) {
         }
         const rangeRowCount = range.end - range.start;
         rowCount = checkedAdd(rowCount, rangeRowCount, "row count");
-        if (rowCount > 0xffffffff)
-            throw new RangeError("Too many rows in one physical column");
+        assertBlockRowCount(rowCount);
         const sourceValidityLength = physicalBitmapByteLength(column.rowCount);
         const sourceValidity = column.bytes.subarray(0, sourceValidityLength);
         if (type === "string") {
@@ -404,8 +408,13 @@ function assertContinuation(bytes, index, end) {
 }
 function assertRowCount(rowCount) {
     assertNonnegativeSafeInteger(rowCount, "row count");
-    if (rowCount > 0xffffffff)
-        throw new RangeError("Too many rows in one physical column");
+    if (rowCount > MAX_BLOCK_ROW_COUNT) {
+        throw new RangeError("Physical column exceeds maximum row count");
+    }
+}
+/** Validates the shared persisted-block row ceiling without allocating a physical payload. */
+export function assertBlockRowCount(rowCount) {
+    assertRowCount(rowCount);
 }
 function assertLogicalType(type) {
     if (type !== "boolean" && type !== "number" && type !== "string" && type !== "datetime") {
@@ -436,4 +445,3 @@ function checkedMultiply(left, right, name) {
     }
     return left * right;
 }
-//# sourceMappingURL=physical.js.map

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

@@ -30,13 +30,18 @@ export interface BlockMetadata {
 }
 export interface BlockDescription {
     formatVersion: number;
+    headerLength: number;
+    metadataLength: number;
     type: LogicalType;
     compression: Compression;
     rowCount: number;
     nullCount: number;
     encodedLength: number;
     storedLength: number;
+    /** CRC32 of the uncompressed physical column bytes. */
     checksum: number;
+    /** CRC32 of the stored payload bytes, independently verifiable without decompression. */
+    storedChecksum: number;
     metadata: BlockMetadata;
 }
 export interface DecodedBlock<T extends LogicalType = LogicalType> {
@@ -46,8 +51,8 @@ export interface DecodedBlock<T extends LogicalType = LogicalType> {
     column: DecodedColumn<T>;
 }
 /**
- * An uncompressed physical column payload. `bytes` uses the version-zero
- * column encoding documented in `docs/BLOCK_FORMAT.md`.
+ * An uncompressed physical column payload. `bytes` uses the canonical v2 column encoding
+ * documented in `apps/site/content/docs/reference/architecture.mdx`.
  */
 export interface PhysicalColumnPayload<T extends LogicalType = LogicalType> {
     type: T;
@@ -90,4 +95,3 @@ export interface DecodedPhysicalBlock<T extends LogicalType = LogicalType> {
     column: ValidatedPhysicalColumn<T>;
 }
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/block-format/types.js

@@ -1,2 +1 @@
 export const logicalTypes = ["boolean", "number", "string", "datetime"];
-//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * Returns the exact UTF-8 byte length of a well-formed JavaScript string without allocating.
+ *
+ * UTF-8 cannot represent isolated UTF-16 surrogate code units. `TextEncoder` silently replaces
+ * them with U+FFFD, which would make persistence lossy and can collapse distinct index keys.
+ * Minnow rejects those strings instead, so every accepted string has one exact UTF-8 encoding
+ * and round-trips byte-for-byte through the block format.
+ */
+export declare function wellFormedUtf8ByteLength(value: string, context?: string): number;
+/** Rejects strings that cannot round-trip exactly through UTF-8 persistence. */
+export declare function assertWellFormedString(value: string, context?: string): void;

package/dist/block-format/unicode.js

@@ -0,0 +1,46 @@
+/**
+ * Returns the exact UTF-8 byte length of a well-formed JavaScript string without allocating.
+ *
+ * UTF-8 cannot represent isolated UTF-16 surrogate code units. `TextEncoder` silently replaces
+ * them with U+FFFD, which would make persistence lossy and can collapse distinct index keys.
+ * Minnow rejects those strings instead, so every accepted string has one exact UTF-8 encoding
+ * and round-trips byte-for-byte through the block format.
+ */
+export function wellFormedUtf8ByteLength(value, context = "String value") {
+    return measureWellFormedUtf8(value, context);
+}
+/** Rejects strings that cannot round-trip exactly through UTF-8 persistence. */
+export function assertWellFormedString(value, context = "String value") {
+    wellFormedUtf8ByteLength(value, context);
+}
+function measureWellFormedUtf8(value, context) {
+    if (typeof value !== "string")
+        throw new TypeError(`${context} must be a string`);
+    let byteLength = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x7f) {
+            byteLength += 1;
+        }
+        else if (code <= 0x7ff) {
+            byteLength += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            const low = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+            if (low < 0xdc00 || low > 0xdfff)
+                throw unpairedSurrogate(context, index);
+            byteLength += 4;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw unpairedSurrogate(context, index);
+        }
+        else {
+            byteLength += 3;
+        }
+    }
+    return byteLength;
+}
+function unpairedSurrogate(context, index) {
+    return new TypeError(`${context} contains an unpaired surrogate at UTF-16 index ${String(index)}`);
+}

package/dist/date-value.d.ts

@@ -0,0 +1,15 @@
+/** Returns a Date's internal millisecond value without invoking an instance override. */
+export declare function dateMilliseconds(value: Date): number;
+/** Copies a Date by its internal value without invoking instance methods. */
+export declare function copyDate(value: Date): Date;
+/** Formats a Date's internal value without invoking an instance override. */
+export declare function dateIsoString(value: Date): string;
+export declare function dateUtcFullYear(value: Date): number;
+export declare function dateUtcMonth(value: Date): number;
+export declare function dateUtcDate(value: Date): number;
+export declare function dateUtcDay(value: Date): number;
+export declare function dateUtcHours(value: Date): number;
+export declare function dateUtcMinutes(value: Date): number;
+export declare function dateUtcSeconds(value: Date): number;
+export declare function setDateUtcDate(value: Date, day: number): number;
+export declare function setDateUtcMonth(value: Date, month: number): number;

package/dist/date-value.js

@@ -0,0 +1,64 @@
+// Capture the intrinsic once. A Date instance may shadow `getTime`; persistence, indexes, and
+// comparisons must all observe its internal [[DateValue]], not caller-controlled method code.
+// Capturing the intrinsic is the point: later Date.prototype mutations must not change values.
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const intrinsicDateGetTime = Date.prototype.getTime;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- See the getTime capture above.
+const intrinsicDateToISOString = Date.prototype.toISOString;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcFullYear = Date.prototype.getUTCFullYear;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcMonth = Date.prototype.getUTCMonth;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcDate = Date.prototype.getUTCDate;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcDay = Date.prototype.getUTCDay;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcHours = Date.prototype.getUTCHours;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcMinutes = Date.prototype.getUTCMinutes;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateGetUtcSeconds = Date.prototype.getUTCSeconds;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateSetUtcDate = Date.prototype.setUTCDate;
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Captured for the same reason.
+const intrinsicDateSetUtcMonth = Date.prototype.setUTCMonth;
+/** Returns a Date's internal millisecond value without invoking an instance override. */
+export function dateMilliseconds(value) {
+    return intrinsicDateGetTime.call(value);
+}
+/** Copies a Date by its internal value without invoking instance methods. */
+export function copyDate(value) {
+    return new Date(dateMilliseconds(value));
+}
+/** Formats a Date's internal value without invoking an instance override. */
+export function dateIsoString(value) {
+    return intrinsicDateToISOString.call(value);
+}
+export function dateUtcFullYear(value) {
+    return intrinsicDateGetUtcFullYear.call(value);
+}
+export function dateUtcMonth(value) {
+    return intrinsicDateGetUtcMonth.call(value);
+}
+export function dateUtcDate(value) {
+    return intrinsicDateGetUtcDate.call(value);
+}
+export function dateUtcDay(value) {
+    return intrinsicDateGetUtcDay.call(value);
+}
+export function dateUtcHours(value) {
+    return intrinsicDateGetUtcHours.call(value);
+}
+export function dateUtcMinutes(value) {
+    return intrinsicDateGetUtcMinutes.call(value);
+}
+export function dateUtcSeconds(value) {
+    return intrinsicDateGetUtcSeconds.call(value);
+}
+export function setDateUtcDate(value, day) {
+    return intrinsicDateSetUtcDate.call(value, day);
+}
+export function setDateUtcMonth(value, month) {
+    return intrinsicDateSetUtcMonth.call(value, month);
+}

package/dist/engine/artifact-cache.d.ts

@@ -17,6 +17,7 @@ export declare class ArtifactCache {
     get enabled(): boolean;
     get(key: string): unknown;
     put(key: string, payload: unknown, bytes: number): void;
+    /** Releases every retained payload while preserving lifetime counters for final diagnostics. */
+    clear(): void;
     stats(): ArtifactCacheStats;
 }
-//# sourceMappingURL=artifact-cache.d.ts.map

package/dist/engine/artifact-cache.js

@@ -54,6 +54,11 @@ export class ArtifactCache {
             this.#evictions += 1;
         }
     }
+    /** Releases every retained payload while preserving lifetime counters for final diagnostics. */
+    clear() {
+        this.#entries.clear();
+        this.#usedBytes = 0;
+    }
     stats() {
         return {
             limitBytes: this.#limitBytes,
@@ -65,4 +70,3 @@ export class ArtifactCache {
         };
     }
 }
-//# sourceMappingURL=artifact-cache.js.map

package/dist/engine/batch.d.ts

@@ -8,11 +8,20 @@
  */
 /** A value a column can hold. */
 export type BatchValue = boolean | number | string | Date | null;
-/** One row. Columns left out are written as null, so nullable columns can be omitted. */
+/** One row. A missing property is SQL omission; an explicit `null` remains SQL NULL. */
 export type BatchRow = Readonly<Record<string, BatchValue>>;
-/** The columnar form: one array per column, all of the same length, aligned by index. */
+/**
+ * The columnar form: one ordinary readonly array per column, all of the same length and aligned by
+ * index. The engine reads these arrays without copying while the asynchronous write is active;
+ * callers must not mutate them or use changing accessor/proxy values until the write settles.
+ */
 export interface ColumnarBatch {
     columns: Readonly<Record<string, readonly BatchValue[]>>;
+    /**
+     * Per-row SQL omission markers. A true slot asks the engine to use the column default (or NULL
+     * when no default exists), without conflating that request with an explicit NULL value.
+     */
+    omitted?: Readonly<Record<string, readonly boolean[]>>;
     /**
      * The batch's row count when no column carries it — a pivot of rows whose every column is
      * default-generated produces an empty column map, and the count would otherwise be lost
@@ -25,4 +34,3 @@ export type InsertBatchInput = readonly BatchRow[] | ColumnarBatch;
 export declare function isColumnarBatch(input: InsertBatchInput): input is ColumnarBatch;
 /** Pivots rows into the engine's columnar form; a columnar batch passes straight through. */
 export declare function toColumnarBatch(input: InsertBatchInput): ColumnarBatch;
-//# sourceMappingURL=batch.d.ts.map