@zakkster/lite-bake-stream 1.6.0 → 1.6.1

package/llms.txt

@@ -1,20 +1,20 @@
 # @zakkster/lite-bake-stream
 
-Streaming byte-level JSON to lite-bake binary compiler for JS runtimes.
+Streaming byte-level JSON to LBK1 binary containers for JS runtimes.
 
 ## Purpose
 
-Ingest gigabyte-scale JSON (top-level array or NDJSON) into the `lite-bake` LBK1 binary format without materializing the intermediate object graph. Reference producer path for downstream consumers of the flat, interleaved, zero-GC `lite-bake` reader API.
+Ingest gigabyte-scale JSON (top-level array or NDJSON) into the LBK1 binary container format without materializing the intermediate object graph. The container is flat, interleaved, and zero-GC to read; a Reader gives random access to any row without re-parsing JSON.
 
 ## Status
 
-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).
+v1.6.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).
 
 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.6.0)
+## Public API (v1.6.1)
 
 Two ingest modes share one top-level API:
 
@@ -34,21 +34,18 @@ Schema-mode classes:
 Preserve-mode classes:
 - `PreserveTokenizer` (`/preserve-tokenizer`): NDJSON record-boundary scanner, JSON-aware depth tracking, chunk-safe.
 - `PreserveWriter` (`/preserve-writer`): opaque byte-blob sink, pre-allocated shard buffer, zero-GC record path.
-- `PreserveReader` (`/preserve-reader`): tri-API — `getBytes(i)` (zero-alloc view), `getString(i)`, `getJSON(i)`.
+- `PreserveReader` (`/preserve-reader`): tri-API -- `getBytes(i)` (zero-alloc view), `getString(i)`, `getJSON(i)`. A returned view pins the container's ArrayBuffer (plain subarray semantics); copy the bytes out if you need the container to be collectable.
 
 Shared:
 - `StringTable` (`/string-table`): byte-level UTF-8 interning primitive.
-- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` through the pipeline. `preserve` option dispatches to the right writer.
+- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` (e.g. `File.stream()`) through the pipeline. `preserve` option dispatches to the right writer. Per-chunk `onProgress` callback; its state object is reused across calls (mutated in place, zero per-chunk allocation) -- copy it if retained past the callback.
 
 Error classes with stable `code`: `TokenizerError`, `WriterError`, `ReaderError`, `RangeReaderError`, `MultiReaderError`, `SplitError`, `PreserveTokenizerError`, `PreserveWriterError`, `PreserveReaderError`.
-- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` (e.g. `File.stream()`) through the Tokenizer + Writer, returning a Reader. Per-chunk `onProgress` callback; its state object is reused across calls (mutated in place, zero per-chunk allocation) -- copy it if retained past the callback.
-- `TokenizerError`, `WriterError`, `ReaderError`, `RangeReaderError`: thrown on parse/write/read errors with stable `code`.
-- `VERSION` const per subpath.
 
 ## Schema forms
 
-- `{ fields: ['id', 'x', 'y'] }` — all-F64 shorthand, back-compat with M2.
-- `{ fields: [{name:'id', laneKind:'f64'}, {name:'tag', laneKind:'u32'}] }` — mixed lanes (M3).
+- `{ fields: ['id', 'x', 'y'] }` -- all-F64 shorthand, back-compat with M2.
+- `{ fields: [{name:'id', laneKind:'f64'}, {name:'tag', laneKind:'u32'}] }` -- mixed lanes (M3).
 - Sample-and-infer (default when no schema is passed): the first `sampleBytes` of INPUT are observed, byte-true (BS-07) -- the window ends at the first record boundary at or after `sampleBytes` input bytes, read from the Tokenizer's `absOffset`, independent of chunking and record count (a hand-driven Writer with no wired source samples by record count). Fields with only numbers become F64, only strings become U32. null is lane-neutral (BS-20): it sets no kind, so null+string infers U32 (no longer "mixed") and null+number infers F64; post-freeze null reads 0 on an F64 lane and "" on a U32 lane. A field that saw both a real number and a real string raises `W_MIXED_LANE_TYPES` at freeze. Sample memory is O(`sampleBytes`): columnar staging plus a shared string table, independent of total input size.
 
 ## Contract
@@ -60,7 +57,7 @@ Error classes with stable `code`: `TokenizerError`, `WriterError`, `ReaderError`
 
 ## Preservation contract
 
-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).
+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 (~103,000 rows across 20 scenarios per fast-tier run).
 
 ## Row-index and refusal codes
 
@@ -85,7 +82,7 @@ F64 only. Values exceeding IEEE 754 double range are rejected as `E_NUMBER_OVERF
 
 ## Tree-shaking
 
