@zakkster/lite-pick 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to `@zakkster/lite-pick` are documented here. The format fol
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-23
+
+M3: P2C (power-of-two-choices), the headline strategy -- and the balance-quality anchor
+(ROADMAP.md M3).
+
+### Added
+
+- `P2cBalancer extends BalancerBase` -- power-of-two-choices. Draws two DISTINCT eligible
+  endpoints uniformly at random (rejection sampling over the shared bitmap -- no peer, no
+  owned draw-set) and returns the one with the lower in-flight load; ties to the first draw.
+  In-flight counts are the caller's `Uint32Array` (read-only to `pick()`). O(1) per pick,
+  0 B/op. Fails closed (`PICK_NONE`) when the whole pool is down. Owns only a seeded,
+  deterministic PRNG (reproducible benches).
+- The distinct second choice uses a BOUNDED redraw (up to 32 tries), not a single nudge, so
+  the two-choices property holds even at tiny pool sizes (~2^-32 collision chance), while
+  staying expected-O(1) and 0 B/op.
+- `test/P2C.test.js` -- 10 tests: n=2 always-lower-load, determinism by seed, fail-closed,
+  single-node, skips-down, a very-sparse-pool fallback path, a never-returns-a-down-index
+  proof under 200k churned picks, and an in-suite balance smoke.
+- **The balance anchor** (`test/balance.mjs`): the balls-into-bins experiment now proves the
+  `ln ln n / ln 2` ceiling -- at n=1024, k=32 balls/bin, P2C peak-to-mean gap ~2 vs a random
+  single-draw foil's ~21, and P2C's gap stays ~2-3 as n grows to 4096 while random's grows.
+- Gates extended for P2C: torture (retention + 0 B/op `pick()`), PerfGate (`zgcSuite` scenario
+  + a `mustFail` teeth-check), witness (`const` complexity -> flat throughput), benchmark
+  matrix (P2C subject + a random-draw foil).
+- `decisions/0005-p2c-draw.md` -- rejection sampling (no peer, RandomSet deferred), the
+  bounded-distinct-redraw enrichment, and caller-owned in-flight counters.
+
+### Changed
+
+- Version 0.2.0 -> 0.3.0 across `package.json`, `Pick.js` `VERSION`, and `llms.txt`.
+- Folded lite-o1 v1.11.0's new members into the substrate map (RESEARCH s6, ROADMAP):
+  `Reservoir` -> the Subsetting substrate (post-1.0 #4); `EliasFano` -> a viable ring-with-
+  vnodes option for M8 ConsistentHash; `RankSelect` noted as static-only (not for the
+  mutating eligibility bitmap).
+
+## [0.2.0] - 2026-09-23
+
+M2: SmoothWRR, the weighted default (ROADMAP.md M2).
+
+### Added
+
+- `SmoothWRRBalancer extends BalancerBase` -- nginx-style smooth weighted round-robin
+  (`current += weight; pick max; current -= total`). Distributes picks by caller-configured
+  integer weights, interleaved SMOOTHLY (weights [5,1,1] -> A,A,B,A,C,A,A), not in the
+  bursts of naive weight-expansion WRR. Owns its Float64Array smoothing accumulators; the
+  sole writer of the weights via the cold `setWeight(i, w)`. O(cap) per pick, 0 B/op. Fails
+  closed (`PICK_NONE`) when the eligible-weight sum is 0 (all down, or all eligible weights 0).
+- `setWeight(i, w)` (cold) -- reconfigure a weight, keeping the eligible-weight total exact.
+  `setEligible` is overridden to maintain the total and reset the toggled node's accumulator
+  (no stale credit across an eligibility epoch).
+- `test/SmoothWRR.test.js` -- 12 tests: the documented [5,1,1] sequence, exact fairness over
+  k cycles, smoothness (max-run strictly below the bursty foil), skips-down / redistribution,
+  fail-closed (all down AND all-zero-weight), setWeight/setEligible invariants + accumulator
+  reset, uint32 validation, and a never-returns-a-down-index proof under 200k churned picks.
+- Gates extended for SmoothWRR: torture (retention + 0 B/op `pick()`), PerfGate (`zgcSuite`
+  scenario at a realistic 256-endpoint pool -- SmoothWRR is O(cap) -- with a `grows` counter
+  over all three backing arrays, plus a `mustFail` teeth-check), witness (a per-strategy
+  complexity flag: `linear` asserts flat WORK RATE `ops/ms * n`), balance (exact weighted
+  fairness + max-run < bursty foil).
+- `benchmark/Matrix.mjs` -- SmoothWRR subject + the naive expand-WRR bursty foil.
+- `decisions/0004-smoothwrr-weight-ownership.md` -- weight ownership (cold setWeight),
+  Float64 accumulators, and the epoch-reset-on-eligibility-transition enrichment.
+
+### Changed
+
+- Version 0.1.0 -> 0.2.0 across `package.json`, `Pick.js` `VERSION`, and `llms.txt`.
+- Corrected the SmoothWRR complexity: O(cap) per pick, not "O(1) amortized" (ROADMAP).
+
 ## [0.1.0] - 2026-09-23
 
 M1: the first strategy, RoundRobin (ROADMAP.md M1). The M0 harness stubs become real,
@@ -72,5 +141,7 @@ ownership boundary in place before any `pick()` is written.
 - Next: **M1 RoundRobin** (0.1.0) -- the first strategy, landing the throughput witness
   and the balance gate.
 
+[0.3.0]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.3.0
+[0.2.0]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.2.0
 [0.1.0]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.1.0
 [0.0.1]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.0.1

package/Pick.d.ts

@@ -1,9 +1,9 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M1 (0.1.0): the substrate seams + the first strategy, RoundRobin. The remaining
- * strategy classes (SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash,
- * BoundedLoad, WeightedRandom) are added one per session.
+ * M3 (0.3.0): substrate seams + RoundRobin + SmoothWRR + P2C (the headline). The
+ * remaining strategy classes (LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad,
+ * WeightedRandom) are added one per session.
  */
 
 /** The single source-of-truth version stamp. */
@@ -68,3 +68,40 @@ export class RoundRobinBalancer extends BalancerBase {
     /** Next eligible index in round-robin order, or `PICK_NONE` when the pool is down. */
     pick(): number;
 }
+
+/**
+ * SmoothWRRBalancer -- nginx-style smooth weighted round-robin (M2). Distributes picks by
+ * caller-configured integer weights, interleaved smoothly (weights [5,1,1] -> A,A,B,A,C,A,A).
+ * Owns its smoothing accumulators; the sole writer of the weights via `setWeight`. O(cap)
+ * per pick, 0 B/op. Fails closed (`PICK_NONE`) when the eligible-weight sum is 0.
+ */
+export class SmoothWRRBalancer extends BalancerBase {
+    /**
+     * @param capacity endpoint count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param weights per-endpoint weights (length >= capacity); mutate only via setWeight.
+     */
+    constructor(capacity: number, eligible: Uint8Array, weights: Uint32Array);
+    /** Cold path: reconfigure endpoint `i`'s weight, keeping the eligible-weight total exact. */
+    setWeight(i: number, w: number): void;
+    /** Next endpoint by smooth weighting, or `PICK_NONE` when the eligible-weight sum is 0. */
+    pick(): number;
+}
+
+/**
+ * P2cBalancer -- power-of-two-choices (M3), the headline strategy. Draws two distinct
+ * eligible endpoints at random and returns the one with the lower in-flight load; the
+ * `ln ln n / ln 2` peak-load ceiling. In-flight counts are the caller's Uint32Array
+ * (read-only to `pick()`). O(1) per pick, 0 B/op. Fails closed (`PICK_NONE`) when down.
+ */
+export class P2cBalancer extends BalancerBase {
+    /**
+     * @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-only.
+     * @param seed deterministic PRNG seed (default 0x9e3779b9); reproducible benches.
+     */
+    constructor(capacity: number, eligible: Uint8Array, inflight: Uint32Array, seed?: number);
+    /** Pick by power-of-two-choices (lower in-flight of two random eligibles), or `PICK_NONE`. */
+    pick(): number;
+}

package/Pick.js

@@ -1,7 +1,7 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * M1 (0.1.0): the substrate seams + the FIRST strategy, RoundRobin. This file ships:
+ * M3 (0.3.0): substrate seams + RoundRobin + SmoothWRR + P2C (the headline). 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.
@@ -13,21 +13,24 @@
  *                    It does NOT implement pick() -- strategies subclass it.
  *   - RoundRobinBalancer  the baseline strategy: a wrapping cursor that forward-scans
  *                    the eligibility view, skipping down nodes, O(1) amortized, 0 B/op.
+ *   - SmoothWRRBalancer   the weighted default: nginx smooth weighted round-robin over
+ *                    caller-configured integer weights, O(cap)/pick, 0 B/op.
+ *   - P2cBalancer    the headline: power-of-two-choices over caller-owned in-flight counts;
+ *                    the ln ln n balance ceiling, O(1)/pick, 0 B/op.
  *
  * 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
  * the caller write, and returns an integer index. Health, circuit state, and load
  * counters live OUTSIDE the kernel. The steady-state pick path allocates 0 B/op.
  *
- * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [shipped M1],
- *   SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad,
- *   WeightedRandom [planned].
+ * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [M1], SmoothWRR [M2],
+ *   P2C [M3], LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom [planned].
  *
  * Zero runtime dependencies. node:test only. ESM, single file, tree-shakeable.
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -202,3 +205,181 @@ export class RoundRobinBalancer extends BalancerBase {
         return PICK_NONE;
     }
 }
