@zakkster/lite-pick 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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.4.0] - 2026-09-23
+
+M4: the exact LeastConn family (IPVS `lc` / `sed` / `nq` made zero-GC) + the seeded invariant
+fuzzer (ROADMAP.md M4).
+
+### Added
+
+- `LeastConnBalancer extends BalancerBase` -- EXACT fewest-in-flight (IPVS `lc`). A full O(cap)
+  scan of the caller-owned in-flight view returning the eligible node with the lowest count
+  (lowest index on a tie); the deterministic complement to P2C's O(1) approximation. In-flight
+  is read LIVE (no `setWeight`, no derived aggregate -- the caller may mutate it directly).
+  0 B/op. Fails closed (`PICK_NONE`) when the whole pool is down.
+- `SedBalancer extends BalancerBase` -- shortest-expected-delay (IPVS `sed`). Returns the
+  eligible, positive-weight node minimizing `(inflight + 1) / weight`. BOTH inflight and weights
+  are caller-owned, read live. A weight-0 eligible node is not a candidate; all-zero-weight fails
+  closed even with the pool up. O(cap), 0 B/op.
+- `NqBalancer extends BalancerBase` -- never-queue (IPVS `nq`). Returns the FIRST idle eligible
+  positive-weight node (in-flight 0) if one exists, else the SED minimum -- the worker-pool fit.
+  O(cap) worst case, O(1) when an early node is idle, 0 B/op.
+- **The invariant fuzzer** (`test/fuzz.mjs` + the reusable `test/invariants.mjs` checker): a
+  seeded, property-based state-machine attack asserting STATE-SYNCHRONISATION invariants after
+  EVERY op (strict mode) per strategy -- `live` and (SmoothWRR) `_totalEligibleWeight` stay EXACT
+  vs a manual recompute, owned Float64 accumulators stay finite, `PICK_NONE` holds IFF the
+  pickable mass is 0, and LeastConn/SED/NQ return the true optimum (NQ its idle-first rule). Prints
+  the seed on failure for byte-for-byte replay; CI runs a fixed seed + a random seed + a regression
+  corpus + a pathological corpus (max-weight 0xFFFFFFFF summed, all-zero-weight while live>0,
+  single-node). Retrofits M2 SmoothWRR. Wired into `npm run fuzz` and `npm run verify`.
+- `test/LeastConn.test.js` (10), `test/SED.test.js` (8), `test/NQ.test.js` (10) -- boundary +
+  behaviour suites (exact minimum, weight-0 exclusion, feedback-loop balance, idle-first fan-out,
+  never-a-down-index under 200k churned picks).
+- Balance anchors (`test/balance.mjs`): LeastConn is greedy-perfect (max-minus-min <= 1, tighter
+  than P2C's gap; peak <= P2C's on the same run); SED converges to load proportional-to-weight
+  (< 1% drift; weighted-imbalance far below a random foil); NQ fans the first n dispatches out to
+  n distinct idle workers.
+- Gates extended for all three: torture (retention + 0 B/op `pick()` phases 6-8), PerfGate
+  (three `zgcSuite` scenarios + three `mustFail` teeth-checks), witness (`linear` complexity ->
+  flat work-rate), benchmark matrix (LeastConn/SED/NQ subjects + a per-pick-allocating
+  `lc-array` foil).
+- `decisions/0006-leastconn-family.md` -- P2C-is-already-least-conn (no redundant alias), exact-
+  O(cap)-scan-first, caller-owned live-read counters (the documented asymmetry with SmoothWRR),
+  and the confirmed-but-deferred lite-logn `BinaryHeap` exact-O(log n) peer seam.
+
+### Changed
+
+- Version 0.3.0 -> 0.4.0 across `package.json`, `Pick.js` `VERSION`, and `llms.txt`.
+- Folded the invariant-fuzz testing methodology (RESEARCH s3, ROADMAP s3/s0) into an adopted,
+  shipped gate: vectors 2 (flap chaos) + 3 (zero-GC soak) were already covered; the net-new
+  seeded state-synchronisation fuzzer is now `test/fuzz.mjs`.
+
+## [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 +190,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,
+ * M4 (0.4.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
+ * (LeastConn/SED/NQ). The remaining strategy classes (PeakEWMA, ConsistentHash, BoundedLoad,
  * WeightedRandom) are added one per session.
  */
 
@@ -87,3 +87,76 @@ 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;
+}
+
+/**
+ * LeastConnBalancer -- EXACT fewest-in-flight (M4, IPVS `lc`). A full O(cap) scan of the
+ * caller-owned in-flight view returning the eligible node with the lowest count (lowest index
+ * on a tie) -- the deterministic complement to P2C's O(1) approximation. In-flight counts are
+ * caller-owned and read LIVE (no `setWeight`, no derived aggregate). 0 B/op. Fails closed
+ * (`PICK_NONE`) when the whole pool is down.
+ */
+export class LeastConnBalancer 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 live.
+     */
+    constructor(capacity: number, eligible: Uint8Array, inflight: Uint32Array);
+    /** The eligible node with the fewest in-flight requests, or `PICK_NONE`. O(cap). */
+    pick(): number;
+}
+
+/**
+ * SedBalancer -- shortest-expected-delay (M4, IPVS `sed`). Returns the eligible, positive-weight
+ * node minimizing `(inflight + 1) / weight`; converges to load proportional-to-weight. BOTH
+ * inflight and weights are caller-owned Uint32Arrays, read LIVE (no `setWeight`, no derived
+ * aggregate). A weight-0 eligible node is not a candidate. O(cap), 0 B/op. Fails closed
+ * (`PICK_NONE`) when no eligible node has a positive weight.
+ */
+export class SedBalancer 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 live.
+     * @param weights per-endpoint weights (length >= capacity), caller-owned, read live.
+     */
+    constructor(capacity: number, eligible: Uint8Array, inflight: Uint32Array, weights: Uint32Array);
+    /** The eligible node minimizing (inflight+1)/weight, or `PICK_NONE`. O(cap). */
+    pick(): number;
+}
+
+/**
+ * NqBalancer -- never-queue (M4, IPVS `nq`). Returns the first idle eligible positive-weight
+ * node (in-flight 0) if one exists, else the SED minimum -- the worker-pool fit. BOTH inflight
+ * and weights are caller-owned, read LIVE. O(cap) worst case, O(1) when an early node is idle,
+ * 0 B/op. Fails closed (`PICK_NONE`) when no eligible node has a positive weight.
+ */
+export class NqBalancer 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 live.
+     * @param weights per-endpoint weights (length >= capacity), caller-owned, read live.
+     */
+    constructor(capacity: number, eligible: Uint8Array, inflight: Uint32Array, weights: Uint32Array);
+    /** The first idle eligible node, else the SED minimum, or `PICK_NONE`. O(cap). */
+    pick(): number;
+}

