@zakkster/lite-stream 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,169 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 1.3.0 -- 2026-09-02
+
+**The consumer contract.** The one real bug the torture harness found is fixed
+(LS-13), and the three things the flagship consumer hand-rolled around
+`pipeToSignal` -- a buffer window, a first-value tap, an abort filter -- are
+offered natively as additive options. Every 1.1.0 call shape stays
+byte-identical; the abort vocabulary is pinned in a decision doc.
+
+### Fixed
+
+- **LS-13** -- a `next()` result object whose `done` or `value` is a THROWING
+  getter now routes to the terminal error state with `onError` fired exactly
+  once, in both pumps (`fromAsyncIterable` and `pipeToSignal`). Previously the
+  getter fired inside the pump's `.then` onFulfilled with no catch at that
+  site: the throw escaped as an `unhandledRejection` and the signal never
+  settled. Both pumps now read the two result properties once into locals inside
+  a dedicated try/catch that routes to the existing "iterator throws" leg
+  (triplet leg 2). The wrap covers ONLY the two property reads -- the LS-01
+  peer-defense catch around `set()` is separate and untouched.
+
+### Added
+
+- **`pipeToSignal` enrichment** (all additive; the un-optioned path is
+  byte-identical to 1.1.0) -- `mode: "buffer"` with a REQUIRED `maxBuffer`
+  drives the target with a bounded newest-last snapshot array (a fresh array per
+  set), dropping the oldest on overflow; `mode: "latest"` (default) is the
+  1.1.0 direct-set behavior. Validated once at construction: `TypeError` on an
+  unknown mode and on `mode: "latest"` + `maxBuffer`; `RangeError` on
+  missing/invalid `maxBuffer` in buffer mode (the `fromAsyncIterable` message
+  voice). The returned stop fn gains `droppedCount` and `overflowCount` getters
+  (aliases of one overflow counter, 0 in latest mode); the stop fn stays
+  callable and idempotent.
+- **`onValue(v)` tap** on `pipeToSignal` -- fires exactly once per value BEFORE
+  each set (after `transform`). A throwing `onValue` routes through the same
+  `stop` + `onError` leg as a throwing transform (the test/04 precedent).
+- **`onAbort(reason)`** on `pipeToSignal` -- when present, aborts route to it
+  INSTEAD of `onError` (both at the abort listener and the pre-aborted early
+  return), so consumers stop filtering intentional aborts out of their error
+  handler. Absent -> 1.1.0 behavior byte-identical.
+- **`decisions/0001-abort-vocabulary.md`** (LS-12) -- a repo-only decision doc
+  (NOT in `files[]`, never in the tarball) pinning the from-side/to-side abort
+  asymmetry as deliberate and recording the `onAbort` addition and the rejected
+  alternatives. llms.txt carries the contract table citing it.
+- **Torture extensions** -- the `s7e` enriched-surface control (10 controls
+  total: s0-s8 + s7e, each individually non-zero) and the `pipeBuffer64`
+  allocation scenario in s5 (~5 B/op, budget 32 B/op). The s1 LS-13 pin is now a
+  hard assertion; the `pipeSteady` default-path budget is unchanged (the
+  purity proof).
+- **21 new tests** -- `test/10-pipe-enriched.test.mjs` (15: mode/maxBuffer/
+  onValue/onAbort matrix, validation throws, stop-fn observability, abort
+  routing with and without `onAbort`, and a StreamQuery-shaped rewrite parity
+  case) plus 6 LS-13 pins in `test/08-dispose-behavior.test.mjs` (throwing
+  getter -> error state, `onError` once, zero unhandledRejection via a scoped
+  process capture; includes the pinned decision that a `done: true` result
+  with a throwing `value` getter routes to the ERROR leg, not the done leg).
+
+### Changed
+
+- `pipeToSignal`'s `Stream.d.ts` return type is now the callable
+  `PipeToSignalStop` (a stop fn with `readonly droppedCount` / `overflowCount`),
+  and its options are the discriminated `PipeToSignalOptions<T>` union. No new
+  value export -- the surface stays exactly five names.
+
+### Testing
+
+- **111 tests** across `test/01-*` through `test/10-*` (up from 90), 0 fail,
+  0 skip under `npm test` and `npm run test:gc`.
+- `npm run torture` -> `ok`, ~1.77s wall (node v26.3.1, macOS arm64,
+  2026-09-02); `maxMajorsPerKOp` 0.000 in every s5 scenario; `pipeSteady`
+  1.38 B/op (budget 32, UNCHANGED) and the new `pipeBuffer64` ~5 B/op
+  (budget 32). Controls are 10/10 individually non-zero; `TORTURE_SEED` replay
+  ok; probes P0-P4 digit-normalized identical.
+- s7 rewrite-parity case: N=12 values, `maxBuffer=4` -> `droppedCount` 8,
+  newest-last order, semantics identical to the hand-rolled StreamQuery shape.
+- Floor-matrix doctrine unchanged from 1.2.0: `npm run test:floor` runs
+  `npm test` against the pinned `@zakkster/lite-signal@1.2.2` and against the
+  resolved latest; per-scenario s5 budgets, the global `maxMajor` rule never
+  widens.
+
+---
+
+## 1.2.0 -- 2026-09-02
+
+**The law's gate, able to fail.** A torture harness that proves the package's
+own claims -- including the zero-steady-state-allocation sentence that has been
+unverified since 1.0.0 -- plus the drift guards that keep docs, exports, and
+ASCII honest, a `VERSION` export, and the LS-11 packaging cleanup. No behavior
+change: the only `Stream.js` code change is the additive `VERSION` const.
+
+### Added
+
+- **Torture harness** -- `test/torture.mjs` + `test/torture/s0-s8`, run by
+  `npm run torture` (`node --expose-gc test/torture.mjs`): metamorphic laws
+  (s0), degenerate values and hostile iterators (s1), async-iteration protocol
+  conformance (s2), API abuse with a decided policy per case (s3), seeded
+  fuzz-vs-oracle (s4), the allocation gate (s5, `@zakkster/lite-gc-profiler`,
+  `maxMajor` 0 with per-scenario byte budgets), a retention soak (s6,
+  `@zakkster/lite-leak` WeakRef census), the StreamQuery conformance corpus and
+  TimeoutError duck-pact (s7), and the controls tier (s8). Prints `ok`, exits
+  0/1; `TORTURE_SEED` replays a failure; `STREAM_TORTURE_BREAK=<s0..s8|1>` arms
+  each tier's injected breakage so every tier's control exits non-zero.
+- **Scripts** -- `torture`, `torture:control` (all-tiers break lane), and
+  `test:floor`. `verify` gains `torture`. **LS-09 amendment:** the floor lane
+  runs `npm test` ONLY against the pinned peer -- `@zakkster/lite-leak` peers
+  `@zakkster/lite-signal >= 1.5.0`, so pinning `1.2.2` alongside it would put
+  lite-leak outside its supported peer range; torture (which imports lite-leak)
+  runs against the resolved latest only. Fail closed: never run a tool outside
+  its peer range.
+- **`VERSION` export** (LS-05) -- a string that always equals the installed
+  `package.json` version. Declared in `Stream.d.ts`; documented in llms.txt and
+  the README API reference with no embedded version literal. Never re-exported
+  by consumers (suite ruling). The `Stream.d.ts` `TimeoutError` type declaration
+  was also added (the shipped runtime export had no type; the surface-guard
+  requires three-way parity).
+- **`test/09-guards.test.mjs`** (5 tests) -- ascii-guard (every `files[]` +
+  `test/`/`bench/`/`demo/` byte is printable ASCII or LF, empty allowlist) and
+  surface-guard (runtime exports == llms.txt import list == `Stream.d.ts` value
+  exports; `VERSION` string-equals `package.json` version; the declared peer is
+  present in both docs). Each family carries an inline failing control.
+- **devDependencies** -- `@zakkster/lite-leak ^1.10.0` and
+  `@zakkster/lite-gc-profiler ^1.16.0` (torture only; not runtime deps).
+
+### Changed
+
+- **`files[]` drops `ROADMAP.md`** (LS-11) -- the roadmap is a working doc, not
+  a shipped artifact. llms.txt's Files section and the CHANGELOG [1.1.0]
+  forward-reference were reworded so tarball readers are not pointed at an
+  unshipped file.
+- **`test` / `test:gc` globs scoped to `test/*.test.mjs`** so the `node:test`
+  runner does not discover the torture files.
+
+### Fixed
+
+- Docs and packaging only; no runtime behavior changed.
+
+### Known issues
+
+- **LS-13** (S1, opened this release, fix targeted for 1.3.0) -- a `next()`
+  result object whose `done` or `value` is a throwing getter escapes the pump's
+  `.then` onFulfilled uncaught: it surfaces as an unhandledRejection and
+  `fromAsyncIterable` never reaches a terminal state (it should transition to
+  the error state). Torture tier s1 reproduces it with a bounded sentinel and a
+  scoped rejection capture and prints it as `TODO(LS3, LS-13)` in the gate
+  output; it does not fail the gate. This refutes the "iterator throws -> error
+  state" triplet leg for the throwing-getter shape specifically.
+
+### Testing
+
+- **90 tests** across `test/01-*` through `test/09-*` (up from 85), 0 fail,
+  0 skip under `npm test` and `npm run test:gc`.
+- `npm run torture` -> `ok`, ~1.8s wall (node v26.3.1, macOS arm64,
+  2026-09-02); zero steady-state majors in every s5 scenario.
+- `npm run test:floor` -> FLOOR-PASS (`npm test` 90/0 against
+  `@zakkster/lite-signal@1.2.2`) and LATEST-PASS (`npm test` 90/0 + torture ok
+  against the resolved `@zakkster/lite-signal@1.5.0`). The `^1.2.0` peer floor
+  is now a tested fact, not a claim.
+- s5 budget doctrine: per-scenario `maxBytesPerOp` budgets (32 B/op for the
+  caught-up toAsyncIterable and pipeToSignal steady pump; 16 B/op for the
+  by-design fromAsyncIterable state-object and waiter-heavy paths), each ~3x the
+  measured 3-pass peak; the global `maxMajor` rule never widens.
+
+---
+
 ## 1.1.1 -- 2026-09-01
 
 **Truth patch. No API change, no behavior change; the `Stream.js` diff is
