@zakkster/lite-pick 0.9.0 → 1.0.1

package/Pick.js

@@ -1,10 +1,11 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * M9 (0.9.0): substrate seams + nine strategies -- RoundRobin, SmoothWRR, P2C, the exact
- * LeastConn family (LeastConn, SED, NQ), PeakEWMA (latency-aware P2C), ConsistentHash
- * (a Maglev lookup table), and BoundedLoad (Consistent Hashing with Bounded Loads: the
- * Maglev table + an occupancy cap that overflows a hot backend). This file ships:
+ * M10 (1.0.0): substrate seams + TEN strategies (the roster-complete release) -- RoundRobin,
+ * SmoothWRR, P2C, the exact LeastConn family (LeastConn, SED, NQ), PeakEWMA (latency-aware P2C),
+ * ConsistentHash (a Maglev lookup table), BoundedLoad (Consistent Hashing with Bounded Loads:
+ * the Maglev table + an occupancy cap that overflows a hot backend), and WeightedRandom (O(1)
+ * Vose alias-table sampling with rejection-sampling eligibility). This file ships:
  *
  *   - VERSION        the single source-of-truth version stamp (3-place sync).
  *   - PICK_NONE      the fail-closed sentinel (-1): "no endpoint", never a dead pick.
@@ -29,7 +30,9 @@
  *   - NqBalancer     never-queue (IPVS `nq`): an IDLE eligible endpoint immediately if one
  *                    exists, else SED. The worker-pool fit. O(cap)/pick, 0 B/op.
  *   - PeakEwmaBalancer  latency-aware P2C (Twitter Finagle's peak-EWMA): draws two distinct
- *                    eligible endpoints and takes the lower cost = (inflight+1) x decayed EWMA(rtt).
+ *                    eligible endpoints and takes the lower cost (three cases: idle-unsampled 0,
+ *                    busy-unsampled priced at the sample mean, sampled (inflight+1) x decayed EWMA
+ *                    floored by time-since-last-sample while busy -- see the class JSDoc).
  *                    Decay-on-READ (pick() never writes -> 0 B/op); the balancer OWNS the Float64
  *                    _ewma/_stamp state and is its SOLE writer via the warm recordRtt() feedback
  *                    path (also 0 B/op). Caller-supplied nanosecond clock. O(d)=O(1)/pick.
@@ -47,6 +50,16 @@
  *                    stickiness + minimal disruption PLUS the hotspot protection plain CH lacks. It
  *                    extends ConsistentHashBalancer (reusing its Maglev build + probe VERBATIM) and
  *                    OWNS a running `_total` (sole writer: the warm note(i, delta) seam). O(1), 0 B/op.
+ *   - WeightedRandomBalancer  O(1) weighted-random selection via a Vose/Walker ALIAS TABLE (one
+ *                    column draw + one probability compare -> a candidate), with rejection-sampling
+ *                    eligibility (retry an ineligible candidate up to a bounded count, then a 0-B/op
+ *                    rotated linear eligible scan). The alias table is built COLD over the eligible-
+ *                    INDEPENDENT weights (a weight-0 node is NEVER a column), so rejection over the
+ *                    bitmap renormalizes the weight distribution across the SURVIVING eligible mass.
+ *                    The balancer OWNS its derived table (_prob/_alias) and is its SOLE writer via cold
+ *                    setWeight/rebuild (the SmoothWRR precedent); an eligibility flap never rebuilds.
+ *                    The stateless O(1) sample (no accumulators to desync) for VERY LARGE pools where
+ *                    SmoothWRR's O(cap) scan hurts. O(1), 0 B/op. (Vose 1991 / Walker alias method.)
  *
  * The identity (decisions/0001): lite-pick OWNS NO mutable state it can avoid owning.
  * It reads pre-allocated views (eligibility, inflight, weights, scores) that siblings or
@@ -55,8 +68,11 @@
  *
  * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [M1], SmoothWRR [M2],
  *   P2C [M3], LeastConn/SED/NQ [M4], PeakEWMA [M7], ConsistentHash [M8], BoundedLoad [M9],
- *   WeightedRandom [planned]. 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.
+ *   WeightedRandom [M10] -- roster complete for now (NOT closed: AZ-aware routing, hedging, and
+ *   subsetting are queued post-1.0). 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;
+ *   a lite-logn Fenwick tree is the deferred DYNAMIC-weight complement to WeightedRandom's static
+ *   alias table, and lite-o1 AliasTable a deferred duck-typed optional-peer upgrade for the build.
  *
  * M5 (0.5.0) adds the ergonomic request layer at the @zakkster/lite-pick/pool subpath (a
  * SEPARATE file, Pool.js -- the async dispatch/settle counter wrapper + distinct-endpoint
@@ -67,7 +83,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.9.0';
+export const VERSION = '1.0.1';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -117,14 +133,33 @@ export class Prng {
     }
 }
 
+/**
+ * Validate an endpoint index for a COLD/WARM mutator (never the hot pick path): it must be an
+ * in-range, non-negative INTEGER. `(i >>> 0) !== i` rejects NaN, fractions (1.5), negatives (-1),
+ * and non-numbers (a string like '2' coerces to a different value under `>>> 0`); `i >= cap`
+ * rejects out-of-range. Fails closed with the same RangeError style as the pre-existing range
+ * checks -- invalid input is an error, never a silent typed-array no-op that desyncs `_live`.
+ * @param {number} i
+ * @param {number} cap
+ */
+function _vIdx(i, cap) {
+    if ((i >>> 0) !== i || i >= cap) {
+        throw new RangeError('[lite-pick] index out of range: ' + i);
+    }
+}
+
 /**
  * BalancerBase -- the shared eligibility seam for every strategy.
  *
  * It owns ONLY: the fixed capacity, a reference to the caller/sibling-owned eligibility
  * Uint8Array (never copied), and an O(1) `_live` count maintained on the cold setEligible()
  * path so a strategy can fail closed in O(1). It never allocates after construction and
- * never calls into a health source -- writers mutate `eligible` at their own cadence; pick()
- * only reads it.
+ * never calls into a health source. The eligibility view is flipped ONLY through setEligible()
+ * (the sole supported writer, which keeps `_live` -- and SmoothWRR's eligible-weight total --
+ * exact); a health source / breaker drives that call. A direct `eligible[i]` write bypasses the
+ * cache and desyncs `_live` (fail-closed picks, wrong ratios) -- UB (1.0.1 contract). Each
+ * balancer needs its OWN eligibility array (a shared `Eligibility` object is deferred to 2.0).
+ * pick() only reads.
  *
  * Subclasses (M1+) implement pick(). BalancerBase.pick() throws, so an unfinished strategy
  * fails loudly rather than silently returning a dead index.
@@ -158,9 +193,10 @@ export class BalancerBase {
         return this._live;
     }
 
-    /** True iff endpoint i is currently pickable. O(1), zero-alloc. */
+    /** True iff endpoint i is currently pickable. O(1), zero-alloc. A non-integer (1.5, NaN)
+     *  is never pickable -> false (isEligible NEVER throws; it is a pure predicate). */
     isEligible(i) {
-        return i >= 0 && i < this._cap && this._eligible[i] !== 0;
+        return (i >>> 0) === i && i < this._cap && this._eligible[i] !== 0;
     }
 
     /**
@@ -170,9 +206,7 @@ export class BalancerBase {
      * @param {boolean} up
      */
     setEligible(i, up) {
-        if (i < 0 || i >= this._cap) {
-            throw new RangeError('[lite-pick] index out of range: ' + i);
-        }
+        _vIdx(i, this._cap);
         const was = this._eligible[i];
         const now = up ? 1 : 0;
         if (was !== now) {
@@ -308,12 +342,13 @@ export class SmoothWRRBalancer extends BalancerBase {
      * @param {number} w  new weight (uint32)
      */
     setWeight(i, w) {
-        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        _vIdx(i, this._cap);
         const nw = w >>> 0;
         if (nw !== w) throw new RangeError('[lite-pick] weight must be a uint32: ' + w);
         const old = this._weights[i];
         if (nw === old) return;
         this._weights[i] = nw;
+        this._current[i] = 0;               // reset credit: a reweighted node holds no stale accumulator
         if (this._eligible[i]) this._totalEligibleWeight += nw - old;
     }
 
@@ -327,13 +362,15 @@ export class SmoothWRRBalancer extends BalancerBase {
         const cap = this._cap, el = this._eligible, wt = this._weights, cur = this._current;
         let best = -1, bestCur = -Infinity;
         for (let i = 0; i < cap; i++) {
-            if (el[i]) {
+            if (el[i] && wt[i] > 0) {       // eligible AND positive weight: a weight-0 node is never a candidate
                 const c = cur[i] + wt[i];
                 cur[i] = c;
                 if (c > bestCur) { bestCur = c; best = i; }
             }
         }
-        cur[best] -= total;                 // best >= 0 guaranteed while total > 0
+        // best >= 0 while total > 0 -- provided eligibility is written ONLY through setEligible (the
+        // 1.0.1 contract that keeps _totalEligibleWeight in lockstep); a direct eligible[] write desyncs it.
+        cur[best] -= total;
         return best;
     }
 }
@@ -437,7 +474,8 @@ export class P2cBalancer extends BalancerBase {
  * directly between picks; that is the whole point of the shared-counter seam.
  *
  * Bound: O(cap) per pick (one scan). Steady-state pick(): integer compares + one index write,
- * no object/closure/array created -- 0 B/op. Tie-break is the lowest index (deterministic);
+ * no object/closure/array created -- 0 B/op. Tie order is UNSPECIFIED in 1.0.1 (deterministic,
+ * but callers must not depend on which tied node wins; a rotating tie-break is planned for 1.1.0);
  * the feedback loop breaks a startup all-zero tie by raising the picked node's count. Fails
  * closed (PICK_NONE) when the whole pool is down.
  *
@@ -462,7 +500,7 @@ export class LeastConnBalancer extends BalancerBase {
 
     /**
      * The eligible endpoint with the fewest in-flight requests, or PICK_NONE (fail closed).
-     * O(cap), zero-alloc. Lowest index on a tie.
+     * O(cap), zero-alloc. Tie order unspecified in 1.0.1 (deterministic; rotating tie-break 1.1.0).
      * @returns {number}
      */
     pick() {
@@ -519,7 +557,8 @@ export class SedBalancer extends BalancerBase {
 
     /**
      * The eligible endpoint minimizing (inflight + 1) / weight, or PICK_NONE (fail closed).
-     * O(cap), zero-alloc. Lowest index on a tie; weight-0 nodes are not candidates.
+     * O(cap), zero-alloc. Tie order unspecified in 1.0.1 (deterministic; rotating tie-break 1.1.0);
+     * weight-0 nodes are not candidates.
      * @returns {number}
      */
     pick() {
@@ -548,8 +587,9 @@ export class SedBalancer extends BalancerBase {
  * case: spin up idle capacity first, only weigh expected delay once everyone is busy.
  *
  * Ownership (ADR 0001, ADR 0006): identical to SED -- caller-owned inflight + weights, read
- * live, no derived aggregate. The first idle eligible node (lowest index, in-flight 0, weight
- * > 0) short-circuits the scan.
+ * live, no derived aggregate. The first idle eligible node found in the scan (in-flight 0, weight
+ * > 0) short-circuits it; when several are idle the one returned is unspecified in 1.0.1
+ * (deterministic; a rotating tie-break is planned for 1.1.0).
  *
  * Bound: O(cap) worst case (no idle node -> a full SED scan); O(1) when a low-index endpoint is
  * idle. 0 B/op. Fails closed (PICK_NONE) when no eligible endpoint has a positive weight.
@@ -600,11 +640,25 @@ export class NqBalancer extends BalancerBase {
  * PeakEwmaBalancer -- latency-aware power-of-two-choices (M7), Twitter Finagle's peak-EWMA.
  *
  * `pick(now)` draws TWO distinct eligible endpoints (the same rejection-sampling machinery as
- * P2cBalancer -- reused verbatim, not re-implemented) and returns the one with the lower COST,
- * where cost(i) = (inflight[i] + 1) x ewmaAt(i, now). It is P2C over a LATENCY signal instead of
- * raw in-flight count: a slow endpoint (high EWMA rtt) is avoided even when its queue is short,
- * so the pool steers around a degraded-but-up node -- the strategy the multi-region FE case wants.
- * O(d) = O(1) per pick.
+ * P2cBalancer -- reused verbatim, not re-implemented) and returns the one with the lower COST. It
+ * is P2C over a LATENCY signal instead of raw in-flight count: a slow endpoint (high EWMA rtt) is
+ * avoided even when its queue is short, so the pool steers around a degraded-but-up node -- the
+ * strategy the multi-region FE case wants. O(d) = O(1) per pick.
+ *
+ * Cost, per candidate i (a pure READ -- scalar-only, no write, no clock call, 0 B/op):
+ *   - unsampled (`_stamp < 0`) AND idle (`inflight === 0`) -> cost 0. This is NOT a one-shot probe the
+ *     kernel can enforce: an idle unsampled node costs 0 EVERY time it is idle, so it holds exactly one
+ *     request in flight at a time (the next pick sees inflight > 0) until its FIRST recordRtt. A node
+ *     that never gets a sample -- e.g. one that fails fast so the caller records nothing -- stays at
+ *     cost 0 whenever idle and keeps winning. Callers MUST record failures too (@zakkster/lite-pick/pool
+ *     does this from 1.0.1) or a fast-failing endpoint is a black hole the kernel alone cannot see.
+ *   - unsampled AND busy (`inflight > 0`) -> `(inflight + 1) x mean`, where `mean` is the pool's
+ *     LIFETIME mean sampled rtt (`_samp[0] / _samp[1]` = sum / count, or 1.0 before ANY sample). A
+ *     cold-but-busy node is priced at the pool mean, NOT the old 1.0 ns that made it a black hole (H1).
+ *   - sampled -> `(inflight + 1) x base`, `base = max(decayedEWMA, dt)` WHILE BUSY else `decayedEWMA`
+ *     (`decayedEWMA = ewma x exp(-dt/tau)`, `dt = max(now - stamp, 0)`). The busy floor means a hung
+ *     node -- inflight > 0 and no completion, so `dt` grows without bound -- gets MORE expensive over
+ *     time instead of decaying toward 0 and becoming the most attractive pick (H1/L6).
  *
  * Ownership (ADR 0001, ADR 0009): `inflight` is the CALLER's Uint32Array, read LIVE (the P2C /
  * LeastConn seam). The EWMA state -- `_ewma` (the decayed rtt estimate) and `_stamp` (the ns
@@ -613,25 +667,34 @@ export class NqBalancer extends BalancerBase {
  * warm `recordRtt()` feedback path. `pick()` NEVER writes: it decays ON READ, so the hot path
  * stays a pure read -> 0 B/op.
  *
- * Decay-on-read: ewmaAt(i, now) = _ewma[i] x exp(-(now - _stamp[i]) / tau). No write, no clock
+ * Decay-on-read: ewmaAt(i, now) = _ewma[i] x exp(-max(now - _stamp[i], 0) / tau). No write, no clock
  * call on the gated path -- `now` (and the rtt sample) are CALLER-supplied nanoseconds, consistent
  * between `pick(now)` and `recordRtt(i, sampleNs, now)`, so the whole strategy is deterministic
- * and testable and allocates nothing.
+ * and testable and allocates nothing. `dt` is clamped at 0 (L6) so a non-monotonic clock can never
+ * inflate the estimate via `exp(+x)`.
+ *
+ * Cold start: `_ewma` seeds to 1.0 and `_stamp` to a NEGATIVE "unsampled" sentinel (-1). An unsampled
+ * node costs 0 WHILE IDLE (so it holds one request in flight at a time until its first recordRtt) and
+ * the pool's lifetime mean ONCE BUSY (1.0 only before the very first sample), so a cold node that took
+ * work is never mistaken for a 1.0 ns node and cannot become a black hole once samples flow (H1). 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.
  *
- * 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.
+ * ACCEPTED CAVEATS (1.1 refinements): (a) a node that was idle and then receives a request is priced by
+ * the time since its LAST response (the `dt` floor / the mean) until that in-flight request completes --
+ * there is no precise per-dispatch "busy since" stamp yet, so the busy floor uses time-since-last-sample
+ * as its proxy, over-pricing a node that has just started a fresh (not hung) request. (b) `mean` is a
+ * LIFETIME mean over every sample ever recorded -- it never forgets a latency-regime change; decaying it
+ * is a 1.1 item. `_samp[0]` (the running sum) saturates to +Infinity after ~1.8e308 of summed rtt and
+ * stays Infinity (a cold-but-busy node then prices at Infinity) -- 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.
+ * Anti-flap (ADR 0002, ADR 0009): the EWMA time constant IS the smoothing -- a single slow sample
+ * snaps the cost up instantly and it decays back over ~tau (half-life = tau x ln2), so there is NO
+ * extra dwell/hysteresis.
  *
  * Deferred (ADR 0009 / llms.txt): a p99-aware variant scoring inflight x p99Rtt via a per-node
  * @zakkster/lite-sketch `DDSketch` (optional peer, 0 B/op `add`). EWMA-mean is the shipped,
@@ -642,13 +705,20 @@ export class NqBalancer extends BalancerBase {
  * the whole pool is down.
  */
 export class PeakEwmaBalancer extends BalancerBase {
+    /**
+     * Marker: this is a LATENCY-AWARE strategy -- pick() consumes a clock reading (`now`), so
+     * @zakkster/lite-pick/pool REQUIRES an `opts.clock` and feeds recordRtt() from it. Read via
+     * `balancer.constructor.LATENCY` so Pool stays duck-typed (imports nothing new).
+     */
+    static LATENCY = true;
+
     /**
      * @param {number} capacity  endpoint count (fixed).
      * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
      * @param {Uint32Array} inflight  per-endpoint in-flight counts (length >= capacity),
      *   caller-owned and only READ here.
-     * @param {number} tauNs  the EWMA time-constant / half-life in nanoseconds (> 0, finite):
-     *   larger tau = slower decay = longer memory of a latency spike.
+     * @param {number} tauNs  the EWMA TIME CONSTANT in nanoseconds (> 0, finite; the half-life is
+     *   tauNs x ln2): larger tau = slower decay = longer memory of a latency spike.
      * @param {number} [seed=0x9e3779b9]  deterministic PRNG seed (reproducible benches).
      */
     constructor(capacity, eligible, inflight, tauNs, seed = 0x9e3779b9) {
@@ -668,6 +738,12 @@ export class PeakEwmaBalancer extends BalancerBase {
         this._rng = new Prng(seed);
         this._ewma = new Float64Array(capacity);
         this._stamp = new Float64Array(capacity);
+        // Lifetime running mean of ALL rtt samples (O(1), warm-path maintained in recordRtt): the price
+        // an unsampled-but-BUSY node pays, so a cold node is not mistaken for a 1.0 ns node once it has
+        // work in flight. mean = _samp[0] / _samp[1] (sum / count); count 0 (no sample yet) -> 1.0. Held
+        // in a pre-allocated Float64Array (the hot-path law: pre-allocate typed-array scalars, never a
+        // per-op object). _samp[0] saturates to +Infinity past ~1.8e308 of summed rtt -- never NaN.
+        this._samp = new Float64Array(2);
         // 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
@@ -697,7 +773,9 @@ export class PeakEwmaBalancer extends BalancerBase {
     ewmaAt(i, now) {
         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);
+        let dt = now - s;
+        if (dt < 0) dt = 0;              // L6: clamp a non-monotonic clock -- exp(+x) must never inflate
+        return this._ewma[i] * Math.exp(-dt / this._tau);
     }
 
     /**
@@ -712,10 +790,10 @@ export class PeakEwmaBalancer extends BalancerBase {
      * @param {number} now  caller-supplied nanoseconds (finite), consistent with pick(now)
      */
     recordRtt(i, sampleNs, now) {
-        if (typeof i !== 'number' || typeof sampleNs !== 'number' || typeof now !== 'number') {
+        _vIdx(i, this._cap);
+        if (typeof sampleNs !== 'number' || typeof now !== 'number') {
             throw new TypeError('[lite-pick] recordRtt(i, sampleNs, now) requires numbers');
         }
-        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
         if (!Number.isFinite(sampleNs) || sampleNs < 0) {
             throw new RangeError('[lite-pick] sampleNs must be a finite number >= 0');
         }
@@ -723,17 +801,26 @@ export class PeakEwmaBalancer extends BalancerBase {
         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);
+            let dt = now - this._stamp[i];
+            if (dt < 0) dt = 0;         // L6: clamp a non-monotonic clock -- exp(+x) must never inflate
+            const w = Math.exp(-dt / this._tau);
             const e = this._ewma[i] * w;
             this._ewma[i] = sampleNs > e ? sampleNs : e + (sampleNs - e) * (1 - w);
         }
         this._stamp[i] = now;
+        // O(1) warm running lifetime mean over ALL samples: the price a cold-but-busy node pays in
+        // pick(). Kept in an unboxed Float64Array (see the ctor); _samp[0] saturates to +Infinity, never NaN.
+        this._samp[0] += sampleNs;
+        this._samp[1] += 1;
     }
 
     /**
-     * Pick by latency-aware power-of-two-choices: two distinct eligible draws, lower cost =
-     * (inflight+1) x ewmaAt(now) wins; a tie goes to the first draw. PICK_NONE (fail closed) iff
-     * the whole pool is down. O(d)=O(1), 0 B/op (pure read -- no write, no clock call).
+     * Pick by latency-aware power-of-two-choices: two distinct eligible draws, LOWER COST wins (a tie
+     * goes to the first draw). Cost is the three-case function documented on the class (unsampled+idle
+     * -> 0; unsampled+busy -> (inflight+1) x lifetime mean; sampled -> (inflight+1) x max(decayedEWMA,
+     * dt-while-busy)), NOT a plain (inflight+1) x ewmaAt. PICK_NONE (fail closed) iff the whole pool is
+     * down. O(d)=O(1), 0 B/op (pure read -- no write, no clock call; the mean division runs only in the
+     * unsampled-and-busy arm, never in the both-sampled steady state).
      * @param {number} now  caller-supplied nanoseconds (consistent with recordRtt)
      * @returns {number}
      */
@@ -747,11 +834,34 @@ 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;
-        // 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));
+        // Per-candidate cost (pure READ, scalar-only, 0 B/op). See the class JSDoc for the three cases.
+        //   unsampled + idle -> 0 (costs 0 while idle until its first recordRtt; NOT a one-shot probe).
+        //   unsampled + busy -> (inf+1) x lifetime mean  (the mean DIVISION runs ONLY here -- never in
+        //                       the both-sampled steady state -- priced at the pool mean, not 1.0 ns).
+        //   sampled          -> (inf+1) x base, base = decayed EWMA, floored at dt WHILE BUSY so a hung
+        //                       node (dt grows, no completion) gets MORE expensive, not less.
+        const sa = stamp[a];
+        let costA;
+        if (sa < 0) {
+            costA = inf[a] === 0 ? 0 : (inf[a] + 1) * (this._samp[1] > 0 ? this._samp[0] / this._samp[1] : 1.0);
+        } else {
+            let dtA = now - sa;
+            if (dtA < 0) dtA = 0;             // L6: clamp non-monotonic clock
+            const decA = ewma[a] * Math.exp(-dtA / tau);
+            const baseA = inf[a] > 0 ? (decA > dtA ? decA : dtA) : decA;   // busy floor: >= time since last sample
+            costA = (inf[a] + 1) * baseA;
+        }
+        const sb = stamp[b];
+        let costB;
+        if (sb < 0) {
+            costB = inf[b] === 0 ? 0 : (inf[b] + 1) * (this._samp[1] > 0 ? this._samp[0] / this._samp[1] : 1.0);
+        } else {
+            let dtB = now - sb;
+            if (dtB < 0) dtB = 0;             // L6: clamp non-monotonic clock
+            const decB = ewma[b] * Math.exp(-dtB / tau);
+            const baseB = inf[b] > 0 ? (decB > dtB ? decB : dtB) : decB;   // busy floor
+            costB = (inf[b] + 1) * baseB;
+        }
         return costB < costA ? b : a;         // lower cost wins; tie -> the first draw
     }
 }
@@ -833,6 +943,13 @@ function chIsPrime(n) {
  * pick, over-conservative only under mass outage; ADR 0010).
  */
 export class ConsistentHashBalancer extends BalancerBase {
+    /**
+     * Marker: this is a KEYED strategy -- pick(keyHash) routes by an integer key, so
+     * @zakkster/lite-pick/pool REQUIRES a numeric `opts.key`. Inherited by BoundedLoadBalancer.
+     * Read via `balancer.constructor.KEYED` so Pool stays duck-typed (imports nothing new).
+     */
+    static KEYED = true;
+
     /**
      * @param {number} capacity  backend count (fixed; add/remove is a cold rebuild).
      * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
@@ -945,7 +1062,7 @@ export class ConsistentHashBalancer extends BalancerBase {
      * @param {number} w  new weight (uint32)
      */
     setWeight(i, w) {
-        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        _vIdx(i, this._cap);
         const nw = w >>> 0;
         if (nw !== w) throw new RangeError('[lite-pick] weight must be a uint32: ' + w);
         if (nw === this._weights[i]) return;
@@ -1005,7 +1122,13 @@ export class ConsistentHashBalancer extends BalancerBase {
  * window (home + CH_PROBE_LIMIT slots) and return the FIRST backend that is ELIGIBLE AND UNDER cap
  * (`inflight[b] < cap`). If none in the window is under cap, FALL BACK to the first eligible seen
  * (sticky wins; the cap is a soft preference, never a dead pick). When `_total === 0` the cap test is
- * skipped entirely -> behaves as pure ConsistentHash. `cap = (1 + eps) x _total / live`.
+ * skipped entirely -> behaves as pure ConsistentHash. `cap = ceil((1 + eps) x (_total + 1) / live)`
+ * -- the load-bearing change from the old `(1 + eps) x _total / live` is the +1 that counts the
+ * INCOMING request (Mirrokni-Thorup-Zadimoghaddam per-bin capacity); the Math.ceil matches the
+ * paper's integer capacity but is a no-op for the `inf < cap` test (for integer inf,
+ * `inf < ceil(x)` == `inf < x`). A second concurrent same-key request correctly overflows the home
+ * until `(1+eps)(_total+1)/live > 1`. HAProxy's `hash-balance-factor` shares the +1 but distributes
+ * ONE global `ceil((m+1)F/100)` slot budget across servers by weight (min 1), which is stricter.
  *
  * Ownership (ADR 0001, ADR 0004, ADR 0010, ADR 0011): the Maglev lookup table + weights are
  * BALANCER-OWNED and built COLD (reused from ConsistentHashBalancer VERBATIM -- `_build`, `setWeight`,
@@ -1014,9 +1137,11 @@ export class ConsistentHashBalancer extends BalancerBase {
  * `_total` is BALANCER-OWNED and its SOLE writer is the warm `note(i, delta)` feedback path
  * (dispatch +1 / settle -1), so the cap's mean stays O(1)-current without a scan.
  *
- * CONTRACT (the SmoothWRR-weights asymmetry): when using BoundedLoad the mirrored inflight counter is
- * mutated ONLY through `note()` / the /pool adapter. Direct mutation desyncs `_total` from the true
- * sum, so the cap goes wrong -- UB. `note()` clamps `_total` at 0; `totalInflight` exposes it.
+ * CONTRACT (the SmoothWRR-weights asymmetry): when using BoundedLoad, update `inflight[i]` AND call
+ * `note(i, +/-1)` in LOCKSTEP (or drive it through the /pool adapter, which does both). `note`
+ * maintains `_total`; it does NOT write `inflight`. A direct `inflight` write without the matching
+ * `note` desyncs `_total` from the true sum, so the cap goes wrong -- UB. `note()` clamps `_total`
+ * at 0; `totalInflight` exposes it.
  *
  * Bound: O(1) per pick (modulo + table read + bounded cap-aware probe), 0 B/op on BOTH `pick()` and
  * `note()` (torture + PerfGate). Fails closed (PICK_NONE) ONLY when no eligible backend is reachable
@@ -1073,7 +1198,7 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
      * @param {number} delta  integer occupancy change (+1 dispatch, -1 settle)
      */
     note(i, delta) {
-        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        _vIdx(i, this._cap);
         if (typeof delta !== 'number') throw new TypeError('[lite-pick] delta must be a number');
         if (!Number.isInteger(delta)) throw new RangeError('[lite-pick] delta must be an integer: ' + delta);
         const t = this._total + delta;
@@ -1083,8 +1208,8 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
     /**
      * Map an INTEGER key to a backend, honouring the occupancy cap, or PICK_NONE (fail closed). O(1),
      * 0 B/op, never throws. slot = (keyHash >>> 0) % M; walk the M8 probe window (home + CH_PROBE_LIMIT
-     * slots) and return the FIRST backend that is ELIGIBLE AND under cap = (1+eps) x _total / live. If
-     * none in the window is under cap, fall back to the FIRST eligible seen (sticky wins -- the cap is
+     * slots) and return the FIRST backend that is ELIGIBLE AND under cap = ceil((1+eps) x (_total+1) /
+     * live). If none in the window is under cap, fall back to the FIRST eligible seen (sticky wins -- the cap is
      * a soft preference, never a dead pick). `_total === 0` skips the cap test -> pure ConsistentHash.
      * PICK_NONE ONLY when no eligible backend is reachable within the window.
      * @param {number} keyHash  a caller-supplied integer key hash (coerced to uint32)
@@ -1096,7 +1221,10 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
         const total = this._total;
         // cap is only meaningful once occupancy is known; _total === 0 -> pure ConsistentHash.
         const capActive = total > 0;
-        const cap = capActive ? (1 + this._eps) * total / this._live : 0;   // finite: total>0, live>0
+        // CHBL cap (Mirrokni-Thorup-Zadimoghaddam per-bin capacity). The load-bearing part is the +1
+        // that counts the INCOMING request; the Math.ceil matches the paper's integer capacity but is a
+        // no-op for the `inf < cap` test (integer inf: `inf < ceil(x)` == `inf < x`).
+        const cap = capActive ? Math.ceil((1 + this._eps) * (total + 1) / this._live) : 0;   // >= 1: total>0, live>0
         let slot = (keyHash >>> 0) % M;           // integer key; NaN >>> 0 = 0 (never throws)
         let firstEligible = -1;                   // the pure-ConsistentHash sticky fallback answer
         let i = lookup[slot];
@@ -1118,3 +1246,177 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
         return firstEligible;   // -1 (PICK_NONE) iff NO eligible backend was reachable in the window
     }
 }
+
+/**
+ * WeightedRandomBalancer -- O(1) weighted-random selection via a Vose/Walker ALIAS TABLE (M10),
+ * the roster-completing strategy.
+ *
+ * `pick()` draws ONE column uniformly (`prng.nextBelow(cap)`), compares one fresh uniform against
+ * `_prob[col]`, and takes `col` or `_alias[col]` -- a constant handful of integer/float ops that
+ * return an endpoint proportional to its weight. This is the STATELESS O(1) weighted selector: no
+ * per-endpoint accumulator to desync (SmoothWRR's `_current`), just a static table sampled with a
+ * PRNG -- the fit for VERY LARGE pools where SmoothWRR's O(cap)-per-pick scan hurts. It trades
+ * SmoothWRR's deterministic low-variance smoothness for sampling variance (any single pick is
+ * random; the LAW OF LARGE NUMBERS delivers the weight ratios over a run -- balance.mjs anchors it).
+ *
+ * ELIGIBILITY is REJECTION SAMPLING over the shared bitmap (the ADR 0005 / P2C discipline, not a
+ * table rebuild): if the drawn candidate is ineligible, redraw up to a bounded 64 times, then fall
+ * back to a 0-B/op rotated linear scan from a random start for the degenerate heavy-outage case.
+ * Because the alias table is built over the ELIGIBLE-INDEPENDENT weights and a candidate is ALWAYS
+ * a positive-weight node (a weight-0 node is never a column -- see _build), rejecting the ineligible
+ * draws RENORMALIZES the weight distribution over the SURVIVING eligible mass: each eligible node's
+ * long-run share converges to weight[i] / sum(eligible weights) (ADR 0012 Fork 1). The rare fallback
+ * scan returns the first eligible positive-weight node from a random offset (unbiased first-after-
+ * offset), a correctness net, not a proportional path.
+ *
+ * Ownership (ADR 0001, ADR 0004, ADR 0012): `weights` is the CALLER's Uint32Array (length >= capacity)
+ * -- the SmoothWRR / SED weight seam -- and the balancer is the SOLE writer of its DERIVED alias table
+ * (`_prob` Float64Array + `_alias` Int32Array, both balancer-owned) via the cold `setWeight` / `rebuild`
+ * (which read `weights` and rebuild the table); mutating `weights` directly desyncs the table (UB, the
+ * SmoothWRR asymmetry). The alias build reuses COLD scratch worklists allocated once in the ctor -- the
+ * build allocates nothing per call, and pick() allocates nothing per call.
+ *
+ * Fail-closed (ADR 0012 Fork 2): `pick()` returns PICK_NONE (-1) IFF `live === 0` OR no eligible node
+ * has a positive weight (all-zero weights, or every eligible node's weight is 0). NEVER a dead pick,
+ * a weight-0 return, or an out-of-range index. `pick()` never throws.
+ *
+ * Bound: O(1) per pick (one column draw + one compare, expected O(1) rejection draws when eligibility
+ * is dense), 0 B/op (integer/float locals only) -- proven by test/torture.mjs + test/perf/PerfGate.test.mjs.
+ *
+ * DEFERRED optional-peer seams (import NOTHING; peerDependencies STAYS `{}` until a shipped path imports
+ * one): a `@zakkster/lite-o1` `AliasTable` as a duck-typed drop-in for the inline Vose build, and a
+ * `@zakkster/lite-logn` Fenwick/BinaryIndexedTree for the DYNAMIC-weight case (O(log n) update + sample)
+ * -- the mutable-weight complement to this static table's O(1) sample / O(cap) rebuild (ADR 0012).
+ *
+ * NOT `@zakkster/lite-random`: that sibling is a GAME RNG (Mulberry32; loot tables, particles, gaussian)
+ * whose `weighted(items, weights)` returns an ITEM one-shot, is NOT eligibility-aware, holds no reusable
+ * table, and uses a different PRNG. lite-pick's WeightedRandom returns an endpoint INDEX, honours the
+ * shared eligibility bitmap (fail-closed), owns a persistent alias table rebuilt only on reweight, and
+ * uses the in-repo xorshift32. Different domain + contract -- not a peer, not a substrate (ADR 0012 / GUIDE.md).
+ */
+export class WeightedRandomBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed; add/remove is a cold rebuild).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param {Uint32Array} weights  caller-owned per-endpoint weights (length >= capacity); the balancer
+     *   is the sole writer of the DERIVED alias table via setWeight (direct mutation desyncs it -- UB).
+     * @param {number} [seed=0x9e3779b9]  deterministic PRNG seed (reproducible benches).
+     */
+    constructor(capacity, eligible, weights, seed = 0x9e3779b9) {
+        super(capacity, eligible);
+        // Validate typeof-first, BEFORE allocating the owned table / scratch (fail closed early -- the
+        // PeakEWMA / ConsistentHash / BoundedLoad discipline).
+        if (!(weights instanceof Uint32Array) || weights.length < capacity) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._weights = weights;
+        this._rng = new Prng(seed);
+        // Balancer-owned derived table: _prob (the split probability per column) + _alias (the column's
+        // alternate). A candidate is ALWAYS a positive-weight node (see _build), so pick() never returns
+        // a weight-0 index.
+        this._prob = new Float64Array(capacity);
+        this._alias = new Int32Array(capacity);
+        // COLD scratch worklists for the Vose build (small/large index stacks + the scaled probabilities),
+        // allocated ONCE here and reused by every _build -- the build never allocates per call.
+        this._small = new Int32Array(capacity);
+        this._large = new Int32Array(capacity);
+        this._scaled = new Float64Array(capacity);
+        this._psum = 0;      // sum of ALL weights (the eligible-independent normalizer); 0 => degenerate.
+        this._builds = 0;    // COLD rebuild counter (observability / the anti-flap gate: a flap adds 0).
+        this._build();
+    }
+
+    /**
+     * COLD: (re)build the Vose/Walker alias table from the current caller weights. The standard
+     * small/large worklist over `scaled[i] = weights[i] * cap / total` (mean-1 normalization): pair a
+     * deficient (< 1) column with a surplus (>= 1) one until one worklist empties, then drain the
+     * residue (numerically ~1 full columns) to prob 1. A weight-0 node has scaled 0, so it is popped
+     * once, assigned prob 0 + a POSITIVE-weight alias, and NEVER reaches the prob-1 drain -- it can
+     * never be returned as its own column. All-zero weights (total 0) leaves _psum 0 and pick() fails
+     * closed. Reuses the cold scratch worklists -- allocates nothing. ~15 lines (do NOT re-implement
+     * lite-o1's AliasTable; this is the inline standard build, ADR 0012 Fork 0).
+     */
+    _build() {
+        this._builds++;
+        const cap = this._cap, wt = this._weights, prob = this._prob, alias = this._alias;
+        const scaled = this._scaled, small = this._small, large = this._large;
+        let total = 0;
+        for (let i = 0; i < cap; i++) total += wt[i];
+        this._psum = total;
+        if (total <= 0) {
+            // Degenerate all-zero weights: no positive-weight column. pick() short-circuits on _psum===0
+            // (PICK_NONE), so the table is never read -- fill it defensively (each column self-referential).
+            for (let i = 0; i < cap; i++) { prob[i] = 0; alias[i] = i; }
+            return;
+        }
+        const scale = cap / total;
+        let ns = 0, nl = 0;                       // small / large stack heights (indices into the scratch)
+        for (let i = 0; i < cap; i++) {
+            const v = wt[i] * scale;
+            scaled[i] = v;
+            if (v < 1) small[ns++] = i; else large[nl++] = i;
+        }
+        while (ns > 0 && nl > 0) {
+            const s = small[--ns];
+            const l = large[--nl];
+            prob[s] = scaled[s];
+            alias[s] = l;                         // l is surplus (scaled >= 1) => positive weight
+            const rem = (scaled[l] + scaled[s]) - 1;
+            scaled[l] = rem;
+            if (rem < 1) small[ns++] = l; else large[nl++] = l;
+        }
+        while (nl > 0) { const l = large[--nl]; prob[l] = 1; alias[l] = l; }   // full columns
+        while (ns > 0) { const s = small[--ns]; prob[s] = 1; alias[s] = s; }   // float residue ~1
+    }
+
+    /**
+     * COLD: reconfigure endpoint i's weight (uint32) and REBUILD the alias table from the new weights.
+     * The balancer is the sole writer of the derived table (the SmoothWRR / ConsistentHash precedent).
+     * @param {number} i
+     * @param {number} w  new weight (uint32)
+     */
+    setWeight(i, w) {
+        _vIdx(i, this._cap);
+        const nw = w >>> 0;
+        if (nw !== w) throw new RangeError('[lite-pick] weight must be a uint32: ' + w);
+        if (nw === this._weights[i]) return;
+        this._weights[i] = nw;
+        this._build();
+    }
+
+    /** COLD: rebuild the alias table from the current caller weights (e.g. after a membership change). */
+    rebuild() {
+        this._build();
+    }
+
+    /**
+     * Pick an endpoint index proportional to weight, or PICK_NONE (fail closed). O(1), 0 B/op, never
+     * throws. One column draw + one probability compare yields a positive-weight candidate; an
+     * ineligible candidate is rejection-redrawn up to 64 times (renormalizing the weight distribution
+     * over the eligible mass), then a rotated linear scan from a random start returns the first eligible
+     * positive-weight node. PICK_NONE IFF live === 0 OR no eligible node has a positive weight.
+     * @returns {number}
+     */
+    pick() {
+        if (this._live === 0 || this._psum === 0) return PICK_NONE;   // pool down / no positive weight
+        const cap = this._cap, el = this._eligible, prob = this._prob, alias = this._alias, rng = this._rng;
+        // Fast path: alias draw + rejection on eligibility. A candidate is always positive-weight, so
+        // rejecting the ineligible ones renormalizes weight-proportionality over the surviving mass.
+        for (let t = 0; t < 64; t++) {
+            const col = rng.nextBelow(cap);
+            const u = rng.next() / 4294967296;    // fresh uniform in [0, 1)
+            const cand = u < prob[col] ? col : alias[col];
+            if (el[cand]) return cand;
+        }
+        // Degenerate (very sparse eligibility): scan from a random start for the first eligible,
+        // positive-weight node. Zero-alloc; returns PICK_NONE only if none exists.
+        const wt = this._weights;
+        let i = rng.nextBelow(cap);
+        for (let k = 0; k < cap; k++) {
+            if (el[i] && wt[i] > 0) return i;
+            i++;
+            if (i >= cap) i = 0;
+        }
+        return PICK_NONE;                         // no eligible positive-weight node
+    }
+}