@zakkster/lite-bake-stream 1.6.0 → 1.7.0

package/llms.txt

@@ -1,20 +1,20 @@
 # @zakkster/lite-bake-stream
 
-Streaming byte-level JSON to lite-bake binary compiler for JS runtimes.
+Streaming byte-level JSON to LBK1 binary containers for JS runtimes.
 
 ## Purpose
 
-Ingest gigabyte-scale JSON (top-level array or NDJSON) into the `lite-bake` LBK1 binary format without materializing the intermediate object graph. Reference producer path for downstream consumers of the flat, interleaved, zero-GC `lite-bake` reader API.
+Ingest gigabyte-scale JSON (top-level array or NDJSON) into the LBK1 binary container format without materializing the intermediate object graph. The container is flat, interleaved, and zero-GC to read; a Reader gives random access to any row without re-parsing JSON.
 
 ## Status
 
-v1.6.0 — stable. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak (M1 MacBook Pro): 98.37M rows, 4.89 GB container, zero major GC, zero minor GC, 499 KB total heap allocation, 590.21M cells verified byte-exact, zero mismatches. Tokenizer benches at 222-237 MB/s (~55% of JSON.parse, with no object graph allocated).
+v1.7.0 -- stable. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak (M1 MacBook Pro): 98.37M rows, 4.89 GB container, zero major GC, zero minor GC, 499 KB total heap allocation, 590.21M cells verified byte-exact, zero mismatches. Tokenizer benches at 222-237 MB/s (~55% of JSON.parse, with no object graph allocated).
 
 Public API follows semver from 1.0.0. Future additions (I64 lane, columnar payload mode, container-level string table) land via the format's forward-compat seams -- `min_reader_version` on ShardEntry, reserved FieldDescriptor flags, the `metadata_off` block wrapper -- without a format_version bump.
 
 See SPEC.md for the LBK1 container format, section 3.6 for zone maps, section 4.3 for the reserved field flags.
 
-## Public API (v1.6.0)
+## Public API (v1.7.0)
 
 Two ingest modes share one top-level API:
 
@@ -27,28 +27,25 @@ Schema-mode classes:
 - `Tokenizer` (`/tokenizer`): chunk-safe UTF-8 JSON SAX scanner.
 - `Writer` (`/writer`): LBK1 shard emitter, plugs into Tokenizer. F64/U32 lanes, per-shard string tables and zone maps.
 - `Reader` (`/reader`): container parser, sync, zero-alloc `get(row, field)` accessors + zone-maps query APIs (`shardBounds`, `findShards`).
-- `RangeReader` (`/range-reader`): HTTP Range lazy shard loading, synchronous query pruning after open.
+- `RangeReader` (`/range-reader`): HTTP Range lazy shard loading, synchronous query pruning after open. Optional `{ signal }` cancels in-flight range I/O; the reader is dead for new I/O once it fires (BS-28).
 - `MultiReader` (`/multi-reader`): logical union over N Readers sharing a schema.
 - `splitNDJSON`, `compilePart`, `compileInParts`, `mergeContainers` (`/split`): worker-agnostic split/compile/merge.
 
 Preserve-mode classes:
 - `PreserveTokenizer` (`/preserve-tokenizer`): NDJSON record-boundary scanner, JSON-aware depth tracking, chunk-safe.
 - `PreserveWriter` (`/preserve-writer`): opaque byte-blob sink, pre-allocated shard buffer, zero-GC record path.
-- `PreserveReader` (`/preserve-reader`): tri-API — `getBytes(i)` (zero-alloc view), `getString(i)`, `getJSON(i)`.
+- `PreserveReader` (`/preserve-reader`): tri-API -- `getBytes(i)` (zero-alloc view), `getString(i)`, `getJSON(i)`. A returned view pins the container's ArrayBuffer (plain subarray semantics); copy the bytes out if you need the container to be collectable.
 
 Shared:
 - `StringTable` (`/string-table`): byte-level UTF-8 interning primitive.
-- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` through the pipeline. `preserve` option dispatches to the right writer.
+- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` (e.g. `File.stream()`) through the pipeline. `preserve` option dispatches to the right writer. Per-chunk `onProgress` callback; its state object is reused across calls (mutated in place, zero per-chunk allocation) -- copy it if retained past the callback.
 
 Error classes with stable `code`: `TokenizerError`, `WriterError`, `ReaderError`, `RangeReaderError`, `MultiReaderError`, `SplitError`, `PreserveTokenizerError`, `PreserveWriterError`, `PreserveReaderError`.
