@zakkster/lite-stream 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 1.2.0 -- 2026-09-02
+
+**The law's gate, able to fail.** A torture harness that proves the package's
+own claims -- including the zero-steady-state-allocation sentence that has been
+unverified since 1.0.0 -- plus the drift guards that keep docs, exports, and
+ASCII honest, a `VERSION` export, and the LS-11 packaging cleanup. No behavior
+change: the only `Stream.js` code change is the additive `VERSION` const.
+
+### Added
+
+- **Torture harness** -- `test/torture.mjs` + `test/torture/s0-s8`, run by
+  `npm run torture` (`node --expose-gc test/torture.mjs`): metamorphic laws
+  (s0), degenerate values and hostile iterators (s1), async-iteration protocol
+  conformance (s2), API abuse with a decided policy per case (s3), seeded
+  fuzz-vs-oracle (s4), the allocation gate (s5, `@zakkster/lite-gc-profiler`,
+  `maxMajor` 0 with per-scenario byte budgets), a retention soak (s6,
+  `@zakkster/lite-leak` WeakRef census), the StreamQuery conformance corpus and
+  TimeoutError duck-pact (s7), and the controls tier (s8). Prints `ok`, exits
+  0/1; `TORTURE_SEED` replays a failure; `STREAM_TORTURE_BREAK=<s0..s8|1>` arms
+  each tier's injected breakage so every tier's control exits non-zero.
+- **Scripts** -- `torture`, `torture:control` (all-tiers break lane), and
+  `test:floor`. `verify` gains `torture`. **LS-09 amendment:** the floor lane
+  runs `npm test` ONLY against the pinned peer -- `@zakkster/lite-leak` peers
+  `@zakkster/lite-signal >= 1.5.0`, so pinning `1.2.2` alongside it would put
+  lite-leak outside its supported peer range; torture (which imports lite-leak)
+  runs against the resolved latest only. Fail closed: never run a tool outside
+  its peer range.
+- **`VERSION` export** (LS-05) -- a string that always equals the installed
+  `package.json` version. Declared in `Stream.d.ts`; documented in llms.txt and
+  the README API reference with no embedded version literal. Never re-exported
+  by consumers (suite ruling). The `Stream.d.ts` `TimeoutError` type declaration
+  was also added (the shipped runtime export had no type; the surface-guard
+  requires three-way parity).
+- **`test/09-guards.test.mjs`** (5 tests) -- ascii-guard (every `files[]` +
+  `test/`/`bench/`/`demo/` byte is printable ASCII or LF, empty allowlist) and
+  surface-guard (runtime exports == llms.txt import list == `Stream.d.ts` value
+  exports; `VERSION` string-equals `package.json` version; the declared peer is
+  present in both docs). Each family carries an inline failing control.
+- **devDependencies** -- `@zakkster/lite-leak ^1.10.0` and
+  `@zakkster/lite-gc-profiler ^1.16.0` (torture only; not runtime deps).
+
+### Changed
+
+- **`files[]` drops `ROADMAP.md`** (LS-11) -- the roadmap is a working doc, not
+  a shipped artifact. llms.txt's Files section and the CHANGELOG [1.1.0]
+  forward-reference were reworded so tarball readers are not pointed at an
+  unshipped file.
+- **`test` / `test:gc` globs scoped to `test/*.test.mjs`** so the `node:test`
+  runner does not discover the torture files.
+
+### Fixed
+
+- Docs and packaging only; no runtime behavior changed.
+
+### Known issues
+
+- **LS-13** (S1, opened this release, fix targeted for 1.3.0) -- a `next()`
+  result object whose `done` or `value` is a throwing getter escapes the pump's
+  `.then` onFulfilled uncaught: it surfaces as an unhandledRejection and
+  `fromAsyncIterable` never reaches a terminal state (it should transition to
+  the error state). Torture tier s1 reproduces it with a bounded sentinel and a
+  scoped rejection capture and prints it as `TODO(LS3, LS-13)` in the gate
+  output; it does not fail the gate. This refutes the "iterator throws -> error
+  state" triplet leg for the throwing-getter shape specifically.
+
+### Testing
+
+- **90 tests** across `test/01-*` through `test/09-*` (up from 85), 0 fail,
+  0 skip under `npm test` and `npm run test:gc`.
+- `npm run torture` -> `ok`, ~1.8s wall (node v26.3.1, macOS arm64,
+  2026-09-02); zero steady-state majors in every s5 scenario.
+- `npm run test:floor` -> FLOOR-PASS (`npm test` 90/0 against
+  `@zakkster/lite-signal@1.2.2`) and LATEST-PASS (`npm test` 90/0 + torture ok
+  against the resolved `@zakkster/lite-signal@1.5.0`). The `^1.2.0` peer floor
+  is now a tested fact, not a claim.
+- s5 budget doctrine: per-scenario `maxBytesPerOp` budgets (32 B/op for the
+  caught-up toAsyncIterable and pipeToSignal steady pump; 16 B/op for the
+  by-design fromAsyncIterable state-object and waiter-heavy paths), each ~3x the
+  measured 3-pass peak; the global `maxMajor` rule never widens.
+
+---
+
 ## 1.1.1 -- 2026-09-01
 
 **Truth patch. No API change, no behavior change; the `Stream.js` diff is
@@ -65,9 +147,9 @@ corrected, and the previously dark GC tier now gates on the default test run.
 ## 1.1.0 -- 2026-07-10
 
 **Additive `toAsyncIterable` enrichment.** Six additions, no breaking
-changes. All 1.0.0 callers continue to work without modification. See
-ROADMAP.md's "Shipped in 1.1.0" section for the triggering signals that
-justified each addition.
+changes. All 1.0.0 callers continue to work without modification. Each
+addition below records the triggering signal that justified it; the
+`Added` and `Changed` entries in this section stand on their own.
 
 ### Added
 

package/README.md

@@ -249,6 +249,16 @@ Treat this as the secondary API for classic "consume signal changes"
 patterns; for the streaming pipeline case (paginated APIs, SSE, pubsub)
 the forward direction is what most consumers want.
 
+### VERSION
+
+```ts
+VERSION: string
+```
+
+A string that always equals the installed `package.json` version. Consumers
+do NOT re-export it (suite ruling); the surface-guard asserts the equality on
+every test run.
+
 ## Modes: latest vs buffer
 
 Pick `"latest"` when you only care about the most recent value:
@@ -486,7 +496,7 @@ target.
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-85 tests across `test/01-*` through `test/08-*`:
+90 tests across `test/01-*` through `test/09-*`:
 
 - `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
   Iterable acceptance variants, pre-aborted, subscriber observability
@@ -506,6 +516,11 @@ target.
   (LS-01: disposing a result/target signal does NOT stop the pump;
   LS-04: a pending `next()` on a disposed source never settles, `timeout`
   is the only escape hatch)
+- `09-guards.test.mjs` -- drift guards: ascii-guard (every shipped +
+  test/bench/demo byte is printable ASCII or LF) and surface-guard (runtime
+  exports == llms.txt == Stream.d.ts, VERSION == package.json version, the
+  declared peer is present in both docs). Each family carries an inline
+  failing control proving the guard can fail.
 
 Run via `npm test`.
 
@@ -525,10 +540,23 @@ retained as an alias.
 `bench/bench.mjs` -- six scenarios; throughput and B/op retained. Run via
 `npm run bench`.
 
+### Tier 4 -- torture (retention + alloc gate + controls)
+
+`npm run torture` (`node --expose-gc test/torture.mjs`) runs tiers s0-s8
+sequentially -- metamorphic laws, degenerate values, protocol conformance,
+API abuse, seeded fuzz-vs-oracle, the s5 per-scenario allocation gate
+(maxMajor 0), a lite-leak retention soak, the StreamQuery conformance corpus,
+and the controls tier. It prints `ok` and exits 0 on success.
+`STREAM_TORTURE_BREAK=<s0..s8|1>` arms one tier's (or every tier's) injected
+breakage so the control lane exits non-zero; `npm run torture:control` runs
+the all-tiers form. `npm run test:floor` runs `npm test` against the peer
+floor `@zakkster/lite-signal@1.2.2` and then `npm test` + torture against the
+resolved latest, printing both verdicts.
+
 No `package-lock.json` is committed: devDependencies float within their
 stated ranges, and correctness against the peer floor is proven by running
-the suite against `@zakkster/lite-signal@1.2.2` rather than by pinning a
-lockfile.
+`npm run test:floor` against `@zakkster/lite-signal@1.2.2` rather than by
+pinning a lockfile.
 
 ## What this is not
 

package/Stream.d.ts

@@ -135,3 +135,16 @@ export function toAsyncIterable<T>(
     sig: Signal<T> | Computed<T>,
     opts?: ToAsyncIterableOptions
 ): AsyncIterable<T> & { readonly droppedCount: number };
+
+/**
+ * Thrown when the `timeout` option on `toAsyncIterable` elapses. Structurally
+ * identical to `@zakkster/lite-await`'s TimeoutError (`e.name === "TimeoutError"`
+ * duck-checks work across both packages); not imported -- lite-stream stays zero-dep.
+ */
+export declare class TimeoutError extends Error {
+    readonly name: "TimeoutError";
+    readonly timeout: number;
+}
+
+/** Package version string; always equals the installed package.json version. */
+export declare const VERSION: string;

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.1.1
+// @zakkster/lite-stream 1.2.0
 //
 // Zero-GC bridge between async iterators and @zakkster/lite-signal. The
 // multi-shot dual of lite-await's fromPromise: project an async source of N
@@ -873,3 +873,7 @@ export {
     toAsyncIterable,
     TimeoutError
 };
+
+// Always equals the installed package.json version (single source of truth is
+// package.json; the /release drill bumps both sites in the same commit).
+export const VERSION = "1.2.0";

package/llms.txt

@@ -14,7 +14,7 @@ Peer dep: `@zakkster/lite-signal ^1.2.0`.
 
 ## Imports
 
-    import { fromAsyncIterable, pipeToSignal, toAsyncIterable, TimeoutError } from "@zakkster/lite-stream";
+    import { fromAsyncIterable, pipeToSignal, toAsyncIterable, TimeoutError, VERSION } from "@zakkster/lite-stream";
 
 ## Exports
 
@@ -120,6 +120,12 @@ Structurally identical to `@zakkster/lite-await`'s TimeoutError so
 `e.name === "TimeoutError"` duck-checks work across both packages. Not
 imported from lite-await -- lite-stream stays zero-dep.
 
+### `VERSION`
+
+String, always equals the installed package.json version. Not re-exported
+by consumers (suite ruling); the surface-guard asserts the equality on
+every test run.
+
 ## Cleanup termination triplet
 
 `fromAsyncIterable` ends on exactly three paths, all structural:
@@ -278,7 +284,7 @@ Per-yield, `fromAsyncIterable` latest mode allocates one wrapper state
 object; buffer mode adds one snapshot array. `toAsyncIterable` `mode:
 "latest"` allocates zero on the steady-state hot path when the consumer
 is caught up; `mode: "buffer"` also zero when no waiter is pending
-(structural claim; gated by the alloc tier in 1.2.0).
+(gated: test/torture.mjs s5, per-scenario budgets).
 
 ## Files
 
@@ -287,7 +293,6 @@ is caught up; `mode: "buffer"` also zero when no waiter is pending
 - `README.md` -- full docs with integration recipes
 - `llms.txt` -- this file
 - `CHANGELOG.md` -- version history
-- `ROADMAP.md` -- deferred features
 
 ## Author
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-stream",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Zero-GC bridge between async iterators and @zakkster/lite-signal. Project async streams (paginated APIs, SSE, network frames, pubsub topics) into signals. Bounded buffering with explicit overflow diagnostics, structural cleanup on three termination paths (iterator done, iterator throws, AbortSignal abort). The multi-shot dual of lite-await's fromPromise.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -22,14 +22,16 @@
     "README.md",
     "llms.txt",
     "LICENSE.txt",
-    "CHANGELOG.md",
-    "ROADMAP.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --expose-gc --test --test-reporter=spec",
-    "test:gc": "node --expose-gc --test --test-reporter=spec",
+    "test": "node --expose-gc --test --test-reporter=spec test/*.test.mjs",
+    "test:gc": "node --expose-gc --test --test-reporter=spec test/*.test.mjs",
     "bench": "node --expose-gc bench/bench.mjs",
-    "verify": "npm test && npm run test:gc && npm run bench"
+    "torture": "node --expose-gc test/torture.mjs",
+    "torture:control": "for t in s0 s1 s2 s3 s4 s5 s6 s7 s8; do if STREAM_TORTURE_BREAK=$t node --expose-gc test/torture.mjs >/dev/null 2>&1; then echo \"control $t FAILED-TO-FAIL\"; exit 1; else echo \"control $t failed-as-expected\"; fi; done",
+    "test:floor": "echo '== floor lane: pin @zakkster/lite-signal@1.2.2 (torture NOT run here -- lite-leak peers lite-signal>=1.5.0, LS-09 amendment) ==' && npm i --no-save --no-package-lock @zakkster/lite-signal@1.2.2 --legacy-peer-deps && npm test && echo 'FLOOR-PASS: npm test green @ lite-signal@1.2.2' && echo '== latest lane: restore @zakkster/lite-signal@^1.2.0 ==' && npm i --no-save --no-package-lock @zakkster/lite-signal@^1.2.0 && npm test && npm run torture && echo 'LATEST-PASS: npm test + torture green @ lite-signal latest'",
+    "verify": "npm test && npm run test:gc && npm run bench && npm run torture"
   },
   "keywords": [
     "stream",
@@ -66,6 +68,8 @@
     "@zakkster/lite-signal": "^1.2.0"
   },
   "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
     "@zakkster/lite-signal": "^1.2.2"
   }
 }

package/ROADMAP.md

@@ -1,711 +0,0 @@
-# lite-stream -- enriched roadmap (post-1.1.0)
-
-Blueprint: `../BLUEPRINT_ROADMAP.md`. Sibling roadmaps this one is wired to:
-`../LiteQuery/ROADMAP.md` (the flagship consumer), `../LiteBakeStream/ROADMAP.md`
-(the torture-spec model), `../LiteAwait/AWAIT_ROADMAP.md` (the TimeoutError
-duck-pact). Ethos carried over unchanged: **reproduce by running, never infer.**
-Every finding below was produced by executing code on 2026-09-01, not by
-reading it. Reproductions live in `bench/findings-probes-2026-09-01.mjs`.
-
-Sessions: LS1 (v1.1.1, truth patch) -> LS2 (v1.2.0, the law's gate) ->
-LS3 (v1.3.0, the consumer contract) -> LS4 (v1.4.0, Q8 enablement, GATED).
-
----
-
-## 0. Ground truth (verified 2026-09-01)
-
-- Registry: `@zakkster/lite-stream` 1.0.0 and 1.1.0 published; `latest` =
-  1.1.0. Local HEAD `e9d2151 1.1.0;` IS the published state; tree clean.
-- Surface: 4 named exports -- `fromAsyncIterable`, `pipeToSignal`,
-  `toAsyncIterable`, `TimeoutError`. NO `VERSION` export (LS-05). `Stream.d.ts`
-  and `llms.txt` agree with the export block (hand-checked; guard pending LS2).
-- Tests: 79. Default `npm test` -> 71 pass, **8 skipped silently** (the entire
-  GC tier, LS-02). `npm run test:gc` -> 79 pass, 0 skip, 0 fail -- against
-  lite-signal **1.5.0** AND against the floor **1.2.2** (both run today; the
-  `^1.2.0` peer claim is TRUE, previously untested -- LS-09).
-- Torture: none. No `test/torture.mjs`, no `@zakkster/lite-leak`, no
-  `@zakkster/lite-gc-profiler`, no seeded fuzz, no controls. The 8 GC tests
-  use coarse "retain < 2 MB" ceilings, not the law's `maxMajor: 0` gate (LS-03).
-- Bench (node v26.3.1, this machine, 2026-09-01): from-latest 61,464 ops/s
-  (0.35 B/op retained), from-buffer 63,382 (0.46), abort-cycle 29,652 (1.49),
-  pipe-to-signal 42,382 (0.26), to-async-iterable 200,956 (negative retained),
-  overflow 204,774 (0.13). Shipped llms.txt claims different numbers with no
-  provenance on the 1.0 block (LS-08).
-- Consumers in the suite: exactly one. `../LiteQuery/StreamQuery.js:36`
-  imports `pipeToSignal` (peer `^1.0.0`, optional). lite-query also vendors
-  a 1.0.0 copy for demos (`demo/vendor/lite-stream.js`).
-- ASCII: **zero** non-ASCII bytes across Stream.js, Stream.d.ts, all docs,
-  test/, bench/, demo/. Already clean; LS2's guard keeps it that way.
-- Hygiene: no `.gitignore` (added at roadmap-pass time: `node_modules/`,
-  `package-lock.json` -- same operator ruling as lite-query Q1), no lockfile
-  (deliberate, now recorded). `files[]` ships ROADMAP.md (LS-11).
-- Runtime facts: engines `>=18`; `Symbol.asyncDispose` feature-detected
-  (present on node 26, its conditional test runs). devDep `^1.2.2` resolves
-  to lite-signal 1.5.0 at install time.
-
-## 1. Shared law (holds in every session)
-
-1. Zero runtime deps; `@zakkster/lite-signal` is the single peer. node:test
-   only. ASCII-only source and docs. Single main file `Stream.js`.
-2. Bounded buffering is this package's own law: "unbounded buffering is a
-   memory bug pretending to be a feature." Every buffer has a required,
-   validated ceiling; every drop is counted and observable.
-3. Fail closed on every unverified state. The LS-01 lesson is the local
-   phrasing: a cleanup path that depends on a peer behavior nobody ever
-   executed is not a cleanup path, it is a comment.
-4. **AbortSignal is the only cleanup contract.** Dispose-based teardown is
-   not promised anywhere until a lite-signal disposed-oracle exists (parked).
-   Docs, tests, and torture pin this in every direction.
-5. No silent skips (the Q-02/AW-14/LS-02 class): the default `npm test` runs
-   every test the repo owns. Environment-conditional skips (asyncDispose on
-   node < 20) must name their condition in the skip message and have a
-   counterpart that runs.
-6. Every module change is proven by `node --expose-gc test/torture.mjs`
-   (lite-leak + lite-gc-profiler) once LS2 lands. No gate output is a FAIL.
-   A gate that cannot fail is decorative -- controls are part of the gate.
-7. Docs parity is release-blocking: exports == llms.txt == Stream.d.ts ==
-   README API section; peer floors in docs == package.json; perf numbers
-   carry provenance (node version, date, machine class) or do not ship.
-8. Measured numbers are measured once, at the source of truth, and cited
-   everywhere else (the bake-stream MQ2 discipline).
-
-## 2. Verified findings
-
-Severity: S1 = a shipped claim is false / correctness; S2 = a gate or
-guarantee is dark; S3 = drift, hygiene, or docs debt. Every row was
-reproduced by running on 2026-09-01; probe bodies live in
-`bench/findings-probes-2026-09-01.mjs` (P0..P4).
-
-| ID | Sev | Finding | Reproduce |
-| --- | --- | --- | --- |
-| **LS-01** | S1 | **The shipped dispose-teardown claim is false, and it has never been true.** llms.txt (lines 132-134): "If the consumer disposes the result signal ... the pump detects on next `sig.set()` and tears down silently." Reality: lite-signal's `set()` after `dispose()` is a **silent no-op** in 1.5.0 AND 1.2.2 (P0), so the pump's catch-based detection (`Stream.js:343`) is dead code born dead -- it never fired against any published peer in the range. Observed: dispose mid-pump leaves the iterator **pulling forever** (P1: 14 pulls at dispose, 64 and climbing 60ms later, `return()` never called); same for `pipeToSignal` with a disposed target (P2, `onError` never fires). For an infinite source (SSE -- the package's own headline use case) this is an unbounded background fetch loop. The `Stream.js:148-152` docstring even offers dispose as a stop mechanism ("the iterator continues until natural completion" -- an infinite source has none). Sole suite consumer verified SAFE: StreamQuery always `ac.abort()`s via `streamStop` before entry teardown (`StreamQuery.js:156`). | `node bench/findings-probes-2026-09-01.mjs` (P0/P1/P2) |
-| **LS-02** | S2 | **Default `npm test` silently skips the entire GC tier.** All 8 tests in `test/06-gc.test.mjs` are `{ skip: !hasGc }` and the `test` script lacks `--expose-gc`; 71/79 green LOOKS complete. The `verify` script runs `test:gc`, but the habitual gate is `npm test`. Third suite recurrence of the green-light-over-a-hole class (Q-02, AW-14). Fix pre-verified: the `test:gc` form runs 79/79 green in 21.5s. | `npm test 2>&1 \| grep skipped` -> 8; `npm run test:gc` -> 0 |
-| **LS-03** | S2 | **The pipeline law's torture gate does not exist.** No `test/torture.mjs`, no lite-leak, no lite-gc-profiler, no seeded fuzz, no zero-alloc gate (llms.txt claims "allocates zero on the steady-state hot path" -- nothing gates it), no controls. The GC tests' "retain < 2 MB" ceilings would pass a 1.9 MB leak. | `ls test/torture.mjs` -> ENOENT; `grep -c lite-leak package.json` -> 0 |
-| **LS-04** | S3 | **Disposing the SOURCE under `toAsyncIterable` hangs the pending `next()` forever** (P3: still PENDING 50ms after dispose; no resolve, no reject). llms.txt already anti-patterns this as "undefined behavior", so it is documented-away rather than false -- but the observed behavior is now on record, and `timeout` is the only escape hatch. Hardening parked on a lite-signal disposed-oracle (see parking ledger). | probes P3 |
-| **LS-05** | S3 | **No `VERSION` const or export.** Suite convention (lite-query, lite-await) and the /release drill's site list expect one in the main file. Current version sites: `package.json`, `Stream.js:1` header comment, CHANGELOG headings. Additive export -> lands with LS2 (1.2.0), never re-exported by consumers (suite ruling, lite-await pass). | `grep -c VERSION Stream.js` -> 0 |
-| **LS-06** | S3 | **Shipped source references a document that does not exist.** `Stream.js:25` and `:560` cite `CONTRACT-toAsyncIterable-1.1.md`; no such file in the repo or the tarball. The TimeoutError comment (`Stream.js:44-45`) still narrates its own dev sessions ("Session B's territory ... Session A"). | `ls CONTRACT-toAsyncIterable-1.1.md` -> ENOENT |
-| **LS-07** | S3 | **The pump comment describes code that is not there.** `Stream.js:352-353`: "Defer the next pull through the microtask queue so back-to-back synchronous yields don't blow the stack" -- `pump()` is called directly; no deferral exists at that site. Behavior is stack-safe anyway (`.then` handlers unwind): P4 drains a 1,000,000-value sync source in ~80ms with no overflow. Fix is the comment, plus a torture case pinning the law. | probes P4 |
-| **LS-08** | S3 | **Shipped perf numbers lack provenance and do not match a current run.** llms.txt's 1.0 block ("178K ops/s ... 235K ... 84K") names no node version, date, or machine; today's run on node v26.3.1 gives 61K/42K/29K for the same scenarios. Not a lie -- a rotting number. Re-measure once with provenance at LS1, cite everywhere (README Benchmarks included). | `npm run bench` vs llms.txt Performance section |
-| **LS-09** | S3 | **The peer floor `^1.2.0` was a claim, not a fact -- now verified, must stay verified.** Tests had only ever run against the latest resolution (1.5.0). Run today against pinned 1.2.2: 79/79 green. The floor holds; nothing keeps it holding. LS2's floor matrix (scripted `test:floor`) institutionalizes the check. | `npm i --no-save --no-package-lock @zakkster/lite-signal@1.2.2 && npm run test:gc` |
-| **LS-10** | S3 | **No repo hygiene layer.** No `.gitignore` -- a plain `npm install` leaves `node_modules/` (and would leave `package-lock.json`) as untracked noise poised to be committed; no recorded lockfile policy. Mitigated at roadmap-pass time (2-line `.gitignore`, same ruling as lite-query Q1); policy recorded here: no lockfile, devDeps float within their stated ranges, the floor matrix pins what must stay true. | `git status` after `npm install` (pre-fix) |
-| **LS-11** | S3 | **ROADMAP.md ships in the tarball, and two shipped docs point into its old shape.** `files[]` includes ROADMAP.md; llms.txt's Files section describes it as "deferred features"; CHANGELOG 1.1.0 cites "ROADMAP.md's 'Shipped in 1.1.0' section" (preserved below under History so the published 1.1.0 pointer stays honest). Ruling to execute at LS2: drop ROADMAP.md from `files[]` (align with lite-query/bake-stream -- the roadmap is a working doc), fix the llms.txt Files line and CHANGELOG forward-refs in the same release. | `npm pack --dry-run \| grep ROADMAP` |
-| **LS-12** | S3 | **The two directions disagree about what abort means, and the flagship consumer pays for it.** `fromAsyncIterable`/`pipeToSignal` route abort through `onError` (error framing, `makeAbortError`); `toAsyncIterable` treats abort as graceful done. StreamQuery hand-filters the noise: "pipeToSignal funnels intentional aborts through onError too. Those are not failures" (`StreamQuery.js:139-142`). Each direction is documented locally; the asymmetry as a whole is undocumented and exports a workaround obligation to every consumer. LS3 owns the decision doc (pin the rationale or add an `onAbort` hook -- see the brief). | read `StreamQuery.js:139-142`; compare `Stream.js:261` vs `:815` |
-
-### 2b. Cross-package facts (verified against the neighbors' code, not their docs)
-
-- **lite-signal 1.5.0 has no public disposed-oracle.** Exports: signal,
-  computed, signalBox, computedBox, effect, dispose, batch, createRegistry,
-  setDefaultRegistry, CapacityError, getOwner, runWithOwner. Nothing answers
-  "is this signal disposed?" -- so LS-01's behavioral fix (pump detects
-  dispose) is IMPOSSIBLE in-library today. Tripwire: if lite-signal ships an
-  oracle, un-park "dispose-aware pumps" (parking ledger).
-- **StreamQuery's exact usage shape** (the contract LS2's conformance tier
-  freezes): `pipeToSignal(source, entry.data, { signal, transform, onError,
-  onDone })` where `transform` doubles as a first-value status tap and a
-  hand-rolled buffer window (`ring.push/shift/slice`, `StreamQuery.js:119-137`),
-  and `onError` filters `signal.aborted`. Three shipped triggering signals for
-  LS3, cited by line.
-- **TimeoutError duck-pact.** Three packages now carry the shape
-  (`e.name === "TimeoutError"`, `.timeout` field): lite-await (origin),
-  lite-stream (structural copy, deliberate zero-dep), lite-query's /await
-  entry (re-export of lite-await's). The duck-check IS suite vocabulary;
-  renaming it anywhere is a breaking change everywhere. Pinned by a shape
-  test in LS2's conformance tier.
-- **lite-bake-stream is bytes-domain** (`ReadableStream<Uint8Array>` in,
-  LBK1 containers out) -- no structural integration with value-domain
-  lite-stream. One honest recipe candidate, docs-only: RangeReader shard
-  walk -> async generator -> `fromAsyncIterable` for a UI-reactive lazy
-  view (parking ledger; needs bake-stream >= MQ1 for abortability).
-- **lite-query Q8 (2.0.0, shared streams)** is the design event LS4 waits
-  for: leader owns one iterator, followers receive frames over lite-channel
-  and need "push externally-delivered values into entry signals with the
-  same windowed-view discipline", plus "leader hung (frames stop, channel
-  alive)" stall detection. Whether those primitives land in lite-stream 1.4.0
-  or inside lite-query is Q8's session-start spike ruling. Their spike is
-  our tripwire; recorded on both sides.
-
-## 3. The torture suite (`test/torture.mjs`) -- spec
-
-Model: `../LiteBakeStream/ROADMAP.md` section 3 (itself ported from
-`../LiteBvh/test/torture/`), tiers renamed to this package's threat model:
-lifecycle leaks, protocol violations, scheduling races, and false zero-GC
-claims. Gate: `node --expose-gc test/torture.mjs` prints exactly "ok",
-exit 0/1. Control switch: `STREAM_TORTURE_BREAK=1` must exit non-zero.
-
-```
-test/
-  torture.mjs           # entry: tiers in order, prints "ok", exit 0/1
-  torture/
-    harness.mjs         # xorshift32 PRNG (TORTURE_SEED replay), check() with
-                        # message thunks, runOpsGate (stabilize:'deep'),
-                        # STREAM_TORTURE_BREAK switch, preflight: exit 2 with
-                        # a clear message when devDeps are missing
-    s0-laws.mjs         # metamorphic invariants
-    s1-degenerate.mjs   # nasty values and nasty iterators
-    s2-protocol.mjs     # async-iteration protocol conformance
-    s3-abuse.mjs        # API misuse: every case has a decided policy
-    s4-fuzz.mjs         # seeded schedule fuzz vs a naive oracle
-    s5-alloc.mjs        # the zero/bounded-alloc gate (gc-profiler)
-    s6-soak.mjs         # lite-leak retention + lifecycle churn
-    s7-conformance.mjs  # consumer corpus + floor matrix + duck-pact
-    s8-controls.mjs     # every tier, deliberately broken, exits non-zero
-```
-
-Harness rules (verbatim from the blueprint; all apply):
-- All scratch allocated once, outside every loop; assertion messages built
-  only on failure.
-- Seeded xorshift32; any failure prints seed + op index, replayable via
-  `TORTURE_SEED=... node --expose-gc test/torture.mjs`.
-- lite-gc-profiler is one-measurement-at-a-time; tiers run sequentially;
-  read `../lite-gc-profiler/llms.txt` before wiring -- rule names from
-  memory are how gates rot. Unknown rule keys throw as of 1.10.0; floor the
-  devDep there.
-- lite-leak held-value contract: neither `cleanup` nor `tag` closes over the
-  tracked target. Never resolve an unexpected `inconclusive` with
-  `allowInconclusive`.
-- `test/` never enters `files[]`; `npm pack --dry-run` proves it.
-
-### s0 -- metamorphic laws
-
-For any seeded op sequence: `state.count` equals values yielded (both modes);
-buffer `values.length <= maxBuffer` always; `droppedCount` equals exactly
-`max(0, yields - maxBuffer)` when no consumer drains; latest-mode terminal
-`value` equals the last yield; toAsyncIterable delivery order equals source
-order (filtered) in buffer mode; **timing invariance**: the same logical
-value sequence delivered via sync iterables, microtask-resolved promises,
-and macrotask-resolved promises produces the same terminal state (count,
-last value/values, done, error class) -- the scheduling analog of
-bake-stream's re-chunk invariance. Terminal states are frozen: after
-done/error, no further mutation ever (already unit-pinned; fuzz-scale it).
-
-### s1 -- degenerate values and hostile iterators
-
-Values: `undefined` yields (state.count is the oracle for "did a value
-arrive", value alone is ambiguous -- pin it), null, NaN, -0, frozen objects,
-functions, symbols. Sources: 1M-value sync iterable (stack law, P4 baseline
-~80ms), empty iterable (immediate done), iterator with `.next` but no
-`Symbol.asyncIterator`, thenable-returning next(), next() returning
-non-object (pinned TypeError), result objects with throwing getters
-(`{get done() {throw}}`), `return()` that throws (swallowed -- pin),
-`return()` that never settles, an iterator that resolves a pull AFTER
-stop/abort landed (the `if (stopped)` guards, fuzz-reachable). Aborts:
-pre-aborted (pinned), abort inside the first `queueMicrotask` window before
-pull one, abort reentrantly from inside `onError`/`onDone`, abort with a
-custom `reason` (pinned), double abort.
-
-### s2 -- protocol conformance (toAsyncIterable)
-
-next() after done; `return(value)` passthrough vs pending waiters resolving
-`{value: undefined, done: true}` (the documented split); `throw()` rejecting
-both waiters and its own call site; multi-waiter FIFO under fuzz (N waiters
-x M values, orders compared to a queue oracle); `Promise.all` batch pulls;
-`for await` + break; `await using` on node >= 20; the emitInitial x filter x
-initial-value matrix (8 cells, each named); filter throwing on the initial
-synchronous fire (the late-binding unsubscribe path, `Stream.js:656-663`).
-
-### s3 -- API abuse (throw / documented no-op / documented undefined -- pick one per case)
-
-Mode typos ("Latest", "newest", 5); maxBuffer 0 / -1 / 1.5 / Infinity / NaN /
-"5"; `mode: "latest"` + maxBuffer (pinned TypeError); timeout 0 (DECIDE and
-pin: fires on the first turn -> first pending next() rejects TimeoutError),
-timeout Infinity (non-finite -> RangeError, pin), timeout -1; filter
-non-function; non-signal source/target (missing peek, missing subscribe,
-missing set, frozen impostor objects); `stop()` twice (pinned) and `stop()`
-racing a pending pull; dispose-then-X: every LS-01/LS-04 case lands here as
-a NAMED test pinning the documented behavior ("dispose does not stop the
-pump; abort does" / "dispose under a consuming iterable hangs -- documented
-anti-pattern, timeout is the escape").
-
-### s4 -- seeded schedule fuzz vs a naive oracle
-
-A seeded generator emits op schedules over both directions: producer-set /
-consumer-next / filter-toggle-outcome / abort / break / return / timeout-arm,
-with micro/macro-task jitter. Oracle: a deliberately naive reference model
-(unbounded array + hand bookkeeping of drops/overflow per the documented
-semantics). Compare delivered sequences, terminal states, and counter values
-cell-for-cell. Divergence prints seed + op index + a minimal replay line.
-The multi-waiter FIFO and the ring head/wrap arithmetic are the two
-mechanisms this tier exists to break.
-
-### s5 -- the alloc gate (the llms.txt claims, gated at last)
-
-`runOpsGate(fn, { ops })` with `RULES = { maxMajor: 0, maxPauseMs: 4 }`,
-stabilize `'deep'`. Scenarios and their DOCUMENTED budgets (the M0 doctrine:
-per-scenario budgets, never a widened global rule):
-- toAsyncIterable `mode:"latest"`, consumer caught up: llms.txt claims ZERO
-  steady-state allocation -- gate exactly that (plus the per-next Promise
-  cost intrinsic to the protocol, measured and documented once).
-- toAsyncIterable buffer, no waiter pending: same claim, same gate.
-- pipeToSignal steady pump: budget from today's 0.26 B/op retained baseline.
-- fromAsyncIterable latest: one state object per yield BY DESIGN -- assert
-  the documented envelope (today 0.35 B/op retained steady-state), assert
-  nothing HIDDEN grows (retained slope flat).
-- fromAsyncIterable buffer: state object + snapshot array per yield BY
-  DESIGN -- envelope pinned per maxBuffer tier (8 / 64 / 1024).
-- waiter-heavy path (consumer faster than producer): waiter objects are
-  intrinsic; retained slope must be flat.
-
-### s6 -- soak and retention (lite-leak enters here)
-
-4096 cycles per surface of: construct -> pump N values -> terminate (each of
-the three paths in rotation) -> drop refs; tracker with the standard kernels;
-`tracker.size()` returns to 0. Abort-listener accumulation on a SHARED
-AbortSignal across 4096 streams (the removeEventListener discipline at
-scale). Timer discipline: 4096 timeout-armed iterables that settle before
-the deadline -- `clearTimeout` called every time (the llms.txt "negative
-retained" bench hints this is right; prove it). The existing 4K-cycle unit
-leak tests stay in `test/07`; s6 is the deeper per-commit version.
-
-### s7 -- conformance: the consumer corpus, the floor, the pact
-
-- **StreamQuery corpus**: the exact call shape from `StreamQuery.js:124-154`
-  (transform-as-tap + hand ring + abort-filtering onError), run against a
-  seeded source, asserting the semantics lite-query depends on: transform
-  called once per value BEFORE set, abort fires onError with
-  `signal.aborted === true` observable, onDone exactly once, stop idempotent.
-  lite-stream must never drift under its flagship consumer silently. When
-  LS3 ships the enriched pipeToSignal, the corpus gains the enriched shape
-  and KEEPS the 1.1.0 shape (both are public API).
-- **Floor matrix**: `npm run test:floor` -- scripted: install the peer floor
-  (`@zakkster/lite-signal@1.2.2`) via `--no-save --no-package-lock`, full
-  `test:gc` + torture, restore latest, print both verdicts. Run per release
-  (release drill step), not per commit. LS-09 stays a fact, not a claim.
-- **TimeoutError duck-pact**: shape assertions (`name`, `timeout` field,
-  `instanceof Error`, message prefix) pinning the cross-package duck-check
-  contract (2b). No lite-await devDep -- the pact is structural.
-
-### s8 -- controls
-
-`STREAM_TORTURE_BREAK=1 node --expose-gc test/torture.mjs` must exit
-non-zero via injected breakage, one per tier minimum: an allocating closure
-in the s5 caught-up loop; an oracle that ignores droppedCount in s4; a
-skipped abort case in s1; a waiter-order swap in s2; a retained-stream ref
-in s6; a corpus assertion inverted in s7. A gate that cannot fail is
-decorative.
-
-## 4. Session order
-
-```
-LS1 (1.1.1 truth patch)
- |
- v
-LS2 (1.2.0 the law's gate + guards + VERSION + packaging)
- |
- v
-LS3 (1.3.0 the consumer contract: pipeToSignal enrichment + abort decision)
- |
- v            [tripwire: lite-query Q8 session-start spike rules the split]
-LS4 (1.4.0 Q8 enablement: stall detection / push-writer / share primitives)
-```
-
-Serial on purpose: LS1's honest docs are the floor LS2's gates stand on;
-LS2's harness is what makes LS3's surface growth safe to ship; LS4 is
-design-gated on lite-query Q8 and MUST NOT jump the queue (building shared-
-stream primitives before the consumer's failover matrix exists would be
-speculative API -- the exact thing the 1.0 deferral discipline refused).
-
-## 5. The briefs
-
-===============================================================================
-# LS1 -- lite-stream v1.1.1 -- the docs tell the truth and the gates run
-===============================================================================
-
-```markdown
----
-package: "@zakkster/lite-stream"
-version_target: 1.1.1
-status: planned
-tests_min: 85
-skip_max: 1        # only the named asyncDispose environment skip, node < 20
-findings: [LS-01, LS-02, LS-04, LS-06, LS-07, LS-08, LS-10]
-depends_on: []
----
-
-# lite-stream -- no shipped sentence the probes can refute
-
-PURPOSE
-  A patch release with zero API change that makes every shipped claim true
-  and every existing test actually run. The package's core positioning is
-  "structural cleanup on every termination path"; today one documented path
-  is a leak generator. Fix the words now, the machinery in LS2/LS3.
-
-TASKS
-  - LS-01 docs surgery, all three shipped docs: llms.txt lines 132-134
-    replaced with the truth ("disposing the result signal does NOT stop the
-    pump; the iterator keeps pulling. AbortSignal or natural completion are
-    the only stop mechanisms. See ROADMAP LS-01."); the Stream.js:148-152
-    docstring stops offering dispose as a stop mechanism; README cleanup
-    section aligned. The dead catch at Stream.js:343-351 STAYS (belt against
-    a future lite-signal that throws) but its comment stops claiming it is
-    the dispose path and starts naming what it actually is: defensive.
-  - LS-01/LS-04 pinned tests (new test/08-dispose-behavior.test.mjs, ~6
-    tests): dispose-mid-pump -> pump continues, return() not called (pin the
-    TRUE behavior so any future change is a conscious one); same for
-    pipeToSignal; dispose-source under toAsyncIterable -> pending next()
-    hangs (pin via a bounded race against a sentinel timer); each test cites
-    LS-01/LS-04 in its name.
-  - LS-02: default gate becomes `"test": "node --expose-gc --test
-    --test-reporter=spec"`; `test:gc` kept as an alias for muscle memory;
-    `verify` unchanged. Assert in-session: 79 -> 79 pass 0 skip (pre-verified
-    2026-09-01: 21.5s).
-  - LS-06: delete the two `CONTRACT-toAsyncIterable-1.1.md` references (the
-    locked semantics live in llms.txt + this roadmap's s2/s3 tiers now);
-    rewrite the TimeoutError comment without the Session A/B narrative.
-  - LS-07: fix the pump comment to state the actual mechanism (".then
-    handlers unwind the stack; no explicit deferral needed") and cite the 1M
-    sync-source probe number.
-  - LS-08: re-run `npm run bench`, stamp llms.txt Performance and README
-    Benchmarks with node version + date + "your numbers will differ", one
-    source of truth (llms.txt), README cites it.
-  - LS-10 (partially done at roadmap-pass time): .gitignore landed; record
-    the no-lockfile policy line in README's Testing section or CONTRIBUTING
-    stub -- one sentence, not a document.
-  - CHANGELOG [1.1.1]: Fixed (docs corrections, each naming its finding),
-    Added (dispose-behavior pins, gate flag). Facts only.
-
-HOT PATH
-  Untouched. `git diff -- Stream.js` shows comment-only hunks; reviewer
-  proves token-stream identity (the Q2 discipline).
-
-ASSERTIONS
-  - npm test -> >= 85 pass, 0 fail, skip <= 1 (asyncDispose env skip only,
-    named).
-  - bench/findings-probes-2026-09-01.mjs output UNCHANGED (the probes pin
-    behavior; this release changes words).
-  - grep proves no shipped doc contains "tears down" dispose claims; grep
-    finds the AbortSignal-only sentence in llms.txt AND README.
-  - npm pack --dry-run: no test/, no bench/, no demo/.
-
-NON-GOALS
-  No API change. No VERSION export (that is additive -> LS2). No torture
-  harness (LS2). No behavior change to the pump.
-
-DONE WHEN
-  Every sentence the probes can check is true, the default gate runs
-  everything, and 1.1.1 is published with the corrected llms.txt.
-```
-
-===============================================================================
-# LS2 -- lite-stream v1.2.0 -- the law's gate, able to fail
-===============================================================================
-
-```markdown
----
-package: "@zakkster/lite-stream"
-version_target: 1.2.0
-status: planned
-tests_min: 90
-skip_max: 1
-torture: "s0-s8 ok; STREAM_TORTURE_BREAK=1 fails every tier; floor matrix green"
-findings: [LS-03, LS-05, LS-09, LS-11]
-depends_on: [LS1]
----
-
-# lite-stream -- prove the claims, then keep them proven
-
-PURPOSE
-  Port the suite-law torture harness (bake-stream M0 discipline, tiers per
-  section 3), add the drift guards that keep docs/exports/ASCII honest
-  (lite-query Q2 discipline), export VERSION, and execute the LS-11
-  packaging ruling. After this session the package can prove its own
-  headline claims -- including the zero-steady-state-alloc sentence that has
-  been unverified since 1.0.0.
-
-TASKS
-  - test/torture.mjs + test/torture/ per section 3: harness (seeded PRNG,
-    check thunks, runOpsGate stabilize:'deep', STREAM_TORTURE_BREAK,
-    preflight exit 2 on missing devDeps), tiers s0-s8, controls for every
-    tier. devDeps: @zakkster/lite-leak (floor from its llms.txt),
-    @zakkster/lite-gc-profiler ^1.10.0 (unknown-rule-keys-throw relied on).
-    Read both llms.txt files before wiring; rule names from memory are how
-    gates rot.
-  - package.json: "torture": "node --expose-gc test/torture.mjs";
-    "torture:control": "STREAM_TORTURE_BREAK=1 node --expose-gc
-    test/torture.mjs || echo control-failed-as-expected"; "test:floor" per
-    s7; "verify" gains torture.
-  - Guards (Q2-modeled, ~5 tests): ascii-guard (walk = files[] parsed at
-    runtime + test/ + bench/ + demo/; printable ASCII + LF; empty allowlist;
-    inline failing control) and surface-guard (exports == llms.txt == d.ts
-    export names; peer names in llms.txt exist in peerDependencies; failing
-    fixture control). Pre-verified 2026-09-01: repo is already 0 non-ASCII.
-  - LS-05: `const VERSION = "1.2.0"` exported from Stream.js; string-equals
-    package.json (release-drill site). Never re-exported by consumers
-    (suite ruling). Surface-guard and d.ts updated in the same commit.
-  - LS-11 ruling executes: ROADMAP.md out of files[]; llms.txt Files section
-    updated; CHANGELOG forward-references fixed (the published 1.1.0 tarball
-    keeps its pointer -- the History section below preserves the target).
-  - LS-09: test:floor scripted and run in-session (pre-verified green
-    2026-09-01); result recorded in CHANGELOG with provenance. Peer floor
-    STAYS ^1.2.0 because it is now a tested fact.
-  - Expected s5 friction, decided in advance (M0 lesson): the per-next
-    Promise allocation in toAsyncIterable and the by-design per-yield state
-    objects in fromAsyncIterable get per-scenario documented budgets --
-    never a widened global rule. A budget that moves is not a gate.
-
-ASSERTIONS
-  - npm test >= 90 pass, 0 fail, skip <= 1; torture prints "ok" exit 0;
-    torture:control exits non-zero FOR EVERY TIER (each control verified
-    individually in-session).
-  - The llms.txt zero-steady-state-alloc sentence now has a gate (s5) and
-    the gate has a control (s8).
-  - npm pack --dry-run: ROADMAP.md ABSENT, test/ bench/ demo/ absent,
-    llms.txt + CHANGELOG.md present; VERSION === package.json version.
-  - Fresh-clone drill: clone to scratch, npm install, npm test, npm run
-    torture -- all green (the lite-query G10 habit).
-
-NON-GOALS
-  No surface growth beyond VERSION. No pipeToSignal enrichment (LS3). No
-  behavior changes -- if a tier finds a real bug, it lands as a NAMED
-  failing todo + ledger row and ships fixed in LS3, not silently here.
-
-DONE WHEN
-  the law's command runs from the law's path, every control fails, the
-  floor matrix is scripted, and 1.2.0 is published with VERSION exported
-```
-
-===============================================================================
-# LS3 -- lite-stream v1.3.0 -- the consumer contract session
-===============================================================================
-
-```markdown
----
-package: "@zakkster/lite-stream"
-version_target: 1.3.0
-status: planned
-tests_min: 105
-skip_max: 1
-torture: "ok + s7 corpus extended to the enriched shape"
-findings: [LS-12]
-depends_on: [LS2]
-consumer_evidence: "StreamQuery.js:119-137 (hand ring), :127 (status tap), :139-142 (abort filter)"
----
-
-# lite-stream -- what its flagship consumer already built by hand, offered properly
-
-PURPOSE
-  Every addition in this session has a shipped consumer code-site as its
-  triggering signal -- the 1.0 deferral discipline, satisfied for real.
-  lite-query's StreamQuery hand-rolls three things around pipeToSignal:
-  a buffer window (push/shift/slice -- O(n) shift where our ring is O(1)),
-  a first-value status tap smuggled through `transform`, and an
-  abort-filtering onError. Offer all three natively; let the consumer
-  delete code.
-
-TASKS
-  - pipeToSignal enrichment (design settled in-session by the planner,
-    candidates): `mode: "latest" | "buffer"` + `maxBuffer` + a
-    droppedCount observable (return-object upgrade or stats getter --
-    decide against the "returns stop fn" 1.x compat constraint: the stop
-    FUNCTION must remain callable as before; additive properties on it are
-    the compat-safe shape), and `onValue(v)` tap firing before set (the
-    status-tap consumer). All additive; 1.1.0 call shapes byte-compatible
-    (s7 corpus keeps both shapes green).
-  - LS-12 decision doc, decisions/0001-abort-vocabulary.md (the lite-await
-    decisions/ convention): EITHER pin the asymmetry as deliberate with the
-    producer/consumer rationale (from-side: abort interrupts production =
-    error framing; to-side: abort stops listening = graceful done) and
-    document it in llms.txt as a contract table -- OR add `onAbort`
-    callbacks so consumers stop filtering. Recommendation: PIN the
-    asymmetry + add `onAbort` to pipeToSignal only (the direction with the
-    shipped workaround); do not touch toAsyncIterable's graceful-done
-    contract (1.0.0-locked, correct for its side).
-  - s7 corpus: add the enriched-shape cases; keep the 1.1.0-shape cases
-    forever.
-  - Cross-repo rider recorded (not executed here): lite-query parking entry
-    exists pointing at this session -- after 1.3.0 ships, StreamQuery can
-    collapse its ring + tap + filter into the enriched call in a lite-query
-    minor, and refresh its vendored demo copy (still 1.0.0).
-
-ASSERTIONS
-  - Old-shape s7 corpus green UNCHANGED against the new build (no drift
-    under the flagship consumer).
-  - A StreamQuery-shaped rewrite using the enriched surface (as a TEST, in
-    this repo) produces identical observable semantics to the hand-rolled
-    original, including droppedCount parity on overflow.
-  - Suite >= 105, 0 fail; torture ok; guards green; VERSION bumped.
-
-NON-GOALS
-  No fromAsyncIterable changes. No toAsyncIterable changes. No shared/
-  multicast primitives (LS4, gated). No combinators (never -- History).
-
-DONE WHEN
-  lite-query COULD delete StreamQuery.js:119-137 without behavior change,
-  and 1.3.0 is published with the decision doc on disk
-```
-
-===============================================================================
-# LS4 -- lite-stream v1.4.0 -- Q8 enablement (GATED, do not start on a hunch)
-===============================================================================
-
-```markdown
----
-package: "@zakkster/lite-stream"
-version_target: 1.4.0
-status: gated
-gate: "lite-query Q8 session-start spike has ruled which primitives land here"
-tests_min: 120
-depends_on: [LS3]
----
-
-# lite-stream -- the primitives a one-connection browser needs, if Q8 wants them here
-
-PURPOSE
-  lite-query 2.0 (Q8) makes one tab own an upstream iterator while N tabs
-  consume frames. Three primitive-shaped needs are visible from Q8's brief
-  today; WHICH of them belong in lite-stream (vs inside lite-query, vs
-  nowhere) is Q8's session-start spike ruling. This brief is a menu, not a
-  commitment.
-
-CANDIDATE MENU (each with its Q8 obligation)
-  - Idle/stall detection: an `idleTimeout` that resets per value (today's
-    `timeout` is an overall deadline -- wrong tool for "leader hung, frames
-    stopped, channel alive"). Smallest candidate, clearest fit.
-  - Push-writer surface: values that arrive by callback (channel frames),
-    not by iterator pull, entering a signal with the same mode/maxBuffer/
-    droppedCount discipline (the follower side's projection). Shape TBD --
-    possibly just documenting the enriched pipeToSignal over a hand-made
-    async queue, possibly a real `createSignalWriter`.
-  - Share/refcount: one source iterator, N signal consumers, last-consumer
-    teardown. The most API-heavy candidate and the most likely to belong
-    INSIDE lite-query next to its cache entries instead -- do not build
-    speculatively.
-
-ASSERTIONS (floor, if the gate opens)
-  Whatever ships: torture tiers extended same-session (a primitive without
-  its soak + fuzz + controls does not ship); Q8's failover matrix consumes
-  the new surface in the same quarter, or the surface is reverted before
-  2.0 -- an enabler nobody enabled is speculative API with a version number.
-
-DONE WHEN
-  the Q8 ruling is recorded here (menu -> commitments), and either 1.4.0
-  ships what Q8 consumes, or this session closes as "not needed in
-  lite-stream" with the reasoning -- both are wins
-```
-
-## 6. How to run it
-
-In order: LS1 -> LS2 -> LS3 -> LS4 (gated). Pipeline per session: planner ->
-coder -> reviewer -> qa; reviewer REJECTED goes back to coder. `status:
-planned -> shipped` in the brief's frontmatter on publish, with the /release
-drill (fail closed; the drill owns version bumps; VERSION site list from
-LS2 on: package.json, Stream.js header, VERSION const, llms.txt if it ever
-gains a version string).
-
-Habits this roadmap is built around (inherited, locally re-proven):
-1. **Reproduce by running, never infer.** Every ledger row above has a
-   command. LS-01 existed for two shipped versions because a comment was
-   trusted over a run.
-2. **A green suite that skips its GC tier is a green light over a hole.**
-   Fourth suite recurrence (Q-02, AR-02, AW-14, LS-02). The fix is always
-   the same: the default gate runs everything.
-3. **Claims about a peer are facts about a VERSION of a peer.** The dispose
-   assumption was never true of any version; the floor claim happened to be
-   true of all of them. Neither status was known until today. The floor
-   matrix and the conformance corpus exist so both stay known.
-4. **Budgets, not widened rules.** By-design allocations (state objects,
-   snapshot arrays, protocol promises) get named per-scenario budgets in
-   s5; the global maxMajor: 0 rule never widens.
-
-## Parking ledger (deferred, with reasons and tripwires)
-
-- **Dispose-aware pumps** (the LS-01 behavioral fix): IMPOSSIBLE in-library
-  today -- lite-signal 1.5.0 exposes no disposed-oracle (2b). Tripwire:
-  lite-signal ships one -> un-park, wire into fromAsyncIterable/pipeToSignal
-  teardown, upgrade the LS1 pinned "pump continues" tests into "pump stops"
-  tests in the same change. Until then: docs + pins (LS1).
-- **toAsyncIterable dispose-source hardening** (LS-04): same tripwire, same
-  fate (pending next() could reject instead of hang).
-- **mapLimit / transform concurrency** on fromAsyncIterable (from the 1.0
-  ledger): trigger re-grounded -- two or more SUITE consumers writing the
-  same bounded-concurrency wrapper. None exist today (checked: only
-  StreamQuery consumes, no concurrency wrapper).
-- **toAsyncIterable overflow policies** (drop-newest / throw / block):
-  trigger unchanged -- a consumer demonstrating drop-oldest causes
-  observable correctness issues. None known.
-- **mergeIterables / splitSignal**: trigger re-grounded from "first Twitch
-  consumer" to "first suite consumer needing >= 2 async sources into one
-  reactive surface with shared cancellation". Q8's leader might be that
-  consumer -- if so it routes through the LS4 menu, not around it.
-- **fromEventTarget(target, eventName)**: browser-facing sugar; trigger:
-  the pattern recurring across suite demos. demo/index.html is the place to
-  look first (unaudited against the demo-audit law -- run that skill next
-  time the demo is touched).
-- **pipeToSignal backpressure "block"**: requires effect-completion
-  semantics lite-signal does not have (2b-class cross-package fact).
-  Tripwire: lite-signal ships them.
-- **opts.equals for buffer-mode snapshot dedup**: trigger: a consumer
-  demonstrating redundant snapshot propagation mattering in a profile.
-- **stats() diagnostic surface**: superseded in part by droppedCount/
-  overflowCount; remainder (yields, startedAt, settledAt) waits for the
-  lite-query Q7 devtools feed to define what a stream should report --
-  tripwire: Q7 ships and asks.
-- **RangeReader recipe** (bake-stream): docs-only candidate -- lazy shard
-  walk -> async generator -> fromAsyncIterable; needs bake-stream >= MQ1
-  (abortable range reads) so the AbortSignal story is end-to-end. Tripwire:
-  MQ1 ships.
-- **propagate: "always"** and **full combinators (map/filter/debounce/...)**:
-  never -- see History; the async-generator composition answer stands.
-
-## History (preserved from the 1.0/1.1 roadmap; the shipped 1.1.0 CHANGELOG points here)
-
-### Shipped in 1.1.0 -- toAsyncIterable enrichment
-
-Six additions, each with the triggering signal that moved it out of
-deferred status: `mode: "latest" | "buffer"` (vocabulary match with
-lite-query's streamQuery + reactive-state consumers); `filter` (removes the
-per-yield wrapper-generator allocation); `timeout` + `TimeoutError` export
-(replaces external AbortController boilerplate; structurally identical to
-lite-await's class, deliberately not imported -- the zero-dep story);
-`Symbol.asyncDispose` on node >= 20 (`await using`); multi-waiter FIFO
-queue (latent 1.0.0 bug: `Promise.all([iter.next(), iter.next()])` silently
-lost the first resolver); `overflowCount` (mode-neutral alias for
-`droppedCount`). Full details: CHANGELOG.md [1.1.0].
-
-### Non-goals carried forward verbatim
-
-No standalone scheduler; no retry/backoff policy (compose lite-await);
-no WebSocket/EventSource adapters (they belong to the consuming SDK); no
-ReactiveX combinator surface (async generators are the composition story --
-inspectable, debuggable, cancellation-transparent); no multi-iterator
-orchestration beyond a potential mergeIterables (lite-await's allOf/anyOf/
-raceOf own that).
-
-### Versioning policy (unchanged)
-
-Strict semver. 1.x additive only (new exports, new opts fields, new
-state-shape fields); breaking waits for 2.0; patches are fixes/docs only.
-Every addition lands with: a concrete suite consumer, full-lifecycle tests
-(happy + all termination paths), a bench with provenance, and a CHANGELOG
-line with a hot-path-cost note.
-
-## Progress log
-
-- 2026-09-01 -- Roadmap enriched to blueprint form. Ground truth verified by
-  running: 79 tests (71+8 dark under default gate; 79/79 under test:gc,
-  against lite-signal 1.5.0 and 1.2.2 both), bench re-run with provenance,
-  five probes written and committed (bench/findings-probes-2026-09-01.mjs).
-  Ledger LS-01..LS-12 opened; LS-01 (dispose forever-pump, llms.txt claim
-  false since 1.0.0) is the headline. .gitignore added (LS-10 mitigation,
-  lite-query Q1 ruling). Cross-package wiring recorded on both sides:
-  lite-query Q8 spike <-> LS4 gate; LS3 <-> StreamQuery hand-ring rider.
-  Sessions LS1..LS4 defined. Nothing else changed; the tree still builds
-  and tests exactly as published 1.1.0.
-
-- 2026-09-01 -- LS1 (v1.1.1 truth patch) landed in the working tree. LS-01:
-  the dispose-teardown claim corrected in llms.txt, README (two sites), the
-  Stream.js fromAsyncIterable + pipeToSignal docstrings, and the package.json
-  description; the defensive set() catch and its forward comment re-framed as
-  peer-defense (not disposal detection), and the LS-07 pump comment corrected
-  to "direct call, no deferral" -- the Stream.js diff is comment-only and the
-  code-line stream is byte-identical (md5 unchanged, exports unchanged). LS-06:
-  the three phantom CONTRACT-toAsyncIterable-1.1.md references and the
-  Session A/B narrative removed from Stream.js and test/07. LS-08: bench
-  re-measured with provenance (node v26.3.1, macOS arm64, 150ms warmup /
-  500ms runs) and consolidated as llms.txt Performance (the single source of
-  truth); README now cites it with no ops/s digits; the four unreproducible
-  1.1 bench scenarios deleted from the docs (no runnable source in the repo).
-  LS-02: --expose-gc added to the default npm test so the GC tier gates on
-  every run. Added test/08-dispose-behavior.test.mjs (6 pins, LS-01/LS-04);
-  LS-10 no-lockfile sentence added to the README. Measured: npm test 85 pass
-  / 0 fail / 0 skipped; probes P0-P4 structurally unchanged. The LS1 brief's
-  `status:` is left at planned -- it flips at publish, not here.