@zakkster/lite-pick 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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).
@@ -105,6 +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,8 +1,8 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M2 (0.2.0): substrate seams + RoundRobin + SmoothWRR (weighted). The remaining
- * strategy classes (P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad,
+ * 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.
  */
 
@@ -87,3 +87,21 @@ export class SmoothWRRBalancer extends BalancerBase {
     /** 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.
  *
- * M2 (0.2.0): substrate seams + RoundRobin + SmoothWRR (weighted). 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.
@@ -15,6 +15,8 @@
  *                    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
@@ -22,13 +24,13 @@
  * counters live OUTSIDE the kernel. The steady-state pick path allocates 0 B/op.
  *
  * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [M1], SmoothWRR [M2],
- *   P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom [planned].
+ *   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.2.0';
+export const VERSION = '0.3.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -298,3 +300,86 @@ export class SmoothWRRBalancer extends BalancerBase {
         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.2.0 ships two strategies -- `RoundRobinBalancer` and `SmoothWRRBalancer`** (the weighted default) -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- 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: M2 (v0.2.0).** Ships the substrate seams **plus `RoundRobinBalancer` and `SmoothWRRBalancer`**. 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** (max-run far below bursty weight-expansion WRR), and each scales as advertised (witness). See [ROADMAP.md](./ROADMAP.md) for the M2 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin (ADR 0003) and SmoothWRR (ADR 0004) design forks.
+> **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
@@ -76,6 +76,32 @@ 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
@@ -101,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.2.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,11 +14,12 @@ 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.2.0 ships the substrate seams + two strategies: RoundRobin and SmoothWRR (the weighted
-default). 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`, and `SmoothWRRBalancer`. The remaining strategies land one per session
-(see ROADMAP.md): P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
+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)
 
@@ -69,6 +70,15 @@ default). It exports `VERSION`, the fail-closed sentinel `PICK_NONE` (-1), a det
     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.2.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",