-- `ingestStream`, `ingestFile` (`/file-ingest`): browser helpers piping a `ReadableStream<Uint8Array>` (e.g. `File.stream()`) through the Tokenizer + Writer, returning a Reader. Per-chunk `onProgress` callback; its state object is reused across calls (mutated in place, zero per-chunk allocation) -- copy it if retained past the callback.
-- `TokenizerError`, `WriterError`, `ReaderError`, `RangeReaderError`: thrown on parse/write/read errors with stable `code`.
-- `VERSION` const per subpath.
 
 ## Schema forms
 
-- `{ fields: ['id', 'x', 'y'] }` — all-F64 shorthand, back-compat with M2.
-- `{ fields: [{name:'id', laneKind:'f64'}, {name:'tag', laneKind:'u32'}] }` — mixed lanes (M3).
+- `{ fields: ['id', 'x', 'y'] }` -- all-F64 shorthand, back-compat with M2.
+- `{ fields: [{name:'id', laneKind:'f64'}, {name:'tag', laneKind:'u32'}] }` -- mixed lanes (M3).
 - Sample-and-infer (default when no schema is passed): the first `sampleBytes` of INPUT are observed, byte-true (BS-07) -- the window ends at the first record boundary at or after `sampleBytes` input bytes, read from the Tokenizer's `absOffset`, independent of chunking and record count (a hand-driven Writer with no wired source samples by record count). Fields with only numbers become F64, only strings become U32. null is lane-neutral (BS-20): it sets no kind, so null+string infers U32 (no longer "mixed") and null+number infers F64; post-freeze null reads 0 on an F64 lane and "" on a U32 lane. A field that saw both a real number and a real string raises `W_MIXED_LANE_TYPES` at freeze. Sample memory is O(`sampleBytes`): columnar staging plus a shared string table, independent of total input size.
 
 ## Contract
@@ -60,13 +57,14 @@ Error classes with stable `code`: `TokenizerError`, `WriterError`, `ReaderError`
 
 ## Preservation contract
 
