@zakkster/lite-pick 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,105 @@ 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.9.0] - 2026-09-23
+
+### Added
+
+- **`BoundedLoadBalancer` (M9)** -- **Consistent Hashing with Bounded Loads** (CHBL: Mirrokni et al.,
+  Google Research; Vimeo's `eps = 0.25`). It **extends `ConsistentHashBalancer`** (the Maglev table) and
+  adds a per-backend occupancy cap `cap = (1 + eps) x _total / live`: `pick(keyHash)` sticks a key to its
+  hashed home **unless** that backend is over cap, in which case the request **overflows** along the same
+  bounded forward-probe to the next eligible, under-cap backend. If none in the probe window is under cap
+  it falls back to the first eligible seen (**sticky wins; the cap is a soft preference, never a dead
+  pick**); `_total === 0` skips the cap entirely, behaving as pure consistent hashing. This keeps
+  consistent hashing's stickiness + minimal disruption **and** adds the **hotspot protection** plain
+  consistent hashing lacks. The Maglev build, probe walk, and `setWeight` / `rebuild` / `tableSize` are
+  reused verbatim. The running occupancy sum `_total` is **balancer-owned** (starts at 0) and written
+  **solely** via the warm `note(i, delta)` seam (dispatch `+1` / settle `-1`), so the cap's mean stays
+  O(1)-current without a scan; `inflight` is the caller's `Uint32Array`, read **live** as the per-backend
+  occupancy. `pick()` and `note()` are both **O(1)** / **0 B/op**. `eps` is validated typeof-first
+  (TypeError non-number, RangeError non-finite / `<= 0`) before the table is allocated; `note()` validates
+  `i` in range and `delta` as an integer, and clamps `_total` at 0. `totalInflight` exposes `_total`.
+  `PICK_NONE` only when no eligible backend is reachable within the probe window -- **never** for
+  over-cap (fail open on overload). **Contract:** the mirrored inflight counter is mutated **only** through
+  `note()` / the `/pool` adapter -- direct mutation desyncs `_total` (UB, the SmoothWRR-weights asymmetry).
+  ([ADR 0011](./decisions/0011-boundedload.md)).
+- **The pivot** (ADR 0011): the first M9 draft built the "overload" reading -- P2C-over-inflight with a
+  `(1 + eps) x mean` cap -- and it was proven **byte-identical to plain P2C** (an under-cap draw always
+  has lower inflight than an over-cap one, so "prefer under-cap" and "lower-of-two" pick the same node).
+  The cap is only *load-bearing* when the primary choice is a **hash**, so M9 is CHBL -- the algorithm
+  the roadmap cited. The P2C-with-cap reading is withdrawn as non-distinct.
+- **Hotspot anchor** (`test/balance.mjs`) -- 64 backends, a Zipfian-skewed key stream (6 hot keys, 85% of
+  traffic), a fixed concurrency window: plain ConsistentHash pins a hot key on one backend -- measured
+  **max occupancy 129** vs a mean of **10** (a ~13x hotspot) -- while CHBL's cap holds **max occupancy 13**
+  (`cap = (1 + eps) x mean = 12.5`) by overflowing to neighbours, materially below ConsistentHash's max
+  (the foil FAILS the bounded-occupancy band). Both keep **~1.55%** minimal disruption on a scale event
+  (`<= 2/N`). Thresholds are measured from a correct run with a small margin and noted -- the impl is
+  never bent to a number.
+- Gates extended for the new strategy: `test/BoundedLoad.test.js` boundary suite (ctor + eps validation,
+  sticky same-key routing, overflow when a home is over cap, fail-open, PICK_NONE only pool-down,
+  pure-ConsistentHash when `_total === 0`, `note()` validation + clamp, `totalInflight` tracking, minimal
+  disruption, a Pool `opts.key` net-zero round-trip); `test/fuzz.mjs` keyed note-driven subject +
+  `checkBoundedLoad` (`totalInflight === sum(inflight)` after every op) + the ConsistentHash structural
+  invariant; `test/torture.mjs` retention (small-instance CHBL loop) + `pick(keyHash)` and `note()` 0 B/op
+  phases; `test/perf/PerfGate.test.mjs` `boundedLoadPick` + `boundedLoadNote` zero-alloc scenarios + a
+  `mustFail` alloc tooth; `test/witness.mjs` O(1) const flat-work keyed subject; `benchmark/Matrix.mjs`
+  subject (dims throughput/balance/gc over the skewed-cost workload); `Pick.d.ts` +
+  `test/types/pick.test-d.ts` typed surface.
+
+### Changed
+
+- `Pool.run` gains an **inert-unless-duck-typed `note` hook** (mirror each dispatch as `note(i, +1)` and
+  each settle as `note(i, -1)`, net-zero per run) paralleling the PeakEWMA `recordRtt` wiring, and an
+  **`opts.key`** option -- when supplied, Pool drives `pick(key)` (keyed / CHBL routing); failover
+  re-picks with the same key, and because the failed backend's occupancy stays elevated a CHBL re-pick
+  naturally overflows to the next backend. All hooks are inert when not applicable -- Pool stays generic,
+  in-flight stays net-zero, abort/failover unchanged.
+- `Pick.js`: STRATEGY-APPEND only -- the other eight strategies are **byte-identical**; the sole changes
+  are the header roster/count (eight -> nine), the `VERSION` bump, and the appended `BoundedLoadBalancer`
+  (which **extends `ConsistentHashBalancer`**, reusing its Maglev build + probe verbatim; ConsistentHash
+  itself is unchanged).
+- `VERSION` bumped 0.8.0 -> **0.9.0** across the three sync sites (package.json, `Pick.js`, llms.txt);
+  package `description` roster updated (keywords already carried `bounded-load`). `peerDependencies`
+  stays `{}` (CHBL reuses M8 -- imports nothing new).
+
+## [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

package/Pick.d.ts

@@ -1,9 +1,10 @@
 /**
  * @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.
+ * M9 (0.9.0): substrate seams + RoundRobin + SmoothWRR + P2C + the exact LeastConn family
+ * (LeastConn/SED/NQ) + PeakEWMA (latency-aware P2C) + ConsistentHash (Maglev table) +
+ * BoundedLoad (P2C with a dynamic occupancy cap). The remaining strategy class (WeightedRandom)
+ * is added one per session.
  */
 
 /** The single source-of-truth version stamp. */
@@ -187,3 +188,86 @@ 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;
+}
+
+/**
+ * BoundedLoadBalancer -- Consistent Hashing with Bounded Loads (M9, CHBL: Mirrokni et al. / Google
+ * Research; Vimeo eps ~ 0.25). `ConsistentHashBalancer` (the Maglev table) PLUS an occupancy cap: a
+ * key sticks to its hashed home backend UNLESS that backend is over `cap = (1 + eps) * _total / live`,
+ * in which case the request OVERFLOWS along the same bounded forward-probe to the next eligible,
+ * under-cap backend -- keeping consistent hashing's stickiness + minimal disruption AND adding the
+ * HOTSPOT protection plain consistent hashing lacks. `pick(keyHash)` returns the first eligible,
+ * under-cap backend in the probe window, else falls back to the first eligible seen (sticky wins; the
+ * cap is a soft preference, never a dead pick); `_total === 0` skips the cap -> pure ConsistentHash.
+ * `inflight` is the caller-owned Uint32Array read LIVE as the per-backend OCCUPANCY; the running
+ * occupancy sum `_total` is BALANCER-OWNED and written ONLY by `note` (dispatch +1 / settle -1), so
+ * when using BoundedLoad the mirrored counter must be mutated exclusively through `note` / the /pool
+ * adapter (direct mutation desyncs `_total` -- UB). It inherits the Maglev table + `setWeight` /
+ * `rebuild` / `tableSize` from ConsistentHashBalancer (reused verbatim). `pick()` and `note()` are
+ * both 0 B/op / O(1). Fails closed (`PICK_NONE`) ONLY when no eligible backend is reachable within
+ * the probe window -- NEVER merely because backends are over cap. NOT the P2C-with-cap "overload"
+ * variant (that is byte-identical to P2C; the cap is only load-bearing on a sticky hash -- ADR 0011).
+ */
+export class BoundedLoadBalancer extends ConsistentHashBalancer {
+    /**
+     * @param capacity backend count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param inflight per-backend OCCUPANCY (length >= capacity), caller-owned, read live; mutated
+     *   EXCLUSIVELY via `note` / the /pool adapter (direct mutation desyncs `_total` -- UB).
+     * @param eps the bounded-load slack over the mean (finite, > 0); default 0.25 (Vimeo).
+     * @param weights optional per-backend weights (length >= capacity), COPIED; 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,
+        inflight: Uint32Array,
+        eps?: number,
+        weights?: Uint32Array | null,
+        m?: number,
+        seed?: number,
+    );
+    /** The balancer-owned running sum of in-flight the mean/cap is computed from. */
+    readonly totalInflight: number;
+    /** Warm feedback path: adjust the owned occupancy sum (dispatch +1 / settle -1). Clamps at 0. 0 B/op. */
+    note(i: number, delta: number): void;
+    /** Map an integer `keyHash` to a backend, honouring the occupancy cap (overflow past a hot home), or `PICK_NONE`. O(1). */
+    pick(keyHash?: number): number;
+}

