@zakkster/lite-stream 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 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
@@ -148,6 +203,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
 
@@ -305,15 +308,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 +467,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 +478,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-*`:
+85 tests across `test/01-*` through `test/08-*`:
 
 - `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
   Iterable acceptance variants, pre-aborted, subscriber observability
@@ -552,6 +502,10 @@ 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)
 
 Run via `npm test`.
 
@@ -562,12 +516,19 @@ 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`.
+
+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.
 
 ## What this is not