@zakkster/lite-bake-stream 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,457 @@
+# Changelog
+
+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.0.0] — 2026-07-12
+
+First stable release. The LBK1 container format is frozen at `format_version: 1`.
+
+### Two ingest modes, one API
+
+- **Schema mode** (default): F64/U32 lane packing, zone-maps query pruning, byte-exact preservation for flat records. This is the mode the 8 GB soak below was run under.
+- **Preserve mode** (`serialize(input, { preserve: true })`): opaque byte blobs, any JSON shape. Deeply nested API responses, arrays, mixed types — all round-trip byte-for-byte identical. Reader exposes a tri-API: `getBytes(i)` (zero-alloc view), `getString(i)` (one `TextDecoder` allocation), `getJSON(i)` (opt-in `JSON.parse`).
+
+`deserialize()` reads the container's flag byte and returns the correct Reader automatically. The mode dispatch is transparent to callers unless they import `Reader` or `PreserveReader` directly.
+
+### Qualified on real hardware
+
+An 8 GB overnight soak on an M1 MacBook Pro, with both release gates armed:
+
+| | |
+| :-- | --: |
+| Source | 8.00 GB NDJSON |
+| Container | 4.89 GB (61.1% of source) |
+| Rows | 98,367,702 |
+| Shards | 119 |
+| Ingest wall | 1m14s |
+| Ingest throughput | 110.0 MB/s |
+| **Major GC** | **0** |
+| **Minor GC** | **0** |
+| **Total heap allocation** | **499.2 KB** |
+| Cells verified | 590,206,212 |
+| Verify wall | 3m37s |
+| **Preservation mismatches** | **0** |
+
+**499 KB of heap allocation to compile 8 GB of JSON.** Not per-shard, not per-second — total, for the entire run. Zero garbage collections of any kind. Every one of 590 million declared cells round-tripped byte-exact.
+
+Tokenizer bench on the same machine: **222.8 MB/s** on a 10 MB fixture, **237.0 MB/s** on 50 MB (min of 10 reps) — roughly 55% of `JSON.parse`'s raw throughput, while allocating no object graph at all. `JSON.parse` cannot process an 8 GB input on any heap; this can, on a 500 KB one.
+
+### Why this is 1.0.0 and not 0.x
+
+The format carries the forward-compat levers it needs to grow without a breaking change:
+
+- **`min_reader_version`** on every ShardEntry. A shard using a lane kind introduced in a future reader sets `min_reader_version: 2`; a v1 reader refuses cleanly at directory load, not on first bad read.
+- **Reserved field flags** in the schema block's FieldDescriptor, admitting the planned I64-preserved lane.
+- **`metadata_off`** as a block wrapper, not a zone-maps-specific pointer. Container-level string tables and columnar-mode metadata can land in the same slot.
+
+Planned additions — the I64 lane, columnar payload mode, container-level interning — all fit these seams. `format_version` stays at `1`.
+
+### Stability commitment
+
+Public API (the 9 documented subpath exports and their `.d.ts` declarations) follows semver from this tag forward. The `@internal`-marked accessors on `Reader` (`shardDirectoryOffset`, `zoneMapsRaw()`) exist for `Split.js`'s container surgery and carry no such guarantee.
+
+### Changed since the pre-release line
+
+- **Reader internal accessors.** `Split.js` was reaching into `Reader`'s underscore-prefixed fields (`_zoneMapsMins`, `_shardDirOff`, and four others) to perform container merges. Replaced with documented `@internal` accessors so a future `Reader` refactor can't silently break `mergeContainers`.
+- **CI (`.github/workflows/ci.yml`).** Both release gates now run on every push and PR: the 37-scenario torture harness (`maxMajor: 0` AND `verify: true`) plus a 500 MB preservation soak. Tests run across Node 18/20/22. The publish tarball is dry-run checked. The gates are enforced, not aspirational.
+
+---
+
+## [0.1.0-alpha.0] — pre-release development line
+
+### Fixed — critical: 32-bit offset overflow past 4 GiB containers
+
+Reported from an 8 GB overnight soak on an M1 MacBook (see run log): at row 81,369,452 of ~98M, verification failed with `got 8.118871342983516e-307, expected 81369452`. Ingest itself completed cleanly — the failure was on read-back.
+
+**Root cause.** `payload_off` in the shard directory (SPEC §3.4) was `u32`. Similarly, `schema_block_off`, `metadata_off`, and `shard_directory_off` in the header were `u32`. A container that grows past 2^32 bytes (~4.29 GB) has late-shard offsets beyond the u32 range; on write they were being truncated silently (`setUint32` accepts and masks JS numbers > 2^32), and on read they'd point at earlier bytes in the container. The reader then interpreted 8 bytes of arbitrary content as a Float64, producing subnormals like `8.1e-307`. Rows in shards whose payload sat below the 4 GB mark verified fine — the failure surfaced exactly where the boundary was crossed, at ~82% of an 8 GB soak (4.89 GB compiled container × 0.82 ≈ 4.0 GB).
+
+**Fix.**
+- Header layout grew from **32 to 48 bytes**. `schema_block_off`, `metadata_off`, `shard_directory_off`, and `total_rows` are all `u64`. Added an explicit `reserved1` at offset 36 to keep the layout 8-byte aligned.
+- `ShardEntry` layout grew from **32 to 40 bytes**. `payload_off` is now `u64` at offset 0; `payload_len` and `row_count` are `u32` at 8 and 12; `min_reader_version` and `flags` are `u16` at 16 and 18; `reserved` at 20; `local_string_off` and `local_string_len` are `u64` at 24 and 32.
+- `Writer.js`, `Reader.js`, `RangeReader.js`, and `Split.js` (`mergeContainers`) updated in lockstep — every offset field is now `setBigUint64`/`getBigUint64`.
+- SPEC §3.1 and §3.4 updated to reflect the new byte layouts.
+
+**Regression test.** `test/OffsetOverflow.test.js` — 4 tests that write and read offset values >2^32 through the actual DataView paths a Reader would use, verifying the u64 round-trip is byte-exact and that the new ShardEntry stride (40 bytes) is honored by second-shard reads. An 8 GB soak isn't feasible in CI, but the arithmetic property that failed at 4+ GB is directly covered.
+
+**Impact for pre-existing containers.** None — the format was pre-publish (0.1.0-alpha.0), no tagged release existed. Any pre-fix development containers must be regenerated. The wire-format version stays `1`.
+
+**Bench (also from the M1 MacBook run):** tokenizer clocked at **222.8 MB/s** on 10 MB and **237.0 MB/s** on 50 MB (min of 10 reps), running at ~55% of `JSON.parse`'s throughput while producing zero object allocations. Torture: 39/39 including 500 MB clean soak, zero GC.
+
+### Fixed — demo table CapacityError on 50k-row fixtures
+
+`lite-table` allocates one signal node per row for row-level reactivity; its internal pool caps around 1024 nodes. The demo mounted the full 50k-row synthetic fixture and blew the cap. Fixed by capping the mounted table at `MAX_TABLE_ROWS = 1000` and logging a warn banner steering users toward the RangeReader panel for browsing the full dataset. The ingest and RangeReader paths are unaffected — this is purely a demo UI budget.
+
+### Fixed — demo error message on non-JSON inputs
+
+Feeding `llms.txt` (or any file starting with a non-JSON byte) into the ingest panel produced `E_UNEXPECTED_BYTE: unexpected byte 0x23 at value position at byte 0` — technically correct but opaque. The demo now appends "— file does not look like JSON/NDJSON." when the failing byte is at position 0. Tokenizer behavior unchanged.
+
+### Added — M8 partial (Conformance + robustness gates)
+
+The M8 mandate has three sub-items: RFC 8259 conformance corpus, fuzzing, oscilloscope-rack demo. This ships the first two — the parts that strengthen the tokenizer's correctness story and belong in every release gate. The oscilloscope-rack demo remains its own project (multi-session UI work; targeted for after 0.1.0).
+
+- **`test/Conformance.test.js`** — 66 tests locking in strict RFC 8259 accept/reject behavior. Every fixture is either `MUST_ACCEPT` (strict valid JSON — tokenizer completes without error) or `MUST_REJECT` (invalid per RFC — tokenizer must throw `TokenizerError` with a stable `E_*` code). Categories cover:
+  - **Structural**: empty containers, nested forms, whitespace variants (spaces, tabs, CR, LF, CRLF), missing/extra commas, mismatched brackets, trailing commas, unquoted/single-quoted keys and values.
+  - **Strings**: empty, all standard escapes (`\"`, `\\`, `\/`, `\b`, `\f`, `\n`, `\r`, `\t`), `\uXXXX` at every Unicode plane boundary (U+0000, U+007F, U+FFFF, U+10000 via surrogate pair), raw UTF-8 multi-byte and 4-byte, adversarial rejections (unclosed strings, raw control chars per §7, lone high surrogate, bad escape).
+  - **Numbers**: integer, negative, zero (including -0), decimal, scientific (`e`, `E`, `+/-` sign, negative exponent), full decimal+exponent form, `Number.MAX_SAFE_INTEGER` and beyond (with documented F64 precision loss), rejections for leading zero (`01`), trailing decimal (`1.`), leading decimal (`.5`), bare exponent (`1e`), `NaN`, `Infinity`, hex (`0x1F`).
+  - **Literals**: `true`, `false`, `null`, plus rejections for `True`, `TRUE`, truncated `tru`.
+
+- **`test/Fuzz.test.js`** — 7 tests, each running hundreds of internal iterations. Proves the robustness invariant:
+  > For ANY byte sequence — valid, malformed, adversarial, random — the tokenizer either completes without error OR throws a `TokenizerError` with a stable `E_*` code. It never throws a non-`TokenizerError` exception, returns silent garbage, hangs, or corrupts internal state.
+  Fuzz categories:
+  - 500 rounds of pure-random bytes across every byte value 0x00–0xFF.
+  - 500 rounds of JSON-alphabet-only bytes (`{}[]":,. 0-9 e E letters`), which surfaces near-JSON malformed inputs. Asserts a diverse set of rejection codes to prove the fuzz exercises multiple failure paths.
+  - 200 rounds of generator-produced valid JSON — must round-trip cleanly.
+  - 500 rounds of single-byte mutation of valid JSON: response must be clean (accept or `E_*`).
+  - Truncation at every offset of 5 generated valid inputs.
+  - Chunk-boundary rehearsal at every byte-split position of 4 curated inputs; behavior must be identical to feeding the whole input at once.
+  - 100 rounds of NDJSON with random valid records.
+
+  Seed-driven so any failure is reproducible offline. On failure, the seed and up to 128 bytes of input are reported.
+
+### Baseline results (M8 partial)
+
+- **233 tests total** (73 new, 66 conformance + 7 fuzz). All green.
+- Fuzz iterations executed per run: **~2,300 tokenizer invocations across pure-random, JSON-alphabet, mutation, truncation, chunk-split, and NDJSON generators.** Zero non-`TokenizerError` exceptions, zero silent-garbage cases, diverse `E_*` code coverage observed.
+- 37/37 torture scenarios still pass. Zero major GC. Zero minor GC.
+- `npm publish --dry-run` still clean: 24 files, 64.3 kB packed.
+
+### Deferred to M8 (later)
+
+- **Oscilloscope-rack demo** — reel-to-reel tape transport, waterfall spectrum per shard, VU needles for MB/s and rows/sec, seven-segment counters. Release gate: locked 60 fps on iPhone 7 with 100 MB NDJSON. Multi-session UI project; the demo blueprint is documented in the memory system as the M8 north star.
+
+### Added — M6 (Split-and-merge primitive)
+
+The M6 mandate: enable parallel or checkpointed ingest without requiring a specific worker module. The primitives ship as pure functions that a caller can wire to any parallel executor (Web Workers, `worker_threads`, worker pools, no workers at all).
+
+- **`src/Split.js`** — four exports covering the full workflow:
+  - `splitNDJSON(bytes, {targetParts?, maxPartBytes?})` → `SplitRange[]`. Divides NDJSON bytes into N byte ranges at safe line boundaries. Every returned range contains complete records — no split mid-line. Union of ranges equals the original bytes (verified by test: concatenating `bytes.subarray(start, end)` across parts is byte-identical to the original).
+  - `compilePart(bytes, opts)` → `Uint8Array`. Compiles one byte range into a standalone LBK1 container via internal Tokenizer + Writer. Result is trivially `Transferable` across worker boundaries via `postMessage(buf, [buf])`.
+  - `compileInParts(bytes, opts)` → `Uint8Array[]`. Sequential convenience: split + compile each part serially. Same output shape as running each part through a worker; use this when workers aren't available or as a deterministic baseline against a worker-parallelized run.
+  - `mergeContainers([...Uint8Array | ArrayBuffer])` → `Uint8Array`. Concatenates N LBK1 containers into ONE. Verifies schema equivalence across inputs (rejects with `S_SCHEMA_MISMATCH` otherwise). Copies per-shard payloads and per-shard string tables verbatim; rewrites the shard directory offsets, header total counts, and zone-maps segment. Preserves the per-shard-independence property — merged shards remain independently decodable and range-fetchable.
+- **`test/M6.test.js`** — 16 tests: split-boundary safety (no mid-line cuts), concatenation-equals-original invariant, empty-input handling, single-line input (no natural split available), `maxPartBytes` ceiling honored, compilePart round-trip, compileInParts + MultiReader byte-exact equivalence with single-pass `serialize`, mergeContainers over 2 and 4 parts, mergeContainers vs MultiReader value equivalence, zone-maps preservation across merge, schema-mismatch rejection, empty-input rejection, ArrayBuffer input acceptance, single-container merge as no-op, and full split→compile→merge→verify pipeline via the universal verifier.
+- **`/split` subpath** added to `package.json` exports with matching `types/Split.d.ts`.
+
+### Design decisions locked in M6
+
+- **Parallelism-safe requires explicit schema.** If two workers ran sample-and-infer independently, they could infer different field orderings or lane kinds — outputs would then fail to merge. The docs specify that multi-part compilation MUST pass the same explicit schema to every part. For sample-and-infer with parts, compile part 0 first, extract `new Reader(container.buffer).schema`, and pass it to parts 1..N.
+- **MultiReader vs mergeContainers is a workload choice.** For query workloads over multiple parts, `MultiReader` (M4) is strictly better — it avoids the copy and works on containers still resident where they were produced (worker memory, IndexedDB, HTTP hosts). Use `mergeContainers` only when a single-file distributable is genuinely required (upload artifact, checkpoint file). Both paths verified to produce equivalent value queries.
+- **No workers in the box.** The Split module ships pure functions. Wire them to whatever parallel executor exists in your environment — the same code path works serially, in Web Workers, in `worker_threads`, in a worker pool, or in a distributed compute layer. The Split module is executor-agnostic by design.
+
+### Worker workflow example
+
+```js
+// Main thread
+import { splitNDJSON, mergeContainers } from '@zakkster/lite-bake-stream/split';
+import { MultiReader } from '@zakkster/lite-bake-stream/multi-reader';
+import { Reader } from '@zakkster/lite-bake-stream/reader';
+
+const parts = splitNDJSON(bytes, { targetParts: 4 });
+const containers = await Promise.all(parts.map(({ start, end }) =>
+  runInWorker('compilePart', bytes.subarray(start, end), { schema })
+));
+
+// Choice A: query across parts without a copy
+const multi = new MultiReader(containers.map(c => new Reader(c.buffer)));
+
+// Choice B: produce a single distributable
+const merged = mergeContainers(containers);
+```
+
+### Baseline results (M6)
+
+- 160 tests total (16 new). All green.
+- 37/37 torture scenarios still pass. Zero major GC. Zero minor GC.
+- `npm publish --dry-run` still clean: 24 files, 62.6 kB packed.
+
+### Added — M4 (Publish prep, convenience API, MultiReader)
+
+The M4 mandate: get the package to a publishable state and add the ergonomic wrappers most consumers actually want.
+
+- **`src/index.js`** — top-level convenience API. `serialize(input, opts)` accepts `Uint8Array` NDJSON, `string` NDJSON, `Iterable<object>` (records), `ReadableStream<Uint8Array>`, or `AsyncIterable<Uint8Array>`; returns `Uint8Array` for sync inputs, `Promise<Uint8Array>` for async. `deserialize(bytes)` returns a `Reader` from either a `Uint8Array` or `ArrayBuffer`; handles subarray offsets by copying to a fresh aligned buffer. Re-exports `Tokenizer`, `Writer`, `Reader`, `StringTable` and their error classes so a single `@zakkster/lite-bake-stream` import covers the common case.
+- **`src/MultiReader.js`** — logical union view over N `Reader` instances with matching schemas. Rows and shards are cumulatively addressed: rows 0..N₀ live in reader 0, N₀..N₀+N₁ in reader 1, etc. `findShards` merges per-reader results into a global shard-index space so query pruning works across the union. Rejects mismatched schemas at construction with `M_SCHEMA_MISMATCH`. Motivates the M6 split-and-merge story: split-and-merge doesn't strictly need a merge step if a `MultiReader` can serve queries directly over the split outputs.
+- **`test/M4.test.js`** — 18 tests: `serialize` for every input shape (bytes, string, records iterable, async iterable, ReadableStream) and its `deserialize` round-trip; `deserialize` handling subarray offsets; MultiReader single-reader passthrough parity, 4-reader boundary-walk, schema-mismatch rejection, empty-array rejection, `findShards` returning global indices across sub-readers, `shardBounds` routing to the correct sub-reader, out-of-range and unknown-field error paths.
+- **Root subpath `.`** and **`/multi-reader`** added to `package.json` exports. Every subpath now has a matching `.d.ts` file in `types/`.
+- **`types/` populated** — 8 hand-written `.d.ts` files (`Tokenizer`, `Writer`, `Reader`, `StringTable`, `RangeReader`, `FileIngest`, `MultiReader`, `index`) covering every public class, function, error type, and options interface. `import type { ... }` cross-references between them so consumers importing a single subpath still see referenced types.
+- **`LICENSE`** — MIT text, copyright Zahary Shinikchiev. Referenced by `package.json` and included in the tarball.
+- **`package.json` publish metadata** — `bugs.url`, `homepage`, `engines.node: ">=18"` added. `publishConfig.access: public` was already in place.
+
+### Publish gate
+
+`npm publish --dry-run` produces a clean tarball: 22 files, 55.2 kB packed, 193 kB unpacked. Files list: 8 `src/*.js`, 8 `types/*.d.ts`, 5 docs (README, CHANGELOG, SPEC, LICENSE, llms.txt), package.json. No warnings other than "not logged in" (expected for dry-run). The package is ready for `npm publish` from a machine with credentials.
+
+### Baseline results (M4)
+
+- 144 tests total (18 new). All green.
+- 37/37 torture scenarios still pass. Zero major GC. Zero minor GC.
+- Publish tarball verified via `--dry-run`.
+
+### Migration notes for consumers
+
+- **Common case (`serialize`/`deserialize`)**: `import { serialize, deserialize } from '@zakkster/lite-bake-stream';`. Bytes in → LBK1 bytes → Reader. Three lines.
+- **Advanced case (subpaths)**: import from `/tokenizer`, `/writer`, `/reader`, `/range-reader`, etc. for finer control. Tree-shakers drop unused paths (`sideEffects: false`).
+- **New import**: `@zakkster/lite-bake-stream/multi-reader` provides `MultiReader` for joining multiple LBK1 containers into one logical stream — worker-parallel compilation output, checkpoint/resume sessions, split-and-merge without the merge.
+
+### Added — M7 (Zone maps)
+
+The M7 mandate: enable query pruning. A filter like "rows where `x` in [800, 900]" should touch only the shards whose bounds overlap that range — not every shard. On HTTP Range fetches (M5), each skipped shard is one round-trip saved.
+
+- **SPEC §3.6 — Zone Maps Segment.** New optional segment placed between shard directory and first shard payload. Layout: `'ZM01'` magic + shard count + tracked field count + reserved, then field-index table (u16 per tracked field), then row-major `f64 mins[shard * T + t]` and `f64 maxes[shard * T + t]`. Header offset 12 (formerly reserved for container-level string table) is now `metadata_off` — `0` means no zone maps. Bumped SPEC section 3.7 to accommodate.
+- **`src/Writer.js`** — Per-shard, per-F64-field min/max tracked on the row-commit hot path. `_trackedFieldToPos` (Int32Array) dispatches from schema field index → tracking position in O(1). Sample drain path also updates bounds. On finalize, snapshot each shard's `mins`/`maxes` into the shard record. `_assembleContainer` emits the zone maps segment before shard payloads and wires the header's `metadata_off`. U32/string fields are not tracked in v1 (dictionary-level bounds are M8+ material).
+- **`src/Reader.js`** — `_parseZoneMaps` reads the segment if `metadata_off != 0`, otherwise no-op. Zero-copy `Float64Array` views over the container buffer for `mins`/`maxes`. New public API:
+  - `reader.hasZoneMaps` — boolean
+  - `reader.shardBounds(shardIdx, fieldName)` → `{min, max} | null` (null for U32 fields, missing zone maps, or unknown fields)
+  - `reader.findShards(fieldName, {min?, max?})` → `shardIdx[]` — every shard whose bounds overlap `[min, max]`. Falls back to all shards when zone maps or the field's tracking is absent (correct query-planner semantics).
+- **`src/RangeReader.js`** — Zone maps fetched ONCE in the open phase (16-byte segment header + one range for the body), then `shardBounds` and `findShards` are synchronous. The query-pruning workflow becomes: `open()` → `findShards()` → `loadShard()` only on covering shards. Each skipped shard is one HTTP Range fetch saved. Locked in by the acceptance test: `findShards('id', {min: 800, max: 900})` on a 1000-row / ~10-shard container returns 2 shards, and reading them triggers exactly 2 additional adapter fetches — zero for the skipped 8.
+- **`test/ZoneMaps.test.js`** — 10 tests: `hasZoneMaps` state, per-shard min/max correctness against scan-verified values, null return for U32 fields and unknown fields, `findShards` overlap semantics (inclusive on both endpoints), unbounded query returns all shards, U32-field fallback returns all shards, RangeReader parity with base Reader, and the **shard-fetch-pruning proof**: `findShards` runs synchronously (zero adapter fetches) and reading the returned shards triggers exactly `shardsWanted.length` additional fetches.
+
+### Design decisions locked in M7
+
+- **Zone maps sit between shard directory and shard payloads.** Rationale: any Reader that fetches header + schema + directory can extend that Range to include zone maps in one round-trip on HTTP/2. Placing them at a distant offset would cost an extra request for every open.
+- **F64 lanes only.** String bounds require dictionary-level min/max (canonical string ordering), which needs the container-level string table (M4+). Deferred as clearly-out-of-scope for M7.
+- **Overlap semantics for `findShards`:** a shard is included iff `smin <= max && smax >= min`. This is inclusive on both endpoints — a shard whose max exactly equals the query's min is still included (its rows may match `<=` predicates). Callers wanting strict-less-than semantics filter the returned shards further.
+- **No zone maps when the schema is all-U32.** The writer sets `metadata_off = 0` when `T === 0`; a Reader loading an all-string schema sees `hasZoneMaps === false` and `findShards` falls back to returning every shard. No overhead, no wasted bytes.
+
+### Migration notes
+
+- Containers written before M7 have `metadata_off = 0` and work unchanged. Readers built after M7 handle them via the fallback path (no zone maps → `findShards` returns all shards, `shardBounds` returns `null`).
+- The header field at offset 12 was formerly documented as `string_table_off` (reserved). Any consumer that read that value literally will still see `0` for any container the writer produced through M6 — it never wrote a non-zero value there.
+
+### Baseline results (M7)
+
+- 126 tests total (10 new). All green.
+- 37/37 torture scenarios still pass. Zero major GC. The zone-map writes on the row-commit path are branchless (`v < min` / `v > max` compare-and-assign against a `Float64Array`) and cache-friendly. No throughput regression measured.
+- Query-pruning demonstration: on a 1000-row container with ~10 shards (2 KB target), querying `id in [500, 550]` returns exactly the 1-2 covering shards, verified by scan-based ground truth. The RangeReader path fetches only those shards' payloads.
+
+### Added — M5 (Browser reader, HTTP Range, File.stream ingest)
+
+The M5 mandate: run the whole pipeline in a browser. Client-side ingest of a local JSON file to an LBK1 container. Remote LBK1 exploration via HTTP Range without downloading the whole file. Reference demo bridging both to `@zakkster/lite-table`.
+
+- `src/RangeReader.js` — LBK1 reader with lazy shard loading via an IO adapter. On `open()`, fetches exactly 3 byte ranges (header 32B, schema block, shard directory) regardless of container size — every shard's byte extents are known without touching a single row. On `get(rowIdx, fieldName)`, fetches only the containing shard's payload + local string table in ONE range request (they're contiguous by SPEC 3.4), caches with LRU eviction bounded to `maxCachedShards`, decodes byte-identical to the base Reader. Also exposes `prefetchRange(firstRow, lastRow)` for viewport-driven prefetch and `syncRange(firstRow, lastRow)` for await-free reads after prefetch.
+- `HTTPRangeAdapter` (in RangeReader.js) — production adapter using `fetch()` with `Range: bytes=off-end` headers. Discovers `Content-Length` via HEAD, falling back to a single-byte range GET for CDNs that block HEAD. Tracks `stats.requests` and `stats.bytesFetched`.
+- `MockRangeAdapter` (in RangeReader.js) — in-memory adapter backed by a `Uint8Array`. Records every fetch as `{offset, length}` for test assertions. Used by the demo to prove the RangeReader path against a container just built in the browser, no server required.
+- `src/FileIngest.js` — `ingestStream(readableStream, opts)` and `ingestFile(blob, opts)`. Piped chunks flow through the existing Tokenizer + Writer; `onProgress` fires per chunk with `{bytesIngested, totalBytes, rowsWritten, shardsCommitted, elapsedMs}`. Works with any `ReadableStream<Uint8Array>` — `File.stream()` in browsers, `fetch()` bodies, Node's `Readable.toWeb()` in Node 18+.
+- `test/RangeReader.test.js` — 13 tests locking in: exactly-3 open-phase fetches (regardless of shard count), single-request combined payload+string-table fetches, byte-identical parity with the base Reader across a 200-row corpus, LRU eviction bounds cache to `maxCachedShards`, cache hits trigger zero additional fetches, `prefetchRange` covers exactly the required shards, `syncRange` refuses uncached shards, error paths (bad magic, row out of range, unknown field), adapter stats accumulation.
+- `test/FileIngest.test.js` — 8 tests: round-trip parity with 1-byte, 7-byte, and 4KB chunks (worst-case chunk-boundary bugs), `onProgress` monotonic progression, blob-like `.size` and `.stream()` recognition, writer options pass-through (schema + shard sizing), rejection of non-Uint8Array chunks.
+- Public getter `reader.buffer` on the base Reader — required for the demo's ingest → RangeReader handoff without reaching into private state.
+- `/file-ingest` and `/range-reader` subpath exports in `package.json`.
+
+### Added — M5 demo (`demo/`)
+
+Single-file HTML + one module JS + one importmap, oscilloscope-adjacent theme (phosphor green oklch tokens with hex fallback, CRT grid backdrop, JetBrains Mono). Three tabbed scenes matching the demo blueprint:
+
+1. **Ingest** — drag-and-drop a JSON/NDJSON file OR generate a synthetic 50k-row fixture. Progress bar and per-chunk MB/s. Container stats (rows, shards, source size, container size, compression ratio, throughput).
+2. **Explore** — mounts `@zakkster/lite-table` over the ingested Reader. Row source is an integer-index array; column accessors call `reader.get(rowIdx, fieldName)` on demand. This is the trick that keeps a million-row table O(viewport) in memory: no row materialization, ever.
+3. **Range reader** — `MockRangeAdapter` over the ingested container bytes; opens a `RangeReader` and shows every `(offset, length)` fetch it makes in a live log. Row-by-row `get()` demonstrates cache hits vs shard-fetch behavior.
+
+Import map routes `@zakkster/lite-signal`, `@zakkster/lite-virtual`, `@zakkster/lite-signal-dom`, `@zakkster/lite-table` to esm.sh; `@zakkster/lite-bake-stream/*` subpaths to the sibling `../src/*.js` files. `npm run demo` serves via `npx serve`.
+
+### Design decisions locked in M5
+
+- **RangeReader is a separate class, not a mode of Reader.** The base Reader's sync API is right for its use case (in-memory containers, tight loops, no `await` overhead). Async row access needs different ergonomics: `prefetchRange` for viewport-driven fetches, `syncRange` for the render pass, per-shard LRU. Sharing the LBK1 constants + `StringTable` between the two classes is fine; sharing the parse code is not.
+- **One range request per shard access.** Per-shard payload and local string table are placed contiguously by the writer (SPEC 3.4). The RangeReader always fetches the combined range in one request — HTTP/2 pipelining is nice but a single request is nicer. Saves round-trips at the cost of pulling the string table even when reading only F64 fields; documented as intentional.
+- **Row source for lite-table is integer indices, not row objects.** For a million-row table this is a 4 MB `Uint32Array` (or 8 MB regular Array) instead of 100+ MB of materialized row objects. Column accessors reach into the Reader on demand. The demo shows a 50k-row fixture; the same code scales to 1M+ without changing the shape.
+
+### Baseline results (M5 tests)
+
+116 tests total across 7 files. **All 116 pass.** RangeReader against a 1000-row container:
+- Open phase: exactly 3 fetches (header 32B + schema block + shard directory).
+- Per-shard access: exactly 1 additional fetch per unique shard touched.
+- Cache hits (repeat reads on same shard): 0 additional fetches, verified across 50 reads.
+- Eviction: bounded to `maxCachedShards`, verified with cap=2.
+- Byte-level parity with base Reader: 100% across 200 rows × 3 fields = 600 cells.
+
+### Added — M3 soak session (CLI-configurable scale + real-hardware qualification)
+
+- `bench/soak.js` — CLI-configurable soak entry point. Sized from the command line (`--mb=N` or `--gb=N`), preservation gate opt-in via `--verify`, progress output every 200 MB during ingest and every 500K rows during verify. Fixture generator is memory-bounded (streams directly into a pre-allocated Uint8Array via `TextEncoder.encodeInto`), enabling arbitrary-scale runs without OOM on the source. Reports ingest throughput, verify throughput, container compression ratio, and zero-GC gate result.
+- `npm run soak` (100 MB), `soak:500` (500 MB), `soak:1gb` (1 GB), `soak:overnight` (8 GB) scripts. Sized for M4 Pro qualification and macOS `caffeinate` overnight runs on older machines.
+- `test/_verify.js` — REWRITTEN with bounded memory. Single-pass byte iteration, JSON.parse per line, discard. No line-array accumulator. Memory steady-state is flat regardless of row count. Verified 500 MB / 6.12M rows / 36.75M cells without heap growth.
+- Torture scenario `writer-string-sample-multi-shard-drain` — lock-in for the bug below. Reproduces the sample-drain-crosses-multiple-shards case with verify:true, so this regression can never come back silently.
+
+### Fixed — Multi-shard sample drain lost strings past shard 0
+
+The 100 MB soak's preservation gate caught it on the first run. Every row past shard 0 boundary (row 838860 in the failing scenario) read back `undefined` for its string field.
+
+**Root cause:** `_drainSampleToShards` handed the sample's shared string table to shard 0, then `_finalizeCurrentShard` serialized it and immediately reset it in place. Shard 1's rows still contained U32 indices that referenced the (now-empty) shared table, and shard 1's local string table was empty. Only shard 0 had populated string content. Bug was silent unless the sample overflowed one shard's row capacity — 400K+ record datasets with any string field. Tests and torture didn't catch it because their sample sizes fit inside one shard.
+
+**Fix:** Per-shard re-interning during drain. `_drainSampleToShards` now allocates a fresh `StringTable` for the drain path, then for each U32 cell looks up the original bytes in the sample's table via `sampleTable.bytesAt(sampleIdx)` and re-interns into the per-shard table. Each drained shard ends up with a tight, self-contained string table holding exactly the strings its rows reference. Preserves the per-shard independence property (SPEC 3.3) that makes M5 HTTP Range fetches work.
+
+**Added:** `StringTable.bytesAt(idx)` — zero-copy byte range lookup for entry `idx`. Used by the drain path.
+
+### Baseline results (M3 soak)
+
+Reproducible on the sandbox environment (Node 22, not particularly fast hardware):
+
+| Scale | Ingest | Verify | Rows | Cells | GC |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 100 MB | 24.7 MB/s | 386K rows/s | 1.25M | 7.48M | 0 major, 0 minor |
+| 500 MB | 24.5 MB/s | 375K rows/s | 6.12M | 36.75M | 0 major, 0 minor |
+
+Ingest and verify throughput are essentially flat across the 5× scale jump — no per-row overhead compounds. Zero-GC gate holds through both. Container compression is stable at ~62% of source (NDJSON → LBK1). Real hardware (M4 Pro etc.) will substantially exceed these numbers.
+
+### Added — M3 addendum (Preservation contract)
+
+The M3 mandate: prove that any data going into the pipeline round-trips out unchanged. Implemented in three complementary layers so no regression can slip through unnoticed:
+
+- **`test/_verify.js`** — universal round-trip verifier. Parses source NDJSON with `JSON.parse` (ground truth), walks it against `Reader.get(rowIdx, fieldName)` for every declared field of every row. Not zero-alloc; runs OUTSIDE the GC-measured band by design. This is the correctness oracle used by both tests and torture.
+- **`test/DataPreservation.test.js`** — property-based fuzz. 23 tests including 12 seeded random-shape corpora (500 rows × 6 fields, random field names, random lane assignments) plus sample-and-infer variants plus a 10K-row 4KB-shard multi-shard preservation gauntlet plus edge cases (extreme F64, adversarial UTF-8, dedupe correctness).
+- **`test/NumericBoundary.test.js`** — 8 tests that pin the F64 fast-path / slow-path boundary. Asserts EXACT round-trip for the guaranteed domain (≤15 sig digits, |exp| ≤ 22) and pins ≤1 ULP drift for known slow-path values. Any regression in the number parser trips these before it can reach production.
+- **Torture-scale verification** — `bench/torture.js` gained a `verify: true` opt-in that runs `verifyRoundTrip` on the assembled container AFTER the GC band closes. Twelve scenarios opted in cover **73,500 rows value-exact per fast-tier run**. The `verified` column in the torture report shows the row count actually checked; any failure blocks the run.
+
+### Changed — Tokenizer: Clinger's fast-path decimal→F64 parser
+
+The property-based fuzz surfaced a real preservation bug. The old naive parser computed `intPart + fracPart/fracDiv * Math.pow(10, exp)` — three sequential floating-point ops, each rounding independently, plus `Math.pow(10, exp)` itself is not exact for many exponents. Result: values like `3.53` decoded to `3.5300000000000002` (1 ULP high). This violated the "same data after parse" invariant for arbitrary decimals, not just extreme edge cases.
+
+Fixed by implementing Clinger's fast-path algorithm:
+- Precomputed `POW10[0..22]` table with exact IEEE 754 doubles for `10^k` (built by iterated multiplication from 1.0 — no rounding).
+- Track `_numFracDigits` and `_numDigitsSeen` counters during accumulation.
+- At emit, if `digitsSeen ≤ 15` AND `|netExp| ≤ 22`, assemble mantissa as an exact u53 integer and do a SINGLE multiply (positive exp) or SINGLE divide (negative exp) by `POW10[|netExp|]`. This is provably correctly-rounded within that domain.
+- Outside the fast path, fall back to the old naive computation (documented as ≤1 ULP drift).
+
+Impact:
+- **Fast-path domain covers >99% of realistic JSON numbers** (integer IDs, prices, ratios, timestamps, coordinates, scientific within `1e±22`).
+- **`long-numbers-200-digits` throughput: 139 → 195 MB/s** (+40%; fast path skips `Math.pow`).
+- **No other throughput regression** in the fast tier (measured across 36 scenarios).
+- **Zero-GC gate held**: torture still passes with `maxMajor: 0` on every writer scenario.
+
+Correctly-rounded parsing across the FULL F64 domain (David Gay `strtod` or Ryu-style algorithm) is now on the M4+ backlog. It would eliminate the residual ≤1 ULP slow-path drift for values with 16+ significant digits or extreme exponents.
+
+### Added — SPEC section 7: Round-trip preservation contract
+
+Explicit, table-form contract stating what the format preserves and how. Covers F64 fast/slow paths, U32 byte-exact strings, coercions (`true`/`false`/`null`), missing-field defaults, unknown-key drop, wrong-type rejection. Backed by references to the specific test files that assert each guarantee. This is now the single source of truth consumers can point to when asked "will this preserve my data?".
+
+### Baseline results (M3 addendum fast tier)
+
+36 scenarios, ~1.9s total wall time. **All 36 pass**; 12 opted into round-trip verification, covering 73,500 rows value-exact. Zero major GC, zero minor GC across every scenario, both ingestion and verification.
+
+### Added — M3 (String-table subpath)
+
+- `src/StringTable.js` — byte-level UTF-8 string interning. Open-addressed hash table (Uint32Array) with linear probing, FNV-1a hash filter, byte-compare on hit. Zero-alloc hit path (no JS string materialized during intern). Growing blob (Uint8Array, 2× doublings) and offsets (Uint32Array, 2× doublings). Serializable to the LBK1 per-shard string-table layout with a trailing sentinel offset so `len(i) = offsets[i+1] - offsets[i]` is branch-free for the reader. `StringTable.parse` returns a zero-copy `StringTableView` for the Reader path.
+- `src/Writer.js` — String value support end-to-end. Sample-and-infer now tracks per-field observed kind (unknown / number / string / mixed); fields that saw only numbers become F64 lanes, only strings become U32 lanes, mixed fields raise `W_MIXED_LANE_TYPES` at schema freeze. Row stride is variable based on lane sizes (F64=8, U32=4, padded to 8-byte multiple). Explicit schema now accepts both the M2 back-compat form `fields: ['a', 'b']` (all F64) and the M3 form `fields: [{name:'a', laneKind:'f64'}, {name:'tag', laneKind:'u32'}]`. Per-shard string table lifecycle: sample's string table becomes shard 0's local table on drain, then resets in place for subsequent shards (per-shard independence for HTTP Range / worker-parallel readers).
+- `src/Reader.js` — Parses per-shard string tables via `StringTable.parse`, exposes `get(rowIdx, fieldName)` that resolves F64 or U32→string transparently. New API surface: `shardPayload` / `strideBytes` / `offsetBytes` / `laneKind` / `shardStringTable`. Back-compat `shardF64` / `strideF64` / `offsetF64` still work for pure-F64 schemas.
+- `test/StringRoundTrip.test.js` — 15 M3 acceptance tests: StringTable unit sanity (dedup, serialize round-trip, hash resize preserves entries), sample-and-infer (pure string → U32 lane, mixed numeric+string schemas, mixed-lane rejection), explicit schema (U32 lanes, unknown laneKind rejection, cross-lane value rejection), string dedup verification (low-cardinality, unicode byte-exact, JSON escapes, empty strings), multi-shard string tables (each shard self-contained).
+- `bench/_string-torture-fixtures.js` — string workload fixtures: low-cardinality tags, high-cardinality slugs (all unique), realistic mixed (low-card + high-card + numeric), unicode across 1/2/3/4-byte codepoints, identical-string repeats, 200-byte long strings, empty strings, mixed-lane pathological.
+- 8 new M3 torture scenarios in `bench/torture.js`. Fast tier grew from 28 to 36 scenarios; total wall time 1.6s. **All 36 pass with `maxMajor: 0`**; the hottest scenario (20K identical-string interns) allocates only 100 KB across the entire pipeline.
+- `/string-table` subpath export in `package.json`.
+
+### Design decisions locked in M3
+
+- **Per-shard string tables** (not container-level) as the v1 default. Rationale: streaming ingestion writes shards independently — the container-level string-table location cannot be filled until the last shard is known, which would defeat the writer's shard-first architecture. Per-shard tables also enable single-Range HTTP fetches to include a shard's string data alongside its payload, which is the M5 story. Container-level tables remain a possibility for M4+ wrap-up.
+- **F64 vs U32 lane inference** is by first-observed value type. A field seen with only numbers becomes F64; only strings becomes U32; mixed fails at schema freeze. Explicit schema mode always wins; consumers who need `"0"` (string) vs `0` (number) discrimination must declare the schema.
+- **Missing string fields default to U32 index 0**, which decodes to whatever string was interned first in that shard. Documented as intentional; not a bug. Consumers who need "field is absent" semantics should coerce absent → sentinel string in the source data.
+- **Per-shard reset semantics**: the sample's string table becomes shard 0's. When shard 0 finalizes, the table is serialized (into a caller-owned byte copy) and then reset in place. Subsequent shards fill the same table object with fresh entries. This keeps peak memory bounded to the LARGEST shard's string cardinality, not the container total.
+
+### Bugs found and fixed in M3
+
+- **`EMPTY_SLOT` sign bug in StringTable**: the initial sentinel was `0xFFFFFFFF | 0` which evaluates to `-1` (signed), but `Uint32Array[i]` reads back as `4294967295` (unsigned). The strict-equal check never matched, causing infinite linear probing on the first `intern()`. Fix: `EMPTY_SLOT = 0xFFFFFFFF` (unsigned). Classic JS foot-gun; documented inline in `StringTable.js`.
+- **Ephemeral-buffer overlap in Writer.onKey (sample mode)**: the sample-window path stored a reference to the tokenizer's ephemeral `_strBuf` byte range for the key, then decoded it later in `onNumber` / `onString`. But `_strBuf` is reused for the VALUE emission between the two calls (documented in SPEC 5.3), so by the time the decode ran, the key bytes had been overwritten. Symptom: field name `"tag"` decoded to `"aag"` because the value `"a"` had landed at position 0. Fix: decode the key to a JS string immediately in `onKey`, in the same call. String allocation here is expected — bounded to the sample window; steady-state post-freeze remains zero-alloc. Post-schema-frozen path was always correct (resolved to field-index immediately).
+
+### Baseline results (M3 fast tier)
+
+36 scenarios, 1.6s total wall time. **Zero major GC across every scenario**, including:
+
+| Scenario | Rows | MB/s | Heap alloc |
+| --- | ---: | ---: | ---: |
+| `writer-string-identical-20k` (pure hit path) | 20,000 | 20.3 | 100 KB |
+| `writer-string-low-cardinality-10k` | 10,000 | 6.8 | 212 KB |
+| `writer-string-high-cardinality-5k` (all inserts, full blob growth) | 5,000 | 3.8 | 163 KB |
+| `writer-string-long-2k` (400 KB total blob) | 2,000 | 9.0 | 106 KB |
+| `writer-string-realistic-mixed-5k` (sample-and-infer, 4 fields) | 5,000 | 3.4 | 194 KB |
+
+The identical-20k scenario is the tightest possible interning gate: every intern is a hit, and total heap alloc is ~5 bytes per record (essentially the record-loop overhead). String field ingestion is now proven zero-GC by CI, not just claimed.
+
+### Breaking changes vs M2 error taxonomy
+
+- `W_STRING_VALUE_UNSUPPORTED` is REMOVED. Strings are now supported. Sending a string to a field declared as F64 (explicit or inferred) now raises `W_LANE_MISMATCH` — a more precise error that also fires in the opposite direction (number to a U32 lane).
+- New error codes: `W_MIXED_LANE_TYPES` (sample-and-infer saw both types in the same field), `W_LANE_MISMATCH` (post-freeze type conflict), `W_UNKNOWN_LANE_KIND` (explicit schema declared a laneKind that isn't `'f64'` or `'u32'`).
+
+### Deferred to M4
+
+- `serialize()` / `deserialize()` first published tag.
+- Multi-container reader (join multiple LBK1 files).
+- Container-level string table (opposite of per-shard: single dedup across all shards, requires writer to buffer all shards until final drain). Suitable for offline transcoding pipelines.
+
+### Added — M2 Session B (Writer + Reader + Round-trip)
+
+- `src/Writer.js` — LBK1 shard emitter, Tokenizer sink implementation. Explicit-schema and sample-and-infer modes. F64-only lanes (v1). 32 MB fixed shard boundaries (configurable via `targetShardBytes`). Zero-alloc record commit post-schema-freeze via byte-compare field lookup with FNV-1a filter.
+- `src/Reader.js` — LBK1 container parser. Header + schema + shard directory parse. Per-shard `Float64Array` views. Hot-loop-friendly `shardF64` / `strideF64` / `offsetF64` for direct typed-array indexing. Strict rejection of non-zero field flags and non-F64 lanes (v2 will accept extended lanes).
+- `test/RoundTrip.test.js` — end-to-end acceptance suite: bytes → tokenize → write → LBK1 → read → verify. 16 tests covering sample-and-infer, explicit schema, multi-shard, F64 range boundaries, boolean/null coercion, container structural checks, and reader hot-loop helpers.
+- `bench/_writer-torture-fixtures.js` — writer-specific adversarial fixtures: homogeneous records, late field appearance, missing fields, F64 range boundary walk, multi-shard boundary crossing, top-level-number rejection, nested-object/array rejection, string-value rejection, empty records.
+- 10 new writer torture scenarios in `bench/torture.js`, extending the mechanical zero-GC gate to the full ingestion pipeline. Total fast tier: 28 scenarios, all pass with `maxMajor: 0` and `maxMinor: 0`.
+- `/writer` and `/reader` subpath exports in `package.json`, preserving the tree-shakeable single-file-per-entry convention.
+
+### Design decisions locked in Session B
+
+- **Sample-and-infer** buffers records in a columnar SoA staging area (`Map<fieldName, Float64Array>`). At the sample threshold (default = one shard's worth), the schema is frozen by insertion order, staging is drained into shard 0, and subsequent records write directly into the current shard's pre-allocated `ArrayBuffer`. All allocations happen inside the sample window; post-freeze is zero-alloc per record.
+- **Field lookup** uses an FNV-1a hash filter over interned name buffers, followed by a byte-compare on hash match. This gives O(N) worst case with N = field count (typically 5-20) but zero string allocation per `onKey` call.
+- **Unknown keys** (fields not in the frozen schema) are silently ignored, matching `lite-bake` core behavior.
+- **Missing fields** default-fill to 0 on the shard row, matching `lite-bake`.
+- **Booleans and null** coerce to F64: `true → 1`, `false → 0`, `null → 0`. Documented; predictable.
+- **Nested objects/arrays and string values** are rejected with distinct writer error codes (`W_NESTED_UNSUPPORTED`, `W_STRING_VALUE_UNSUPPORTED`). String values return in M3 via the string-table subpath.
+
+### Baseline results (Session B fast tier)
+
+28 scenarios, ~1 second total wall time. **Zero major GCs, zero minor GCs across every scenario, tokenizer and writer combined.** The writer's hottest scenario (`writer-homogeneous-10k`): 10K records ingested, container assembled, 112 KB heap growth for the whole pipeline including the sample window's staging arrays. That heap footprint is bounded to the sample window; steady-state per-record allocation is zero, verified by CI.
+
+### Deferred to M3
+
+- String-table subpath (`@zakkster/lite-bake-stream/string-table`): per-shard UTF-8 blob + U32 offset index, pre-allocated typed-array hash-map interning. Enables the writer to accept `onString` events instead of rejecting them.
+- Shard payload micro-optimization: keep the pre-allocated 32 MB ArrayBuffer instead of copying used bytes into a right-sized `Uint8Array` at shard finalization. Eliminates one allocation per shard boundary.
+- Reader HTTP Range support (`@zakkster/lite-bake-stream/reader-http`), for browser consumers.
+
+### Added — M2 Session A (torture harness)
+
+- `bench/torture.js` — CI-ready adversarial-input harness with fast (~1s) and full (~5min) tiers. Every scenario runs under `@zakkster/lite-gc-profiler` with `maxMajor: 0` as the mechanical release gate.
+- `bench/_torture-fixtures.js` — deterministic, seeded fixture generators covering: pathological nesting (up to and past MAX_DEPTH), adversarial escapes/unicode/surrogates, buffer-growth boundary strings, F64-limit numbers, 200-digit numbers, malformed inputs (unterminated string/array, invalid escape, unclosed-array attack), and multi-strategy chunk arrival (whole/fixed/random/single-byte).
+- `npm run torture` and `npm run torture:full` scripts.
+- `@zakkster/lite-gc-profiler` as a devDependency.
+
+### Changed — M1.1 (driven by torture-harness findings)
+
+- `Tokenizer._appendStrRange` — removed `Uint8Array.set(chunk.subarray(from, to), ...)` in favor of a manual byte-copy loop. The `subarray` was allocating a small view header (~50 bytes) per contiguous string byte run; on string-heavy fixtures this translated to megabytes of GC pressure. Measured impact on the fast tier: 12× reduction in escape-cycle-1mb heap alloc, 630× reduction in unicode-cycle-1mb, 30× reduction in 4 MB chunked ingestion; throughput up 67% (88→147 MB/s) on chunked NDJSON.
+
+### Baseline results (Session A)
+
+Fast tier: 18 scenarios, 575 ms total wall time, **all pass with maxMajor: 0 AND maxMinor: 0**. Soak scenario (500 MB clean NDJSON): 124 MB/s sustained, 56 KB heap growth across the entire run (0.011% overhead). Mechanical zero-GC on gigabyte-scale ingestion is now proven by CI, not just claimed.
+
+### Added — M0 / M1
+
+- `SPEC.md` — LBK1 container format draft 0.1. Header, schema block with reserved forward-compat flags, string-table segment, shard directory with `min_reader_version`, container footer, extended-lane table reserving `I64_BYTES_PRESERVED` / `U64_BYTES_PRESERVED`.
+- `src/Tokenizer.js` — chunk-safe UTF-8 JSON SAX scanner. `auto` / `array` / `ndjson` framing. Byte-level number parsing. All standard escapes, surrogate pairs, error codes with absolute `byteOffset`.
+- `test/Tokenizer.test.js` — 33 conformance tests including byte-split boundary fuzz across four fixtures and single-byte-chunk streaming.
+- `bench/bench-tokenizer.js` — 10 interleaved reps, 3 warmups, min-of-reps headline. Baselines against `JSON.parse` per-line and wrapped-array.
+- Package exports map with `sideEffects: false` and single subpath `/tokenizer`.
+
+### Notes
+
+- No published tag yet; format may change until M4.
+- Tokenizer throughput after the M1.1 subarray fix: 124 MB/s sustained on a 500 MB clean NDJSON fixture. String-heavy adversarial fixtures land between 20 MB/s (escape-cycle) and 300 MB/s (unicode-cycle-1mb).
+- The `chunk-single-byte-64kb` scenario shows ~6 MB heap growth: this is caller-side, not tokenizer-side (the harness's `feedSingleByte` allocates 64k subarray views to synthesize the pathological chunking). Documented as expected; not a target for the mechanical gate.
+
+
+- `bench/torture.js` — CI-ready adversarial-input harness with fast (~1s) and full (~5min) tiers. Every scenario runs under `@zakkster/lite-gc-profiler` with `maxMajor: 0` as the mechanical release gate.
+- `bench/_torture-fixtures.js` — deterministic, seeded fixture generators covering: pathological nesting (up to and past MAX_DEPTH), adversarial escapes/unicode/surrogates, buffer-growth boundary strings, F64-limit numbers, 200-digit numbers, malformed inputs (unterminated string/array, invalid escape, unclosed-array attack), and multi-strategy chunk arrival (whole/fixed/random/single-byte).
+- `npm run torture` and `npm run torture:full` scripts.
+- `@zakkster/lite-gc-profiler` as a devDependency.
+
+### Changed — M1.1 (driven by torture-harness findings)
+
+- `Tokenizer._appendStrRange` — removed `Uint8Array.set(chunk.subarray(from, to), ...)` in favor of a manual byte-copy loop. The `subarray` was allocating a small view header (~50 bytes) per contiguous string byte run; on string-heavy fixtures this translated to megabytes of GC pressure. Measured impact on the fast tier: 12× reduction in escape-cycle-1mb heap alloc, 630× reduction in unicode-cycle-1mb, 30× reduction in 4 MB chunked ingestion; throughput up 67% (88→147 MB/s) on chunked NDJSON.
+
+### Baseline results (Session A)
+
+Fast tier: 18 scenarios, 575 ms total wall time, **all pass with maxMajor: 0 AND maxMinor: 0**. Soak scenario (500 MB clean NDJSON): 124 MB/s sustained, 56 KB heap growth across the entire run (0.011% overhead). Mechanical zero-GC on gigabyte-scale ingestion is now proven by CI, not just claimed.
+
+### Added — M0 / M1
+
+- `SPEC.md` — LBK1 container format draft 0.1. Header, schema block with reserved forward-compat flags, string-table segment, shard directory with `min_reader_version`, container footer, extended-lane table reserving `I64_BYTES_PRESERVED` / `U64_BYTES_PRESERVED`.
+- `src/Tokenizer.js` — chunk-safe UTF-8 JSON SAX scanner. `auto` / `array` / `ndjson` framing. Byte-level number parsing. All standard escapes, surrogate pairs, error codes with absolute `byteOffset`.
+- `test/Tokenizer.test.js` — 33 conformance tests including byte-split boundary fuzz across four fixtures and single-byte-chunk streaming.
+- `bench/bench-tokenizer.js` — 10 interleaved reps, 3 warmups, min-of-reps headline. Baselines against `JSON.parse` per-line and wrapped-array.
+- Package exports map with `sideEffects: false` and single subpath `/tokenizer`.
+
+### Notes
+
+- No published tag yet; format may change until M4.
+- Tokenizer throughput after the M1.1 subarray fix: 124 MB/s sustained on a 500 MB clean NDJSON fixture. String-heavy adversarial fixtures land between 20 MB/s (escape-cycle) and 300 MB/s (unicode-cycle-1mb).
+- The `chunk-single-byte-64kb` scenario shows ~6 MB heap growth: this is caller-side, not tokenizer-side (the harness's `feedSingleByte` allocates 64k subarray views to synthesize the pathological chunking). Documented as expected; not a target for the mechanical gate.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.