@zakkster/lite-bake-stream 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] -- 2026-09-02
+
+MQ1 -- abortable range reads (BS-28). RangeReader gains reader-level cancellation so a mount/unmount consumer (lite-query's abort-on-detach law) can cancel in-flight range I/O instead of orphaning it.
+
+### Added
+- `RangeReader` constructor / `RangeReader.open` accept `{ signal }` (an AbortSignal-shaped object); `HTTPRangeAdapter.open` accepts and forwards `{ signal }` into its HEAD + probe GET. One signal governs the reader's lifetime; once it fires the reader is permanently dead for new I/O (design A, decisions/0013-range-abort.md).
+- Additive adapter contract: `fetch(byteOffset, byteLength, signal?)`. A 2-arg adapter degrades cancellation only, never correctness -- every shipped 1.6.1 adapter and call site stays conformant byte-for-byte.
+- One new thrown code `R_ABORTED` (pinned same-diff in test/RangeAbort.test.js); inventory 60 -> 61 codes / 0 unpinned. The fail-closed triangle: a pre-aborted signal requests zero bytes; a hanging adapter still rejects within the tick of the abort; resolved-after-abort bytes are discarded and nothing is cached. A foreign `AbortError` rejection while aborted maps to `R_ABORTED` (never leaks); a non-abort rejection rethrows verbatim.
+- The abort listener is removed on settle in both directions, so a long-lived (page-lifetime) signal retains nothing (t7-soak abort retention witness; the swallow lens is BREAK id `r`). New t9 in-process control `(q)` proves the pre-aborted-open assertion bites; named controls 16 -> 17.
+- `MockRangeAdapter` gains observation-only `signals` (index-aligned with `log`) and `lastSignal`; the `log` shape stays byte-identical.
+- decisions/0013-range-abort.md; test/RangeAbort.test.js.
+
+### Changed
+- Opts.js gains a `{ t: 'signal' }` descriptor: a malformed signal fails closed with the existing `E_OPTION_VALUE` (shape-check -- aborted boolean + addEventListener/removeEventListener -- not instanceof, so a cross-realm signal is accepted). No new validation code.
+
+Suite: 519 -> 530 tests / 530 pass / 0 fail / 0 todo. Torture 44 fast / 47 full; t9 controls 16 -> 17. BREAK matrix adds `r` (BAKE_TORTURE_BREAK=r exits non-zero). All 16 version sites move to 1.7.0 at this release; the one grep skip is decisions/0013's historical "shipped 1.6.1 adapter" compat statement.
+
 ## [1.6.1] -- 2026-09-02
 
 M7 -- docs, comment prose, and two new guards. No src logic, no API surface change (exports map, error codes, and types signatures all unchanged; inventory 60 codes / 0 unpinned).

package/README.md

@@ -13,7 +13,7 @@
 ![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
 
-**Status:** v1.6.1. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak with zero GC and byte-exact preservation across 590 million cells.
+**Status:** v1.7.0. LBK1 format frozen at `format_version: 1`. Qualified on an 8 GB soak with zero GC and byte-exact preservation across 590 million cells.
 
 ## The gigabyte-scale JSON front door the ecosystem was missing
 
@@ -164,7 +164,8 @@ Every subpath also exports a `VERSION` const.
   plus zone-map query APIs `shardBounds(shardIdx, field)` and
   `findShards(field, range)`.
 - `RangeReader` (`/range-reader`) -- HTTP Range lazy shard loading; synchronous
-  query pruning after open.
+  query pruning after open. Optional `{ signal }` cancels in-flight range I/O
+  (`R_ABORTED`); once it fires the reader is dead for new I/O.
 - `MultiReader` (`/multi-reader`) -- logical union over N Readers sharing a
   schema.
 - `splitNDJSON`, `compilePart`, `compileInParts`, `mergeContainers` (`/split`) --
@@ -220,7 +221,7 @@ the torture gate):
 | :----- | :----------------------------------------------------------------- |
 | `E_`   | `TokenizerError` (e.g. `E_NUMBER_OVERFLOW`)                        |
 | `W_`   | `WriterError` (`W_MIXED_LANE_TYPES`, `W_LANE_MISMATCH`, `W_BAD_SINK`, `W_FINALIZED`) |
-| `R_`   | `ReaderError` / `RangeReaderError` (`R_ROW_OUT_OF_RANGE`, `R_OFFSET_TOO_LARGE`, `R_BAD_CRC`, `R_CRC_ABSENT`, ...) |
+| `R_`   | `ReaderError` / `RangeReaderError` (`R_ROW_OUT_OF_RANGE`, `R_OFFSET_TOO_LARGE`, `R_BAD_CRC`, `R_CRC_ABSENT`, `R_ABORTED`, ...) |
 | `M_`   | `MultiReaderError` (`M_ROW_OUT_OF_RANGE`)                          |
 | `S_`   | `SplitError`                                                       |
 | `ST_`  | `StringTableError` (`ST_BLOB_OVERFLOW`)                            |
@@ -243,7 +244,8 @@ const containers = compileInParts(parts);
 const merged = mergeContainers(containers);
 
 // 3. open the merged container and prune shards before fetching them
-const reader = await RangeReader.open(adapterOver(merged));
+//    (pass { signal } to cancel in-flight range I/O when the consumer detaches)
+const reader = await RangeReader.open(adapterOver(merged), { signal: controller.signal });
 const shards = reader.findShards('id', { min: 500, max: 999 });
 for (const s of shards) reader.get(s.firstRow, 'id');
 ```
@@ -316,7 +318,7 @@ The gates run at scales chosen to fit different hardware and time budgets:
 
 | Command | Scale | Use |
 | :-- | :-- | :-- |
-| `npm test` | 519 tests across 36 files | Dev loop, every save |
+| `npm test` | 530 tests across 37 files | Dev loop, every save |
 | `npm run torture` | 44 fast scenarios (~1 MB each) | Before every commit |
 | `npm run torture:full` | 47 scenarios incl. the 500 MB soak | Before every publish |
 | `npm run soak` | 100 MB with preservation gate | Sanity check |

package/SPEC.md

@@ -297,7 +297,7 @@ Subpath entries carved so consumers pay only for what they import. Each entry is
 | `@zakkster/lite-bake-stream/reader` | LBK1 parser over an in-memory `ArrayBuffer`. Synchronous. Zone-maps query APIs. |
 | `@zakkster/lite-bake-stream/string-table` | Byte-level UTF-8 interning primitive. |
 | `@zakkster/lite-bake-stream/file-ingest` | Browser helper: `File.stream()` -> Reader. Any `ReadableStream<Uint8Array>` works. |
-| `@zakkster/lite-bake-stream/range-reader` | LBK1 parser with lazy shard loading via an IO adapter. HTTP Range fetch or in-memory mock. Synchronous zone-maps pruning. |
+| `@zakkster/lite-bake-stream/range-reader` | LBK1 parser with lazy shard loading via an IO adapter. HTTP Range fetch or in-memory mock. Synchronous zone-maps pruning. Optional reader-level `{ signal }` cancels in-flight range I/O (`R_ABORTED`); the adapter `fetch(byteOffset, byteLength, signal?)` contract is additive (a 2-arg adapter degrades cancellation only). |
 | `@zakkster/lite-bake-stream/multi-reader` | Logical union over N Reader instances. Rows and shards cumulatively addressed; findShards merges across sub-readers. |
 | `@zakkster/lite-bake-stream/split` | NDJSON splitter + per-part compile + container merge. Executor-agnostic -- wire to any worker pool or run serially. |
 

package/llms.txt

@@ -8,13 +8,13 @@ Ingest gigabyte-scale JSON (top-level array or NDJSON) into the LBK1 binary cont
 
 ## Status
 
-v1.6.1 -- 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.1)
+## Public API (v1.7.0)
 
 Two ingest modes share one top-level API:
 
@@ -27,7 +27,7 @@ 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.
 
@@ -64,6 +64,7 @@ Every declared field of every row round-trips. F64 lanes: bit-exact for numeric
 - 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

package/package.json

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

package/src/FileIngest.js

@@ -31,7 +31,7 @@ import { PreserveWriter } from './PreserveWriter.js';
 import { PreserveReader } from './PreserveReader.js';
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.1';
+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.1';
+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

@@ -18,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.
@@ -51,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)
@@ -119,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

@@ -37,7 +37,7 @@ import { toContainerBuffer } from './Views.js';
 import { checkOpts } from './Opts.js';
 import { crc32cInit, crc32cUpdate, crc32cFinal } from './Crc32c.js';
 
-export const VERSION = '1.6.1';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/PreserveTokenizer.js

@@ -41,7 +41,7 @@
 
 import { checkOpts } from './Opts.js';
 
-export const VERSION = '1.6.1';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 const PRESERVE_TOKENIZER_OPTS = {

package/src/PreserveWriter.js

@@ -26,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.1';
+export const VERSION = '1.7.0';
 
 export class PreserveWriterError extends Error {
   constructor(code, msg) { super(msg); this.code = code; this.name = 'PreserveWriterError'; }

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.
@@ -43,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.1';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;
@@ -62,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); }
 
@@ -75,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
@@ -125,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);
@@ -156,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',
@@ -184,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".
@@ -221,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();
@@ -500,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

@@ -38,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.1';
+export const VERSION = '1.7.0';
 
 const CONTAINER_HEADER_BYTES = 48;
 const SHARD_ENTRY_BYTES = 40;

package/src/Split.js

@@ -42,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.1';
+export const VERSION = '1.7.0';
 
 const LF = 0x0A;
 const CONTAINER_HEADER_BYTES = 48;

package/src/StringTable.js

@@ -41,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.1';
+export const VERSION = '1.7.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.6.1';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 const TOKENIZER_OPTS = {

package/src/Writer.js

@@ -62,7 +62,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.1';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 // Post-finalize sentinel for _recordDepth. Chosen = 2 so every post-finalize

package/src/index.js

@@ -32,7 +32,7 @@ export {
   PreserveWriter, PreserveWriterError,
   PreserveReader, PreserveReaderError,
 };
-export const VERSION = '1.6.1';
+export const VERSION = '1.7.0';
 
 const encoder = new TextEncoder();
 

package/types/RangeReader.d.ts

@@ -8,7 +8,12 @@ export const VERSION: string;
 
 export interface IOAdapter {
   size: number;
-  fetch(byteOffset: number, byteLength: number): Promise<Uint8Array>;
+  /**
+   * `signal` is ADDITIVE (BS-28): a 2-arg adapter that ignores it degrades
+   * CANCELLATION only, never correctness -- the reader-side fail-closed triangle
+   * guarantees the outcome regardless of whether the adapter honoured the signal.
+   */
+  fetch(byteOffset: number, byteLength: number, signal?: AbortSignal): Promise<Uint8Array>;
 }
 
 export interface AdapterStats {
@@ -17,11 +22,11 @@ export interface AdapterStats {
 }
 
 export class HTTPRangeAdapter implements IOAdapter {
-  static open(url: string, opts?: { fetch?: typeof fetch }): Promise<HTTPRangeAdapter>;
+  static open(url: string, opts?: { fetch?: typeof fetch; signal?: AbortSignal }): Promise<HTTPRangeAdapter>;
   readonly url: string;
   size: number;
   stats: AdapterStats;
-  fetch(byteOffset: number, byteLength: number): Promise<Uint8Array>;
+  fetch(byteOffset: number, byteLength: number, signal?: AbortSignal): Promise<Uint8Array>;
 }
 
 export class MockRangeAdapter implements IOAdapter {
@@ -29,8 +34,12 @@ export class MockRangeAdapter implements IOAdapter {
   size: number;
   /** Fetch log: [[offset, length], ...] for test assertions. */
   log: [number, number][];
+  /** Observation only (BS-28): index-aligned with `log`, null when no signal forwarded. */
+  signals: (AbortSignal | null)[];
+  /** Observation only (BS-28): the most recently forwarded signal (or null). */
+  lastSignal: AbortSignal | null;
   stats: AdapterStats;
-  fetch(byteOffset: number, byteLength: number): Promise<Uint8Array>;
+  fetch(byteOffset: number, byteLength: number, signal?: AbortSignal): Promise<Uint8Array>;
 }
 
 export interface RangeReaderOptions {
@@ -38,6 +47,13 @@ export interface RangeReaderOptions {
   maxCachedShards?: number;
   /** Verify the footer CRC-32C at open; rejects R_BAD_CRC on mismatch, R_CRC_ABSENT if absent. */
   verifyCrc?: boolean;
+  /**
+   * Reader-level cancellation (BS-28). One signal governs the reader's whole
+   * lifetime. Once it fires the reader is permanently DEAD for NEW I/O -- every
+   * fetch throws R_ABORTED. Already-cached shards stay readable through
+   * syncRange. A remount makes a new reader with a new signal (design A).
+   */
+  signal?: AbortSignal;
 }
 
 export interface RangeShardHandle {