@zakkster/lite-bake-stream 1.1.0 → 1.3.0

package/src/Reader.js

@@ -10,15 +10,22 @@
 //   R_BAD_MAGIC              - header magic mismatch
 //   R_UNSUPPORTED_VERSION    - format_version > 1
 //   R_UNSUPPORTED_ENDIAN     - endian byte is neither LE nor BE
+//   R_WRONG_MODE             - preserve-mode container fed to the schema Reader
+//   R_BAD_FLAGS              - unknown header flag bits set
 //   R_BAD_FIELD_FLAGS        - a FieldDescriptor.flags is non-zero (v2+ reserved)
 //   R_UNSUPPORTED_LANE       - lane_kind is not F64 or U32
 //   R_SHARD_VERSION_TOO_NEW  - a shard's min_reader_version > this reader
-//   R_TRUNCATED              - container ends before an expected structure
-//   R_UNKNOWN_FIELD          - get() called with an unknown field name
+//   R_TRUNCATED              - a structure claims bytes past the buffer end
+//   R_RESERVED_NONZERO       - a reserved header/descriptor/shard field is non-zero
+//   R_BAD_FOOTER             - footer magic_end or footer_len is malformed
+//   R_BAD_METADATA           - metadata_off is non-zero but the zone-map segment is unparseable
+//   R_INVALID                - a structure is internally inconsistent but in-bounds
+//   R_UNKNOWN_FIELD          - get()/findShards()/shardBounds() called with an unknown field name
 
 import { StringTable } from './StringTable.js';
+import { toContainerBuffer } from './Views.js';
 
-export const VERSION = '1.1.0';
+export const VERSION = '1.3.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -29,16 +36,43 @@ const LANE_F64 = 1;
 const LANE_U32 = 3;
 const READER_VERSION = 1;
 
+function laneBytesOf(k) { return k === LANE_F64 ? 8 : (k === LANE_U32 ? 4 : 0); }
+
 export class ReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'ReaderError'; }
 }
 
