@zakkster/lite-bake-stream 1.1.0 → 1.3.0

package/src/PreserveTokenizer.js

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

package/src/PreserveWriter.js

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

package/src/RangeReader.js

@@ -9,9 +9,9 @@
 // table offsets exist precisely so a client can fetch only what it needs.
 //
 // RangeReader implements that story:
-//   1. On open, fetch the header (32 bytes) + schema block + shard directory.
-//      That gives us the whole schema and every shard's byte extents without
-//      touching a single row.
+//   1. On open, fetch the header (48 bytes) + footer + schema block + shard
+//      directory. That gives us the whole schema and every shard's byte extents
+//      without touching a single row.
 //   2. On get(rowIdx, fieldName), locate the shard containing rowIdx, fetch
 //      its payload + local string table in ONE range request (they are
 //      contiguous by SPEC 3.4), cache it, decode.
@@ -32,10 +32,17 @@
 //   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_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
+//   R_BAD_FOOTER           -- footer magic_end or footer_len is malformed
+//   R_BAD_METADATA         -- metadata_off non-zero but the zone-map segment is unparseable
+//   R_INVALID              -- a structure is internally inconsistent but in-bounds
 
 import { StringTable } from './StringTable.js';
+import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.1.0';
+export const VERSION = '1.3.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -44,10 +51,44 @@ const FIELD_DESCRIPTOR_BYTES = 24;
 const LANE_F64 = 1;
 const LANE_U32 = 3;
 const READER_VERSION = 1;
+const U32_MAX = 4294967295;
+
+const RANGE_READER_OPTS = { maxCachedShards: { t: 'int', min: 0, max: U32_MAX } };
+const HTTP_ADAPTER_OPTS = { fetch: { t: 'fn' } };
+
+const CONTAINER_FOOTER_BYTES = 16;
+
+function laneBytesOf(k) { return k === LANE_F64 ? 8 : (k === LANE_U32 ? 4 : 0); }
 
 export class RangeReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'RangeReaderError'; }
 }