@@ -65,9 +228,9 @@ corrected, and the previously dark GC tier now gates on the default test run.
 ## 1.1.0 -- 2026-07-10
 
 **Additive `toAsyncIterable` enrichment.** Six additions, no breaking
-changes. All 1.0.0 callers continue to work without modification. See
-ROADMAP.md's "Shipped in 1.1.0" section for the triggering signals that
-justified each addition.
+changes. All 1.0.0 callers continue to work without modification. Each
+addition below records the triggering signal that justified it; the
+`Added` and `Changed` entries in this section stand on their own.
 
 ### Added
 

package/README.md

@@ -165,16 +165,22 @@ pipeToSignal<T>(
     target: Signal<T>,
     opts?: {
         signal?:    AbortSignal,
+        mode?:      "latest" | "buffer",     // default "latest"
+        maxBuffer?: number,                   // REQUIRED if mode = "buffer"
+        transform?: (value: T) => T,          // per-value map, runs first
+        onValue?:   (value: T) => void,       // tap: fires once BEFORE set
+        onAbort?:   (reason: unknown) => void, // aborts route here, not onError
         onError?:   (err: unknown) => void,
-        onDone?:    () => void,
-        transform?: (value: T) => T
+        onDone?:    () => void
     }
-): () => void   // stop fn (idempotent)
+): (() => void) & { readonly droppedCount: number, readonly overflowCount: number }
 ```
 
 Lower-level companion: pump an existing writable signal from an async
-iterator. The signal's value is replaced directly with each yielded value
-(no `{ value, count, ... }` wrapper). Returns a `stop` function.
+iterator. In the default `"latest"` mode the signal's value is replaced
+directly with each yielded value (no `{ value, count, ... }` wrapper).
+Returns an idempotent `stop` function that also carries `droppedCount` /
+`overflowCount` getters.
 
 Use `pipeToSignal` when:
 
@@ -182,10 +188,41 @@ Use `pipeToSignal` when:
 - You don't need the lifecycle metadata wrapper
 - You want a `stop` fn instead of an `AbortController` for cleanup
 
+**Enrichment (1.3.0, all additive -- the un-optioned path is byte-identical
+to 1.1.0):**
+
+- `mode: "buffer"` (with required `maxBuffer`) drives the target with a bounded
+  newest-last snapshot array instead of the raw value; overflow drops the
+  oldest and increments `stop.droppedCount`. `mode: "latest"` + `maxBuffer`
+  throws `TypeError`; missing/invalid `maxBuffer` in buffer mode throws
+  `RangeError`.
+- `onValue(v)` is a per-value tap that fires once BEFORE each set (after
+  `transform`). A throwing `onValue` routes through the same `stop` + `onError`
+  leg as a throwing transform.
+- `onAbort(reason)`, when present, receives aborts INSTEAD of `onError`, so a
+  consumer aborting on purpose (detach / restart) no longer filters
+  `signal.aborted` out of its error handler. See the abort-vocabulary contract
+  in `llms.txt` and `decisions/0001-abort-vocabulary.md`.
+
 **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`.
 