-Subpath entries per SPEC section 6. `sideEffects: false`. Consumers import only the path they need; the browser reader never pulls the writer.
+Subpath entries per SPEC section 6. `sideEffects: false`. Consumers import only the path they need; the browser reader never pulls the writer. Every subpath exports a `VERSION` const.
 
 ## Streaming emission and integrity (M6)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-bake-stream",
-  "version": "1.6.0",
-  "description": "Streaming byte-level JSON to lite-bake binary compiler. Zero-GC, tree-shakeable, gigabyte-scale.",
+  "version": "1.6.1",
+  "description": "Streaming byte-level JSON to LBK1 binary containers. Zero-GC, tree-shakeable, gigabyte-scale.",
   "type": "module",
   "sideEffects": false,
   "exports": {

package/src/FileIngest.js

@@ -2,11 +2,15 @@
 // Browser-side helper: File.stream() -> Tokenizer -> Writer -> Reader.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_OPTION_CONFLICT  - preserve mode requested with a non-ndjson framing
+//
 // The natural browser ingest path is:
 //
 //   const file = fileInputEl.files[0];
-//   const reader = await ingestStream(file.stream(), file.size, {
+//   const reader = await ingestStream(file.stream(), {
 //     framing: 'ndjson',
+//     totalBytes: file.size,
 //     onProgress: ({bytesIngested, totalBytes, rowsWritten, shardsCommitted}) => {...}
 //   });
 //   // reader is a fully-materialized in-memory LBK1 Reader.
@@ -27,7 +31,7 @@ import { PreserveWriter } from './PreserveWriter.js';
 import { PreserveReader } from './PreserveReader.js';
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 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.6.0';
+export const VERSION = '1.6.1';
 
 export class MultiReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'MultiReaderError'; }

package/src/Opts.js

@@ -1,6 +1,10 @@
 // @zakkster/lite-bake-stream / Opts (internal, not exported from index.js)
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_UNKNOWN_OPTION  - an unknown option key (fails closed with a did-you-mean hint)
+//   E_OPTION_VALUE    - an option value falls outside its declared domain
+//
 // Shared construction-time options validator. Every public constructor and
 // entry function that takes an opts object runs checkOpts once, at construction
 // or in a synchronous prologue -- never per byte, never per record. An unknown

package/src/PreserveReader.js

@@ -29,13 +29,15 @@
 //   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 negative, fractional, NaN, or >= totalRows (BS-32)
+//   R_BAD_CRC                - CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT             - CRC verify requested but the container carries no checksum
 //   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.6.0';
+export const VERSION = '1.6.1';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/PreserveTokenizer.js

@@ -1,11 +1,20 @@
 // @zakkster/lite-bake-stream / PreserveTokenizer
 // NDJSON record-boundary scanner for preserve-mode. Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_UNSUPPORTED_FRAMING  - preserve mode fed a framing other than ndjson
+//   E_RECORD_TOO_LARGE     - a single record exceeds maxRecordBytes
+//   E_UNBALANCED           - a record's JSON structure never closes
+//   E_TRUNCATED            - input ends mid-record
+//   E_ENDED                - feed() called after end()
+//   E_POISONED             - reuse after a prior throw
+//
 // The schema-mode Tokenizer walks the full JSON AST (numbers, strings, keys,
 // object/array structure) so the Writer can pack values into typed lanes.
-// Preserve-mode doesn't crack open records — it just needs to find where one
+// Preserve-mode doesn't crack open records -- it just needs to find where one
 // record ends and the next begins, so the record's original bytes can be
 // shoved into a shard intact.
