@zakkster/lite-stream 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,12 +7,149 @@ 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
+comment-only.** Every shipped sentence the runnable probes could refute is
+corrected, and the previously dark GC tier now gates on the default test run.
+
+### Fixed
+
+- **dispose-teardown claim (LS-01)** -- llms.txt, README, the `Stream.js`
+  `fromAsyncIterable` docstring, and the `package.json` description all
+  claimed the pump detects a disposed result signal on the next `sig.set()`
+  and cleans up silently. It never did: `set()` after `dispose()` is a
+  silent no-op in lite-signal 1.2.2 and 1.5.0, so the pump keeps pulling and
+  neither `iterator.return()` nor any callback fires. Corrected to the true
+  behavior -- AbortSignal or natural completion are the only stop mechanisms.
+  The defensive `catch` around `set()` and its comment were re-framed
+  accordingly.
+- **phantom contract doc + session narrative (LS-06)** -- three references
+  to a non-existent `CONTRACT-toAsyncIterable-1.1.md` (in `Stream.js` and
+  `test/07-to-async-iterable-rich.test.mjs`) and the "Session A/Session B"
+  development narrative were removed; the locked 1.1 semantics now point at
+  CHANGELOG.md [1.1.0] and llms.txt.
+- **pump deferral comment (LS-07)** -- the comment claimed a microtask
+  deferral that is not in the code. `pump()` is called directly; the stack
+  stays bounded because the continuation runs from a `.then()` handler.
+- **perf numbers (LS-08)** -- the shipped ops/s figures named no node
+  version, date, or machine and no longer matched a current run. Re-measured
+  once with provenance; llms.txt (Performance) is now the single source of
+  truth and README cites it. Four 1.1 `toAsyncIterable` bench scenarios
+  (`latest-1to1-x10`, `latest-churn-100`, `filter-timeout`, `multi-waiter-x3`)
+  were removed from the docs as unreproducible -- no runnable source for them
+  exists in the repo; only the six scenarios `bench/bench.mjs` runs are cited.
+
+### Added
+
+- **`test/08-dispose-behavior.test.mjs`** -- 6 tests pinning the TRUE dispose
+  semantics (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 escape hatch).
+- **`--expose-gc` on the default `npm test`** (LS-02) -- the 8 GC-tier tests
+  were dark under the default gate (71 run, 8 skipped); they now run on every
+  `npm test` (85 total, 0 skipped on Node 20+). `npm run test:gc` is retained
+  as an alias.
+- **no-lockfile policy** (LS-10) -- one sentence in the README Testing
+  strategy documents why no `package-lock.json` is committed and how the peer
+  floor is verified.
+
+### Testing
+
+- 85 tests across `test/01-*` through `test/08-*` (up from 79 in 1.1.0). All
+  pass under `npm test` and `npm run test:gc`; per-scenario bench numbers with
+  provenance live in llms.txt (no ops/s digits are pinned in this changelog).
+
+---
+
 ## 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
 
@@ -148,6 +285,8 @@ All three paths handled structurally; abort listeners always removed.
 Additionally: if the consumer disposes the result signal externally, the
 pump detects on next `sig.set()` and tears down silently (no `onError` --
 this is consumer-initiated cleanup).
+(Superseded in 1.1.1: this claim was never true -- see [1.1.1] and ROADMAP
+LS-01.)
 
 ### Performance (Node v22, --expose-gc, 500ms runs)
 

package/README.md

@@ -116,10 +116,11 @@ The abort listener is registered with `addEventListener("abort", ...)` and
 **always removed** on any of the three paths -- no AbortSignal accumulates
 dangling listeners across stream lifecycles.
 
-If the consumer disposes the result signal via `lite-signal`'s `dispose()`,
-the pump detects the disposal on its next attempted `sig.set()`, tears down
-the iterator silently (no `onError` fired -- this is consumer-initiated
-cleanup, not a stream error), and exits.
+Disposing the result signal does NOT stop the pump: the iterator keeps
+pulling. AbortSignal or natural completion are the only stop mechanisms.
+`iterator.return()` is never called and no callback fires, because
+`lite-signal`'s `set()` after `dispose()` is a silent no-op -- the pump never
+learns of the disposal. Abort `opts.signal` to stop early. See ROADMAP LS-01.
 
 ## API reference
 
