@zakkster/lite-bake-stream 1.0.0

package/src/Split.js

@@ -0,0 +1,359 @@
+// @zakkster/lite-bake-stream / Split (M6)
+// Splitters + per-part compilation + container merge for parallel/checkpointed ingest.
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+//
+// M6 covers three primitives that together enable worker-parallel or checkpoint-
+// resumable ingest against LBK1:
+//
+//   splitNDJSON(bytes, opts)      -> [{start, end}, ...]
+//     Divide input into N byte ranges that each contain complete NDJSON records.
+//
+//   compilePart(bytes, opts)       -> Uint8Array
+//     Compile ONE byte range into a standalone LBK1 container. Trivially
+//     Transferable across worker boundaries via postMessage(buf, [buf]).
+//
+//   compileInParts(bytes, opts)    -> Uint8Array[]
+//     Sequential convenience: split + compile each part. Same output shape as
+//     running each part through a worker; deterministic and easy to test.
+//     Skip this when you have workers; use it as a fallback when you don't.
+//
+//   mergeContainers([bytes, ...])  -> Uint8Array
+//     Concatenate N LBK1 containers into ONE. All must share the same schema.
+//     Preserves per-shard string tables and zone maps verbatim; rewrites the
+//     shard directory and header offsets. For query workloads over multiple
+//     parts, prefer MultiReader (M4) which avoids the copy; use mergeContainers
+//     when you need a single-file distributable.
+//
+// The "parallelism-safe" contract: every part MUST use the SAME explicit
+// schema. Two workers running sample-and-infer independently could infer
+// different field sets or lane kinds, and their outputs would then fail to
+// merge. To use sample-and-infer with parts, compile part 0 first, extract
+// its schema via `new Reader(container.buffer).schema`, and pass that as the
+// explicit schema for parts 1..N.
+
+import { Tokenizer, TokenizerError } from './Tokenizer.js';
+import { Writer, WriterError } from './Writer.js';
+import { Reader, ReaderError } from './Reader.js';
+import { StringTable } from './StringTable.js';
+
+export const VERSION = '1.0.0';
+
+const LF = 0x0A;
+const CONTAINER_HEADER_BYTES = 48;
+const SHARD_ENTRY_BYTES = 40;
+const FIELD_DESCRIPTOR_BYTES = 24;
+const FOOTER_BYTES = 16;
+const LANE_F64 = 1;
+
+export class SplitError extends Error {
+  constructor(code, msg) { super(msg); this.code = code; this.name = 'SplitError'; }
+}
+
+// ---------- splitNDJSON ----------
+
+// Divide NDJSON bytes into N ranges, each ending at (and including) a newline.
+// Guarantees:
+//   - Every returned {start, end} covers complete records (no split mid-line).
+//   - Union of ranges = original bytes (no gaps, no overlaps).
+//   - Concatenating bytes.subarray(start, end) across parts reproduces the
+//     original byte-for-byte.
+// Options:
+//   targetParts:    desired part count (default 4). Actual count may be less
+//                   if the input is too small or has too few newlines.
+//   maxPartBytes:   optional cap on part size. If set, splitter emits enough
+//                   parts to keep each under this ceiling.
+export function splitNDJSON(bytes, opts) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('splitNDJSON: expected Uint8Array');
+  }
+  opts = opts || {};
+  const targetParts = Math.max(1, opts.targetParts || 4);
+  const maxPartBytes = opts.maxPartBytes || Infinity;
+  const total = bytes.length;
+  if (total === 0) return [];
+
+  // Compute effective number of parts: honor targetParts, then bump up if
+  // any part would exceed maxPartBytes.
+  let parts = targetParts;
+  if (Number.isFinite(maxPartBytes)) {
+    const minPartsByCap = Math.ceil(total / maxPartBytes);
+    if (minPartsByCap > parts) parts = minPartsByCap;
+  }
+
+  const ranges = [];
+  let cursor = 0;
+  for (let i = 1; i < parts; i++) {
+    // Target boundary at even split; slide forward to the NEXT newline so we
+    // don't cut a record. If no newline exists between cursor and end, this
+    // part absorbs the remainder and we stop.
+    const target = Math.floor((total * i) / parts);
+    if (target <= cursor) continue;   // parts overlap in tiny inputs; skip
+    let boundary = target;
+    while (boundary < total && bytes[boundary] !== LF) boundary++;
+    if (boundary >= total) break;
+    boundary++;   // include the newline in this part
+    ranges.push({ start: cursor, end: boundary });
+    cursor = boundary;
+  }
+  // Last part absorbs everything left.
+  if (cursor < total) ranges.push({ start: cursor, end: total });
+  return ranges;
+}
+
+// ---------- compilePart ----------
+
+// Compile one byte range into a standalone LBK1 container.
+// Same options as Writer; a schema is STRONGLY recommended when this is a
+// part of a larger multi-part compile (see module doc).
+export function compilePart(bytes, opts) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('compilePart: expected Uint8Array');
+  }
+  opts = opts || {};
+  const framing = opts.framing || 'ndjson';
+  const w = new Writer(opts.writer || {});
+  const t = new Tokenizer(w, { framing });
+  t.feed(bytes);
+  t.end();
+  return new Uint8Array(w.finalize().buffer);
+}
+
+// ---------- compileInParts ----------
+
+// Sequential convenience: split then compile each part serially.
+// 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) {
+  opts = opts || {};
+  const splitOpts = {
+    targetParts: opts.targetParts,
+    maxPartBytes: opts.maxPartBytes,
+  };
+  const partOpts = {
+    framing: opts.framing || 'ndjson',
+    writer: opts.writer || {},
+  };
+  const ranges = splitNDJSON(bytes, splitOpts);
+  const containers = new Array(ranges.length);
+  for (let i = 0; i < ranges.length; i++) {
+    const { start, end } = ranges[i];
+    containers[i] = compilePart(bytes.subarray(start, end), partOpts);
+  }
+  return containers;
+}
+
+// ---------- mergeContainers ----------
+
+// Concatenate N LBK1 containers into ONE. All containers must share an
+// identical schema (byte-compare over the schema block). Preserves per-shard
+// string tables and zone maps verbatim; rewrites the shard directory + header
+// offsets to make the combined layout self-consistent.
+//
+// The result is byte-identical (except for the shard directory / header
+// offsets) to what a single Writer would have produced if it had emitted the
+// same shards in the same order. Query behavior via `new Reader(merged)` and
+// via `new MultiReader([readers...])` is equivalent (both return the same
+// values for the same global row indices).
+export function mergeContainers(containers) {
+  if (!Array.isArray(containers) || containers.length === 0) {
+    throw new SplitError('S_MERGE_EMPTY', 'mergeContainers requires a non-empty array');
+  }
+  // Normalize inputs to Uint8Array
+  const parts = containers.map((c, i) => {
+    if (c instanceof Uint8Array) return c;
+    if (c instanceof ArrayBuffer) return new Uint8Array(c);
+    throw new TypeError('mergeContainers: container ' + i + ' is not Uint8Array or ArrayBuffer');
+  });
+
+  // Parse each via Reader for authoritative metadata. This also validates
+  // the LBK1 magic and version.
+  const readers = parts.map((p) => new Reader(_toArrayBuffer(p)));
+
+  // Schemas must match. We compare the parsed schema (byte-exact would work
+  // too but this catches equivalent-but-differently-padded cases).
+  const schema0 = readers[0].schema;
+  for (let i = 1; i < readers.length; i++) {
+    if (!_schemasEqual(schema0, readers[i].schema)) {
+      throw new SplitError('S_SCHEMA_MISMATCH',
+        'mergeContainers: container ' + i + ' schema differs from container 0');
+    }
+  }
+
+  // Total shards and rows
+  let totalShards = 0, totalRows = 0;
+  for (const r of readers) { totalShards += r.shardCount; totalRows += r.totalRows; }
+
+  // Compute the target layout. Schema block is copied from container 0 verbatim.
+  // Reader gives us schemaBlockOff and shardDirOff; the schema-block byte range
+  // is [schemaBlockOff, shardDirOff). We reuse this slice.
+  const src0 = parts[0];
+  const dv0 = new DataView(src0.buffer, src0.byteOffset, src0.byteLength);
+  const schemaBlockOff = Number(dv0.getBigUint64(8, true));
+  const shardDirOff0   = Number(dv0.getBigUint64(24, true));
+  const schemaBlockLen = shardDirOff0 - schemaBlockOff;
+
+  // New offsets
+  const outSchemaBlockOff = CONTAINER_HEADER_BYTES;
+  const outShardDirOff    = outSchemaBlockOff + schemaBlockLen;
+  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.)
+  const outHasZoneMaps = readers.every((r) => r.hasZoneMaps);
+  const zoneMapsRaw = readers.map((r) => r.zoneMapsRaw());
+  const T = outHasZoneMaps ? zoneMapsRaw[0].trackedFields.length : 0;
+  const zoneMapsHeaderLen = 16;
+  const zoneMapsFieldTableLen = T * 2;
+  const zoneMapsFieldTablePad = (8 - (zoneMapsFieldTableLen & 7)) & 7;
+  const zoneMapsMinsMaxesLen = outHasZoneMaps ? totalShards * T * 8 * 2 : 0;
+  const outMetadataOff = outHasZoneMaps ? (outShardDirOff + outShardDirBytes) : 0;
+  const outZoneMapsBytes = outHasZoneMaps
+    ? zoneMapsHeaderLen + zoneMapsFieldTableLen + zoneMapsFieldTablePad + zoneMapsMinsMaxesLen
+    : 0;
+  const outFirstShardOff = outShardDirOff + outShardDirBytes + outZoneMapsBytes;
+
+  // Compute per-source-shard payload/string-table extents in the OUTPUT buffer.
+  // Layout mirrors the writer's: each shard's payload followed by its local
+  // string table, padded to 8 between shards.
+  let cursor = outFirstShardOff;
+  const shardOutMap = [];   // array of {payloadOff, payloadLen, stringOff, stringLen, srcContainerIdx, srcShardIdx, rowCount, mins?, maxes?}
+  for (let ci = 0; ci < readers.length; ci++) {
+    const r = readers[ci];
+    for (let si = 0; si < r.shardCount; si++) {
+      const shard = r.shards[si];
+      // Source shard payload lives at shard.payloadOff in the source container.
+      const payloadLen = shard.payloadLen;
+      const payloadPad = (8 - (payloadLen & 7)) & 7;
+      const stringLen = shard.stringTable ? _sourceStringTableLen(readers[ci], si) : 0;
+      const outPayloadOff = cursor;
+      const outStringOff = outPayloadOff + payloadLen + payloadPad;
+      shardOutMap.push({
+        payloadOff: outPayloadOff,
+        payloadLen,
+        stringOff: outStringOff,
+        stringLen,
+        srcContainerIdx: ci,
+        srcShardIdx: si,
+        rowCount: shard.rowCount,
+      });
+      cursor = outStringOff + stringLen;
+    }
+  }
+  const totalBytes = cursor + FOOTER_BYTES;
+
+  // Allocate output
+  const out = new Uint8Array(totalBytes);
+  const outDv = new DataView(out.buffer);
+
+  // Header
+  out[0] = 0x4C; out[1] = 0x42; out[2] = 0x4B; out[3] = 0x31;   // 'LBK1'
+  outDv.setUint16(4, 1, true);            // format_version
+  out[6] = 1;                              // endian LE
+  out[7] = 0;
+  outDv.setBigUint64(8,  BigInt(outSchemaBlockOff), true);
+  outDv.setBigUint64(16, BigInt(outMetadataOff),    true);
+  outDv.setBigUint64(24, BigInt(outShardDirOff),    true);
+  outDv.setUint32(32, totalShards, true);
+  outDv.setUint32(36, 0, true);
+  outDv.setBigUint64(40, BigInt(totalRows), true);
+
+  // Schema block: copy verbatim from container 0
+  out.set(parts[0].subarray(schemaBlockOff, schemaBlockOff + schemaBlockLen), outSchemaBlockOff);
+
+  // Shard directory: rewrite ShardEntry for every output shard
+  for (let s = 0; s < shardOutMap.length; s++) {
+    const m = shardOutMap[s];
+    const entryOff = outShardDirOff + s * SHARD_ENTRY_BYTES;
+    outDv.setBigUint64(entryOff + 0,  BigInt(m.payloadOff), true);
+    outDv.setUint32(entryOff + 8,  m.payloadLen, true);
+    outDv.setUint32(entryOff + 12, m.rowCount, true);
+    outDv.setUint16(entryOff + 16, 1, true);   // min_reader_version
+    outDv.setUint16(entryOff + 18, 0, true);   // flags
+    outDv.setUint32(entryOff + 20, 0, true);   // reserved
+    outDv.setBigUint64(entryOff + 24, BigInt(m.stringLen > 0 ? m.stringOff : 0), true);
+    outDv.setBigUint64(entryOff + 32, BigInt(m.stringLen), true);
+  }
+
+  // Zone maps: header + field table + interleaved mins/maxes.
+  if (outHasZoneMaps) {
+    // Segment header
+    out[outMetadataOff + 0] = 0x30; out[outMetadataOff + 1] = 0x5A;
+    out[outMetadataOff + 2] = 0x4D; out[outMetadataOff + 3] = 0x31;   // 'ZM01'
+    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)
+    const fieldTableOut = outMetadataOff + zoneMapsHeaderLen;
+    const tracked0 = zoneMapsRaw[0].trackedFields;
+    for (let t = 0; t < T; t++) outDv.setUint16(fieldTableOut + t * 2, tracked0[t], true);
+    // Mins / maxes concatenated in output-shard order
+    const minsOut = fieldTableOut + zoneMapsFieldTableLen + zoneMapsFieldTablePad;
+    const maxesOut = minsOut + totalShards * T * 8;
+    for (let s = 0; s < shardOutMap.length; s++) {
+      const m = shardOutMap[s];
+      const zm = zoneMapsRaw[m.srcContainerIdx];
+      for (let t = 0; t < T; t++) {
+        const srcPos = m.srcShardIdx * zm.laneCount + t;
+        outDv.setFloat64(minsOut  + (s * T + t) * 8, zm.mins[srcPos],  true);
+        outDv.setFloat64(maxesOut + (s * T + t) * 8, zm.maxes[srcPos], true);
+      }
+    }
+  }
+
+  // Shard payloads + string tables: bulk-copy each source range to its new offset
+  for (const m of shardOutMap) {
+    const src = parts[m.srcContainerIdx];
+    const r = readers[m.srcContainerIdx];
+    const srcShard = r.shards[m.srcShardIdx];
+    // Payload
+    out.set(src.subarray(srcShard.payloadOff, srcShard.payloadOff + m.payloadLen), m.payloadOff);
+    // String table (if any)
+    if (m.stringLen > 0) {
+      // In source, the string table starts at localStrOff (from the ShardEntry).
+      const srcDv = new DataView(src.buffer, src.byteOffset, src.byteLength);
+      const srcShardEntry = r.shardDirectoryOffset + m.srcShardIdx * SHARD_ENTRY_BYTES;
+      const srcLocalStrOff = Number(srcDv.getBigUint64(srcShardEntry + 24, true));
+      out.set(src.subarray(srcLocalStrOff, srcLocalStrOff + m.stringLen), m.stringOff);
+    }
+  }
+
+  // Footer
+  const footerOff = totalBytes - FOOTER_BYTES;
+  outDv.setUint32(footerOff + 0, 0xFFFFFFFF, true);   // CRC absent
+  outDv.setUint32(footerOff + 4, 0, true);
+  out[footerOff + 8]  = 0x31;
+  out[footerOff + 9]  = 0x4B;
+  out[footerOff + 10] = 0x42;
+  out[footerOff + 11] = 0x4C;
+  outDv.setUint32(footerOff + 12, FOOTER_BYTES, true);
+
+  return out;
+}
+
+// ---------- internals ----------
+
+function _toArrayBuffer(u8) {
+  if (u8.byteOffset === 0 && u8.byteLength === u8.buffer.byteLength) return u8.buffer;
+  const copy = new Uint8Array(u8.byteLength);
+  copy.set(u8);
+  return copy.buffer;
+}
+
+function _schemasEqual(a, b) {
+  if (a.fields.length !== b.fields.length) return false;
+  if (a.rowStride !== b.rowStride) return false;
+  for (let i = 0; i < a.fields.length; i++) {
+    if (a.fields[i].name !== b.fields[i].name) return false;
+    if (a.fields[i].laneKind !== b.fields[i].laneKind) return false;
+    if (a.fields[i].offsetInRow !== b.fields[i].offsetInRow) return false;
+  }
+  return true;
+}
+
+// Look up the source string-table byte length for a shard.
+function _sourceStringTableLen(reader, shardIdx) {
+  const dv = new DataView(reader.buffer);
+  const entryOff = reader.shardDirectoryOffset + shardIdx * SHARD_ENTRY_BYTES;
+  return Number(dv.getBigUint64(entryOff + 32, true));
+}

