@zakkster/lite-stream 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,87 @@ 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

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
@@ -496,7 +533,7 @@ target.
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-90 tests across `test/01-*` through `test/09-*`:
+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
@@ -515,12 +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`.
 
@@ -545,11 +588,14 @@ retained as an alias.
 `npm run torture` (`node --expose-gc test/torture.mjs`) runs tiers s0-s8
 sequentially -- metamorphic laws, degenerate values, protocol conformance,
 API abuse, seeded fuzz-vs-oracle, the s5 per-scenario allocation gate
-(maxMajor 0), a lite-leak retention soak, the StreamQuery conformance corpus,
+(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|1>` arms one tier's (or every tier's) injected
-breakage so the control lane exits non-zero; `npm run torture:control` runs
-the all-tiers form. `npm run test:floor` runs `npm test` against the peer
+`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.
 

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

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.2.0
+// @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);
 }
 
 // ---------------------------------------------------------------------------
@@ -876,4 +993,4 @@ export {
 
 // Always equals the installed package.json version (single source of truth is
 // package.json; the /release drill bumps both sites in the same commit).
-export const VERSION = "1.2.0";
+export const VERSION = "1.3.0";

package/llms.txt

@@ -5,7 +5,7 @@ multi-shot dual of lite-await's `fromPromise`. Project async streams
 (paginated APIs, SSE, network frames, pubsub topics) into signals with
 bounded buffering and structural cleanup.
 
-ESM-only. Node >= 18. ~5 KB minified. Single file `Stream.js`.
+ESM-only. Node >= 18. Zero runtime dependencies. Single file `Stream.js`.
 Peer dep: `@zakkster/lite-signal ^1.2.0`.
 
 ## Install
@@ -49,22 +49,72 @@ Throws `TypeError` on null/undefined/wrong-shape source. Throws
 
 ### `pipeToSignal(source, target, opts?) -> stop`
 
-Pump an existing writable signal from an async iterator. The signal's
-value is replaced directly (no wrapper). Returns an idempotent stop fn.
+Pump an existing writable signal from an async iterator. In the default
+`"latest"` mode the signal's value is replaced directly (no wrapper). Returns
+an idempotent stop fn that also carries `droppedCount` / `overflowCount`
+getters.
 
 ```js
 const stop = pipeToSignal(source, targetSig, {
     signal: abortCtrl.signal,
+    mode: "latest" | "buffer",         // default "latest"
+    maxBuffer: 64,                     // REQUIRED if mode = "buffer"
+    transform: (v) => transform(v),    // per-value map, runs first
+    onValue: (v) => {},                // tap: fires ONCE per value BEFORE set
+    onAbort: (reason) => {},           // aborts route HERE instead of onError
     onError: (e) => {},
-    onDone: () => {},
-    transform: (v) => transform(v)
+    onDone: () => {}
 });
+
+stop();                 // idempotent -- calling again is a no-op
+stop.droppedCount;      // buffer-mode overflow count (0 in latest mode)
+stop.overflowCount;     // alias of droppedCount
 ```
 
+Enrichment (1.3.0, all ADDITIVE -- the un-optioned path is byte-identical to
+1.1.0):
+
+- `mode: "buffer"` drives the target with a bounded newest-last snapshot array
+  (a fresh array per set) instead of the raw value. REQUIRES `maxBuffer` (a
+  positive integer; missing/invalid throws `RangeError` -- same
+  "unbounded buffering is a memory bug pretending to be a feature" voice as
+  `fromAsyncIterable`). Overflow drops the oldest and increments the stop fn's
+  `droppedCount`. `mode: "latest"` + `maxBuffer` throws `TypeError`; an unknown
+  mode throws `TypeError`. All validated ONCE at construction.
+- `onValue(v)` is a per-value tap that fires exactly once per value BEFORE the
+  `set` (and after `transform`). A THROWING `onValue` routes through the same
+  leg as a throwing transform -- `stop()` then `onError` (precedent: test/04
+  "transform throwing stops the pump cleanly").
+- `onAbort(reason)`, when present, receives aborts 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 (aborts flow through `onError`). See the abort
+  vocabulary contract table below and `decisions/0001-abort-vocabulary.md`.
+- `stop.droppedCount` and `stop.overflowCount` are getters ON the returned stop
+  fn (aliases of one overflow counter); the stop fn stays callable and
+  idempotent exactly as 1.1.0.
+
 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.
 
+#### Abort vocabulary contract
+
+The two directions frame an AbortSignal abort differently, by design. See
+`decisions/0001-abort-vocabulary.md` (a repo-only doc, not shipped in the
+tarball).
+
+| Direction | On abort | Framing | Escape hatch |
+| --- | --- | --- | --- |
+| `fromAsyncIterable` (from-side) | interrupt production; `iter.return()` best-effort; terminal error state | error (`onError`, `state.error`) | -- |
+| `pipeToSignal` (from-side) | interrupt production; `iter.return()` best-effort | error (`onError`) by default | `onAbort` routes aborts away from `onError` |
+| `toAsyncIterable` (to-side) | stop listening; pending `next()` resolves `{ done: true }` | graceful done | already graceful; nothing to filter |
+
+Aborting a producer is an interruption of work in flight (error framing);
+aborting a consumer is a subscriber leaving (graceful done). `onAbort` is added
+to `pipeToSignal` ONLY -- the sole direction that carried a shipped consumer
+workaround.
+
 ### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount, overflowCount }`
 
 Reverse direction: yield signal changes as an async iterable.
@@ -131,7 +181,14 @@ every test run.
 `fromAsyncIterable` ends on exactly three paths, all structural:
 
 1. Iterator natural completion (`{ done: true }`) -> done state, onDone fires.
-2. Iterator throws -> error state, onError fires.
+2. Iterator throws -> error state, onError fires. As of 1.3.0 (LS-13) this leg
+   also covers a `next()` result whose `done` or `value` is a THROWING getter:
+   the thrown value routes to the error state with onError fired exactly once,
+   instead of escaping as an unhandledRejection with the signal never settling.
+   `pipeToSignal` gets the same fix (stop + onError). Both pumps read the two
+   result properties once, inside a dedicated try/catch that routes to the
+   existing "iterator throws" leg; the peer-defense catch around `set()` (LS-01)
+   is separate and untouched.
 3. AbortSignal aborts -> `iter.return()` called, error state, onError fires.
 
 The abort listener is always removed on any of the three paths -- no
@@ -288,7 +345,7 @@ is caught up; `mode: "buffer"` also zero when no waiter is pending
 
 ## Files
 
-- `Stream.js` -- single-file ESM implementation (~875 lines)
+- `Stream.js` -- single-file ESM implementation (~995 lines)
 - `Stream.d.ts` -- TypeScript types with discriminated state union
 - `README.md` -- full docs with integration recipes
 - `llms.txt` -- this file

package/package.json

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