@zakkster/lite-bake-stream 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] -- 2026-09-02
+
+M6 -- streaming emission + optional integrity. Public `beginStream(sink, { layout: 'stream', crc? })` binds a sink BEFORE feeding, so each shard payload streams to the sink as it finalizes and is dropped; `finalizeToSink(sink, { layout })` then writes the schema/directory/zone-map trailer + footer with one `writeAt(header, 0)` backpatch and returns `{ totalRows, shardCount, schema | mode, bytesWritten, layout }`. Called without a prior `beginStream`, `finalizeToSink` is the buffered convenience mode (`O(container)` peak, stated in the memory-model docs). `layout: 'prefix'` is byte-identical to `finalize()`. With the two-step contract, peak memory drops from `O(container)` to `O(targetShardBytes + directory)`. A default-emitted stream container is a legal v1 container (format_version stays 1) accepted by every shipped reader, `checkContainer`, and `mergeContainers`. `finalize()` is re-based over the same emitters, so its output is byte-for-byte identical to 1.5.0 (frozen sha256 goldens hold).
+
+Optional CRC-32C (Castagnoli, table-driven, zero deps, `src/Crc32c.js`): writers opt in with `{ crc: true }`; readers get `verifyCrc()` -> `'ok' | 'absent'` (mismatch throws `R_BAD_CRC`) and an open option `{ verifyCrc: true }` that fails closed on mismatch (`R_BAD_CRC`) and absence (`R_CRC_ABSENT`). `mergeContainers` recomputes the CRC iff every input carried one, else absent. KATs: `CRC32C("")=0x00000000`, `CRC32C("123456789")=0xE3069283`; the stream layout closes the ring with a split-buffer combine (`crc32cCombine`, KAT-pinned and covered end-to-end by a streaming `beginStream` + flipped-byte case). New sink guard `W_BAD_SINK`. Three new thrown codes (`W_BAD_SINK`, `R_BAD_CRC`, `R_CRC_ABSENT`); inventory 57 -> 60 / 0 unpinned.
+
+Measured peak RSS (full-tier gate, 500 MB streamed in 8 MiB chunks into a counting sink, container never materialized): `peakRss - baselineRss` = 32.1 MiB against the bound `4*targetShardBytes + 64*shardCount + 64 MiB` = 96.0 MiB at 41 shards -- versus the buffered `finalize()` path at ~704 MiB (baseline `soak --mb=500`: baselineRss 667 MiB, peakRss 1371 MiB). Suite: 479 -> 515 tests / 515 pass / 0 fail / 0 todo. Torture: 44/44 fast, 47/47 full, arrayBuffers growth 0.00 MB both tiers, t7 sink-release witness (retained shard slots <= 1; independently armed during qa -- retained shards fail 364/364, clean run 0/0). Measurement note: t7's final arrayBuffers read now settles and collects twice before reading (the gc-profiler contract) -- t5-fuzz's large-ArrayBuffer churn was polluting the single-gc read via V8's buffer pool; the 8 MB budget and all RULES numbers are unchanged, and the M6 paths retain ~0 in isolation. Pack 32 -> 33 (new `src/Crc32c.js`). See `decisions/0009-streaming-emission.md`.
+
+## [1.5.0] -- 2026-09-02
+
+M5 -- every ceiling gets a door; the shard budget counts all the bytes it ships; the floors are measured. BS-26 closed; BS-27's floor items closed (the writer-holds-all-shards ~2x container peak moves to M6's streaming emission); BS-32/BS-33/BS-34 closed. Suite: 461 -> 479 tests / 479 pass / 0 fail / 0 todo. Torture: 44/44 fast (~322 ms tier sum), 47/47 full (~5.6 s) incl. a 2100-shard directory-scale scenario (SPEC checker green, RangeReader LRU cap held at 8, `_maybeEvict` allocation-flat over 20000 ops); arrayBuffers growth 0.00 MB both tiers; t7 soak tracker size 0. Inventory gate: 54 -> 57 thrown codes / 0 unpinned. Falsifiability, measured item-by-item with baseline src stashed: all 15 new door/behavior assertions fail on baseline and pass on this tree, every stay-green net holds on both, and an all-F64-lane container is byte-identical to the 1.4.1 output (same sha256 and length). BREAK matrix {1, t6, l, m, j} all exit non-zero.
+
+### Added
+
+- **Serialization ceilings (BS-26).** `StringTable` now fails closed with a new
+  `StringTableError` code `ST_BLOB_OVERFLOW` when a per-shard string table would
+  cross the u32 `blob_length` (4294967295) or `entry_count` (4294967294) ceiling,
+  instead of wrapping silently on `setUint32` and minting a corrupt-but-in-bounds
+  container. The doubling paths clamp their allocation at the ceiling so every
+  crossing write re-enters the guard, making placement provably complete.
+  `StringTableError` is re-exported from `index.js` and declared in the types.
+  `PreserveWriter.onRecord` raises the same `ST_BLOB_OVERFLOW` (shared code)
+  before a shard's `payload_len` (blob + trailing offset table) would exceed u32.
+  A test-only `__setStringTableLimits({blobBytes, entryCount})` seam (no semver
+  guarantee, absent from the public API/types/docs) lowers the ceilings for a
+  cheap gated crossing on the real grow path.
+- **Row-index doors (BS-32).** `Reader.get`, `MultiReader.get`, `RangeReader.get`
+  and `PreserveReader.getBytes/getString/getJSON` now reject a negative,
+  fractional, `NaN`, or out-of-range `rowIdx` with `R_ROW_OUT_OF_RANGE`
+  (`M_ROW_OUT_OF_RANGE` for `MultiReader`) rather than returning `undefined` or a
+  garbage subarray from a fractional byte offset. `Reader.get` uses a `>>>0`
+  compare; the others use `Number.isInteger` (they legitimately address up to
+  2^53). The SHARD-index escape hatches keep their unchecked raw-access contract.
+- **Safe-integer offset guard (BS-26).** `Reader`, `RangeReader` and
+  `PreserveReader` narrow every u64 header/schema/directory offset through a cold
+  `u64()` helper that throws `R_OFFSET_TOO_LARGE` past 2^53-1, where a `Number()`
+  cast would lose precision and hand a corrupted offset to every bounds check.
+- **`RangeReader` adapter validation (BS-34 + BS-33).** All seven `adapter.fetch` sites
+  funnel through `_fetchExact`, which rejects a non-`Uint8Array` or wrong-length
+  return with `R_ADAPTER_SHORT_READ`. `syncRange` over a not-prefetched shard now
+  throws its own `R_NOT_PREFETCHED`, distinct from the `R_TRUNCATED` truncation
+  door.
+
+### Changed
+
+- **Shard-byte budget (D2).** The schema `Writer` now rolls a shard when its
+  payload plus string-table bytes reach `targetShardBytes`, not on the row
+  ceiling alone, so a string-heavy shard no longer overshoots the target. The
+  string-table byte length is tracked incrementally with zero allocation (one
+  compare per string value, updated only on a unique arrival) and is exact versus
+  `StringTable.serialize` at every finalize. The budget reads only
+  chunk-invariant state, so re-chunked input still yields byte-identical
+  containers (the t0 law), and a container whose schema has only F64 lanes keeps
+  a zero string budget and is **byte-identical** to the pre-D2 output.
+- **Floors.** The schema `Writer` field-name lookup moves from an O(F) hash-scan
+  to an O(1) `Map` (byte-confirmed, so a real FNV collision such as
+  `gwzx`/`16cd` still resolves correctly): on an ad-hoc 64-/256-field
+  flat-record serialize microbench (`bench/bench-tokenizer.js` carries a fixed
+  7-field fixture, so it cannot express this floor), throughput went from
+  190.0 -> 216.7 MB/s at 64 fields and 113.3 -> 213.6 MB/s at 256 fields --
+  the O(F) per-key term no longer degrades with field count. qa's independent
+  microbench (different corpus) corroborates the shape: baseline fell
+  128.0 -> 77.3 MB/s going 64 -> 256 fields; with the map it holds
+  163.0 -> 167.9 MB/s. The sample-window key
+  decoder is now a shared module-scope `TextDecoder` instead of one per key.
+  `PreserveWriter` reuses its working buffers across shard rolls (they were
+  reallocated every roll) -- the reuse is byte-safe (every read is bounded by the
+  reset cursors) and holds the working store byte-flat under a steady-stream soak.
+- `package.json` exports: all 12 entries (root + 11 subpaths) gain the `node` condition alongside `types`/`import`/`default`, matching the suite convention. Verified: 12/12 subpaths resolve via self-reference import, `require()` resolves through `node` on Node 26 (`require(esm)`), npm test 461/461, `npm pack --dry-run` unchanged at 32 files.
+
 ## [1.4.1] -- 2026-09-02
 
 M8 -- the four reserved torture cells become real; BS-30 and BS-31 close. No tier prints "reserved" any more. Suite: 461 tests / 461 pass / 0 fail / 0 todo (unchanged -- no named-suite edits). Torture: 44/44 fast (~1.3 s wall), 47/47 full, arrayBuffers growth 0. BREAK matrix: ten runs (`=1`, eight registry ids, one unknown id) all exit non-zero; the unknown id is refused at import. Inventory gate: 54 thrown codes / 0 unpinned. Falsifiability: with baseline src stashed, exactly one new assertion fails (the onProgress-identity pin), both tiers. Test-only except one hot-path reuse in `src/FileIngest.js` (below).

