@zakkster/lite-bake-stream 1.6.0 → 1.7.0

package/src/Views.js

@@ -1,6 +1,9 @@
 // @zakkster/lite-bake-stream / Views (internal)
 // Copyright (c) 2026 Zahary Shinikchiev. MIT.
 //
+// Error codes:
+//   W_BAD_SINK  - shared finalizeToSink guard: sink missing write/writeAt or async
+//
 // One shared helper so every container entry point (deserialize,
 // Reader.fromBuffer, PreserveReader.fromBuffer) resolves caller-supplied bytes
 // to an ArrayBuffer by exactly the SAME rule (BS-09). A Uint8Array that is a

package/src/Writer.js

@@ -11,6 +11,7 @@
 //     setInputSource; hand-driven Writers with no source sample by record
 //     count) buffered in a columnar staging area, per-field lane kind inferred
 //     from observed value types (number->F64, string->U32-into-string-table).
+//     See decisions/0011-sample-drain-reintern.md.
 //     null is lane-neutral (BS-20): it marks the field but sets no kind, so
 //     null+string infers U32 and null+number infers F64. A field that saw both
 //     a real number and a real string raises W_MIXED_LANE_TYPES at freeze.
@@ -52,6 +53,7 @@
 //   W_SCHEMA_TOO_WIDE          - a field offset exceeds the u16 offset_in_row ceiling
 //   W_FIELD_NAME_INVALID       - field name empty, non-string, or > 255 UTF-8 bytes
 //   W_FINALIZED                - a sink event or finalize() after finalize()
+//   W_BAD_SINK                 - finalizeToSink given a sink missing write/writeAt or async
 //   E_UNKNOWN_OPTION           - unknown constructor option key
 //   E_OPTION_VALUE             - constructor option value out of domain
 
@@ -60,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.0';
+export const VERSION = '1.7.0';
 
 const U32_MAX = 4294967295;
 // Post-finalize sentinel for _recordDepth. Chosen = 2 so every post-finalize
@@ -253,8 +255,8 @@ export class Writer {
     this._schema = null;                // { fields: [{name, laneKind, offsetInRow}], rowStride }
     this._fieldNamesUtf8 = null;
     this._fieldNameHashes = null;
-    this._fieldLaneKinds = null;        // Uint8Array — per-field LANE_* (fast dispatch)
-    this._fieldOffsets  = null;         // Uint16Array — per-field byte offset in row
+    this._fieldLaneKinds = null;        // Uint8Array -- per-field LANE_* (fast dispatch)
+    this._fieldOffsets  = null;         // Uint16Array -- per-field byte offset in row
     this._rowValueSlotsF64 = null;      // Float64Array<fieldCount> scratch
     this._rowValueSlotsU32 = null;      // Uint32Array<fieldCount> scratch
 
@@ -336,7 +338,7 @@ export class Writer {
     } else {
       // Sample window: decode to a JS string NOW. The tokenizer will reuse this
       // buffer for the value bytes before onNumber/onString fires, so we cannot
-      // defer decoding. String allocation here is expected — bounded to the
+      // defer decoding. String allocation here is expected -- bounded to the
       // sample window; steady-state post-freeze remains zero-alloc.
       this._currentKeyName = KEY_DECODER.decode(bytes.subarray(from, to));
     }

package/src/index.js

@@ -8,6 +8,10 @@
 //                           Set opts.preserve = true. Bytes in, same bytes out.
 // deserialize() auto-detects the mode via the container's flag bit and
 // returns the appropriate Reader.
+//
+// Error codes:
+//   E_OPTION_CONFLICT  - serialize() opts combine preserve with an incompatible framing
+//   R_TRUNCATED        - deserialize() container too small to inspect header flags
 
 import { Tokenizer, TokenizerError } from './Tokenizer.js';
 import { Writer, WriterError } from './Writer.js';
@@ -28,7 +32,7 @@ export {
   PreserveWriter, PreserveWriterError,
   PreserveReader, PreserveReaderError,
 };
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 const encoder = new TextEncoder();
 

package/types/MultiReader.d.ts

@@ -24,7 +24,7 @@ export class MultiReader {
   /** Which sub-Reader owns a given global shard? */
   readerForShard(globalShardIdx: number): { readerIdx: number; localShard: number } | null;
 
-  // Zone maps — global shard indices merged across sub-readers
+  // Zone maps -- global shard indices merged across sub-readers
   shardBounds(globalShardIdx: number, fieldName: string): Bounds | null;
   findShards(fieldName: string, opts?: FindShardsOptions): number[];
 }

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 {
@@ -86,7 +102,7 @@ export class RangeReader {
     get(rowIdx: number, fieldName: string): number | string | undefined;
   };
 
-  // Zone maps (M7) — synchronous, populated at open()
+  // Zone maps (M7) -- synchronous, populated at open()
   shardBounds(shardIdx: number, fieldName: string): Bounds | null;
   findShards(fieldName: string, opts?: FindShardsOptions): number[];
 }

package/types/Reader.d.ts

@@ -63,7 +63,7 @@ export class Reader {
   fieldIndex(name: string): number;
 
   /**
-   * Get value at (rowIdx, fieldName). F64 lane → number; U32 lane → string
+   * Get value at (rowIdx, fieldName). F64 lane -> number; U32 lane -> string
    * (resolved via the shard's local string table).
    */
   get(rowIdx: number, fieldName: string): number | string | undefined;

package/types/Split.d.ts

@@ -28,7 +28,7 @@ export interface CompileInPartsOptions extends SplitOptions, CompilePartOptions
 
 /**
  * Divide NDJSON bytes into N ranges at safe line boundaries. Every returned
- * range contains complete records — no split mid-line. The union of ranges
+ * range contains complete records -- no split mid-line. The union of ranges
  * equals the original bytes (no gaps, no overlaps).
  */
 export function splitNDJSON(bytes: Uint8Array, opts?: SplitOptions): SplitRange[];

package/types/Tokenizer.d.ts

@@ -5,7 +5,7 @@ export const VERSION: string;
 
 /**
  * Sink protocol the Tokenizer emits into. Byte ranges (bytes[from, to)) are
- * ephemeral — valid only for the duration of the call. Consumers that need
+ * ephemeral -- valid only for the duration of the call. Consumers that need
  * to retain content must copy or decode inside the sink method.
  */
 export interface TokenizerSink {

package/types/Writer.d.ts

@@ -78,7 +78,7 @@ export interface Container {
 export class Writer implements TokenizerSinkForWriter {
   constructor(opts?: WriterOptions);
   /**
-   * Sink protocol — the Tokenizer calls these. Byte ranges are ephemeral.
+   * Sink protocol -- the Tokenizer calls these. Byte ranges are ephemeral.
    */
   onStartObject(): void;
   onEndObject(): void;
@@ -127,7 +127,7 @@ export class Writer implements TokenizerSinkForWriter {
   readonly shardCount: number;
 }
 
-// Structural type — the Writer conforms to the Tokenizer's sink protocol.
+// Structural type -- the Writer conforms to the Tokenizer's sink protocol.
 // (Redeclared here so the /writer subpath is self-contained.)
 interface TokenizerSinkForWriter {
   onStartObject(): void;