@@ -182,6 +183,8 @@ Use `pipeToSignal` when:
 - You want a `stop` fn instead of an `AbortController` for cleanup
 
 **Does NOT dispose the target signal.** The caller owns its lifetime.
+Disposing the target signal does NOT stop the pump: call the returned stop
+fn or abort `opts.signal`.
 
 ### toAsyncIterable
 
@@ -246,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:
@@ -305,15 +318,8 @@ aborts on detach, `toAsyncIterable` catches the abort and calls
 ## Zero-GC hot paths
 
 `lite-stream`'s hot paths -- per-yield state allocation and per-pull abort
-checks -- minimize per-op allocation. Measured retention is sub-byte per op
-across all scenarios:
-
-```
-from-latest-10                 178K ops/s   0.07 B/op
-from-buffer-20-drop            128K ops/s   0.13 B/op
-abort-cycle                     84K ops/s   0.71 B/op
-pipe-to-signal                 235K ops/s   0.10 B/op
-```
+checks -- minimize per-op allocation. Current numbers with provenance live in
+`llms.txt` (Performance); re-run `npm run bench` on your target.
 
 Per-yield, `"latest"` mode allocates exactly one wrapper state object. The
 underlying signal node is reused via lite-signal's pool. `"buffer"` mode
@@ -471,8 +477,9 @@ const ws = new WebSocket("wss://logs.example.com/ingest");
 - **Sync `Iterable<T>`**: accepted via `Symbol.iterator`. Pulls happen
   microtask-asynchronously even for sync sources, so caller's `effect()`
   can wire up before the first yield.
-- **Consumer disposes the signal mid-stream**: pump detects on next
-  `sig.set()`, tears down the iterator silently. No `onError` fired.
+- **Consumer disposes the signal mid-stream**: the pump keeps pulling.
+  `iterator.return()` is not called and no callback fires; abort
+  `opts.signal` to stop.
 - **Buffer mode snapshot array**: a fresh array per yield. Past observers
   hold stable, non-mutated references.
 - **Disposing the signal multiple times**: lite-signal's `dispose` is
@@ -481,62 +488,15 @@ const ws = new WebSocket("wss://logs.example.com/ingest");
 
 ## Benchmarks
 
-Run via `npm run bench` (requires `--expose-gc`).
-
-```
-[1] fromAsyncIterable latest mode -- 10-item async gen
-  from-latest-10                       178,554 ops/s   retained: 0.07 B/op
-
-[2] fromAsyncIterable buffer mode -- 20-item gen, maxBuffer 5
-  from-buffer-20-drop                  128,630 ops/s   retained: 0.13 B/op
-
-[3] Abort cycle -- infinite gen, abort after first yield
-  abort-cycle                           84,102 ops/s   retained: 0.71 B/op
-
-[4] pipeToSignal -- pump existing signal directly
-  pipe-to-signal                       235,376 ops/s   retained: 0.10 B/op
-
-[5] toAsyncIterable -- 10 signal updates, consumer drains in order
-  to-async-iterable                     42,480 ops/s   retained: ~0 B/op
-
-[6] toAsyncIterable -- producer overflow, drop-oldest
-  to-async-iterable-overflow            62,164 ops/s   retained: ~25 B/op
-
---- 1.1 additions ---
-
-[7] toAsyncIterable mode:latest -- 10 write/next pairs per cycle
-  to-async-iterable-latest-1to1-x10    119,278 ops/s   retained:  0.12 B/op
-
-[8] toAsyncIterable mode:latest -- 100 writes coalesced, single read
-  to-async-iterable-latest-churn-100    60,674 ops/s   retained:  0.28 B/op
-
-[9] toAsyncIterable filter + timeout -- consumer wins before timeout
-  to-async-iterable-filter-timeout     141,080 ops/s   retained: -11.80 B/op
-
-[10] toAsyncIterable multi-waiter -- 3 concurrent next() calls
-  to-async-iterable-multi-waiter-x3    120,020 ops/s   retained: -0.01 B/op
-```
-
-(Node v22, 150ms warmup, 500ms runs.)
-
-The full lifecycle (construct, pull, settle, dispose) of `fromAsyncIterable`
-in latest mode runs at 178K ops/s with sub-byte/op retained heap. Per-pull
-allocation is dominated by the iterator's own microtask cost, not by
-lite-stream's wrapper state.
-
-1.1's `toAsyncIterable mode:"latest"` amortizes to ~2.4M ops/s per operation
-(divide the reported cycle rate by the inner loop count). The filter+timeout
-scenario `[9]` runs at 141K ops/s with NEGATIVE retained heap -- the
-timer-clear discipline on `iter.return()` lets V8's subsequent GC pass
-reclaim more than the pre-run measurement. The multi-waiter scenario `[10]`
-confirms the 1.0.0 latent-bug fix (single-slot `pendingResolve` overwriting
-the first resolver) works cleanly under bench load.
+Run via `npm run bench` (requires `--expose-gc`). Current numbers with
+provenance live in `llms.txt` (Performance); re-run `npm run bench` on your
+target.
 
 ## Testing strategy
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-74 tests across `test/01-*` through `test/07-*`:
+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
@@ -552,6 +512,15 @@ the first resolver) works cleanly under bench load.
   filter (including throwing-filter no-writer-surface discipline), timeout
   + TimeoutError, Symbol.asyncDispose (Node 20+ guarded), multi-waiter
   queue, `overflowCount` alias, 4K structural cleanup cycles
