@zakkster/lite-pick 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.8.0] - 2026-09-23
+
+### Added
+
+- **`ConsistentHashBalancer` (M8)** -- sticky / cache-affinity routing via a prebuilt **Maglev
+  lookup table** (the in-kernel/production choice: Linux IPVS `mh`, Meta Katran, Cilium).
+  `pick(keyHash)` maps a caller-supplied **integer** key to a backend (`slot = keyHash % M`, a table
+  read, and a bounded forward-probe past down slots) -- **O(1)**, **0 B/op**. The key is coerced
+  `>>> 0` (NaN -> 0) and `pick` never throws (fail-closed). Per-pick *string* hashing is the one
+  zero-GC hazard, so callers hash string keys themselves (cold); `lite-pick` adds **no hashing
+  dependency**. The balancer owns the lookup `Uint32Array` (`M x 4` bytes -- ~256KB at the `65537`
+  default `M`, a disclosed **cold** one-time allocation; `M` is configurable down for small pools)
+  and an internal weights array; `setWeight(i, w)` / `rebuild()` rebuild the table cold, while a
+  **health flap never rebuilds** -- the bounded probe (<= 64 slots) absorbs it. Weighted Maglev
+  populate gives each backend a per-backend slot quota proportional to its weight (unweighted = equal).
+  Fails closed (`PICK_NONE`) when the pool is down or no eligible backend is reachable within the bound.
+  Exports `CH_DEFAULT_M` (65537) and `CH_PROBE_LIMIT` (64) alongside the class. ([ADR 0010](./decisions/0010-consistenthash.md)).
+- **Minimal-disruption anchor** -- removing 1 of 64 backends remaps only **~1.6%** of keys (`test/balance.mjs`,
+  `benchmark/Disruption.mjs`), versus the naive-modulo foil's **~98%**. `benchmark/Disruption.mjs`
+  replaces its M6 explicit ConsistentHash **SKIP** row with a real measured Maglev row (vs the modulo
+  foil and the `1/n` ideal); `benchmark/results.json` + the README fences regenerated (bench:verify green).
+- Gates extended for the new strategy: `test/ConsistentHash.test.js` boundary suite; `test/fuzz.mjs`
+  keyed subject + `checkConsistentHash` / `reachableWithinBound` invariants; `test/torture.mjs` retention
+  + a `pick(keyHash)` 0 B/op phase (build excluded, cold); `test/perf/PerfGate.test.mjs`
+  `consistentHashPick` scenario + a `mustFail` alloc tooth; `test/witness.mjs` O(1) const flat-work
+  subject; `benchmark/Matrix.mjs` subject; `Pick.d.ts` + `test/types/pick.test-d.ts` typed surface.
+
+### Changed
+
+- `Pick.js`: STRATEGY-APPEND only -- the other seven strategies are **byte-identical**; the sole
+  changes are the header roster/count (seven -> eight), the `VERSION` bump, and the appended
+  `ConsistentHashBalancer` (+ the `chMix32` / `chIsPrime` cold helpers and the `CH_*` constants).
+- `VERSION` bumped 0.7.2 -> **0.8.0** across the three sync sites (package.json, `Pick.js`, llms.txt);
+  package `description` + `keywords` (added `consistent-hash`, `sticky`) updated. `peerDependencies`
+  stays `{}` (the deferred `@zakkster/lite-filter` hot-key-oracle and `@zakkster/lite-o1` `EliasFano`
+  ring seams import nothing until a shipped path uses them).
+
+## [0.7.2] - 2026-09-23
+
+### Added
+
+- `RECIPES.md` -- a beginner-to-advanced usage guide that builds the selection kernel up into a
+  real load balancer (health/eligibility wiring, caller-owned in-flight counters, the
+  dispatch/settle loop, `/pool` failover, PeakEWMA rtt feedback, the FE profile, a strategy
+  decision table, suite composition, zero-GC discipline, and gotchas). Added to the published
+  package (`files[]`) and linked from the README.
+
+Docs-only release: no source or behavior change from 0.7.1 (the `VERSION` stamp is bumped for the
+three-place sync).
+
 ## [0.7.1] - 2026-09-23
 
 ### Fixed

package/Pick.d.ts

@@ -1,9 +1,9 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M7 (0.7.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
- * (LeastConn/SED/NQ) + PeakEWMA (latency-aware P2C). The remaining strategy classes
- * (ConsistentHash, BoundedLoad, WeightedRandom) are added one per session.
+ * M8 (0.8.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
+ * (LeastConn/SED/NQ) + PeakEWMA (latency-aware P2C) + ConsistentHash (Maglev table). The
+ * remaining strategy classes (BoundedLoad, WeightedRandom) are added one per session.
  */
 
 /** The single source-of-truth version stamp. */
@@ -187,3 +187,40 @@ export class PeakEwmaBalancer extends BalancerBase {
     /** Pick by latency-aware power-of-two-choices at time `now` (ns), or `PICK_NONE`. O(d)=O(1). */
     pick(now?: number): number;
 }
+
+/** The default Maglev lookup-table size (a prime, 2^16 + 1). Configurable via the ctor. */
+export const CH_DEFAULT_M: number;
+
+/** The bounded forward-probe limit ConsistentHash walks past down slots (fail-closed). */
+export const CH_PROBE_LIMIT: number;
+
+/**
+ * ConsistentHashBalancer -- sticky / cache-affinity routing via a prebuilt MAGLEV lookup table
+ * (M8, IPVS `mh` / Meta Katran / Cilium). `pick(keyHash)` maps a caller-supplied INTEGER key to a
+ * fixed backend (slot = keyHash % M, a table read, and a bounded forward-probe past down slots) --
+ * O(1), 0 B/op. The key is a caller-supplied integer (coerced `>>> 0`; NaN -> 0), never a per-pick
+ * string hash (the one zero-GC hazard -- hash string keys yourself, cold). The balancer OWNS the
+ * lookup table (M x 4 bytes; the 65537 default is ~256KB, a COLD one-time allocation) and an internal
+ * weights array; `setWeight` / `rebuild` rebuild the table (COLD). A health flap is absorbed by the
+ * probe -- never a rebuild -- so removing a backend (`setEligible(i, false)`) remaps only ~1/N keys.
+ * Fails closed (`PICK_NONE`) when the pool is down or no eligible backend is reachable within the bound.
+ */
+export class ConsistentHashBalancer extends BalancerBase {
+    /**
+     * @param capacity backend count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param weights optional per-backend weights (length >= capacity), COPIED at construction;
+     *   null = equal weight.
+     * @param m the Maglev table size: a prime, > 1, and >= capacity (default 65537).
+     * @param seed deterministic salt for the permutation mix (default 0x9e3779b9); reproducible.
+     */
+    constructor(capacity: number, eligible: Uint8Array, weights?: Uint32Array | null, m?: number, seed?: number);
+    /** The Maglev table size M (prime). */
+    readonly tableSize: number;
+    /** Cold path: reconfigure backend `i`'s weight (uint32) and rebuild the table. */
+    setWeight(i: number, w: number): void;
+    /** Cold path: rebuild the lookup table from the current owned weights. */
+    rebuild(): void;
+    /** Map an integer `keyHash` to a backend index (bounded probe past down slots), or `PICK_NONE`. */
+    pick(keyHash?: number): number;
+}

package/Pick.js

@@ -1,8 +1,9 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * M7 (0.7.0): substrate seams + seven strategies -- RoundRobin, SmoothWRR, P2C, the exact
- * LeastConn family (LeastConn, SED, NQ), and PeakEWMA (latency-aware P2C). This file ships:
+ * M8 (0.8.0): substrate seams + eight strategies -- RoundRobin, SmoothWRR, P2C, the exact
+ * LeastConn family (LeastConn, SED, NQ), PeakEWMA (latency-aware P2C), and ConsistentHash
+ * (a Maglev lookup table). 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.
@@ -31,6 +32,12 @@
  *                    Decay-on-READ (pick() never writes -> 0 B/op); the balancer OWNS the Float64
  *                    _ewma/_stamp state and is its SOLE writer via the warm recordRtt() feedback
  *                    path (also 0 B/op). Caller-supplied nanosecond clock. O(d)=O(1)/pick.
+ *   - ConsistentHashBalancer  sticky/affinity routing via a prebuilt Maglev lookup table (IPVS
+ *                    `mh`, Meta Katran, Cilium): pick(keyHash) is slot = keyHash % M, a table read,
+ *                    and a bounded forward-probe over down slots -- O(1)/pick, 0 B/op. keyHash is a
+ *                    caller-supplied INTEGER (no per-pick string hashing = the one zero-GC hazard);
+ *                    the balancer OWNS the Uint32Array table + weights, rebuilt COLD on membership /
+ *                    weight change (health flap is handled by the probe, never a rebuild).
  *
  * 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
@@ -38,9 +45,9 @@
  * 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 [M4], PeakEWMA [M7], 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.
+ *   P2C [M3], LeastConn/SED/NQ [M4], PeakEWMA [M7], ConsistentHash [M8], 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
@@ -51,7 +58,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.7.1';
+export const VERSION = '0.8.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -739,3 +746,233 @@ export class PeakEwmaBalancer extends BalancerBase {
         return costB < costA ? b : a;         // lower cost wins; tie -> the first draw
     }
 }
