@zakkster/lite-pick 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.2.0] - 2026-09-23
+
+M2: SmoothWRR, the weighted default (ROADMAP.md M2).
+
+### Added
+
+- `SmoothWRRBalancer extends BalancerBase` -- nginx-style smooth weighted round-robin
+  (`current += weight; pick max; current -= total`). Distributes picks by caller-configured
+  integer weights, interleaved SMOOTHLY (weights [5,1,1] -> A,A,B,A,C,A,A), not in the
+  bursts of naive weight-expansion WRR. Owns its Float64Array smoothing accumulators; the
+  sole writer of the weights via the cold `setWeight(i, w)`. O(cap) per pick, 0 B/op. Fails
+  closed (`PICK_NONE`) when the eligible-weight sum is 0 (all down, or all eligible weights 0).
+- `setWeight(i, w)` (cold) -- reconfigure a weight, keeping the eligible-weight total exact.
+  `setEligible` is overridden to maintain the total and reset the toggled node's accumulator
+  (no stale credit across an eligibility epoch).
+- `test/SmoothWRR.test.js` -- 12 tests: the documented [5,1,1] sequence, exact fairness over
+  k cycles, smoothness (max-run strictly below the bursty foil), skips-down / redistribution,
+  fail-closed (all down AND all-zero-weight), setWeight/setEligible invariants + accumulator
+  reset, uint32 validation, and a never-returns-a-down-index proof under 200k churned picks.
+- Gates extended for SmoothWRR: torture (retention + 0 B/op `pick()`), PerfGate (`zgcSuite`
+  scenario at a realistic 256-endpoint pool -- SmoothWRR is O(cap) -- with a `grows` counter
+  over all three backing arrays, plus a `mustFail` teeth-check), witness (a per-strategy
+  complexity flag: `linear` asserts flat WORK RATE `ops/ms * n`), balance (exact weighted
+  fairness + max-run < bursty foil).
+- `benchmark/Matrix.mjs` -- SmoothWRR subject + the naive expand-WRR bursty foil.
+- `decisions/0004-smoothwrr-weight-ownership.md` -- weight ownership (cold setWeight),
+  Float64 accumulators, and the epoch-reset-on-eligibility-transition enrichment.
+
+### Changed
+
+- Version 0.1.0 -> 0.2.0 across `package.json`, `Pick.js` `VERSION`, and `llms.txt`.
+- Corrected the SmoothWRR complexity: O(cap) per pick, not "O(1) amortized" (ROADMAP).
+
 ## [0.1.0] - 2026-09-23
 
 M1: the first strategy, RoundRobin (ROADMAP.md M1). The M0 harness stubs become real,
@@ -72,5 +105,6 @@ ownership boundary in place before any `pick()` is written.
 - Next: **M1 RoundRobin** (0.1.0) -- the first strategy, landing the throughput witness
   and the balance gate.
 
+[0.2.0]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.2.0
 [0.1.0]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.1.0
 [0.0.1]: https://github.com/PeshoVurtoleta/lite-pick/releases/tag/v0.0.1

package/Pick.d.ts

@@ -1,9 +1,9 @@
 /**
  * @zakkster/lite-pick -- TypeScript declarations.
  *
- * M1 (0.1.0): the substrate seams + the first strategy, RoundRobin. The remaining
- * strategy classes (SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash,
- * BoundedLoad, WeightedRandom) are added one per session.
+ * M2 (0.2.0): substrate seams + RoundRobin + SmoothWRR (weighted). The remaining
+ * strategy classes (P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad,
+ * WeightedRandom) are added one per session.
  */
 
 /** The single source-of-truth version stamp. */
@@ -68,3 +68,22 @@ export class RoundRobinBalancer extends BalancerBase {
     /** Next eligible index in round-robin order, or `PICK_NONE` when the pool is down. */
     pick(): number;
 }