+- `08-dispose-behavior.test.mjs` -- pins the TRUE dispose semantics
+  (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`.
 
@@ -562,12 +531,32 @@ ceilings at 2 MB for the 1.0.0 paths (2K latest, 1K buffer, 1K abort) and
 the 1.1 additions (5K `mode:"latest"` resolve, 3K timeout, 1K buffer
 fill+drain, 2K `mode:"latest"` churn, 2K filter-throw).
 
-Run via `npm run test:gc`.
+The GC tier now runs under the default `npm test` (the script carries
+`--expose-gc`), so these budgets gate on every run; `npm run test:gc` is
+retained as an alias.
 
 ### Tier 3 -- performance (measured throughput)
 
-`bench/bench.mjs` -- ten scenarios (six 1.0.0 + four 1.1); throughput and
-B/op retained. Run via `npm run bench`.
+`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
+`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.0
+// @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
@@ -22,7 +22,8 @@
 //
 // 1.1 added `mode: "latest"`, `filter`, `timeout`, `Symbol.asyncDispose`,
 // multi-waiter FIFO queue, and `overflowCount` on `toAsyncIterable`. See
-// CONTRACT-toAsyncIterable-1.1.md and CHANGELOG.md for the full 1.1 story.
+// CHANGELOG.md [1.1.0] and llms.txt (toAsyncIterable section) for the full
+// 1.1 story.
 //
 // Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
 // MIT License
@@ -40,9 +41,10 @@ import { signal as _signal } from "@zakkster/lite-signal";
  * duck-check via `e.name === "TimeoutError"` across both packages -- but
  * NOT imported from lite-await, to preserve lite-stream's zero-dep story.
  *
- * The wiring (start / clear / reject with) is Session B's territory; this
- * class exists in Session A only so the exported shape is stable and the
- * failing test suite can compile.
+ * A structural twin of lite-await's TimeoutError, deliberately not imported
+ * (zero-dep by design), carrying `name === "TimeoutError"` and a `.timeout`
+ * field (the elapsed deadline in ms). The duck-check is suite-wide vocabulary;
+ * renaming it would be a breaking change everywhere it is consumed.
  */
 class TimeoutError extends Error {
     constructor(timeoutMs) {
@@ -145,11 +147,11 @@ function closeIterator(iter) {
  *   - iterator throws
  *   - opts.signal aborts (the iterator's return() is called best-effort)
  *
- * To stop the stream without an AbortSignal, you can either:
- *   - dispose the returned signal via lite-signal's dispose(sig); pending
- *     iterator pulls will see the signal as disposed on next set() (no-op),
- *     but the iterator continues until natural completion. PREFER AbortSignal.
- *   - pass opts.signal and abort it externally.
+ * Disposing the result signal does NOT stop the pump: the iterator keeps
+ * pulling. AbortSignal or natural completion are the only stop mechanisms.
+ * A disposed signal's set() is a silent no-op, so the pump never learns of
+ * the disposal; an infinite source becomes an unbounded background loop.
+ * Pass opts.signal and abort it to stop early. See ROADMAP LS-01.
  *
  * @template T
  * @param {AsyncIterable<T> | AsyncIterator<T> | Iterable<T>} source
@@ -301,9 +303,11 @@ function fromAsyncIterable(source, opts) {
                 }
                 const v = result.value;
                 // Build the new state from lastState (never sig.peek), then
-                // commit to both lastState and sig. If sig.set throws (consumer
-                // disposed the signal externally), bail and tear down the
-                // iterator so we don't keep pulling into the void.
+                // commit to both lastState and sig. The try/catch around set()
+                // is defensive against a peer whose set() throws; on a throw we
+                // bail and tear down the iterator rather than pull into the
+                // void. Disposal is NOT the trigger -- set() after dispose() is
+                // a silent no-op in lite-signal 1.2.2 and 1.5.0 (see LS-01).
                 let newState;
                 if (mode === "latest") {
                     newState = {
@@ -341,16 +345,22 @@ function fromAsyncIterable(source, opts) {
                 try {
                     sig.set(newState);
                 } catch (_e) {
-                    // Signal disposed externally. Tear down quietly without
-                    // firing onError -- this is consumer-initiated cleanup,
-                    // not a stream error.
+                    // Defensive against a peer signal whose set() throws. This
+                    // is NOT disposal detection: set() after dispose() is a
+                    // silent no-op in lite-signal 1.2.2 and 1.5.0 (probe P0),
+                    // so this branch has never fired against any published
+                    // peer. If it ever does, tear down without firing onError.
                     stopped = true;
                     cleanup();
                     closeIterator(iter);
                     return;
                 }
-                // Defer the next pull through the microtask queue so back-to-back
-                // synchronous yields don't blow the stack.
+                // pump() is called DIRECTLY here -- no explicit deferral at
+                // this site. The stack is already unwound because this
+                // continuation runs from a .then() handler, i.e. a fresh
+                // microtask. Proven safe: 1,000,000 synchronous values drained
+                // in ~80ms with no stack overflow (probe P4, node v26.3.1,
+                // 2026-09-01).
                 pump();
             },
             function (err) {
@@ -420,6 +430,8 @@ function makeErrorState(prevState, err, mode) {
  *   - You want a stop fn instead of an AbortController for cleanup
  *
  * NOTE: this does NOT dispose the target signal. The caller owns its lifetime.
+ * Disposing the target signal does NOT stop the pump: call the returned
+ * stop fn or abort opts.signal. See ROADMAP LS-01.
  *
  * @template T
  * @param {AsyncIterable<T> | AsyncIterator<T>} source
@@ -557,7 +569,8 @@ const ASYNC_DISPOSE = (typeof Symbol !== "undefined" && Symbol.asyncDispose)
  * where Promise.all([iter.next(), iter.next()]) silently lost the first
  * resolver.
  *
- * See CONTRACT-toAsyncIterable-1.1.md for the full locked semantics.
+ * See CHANGELOG.md [1.1.0] and llms.txt (toAsyncIterable section) for the
+ * full locked semantics.
  *
  * @template T
  * @param {import("@zakkster/lite-signal").Signal<T> | import("@zakkster/lite-signal").Computed<T>} sig
@@ -860,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
 
@@ -61,7 +61,9 @@ const stop = pipeToSignal(source, targetSig, {
 });
 ```
 
-Does NOT dispose the target signal. The caller owns its lifetime.
+Does NOT dispose the target signal. The caller owns its lifetime. Disposing
+the target signal does NOT stop the pump: call the returned stop fn or abort
+opts.signal.
 
 ### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount, overflowCount }`
 
@@ -118,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:
@@ -129,9 +137,13 @@ imported from lite-await -- lite-stream stays zero-dep.
 The abort listener is always removed on any of the three paths -- no
 AbortSignal accumulates dangling listeners.
 
-If the consumer disposes the result signal via lite-signal's `dispose()`,
-the pump detects on next `sig.set()` and tears down silently (no onError --
-this is consumer-initiated cleanup, not a stream error).
+Disposing the result signal does NOT stop the pump: the iterator keeps
+pulling. AbortSignal or natural completion are the only stop mechanisms.
+`iterator.return()` is never called and neither `onError` nor `onDone` ever
+fire, because lite-signal's `set()` after `dispose()` is a silent no-op (in
+1.2.2 and 1.5.0), so the pump never learns of the disposal. For an infinite
+source (SSE, a live feed) this turns the stream into an unbounded background
+loop. Abort `opts.signal` to stop early. See ROADMAP LS-01.
 
 ## Key invariants
 
