@zakkster/lite-bake-stream 1.5.0 → 1.6.0

package/src/RangeReader.js

@@ -44,8 +44,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.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -56,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); }
 
@@ -201,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;
   }
 
@@ -209,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;
@@ -298,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() {

package/src/Reader.js

@@ -33,13 +33,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.0';
 
 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 +99,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 +114,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

@@ -36,8 +36,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.0';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -355,9 +356,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

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

package/src/Tokenizer.js

@@ -30,7 +30,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.5.0';
+export const VERSION = '1.6.0';
 
 const U32_MAX = 4294967295;
 const TOKENIZER_OPTS = {

package/src/Views.js

@@ -23,3 +23,65 @@ export function toContainerBuffer(input, label) {
   throw new TypeError(label + ': expected ArrayBuffer or Uint8Array, got ' +
     (input === null ? 'null' : typeof input));
 }
+
+// ---- streaming sink support (M6) --------------------------------------------
+//
+// A sink is any object with a synchronous write(bytes) method; the streaming
+// (layout:'stream') path additionally needs writeAt(bytes, position) for the
+// single header backpatch. MemorySink is the in-RAM reference implementation
+// that finalize() drives internally so it can return the identical container
+// buffer the classic assembler produced.
+
+// Growable in-RAM sink. write() appends; writeAt() places bytes at an absolute
+// position (growing the logical length if needed); toArrayBuffer() returns an
+// EXACT-length ArrayBuffer copy of the bytes written.
+export class MemorySink {
+  constructor(hint) {
+    const cap = (typeof hint === 'number' && hint > 0) ? hint : 64 * 1024;
+    this._buf = new Uint8Array(cap);
+    this._len = 0;
+  }
+  _ensure(need) {
+    if (need <= this._buf.length) return;
+    let cap = this._buf.length;
+    while (cap < need) cap *= 2;
+    const next = new Uint8Array(cap);
+    next.set(this._buf.subarray(0, this._len));
+    this._buf = next;
+  }
+  write(bytes) {
+    this._ensure(this._len + bytes.length);
+    this._buf.set(bytes, this._len);
+    this._len += bytes.length;
+  }
+  writeAt(bytes, position) {
+    this._ensure(position + bytes.length);
+    this._buf.set(bytes, position);
+    if (position + bytes.length > this._len) this._len = position + bytes.length;
+  }
+  toArrayBuffer() {
+    return this._buf.buffer.slice(0, this._len);
+  }
+}
+
+// Cold prologue guard for finalizeToSink (raised as W_BAD_SINK by the writer):
+// the sink must be an object with write(); layout:'stream' also needs writeAt().
+export function validateSink(sink, needsWriteAt, raise) {
+  if (sink === null || typeof sink !== 'object') {
+    raise('W_BAD_SINK', 'sink must be an object with a write(bytes) method; got ' +
+      (sink === null ? 'null' : typeof sink));
+  }
+  if (typeof sink.write !== 'function') {
+    raise('W_BAD_SINK', 'sink is missing a write(bytes) method');
+  }
+  if (needsWriteAt && typeof sink.writeAt !== 'function') {
+    raise('W_BAD_SINK', "sink is missing a writeAt(bytes, position) method required for layout:'stream'");
+  }
+}
+
+// A sink write that returns a thenable is an async sink; the contract is
+// synchronous, so the writer treats it as a malformed sink (W_BAD_SINK).
+export function isThenable(v) {
+  return v !== null && (typeof v === 'object' || typeof v === 'function') &&
+    typeof v.then === 'function';
+}