package/README.md

@@ -13,7 +13,7 @@
 
 > Streaming byte-level JSON compiler for [`@zakkster/lite-bake`](https://github.com/PeshoVurtoleta/lite-bake). Zero-GC, tree-shakeable, gigabyte-scale.
 
-**Status:** v1.4.1. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak with zero GC and byte-exact preservation across 590 million cells.
+**Status:** v1.6.0. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak with zero GC and byte-exact preservation across 590 million cells.
 
 ## Two modes, one API
 
@@ -123,6 +123,23 @@ All of these fit the format's existing forward-compat seams — `format_version`
 
 Two release gates. Zero major GC AND every declared cell round-trips exactly. If either fails, no publish.
 
+## Streaming emission and integrity
+
+`finalize()` returns the whole container as one `ArrayBuffer` -- peak memory is `O(container)`. For bounded-memory output, `writer.finalizeToSink(sink, { layout })` emits to a caller sink and returns `{ totalRows, shardCount, schema | mode, bytesWritten, layout }` (no buffer). A sink is any object with a synchronous `write(bytes)`; `layout: 'stream'` also needs `writeAt(bytes, position)` for one header backpatch -- satisfiable by `fs.write(fd, buf, 0, len, pos)`, the FS Access API's `createWritable().write({ type: 'write', position })`, and the in-memory `MemorySink`.
+
+There are two ways to drive a stream, and they deliver different peaks:
+
+- **Two-step, bounded RAM** -- call `writer.beginStream(sink, { layout: 'stream' })` BEFORE feeding, feed the tokenizer, then `writer.finalizeToSink(sink, { layout: 'stream' })`. Each shard is written to the sink as it finalizes and its bytes are dropped, so peak memory is `peak(stream) = 2*targetShardBytes + shardCount*(40 + 16*T) + schemaBlockBytes` -- `O(targetShardBytes + directory)`, never `O(container)`. This is the mode the 500 MB gate proves.
+- **One-shot, buffered** -- call `writer.finalizeToSink(sink, opts)` alone (no `beginStream`). Correct and simplest, but the shards are buffered first, so peak is `peak(prefix) = containerBytes + sum(shard bytes)` -- `O(container)`, the same as `finalize()`.
+
+`layout: 'prefix'` is the classic layout, **byte-identical** to `finalize()`. `layout: 'stream'` places the schema/directory/zone-map trailer and footer after the payloads with one header backpatch; a default-emitted stream container is a legal v1 container (format_version stays 1) that every shipped reader, `checkContainer`, and `mergeContainers` accept.
+
+A malformed sink (non-object, missing `write`, missing `writeAt` for stream, or an async/thenable return) throws `W_BAD_SINK`; a sink that throws mid-emission fails the writer closed and rethrows the source error verbatim (a retry then hits `W_FINALIZED`).
+
+**Memory model.** `peak(prefix) = containerBytes + sum(shard bytes)`; `peak(stream) = 2*targetShardBytes + shardCount*(40 + 16*T) + schemaBlockBytes`. The full-tier gate drives the two-step bounded path, streaming 500 MB in 8 MiB chunks into a counting sink, and asserts `peakRss - baselineRss <= 4*targetShardBytes + 64*shardCount + 64 MiB` (measured 32.1 MiB against the 96.0 MiB bound at 41 shards; the buffered path is ~704 MiB at 500 MB).
+
+**Optional CRC-32C** (Castagnoli, table-driven, zero deps). Opt in with `{ crc: true }` on the writer (or serialize `writer` opts); coverage is `[0, footer_off)`, folded per emitted chunk. Readers expose `verifyCrc()` -> `'ok' | 'absent'` (a mismatch throws `R_BAD_CRC`) on `Reader`/`PreserveReader` (sync) and `RangeReader` (async). The open option `{ verifyCrc: true }` (also `deserialize(bytes, opts)`) fails closed on both mismatch (`R_BAD_CRC`) and absence (`R_CRC_ABSENT`) -- `null` is not zero. `0xFFFFFFFF` means absent and stays legal. `mergeContainers` recomputes the CRC iff every input carried one, else emits absent. See `decisions/0009-streaming-emission.md`.
+
 ## Release testing tiers
 
 The gates run at four scales, chosen to fit different hardware and time budgets:

package/SPEC.md

@@ -165,7 +165,9 @@ reader.findShards(fieldName, {min, max})    → shardIdx[]     // shards that MA
 |      8 |    4 | `magic_end` | ASCII `1 K B L` = `0x31 0x4B 0x42 0x4C`.                  |
 |     12 |    4 | `footer_len`| u32. Currently `16`. Lets future versions grow the footer without breaking magic detection. |
 
-CRC is optional in M4; producers that omit it write `0xFFFFFFFF`.
+CRC is optional; producers that omit it write `0xFFFFFFFF` (absent). Producers opt in with the writer option `{ crc: true }`. The CRC-32C uses the Castagnoli polynomial (bit-reflected `0x82F63B78`); check value `CRC32C("123456789") = 0xE3069283`. Readers verify with `verifyCrc()` (returns `'ok' | 'absent'`, throws `R_BAD_CRC` on mismatch) or the open option `{ verifyCrc: true }`, which additionally throws `R_CRC_ABSENT` when the caller demanded verification but the CRC is absent.
+
+Note (SPEC 3 / 3.6): container offsets are ABSOLUTE, so two conformant orderings exist for a v1 container. The classic PREFIX ordering places the schema block, shard directory, and zone maps before the shard payloads. The STREAMING ordering (`layout: 'stream'`) places the shard payloads first, then the schema block, shard directory, and zone maps as a trailer, then the footer; the schema block still immediately precedes the shard directory (adjacency preserved). Both are valid v1 containers; format_version is unchanged.
 
 ## 4. Schema and field descriptors
 

package/llms.txt

@@ -8,13 +8,13 @@ Ingest gigabyte-scale JSON (top-level array or NDJSON) into the `lite-bake` LBK1
 
 ## Status
 
-v1.4.1 — stable. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak (M1 MacBook Pro): 98.37M rows, 4.89 GB container, zero major GC, zero minor GC, 499 KB total heap allocation, 590.21M cells verified byte-exact, zero mismatches. Tokenizer benches at 222-237 MB/s (~55% of JSON.parse, with no object graph allocated).
+v1.6.0 — stable. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak (M1 MacBook Pro): 98.37M rows, 4.89 GB container, zero major GC, zero minor GC, 499 KB total heap allocation, 590.21M cells verified byte-exact, zero mismatches. Tokenizer benches at 222-237 MB/s (~55% of JSON.parse, with no object graph allocated).
 
 Public API follows semver from 1.0.0. Future additions (I64 lane, columnar payload mode, container-level string table) land via the format's forward-compat seams -- `min_reader_version` on ShardEntry, reserved FieldDescriptor flags, the `metadata_off` block wrapper -- without a format_version bump.
 
 See SPEC.md for the LBK1 container format, section 3.6 for zone maps, section 4.3 for the reserved field flags.
 
-## Public API (v1.4.1)
+## Public API (v1.6.0)
 
 Two ingest modes share one top-level API:
 
@@ -62,6 +62,17 @@ Error classes with stable `code`: `TokenizerError`, `WriterError`, `ReaderError`
 
 Every declared field of every row round-trips. F64 lanes: bit-exact for numeric literals with ≤15 significant digits and |exponent| ≤ 22 (Clinger's fast path); ≤1 ULP drift outside that domain (documented, pinned by NumericBoundary.test.js). U32 lanes: byte-exact UTF-8, unconditional. Missing fields → documented defaults. Unknown keys → silently dropped. Wrong-type value on post-freeze schema → W_LANE_MISMATCH error, no corrupt container produced. See SPEC section 7 for the full table. Asserted by tests, property-based fuzz, AND torture-scale verification (~73,500 rows per fast-tier run).
 
+## Row-index and refusal codes
+
+- Random-access row surfaces fail closed on a bad `rowIdx` (negative, fractional, NaN, or >= totalRows): `Reader.get`, `RangeReader.get` and `PreserveReader.getBytes/getString/getJSON` throw `R_ROW_OUT_OF_RANGE`; `MultiReader.get` throws `M_ROW_OUT_OF_RANGE`. The SHARD-index escape hatches (`shardPayload`, `shardF64`, `shardStringTable`, `loadShard`) keep their unchecked raw-access contract; `shardBounds` returns null out-of-range.
+- `R_OFFSET_TOO_LARGE`: a u64 header/schema/directory offset exceeds 2^53-1 (a Number() cast would lose precision). Raised by all three reader classes.
+- `R_NOT_PREFETCHED`: `RangeReader.syncRange` over a shard `prefetchRange` has not cached (distinct from the `R_TRUNCATED` truncation door). `R_ADAPTER_SHORT_READ` also covers a non-Uint8Array or wrong-length adapter return.
+- `ST_BLOB_OVERFLOW`: a per-shard string table would cross the u32 blob_length (4294967295) or entry_count (4294967294) ceiling; also raised by `PreserveWriter` before a shard payload_len would exceed u32. One shared code across `StringTable` and `PreserveWriter`. `StringTableError` is exported from the root and the `string-table` subpath.
+
+## Shard budget
+
+Schema-mode shards roll when payload bytes plus string-table bytes reach `targetShardBytes`, not on the row ceiling alone. The string-table byte count is tracked with zero allocation and is chunk-invariant, so re-chunked input yields byte-identical containers and an all-F64 schema is byte-identical to the pre-budget output. `PreserveWriter` reuses its working buffers across shard rolls.
+
 ## Numbers
 
 F64 only. Values exceeding IEEE 754 double range are rejected as `E_NUMBER_OVERFLOW`. 64-bit integer IDs above 2^53 lose precision silently (documented in SPEC 5.4); v2 will introduce an opt-in bytes-preserved lane.
@@ -76,6 +87,14 @@ F64 only. Values exceeding IEEE 754 double range are rejected as `E_NUMBER_OVERF
 
 Subpath entries per SPEC section 6. `sideEffects: false`. Consumers import only the path they need; the browser reader never pulls the writer.
 
+## Streaming emission and integrity (M6)
+
+`finalize()` returns the whole container as one ArrayBuffer (peak memory O(container)). `writer.finalizeToSink(sink, { layout })` emits to a caller sink instead and returns `{ totalRows, shardCount, schema|mode, bytesWritten, layout }` (no buffer). A sink is any object with a synchronous `write(bytes)`; `layout: 'stream'` also needs `writeAt(bytes, position)` for one header backpatch. Two ways to drive a stream with different peaks: (1) TWO-STEP bounded RAM -- `writer.beginStream(sink, { layout: 'stream' })` BEFORE feeding, feed the tokenizer, then `writer.finalizeToSink(sink, { layout: 'stream' })`; each shard streams to the sink as it finalizes and its bytes drop, so peak is `peak(stream) = 2*targetShardBytes + shardCount*(40 + 16*T) + schemaBlockBytes` = O(targetShardBytes + directory). (2) ONE-SHOT buffered -- `finalizeToSink(sink, opts)` alone (no beginStream); correct but the shards are buffered first, so peak is `peak(prefix) = containerBytes + sum(shard bytes)` = O(container), same as `finalize()`. `layout: 'prefix'` is the classic layout, byte-identical to `finalize()`. A default-emitted stream container is a legal v1 container (format_version stays 1) that every shipped reader, `checkContainer`, and `mergeContainers` accept. A malformed sink (non-object, missing `write`, missing `writeAt` for stream, or an async/thenable return) throws `W_BAD_SINK`; a sink that throws mid-emission fails the writer closed and rethrows the source error verbatim (a retry then hits `W_FINALIZED`).
+
+Memory model. `peak(prefix) = containerBytes + sum(shard bytes)`; `peak(stream) = 2*targetShardBytes + shardCount*(40 + 16*T) + schemaBlockBytes`. The full-tier gate streams 500 MB in 8 MiB chunks into a counting sink and asserts `peakRss - baselineRss <= 4*targetShardBytes + 64*shardCount + 64 MiB` (measured 32.1 MiB vs the 96.0 MiB bound at 41 shards; the buffered prefix path is ~704 MiB at 500 MB).
+
+Optional CRC-32C (Castagnoli, table-driven, zero deps). Writers opt in with `{ crc: true }` (constructor or serialize `writer` opts); coverage is [0, footer_off), folded per emitted chunk. Readers expose `verifyCrc()` -> `'ok' | 'absent'` (a mismatch throws `R_BAD_CRC`) on `Reader`/`PreserveReader` (sync) and `RangeReader` (async). The open option `{ verifyCrc: true }` (also `deserialize(bytes, opts)`) fails closed on both mismatch (`R_BAD_CRC`) and absence (`R_CRC_ABSENT`). `0xFFFFFFFF` means absent and stays legal (SPEC 3.7). `mergeContainers` recomputes the CRC iff every input carried one, else emits absent. KAT: `CRC32C("123456789") = 0xE3069283`. See decisions/0009-streaming-emission.md.
+
 ## Non-goals
 
 JSON5, JSONC, comments, trailing commas, streaming field updates, compression, native (non-JS) producers.

package/package.json

@@ -1,67 +1,79 @@
 {
   "name": "@zakkster/lite-bake-stream",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Streaming byte-level JSON to lite-bake binary compiler. Zero-GC, tree-shakeable, gigabyte-scale.",
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
+      "node": "./src/index.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
     "./tokenizer": {
       "types": "./types/Tokenizer.d.ts",
+      "node": "./src/Tokenizer.js",
       "import": "./src/Tokenizer.js",
       "default": "./src/Tokenizer.js"
     },
     "./writer": {
       "types": "./types/Writer.d.ts",
+      "node": "./src/Writer.js",
       "import": "./src/Writer.js",
       "default": "./src/Writer.js"
     },
     "./reader": {
       "types": "./types/Reader.d.ts",
+      "node": "./src/Reader.js",
       "import": "./src/Reader.js",
       "default": "./src/Reader.js"
     },
     "./string-table": {
       "types": "./types/StringTable.d.ts",
+      "node": "./src/StringTable.js",
       "import": "./src/StringTable.js",
       "default": "./src/StringTable.js"
     },
     "./file-ingest": {
       "types": "./types/FileIngest.d.ts",
+      "node": "./src/FileIngest.js",
       "import": "./src/FileIngest.js",
       "default": "./src/FileIngest.js"
     },
     "./range-reader": {
       "types": "./types/RangeReader.d.ts",
+      "node": "./src/RangeReader.js",
       "import": "./src/RangeReader.js",
       "default": "./src/RangeReader.js"
     },
     "./multi-reader": {
       "types": "./types/MultiReader.d.ts",
+      "node": "./src/MultiReader.js",
       "import": "./src/MultiReader.js",
       "default": "./src/MultiReader.js"
     },
     "./split": {
       "types": "./types/Split.d.ts",
+      "node": "./src/Split.js",
       "import": "./src/Split.js",
       "default": "./src/Split.js"
     },
     "./preserve-tokenizer": {
       "types": "./types/PreserveTokenizer.d.ts",
+      "node": "./src/PreserveTokenizer.js",
       "import": "./src/PreserveTokenizer.js",
       "default": "./src/PreserveTokenizer.js"
     },
     "./preserve-writer": {
       "types": "./types/PreserveWriter.d.ts",
+      "node": "./src/PreserveWriter.js",
       "import": "./src/PreserveWriter.js",
       "default": "./src/PreserveWriter.js"
     },
     "./preserve-reader": {
       "types": "./types/PreserveReader.d.ts",
+      "node": "./src/PreserveReader.js",
       "import": "./src/PreserveReader.js",
       "default": "./src/PreserveReader.js"
     }

package/src/Crc32c.js

@@ -0,0 +1,96 @@
+// @zakkster/lite-bake-stream / Crc32c (internal)
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+//
+// CRC-32C (Castagnoli, bit-reflected polynomial 0x82F63B78) over container
+// bodies. Backs the optional footer integrity field (SPEC 3.7). The 256-entry
+// lookup table is built ONCE at import (cold); the update loop is scalar and
+// allocation-free, folding one byte per iteration:
+//     crc = (crc >>> 8) ^ TABLE[(crc ^ b) & 0xFF]
+// It is called per emitted CHUNK, never per record.
+//
+// The running CRC is carried as a signed int32 (init = 0xFFFFFFFF, i.e. -1);
+// crc32cFinal applies the trailing one-complement and returns an unsigned u32.
+//
+// crc32cCombine folds the finalized CRC of a suffix onto the finalized CRC of a
+// prefix (GF(2) matrix method, as in zlib's crc32_combine but with the CRC-32C
+// polynomial). The streaming writer uses it ONCE at end-of-input to prepend the
+// 48-byte header CRC onto the running body CRC without re-reading the dropped
+// shard payloads. Cold path; not on any per-chunk loop.
+//
+// Not a public export. No subpath. Internal to the package.
+
+const POLY = 0x82F63B78;   // CRC-32C, bit-reflected
+const TABLE = buildTable();
+
+function buildTable() {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = (c & 1) ? (POLY ^ (c >>> 1)) : (c >>> 1);
+    }
+    t[n] = c | 0;
+  }
+  return t;
+}
+
+export function crc32cInit() { return 0xFFFFFFFF | 0; }
+
+export function crc32cUpdate(crc, bytes, off, len) {
+  let c = crc | 0;
+  const end = off + len;
+  for (let i = off; i < end; i++) {
+    c = (c >>> 8) ^ TABLE[(c ^ bytes[i]) & 0xFF];
+  }
+  return c | 0;
+}
+
+export function crc32cFinal(crc) {
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+// ---- GF(2) matrix helpers for crc32cCombine (cold) --------------------------
+
+const _even = new Int32Array(32);
+const _odd = new Int32Array(32);
+
+function gf2Times(mat, vec) {
+  let sum = 0;
+  let v = vec >>> 0;
+  let i = 0;
+  while (v !== 0) {
+    if (v & 1) sum ^= mat[i];
+    v >>>= 1;
+    i++;
+  }
+  return sum | 0;
+}
+
+function gf2Square(square, mat) {
+  for (let n = 0; n < 32; n++) square[n] = gf2Times(mat, mat[n]);
+}
+
+// crcA = finalized CRC of prefix A; crcB = finalized CRC of suffix B; len2 =
+// byte length of B. Returns the finalized CRC of A || B. len2 may exceed 2^31,
+// so it is halved by division and tested by remainder.
+export function crc32cCombine(crcA, crcB, len2) {
+  if (len2 === 0) return crcA >>> 0;
+  const odd = _odd, even = _even;
+  odd[0] = POLY | 0;               // operator for a single zero bit
+  let row = 1;
+  for (let n = 1; n < 32; n++) { odd[n] = row; row = (row << 1) | 0; }
+  gf2Square(even, odd);            // 2 zero bits
+  gf2Square(odd, even);            // 4 zero bits
+  let crc = crcA >>> 0;
+  let len = len2;
+  do {
+    gf2Square(even, odd);
+    if (len % 2) crc = gf2Times(even, crc) >>> 0;
+    len = Math.floor(len / 2);
+    if (len === 0) break;
+    gf2Square(odd, even);
+    if (len % 2) crc = gf2Times(odd, crc) >>> 0;
+    len = Math.floor(len / 2);
+  } while (len !== 0);
+  return (crc ^ (crcB >>> 0)) >>> 0;
+}

package/src/FileIngest.js

@@ -27,7 +27,7 @@ import { PreserveWriter } from './PreserveWriter.js';
 import { PreserveReader } from './PreserveReader.js';
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.4.1';
+export const VERSION = '1.6.0';
 
 const U32_MAX = 4294967295;
 const INGEST_OPTS = {

package/src/MultiReader.js

@@ -25,7 +25,7 @@
 //   M_ROW_OUT_OF_RANGE    - rowIdx >= totalRows
 //   M_TOO_MANY_ROWS       - cumulative row count exceeds Number.MAX_SAFE_INTEGER
 
-export const VERSION = '1.4.1';
+export const VERSION = '1.6.0';
 
 export class MultiReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'MultiReaderError'; }
@@ -100,7 +100,10 @@ export class MultiReader {
 
   // Which reader contains global row rowIdx? Returns { readerIdx, localRow }.
   _locateRow(rowIdx) {
-    if (rowIdx < 0 || rowIdx >= this._totalRows) {
+    // BS-32: Number.isInteger (not >>>0) because MultiReader legitimately
+    // addresses up to 2^53 (see M_TOO_MANY_ROWS). Rejects fractional, NaN, and
+    // out-of-range in one guard; covers get() and readerForRow().
+    if (!Number.isInteger(rowIdx) || rowIdx < 0 || rowIdx >= this._totalRows) {
       throw new MultiReaderError('M_ROW_OUT_OF_RANGE',
         'rowIdx ' + rowIdx + ' out of range [0, ' + this._totalRows + ')');
     }

package/src/PreserveReader.js

@@ -28,29 +28,48 @@
 //   R_BAD_FOOTER             - footer magic_end or footer_len is malformed
 //   R_INVALID                - a structure is internally inconsistent but in-bounds
 //   R_SHARD_VERSION_TOO_NEW  - a shard's min_reader_version > this reader
-//   R_ROW_OUT_OF_RANGE       - rowIdx >= totalRows
+//   R_ROW_OUT_OF_RANGE       - rowIdx negative, fractional, NaN, or >= totalRows (BS-32)
+//   R_OFFSET_TOO_LARGE       - a u64 header/directory offset exceeds 2^53-1
 
 import { toContainerBuffer } from './Views.js';
+import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.4.1';
+export const VERSION = '1.6.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
 const FOOTER_BYTES = 16;
+const CRC_ABSENT = 0xFFFFFFFF;
+
+const PRESERVE_READER_OPTS = { verifyCrc: { t: 'bool' } };
+function raisePreserveReaderOpt(code, msg) { throw new PreserveReaderError(code, msg); }
 
 export class PreserveReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveReaderError'; }
 }
 
+// Read a u64 header/directory field and narrow it to a JS number, failing closed
+// past Number.MAX_SAFE_INTEGER. Past 2^53-1 a Number() cast loses precision and
+// every downstream bounds check reads a corrupted offset (BS-05). Cold: parse-only.
+function u64(dv, off, what) {
+  const v = dv.getBigUint64(off, true);
+  if (v > 9007199254740991n)
+    throw new PreserveReaderError('R_OFFSET_TOO_LARGE',
+      what + ' value ' + v + ' exceeds the safe-integer ceiling 9007199254740991');
+  return Number(v);
+}
+
 export class PreserveReader {
-  static fromBuffer(input) {
-    return new PreserveReader(toContainerBuffer(input, 'PreserveReader.fromBuffer'));
+  static fromBuffer(input, opts) {
+    return new PreserveReader(toContainerBuffer(input, 'PreserveReader.fromBuffer'), opts);
   }
 
-  constructor(buffer) {
+  constructor(buffer, opts) {
     if (!(buffer instanceof ArrayBuffer)) {
       throw new TypeError('PreserveReader: expected ArrayBuffer');
     }
+    checkOpts('PreserveReader', opts, PRESERVE_READER_OPTS, raisePreserveReaderOpt);
     this._buffer = buffer;
     this._dv = new DataView(buffer);
     this._bytes = new Uint8Array(buffer);
@@ -58,6 +77,22 @@ export class PreserveReader {
     this._parseHeader();
     this._parseFooter();
     this._parseShardDirectory();
+    if (opts && opts.verifyCrc === true) {
+      const status = this.verifyCrc();
+      if (status === 'absent')
+        throw new PreserveReaderError('R_CRC_ABSENT', 'verifyCrc:true but the container carries no CRC (footer CRC is absent, 0xFFFFFFFF)');
+    }
+  }
+
+  // SPEC 3.7 integrity: 'ok' | 'absent'; a mismatch throws R_BAD_CRC.
+  verifyCrc() {
+    const footerOff = this._buffer.byteLength - FOOTER_BYTES;
+    const stored = this._dv.getUint32(footerOff, true) >>> 0;
+    if (stored === CRC_ABSENT) return 'absent';
+    const actual = crc32cFinal(crc32cUpdate(crc32cInit(), this._bytes, 0, footerOff));
+    if (actual !== stored)
+      throw new PreserveReaderError('R_BAD_CRC', 'container CRC mismatch: stored 0x' + stored.toString(16) + ' != computed 0x' + actual.toString(16));
+    return 'ok';
   }
 
   _parseHeader() {
@@ -84,11 +119,11 @@ export class PreserveReader {
     if (reserved1 !== 0)
       throw new PreserveReaderError('R_RESERVED_NONZERO', 'header reserved1 at offset 36 must be 0, got ' + reserved1);
 
-    this._schemaBlockOff = Number(this._dv.getBigUint64(8, true));
-    this._metadataOff    = Number(this._dv.getBigUint64(16, true));
-    this._shardDirOff    = Number(this._dv.getBigUint64(24, true));
+    this._schemaBlockOff = u64(this._dv, 8, 'schema_block_off');
+    this._metadataOff    = u64(this._dv, 16, 'metadata_off');
+    this._shardDirOff    = u64(this._dv, 24, 'shard_directory_off');
     this._shardCount     = this._dv.getUint32(32, true);
-    this._totalRows      = Number(this._dv.getBigUint64(40, true));
+    this._totalRows      = u64(this._dv, 40, 'total_rows');
 
     if (this._schemaBlockOff !== 0) {
       throw new PreserveReaderError('R_INVALID', 'preserve container has non-zero schema_block_off');
@@ -127,14 +162,14 @@ export class PreserveReader {
     let cumulativeRow = 0;
     for (let i = 0; i < this._shardCount; i++) {
       const entryOff = this._shardDirOff + i * SHARD_ENTRY_BYTES;
-      const payloadOff = Number(this._dv.getBigUint64(entryOff + 0, true));
+      const payloadOff = u64(this._dv, entryOff + 0, 'shard ' + i + ' payload_off');
       const payloadLen = this._dv.getUint32(entryOff + 8, true);
       const rowCount   = this._dv.getUint32(entryOff + 12, true);
       const minReaderVer = this._dv.getUint16(entryOff + 16, true);
       const shardFlags   = this._dv.getUint16(entryOff + 18, true);
       const shardReserved = this._dv.getUint32(entryOff + 20, true);
-      const localStrOff  = Number(this._dv.getBigUint64(entryOff + 24, true));
-      const localStrLen  = Number(this._dv.getBigUint64(entryOff + 32, true));
+      const localStrOff  = u64(this._dv, entryOff + 24, 'shard ' + i + ' local_string_off');
+      const localStrLen  = u64(this._dv, entryOff + 32, 'shard ' + i + ' local_string_len');
       if (minReaderVer > 1) {
         throw new PreserveReaderError('R_SHARD_VERSION_TOO_NEW',
           'shard ' + i + ' requires reader version ' + minReaderVer);
@@ -195,7 +230,10 @@ export class PreserveReader {
   get hasZoneMaps() { return false; }
 
   _locateShard(rowIdx) {
-    if (rowIdx < 0 || rowIdx >= this._totalRows) {
+    // BS-32: Number.isInteger rejects fractional/NaN too, so getBytes(1.5) fails
+    // closed instead of returning a garbage subarray. One site covers
+    // getBytes/getString/getJSON.
+    if (!Number.isInteger(rowIdx) || rowIdx < 0 || rowIdx >= this._totalRows) {
       throw new PreserveReaderError('R_ROW_OUT_OF_RANGE',
         'rowIdx ' + rowIdx + ' out of range [0, ' + this._totalRows + ')');
     }

package/src/PreserveTokenizer.js

@@ -32,7 +32,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.4.1';
+export const VERSION = '1.6.0';
 
 const U32_MAX = 4294967295;
 const PRESERVE_TOKENIZER_OPTS = {