+// Validate a local string table's shape BEFORE StringTable.parse casts a
+// Uint32Array over it (T-1..T-4): the offsets array must be in bounds, the
+// count/blob must fit, offsets must be non-decreasing, and the trailing
+// sentinel must equal blob_length. A lie here is otherwise a raw RangeError
+// from `new Uint32Array(buffer, off, ...)` or a silent out-of-range read.
+function validateStringTable(bytes, off, len, label) {
+  if (len < 8)
+    throw new ReaderError('R_TRUNCATED', label + ' string table shorter than its 8-byte header');
+  const dv = new DataView(bytes.buffer, bytes.byteOffset + off, len);
+  const entryCount = dv.getUint32(0, true);
+  const blobLen = dv.getUint32(4, true);
+  const offsetsBytes = (entryCount + 1) * 4;
+  if (8 + offsetsBytes + blobLen > len)
+    throw new ReaderError('R_TRUNCATED', label + ' string table claims ' + entryCount +
+      ' entries + ' + blobLen + ' blob bytes past its ' + len + '-byte extent');
+  let prev = dv.getUint32(8, true);
+  if (prev !== 0)
+    throw new ReaderError('R_INVALID', label + ' string table offsets[0] is ' + prev + ', must be 0');
+  for (let i = 1; i <= entryCount; i++) {
+    const cur = dv.getUint32(8 + i * 4, true);
+    if (cur < prev)
+      throw new ReaderError('R_INVALID', label + ' string table offsets not monotonic at index ' + i);
+    prev = cur;
+  }
+  if (prev !== blobLen)
+    throw new ReaderError('R_INVALID', label + ' string table sentinel ' + prev + ' != blob_length ' + blobLen);
+}
+
 export class Reader {
-  static fromBuffer(bufferOrArrayBuffer) {
-    const buffer = bufferOrArrayBuffer instanceof ArrayBuffer
-      ? bufferOrArrayBuffer
-      : bufferOrArrayBuffer.buffer;
-    return new Reader(buffer);
+  static fromBuffer(input) {
+    return new Reader(toContainerBuffer(input, 'Reader.fromBuffer'));
   }
 
   constructor(buffer) {
@@ -46,9 +80,10 @@ export class Reader {
     this._dv = new DataView(buffer);
     this._bytes = new Uint8Array(buffer);
     this._parseHeader();
+    this._parseFooter();
     this._parseSchema();
     this._parseShardDirectory();
-    this._parseZoneMaps();      // M7 — no-op if metadata_off is 0
+    this._parseZoneMaps();      // M7 -- no-op if metadata_off is 0
     this._buildFieldIndex();
   }
 
@@ -79,13 +114,42 @@ export class Reader {
     }
     this._flags = flags;
 
+    const reserved1 = this._dv.getUint32(36, true);
+    if (reserved1 !== 0)
+      throw new ReaderError('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));   // 0 = no metadata block; M7+ zone maps
     this._shardDirOff     = Number(this._dv.getBigUint64(24, true));
     this._shardCount      = this._dv.getUint32(32, true);
-    // 4 bytes reserved at 36
     this._totalRows       = Number(this._dv.getBigUint64(40, true));
     this._formatVersion   = version;
+
+    const len = this._buffer.byteLength;
+    if (this._schemaBlockOff < CONTAINER_HEADER_BYTES || this._schemaBlockOff >= len)
+      throw new ReaderError('R_TRUNCATED', 'schema_block_off ' + this._schemaBlockOff + ' out of range [48, ' + len + ')');
+    if (this._shardDirOff < CONTAINER_HEADER_BYTES || this._shardDirOff >= len)
+      throw new ReaderError('R_TRUNCATED', 'shard_directory_off ' + this._shardDirOff + ' out of range [48, ' + len + ')');
+    if (this._metadataOff !== 0 && (this._metadataOff < CONTAINER_HEADER_BYTES || this._metadataOff >= len))
+      throw new ReaderError('R_TRUNCATED', 'metadata_off ' + this._metadataOff + ' out of range {0} u [48, ' + len + ')');
+    if (this._shardCount * SHARD_ENTRY_BYTES > len - CONTAINER_HEADER_BYTES)
+      throw new ReaderError('R_TRUNCATED', 'shard_count ' + this._shardCount + ' exceeds the bytes available for a shard directory');
+  }
+
+  // Footer (SPEC 3.7): magic_end 'LBK1'-reversed = '1KBL' at footer_off+8,
+  // footer_len >= 16 at footer_off+12. Runs once, at construction.
+  _parseFooter() {
+    const len = this._buffer.byteLength;
+    const footerOff = len - FOOTER_BYTES;
+    const b = this._bytes;
+    if (b[footerOff + 8] !== 0x31 || b[footerOff + 9] !== 0x4B ||
+        b[footerOff + 10] !== 0x42 || b[footerOff + 11] !== 0x4C)
+      throw new ReaderError('R_BAD_FOOTER', 'footer magic_end at offset ' + (footerOff + 8) + ' is not 1KBL');
+    const footerLen = this._dv.getUint32(footerOff + 12, true);
+    if (footerLen < FOOTER_BYTES)
+      throw new ReaderError('R_BAD_FOOTER', 'footer_len ' + footerLen + ' is less than the minimum ' + FOOTER_BYTES);
+    if (footerLen > len - CONTAINER_HEADER_BYTES)
+      throw new ReaderError('R_BAD_FOOTER', 'footer_len ' + footerLen + ' exceeds the container body size');
   }
 
   _parseSchema() {
@@ -93,6 +157,7 @@ export class Reader {
     if (off + 8 > this._buffer.byteLength) throw new ReaderError('R_TRUNCATED', 'schema header truncated');
     const fieldCount  = this._dv.getUint32(off + 0, true);
     const rowStride   = this._dv.getUint32(off + 4, true);
+    if (rowStride < 1) throw new ReaderError('R_INVALID', 'schema row_stride is 0');
     const descriptorsOff = off + 8;
     const descriptorsBytes = fieldCount * FIELD_DESCRIPTOR_BYTES;
     if (descriptorsOff + descriptorsBytes + 4 > this._buffer.byteLength) {
@@ -114,11 +179,21 @@ export class Reader {
       const offsetInRow = this._dv.getUint16(descOff + 2, true);
       const laneKind    = this._bytes[descOff + 4];
       const flags       = this._bytes[descOff + 5];
+      const reserved2   = this._dv.getUint16(descOff + 6, true);
       const nameStrOff  = Number(this._dv.getBigUint64(descOff + 8, true));
+      const reserved3   = this._dv.getBigUint64(descOff + 16, true);
 
       if (flags !== 0) throw new ReaderError('R_BAD_FIELD_FLAGS', 'field ' + i + ' has non-zero flags (v2+ reserved)');
+      if (reserved2 !== 0) throw new ReaderError('R_RESERVED_NONZERO', 'field ' + i + ' reserved2 must be 0, got ' + reserved2);
+      if (reserved3 !== 0n) throw new ReaderError('R_RESERVED_NONZERO', 'field ' + i + ' reserved3 must be 0, got ' + reserved3);
       if (laneKind !== LANE_F64 && laneKind !== LANE_U32)
         throw new ReaderError('R_UNSUPPORTED_LANE', 'field ' + i + ' lane_kind=' + laneKind);
+      if (nameLen > 255) throw new ReaderError('R_INVALID', 'field ' + i + ' name_len ' + nameLen + ' exceeds 255');
+      if (offsetInRow + laneBytesOf(laneKind) > rowStride)
+        throw new ReaderError('R_INVALID', 'field ' + i + ' offset_in_row ' + offsetInRow +
+          ' + lane bytes exceeds row_stride ' + rowStride);
+      if (nameStrOff + nameLen > nameBlobLen)
+        throw new ReaderError('R_TRUNCATED', 'field ' + i + ' name range past the name blob');
 
       const nameBytes = this._bytes.subarray(nameBlobOff + nameStrOff, nameBlobOff + nameStrOff + nameLen);
       const name = decoder.decode(nameBytes);
@@ -133,22 +208,35 @@ export class Reader {
     const need = this._shardCount * SHARD_ENTRY_BYTES;
     if (off + need > this._buffer.byteLength) throw new ReaderError('R_TRUNCATED', 'shard directory truncated');
     const shards = new Array(this._shardCount);
+    const rowStride = this._schema.rowStride;
+    let rowSum = 0;
     for (let i = 0; i < this._shardCount; i++) {
       const entryOff = off + i * SHARD_ENTRY_BYTES;
       const payloadOff    = Number(this._dv.getBigUint64(entryOff + 0, true));
       const payloadLen    = this._dv.getUint32(entryOff + 8, true);
       const rowCount      = this._dv.getUint32(entryOff + 12, true);
       const minReaderVer  = this._dv.getUint16(entryOff + 16, true);
-      // 2 bytes flags at 18, 4 bytes reserved at 20
+      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));
       if (minReaderVer > READER_VERSION) {
         throw new ReaderError('R_SHARD_VERSION_TOO_NEW',
           'shard ' + i + ' requires reader version ' + minReaderVer);
       }
+      if (shardFlags !== 0) throw new ReaderError('R_RESERVED_NONZERO', 'shard ' + i + ' flags must be 0, got ' + shardFlags);
+      if (shardReserved !== 0) throw new ReaderError('R_RESERVED_NONZERO', 'shard ' + i + ' reserved must be 0, got ' + shardReserved);
+      if (payloadOff < CONTAINER_HEADER_BYTES)
+        throw new ReaderError('R_INVALID', 'shard ' + i + ' payload_off ' + payloadOff + ' overlaps the header');
       if (payloadOff + payloadLen > this._buffer.byteLength) {
         throw new ReaderError('R_TRUNCATED', 'shard ' + i + ' payload truncated');
       }
+      if (rowCount * rowStride > payloadLen)
+        throw new ReaderError('R_INVALID', 'shard ' + i + ' row_count ' + rowCount +
+          ' * row_stride ' + rowStride + ' exceeds payload_len ' + payloadLen);
+      if (localStrLen === 0 && localStrOff !== 0)
+        throw new ReaderError('R_INVALID', 'shard ' + i + ' has local_string_len 0 but local_string_off ' + localStrOff);
+      rowSum += rowCount;
       // Byte view over payload (no F64 view; row stride can be non-multiple-of-8 with U32 fields)
       const payloadBytes = new Uint8Array(this._buffer, payloadOff, payloadLen);
       const payloadDv = new DataView(this._buffer, payloadOff, payloadLen);
@@ -158,10 +246,13 @@ export class Reader {
         if (localStrOff + localStrLen > this._buffer.byteLength) {
           throw new ReaderError('R_TRUNCATED', 'shard ' + i + ' string table truncated');
         }
+        validateStringTable(this._bytes, localStrOff, localStrLen, 'shard ' + i);
         stringTable = StringTable.parse(new Uint8Array(this._buffer, localStrOff, localStrLen), 0);
       }
       shards[i] = { payloadOff, payloadLen, rowCount, payloadBytes, payloadDv, stringTable };
     }
+    if (rowSum !== this._totalRows)
+      throw new ReaderError('R_INVALID', 'shard row_count sum ' + rowSum + ' != header total_rows ' + this._totalRows);
     this._shards = shards;
   }
 
@@ -178,33 +269,38 @@ export class Reader {
   //   _zoneMapsMins/Maxes:    Float64Array  -- length shardCount * T, row-major
   _parseZoneMaps() {
     this._zoneMapsTrackedFields = null;
-    if (this._metadataOff === 0) return;
-    if (this._metadataOff + 16 > this._buffer.byteLength) return;
+    if (this._metadataOff === 0) return;   // legal absence
     const off = this._metadataOff;
-    // Check 'ZM01' magic
+    // D1: a non-zero metadata_off is a producer assertion that a parseable
+    // segment lives here. Any way it fails to parse is corruption, not absence.
+    if (off + 16 > this._buffer.byteLength)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps segment header at ' + off + ' runs past the buffer');
     if (this._bytes[off]     !== 0x30 || this._bytes[off + 1] !== 0x5A ||
-        this._bytes[off + 2] !== 0x4D || this._bytes[off + 3] !== 0x31) return;
+        this._bytes[off + 2] !== 0x4D || this._bytes[off + 3] !== 0x31)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps magic at ' + off + ' is not ZM01');
     const shardCount = this._dv.getUint32(off + 4, true);
     const T          = this._dv.getUint32(off + 8, true);
-    if (shardCount !== this._shardCount) {
-      throw new ReaderError('R_TRUNCATED', 'zone maps shard_count mismatch');
-    }
-    if (T === 0) return;
+    const reserved0  = this._dv.getUint32(off + 12, true);
+    if (shardCount !== this._shardCount)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps shard_count ' + shardCount + ' != header ' + this._shardCount);
+    if (reserved0 !== 0)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps reserved0 must be 0, got ' + reserved0);
+    if (T === 0) return;   // a well-formed segment tracking nothing: hasZoneMaps false
     const fieldTableOff = off + 16;
     const fieldTablePad = (8 - ((T * 2) & 7)) & 7;
     const minsOff = fieldTableOff + T * 2 + fieldTablePad;
     const maxesOff = minsOff + shardCount * T * 8;
     const requiredEnd = maxesOff + shardCount * T * 8;
-    if (requiredEnd > this._buffer.byteLength) {
-      throw new ReaderError('R_TRUNCATED', 'zone maps segment truncated');
-    }
+    if (requiredEnd > this._buffer.byteLength)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps segment runs past the buffer');
+    if ((minsOff & 7) !== 0)
+      throw new ReaderError('R_BAD_METADATA', 'zone maps mins offset ' + minsOff + ' is not 8-byte aligned');
     const tracked = new Array(T);
     const fieldToPos = new Map();
     for (let t = 0; t < T; t++) {
       const schemaFieldIdx = this._dv.getUint16(fieldTableOff + t * 2, true);
-      if (schemaFieldIdx >= this._schema.fields.length) {
-        throw new ReaderError('R_TRUNCATED', 'zone maps references field index ' + schemaFieldIdx);
-      }
+      if (schemaFieldIdx >= this._schema.fields.length)
+        throw new ReaderError('R_BAD_METADATA', 'zone maps references field index ' + schemaFieldIdx + ' past the schema');
       tracked[t] = schemaFieldIdx;
       fieldToPos.set(this._schema.fields[schemaFieldIdx].name, t);
     }
@@ -259,6 +355,8 @@ export class Reader {
   //   - the field is not tracked (currently: U32/string fields are never tracked in v1).
   // For empty ranges (a shard where the field defaulted to 0), returns {min:0, max:0}.
   shardBounds(shardIdx, fieldName) {
+    if (!this._fieldIndex.has(fieldName))
+      throw new ReaderError('R_UNKNOWN_FIELD', 'no field named ' + JSON.stringify(fieldName));
     if (!this._zoneMapsTrackedFields) return null;
     const t = this._zoneMapsFieldToPos.get(fieldName);
     if (t === undefined) return null;
@@ -273,6 +371,8 @@ export class Reader {
   // Semantics: a shard is INCLUDED iff its [smin, smax] overlaps [min, max].
   // A pass-through range ({min: -Inf, max: +Inf} or omitted) returns all shards.
   findShards(fieldName, opts) {
+    if (!this._fieldIndex.has(fieldName))
+      throw new ReaderError('R_UNKNOWN_FIELD', 'no field named ' + JSON.stringify(fieldName));
     const all = () => { const a = new Array(this._shardCount); for (let i = 0; i < this._shardCount; i++) a[i] = i; return a; };
     if (!this._zoneMapsTrackedFields) return all();
     const t = this._zoneMapsFieldToPos.get(fieldName);

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.1.0';
+export const VERSION = '1.3.0';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -44,10 +45,28 @@ const SHARD_ENTRY_BYTES = 40;
 const FIELD_DESCRIPTOR_BYTES = 24;
 const FOOTER_BYTES = 16;
 const LANE_F64 = 1;
+const LANE_U32 = 3;
+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 +86,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 +130,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 +147,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);
@@ -180,6 +202,16 @@ export function mergeContainers(containers) {
     }
   }
 
+  // BS-15 conformance: a merged container whose schema has no U32 lane must
+  // emit NO local string tables (local_string_off/len = 0), regardless of what
+  // the source containers carry. A pre-M2 F64-only input holds a stale 16-byte
+  // empty table; without this, merge would launder it into the output and the
+  // t8 spec-checker would reject the result. Computed once from the shared schema.
+  let mergedHasU32 = false;
+  for (let i = 0; i < schema0.fields.length; i++) {
+    if (schema0.fields[i].laneKind === LANE_U32) { mergedHasU32 = true; break; }
+  }
+
   // Total shards and rows
   let totalShards = 0, totalRows = 0;
   for (const r of readers) { totalShards += r.shardCount; totalRows += r.totalRows; }
@@ -225,7 +257,7 @@ export function mergeContainers(containers) {
       // Source shard payload lives at shard.payloadOff in the source container.
       const payloadLen = shard.payloadLen;
       const payloadPad = (8 - (payloadLen & 7)) & 7;
-      const stringLen = shard.stringTable ? _sourceStringTableLen(readers[ci], si) : 0;
+      const stringLen = (mergedHasU32 && shard.stringTable) ? _sourceStringTableLen(readers[ci], si) : 0;
       const outPayloadOff = cursor;
       const outStringOff = outPayloadOff + payloadLen + payloadPad;
       shardOutMap.push({

package/src/StringTable.js

@@ -20,7 +20,7 @@
 // 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.1.0';
+export const VERSION = '1.3.0';
 
 const EMPTY_SLOT = 0xFFFFFFFF;   // MUST be unsigned; typed-array reads are unsigned
 const INITIAL_BLOB_BYTES  = 64 * 1024;

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.1.0';
+import { checkOpts } from './Opts.js';
+
+export const VERSION = '1.3.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,12 @@ 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 or an in-flight feed(); construct a new instance');
+    if (this._ended) throw new TokenizerError('E_ENDED', this._absOffset, 'tokenizer already ended; construct a new instance');
+    // D3 armed-flag: a sink throw mid-feed unwinds through here with the flag
+    // set, poisoning the instance. Cleared on the successful fall-through below.
+    // Two boolean stores per chunk; the byte loop is untouched.
+    this._poisoned = true;
     const len = chunk.length;
     let i = 0;
     while (i < len) {
@@ -306,9 +335,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;
@@ -317,9 +346,13 @@ export class Tokenizer {
       // unreachable
       this._err('E_UNEXPECTED_BYTE', 'internal: unknown state ' + st);
     }
+    this._poisoned = false;   // D3: clean fall-through un-arms the flag
   }
 
   end() {
+    if (this._poisoned) throw new TokenizerError('E_POISONED', this._absOffset, 'tokenizer poisoned by a previous error or an in-flight feed(); construct a new instance');
+    if (this._ended) throw new TokenizerError('E_ENDED', this._absOffset, 'tokenizer already ended; construct a new instance');
+    this._poisoned = true;    // D3: armed until a clean exit below
     // A trailing number may still be pending
     if (this._state === S_NUMBER) {
       this._emitNumber();
@@ -328,7 +361,9 @@ 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();
+      this._poisoned = false;   // clear AFTER _onEnd(): a throwing onEnd stays poisoned
       return;
     }
     this._err('E_UNEXPECTED_EOF', 'input ended mid-token (state=' + this._state + ')');
@@ -378,7 +413,7 @@ export class Tokenizer {
 
   _handleObjectStartByte(b) {
     if (b === B_RBRACE) {
-      this.sink.onEndObject();
+      this._onEndObject();
       this._popContainer();
       return;
     }
@@ -389,7 +424,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 +439,7 @@ export class Tokenizer {
         this._state = S_TOP;
         return;
       }
-      this.sink.onEndArray();
+      this._onEndArray();
       this._popContainer();
       return;
     }
@@ -419,7 +454,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 +465,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 +613,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 +672,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 +705,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 +721,7 @@ export class Tokenizer {
   }
 
   _err(code, msg) {
+    this._poisoned = true;
     throw new TokenizerError(code, this._absOffset, msg);
   }
 }

package/src/Views.js

@@ -0,0 +1,25 @@
+// @zakkster/lite-bake-stream / Views (internal)
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+//
+// 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
+// full-buffer view is unwrapped in place (zero copy); a partial view (a pooled
+// Buffer with byteOffset > 0, or a subarray) is COPIED so the reader never sees
+// bytes outside the caller's window. Anything else fails closed.
+//
+// Not a public export. Internal to the package.
+
+export function toContainerBuffer(input, label) {
+  if (input instanceof ArrayBuffer) return input;
+  if (input instanceof Uint8Array) {
+    if (input.byteOffset === 0 && input.byteLength === input.buffer.byteLength) {
+      return input.buffer;
+    }
+    const copy = new Uint8Array(input.byteLength);
+    copy.set(input);
+    return copy.buffer;
+  }
+  throw new TypeError(label + ': expected ArrayBuffer or Uint8Array, got ' +
+    (input === null ? 'null' : typeof input));
+}