@zakkster/lite-pick 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,89 @@ All notable changes to `@zakkster/lite-pick` are documented here. The format fol
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.2] - 2026-09-23
+
+### Added
+
+- `RECIPES.md` -- a beginner-to-advanced usage guide that builds the selection kernel up into a
+  real load balancer (health/eligibility wiring, caller-owned in-flight counters, the
+  dispatch/settle loop, `/pool` failover, PeakEWMA rtt feedback, the FE profile, a strategy
+  decision table, suite composition, zero-GC discipline, and gotchas). Added to the published
+  package (`files[]`) and linked from the README.
+
+Docs-only release: no source or behavior change from 0.7.1 (the `VERSION` stamp is bumped for the
+three-place sync).
+
+## [0.7.1] - 2026-09-23
+
+### Fixed
+
+- PeakEWMA cold-start / unsampled-node scoring under real large-magnitude clocks. An unsampled node
+  now scores at its UNDECAYED baseline (`_stamp` initialized to a negative sentinel, read as the
+  1.0 baseline) = graceful least-connections, instead of `exp(-now/tau)` underflowing to 0 and
+  collapsing a cold pool to random selection. The FIRST `recordRtt` sample now initializes the EWMA
+  EXACTLY to the sample (clock-magnitude-independent); the Finagle peak rule applies from the second
+  sample on. `pick()` stays a pure 0 B/op read (a per-candidate sentinel compare, no allocation).
+
+### Changed
+
+- Completes the 0.7.0 packaging: synced the `llms.txt` version stamp, added the PeakEWMA
+  README / CHANGELOG sections + `decisions/0009-peakewma.md`, and regenerated the benchmark
+  `results.json`. Documented that `pick(now)` / `recordRtt` require a FINITE `now` -- `recordRtt`
+  throws on a non-finite argument; `pick(now)` never throws (fail-closed) and degrades a non-finite
+  `now` to P2C-random selection. No API or behavior change beyond the cold-start fix.
+
+## [0.7.0] - 2026-09-23
+
+M7: `PeakEwmaBalancer` -- latency-aware power-of-two-choices (Twitter Finagle's peak-EWMA). A
+STRATEGY-APPEND session: one class is added to `Pick.js`; the other strategies are byte-identical,
+only the header roster/count and the `VERSION` stamp change. `peerDependencies` stays `{}`.
+
+### Added
+
+- `PeakEwmaBalancer extends BalancerBase` (`Pick.js`, `Pick.d.ts`) -- `new PeakEwmaBalancer(capacity,
+  eligible, inflight, tauNs, seed?)`. `pick(now)` draws two distinct eligible endpoints (reusing
+  `P2cBalancer`'s rejection-sampling `_draw`) and returns the lower `cost = (inflight + 1) x
+  ewmaAt(now)`, tie to the first draw; `O(d)=O(1)`. `ewmaAt(i, now)` decays ON READ
+  (`_ewma[i] * exp(-(now - _stamp[i]) / tau)`), so `pick()` never writes and is **0 B/op**.
+  `recordRtt(i, sampleNs, now)` is the warm feedback path (the Finagle peak rule: snap up to a
+  larger sample, decay down over `~tau`), also **0 B/op** on the success path. `now` / `sampleNs`
+  are caller-supplied nanoseconds. The EWMA state (`_ewma` / `_stamp`, `Float64Array`) is
+  balancer-owned; `inflight` is the caller's `Uint32Array` read live. Cold start seeds the EWMA to
+  `1.0` -> graceful least-connections, never `NaN`. Constructor and `recordRtt` validate
+  typeof-first, before allocation. Anti-flap = the half-life, no extra dwell.
+- `Pool.run` opt-in latency feedback (`Pool.js`, `Pool.d.ts`): when `opts.clock` (a caller-owned
+  nanosecond source) is supplied AND the balancer duck-types `recordRtt`, Pool drives `pick(now)`
+  and records the settled rtt on success. Otherwise the hook is inert -- Pool stays generic, the
+  in-flight counter stays net-zero, and abort/failover are unchanged.
+- `test/PeakEWMA.test.js` -- the boundary suite (cold-start valid + never-NaN, snap-up, decay to
+  sample/e at dt=tau within ~1%, slow-node avoidance, fail-closed, tie-break to the first draw =
+  identical to P2C on the same seed, constructor + recordRtt validation throws, flap churn).
+- `test/balance.mjs` -- the LATENCY ANCHOR: a closed-loop single-server-per-node queue with one node
+  at 10x service time. Measured: PeakEWMA slow-node share ~0.007% vs P2C ~1.47% (<= 25% of P2C);
+  PeakEWMA service p99 ~1950ns vs P2C ~14500ns (>= 20% lower); random foil worse than both.
+- `test/torture.mjs` -- PeakEWMA retention + `pick(now)` and `recordRtt()` 0 B/op phases.
+- `test/perf/PerfGate.test.mjs` -- `PeakEwmaBalancer.pick(now)` + `recordRtt()` zero-alloc scenarios
+  and a `pick(now)`-boxed-into-a-fresh-array `mustFail` tooth.
+- `test/witness.mjs` -- PeakEWMA subject, `const` (O(d)=O(1)) flat flag; work-rate flatness ~0.89
+  (the `Math.exp` runs ~2x/pick and stays flat -- the cached 2^-k decay-table fallback was NOT
+  needed).
+- `test/fuzz.mjs` -- PeakEWMA subject: `_ewma` / `_stamp` stay finite and `PICK_NONE` holds iff the
+  pickable mass is 0 under a `recordRtt` / `pick(now)` / `setEligible` barrage.
+- `test/types/pick.test-d.ts` -- PeakEwmaBalancer type-surface smoke.
+- `benchmark/Matrix.mjs` PeakEWMA throughput subject; PeakEWMA lanes in `benchmark/GcBlastRadius.mjs`
+  (same maxMajor 0 / 0 B/op / bounded-pause contract) and `benchmark/Fairness.mjs` (latency
+  steering); `benchmark/results.json` regenerated (version 0.7.0), `bench:verify` green.
+- `decisions/0009-peakewma.md` -- the ADR (latency-aware P2C, decay-on-read, the Finagle peak rule,
+  caller-supplied clock, balancer-owned state, deferred DDSketch-p99, anti-flap = half-life).
+
+### Changed
+
+- `Pick.js` header roster/count (six -> seven strategies), `VERSION` 0.6.0 -> 0.7.0; `package.json`
+  version + description; `llms.txt` version + PeakEWMA surface + the FE-profile note + the deferred
+  DDSketch-p99 note; `README.md` PeakEWMA section + FE profile + the AWS anomaly-mitigation mapping
+  row.
+
 ## [0.6.0] - 2026-09-23
 
 M6: the benchmark suite (ROADMAP.md M6). An EVIDENCE session -- no API change. `Pick.js` and

package/Pick.js

@@ -51,7 +51,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.7.0';
+export const VERSION = '0.7.2';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -602,9 +602,17 @@ export class NqBalancer extends BalancerBase {
  * between `pick(now)` and `recordRtt(i, sampleNs, now)`, so the whole strategy is deterministic
  * and testable and allocates nothing.
  *
- * Cold start: `_ewma` seeds to 1.0 and `_stamp` to 0 at construction, so before any sample
- * cost(i) ~ (inflight[i] + 1) x 1 and PeakEWMA degrades GRACEFULLY to plain least-connections
- * (P2C-over-inflight). It is never NaN.
+ * Cold start: `_ewma` seeds to 1.0 and `_stamp` to a NEGATIVE "unsampled" sentinel (-1). While a
+ * node is unsampled `ewmaAt` returns the baseline 1.0 UNDECAYED, so before any sample cost(i) =
+ * (inflight[i] + 1) x 1 and PeakEWMA degrades GRACEFULLY to plain least-connections (P2C-over-
+ * inflight) REGARDLESS of the caller's clock magnitude -- a plain `_stamp = 0` would decay as
+ * exp(-now/tau) -> 0 under a real large clock and collapse a cold pool to random. The first
+ * `recordRtt` initializes the EWMA EXACTLY to the sample (clock-independent); the peak rule applies
+ * only from the second sample on. It is never NaN.
+ *
+ * Contract: `now` (in `pick(now)` / `recordRtt`) and `sampleNs` MUST be FINITE numbers. `recordRtt`
+ * throws on a non-finite argument (the warm path); `pick(now)` never throws (the fail-closed
+ * contract), so a non-finite `now` yields P2C-random selection rather than an error.
  *
  * Anti-flap (ADR 0002, ADR 0009): the EWMA half-life IS the smoothing -- a single slow sample
  * snaps the cost up instantly and it decays back over ~tau, so there is NO extra dwell/hysteresis.
@@ -643,8 +651,12 @@ export class PeakEwmaBalancer extends BalancerBase {
         this._tau = tauNs;
         this._rng = new Prng(seed);
         this._ewma = new Float64Array(capacity);
-        this._stamp = new Float64Array(capacity);   // all-zero: last-update timestamp
-        for (let i = 0; i < capacity; i++) this._ewma[i] = 1.0; // cold start -> graceful LeastConn
+        this._stamp = new Float64Array(capacity);
+        // Cold start: _ewma seeds to 1.0 and _stamp to a NEGATIVE "unsampled" sentinel (-1). The
+        // sentinel makes ewmaAt read the baseline UNDECAYED (graceful LeastConn) regardless of the
+        // caller's clock magnitude -- a plain _stamp=0 would decay as exp(-now/tau) -> 0 under a
+        // real large-magnitude clock and collapse a cold pool to random selection.
+        for (let i = 0; i < capacity; i++) { this._ewma[i] = 1.0; this._stamp[i] = -1; }
     }
 
     /**
@@ -659,20 +671,26 @@ export class PeakEwmaBalancer extends BalancerBase {
 
     /**
      * The decayed EWMA rtt estimate for endpoint i at time `now` (ns). Pure READ -- exponential
-     * decay applied on read, never written. Cold (unsampled) nodes read ~1.0. Zero-alloc.
+     * decay applied on read, never written. An UNSAMPLED node (`_stamp < 0`) reads its baseline
+     * 1.0 UNDECAYED (graceful LeastConn), so a cold pool never underflows to 0 under a real
+     * large-magnitude clock. `now` must be finite. Zero-alloc.
      * @param {number} i
      * @param {number} now  caller-supplied nanoseconds
      * @returns {number}
      */
     ewmaAt(i, now) {
-        return this._ewma[i] * Math.exp(-(now - this._stamp[i]) / this._tau);
+        const s = this._stamp[i];
+        if (s < 0) return this._ewma[i]; // unsampled: undecayed baseline, clock-magnitude-independent
+        return this._ewma[i] * Math.exp(-(now - s) / this._tau);
     }
 
     /**
      * Record an rtt SAMPLE for endpoint i at time `now` (the warm feedback path -- NOT the hot
-     * pick path). The Finagle peak rule: decay the stored estimate to `now`, then SNAP UP to the
-     * sample if it is larger (a spike is felt instantly) else ease toward it (it decays back over
-     * ~tau). The balancer is the SOLE writer of `_ewma` / `_stamp`. Zero-alloc on the success path.
+     * pick path). The FIRST sample (an unsampled node, `_stamp < 0`) initializes the EWMA EXACTLY
+     * to the sample, clock-magnitude-independent. Thereafter the Finagle peak rule applies: decay
+     * the stored estimate to `now`, then SNAP UP to the sample if it is larger (a spike is felt
+     * instantly) else ease toward it (it decays back over ~tau). The balancer is the SOLE writer of
+     * `_ewma` / `_stamp`. Zero-alloc on the success path.
      * @param {number} i  endpoint index
      * @param {number} sampleNs  observed rtt in nanoseconds (finite, >= 0)
      * @param {number} now  caller-supplied nanoseconds (finite), consistent with pick(now)
@@ -686,9 +704,13 @@ export class PeakEwmaBalancer extends BalancerBase {
             throw new RangeError('[lite-pick] sampleNs must be a finite number >= 0');
         }
         if (!Number.isFinite(now)) throw new RangeError('[lite-pick] now must be a finite number');
-        const w = Math.exp(-(now - this._stamp[i]) / this._tau);
-        const e = this._ewma[i] * w;
-        this._ewma[i] = sampleNs > e ? sampleNs : e + (sampleNs - e) * (1 - w);
+        if (this._stamp[i] < 0) {
+            this._ewma[i] = sampleNs;   // first sample: exact init, no decay (clock-independent)
+        } else {
+            const w = Math.exp(-(now - this._stamp[i]) / this._tau);
+            const e = this._ewma[i] * w;
+            this._ewma[i] = sampleNs > e ? sampleNs : e + (sampleNs - e) * (1 - w);
+        }
         this._stamp[i] = now;
     }
 
@@ -709,8 +731,11 @@ export class PeakEwmaBalancer extends BalancerBase {
         for (let t = 0; b === a && t < 32; t++) b = this._draw();
         if (b < 0 || b === a) return a;       // astronomically rare: fall back to the first draw
         const inf = this._inflight, ewma = this._ewma, stamp = this._stamp, tau = this._tau;
-        const costA = (inf[a] + 1) * (ewma[a] * Math.exp(-(now - stamp[a]) / tau));
-        const costB = (inf[b] + 1) * (ewma[b] * Math.exp(-(now - stamp[b]) / tau));
+        // Decay-on-read with the unsampled sentinel: `_stamp < 0` reads the undecayed baseline
+        // (graceful LeastConn), else exponential decay. A cheap per-candidate compare, no alloc.
+        const sa = stamp[a], sb = stamp[b];
+        const costA = (inf[a] + 1) * (sa < 0 ? ewma[a] : ewma[a] * Math.exp(-(now - sa) / tau));
+        const costB = (inf[b] + 1) * (sb < 0 ? ewma[b] : ewma[b] * Math.exp(-(now - sb) / tau));
         return costB < costA ? b : a;         // lower cost wins; tie -> the first draw
     }
 }

package/README.md

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-> Zero-GC load-balancing **selection kernel**: one hot `pick()` that returns an endpoint **index** over a fixed pool and allocates **0 B/op** on the steady-state path. A pure selector, never a proxy -- it consumes health and circuit state, it never owns them. **v0.5.0 ships six strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family** -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view), plus a **`@zakkster/lite-pick/pool`** subpath: the async dispatch/settle counter layer with distinct-endpoint failover and a duck-typed query-cache fetcher. The rest of the roster -- PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
+> Zero-GC load-balancing **selection kernel**: one hot `pick()` that returns an endpoint **index** over a fixed pool and allocates **0 B/op** on the steady-state path. A pure selector, never a proxy -- it consumes health and circuit state, it never owns them. **v0.7.0 ships seven strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, and the latency-aware `PeakEwmaBalancer`** -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view), plus a **`@zakkster/lite-pick/pool`** subpath: the async dispatch/settle counter layer with distinct-endpoint failover and a duck-typed query-cache fetcher. The rest of the roster -- ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-pick.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-pick)
 [![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
@@ -21,7 +21,7 @@ The npm landscape has old algorithm libraries (`load-balancers`, `loadbalance`,
 - **Two pieces of evidence, both shipped.** A **0 B/op** witness on the pick path (no object, closure, string, or array created per pick), and a measured **balance-quality anchor** -- peak-to-average load within the strategy's theoretical ceiling (for P2C, the Azar-Broder-Karlin-Upfal `ln ln n / ln 2` bound) and strictly better than a random foil.
 - **A pure selector, not a proxy.** It **consumes** health and circuit state; it never owns them. Health is a shared read-only bitmap written by [`@zakkster/lite-di-health`](https://www.npmjs.com/package/@zakkster/lite-di-health); circuit state comes from [`@zakkster/lite-statechart`](https://www.npmjs.com/package/@zakkster/lite-statechart); load counters are caller-owned typed arrays. `pick()` only reads.
 
-> **Status: M6 (v0.6.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**, the **`@zakkster/lite-pick/pool`** request layer, and now the **benchmark suite** -- the balance anchor + GC blast-radius headlines, a seeded/version-stamped `results.json`, a `bench:verify` drift check with teeth, and the vs-AWS positioning (see *Evidence* below). The kernel `Pick.js` / `Pool.js` are byte-identical to v0.5.0 apart from the version stamp. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), and **SED tracks weight within 1%** -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M6 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), the RoundRobin (0003), SmoothWRR (0004), P2C (0005), LeastConn-family (0006), pool-adapter (0007), and benchmark-suite (0008) design forks.
+> **Status: M7 (v0.7.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, and the latency-aware `PeakEwmaBalancer`**, the **`@zakkster/lite-pick/pool`** request layer (now with an opt-in latency-feedback hook), and the **benchmark suite** -- the balance anchor + GC blast-radius headlines, a seeded/version-stamped `results.json`, a `bench:verify` drift check with teeth, and the vs-AWS positioning (see *Evidence* below). This session APPENDS one class: the other strategies in `Pick.js` are byte-identical, only the header roster/count and the `VERSION` stamp change. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), **SED tracks weight within 1%**, and **PeakEWMA steers around a 10x-slow node** (it takes <= 25% of P2C's share for it and cuts service p99) -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M7 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), the RoundRobin (0003), SmoothWRR (0004), P2C (0005), LeastConn-family (0006), pool-adapter (0007), benchmark-suite (0008), and PeakEWMA (0009) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -139,6 +139,47 @@ The proof (from `test/balance.mjs`):
 
 Each `pick()` is **0 B/op** and **O(cap)** (NQ is O(1) when an early node is idle). Because these are the state-heaviest strategies so far, M4 also introduces the **invariant fuzzer** (`npm run fuzz`): a seeded state-machine attack that, after *every* `pick` / `setEligible` / weight / load op, asserts the chosen endpoint is the *exact* optimum, `live` stays exact, and `PICK_NONE` holds *iff* nothing is pickable -- printing the seed on any failure for byte-for-byte replay.
 
+## PeakEWMA -- latency-aware P2C (v0.7.0)
+
+When endpoints differ in **latency**, not just queue depth, count-based strategies keep re-probing a slow-but-up node: it drains its queue between visits, so its in-flight looks attractive again. `PeakEwmaBalancer` (Twitter Finagle's *peak-EWMA*) is power-of-two-choices over a **latency cost** -- `cost = (inflight + 1) x decayed-EWMA(rtt)` -- so a degraded node is avoided **even while idle** ([ADR 0009](./decisions/0009-peakewma.md)). It is `O(d) = O(1)` per pick and **0 B/op** on both the pick path and the feedback path.
+
+```js
+import { PeakEwmaBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);          // YOU own this; read live by pick()
+const TAU_NS = 30e6;                          // EWMA half-life: 30ms of latency memory
+
+// `now` and rtt samples are CALLER-supplied nanoseconds -- deterministic, testable, zero-GC.
+const pe = new PeakEwmaBalancer(4, eligible, inflight, TAU_NS);
+
+const now = perfNs();                          // your monotonic ns clock
+const i = pe.pick(now);                         // two random eligibles, lower latency-cost wins
+inflight[i]++;                                  // dispatch
+// ... await the request ...
+inflight[i]--;                                  // settle
+pe.recordRtt(i, perfNs() - now, perfNs());      // feed the observed rtt back (the warm path)
+```
+
+- **Decay-on-read.** `pick()` *never writes* -- it applies exponential decay when it reads (`ewmaAt(i, now) = _ewma[i] x exp(-(now - _stamp[i]) / tau)`), so the hot path is a pure read and allocates nothing.
+- **The peak rule.** `recordRtt` *snaps the cost up* to a larger sample instantly (a spike is felt on the next pick) and *decays it down* over `~tau`. The half-life **is** the anti-flap smoothing -- no extra dwell ([ADR 0002](./decisions/0002-anti-flapping.md)).
+- **Balancer-owned state.** `inflight` is your live-read `Uint32Array`; the EWMA arrays are owned by the balancer and written *only* by `recordRtt`. Cold start seeds the EWMA to `1.0` with an *unsampled* sentinel (`_stamp = -1`): an unsampled node scores at its undecayed baseline, so before any sample PeakEWMA degrades gracefully to least-connections **regardless of your clock's magnitude** -- never underflowing to `0` (which a plain `_stamp = 0` would, as `exp(-now/tau)`, under a real large clock) and never `NaN`. The first `recordRtt` initializes the EWMA *exactly* to the sample; the peak rule applies from the second sample on.
+- **`now` must be finite.** `now` (for `pick(now)` / `recordRtt`) and `sampleNs` must be finite numbers. `recordRtt` throws on a non-finite argument; `pick(now)` never throws (the fail-closed contract), so a non-finite `now` yields P2C-random selection rather than an error.
+
+The proof (from `test/balance.mjs`, a closed-loop queue sim with one node at 10x service time):
+
+| lane | slow-node share | service p99 |
+|---|---|---|
+| **PeakEWMA** | **~0.01%** (learns and avoids it) | **lowest** |
+| P2C (in-flight only) | ~1.5% (keeps re-probing) | ~7x PeakEWMA's |
+| random foil | ~6% (blind) | saturates the slow node |
+
+PeakEWMA sends the slow node **<= 25% of P2C's share** for it and cuts service p99 **>= 20% below** P2C-over-inflight; the random foil is worse than both.
+
+### FE profile -- PeakEWMA + health, nothing else
+
+For a **front-end / browser client** -- a handful of picks per second across origins/regions, not a zero-GC hot loop -- the recommended profile is **PeakEWMA + the eligibility bitmap only**: latency-aware choice with a fail-closed health view, and **none** of the server-side bounded-load / availability-zone / occupancy machinery. It is the smallest honest latency-aware client balancer. *(Deferred: a tail-aware `inflight x p99Rtt` variant via an optional-peer `@zakkster/lite-sketch` `DDSketch`; the EWMA-mean score is the shipped zero-peer default, and `peerDependencies` stays `{}` -- [ADR 0009](./decisions/0009-peakewma.md).)*
+
 ## Evidence -- the two headlines (v0.6.0 benchmark suite)
 
 > **Framing: parity on speed, superiority on the contract + balance + tail.** A trivial `i++ % n` round-robin -- or `wrr` -- *matches* P2C on raw ops/sec, so `lite-pick` does **not** claim "N times faster." Throughput is claimed at **parity**; the wins are **zero-GC**, **balance quality**, **tail latency** (GC blast-radius), and **never a dead pick**. Every number below is **seeded** and regenerated by `npm run bench:report`; `npm run bench:verify` fails CI if a README number drifts from a fresh run (algorithmic exact, timing within +/-15%). Node / CPU / OS / every PRNG seed are stamped into `benchmark/results.json`.
@@ -151,9 +192,9 @@ The real pinned npm incumbents (`load-balancers`, `loadbalance`, `wrr`) run thro
 
 | family | lite-pick | lite-pick ops/ms | incumbent (npm) | incumbent ops/ms |
 | --- | --- | --- | --- | --- |
-| P2C (power-of-two-choices) | P2cBalancer | 59591 | load-balancers@1.3.52 | 60956 |
-| RoundRobin | RoundRobinBalancer | 260168 | loadbalance@1.0.0 | 334541 |
-| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 158395 |
+| P2C (power-of-two-choices) | P2cBalancer | 53426 | load-balancers@1.3.52 | 61749 |
+| RoundRobin | RoundRobinBalancer | 246108 | loadbalance@1.0.0 | 282939 |
+| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 151557 |
 
 <!-- /bench:competitors -->
 
@@ -181,8 +222,8 @@ The point of zero-GC is **not** the pick's own latency -- a major GC pause freez
 
 | lane | major GC | pick B/op | max GC pause (ms) |
 | --- | --- | --- | --- |
-| lite-pick | 0 | 0 | 0.1 |
-| allocating foil | 13 | allocates | 2.9 |
+| lite-pick | 0 | 0 | 0.3 |
+| allocating foil | 13 | allocates | 1.9 |
 
 <!-- /bench:gc -->
 
@@ -221,6 +262,7 @@ On a scale event (add / remove a node), what fraction of keys keep their node? T
 | AWS edge feature (managed, billed) | `lite-pick` equivalent (in-process, zero-GC) |
 | --- | --- |
 | ALB `least_outstanding_requests` (LOR) | `LeastConnBalancer` / `P2cBalancer` |
+| ALB anomaly mitigation / latency-aware shedding | `PeakEwmaBalancer` (latency-aware P2C) |
 | ALB `weighted_random` + anomaly mitigation | `WeightedRandom` + `BoundedLoad` (M9/M10) |
 | NLB flow-hash (5-tuple) | `ConsistentHash` (Maglev, M8) |
 
@@ -254,10 +296,12 @@ PICK_NONE;            // -> -1  (fail-closed sentinel: no endpoint, never a dead
 VERSION;              // -> '0.6.0'
 ```
 
-`BalancerBase.pick()` is **abstract** -- it throws, so an unfinished strategy fails loudly rather than returning a dead index. Every shipped strategy (`RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`) extends it and reads the same shared eligibility view; you subclass it the same way to add your own.
+`BalancerBase.pick()` is **abstract** -- it throws, so an unfinished strategy fails loudly rather than returning a dead index. Every shipped strategy (`RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`, `PeakEwmaBalancer`) extends it and reads the same shared eligibility view; you subclass it the same way to add your own.
 
 ## Wiring it up -- `@zakkster/lite-pick/pool` (v0.5.0)
 
+> **New to lite-pick as a load balancer?** [**RECIPES.md**](./RECIPES.md) is a beginner-to-advanced guide: it builds the kernel up into a real balancer step by step -- health/eligibility, load counters, the dispatch/settle loop, failover, latency feedback (PeakEWMA), the FE profile, and choosing a strategy. Start there; the sections below are the reference.
+
 The kernel gives you `pick() -> index`. Real callers also need the counter ergonomics: **increment in-flight on dispatch, decrement on settle, and re-pick a *different* endpoint on failure.** That layer is async (it wraps the request), so it lives in a separate subpath -- `@zakkster/lite-pick/pool` -- and the kernel stays 0 B/op.
 
 ```js

package/RECIPES.md

@@ -0,0 +1,329 @@
+# lite-pick recipes -- from a one-liner to a real load balancer
+
+`@zakkster/lite-pick` is a SELECTION KERNEL, not a proxy. It answers one question --
+"which endpoint should this request go to?" -- and returns an integer index (or
+`PICK_NONE` = -1 when nothing is eligible). A *real* load balancer is that kernel plus
+the wiring around it:
+
+- **eligibility** -- who is up? (a health check writes a shared bitmap)
+- **load counters** -- how busy is each endpoint? (you own an `inflight` array)
+- **the dispatch/settle loop** -- increment on send, decrement on finish
+- **failover** -- if a call fails, try a different endpoint
+- **latency feedback** -- for latency-aware routing, feed measured rtt back
+
+These recipes build that wiring up, one layer at a time. Every array is preallocated
+once and reused -- the pick path allocates 0 bytes.
+
+Install: `npm i @zakkster/lite-pick`  (zero runtime dependencies; ESM; Node >= 18)
+
+---
+
+## 1. The 30-second version -- round-robin over a fixed pool
+
+```js
+import { RoundRobinBalancer, PICK_NONE } from '@zakkster/lite-pick';
+
+const CAP = 4;                              // fixed pool size
+const eligible = new Uint8Array(CAP).fill(1); // 1 = up, 0 = down (all up here)
+const lb = new RoundRobinBalancer(CAP, eligible);
+
+const endpoints = ['a.svc:8080', 'b.svc:8080', 'c.svc:8080', 'd.svc:8080'];
+
+for (let r = 0; r < 6; r++) {
+  const i = lb.pick();                      // -> next eligible index, round-robin
+  if (i === PICK_NONE) throw new Error('pool is down');
+  send(endpoints[i]);                        // your transport; lite-pick never opens a socket
+}
+// picks: a, b, c, d, a, b
+```
+
+`pick()` is the whole kernel. Everything below adds a capability around it.
+
+---
+
+## 2. Fail closed -- always handle PICK_NONE
+
+lite-pick never returns a down endpoint and never guesses. When the whole pool is
+ineligible, `pick()` returns `PICK_NONE` (-1). Treat it as a first-class outcome:
+
+```js
+const i = lb.pick();
+if (i === PICK_NONE) {
+  // shed load, return 503, or fall back -- your policy. Never index endpoints[-1].
+  return respond503();
+}
+send(endpoints[i]);
+```
+
+`lb.live` is an O(1) count of eligible endpoints if you want to check before picking.
+
+---
+
+## 3. Wire health -> eligibility (the shared bitmap)
+
+Eligibility is a shared `Uint8Array` (1 = pickable, 0 = down). Something else writes it
+-- a health checker, a circuit breaker, or `@zakkster/lite-di-health` -- and `pick()`
+only reads it. Two ways to flip a node:
+
+```js
+// (a) write the bitmap directly if you own it elsewhere (zero-copy, pick sees it live):
+eligible[2] = 0;                 // endpoint c is down
+
+// (b) go through the balancer so its O(1) `live` count stays exact (recommended):
+lb.setEligible(2, false);        // COLD path; idempotent; keeps `live` correct
+lb.setEligible(2, true);         // back up
+
+lb.isEligible(2);                // -> boolean, HOT, out-of-range is false (never throws)
+```
+
+Prefer `setEligible` when you rely on `live`. Health flapping is the writer's problem:
+apply hysteresis/dwell in the health layer -- `pick()` stays greedy and stateless.
+
+---
+
+## 4. Weighted pools -- SmoothWRR
+
+When endpoints have different capacities, weight them. `SmoothWRRBalancer` owns its
+weight state; it is the SOLE writer -- always go through `setWeight`, never mutate the
+array directly (direct mutation desyncs the internal total = undefined behavior).
+
+```js
+import { SmoothWRRBalancer } from '@zakkster/lite-pick';
+
+const weights = new Uint32Array(CAP);        // the balancer manages these
+const lb = new SmoothWRRBalancer(CAP, eligible, weights);
+lb.setWeight(0, 5);                          // a is 5x
+lb.setWeight(1, 1);
+lb.setWeight(2, 1);
+lb.setWeight(3, 1);
+// pick() interleaves smoothly (nginx smooth WRR): a a b a c a a d ... not a a a a a b c d
+```
+
+Use SmoothWRR when weights are known/config-driven and change rarely.
+
+---
+
+## 5. Load-aware selection -- you own the `inflight` counters
+
+P2C, LeastConn, SED, and NQ route by *current load*. That load lives in a
+caller-owned `Uint32Array` you increment on dispatch and decrement on settle. If you
+don't maintain it, these strategies are blind (they see every node at 0).
+
+```js
+import { P2cBalancer } from '@zakkster/lite-pick';
+
+const inflight = new Uint32Array(CAP);       // YOURS to maintain
+const lb = new P2cBalancer(CAP, eligible, inflight);
+
+async function handle(req) {
+  const i = lb.pick();
+  if (i === PICK_NONE) return respond503();
+  inflight[i]++;                             // DISPATCH
+  try {
+    return await send(endpoints[i], req);
+  } finally {
+    inflight[i]--;                           // SETTLE (always, even on error)
+  }
+}
+```
+
+- **P2C** -- two random draws, pick the lighter. O(1), the scalable default; peak load
+  hugs the `ln ln n` band. Great from ~8 endpoints up.
+- **LeastConn** -- exact fewest-in-flight (O(cap) scan). Best balance for small pools.
+- **SED** / **NQ** -- weighted least-conn: pass a `weights` Uint32Array too;
+  `new SedBalancer(CAP, eligible, inflight, weights)`. NQ sends to an idle node first.
+
+Maintaining the dispatch/settle loop by hand is easy to get wrong. Recipe 6 does it for
+you.
+
+---
+
+## 6. The real request loop -- `@zakkster/lite-pick/pool`
+
+The `/pool` subpath wraps the kernel with the async dispatch/settle ergonomics so you
+don't hand-maintain `inflight`. The kernel `pick()` stays 0 B/op; `Pool.run` is a normal
+async wrapper on top.
+
+```js
+import { P2cBalancer } from '@zakkster/lite-pick';
+import { Pool } from '@zakkster/lite-pick/pool';
+
+const inflight = new Uint32Array(CAP);
+const lb = new P2cBalancer(CAP, eligible, inflight);
+const pool = new Pool(lb, inflight);         // SAME inflight array the balancer reads
+
+// Pool does pick -> inflight++ -> await fn -> inflight-- (in a finally) for you:
+const body = await pool.run((i, signal) => fetchFrom(endpoints[i], { signal }));
+```
+
+`run(fn, opts?)` rejects with a `code: 'LITE_PICK_NONE'` error when the pool is down.
+`fn(endpoint, signal)` receives the chosen index and the (optional) AbortSignal.
+
+---
+
+## 7. Failover -- try a different endpoint on error
+
+Set `tries > 1`. On a thrown error, Pool keeps the failed node's in-flight count
+elevated and re-picks -- so a load-aware strategy naturally steers to a DIFFERENT
+endpoint -- up to `tries` attempts, then rejects with the last error.
+
+```js
+const body = await pool.run(
+  (i, signal) => fetchFrom(endpoints[i], { signal }),
+  { tries: 3, signal: req.signal }           // up to 3 distinct endpoints
+);
+```
+
+Boundary: Pool owns **spatial** failover (move across the pool, once each, in-process).
+The caller or your query cache owns **temporal** retry (backoff, staleness, dedup).
+Don't double-own them. If `signal` aborts after a failure, failover stops and the abort
+propagates.
+
+---
+
+## 8. Latency-aware routing -- PeakEWMA with rtt feedback
+
+PeakEWMA (latency-aware P2C, Finagle's peak-EWMA) steers away from *slow* endpoints,
+not just busy ones. It scores each candidate `(inflight + 1) x ewma(rtt)`, so a node
+that got slow gets less traffic even if its connection count looks fine. It needs two
+things you didn't need before: a **clock** (`now`, caller-supplied nanoseconds) and
+**rtt feedback** (`recordRtt`).
+
+Manual loop:
+
+```js
+import { PeakEwmaBalancer } from '@zakkster/lite-pick';
+
+const TAU_NS = 30_000_000;                    // 30ms half-life for the EWMA decay
+const inflight = new Uint32Array(CAP);
+const lb = new PeakEwmaBalancer(CAP, eligible, inflight, TAU_NS);
+const nowNs = () => Number(process.hrtime.bigint());
+
+async function handle(req) {
+  const now = nowNs();
+  const i = lb.pick(now);                      // decay-on-read, 0 B/op
+  if (i === PICK_NONE) return respond503();
+  inflight[i]++;
+  const start = nowNs();
+  try {
+    return await send(endpoints[i], req);
+  } finally {
+    inflight[i]--;
+    lb.recordRtt(i, nowNs() - start, nowNs()); // FEEDBACK: measured rtt, snaps up / decays down
+  }
+}
+```
+
+Or let Pool do the feedback for you -- pass a `clock`; Pool drives `pick(now)` and calls
+`recordRtt` on a successful settle when the balancer supports it:
+
+```js
+import { Pool } from '@zakkster/lite-pick/pool';
+const pool = new Pool(lb, inflight);
+const body = await pool.run(
+  (i, signal) => fetchFrom(endpoints[i], { signal }),
+  { clock: () => Number(process.hrtime.bigint()), tries: 2 }
+);
+```
+
+Notes:
+- **Cold start** (no samples yet) degrades gracefully to least-connections -- never NaN.
+- `now` must be a FINITE number. A non-finite `now` degrades to P2C-random (no throw).
+- Pick `tauNs` around your p50-p90 rtt: smaller = reacts faster to a slowdown, larger =
+  steadier. It IS the anti-flap smoothing; no extra dwell needed.
+- Measured effect: with one node at 10x latency, PeakEWMA sends it a tiny fraction of
+  the traffic P2C-over-inflight would, and cuts service p99 sharply.
+
+---
+
+## 9. Wire it into a query cache (lite-query, or any fetcher)
+
+`liteQueryFetcher` adapts a Pool into a `({ key, signal }) => Promise` fetcher -- the
+shape lite-query (or any cache/route-loader) expects. It imports nothing from lite-query
+(duck-typed), so it works with any fetcher-shaped consumer.
+
+```js
+import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+
+const pool = new Pool(lb, inflight);
+const fetcher = liteQueryFetcher(
+  pool,
+  ({ endpoint, key, signal }) => fetchFrom(endpoints[endpoint], { key, signal }),
+  { tries: 2 }
+);
+// hand `fetcher` to your query cache; each cache miss fans out across the pool with failover.
+```
+
+---
+
+## 10. Choosing a strategy
+
+| Strategy      | Route by            | Cost        | Reach for it when |
+|---------------|---------------------|-------------|-------------------|
+| RoundRobin    | position            | O(1) amort. | uniform endpoints, no load signal |
+| SmoothWRR     | static weight       | O(cap)      | known/config capacities, smooth interleave |
+| P2C           | in-flight (approx)  | O(1)        | the scalable default from ~8 nodes up |
+| LeastConn     | in-flight (exact)   | O(cap)      | small pools, tightest connection balance |
+| SED           | in-flight / weight  | O(cap)      | weighted least-conn |
+| NQ            | idle-first else SED  | O(cap)/O(1) | worker pools -- never queue while a worker is free |
+| PeakEWMA      | in-flight x ewma(rtt)| O(1)        | heterogeneous / flaky backends; steer around slow nodes |
+
+All read the SAME `inflight` array live, so you can swap strategies without rewiring.
+
+---
+
+## 11. The "FE profile" -- a browser / front-end client
+
+For a front-end client picking among origins a handful of times per second (not a
+zero-GC hot loop), the recommended profile is **PeakEWMA + health/eligibility only** --
+latency-aware choice across origins with a fail-closed eligibility view -- and skip the
+bounded-load / AZ / occupancy machinery. Feed rtt from your `fetch` timings via
+`recordRtt`.
+
+---
+
+## 12. Compose with the suite (all optional, all duck-typed)
+
+lite-pick declares ZERO hard dependencies and an EMPTY `peerDependencies`. Each seam is
+a shared TypedArray or a duck-typed shape, so you wire in a sibling only if you use it:
+
+- `@zakkster/lite-di-health` -- writes the eligibility bitmap from health checks.
+- `@zakkster/lite-statechart` -- a circuit breaker that flips eligibility.
+- `@zakkster/lite-query` -- the cache behind `liteQueryFetcher` (recipe 9).
+- `@zakkster/lite-sketch` -- `DDSketch` for a p99-aware PeakEWMA variant (deferred).
+- `@zakkster/lite-await` -- hedging (race the P2C second choice past a percentile).
+
+None is required; the kernel runs over raw TypedArrays with nothing installed.
+
+---
+
+## 13. Zero-GC discipline (why the pick path stays 0 B/op)
+
+- Allocate `eligible` / `inflight` / `weights` ONCE at startup and reuse them. Never
+  build arrays per pick.
+- The counters are YOURS -- mutate them in place (`inflight[i]++/--`), don't replace them.
+- `pick()` / `pick(now)` and `recordRtt` allocate nothing. The only async allocation is
+  the promise your own `fn` already creates (disclosed; `Pool.run` adds O(1) integer ops
+  plus one small per-run array).
+- Fixed capacity: the pool size is set at construction and the backing arrays never
+  reallocate.
+
+---
+
+## 14. Gotchas
+
+- **PICK_NONE (-1)** is always possible -- handle it before indexing (recipe 2).
+- **SmoothWRR weights** must go through `setWeight`; direct array mutation is UB.
+- **Load-aware strategies need the dispatch/settle loop** -- forget the `inflight--` in
+  a `finally` and load leaks upward forever. Use `/pool` (recipe 6) to avoid it.
+- **PeakEWMA needs a finite `now`** and rtt feedback -- without `recordRtt` it behaves
+  like LeastConn (cold-start baseline).
+- **Eligibility is read-only to `pick()`** -- the health layer writes it; the balancer
+  only reads (or maintains `live` via `setEligible`).
+- **lite-pick is not a proxy** -- it returns an index; you own transport, retries/backoff
+  (temporal), health checking, and the socket.
+
+---
+
+See also: `README.md` (overview + gates), `llms.txt` (full API surface),
+`decisions/` (the ADRs behind each design call), `ROADMAP.md` (what's next).

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.6.0
+Version: 0.7.2
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,15 +14,25 @@ reading pre-allocated views that siblings or the caller write, and returning an
 The complementary evidence lite-pick ships is a measured balance-quality anchor (peak-to-
 average load vs the strategy's theoretical ceiling) alongside the 0 B/op pick witness.
 
-0.6.0 ships the substrate seams + six strategies: RoundRobin, SmoothWRR (the weighted
-default), P2C (power-of-two-choices -- also the O(1) least-connections APPROXIMATION), and the
-EXACT LeastConn family (LeastConn, SED, NQ). It exports `VERSION`, the fail-closed sentinel
-`PICK_NONE` (-1), a deterministic `Prng` (xorshift32), `BalancerBase` (the shared read-only
-eligibility seam + O(1) live count), `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`,
-`LeastConnBalancer`, `SedBalancer`, and `NqBalancer`. The remaining strategies land one per
-session (see ROADMAP.md): PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom. The EXACT-O(log
-n) fewest-in-flight variant is a deferred @zakkster/lite-logn `BinaryHeap` optional-peer seam
-(decisions/0006), not this exact-O(cap) scan.
+0.7.0 ships the substrate seams + seven strategies: RoundRobin, SmoothWRR (the weighted
+default), P2C (power-of-two-choices -- also the O(1) least-connections APPROXIMATION), the
+EXACT LeastConn family (LeastConn, SED, NQ), and PeakEWMA (latency-aware P2C). It exports
+`VERSION`, the fail-closed sentinel `PICK_NONE` (-1), a deterministic `Prng` (xorshift32),
+`BalancerBase` (the shared read-only eligibility seam + O(1) live count), `RoundRobinBalancer`,
+`SmoothWRRBalancer`, `P2cBalancer`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`, and
+`PeakEwmaBalancer`. The remaining strategies land one per session (see ROADMAP.md):
+ConsistentHash, BoundedLoad, WeightedRandom. The EXACT-O(log n) fewest-in-flight variant is a
+deferred @zakkster/lite-logn `BinaryHeap` optional-peer seam (decisions/0006), not this
+exact-O(cap) scan.
+
+M7 (0.7.0) adds PeakEwmaBalancer (decisions/0009). The FE PROFILE: for a browser / front-end
+client (a handful of picks per second, not a zero-GC hot loop), the recommended profile is
+PeakEWMA + health/eligibility ONLY -- no bounded-load / AZ / occupancy machinery -- latency-aware
+choice across origins with a fail-closed eligibility view. DEFERRED tail-aware variant: a p99-aware
+score (inflight x p99Rtt) via a per-node @zakkster/lite-sketch `DDSketch` (published 0.3.0; `add`
+is O(1) / 0 B/op, `quantile` carries a hard relative-error bound) is an OPTIONAL PEER complement;
+the EWMA-mean score is the shipped, zero-peer default and `peerDependencies` STAYS `{}` until a
+shipped code path imports the sketch.
 
 M6 (0.6.0) adds the BENCHMARK SUITE -- an evidence session, no API change: Pick.js / Pool.js are
 byte-identical to 0.5.0 apart from the VERSION stamp. It lives entirely under benchmark/ (NOT in
@@ -116,6 +126,30 @@ the contract + balance + tail -- never an "N times faster" headline (decisions/0
   - `pick()` -> number. Returns the FIRST idle eligible positive-weight node (in-flight 0) if one
     exists -- never queueing while a server is free -- else the SED minimum, else `PICK_NONE`.
     O(cap) worst case, O(1) when an early node is idle. 0 B/op.
+- `PeakEwmaBalancer extends BalancerBase` -- class. Latency-aware P2C (M7, Finagle peak-EWMA).
+  - `new PeakEwmaBalancer(capacity, eligible, inflight, tauNs, seed?=0x9e3779b9)` -- `inflight` is a
+    caller-owned Uint32Array (length >= capacity) read LIVE; `tauNs` is the EWMA time-constant /
+    half-life in nanoseconds (finite, > 0). The per-endpoint EWMA state (`_ewma` / `_stamp`,
+    Float64) is BALANCER-OWNED and written ONLY by `recordRtt`. Validates typeof-first BEFORE
+    allocating (RangeError/TypeError). Cold start seeds the EWMA to 1.0 with an UNSAMPLED sentinel
+    (`_stamp = -1`), so an unsampled node scores at its undecayed baseline -> graceful
+    least-connections regardless of clock magnitude (never underflows to 0).
+  - `pick(now)` -> number. Draws two DISTINCT eligible endpoints (ADR 0005's rejection sampling,
+    reused) and returns the lower `cost = (inflight + 1) * ewmaAt(now)`; a tie goes to the first
+    draw. `now` is caller-supplied nanoseconds. Decays ON READ (never writes) -> O(d)=O(1), 0 B/op.
+    `PICK_NONE` when the whole pool is down. A slow-but-up node (high EWMA rtt) is avoided even while
+    idle -- the difference from P2C-over-inflight (latency anchor in balance.mjs).
+  - `ewmaAt(i, now)` -> number. The EWMA rtt estimate for endpoint i at `now`. Pure read. An
+    unsampled node (`_stamp < 0`) returns the baseline 1.0 undecayed; otherwise exponential decay.
+  - `recordRtt(i, sampleNs, now)` -> void. WARM feedback path (not the hot pick path): the FIRST
+    sample initializes the EWMA EXACTLY to `sampleNs` (clock-magnitude-independent); thereafter the
+    Finagle peak rule -- the cost SNAPS UP to a larger sample instantly and DECAYS DOWN over ~tau.
+    `now` / `sampleNs` are caller-supplied nanoseconds, consistent with `pick(now)`. Validates
+    typeof-first; 0 B/op on the success path. Anti-flap = the half-life, no extra dwell (ADR 0002,
+    ADR 0009).
+  - CONTRACT: `now` and `sampleNs` MUST be FINITE numbers. `recordRtt` THROWS on a non-finite
+    argument (warm path); `pick(now)` NEVER throws (fail-closed contract), so a non-finite `now`
+    yields P2C-random selection, not an error.
 
 ## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
 
@@ -140,7 +174,11 @@ duck-typed and imports NOTHING from lite-query.
     once aborted after a failure, failover stops and the abort propagates. NOT a 0 B/op path (the
     kernel `pick()` is): a normal async wrapper adding O(1) counter ops + one small per-run array.
     BOUNDARY: Pool owns SPATIAL failover (across the pool); the caller / query cache owns TEMPORAL
-    retry (backoff, staleness). Never double-owned (decisions/0007).
+    retry (backoff, staleness). Never double-owned (decisions/0007). OPT-IN latency feedback: when
+    `opts.clock` (a caller-owned nanosecond source) is supplied AND the balancer duck-types
+    `recordRtt` (PeakEwmaBalancer), Pool drives `pick(now)` and records the settled rtt on success;
+    otherwise the hook is inert -- Pool stays generic, in-flight stays net-zero, abort/failover
+    unchanged.
 - `liteQueryFetcher(pool, perEndpoint, opts?)` -> a `({ key, signal }) => Promise` fetcher for a
   query cache (lite-query's `fetcher`, or any fetcher-shaped consumer). `perEndpoint({ endpoint,
   key, signal })` -> the per-endpoint work. `opts.tries` (default 1) is the spatial failover count.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Zero-dependency, zero-GC load-balancing selection kernel: one hot pick() -> endpoint index over a fixed pool, 0 B/op steady-state. A pure selector (consumes health/circuit state, never a proxy) for the in-process hop, complementary to AWS NLB/ALB. Tree-shakeable ESM roster: RoundRobin, SmoothWRR, P2C, LeastConn, SED, NQ, PeakEWMA (latency-aware peak-EWMA), plus consistent hashing; the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
   "type": "module",
   "main": "./Pick.js",
@@ -28,6 +28,7 @@
     "Pool.d.ts",
     "llms.txt",
     "README.md",
+    "RECIPES.md",
     "CHANGELOG.md",
     "LICENSE"
   ],