package/Pick.js

@@ -1,7 +1,8 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * M2 (0.2.0): substrate seams + RoundRobin + SmoothWRR (weighted). This file ships:
+ * M4 (0.4.0): substrate seams + six strategies -- RoundRobin, SmoothWRR, P2C, and the
+ * exact LeastConn family (LeastConn, SED, NQ). 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 +16,16 @@
  *                    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    power-of-two-choices over caller-owned in-flight counts; the ln ln n
+ *                    balance ceiling, O(1)/pick, 0 B/op. This IS the O(1) least-connections
+ *                    APPROXIMATION ("P2C-least-conn") -- the LeastConn family below is exact.
+ *   - LeastConnBalancer   EXACT fewest-in-flight (IPVS `lc`): a full O(cap) scan of the
+ *                    caller-owned in-flight view, 0 B/op. The deterministic complement to
+ *                    P2C's O(1) approximation.
+ *   - SedBalancer    shortest-expected-delay (IPVS `sed`): minimizes (inflight+1)/weight --
+ *                    charges the NEW request's marginal cost. O(cap)/pick, 0 B/op.
+ *   - NqBalancer     never-queue (IPVS `nq`): an IDLE eligible endpoint immediately if one
+ *                    exists, else SED. The worker-pool fit. O(cap)/pick, 0 B/op.
  *
  * 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 +33,15 @@
  * 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 [M4], PeakEWMA, ConsistentHash, BoundedLoad, 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.
  *
  * 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.4.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -298,3 +311,261 @@ 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;
