@zakkster/lite-pick 0.9.0 → 1.0.1

package/CHANGELOG.md

@@ -4,6 +4,200 @@ 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).
 
+## [1.0.1] - 2026-09-27
+
+Bug-fix release: the fixes from the full audit at `audit/2026-09-26/` (audited code state commit
+`8c1ecc7`; H1-H4 and M1 independently reproduced on darwin/arm64 Node 26 before fixing). No new
+strategy, no new public class, no removed API -- caller-visible behaviour changes only where a
+documented contract was wrong or unsafe. See [ADR 0013](./decisions/0013-audit-1.0.1.md).
+
+### Fixed
+
+- **PeakEWMA + Pool no longer turns a fast-failing or hung endpoint into a black hole (H1).**
+  Kernel side: an unsampled node now costs 0 only WHILE IDLE (so it holds one request in flight at a
+  time until its first sample); an unsampled BUSY node is priced at the LIFETIME mean of all recorded
+  samples, not the old 1.0 ns baseline; a sampled node with work in flight is floored at
+  time-since-last-sample, so a hung node gets MORE expensive over time instead of decaying toward 0.
+  `Pool.run` side: a thrown attempt now feeds `recordRtt(i, max(elapsed, failurePenaltyNs), done)`
+  (new `opts.failurePenaltyNs`, default `1e9`), so a failing node stops being the cheapest pick.
+  Measured (4 PeakEWMA nodes, node 0 always throws): failure rate 49.4% (988/2000) in 1.0.0 -> ~0.05%
+  (1/2000); a hung node took 1 dispatch, was 4891/10000.
+- **SmoothWRR never returns a weight-0 node (H3).** `pick()` now requires a candidate to be eligible
+  AND have `weight > 0` (path-independent -- covers `setWeight(i, 0)` and eligibility toggles), and
+  `setWeight` resets that node's accumulated credit. A drained node is no longer selected.
+- **BoundedLoad keeps key affinity at the low-load boundary (H4).** The per-backend cap is now
+  `ceil((1 + eps) * (total + 1) / live)`; the `+ 1` counts the incoming request
+  (Mirrokni-Thorup-Zadimoghaddam per-bin capacity), so the cap is always >= 1. The `Math.ceil` is a
+  no-op for the integer `inflight < cap` test; behaviour is identical to 1.0.0 except at the boundary
+  where the old cap fell below 1.
+- **Non-integer, NaN, negative and string indices are rejected instead of silently desyncing state
+  (M1).** One shared index-validation helper (`(i >>> 0) === i && i < capacity`) guards `setEligible`,
+  `setWeight` (SmoothWRR / ConsistentHash / BoundedLoad / WeightedRandom), `note` and `recordRtt`:
+  they throw `RangeError` for `NaN`, fractions (`1.5`), negatives, out-of-range, and non-numbers
+  (including numeric strings like `'2'`, which previously "worked"); a rejected call changes no state.
+  `isEligible` returns `false` for a non-integer instead of `true`.
+- **`Pool` failover now reaches a genuinely DIFFERENT endpoint (M2).** A per-run tried set, up to 8
+  re-picks, then a scan for an eligible untried endpoint from a key-derived start (keyed) or a
+  rotating per-Pool cursor (unkeyed); when no untried eligible endpoint remains, failover STOPS and
+  the last error is thrown (a 1-node pool with `tries: 3` now makes 1 attempt). ConsistentHash keyed
+  `tries: 3` now hits 3 distinct backends (was `3, 3, 3`); a failing backend's keys spread over
+  neighbours (max share ~23%, was 100% onto one neighbour in an intermediate build).
+- **A `recordRtt` exception after a SUCCESSFUL call no longer re-runs `fn` (M4).** Settle-time
+  feedback runs OUTSIDE the attempt's try/catch, so `fn` runs exactly once; if it fails, `run` rejects
+  with a `LITE_PICK_FEEDBACK`-coded error carrying `.cause` and `.result` (fn's resolved value).
+- **`Pool.run(fn, null)` works (L1).** `opts` may be omitted or `null`; the option reads are null-safe.
+- **A throwing custom `note(+1)` no longer leaves an unpaired `note(-1)`** at settle: `note(-1)` fires
+  only for a dispatch whose `note(+1)` actually landed, and a cleanup-time throw is swallowed so it
+  never masks the error being thrown.
+- **PeakEWMA `dt` is clamped `>= 0` in `pick`, `recordRtt` and `ewmaAt` (L6),** so a non-monotonic
+  clock can no longer inflate the estimate via `exp(+x)`.
+- **`verify` is green (H5).** The PerfGate WeightedRandom heavy-outage scenario is shrunk (`FB_CAP`
+  2048; slowest phase 16.7 s -> ~3 s) so V8's memory reducer can no longer fire inside it.
+
+### Changed
+
+- **`Pool.run` keyed and latency channels are now separate and REQUIRED (M3).** A keyed balancer
+  (`ConsistentHashBalancer` / `BoundedLoadBalancer`, marked `static KEYED = true`) requires a numeric
+  `opts.key` (else `LITE_PICK_KEY_REQUIRED`); a latency balancer (`PeakEwmaBalancer`, marked
+  `static LATENCY = true`) requires an `opts.clock` (else `LITE_PICK_CLOCK_REQUIRED`). The key reaches
+  ONLY a keyed pick; a clock reading NEVER reaches a keyed pick. A non-keyed clocked run still passes
+  the clock reading to `pick(now)` (preserving 1.0.0 behaviour for a duck-typed latency balancer that
+  omits the marker). Previously a missing key routed everything to one backend, and `key` / `clock`
+  were conflated.
+- **`Pool.run` checks the abort signal before EVERY attempt.** An already-aborted signal now
+  dispatches nothing and rejects (`throwIfAborted`, then the signal's `reason`, else
+  `LITE_PICK_ABORTED`), including a structural `{ aborted: true }` signal with no `throwIfAborted`.
+- **A backwards but finite clock reading on a successful settle records NO rtt sample** (a fabricated
+  0 ns sample would make the node look instant); `done === now` is a real coarse-clock 0 and is
+  recorded. A non-finite clock reading throws before dispatch.
+- **On a failed attempt whose penalty feedback then fails, `Pool.run` throws `fn`'s original error
+  object (identity preserved)** with a non-enumerable `liteFeedbackError` attached, and stops
+  failover.
+- **`liteQueryFetcher` forwards `clock` and `failurePenaltyNs`** to `pool.run` (validated once at
+  creation). Its `ctx.key` remains the query-cache key, not a routing key.
+- **PeakEWMA `tau` is documented as the EWMA TIME CONSTANT (half-life = `tau x ln2`),** correcting the
+  earlier "half-life" wording (L5). No math change.
+- **Static class markers added:** `ConsistentHashBalancer.KEYED` (inherited by `BoundedLoadBalancer`)
+  and `PeakEwmaBalancer.LATENCY`, so `/pool` selects the right channel while staying duck-typed.
+- **BoundedLoad docs corrected (M-Doc1):** update `inflight[i]` AND call `note(i, +/-1)` in lockstep
+  (or drive it through `/pool`); `note` maintains `_total`, it does not write `inflight`.
+- **Types tightened:** `pick(now)` / `pick(keyHash)` are now REQUIRED on the concrete
+  `PeakEwmaBalancer` / `ConsistentHashBalancer` / `BoundedLoadBalancer` classes (`BalancerBase.pick`
+  stays deliberately loose, `pick(arg?)`); the `KEYED` / `LATENCY` markers are typed; `Pool.d.ts` now
+  uses a structural `AbortLike` type (compiles with `lib: ES2022` and no DOM, L15).
+
+### Added
+
+- **`opts.failurePenaltyNs`** on `Pool.run` (and `liteQueryFetcher`): the minimum rtt penalty a thrown
+  attempt feeds a latency-aware balancer (finite `> 0`, default `1e9`).
+- **`typesVersions`** maps `@zakkster/lite-pick/pool` -> `Pool.d.ts` for `moduleResolution: node10`
+  (L16); `test:types` gains an ES2022-no-DOM lane.
+- **`.github/workflows/ci.yml`:** `test` (Node 20/22/24 x ubuntu/macos/windows), `test-node18` (unit
+  suites only, backing `engines >=18`), `gates` (torture, `test:perf`, `bench:verify`, an exact
+  11-file tarball check), and `types-compat` (the packed tarball compiled with TypeScript 5 under
+  node10 / node16 / bundler / ES2022-only on case-sensitive Linux). `package-lock.json` is now
+  committed (maintainer decision; follows lite-di-container).
+- **`test` is now an explicit file list** (portable to Windows / Node 20 -- no shell glob), guarded by
+  `test/suite-list.test.js`, which fails if any test file under `test/` is not run.
+- **Gates hardened with teeth:** `test:perf` pins the semi-space `min = max = 1 MB` (sharper than
+  1.0.0's `max = 4 MB`) with a fail-closed test asserting the pin; must-fail allocations escape via a
+  64-slot ring and `grows` compares buffer identity (M-T3); new intermittent must-fail controls (an
+  allocation every 16 and every 32 picks). `torture` now reports RETAINED B/op, treats an unmeasured
+  reading as FAIL, and has a retaining must-fail control (trips at 40 B/op) (H6); `GcBlastRadius`
+  likewise, and its README column is renamed "pick retained B/op". Every `benchmark/*.mjs` entry check
+  uses `pathToFileURL` (M-T2); `bench:verify` states which blocks are re-measured vs compared to stored
+  `results.json` (M-T1); the fuzz single-node-down block uses one eligibility array per balancer (M-T4)
+  and prints the discovery seed every run (L21).
+- Demo (repo-only, not in the tarball): the Pool Scope web server binds `127.0.0.1`, serves GET/HEAD
+  only, enforces a path allowlist + Host-header check + `path.relative`/`realpath` traversal guard +
+  `nosniff` + port validation (M-D1, M-D2, L26); the driver keeps BoundedLoad's `totalInflight` in
+  lockstep (M-D3); the TUI reset uses `DEFAULT_CONC` and restores the terminal on SIGTERM/SIGHUP with
+  the alternate screen (M-D4, L23); fanout counts only distinct failovers and reports exhausted
+  requests (L24).
+
+### Known limitations
+
+Disclosed, shipped, and slated for 1.1.0:
+
+- **A realistic (non-small-integer) number argument boxes once per non-inlined call.** V8 boxes a
+  `HeapNumber` (~16 B) for a `PeakEWMA` `pick(now ~1.7e15)`, ~16-30 B for `recordRtt` with a realistic
+  clock and a fractional sample, and ~16 B for `ConsistentHash`/`BoundedLoad` `pick(keyHash >= 2^31)`.
+  Small-integer arguments are 0 B/op (range is build-dependent: `< 2^31` on stock 64-bit Node, `< 2^30`
+  on pointer-compressed builds); values produced by `%` or division may box even when small. 1.1.0 adds
+  buffer-based variants that read the clock/key from a caller-owned typed array (prototype measured
+  0 B/op at 1e15). `test:perf` prints these as report-only lines every run.
+- **OPEN:** run in isolation with some integer sample patterns (e.g. mod 500000, step 1000), the
+  PerfGate `recordRtt` lane shows a small allocation that scales with window length (8N: 2, 16N: 4,
+  32N: 9 scavenges at the 1 MB pin); it disappears with `--no-maglev`,
+  `--no-concurrent-recompilation`, or a preceding lane. Root cause not established; printed as a
+  report-only line; tracked for 1.1.0.
+- **M5 (LeastConn / NQ tie order) is now documented as unspecified.** A rotating tie-break lands in
+  1.1.0; it was moved OUT of 1.0.1 because "lowest index" was an explicit documented promise, so
+  changing it is not a patch-level fix.
+
+### Not in this release
+
+- The soak redesign (audit RECOMMENDATIONS section 1): the 1.0.0 soak's drift gates compared lanes
+  rather than time, and its heap sample included harness bookkeeping. Redesign pending.
+- Observability (section 2): zero-cost counters, `diagnostics_channel`/hooks, `describe()`, error codes.
+- The `Eligibility` object as the shared unit (section 3.1) -- a breaking change deferred to 2.0.
+
+## [1.0.0] - 2026-09-23
+
+The **roster-complete** release: ten selection strategies + the `/pool` request layer + the benchmark
+suite + the docs/GUIDE capstone. Roster complete **for now, not closed** -- AZ-aware routing, the
+lite-await hedging combinator, and subsetting are queued post-1.0 (see [ROADMAP.md](./ROADMAP.md)).
+
+### Added
+
+- **`WeightedRandomBalancer` (M10)** -- O(1) weighted-random selection via an inline **Vose/Walker alias
+  table** (one column draw + one probability compare -> a candidate) with **rejection-sampling
+  eligibility** (retry an ineligible candidate up to a bounded 64, then a 0-B/op rotated linear eligible
+  scan) -- the ADR 0005 / P2C discipline. The alias table is built **cold** over the eligible-independent
+  weights, so a **weight-0 node is never a column** (never returned) and rejecting the ineligible draws
+  **renormalizes** the weight distribution over the surviving eligible mass (each eligible node's share
+  converges to `weight[i] / sum(eligible weights)`). `weights` is the caller's `Uint32Array` (the
+  SmoothWRR/SED seam); the balancer is the **sole writer** of its derived table (`_prob` / `_alias`) via
+  cold `setWeight` / `rebuild` -- an eligibility flap **never** rebuilds (anti-flap). Validates
+  typeof-first before allocating the table. `pick()` is **O(1)**, **0 B/op**, never throws; `PICK_NONE`
+  only when `live === 0` or no eligible node has a positive weight. It is the **stateless** O(1) weighted
+  sampler (no accumulator to desync) for very large pools where SmoothWRR's O(cap) scan hurts -- trading
+  smoothness for sampling variance. `peerDependencies` stays `{}` (the Vose build is inlined; a lite-o1
+  `AliasTable` and a lite-logn Fenwick tree are deferred optional peers, imported by nothing).
+  ([ADR 0012](./decisions/0012-weightedrandom.md)).
+- **Fairness anchor** (`test/balance.mjs`) -- n=64, skewed weights [1..16], 8e6 seeded draws: every node's
+  observed share is within **2% relative** of `weight[i]/sum` (measured worst ~0.84%), and a cumsum-linear
+  O(n) foil matches the same fairness. The O(1) alias sample beats that O(n) foil by **~107x ops/ms** at
+  n=4096 (gate: >=3x). Under half the pool down (1e6 picks): **0 ineligible / 0 weight-0** returns,
+  survivor shares within **3% relative** of `weight[i]/sum(eligible)` (measured worst ~1.77%), and all-zero
+  weights -> `PICK_NONE`. Thresholds are the sampling-variance floor from a correct run (N sized so the
+  band holds with margin) -- the band is never widened to pass.
+- **`GUIDE.md`** -- the "which of the ten strategies do I pick?" decision guide (a decision tree + table
+  keyed by keyed-vs-load-vs-latency-vs-weighted, O(1) vs O(cap), state owned, and when each wins),
+  distinct from `RECIPES.md` (how-to wiring). Added to the published `files[]` (the tarball is now 11 files).
+- Gates extended for the new strategy: `test/WeightedRandom.test.js` boundary + behaviour suite;
+  `test/fuzz.mjs` keyed-agnostic subject + `checkWeightedRandom` (structural + no-weight-0-column + the
+  sum-reconstruction invariant, after every op) + a 1000-flap **0-rebuild** anti-flap assertion;
+  `test/torture.mjs` retention + a `pick()` 0 B/op phase (phase 14); `test/perf/PerfGate.test.mjs`
+  `weightedRandomPick` zero-alloc scenario + a boxed `mustFail` tooth; `test/witness.mjs` 'const'
+  flat-work subject; `benchmark/Matrix.mjs` throughput + fairness subject; `benchmark/Report.mjs`
+  Weighted-random parity row now times `WeightedRandomBalancer` vs `wrr` (both O(1) weighted-random --
+  previously a pending SKIP); `Pick.d.ts` + `test/types/pick.test-d.ts` typed surface.
+
+### Changed
+
+- **`Pick.js` header roster/count** nine -> **ten**, and the `VERSION` stamp `0.9.0` -> `1.0.0` (the
+  three-place sync: `package.json`, the `VERSION` const, `llms.txt`). This session appends **one** class;
+  every other strategy in `Pick.js` is byte-identical.
+- **`package.json`** version `1.0.0`, the description roster gains WeightedRandom + a GUIDE.md pointer,
+  keywords gain `alias-method` / `vose` (`weighted-random` was already present), and `files[]` gains
+  `GUIDE.md`. `peerDependencies` stays `{}`.
+- Sibling boundary documented explicitly (so 1.0.0's WeightedRandom does not look duplicative with
+  `@zakkster/lite-random`): lite-random is a **game RNG** returning an item, not eligibility-aware, no
+  reusable table; lite-pick WeightedRandom returns an endpoint index, honours the shared eligibility
+  bitmap (fail-closed), and owns a persistent alias table -- different domain, not a peer (GUIDE.md,
+  llms.txt, ADR 0012).
+
 ## [0.9.0] - 2026-09-23
 
 ### Added

package/GUIDE.md

@@ -0,0 +1,105 @@
+# Which strategy? -- the lite-pick decision guide
+
+`@zakkster/lite-pick` ships **ten** selection strategies. They are not ranked; each wins a different
+job. This guide is how you CHOOSE one. It is deliberately distinct from [RECIPES.md](./RECIPES.md),
+which shows how to WIRE a chosen strategy (dispatch/settle counters, health, the `/pool` layer).
+
+Every strategy shares the same contract: a hot `pick()` returning an endpoint **index** over a fixed
+pool, **fail-closed** (`PICK_NONE` = -1 when nothing is pickable, never a dead pick), reading a
+**read-only eligibility bitmap** it never writes -- flipped only through `setEligible` (the sole
+supported writer, which keeps the cached `live` exact; a direct byte write desyncs it), and each
+balancer has its own eligibility array.
+
+`pick()` **allocates 0 B/op** (PerfGate scavenge counting) and **retains 0 B/op** (torture) in the
+steady state. KNOWN LIMITATION (1.0.1): the strategies that take a **number argument** on the hot
+path -- `PeakEWMA.pick(now)` / `recordRtt(..., now)` with a realistic nanosecond clock, and
+`ConsistentHash`/`BoundedLoad.pick(keyHash)` with a key `>= 2^31` -- box that argument into a ~16 B
+transient `HeapNumber` when the call is not inlined (transient, does not retain, does not force a
+major GC). Arguments within V8's small-integer range are 0 B/op; that range is build-dependent (below
+2^31 on stock 64-bit Node, below 2^30 on pointer-compressed builds such as Chrome/Electron), and a
+value produced by `%` or division can box even when its value is a small integer. Buffer-based
+variants are planned for 1.1.0.
+
+## The one question that splits everything: what fixes the primary choice?
+
+```
+Is routing decided by a KEY (same key -> same backend, for cache/session affinity)?
+|
++-- YES -> you want a CONSISTENT HASH.
+|          |
+|          +-- Do a few hot keys overload one backend?
+|          |     NO  -> ConsistentHash   (sticky, minimal disruption, O(1))
+|          |     YES -> BoundedLoad       (sticky + an occupancy cap that overflows a hotspot, O(1))
+|
++-- NO -> the choice is by LOAD / LATENCY / WEIGHT, not a key.
+          |
+          +-- Do you have a LATENCY signal (rtt) and want to steer around a slow-but-up node?
+          |     YES -> PeakEWMA           (latency-aware power-of-two-choices, O(1))
+          |
+          +-- Do you have live IN-FLIGHT counts (a closed dispatch/settle loop)?
+          |     |
+          |     +-- Want the EXACT least-loaded, and O(cap) is fine (dozens-hundreds of nodes)?
+          |     |     unweighted        -> LeastConn   (exact fewest-in-flight, O(cap))
+          |     |     weighted          -> SED         (minimizes (inflight+1)/weight, O(cap))
+          |     |     worker pool (idle-first) -> NQ    (never-queue: idle node first, else SED, O(cap))
+          |     |
+          |     +-- Want O(1) at very large pools and can accept a tiny balance gap?
+          |           -> P2C              (power-of-two-choices, the ln ln n ceiling, O(1))
+          |
+          +-- No load signal -- just spread by a fixed WEIGHT (or evenly)?
+                |
+                +-- Equal weight, simple rotation      -> RoundRobin   (O(1) amortized)
+                +-- Weighted, want SMOOTH low-variance  -> SmoothWRR    (deterministic, O(cap))
+                +-- Weighted, want STATELESS O(1) at scale -> WeightedRandom (alias table, O(1))
+```
+
+## The table
+
+| Strategy | Decides by | Bound / pick | State the balancer owns | Wins when |
+| --- | --- | --- | --- | --- |
+| **RoundRobin** | rotation | O(1) amortized | a cursor | equal weight, no load signal, simplest fair spread |
+| **SmoothWRR** | fixed weight | O(cap) | smoothing accumulators (`_current`) | weighted **and** you want deterministic, smooth, low-variance interleaving |
+| **WeightedRandom** | fixed weight | **O(1)** | a Vose alias table (`_prob`/`_alias`) | weighted at **very large** pools where SmoothWRR's O(cap) scan hurts; can accept sampling variance |
+| **P2C** | in-flight load | **O(1)** | just a PRNG | O(1) load-balancing at scale; the `ln ln n` peak ceiling, a tiny gap vs exact |
+| **LeastConn** | in-flight load | O(cap) | none (reads live) | the **exact** least-loaded in a feedback loop; dozens-hundreds of nodes |
+| **SED** | (inflight+1)/weight | O(cap) | none (reads live) | **weighted** exact least-loaded (load settles proportional to weight) |
+| **NQ** | idle-first, else SED | O(cap) | none (reads live) | **worker pools** -- never queue while a server is idle |
+| **PeakEWMA** | (inflight+1) x decayed rtt | **O(1)** | EWMA rtt state (`_ewma`/`_stamp`) | you have latency and want to steer around a **slow-but-up** node |
+| **ConsistentHash** | key hash (Maglev) | **O(1)** | a Maglev lookup table | **sticky** cache/session affinity; minimal disruption on scale events (~1/N keys move) |
+| **BoundedLoad** | key hash + occupancy cap | **O(1)** | Maglev table + a running `_total` | sticky routing **and** a few hot keys would otherwise overload one backend |
+
+## SmoothWRR vs WeightedRandom -- the weighted fork, made explicit
+
+Both send load proportional to a configured integer weight. They differ in HOW and in cost:
+
+- **SmoothWRR** is DETERMINISTIC and SMOOTH: weights `[5,1,1]` yield `A A B A C A A`, not bursts. It
+  converges EXACTLY (counts == k x weight over a cycle) with the lowest variance. Cost: **O(cap) per
+  pick**, and it owns per-endpoint accumulator state that is maintained in lockstep.
+- **WeightedRandom** is a STATELESS **O(1)** sample from a Vose alias table: one column draw + one
+  compare. It converges to the weight ratios by the law of large numbers (any single pick is random --
+  it pays SAMPLING VARIANCE). No accumulator to desync.
+
+Rule of thumb: **small-to-medium pools or when smoothness matters -> SmoothWRR; very large pools where
+the O(cap) scan hurts -> WeightedRandom.** For **frequently-changing** weights, a `@zakkster/lite-logn`
+Fenwick tree (O(log n) update + sample) is the deferred dynamic-weight complement to WeightedRandom's
+static alias table (rebuilt cold on reweight); see the roadmap.
+
+## Not sure you even want lite-pick? -- the sibling boundary
+
+- **`@zakkster/lite-random` is NOT a load balancer.** It is a GAME RNG (Mulberry32) for loot tables,
+  particle systems, and gaussian sampling; its `weighted(items, weights) -> T` returns an **item**
+  one-shot, is not eligibility-aware, and holds no reusable table. For **game loot tables use
+  lite-random**; **lite-pick WeightedRandom is the eligibility-aware LB selector** (returns an endpoint
+  INDEX, honours the shared eligibility bitmap, owns a persistent alias table rebuilt only on reweight,
+  fail-closed). Different domain, different contract -- lite-random is not a peer or a substrate here.
+- lite-pick is the **in-process** hop selector: it consumes health/circuit state and returns an index;
+  it is never a proxy. It is complementary to AWS NLB/ALB (which balance the network hop AWS sees) --
+  ALB's `weighted_random` + anomaly mitigation is lite-pick's WeightedRandom + BoundedLoad, and NLB's
+  flow-hash is ConsistentHash, at the hop AWS never sees.
+
+## Then wire it
+
+Once you have picked a strategy, [RECIPES.md](./RECIPES.md) shows the real wiring: the shared
+eligibility bitmap from a health source, the caller-owned in-flight / weight arrays, the `/pool`
+dispatch/settle + failover layer, and the latency (`recordRtt`) / occupancy (`note`) / keyed
+(`opts.key`) feedback hooks.

