@zakkster/lite-bake-stream 1.4.1 → 1.6.0

package/src/PreserveWriter.js

@@ -17,8 +17,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.4.1';
+export const VERSION = '1.6.0';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }
@@ -28,6 +30,11 @@ function raisePreserveWriter(code, msg) { throw new PreserveWriterError(code, ms
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
 const FOOTER_BYTES = 16;
+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;
@@ -38,6 +45,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,16 +53,29 @@ 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();
   }
 
   _allocateShard() {
-    // Pre-allocate up to targetShardBytes for zero-GC record writes.
-    this._currentBlobs = new Uint8Array(this._targetShardBytes);
-    this._currentOffsets = new Uint32Array(INITIAL_OFFSETS_CAP);
+    // Allocate the working buffers ONCE (BS-27 floor). Every subsequent shard
+    // reuses them: _finalizeCurrentShard resets the cursors instead of nulling
+    // the buffers, so a shard roll allocates nothing. A grown buffer (oversized
+    // record) simply carries forward as a larger reusable buffer.
+    if (this._currentBlobs === null) {
+      this._currentBlobs = new Uint8Array(this._targetShardBytes);
+      this._currentOffsets = new Uint32Array(INITIAL_OFFSETS_CAP);
+    }
     this._currentBlobBytes = 0;
     this._currentRowCount = 0;
   }
@@ -74,7 +95,19 @@ export class PreserveWriter {
       this._allocateShard();
     }
     // Grow shard buffer if this single record exceeds the pre-allocated size.
+    // Fail closed (BS-31) on a BLOB-dimension crossing: this guard covers a
+    // record whose blob bytes push payload_len past the u32 ceiling (including
+    // the oversized-single-record path), and the _growBlobBuffer clamp keeps the
+    // buffer <= U32_MAX so such a write always re-enters this grow branch. The
+    // ORTHOGONAL crossing -- payload_len exceeding u32 via OFFSET-TABLE
+    // accumulation (many tiny records, blob under target, grow branch never
+    // firing) -- is caught in _finalizeCurrentShard. ST_BLOB_OVERFLOW is the
+    // shared cross-writer overflow code (R11).
     if (this._currentBlobBytes + len > this._currentBlobs.length) {
+      if (this._currentBlobBytes + len + (this._currentRowCount + 1) * 4 > U32_MAX)
+        throw new PreserveWriterError('ST_BLOB_OVERFLOW',
+          'preserve shard payload ' + (this._currentBlobBytes + len) +
+          ' bytes + offset table would exceed the u32 payload_len ceiling ' + U32_MAX);
       this._growBlobBuffer(this._currentBlobBytes + len);
     }
     // Grow offsets array if we've hit the pre-allocated ceiling.
@@ -107,6 +140,9 @@ export class PreserveWriter {
   _growBlobBuffer(needed) {
     let cap = this._currentBlobs.length;
     while (cap < needed) cap *= 2;
+    // Clamp so the buffer never exceeds the u32 payload ceiling; this makes the
+    // onRecord grow-branch guard provably complete (see onRecord).
+    if (cap > U32_MAX) cap = U32_MAX;
     const next = new Uint8Array(cap);
     next.set(this._currentBlobs.subarray(0, this._currentBlobBytes));
     this._currentBlobs = next;
@@ -124,6 +160,15 @@ export class PreserveWriter {
     const blobLen = this._currentBlobBytes;
     const offsetTableBytes = rowCount * 4;
     const shardBytesLen = blobLen + offsetTableBytes;
+    // Fail closed (BS-31, cold) on an OFFSET-TABLE-driven crossing: payload_len =
+    // blob bytes + rowCount*4 is written into the shard directory as a u32, and
+    // enough tiny records can push it past the ceiling without the onRecord grow
+    // branch ever firing. This is the door that branch cannot cover. Shared code
+    // ST_BLOB_OVERFLOW (R11).
+    if (shardBytesLen > U32_MAX)
+      throw new PreserveWriterError('ST_BLOB_OVERFLOW',
+        'preserve shard payload_len ' + shardBytesLen + ' (blob ' + blobLen + ' + offset table ' +
+        offsetTableBytes + ') exceeds the u32 ceiling ' + U32_MAX);
 
     const shardBytes = new Uint8Array(shardBytesLen);
     shardBytes.set(this._currentBlobs.subarray(0, blobLen), 0);
@@ -132,100 +177,236 @@ 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,
-    });
-    // Zero out the working buffers so a stale ref can't leak old bytes into
-    // the next shard by accident. The buffers are reused via _allocateShard.
-    this._currentBlobs = null;
-    this._currentOffsets = null;
+    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
+    // here), and the shard copy above took only subarray(0, blobLen).
     this._currentBlobBytes = 0;
     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

@@ -30,8 +30,11 @@
 // Error codes (stable, share prefix with Reader.js where semantics overlap):
 //   R_BAD_MAGIC / R_UNSUPPORTED_VERSION / R_UNSUPPORTED_ENDIAN / R_BAD_FIELD_FLAGS
 //   R_UNSUPPORTED_LANE / R_SHARD_VERSION_TOO_NEW / R_TRUNCATED / R_UNKNOWN_FIELD
-//   R_ADAPTER_SHORT_READ   -- adapter returned fewer bytes than requested
-//   R_ROW_OUT_OF_RANGE     -- rowIdx >= totalRows
+//   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_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
 //   R_BAD_FLAGS            -- unknown header flag bits set
 //   R_RESERVED_NONZERO     -- a reserved header/descriptor/shard field is non-zero
@@ -41,8 +44,9 @@
 
 import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
+import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.4.1';
+export const VERSION = '1.6.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -53,10 +57,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); }
 
@@ -65,6 +73,18 @@ export class RangeReaderError extends Error {
 }
 function raiseRange(code, msg) { throw new RangeReaderError(code, msg); }
 
+// Read a u64 field from `dv` (the header, schema, or directory view -- three
+// different DataViews here) and narrow it to a JS number, failing closed past
+// Number.MAX_SAFE_INTEGER. Past 2^53-1 a Number() cast loses precision and every
+// downstream bounds check reads a corrupted offset (BS-05). Cold: parse-only.
+function u64(dv, off, what) {
+  const v = dv.getBigUint64(off, true);
+  if (v > 9007199254740991n)
+    throw new RangeReaderError('R_OFFSET_TOO_LARGE',
+      what + ' value ' + v + ' exceeds the safe-integer ceiling 9007199254740991');
+  return Number(v);
+}
+
 // Validate a local string table's shape before StringTable.parse casts a
 // Uint32Array over it (T-1..T-4). `bytes` is the already-fetched shard slice;
 // `off` and `len` locate the table within it.
@@ -186,6 +206,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;
   }
 
@@ -194,6 +219,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;
@@ -205,7 +231,7 @@ export class RangeReader {
     }
 
     // Step 1: header (48 bytes) tells us schema + shard-dir offsets.
-    const headerBytes = await this.adapter.fetch(0, CONTAINER_HEADER_BYTES);
+    const headerBytes = await this._fetchExact(0, CONTAINER_HEADER_BYTES);
     const hdrDv = new DataView(headerBytes.buffer, headerBytes.byteOffset, headerBytes.byteLength);
     if (headerBytes[0] !== 0x4C || headerBytes[1] !== 0x42 || headerBytes[2] !== 0x4B || headerBytes[3] !== 0x31) {
       throw new RangeReaderError('R_BAD_MAGIC', 'header magic is not LBK1');
@@ -226,11 +252,11 @@ export class RangeReader {
     if (reserved1 !== 0)
       throw new RangeReaderError('R_RESERVED_NONZERO', 'header reserved1 at offset 36 must be 0, got ' + reserved1);
 
-    this._schemaBlockOff = Number(hdrDv.getBigUint64(8, true));
-    this._metadataOff    = Number(hdrDv.getBigUint64(16, true));
-    this._shardDirOff    = Number(hdrDv.getBigUint64(24, true));
+    this._schemaBlockOff = u64(hdrDv, 8, 'schema_block_off');
+    this._metadataOff    = u64(hdrDv, 16, 'metadata_off');
+    this._shardDirOff    = u64(hdrDv, 24, 'shard_directory_off');
     this._shardCount     = hdrDv.getUint32(32, true);
-    this._totalRows      = Number(hdrDv.getBigUint64(40, true));
+    this._totalRows      = u64(hdrDv, 40, 'total_rows');
 
     const size = this.adapter.size;
     if (this._schemaBlockOff < CONTAINER_HEADER_BYTES || this._schemaBlockOff >= size)
@@ -252,11 +278,11 @@ export class RangeReader {
     if (this._shardDirOff <= this._schemaBlockOff)
       throw new RangeReaderError('R_TRUNCATED', 'shard_directory_off ' + this._shardDirOff + ' not after schema_block_off ' + this._schemaBlockOff);
     const schemaBlockLen = this._shardDirOff - this._schemaBlockOff;
-    const schemaBytes = await this.adapter.fetch(this._schemaBlockOff, schemaBlockLen);
+    const schemaBytes = await this._fetchExact(this._schemaBlockOff, schemaBlockLen);
     this._parseSchema(schemaBytes);
 
     // Step 3: shard directory (fixed size = shardCount * 40).
-    const dirBytes = await this.adapter.fetch(this._shardDirOff, this._shardCount * SHARD_ENTRY_BYTES);
+    const dirBytes = await this._fetchExact(this._shardDirOff, this._shardCount * SHARD_ENTRY_BYTES);
     this._parseShardDirectory(dirBytes);
 
     // Step 4 (M7): zone maps. Fetched ONCE at open, cached. Enables query
@@ -274,7 +300,7 @@ export class RangeReader {
 
   async _loadFooter() {
     const size = this.adapter.size;
-    const footer = await this.adapter.fetch(size - CONTAINER_FOOTER_BYTES, CONTAINER_FOOTER_BYTES);
+    const footer = await this._fetchExact(size - CONTAINER_FOOTER_BYTES, CONTAINER_FOOTER_BYTES);
     if (footer[8] !== 0x31 || footer[9] !== 0x4B || footer[10] !== 0x42 || footer[11] !== 0x4C)
       throw new RangeReaderError('R_BAD_FOOTER', 'footer magic_end is not 1KBL');
     const fDv = new DataView(footer.buffer, footer.byteOffset, footer.byteLength);
@@ -283,6 +309,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() {
@@ -291,7 +331,7 @@ export class RangeReader {
     // corruption (D1), not absence.
     if (this._metadataOff + 16 > this.adapter.size)
       throw new RangeReaderError('R_BAD_METADATA', 'zone maps segment header runs past the container');
-    const hdr = await this.adapter.fetch(this._metadataOff, 16);
+    const hdr = await this._fetchExact(this._metadataOff, 16);
     if (hdr[0] !== 0x30 || hdr[1] !== 0x5A || hdr[2] !== 0x4D || hdr[3] !== 0x31)
       throw new RangeReaderError('R_BAD_METADATA', 'zone maps magic is not ZM01');
     const hdrDv = new DataView(hdr.buffer, hdr.byteOffset, hdr.byteLength);
@@ -309,7 +349,7 @@ export class RangeReader {
     const restLen = fieldTableLen + fieldTablePad + shardCount * T * 8 * 2;
     if (this._metadataOff + 16 + restLen > this.adapter.size)
       throw new RangeReaderError('R_BAD_METADATA', 'zone maps segment runs past the container');
-    const rest = await this.adapter.fetch(this._metadataOff + 16, restLen);
+    const rest = await this._fetchExact(this._metadataOff + 16, restLen);
     const restDv = new DataView(rest.buffer, rest.byteOffset, rest.byteLength);
     const tracked = new Array(T);
     const fieldToPos = new Map();
@@ -357,7 +397,10 @@ export class RangeReader {
       const laneKind    = bytes[off + 4];
       const flags       = bytes[off + 5];
       const reserved2   = dv.getUint16(off + 6, true);
-      const nameStrOff  = Number(dv.getBigUint64(off + 8, true));
+      const nameStrOff  = u64(dv, off + 8, 'field ' + i + ' name_str_off');
+      // reserved3 is BigInt-compared vs 0n below, never Number()-cast, so it
+      // needs no narrowing guard -- the reserved-must-be-zero check catches any
+      // out-of-range value (BS-05).
       const reserved3   = dv.getBigUint64(off + 16, true);
       if (flags !== 0) throw new RangeReaderError('R_BAD_FIELD_FLAGS', 'field ' + i + ' has non-zero flags');
       if (reserved2 !== 0) throw new RangeReaderError('R_RESERVED_NONZERO', 'field ' + i + ' reserved2 must be 0, got ' + reserved2);
@@ -383,14 +426,14 @@ export class RangeReader {
     let cumulativeRow = 0;
     for (let i = 0; i < this._shardCount; i++) {
       const off = i * SHARD_ENTRY_BYTES;
-      const payloadOff   = Number(dv.getBigUint64(off + 0, true));
+      const payloadOff   = u64(dv, off + 0, 'shard ' + i + ' payload_off');
       const payloadLen   = dv.getUint32(off + 8, true);
       const rowCount     = dv.getUint32(off + 12, true);
       const minReaderVer = dv.getUint16(off + 16, true);
       const shardFlags   = dv.getUint16(off + 18, true);
       const shardReserved = dv.getUint32(off + 20, true);
-      const localStrOff  = Number(dv.getBigUint64(off + 24, true));
-      const localStrLen  = Number(dv.getBigUint64(off + 32, true));
+      const localStrOff  = u64(dv, off + 24, 'shard ' + i + ' local_string_off');
+      const localStrLen  = u64(dv, off + 32, 'shard ' + i + ' local_string_len');
       if (minReaderVer > READER_VERSION)
         throw new RangeReaderError('R_SHARD_VERSION_TOO_NEW',
           'shard ' + i + ' requires reader version ' + minReaderVer);
@@ -433,7 +476,10 @@ export class RangeReader {
 
   // Locate the shard containing rowIdx via binary search.
   _findShardIndex(rowIdx) {
-    if (rowIdx < 0 || rowIdx >= this._totalRows) {
+    // BS-32: Number.isInteger rejects fractional/NaN as well as out-of-range in
+    // one guard. This ONE site covers get(), prefetchRange, syncRange's bounds
+    // walk and the syncRange view's inner get.
+    if (!Number.isInteger(rowIdx) || rowIdx < 0 || rowIdx >= this._totalRows) {
       throw new RangeReaderError('R_ROW_OUT_OF_RANGE',
         'rowIdx ' + rowIdx + ' out of range [0, ' + this._totalRows + ')');
     }
@@ -447,6 +493,21 @@ export class RangeReader {
     return -1;   // unreachable given the range check above
   }
 
+  // Every adapter read funnels through here (T7c). The IOAdapter contract says
+  // fetch() MUST return exactly byteLength bytes; a short, over-long, or
+  // non-Uint8Array return would otherwise seed a DataView over the wrong extent
+  // and decode silent garbage. Fail closed with R_ADAPTER_SHORT_READ instead.
+  async _fetchExact(byteOffset, byteLength) {
+    const buf = await this.adapter.fetch(byteOffset, byteLength);
+    if (!(buf instanceof Uint8Array) || buf.byteLength !== byteLength) {
+      throw new RangeReaderError('R_ADAPTER_SHORT_READ',
+        'adapter returned ' +
+        (buf instanceof Uint8Array ? buf.byteLength + ' bytes' : Object.prototype.toString.call(buf)) +
+        ' for a ' + byteLength + '-byte request at offset ' + byteOffset);
+    }
+    return buf;
+  }
+
   // Load a shard's payload + local string table with ONE range request.
   // They are contiguous in the container by SPEC 3.4, so a single fetch covers
   // both. Returns the cached shard record.
@@ -464,7 +525,7 @@ export class RangeReader {
       throw new RangeReaderError('R_TRUNCATED',
         'shard ' + shardIdx + ' string table not contiguous with payload');
     }
-    const combined = await this.adapter.fetch(combinedOff, combinedLen);
+    const combined = await this._fetchExact(combinedOff, combinedLen);
     const payloadBytes = combined.subarray(0, s.payloadLen);
     // DataView over the payload's underlying ArrayBuffer window.
     const payloadDv = new DataView(payloadBytes.buffer, payloadBytes.byteOffset, payloadBytes.byteLength);
@@ -532,7 +593,7 @@ export class RangeReader {
     const lastShard  = this._findShardIndex(lastRow - 1);
     for (let s = firstShard; s <= lastShard; s++) {
       if (!this._shardCache.has(s)) {
-        throw new RangeReaderError('R_TRUNCATED',
+        throw new RangeReaderError('R_NOT_PREFETCHED',
           'syncRange requires shard ' + s + ' to be prefetched (call prefetchRange first)');
       }
     }