+```js
+// Enriched buffer-mode pipe -- replaces a hand-rolled ring + status tap +
+// abort filter (the StreamQuery shape) with native options.
+const stop = pipeToSignal(topicSource, entrySig, {
+    signal:    ctrl.signal,
+    mode:      "buffer",
+    maxBuffer: 64,                               // bounded, drop-oldest
+    onValue:   (v) => { if (first) status.set("streaming"); first = false; },
+    onAbort:   () => {},                         // intentional abort, not an error
+    onError:   (e) => status.set("error"),       // real failures only
+    onDone:    () => status.set("done")
+});
+// stop.droppedCount tells you how many values overflowed the window.
+```
+
 ### toAsyncIterable
 
 ```ts
@@ -249,6 +286,16 @@ Treat this as the secondary API for classic "consume signal changes"
 patterns; for the streaming pipeline case (paginated APIs, SSE, pubsub)
 the forward direction is what most consumers want.
 
+### VERSION
+
+```ts
+VERSION: string
+```
+
+A string that always equals the installed `package.json` version. Consumers
+do NOT re-export it (suite ruling); the surface-guard asserts the equality on
+every test run.
+
 ## Modes: latest vs buffer
 
 Pick `"latest"` when you only care about the most recent value:
@@ -486,7 +533,7 @@ target.
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-85 tests across `test/01-*` through `test/08-*`:
+111 tests across `test/01-*` through `test/10-*`:
 
 - `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
   Iterable acceptance variants, pre-aborted, subscriber observability