+// See decisions/0010-preserve-mode.md.
 //
 // Contract:
 //   - Input:  NDJSON bytes. One JSON value per line, delimited by 0x0A.
@@ -32,7 +41,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const U32_MAX = 4294967295;
 const PRESERVE_TOKENIZER_OPTS = {
@@ -57,7 +66,7 @@ const BYTE_RBRACK = 0x5D;
 const BYTE_SPACE  = 0x20;
 const BYTE_TAB    = 0x09;
 
-const INITIAL_BUF = 1 << 16;   // 64 KiB — grows on demand for larger records
+const INITIAL_BUF = 1 << 16;   // 64 KiB -- grows on demand for larger records
 
 export class PreserveTokenizer {
   constructor(sink, opts) {

package/src/PreserveWriter.js

@@ -1,6 +1,12 @@
 // @zakkster/lite-bake-stream / PreserveWriter
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   W_EMPTY_INPUT      - finalize with no records written
+//   W_BAD_SINK         - sink is not an object / missing write / async return
+//   W_FINALIZED        - write after the writer was finalized
+//   ST_BLOB_OVERFLOW   - a shard payload_len would exceed the u32 ceiling
+//
 // Preserve-mode sink: opaque record blobs packed into shards, with a trailing
 // u32 offset table per shard. No schema, no lanes, no string table, no zone
 // maps. Bytes in, same bytes out.
@@ -20,7 +26,7 @@ import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal, crc32cCombine } from './Crc32c.js';
 import { validateSink, isThenable } from './Views.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }
@@ -35,7 +41,7 @@ const FINALIZE_TO_SINK_OPTS = {
   layout: { t: 'enum', values: ['prefix', 'stream'] },
   crc: { t: 'bool' },
 };
-const DEFAULT_TARGET_SHARD_BYTES = 8 * 1024 * 1024;   // 8 MiB — smaller than schema mode
+const DEFAULT_TARGET_SHARD_BYTES = 8 * 1024 * 1024;   // 8 MiB -- smaller than schema mode
 const INITIAL_OFFSETS_CAP = 4096;
 const U32_MAX = 4294967295;
 // maxRecordBytes is a declared, validated, deliberately-unused key here: the

package/src/RangeReader.js

@@ -33,6 +33,8 @@
 //   R_ADAPTER_SHORT_READ   -- adapter returned fewer bytes than requested, OR a
 //                             non-Uint8Array / wrong-length adapter return (T7c)
 //   R_ROW_OUT_OF_RANGE     -- rowIdx negative, fractional, NaN, or >= totalRows (BS-32)
+//   R_BAD_CRC              -- CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT           -- CRC verify requested but the container carries no checksum
 //   R_OFFSET_TOO_LARGE     -- a u64 header/schema/directory offset exceeds 2^53-1
 //   R_NOT_PREFETCHED       -- syncRange over a shard that prefetchRange has not cached
 //   R_WRONG_MODE           -- preserve-mode container fed to the schema RangeReader
@@ -46,7 +48,7 @@ import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/Reader.js

@@ -25,6 +25,8 @@
 //                              (Number() would lose precision; fail closed, BS-05)
 //   R_ROW_OUT_OF_RANGE       - get(rowIdx) with rowIdx negative, fractional, NaN,
 //                              or >= totalRows (BS-32)
+//   R_BAD_CRC                - CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT             - CRC verify requested but the container carries no checksum
 //
 // Row-index policy (BS-32): get() range-checks rowIdx; the SHARD-index escape
 // hatches (shardPayload, shardF64, shardStringTable) do NOT -- their contract is
@@ -36,7 +38,7 @@ import { toContainerBuffer } from './Views.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/Split.js

@@ -2,6 +2,10 @@
 // Splitters + per-part compilation + container merge for parallel/checkpointed ingest.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   S_MERGE_EMPTY      - mergeContainers called with no inputs
+//   S_SCHEMA_MISMATCH  - parts carry incompatible schemas
+//
 // M6 covers three primitives that together enable worker-parallel or checkpoint-
 // resumable ingest against LBK1:
 //
@@ -38,7 +42,7 @@ import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -143,7 +147,7 @@ export function compilePart(bytes, opts) {
 // ---------- compileInParts ----------
 
 // Sequential convenience: split then compile each part serially.
-// Returns Uint8Array[] — one container per part. Equivalent output to running
+// Returns Uint8Array[] -- one container per part. Equivalent output to running
 // each part through a worker (or any parallel executor); use this when workers
 // aren't available or for testing.
 export function compileInParts(bytes, opts) {
@@ -237,7 +241,7 @@ export function mergeContainers(containers) {
   const outShardDirBytes  = totalShards * SHARD_ENTRY_BYTES;
 
   // Zone maps: emit iff container 0 has them AND all others do too.
-  // (MultiReader uses the same "all-or-none" policy — see MultiReader.d.ts.)
+  // (MultiReader uses the same "all-or-none" policy -- see MultiReader.d.ts.)
   const outHasZoneMaps = readers.every((r) => r.hasZoneMaps);
   const zoneMapsRaw = readers.map((r) => r.zoneMapsRaw());
   const T = outHasZoneMaps ? zoneMapsRaw[0].trackedFields.length : 0;
@@ -321,7 +325,7 @@ export function mergeContainers(containers) {
     outDv.setUint32(outMetadataOff + 4, totalShards, true);
     outDv.setUint32(outMetadataOff + 8, T, true);
     outDv.setUint32(outMetadataOff + 12, 0, true);
-    // Field index table (copied from container 0 — all containers share the schema)
+    // Field index table (copied from container 0 -- all containers share the schema)
     const fieldTableOut = outMetadataOff + zoneMapsHeaderLen;
     const tracked0 = zoneMapsRaw[0].trackedFields;
     for (let t = 0; t < T; t++) outDv.setUint16(fieldTableOut + t * 2, tracked0[t], true);

package/src/StringTable.js

@@ -2,6 +2,9 @@
 // Byte-level UTF-8 string interning with zero-alloc hot path.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   ST_BLOB_OVERFLOW  - the blob or entry count would cross its u32 ceiling
+//
 // intern(bytes, from, to) -> u32 index, deduplicating identical byte ranges.
 // The hash path never allocates: bytes stay in the caller's buffer during
 // lookup, and internal storage grows in doubling steps.
@@ -14,7 +17,7 @@
 //   u8  blob[blob_length_bytes]
 //
 // The trailing sentinel makes `len(i) = offsets[i+1] - offsets[i]` uniform for
-// all i including the last — no branch in the reader hot path.
+// all i including the last -- no branch in the reader hot path.
 //
 // Entry 0 is always the empty string: the table reserves it in the constructor
 // and at every reset(), so an absent U32 row cell (which is 0) decodes as ""
@@ -38,7 +41,7 @@
 // TEST-ONLY: not re-exported from index.js, absent from the .d.ts and docs,
 // and carrying no semver guarantee.
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const EMPTY_SLOT = 0xFFFFFFFF;   // MUST be unsigned; typed-array reads are unsigned
 const INITIAL_BLOB_BYTES  = 64 * 1024;
@@ -256,7 +259,7 @@ export class StringTable {
   }
 
   // Static: parse a serialized table from a byte view. Returns a read-only
-  // accessor object (not a live StringTable — cheaper for the Reader path).
+  // accessor object (not a live StringTable -- cheaper for the Reader path).
   static parse(bytes, byteOffset) {
     const dv = new DataView(bytes.buffer, bytes.byteOffset + byteOffset, bytes.byteLength - byteOffset);
     const entryCount = dv.getUint32(0, true);
@@ -277,7 +280,7 @@ export class StringTableView {
     this._count = count;
     this._blob = blob;
     this._offsets = offsets;
-    this._decoder = null;   // lazy — created on first get()
+    this._decoder = null;   // lazy -- created on first get()
   }
 
   get count() { return this._count; }

package/src/Tokenizer.js

@@ -30,7 +30,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const U32_MAX = 4294967295;
 const TOKENIZER_OPTS = {
@@ -88,6 +88,7 @@ const NS_EXP      = 7; // in exponent digits
 // correctly-rounded F64 via a single multiplication (positive exp) or single
 // division (negative exp) using this table. Outside that domain, correctly
 // rounded parsing requires David Gay's strtod, deferred to M4+.
+// See decisions/0012-clinger-fast-path.md.
 const POW10 = new Float64Array(23);
 POW10[0] = 1;
 for (let _pi = 1; _pi < 23; _pi++) POW10[_pi] = POW10[_pi - 1] * 10;
@@ -691,7 +692,7 @@ export class Tokenizer {
     const need = to - from;
     if (this._strLen + need > this._maxStringBytes) this._err('E_STRING_TOO_LONG', 'string exceeds maxStringBytes cap (' + (this._strLen + need) + ' > ' + this._maxStringBytes + ')');
     if (this._strLen + need > this._strBuf.length) this._growStrBuf(need);
-    // Manual copy loop — Uint8Array.set(source) via subarray allocates a small
+    // Manual copy loop -- Uint8Array.set(source) via subarray allocates a small
     // view header per call, which turns into MB-scale GC pressure across a
     // string-heavy fixture. The loop is boring but keeps the hot path allocation-free.
     const dst = this._strBuf;

package/src/Views.js

@@ -1,6 +1,9 @@
 // @zakkster/lite-bake-stream / Views (internal)
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   W_BAD_SINK  - shared finalizeToSink guard: sink missing write/writeAt or async
+//
 // One shared helper so every container entry point (deserialize,
 // Reader.fromBuffer, PreserveReader.fromBuffer) resolves caller-supplied bytes
 // to an ArrayBuffer by exactly the SAME rule (BS-09). A Uint8Array that is a

package/src/Writer.js

@@ -11,6 +11,7 @@
 //     setInputSource; hand-driven Writers with no source sample by record
 //     count) buffered in a columnar staging area, per-field lane kind inferred
 //     from observed value types (number->F64, string->U32-into-string-table).
+//     See decisions/0011-sample-drain-reintern.md.
 //     null is lane-neutral (BS-20): it marks the field but sets no kind, so
 //     null+string infers U32 and null+number infers F64. A field that saw both
 //     a real number and a real string raises W_MIXED_LANE_TYPES at freeze.
@@ -52,6 +53,7 @@
 //   W_SCHEMA_TOO_WIDE          - a field offset exceeds the u16 offset_in_row ceiling
 //   W_FIELD_NAME_INVALID       - field name empty, non-string, or > 255 UTF-8 bytes
 //   W_FINALIZED                - a sink event or finalize() after finalize()
+//   W_BAD_SINK                 - finalizeToSink given a sink missing write/writeAt or async
 //   E_UNKNOWN_OPTION           - unknown constructor option key
 //   E_OPTION_VALUE             - constructor option value out of domain
 
@@ -60,7 +62,7 @@ import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal, crc32cCombine } from './Crc32c.js';
 import { validateSink, isThenable } from './Views.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const U32_MAX = 4294967295;
 // Post-finalize sentinel for _recordDepth. Chosen = 2 so every post-finalize
@@ -253,8 +255,8 @@ export class Writer {
     this._schema = null;                // { fields: [{name, laneKind, offsetInRow}], rowStride }
     this._fieldNamesUtf8 = null;
     this._fieldNameHashes = null;
-    this._fieldLaneKinds = null;        // Uint8Array — per-field LANE_* (fast dispatch)
-    this._fieldOffsets  = null;         // Uint16Array — per-field byte offset in row
+    this._fieldLaneKinds = null;        // Uint8Array -- per-field LANE_* (fast dispatch)
+    this._fieldOffsets  = null;         // Uint16Array -- per-field byte offset in row
     this._rowValueSlotsF64 = null;      // Float64Array<fieldCount> scratch
     this._rowValueSlotsU32 = null;      // Uint32Array<fieldCount> scratch
 
@@ -336,7 +338,7 @@ export class Writer {
     } else {
       // Sample window: decode to a JS string NOW. The tokenizer will reuse this
       // buffer for the value bytes before onNumber/onString fires, so we cannot
-      // defer decoding. String allocation here is expected — bounded to the
+      // defer decoding. String allocation here is expected -- bounded to the
       // sample window; steady-state post-freeze remains zero-alloc.
       this._currentKeyName = KEY_DECODER.decode(bytes.subarray(from, to));
     }

package/src/index.js

@@ -8,6 +8,10 @@
 //                           Set opts.preserve = true. Bytes in, same bytes out.
 // deserialize() auto-detects the mode via the container's flag bit and
 // returns the appropriate Reader.
+//
+// Error codes:
+//   E_OPTION_CONFLICT  - serialize() opts combine preserve with an incompatible framing
+//   R_TRUNCATED        - deserialize() container too small to inspect header flags
 
 import { Tokenizer, TokenizerError } from './Tokenizer.js';
 import { Writer, WriterError } from './Writer.js';
@@ -28,7 +32,7 @@ export {
   PreserveWriter, PreserveWriterError,
   PreserveReader, PreserveReaderError,
 };
-export const VERSION = '1.6.0';
+export const VERSION = '1.6.1';
 
 const encoder = new TextEncoder();
 

package/types/MultiReader.d.ts

@@ -24,7 +24,7 @@ export class MultiReader {
   /** Which sub-Reader owns a given global shard? */
   readerForShard(globalShardIdx: number): { readerIdx: number; localShard: number } | null;
 
-  // Zone maps — global shard indices merged across sub-readers
+  // Zone maps -- global shard indices merged across sub-readers
   shardBounds(globalShardIdx: number, fieldName: string): Bounds | null;
   findShards(fieldName: string, opts?: FindShardsOptions): number[];
 }

package/types/RangeReader.d.ts

@@ -86,7 +86,7 @@ export class RangeReader {
     get(rowIdx: number, fieldName: string): number | string | undefined;
   };
 
-  // Zone maps (M7) — synchronous, populated at open()
+  // Zone maps (M7) -- synchronous, populated at open()
   shardBounds(shardIdx: number, fieldName: string): Bounds | null;
   findShards(fieldName: string, opts?: FindShardsOptions): number[];
 }

package/types/Reader.d.ts

@@ -63,7 +63,7 @@ export class Reader {
   fieldIndex(name: string): number;
 
   /**
-   * Get value at (rowIdx, fieldName). F64 lane → number; U32 lane → string
+   * Get value at (rowIdx, fieldName). F64 lane -> number; U32 lane -> string
    * (resolved via the shard's local string table).
    */
   get(rowIdx: number, fieldName: string): number | string | undefined;

package/types/Split.d.ts

@@ -28,7 +28,7 @@ export interface CompileInPartsOptions extends SplitOptions, CompilePartOptions
 
 /**
  * Divide NDJSON bytes into N ranges at safe line boundaries. Every returned
- * range contains complete records — no split mid-line. The union of ranges
+ * range contains complete records -- no split mid-line. The union of ranges
  * equals the original bytes (no gaps, no overlaps).
  */
 export function splitNDJSON(bytes: Uint8Array, opts?: SplitOptions): SplitRange[];

package/types/Tokenizer.d.ts

@@ -5,7 +5,7 @@ export const VERSION: string;
 
 /**
  * Sink protocol the Tokenizer emits into. Byte ranges (bytes[from, to)) are
- * ephemeral — valid only for the duration of the call. Consumers that need
+ * ephemeral -- valid only for the duration of the call. Consumers that need
  * to retain content must copy or decode inside the sink method.
  */
 export interface TokenizerSink {

package/types/Writer.d.ts

@@ -78,7 +78,7 @@ export interface Container {
 export class Writer implements TokenizerSinkForWriter {
   constructor(opts?: WriterOptions);
   /**
-   * Sink protocol — the Tokenizer calls these. Byte ranges are ephemeral.
+   * Sink protocol -- the Tokenizer calls these. Byte ranges are ephemeral.
    */
   onStartObject(): void;
   onEndObject(): void;
@@ -127,7 +127,7 @@ export class Writer implements TokenizerSinkForWriter {
   readonly shardCount: number;
 }
 
-// Structural type — the Writer conforms to the Tokenizer's sink protocol.
+// Structural type -- the Writer conforms to the Tokenizer's sink protocol.
 // (Redeclared here so the /writer subpath is self-contained.)
 interface TokenizerSinkForWriter {
   onStartObject(): void;