@zakkster/lite-stream 1.0.0 → 1.1.1

package/ROADMAP.md

@@ -1,191 +1,711 @@
-# @zakkster/lite-stream Roadmap
+# lite-stream -- enriched roadmap (post-1.1.0)
 
-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.
+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`.
 
-## 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."
+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).
 
 ---
 
-## 1.1.0 candidates
-
-### Concurrent mapping (`mapLimit`)
+## 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.
 
-```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
-});
+```
+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
 ```
 
-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 modes
+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
 
-`toAsyncIterable` currently only does drop-oldest on overflow. Some
-consumers might want:
+```
+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)
+```
 
-- `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)
+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).
 
-**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.
+## 5. The briefs
 
-**Triggering signal:** A consumer demonstrating that drop-oldest causes
-observable correctness issues for their use case.
+===============================================================================
+# LS1 -- lite-stream v1.1.1 -- the docs tell the truth and the gates run
+===============================================================================
 
+```markdown
 ---
-
-### `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.
-
+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: []
 ---
 
-### `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.
+# 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.
+```
 
-**Triggering signal:** A consumer demonstrating a real need to fan-out a
-single async source into two reactive surfaces.
+===============================================================================
+# LS2 -- lite-stream v1.2.0 -- the law's gate, able to fail
+===============================================================================
 
+```markdown
 ---
-
-## 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.
-
+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]
 ---
 
-## 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;
-    }
-}
+# 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
 ```
 
-Not as pretty as `source.pipe(debounce(500))`, but inspectable, debuggable,
-and composes with everything else in the JS async ecosystem.
+===============================================================================
+# LS3 -- lite-stream v1.3.0 -- the consumer contract session
+===============================================================================
 
+```markdown
 ---
-
-### `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.
-
+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)"
 ---
 
-## Non-goals
-
-These will never ship in `lite-stream`:
+# 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
+```
 
-- **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.
+===============================================================================
+# 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]
 ---
 
-## 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:
+# 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
+```
 
-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
+## 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.