+    }
+}
+
+/**
+ * LeastConnBalancer -- EXACT fewest-in-flight (M4), IPVS `lc` made zero-GC.
+ *
+ * `pick()` scans the whole pool and returns the eligible endpoint with the lowest in-flight
+ * count -- the deterministic, exact complement to P2cBalancer's O(1) two-choice APPROXIMATION
+ * of the same objective. Where P2C trades a tiny balance gap for O(1), LeastConn pays O(cap)
+ * for the exact minimum: in a closed feedback loop (the caller increments inflight on dispatch
+ * and decrements on settle) it is the greedy-optimal assignment -- max-minus-min load stays
+ * within 1 (test/balance.mjs proves the perfect balance, tighter than P2C's ln ln n gap).
+ *
+ * Ownership (ADR 0001, ADR 0006): in-flight counts live in the CALLER's Uint32Array, read-only
+ * to `pick()`. LeastConn owns NO derived state beyond the base `_live` -- it reads inflight
+ * live each scan, so (unlike SmoothWRR's weights) the caller may mutate the inflight view
+ * directly between picks; that is the whole point of the shared-counter seam.
+ *
+ * Bound: O(cap) per pick (one scan). Steady-state pick(): integer compares + one index write,
+ * no object/closure/array created -- 0 B/op. Tie-break is the lowest index (deterministic);
+ * the feedback loop breaks a startup all-zero tie by raising the picked node's count. Fails
+ * closed (PICK_NONE) when the whole pool is down.
+ *
+ * NOTE: without a feedback loop (inflight never changes) LeastConn returns the same lowest-load
+ * index every call -- correct by contract (it IS the least-loaded), but the caller must feed
+ * load back for it to distribute. The M5 lite-query adapter provides that increment/decrement.
+ */
+export class LeastConnBalancer 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.
+     */
+    constructor(capacity, eligible, inflight) {
+        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;
+    }
+
+    /**
+     * The eligible endpoint with the fewest in-flight requests, or PICK_NONE (fail closed).
+     * O(cap), zero-alloc. Lowest index on a tie.
+     * @returns {number}
+     */
+    pick() {
+        if (this._live === 0) return PICK_NONE;   // whole pool down: fail closed
+        const cap = this._cap, el = this._eligible, inf = this._inflight;
+        let best = -1, bestLoad = 0;
+        for (let i = 0; i < cap; i++) {
+            if (el[i]) {
+                const c = inf[i];
+                if (best < 0 || c < bestLoad) { best = i; bestLoad = c; }
+            }
+        }
+        return best;                              // best >= 0 guaranteed while _live > 0
+    }
+}
+
+/**
+ * SedBalancer -- shortest-expected-delay (M4), IPVS `sed` made zero-GC.
+ *
+ * `pick()` returns the eligible endpoint that minimizes `(inflight + 1) / weight` -- the
+ * expected delay if the NEW request were placed there (the +1 charges the request itself).
+ * Higher-weight endpoints absorb proportionally more load; SED converges to inflight/weight
+ * equal across the pool (test/balance.mjs proves the weighted fairness). It is the weighted
+ * generalization of least-connections: with all weights equal, SED and LeastConn agree.
+ *
+ * Ownership (ADR 0001, ADR 0006): BOTH inflight AND weights are caller-owned Uint32Arrays,
+ * read-only to `pick()`. SED (like LeastConn, unlike SmoothWRR) owns NO derived weight
+ * aggregate -- it reads weights live each scan, so there is no `setWeight` and no total to
+ * desync: the caller may retune weights directly between picks. An eligible endpoint whose
+ * weight is 0 is NOT a candidate (its expected delay is infinite); if every eligible endpoint
+ * has weight 0, `pick()` fails closed.
+ *
+ * Bound: O(cap) per pick (one scan, one Float64 division per eligible node), 0 B/op. Lowest
+ * index on a tie. Fails closed (PICK_NONE) when no eligible endpoint has a positive weight.
+ */
+export class SedBalancer 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.
+     * @param {Uint32Array} weights  per-endpoint weights (length >= capacity), caller-owned; read live.
+     */
+    constructor(capacity, eligible, inflight, weights) {
+        super(capacity, eligible);
+        if (!(inflight instanceof Uint32Array) || inflight.length < capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= capacity');
+        }
+        if (!(weights instanceof Uint32Array) || weights.length < capacity) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._inflight = inflight;
+        this._weights = weights;
+    }
+
+    /**
+     * The eligible endpoint minimizing (inflight + 1) / weight, or PICK_NONE (fail closed).
+     * O(cap), zero-alloc. Lowest index on a tie; weight-0 nodes are not candidates.
+     * @returns {number}
+     */
+    pick() {
+        if (this._live === 0) return PICK_NONE;   // whole pool down: fail closed
+        const cap = this._cap, el = this._eligible, inf = this._inflight, wt = this._weights;
+        let best = -1, bestScore = Infinity;
+        for (let i = 0; i < cap; i++) {
+            if (el[i]) {
+                const w = wt[i];
+                if (w > 0) {
+                    const score = (inf[i] + 1) / w;
+                    if (score < bestScore) { bestScore = score; best = i; }
+                }
+            }
+        }
+        return best;                              // -1 when every eligible node has weight 0
+    }
+}
+
+/**
+ * NqBalancer -- never-queue (M4), IPVS `nq` made zero-GC.
+ *
+ * `pick()` returns an IDLE eligible endpoint (in-flight 0, positive weight) the instant one
+ * exists -- never leaving a free server idle while queueing elsewhere -- and otherwise falls
+ * back to SED (`(inflight + 1) / weight`). This is the best fit for the in-process worker-pool
+ * case: spin up idle capacity first, only weigh expected delay once everyone is busy.
+ *
+ * Ownership (ADR 0001, ADR 0006): identical to SED -- caller-owned inflight + weights, read
+ * live, no derived aggregate. The first idle eligible node (lowest index, in-flight 0, weight
+ * > 0) short-circuits the scan.
+ *
+ * Bound: O(cap) worst case (no idle node -> a full SED scan); O(1) when a low-index endpoint is
+ * idle. 0 B/op. Fails closed (PICK_NONE) when no eligible endpoint has a positive weight.
+ */
+export class NqBalancer 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.
+     * @param {Uint32Array} weights  per-endpoint weights (length >= capacity), caller-owned; read live.
+     */
+    constructor(capacity, eligible, inflight, weights) {
+        super(capacity, eligible);
+        if (!(inflight instanceof Uint32Array) || inflight.length < capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= capacity');
+        }
+        if (!(weights instanceof Uint32Array) || weights.length < capacity) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._inflight = inflight;
+        this._weights = weights;
+    }
+
+    /**
+     * The first idle eligible endpoint (in-flight 0, weight > 0), else the SED minimum, else
+     * PICK_NONE (fail closed). O(cap) worst case, O(1) when an early node is idle. Zero-alloc.
+     * @returns {number}
+     */
+    pick() {
+        if (this._live === 0) return PICK_NONE;   // whole pool down: fail closed
+        const cap = this._cap, el = this._eligible, inf = this._inflight, wt = this._weights;
+        let best = -1, bestScore = Infinity;
+        for (let i = 0; i < cap; i++) {
+            if (el[i]) {
+                const w = wt[i];
+                if (w > 0) {
+                    if (inf[i] === 0) return i;   // idle: never queue -- take it immediately
+                    const score = (inf[i] + 1) / w;
+                    if (score < bestScore) { bestScore = score; best = i; }
+                }
+            }
+        }
+        return best;                              // -1 when every eligible node has weight 0
+    }
+}

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.4.0 ships six strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family** -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- 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: M4 (v0.4.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**. 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), and **SED tracks weight within 1%**. New in M4: a **seeded invariant fuzzer** (`test/fuzz.mjs`) that asserts each strategy's state-synchronisation invariants after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M4 -> 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), P2C (0005), and LeastConn-family (0006) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -76,6 +76,69 @@ 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)).
+
+## LeastConn / SED / NQ -- the exact load-aware family (v0.4.0)
+
+P2C above is the **O(1) approximation** of least-connections. When you want the **exact** least-loaded endpoint -- and the weighted (SED) and worker-pool (NQ) variants -- M4 ships the IPVS `lc` / `sed` / `nq` cohort, made zero-GC. All three read your caller-owned `inflight` (and, for SED/NQ, `weights`) **live** -- no `setWeight`, no derived total, so you mutate the counters directly in your feedback loop ([ADR 0006](./decisions/0006-leastconn-family.md)).
+
+```js
+import { LeastConnBalancer, SedBalancer, NqBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);            // YOU own this; increment on dispatch, decrement on settle
+
+// LeastConn: the EXACT fewest-in-flight endpoint (O(cap) scan). In a feedback loop it is
+// greedy-optimal -- load spreads within 1 of the mean (tighter than P2C's ln ln n gap).
+const lc = new LeastConnBalancer(4, eligible, inflight);
+const a = lc.pick(); inflight[a]++;
+
+// SED (shortest-expected-delay): minimizes (inflight + 1) / weight -- higher weight absorbs
+// proportionally more load. A weight-0 eligible node is never a candidate.
+const weights = Uint32Array.from([1, 2, 3, 4]);
+const sed = new SedBalancer(4, eligible, inflight, weights);
+const b = sed.pick(); inflight[b]++;
+
+// NQ (never-queue): jump to an IDLE endpoint (in-flight 0) the instant one exists, else SED.
+// The best fit for a worker pool -- fill free workers before queueing anywhere.
+const nq = new NqBalancer(4, eligible, inflight, weights);
+const c = nq.pick(); inflight[c]++;
+```
+
+The proof (from `test/balance.mjs`):
+
+| strategy | claim | measured |
+|---|---|---|
+| **LeastConn** | exact greedy balance | **max-minus-min load <= 1** (peak/avg 1.00), tighter than P2C; peak <= P2C's on the same run |
+| **SED** | load proportional to weight | **< 1% share drift** from each node's weight fraction; weighted-imbalance far below a random foil |
+| **NQ** | never queue while idle | first *n* dispatches hit **n distinct idle workers**, then falls back to SED |
+
+Each `pick()` is **0 B/op** and **O(cap)** (NQ is O(1) when an early node is idle). Because these are the state-heaviest strategies so far, M4 also introduces the **invariant fuzzer** (`npm run fuzz`): a seeded state-machine attack that, after *every* `pick` / `setEligible` / weight / load op, asserts the chosen endpoint is the *exact* optimum, `live` stays exact, and `PICK_NONE` holds *iff* nothing is pickable -- printing the seed on any failure for byte-for-byte replay.
+
 ## The substrate (under every strategy)
 
 ```js
@@ -101,27 +164,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.4.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`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`) 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)
 
@@ -152,6 +198,7 @@ npm run torture    # lite-leak retention + lite-gc-profiler 0 B/op (needs --expo
 npm run test:perf  # lite-perf-gate HARD zero-alloc gate + a mustFail teeth-check
 npm run witness    # pick throughput flatness across a pool-size sweep
 npm run balance    # peak-to-average vs the strategy ceiling + random foil (the anchor)
+npm run fuzz       # seeded invariant fuzzer: state-sync invariants after every op
 npm run verify     # all of the above
 ```
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.2.0
+Version: 0.4.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,11 +14,15 @@ 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.4.0 ships the substrate seams + six strategies: RoundRobin, SmoothWRR (the weighted
+default), P2C (power-of-two-choices -- also the O(1) least-connections APPROXIMATION), and the
+EXACT LeastConn family (LeastConn, SED, NQ). 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`, and `NqBalancer`. The remaining strategies land one per
+session (see ROADMAP.md): PeakEWMA, ConsistentHash, BoundedLoad, 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.
 
 ## Design ownership (decisions/0001, 0002)
 
@@ -69,6 +73,39 @@ 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. This IS the O(1) least-connections APPROXIMATION;
+    `LeastConnBalancer` below is the exact-O(cap) complement.
+- `LeastConnBalancer extends BalancerBase` -- class. EXACT fewest-in-flight (M4, IPVS `lc`).
+  - `new LeastConnBalancer(capacity, eligible, inflight)` -- `inflight` a caller-owned Uint32Array
+    (length >= capacity), read LIVE each pick. No `setWeight`, no derived aggregate: the caller may
+    mutate inflight directly between picks (that is the shared-counter seam).
+  - `pick()` -> number. Full O(cap) scan returning the eligible node with the fewest in-flight
+    requests (lowest index on a tie), or `PICK_NONE` when the whole pool is down. 0 B/op. In a
+    feedback loop (increment on dispatch, decrement on settle) it is greedy-optimal: max-minus-min
+    load stays within 1 (balance.mjs). Without feedback it returns the same lowest-load index --
+    correct by contract; the M5 lite-query adapter provides the increment/decrement.
+- `SedBalancer extends BalancerBase` -- class. Shortest-expected-delay (M4, IPVS `sed`).
+  - `new SedBalancer(capacity, eligible, inflight, weights)` -- `inflight` AND `weights` are
+    caller-owned Uint32Arrays (length >= capacity), read LIVE (no `setWeight`, no derived total --
+    the caller may retune weights directly, UNLIKE SmoothWRR).
+  - `pick()` -> number. O(cap) scan returning the eligible, positive-weight node minimizing
+    `(inflight + 1) / weight` (the new request's marginal expected delay), lowest index on a tie,
+    or `PICK_NONE` when no eligible node has a positive weight. A weight-0 eligible node is NOT a
+    candidate. Converges to load proportional-to-weight (balance.mjs). 0 B/op.
+- `NqBalancer extends BalancerBase` -- class. Never-queue (M4, IPVS `nq`); the worker-pool fit.
+  - `new NqBalancer(capacity, eligible, inflight, weights)` -- same caller-owned, read-live
+    inflight + weights contract as SED.
+  - `pick()` -> number. Returns the FIRST idle eligible positive-weight node (in-flight 0) if one
+    exists -- never queueing while a server is free -- else the SED minimum, else `PICK_NONE`.
+    O(cap) worst case, O(1) when an early node is idle. 0 B/op.
 
 ## Gates (every session)
 
@@ -78,6 +115,8 @@ default). It exports `VERSION`, the fail-closed sentinel `PICK_NONE` (-1), a det
   lite-perf-gate `zgcSuite` HARD zero-alloc gate + a `mustFail` teeth-check.
 - `npm run witness`   -- pick throughput flatness across a pool-size sweep.
 - `npm run balance`   -- peak-to-average load vs the strategy ceiling + random foil (the anchor).
+- `npm run fuzz`      -- the seeded invariant fuzzer (the state-machine attack): strict-mode
+  state-synchronisation invariants after every op, per strategy; prints the seed on failure.
 - `npm test` / `npm run test:types` -- node:test boundary suite + tsc type-surface check.
 
 ## Composes with

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.2.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.",
+  "version": "0.4.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, plus PeakEWMA and consistent hashing.",
   "type": "module",
   "main": "./Pick.js",
   "module": "./Pick.js",
@@ -29,10 +29,11 @@
     "torture": "node --expose-gc test/torture.mjs",
     "witness": "node test/witness.mjs",
     "balance": "node test/balance.mjs",
+    "fuzz": "node test/fuzz.mjs",
     "test:perf": "node --expose-gc --max-semi-space-size=4 --test test/perf/PerfGate.test.mjs",
     "bench": "node benchmark/Matrix.mjs",
     "bench:report": "node benchmark/Matrix.mjs && node benchmark/Report.mjs",
-    "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run balance && npm run test:perf"
+    "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run balance && npm run fuzz && npm run test:perf"
   },
   "keywords": [
     "load-balancer",