@zakkster/lite-pick 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,62 @@ 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.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,93 @@
+# 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, **0 B/op** steady-state, **fail-closed** (`PICK_NONE` = -1 when nothing is pickable, never a
+dead pick), reading a **shared read-only eligibility bitmap** it never writes.
+
+## 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. */
@@ -271,3 +271,34 @@ export class BoundedLoadBalancer extends ConsistentHashBalancer {
     /** 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;
 }
+
+/**
+ * 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;
+}

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.
@@ -47,6 +48,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 +66,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 +81,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.9.0';
+export const VERSION = '1.0.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -1118,3 +1132,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) {
+        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        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
+    }
+}

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.9.0 ships nine strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev lookup table), and the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads -- sticky routing + an occupancy cap that overflows a hot backend to its neighbours)** -- 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 -- WeightedRandom -- lands next 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. **v1.0.0 ships the complete ten-strategy roster -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev lookup table), the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads -- sticky routing + an occupancy cap that overflows a hot backend to its neighbours), and `WeightedRandomBalancer` (O(1) Vose alias-table sampling with rejection-sampling eligibility)** -- 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. Not sure which strategy? See **[GUIDE.md](./GUIDE.md)**.
 
 [![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: M9 (v0.9.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev table), and the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads)**, the **`@zakkster/lite-pick/pool`** request layer (with opt-in latency-feedback, occupancy-feedback, and keyed-routing hooks), 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%**, **PeakEWMA steers around a 10x-slow node** (it takes <= 25% of P2C's share for it and cuts service p99), **ConsistentHash remaps only ~1.6% of keys on a scale event** (vs ~98% for naive modulo), and **BoundedLoad tames a hotspot plain consistent hashing can't** (under a skewed key stream ConsistentHash spikes a hot backend to ~13x the mean occupancy while BoundedLoad's `(1+eps)` cap holds it near the mean by overflowing to neighbours -- keeping the same ~1.6% minimal disruption) -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M9 -> 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), PeakEWMA (0009), ConsistentHash (0010), and BoundedLoad/CHBL (0011) design forks.
+> **Status: M10 (v1.0.0) -- the roster-complete release.** Ships the substrate seams **plus all ten strategies: `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev table), the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads), and `WeightedRandomBalancer` (O(1) Vose alias-table sampling with rejection-sampling eligibility)**, the **`@zakkster/lite-pick/pool`** request layer (with opt-in latency-feedback, occupancy-feedback, and keyed-routing hooks), 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) -- and the **[GUIDE.md](./GUIDE.md)** strategy-selection capstone. 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%**, **PeakEWMA steers around a 10x-slow node** (it takes <= 25% of P2C's share for it and cuts service p99), **ConsistentHash remaps only ~1.6% of keys on a scale event** (vs ~98% for naive modulo), **BoundedLoad tames a hotspot plain consistent hashing can't** (under a skewed key stream ConsistentHash spikes a hot backend to ~13x the mean occupancy while BoundedLoad's `(1+eps)` cap holds it near the mean by overflowing to neighbours), and **WeightedRandom holds every node's share within 2% of its weight** while its O(1) alias sample beats an O(n) cumsum foil by >=3x ops/ms at n=4096 -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. Roster complete **for now, not closed** (AZ-aware routing, hedging, subsetting are post-1.0). See [ROADMAP.md](./ROADMAP.md), 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), PeakEWMA (0009), ConsistentHash (0010), BoundedLoad/CHBL (0011), and WeightedRandom (0012) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -238,6 +238,38 @@ The proof (from `test/balance.mjs`, a Zipfian-skewed key stream over 64 backends
 
 BoundedLoad caps the hot backend near `(1 + eps) x mean` while plain consistent hashing lets it run away, and both reroute only **~1.6%** of keys on a scale event (`test/balance.mjs`). See [`ConsistentHashBalancer`](#consistenthash--sticky--cache-affinity-routing-v080) above for the integer-key contract and the FNV-1a helper.
 
+## WeightedRandom -- O(1) alias-table weighted selection (v1.0.0)
+
+The weighted strategy for **very large pools**. Where `SmoothWRRBalancer` is deterministic and smooth but scans O(cap) per pick and owns per-endpoint accumulator state, `WeightedRandomBalancer` is a **stateless O(1) sample**: one draw from a precomputed **Vose/Walker alias table** (one column draw + one probability compare) returns an endpoint proportional to its weight. It converges to the weight ratios by the law of large numbers -- trading SmoothWRR's low-variance smoothness for sampling variance.
+
+```js
+import { WeightedRandomBalancer, PICK_NONE } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const weights = Uint32Array.from([1, 2, 3, 10]);   // YOU own this; endpoint 3 gets ~10/16 of traffic
+const wr = new WeightedRandomBalancer(4, eligible, weights);
+
+wr.pick();            // -> a weighted-random eligible index (mostly 3, sometimes 0/1/2)
+
+// Reweight is COLD (rebuilds the alias table); the balancer is the sole writer of its table.
+wr.setWeight(3, 1);   // now roughly uniform
+wr.setEligible(1, false); // an eligibility flap is FREE -- it never rebuilds the table (anti-flap)
+wr.pick();            // never returns endpoint 1 (down) or a weight-0 node
+
+// Whole pool down, or every eligible node weight 0 -> fail closed.
+for (let i = 0; i < 4; i++) wr.setEligible(i, false);
+wr.pick() === PICK_NONE; // -> true
+```
+
+- **O(1), 0 B/op, never throws.** One alias-column draw + one compare. The table is built **cold** in the constructor (and on `setWeight` / `rebuild`) with the standard Vose small/large worklist -- reusing scratch buffers, so a rebuild allocates nothing and `pick()` allocates nothing.
+- **Eligibility by rejection sampling** (the same discipline as P2C, [ADR 0005](./decisions/0005-p2c-draw.md)): the table is built over the **eligible-independent** weights, so a **weight-0 node is never a column** (never returned). If a drawn candidate is ineligible, `pick()` redraws up to a bounded 64, then falls back to a 0-B/op rotated linear eligible scan. Because every candidate is a positive-weight node, rejecting the ineligible ones **renormalizes** the weight distribution over the surviving eligible mass -- each eligible node's share converges to `weight[i] / sum(eligible weights)`.
+- **Sole writer of its table.** `weights` is your `Uint32Array` (the SmoothWRR/SED seam); the balancer owns the derived alias table and is its only writer via cold `setWeight` / `rebuild`. Mutate `weights` directly and the table desyncs (UB). An eligibility flap **never** rebuilds. `PICK_NONE` only when `live === 0` or no eligible node has a positive weight.
+- **Not `@zakkster/lite-random`.** That is a *game RNG* (loot tables, particles) whose `weighted(items, weights)` returns an **item** one-shot and is not eligibility-aware. WeightedRandom returns an endpoint **index**, honours the shared eligibility bitmap, and owns a persistent table -- different domain (see [GUIDE.md](./GUIDE.md) / [ADR 0012](./decisions/0012-weightedrandom.md)).
+
+The proof (from `test/balance.mjs`, n=64, skewed weights 1..16, 8e6 seeded draws): every node's observed share is within **2%** of `weight[i]/sum` (measured worst ~0.84%), a cumsum-linear O(n) foil matches the *same* fairness, and the O(1) alias sample beats that foil by **~107x ops/ms** at n=4096. Under half the pool down: **0 ineligible / 0 weight-0** returns and survivor shares within **3%** of the renormalized target.
+
+> **Which weighted strategy?** Small-to-medium pools or when smoothness matters -> **SmoothWRR**; very large pools where the O(cap) scan hurts -> **WeightedRandom**. Full decision tree in **[GUIDE.md](./GUIDE.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`.
@@ -250,9 +282,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 | 53009 | load-balancers@1.3.52 | 59485 |
-| RoundRobin | RoundRobinBalancer | 246432 | loadbalance@1.0.0 | 303459 |
-| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 163481 |
+| P2C (power-of-two-choices) | P2cBalancer | 57019 | load-balancers@1.3.52 | 59778 |
+| RoundRobin | RoundRobinBalancer | 229911 | loadbalance@1.0.0 | 261301 |
+| Weighted-random | WeightedRandomBalancer | 73673 | wrr@1.0.0 | 172137 |
 
 <!-- /bench:competitors -->
 
@@ -280,8 +312,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.2 |
+| allocating foil | 13 | allocates | 1.8 |
 
 <!-- /bench:gc -->
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.9.0
+Version: 1.0.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,19 +14,42 @@ 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.9.0 ships the substrate seams + nine 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), PeakEWMA (latency-aware P2C), ConsistentHash
-(a Maglev lookup table -- sticky/affinity routing), and BoundedLoad (Consistent Hashing with Bounded
-Loads -- sticky routing + a per-backend occupancy cap that overflows a hotspot to neighbours). It
-exports `VERSION`, the fail-closed
+1.0.0 -- the ROSTER-COMPLETE release -- ships the substrate seams + TEN 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), PeakEWMA (latency-aware P2C),
+ConsistentHash (a Maglev lookup table -- sticky/affinity routing), BoundedLoad (Consistent Hashing
+with Bounded Loads -- sticky routing + a per-backend occupancy cap that overflows a hotspot to
+neighbours), and WeightedRandom (O(1) Vose alias-table sampling with rejection-sampling eligibility).
+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`, `PeakEwmaBalancer`,
-`ConsistentHashBalancer`, `BoundedLoadBalancer`, and the ConsistentHash constants `CH_DEFAULT_M`
-(65537) / `CH_PROBE_LIMIT` (64). The remaining strategy lands next session (see ROADMAP.md):
-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.
+`ConsistentHashBalancer`, `BoundedLoadBalancer`, `WeightedRandomBalancer`, and the ConsistentHash
+constants `CH_DEFAULT_M` (65537) / `CH_PROBE_LIMIT` (64). Roster complete FOR NOW, not closed:
+AZ-aware routing, the lite-await hedging combinator, and subsetting are queued post-1.0 (ROADMAP.md).
+GUIDE.md is the "which of the ten strategies do I pick?" decision guide. 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.
+
+M10 (1.0.0) adds WeightedRandomBalancer (decisions/0012): 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). Fail-closed (PICK_NONE) IFF live === 0 OR no
+eligible node has a positive weight. O(1), 0 B/op, never throws. 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` (duck-typed drop-in for the build) and a lite-logn Fenwick tree (the DYNAMIC-weight
+complement -- O(log n) update + sample) are DEFERRED optional peers, imported by NOTHING. NOT
+@zakkster/lite-random: that is a GAME RNG (Mulberry32; loot tables, particles, gaussian) whose
+`weighted(items, weights)` returns an ITEM one-shot, is not eligibility-aware, and holds no reusable
+table -- lite-pick's WeightedRandom returns an endpoint INDEX, honours the shared eligibility bitmap
+(fail-closed), and owns a persistent alias table rebuilt only on reweight. Different domain + contract
+-- not a peer, not a substrate (GUIDE.md / ADR 0012).
 
 M9 (0.9.0) adds BoundedLoadBalancer (decisions/0011): Consistent Hashing with Bounded Loads (CHBL --
 Mirrokni et al. / Google Research; Vimeo eps=0.25). It is `ConsistentHashBalancer` (the Maglev table)
@@ -236,6 +259,35 @@ the contract + balance + tail -- never an "N times faster" headline (decisions/0
     the mean occupancy while CHBL caps it near (1+eps) x mean by overflow; both keep ~1/N minimal
     disruption. `Pool.run` mirrors dispatch/settle into `note` when the balancer duck-types it, and
     `Pool.run(fn, { key })` drives `pick(key)` for keyed CHBL routing (both inert otherwise).
+- `WeightedRandomBalancer extends BalancerBase` -- class. O(1) weighted-random via a Vose/Walker ALIAS
+  TABLE (M10, decisions/0012). The roster-completing strategy.
+  - `new WeightedRandomBalancer(capacity, eligible, weights, seed?=0x9e3779b9)` -- `weights` is the
+    CALLER's Uint32Array (length >= capacity, the SmoothWRR/SED seam); the balancer is the SOLE writer
+    of its DERIVED alias table (`_prob` Float64Array + `_alias` Int32Array) via cold setWeight/rebuild
+    (direct weight mutation desyncs the table -- UB). Validates typeof-first (RangeError) BEFORE
+    allocating the table. Builds the table COLD in the ctor (the standard small/large Vose worklist over
+    the eligible-INDEPENDENT weights, ~15 lines -- NOT a re-implementation of lite-o1's AliasTable). The
+    build reuses cold scratch worklists -- it allocates nothing per rebuild.
+  - `pick()` -> number. Draws one column (`prng.nextBelow(cap)`) + one probability compare against a
+    fresh `prng.next()` uniform -> a candidate (`col` or `_alias[col]`), which is ALWAYS a positive-
+    weight node (a weight-0 node is NEVER a column). REJECTION SAMPLING on eligibility: if the candidate
+    is ineligible, redraw up to a bounded 64, then fall back to a 0-B/op rotated linear scan from a
+    random start for the first eligible positive-weight node. Because a candidate is always positive-
+    weight, 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)). O(1),
+    0 B/op, NEVER throws. `PICK_NONE` IFF live === 0 OR no eligible node has a positive weight. NEVER a
+    dead pick, a weight-0 return, or an out-of-range index.
+  - `setWeight(i, w)` -> void. COLD. Set endpoint i's weight (uint32) and REBUILD the alias table (the
+    SmoothWRR sole-writer precedent). `rebuild()` -> void. COLD. Re-derive the table from the current
+    caller weights. An eligibility flap NEVER rebuilds (anti-flap; only setWeight/rebuild/membership).
+  - vs SmoothWRR: SmoothWRR is deterministic/smooth/low-variance but O(cap)/pick and owns accumulator
+    state; WeightedRandom is a STATELESS O(1) sample (no accumulator to desync) with sampling variance --
+    the fit for VERY LARGE pools where SmoothWRR's O(cap) scan hurts. vs @zakkster/lite-random: that is a
+    GAME RNG (Mulberry32; loot tables) returning an ITEM one-shot, not eligibility-aware, no reusable
+    table; WeightedRandom returns an endpoint INDEX, honours the shared eligibility bitmap (fail-closed),
+    and owns a persistent alias table -- different domain, NOT a peer (see GUIDE.md / ADR 0012). DEFERRED
+    optional-peer seams (import NOTHING; `peerDependencies` STAYS `{}`): a lite-o1 `AliasTable` duck-typed
+    drop-in for the Vose build, and a lite-logn Fenwick/BinaryIndexedTree for DYNAMIC weights.
 
 ## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
 
@@ -293,7 +345,10 @@ duck-typed and imports NOTHING from lite-query.
 
 @zakkster/lite-di-health (eligibility writer), lite-statechart (breaker), lite-o1
 (RandomSet / AliasTable / RingLog substrate), lite-logn (exact least-conn heap / Fenwick
-weights), lite-lru (sticky affinity), lite-fastbit32 (optional small-pool bitset peer),
+dynamic weights -- the mutable-weight complement to WeightedRandom's static alias table),
+lite-random (a SEPARATE domain -- a GAME RNG for loot tables / particles that returns an ITEM,
+NOT an eligibility-aware LB index selector; use lite-pick WeightedRandom for load balancing),
+lite-lru (sticky affinity), lite-fastbit32 (optional small-pool bitset peer),
 lite-query (the fetcher adapter), lite-await (hedging), lite-worker-pool (in-process
 consumer), lite-di-signal / lite-signal-decorators (observability). None is a HARD
 dependency -- each is an OPTIONAL PEER dep (peerDependenciesMeta.optional, the LiteQuery

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.9.0",
-  "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), ConsistentHash (Maglev sticky/affinity routing, minimal disruption), and BoundedLoad (consistent hashing with bounded loads -- sticky routing with a per-backend occupancy cap that overflows a hotspot to neighbours); the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
+  "version": "1.0.0",
+  "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 of ten strategies: RoundRobin, SmoothWRR, P2C, LeastConn, SED, NQ, PeakEWMA (latency-aware peak-EWMA), ConsistentHash (Maglev sticky/affinity routing, minimal disruption), BoundedLoad (consistent hashing with bounded loads -- sticky routing with a per-backend occupancy cap that overflows a hotspot to neighbours), and WeightedRandom (O(1) Vose alias-table sampling with rejection-sampling eligibility); the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher. See GUIDE.md to choose a strategy.",
   "type": "module",
   "main": "./Pick.js",
   "module": "./Pick.js",
@@ -29,6 +29,7 @@
     "llms.txt",
     "README.md",
     "RECIPES.md",
+    "GUIDE.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -79,6 +80,8 @@
     "maglev",
     "bounded-load",
     "weighted-random",
+    "alias-method",
+    "vose",
     "sticky-routing",
     "client-side-load-balancing",
     "in-process",