+
+/**
+ * SmoothWRRBalancer -- nginx-style smooth weighted round-robin (M2). Distributes picks by
+ * caller-configured integer weights, interleaved smoothly (weights [5,1,1] -> A,A,B,A,C,A,A).
+ * Owns its smoothing accumulators; the sole writer of the weights via `setWeight`. O(cap)
+ * per pick, 0 B/op. Fails closed (`PICK_NONE`) when the eligible-weight sum is 0.
+ */
+export class SmoothWRRBalancer extends BalancerBase {
+    /**
+     * @param capacity endpoint count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param weights per-endpoint weights (length >= capacity); mutate only via setWeight.
+     */
+    constructor(capacity: number, eligible: Uint8Array, weights: Uint32Array);
+    /** Cold path: reconfigure endpoint `i`'s weight, keeping the eligible-weight total exact. */
+    setWeight(i: number, w: number): void;
+    /** Next endpoint by smooth weighting, or `PICK_NONE` when the eligible-weight sum is 0. */
+    pick(): number;
+}

package/Pick.js

@@ -1,7 +1,7 @@
 /**
  * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
  *
- * M1 (0.1.0): the substrate seams + the FIRST strategy, RoundRobin. This file ships:
+ * M2 (0.2.0): substrate seams + RoundRobin + SmoothWRR (weighted). 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.
@@ -13,21 +13,22 @@
  *                    It does NOT implement pick() -- strategies subclass it.
  *   - RoundRobinBalancer  the baseline strategy: a wrapping cursor that forward-scans
  *                    the eligibility view, skipping down nodes, O(1) amortized, 0 B/op.
+ *   - SmoothWRRBalancer   the weighted default: nginx smooth weighted round-robin over
+ *                    caller-configured integer weights, O(cap)/pick, 0 B/op.
  *
  * 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
  * the caller write, and returns an integer index. Health, circuit state, and load
  * counters live OUTSIDE the kernel. The steady-state pick path allocates 0 B/op.
  *
- * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [shipped M1],
- *   SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad,
- *   WeightedRandom [planned].
+ * Roster (one strategy per session -- see ROADMAP.md): RoundRobin [M1], SmoothWRR [M2],
+ *   P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom [planned].
  *
  * Zero runtime dependencies. node:test only. ESM, single file, tree-shakeable.
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.
@@ -202,3 +203,98 @@ export class RoundRobinBalancer extends BalancerBase {
         return PICK_NONE;
     }
 }
+
+/**
+ * SmoothWRRBalancer -- nginx-style smooth weighted round-robin (M2).
+ *
+ * Distributes picks by caller-configured integer weights, spreading them SMOOTHLY over
+ * time rather than in bursts: weights [5, 1, 1] yield A, A, B, A, C, A, A -- not the
+ * A A A A A B C clumping of naive weight-expansion WRR. Each pick adds every eligible
+ * node's weight to its accumulator, takes the node with the highest accumulator, and
+ * subtracts the total eligible weight from it (the nginx `current += weight; pick max;
+ * current -= total` algorithm).
+ *
+ * Ownership (ADR 0001, ADR 0004): this is the first strategy that owns ALGORITHM state --
+ * the per-endpoint smoothing accumulators (`_current`, a Float64Array; Float64 absorbs the
+ * sum of uint32 weights without overflow and is 0 B/op on the hot path). Weights live in
+ * the caller's Uint32Array, but the balancer is the SOLE writer via the cold `setWeight()`,
+ * which keeps `_totalEligibleWeight` exact; mutating the weights array directly desyncs the
+ * total (documented UB). An eligibility toggle maintains the total AND resets the toggled
+ * node's accumulator (ADR 0004: no stale credit across an eligibility epoch -- anti-flap
+ * aligned, ADR 0002).
+ *
+ * Bound: O(cap) per pick (one scan of the pool -- SmoothWRR is inherently linear in the
+ * pool size, negligible at real endpoint counts), zero-alloc. Fails closed (PICK_NONE)
+ * when the eligible-weight sum is 0 -- whole pool down, or every eligible node's weight 0.
+ */
+export class SmoothWRRBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     * @param {Uint32Array} weights  per-endpoint weights (length >= capacity); the balancer
+     *   is the sole writer via setWeight() -- direct mutation desyncs the total (UB).
+     */
+    constructor(capacity, eligible, weights) {
+        super(capacity, eligible);
+        if (!(weights instanceof Uint32Array) || weights.length < capacity) {
+            throw new RangeError('[lite-pick] weights must be a Uint32Array of length >= capacity');
+        }
+        this._weights = weights;
+        this._current = new Float64Array(capacity);
+        let total = 0;
+        for (let i = 0; i < capacity; i++) if (eligible[i]) total += weights[i];
+        this._totalEligibleWeight = total;
+    }
+
+    /**
+     * Cold path: mark endpoint i up/down, maintaining the eligible-weight total and
+     * RESETTING the toggled node's accumulator (no stale credit across an eligibility
+     * epoch, ADR 0004). Zero-alloc.
+     * @param {number} i
+     * @param {boolean} up
+     */
+    setEligible(i, up) {
+        const was = this.isEligible(i);
+        super.setEligible(i, up);           // validates range, flips the bit, updates _live
+        const now = this._eligible[i] !== 0;
+        if (was !== now) {
+            this._totalEligibleWeight += now ? this._weights[i] : -this._weights[i];
+            this._current[i] = 0;           // reset on every eligibility transition
+        }
+    }
+
+    /**
+     * Cold path: reconfigure endpoint i's weight, keeping the eligible-weight total exact.
+     * @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);
+        const old = this._weights[i];
+        if (nw === old) return;
+        this._weights[i] = nw;
+        if (this._eligible[i]) this._totalEligibleWeight += nw - old;
+    }
+
+    /**
+     * Next endpoint by smooth weighting, or PICK_NONE (fail closed). O(cap), zero-alloc.
+     * @returns {number}
+     */
+    pick() {
+        const total = this._totalEligibleWeight;
+        if (total <= 0) return PICK_NONE;   // whole pool down, or all eligible weights 0
+        const cap = this._cap, el = this._eligible, wt = this._weights, cur = this._current;
+        let best = -1, bestCur = -Infinity;
+        for (let i = 0; i < cap; i++) {
+            if (el[i]) {
+                const c = cur[i] + wt[i];
+                cur[i] = c;
+                if (c > bestCur) { bestCur = c; best = i; }
+            }
+        }
+        cur[best] -= total;                 // best >= 0 guaranteed while total > 0
+        return best;
+    }
+}

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.1.0 ships the first strategy, `RoundRobinBalancer`**, on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- SmoothWRR, P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
+> Zero-GC load-balancing **selection kernel**: one hot `pick()` that returns an endpoint **index** over a fixed pool and allocates **0 B/op** on the steady-state path. A pure selector, never a proxy -- it consumes health and circuit state, it never owns them. **v0.2.0 ships two strategies -- `RoundRobinBalancer` and `SmoothWRRBalancer`** (the weighted default) -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom -- lands one per session.
 
 [![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: M1 (v0.1.0).** Ships the substrate seams **plus the first strategy, `RoundRobinBalancer`**. The M0 harness stubs are now real gates: `pick()` is proven **0 B/op** (torture + PerfGate), **perfectly fair** (balance: imbalance 1.0000, and zero dead picks vs the naive `i++ % n` foil), and **flat** across the pool sweep (witness). See [ROADMAP.md](./ROADMAP.md) for the M1 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin design fork (ADR 0003).
+> **Status: M2 (v0.2.0).** Ships the substrate seams **plus `RoundRobinBalancer` and `SmoothWRRBalancer`**. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth** (max-run far below bursty weight-expansion WRR), and each scales as advertised (witness). See [ROADMAP.md](./ROADMAP.md) for the M2 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin (ADR 0003) and SmoothWRR (ADR 0004) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -54,6 +54,28 @@ rr.pick() === PICK_NONE; // -> true  (-1)
 
 Every `pick()` above allocates **0 bytes**, owns only an integer cursor, and reads the one shared eligibility view (no second copy to drift). Over a run it hands each *live* endpoint an equal share -- true round-robin over the eligible set, not the raw index space.
 
+## SmoothWRR (v0.2.0)
+
+The weighted default -- nginx's *smooth* weighted round-robin. Weighted picks are **interleaved evenly** instead of clumped, so a heavy endpoint doesn't get a burst of consecutive requests.
+
+```js
+import { SmoothWRRBalancer } from '@zakkster/lite-pick';
+
+const eligible = Uint8Array.from([1, 1, 1]);
+const weights  = Uint32Array.from([5, 1, 1]); // A is 5x
+
+const wrr = new SmoothWRRBalancer(3, eligible, weights);
+
+const seq = Array.from({ length: 7 }, () => wrr.pick());
+// -> [0, 0, 1, 0, 2, 0, 0]   smooth: A A B A C A A  (not A A A A A B C)
+// over 7 picks: A=5, B=1, C=1 -- exactly the weights
+
+// Reweight on the cold path (the balancer stays the sole writer of the weights):
+wrr.setWeight(1, 4);  // B is now 4x
+```
+
+`pick()` is **0 B/op** and **O(cap)** (one scan of the pool -- negligible at real endpoint counts). It owns its smoothing accumulators; weights live in your `Uint32Array` but you mutate them only through `setWeight`, which keeps the internal eligible-weight total exact. Marking a node down/up resets its accumulator, so a recovered node rejoins neutral -- no stale burst or starvation ([ADR 0004](./decisions/0004-smoothwrr-weight-ownership.md)).
+
 ## The substrate (under every strategy)
 
 ```js

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.1.0
+Version: 0.2.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,11 +14,11 @@ 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.1.0 ships the substrate seams + the FIRST strategy, RoundRobin. 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), and `RoundRobinBalancer`. The
-remaining strategies land one per session (see ROADMAP.md): SmoothWRR, P2C, LeastConn/SED/NQ,
-PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
+0.2.0 ships the substrate seams + two strategies: RoundRobin and SmoothWRR (the weighted
+default). It exports `VERSION`, the fail-closed sentinel `PICK_NONE` (-1), a deterministic
+`Prng` (xorshift32), `BalancerBase` (the shared read-only eligibility seam + O(1) live count),
+`RoundRobinBalancer`, and `SmoothWRRBalancer`. The remaining strategies land one per session
+(see ROADMAP.md): P2C, LeastConn/SED/NQ, PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
 
 ## Design ownership (decisions/0001, 0002)
 
@@ -57,6 +57,18 @@ PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
     forward-scans the eligibility view, skipping down nodes), or `PICK_NONE` when the pool is
     down. O(1) amortized, O(cap) worst case under sparse eligibility, 0 B/op. Owns only its
     cursor; no eligible-set structure (ADR 0003 chose the stateless bitmap-scan path for M1).
+- `SmoothWRRBalancer extends BalancerBase` -- class. The weighted default (M2).
+  - `new SmoothWRRBalancer(capacity, eligible, weights)` -- `weights` is a Uint32Array
+    (length >= capacity); the balancer is the sole writer via setWeight (direct mutation
+    desyncs the total -- UB).
+  - `setWeight(i, w)` -> void. COLD. Reconfigure endpoint i's weight (uint32), keeping the
+    eligible-weight total exact.
+  - `setEligible(i, up)` -> void. COLD. Overrides the base to maintain the eligible-weight
+    total and reset the toggled node's accumulator (no stale credit across an epoch, ADR 0004).
+  - `pick()` -> number. Next endpoint by nginx smooth weighted round-robin (`current +=
+    weight; pick max; current -= total`), interleaved smoothly (weights [5,1,1] ->
+    A,A,B,A,C,A,A), or `PICK_NONE` when the eligible-weight sum is 0. O(cap) per pick, 0 B/op.
+    Owns its Float64Array smoothing accumulators (ADR 0004).
 
 ## Gates (every session)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-dependency, zero-GC load-balancing selection kernel: one hot pick() -> endpoint index over a fixed pool, 0 B/op steady-state. A pure selector (consumes health/circuit state, never a proxy) for the in-process hop, complementary to AWS NLB/ALB. Tree-shakeable ESM roster: RoundRobin, SmoothWRR, P2C, least-conn, PeakEWMA, consistent hashing.",
   "type": "module",
   "main": "./Pick.js",