package/src/StringTable.js

@@ -0,0 +1,225 @@
+// @zakkster/lite-bake-stream / StringTable
+// Byte-level UTF-8 string interning with zero-alloc hot path.
+// Copyright (c) 2026 Zahary Shinikchiev. MIT.
+//
+// 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.
+//
+// Serializes to the LBK1 per-shard string-table layout (SPEC.md section 3.3):
+//   u32 entry_count
+//   u32 blob_length_bytes
+//   u32 offsets[entry_count]     (start of each string in the blob)
+//   u32 blob_end_sentinel        (= blob_length_bytes, for len derivation)
+//   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.
+
+export const VERSION = '1.0.0';
+
+const EMPTY_SLOT = 0xFFFFFFFF;   // MUST be unsigned; typed-array reads are unsigned
+const INITIAL_BLOB_BYTES  = 64 * 1024;
+const INITIAL_ENTRIES     = 1024;
+const INITIAL_HASH_CAP    = 2048;      // load factor target 50%
+const HASH_MAX_LOAD_NUM   = 1;         // 50% load factor: num/den = 1/2
+const HASH_MAX_LOAD_DEN   = 2;
+
+// FNV-1a 32-bit over a byte range.
+function fnv1a(bytes, from, to) {
+  let h = 0x811c9dc5 | 0;
+  for (let i = from; i < to; i++) {
+    h = (h ^ bytes[i]) | 0;
+    h = Math.imul(h, 0x01000193) | 0;
+  }
+  return h >>> 0;
+}
+
+export class StringTable {
+  constructor() {
+    this._blob = new Uint8Array(INITIAL_BLOB_BYTES);
+    this._blobLen = 0;
+    this._offsets = new Uint32Array(INITIAL_ENTRIES + 1);   // +1 for sentinel slot
+    this._count = 0;
+    this._hashCap = INITIAL_HASH_CAP;
+    this._hashMask = INITIAL_HASH_CAP - 1;
+    this._hashKeys = new Uint32Array(INITIAL_HASH_CAP).fill(EMPTY_SLOT);
+  }
+
+  // Returns u32 index of the string with these bytes, adding a new entry if
+  // this exact byte sequence hasn't been seen before. Zero-alloc on the hit path.
+  intern(bytes, from, to) {
+    const h = fnv1a(bytes, from, to);
+    let slot = h & this._hashMask;
+    // Linear probing with wraparound
+    for (;;) {
+      const stored = this._hashKeys[slot];
+      if (stored === EMPTY_SLOT) {
+        // Miss: this is a new string; append + record + insert.
+        return this._insertNew(bytes, from, to, slot);
+      }
+      // Occupied: check for byte-equal match at stored index
+      if (this._equalsAt(stored, bytes, from, to)) return stored;
+      slot = (slot + 1) & this._hashMask;
+    }
+  }
+
+  _equalsAt(idx, bytes, from, to) {
+    const start = this._offsets[idx];
+    const end   = this._offsets[idx + 1];  // sentinel makes this valid for the last entry too
+    const n = to - from;
+    if ((end - start) !== n) return false;
+    const blob = this._blob;
+    for (let i = 0; i < n; i++) {
+      if (blob[start + i] !== bytes[from + i]) return false;
+    }
+    return true;
+  }
+
+  _insertNew(bytes, from, to, slot) {
+    const n = to - from;
+    // Grow blob if needed
+    if (this._blobLen + n > this._blob.length) this._growBlob(n);
+    // Grow offsets if needed (leave room for +1 sentinel)
+    if (this._count + 1 >= this._offsets.length) this._growOffsets();
+
+    const idx = this._count;
+    this._offsets[idx] = this._blobLen;
+    // append bytes
+    const dst = this._blob;
+    let d = this._blobLen;
+    for (let s = from; s < to; s++) dst[d++] = bytes[s];
+    this._blobLen = d;
+    // update sentinel at idx+1
+    this._offsets[idx + 1] = this._blobLen;
+    this._count++;
+
+    // Insert into hash table
+    this._hashKeys[slot] = idx;
+
+    // Resize hash table if load factor exceeded
+    if (this._count * HASH_MAX_LOAD_DEN > this._hashCap * HASH_MAX_LOAD_NUM) {
+      this._resizeHash();
+    }
+    return idx;
+  }
+
+  _growBlob(needed) {
+    let cap = this._blob.length;
+    while (cap < this._blobLen + needed) cap *= 2;
+    const nb = new Uint8Array(cap);
+    nb.set(this._blob);
+    this._blob = nb;
+  }
+
+  _growOffsets() {
+    const nb = new Uint32Array(this._offsets.length * 2);
+    nb.set(this._offsets);
+    this._offsets = nb;
+  }
+
+  _resizeHash() {
+    const newCap = this._hashCap * 2;
+    const newMask = newCap - 1;
+    const newKeys = new Uint32Array(newCap).fill(EMPTY_SLOT);
+    // Rehash every occupied slot by looking up its string in the blob.
+    const oldKeys = this._hashKeys;
+    for (let i = 0; i < oldKeys.length; i++) {
+      const idx = oldKeys[i];
+      if (idx === EMPTY_SLOT) continue;
+      const start = this._offsets[idx];
+      const end   = this._offsets[idx + 1];
+      const h = fnv1a(this._blob, start, end);
+      let slot = h & newMask;
+      while (newKeys[slot] !== EMPTY_SLOT) slot = (slot + 1) & newMask;
+      newKeys[slot] = idx;
+    }
+    this._hashCap = newCap;
+    this._hashMask = newMask;
+    this._hashKeys = newKeys;
+  }
+
+  get count()    { return this._count; }
+  get blobLen()  { return this._blobLen; }
+
+  // Zero-copy byte range for entry `idx`. Used by consumers that want the raw
+  // UTF-8 bytes without materializing a JS string (e.g. re-interning across
+  // string tables during sample drain).
+  bytesAt(idx) {
+    if (idx >= this._count) return undefined;
+    return this._blob.subarray(this._offsets[idx], this._offsets[idx + 1]);
+  }
+
+  // Reset in-place, keeping allocated arrays (per-shard reuse pattern).
+  reset() {
+    this._blobLen = 0;
+    this._count = 0;
+    // clear the sentinel/offsets that were in use to avoid stale data
+    // (we only touched [0..count], so the fill is bounded)
+    this._offsets[0] = 0;
+    this._hashKeys.fill(EMPTY_SLOT);
+  }
+
+  // Serialize into the LBK1 per-shard string-table byte layout described at the
+  // top of this file. Returns { bytes: Uint8Array, byteLength: number }.
+  // byteLength includes 8-byte pad so the payload aligns cleanly.
+  serialize() {
+    const entryCount = this._count;
+    const blobLen = this._blobLen;
+    // header: 4 (entry_count) + 4 (blob_len) + 4*(entry_count+1) (offsets incl. sentinel) + blob
+    const bodyBytes = 8 + 4 * (entryCount + 1) + blobLen;
+    const padded = (bodyBytes + 7) & ~7;
+    const bytes = new Uint8Array(padded);
+    const dv = new DataView(bytes.buffer);
+    dv.setUint32(0, entryCount, true);
+    dv.setUint32(4, blobLen, true);
+    let off = 8;
+    for (let i = 0; i <= entryCount; i++) {   // <=: include the sentinel
+      dv.setUint32(off, this._offsets[i], true);
+      off += 4;
+    }
+    bytes.set(this._blob.subarray(0, blobLen), off);
+    return { bytes, byteLength: padded };
+  }
+
+  // Static: parse a serialized table from a byte view. Returns a read-only
+  // 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);
+    const blobLen    = dv.getUint32(4, true);
+    // offsets live at bytes[byteOffset + 8 ..], length = (entryCount+1)*4
+    const offsetsByteOff = byteOffset + 8;
+    const offsets = new Uint32Array(bytes.buffer, bytes.byteOffset + offsetsByteOff, entryCount + 1);
+    const blobByteOff = offsetsByteOff + 4 * (entryCount + 1);
+    const blob = new Uint8Array(bytes.buffer, bytes.byteOffset + blobByteOff, blobLen);
+    return new StringTableView(entryCount, blob, offsets);
+  }
+}
+
+// Read-only view over a serialized string table. Zero-copy over the underlying
+// buffer; JS string materialized only on .get(i) call.
+export class StringTableView {
+  constructor(count, blob, offsets) {
+    this._count = count;
+    this._blob = blob;
+    this._offsets = offsets;
+    this._decoder = null;   // lazy — created on first get()
+  }
+
+  get count() { return this._count; }
+
+  get(idx) {
+    if (idx >= this._count) return undefined;
+    if (!this._decoder) this._decoder = new TextDecoder('utf-8');
+    const start = this._offsets[idx];
+    const end   = this._offsets[idx + 1];
+    return this._decoder.decode(this._blob.subarray(start, end));
+  }
+
+  // Raw byte range for callers that want to skip UTF-8 decode.
+  bytesAt(idx) {
+    if (idx >= this._count) return undefined;
+    return this._blob.subarray(this._offsets[idx], this._offsets[idx + 1]);
+  }
+}