@zakkster/lite-pick 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,95 @@ 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.5.0] - 2026-09-23
+
+M5: the ergonomic request layer at the `@zakkster/lite-pick/pool` subpath -- dispatch/settle
+in-flight counters + distinct-endpoint failover + a duck-typed query-cache fetcher (ROADMAP.md M5).
+
+### Added
+
+- `@zakkster/lite-pick/pool` (`Pool.js`) -- a new SUBPATH export (the kernel `Pick.js` stays a
+  single 0 B/op file; the async layer lives outside it, the lite-query `/stream` + `/await`
+  precedent, ADR 0007).
+- `Pool` -- wraps a balancer + the caller-owned in-flight view. `run(fn, opts?)` picks an endpoint,
+  increments in-flight on dispatch, awaits `fn(endpoint, signal)`, decrements on settle (in a
+  `finally` -- net-zero per run, even on throw). On a thrown error it keeps the failed endpoint's
+  count ELEVATED and re-picks, so a load-aware strategy (P2C/LeastConn/SED/NQ) steers the next
+  attempt to a DISTINCT endpoint -- up to `opts.tries` attempts (default 1 = no failover), then
+  rejects with the last error. Rejects a `code:'LITE_PICK_NONE'` error when no endpoint is eligible;
+  `opts.signal` is passed to `fn` and, once aborted after a failure, stops failover. NOT a 0 B/op
+  path (the kernel `pick()` is) -- a normal async wrapper, disclosed.
+- `liteQueryFetcher(pool, perEndpoint, opts?)` -- returns a `({ key, signal }) => Promise` fetcher
+  for a query cache (lite-query's `fetcher`, or any fetcher-shaped consumer). Imports NOTHING from
+  lite-query -- duck-typed, so `peerDependencies` stays empty. `opts.tries` is the spatial failover
+  count. BOUNDARY: Pool owns SPATIAL failover across the pool; the cache owns TEMPORAL retry/backoff.
+- `test/Pool.test.js` -- 12 tests: dispatch/settle in-flight balance (success AND throw), fail-closed
+  coding, distinct-endpoint failover, tries exhaustion (last error), abort-stops-failover, signal
+  passthrough, a 200-way CONCURRENT-consistency check (in-flight drains to all-zero -- no leak), and
+  the duck-typed fetcher.
+- `Pool.d.ts` + `test/types/pool.test-d.ts` -- the typed surface (the type-test tsconfig gains the
+  `DOM` lib for `AbortSignal`).
+- `demo/fanout.mjs` (`npm run demo`) -- the integration moat: least-connections fan-out over a flaky
+  pool with a replica killed mid-run, proving 0 dead picks + 0 leaked in-flight + live failover, and
+  showing the lite-query fetcher wiring. (`demo/` is not in `files[]`.)
+- `decisions/0007-pool-adapter.md` -- the /pool-subpath home, spatial-vs-temporal retry ownership,
+  the explicit 0 B/op boundary, and the duck-typed (zero-peer) fetcher.
+
+### Changed
+
+- Version 0.4.0 -> 0.5.0 across `package.json`, `Pick.js` `VERSION` (re-exported by `Pool.js`), and
+  `llms.txt`. `exports` gains `./pool`; `files[]` gains `Pool.js` + `Pool.d.ts`.
+- `peerDependencies` stays `{}` -- the fetcher adapter is duck-typed (ADR 0007 Fork 4).
+
+## [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

package/Pick.d.ts

@@ -1,8 +1,8 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M3 (0.3.0): substrate seams + RoundRobin + SmoothWRR + P2C (the headline). The
- * remaining strategy classes (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.
  */
 
@@ -105,3 +105,58 @@ export class P2cBalancer extends BalancerBase {
     /** 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.
  *
- * M3 (0.3.0): substrate seams + RoundRobin + SmoothWRR + P2C (the headline). 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,8 +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    the headline: power-of-two-choices over caller-owned in-flight counts;
- *                    the ln ln n balance ceiling, O(1)/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
@@ -24,13 +33,20 @@
  * 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 [M3], 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.
+ *
+ * M5 (0.5.0) adds the ergonomic request layer at the @zakkster/lite-pick/pool subpath (a
+ * SEPARATE file, Pool.js -- the async dispatch/settle counter wrapper + distinct-endpoint
+ * failover + a duck-typed query-cache fetcher). This kernel file stays PURE and 0 B/op; the
+ * async Pool lives outside it (decisions/0007, the lite-query /stream + /await subpath precedent).
  *
  * 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.3.0';
+export const VERSION = '0.5.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -383,3 +399,178 @@ export class P2cBalancer extends BalancerBase {
         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/Pool.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @zakkster/lite-pick/pool -- TypeScript declarations (M5).
+ *
+ * The async request layer over the 0 B/op kernel: dispatch/settle in-flight counter
+ * ergonomics + distinct-endpoint failover, plus a duck-typed query-cache fetcher adapter.
+ */
+
+/** The source-of-truth version stamp (re-exported from the core). */
+export const VERSION: string;
+
+/** The minimal balancer shape Pool drives (any lite-pick strategy satisfies it). */
+export interface Balancer {
+    pick(): number;
+    readonly capacity: number;
+    readonly live: number;
+}
+
+/** Options for `Pool.run`. */
+export interface RunOptions {
+    /** Passed to `fn`; when already aborted after a failure, stops failover (abort propagates). */
+    signal?: AbortSignal;
+    /** Max distinct-endpoint attempts (default 1 = no failover). */
+    tries?: number;
+}
+
+/**
+ * Pool -- wraps a balancer + the caller-owned in-flight view with dispatch/settle counter
+ * ergonomics and distinct-endpoint failover. `run` increments in-flight on dispatch, decrements
+ * on settle, and on a thrown error keeps the failed endpoint elevated so a load-aware strategy
+ * steers the next attempt elsewhere. NOT a 0 B/op path (the kernel `pick()` is).
+ */
+export class Pool {
+    /**
+     * @param balancer a lite-pick strategy (or duck-compatible) with `pick()`, `capacity`, `live`.
+     * @param inflight the SAME caller-owned in-flight view the balancer reads (length >= capacity).
+     */
+    constructor(balancer: Balancer, inflight: Uint32Array);
+    /** The wrapped balancer. */
+    readonly balancer: Balancer;
+    /** The shared in-flight view Pool increments on dispatch and decrements on settle. */
+    readonly inflight: Uint32Array;
+    /**
+     * Run `fn` against a chosen endpoint (in-flight incremented on dispatch, decremented on
+     * settle), with up to `opts.tries` distinct-endpoint failover attempts on a throw. Rejects
+     * with a `LITE_PICK_NONE`-coded error when no endpoint is eligible, or the last error when
+     * every attempt fails.
+     */
+    run<T>(fn: (endpoint: number, signal?: AbortSignal) => Promise<T> | T, opts?: RunOptions): Promise<T>;
+}
+
+/** Context passed to the per-endpoint fetcher. */
+export interface PerEndpointContext {
+    endpoint: number;
+    key: any;
+    signal?: AbortSignal;
+}
+
+/** Context a query cache passes to the produced fetcher (lite-query's fetcher shape). */
+export interface FetcherContext {
+    key: any;
+    signal?: AbortSignal;
+}
+
+/** Options for `liteQueryFetcher`. */
+export interface FetcherOptions {
+    /** Spatial failover attempts across the pool (default 1). */
+    tries?: number;
+}
+
+/**
+ * Adapt a Pool into a `({ key, signal }) => Promise` fetcher for a query cache (lite-query, or
+ * any fetcher-shaped consumer). Imports nothing from lite-query -- duck-typed, zero peers.
+ */
+export function liteQueryFetcher<T>(
+    pool: Pool,
+    perEndpoint: (ctx: PerEndpointContext) => Promise<T> | T,
+    opts?: FetcherOptions,
+): (ctx: FetcherContext) => Promise<T>;

package/Pool.js

@@ -0,0 +1,147 @@
+/**
+ * @zakkster/lite-pick/pool -- the ergonomic request wrapper (M5).
+ *
+ *     import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+ *
+ * The kernel (Pick.js) is a PURE, 0 B/op selector: pick() -> index. Real callers also need
+ * the counter ergonomics ADR 0001 always promised -- increment in-flight on DISPATCH,
+ * decrement on SETTLE, and on a failure re-pick a DIFFERENT endpoint. That layer is async
+ * (it wraps the request lifecycle), so it lives OUTSIDE the single-file 0 B/op kernel, in
+ * this separate subpath file (the lite-query precedent: /stream, /await are subpath entries).
+ *
+ * BOUNDARY (decisions/0007): Pool owns SPATIAL failover -- try up to `tries` DISTINCT endpoints,
+ * once each, on a thrown error. It does NOT own TEMPORAL retry (backoff, staleness) -- that
+ * belongs to the caller / a query cache (lite-query's `retry`). The two never double-own: Pool
+ * moves ACROSS the pool once; the caller retries the whole operation over TIME.
+ *
+ * ZERO-GC boundary: the kernel `pick()` is 0 B/op; `Pool.run` is a NORMAL async wrapper -- the
+ * request it wraps already allocates a promise -- adding only O(1) integer counter ops per
+ * attempt plus one small per-run bookkeeping array. It is NOT held to the kernel's 0 B/op bar.
+ *
+ * Duck-typed, zero HARD deps, zero peers: `liteQueryFetcher` returns a value shaped like
+ * lite-query's `fetcher` (`({ key, signal }) => Promise`) WITHOUT importing lite-query, so
+ * `peerDependencies` stays empty and the same helper serves any fetcher-shaped consumer.
+ */
+
+import { VERSION, PICK_NONE } from './Pick.js';
+
+/** Re-exported so a /pool-only importer can read the version without importing the core. */
+export { VERSION };
+
+/**
+ * Pool -- wraps a balancer + the caller-owned in-flight view with the dispatch/settle counter
+ * ergonomics and distinct-endpoint failover. The balancer is duck-typed (anything with
+ * `pick() -> number`, `capacity`, and `live`), so a Pool can drive any lite-pick strategy or a
+ * compatible custom one.
+ */
+export class Pool {
+    /**
+     * @param {{ pick(): number, capacity: number, live: number }} balancer  a lite-pick
+     *   strategy (RoundRobin / SmoothWRR / P2C / LeastConn / SED / NQ) or a duck-compatible one.
+     * @param {Uint32Array} inflight  the SAME caller-owned in-flight view the balancer reads
+     *   (length >= balancer.capacity). Pool is the increment/decrement authority around run().
+     */
+    constructor(balancer, inflight) {
+        if (!balancer || typeof balancer.pick !== 'function' ||
+            typeof balancer.capacity !== 'number' || typeof balancer.live !== 'number') {
+            throw new TypeError('[lite-pick] Pool needs a balancer with pick(), capacity, and live');
+        }
+        if (!(inflight instanceof Uint32Array) || inflight.length < balancer.capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= balancer.capacity');
+        }
+        this._b = balancer;
+        this._inflight = inflight;
+    }
+
+    /** The wrapped balancer. */
+    get balancer() {
+        return this._b;
+    }
+
+    /** The shared in-flight view Pool increments on dispatch and decrements on settle. */
+    get inflight() {
+        return this._inflight;
+    }
+
+    /**
+     * Run `fn` against a chosen endpoint, incrementing its in-flight on dispatch and decrementing
+     * on settle. On a thrown error, keep the failed endpoint's count ELEVATED and re-pick -- so a
+     * load-aware strategy (P2C / LeastConn / SED / NQ) naturally steers the next attempt to a
+     * DIFFERENT endpoint -- up to `tries` attempts, then throw the last error. All counts this run
+     * raised are released before returning or throwing (net-zero per run).
+     *
+     * @template T
+     * @param {(endpoint: number, signal?: AbortSignal) => (Promise<T>|T)} fn  the per-endpoint work.
+     * @param {{ signal?: AbortSignal, tries?: number }} [opts]  `tries` (default 1 = no failover)
+     *   is the max number of distinct-endpoint attempts; `signal` is passed to `fn` and, when
+     *   already aborted after a failure, stops failover (the abort propagates, no re-pick).
+     * @returns {Promise<T>}
+     */
+    async run(fn, opts) {
+        if (typeof fn !== 'function') throw new TypeError('[lite-pick] Pool.run needs a function');
+        const rawTries = opts && opts.tries != null ? (opts.tries | 0) : 1;
+        const tries = rawTries > 0 ? rawTries : 1;
+        const signal = opts ? opts.signal : undefined;
+        const inflight = this._inflight, b = this._b;
+        const held = [];                 // endpoints incremented this run (kept elevated across failover)
+        let lastErr;
+        try {
+            for (let attempt = 0; attempt < tries; attempt++) {
+                const i = b.pick();
+                if (i === PICK_NONE) {
+                    if (attempt === 0) {
+                        const e = new Error('[lite-pick] no eligible endpoint');
+                        e.code = 'LITE_PICK_NONE';
+                        throw e;
+                    }
+                    break;               // pool went fully down mid-failover: surface the last error
+                }
+                inflight[i] = (inflight[i] + 1) >>> 0;
+                held.push(i);
+                try {
+                    return await fn(i, signal);
+                } catch (err) {
+                    lastErr = err;
+                    if (signal && signal.aborted) throw err;   // abort: stop failover, propagate
+                }
+                // keep inflight[i] elevated so the next pick() steers to a different endpoint
+            }
+            throw lastErr;
+        } finally {
+            for (let k = 0; k < held.length; k++) {
+                const j = held[k];
+                inflight[j] = inflight[j] > 0 ? inflight[j] - 1 : 0;
+            }
+        }
+    }
+}
+
+/**
+ * liteQueryFetcher -- adapt a Pool into a fetcher for a query cache (lite-query's `fetcher`, or
+ * any `({ key, signal }) => Promise` consumer). Duck-typed: imports NOTHING from lite-query.
+ *
+ *     const fetcher = liteQueryFetcher(pool, ({ endpoint, key, signal }) =>
+ *         fetch(urls[endpoint] + '/' + key[0], { signal }).then(r => r.json()), { tries: 2 });
+ *     query(qc, { key: ['users'], fetcher });
+ *
+ * The query cache owns TEMPORAL retry/backoff/staleness; the Pool owns SPATIAL failover across
+ * the pool (`tries`). Wiring both is deliberate layering, never double-ownership (ADR 0007).
+ *
+ * @template T
+ * @param {Pool} pool
+ * @param {(ctx: { endpoint: number, key: any, signal?: AbortSignal }) => (Promise<T>|T)} perEndpoint
+ * @param {{ tries?: number }} [opts]  spatial failover attempts (default 1).
+ * @returns {(ctx: { key: any, signal?: AbortSignal }) => Promise<T>}
+ */
+export function liteQueryFetcher(pool, perEndpoint, opts) {
+    if (!(pool instanceof Pool)) throw new TypeError('[lite-pick] liteQueryFetcher needs a Pool');
+    if (typeof perEndpoint !== 'function') {
+        throw new TypeError('[lite-pick] liteQueryFetcher needs a per-endpoint function');
+    }
+    const tries = opts && opts.tries != null ? opts.tries : 1;
+    return function fetcher(ctx) {
+        const key = ctx ? ctx.key : undefined;
+        const signal = ctx ? ctx.signal : undefined;
+        return pool.run((endpoint, sig) => perEndpoint({ endpoint, key, signal: sig }), { signal, tries });
+    };
+}

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.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.
+> 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.5.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), plus a **`@zakkster/lite-pick/pool`** subpath: the async dispatch/settle counter layer with distinct-endpoint failover and a duck-typed query-cache fetcher. The rest of the roster -- 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: 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.
+> **Status: M5 (v0.5.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**, and the **`@zakkster/lite-pick/pool`** request layer. 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%** -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M5 -> 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), LeastConn-family (0006), and pool-adapter (0007) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -102,6 +102,43 @@ The proof (from `test/balance.mjs`, the library's analytical anchor):
 
 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
@@ -127,10 +164,41 @@ 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.3.0'
+VERSION;              // -> '0.4.0'
 ```
 
-`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.
+`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.
+
+## Wiring it up -- `@zakkster/lite-pick/pool` (v0.5.0)
+
+The kernel gives you `pick() -> index`. Real callers also need the counter ergonomics: **increment in-flight on dispatch, decrement on settle, and re-pick a *different* endpoint on failure.** That layer is async (it wraps the request), so it lives in a separate subpath -- `@zakkster/lite-pick/pool` -- and the kernel stays 0 B/op.
+
+```js
+import { LeastConnBalancer } from '@zakkster/lite-pick';
+import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);
+const balancer = new LeastConnBalancer(4, eligible, inflight);
+const pool = new Pool(balancer, inflight);      // Pool is the inc/dec authority around run()
+
+// run(): pick -> inflight++ -> await fn -> inflight-- (in a finally). tries=2 re-picks a
+// DIFFERENT endpoint if the first throws (a load-aware strategy steers off the failed node).
+const res = await pool.run((i, signal) => fetch(urls[i], { signal }), { tries: 2 });
+
+// Drop-in for a query cache (lite-query, or any `({ key, signal }) => Promise` fetcher).
+// Duck-typed -- imports NOTHING from lite-query, so peerDependencies stays empty.
+const fetcher = liteQueryFetcher(pool,
+  ({ endpoint, key, signal }) => fetch(urls[endpoint] + '/' + key[0], { signal }).then(r => r.json()),
+  { tries: 2 });
+// query(qc, { key: ['users'], fetcher });
+```
+
+**Two layers, no overlap** ([ADR 0007](./decisions/0007-pool-adapter.md)): the pool owns **spatial** failover (try a different endpoint *now*); your query cache owns **temporal** retry (backoff, staleness). `run()` is a normal async wrapper -- it adds O(1) counter ops per attempt, **it is not held to the kernel's 0 B/op bar** (that's `pick()`). See it end-to-end -- least-conn fan-out over a flaky pool with a node killed mid-run, proving 0 dead picks and 0 leaked in-flight:
+
+```bash
+npm run demo
+```
 
 ## Design ownership (ratified before any strategy)
 
@@ -161,6 +229,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.3.0
+Version: 0.5.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,12 +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.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.
+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)
 
@@ -78,7 +81,60 @@ PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
   - `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.
+    `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.
+
+## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
+
+The kernel is a PURE 0 B/op selector; `/pool` is the ASYNC layer over it -- dispatch/settle
+in-flight counter ergonomics + distinct-endpoint failover + a duck-typed query-cache fetcher.
+It is a SEPARATE subpath file (the lite-query /stream + /await precedent), NOT part of the
+0 B/op single-file kernel (decisions/0007). Zero HARD deps, zero peers: the fetcher adapter is
+duck-typed and imports NOTHING from lite-query.
+
+- `VERSION` -- string. Re-exported from the core (same three-place stamp).
+- `Pool` -- class. Wraps a balancer + the caller-owned in-flight view.
+  - `new Pool(balancer, inflight)` -- `balancer` is duck-typed (any `{ pick(): number, capacity,
+    live }` -- every lite-pick strategy qualifies); `inflight` is the SAME caller-owned Uint32Array
+    the balancer reads (length >= balancer.capacity). Throws on a bad balancer / undersized view.
+  - `balancer` / `inflight` -- readonly getters.
+  - `run(fn, opts?)` -> Promise. Picks an endpoint, increments its in-flight on DISPATCH, awaits
+    `fn(endpoint, signal)`, decrements on SETTLE (in a finally -- net-zero per run, even on throw).
+    On a thrown error it keeps the failed endpoint's count ELEVATED and re-picks, so a load-aware
+    strategy (P2C/LeastConn/SED/NQ) steers the next attempt to a DIFFERENT endpoint -- up to
+    `opts.tries` attempts (default 1 = no failover), then rejects with the LAST error. Rejects with
+    a `code:'LITE_PICK_NONE'` error when no endpoint is eligible. `opts.signal` is passed to `fn`;
+    once aborted after a failure, failover stops and the abort propagates. NOT a 0 B/op path (the
+    kernel `pick()` is): a normal async wrapper adding O(1) counter ops + one small per-run array.
+    BOUNDARY: Pool owns SPATIAL failover (across the pool); the caller / query cache owns TEMPORAL
+    retry (backoff, staleness). Never double-owned (decisions/0007).
+- `liteQueryFetcher(pool, perEndpoint, opts?)` -> a `({ key, signal }) => Promise` fetcher for a
+  query cache (lite-query's `fetcher`, or any fetcher-shaped consumer). `perEndpoint({ endpoint,
+  key, signal })` -> the per-endpoint work. `opts.tries` (default 1) is the spatial failover count.
+  Imports nothing from lite-query -- duck-typed, so `peerDependencies` stays empty.
 
 ## Gates (every session)
 
@@ -88,6 +144,8 @@ PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
   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.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.",
+  "version": "0.5.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; the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
   "type": "module",
   "main": "./Pick.js",
   "module": "./Pick.js",
@@ -13,11 +13,19 @@
       "node": "./Pick.js",
       "import": "./Pick.js",
       "default": "./Pick.js"
+    },
+    "./pool": {
+      "types": "./Pool.d.ts",
+      "node": "./Pool.js",
+      "import": "./Pool.js",
+      "default": "./Pool.js"
     }
   },
   "files": [
     "Pick.js",
     "Pick.d.ts",
+    "Pool.js",
+    "Pool.d.ts",
     "llms.txt",
     "README.md",
     "CHANGELOG.md",
@@ -29,10 +37,12 @@
     "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"
+    "demo": "node demo/fanout.mjs",
+    "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",