-Every declared field of every row round-trips. F64 lanes: bit-exact for numeric literals with ≤15 significant digits and |exponent| ≤ 22 (Clinger's fast path); ≤1 ULP drift outside that domain (documented, pinned by NumericBoundary.test.js). U32 lanes: byte-exact UTF-8, unconditional. Missing fields → documented defaults. Unknown keys → silently dropped. Wrong-type value on post-freeze schema → W_LANE_MISMATCH error, no corrupt container produced. See SPEC section 7 for the full table. Asserted by tests, property-based fuzz, AND torture-scale verification (~73,500 rows per fast-tier run).
+Every declared field of every row round-trips. F64 lanes: bit-exact for numeric literals with <=15 significant digits and |exponent| <= 22 (Clinger's fast path); <=1 ULP drift outside that domain (documented, pinned by NumericBoundary.test.js). U32 lanes: byte-exact UTF-8, unconditional. Missing fields -> documented defaults. Unknown keys -> silently dropped. Wrong-type value on post-freeze schema -> W_LANE_MISMATCH error, no corrupt container produced. See SPEC section 7 for the full table. Asserted by tests, property-based fuzz, AND torture-scale verification (~103,000 rows across 20 scenarios per fast-tier run).
 
 ## Row-index and refusal codes
 
 - Random-access row surfaces fail closed on a bad `rowIdx` (negative, fractional, NaN, or >= totalRows): `Reader.get`, `RangeReader.get` and `PreserveReader.getBytes/getString/getJSON` throw `R_ROW_OUT_OF_RANGE`; `MultiReader.get` throws `M_ROW_OUT_OF_RANGE`. The SHARD-index escape hatches (`shardPayload`, `shardF64`, `shardStringTable`, `loadShard`) keep their unchecked raw-access contract; `shardBounds` returns null out-of-range.
 - `R_OFFSET_TOO_LARGE`: a u64 header/schema/directory offset exceeds 2^53-1 (a Number() cast would lose precision). Raised by all three reader classes.
 - `R_NOT_PREFETCHED`: `RangeReader.syncRange` over a shard `prefetchRange` has not cached (distinct from the `R_TRUNCATED` truncation door). `R_ADAPTER_SHORT_READ` also covers a non-Uint8Array or wrong-length adapter return.
+- `R_ABORTED`: a reader-level `{ signal }` (constructor / `RangeReader.open`, forwarded into `HTTPRangeAdapter.open`) fired -- in-flight range I/O is cancelled. Fail-closed triangle: a pre-aborted signal requests zero bytes; a hanging adapter still rejects within the tick of the abort (the abort listener is removed on settle in both directions, so a long-lived signal retains nothing); resolved-after-abort bytes are discarded and nothing is cached. A foreign `AbortError` rejection while aborted maps here (never leaks); a non-abort rejection rethrows verbatim. The adapter contract goes additive `fetch(byteOffset, byteLength, signal?)` -- a 2-arg adapter degrades cancellation only, never correctness. See decisions/0013-range-abort.md.
 - `ST_BLOB_OVERFLOW`: a per-shard string table would cross the u32 blob_length (4294967295) or entry_count (4294967294) ceiling; also raised by `PreserveWriter` before a shard payload_len would exceed u32. One shared code across `StringTable` and `PreserveWriter`. `StringTableError` is exported from the root and the `string-table` subpath.
 
 ## Shard budget
@@ -85,7 +83,7 @@ F64 only. Values exceeding IEEE 754 double range are rejected as `E_NUMBER_OVERF
 
 ## Tree-shaking
 
-Subpath entries per SPEC section 6. `sideEffects: false`. Consumers import only the path they need; the browser reader never pulls the writer.
+Subpath entries per SPEC section 6. `sideEffects: false`. Consumers import only the path they need; the browser reader never pulls the writer. Every subpath exports a `VERSION` const.
 
 ## Streaming emission and integrity (M6)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-bake-stream",
-  "version": "1.6.0",
-  "description": "Streaming byte-level JSON to lite-bake binary compiler. Zero-GC, tree-shakeable, gigabyte-scale.",
+  "version": "1.7.0",
+  "description": "Streaming byte-level JSON to LBK1 binary containers. Zero-GC, tree-shakeable, gigabyte-scale.",
   "type": "module",
   "sideEffects": false,
   "exports": {

package/src/FileIngest.js

@@ -2,11 +2,15 @@
 // Browser-side helper: File.stream() -> Tokenizer -> Writer -> Reader.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_OPTION_CONFLICT  - preserve mode requested with a non-ndjson framing
+//
 // The natural browser ingest path is:
 //
 //   const file = fileInputEl.files[0];
-//   const reader = await ingestStream(file.stream(), file.size, {
+//   const reader = await ingestStream(file.stream(), {
 //     framing: 'ndjson',
+//     totalBytes: file.size,
 //     onProgress: ({bytesIngested, totalBytes, rowsWritten, shardsCommitted}) => {...}
 //   });
 //   // reader is a fully-materialized in-memory LBK1 Reader.
@@ -27,7 +31,7 @@ import { PreserveWriter } from './PreserveWriter.js';
 import { PreserveReader } from './PreserveReader.js';
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 const INGEST_OPTS = {

package/src/MultiReader.js

@@ -25,7 +25,7 @@
 //   M_ROW_OUT_OF_RANGE    - rowIdx >= totalRows
 //   M_TOO_MANY_ROWS       - cumulative row count exceeds Number.MAX_SAFE_INTEGER
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 export class MultiReaderError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'MultiReaderError'; }

package/src/Opts.js

@@ -1,6 +1,10 @@
 // @zakkster/lite-bake-stream / Opts (internal, not exported from index.js)
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_UNKNOWN_OPTION  - an unknown option key (fails closed with a did-you-mean hint)
+//   E_OPTION_VALUE    - an option value falls outside its declared domain
+//
 // Shared construction-time options validator. Every public constructor and
 // entry function that takes an opts object runs checkOpts once, at construction
 // or in a synchronous prologue -- never per byte, never per record. An unknown
@@ -14,6 +18,8 @@
 //   { t: 'int',  min, max }             - integer in [min, max] inclusive
 //   { t: 'bool' }                       - boolean
 //   { t: 'fn' }                         - function
+//   { t: 'signal' }                     - AbortSignal-shaped (aborted boolean +
+//                                         addEventListener/removeEventListener fns)
 //   { t: 'obj', nullable }              - object (contents validated downstream)
 // A value of `undefined` for any key means "use the default" and is skipped,
 // matching each host's `opts.k !== undefined ? opts.k : DEFAULT` defaulting.
@@ -47,8 +53,10 @@
 //     totalBytes      int [0, 9007199254740991]          def -1        (ingest only)
 //   RangeReader(adapter,opts) / .open
 //     maxCachedShards int [0, 4294967295]               def 8         (0 = retain no shard)
+//     signal          AbortSignal-shaped                 def none (no cancellation)
 //   HTTPRangeAdapter.open(url,opts)
 //     fetch           function                           def globalThis.fetch
+//     signal          AbortSignal-shaped                 def none (no cancellation)
 //   splitNDJSON(bytes,opts) / compileInParts
 //     targetParts     int [1, 4294967295]               def 4         (0 forbidden)
 //     maxPartBytes    int [1, 4294967295] or Infinity   def Infinity  (0 forbidden; Infinity = no cap)
@@ -115,6 +123,21 @@ function _checkValue(label, key, v, d, raise) {
     }
     return;
   }
+  if (t === 'signal') {
+    // AbortSignal by DUCK shape, not instanceof (cross-realm false negatives
+    // against the exact scheduled consumer). removeEventListener is REQUIRED --
+    // a signal that cannot be un-listened cannot satisfy the settle-removal law
+    // (unverified state, refused at the door). See decisions/0013.
+    if (v === null || typeof v !== 'object' ||
+        typeof v.aborted !== 'boolean' ||
+        typeof v.addEventListener !== 'function' ||
+        typeof v.removeEventListener !== 'function') {
+      raise('E_OPTION_VALUE',
+        label + ": option '" + key + "' must be an AbortSignal (aborted boolean + " +
+        'addEventListener/removeEventListener); got ' + _show(v));
+    }
+    return;
+  }
   if (t === 'obj') {
     if (v === null) {
       if (!d.nullable) {

package/src/PreserveReader.js

@@ -29,13 +29,15 @@
 //   R_INVALID                - a structure is internally inconsistent but in-bounds
 //   R_SHARD_VERSION_TOO_NEW  - a shard's min_reader_version > this reader
 //   R_ROW_OUT_OF_RANGE       - rowIdx negative, fractional, NaN, or >= totalRows (BS-32)
+//   R_BAD_CRC                - CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT             - CRC verify requested but the container carries no checksum
 //   R_OFFSET_TOO_LARGE       - a u64 header/directory offset exceeds 2^53-1
 
 import { toContainerBuffer } from './Views.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/PreserveTokenizer.js

@@ -1,11 +1,20 @@
 // @zakkster/lite-bake-stream / PreserveTokenizer
 // NDJSON record-boundary scanner for preserve-mode. Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   E_UNSUPPORTED_FRAMING  - preserve mode fed a framing other than ndjson
+//   E_RECORD_TOO_LARGE     - a single record exceeds maxRecordBytes
+//   E_UNBALANCED           - a record's JSON structure never closes
+//   E_TRUNCATED            - input ends mid-record
+//   E_ENDED                - feed() called after end()
+//   E_POISONED             - reuse after a prior throw
+//
 // The schema-mode Tokenizer walks the full JSON AST (numbers, strings, keys,
 // object/array structure) so the Writer can pack values into typed lanes.
-// Preserve-mode doesn't crack open records — it just needs to find where one
+// Preserve-mode doesn't crack open records -- it just needs to find where one
 // record ends and the next begins, so the record's original bytes can be
 // shoved into a shard intact.
+// See decisions/0010-preserve-mode.md.
 //
 // Contract:
 //   - Input:  NDJSON bytes. One JSON value per line, delimited by 0x0A.
@@ -32,7 +41,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 const PRESERVE_TOKENIZER_OPTS = {
@@ -57,7 +66,7 @@ const BYTE_RBRACK = 0x5D;
 const BYTE_SPACE  = 0x20;
 const BYTE_TAB    = 0x09;
 
-const INITIAL_BUF = 1 << 16;   // 64 KiB — grows on demand for larger records
+const INITIAL_BUF = 1 << 16;   // 64 KiB -- grows on demand for larger records
 
 export class PreserveTokenizer {
   constructor(sink, opts) {

package/src/PreserveWriter.js

@@ -1,6 +1,12 @@
 // @zakkster/lite-bake-stream / PreserveWriter
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   W_EMPTY_INPUT      - finalize with no records written
+//   W_BAD_SINK         - sink is not an object / missing write / async return
+//   W_FINALIZED        - write after the writer was finalized
+//   ST_BLOB_OVERFLOW   - a shard payload_len would exceed the u32 ceiling
+//
 // Preserve-mode sink: opaque record blobs packed into shards, with a trailing
 // u32 offset table per shard. No schema, no lanes, no string table, no zone
 // maps. Bytes in, same bytes out.
@@ -20,7 +26,7 @@ import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal, crc32cCombine } from './Crc32c.js';
 import { validateSink, isThenable } from './Views.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }
@@ -35,7 +41,7 @@ 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 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

package/src/RangeReader.js

@@ -19,9 +19,13 @@
 //
 // IO adapter contract:
 //   interface IOAdapter {
-//     size: number;                                         // container byte length
-//     fetch(byteOffset, byteLength): Promise<Uint8Array>;   // MUST return exactly that many bytes
+//     size: number;                                                  // container byte length
+//     fetch(byteOffset, byteLength, signal?): Promise<Uint8Array>;   // MUST return exactly that many bytes
 //   }
+// The signal parameter is ADDITIVE (BS-28): a 2-arg adapter that ignores it
+// degrades CANCELLATION only, never correctness -- the reader-side fail-closed
+// triangle (pre-check / race / post-settle) guarantees the outcome regardless.
+// See decisions/0013-range-abort.md.
 //
 // Two adapters ship in-box:
 //   HTTPRangeAdapter -- uses fetch() with Range headers.
@@ -33,6 +37,8 @@
 //   R_ADAPTER_SHORT_READ   -- adapter returned fewer bytes than requested, OR a
 //                             non-Uint8Array / wrong-length adapter return (T7c)
 //   R_ROW_OUT_OF_RANGE     -- rowIdx negative, fractional, NaN, or >= totalRows (BS-32)
+//   R_BAD_CRC              -- CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT           -- CRC verify requested but the container carries no checksum
 //   R_OFFSET_TOO_LARGE     -- a u64 header/schema/directory offset exceeds 2^53-1
 //   R_NOT_PREFETCHED       -- syncRange over a shard that prefetchRange has not cached
 //   R_WRONG_MODE           -- preserve-mode container fed to the schema RangeReader
@@ -41,12 +47,15 @@
 //   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
+//   R_ABORTED              -- a reader-level { signal } fired: in-flight range I/O is
+//                             cancelled, resolved-after-abort bytes discarded, and a
+//                             foreign AbortError rejection is mapped here (BS-28)
 
 import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -60,11 +69,13 @@ const U32_MAX = 4294967295;
 const RANGE_READER_OPTS = {
   maxCachedShards: { t: 'int', min: 0, max: U32_MAX },
   verifyCrc: { t: 'bool' },
+  signal: { t: 'signal' },
 };
-const HTTP_ADAPTER_OPTS = { fetch: { t: 'fn' } };
+const HTTP_ADAPTER_OPTS = { fetch: { t: 'fn' }, signal: { t: 'signal' } };
 
 const CONTAINER_FOOTER_BYTES = 16;
 const CRC_ABSENT = 0xFFFFFFFF;
+const NOOP = function () {};
 
 function laneBytesOf(k) { return k === LANE_F64 ? 8 : (k === LANE_U32 ? 4 : 0); }
 
@@ -73,6 +84,12 @@ export class RangeReaderError extends Error {
 }
 function raiseRange(code, msg) { throw new RangeReaderError(code, msg); }
 
+// A reader-level signal fired: cancel in-flight range I/O. The one message for
+// every R_ABORTED site (pre-check, post-settle, foreign-AbortError mapping).
+function abortedError() {
+  return new RangeReaderError('R_ABORTED', 'range I/O aborted: the reader-level signal fired');
+}
+
 // 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
@@ -123,25 +140,42 @@ export class HTTPRangeAdapter {
     if (typeof fetchImpl !== 'function') {
       throw new RangeReaderError('R_TRUNCATED', 'no fetch() available in this environment');
     }
+    // Reader-level cancellation (BS-28). The adapter itself stays signal-stateless
+    // (one adapter may serve N readers); this signal governs only its own open().
+    const signal = opts.signal !== undefined ? opts.signal : null;
+    if (signal !== null && signal.aborted) throw abortedError();
     let size = -1;
-    // Try HEAD first.
+    // Try HEAD first (forward the signal so a real HEAD is cancellable).
     try {
-      const head = await fetchImpl(url, { method: 'HEAD' });
+      const head = await fetchImpl(url, { method: 'HEAD', signal });
       if (head.ok) {
         const cl = head.headers.get('content-length');
         if (cl) size = parseInt(cl, 10);
       }
     } catch { /* fall through */ }
+    // E1 (O-5): the HEAD's own rejection is swallowed by design. Re-check the
+    // signal after the catch and BEFORE the probe GET -- an abort during HEAD
+    // must not fire a second network request.
+    if (signal !== null && signal.aborted) throw abortedError();
     // Fallback: single-byte range GET.
     if (size < 0) {
-      const probe = await fetchImpl(url, { headers: { Range: 'bytes=0-0' } });
-      const cr = probe.headers.get('content-range');
-      if (cr) {
-        const m = cr.match(/\/(\d+)$/);
-        if (m) size = parseInt(m[1], 10);
+      try {
+        const probe = await fetchImpl(url, { headers: { Range: 'bytes=0-0' }, signal });
+        const cr = probe.headers.get('content-range');
+        if (cr) {
+          const m = cr.match(/\/(\d+)$/);
+          if (m) size = parseInt(m[1], 10);
+        }
+        // consume body so the connection doesn't hang
+        await probe.arrayBuffer();
+      } catch (err) {
+        // O-10: an abort landing mid-probe (fetch or drain) maps to R_ABORTED,
+        // symmetric with the E1-mapped HEAD path -- a foreign DOMException
+        // AbortError must not leak out of open(). A non-abort failure rethrows
+        // verbatim. Cold path; allocation here is fine.
+        if (signal !== null && signal.aborted) throw abortedError();
+        throw err;
       }
-      // consume body so the connection doesn't hang
-      await probe.arrayBuffer();
     }
     if (size < 0) throw new RangeReaderError('R_TRUNCATED', 'could not determine container size for ' + url);
     return new HTTPRangeAdapter(url, size, fetchImpl);
@@ -154,10 +188,11 @@ export class HTTPRangeAdapter {
     this.stats = { requests: 0, bytesFetched: 0 };
   }
 
-  async fetch(byteOffset, byteLength) {
+  async fetch(byteOffset, byteLength, signal) {
     const rangeEnd = byteOffset + byteLength - 1;
     const res = await this._fetch(this.url, {
       headers: { Range: 'bytes=' + byteOffset + '-' + rangeEnd },
+      signal,
     });
     if (!res.ok && res.status !== 206) {
       throw new RangeReaderError('R_TRUNCATED',
@@ -182,16 +217,23 @@ export class MockRangeAdapter {
     this.bytes = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
     this.size = this.bytes.length;
     this.log = [];    // [[offset, length], ...] for test assertions
+    // OBSERVATION-ONLY (O-2, BS-28): `signals` is index-aligned with `log` (null
+    // when no signal was forwarded); `lastSignal` is the most recent one. Neither
+    // changes behaviour -- `log` stays byte-identical.
+    this.signals = [];
+    this.lastSignal = null;
     this.stats = { requests: 0, bytesFetched: 0 };
   }
 
-  async fetch(byteOffset, byteLength) {
+  async fetch(byteOffset, byteLength, signal) {
     if (byteOffset + byteLength > this.size) {
       throw new RangeReaderError('R_ADAPTER_SHORT_READ',
         'mock adapter: request bytes=' + byteOffset + '-' + (byteOffset + byteLength - 1) +
         ' exceeds size ' + this.size);
     }
     this.log.push([byteOffset, byteLength]);
+    this.signals.push(signal !== undefined ? signal : null);
+    this.lastSignal = signal !== undefined ? signal : null;
     this.stats.requests++;
     this.stats.bytesFetched += byteLength;
     // Return a COPY so mutations by the caller don't affect the "source of truth".
@@ -219,6 +261,10 @@ export class RangeReader {
     opts = opts || {};
     this.adapter = adapter;
     this.maxCachedShards = opts.maxCachedShards !== undefined ? opts.maxCachedShards : 8;
+    // Reader-level cancellation (BS-28). null = no signal = the pre-MQ1 hot path
+    // (one property read in _fetchExact, zero race/listener allocation). A signal
+    // that has already fired makes this reader permanently dead for NEW I/O.
+    this._signal = opts.signal !== undefined ? opts.signal : null;
     this._footerCrc = CRC_ABSENT;
     // shard cache: shardIdx -> { payloadBytes, payloadDv, stringTable, lastAccess }
     this._shardCache = new Map();
@@ -498,7 +544,56 @@ export class RangeReader {
   // 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);
+    // HOT PATH (no signal): one property read is the entire legacy-path cost.
+    // The abort triangle + race live in the cold _fetchAborting (O-8). Collapsing
+    // the two is forbidden -- a reader without a signal reaches no listener, no
+    // race, no extra allocation.
+    if (this._signal === null) {
+      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;
+    }
+    return this._fetchAborting(byteOffset, byteLength, this._signal);
+  }
+
+  // COLD PATH (a signal is bound): the fail-closed triangle plus a race. See
+  // decisions/0013-range-abort.md and BS-28.
+  //   (a) pre-check  -- signal already fired -> R_ABORTED, ZERO adapter calls;
+  //   (b) race       -- adapter promise vs an abort promise, so a never-resolving
+  //                     fetch still rejects within the tick of the abort; the
+  //                     listener is removed on settle in BOTH directions;
+  //   (c) post-settle -- a signal-ignoring adapter that resolved anyway still
+  //                     yields R_ABORTED (bytes discarded, nothing cached); an
+  //                     adapter rejection while aborted maps to R_ABORTED (a
+  //                     foreign DOMException AbortError never leaks); a non-abort
+  //                     rejection rethrows verbatim; the short-read shape check
+  //                     runs only on the clean-resolve path.
+  async _fetchAborting(byteOffset, byteLength, sig) {
+    if (sig.aborted) throw abortedError();                       // (a)
+    const adapterP = this.adapter.fetch(byteOffset, byteLength, sig);
+    let onAbort = null;
+    const abortP = new Promise((_resolve, reject) => {
+      onAbort = function () { reject(abortedError()); };
+      sig.addEventListener('abort', onAbort, { once: true });
+    });
+    let buf;
+    try {
+      buf = await Promise.race([adapterP, abortP]);             // (b)
+    } catch (err) {
+      if (sig.aborted) {
+        adapterP.catch(NOOP);   // neutralize the loser: no late unhandledRejection
+        throw abortedError();   // foreign AbortError mapped; never leaks
+      }
+      throw err;                // non-abort rejection rethrows verbatim
+    } finally {
+      sig.removeEventListener('abort', onAbort);
+    }
+    if (sig.aborted) throw abortedError();                       // (c)
     if (!(buf instanceof Uint8Array) || buf.byteLength !== byteLength) {
       throw new RangeReaderError('R_ADAPTER_SHORT_READ',
         'adapter returned ' +

package/src/Reader.js

@@ -25,6 +25,8 @@
 //                              (Number() would lose precision; fail closed, BS-05)
 //   R_ROW_OUT_OF_RANGE       - get(rowIdx) with rowIdx negative, fractional, NaN,
 //                              or >= totalRows (BS-32)
+//   R_BAD_CRC                - CRC-32C verify requested and the stored checksum mismatched
+//   R_CRC_ABSENT             - CRC verify requested but the container carries no checksum
 //
 // Row-index policy (BS-32): get() range-checks rowIdx; the SHARD-index escape
 // hatches (shardPayload, shardF64, shardStringTable) do NOT -- their contract is
@@ -36,7 +38,7 @@ import { toContainerBuffer } from './Views.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/Split.js

@@ -2,6 +2,10 @@
 // Splitters + per-part compilation + container merge for parallel/checkpointed ingest.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   S_MERGE_EMPTY      - mergeContainers called with no inputs
+//   S_SCHEMA_MISMATCH  - parts carry incompatible schemas
+//
 // M6 covers three primitives that together enable worker-parallel or checkpoint-
 // resumable ingest against LBK1:
 //
@@ -38,7 +42,7 @@ import { StringTable } from './StringTable.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;
@@ -143,7 +147,7 @@ export function compilePart(bytes, opts) {
 // ---------- compileInParts ----------
 
 // Sequential convenience: split then compile each part serially.
-// Returns Uint8Array[] — one container per part. Equivalent output to running
+// Returns Uint8Array[] -- one container per part. Equivalent output to running
 // each part through a worker (or any parallel executor); use this when workers
 // aren't available or for testing.
 export function compileInParts(bytes, opts) {
@@ -237,7 +241,7 @@ export function mergeContainers(containers) {
   const outShardDirBytes  = totalShards * SHARD_ENTRY_BYTES;
 
   // Zone maps: emit iff container 0 has them AND all others do too.
-  // (MultiReader uses the same "all-or-none" policy — see MultiReader.d.ts.)
+  // (MultiReader uses the same "all-or-none" policy -- see MultiReader.d.ts.)
   const outHasZoneMaps = readers.every((r) => r.hasZoneMaps);
   const zoneMapsRaw = readers.map((r) => r.zoneMapsRaw());
   const T = outHasZoneMaps ? zoneMapsRaw[0].trackedFields.length : 0;
@@ -321,7 +325,7 @@ export function mergeContainers(containers) {
     outDv.setUint32(outMetadataOff + 4, totalShards, true);
     outDv.setUint32(outMetadataOff + 8, T, true);
     outDv.setUint32(outMetadataOff + 12, 0, true);
-    // Field index table (copied from container 0 — all containers share the schema)
+    // Field index table (copied from container 0 -- all containers share the schema)
     const fieldTableOut = outMetadataOff + zoneMapsHeaderLen;
     const tracked0 = zoneMapsRaw[0].trackedFields;
     for (let t = 0; t < T; t++) outDv.setUint16(fieldTableOut + t * 2, tracked0[t], true);

package/src/StringTable.js

@@ -2,6 +2,9 @@
 // Byte-level UTF-8 string interning with zero-alloc hot path.
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   ST_BLOB_OVERFLOW  - the blob or entry count would cross its u32 ceiling
+//
 // intern(bytes, from, to) -> u32 index, deduplicating identical byte ranges.
 // The hash path never allocates: bytes stay in the caller's buffer during
 // lookup, and internal storage grows in doubling steps.
@@ -14,7 +17,7 @@
 //   u8  blob[blob_length_bytes]
 //
 // The trailing sentinel makes `len(i) = offsets[i+1] - offsets[i]` uniform for
-// all i including the last — no branch in the reader hot path.
+// all i including the last -- no branch in the reader hot path.
 //
 // Entry 0 is always the empty string: the table reserves it in the constructor
 // and at every reset(), so an absent U32 row cell (which is 0) decodes as ""
@@ -38,7 +41,7 @@
 // TEST-ONLY: not re-exported from index.js, absent from the .d.ts and docs,
 // and carrying no semver guarantee.
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const EMPTY_SLOT = 0xFFFFFFFF;   // MUST be unsigned; typed-array reads are unsigned
 const INITIAL_BLOB_BYTES  = 64 * 1024;
@@ -256,7 +259,7 @@ export class StringTable {
   }
 
   // Static: parse a serialized table from a byte view. Returns a read-only
-  // accessor object (not a live StringTable — cheaper for the Reader path).
+  // accessor object (not a live StringTable -- cheaper for the Reader path).
   static parse(bytes, byteOffset) {
     const dv = new DataView(bytes.buffer, bytes.byteOffset + byteOffset, bytes.byteLength - byteOffset);
     const entryCount = dv.getUint32(0, true);
@@ -277,7 +280,7 @@ export class StringTableView {
     this._count = count;
     this._blob = blob;
     this._offsets = offsets;
-    this._decoder = null;   // lazy — created on first get()
+    this._decoder = null;   // lazy -- created on first get()
   }
 
   get count() { return this._count; }

package/src/Tokenizer.js

@@ -30,7 +30,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 const TOKENIZER_OPTS = {
@@ -88,6 +88,7 @@ const NS_EXP      = 7; // in exponent digits
 // correctly-rounded F64 via a single multiplication (positive exp) or single
 // division (negative exp) using this table. Outside that domain, correctly
 // rounded parsing requires David Gay's strtod, deferred to M4+.
+// See decisions/0012-clinger-fast-path.md.
 const POW10 = new Float64Array(23);
 POW10[0] = 1;
 for (let _pi = 1; _pi < 23; _pi++) POW10[_pi] = POW10[_pi - 1] * 10;
@@ -691,7 +692,7 @@ export class Tokenizer {
     const need = to - from;
     if (this._strLen + need > this._maxStringBytes) this._err('E_STRING_TOO_LONG', 'string exceeds maxStringBytes cap (' + (this._strLen + need) + ' > ' + this._maxStringBytes + ')');
     if (this._strLen + need > this._strBuf.length) this._growStrBuf(need);
-    // Manual copy loop — Uint8Array.set(source) via subarray allocates a small
+    // Manual copy loop -- Uint8Array.set(source) via subarray allocates a small
     // view header per call, which turns into MB-scale GC pressure across a
     // string-heavy fixture. The loop is boring but keeps the hot path allocation-free.
     const dst = this._strBuf;