+function raiseRange(code, msg) { throw new RangeReaderError(code, msg); }
+
+// 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.
+function validateStringTable(bytes, off, len, label) {
+  if (len < 8)
+    throw new RangeReaderError('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);
+  if (8 + (entryCount + 1) * 4 + blobLen > len)
+    throw new RangeReaderError('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 RangeReaderError('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 RangeReaderError('R_INVALID', label + ' string table offsets not monotonic at index ' + i);
+    prev = cur;
+  }
+  if (prev !== blobLen)
+    throw new RangeReaderError('R_INVALID', label + ' string table sentinel ' + prev + ' != blob_length ' + blobLen);
+}
 
 // ----- Adapters --------------------------------------------------------------
 
@@ -56,8 +97,9 @@ export class RangeReaderError extends Error {
 // origin/CDN).
 export class HTTPRangeAdapter {
   static async open(url, opts) {
+    checkOpts('HTTPRangeAdapter', opts, HTTP_ADAPTER_OPTS, raiseRange);
     opts = opts || {};
-    const fetchImpl = opts.fetch || globalThis.fetch;
+    const fetchImpl = opts.fetch !== undefined ? opts.fetch : globalThis.fetch;
     if (typeof fetchImpl !== 'function') {
       throw new RangeReaderError('R_TRUNCATED', 'no fetch() available in this environment');
     }
@@ -148,9 +190,10 @@ export class RangeReader {
   }
 
   constructor(adapter, opts) {
+    checkOpts('RangeReader', opts, RANGE_READER_OPTS, raiseRange);
     opts = opts || {};
     this.adapter = adapter;
-    this.maxCachedShards = opts.maxCachedShards || 8;
+    this.maxCachedShards = opts.maxCachedShards !== undefined ? opts.maxCachedShards : 8;
     // shard cache: shardIdx -> { payloadBytes, payloadDv, stringTable, lastAccess }
     this._shardCache = new Map();
     this._accessCounter = 0;
@@ -161,7 +204,7 @@ export class RangeReader {
       throw new RangeReaderError('R_TRUNCATED', 'adapter size smaller than header');
     }
 
-    // Step 1: header (32 bytes) tells us schema + shard-dir offsets.
+    // Step 1: header (48 bytes) tells us schema + shard-dir offsets.
     const headerBytes = await this.adapter.fetch(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) {
@@ -171,21 +214,48 @@ export class RangeReader {
     if (version > 1) throw new RangeReaderError('R_UNSUPPORTED_VERSION', 'format_version=' + version);
     const endian = headerBytes[6];
     if (endian !== 1) throw new RangeReaderError('R_UNSUPPORTED_ENDIAN', 'BE payloads not implemented in v1 reader');
+    const flags = headerBytes[7];
+    if (flags & 0x01) {
+      throw new RangeReaderError('R_WRONG_MODE',
+        'container is preserve-mode; RangeReader is unsupported in preserve mode (SPEC 3.8) -- use PreserveReader');
+    }
+    if (flags & ~0x01) {
+      throw new RangeReaderError('R_BAD_FLAGS', 'unknown flag bits set in header byte 7: 0x' + flags.toString(16));
+    }
+    const reserved1 = hdrDv.getUint32(36, true);
+    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._shardCount     = hdrDv.getUint32(32, true);
-    // 4 bytes reserved at 36
     this._totalRows      = Number(hdrDv.getBigUint64(40, true));
 
+    const size = this.adapter.size;
+    if (this._schemaBlockOff < CONTAINER_HEADER_BYTES || this._schemaBlockOff >= size)
+      throw new RangeReaderError('R_TRUNCATED', 'schema_block_off ' + this._schemaBlockOff + ' out of range [48, ' + size + ')');
+    if (this._shardDirOff < CONTAINER_HEADER_BYTES || this._shardDirOff >= size)
+      throw new RangeReaderError('R_TRUNCATED', 'shard_directory_off ' + this._shardDirOff + ' out of range [48, ' + size + ')');
+    if (this._metadataOff !== 0 && (this._metadataOff < CONTAINER_HEADER_BYTES || this._metadataOff >= size))
+      throw new RangeReaderError('R_TRUNCATED', 'metadata_off ' + this._metadataOff + ' out of range {0} u [48, ' + size + ')');
+    if (this._shardCount * SHARD_ENTRY_BYTES > size - CONTAINER_HEADER_BYTES)
+      throw new RangeReaderError('R_TRUNCATED', 'shard_count ' + this._shardCount + ' exceeds the bytes available for a shard directory');
+
+    // Footer: one 16-byte suffix fetch. Refuse a wrong-footer container before
+    // spending fetches on the schema. Gated on a body big enough to hold a
+    // header and a footer that do not overlap.
+    if (size >= CONTAINER_HEADER_BYTES + CONTAINER_FOOTER_BYTES) await this._loadFooter();
+
     // Step 2: schema block. We know its start but not its length; compute
     // upper bound: schemaBlockOff .. shardDirOff.
+    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);
     this._parseSchema(schemaBytes);
 
-    // Step 3: shard directory (fixed size = shardCount * 32).
+    // Step 3: shard directory (fixed size = shardCount * 40).
     const dirBytes = await this.adapter.fetch(this._shardDirOff, this._shardCount * SHARD_ENTRY_BYTES);
     this._parseShardDirectory(dirBytes);
 
@@ -202,21 +272,43 @@ export class RangeReader {
     }
   }
 
+  async _loadFooter() {
+    const size = this.adapter.size;
+    const footer = await this.adapter.fetch(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);
+    const footerLen = fDv.getUint32(12, true);
+    if (footerLen < CONTAINER_FOOTER_BYTES)
+      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');
+  }
+
   async _loadZoneMaps() {
-    // Fetch the segment header first (16 bytes) so we can size the rest.
+    // Fetch the segment header first (16 bytes) so we can size the rest. A
+    // non-zero metadata_off asserts a parseable segment; any failure is
+    // 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);
-    if (hdr[0] !== 0x30 || hdr[1] !== 0x5A || hdr[2] !== 0x4D || hdr[3] !== 0x31) return;
+    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);
     const shardCount = hdrDv.getUint32(4, true);
     const T          = hdrDv.getUint32(8, true);
-    if (shardCount !== this._shardCount) {
-      throw new RangeReaderError('R_TRUNCATED', 'zone maps shard_count mismatch');
-    }
+    const reserved0  = hdrDv.getUint32(12, true);
+    if (shardCount !== this._shardCount)
+      throw new RangeReaderError('R_BAD_METADATA', 'zone maps shard_count ' + shardCount + ' != header ' + this._shardCount);
+    if (reserved0 !== 0)
+      throw new RangeReaderError('R_BAD_METADATA', 'zone maps reserved0 must be 0, got ' + reserved0);
     if (T === 0) return;
     // Fetch the rest in one range: field table + pad + mins + maxes.
     const fieldTableLen = T * 2;
     const fieldTablePad = (8 - (fieldTableLen & 7)) & 7;
     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 restDv = new DataView(rest.buffer, rest.byteOffset, rest.byteLength);
     const tracked = new Array(T);
@@ -224,7 +316,7 @@ export class RangeReader {
     for (let t = 0; t < T; t++) {
       const schemaFieldIdx = restDv.getUint16(t * 2, true);
       if (schemaFieldIdx >= this._schema.fields.length) {
-        throw new RangeReaderError('R_TRUNCATED', 'zone maps references field index ' + schemaFieldIdx);
+        throw new RangeReaderError('R_BAD_METADATA', 'zone maps references field index ' + schemaFieldIdx + ' past the schema');
       }
       tracked[t] = schemaFieldIdx;
       fieldToPos.set(this._schema.fields[schemaFieldIdx].name, t);
@@ -242,13 +334,20 @@ export class RangeReader {
 
   _parseSchema(bytes) {
     const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const total = bytes.byteLength;
+    if (total < 8) throw new RangeReaderError('R_TRUNCATED', 'schema block shorter than its 8-byte header');
     const fieldCount = dv.getUint32(0, true);
     const rowStride  = dv.getUint32(4, true);
+    if (rowStride < 1) throw new RangeReaderError('R_INVALID', 'schema row_stride is 0');
     const descOff = 8;
     const descBytes = fieldCount * FIELD_DESCRIPTOR_BYTES;
+    if (descOff + descBytes + 4 > total)
+      throw new RangeReaderError('R_TRUNCATED', 'schema descriptors run past the fetched schema block');
     const nameBlobLenOff = descOff + descBytes;
     const nameBlobLen = dv.getUint32(nameBlobLenOff, true);
     const nameBlobOff = nameBlobLenOff + 4;
+    if (nameBlobOff + nameBlobLen > total)
+      throw new RangeReaderError('R_TRUNCATED', 'schema name blob runs past the fetched schema block');
     const decoder = new TextDecoder('utf-8');
     const fields = new Array(fieldCount);
     for (let i = 0; i < fieldCount; i++) {
@@ -257,10 +356,19 @@ export class RangeReader {
       const offsetInRow = dv.getUint16(off + 2, true);
       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 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);
+      if (reserved3 !== 0n) throw new RangeReaderError('R_RESERVED_NONZERO', 'field ' + i + ' reserved3 must be 0, got ' + reserved3);
       if (laneKind !== LANE_F64 && laneKind !== LANE_U32)
         throw new RangeReaderError('R_UNSUPPORTED_LANE', 'field ' + i + ' lane_kind=' + laneKind);
+      if (nameLen > 255) throw new RangeReaderError('R_INVALID', 'field ' + i + ' name_len ' + nameLen + ' exceeds 255');
+      if (offsetInRow + laneBytesOf(laneKind) > rowStride)
+        throw new RangeReaderError('R_INVALID', 'field ' + i + ' offset_in_row ' + offsetInRow + ' + lane bytes exceeds row_stride ' + rowStride);
+      if (nameStrOff + nameLen > nameBlobLen)
+        throw new RangeReaderError('R_TRUNCATED', 'field ' + i + ' name range past the name blob');
       const nb = bytes.subarray(nameBlobOff + nameStrOff, nameBlobOff + nameStrOff + nameLen);
       fields[i] = { name: decoder.decode(nb), laneKind, offsetInRow };
     }
@@ -270,6 +378,8 @@ export class RangeReader {
   _parseShardDirectory(bytes) {
     const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const shards = new Array(this._shardCount);
+    const size = this.adapter.size;
+    const rowStride = this._schema.rowStride;
     let cumulativeRow = 0;
     for (let i = 0; i < this._shardCount; i++) {
       const off = i * SHARD_ENTRY_BYTES;
@@ -277,12 +387,25 @@ export class RangeReader {
       const payloadLen   = dv.getUint32(off + 8, true);
       const rowCount     = dv.getUint32(off + 12, true);
       const minReaderVer = dv.getUint16(off + 16, true);
-      // 2 bytes flags at 18, 4 bytes reserved at 20
+      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));
       if (minReaderVer > READER_VERSION)
         throw new RangeReaderError('R_SHARD_VERSION_TOO_NEW',
           'shard ' + i + ' requires reader version ' + minReaderVer);
+      if (shardFlags !== 0) throw new RangeReaderError('R_RESERVED_NONZERO', 'shard ' + i + ' flags must be 0, got ' + shardFlags);
+      if (shardReserved !== 0) throw new RangeReaderError('R_RESERVED_NONZERO', 'shard ' + i + ' reserved must be 0, got ' + shardReserved);
+      if (payloadOff < CONTAINER_HEADER_BYTES)
+        throw new RangeReaderError('R_INVALID', 'shard ' + i + ' payload_off ' + payloadOff + ' overlaps the header');
+      if (payloadOff + payloadLen > size)
+        throw new RangeReaderError('R_TRUNCATED', 'shard ' + i + ' payload past the container size ' + size);
+      if (rowCount * rowStride > payloadLen)
+        throw new RangeReaderError('R_INVALID', 'shard ' + i + ' row_count ' + rowCount + ' * row_stride ' + rowStride + ' exceeds payload_len ' + payloadLen);
+      if (localStrLen === 0 && localStrOff !== 0)
+        throw new RangeReaderError('R_INVALID', 'shard ' + i + ' has local_string_len 0 but local_string_off ' + localStrOff);
+      if (localStrLen > 0 && localStrOff + localStrLen > size)
+        throw new RangeReaderError('R_TRUNCATED', 'shard ' + i + ' string table past the container size ' + size);
       shards[i] = {
         payloadOff, payloadLen, rowCount, localStrOff, localStrLen,
         firstRow: cumulativeRow,
@@ -290,6 +413,8 @@ export class RangeReader {
       };
       cumulativeRow += rowCount;
     }
+    if (cumulativeRow !== this._totalRows)
+      throw new RangeReaderError('R_INVALID', 'shard row_count sum ' + cumulativeRow + ' != header total_rows ' + this._totalRows);
     this._shards = shards;
   }
 
@@ -346,6 +471,7 @@ export class RangeReader {
     let stringTable = null;
     if (s.localStrLen > 0) {
       const stBytes = combined.subarray(s.payloadLen, s.payloadLen + s.localStrLen);
+      validateStringTable(stBytes, 0, s.localStrLen, 'shard ' + shardIdx);
       stringTable = StringTable.parse(stBytes, 0);
     }
     const record = {
@@ -440,6 +566,8 @@ export class RangeReader {
   // the container has no zone maps or the field is not tracked. Synchronous
   // -- zone maps were fetched during open().
   shardBounds(shardIdx, fieldName) {
+    if (!this._fieldIndex.has(fieldName))
+      throw new RangeReaderError('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;
@@ -452,6 +580,8 @@ export class RangeReader {
   // When no zone maps are present or the field is not tracked, returns every
   // shard (query planner must fall back to full scan).
   findShards(fieldName, opts) {
+    if (!this._fieldIndex.has(fieldName))
+      throw new RangeReaderError('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);