+
+/**
+ * SmoothWRRBalancer -- nginx-style smooth weighted round-robin (M2).
+ *
+ * Distributes picks by caller-configured integer weights, spreading them SMOOTHLY over
+ * time rather than in bursts: weights [5, 1, 1] yield A, A, B, A, C, A, A -- not the
+ * A A A A A B C clumping of naive weight-expansion WRR. Each pick adds every eligible
+ * node's weight to its accumulator, takes the node with the highest accumulator, and
+ * subtracts the total eligible weight from it (the nginx `current += weight; pick max;
+ * current -= total` algorithm).
+ *
+ * Ownership (ADR 0001, ADR 0004): this is the first strategy that owns ALGORITHM state --
+ * the per-endpoint smoothing accumulators (`_current`, a Float64Array; Float64 absorbs the
+ * sum of uint32 weights without overflow and is 0 B/op on the hot path). Weights live in
+ * the caller's Uint32Array, but the balancer is the SOLE writer via the cold `setWeight()`,
+ * which keeps `_totalEligibleWeight` exact; mutating the weights array directly desyncs the
+ * total (documented UB). An eligibility toggle maintains the total AND resets the toggled
+ * node's accumulator (ADR 0004: no stale credit across an eligibility epoch -- anti-flap
+ * aligned, ADR 0002).
+ *
+ * Bound: O(cap) per pick (one scan of the pool -- SmoothWRR is inherently linear in the
+ * pool size, negligible at real endpoint counts), zero-alloc. Fails closed (PICK_NONE)
+ * when the eligible-weight sum is 0 -- whole pool down, or every eligible node's weight 0.
+ */
+export class SmoothWRRBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param {Uint32Array} weights  per-endpoint weights (length >= capacity); the balancer
+     *   is the sole writer via setWeight() -- direct mutation desyncs the total (UB).
+     */
+    constructor(capacity, eligible, weights) {
+        super(capacity, eligible);
+        if (!(weights instanceof Uint32Array) || weights.length < capacity) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._weights = weights;
+        this._current = new Float64Array(capacity);
+        let total = 0;
+        for (let i = 0; i < capacity; i++) if (eligible[i]) total += weights[i];
+        this._totalEligibleWeight = total;
+    }
+
+    /**
+     * Cold path: mark endpoint i up/down, maintaining the eligible-weight total and
+     * RESETTING the toggled node's accumulator (no stale credit across an eligibility
+     * epoch, ADR 0004). Zero-alloc.
+     * @param {number} i
+     * @param {boolean} up
+     */
+    setEligible(i, up) {
+        const was = this.isEligible(i);
+        super.setEligible(i, up);           // validates range, flips the bit, updates _live
+        const now = this._eligible[i] !== 0;
+        if (was !== now) {
+            this._totalEligibleWeight += now ? this._weights[i] : -this._weights[i];
+            this._current[i] = 0;           // reset on every eligibility transition
+        }
+    }
+
+    /**
+     * Cold path: reconfigure endpoint i's weight, keeping the eligible-weight total exact.
+     * @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);
+        const old = this._weights[i];
+        if (nw === old) return;
+        this._weights[i] = nw;
+        if (this._eligible[i]) this._totalEligibleWeight += nw - old;
+    }
+
+    /**
+     * Next endpoint by smooth weighting, or PICK_NONE (fail closed). O(cap), zero-alloc.
+     * @returns {number}
+     */
+    pick() {
+        const total = this._totalEligibleWeight;
+        if (total <= 0) return PICK_NONE;   // whole pool down, or all eligible weights 0
+        const cap = this._cap, el = this._eligible, wt = this._weights, cur = this._current;
+        let best = -1, bestCur = -Infinity;
+        for (let i = 0; i < cap; i++) {
+            if (el[i]) {
+                const c = cur[i] + wt[i];
+                cur[i] = c;
+                if (c > bestCur) { bestCur = c; best = i; }
+            }
+        }
+        cur[best] -= total;                 // best >= 0 guaranteed while total > 0
+        return best;
+    }
+}
+
+/**
+ * P2cBalancer -- power-of-two-choices (M3), the headline strategy.
+ *
+ * `pick()` draws TWO distinct eligible endpoints uniformly at random and returns the one
+ * with the lower in-flight load. One extra probe over pure random buys an exponential drop
+ * in peak load: the max load stays within `ln ln n / ln 2 + O(1)` of the mean (Azar-Broder-
+ * Karlin-Upfal 1994), versus random's `ln n / ln ln n` gap. That additive `ln ln n` ceiling
+ * -- proven in test/balance.mjs against a random foil -- is the library's analytical anchor.
+ *
+ * Ownership (ADR 0001, ADR 0005): in-flight counts live in the CALLER's Uint32Array, read-
+ * only to `pick()` (the caller / the M5 lite-query adapter increments on dispatch, decrements
+ * on settle -- lite-pick holds no request state). The eligible draw is REJECTION SAMPLING
+ * over the shared bitmap: no peer, no owned draw-set, expected O(1) draws when eligibility is
+ * dense (the common case), a bounded retry + a zero-alloc rotated linear-scan fallback for the
+ * degenerate sparse case. A true worst-case-O(1) draw via lite-o1 `RandomSet` is a deferred
+ * optional-peer optimization (ADR 0005), added only if sparse-eligibility measurement demands.
+ *
+ * Bound: O(d) = O(1) with d = 2 (two expected-O(1) draws + one compare). Steady-state pick():
+ * a few PRNG steps + array reads, no object/closure/array created -- proven 0 B/op by
+ * test/torture.mjs and test/perf/PerfGate.test.mjs. Fails closed (PICK_NONE) when the whole
+ * pool is down.
+ */
+export class P2cBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param {Uint32Array} inflight  per-endpoint in-flight counts (length >= capacity),
+     *   caller-owned and only READ here.
+     * @param {number} [seed=0x9e3779b9]  deterministic PRNG seed (reproducible benches).
+     */
+    constructor(capacity, eligible, inflight, seed = 0x9e3779b9) {
+        super(capacity, eligible);
+        if (!(inflight instanceof Uint32Array) || inflight.length < capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= capacity');
+        }
+        this._inflight = inflight;
+        this._rng = new Prng(seed);
+    }
+
+    /**
+     * A uniformly random ELIGIBLE index, or PICK_NONE if none. Expected O(1) (rejection
+     * sampling); a rotated linear scan from a random start is the zero-alloc fallback under
+     * degenerate sparsity (unbiased first-eligible-after-a-random-offset). Internal.
+     * @returns {number}
+     */
+    _draw() {
+        if (this._live === 0) return PICK_NONE;
+        const cap = this._cap, el = this._eligible;
+        for (let tries = 0; tries < 64; tries++) {
+            const i = this._rng.nextBelow(cap);
+            if (el[i]) return i;
+        }
+        // Degenerate (very sparse eligibility): scan from a random start, wrapping, and
+        // return the first eligible found. Zero-alloc; live > 0 guarantees a hit.
+        let i = this._rng.nextBelow(cap);
+        for (let k = 0; k < cap; k++) {
+            if (el[i]) return i;
+            i++;
+            if (i >= cap) i = 0;
+        }
+        return PICK_NONE;
+    }
+
+    /**
+     * Pick an endpoint by power-of-two-choices, or PICK_NONE (fail closed). O(1).
+     * @returns {number}
+     */
+    pick() {
+        const a = this._draw();
+        if (a < 0) return PICK_NONE;          // whole pool down: fail closed
+        if (this._live === 1) return a;       // only one eligible: it is both choices
+        // Draw a DISTINCT second choice. A bounded redraw (not a single nudge) keeps the
+        // two-choices property intact even at tiny pool sizes, where a single retry collides
+        // often: at live>=2 each redraw misses with probability <= 1/2, so 32 tries leaves a
+        // ~2^-32 collision chance -- while staying expected-O(1) (about two draws) and 0 B/op.
+        let b = this._draw();
+        for (let t = 0; b === a && t < 32; t++) b = this._draw();
+        if (b < 0 || b === a) return a;       // astronomically rare: fall back to the first draw
+        // Lower in-flight wins; ties go to the first draw (unbiased over many picks).
+        return this._inflight[b] < this._inflight[a] ? b : a;
+    }
+}

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.1.0 ships the first strategy, `RoundRobinBalancer`**, on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
+> Zero-GC load-balancing **selection kernel**: one hot `pick()` that returns an endpoint **index** over a fixed pool and allocates **0 B/op** on the steady-state path. A pure selector, never a proxy -- it consumes health and circuit state, it never owns them. **v0.3.0 ships three strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, and `P2cBalancer`** (power-of-two-choices, the headline) -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-pick.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-pick)
 [![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
@@ -21,7 +21,7 @@ The npm landscape has old algorithm libraries (`load-balancers`, `loadbalance`,
 - **Two pieces of evidence, both shipped.** A **0 B/op** witness on the pick path (no object, closure, string, or array created per pick), and a measured **balance-quality anchor** -- peak-to-average load within the strategy's theoretical ceiling (for P2C, the Azar-Broder-Karlin-Upfal `ln ln n / ln 2` bound) and strictly better than a random foil.
 - **A pure selector, not a proxy.** It **consumes** health and circuit state; it never owns them. Health is a shared read-only bitmap written by [`@zakkster/lite-di-health`](https://www.npmjs.com/package/@zakkster/lite-di-health); circuit state comes from [`@zakkster/lite-statechart`](https://www.npmjs.com/package/@zakkster/lite-statechart); load counters are caller-owned typed arrays. `pick()` only reads.
 
-> **Status: M1 (v0.1.0).** Ships the substrate seams **plus the first strategy, `RoundRobinBalancer`**. The M0 harness stubs are now real gates: `pick()` is proven **0 B/op** (torture + PerfGate), **perfectly fair** (balance: imbalance 1.0000, and zero dead picks vs the naive `i++ % n` foil), and **flat** across the pool sweep (witness). See [ROADMAP.md](./ROADMAP.md) for the M1 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin design fork (ADR 0003).
+> **Status: M3 (v0.3.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, and `P2cBalancer`**. 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**, and **P2C proves the `ln ln n` balance ceiling** -- peak-to-mean gap ~2 vs a random foil's ~21 at n=1024, holding flat as the pool grows. See [ROADMAP.md](./ROADMAP.md) for the M3 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin (0003), SmoothWRR (0004), and P2C (0005) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -54,6 +54,54 @@ rr.pick() === PICK_NONE; // -> true  (-1)
 
 Every `pick()` above allocates **0 bytes**, owns only an integer cursor, and reads the one shared eligibility view (no second copy to drift). Over a run it hands each *live* endpoint an equal share -- true round-robin over the eligible set, not the raw index space.
 
+## SmoothWRR (v0.2.0)
+
+The weighted default -- nginx's *smooth* weighted round-robin. Weighted picks are **interleaved evenly** instead of clumped, so a heavy endpoint doesn't get a burst of consecutive requests.
+
+```js
+import { SmoothWRRBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1]);
+const weights  = Uint32Array.from([5, 1, 1]); // A is 5x
+
+const wrr = new SmoothWRRBalancer(3, eligible, weights);
+
+const seq = Array.from({ length: 7 }, () => wrr.pick());
+// -> [0, 0, 1, 0, 2, 0, 0]   smooth: A A B A C A A  (not A A A A A B C)
+// over 7 picks: A=5, B=1, C=1 -- exactly the weights
+
+// Reweight on the cold path (the balancer stays the sole writer of the weights):
+wrr.setWeight(1, 4);  // B is now 4x
+```
+
+`pick()` is **0 B/op** and **O(cap)** (one scan of the pool -- negligible at real endpoint counts). It owns its smoothing accumulators; weights live in your `Uint32Array` but you mutate them only through `setWeight`, which keeps the internal eligible-weight total exact. Marking a node down/up resets its accumulator, so a recovered node rejoins neutral -- no stale burst or starvation ([ADR 0004](./decisions/0004-smoothwrr-weight-ownership.md)).
+
+## P2C -- power-of-two-choices (v0.3.0, the headline)
+
+Two random eligible draws, take the one with lower in-flight load. That single extra probe buys an **exponential** drop in peak load -- the max stays within an *additive* `ln ln n / ln 2` of the mean, versus random's `ln n / ln ln n` gap.
+
+```js
+import { P2cBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);           // YOU own this; pick() only reads it
+
+const p2c = new P2cBalancer(4, eligible, inflight);
+
+const i = p2c.pick();                           // the lower-loaded of two random eligibles
+inflight[i]++;                                  // you increment on dispatch...
+// ...and inflight[i]-- when the request settles (the M5 lite-query adapter will do this)
+```
+
+The proof (from `test/balance.mjs`, the library's analytical anchor):
+
+| pool `n` | P2C peak/avg | random foil peak/avg |
+|---|---|---|
+| 1024 | **1.06** (gap 2) | 1.66 (gap 21) |
+| 4096 | **1.06** (gap 2) | 1.78 (gap 25) |
+
+P2C's gap stays a small `ln ln n` constant while the random foil's grows with the pool. `pick()` is **0 B/op** and **O(1)** (two expected-O(1) rejection draws + a compare); in-flight counts are your caller-owned `Uint32Array` ([ADR 0005](./decisions/0005-p2c-draw.md)).
+
 ## The substrate (under every strategy)
 
 ```js
@@ -79,27 +127,10 @@ rng.nextBelow(4);     // -> a uint32 in [0, 4)
 rng.reset();          // replays the exact stream
 
 PICK_NONE;            // -> -1  (fail-closed sentinel: no endpoint, never a dead pick)
-VERSION;              // -> '0.1.0'
+VERSION;              // -> '0.3.0'
 ```
 
-`BalancerBase.pick()` is **abstract** -- it throws, so an unfinished strategy fails loudly rather than returning a dead index; `RoundRobinBalancer` (above) overrides it. Here is the shape the headline **P2C** strategy will take (M3), for orientation:
-
-```js
-// SHAPE ONLY -- not shipped until M3. Two random eligible draws, return the lower
-// in-flight load. One extra probe over random buys the ln ln n balance ceiling.
-class P2cBalancer extends BalancerBase {
-  constructor(capacity, eligible, inflight, seed) {
-    super(capacity, eligible);
-    this._inflight = inflight;  // caller-owned Uint32Array; pick() only reads it
-    this._rng = new Prng(seed);
-  }
-  pick() {
-    if (this.live === 0) return PICK_NONE;      // fail closed
-    const a = this._draw(), b = this._draw();   // two distinct eligible draws
-    return this._inflight[b] < this._inflight[a] ? b : a;
-  }
-}
-```
+`BalancerBase.pick()` is **abstract** -- it throws, so an unfinished strategy fails loudly rather than returning a dead index. Every shipped strategy (`RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`) extends it and reads the same shared eligibility view; you subclass it the same way to add your own.
 
 ## Design ownership (ratified before any strategy)
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.1.0
+Version: 0.3.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,10 +14,11 @@ 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.1.0 ships the substrate seams + the FIRST strategy, RoundRobin. 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), and `RoundRobinBalancer`. The
-remaining strategies land one per session (see ROADMAP.md): SmoothWRR, P2C, LeastConn/SED/NQ,
+0.3.0 ships the substrate seams + three strategies: RoundRobin, SmoothWRR (the weighted
+default), and P2C (power-of-two-choices, the headline). 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`, and
+`P2cBalancer`. The remaining strategies land one per session (see ROADMAP.md): LeastConn/SED/NQ,
 PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
 
 ## Design ownership (decisions/0001, 0002)
@@ -57,6 +58,27 @@ PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
     forward-scans the eligibility view, skipping down nodes), or `PICK_NONE` when the pool is
     down. O(1) amortized, O(cap) worst case under sparse eligibility, 0 B/op. Owns only its
     cursor; no eligible-set structure (ADR 0003 chose the stateless bitmap-scan path for M1).
+- `SmoothWRRBalancer extends BalancerBase` -- class. The weighted default (M2).
+  - `new SmoothWRRBalancer(capacity, eligible, weights)` -- `weights` is a Uint32Array
+    (length >= capacity); the balancer is the sole writer via setWeight (direct mutation
+    desyncs the total -- UB).
+  - `setWeight(i, w)` -> void. COLD. Reconfigure endpoint i's weight (uint32), keeping the
+    eligible-weight total exact.
+  - `setEligible(i, up)` -> void. COLD. Overrides the base to maintain the eligible-weight
+    total and reset the toggled node's accumulator (no stale credit across an epoch, ADR 0004).
+  - `pick()` -> number. Next endpoint by nginx smooth weighted round-robin (`current +=
+    weight; pick max; current -= total`), interleaved smoothly (weights [5,1,1] ->
+    A,A,B,A,C,A,A), or `PICK_NONE` when the eligible-weight sum is 0. O(cap) per pick, 0 B/op.
+    Owns its Float64Array smoothing accumulators (ADR 0004).
+- `P2cBalancer extends BalancerBase` -- class. The headline strategy (M3): power-of-two-choices.
+  - `new P2cBalancer(capacity, eligible, inflight, seed?=0x9e3779b9)` -- `inflight` is a
+    caller-owned Uint32Array (length >= capacity), read-only to pick(): the caller / the M5
+    lite-query adapter increments on dispatch, decrements on settle. `seed` seeds the internal
+    deterministic PRNG (reproducible benches).
+  - `pick()` -> number. Draws two DISTINCT eligible endpoints uniformly at random (rejection
+    sampling over the bitmap, no peer) and returns the one with the lower in-flight load; ties
+    to the first draw. The `ln ln n / ln 2` peak-load ceiling (ADR 0005). O(1) per pick, 0 B/op.
+    `PICK_NONE` when the whole pool is down.
 
 ## Gates (every session)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.1.0",
+  "version": "0.3.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, least-conn, PeakEWMA, consistent hashing.",
   "type": "module",
   "main": "./Pick.js",