@zakkster/lite-bake-stream 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 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.2.0] -- 2026-08-31
+
+M1 -- the write path refuses what it cannot store. Eight findings closed by a set of doors that all run at construction, freeze, or terminal transition; the byte and record hot paths are unchanged (proven by the torture t6 gate, numbers within noise of M0). Suite: 359 tests / 358 pass / 0 fail / 1 todo. Torture: 37/37 fast, 39/39 full, arrayBuffers growth 0. Mutation check: all 63 door tests fail on source revert; all 13 behavior-unchanged pins hold.
+
+### Added
+
+- `src/Opts.js` (internal, not exported): a shared construction-time options validator wired into `Tokenizer`, `Writer`, `PreserveTokenizer`, `PreserveWriter`, `serialize`, `ingestStream`/`ingestFile`, `RangeReader`, `HTTPRangeAdapter.open`, and the `./split` subpath (`splitNDJSON`, `compilePart`, `compileInParts`). Unknown keys throw with a did-you-mean hint (Levenshtein distance <= 2); out-of-domain values throw naming the key, the received value, and the domain.
+- New stable error codes: `E_UNKNOWN_OPTION`, `E_OPTION_VALUE`, `E_OPTION_CONFLICT` (options); `W_DUPLICATE_FIELD`, `W_SCHEMA_TOO_WIDE`, `W_FIELD_NAME_INVALID` (schema freeze); `W_FINALIZED` on the schema `Writer` (already present on `PreserveWriter`); `E_ENDED`, `E_POISONED` (tokenizer terminal state); `E_STRING_TOO_LONG` (maxStringBytes cap).
+
+### Changed
+
+- Unknown or typo'd option keys now throw `E_UNKNOWN_OPTION` instead of being silently ignored.
+- Explicit `0` now means 0 for `sampleBytes` (freeze from the first record), `maxCachedShards` (retain no shard), and `maxRecordBytes` (unlimited) instead of silently becoming the default. `null` is out-of-domain and throws (null is not zero).
+- `Writer.finalize()` called twice now throws `W_FINALIZED` instead of returning the stale container.
+- Over-cap strings now throw the dedicated `E_STRING_TOO_LONG` instead of the wrong `E_UNEXPECTED_BYTE`, and the cap is enforced exactly (no longer only when the 4096-byte buffer grows).
+- `Tokenizer` no longer writes NOOP methods into the caller's sink object; a frozen sink now constructs and drives a full feed/end.
+- `splitNDJSON`/`compileInParts`: an explicit `targetParts:0` or `maxPartBytes:0` now throws instead of silently becoming the default 4 / no-cap, and a negative `targetParts` now throws instead of clamping to 1.
+- `compilePart`/`compileInParts`: `preserve` was never supported and was silently ignored; it is now an unknown-key error (use `serialize(..., {preserve:true})` for preserve mode).
+
+### Fixed
+
+- **BS-02:** an over-wide schema (a field offset past the u16 `offset_in_row` ceiling of 65535) now throws `W_SCHEMA_TOO_WIDE` at freeze instead of wrapping the offset and cross-writing fields. 8192 all-F64 fields freeze; 8193 throw.
+- **BS-03:** duplicate schema field names now throw `W_DUPLICATE_FIELD` at freeze instead of writing a container the Writer reads from one lane and the Reader from another. See `decisions/0003-duplicate-field-names.md`.
+- **BS-04:** a depth-0 non-object record (number, string, true, false, null) now throws `W_TOP_LEVEL_NOT_OBJECT` in schema mode instead of silently vanishing. Preserve mode is unchanged. See `decisions/0002-record-shape-policy.md`.
+- **BS-11:** every construction-time options object is validated at every entry point that takes one; unknown keys and out-of-domain values fail closed.
+- **BS-12:** `maxStringBytes` is enforced exactly against the running string length, so a cap below the initial 4096-byte buffer is honored, and over-cap strings throw `E_STRING_TOO_LONG`.
+- **BS-13:** the schema `Writer` refuses any sink event or a second `finalize()` after `finalize()` with `W_FINALIZED`, matching `PreserveWriter`.
+- **BS-14:** `Tokenizer` and `PreserveTokenizer` refuse `feed()`/`end()` after `end()` (`E_ENDED`) and after any thrown error (`E_POISONED`); a terminal instance never resurrects.
+- **BS-19:** `Tokenizer` reads each sink method once at construction into a per-instance dispatch field (bound to the sink), so the caller's sink object is never mutated and a frozen sink works.
+
+## [1.1.0] -- 2026-08-31
+
+### Added
+
+- Torture gate at the pipeline's canonical path: `node --expose-gc test/torture.mjs` prints `ok` on success, exit 0/1. Tiers: t5 (the 37-scenario stress suite, relocated from bench/ with behavior unchanged), t6 (zero-alloc gates with `maxArrayBuffersGrowth: 0` via measureOps `stabilize: 'deep'` over the tokenizer steady state, the StringTable intern hit path, and the Reader cell loop, each with structural buffer asserts), t7 (lite-leak retention soak: 4096 full-tier cycles, tracker size 0, arrayBuffers delta 0.00 MB), t9 (four in-process controls plus the `BAKE_TORTURE_BREAK=1` whole-suite control, proven to exit non-zero). Tiers t0-t4/t8 are registered reserved stubs. Preflight exits 2 with a remedy line when devDependencies are not installed.
+- `decisions/` directory (repo-only, not shipped): 0001-reserved-empty-string.md records the BS-01 fix and its two rejected alternatives.
+- Round-trip regression suite hardening: 284 tests (282 pass / 2 todo). Five permanent guards pin the BS-01 fix; the two remaining todos are registered known issues (BS-05 invalid UTF-8 acceptance, BS-03 duplicate schema field names). Absent-field fuzz generation, -0 sign, duplicate-key last-wins, null/bool lane-policy codes, and preserve-mode byte-exactness pins added.
+- `npm run verify` (test + torture).
+
+### Changed
+
+- `npm test` now globs `test/*.test.js`; a new test file runs without editing package.json.
+- `bench/torture.js` is a deprecation shim forwarding to `test/torture.mjs` (same exit codes, same `--tier` flag).
+- devDependencies: added `@zakkster/lite-leak` `^1.10.0`; `@zakkster/lite-gc-profiler` `^1.0.0` -> `^1.16.0` (the `stabilize: 'deep'` option used by the t6 gate landed in 1.16.0).
+- SPEC 3.3: string-table entry 0 is reserved as the empty string (writers MUST emit it); SPEC 7 absent-U32 row now reads `""`. See Fixed.
+
+### Fixed
+
+- **BS-01: absent string fields now decode as `""`.** A record that omits a U32-lane field leaves index 0 in that row slot. Index 0 of a shard's string table used to be whichever string interned first in that shard, so `{"s":"zebra"}` followed by `{}` read row 1 back as `"zebra"` -- silently, and differently depending on record order and where shard boundaries fell. `StringTable` now reserves index 0 as the empty string in its constructor and at every `reset()`, so absent U32 cells decode as `""` on every write path: explicit schema, sample-and-infer, and every shard of a multi-shard drain. Containers written before this change keep their old bytes and their old, data-dependent behavior on those bytes; the fix is not retroactive. Readers are unchanged. SPEC 3.3 and the SPEC 7 coercion table are amended to match.
+
 ## [1.0.0] — 2026-07-12
 
 First stable release. The LBK1 container format is frozen at `format_version: 1`.

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.0.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.
+**Status:** v1.2.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
 

