@zakkster/lite-pick 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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

package/Pick.d.ts

@@ -1,9 +1,10 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * 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.
+ * 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. */
@@ -224,3 +225,49 @@ export class ConsistentHashBalancer extends BalancerBase {
     /** 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,9 +1,10 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * 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:
+ * 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.
@@ -38,6 +39,14 @@
  *                    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
@@ -45,7 +54,7 @@
  * 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 [M8], BoundedLoad,
+ *   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.
  *
@@ -58,7 +67,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.8.0';
+export const VERSION = '0.9.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -976,3 +985,136 @@ export class ConsistentHashBalancer extends BalancerBase {
         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.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.
+> 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: 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.
+> **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
@@ -204,6 +204,40 @@ function fnv1a(s) { let h = 0x811c9dc5; for (let k = 0; k < s.length; k++) { h ^
 - **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`.
@@ -287,7 +321,8 @@ 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) |
+| 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."
@@ -317,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/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.8.0
+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,17 +14,38 @@ 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.8.0 ships the substrate seams + eight 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), PeakEWMA (latency-aware P2C), and ConsistentHash
-(a Maglev lookup table -- sticky/affinity routing). It exports `VERSION`, the fail-closed
+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`, 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.
+`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
@@ -184,6 +205,37 @@ the contract + balance + tail -- never an "N times faster" headline (decisions/0
     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)
 
@@ -212,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.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.",
+  "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",