@@ -505,7 +552,18 @@ target.
 - `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)
+  is the only escape hatch) plus the LS-13 pins (a throwing `done`/`value`
+  result getter routes to the error state, `onError` once, no
+  unhandledRejection)
+- `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.
+- `10-pipe-enriched.test.mjs` (1.3.0) -- the enriched `pipeToSignal`:
+  `mode`/`maxBuffer` validation, buffer-window snapshots and drop counting,
+  `onValue` ordering and throw policy, `onAbort` routing with and without the
+  hook, and the stop-fn `droppedCount`/`overflowCount` observability
 
 Run via `npm test`.
 
@@ -525,10 +583,26 @@ retained as an alias.
 `bench/bench.mjs` -- six scenarios; throughput and B/op retained. Run via
 `npm run bench`.
 
+### Tier 4 -- torture (retention + alloc gate + controls)
+
+`npm run torture` (`node --expose-gc test/torture.mjs`) runs tiers s0-s8
+sequentially -- metamorphic laws, degenerate values, protocol conformance,
+API abuse, seeded fuzz-vs-oracle, the s5 per-scenario allocation gate
+(maxMajor 0, including the 1.3.0 `pipeBuffer64` scenario alongside the
+unchanged `pipeSteady` default-path budget), a lite-leak retention soak, the
+StreamQuery conformance corpus (with the enriched-shape rewrite parity case),
+and the controls tier. It prints `ok` and exits 0 on success.
+`STREAM_TORTURE_BREAK=<s0..s8|s7e|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 (10 controls: s0-s8 plus the s7e
+enriched-surface control, each individually non-zero). `npm run test:floor` runs `npm test` against the peer
+floor `@zakkster/lite-signal@1.2.2` and then `npm test` + torture against the
+resolved latest, printing both verdicts.
+
 No `package-lock.json` is committed: devDependencies float within their
 stated ranges, and correctness against the peer floor is proven by running
-the suite against `@zakkster/lite-signal@1.2.2` rather than by pinning a
-lockfile.
+`npm run test:floor` against `@zakkster/lite-signal@1.2.2` rather than by
+pinning a lockfile.
 
 ## What this is not
 

package/Stream.d.ts

@@ -64,11 +64,57 @@ export interface FromAsyncIterableBufferOptions<T> {
     onDone?: () => void;
 }
 
-export interface PipeToSignalOptions<T> {
+/**
+ * Common `pipeToSignal` options, shared by both modes. `onValue` is a per-value
+ * tap that fires once BEFORE each `set` (after `transform`); a throw from it
+ * routes through the same stop + `onError` leg as a throwing transform.
+ * `onAbort`, when present, receives aborts INSTEAD of `onError` (see
+ * decisions/0001-abort-vocabulary.md) -- both at the abort listener and the
+ * pre-aborted early return.
+ */
+export interface PipeToSignalCommonOptions<T> {
     signal?: AbortSignal;
     onError?: (err: unknown) => void;
     onDone?: () => void;
     transform?: (value: T) => T;
+    onValue?: (value: T) => void;
+    onAbort?: (reason: unknown) => void;
+}
+
+export interface PipeToSignalLatestOptions<T> extends PipeToSignalCommonOptions<T> {
+    /** Default. The target signal's value is replaced with the raw value. */
+    mode?: "latest";
+}
+
+export interface PipeToSignalBufferOptions<T> extends PipeToSignalCommonOptions<T> {
+    /**
+     * Buffer mode: the target signal's value is a bounded newest-last snapshot
+     * array (a fresh array per set); overflow drops the oldest and increments
+     * the stop fn's `droppedCount`.
+     */
+    mode: "buffer";
+    /**
+     * Required when mode === "buffer". Positive integer. Unbounded buffering is
+     * rejected as a memory bug pretending to be a feature (RangeError); combining
+     * it with mode "latest" throws TypeError.
+     */
+    maxBuffer: number;
+}
+
+export type PipeToSignalOptions<T> =
+    | PipeToSignalLatestOptions<T>
+    | PipeToSignalBufferOptions<T>;
+
+/**
+ * The `pipeToSignal` return value: an idempotent stop function (calling it more
+ * than once is a no-op) that also carries two read-only overflow counters.
+ * `droppedCount` and `overflowCount` are aliases of the same buffer-mode
+ * overflow counter (0 in latest mode); reading them never allocates.
+ */
+export interface PipeToSignalStop {
+    (): void;
+    readonly droppedCount: number;
+    readonly overflowCount: number;
 }
 
 export interface ToAsyncIterableOptions {
@@ -110,16 +156,23 @@ export function fromAsyncIterable<T>(
 /**
  * Lower-level companion to `fromAsyncIterable`: pump an existing writable
  * signal from an async iterator. The signal's value is replaced directly
- * with each yielded value (no wrapper state). Returns a stop function that
- * ends the pump and calls `iterator.return()`.
+ * with each yielded value (no wrapper state) in the default "latest" mode, or
+ * with a bounded newest-last snapshot array in "buffer" mode. Returns a stop
+ * function that ends the pump and calls `iterator.return()`; the stop fn also
+ * carries `droppedCount` / `overflowCount` getters.
  *
  * Does NOT dispose the target signal; the caller owns its lifetime.
+ *
+ * Enrichment (1.3.0, all ADDITIVE -- the un-optioned path is byte-identical to
+ * 1.1.0): `mode: "buffer"` + required `maxBuffer`, an `onValue` tap firing
+ * before each set, and `onAbort` routing aborts instead of `onError` (see
+ * decisions/0001-abort-vocabulary.md).
  */
 export function pipeToSignal<T>(
     source: AsyncIterable<T> | AsyncIterator<T>,
     target: Signal<T>,
     opts?: PipeToSignalOptions<T>
-): () => void;
+): PipeToSignalStop;
 
 /**
  * Yield signal changes as an async iterable. Each change resolves a pending
@@ -135,3 +188,16 @@ export function toAsyncIterable<T>(
     sig: Signal<T> | Computed<T>,
     opts?: ToAsyncIterableOptions
 ): AsyncIterable<T> & { readonly droppedCount: number };
+
+/**
+ * Thrown when the `timeout` option on `toAsyncIterable` elapses. Structurally
+ * identical to `@zakkster/lite-await`'s TimeoutError (`e.name === "TimeoutError"`
+ * duck-checks work across both packages); not imported -- lite-stream stays zero-dep.
+ */
+export declare class TimeoutError extends Error {
+    readonly name: "TimeoutError";
+    readonly timeout: number;
+}
+
+/** Package version string; always equals the installed package.json version. */
+export declare const VERSION: string;

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.1.1
+// @zakkster/lite-stream 1.3.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
@@ -297,11 +297,23 @@ function fromAsyncIterable(source, opts) {
                     stop(new TypeError("lite-stream: iterator.next() returned non-object"));
                     return;
                 }
-                if (result.done === true) {
+                // LS-13: a throwing done/value getter on the result routes to
+                // the "iterator throws" leg (stop(err)). Wrap ONLY the two
+                // property reads -- widening this try over sig.set() below would
+                // swallow the LS-01 peer-defense catch semantics. Each property
+                // is read exactly once into a local.
+                let rDone, v;
+                try {
+                    rDone = result.done;
+                    v = result.value;
+                } catch (err) {
+                    stop(err);
+                    return;
+                }
+                if (rDone === true) {
                     stop(null);
                     return;
                 }
-                const v = result.value;
                 // Build the new state from lastState (never sig.peek), then
                 // commit to both lastState and sig. The try/catch around set()
                 // is defensive against a peer whose set() throws; on a throw we
@@ -433,6 +445,17 @@ function makeErrorState(prevState, err, mode) {
  * Disposing the target signal does NOT stop the pump: call the returned
  * stop fn or abort opts.signal. See ROADMAP LS-01.
  *
+ * Enrichment (1.3.0, all ADDITIVE -- the un-optioned path is byte-identical to
+ * 1.1.0): `mode: "buffer"` (with REQUIRED `maxBuffer`) drives the target with a
+ * bounded newest-last snapshot window instead of the raw value, dropping oldest
+ * on overflow and counting the drops; `onValue(v)` is a per-value tap that fires
+ * once BEFORE each set (a throw routes through the same leg as a throwing
+ * transform -- stop + onError); `onAbort(reason)` receives aborts INSTEAD of
+ * onError when present (so consumers stop filtering intentional aborts out of
+ * their error handler). The returned stop fn carries `droppedCount` and
+ * `overflowCount` getters (aliases of the same overflow counter); it stays
+ * callable and idempotent exactly as 1.1.0.
+ *
  * @template T
  * @param {AsyncIterable<T> | AsyncIterator<T>} source
  * @param {import("@zakkster/lite-signal").Signal<T>} target
@@ -440,9 +463,13 @@ function makeErrorState(prevState, err, mode) {
  *     signal?:  AbortSignal,
  *     onError?: (err: unknown) => void,
  *     onDone?:  () => void,
- *     transform?: (value: T) => T
+ *     transform?: (value: T) => T,
+ *     mode?: "latest" | "buffer",
+ *     maxBuffer?: number,
+ *     onValue?: (value: T) => void,
+ *     onAbort?: (reason: unknown) => void
  * }} [opts]
- * @returns {() => void} stop fn (idempotent)
+ * @returns {(() => void) & { readonly droppedCount: number, readonly overflowCount: number }} stop fn (idempotent)
  */
 function pipeToSignal(source, target, opts) {
     if (target === null || target === undefined || typeof target.set !== "function") {
@@ -452,18 +479,68 @@ function pipeToSignal(source, target, opts) {
     const onError   = (opts !== undefined && opts !== null) ? opts.onError   : undefined;
     const onDone    = (opts !== undefined && opts !== null) ? opts.onDone    : undefined;
     const transform = (opts !== undefined && opts !== null) ? opts.transform : undefined;
+    const mode      = (opts !== undefined && opts !== null) ? (opts.mode || "latest") : "latest";
+    const maxBuffer = (opts !== undefined && opts !== null) ? opts.maxBuffer : undefined;
+    const onValue   = (opts !== undefined && opts !== null) ? opts.onValue   : undefined;
+    const onAbort   = (opts !== undefined && opts !== null) ? opts.onAbort   : undefined;
+
+    // Validate ONCE at construction. Unknown mode / latest+maxBuffer are
+    // programmer bugs surfaced synchronously; buffer mode requires a deliberate
+    // ceiling (unbounded buffering is a memory bug pretending to be a feature).
+    if (mode !== "latest" && mode !== "buffer") {
+        throw new TypeError(
+            "lite-stream: opts.mode must be \"latest\" or \"buffer\" (got " + JSON.stringify(mode) + ")"
+        );
+    }
+    if (mode === "latest" && maxBuffer !== undefined) {
+        throw new TypeError(
+            "lite-stream: opts.maxBuffer is not allowed with mode: \"latest\" -- latest-wins sets the raw value"
+        );
+    }
+    if (mode === "buffer") {
+        if (typeof maxBuffer !== "number" || !Number.isFinite(maxBuffer) || maxBuffer < 1 || (maxBuffer | 0) !== maxBuffer) {
+            throw new RangeError(
+                "lite-stream: \"buffer\" mode requires opts.maxBuffer to be a positive integer "
+                    + "(got " + JSON.stringify(maxBuffer) + "). Unbounded buffering is a memory "
+                    + "bug pretending to be a feature; pick a deliberate ceiling."
+            );
+        }
+    }
+    const isBuffer = mode === "buffer";
+
+    // Overflow counter. droppedCount and overflowCount are aliases (a drop is
+    // an overflow), matching toAsyncIterable's vocabulary. Both getters on the
+    // returned stop fn read this one variable; no per-value allocation.
+    let dropped = 0;
+    // Attach the observability getters to whatever stop fn we return. Closes
+    // over `dropped`; defined once at construction, never on the hot path.
+    const attachCounters = function (fn) {
+        Object.defineProperty(fn, "droppedCount", { get() { return dropped; }, enumerable: true, configurable: true });
+        Object.defineProperty(fn, "overflowCount", { get() { return dropped; }, enumerable: true, configurable: true });
+        return fn;
+    };
 
     if (abortSig !== undefined && abortSig !== null && abortSig.aborted) {
-        if (onError !== undefined) {
-            try { onError(makeAbortError(abortSig)); } catch (_e) {}
+        const err = makeAbortError(abortSig);
+        if (onAbort !== undefined) {
+            try { onAbort(err); } catch (_e) {}
+        } else if (onError !== undefined) {
+            try { onError(err); } catch (_e) {}
         }
-        return function noopStop() {};
+        return attachCounters(function noopStop() {});
     }
 
     const iter = toIterator(source);
     let stopped = false;
     let abortListener = null;
 
+    // Buffer-mode ring: fixed-size, head-pointer wrap, oldest dropped on
+    // overflow. Snapshot rebuilt newest-last per set (fromAsyncIterable pattern).
+    let ring     = null;
+    let ringHead = 0;
+    let ringLen  = 0;
+    if (isBuffer) ring = new Array(maxBuffer);
+
     const stop = function () {
         if (stopped) return;
         stopped = true;
@@ -478,7 +555,10 @@ function pipeToSignal(source, target, opts) {
         abortListener = function () {
             const err = makeAbortError(abortSig);
             stop();
-            if (onError !== undefined) {
+            // onAbort, when present, receives aborts INSTEAD of onError.
+            if (onAbort !== undefined) {
+                try { onAbort(err); } catch (_e) {}
+            } else if (onError !== undefined) {
                 try { onError(err); } catch (_e) {}
             }
         };
@@ -506,15 +586,52 @@ function pipeToSignal(source, target, opts) {
                     }
                     return;
                 }
-                if (result.done === true) {
+                // LS-13: a throwing done/value getter routes to the "iterator
+                // throws" leg (stop + onError). Wrap ONLY the two property reads
+                // -- widening this try over transform()/target.set() below would
+                // fold the transform-throw leg into this one. Each property is
+                // read exactly once into a local.
+                let rDone, rValue;
+                try {
+                    rDone = result.done;
+                    rValue = result.value;
+                } catch (err) {
+                    stop();
+                    if (onError !== undefined) {
+                        try { onError(err); } catch (_e) {}
+                    }
+                    return;
+                }
+                if (rDone === true) {
                     stop();
                     if (onDone !== undefined) {
                         try { onDone(); } catch (_e) {}
                     }
                     return;
                 }
+                // transform -> onValue tap -> set. A throw anywhere here routes
+                // to the same stop + onError leg (the 1.1.0 transform-throw
+                // precedent; see test/04 "transform throwing stops the pump").
                 try {
-                    target.set(transform === undefined ? result.value : transform(result.value));
+                    const v = transform === undefined ? rValue : transform(rValue);
+                    if (onValue !== undefined) onValue(v);
+                    if (isBuffer) {
+                        if (ringLen < maxBuffer) {
+                            ring[(ringHead + ringLen) % maxBuffer] = v;
+                            ringLen = (ringLen + 1) | 0;
+                        } else {
+                            ring[ringHead] = v;
+                            ringHead = (ringHead + 1) % maxBuffer;
+                            dropped = (dropped + 1) | 0;
+                        }
+                        const snapshot = new Array(ringLen);
+                        for (let i = 0; i < ringLen; i = (i + 1) | 0) {
+                            snapshot[i] = ring[(ringHead + i) % maxBuffer];
+                        }
+                        target.set(snapshot);
+                    } else {
+                        target.set(v);
+                    }
                 } catch (err) {
                     stop();
                     if (onError !== undefined) {
@@ -534,7 +651,7 @@ function pipeToSignal(source, target, opts) {
     }
 
     queueMicrotask(pump);
-    return stop;
+    return attachCounters(stop);
 }
 
 // ---------------------------------------------------------------------------
@@ -873,3 +990,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.3.0";