+
+/** The default Maglev lookup-table size: a prime (2^16 + 1). Configurable via the ctor. */
+export const CH_DEFAULT_M = 65537;
+
+/** The bounded forward-probe limit ConsistentHash walks past down slots (fail-closed). */
+export const CH_PROBE_LIMIT = 64;
+
+/**
+ * A deterministic 32-bit integer mix (an SplitMix/Murmur-style finalizer). Used COLD, once
+ * per backend at table build, to derive the two Maglev permutation parameters from a backend
+ * INDEX -- NO string hashing, NO new dependency, no allocation. Returns a uint32.
+ * @param {number} x
+ * @returns {number}
+ */
+function chMix32(x) {
+    x = x >>> 0;
+    x ^= x >>> 16; x = Math.imul(x, 0x7feb352d);
+    x ^= x >>> 15; x = Math.imul(x, 0x846ca68b);
+    x ^= x >>> 16;
+    return x >>> 0;
+}
+
+/** Cold primality test (trial division). M must be prime so a Maglev skip yields a full permutation. */
+function chIsPrime(n) {
+    if (!Number.isInteger(n) || n < 2) return false;
+    if (n % 2 === 0) return n === 2;
+    if (n % 3 === 0) return n === 3;
+    for (let d = 5; d * d <= n; d += 6) {
+        if (n % d === 0 || n % (d + 2) === 0) return false;
+    }
+    return true;
+}
+
+/**
+ * ConsistentHashBalancer -- sticky / cache-affinity routing via a prebuilt MAGLEV lookup table
+ * (M8), the in-kernel/production consistent-hash choice (Linux IPVS `mh`, Meta Katran, Cilium).
+ *
+ * `pick(keyHash)` maps a caller-supplied INTEGER key to a fixed backend: slot = keyHash % M, read
+ * the backend at `lookup[slot]`, and if it is down walk a BOUNDED forward-probe (<= 64 slots) to
+ * the next eligible backend. That is a few integer ops over a prebuilt Uint32Array table -- O(1)
+ * per pick, 0 B/op. The KEY MUST BE AN INTEGER (`keyHash >>> 0`, so NaN -> 0 deterministically):
+ * per-pick STRING hashing is the one zero-GC hazard, so the caller hashes string keys themselves
+ * (cold) and passes the integer -- lite-pick adds NO hashing dependency (RESEARCH section 5).
+ *
+ * MINIMAL DISRUPTION is the selling point: on a scale event only ~1/N of keys move. Removing a
+ * backend is just marking it down (`setEligible(i, false)`) -- the table is UNCHANGED, so every
+ * key NOT on that backend keeps its exact backend (0 remap) and only its keys probe forward.
+ * A membership or WEIGHT change rebuilds the table (COLD); a health flap NEVER does (the probe
+ * absorbs it). test/balance.mjs anchors this: remove 1 of 64 backends -> <= 3.13% keys remapped,
+ * vs the naive-modulo foil's >= 95%.
+ *
+ * Ownership (ADR 0001, ADR 0010): the balancer OWNS the lookup `Uint32Array` (M x 4 bytes; the
+ * 65537 default is ~256KB, a COLD one-time allocation -- disclosed, and M is configurable DOWN
+ * for small pools) AND an internal weights `Uint32Array` (the SmoothWRR sole-writer precedent):
+ * cold `setWeight(i, w)` / `rebuild()` rebuild the table from the current weights. Eligibility is
+ * the shared read-only bitmap from BalancerBase, read live by `pick()`; the base `setEligible`
+ * only flips a bit (no rebuild).
+ *
+ * Weighted Maglev populate: each backend b takes a per-backend slot QUOTA proportional to its
+ * weight (unweighted = equal quota, quotas summing to exactly M), stepping through its own
+ * permutation `permutation[j] = (offset + j*skip) % M` (offset = h1(b) % M, skip = h2(b) % (M-1) +
+ * 1, h1/h2 from a deterministic integer mix of the index -- no string hashing). Because the
+ * permutation covers ALL M slots, a backend with remaining quota can always reach an empty slot
+ * while one exists, so the O(M x N) COLD build never stalls. BUILD-COST GUARD (fail closed): the
+ * ctor requires `capacity <= M` (more members than slots would overfill M / starve backends) and
+ * M prime > 1.
+ *
+ * DEFERRED optional-peer seam (ADR 0010 / llms.txt, never on the pick path): a `@zakkster/lite-filter`
+ * hot-key / known-key oracle (BlockedBloom etc.) for warm-affinity + admission at the KEY-routing
+ * layer, and a `@zakkster/lite-o1` `EliasFano` ring alternative to the table. Import NOTHING;
+ * `peerDependencies` STAYS `{}` until a shipped code path imports it.
+ *
+ * Bound: O(1) per pick, 0 B/op (integer ops over the prebuilt table -- no allocation). Fails closed
+ * (PICK_NONE) when the whole pool is down OR no eligible backend is reachable within the probe bound
+ * (a near-total outage may return PICK_NONE even if a far eligible slot exists -- safe, never a dead
+ * pick, over-conservative only under mass outage; ADR 0010).
+ */
+export class ConsistentHashBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  backend count (fixed; add/remove is a cold rebuild).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param {Uint32Array|null} [weights=null]  optional per-backend weights (length >= capacity);
+     *   the values are COPIED into the balancer-owned weights at construction. null = equal weight.
+     * @param {number} [m=CH_DEFAULT_M]  the Maglev table size: a prime, > 1, and >= capacity.
+     * @param {number} [seed=0x9e3779b9]  deterministic salt for the permutation mix (reproducible).
+     */
+    constructor(capacity, eligible, weights = null, m = CH_DEFAULT_M, seed = 0x9e3779b9) {
+        super(capacity, eligible);
+        // Validate typeof-first, BEFORE allocating the table / owned weights (fail closed early).
+        if (typeof m !== 'number') {
+            throw new TypeError('[lite-pick] table size M must be a number');
+        }
+        if (!Number.isInteger(m) || m < 2 || !chIsPrime(m)) {
+            throw new RangeError('[lite-pick] table size M must be a prime integer > 1: ' + m);
+        }
+        if (capacity > m) {
+            throw new RangeError('[lite-pick] capacity ' + capacity +
+                ' exceeds table size M ' + m + ' (would overfill / starve backends)');
+        }
+        if (weights !== null && (!(weights instanceof Uint32Array) || weights.length < capacity)) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._m = m;
+        this._seed = seed >>> 0;
+        // Balancer-owned weights (the SmoothWRR sole-writer precedent): copied, then the sole
+        // mutator is setWeight (which rebuilds). Unweighted default = equal weight 1.
+        this._weights = new Uint32Array(capacity);
+        if (weights !== null) this._weights.set(weights.subarray(0, capacity));
+        else this._weights.fill(1);
+        // The prebuilt lookup table (slot -> backend index). M x 4 bytes; the COLD build fills it.
+        this._lookup = new Uint32Array(m);
+        this._build();
+    }
+
+    /** The Maglev table size M (prime). Readonly. */
+    get tableSize() {
+        return this._m;
+    }
+
+    /**
+     * COLD: (re)populate the lookup table from the current balancer-owned weights via the weighted
+     * Maglev algorithm. O(M x N); never stalls (each backend's permutation covers all M slots).
+     * Rebuilt only on a membership / weight change -- never on a health flap. Allocates only cold
+     * scratch that is released after the build; the lookup table itself is reused in place.
+     */
+    _build() {
+        const M = this._m, N = this._cap, wt = this._weights, lookup = this._lookup, seed = this._seed;
+        // Per-backend Maglev permutation parameters from a deterministic integer mix of the index.
+        const offset = new Int32Array(N);
+        const skip = new Int32Array(N);
+        for (let b = 0; b < N; b++) {
+            const h1 = chMix32(b ^ seed);
+            const h2 = chMix32((b ^ seed) + 0x9e3779b9);
+            offset[b] = h1 % M;
+            skip[b] = (h2 % (M - 1)) + 1;
+        }
+        // Per-backend slot QUOTA proportional to weight, summing to exactly M (unweighted = equal).
+        const quota = new Int32Array(N);
+        let total = 0;
+        for (let b = 0; b < N; b++) total += wt[b];
+        if (total <= 0) {
+            // Degenerate all-zero weights: equal quota so the table is still fully, validly populated.
+            const base = Math.floor(M / N);
+            for (let b = 0; b < N; b++) quota[b] = base;
+            let leftover = M - base * N;
+            for (let b = 0; leftover > 0; b = (b + 1) % N) { quota[b]++; leftover--; }
+        } else {
+            let assigned = 0;
+            for (let b = 0; b < N; b++) { const q = Math.floor(wt[b] / total * M); quota[b] = q; assigned += q; }
+            let leftover = M - assigned;
+            // Hand the rounding leftover to positive-weight backends in index order (deterministic).
+            for (let b = 0; leftover > 0; b = (b + 1) % N) { if (wt[b] > 0) { quota[b]++; leftover--; } }
+        }
+        // Maglev populate honoring the quota. The permutation is surjective over all M slots, so a
+        // backend with remaining quota always reaches an empty slot while one exists -> no stall.
+        const next = new Int32Array(N);
+        const filledCount = new Int32Array(N);
+        const taken = new Uint8Array(M);
+        let filled = 0;
+        while (filled < M) {
+            let progressed = false;
+            for (let b = 0; b < N; b++) {
+                if (filledCount[b] >= quota[b]) continue;
+                let j = next[b];
+                let c = (offset[b] + (j % M) * skip[b]) % M;
+                while (taken[c]) { j++; c = (offset[b] + (j % M) * skip[b]) % M; }
+                lookup[c] = b;
+                taken[c] = 1;
+                next[b] = j + 1;
+                filledCount[b]++;
+                filled++;
+                progressed = true;
+                if (filled >= M) break;
+            }
+            if (!progressed) break;   // unreachable while quotas sum to M -- defensive
+        }
+        // Defensive completeness (unreachable): any slot left empty is pinned to backend 0 so pick()
+        // never reads a stale / out-of-range index. Fail closed on a valid table, always.
+        if (filled < M) {
+            for (let c = 0; c < M; c++) if (!taken[c]) lookup[c] = 0;
+        }
+    }
+
+    /**
+     * COLD: reconfigure backend i's weight (uint32) and REBUILD the table from the new weights.
+     * The balancer is the sole writer of its owned weights (the SmoothWRR precedent).
+     * @param {number} i
+     * @param {number} w  new weight (uint32)
+     */
+    setWeight(i, w) {
+        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        const nw = w >>> 0;
+        if (nw !== w) throw new RangeError('[lite-pick] weight must be a uint32: ' + w);
+        if (nw === this._weights[i]) return;
+        this._weights[i] = nw;
+        this._build();
+    }
+
+    /** COLD: rebuild the lookup table from the current owned weights (e.g. after a membership change). */
+    rebuild() {
+        this._build();
+    }
+
+    /**
+     * Map an INTEGER key to a backend index, or PICK_NONE (fail closed). O(1), 0 B/op.
+     *
+     * slot = (keyHash >>> 0) % M; if `lookup[slot]` is eligible return it, else forward-probe up to
+     * CH_PROBE_LIMIT (64) slots for the next eligible backend. `keyHash` is coerced `>>> 0` (NaN -> 0
+     * deterministically) and pick NEVER throws (the fail-closed contract). Returns PICK_NONE when the
+     * whole pool is down or no eligible backend is reachable within the bound.
+     * @param {number} keyHash  a caller-supplied integer key hash (coerced to uint32)
+     * @returns {number}
+     */
+    pick(keyHash) {
+        if (this._live === 0) return PICK_NONE;   // whole pool down: fail closed
+        const M = this._m, el = this._eligible, lookup = this._lookup;
+        let slot = (keyHash >>> 0) % M;           // integer key; NaN >>> 0 = 0 (never throws)
+        let i = lookup[slot];
+        if (el[i]) return i;
+        // Bounded forward-probe past down slots. Past the bound we fail closed: a near-total outage
+        // may return PICK_NONE even if a far eligible slot exists -- safe, never a dead pick.
+        for (let p = 0; p < CH_PROBE_LIMIT; p++) {
+            slot++;
+            if (slot >= M) slot = 0;
+            i = lookup[slot];
+            if (el[i]) return i;
+        }
+        return PICK_NONE;
+    }
+}

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.7.0 ships seven strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, and the latency-aware `PeakEwmaBalancer`** -- 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 -- 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.8.0 ships eight strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, and the sticky/affinity `ConsistentHashBalancer` (a Maglev lookup table)** -- 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 -- 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: M7 (v0.7.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, and the latency-aware `PeakEwmaBalancer`**, the **`@zakkster/lite-pick/pool`** request layer (now with an opt-in latency-feedback hook), and the **benchmark suite** -- the balance anchor + GC blast-radius headlines, a seeded/version-stamped `results.json`, a `bench:verify` drift check with teeth, and the vs-AWS positioning (see *Evidence* below). This session APPENDS one class: the other strategies in `Pick.js` are byte-identical, only the header roster/count and the `VERSION` stamp change. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), **SED tracks weight within 1%**, and **PeakEWMA steers around a 10x-slow node** (it takes <= 25% of P2C's share for it and cuts service p99) -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M7 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), the RoundRobin (0003), SmoothWRR (0004), P2C (0005), LeastConn-family (0006), pool-adapter (0007), benchmark-suite (0008), and PeakEWMA (0009) design forks.
+> **Status: M8 (v0.8.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, and the sticky/affinity `ConsistentHashBalancer` (a Maglev table)**, the **`@zakkster/lite-pick/pool`** request layer (now with an opt-in latency-feedback hook), and the **benchmark suite** -- the balance anchor + GC blast-radius headlines, a seeded/version-stamped `results.json`, a `bench:verify` drift check with teeth, and the vs-AWS positioning (see *Evidence* below). This session APPENDS one class: the other strategies in `Pick.js` are byte-identical, only the header roster/count and the `VERSION` stamp change. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), **SED tracks weight within 1%**, **PeakEWMA steers around a 10x-slow node** (it takes <= 25% of P2C's share for it and cuts service p99), and **ConsistentHash remaps only ~1.6% of keys on a scale event** (vs ~98% for naive modulo) -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M8 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), the RoundRobin (0003), SmoothWRR (0004), P2C (0005), LeastConn-family (0006), pool-adapter (0007), benchmark-suite (0008), PeakEWMA (0009), and ConsistentHash (0010) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -180,6 +180,30 @@ PeakEWMA sends the slow node **<= 25% of P2C's share** for it and cuts service p
 
 For a **front-end / browser client** -- a handful of picks per second across origins/regions, not a zero-GC hot loop -- the recommended profile is **PeakEWMA + the eligibility bitmap only**: latency-aware choice with a fail-closed health view, and **none** of the server-side bounded-load / availability-zone / occupancy machinery. It is the smallest honest latency-aware client balancer. *(Deferred: a tail-aware `inflight x p99Rtt` variant via an optional-peer `@zakkster/lite-sketch` `DDSketch`; the EWMA-mean score is the shipped zero-peer default, and `peerDependencies` stays `{}` -- [ADR 0009](./decisions/0009-peakewma.md).)*
 
+## ConsistentHash -- sticky / cache-affinity routing (v0.8.0)
+
+When a request must go to the **same** backend every time -- a session, a cache shard, a stateful worker -- you want **consistent hashing**: a stable key -> backend map that barely changes when the pool scales. `ConsistentHashBalancer` is a prebuilt **Maglev lookup table** (the in-kernel/production choice -- Linux IPVS `mh`, Meta Katran, Cilium), so `pick(keyHash)` is `slot = keyHash % M`, one table read, and a bounded probe past down slots -- **O(1)** and **0 B/op** ([ADR 0010](./decisions/0010-consistenthash.md)).
+
+```js
+import { ConsistentHashBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+// YOU hash the key to an INTEGER (cold) -- per-pick STRING hashing is the one zero-GC hazard.
+const b = new ConsistentHashBalancer(4, eligible);  // default M = 65537 (prime); weights optional
+
+const key = fnv1a(sessionId);       // any integer hash you like -- lite-pick adds none
+const i = b.pick(key >>> 0);        // same key -> same backend, at fixed membership
+
+// A tiny FNV-1a over a string, done ONCE per key on the cold path (never inside pick):
+function fnv1a(s) { let h = 0x811c9dc5; for (let k = 0; k < s.length; k++) { h ^= s.charCodeAt(k); h = Math.imul(h, 0x01000193); } return h >>> 0; }
+```
+
+- **Caller-supplied INTEGER key.** `pick(keyHash)` coerces `keyHash >>> 0` (so `NaN`/`undefined` -> `0`) and **never throws** (the fail-closed contract). It never hashes a string -- that would allocate on the hot path. Hash string keys yourself, cold (a tiny FNV-1a is fine -- see the snippet above); `lite-pick` adds **no hashing dependency**.
+- **Minimal disruption.** Removing a backend is just `setEligible(i, false)` -- the table is **untouched**, so every key not on that backend keeps its exact backend and only ~`1/N` reroute (measured **1.6%** vs the naive-modulo trap's **98%** above). A membership or weight change rebuilds the table (**cold**); a health flap **never** does -- the bounded probe (<= 64 slots) absorbs it.
+- **Weighted.** Pass a `Uint32Array` of weights (copied, balancer-owned) for a per-backend slot share proportional to weight; `setWeight(i, w)` / `rebuild()` rebuild the table cold. Unweighted = equal share.
+- **Cost & bound.** The lookup table is `M x 4` bytes -- `~256KB` at the `65537` default -- a **cold, one-time** allocation (disclosed in the cost table below; `M` is configurable **down** for small pools). `pick()` is `O(1)`, `0 B/op`. Fail-closed: `PICK_NONE` when the pool is down or no eligible backend is reachable within the probe bound (a near-total outage may return `PICK_NONE` even if a far eligible slot exists -- safe, never a dead pick).
+- **Deferred seams (import nothing).** A `@zakkster/lite-filter` hot-key / known-key oracle at the key-routing layer (warm/cold only, never the pick path) and a `@zakkster/lite-o1` `EliasFano` ring alternative to the table are optional-peer seams -- `peerDependencies` **stays `{}`** until a shipped path imports one ([ADR 0010](./decisions/0010-consistenthash.md)).
+
 ## Evidence -- the two headlines (v0.6.0 benchmark suite)
 
 > **Framing: parity on speed, superiority on the contract + balance + tail.** A trivial `i++ % n` round-robin -- or `wrr` -- *matches* P2C on raw ops/sec, so `lite-pick` does **not** claim "N times faster." Throughput is claimed at **parity**; the wins are **zero-GC**, **balance quality**, **tail latency** (GC blast-radius), and **never a dead pick**. Every number below is **seeded** and regenerated by `npm run bench:report`; `npm run bench:verify` fails CI if a README number drifts from a fresh run (algorithmic exact, timing within +/-15%). Node / CPU / OS / every PRNG seed are stamped into `benchmark/results.json`.
@@ -192,9 +216,9 @@ The real pinned npm incumbents (`load-balancers`, `loadbalance`, `wrr`) run thro
 
 | family | lite-pick | lite-pick ops/ms | incumbent (npm) | incumbent ops/ms |
 | --- | --- | --- | --- | --- |
-| P2C (power-of-two-choices) | P2cBalancer | 53426 | load-balancers@1.3.52 | 61749 |
-| RoundRobin | RoundRobinBalancer | 246108 | loadbalance@1.0.0 | 282939 |
-| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 151557 |
+| P2C (power-of-two-choices) | P2cBalancer | 53009 | load-balancers@1.3.52 | 59485 |
+| RoundRobin | RoundRobinBalancer | 246432 | loadbalance@1.0.0 | 303459 |
+| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 163481 |
 
 <!-- /bench:competitors -->
 
@@ -222,8 +246,8 @@ The point of zero-GC is **not** the pick's own latency -- a major GC pause freez
 
 | lane | major GC | pick B/op | max GC pause (ms) |
 | --- | --- | --- | --- |
-| lite-pick | 0 | 0 | 0.3 |
-| allocating foil | 13 | allocates | 1.9 |
+| lite-pick | 0 | 0 | 0.1 |
+| allocating foil | 13 | allocates | 2.9 |
 
 <!-- /bench:gc -->
 
@@ -231,15 +255,14 @@ The `lite-pick` lane holds **0 major GC / 0 B/op** on the pick path; the allocat
 
 ### Consistent-hash disruption -- a trust gate
 
-On a scale event (add / remove a node), what fraction of keys keep their node? The **naive-modulo** trap (`key % n`) reshuffles almost everything -- blowing every downstream cache -- while a good consistent hash moves only ~`1/n`. The real `ConsistentHash` (Maglev) lands at **M8**; it is disclosed here as an explicit **SKIP**, not a stub:
+On a scale event (add / remove a node), what fraction of keys keep their node? The **naive-modulo** trap (`key % n`) reshuffles almost everything -- blowing every downstream cache -- while a good consistent hash moves only ~`1/n`. `ConsistentHashBalancer` (the Maglev table, **M8**) is measured here beside the trap and the `1/n` ideal -- removing a backend is just marking it down, so only its keys reroute:
 
 <!-- bench:disruption -->
 
-| scale event | naive-modulo remap | good consistent hash |
-| --- | --- | --- |
-| node removed | 98.4% | 1.6% |
-| node added | 98.5% | 1.5% |
-| ConsistentHash (Maglev) | SKIP -- ships in a later milestone | -- |
+| scale event | naive-modulo remap | ConsistentHash (Maglev) | ideal (1/n) |
+| --- | --- | --- | --- |
+| node removed | 98.4% | 1.6% | 1.6% |
+| node added | 98.5% | 1.5% | 1.5% |
 
 <!-- /bench:disruption -->
 
@@ -250,6 +273,7 @@ On a scale event (add / remove a node), what fraction of keys keep their node? T
 | operation | when | allocates |
 | --- | --- | --- |
 | `new <Strategy>Balancer(...)` | construction, once | the balancer object + its owned accumulators (SmoothWRR's Float64 `current`). The eligibility / inflight / weight views are **caller-owned**, never copied |
+| `new ConsistentHashBalancer(...)` / `rebuild()` / `setWeight()` | cold, on build / membership / reweight | the Maglev lookup table: **`M x 4` bytes** (`~256KB` at the `65537` default `M`), a one-time `Uint32Array` allocation + an `O(M x N)` populate. `M` is **configurable down** for small pools. A health flap does **not** rebuild -- the bounded probe absorbs it |
 | `setEligible(i, up)` | cold, on a health flip | **0** -- one byte write + an O(1) live-count adjust |
 | `setWeight(i, w)` (SmoothWRR) | cold, on reweight | **0** -- one array write + an O(1) eligible-total adjust |
 | `pick()` | **HOT**, per request | **0 B/op** -- proven by `torture` + `test:perf`, measured by `bench:gc` |
@@ -264,7 +288,7 @@ On a scale event (add / remove a node), what fraction of keys keep their node? T
 | ALB `least_outstanding_requests` (LOR) | `LeastConnBalancer` / `P2cBalancer` |
 | ALB anomaly mitigation / latency-aware shedding | `PeakEwmaBalancer` (latency-aware P2C) |
 | ALB `weighted_random` + anomaly mitigation | `WeightedRandom` + `BoundedLoad` (M9/M10) |
-| NLB flow-hash (5-tuple) | `ConsistentHash` (Maglev, M8) |
+| NLB flow-hash (5-tuple) | `ConsistentHashBalancer` (Maglev table -- the same family NLB flow-hash uses, at the in-process hop) |
 
 The composition: inbound traffic still enters through your **ALB/NLB -> service** (the edge hop AWS owns and bills); `lite-pick` governs the fan-out **after** that, the hop no AWS load balancer touches. Complementary, not a replacement -- "the hop your ALB/NLB never sees."
 
@@ -300,6 +324,8 @@ VERSION;              // -> '0.6.0'
 
 ## Wiring it up -- `@zakkster/lite-pick/pool` (v0.5.0)
 
+> **New to lite-pick as a load balancer?** [**RECIPES.md**](./RECIPES.md) is a beginner-to-advanced guide: it builds the kernel up into a real balancer step by step -- health/eligibility, load counters, the dispatch/settle loop, failover, latency feedback (PeakEWMA), the FE profile, and choosing a strategy. Start there; the sections below are the reference.
+
 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

package/RECIPES.md

@@ -0,0 +1,379 @@
+# lite-pick recipes -- from a one-liner to a real load balancer
+
+`@zakkster/lite-pick` is a SELECTION KERNEL, not a proxy. It answers one question --
+"which endpoint should this request go to?" -- and returns an integer index (or
+`PICK_NONE` = -1 when nothing is eligible). A *real* load balancer is that kernel plus
+the wiring around it:
+
+- **eligibility** -- who is up? (a health check writes a shared bitmap)
+- **load counters** -- how busy is each endpoint? (you own an `inflight` array)
+- **the dispatch/settle loop** -- increment on send, decrement on finish
+- **failover** -- if a call fails, try a different endpoint
+- **latency feedback** -- for latency-aware routing, feed measured rtt back
+
+These recipes build that wiring up, one layer at a time. Every array is preallocated
+once and reused -- the pick path allocates 0 bytes.
+
+Install: `npm i @zakkster/lite-pick`  (zero runtime dependencies; ESM; Node >= 18)
+
+---
+
+## 1. The 30-second version -- round-robin over a fixed pool
+
+```js
+import { RoundRobinBalancer, PICK_NONE } from '@zakkster/lite-pick';
+
+const CAP = 4;                              // fixed pool size
+const eligible = new Uint8Array(CAP).fill(1); // 1 = up, 0 = down (all up here)
+const lb = new RoundRobinBalancer(CAP, eligible);
+
+const endpoints = ['a.svc:8080', 'b.svc:8080', 'c.svc:8080', 'd.svc:8080'];
+
+for (let r = 0; r < 6; r++) {
+  const i = lb.pick();                      // -> next eligible index, round-robin
+  if (i === PICK_NONE) throw new Error('pool is down');
+  send(endpoints[i]);                        // your transport; lite-pick never opens a socket
+}
+// picks: a, b, c, d, a, b
+```
+
+`pick()` is the whole kernel. Everything below adds a capability around it.
+
+---
+
+## 2. Fail closed -- always handle PICK_NONE
+
+lite-pick never returns a down endpoint and never guesses. When the whole pool is
+ineligible, `pick()` returns `PICK_NONE` (-1). Treat it as a first-class outcome:
+
+```js
+const i = lb.pick();
+if (i === PICK_NONE) {
+  // shed load, return 503, or fall back -- your policy. Never index endpoints[-1].
+  return respond503();
+}
+send(endpoints[i]);
+```
+
+`lb.live` is an O(1) count of eligible endpoints if you want to check before picking.
+
+---
+
+## 3. Wire health -> eligibility (the shared bitmap)
+
+Eligibility is a shared `Uint8Array` (1 = pickable, 0 = down). Something else writes it
+-- a health checker, a circuit breaker, or `@zakkster/lite-di-health` -- and `pick()`
+only reads it. Two ways to flip a node:
+
+```js
+// (a) write the bitmap directly if you own it elsewhere (zero-copy, pick sees it live):
+eligible[2] = 0;                 // endpoint c is down
+
+// (b) go through the balancer so its O(1) `live` count stays exact (recommended):
+lb.setEligible(2, false);        // COLD path; idempotent; keeps `live` correct
+lb.setEligible(2, true);         // back up
+
+lb.isEligible(2);                // -> boolean, HOT, out-of-range is false (never throws)
+```
+
+Prefer `setEligible` when you rely on `live`. Health flapping is the writer's problem:
+apply hysteresis/dwell in the health layer -- `pick()` stays greedy and stateless.
+
+---
+
+## 4. Weighted pools -- SmoothWRR
+
+When endpoints have different capacities, weight them. `SmoothWRRBalancer` owns its
+weight state; it is the SOLE writer -- always go through `setWeight`, never mutate the
+array directly (direct mutation desyncs the internal total = undefined behavior).
+
+```js
+import { SmoothWRRBalancer } from '@zakkster/lite-pick';
+
+const weights = new Uint32Array(CAP);        // the balancer manages these
+const lb = new SmoothWRRBalancer(CAP, eligible, weights);
+lb.setWeight(0, 5);                          // a is 5x
+lb.setWeight(1, 1);
+lb.setWeight(2, 1);
+lb.setWeight(3, 1);
+// pick() interleaves smoothly (nginx smooth WRR): a a b a c a a d ... not a a a a a b c d
+```
+
+Use SmoothWRR when weights are known/config-driven and change rarely.
+
+---
+
+## 5. Load-aware selection -- you own the `inflight` counters
+
+P2C, LeastConn, SED, and NQ route by *current load*. That load lives in a
+caller-owned `Uint32Array` you increment on dispatch and decrement on settle. If you
+don't maintain it, these strategies are blind (they see every node at 0).
+
+```js
+import { P2cBalancer } from '@zakkster/lite-pick';
+
+const inflight = new Uint32Array(CAP);       // YOURS to maintain
+const lb = new P2cBalancer(CAP, eligible, inflight);
+
+async function handle(req) {
+  const i = lb.pick();
+  if (i === PICK_NONE) return respond503();
+  inflight[i]++;                             // DISPATCH
+  try {
+    return await send(endpoints[i], req);
+  } finally {
+    inflight[i]--;                           // SETTLE (always, even on error)
+  }
+}
+```
+
+- **P2C** -- two random draws, pick the lighter. O(1), the scalable default; peak load
+  hugs the `ln ln n` band. Great from ~8 endpoints up.
+- **LeastConn** -- exact fewest-in-flight (O(cap) scan). Best balance for small pools.
+- **SED** / **NQ** -- weighted least-conn: pass a `weights` Uint32Array too;
+  `new SedBalancer(CAP, eligible, inflight, weights)`. NQ sends to an idle node first.
+
+Maintaining the dispatch/settle loop by hand is easy to get wrong. Recipe 6 does it for
+you.
+
+---
+
+## 6. The real request loop -- `@zakkster/lite-pick/pool`
+
+The `/pool` subpath wraps the kernel with the async dispatch/settle ergonomics so you
+don't hand-maintain `inflight`. The kernel `pick()` stays 0 B/op; `Pool.run` is a normal
+async wrapper on top.
+
+```js
+import { P2cBalancer } from '@zakkster/lite-pick';
+import { Pool } from '@zakkster/lite-pick/pool';
+
+const inflight = new Uint32Array(CAP);
+const lb = new P2cBalancer(CAP, eligible, inflight);
+const pool = new Pool(lb, inflight);         // SAME inflight array the balancer reads
+
+// Pool does pick -> inflight++ -> await fn -> inflight-- (in a finally) for you:
+const body = await pool.run((i, signal) => fetchFrom(endpoints[i], { signal }));
+```
+
+`run(fn, opts?)` rejects with a `code: 'LITE_PICK_NONE'` error when the pool is down.
+`fn(endpoint, signal)` receives the chosen index and the (optional) AbortSignal.
+
+---
+
+## 7. Failover -- try a different endpoint on error
+
+Set `tries > 1`. On a thrown error, Pool keeps the failed node's in-flight count
+elevated and re-picks -- so a load-aware strategy naturally steers to a DIFFERENT
+endpoint -- up to `tries` attempts, then rejects with the last error.
+
+```js
+const body = await pool.run(
+  (i, signal) => fetchFrom(endpoints[i], { signal }),
+  { tries: 3, signal: req.signal }           // up to 3 distinct endpoints
+);
+```
+
+Boundary: Pool owns **spatial** failover (move across the pool, once each, in-process).
+The caller or your query cache owns **temporal** retry (backoff, staleness, dedup).
+Don't double-own them. If `signal` aborts after a failure, failover stops and the abort
+propagates.
+
+---
+
+## 8. Latency-aware routing -- PeakEWMA with rtt feedback
+
+PeakEWMA (latency-aware P2C, Finagle's peak-EWMA) steers away from *slow* endpoints,
+not just busy ones. It scores each candidate `(inflight + 1) x ewma(rtt)`, so a node
+that got slow gets less traffic even if its connection count looks fine. It needs two
+things you didn't need before: a **clock** (`now`, caller-supplied nanoseconds) and
+**rtt feedback** (`recordRtt`).
+
+Manual loop:
+
+```js
+import { PeakEwmaBalancer } from '@zakkster/lite-pick';
+
+const TAU_NS = 30_000_000;                    // 30ms half-life for the EWMA decay
+const inflight = new Uint32Array(CAP);
+const lb = new PeakEwmaBalancer(CAP, eligible, inflight, TAU_NS);
+const nowNs = () => Number(process.hrtime.bigint());
+
+async function handle(req) {
+  const now = nowNs();
+  const i = lb.pick(now);                      // decay-on-read, 0 B/op
+  if (i === PICK_NONE) return respond503();
+  inflight[i]++;
+  const start = nowNs();
+  try {
+    return await send(endpoints[i], req);
+  } finally {
+    inflight[i]--;
+    lb.recordRtt(i, nowNs() - start, nowNs()); // FEEDBACK: measured rtt, snaps up / decays down
+  }
+}
+```
+
+Or let Pool do the feedback for you -- pass a `clock`; Pool drives `pick(now)` and calls
+`recordRtt` on a successful settle when the balancer supports it:
+
+```js
+import { Pool } from '@zakkster/lite-pick/pool';
+const pool = new Pool(lb, inflight);
+const body = await pool.run(
+  (i, signal) => fetchFrom(endpoints[i], { signal }),
+  { clock: () => Number(process.hrtime.bigint()), tries: 2 }
+);
+```
+
+Notes:
+- **Cold start** (no samples yet) degrades gracefully to least-connections -- never NaN.
+- `now` must be a FINITE number. A non-finite `now` degrades to P2C-random (no throw).
+- Pick `tauNs` around your p50-p90 rtt: smaller = reacts faster to a slowdown, larger =
+  steadier. It IS the anti-flap smoothing; no extra dwell needed.
+- Measured effect: with one node at 10x latency, PeakEWMA sends it a tiny fraction of
+  the traffic P2C-over-inflight would, and cuts service p99 sharply.
+
+---
+
+## 9. Sticky / affinity routing -- ConsistentHash (you hash the key)
+
+When a request must land on the **same** backend every time -- a session pinned to a shard,
+a cache key kept warm, a stateful worker -- use `ConsistentHashBalancer`. It is a prebuilt
+**Maglev table**, so `pick(keyHash)` is `O(1)` and `0 B/op`, and scaling the pool moves only
+~`1/N` of keys (not the whole keyspace, the way `key % n` would).
+
+The one rule: **you hash the key to an INTEGER**, on the cold path. Per-pick *string* hashing
+allocates -- the single zero-GC hazard -- so `pick()` takes a number and `lite-pick` ships no
+hashing dependency. Any small integer hash works; FNV-1a is a fine default:
+
+```js
+import { ConsistentHashBalancer, PICK_NONE } from '@zakkster/lite-pick';
+
+// A tiny FNV-1a over a string -- done ONCE per key, never inside pick().
+function fnv1a(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return h >>> 0;
+}
+
+const eligible = new Uint8Array(CAP).fill(1);
+const lb = new ConsistentHashBalancer(CAP, eligible);   // default M = 65537 (prime)
+
+function routeFor(sessionId) {
+  const i = lb.pick(fnv1a(sessionId));   // same session -> same backend, at fixed membership
+  if (i === PICK_NONE) return respond503();
+  return endpoints[i];
+}
+```
+
+Notes:
+- **Remove a backend by marking it down** (`lb.setEligible(i, false)`) -- the table is
+  untouched, so only that backend's keys reroute (~`1/N`); everyone else stays put. A health
+  flap costs nothing (the bounded probe absorbs it) -- it never rebuilds.
+- **Add / reweight** rebuilds the table (cold): `new ConsistentHashBalancer(N + 1, ...)`, or
+  `lb.setWeight(i, w)` / `lb.rebuild()`. Pass a `Uint32Array` of weights for proportional shares.
+- **Cost:** the table is `M x 4` bytes (~256KB at the `65537` default) -- a cold, one-time
+  allocation. Turn `M` down for a small pool (any prime `>= N`).
+- `pick(keyHash)` coerces `keyHash >>> 0` and never throws; it returns `PICK_NONE` only when the
+  pool is down or no eligible backend is reachable within the probe bound.
+
+---
+
+## 10. Wire it into a query cache (lite-query, or any fetcher)
+
+`liteQueryFetcher` adapts a Pool into a `({ key, signal }) => Promise` fetcher -- the
+shape lite-query (or any cache/route-loader) expects. It imports nothing from lite-query
+(duck-typed), so it works with any fetcher-shaped consumer.
+
+```js
+import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+
+const pool = new Pool(lb, inflight);
+const fetcher = liteQueryFetcher(
+  pool,
+  ({ endpoint, key, signal }) => fetchFrom(endpoints[endpoint], { key, signal }),
+  { tries: 2 }
+);
+// hand `fetcher` to your query cache; each cache miss fans out across the pool with failover.
+```
+
+---
+
+## 11. Choosing a strategy
+
+| Strategy      | Route by            | Cost        | Reach for it when |
+|---------------|---------------------|-------------|-------------------|
+| RoundRobin    | position            | O(1) amort. | uniform endpoints, no load signal |
+| SmoothWRR     | static weight       | O(cap)      | known/config capacities, smooth interleave |
+| P2C           | in-flight (approx)  | O(1)        | the scalable default from ~8 nodes up |
+| LeastConn     | in-flight (exact)   | O(cap)      | small pools, tightest connection balance |
+| SED           | in-flight / weight  | O(cap)      | weighted least-conn |
+| NQ            | idle-first else SED  | O(cap)/O(1) | worker pools -- never queue while a worker is free |
+| PeakEWMA      | in-flight x ewma(rtt)| O(1)        | heterogeneous / flaky backends; steer around slow nodes |
+| ConsistentHash| key hash (sticky)   | O(1)        | affinity/sticky: same key -> same backend, minimal disruption on scale |
+
+The load-aware strategies read the SAME `inflight` array live, so you can swap among them
+without rewiring; ConsistentHash instead takes an integer key per pick (recipe 9).
+
+---
+
+## 12. The "FE profile" -- a browser / front-end client
+
+For a front-end client picking among origins a handful of times per second (not a
+zero-GC hot loop), the recommended profile is **PeakEWMA + health/eligibility only** --
+latency-aware choice across origins with a fail-closed eligibility view -- and skip the
+bounded-load / AZ / occupancy machinery. Feed rtt from your `fetch` timings via
+`recordRtt`.
+
+---
+
+## 13. Compose with the suite (all optional, all duck-typed)
+
+lite-pick declares ZERO hard dependencies and an EMPTY `peerDependencies`. Each seam is
+a shared TypedArray or a duck-typed shape, so you wire in a sibling only if you use it:
+
+- `@zakkster/lite-di-health` -- writes the eligibility bitmap from health checks.
+- `@zakkster/lite-statechart` -- a circuit breaker that flips eligibility.
+- `@zakkster/lite-query` -- the cache behind `liteQueryFetcher` (recipe 10).
+- `@zakkster/lite-sketch` -- `DDSketch` for a p99-aware PeakEWMA variant (deferred).
+- `@zakkster/lite-filter` -- a hot-key / known-key oracle at the ConsistentHash key-routing
+  layer (warm/cold only, never the pick path; deferred).
+- `@zakkster/lite-await` -- hedging (race the P2C second choice past a percentile).
+
+None is required; the kernel runs over raw TypedArrays with nothing installed.
+
+---
+
+## 14. Zero-GC discipline (why the pick path stays 0 B/op)
+
+- Allocate `eligible` / `inflight` / `weights` ONCE at startup and reuse them. Never
+  build arrays per pick.
+- The counters are YOURS -- mutate them in place (`inflight[i]++/--`), don't replace them.
+- `pick()` / `pick(now)` and `recordRtt` allocate nothing. The only async allocation is
+  the promise your own `fn` already creates (disclosed; `Pool.run` adds O(1) integer ops
+  plus one small per-run array).
+- Fixed capacity: the pool size is set at construction and the backing arrays never
+  reallocate.
+
+---
+
+## 15. Gotchas
+
+- **PICK_NONE (-1)** is always possible -- handle it before indexing (recipe 2).
+- **SmoothWRR weights** must go through `setWeight`; direct array mutation is UB.
+- **ConsistentHash takes an INTEGER key** -- hash strings yourself, cold (recipe 9). Never
+  `pick(someString)` on the hot path; `M` must be a prime `>= capacity`.
+- **Load-aware strategies need the dispatch/settle loop** -- forget the `inflight--` in
+  a `finally` and load leaks upward forever. Use `/pool` (recipe 6) to avoid it.
+- **PeakEWMA needs a finite `now`** and rtt feedback -- without `recordRtt` it behaves
+  like LeastConn (cold-start baseline).
+- **Eligibility is read-only to `pick()`** -- the health layer writes it; the balancer
+  only reads (or maintains `live` via `setEligible`).
+- **lite-pick is not a proxy** -- it returns an index; you own transport, retries/backoff
+  (temporal), health checking, and the socket.
+
+---
+
+See also: `README.md` (overview + gates), `llms.txt` (full API surface),
+`decisions/` (the ADRs behind each design call), `ROADMAP.md` (what's next).

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.7.1
+Version: 0.8.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,16 +14,26 @@ 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.7.0 ships the substrate seams + seven strategies: RoundRobin, SmoothWRR (the weighted
+0.8.0 ships the substrate seams + eight strategies: RoundRobin, SmoothWRR (the weighted
 default), P2C (power-of-two-choices -- also the O(1) least-connections APPROXIMATION), the
-EXACT LeastConn family (LeastConn, SED, NQ), and PeakEWMA (latency-aware P2C). It exports
-`VERSION`, the fail-closed sentinel `PICK_NONE` (-1), a deterministic `Prng` (xorshift32),
-`BalancerBase` (the shared read-only eligibility seam + O(1) live count), `RoundRobinBalancer`,
-`SmoothWRRBalancer`, `P2cBalancer`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`, and
-`PeakEwmaBalancer`. The remaining strategies land one per session (see ROADMAP.md):
-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.
+EXACT LeastConn family (LeastConn, SED, NQ), PeakEWMA (latency-aware P2C), and ConsistentHash
+(a Maglev lookup table -- sticky/affinity routing). It exports `VERSION`, the fail-closed
+sentinel `PICK_NONE` (-1), a deterministic `Prng` (xorshift32), `BalancerBase` (the shared
+read-only eligibility seam + O(1) live count), `RoundRobinBalancer`, `SmoothWRRBalancer`,
+`P2cBalancer`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`, `PeakEwmaBalancer`,
+`ConsistentHashBalancer`, and the ConsistentHash constants `CH_DEFAULT_M` (65537) / `CH_PROBE_LIMIT`
+(64). The remaining strategies land one per session (see ROADMAP.md): 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.
+
+M8 (0.8.0) adds ConsistentHashBalancer (decisions/0010): a prebuilt Maglev lookup table (IPVS `mh`,
+Meta Katran, Cilium) mapping a caller-supplied INTEGER key to a backend, O(1) / 0 B/op, with minimal
+disruption on a scale event (~1/N keys move, measured ~1.6% vs the naive-modulo foil's ~98%). The
+vs-AWS positioning: NLB flow-hash (5-tuple) is a Maglev consistent hash -- ConsistentHashBalancer is
+that same family at the in-process hop AWS never sees. DEFERRED optional-peer seams (import NOTHING;
+peerDependencies STAYS `{}` until a shipped path imports one): a @zakkster/lite-filter hot-key /
+known-key oracle (BlockedBloom etc.) at the KEY-routing layer (warm/cold only, never the pick path),
+and a @zakkster/lite-o1 `EliasFano` ring alternative to the table.
 
 M7 (0.7.0) adds PeakEwmaBalancer (decisions/0009). The FE PROFILE: for a browser / front-end
 client (a handful of picks per second, not a zero-GC hot loop), the recommended profile is
@@ -150,6 +160,30 @@ the contract + balance + tail -- never an "N times faster" headline (decisions/0
   - CONTRACT: `now` and `sampleNs` MUST be FINITE numbers. `recordRtt` THROWS on a non-finite
     argument (warm path); `pick(now)` NEVER throws (fail-closed contract), so a non-finite `now`
     yields P2C-random selection, not an error.
+- `ConsistentHashBalancer extends BalancerBase` -- class. Sticky/affinity routing via a prebuilt
+  MAGLEV lookup table (M8, IPVS `mh` / Meta Katran / Cilium).
+  - `new ConsistentHashBalancer(capacity, eligible, weights?=null, m?=65537, seed?=0x9e3779b9)` --
+    `weights` is an optional caller Uint32Array (length >= capacity) COPIED into balancer-owned
+    weights (null = equal). `m` is the table size: a PRIME, > 1, and >= capacity (the guard: capacity
+    > m throws -- it would overfill / starve backends). Validates typeof-first BEFORE allocating the
+    table. Builds the table COLD (O(M x N) weighted Maglev populate; the M x 4-byte table is ~256KB at
+    the 65537 default -- disclosed cold cost, M configurable down for small pools).
+  - `pick(keyHash)` -> number. Maps an INTEGER key: slot = (keyHash >>> 0) % M, read `lookup[slot]`,
+    and if down forward-probe up to CH_PROBE_LIMIT (64) slots for the next eligible backend. O(1),
+    0 B/op. `keyHash` is coerced `>>> 0` (NaN -> 0) and pick NEVER throws. `PICK_NONE` when the pool is
+    down OR no eligible backend is reachable within the bound (a mass outage may fail closed even if a
+    far eligible slot exists -- safe, never a dead pick). KEY IS A CALLER INTEGER -- no per-pick string
+    hashing (the one zero-GC hazard); hash string keys yourself, cold. No hashing dependency added.
+  - `setWeight(i, w)` -> void. COLD. Set backend i's weight (uint32) and REBUILD the table.
+  - `rebuild()` -> void. COLD. Rebuild the table from the current owned weights (e.g. after a
+    membership change). A health flap does NOT rebuild -- the bounded probe absorbs it.
+  - `tableSize` -- readonly number. The Maglev table size M (prime).
+  - Minimal disruption: removing a backend is `setEligible(i, false)` (no rebuild), so only ~1/N keys
+    reroute (measured ~1.6% on remove/add vs the naive-modulo foil's ~98%; benchmark/Disruption.mjs).
+  - vs-AWS: NLB flow-hash (5-tuple) is a Maglev consistent hash -- this is that family at the
+    in-process hop. DEFERRED optional-peer seams (import nothing, peerDependencies STAYS `{}`): a
+    @zakkster/lite-filter hot-key oracle at the key-routing layer (warm/cold only), and a
+    @zakkster/lite-o1 `EliasFano` ring alternative to the table (decisions/0010).
 
 ## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.7.1",
-  "description": "Zero-dependency, zero-GC load-balancing selection kernel: one hot pick() -> endpoint index over a fixed pool, 0 B/op steady-state. A pure selector (consumes health/circuit state, never a proxy) for the in-process hop, complementary to AWS NLB/ALB. Tree-shakeable ESM roster: RoundRobin, SmoothWRR, P2C, LeastConn, SED, NQ, PeakEWMA (latency-aware peak-EWMA), plus consistent hashing; the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
+  "version": "0.8.0",
+  "description": "Zero-dependency, zero-GC load-balancing selection kernel: one hot pick() -> endpoint index over a fixed pool, 0 B/op steady-state. A pure selector (consumes health/circuit state, never a proxy) for the in-process hop, complementary to AWS NLB/ALB. Tree-shakeable ESM roster: RoundRobin, SmoothWRR, P2C, LeastConn, SED, NQ, PeakEWMA (latency-aware peak-EWMA), and ConsistentHash (Maglev sticky/affinity routing, minimal disruption); the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
   "type": "module",
   "main": "./Pick.js",
   "module": "./Pick.js",
@@ -28,6 +28,7 @@
     "Pool.d.ts",
     "llms.txt",
     "README.md",
+    "RECIPES.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -73,6 +74,8 @@
     "peak-ewma",
     "latency-aware",
     "consistent-hashing",
+    "consistent-hash",
+    "sticky",
     "maglev",
     "bounded-load",
     "weighted-random",