package/Pick.d.ts

@@ -1,10 +1,10 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M9 (0.9.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
+ * M10 (1.0.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
  * (LeastConn/SED/NQ) + PeakEWMA (latency-aware P2C) + ConsistentHash (Maglev table) +
- * BoundedLoad (P2C with a dynamic occupancy cap). The remaining strategy class (WeightedRandom)
- * is added one per session.
+ * BoundedLoad (consistent hashing with bounded loads) + WeightedRandom (O(1) Vose alias-table
+ * sampling). Roster complete for now (NOT closed: AZ-aware routing, hedging, subsetting post-1.0).
  */
 
 /** The single source-of-truth version stamp. */
@@ -32,27 +32,35 @@ export class Prng {
 }
 
 /**
- * The shared eligibility seam for every strategy. Owns the fixed capacity, a reference
- * to a shared read-only eligibility `Uint8Array` (written by @zakkster/lite-di-health /
- * circuit breakers, read by `pick()`), and an O(1) live count. Subclasses implement
- * `pick()`; the base `pick()` throws.
+ * The eligibility seam for every strategy. Owns the fixed capacity, a reference to a
+ * read-only eligibility `Uint8Array`, and an O(1) live count. The array is flipped ONLY
+ * through `setEligible` (the sole supported writer -- @zakkster/lite-di-health / circuit
+ * breakers drive that call); a direct byte write desyncs the cached live count (UB). Each
+ * balancer needs its own array. Subclasses implement `pick()`; the base `pick()` throws.
  */
 export class BalancerBase {
     /**
      * @param capacity endpoint count (fixed).
-     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param eligible 1 = pickable, 0 = down (length >= capacity); per-balancer, flipped only via `setEligible`.
      */
     constructor(capacity: number, eligible: Uint8Array);
     /** Endpoint count (fixed at construction). */
     readonly capacity: number;
     /** Number of currently eligible endpoints (O(1)). */
     readonly live: number;
-    /** True iff endpoint `i` is currently pickable. */
+    /** True iff endpoint `i` is currently pickable; a non-integer or out-of-range `i` is `false` (never throws). */
     isEligible(i: number): boolean;
-    /** Cold path: mark endpoint `i` up/down, keeping the live count exact. */
+    /** Cold path: the only supported eligibility writer -- flips `i` up/down and keeps the live count exact.
+     *  Throws `RangeError` on a non-integer or out-of-range index (incl. a numeric string like '2'). */
     setEligible(i: number, up: boolean): void;
-    /** Choose an endpoint index, or `PICK_NONE`. Abstract in the base (throws). */
-    pick(): number;
+    /**
+     * Choose an endpoint index, or `PICK_NONE`. Abstract in the base (throws). Declared with a
+     * DELIBERATELY LOOSE optional numeric argument so a keyed subclass (`pick(keyHash)`) or a latency
+     * subclass (`pick(now)`) that requires it stays assignable to `BalancerBase` (`const b:
+     * BalancerBase = ch; b.pick()` type-checks). To get the required-arg compile check, reference the
+     * CONCRETE class type (e.g. `ConsistentHashBalancer` / `PeakEwmaBalancer`), not `BalancerBase`.
+     */
+    pick(arg?: number): number;
 }
 
 /**
@@ -109,8 +117,9 @@ export class P2cBalancer extends BalancerBase {
 
 /**
  * LeastConnBalancer -- EXACT fewest-in-flight (M4, IPVS `lc`). A full O(cap) scan of the
- * caller-owned in-flight view returning the eligible node with the lowest count (lowest index
- * on a tie) -- the deterministic complement to P2C's O(1) approximation. In-flight counts are
+ * caller-owned in-flight view returning the eligible node with the lowest count (tie order is
+ * UNSPECIFIED in 1.0.1 -- deterministic, but do not depend on it; a rotating tie-break is planned
+ * for 1.1.0) -- the deterministic complement to P2C's O(1) approximation. In-flight counts are
  * caller-owned and read LIVE (no `setWeight`, no derived aggregate). 0 B/op. Fails closed
  * (`PICK_NONE`) when the whole pool is down.
  */
@@ -164,20 +173,27 @@ export class NqBalancer extends BalancerBase {
 
 /**
  * PeakEwmaBalancer -- latency-aware power-of-two-choices (M7, Twitter Finagle's peak-EWMA).
- * Draws two distinct eligible endpoints and returns the lower cost = `(inflight + 1) * ewmaAt(now)`;
- * a slow endpoint (high decayed EWMA rtt) is avoided even with a short queue. `inflight` is the
+ * Draws two distinct eligible endpoints and returns the LOWER COST (three cases: unsampled+idle -> 0;
+ * unsampled+busy -> `(inflight + 1) x lifetime mean`; sampled -> `(inflight + 1) x max(decayedEWMA,
+ * dt-while-busy)`); a slow endpoint (high decayed EWMA rtt) is avoided even with a short queue,
+ * and a hung node grows more expensive over time. `inflight` is the
  * caller-owned Uint32Array read LIVE; the EWMA state (`_ewma` / `_stamp`, Float64) is BALANCER-OWNED
  * and written ONLY by `recordRtt` (the warm feedback path). `pick(now)` decays on READ -- never
  * writes -- so it is 0 B/op, as is `recordRtt`. `now` / `sampleNs` are caller-supplied nanoseconds.
- * Cold start seeds the EWMA to 1.0 -> graceful least-connections, never NaN. O(d)=O(1). Fails
- * closed (`PICK_NONE`) when the whole pool is down.
+ * Cold start: an unsampled node costs 0 WHILE IDLE (graceful least-connections) and the pool's
+ * lifetime mean sampled rtt ONCE BUSY, so a fast-failing or hung node cannot masquerade as a 1.0 ns
+ * node and become a black hole; a hung node's busy floor grows with `dt` so it gets more expensive,
+ * not less. Never NaN. O(d)=O(1). Fails closed (`PICK_NONE`) when the whole pool is down.
+ * Latency-aware: @zakkster/lite-pick/pool REQUIRES an `opts.clock` for this strategy.
  */
 export class PeakEwmaBalancer extends BalancerBase {
+    /** Marker: latency-aware; /pool requires `opts.clock` and feeds recordRtt() from it. */
+    static readonly LATENCY: true;
     /**
      * @param capacity endpoint count (fixed).
      * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
      * @param inflight per-endpoint in-flight counts (length >= capacity), caller-owned, read live.
-     * @param tauNs the EWMA time-constant / half-life in nanoseconds (finite, > 0).
+     * @param tauNs the EWMA TIME CONSTANT in nanoseconds (finite, > 0); the half-life is tauNs x ln2.
      * @param seed deterministic PRNG seed (default 0x9e3779b9); reproducible benches.
      */
     constructor(capacity: number, eligible: Uint8Array, inflight: Uint32Array, tauNs: number, seed?: number);
@@ -186,7 +202,7 @@ export class PeakEwmaBalancer extends BalancerBase {
     /** Warm feedback path: record an rtt sample (ns) for endpoint `i` at time `now` (ns). 0 B/op. */
     recordRtt(i: number, sampleNs: number, now: number): void;
     /** Pick by latency-aware power-of-two-choices at time `now` (ns), or `PICK_NONE`. O(d)=O(1). */
-    pick(now?: number): number;
+    pick(now: number): number;
 }
 
 /** The default Maglev lookup-table size (a prime, 2^16 + 1). Configurable via the ctor. */
@@ -207,6 +223,8 @@ export const CH_PROBE_LIMIT: number;
  * Fails closed (`PICK_NONE`) when the pool is down or no eligible backend is reachable within the bound.
  */
 export class ConsistentHashBalancer extends BalancerBase {
+    /** Marker: keyed; /pool requires a numeric `opts.key`. Inherited by BoundedLoadBalancer. */
+    static readonly KEYED: true;
     /**
      * @param capacity backend count (fixed).
      * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
@@ -223,22 +241,26 @@ export class ConsistentHashBalancer extends BalancerBase {
     /** Cold path: rebuild the lookup table from the current owned weights. */
     rebuild(): void;
     /** Map an integer `keyHash` to a backend index (bounded probe past down slots), or `PICK_NONE`. */
-    pick(keyHash?: number): number;
+    pick(keyHash: number): number;
 }
 
 /**
  * BoundedLoadBalancer -- Consistent Hashing with Bounded Loads (M9, CHBL: Mirrokni et al. / Google
  * Research; Vimeo eps ~ 0.25). `ConsistentHashBalancer` (the Maglev table) PLUS an occupancy cap: a
- * key sticks to its hashed home backend UNLESS that backend is over `cap = (1 + eps) * _total / live`,
- * in which case the request OVERFLOWS along the same bounded forward-probe to the next eligible,
+ * key sticks to its hashed home backend UNLESS that backend is over
+ * `cap = ceil((1 + eps) * (total + 1) / live)` -- the load-bearing part is the `+ 1` that counts the
+ * INCOMING request (Mirrokni-Thorup-Zadimoghaddam per-bin capacity), so the cap is always >= 1 and a
+ * second concurrent same-key request correctly overflows the home. In that case the request OVERFLOWS
+ * along the same bounded forward-probe to the next eligible,
  * under-cap backend -- keeping consistent hashing's stickiness + minimal disruption AND adding the
  * HOTSPOT protection plain consistent hashing lacks. `pick(keyHash)` returns the first eligible,
  * under-cap backend in the probe window, else falls back to the first eligible seen (sticky wins; the
  * cap is a soft preference, never a dead pick); `_total === 0` skips the cap -> pure ConsistentHash.
  * `inflight` is the caller-owned Uint32Array read LIVE as the per-backend OCCUPANCY; the running
- * occupancy sum `_total` is BALANCER-OWNED and written ONLY by `note` (dispatch +1 / settle -1), so
- * when using BoundedLoad the mirrored counter must be mutated exclusively through `note` / the /pool
- * adapter (direct mutation desyncs `_total` -- UB). It inherits the Maglev table + `setWeight` /
+ * occupancy sum `_total` is BALANCER-OWNED and written ONLY by `note` (dispatch +1 / settle -1). When
+ * using BoundedLoad you 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 mutation of `inflight` without the matching `note` desyncs `_total` -- UB. It inherits the Maglev table + `setWeight` /
  * `rebuild` / `tableSize` from ConsistentHashBalancer (reused verbatim). `pick()` and `note()` are
  * both 0 B/op / O(1). Fails closed (`PICK_NONE`) ONLY when no eligible backend is reachable within
  * the probe window -- NEVER merely because backends are over cap. NOT the P2C-with-cap "overload"
@@ -266,8 +288,43 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
     );
     /** The balancer-owned running sum of in-flight the mean/cap is computed from. */
     readonly totalInflight: number;
-    /** Warm feedback path: adjust the owned occupancy sum (dispatch +1 / settle -1). Clamps at 0. 0 B/op. */
+    /**
+     * Warm feedback path: adjust the owned occupancy SUM by `delta` (dispatch +1 / settle -1), in
+     * LOCKSTEP with the caller's `inflight[i]` write. Maintains `_total`; does NOT write `inflight`.
+     * Clamps at 0. 0 B/op.
+     */
     note(i: number, delta: number): void;
     /** Map an integer `keyHash` to a backend, honouring the occupancy cap (overflow past a hot home), or `PICK_NONE`. O(1). */
-    pick(keyHash?: number): number;
+    pick(keyHash: number): number;
+}
+
+/**
+ * WeightedRandomBalancer -- O(1) weighted-random selection via a Vose/Walker ALIAS TABLE (M10). `pick()`
+ * draws one column + one probability compare to return an endpoint proportional to its weight, 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 renormalizes the weight distribution across the
+ * surviving eligible mass. `weights` is the caller-owned Uint32Array; the balancer is the SOLE writer of
+ * its derived table via cold `setWeight` / `rebuild` (direct weight mutation desyncs the table -- UB).
+ * 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 -- trading smoothness for sampling variance. O(1),
+ * 0 B/op, never throws. Fails closed (`PICK_NONE`) IFF `live === 0` OR no eligible node has a positive
+ * weight. NOT `@zakkster/lite-random` (a game RNG returning an item; use lite-random for loot tables --
+ * this is the eligibility-aware LB index selector; see GUIDE.md / ADR 0012).
+ */
+export class WeightedRandomBalancer extends BalancerBase {
+    /**
+     * @param capacity endpoint count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param weights caller-owned per-endpoint weights (length >= capacity); mutate only via setWeight
+     *   (the balancer is the sole writer of the derived alias table -- direct mutation is UB).
+     * @param seed deterministic PRNG seed (default 0x9e3779b9); reproducible benches.
+     */
+    constructor(capacity: number, eligible: Uint8Array, weights: Uint32Array, seed?: number);
+    /** Cold path: reconfigure endpoint `i`'s weight (uint32) and rebuild the alias table. */
+    setWeight(i: number, w: number): void;
+    /** Cold path: rebuild the alias table from the current caller weights (e.g. after a membership change). */
+    rebuild(): void;
+    /** Pick an endpoint index proportional to weight (eligibility by rejection sampling), or `PICK_NONE`. O(1). */
+    pick(): number;
 }