@@ -243,36 +255,44 @@ states: {
   true}` per the async iteration protocol; only `return()`'s own returned
   Promise carries the value.
 - DO NOT dispose the source signal while an iterable is still consuming
-  from it. Call `iter.return()` first; disposing an in-flight source is
-  undefined behavior.
+  from it. Call `iter.return()` first. A pending `next()` at the moment of
+  disposal never settles -- it neither resolves nor rejects; the only escape
+  hatch is the `timeout` option, which rejects the pending `next()` with
+  `TimeoutError` once its deadline elapses. See ROADMAP LS-04.
 
 ## Performance
 
-178K ops/s for the full lifecycle in `fromAsyncIterable` latest mode
-(construct + pull + settle + dispose), sub-byte/op retained heap. 235K
-ops/s for `pipeToSignal` direct. 84K ops/s for the full abort cycle.
+Measured 2026-09-01 on node v26.3.1 (macOS arm64, laptop class), 150ms
+warmup / 500ms runs, via npm run bench. Your numbers will differ -- re-run
+npm run bench on your target.
+
+The six scenarios `bench/bench.mjs` actually runs (ops/s, retained B/op):
+
+- `from-latest-10`: 68,156 ops/s, 0.3218 B/op
+- `from-buffer-20-drop`: 61,960 ops/s, 0.4715 B/op
+- `abort-cycle`: 29,078 ops/s, 1.5132 B/op
+- `pipe-to-signal`: 50,098 ops/s, 0.0853 B/op
+- `to-async-iterable`: 198,948 ops/s, -8.4923 B/op
+- `to-async-iterable-overflow`: 208,790 ops/s, 0.1013 B/op
 
-1.1 `toAsyncIterable` throughput (Node v22, 500ms runs):
-- `mode: "latest"` 1:1 alternation: 119K cycles/s (2.4M ops/s per pair)
-- `mode: "latest"` churn (100 writes coalesced): 60K cycles/s (6M
-  writes/s absorbed into the single slot)
-- `filter + timeout`: 141K ops/s, negative retained (the timer-clear
-  discipline on `iter.return()` helps V8 reclaim more than baseline)
-- multi-waiter x3 concurrent .next(): 120K cycles/s
+The negative B/op on `to-async-iterable` is a GC-timing artifact (the
+post-run gc() reclaims more than the pre-run baseline held); it is not a
+zero-alloc guarantee. Per-scenario numbers only -- there is no "sub-byte
+across all scenarios" claim.
 
 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.
+is caught up; `mode: "buffer"` also zero when no waiter is pending
+(gated: test/torture.mjs s5, per-scenario budgets).
 
 ## Files
 
-- `Stream.js` -- single-file ESM implementation (~830 lines)
+- `Stream.js` -- single-file ESM implementation (~875 lines)
 - `Stream.d.ts` -- TypeScript types with discriminated state union
 - `README.md` -- full docs with integration recipes
 - `llms.txt` -- this file
 - `CHANGELOG.md` -- version history
-- `ROADMAP.md` -- deferred features
 
 ## Author
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-stream",
-  "version": "1.1.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, abort, dispose). The multi-shot dual of lite-await's fromPromise.",
+  "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",
   "type": "module",
@@ -22,14 +22,16 @@
     "README.md",
     "llms.txt",
     "LICENSE.txt",
-    "CHANGELOG.md",
-    "ROADMAP.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --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,239 +0,0 @@
-# @zakkster/lite-stream Roadmap
-
-Features deliberately deferred from 1.0 with the rationale. Each is gated
-on a specific triggering signal from a real consumer rather than
-speculative inclusion.
-
-## Triggering signals
-
-This roadmap exists because of the same discipline that drove
-`lite-signal`'s and `lite-statechart`'s development: ship the minimum that
-solves the actual problem, defer everything else until a concrete consumer
-demonstrates the need with a real code site. Nothing in this file is
-"planned for 1.x" -- everything is "considered, deferred, waiting for a
-triggering signal."
-
----
-
-## Shipped in 1.1.0 -- toAsyncIterable enrichment
-
-The six additions below landed together in 1.1.0. Each is documented with
-the triggering signal that justified moving it out of "deferred" status.
-
-### `mode: "latest" | "buffer"` (default `"buffer"`)
-**Triggering signal:** vocabulary mismatch with `@zakkster/lite-query`'s
-`streamQuery`, which already offers `mode: "latest"` on its
-`fromAsyncIterable` side. Bridging a signal INTO streamQuery via
-`toAsyncIterable` needed a matching option. Twitch overlay reactive-state
-use ("show current frame, not the backlog") is the second consumer.
-
-### `filter` option
-**Triggering signal:** per-value gating was previously done with async-
-generator wrappers around `toAsyncIterable`. In hot-path use (reactive
-state filtered by predicate) the wrapper adds an allocation per yield.
-Inlining the filter into the subscription callback removes the wrapper
-cost.
-
-### `timeout` option + new `TimeoutError` export
-**Triggering signal:** consumers wrap `toAsyncIterable` with external
-`AbortController` + `setTimeout` boilerplate today. Native `timeout` opt
-saves ~10 lines per usage. `TimeoutError` is structurally identical to
-lite-await's class (`e.name === "TimeoutError"` duck-checks work across
-both packages), NOT imported from lite-await -- zero-dep story preserved.
-
-### `Symbol.asyncDispose` on Node 20+
-**Triggering signal:** Node 20 shipped, `await using` is idiomatic modern
-async-iterator ergonomics. Absent on older runtimes; `iter.return()`
-remains the portable path.
-
-### Multi-waiter FIFO queue (latent bug fix)
-**Triggering signal:** correctness. `Promise.all([iter.next(),
-iter.next()])` silently lost the first resolver in 1.0.0 (single-slot
-`pendingResolve`). Async generators queue concurrent .next() calls; ours
-now does too. Invisible fix for correct callers; unblocks
-`Promise.all`-style consumers.
-
-### `overflowCount` getter (alias for `droppedCount`)
-**Triggering signal:** vocabulary consistency with `mode: "latest"`.
-"Dropped" reads as FIFO-specific; "overflow" is mode-neutral.
-`droppedCount` continues to work identically in both modes.
-
-## 1.1.0 candidates
-
-### Concurrent mapping (`mapLimit`)
-
-```js
-const live = fromAsyncIterable(urls, {
-    transform: async (url, ctx) => {
-        return await fetch(url, { signal: ctx.signal }).then((r) => r.json());
-    },
-    concurrency: 4                      // up to 4 in-flight transforms
-});
-```
-
-A consumer-side pattern where each yielded value needs an async
-transformation, and the user wants bounded concurrency. Currently doable
-by composing async generators externally, but if multiple consumers (helix
-batch enrichment, EBS request fan-out) end up writing the same pattern,
-add it.
-
-**Triggering signal:** Two or more consumers in the ecosystem writing
-identical "transform-with-concurrency-limit" wrappers around
-`fromAsyncIterable`.
-
----
-
-### Reverse-direction buffering overflow policies
-
-`toAsyncIterable` in `mode: "buffer"` currently only does drop-oldest on
-overflow. Some consumers might want:
-
-- `overflow: "drop-newest"` -- reject incoming when full
-- `overflow: "throw"` -- iterator throws on overflow
-- `overflow: "block"` -- producer-side signal back-channel (requires
-  consumer cooperation; significant API change)
-
-**Not to be confused with `mode: "latest"`** (shipped in 1.1), which is a
-different backpressure MODEL -- single-slot overwrite semantics rather
-than a bounded FIFO with a different overflow policy. See the "Shipped in
-1.1.0" section above.
-
-**Why deferred from 1.0:** Drop-oldest is the only mode any real consumer
-in the roadmap actually wants. Adding alternatives speculatively grows the
-API surface for no measurable benefit.
-
-**Triggering signal:** A consumer demonstrating that drop-oldest causes
-observable correctness issues for their use case.
-
----
-
-### `mergeIterables(iterA, iterB, ...)`
-
-Merge multiple async iterators into one signal, interleaving values as
-they arrive. Useful for "watch both helix and pubsub for follower
-changes" patterns.
-
-**Why deferred from 1.0:** Doable today by composing iterators externally
-(an async generator that races multiple sources). Built-in support cleans
-up the cancellation story (one AbortSignal cancels all sources) but adds
-complexity.
-
-**Triggering signal:** First Twitch consumer that needs to merge >= 2
-async sources into a single reactive surface with shared cancellation.
-
----
-
-### `splitSignal(sig, predicate) -> [matchingSig, restSig]`
-
-The dual of `mergeIterables`: split a signal's value stream into two based
-on a predicate, exposing both halves as new signals.
-
-**Why deferred from 1.0:** No concrete consumer in the roadmap needs this.
-Speculative.
-
-**Triggering signal:** A consumer demonstrating a real need to fan-out a
-single async source into two reactive surfaces.
-
----
-
-## 1.2.0+ candidates (smaller, lower priority)
-
-- **`fromEventTarget(target, eventName)`** -- a wrapper that turns DOM
-  EventTarget events into an async iterable feeding a signal. Doable
-  today via async generators, but ergonomically common. Add if the
-  pattern recurs across browser-facing consumers (e.g. window resize
-  observers, pointer event streams).
-
-- **`backpressure: "block"` for pipeToSignal** -- await the target
-  signal's effects before pulling the next value. Requires effect-
-  completion semantics from lite-signal, which don't exist today.
-
-- **`opts.equals` for diff-mode signals** -- by default the underlying
-  signal uses lite-signal's default `Object.is`. Allow opt-in to a custom
-  equality predicate for buffer-mode snapshot arrays (where Object.is
-  always reports them as distinct).
-
-- **Diagnostic surface** -- `live.stats() -> { yields, drops, errors,
-  startedAt, settledAt }` for telemetry. Useful but no consumer asking
-  for it yet.
-
----
-
-## Deferred indefinitely
-
-### Full reactive stream combinators
-
-`map`, `filter`, `take`, `skip`, `debounce`, `throttle`, etc. -- the
-ReactiveX / RxJS surface area.
-
-**Why:** Once you have async iterators, all of these are five-line async
-generators. Adding them to lite-stream would create two ways to do the
-same thing, where the second way (combinator API) hides the source code
-and makes the cancellation model harder to reason about. The async
-generator form is more inspectable and composes naturally with all of
-JS's existing async tooling.
-
-If a consumer wants `debounce`, they write:
-
-```js
-async function* debounce(source, ms, signal) {
-    let pending;
-    for await (const v of source) {
-        if (pending) clearTimeout(pending);
-        pending = await new Promise((r) => {
-            setTimeout(() => r(v), ms);
-            signal?.addEventListener("abort", () => r(undefined));
-        });
-        if (pending !== undefined) yield pending;
-    }
-}
-```
-
-Not as pretty as `source.pipe(debounce(500))`, but inspectable, debuggable,
-and composes with everything else in the JS async ecosystem.
-
----
-
-### `propagate: "always"` mode
-
-A mode where every yielded value triggers an effect run even if
-`Object.is`-equal to the previous. Currently the underlying signal's
-default equality (`Object.is`) is sufficient for all known consumers --
-our wrapper state object is fresh per yield, so dedup never kicks in.
-
-**Why deferred:** No consumer wants force-propagate semantics in
-practice; the wrapper state shape already guarantees per-yield
-propagation.
-
----
-
-## Non-goals
-
-These will never ship in `lite-stream`:
-
-- **A standalone scheduler.** Microtask / setImmediate decisions stay
-  inside the pump. The library does not expose a scheduling API.
-- **A retry/backoff policy.** Consumers compose with `lite-await`'s
-  `withTimeout`, `withAbort`, and a plain `for` loop. Every Twitch SDK
-  endpoint has different retry semantics; a single policy would be
-  opinionated wrong for half of them.
-- **WebSocket / EventSource adapters.** Those belong in the SDK that
-  consumes them (lite-twitch-ebs, lite-twitch-pubsub), not in lite-stream.
-- **Concurrent multi-iterator orchestration beyond `mergeIterables`** --
-  use `lite-await`'s `allOf` / `anyOf` / `raceOf` for that.
-
----
-
-## Versioning policy
-
-`@zakkster/lite-stream` follows strict semver. 1.x is a stable API; only
-additive changes (new exports, new opts fields, new state-shape fields)
-ship in minor releases. Breaking changes wait for 2.0. Patch releases are
-bug fixes only.
-
-Each addition will land with:
-
-1. A concrete triggering consumer in the `@zakkster/lite-*` ecosystem
-2. Tests covering the full lifecycle (happy + all three cleanup paths)
-3. A bench measuring throughput + retained heap
-4. A line item in CHANGELOG.md with a hot-path-cost note