@zakkster/lite-bake-stream 1.5.0 → 1.6.1

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.
@@ -17,8 +23,10 @@
 // container with R_WRONG_MODE.
 
 import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal, crc32cCombine } from './Crc32c.js';
+import { validateSink, isThenable } from './Views.js';
 
-export const VERSION = '1.5.0';
+export const VERSION = '1.6.1';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }
@@ -28,7 +36,12 @@ function raisePreserveWriter(code, msg) { throw new PreserveWriterError(code, ms
 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 CRC_ABSENT = 0xFFFFFFFF;
+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 INITIAL_OFFSETS_CAP = 4096;
 const U32_MAX = 4294967295;
 // maxRecordBytes is a declared, validated, deliberately-unused key here: the
@@ -38,6 +51,7 @@ const U32_MAX = 4294967295;
 const PRESERVE_WRITER_OPTS = {
   targetShardBytes: { t: 'int', min: 1, max: U32_MAX },
   maxRecordBytes: { t: 'int', min: 0, max: U32_MAX },
+  crc: { t: 'bool' },
 };
 
 export class PreserveWriter {
@@ -45,9 +59,16 @@ export class PreserveWriter {
     checkOpts('PreserveWriter', opts, PRESERVE_WRITER_OPTS, raisePreserveWriter);
     opts = opts || {};
     this._targetShardBytes = opts.targetShardBytes !== undefined ? opts.targetShardBytes : DEFAULT_TARGET_SHARD_BYTES;
+    this._crc = opts.crc === true;
     this._shards = [];
     this._totalRows = 0;
     this._finalized = false;
+    // Streaming-emission state (M6); see Writer for the model. A bound sink makes
+    // _finalizeCurrentShard emit + drop each shard, retaining only a descriptor.
+    this._sink = null;
+    this._sinkCrcOn = false;
+    this._sinkPos = 0;
+    this._sinkCrc = 0;
     this._currentBlobs = null;   // null => never allocated; _allocateShard allocates once
     this._allocateShard();
   }
@@ -162,11 +183,15 @@ export class PreserveWriter {
     for (let i = 0; i < rowCount; i++) {
       dv.setUint32(blobLen + i * 4, this._currentOffsets[i], true);
     }
-    this._shards.push({
-      bytes: shardBytes,
-      rowCount,
-      blobLen,
-    });
+    if (this._sink !== null) {
+      this._streamEmitShard(shardBytes, rowCount);
+    } else {
+      this._shards.push({
+        bytes: shardBytes,
+        rowCount,
+        blobLen,
+      });
+    }
     // Reuse the working buffers for the next shard: reset the cursors only, keep
     // the allocations (BS-27). No stale bytes can leak -- every read into these
     // buffers is bounded by _currentBlobBytes / _currentRowCount (both zeroed
@@ -175,87 +200,219 @@ export class PreserveWriter {
     this._currentRowCount = 0;
   }
 
-  finalize() {
+  _completeInput() {
     if (this._finalized) throw new PreserveWriterError('W_FINALIZED', 'writer already finalized');
     if (this._currentRowCount > 0) this._finalizeCurrentShard();
     if (this._shards.length === 0) {
-      // Emit an empty container? Or error? Match schema-mode: throw.
+      // Match schema-mode: an empty container is an error, not a silent no-op.
       throw new PreserveWriterError('W_EMPTY_INPUT', 'no records written; nothing to finalize');
     }
+  }
+
+  finalize() {
+    this._completeInput();
+    const bytes = this._buildPrefixBytes(this._crc);
     this._finalized = true;
-    return this._assembleContainer();
+    return { buffer: bytes.buffer, totalRows: this._totalRows, shardCount: this._shards.length, mode: 'preserve' };
   }
 
   get totalRows()  { return this._totalRows; }
   get shardCount() { return this._shards.length; }
 
-  _assembleContainer() {
+  // -------- container assembly (placement-free emitters) --------
+  // Preserve mode has no schema block and no zone maps: schema_block_off and
+  // metadata_off are 0. Classic prefix layout is header | directory | payloads |
+  // footer; the streaming layout (O9) is header | payloads | directory | footer.
+
+  _emitHeaderInto(dv, bytes, off, shardDirOff, shardCount, totalRows) {
+    bytes[off + 0] = 0x4C; bytes[off + 1] = 0x42; bytes[off + 2] = 0x4B; bytes[off + 3] = 0x31;   // 'LBK1'
+    dv.setUint16(off + 4, 1, true);       // format_version
+    bytes[off + 6] = 1;                   // endian LE
+    bytes[off + 7] = 0x01;                // flags: bit 0 = preserve mode
+    dv.setBigUint64(off + 8,  0n, true);  // schema_block_off = 0
+    dv.setBigUint64(off + 16, 0n, true);  // metadata_off = 0
+    dv.setBigUint64(off + 24, BigInt(shardDirOff), true);
+    dv.setUint32(off + 32, shardCount, true);
+    dv.setUint32(off + 36, 0, true);      // reserved1
+    dv.setBigUint64(off + 40, BigInt(totalRows), true);
+  }
+
+  _emitDirEntryInto(dv, entryOff, payloadOff, payloadLen, rowCount) {
+    dv.setBigUint64(entryOff + 0,  BigInt(payloadOff), true);
+    dv.setUint32(entryOff + 8,  payloadLen, true);
+    dv.setUint32(entryOff + 12, rowCount, true);
+    dv.setUint16(entryOff + 16, 1, true);   // min_reader_version
+    dv.setUint16(entryOff + 18, 0, true);   // shard flags
+    dv.setUint32(entryOff + 20, 0, true);   // reserved
+    dv.setBigUint64(entryOff + 24, 0n, true);   // no string table
+    dv.setBigUint64(entryOff + 32, 0n, true);
+  }
+
+  _emitFooterInto(dv, bytes, footerOff, crcVal) {
+    dv.setUint32(footerOff + 0, crcVal >>> 0, true);
+    dv.setUint32(footerOff + 4, 0, true);
+    bytes[footerOff + 8]  = 0x31;   // '1'
+    bytes[footerOff + 9]  = 0x4B;   // 'K'
+    bytes[footerOff + 10] = 0x42;   // 'B'
+    bytes[footerOff + 11] = 0x4C;   // 'L'
+    dv.setUint32(footerOff + 12, FOOTER_BYTES, true);
+  }
+
+  // Classic prefix layout, byte-for-byte identical to the pre-M6 assembler when
+  // crc is off; the optional CRC-32C covers [0, footer_off).
+  _buildPrefixBytes(crcOn) {
     const shardCount = this._shards.length;
     const shardDirBytes = shardCount * SHARD_ENTRY_BYTES;
-
-    // Layout: header (48) | shard directory | shard payloads | footer (16)
-    // No schema block, no zone maps in preserve mode; schema_block_off = 0.
     const shardDirOff = CONTAINER_HEADER_BYTES;
     let cursor = shardDirOff + shardDirBytes;
-    const shardPayloadOffsets = new Array(shardCount);
+    const payloadOffs = new Array(shardCount);
     for (let i = 0; i < shardCount; i++) {
-      shardPayloadOffsets[i] = cursor;
+      payloadOffs[i] = cursor;
       cursor += this._shards[i].bytes.length;
     }
+    const footerOff = cursor;
     const totalBytes = cursor + FOOTER_BYTES;
+    const buffer = new ArrayBuffer(totalBytes);
+    const dv = new DataView(buffer);
+    const bytes = new Uint8Array(buffer);
 
-    const container = new ArrayBuffer(totalBytes);
-    const dv = new DataView(container);
-    const bytes = new Uint8Array(container);
-
-    // Header
-    bytes[0] = 0x4C; bytes[1] = 0x42; bytes[2] = 0x4B; bytes[3] = 0x31;   // 'LBK1'
-    dv.setUint16(4, 1, true);            // format_version
-    bytes[6] = 1;                         // endian LE
-    bytes[7] = 0x01;                      // flags: bit 0 = preserve mode
-    dv.setBigUint64(8,  0n, true);        // schema_block_off = 0 (no schema)
-    dv.setBigUint64(16, 0n, true);        // metadata_off = 0 (no zone maps)
-    dv.setBigUint64(24, BigInt(shardDirOff), true);
-    dv.setUint32(32, shardCount, true);
-    dv.setUint32(36, 0, true);            // reserved1
-    dv.setBigUint64(40, BigInt(this._totalRows), true);
-
-    // Shard directory (40 bytes per entry, u64 payload_off, u32 payload_len,
-    // u32 row_count, u16 min_reader_version, u16 flags, u32 reserved,
-    // u64 local_string_off=0, u64 local_string_len=0)
+    this._emitHeaderInto(dv, bytes, 0, shardDirOff, shardCount, this._totalRows);
     for (let i = 0; i < shardCount; i++) {
-      const entryOff = shardDirOff + i * SHARD_ENTRY_BYTES;
       const s = this._shards[i];
-      dv.setBigUint64(entryOff + 0,  BigInt(shardPayloadOffsets[i]), true);
-      dv.setUint32(entryOff + 8,  s.bytes.length, true);
-      dv.setUint32(entryOff + 12, s.rowCount, true);
-      dv.setUint16(entryOff + 16, 1, true);   // min_reader_version
-      dv.setUint16(entryOff + 18, 0, true);   // shard flags
-      dv.setUint32(entryOff + 20, 0, true);   // reserved
-      dv.setBigUint64(entryOff + 24, 0n, true);   // no string table
-      dv.setBigUint64(entryOff + 32, 0n, true);
+      this._emitDirEntryInto(dv, shardDirOff + i * SHARD_ENTRY_BYTES, payloadOffs[i], s.bytes.length, s.rowCount);
     }
+    for (let i = 0; i < shardCount; i++) bytes.set(this._shards[i].bytes, payloadOffs[i]);
 
-    // Shard payloads
+    let crcVal = CRC_ABSENT;
+    if (crcOn) crcVal = crc32cFinal(crc32cUpdate(crc32cInit(), bytes, 0, footerOff));
+    this._emitFooterInto(dv, bytes, footerOff, crcVal);
+    return bytes;
+  }
+
+  // PUBLIC. Bind a sink and stream shards as they finalize (bounded RAM). Call
+  // before feeding, then finalizeToSink(sink, opts) writes the trailer. Calling
+  // finalizeToSink alone is BUFFERED mode (O(container) peak). opts.layout must
+  // be 'stream'; opts.crc defaults to the constructor crc.
+  beginStream(sink, opts) {
+    if (this._finalized) throw new PreserveWriterError('W_FINALIZED', 'writer already finalized');
+    if (this._sink !== null) throw new PreserveWriterError('W_FINALIZED', 'writer is already streaming to a sink');
+    if (this._shards.length > 0 || this._currentRowCount > 0)
+      throw new PreserveWriterError('W_FINALIZED', 'beginStream must be called before the first record');
+    checkOpts('PreserveWriter.beginStream', opts, FINALIZE_TO_SINK_OPTS, raisePreserveWriter);
+    opts = opts || {};
+    if (opts.layout !== undefined && opts.layout !== 'stream')
+      raisePreserveWriter('W_BAD_SINK', "beginStream requires layout:'stream'");
+    validateSink(sink, true, raisePreserveWriter);
+    this._sink = sink;
+    this._sinkCrcOn = opts.crc !== undefined ? opts.crc === true : this._crc;
+    this._sinkCrc = crc32cInit();
+    this._sinkWrite(new Uint8Array(CONTAINER_HEADER_BYTES), false);
+    this._sinkPos = CONTAINER_HEADER_BYTES;
+  }
+
+  _sinkWrite(bytes, fold) {
+    if (fold && this._sinkCrcOn) this._sinkCrc = crc32cUpdate(this._sinkCrc, bytes, 0, bytes.length);
+    let ret;
+    // A throwing sink fails the writer closed and rethrows verbatim; retry -> W_FINALIZED.
+    try { ret = this._sink.write(bytes); }
+    catch (e) { this._finalized = true; throw e; }
+    if (isThenable(ret)) { this._finalized = true; raisePreserveWriter('W_BAD_SINK', 'sink.write returned a thenable; sinks must be synchronous'); }
+  }
+
+  // Preserve payloads carry an internal offset table and are NOT 8-padded (the
+  // classic layout packs them back-to-back), so the streaming layout does the
+  // same: no inter-shard padding.
+  _streamEmitShard(shardBytes, rowCount) {
+    const payloadOff = this._sinkPos;
+    const payloadLen = shardBytes.length;
+    this._sinkWrite(shardBytes, true);
+    this._sinkPos += payloadLen;
+    this._shards.push({ rowCount, payloadOff, payloadLen });
+  }
+
+  // PUBLIC. Emit to a caller sink. Returns { totalRows, shardCount, mode,
+  // bytesWritten, layout }.
+  finalizeToSink(sink, opts) {
+    if (this._finalized) throw new PreserveWriterError('W_FINALIZED', 'writer already finalized');
+    checkOpts('PreserveWriter.finalizeToSink', opts, FINALIZE_TO_SINK_OPTS, raisePreserveWriter);
+    opts = opts || {};
+
+    if (this._sink !== null) {
+      if (sink !== this._sink) raisePreserveWriter('W_BAD_SINK', 'finalizeToSink sink differs from the streaming sink');
+      if (opts.layout !== undefined && opts.layout !== 'stream')
+        raisePreserveWriter('W_BAD_SINK', "a streaming writer must be finalized with layout:'stream'");
+      const crcOn = opts.crc !== undefined ? opts.crc === true : this._sinkCrcOn;
+      this._sinkCrcOn = crcOn;
+      this._completeInput();
+      return this._finishStream(sink, crcOn);
+    }
+
+    const layout = opts.layout !== undefined ? opts.layout : 'stream';
+    const crcOn = opts.crc !== undefined ? opts.crc === true : this._crc;
+    validateSink(sink, layout === 'stream', raisePreserveWriter);
+    this._completeInput();
+
+    if (layout === 'prefix') {
+      const bytes = this._buildPrefixBytes(crcOn);
+      let ret;
+      try { ret = sink.write(bytes); }
+      catch (e) { this._finalized = true; throw e; }
+      if (isThenable(ret)) { this._finalized = true; raisePreserveWriter('W_BAD_SINK', 'sink.write returned a thenable; sinks must be synchronous'); }
+      this._finalized = true;
+      return { totalRows: this._totalRows, shardCount: this._shards.length, mode: 'preserve', bytesWritten: bytes.length, layout: 'prefix' };
+    }
+
+    const buffered = this._shards;
+    this._shards = [];
+    this._sink = sink;
+    this._sinkCrcOn = crcOn;
+    this._sinkCrc = crc32cInit();
+    this._sinkWrite(new Uint8Array(CONTAINER_HEADER_BYTES), false);
+    this._sinkPos = CONTAINER_HEADER_BYTES;
+    for (let i = 0; i < buffered.length; i++) {
+      this._streamEmitShard(buffered[i].bytes, buffered[i].rowCount);
+      buffered[i] = null;
+    }
+    return this._finishStream(sink, crcOn);
+  }
+
+  _finishStream(sink, crcOn) {
+    const shardCount = this._shards.length;
+    const shardDirBytes = shardCount * SHARD_ENTRY_BYTES;
+    const shardDirOff = this._sinkPos;   // directory follows the payloads (O9)
+    const footerOff = shardDirOff + shardDirBytes;
+
+    const dir = new Uint8Array(shardDirBytes);
+    const ddv = new DataView(dir.buffer);
     for (let i = 0; i < shardCount; i++) {
-      bytes.set(this._shards[i].bytes, shardPayloadOffsets[i]);
+      const d = this._shards[i];
+      this._emitDirEntryInto(ddv, i * SHARD_ENTRY_BYTES, d.payloadOff, d.payloadLen, d.rowCount);
     }
+    this._sinkWrite(dir, true);
+    this._sinkPos += shardDirBytes;
 
-    // Footer
-    const footerOff = totalBytes - FOOTER_BYTES;
-    dv.setUint32(footerOff + 0, 0xFFFFFFFF, true);   // CRC absent
-    dv.setUint32(footerOff + 4, 0, true);
-    bytes[footerOff + 8]  = 0x31;   // '1'
-    bytes[footerOff + 9]  = 0x4B;   // 'K'
-    bytes[footerOff + 10] = 0x42;   // 'B'
-    bytes[footerOff + 11] = 0x4C;   // 'L'
-    dv.setUint32(footerOff + 12, FOOTER_BYTES, true);
+    const header = new Uint8Array(CONTAINER_HEADER_BYTES);
+    const hdv = new DataView(header.buffer);
+    this._emitHeaderInto(hdv, header, 0, shardDirOff, shardCount, this._totalRows);
 
-    return {
-      buffer: container,
-      totalRows: this._totalRows,
-      shardCount,
-      mode: 'preserve',
-    };
+    let crcVal = CRC_ABSENT;
+    if (crcOn) {
+      const headerCrc = crc32cFinal(crc32cUpdate(crc32cInit(), header, 0, CONTAINER_HEADER_BYTES));
+      const suffixCrc = crc32cFinal(this._sinkCrc);
+      crcVal = crc32cCombine(headerCrc, suffixCrc, footerOff - CONTAINER_HEADER_BYTES);
+    }
+    const footer = new Uint8Array(FOOTER_BYTES);
+    const fdv = new DataView(footer.buffer);
+    this._emitFooterInto(fdv, footer, 0, crcVal);
+    this._sinkWrite(footer, false);
+    this._sinkPos += FOOTER_BYTES;
+
+    let ret;
+    try { ret = sink.writeAt(header, 0); }
+    catch (e) { this._finalized = true; throw e; }
+    if (isThenable(ret)) { this._finalized = true; raisePreserveWriter('W_BAD_SINK', 'sink.writeAt returned a thenable; sinks must be synchronous'); }
+
+    this._finalized = true;
+    return { totalRows: this._totalRows, shardCount, mode: 'preserve', bytesWritten: this._sinkPos, layout: 'stream' };
   }
 }

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
@@ -44,8 +46,9 @@
 
 import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.5.0';
+export const VERSION = '1.6.1';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -56,10 +59,14 @@ 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 RANGE_READER_OPTS = {
+  maxCachedShards: { t: 'int', min: 0, max: U32_MAX },
+  verifyCrc: { t: 'bool' },
+};
 const HTTP_ADAPTER_OPTS = { fetch: { t: 'fn' } };
 
 const CONTAINER_FOOTER_BYTES = 16;
+const CRC_ABSENT = 0xFFFFFFFF;
 
 function laneBytesOf(k) { return k === LANE_F64 ? 8 : (k === LANE_U32 ? 4 : 0); }
 
@@ -201,6 +208,11 @@ export class RangeReader {
   static async open(adapter, opts) {
     const r = new RangeReader(adapter, opts);
     await r._loadHeaderAndSchema();
+    if (opts && opts.verifyCrc === true) {
+      const status = await r.verifyCrc();
+      if (status === 'absent')
+        throw new RangeReaderError('R_CRC_ABSENT', 'verifyCrc:true but the container carries no CRC (footer CRC is absent, 0xFFFFFFFF)');
+    }
     return r;
   }
 
@@ -209,6 +221,7 @@ export class RangeReader {
     opts = opts || {};
     this.adapter = adapter;
     this.maxCachedShards = opts.maxCachedShards !== undefined ? opts.maxCachedShards : 8;
+    this._footerCrc = CRC_ABSENT;
     // shard cache: shardIdx -> { payloadBytes, payloadDv, stringTable, lastAccess }
     this._shardCache = new Map();
     this._accessCounter = 0;
@@ -298,6 +311,20 @@ export class RangeReader {
       throw new RangeReaderError('R_BAD_FOOTER', 'footer_len ' + footerLen + ' is less than the minimum ' + CONTAINER_FOOTER_BYTES);
     if (footerLen > size - CONTAINER_HEADER_BYTES)
       throw new RangeReaderError('R_BAD_FOOTER', 'footer_len ' + footerLen + ' exceeds the container body size');
+    this._footerCrc = fDv.getUint32(0, true) >>> 0;
+  }
+
+  // SPEC 3.7 integrity over a ranged source: 'ok' | 'absent'; a mismatch throws
+  // R_BAD_CRC. Fetches the body [0, footer_off) in one range (a full-integrity
+  // check is inherently whole-body). The footer CRC was captured at open.
+  async verifyCrc() {
+    if (this._footerCrc === CRC_ABSENT) return 'absent';
+    const footerOff = this.adapter.size - CONTAINER_FOOTER_BYTES;
+    const body = await this._fetchExact(0, footerOff);
+    const actual = crc32cFinal(crc32cUpdate(crc32cInit(), body, 0, footerOff));
+    if (actual !== this._footerCrc)
+      throw new RangeReaderError('R_BAD_CRC', 'container CRC mismatch: stored 0x' + this._footerCrc.toString(16) + ' != computed 0x' + actual.toString(16));
+    return 'ok';
   }
 
   async _loadZoneMaps() {

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
@@ -33,13 +35,19 @@
 
 import { StringTable } from './StringTable.js';
 import { toContainerBuffer } from './Views.js';
+import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.5.0';
+export const VERSION = '1.6.1';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
 const FIELD_DESCRIPTOR_BYTES = 24;
 const FOOTER_BYTES = 16;
+const CRC_ABSENT = 0xFFFFFFFF;
+
+const READER_OPTS = { verifyCrc: { t: 'bool' } };
+function raiseReaderOpt(code, msg) { throw new ReaderError(code, msg); }
 
 const LANE_F64 = 1;
 const LANE_U32 = 3;
@@ -93,11 +101,12 @@ function validateStringTable(bytes, off, len, label) {
 }
 
 export class Reader {
-  static fromBuffer(input) {
-    return new Reader(toContainerBuffer(input, 'Reader.fromBuffer'));
+  static fromBuffer(input, opts) {
+    return new Reader(toContainerBuffer(input, 'Reader.fromBuffer'), opts);
   }
 
-  constructor(buffer) {
+  constructor(buffer, opts) {
+    checkOpts('Reader', opts, READER_OPTS, raiseReaderOpt);
     this._buffer = buffer;
     this._dv = new DataView(buffer);
     this._bytes = new Uint8Array(buffer);
@@ -107,6 +116,27 @@ export class Reader {
     this._parseShardDirectory();
     this._parseZoneMaps();      // M7 -- no-op if metadata_off is 0
     this._buildFieldIndex();
+    // Optional open-time verification (fail closed on BOTH mismatch AND absence:
+    // the caller demanded verification, so an unverifiable container is an
+    // unverified state -- null is not zero).
+    if (opts && opts.verifyCrc === true) {
+      const status = this.verifyCrc();
+      if (status === 'absent')
+        throw new ReaderError('R_CRC_ABSENT', 'verifyCrc:true but the container carries no CRC (footer CRC is absent, 0xFFFFFFFF)');
+    }
+  }
+
+  // SPEC 3.7 integrity: recompute CRC-32C over [0, footer_off) and compare to the
+  // stored footer CRC. Returns 'ok' when they match, 'absent' when the container
+  // carries no CRC (footer CRC == 0xFFFFFFFF). A MISMATCH throws R_BAD_CRC.
+  verifyCrc() {
+    const footerOff = this._buffer.byteLength - FOOTER_BYTES;
+    const stored = this._dv.getUint32(footerOff, true) >>> 0;
+    if (stored === CRC_ABSENT) return 'absent';
+    const actual = crc32cFinal(crc32cUpdate(crc32cInit(), this._bytes, 0, footerOff));
+    if (actual !== stored)
+      throw new ReaderError('R_BAD_CRC', 'container CRC mismatch: stored 0x' + stored.toString(16) + ' != computed 0x' + actual.toString(16));
+    return 'ok';
   }
 
   _parseHeader() {

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:
 //
@@ -36,8 +40,9 @@ import { Writer, WriterError } from './Writer.js';
 import { Reader, ReaderError } from './Reader.js';
 import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.5.0';
+export const VERSION = '1.6.1';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -142,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) {
@@ -236,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;
@@ -320,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);
@@ -355,9 +360,20 @@ export function mergeContainers(containers) {
     }
   }
 
-  // Footer
+  // Footer. CRC policy (D4): recompute a fresh CRC-32C over the merged body iff
+  // EVERY input carried one; if any input's CRC is absent the merged CRC is
+  // absent too (an integrity guarantee only the inputs all shared can be
+  // honestly re-asserted -- never fabricated over an unverified part).
   const footerOff = totalBytes - FOOTER_BYTES;
-  outDv.setUint32(footerOff + 0, 0xFFFFFFFF, true);   // CRC absent
+  let mergedCrc = 0xFFFFFFFF;
+  let allHaveCrc = true;
+  for (const p of parts) {
+    const pDv = new DataView(p.buffer, p.byteOffset, p.byteLength);
+    const pCrc = pDv.getUint32(p.byteLength - FOOTER_BYTES, true) >>> 0;
+    if (pCrc === 0xFFFFFFFF) { allHaveCrc = false; break; }
+  }
+  if (allHaveCrc) mergedCrc = crc32cFinal(crc32cUpdate(crc32cInit(), out, 0, footerOff));
+  outDv.setUint32(footerOff + 0, mergedCrc >>> 0, true);
   outDv.setUint32(footerOff + 4, 0, true);
   out[footerOff + 8]  = 0x31;
   out[footerOff + 9]  = 0x4B;

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