package/SPEC.md

@@ -95,7 +95,7 @@ u32   offsets[entry_count + 1]   // byte offsets into blob, INCLUDING a trailing
 u8    blob[blob_length_bytes]
 ```
 
-Padded to 8. Strings are UTF-8, not null-terminated. Length of string `i` is `offsets[i+1] - offsets[i]`; the trailing sentinel makes this valid for `i = entry_count - 1` without a branch. Entry index 0 is not reserved; the empty string is a legitimate entry.
+Padded to 8. Strings are UTF-8, not null-terminated. Length of string `i` is `offsets[i+1] - offsets[i]`; the trailing sentinel makes this valid for `i = entry_count - 1` without a branch. Entry index 0 is reserved: it is always the empty string. Writers MUST emit "" as entry 0 of every shard's local table, including tables that hold no other entries. Readers MAY rely on this for containers written at or after this rule; containers written before it may hold any string at index 0.
 
 Per-shard tables are placed immediately after their shard payload in the container, so a single HTTP Range fetch covering `[payload_off, payload_off + payload_len + local_string_len)` retrieves both.
 
@@ -337,7 +337,7 @@ Given source NDJSON `S` and a schema `Σ` (either explicit or inferred), the LBK
 | JSON string (any valid UTF-8) | U32 | **byte-exact UTF-8 sequence** |
 | JSON `true` / `false` / `null` | F64 | `1` / `0` / `0` (documented coercion) |
 | absent field (missing in source) | F64 | `0` (default) |
-| absent field | U32 | string at index 0 of the shard's local table |
+| absent field | U32 | `""` (index 0 is the reserved empty-string entry) |
 | field in source but NOT in `Σ` | — | silently dropped (matches lite-bake core) |
 | field in `Σ` with wrong value type (post-freeze) | — | `W_LANE_MISMATCH` error, container not produced |
 

package/llms.txt

@@ -8,13 +8,13 @@ Ingest gigabyte-scale JSON (top-level array or NDJSON) into the `lite-bake` LBK1
 
 ## Status
 
-v1.0.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.2.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.0.0)
+## Public API (v1.2.0)
 
 Two ingest modes share one top-level API:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-bake-stream",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Streaming byte-level JSON to lite-bake binary compiler. Zero-GC, tree-shakeable, gigabyte-scale.",
   "type": "module",
   "sideEffects": false,
@@ -76,10 +76,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/Tokenizer.test.js test/RoundTrip.test.js test/StringRoundTrip.test.js test/DataPreservation.test.js test/NumericBoundary.test.js test/RangeReader.test.js test/FileIngest.test.js test/ZoneMaps.test.js test/M4.test.js test/M6.test.js test/Conformance.test.js test/Fuzz.test.js test/OffsetOverflow.test.js test/Preserve.test.js",
+    "test": "node --test test/*.test.js",
     "bench": "node --expose-gc bench/bench-tokenizer.js",
-    "torture": "node --expose-gc bench/torture.js --tier=fast",
-    "torture:full": "node --expose-gc bench/torture.js --tier=full",
+    "torture": "node --expose-gc test/torture.mjs",
+    "torture:full": "node --expose-gc test/torture.mjs --tier=full",
+    "verify": "npm test && npm run torture",
     "soak": "node --expose-gc bench/soak.js --mb=100 --verify",
     "soak:500": "node --expose-gc bench/soak.js --mb=500 --verify",
     "soak:1gb": "node --expose-gc bench/soak.js --gb=1 --verify",
@@ -112,6 +113,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@zakkster/lite-gc-profiler": "^1.0.0"
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0"
   }
 }

package/src/FileIngest.js

@@ -20,13 +20,24 @@
 // most engines), use server-side pre-compilation and RangeReader instead.
 
 import { Tokenizer } from './Tokenizer.js';
-import { Writer } from './Writer.js';
+import { Writer, WriterError } from './Writer.js';
 import { Reader } from './Reader.js';
 import { PreserveTokenizer } from './PreserveTokenizer.js';
 import { PreserveWriter } from './PreserveWriter.js';
 import { PreserveReader } from './PreserveReader.js';
+import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
+
+const U32_MAX = 4294967295;
+const INGEST_OPTS = {
+  preserve: { t: 'bool' },
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  writer: { t: 'obj' },
+  onProgress: { t: 'fn' },
+  totalBytes: { t: 'int', min: 0, max: Number.MAX_SAFE_INTEGER },
+};
+function raiseIngest(code, msg) { throw new WriterError(code, msg); }
 
 // Ingest a ReadableStream<Uint8Array> and return a Reader over the resulting
 // LBK1 container. Options:
@@ -42,16 +53,23 @@ export const VERSION = '1.0.0';
 //   totalBytes:         optional total for progress percentage. Pass file.size
 //                       when ingesting a File; omit for indeterminate streams.
 export async function ingestStream(readableStream, opts) {
+  // Validated once, here, after ingestFile's totalBytes merge (R6): a single
+  // label, no double report.
+  checkOpts('ingestStream', opts, INGEST_OPTS, raiseIngest);
   opts = opts || {};
   const preserve = opts.preserve === true;
-  const framing  = opts.framing || 'ndjson';
-  const writerOpts = opts.writer || {};
-  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : null;
-  const totalBytes = typeof opts.totalBytes === 'number' ? opts.totalBytes : -1;
+  const framing  = opts.framing !== undefined ? opts.framing : 'ndjson';
+  const writerOpts = opts.writer !== undefined ? opts.writer : {};
+  const onProgress = opts.onProgress !== undefined ? opts.onProgress : null;
+  const totalBytes = opts.totalBytes !== undefined ? opts.totalBytes : -1;
+  if (preserve && opts.framing !== undefined && opts.framing !== 'ndjson') {
+    throw new WriterError('E_OPTION_CONFLICT',
+      "ingestStream: preserve mode is NDJSON-only; remove framing:'" + opts.framing + "' or set preserve:false");
+  }
 
   const writer = preserve ? new PreserveWriter(writerOpts) : new Writer(writerOpts);
   const tokenizer = preserve
-    ? new PreserveTokenizer(writer, { framing, maxRecordBytes: writerOpts.maxRecordBytes || 0 })
+    ? new PreserveTokenizer(writer, { framing, maxRecordBytes: writerOpts.maxRecordBytes !== undefined ? writerOpts.maxRecordBytes : 0 })
     : new Tokenizer(writer, { framing });
 
   const reader = readableStream.getReader();

package/src/MultiReader.js

@@ -24,7 +24,7 @@
 //   M_UNKNOWN_FIELD       - .get() / .fieldIndex() called with unknown name
 //   M_ROW_OUT_OF_RANGE    - rowIdx >= totalRows
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 export class MultiReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'MultiReaderError'; }

package/src/Opts.js

@@ -0,0 +1,189 @@
+// @zakkster/lite-bake-stream / Opts (internal, not exported from index.js)
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+//
+// 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
+// key is an error with a did-you-mean hint (suite law: no silent ignore). An
+// out-of-domain value is an error (suite law: null is not zero; explicit 0 is 0
+// where 0 is in-domain). This file allocates only on the throw path.
+//
+// Each host declares a module-level frozen spec object literal mapping every
+// known key to a domain descriptor:
+//   { t: 'enum', values: [...] }        - string, must be a listed member
+//   { t: 'int',  min, max }             - integer in [min, max] inclusive
+//   { t: 'bool' }                       - boolean
+//   { t: 'fn' }                         - function
+//   { t: 'obj', nullable }              - object (contents validated downstream)
+// A value of `undefined` for any key means "use the default" and is skipped,
+// matching each host's `opts.k !== undefined ? opts.k : DEFAULT` defaulting.
+//
+// OPTS DOMAIN TABLE (ships with the package; the M1 plan is the source of truth)
+//
+// Unknown-key rule (all entry points): throw E_UNKNOWN_OPTION. Levenshtein
+// distance from the offending key to every known key; if the minimum is <= 2,
+// message is "unknown option 'framming' -- did you mean 'framing'?"; else
+// "unknown option 'zzz' (known: framing, maxStringBytes)". Ties break by spec
+// declaration order.
+//
+//   Tokenizer(sink,opts)
+//     framing         enum 'auto'|'array'|'ndjson'      def 'auto'
+//     maxStringBytes  int [1, 4294967295]               def 1048576   (0 forbidden)
+//   Writer(opts)
+//     schema          object|null with array fields     def null
+//     targetShardBytes int [1, 4294967295]              def 33554432  (0 forbidden)
+//     sampleBytes     int [0, 4294967295]               def targetShardBytes  (0 = freeze on record 1)
+//   PreserveTokenizer(sink,opts)
+//     framing         enum 'ndjson'                      def 'ndjson'
+//     maxRecordBytes  int [0, 4294967295]               def 0         (0 = unlimited)
+//   PreserveWriter(opts)
+//     targetShardBytes int [1, 4294967295]              def 8388608   (0 forbidden)
+//     maxRecordBytes  int [0, 4294967295]               declared, consumed by PreserveTokenizer
+//   serialize(input,opts) / ingestStream / ingestFile
+//     preserve        bool                               def false
+//     framing         enum 'auto'|'array'|'ndjson'       def 'ndjson'  (conflict if preserve && != 'ndjson')
+//     writer          object                             def {}
+//     onProgress      function                           (ingest only)
+//     totalBytes      int [0, 9007199254740991]          def -1        (ingest only)
+//   RangeReader(adapter,opts) / .open
+//     maxCachedShards int [0, 4294967295]               def 8         (0 = retain no shard)
+//   HTTPRangeAdapter.open(url,opts)
+//     fetch           function                           def globalThis.fetch
+//   splitNDJSON(bytes,opts) / compileInParts
+//     targetParts     int [1, 4294967295]               def 4         (0 forbidden)
+//     maxPartBytes    int [1, 4294967295] or Infinity   def Infinity  (0 forbidden; Infinity = no cap)
+//   compilePart(bytes,opts) / compileInParts
+//     framing         enum 'auto'|'array'|'ndjson'       def 'ndjson'
+//     writer          object                             def {}
+//
+// Non-integer, NaN, Infinity, negative, null, and wrong-typeof all land on
+// E_OPTION_VALUE with a message naming key, received value, and the domain.
+
+export function checkOpts(label, opts, spec, raise) {
+  if (opts === undefined || opts === null || typeof opts !== 'object') return;
+  for (const key in opts) {
+    if (!Object.prototype.hasOwnProperty.call(opts, key)) continue;
+    const d = spec[key];
+    if (d === undefined) {
+      const keys = Object.keys(spec);
+      const near = nearestKey(key, keys);
+      if (near !== null) {
+        raise('E_UNKNOWN_OPTION',
+          label + ": unknown option '" + key + "' -- did you mean '" + near + "'?");
+      } else {
+        raise('E_UNKNOWN_OPTION',
+          label + ": unknown option '" + key + "' (known: " + keys.join(', ') + ')');
+      }
+      continue;
+    }
+    const v = opts[key];
+    if (v === undefined) continue;   // explicit undefined == use default
+    _checkValue(label, key, v, d, raise);
+  }
+}
+
+function _checkValue(label, key, v, d, raise) {
+  const t = d.t;
+  if (t === 'int') {
+    if (d.inf && v === Infinity) return;   // Infinity is a legal explicit value for this key
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < d.min || v > d.max) {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be an integer in [" +
+        d.min + ', ' + d.max + ']' + (d.inf ? ' or Infinity' : '') + '; got ' + _show(v));
+    }
+    return;
+  }
+  if (t === 'enum') {
+    if (typeof v !== 'string' || d.values.indexOf(v) < 0) {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be one of " +
+        _quoteList(d.values) + '; got ' + _show(v));
+    }
+    return;
+  }
+  if (t === 'bool') {
+    if (typeof v !== 'boolean') {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be a boolean; got " + _show(v));
+    }
+    return;
+  }
+  if (t === 'fn') {
+    if (typeof v !== 'function') {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be a function; got " + _show(v));
+    }
+    return;
+  }
+  if (t === 'obj') {
+    if (v === null) {
+      if (!d.nullable) {
+        raise('E_OPTION_VALUE',
+          label + ": option '" + key + "' must be an object; got null");
+      }
+      return;
+    }
+    if (typeof v !== 'object' || Array.isArray(v)) {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be an object; got " + _show(v));
+    }
+  }
+}
+
+function _show(v) {
+  if (typeof v === 'string') return "'" + v + "'";
+  if (v === null) return 'null';
+  if (typeof v === 'object') return Array.isArray(v) ? 'array' : 'object';
+  return String(v);
+}
+
+function _quoteList(values) {
+  let s = '';
+  for (let i = 0; i < values.length; i++) {
+    if (i > 0) s += ', ';
+    s += "'" + values[i] + "'";
+  }
+  return s;
+}
+
+// Nearest known key by Levenshtein distance, returning it only when the minimum
+// distance is <= 2. Ties break by declaration order (strict < keeps the first).
+export function nearestKey(key, knownKeys) {
+  let best = null;
+  let bestDist = 3;
+  const klen = key.length;
+  for (let k = 0; k < knownKeys.length; k++) {
+    const cand = knownKeys[k];
+    const diff = klen - cand.length;
+    if (diff > 2 || diff < -2) continue;   // length delta alone exceeds the cap
+    const dist = _lev(key, cand);
+    if (dist < bestDist) { bestDist = dist; best = cand; }
+  }
+  return bestDist <= 2 ? best : null;
+}
+
+// Two-row Levenshtein. Allocates two small arrays; only reached on the throw
+// path (nearestKey is called only when an unknown key is being reported).
+function _lev(a, b) {
+  const n = a.length, m = b.length;
+  if (n === 0) return m;
+  if (m === 0) return n;
+  let prev = new Array(m + 1);
+  let curr = new Array(m + 1);
+  for (let j = 0; j <= m; j++) prev[j] = j;
+  for (let i = 1; i <= n; i++) {
+    curr[0] = i;
+    const ca = a.charCodeAt(i - 1);
+    for (let j = 1; j <= m; j++) {
+      const cost = ca === b.charCodeAt(j - 1) ? 0 : 1;
+      let v = prev[j] + 1;
+      const del = curr[j - 1] + 1;
+      if (del < v) v = del;
+      const sub = prev[j - 1] + cost;
+      if (sub < v) v = sub;
+      curr[j] = v;
+    }
+    const tmp = prev; prev = curr; curr = tmp;
+  }
+  return prev[m];
+}

package/src/PreserveReader.js

@@ -17,7 +17,7 @@
 // buffer. It is valid for as long as the Reader instance holds the container.
 // Do NOT mutate it, and do NOT retain it past the Reader's lifetime.
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/PreserveTokenizer.js

@@ -25,12 +25,25 @@
 // Errors (stable E_* codes):
 //   E_TRUNCATED         - end of input reached mid-record (depth != 0 or in-string)
 //   E_RECORD_TOO_LARGE  - single record exceeds maxRecordBytes (default: none)
+//   E_ENDED             - feed()/end() after end()
+//   E_POISONED          - feed()/end() after a thrown error
+//   E_UNKNOWN_OPTION    - unknown constructor option key
+//   E_OPTION_VALUE      - constructor option value out of domain
 
-export const VERSION = '1.0.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.2.0';
+
+const U32_MAX = 4294967295;
+const PRESERVE_TOKENIZER_OPTS = {
+  framing: { t: 'enum', values: ['ndjson', 'array', 'auto'] },
+  maxRecordBytes: { t: 'int', min: 0, max: U32_MAX },
+};
 
 export class PreserveTokenizerError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveTokenizerError'; }
 }
+function raisePreserveTok(code, msg) { throw new PreserveTokenizerError(code, msg); }
 
 // Byte values used by the scanner (named so the hot loop reads cleanly).
 const BYTE_LF     = 0x0A;
@@ -51,14 +64,18 @@ export class PreserveTokenizer {
     if (!sink || typeof sink.onRecord !== 'function') {
       throw new TypeError('PreserveTokenizer: sink must implement onRecord(bytes, from, to)');
     }
+    checkOpts('PreserveTokenizer', opts, PRESERVE_TOKENIZER_OPTS, raisePreserveTok);
     opts = opts || {};
-    if (opts.framing && opts.framing !== 'ndjson') {
+    if (opts.framing !== undefined && opts.framing !== 'ndjson') {
       // 'array' framing (top-level `[a, b, c]`) is a future addition.
       throw new PreserveTokenizerError('E_UNSUPPORTED_FRAMING',
         'preserve-mode currently supports NDJSON only; got framing=' + opts.framing);
     }
     this._sink = sink;
-    this._maxRecordBytes = typeof opts.maxRecordBytes === 'number' ? opts.maxRecordBytes : 0;   // 0 = unlimited
+    this._maxRecordBytes = opts.maxRecordBytes !== undefined ? opts.maxRecordBytes : 0;   // 0 = unlimited
+    // Terminal state (BS-14): once ended or poisoned, the instance is dead.
+    this._ended = false;
+    this._poisoned = false;
     // Accumulator: bytes seen since the last emitted record's terminating LF.
     this._buf = new Uint8Array(INITIAL_BUF);
     this._bufLen = 0;
@@ -71,6 +88,8 @@ export class PreserveTokenizer {
   }
 
   feed(chunk) {
+    if (this._poisoned) throw new PreserveTokenizerError('E_POISONED', 'tokenizer poisoned by a previous error; construct a new instance');
+    if (this._ended) throw new PreserveTokenizerError('E_ENDED', 'tokenizer already ended; construct a new instance');
     if (!(chunk instanceof Uint8Array)) {
       throw new TypeError('PreserveTokenizer.feed: expected Uint8Array');
     }
@@ -84,9 +103,12 @@ export class PreserveTokenizer {
   }
 
   end() {
+    if (this._poisoned) throw new PreserveTokenizerError('E_POISONED', 'tokenizer poisoned by a previous error; construct a new instance');
+    if (this._ended) throw new PreserveTokenizerError('E_ENDED', 'tokenizer already ended; construct a new instance');
     if (this._bufLen > this._recordStart) {
       // There's pending content that never terminated.
       if (this._depth !== 0 || this._inString || this._escape) {
+        this._poisoned = true;
         throw new PreserveTokenizerError('E_TRUNCATED',
           'input ended mid-record at byte ' + (this._absOffset + this._bufLen) +
           ' (depth=' + this._depth + ', inString=' + this._inString + ')');
@@ -96,6 +118,7 @@ export class PreserveTokenizer {
       this._emitRecord(this._recordStart, this._bufLen);
       this._recordStart = this._bufLen;
     }
+    this._ended = true;
   }
 
   _scan(from) {
@@ -119,6 +142,7 @@ export class PreserveTokenizer {
           depth--;
           if (depth < 0) {
             this._depth = depth; this._inString = inString; this._escape = escape;
+            this._poisoned = true;
             throw new PreserveTokenizerError('E_UNBALANCED',
               'closing bracket without matching open at byte ' + (this._absOffset + i));
           }
@@ -130,6 +154,7 @@ export class PreserveTokenizer {
         }
       }
       if (this._maxRecordBytes > 0 && (i - this._recordStart) > this._maxRecordBytes) {
+        this._poisoned = true;
         throw new PreserveTokenizerError('E_RECORD_TOO_LARGE',
           'record starting at byte ' + (this._absOffset + this._recordStart) +
           ' exceeded maxRecordBytes=' + this._maxRecordBytes);

package/src/PreserveWriter.js

@@ -16,22 +16,35 @@
 // Reader dispatch happens via the flag bit; a schema-mode Reader refuses this
 // container with R_WRONG_MODE.
 
-export const VERSION = '1.0.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.2.0';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }
 }
+function raisePreserveWriter(code, msg) { throw new PreserveWriterError(code, msg); }
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
 const FOOTER_BYTES = 16;
 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
+// documented call serialize(x, {preserve:true, writer:{maxRecordBytes:N}}) reads
+// it out of opts.writer and hands it to PreserveTokenizer, which consumes it.
+// PreserveWriter accepts it so that call shape does not trip E_UNKNOWN_OPTION.
+const PRESERVE_WRITER_OPTS = {
+  targetShardBytes: { t: 'int', min: 1, max: U32_MAX },
+  maxRecordBytes: { t: 'int', min: 0, max: U32_MAX },
+};
 
 export class PreserveWriter {
   constructor(opts) {
+    checkOpts('PreserveWriter', opts, PRESERVE_WRITER_OPTS, raisePreserveWriter);
     opts = opts || {};
-    this._targetShardBytes = opts.targetShardBytes || DEFAULT_TARGET_SHARD_BYTES;
+    this._targetShardBytes = opts.targetShardBytes !== undefined ? opts.targetShardBytes : DEFAULT_TARGET_SHARD_BYTES;
     this._shards = [];
     this._totalRows = 0;
     this._finalized = false;

package/src/RangeReader.js

@@ -34,8 +34,9 @@
 //   R_ROW_OUT_OF_RANGE     -- rowIdx >= totalRows
 
 import { StringTable } from './StringTable.js';
+import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -44,10 +45,15 @@ const FIELD_DESCRIPTOR_BYTES = 24;
 const LANE_F64 = 1;
 const LANE_U32 = 3;
 const READER_VERSION = 1;
+const U32_MAX = 4294967295;
+
+const RANGE_READER_OPTS = { maxCachedShards: { t: 'int', min: 0, max: U32_MAX } };
+const HTTP_ADAPTER_OPTS = { fetch: { t: 'fn' } };
 
 export class RangeReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'RangeReaderError'; }
 }
+function raiseRange(code, msg) { throw new RangeReaderError(code, msg); }
 
 // ----- Adapters --------------------------------------------------------------
 
@@ -56,8 +62,9 @@ export class RangeReaderError extends Error {
 // origin/CDN).
 export class HTTPRangeAdapter {
   static async open(url, opts) {
+    checkOpts('HTTPRangeAdapter', opts, HTTP_ADAPTER_OPTS, raiseRange);
     opts = opts || {};
-    const fetchImpl = opts.fetch || globalThis.fetch;
+    const fetchImpl = opts.fetch !== undefined ? opts.fetch : globalThis.fetch;
     if (typeof fetchImpl !== 'function') {
       throw new RangeReaderError('R_TRUNCATED', 'no fetch() available in this environment');
     }
@@ -148,9 +155,10 @@ export class RangeReader {
   }
 
   constructor(adapter, opts) {
+    checkOpts('RangeReader', opts, RANGE_READER_OPTS, raiseRange);
     opts = opts || {};
     this.adapter = adapter;
-    this.maxCachedShards = opts.maxCachedShards || 8;
+    this.maxCachedShards = opts.maxCachedShards !== undefined ? opts.maxCachedShards : 8;
     // shard cache: shardIdx -> { payloadBytes, payloadDv, stringTable, lastAccess }
     this._shardCache = new Map();
     this._accessCounter = 0;

package/src/Reader.js

@@ -18,7 +18,7 @@
 
 import { StringTable } from './StringTable.js';
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/Split.js

@@ -35,8 +35,9 @@ import { Tokenizer, TokenizerError } from './Tokenizer.js';
 import { Writer, WriterError } from './Writer.js';
 import { Reader, ReaderError } from './Reader.js';
 import { StringTable } from './StringTable.js';
+import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -44,10 +45,27 @@ const SHARD_ENTRY_BYTES = 40;
 const FIELD_DESCRIPTOR_BYTES = 24;
 const FOOTER_BYTES = 16;
 const LANE_F64 = 1;
+const U32_MAX = 4294967295;
+
+const SPLIT_NDJSON_OPTS = {
+  targetParts: { t: 'int', min: 1, max: U32_MAX },
+  maxPartBytes: { t: 'int', min: 1, max: U32_MAX, inf: true },
+};
+const COMPILE_PART_OPTS = {
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  writer: { t: 'obj' },
+};
+const COMPILE_IN_PARTS_OPTS = {
+  targetParts: { t: 'int', min: 1, max: U32_MAX },
+  maxPartBytes: { t: 'int', min: 1, max: U32_MAX, inf: true },
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  writer: { t: 'obj' },
+};
 
 export class SplitError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'SplitError'; }
 }
+function raiseSplit(code, msg) { throw new SplitError(code, msg); }
 
 // ---------- splitNDJSON ----------
 
@@ -67,8 +85,9 @@ export function splitNDJSON(bytes, opts) {
     throw new TypeError('splitNDJSON: expected Uint8Array');
   }
   opts = opts || {};
-  const targetParts = Math.max(1, opts.targetParts || 4);
-  const maxPartBytes = opts.maxPartBytes || Infinity;
+  checkOpts('splitNDJSON', opts, SPLIT_NDJSON_OPTS, raiseSplit);
+  const targetParts = Math.max(1, opts.targetParts !== undefined ? opts.targetParts : 4);
+  const maxPartBytes = opts.maxPartBytes !== undefined ? opts.maxPartBytes : Infinity;
   const total = bytes.length;
   if (total === 0) return [];
 
@@ -110,8 +129,9 @@ export function compilePart(bytes, opts) {
     throw new TypeError('compilePart: expected Uint8Array');
   }
   opts = opts || {};
-  const framing = opts.framing || 'ndjson';
-  const w = new Writer(opts.writer || {});
+  checkOpts('compilePart', opts, COMPILE_PART_OPTS, raiseSplit);
+  const framing = opts.framing !== undefined ? opts.framing : 'ndjson';
+  const w = new Writer(opts.writer !== undefined ? opts.writer : {});
   const t = new Tokenizer(w, { framing });
   t.feed(bytes);
   t.end();
@@ -126,13 +146,14 @@ export function compilePart(bytes, opts) {
 // aren't available or for testing.
 export function compileInParts(bytes, opts) {
   opts = opts || {};
+  checkOpts('compileInParts', opts, COMPILE_IN_PARTS_OPTS, raiseSplit);
   const splitOpts = {
     targetParts: opts.targetParts,
     maxPartBytes: opts.maxPartBytes,
   };
   const partOpts = {
-    framing: opts.framing || 'ndjson',
-    writer: opts.writer || {},
+    framing: opts.framing !== undefined ? opts.framing : 'ndjson',
+    writer: opts.writer !== undefined ? opts.writer : {},
   };
   const ranges = splitNDJSON(bytes, splitOpts);
   const containers = new Array(ranges.length);

package/src/StringTable.js

@@ -15,8 +15,12 @@
 //
 // 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.
+//
+// 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 ""
+// rather than aliasing the shard's first-interned string (SPEC 3.3, SPEC 7).
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const EMPTY_SLOT = 0xFFFFFFFF;   // MUST be unsigned; typed-array reads are unsigned
 const INITIAL_BLOB_BYTES  = 64 * 1024;
@@ -25,6 +29,10 @@ const INITIAL_HASH_CAP    = 2048;      // load factor target 50%
 const HASH_MAX_LOAD_NUM   = 1;         // 50% load factor: num/den = 1/2
 const HASH_MAX_LOAD_DEN   = 2;
 
+// Reserved entry 0. A zero-length range: no blob bytes, no growth, one hash
+// slot. Module-level so reset() reserves without allocating.
+const EMPTY = new Uint8Array(0);
+
 // FNV-1a 32-bit over a byte range.
 function fnv1a(bytes, from, to) {
   let h = 0x811c9dc5 | 0;
@@ -44,6 +52,7 @@ export class StringTable {
     this._hashCap = INITIAL_HASH_CAP;
     this._hashMask = INITIAL_HASH_CAP - 1;
     this._hashKeys = new Uint32Array(INITIAL_HASH_CAP).fill(EMPTY_SLOT);
+    this._reserveEmpty();
   }
 
   // Returns u32 index of the string with these bytes, adding a new entry if
@@ -76,6 +85,13 @@ export class StringTable {
     return true;
   }
 
+  // Class invariant: index 0 is the empty string. Zero-alloc -- _insertNew with
+  // n === 0 appends no bytes, offsets[0]/[1] already exist, and the load-factor
+  // check cannot trip at count 1.
+  _reserveEmpty() {
+    this.intern(EMPTY, 0, 0);
+  }
+
   _insertNew(bytes, from, to, slot) {
     const n = to - from;
     // Grow blob if needed
@@ -158,6 +174,7 @@ export class StringTable {
     // (we only touched [0..count], so the fill is bounded)
     this._offsets[0] = 0;
     this._hashKeys.fill(EMPTY_SLOT);
+    this._reserveEmpty();
   }
 
   // Serialize into the LBK1 per-shard string-table byte layout described at the

package/src/Tokenizer.js

@@ -16,8 +16,22 @@
 //   E_KEYWORD_MISMATCH     - true/false/null spelled wrong
 //   E_TRAILING_INPUT       - non-whitespace bytes after top-level value(s) (array mode only)
 //   E_DEPTH_LIMIT          - nesting depth exceeded MAX_DEPTH
+//   E_STRING_TOO_LONG      - string exceeds maxStringBytes cap
+//   E_ENDED                - feed()/end() after end()
+//   E_POISONED             - feed()/end() after a thrown error
+//   E_UNKNOWN_OPTION       - unknown constructor option key
+//   E_OPTION_VALUE         - constructor option value out of domain
 
-export const VERSION = '1.0.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.2.0';
+
+const U32_MAX = 4294967295;
+const TOKENIZER_OPTS = {
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  maxStringBytes: { t: 'int', min: 1, max: U32_MAX },
+};
+function raiseTok(code, msg) { throw new TokenizerError(code, 0, msg); }
 
 // ---------- byte constants ----------
 const B_SPACE = 0x20, B_TAB = 0x09, B_LF = 0x0A, B_CR = 0x0D;
@@ -104,24 +118,33 @@ const NOOP = () => {};
 export class Tokenizer {
   constructor(sink, opts) {
     if (!sink) throw new Error('sink required');
+    checkOpts('Tokenizer', opts, TOKENIZER_OPTS, raiseTok);
     this.sink = sink;
 
     // top-level framing: 'auto' (default), 'array', or 'ndjson'
-    this._framing = (opts && opts.framing) || 'auto';
-    this._maxStringBytes = (opts && opts.maxStringBytes) || (1 << 20); // 1 MB default cap
-
-    // fill in missing sink methods to avoid per-token undefined checks
-    if (!sink.onStartObject) sink.onStartObject = NOOP;
-    if (!sink.onEndObject)   sink.onEndObject   = NOOP;
-    if (!sink.onStartArray)  sink.onStartArray  = NOOP;
-    if (!sink.onEndArray)    sink.onEndArray    = NOOP;
-    if (!sink.onKey)         sink.onKey         = NOOP;
-    if (!sink.onString)      sink.onString      = NOOP;
-    if (!sink.onNumber)      sink.onNumber      = NOOP;
-    if (!sink.onTrue)        sink.onTrue        = NOOP;
-    if (!sink.onFalse)       sink.onFalse       = NOOP;
-    if (!sink.onNull)        sink.onNull        = NOOP;
-    if (!sink.onEnd)         sink.onEnd         = NOOP;
+    this._framing = (opts && opts.framing !== undefined) ? opts.framing : 'auto';
+    this._maxStringBytes = (opts && opts.maxStringBytes !== undefined) ? opts.maxStringBytes : (1 << 20); // 1 MB default cap
+
+    // Per-instance dispatch fields: bind each present sink method to the sink
+    // once at construction (cold path), defaulting to NOOP. The caller's sink
+    // object is never mutated (BS-19), so a frozen sink constructs and drives
+    // fine. Binding preserves the sink as receiver while the hot call sites read
+    // a single monomorphic field (this._onX) instead of this.sink.onX.
+    this._onStartObject = sink.onStartObject ? sink.onStartObject.bind(sink) : NOOP;
+    this._onEndObject   = sink.onEndObject   ? sink.onEndObject.bind(sink)   : NOOP;
+    this._onStartArray  = sink.onStartArray  ? sink.onStartArray.bind(sink)  : NOOP;
+    this._onEndArray    = sink.onEndArray    ? sink.onEndArray.bind(sink)    : NOOP;
+    this._onKey         = sink.onKey         ? sink.onKey.bind(sink)         : NOOP;
+    this._onString      = sink.onString      ? sink.onString.bind(sink)      : NOOP;
+    this._onNumber      = sink.onNumber      ? sink.onNumber.bind(sink)      : NOOP;
+    this._onTrue        = sink.onTrue        ? sink.onTrue.bind(sink)        : NOOP;
+    this._onFalse       = sink.onFalse       ? sink.onFalse.bind(sink)       : NOOP;
+    this._onNull        = sink.onNull        ? sink.onNull.bind(sink)        : NOOP;
+    this._onEnd         = sink.onEnd         ? sink.onEnd.bind(sink)         : NOOP;
+
+    // Terminal state (BS-14): once ended or poisoned, the instance is dead.
+    this._ended = false;
+    this._poisoned = false;
 
     // parser state
     this._state = S_TOP;
@@ -158,6 +181,8 @@ export class Tokenizer {
 
   // Feed a chunk. Bytes are consumed synchronously; sink events fire during this call.
   feed(chunk) {
+    if (this._poisoned) throw new TokenizerError('E_POISONED', this._absOffset, 'tokenizer poisoned by a previous error; construct a new instance');
+    if (this._ended) throw new TokenizerError('E_ENDED', this._absOffset, 'tokenizer already ended; construct a new instance');
     const len = chunk.length;
     let i = 0;
     while (i < len) {
@@ -306,9 +331,9 @@ export class Tokenizer {
         this._kwPos++;
         i++; this._absOffset++;
         if (this._kwPos === tmpl.length) {
-          if (this._kwId === KW_ID_TRUE) this.sink.onTrue();
-          else if (this._kwId === KW_ID_FALSE) this.sink.onFalse();
-          else this.sink.onNull();
+          if (this._kwId === KW_ID_TRUE) this._onTrue();
+          else if (this._kwId === KW_ID_FALSE) this._onFalse();
+          else this._onNull();
           this._afterValue();
         }
         continue;
@@ -320,6 +345,8 @@ export class Tokenizer {
   }
 
   end() {
+    if (this._poisoned) throw new TokenizerError('E_POISONED', this._absOffset, 'tokenizer poisoned by a previous error; construct a new instance');
+    if (this._ended) throw new TokenizerError('E_ENDED', this._absOffset, 'tokenizer already ended; construct a new instance');
     // A trailing number may still be pending
     if (this._state === S_NUMBER) {
       this._emitNumber();
@@ -328,7 +355,8 @@ export class Tokenizer {
       if (this._arrayMode && this._arrayModeOuterOpen) {
         this._err('E_UNEXPECTED_EOF', 'unclosed top-level array');
       }
-      this.sink.onEnd();
+      this._ended = true;
+      this._onEnd();
       return;
     }
     this._err('E_UNEXPECTED_EOF', 'input ended mid-token (state=' + this._state + ')');
@@ -378,7 +406,7 @@ export class Tokenizer {
 
   _handleObjectStartByte(b) {
     if (b === B_RBRACE) {
-      this.sink.onEndObject();
+      this._onEndObject();
       this._popContainer();
       return;
     }
@@ -389,7 +417,7 @@ export class Tokenizer {
   _handleObjectValueEndByte(b) {
     if (b === B_COMMA) { this._state = S_OBJECT_NEXT_KEY; }
     else if (b === B_RBRACE) {
-      this.sink.onEndObject();
+      this._onEndObject();
       this._popContainer();
     } else {
       this._err('E_UNEXPECTED_BYTE', 'expected , or }');
@@ -404,7 +432,7 @@ export class Tokenizer {
         this._state = S_TOP;
         return;
       }
-      this.sink.onEndArray();
+      this._onEndArray();
       this._popContainer();
       return;
     }
@@ -419,7 +447,7 @@ export class Tokenizer {
         this._state = S_TOP;
         return;
       }
-      this.sink.onEndArray();
+      this._onEndArray();
       this._popContainer();
     } else {
       this._err('E_UNEXPECTED_BYTE', 'expected , or ]');
@@ -430,13 +458,13 @@ export class Tokenizer {
 
   _beginValue(b) {
     if (b === B_LBRACE) {
-      this.sink.onStartObject();
+      this._onStartObject();
       this._pushContainer(C_OBJECT);
       this._state = S_OBJECT_START;
       return;
     }
     if (b === B_LBRACKET) {
-      this.sink.onStartArray();
+      this._onStartArray();
       this._pushContainer(C_ARRAY);
       this._state = S_ARRAY_START;
       return;
@@ -578,16 +606,17 @@ export class Tokenizer {
       v = this._numSign * v;
     }
     if (!Number.isFinite(v)) this._err('E_NUMBER_OVERFLOW', 'number exceeds F64 range');
-    this.sink.onNumber(v);
+    this._onNumber(v);
     this._afterValue();
   }
 
   _emitString() {
+    if (this._strLen > this._maxStringBytes) this._err('E_STRING_TOO_LONG', 'string exceeds maxStringBytes cap (' + this._strLen + ' > ' + this._maxStringBytes + ')');
     if (this._strIsKey) {
-      this.sink.onKey(this._strBuf, 0, this._strLen);
+      this._onKey(this._strBuf, 0, this._strLen);
       this._state = S_OBJECT_KEY_END;
     } else {
-      this.sink.onString(this._strBuf, 0, this._strLen);
+      this._onString(this._strBuf, 0, this._strLen);
       this._afterValue();
     }
   }
@@ -636,6 +665,7 @@ export class Tokenizer {
 
   _appendStrRange(chunk, from, to) {
     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
     // view header per call, which turns into MB-scale GC pressure across a
@@ -668,9 +698,9 @@ export class Tokenizer {
   }
 
   _growStrBuf(need) {
+    if (this._strLen + need > this._maxStringBytes) this._err('E_STRING_TOO_LONG', 'string exceeds maxStringBytes cap (' + (this._strLen + need) + ' > ' + this._maxStringBytes + ')');
     let cap = this._strBuf.length;
     while (cap < this._strLen + need) cap *= 2;
-    if (cap > this._maxStringBytes) this._err('E_UNEXPECTED_BYTE', 'string exceeds maxStringBytes cap');
     const nb = new Uint8Array(cap);
     nb.set(this._strBuf);
     this._strBuf = nb;
@@ -684,6 +714,7 @@ export class Tokenizer {
   }
 
   _err(code, msg) {
+    this._poisoned = true;
     throw new TokenizerError(code, this._absOffset, msg);
   }
 }

package/src/Writer.js

@@ -26,10 +26,31 @@
 //   W_MIXED_LANE_TYPES         - a field saw both number and string values
 //   W_LANE_MISMATCH            - post-freeze: value type doesn't match schema lane
 //   W_UNKNOWN_LANE_KIND        - explicit schema declares an unknown laneKind
+//   W_DUPLICATE_FIELD          - schema declares the same field name twice
+//   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()
+//   E_UNKNOWN_OPTION           - unknown constructor option key
+//   E_OPTION_VALUE             - constructor option value out of domain
 
 import { StringTable } from './StringTable.js';
-
-export const VERSION = '1.0.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.2.0';
+
+const U32_MAX = 4294967295;
+// Post-finalize sentinel for _recordDepth. Chosen = 2 so every post-finalize
+// sink event lands in an existing cold arm (onNumber/onString depth != 1,
+// onStartObject depth > 1) without adding a per-record compare on the hot path.
+// It is NOT a real nesting depth: onEndObject is unreachable post-finalize
+// because onStartObject throws W_FINALIZED first.
+const FINALIZED_DEPTH = 2;
+const WRITER_OPTS = {
+  schema: { t: 'obj', nullable: true },
+  targetShardBytes: { t: 'int', min: 1, max: U32_MAX },
+  sampleBytes: { t: 'int', min: 0, max: U32_MAX },
+};
+function raiseWriter(code, msg) { throw new WriterError(code, msg); }
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -157,10 +178,11 @@ class SampleBuffer {
 
 export class Writer {
   constructor(opts) {
+    checkOpts('Writer', opts, WRITER_OPTS, raiseWriter);
     opts = opts || {};
-    this._targetShardBytes = opts.targetShardBytes || DEFAULT_SHARD_BYTES;
-    this._sampleBytes = opts.sampleBytes || this._targetShardBytes;
-    this._explicitSchema = opts.schema || null;
+    this._targetShardBytes = opts.targetShardBytes !== undefined ? opts.targetShardBytes : DEFAULT_SHARD_BYTES;
+    this._sampleBytes = opts.sampleBytes !== undefined ? opts.sampleBytes : this._targetShardBytes;
+    this._explicitSchema = opts.schema !== undefined ? opts.schema : null;
 
     // Frozen schema state
     this._schema = null;                // { fields: [{name, laneKind, offsetInRow}], rowStride }
@@ -201,7 +223,10 @@ export class Writer {
 
   onStartObject() {
     this._recordDepth++;
-    if (this._recordDepth > 1) throw new WriterError('W_NESTED_UNSUPPORTED', 'nested object inside record');
+    if (this._recordDepth > 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_NESTED_UNSUPPORTED', 'nested object inside record');
+    }
     if (this._schema) {
       // clear scratch slots
       const f = this._rowValueSlotsF64, u = this._rowValueSlotsU32;
@@ -216,7 +241,8 @@ export class Writer {
   }
 
   onStartArray() {
-    if (this._recordDepth === 0) throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level array (in-record) not supported');
+    if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+    if (this._recordDepth === 0) throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level array is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
     throw new WriterError('W_NESTED_UNSUPPORTED', 'nested array inside record');
   }
 
@@ -236,7 +262,10 @@ export class Writer {
   }
 
   onNumber(v) {
-    if (this._recordDepth !== 1) return;
+    if (this._recordDepth !== 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level number is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
+    }
     if (this._schema) {
       const idx = this._currentFieldIdx;
       if (idx < 0) return;
@@ -255,7 +284,10 @@ export class Writer {
   onNull()  { this.onNumber(0); }
 
   onString(bytes, from, to) {
-    if (this._recordDepth === 0) return;
+    if (this._recordDepth !== 1) {
+      if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
+      throw new WriterError('W_TOP_LEVEL_NOT_OBJECT', 'top-level string is not an object; LBK1 schema mode stores objects only (SPEC 5.1)');
+    }
     if (this._schema) {
       const idx = this._currentFieldIdx;
       if (idx < 0) return;
@@ -333,8 +365,33 @@ export class Writer {
     this._fieldNameHashes = new Uint32Array(fields.length);
     this._fieldLaneKinds = new Uint8Array(fields.length);
     this._fieldOffsets = new Uint16Array(fields.length);
+    // Freeze-time schema validation (BS-02/BS-03): runs once per schema on both
+    // freeze paths (explicit + sample-drain funnel here), never per record.
+    const seenNames = new Map();
     for (let i = 0; i < fields.length; i++) {
-      const b = enc.encode(fields[i].name);
+      const name = fields[i].name;
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new WriterError('W_FIELD_NAME_INVALID',
+          'field name at index ' + i + ' must be a non-empty string of at most 255 UTF-8 bytes; got ' +
+          (typeof name === 'string' ? '0 bytes' : typeof name));
+      }
+      const b = enc.encode(name);
+      if (b.length > 255) {
+        throw new WriterError('W_FIELD_NAME_INVALID',
+          'field name at index ' + i + ' must be a non-empty string of at most 255 UTF-8 bytes; got ' +
+          b.length + ' bytes');
+      }
+      const first = seenNames.get(name);
+      if (first !== undefined) {
+        throw new WriterError('W_DUPLICATE_FIELD',
+          "duplicate field name '" + name + "' at index " + i + ' (first declared at index ' + first + ')');
+      }
+      seenNames.set(name, i);
+      if (fields[i].offsetInRow > 65535) {
+        throw new WriterError('W_SCHEMA_TOO_WIDE',
+          "field '" + name + "' at offset " + fields[i].offsetInRow +
+          ' exceeds the u16 offset_in_row ceiling (max 65535)');
+      }
       this._fieldNamesUtf8[i] = b;
       this._fieldNameHashes[i] = hashBytes(b, 0, b.length);
       this._fieldLaneKinds[i] = fields[i].laneKind;
@@ -526,7 +583,7 @@ export class Writer {
   }
 
   finalize() {
-    if (this._finalized) return this._container;
+    if (this._finalized) throw new WriterError('W_FINALIZED', 'writer already finalized');
     if (!this._schema) {
       if (this._sample.rowCount === 0) throw new WriterError('W_EMPTY_INPUT', 'no records to write');
       this._freezeSchemaFromSample();
@@ -536,6 +593,8 @@ export class Writer {
     if (this._shards.length === 0) throw new WriterError('W_EMPTY_INPUT', 'no records to write');
     this._container = this._assembleContainer();
     this._finalized = true;
+    // Post-finalize sentinel: route every later sink event into a cold arm.
+    this._recordDepth = FINALIZED_DEPTH;
     return this._container;
   }
 

package/src/index.js

@@ -16,6 +16,7 @@ import { StringTable } from './StringTable.js';
 import { PreserveTokenizer, PreserveTokenizerError } from './PreserveTokenizer.js';
 import { PreserveWriter, PreserveWriterError } from './PreserveWriter.js';
 import { PreserveReader, PreserveReaderError } from './PreserveReader.js';
+import { checkOpts } from './Opts.js';
 
 export {
   Tokenizer, TokenizerError,
@@ -26,10 +27,17 @@ export {
   PreserveWriter, PreserveWriterError,
   PreserveReader, PreserveReaderError,
 };
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 const encoder = new TextEncoder();
 
+const SERIALIZE_OPTS = {
+  preserve: { t: 'bool' },
+  framing: { t: 'enum', values: ['auto', 'array', 'ndjson'] },
+  writer: { t: 'obj' },
+};
+function raiseSerialize(code, msg) { throw new WriterError(code, msg); }
+
 // Serialize input data into an LBK1 container. Input may be:
 //   - Uint8Array         (raw NDJSON bytes)
 //   - string             (NDJSON text)
@@ -43,22 +51,32 @@ const encoder = new TextEncoder();
 //   writer:    writer options. Schema mode: { schema, targetShardBytes, sampleBytes }.
 //              Preserve mode: { targetShardBytes, maxRecordBytes }.
 export function serialize(input, opts) {
+  // Validate synchronously in the prologue so a typo throws before any async
+  // dispatch (R7): E_UNKNOWN_OPTION must surface as a throw, never a rejected
+  // promise, for ReadableStream / AsyncIterable inputs too.
+  checkOpts('serialize', opts, SERIALIZE_OPTS, raiseSerialize);
   opts = opts || {};
   const preserve = opts.preserve === true;
+  const framing = opts.framing !== undefined ? opts.framing : 'ndjson';
+  const writerOpts = opts.writer !== undefined ? opts.writer : {};
+  if (preserve && opts.framing !== undefined && opts.framing !== 'ndjson') {
+    throw new WriterError('E_OPTION_CONFLICT',
+      "serialize: preserve mode is NDJSON-only; remove framing:'" + opts.framing + "' or set preserve:false");
+  }
 
   if (input && typeof input.getReader === 'function') {
     return preserve
       ? _serializeReadableStreamPreserve(input, opts)
-      : _serializeReadableStream(input, opts.writer || {}, opts.framing || 'ndjson');
+      : _serializeReadableStream(input, writerOpts, framing);
   }
   if (input && typeof input[Symbol.asyncIterator] === 'function') {
     return preserve
       ? _serializeAsyncIterablePreserve(input, opts)
-      : _serializeAsyncIterable(input, opts.writer || {}, opts.framing || 'ndjson');
+      : _serializeAsyncIterable(input, writerOpts, framing);
   }
 
   if (preserve) return _serializeSyncPreserve(input, opts);
-  return _serializeSyncSchema(input, opts.writer || {}, opts.framing || 'ndjson');
+  return _serializeSyncSchema(input, writerOpts, framing);
 }
 
 function _serializeSyncSchema(input, writerOpts, framing) {
@@ -83,10 +101,10 @@ function _serializeSyncSchema(input, writerOpts, framing) {
 }
 
 function _serializeSyncPreserve(input, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   if (input instanceof Uint8Array) {
     t.feed(input);
@@ -124,10 +142,10 @@ async function _serializeReadableStream(stream, writerOpts, framing) {
 }
 
 async function _serializeReadableStreamPreserve(stream, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   const reader = stream.getReader();
   try {
@@ -154,10 +172,10 @@ async function _serializeAsyncIterable(iterable, writerOpts, framing) {
 }
 
 async function _serializeAsyncIterablePreserve(iterable, opts) {
-  const w = new PreserveWriter(opts.writer || {});
+  const w = new PreserveWriter(opts.writer !== undefined ? opts.writer : {});
   const t = new PreserveTokenizer(w, {
     framing: 'ndjson',
-    maxRecordBytes: (opts.writer && opts.writer.maxRecordBytes) || 0,
+    maxRecordBytes: (opts.writer !== undefined && opts.writer.maxRecordBytes !== undefined) ? opts.writer.maxRecordBytes : 0,
   });
   for await (const chunk of iterable) {
     if (!(chunk instanceof Uint8Array)) throw new TypeError('serialize: async iterable must yield Uint8Array');