package/Pick.js

@@ -1,8 +1,10 @@
 /**
  * @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:
+ * M9 (0.9.0): substrate seams + nine strategies -- RoundRobin, SmoothWRR, P2C, the exact
+ * LeastConn family (LeastConn, SED, NQ), PeakEWMA (latency-aware P2C), ConsistentHash
+ * (a Maglev lookup table), and BoundedLoad (Consistent Hashing with Bounded Loads: the
+ * Maglev table + an occupancy cap that overflows a hot backend). 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 +33,20 @@
  *                    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).
+ *   - BoundedLoadBalancer  Consistent Hashing with Bounded Loads (CHBL, Mirrokni et al. / Google
+ *                    Research; Vimeo eps=0.25): ConsistentHash (the Maglev table) PLUS an occupancy
+ *                    cap. pick(keyHash) sticks a key to its hashed home UNLESS that backend is over
+ *                    cap = (1+eps) x _total / live, in which case the request OVERFLOWS along the same
+ *                    bounded probe to the next eligible under-cap backend -- consistent hashing's
+ *                    stickiness + minimal disruption PLUS the hotspot protection plain CH lacks. It
+ *                    extends ConsistentHashBalancer (reusing its Maglev build + probe VERBATIM) and
+ *                    OWNS a running `_total` (sole writer: the warm note(i, delta) seam). O(1), 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
@@ -38,9 +54,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 [M9],
+ *   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 +67,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.7.2';
+export const VERSION = '0.9.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -739,3 +755,366 @@ 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;
+    }
+}
+
+/**
+ * BoundedLoadBalancer -- Consistent Hashing with Bounded Loads (M9, CHBL: Mirrokni-Thorup-
+ * Zadimoghaddam, Google Research 2016; Vimeo's eps ~ 0.25). This is `ConsistentHashBalancer` (the M8
+ * Maglev table) PLUS an occupancy CAP: a key sticks to its hashed home backend UNLESS that backend is
+ * over the cap, in which case the request OVERFLOWS along the same bounded forward-probe to the next
+ * eligible, under-cap backend. It keeps consistent hashing's stickiness + minimal disruption AND adds
+ * the HOTSPOT protection plain consistent hashing lacks: a few very hot keys can pile unbounded load
+ * on one backend, so the cap spreads the overflow to neighbours while everything else stays put.
+ *
+ * Why this is the REAL bounded-load strategy (ADR 0011): P2C-over-inflight with a `(1+eps) x mean` cap
+ * is byte-identical to plain P2C (an under-cap draw ALWAYS has lower inflight than an over-cap one, so
+ * "prefer under-cap" and "lower-of-two" pick the same node) -- the cap is a no-op there. The cap is
+ * only LOAD-BEARING when the primary choice is fixed by something OTHER than load: a hash. CHBL is
+ * that -- the hashed home is sticky, and the cap is what lets a hot home overflow.
+ *
+ * `pick(keyHash)` (HOT, 0 B/op, NEVER throws): k = keyHash >>> 0; slot = k % M; walk the M8 probe
+ * window (home + CH_PROBE_LIMIT slots) and return the FIRST backend that is ELIGIBLE AND UNDER cap
+ * (`inflight[b] < cap`). If none in the window is under cap, FALL BACK to the first eligible seen
+ * (sticky wins; the cap is a soft preference, never a dead pick). When `_total === 0` the cap test is
+ * skipped entirely -> behaves as pure ConsistentHash. `cap = (1 + eps) x _total / live`.
+ *
+ * Ownership (ADR 0001, ADR 0004, ADR 0010, ADR 0011): the Maglev lookup table + weights are
+ * BALANCER-OWNED and built COLD (reused from ConsistentHashBalancer VERBATIM -- `_build`, `setWeight`,
+ * `rebuild`, `tableSize`, the probe walk, `chMix32`, `CH_DEFAULT_M`, `CH_PROBE_LIMIT`). `inflight` is
+ * the CALLER's Uint32Array, read LIVE as the per-backend OCCUPANCY source. The running occupancy sum
+ * `_total` is BALANCER-OWNED and its SOLE writer is the warm `note(i, delta)` feedback path
+ * (dispatch +1 / settle -1), so the cap's mean stays O(1)-current without a scan.
+ *
+ * CONTRACT (the SmoothWRR-weights asymmetry): when using BoundedLoad the mirrored inflight counter is
+ * mutated ONLY through `note()` / the /pool adapter. Direct mutation desyncs `_total` from the true
+ * sum, so the cap goes wrong -- UB. `note()` clamps `_total` at 0; `totalInflight` exposes it.
+ *
+ * Bound: O(1) per pick (modulo + table read + bounded cap-aware probe), 0 B/op on BOTH `pick()` and
+ * `note()` (torture + PerfGate). Fails closed (PICK_NONE) ONLY when no eligible backend is reachable
+ * within the probe window (M8's contract) -- NEVER merely because backends are over cap.
+ */
+export class BoundedLoadBalancer extends ConsistentHashBalancer {
+    /**
+     * @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} inflight  per-backend OCCUPANCY (length >= capacity), caller-owned and read
+     *   LIVE -- but mutated EXCLUSIVELY via note() / the /pool adapter (direct mutation desyncs the
+     *   owned _total -- UB).
+     * @param {number} [eps=0.25]  the bounded-load slack over the mean: finite, > 0. cap =
+     *   (1 + eps) x mean occupancy. Default 0.25 (Vimeo).
+     * @param {Uint32Array|null} [weights=null]  optional per-backend weights (COPIED); null = equal.
+     * @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, inflight, eps = 0.25, weights = null, m = CH_DEFAULT_M, seed = 0x9e3779b9) {
+        // Validate inflight + eps typeof-first, BEFORE super() allocates the (cold, ~256KB) Maglev
+        // table (fail closed early -- the PeakEWMA / ConsistentHash precedent). These read the args
+        // only (no `this`), so they may run before super().
+        if (!(inflight instanceof Uint32Array) || inflight.length < capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= capacity');
+        }
+        if (typeof eps !== 'number') {
+            throw new TypeError('[lite-pick] eps must be a number');
+        }
+        if (!Number.isFinite(eps) || eps <= 0) {
+            throw new RangeError('[lite-pick] eps must be a finite number > 0');
+        }
+        // super() validates capacity/eligible/weights/m, copies weights, and builds the Maglev table.
+        super(capacity, eligible, weights, m, seed);
+        this._inflight = inflight;
+        this._eps = eps;
+        // The running occupancy sum the balancer OWNS. Starts at 0: note() is its sole writer, so a
+        // caller must drive dispatch/settle through note() (or /pool) -- inflight seeded non-zero
+        // BEFORE construction would desync it (UB, as documented).
+        this._total = 0;
+    }
+
+    /** The balancer-owned running sum of in-flight the mean/cap is computed from. Readonly. */
+    get totalInflight() {
+        return this._total;
+    }
+
+    /**
+     * Warm feedback path (NOT the hot pick path): adjust the owned running occupancy sum by `delta`
+     * for backend `i`. This is the SOLE writer of `_total`: dispatch is note(i, +1), settle is
+     * note(i, -1), so the cap's mean stays O(1)-current without scanning inflight. `i` is validated in
+     * range (like setEligible); `delta` is validated typeof-first as an integer. `_total` clamps at 0
+     * (an over-decrement never drives the mean negative). Zero-alloc on the success path.
+     * @param {number} i  backend index (validated in range)
+     * @param {number} delta  integer occupancy change (+1 dispatch, -1 settle)
+     */
+    note(i, delta) {
+        if (i < 0 || i >= this._cap) throw new RangeError('[lite-pick] index out of range: ' + i);
+        if (typeof delta !== 'number') throw new TypeError('[lite-pick] delta must be a number');
+        if (!Number.isInteger(delta)) throw new RangeError('[lite-pick] delta must be an integer: ' + delta);
+        const t = this._total + delta;
+        this._total = t > 0 ? t : 0;   // clamp: over-decrement never drives the mean negative
+    }
+
+    /**
+     * Map an INTEGER key to a backend, honouring the occupancy cap, or PICK_NONE (fail closed). O(1),
+     * 0 B/op, never throws. slot = (keyHash >>> 0) % M; walk the M8 probe window (home + CH_PROBE_LIMIT
+     * slots) and return the FIRST backend that is ELIGIBLE AND under cap = (1+eps) x _total / live. If
+     * none in the window is under cap, fall back to the FIRST eligible seen (sticky wins -- the cap is
+     * a soft preference, never a dead pick). `_total === 0` skips the cap test -> pure ConsistentHash.
+     * PICK_NONE ONLY when no eligible backend is reachable within the window.
+     * @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, inf = this._inflight;
+        const total = this._total;
+        // cap is only meaningful once occupancy is known; _total === 0 -> pure ConsistentHash.
+        const capActive = total > 0;
+        const cap = capActive ? (1 + this._eps) * total / this._live : 0;   // finite: total>0, live>0
+        let slot = (keyHash >>> 0) % M;           // integer key; NaN >>> 0 = 0 (never throws)
+        let firstEligible = -1;                   // the pure-ConsistentHash sticky fallback answer
+        let i = lookup[slot];
+        if (el[i]) {
+            if (!capActive || inf[i] < cap) return i;   // sticky home, under cap: the common fast path
+            firstEligible = i;
+        }
+        // Bounded forward-probe (M8's exact walk): the first eligible AND under-cap backend wins; a hot
+        // home OVERFLOWS to its neighbours. Past the window we fall back to the sticky first-eligible.
+        for (let p = 0; p < CH_PROBE_LIMIT; p++) {
+            slot++;
+            if (slot >= M) slot = 0;
+            i = lookup[slot];
+            if (el[i]) {
+                if (!capActive || inf[i] < cap) return i;   // eligible + under cap: overflow target
+                if (firstEligible < 0) firstEligible = i;    // remember the first eligible (fallback)
+            }
+        }
+        return firstEligible;   // -1 (PICK_NONE) iff NO eligible backend was reachable in the window
+    }
+}

package/Pool.d.ts

@@ -10,11 +10,14 @@ export const VERSION: string;
 
 /** The minimal balancer shape Pool drives (any lite-pick strategy satisfies it). */
 export interface Balancer {
-    pick(now?: number): number;
+    /** `now` (PeakEwma clock) or `keyHash` (ConsistentHash/BoundedLoad) when supplied via opts. */
+    pick(arg?: number): number;
     readonly capacity: number;
     readonly live: number;
     /** Optional latency-feedback sink (PeakEwmaBalancer); fed on settle when a clock is supplied. */
     recordRtt?(i: number, sampleNs: number, now: number): void;
+    /** Optional occupancy sink (BoundedLoadBalancer); fed +1 on dispatch, -1 on settle. */
+    note?(i: number, delta: number): void;
 }
 
 /** Options for `Pool.run`. */
@@ -28,6 +31,12 @@ export interface RunOptions {
      * `recordRtt` latency feedback for a latency-aware balancer (PeakEwma); otherwise inert.
      */
     clock?: () => number;
+    /**
+     * An integer routing key for a keyed balancer (ConsistentHash / BoundedLoad). When present,
+     * `run` calls `pick(key)`; the opt-in `note` occupancy hook is driven on dispatch/settle for
+     * a bounded-load balancer. Ignored by non-keyed strategies.
+     */
+    key?: number;
 }
 
 /**

package/Pool.js

@@ -77,13 +77,27 @@ export class Pool {
      * Pool stays generic, the in-flight counter stays net-zero, and abort/failover are unaffected.
      * The kernel `pick()` remains 0 B/op; this wrapper is not held to that bar.
      *
+     * An OCCUPANCY-AWARE balancer (BoundedLoadBalancer -- anything duck-typing `note`) has each
+     * dispatch mirrored as `note(i, +1)` and each settle as `note(i, -1)`, so its owned running mean
+     * stays current; against a balancer with no `note` the hook is fully INERT (same net-zero,
+     * generic behaviour). The two hooks are independent -- a balancer may duck-type neither, one, or
+     * both.
+     *
+     * A KEYED balancer (ConsistentHashBalancer / BoundedLoadBalancer -- CHBL) routes by an INTEGER
+     * key. When `opts.key` is supplied, Pool drives `pick(key)` (sticky / bounded-load routing);
+     * failover re-picks with the SAME key, and because the failed backend's occupancy stays elevated
+     * (its `note(+1)` held across attempts) a CHBL re-pick naturally OVERFLOWS to the next backend.
+     * Without `opts.key`, `pick()` / `pick(now)` behaviour is unchanged.
+     *
      * @template T
      * @param {(endpoint: number, signal?: AbortSignal) => (Promise<T>|T)} fn  the per-endpoint work.
-     * @param {{ signal?: AbortSignal, tries?: number, clock?: () => number }} [opts]  `tries`
-     *   (default 1 = no failover) is the max number of distinct-endpoint attempts; `signal` is
+     * @param {{ signal?: AbortSignal, tries?: number, clock?: () => number, key?: 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); `clock` is a caller-owned nanosecond source that, when present,
-     *   drives `pick(now)` and the opt-in `recordRtt` latency feedback for a latency-aware balancer.
+     *   drives `pick(now)` and the opt-in `recordRtt` latency feedback for a latency-aware balancer;
+     *   `key` is a caller-supplied INTEGER key that, when present, drives `pick(key)` for a keyed
+     *   balancer (sticky / CHBL routing).
      * @returns {Promise<T>}
      */
     async run(fn, opts) {
@@ -92,16 +106,27 @@ export class Pool {
         const tries = rawTries > 0 ? rawTries : 1;
         const signal = opts ? opts.signal : undefined;
         const clock = opts && typeof opts.clock === 'function' ? opts.clock : undefined;
+        // A keyed balancer (ConsistentHash / BoundedLoad -- CHBL) picks by an INTEGER key. When
+        // `opts.key` is supplied, pick(key) drives selection; otherwise the existing pick()/pick(now)
+        // behaviour is unchanged. `keyed` is true exactly when a key was passed.
+        const keyed = opts !== undefined && opts.key !== undefined;
+        const key = keyed ? opts.key : undefined;
         const inflight = this._inflight, b = this._b;
         // Opt-in latency feedback: only when BOTH a clock is supplied AND the balancer duck-types
         // recordRtt. Otherwise inert -- Pool stays generic and byte-for-byte behaviour is unchanged.
         const rtt = clock !== undefined && typeof b.recordRtt === 'function';
+        // Opt-in occupancy feedback (BoundedLoadBalancer): when the balancer duck-types note(), Pool
+        // mirrors each dispatch(+1)/settle(-1) into it so the balancer's owned _total mean stays
+        // O(1)-current. Otherwise inert -- Pool stays generic, in-flight stays net-zero, and
+        // abort/failover are unchanged. Follows the exact opt-in shape the recordRtt hook uses.
+        const notes = typeof b.note === 'function';
         const held = [];                 // endpoints incremented this run (kept elevated across failover)
         let lastErr;
         try {
             for (let attempt = 0; attempt < tries; attempt++) {
                 const now = clock !== undefined ? clock() : undefined;
-                const i = b.pick(now);
+                // A keyed pick (opts.key) takes precedence -- sticky/CHBL routing; else pick(now)/pick().
+                const i = keyed ? b.pick(key) : b.pick(now);
                 if (i === PICK_NONE) {
                     if (attempt === 0) {
                         const e = new Error('[lite-pick] no eligible endpoint');
@@ -112,6 +137,7 @@ export class Pool {
                 }
                 inflight[i] = (inflight[i] + 1) >>> 0;
                 held.push(i);
+                if (notes) b.note(i, 1);       // mirror the dispatch into the balancer's occupancy sum
                 try {
                     const out = await fn(i, signal);
                     if (rtt) {           // successful settle: feed the measured rtt back to the balancer
@@ -130,6 +156,7 @@ export class Pool {
             for (let k = 0; k < held.length; k++) {
                 const j = held[k];
                 inflight[j] = inflight[j] > 0 ? inflight[j] - 1 : 0;
+                if (notes) b.note(j, -1);      // net-zero settle -- keeps _total in lockstep per run
             }
         }
     }

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.9.0 ships nine strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev lookup table), and the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads -- sticky routing + an occupancy cap that overflows a hot backend to its neighbours)** -- 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 -- WeightedRandom -- lands next 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: M9 (v0.9.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family, the latency-aware `PeakEwmaBalancer`, the sticky/affinity `ConsistentHashBalancer` (a Maglev table), and the hotspot-protecting `BoundedLoadBalancer` (consistent hashing with bounded loads)**, the **`@zakkster/lite-pick/pool`** request layer (with opt-in latency-feedback, occupancy-feedback, and keyed-routing hooks), 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), **ConsistentHash remaps only ~1.6% of keys on a scale event** (vs ~98% for naive modulo), and **BoundedLoad tames a hotspot plain consistent hashing can't** (under a skewed key stream ConsistentHash spikes a hot backend to ~13x the mean occupancy while BoundedLoad's `(1+eps)` cap holds it near the mean by overflowing to neighbours -- keeping the same ~1.6% minimal disruption) -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M9 -> 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), ConsistentHash (0010), and BoundedLoad/CHBL (0011) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -180,6 +180,64 @@ 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)).
+
+## BoundedLoad -- consistent hashing with bounded loads (v0.9.0)
+
+Plain consistent hashing is sticky and minimally-disruptive, but it has one failure mode: a **hot key**. If a handful of keys carry most of the traffic, consistent hashing pins each one's *entire* load on its one hashed backend -- an unbounded **hotspot**. `BoundedLoadBalancer` is [`ConsistentHashBalancer`](#consistenthash--sticky--cache-affinity-routing-v080) (the Maglev table) **plus a per-backend occupancy cap** `cap = (1 + eps) x mean` (the mean occupancy `_total / live`, with slack `eps`): a key sticks to its hashed home **unless** that backend is over cap, in which case the request **overflows** along the same bounded probe to the next eligible, under-cap backend (Mirrokni et al. *Consistent Hashing with Bounded Loads*, Google Research; Vimeo's `eps = 0.25` -- [ADR 0011](./decisions/0011-boundedload.md)). You keep stickiness + minimal disruption **and** gain the hotspot protection consistent hashing lacks.
+
+```js
+import { BoundedLoadBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);            // YOU own this; read live as per-backend OCCUPANCY
+
+// eps = 0.25 -> a backend over 1.25x the mean occupancy overflows the key to a neighbour.
+const bl = new BoundedLoadBalancer(4, eligible, inflight, 0.25);
+
+const key = fnv1a(sessionId);                    // any integer hash (cold) -- lite-pick adds none
+const i = bl.pick(key >>> 0);                    // sticky home, or the overflow target if it's hot
+inflight[i]++;   bl.note(i, +1);                 // dispatch: bump the counter AND tell the balancer
+// ... await the request ...
+inflight[i]--;   bl.note(i, -1);                 // settle: net-zero on both
+```
+
+- **Sticky + overflow.** `pick(keyHash)` maps the integer key to its Maglev home; if that backend is under cap it wins (the common, sticky path). If it is over cap, the request overflows along the bounded probe to the first eligible, under-cap backend. If nothing in the window is under cap, it falls back to the first eligible seen -- **sticky wins; the cap is a soft preference, never a dead pick**. When `_total === 0` the cap is skipped entirely, so it behaves as pure `ConsistentHashBalancer`.
+- **`note()` is the sole writer of the mean.** BoundedLoad **owns** a running occupancy sum `_total` and keeps it O(1)-current through `note(i, +1)` on dispatch / `note(i, -1)` on settle -- so the cap's mean never needs a scan; `inflight` is your live-read per-backend occupancy. **Contract:** mutate the mirrored counter **only** through `note()` (or the `/pool` adapter, which does it for you) -- direct mutation desyncs `_total` (UB, the same asymmetry `SmoothWRRBalancer` has for its weights). `note()` clamps `_total` at 0, and `totalInflight` exposes it.
+- **Inherits the Maglev table.** It extends `ConsistentHashBalancer`, so `setWeight(i, w)` / `rebuild()` / `tableSize` and the whole weighted-Maglev build + bounded-probe walk are reused verbatim; the `weights` / `m` / `seed` constructor args are the same. `pick()` and `note()` are both **0 B/op**, `O(1)`. `PICK_NONE` only when no eligible backend is reachable in the probe window -- never merely because backends are over cap.
+- **Why not "P2C with a cap"?** A note on the design (the honest one): power-of-two-choices over in-flight *plus* a `(1+eps) x mean` cap is **byte-identical to plain P2C** -- an under-cap draw always has lower in-flight than an over-cap one, so "prefer under-cap" and "lower-of-two" pick the same node. The cap is a no-op there. It is only *load-bearing* when the primary choice is fixed by something other than load -- a **hash**. That is CHBL, and it is why BoundedLoad is built on consistent hashing ([ADR 0011](./decisions/0011-boundedload.md)).
+
+The proof (from `test/balance.mjs`, a Zipfian-skewed key stream over 64 backends, one fixed concurrency window):
+
+| lane | mean occupancy | max backend occupancy |
+|---|---|---|
+| **BoundedLoad (CHBL)** | 10 | **13** (cap = 12.5 -- overflow holds it near the mean) |
+| ConsistentHash (no cap) | 10 | **129** (~13x -- the hotspot) |
+
+BoundedLoad caps the hot backend near `(1 + eps) x mean` while plain consistent hashing lets it run away, and both reroute only **~1.6%** of keys on a scale event (`test/balance.mjs`). See [`ConsistentHashBalancer`](#consistenthash--sticky--cache-affinity-routing-v080) above for the integer-key contract and the FNV-1a helper.
+
 ## 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 +250,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 +280,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 +289,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 +307,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` |
@@ -263,8 +321,9 @@ 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) |
+| ALB anomaly mitigation on a sticky/affinity hash | `BoundedLoadBalancer` (consistent hashing with bounded loads -- sticky + hotspot overflow, M9) |
+| ALB `weighted_random` | `WeightedRandom` (M10) |
+| 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."
 
@@ -293,10 +352,10 @@ rng.nextBelow(4);     // -> a uint32 in [0, 4)
 rng.reset();          // replays the exact stream
 
 PICK_NONE;            // -> -1  (fail-closed sentinel: no endpoint, never a dead pick)
-VERSION;              // -> '0.6.0'
+VERSION;              // -> '0.9.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`, `LeastConnBalancer`, `SedBalancer`, `NqBalancer`, `PeakEwmaBalancer`) 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`, `PeakEwmaBalancer`, `ConsistentHashBalancer`, `BoundedLoadBalancer`) 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)
 

package/RECIPES.md

@@ -236,7 +236,51 @@ Notes:
 
 ---
 
-## 9. Wire it into a query cache (lite-query, or any fetcher)
+## 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
@@ -256,7 +300,7 @@ const fetcher = liteQueryFetcher(
 
 ---
 
-## 10. Choosing a strategy
+## 11. Choosing a strategy
 
 | Strategy      | Route by            | Cost        | Reach for it when |
 |---------------|---------------------|-------------|-------------------|
@@ -267,12 +311,14 @@ const fetcher = liteQueryFetcher(
 | 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 |
 
-All read the SAME `inflight` array live, so you can swap strategies without rewiring.
+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).
 
 ---
 
-## 11. The "FE profile" -- a browser / front-end client
+## 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** --
@@ -282,22 +328,24 @@ bounded-load / AZ / occupancy machinery. Feed rtt from your `fetch` timings via
 
 ---
 
-## 12. Compose with the suite (all optional, all duck-typed)
+## 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 9).
+- `@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.
 
 ---
 
-## 13. Zero-GC discipline (why the pick path stays 0 B/op)
+## 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.
@@ -310,10 +358,12 @@ None is required; the kernel runs over raw TypedArrays with nothing installed.
 
 ---
 
-## 14. Gotchas
+## 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

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.7.2
+Version: 0.9.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,16 +14,47 @@ 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.9.0 ships the substrate seams + nine 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), ConsistentHash
+(a Maglev lookup table -- sticky/affinity routing), and BoundedLoad (Consistent Hashing with Bounded
+Loads -- sticky routing + a per-backend occupancy cap that overflows a hotspot to neighbours). 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`, `BoundedLoadBalancer`, and the ConsistentHash constants `CH_DEFAULT_M`
+(65537) / `CH_PROBE_LIMIT` (64). The remaining strategy lands next session (see ROADMAP.md):
+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.
+
+M9 (0.9.0) adds BoundedLoadBalancer (decisions/0011): Consistent Hashing with Bounded Loads (CHBL --
+Mirrokni et al. / Google Research; Vimeo eps=0.25). It is `ConsistentHashBalancer` (the Maglev table)
+PLUS a per-backend occupancy cap `cap = (1 + eps) x _total / live`: `pick(keyHash)` sticks a key to its
+hashed home UNLESS that backend is over cap, in which case the request OVERFLOWS along the same bounded
+probe to the next eligible under-cap backend -- consistent hashing's stickiness + minimal disruption
+PLUS the HOTSPOT protection plain CH lacks. If none in the window is under cap it FALLS BACK to the
+first eligible (sticky wins; PICK_NONE is pool-down ONLY, never for over-cap); `_total === 0` skips the
+cap -> pure ConsistentHash. It extends ConsistentHashBalancer (reusing the Maglev build + probe +
+setWeight/rebuild/tableSize VERBATIM) and OWNS a running `_total` whose SOLE writer is the warm
+`note(i, delta)` seam (dispatch +1 / settle -1); `inflight` is the caller's Uint32Array read LIVE as
+the per-backend occupancy. `pick()` and `note()` are both O(1) / 0 B/op. CONTRACT: when using
+BoundedLoad the mirrored counter is mutated ONLY through `note()` / /pool -- direct mutation desyncs
+`_total` (UB, the SmoothWRR-weights asymmetry). THE PIVOT (decisions/0011): P2C-over-inflight with a
+`(1+eps) x mean` cap is byte-identical to plain P2C (an under-cap draw always has lower inflight than an
+over-cap one), so the cap is only LOAD-BEARING when the primary choice is a HASH -- CHBL is that. The
+hotspot anchor (test/balance.mjs): under a skewed key stream, plain ConsistentHash spikes a hot backend
+to ~13x the mean occupancy while CHBL caps it near (1+eps) x mean by overflow -- and both keep ~1/N
+minimal disruption on a scale event.
+
+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 +181,61 @@ 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).
+- `BoundedLoadBalancer extends ConsistentHashBalancer` -- class. Consistent Hashing with Bounded Loads
+  (M9, CHBL: Mirrokni et al. / Google Research; Vimeo eps=0.25). ConsistentHash (the Maglev table) PLUS
+  a per-backend occupancy cap that overflows a hot backend to its neighbours.
+  - `new BoundedLoadBalancer(capacity, eligible, inflight, eps?=0.25, weights?=null, m?=65537, seed?=0x9e3779b9)`
+    -- `inflight` is a caller-owned Uint32Array (length >= capacity) read LIVE as the per-backend
+    OCCUPANCY; `eps` is the bounded-load slack (finite, > 0). Validates inflight + eps typeof-first
+    BEFORE super() allocates the Maglev table (TypeError non-number eps, RangeError non-finite / <= 0).
+    `weights` / `m` / `seed` are the ConsistentHash args (copied weights, prime m >= capacity, COLD
+    build). The running occupancy sum `_total` is BALANCER-OWNED (starts at 0) and written SOLELY by
+    `note`; when using BoundedLoad, the mirrored inflight counter is mutated ONLY through `note` / /pool
+    (direct mutation desyncs `_total` -- UB, the SmoothWRR-weights asymmetry).
+  - `pick(keyHash)` -> number. slot = (keyHash >>> 0) % M; walk the probe window (home + CH_PROBE_LIMIT
+    slots) and return the FIRST backend that is ELIGIBLE AND under `cap = (1 + eps) * _total / live`
+    (a hot home OVERFLOWS to a neighbour). If none in the window is under cap, fall back to the FIRST
+    eligible seen (sticky wins; the cap is a soft preference). `_total === 0` skips the cap -> pure
+    ConsistentHash. O(1), 0 B/op, NEVER throws. `PICK_NONE` ONLY when no eligible backend is reachable
+    in the window -- NEVER merely because backends are over cap (fail OPEN on overload).
+  - `note(i, delta)` -> void. WARM feedback path (not the hot pick path): the SOLE writer of `_total`
+    (dispatch note(i,+1) / settle note(i,-1)), so the cap's mean stays O(1)-current without a scan.
+    `i` is validated in range (RangeError), `delta` typeof-first as an integer; `_total` clamps at 0.
+    0 B/op on the success path.
+  - `totalInflight` -- readonly number. The owned running occupancy sum (for tests / observability).
+  - `setWeight(i, w)` / `rebuild()` / `tableSize` -- inherited from ConsistentHashBalancer (COLD
+    rebuild of the Maglev table; the readonly prime table size).
+  - THE PIVOT (decisions/0011): P2C-over-inflight with a `(1+eps) x mean` cap is byte-identical to
+    plain P2C (an under-cap draw always has lower inflight than an over-cap one), so the cap is only
+    LOAD-BEARING when the primary choice is a HASH -- CHBL is that. The hotspot anchor
+    (test/balance.mjs): under a skewed key stream, plain ConsistentHash spikes a hot backend to ~13x
+    the mean occupancy while CHBL caps it near (1+eps) x mean by overflow; both keep ~1/N minimal
+    disruption. `Pool.run` mirrors dispatch/settle into `note` when the balancer duck-types it, and
+    `Pool.run(fn, { key })` drives `pick(key)` for keyed CHBL routing (both inert otherwise).
 
 ## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
 
@@ -178,7 +264,14 @@ duck-typed and imports NOTHING from lite-query.
     `opts.clock` (a caller-owned nanosecond source) is supplied AND the balancer duck-types
     `recordRtt` (PeakEwmaBalancer), Pool drives `pick(now)` and records the settled rtt on success;
     otherwise the hook is inert -- Pool stays generic, in-flight stays net-zero, abort/failover
-    unchanged.
+    unchanged. OPT-IN occupancy feedback: when the balancer duck-types `note` (BoundedLoadBalancer),
+    Pool mirrors each dispatch as `note(i, +1)` and each settle as `note(i, -1)` so its owned mean
+    stays current; inert otherwise. The hooks are independent -- a balancer may duck-type neither,
+    one, or both; a BoundedLoad + Pool round is net-zero on BOTH the inflight array and `_total`.
+    OPT-IN keyed routing: `opts.key` (a caller INTEGER) drives `pick(key)` for a keyed balancer
+    (ConsistentHash / BoundedLoad -- CHBL); failover re-picks with the SAME key, and because the failed
+    backend's occupancy stays elevated a CHBL re-pick naturally OVERFLOWS to the next backend. Without
+    `opts.key`, `pick()` / `pick(now)` behaviour is unchanged.
 - `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.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.7.2",
-  "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.9.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), ConsistentHash (Maglev sticky/affinity routing, minimal disruption), and BoundedLoad (consistent hashing with bounded loads -- sticky routing with a per-backend occupancy cap that overflows a hotspot to neighbours); the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
   "type": "module",
   "main": "./Pick.js",
   "module": "./Pick.js",
@@ -74,6 +74,8 @@
     "peak-ewma",
     "latency-aware",
     "consistent-hashing",
+    "consistent-hash",
+    "sticky",
     "maglev",
     "bounded-load",
     "weighted-random",