@zakkster/lite-pick 0.5.0 → 0.6.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.6.0] - 2026-09-23
+
+M6: the benchmark suite (ROADMAP.md M6). An EVIDENCE session -- no API change. `Pick.js` and
+`Pool.js` are byte-identical to 0.5.0 apart from the `VERSION` stamp; the kernel gates
+(torture / PerfGate / witness / balance / fuzz) are unchanged and green. Everything added lives
+under `benchmark/` and is NOT in the published tarball (`files[]` unchanged).
+
+### Added
+
+- `benchmark/GcBlastRadius.mjs` -- the GC blast-radius headline (dimension 3). The same sustained
+  mixed workload (n=1024, 2,000,000 requests) through two lanes: the lite-pick lane (`P2cBalancer`
+  over caller-owned typed arrays) measures `major=0`, pick `B/op=0`, `maxPause` ~0.1-0.3ms; the
+  allocating foil lane (collect-candidates-sort idiom with a retained in-flight request context)
+  measures `major=13-14`, `maxPause` ~2.5-4ms. GC sampled via `@zakkster/lite-gc-profiler`
+  (`GcProfiler` + `checkNoGc`, the torture.mjs machinery); `B/op` via `measureAllocs`.
+- `benchmark/Fairness.mjs` -- weighted convergence + burstiness (dimension 8). SmoothWRR weights
+  [10,3,2,1]: exact fairness (counts == k*weight) over 500 cycles, max-run 3 vs the bursty
+  weight-expansion foil's 10. SED weights [1,2,3,4,6,8,12,16]: worst share drift < 0.0001 from the
+  weight target; weighted-imbalance ~0.00 vs a weight-blind random foil's ~5.5.
+- `benchmark/Disruption.mjs` -- consistent-hash disruption (dimension 7). Naive-modulo foil over
+  100,000 seeded keys remaps 98.4% (remove node 64->63) / 98.5% (add node 64->65) of keys vs a good
+  consistent hash's ~1.6% / ~1.5% ideal. Explicit SKIP row for `ConsistentHash` (Maglev, M8) -- no
+  stub in `Pick.js`.
+- `benchmark/Report.mjs` -- emits `benchmark/results.json` stamping Node version, V8, CPU model,
+  core count, arch, OS, and every PRNG seed alongside the measured numbers; renders the README
+  `<!-- bench:ID -->` fenced tables from it. `--verify` mode is the `bench:verify` drift check:
+  ALGORITHMIC numbers (balance peak-gap, disruption remap %) recomputed FRESH and compared EXACT;
+  TIMING numbers (GC pauses) compared to `results.json` within +/-15%. Exits non-zero on any drift.
+  (Fixes the previously-broken `bench:report` script, which pointed at an absent `Report.mjs`.)
+- `benchmark/Soak.mjs` -- the endurance-soak scaffold (post-1.0 #8): ONE P2C lane, continuous
+  mixed-chaos load (flap storms + whole-pool-down troughs + load feedback), emits a JSONL
+  time-series to `benchmark/soak.jsonl`, and RUNS `test/invariants.mjs:checkBase` at every
+  checkpoint. `tracker.size()` returns to 0 after each cycle; invariants green at all checkpoints.
+  `SOAK_CYCLES=0` runs forever -- the harness the `caffeinate -i` overnight burn-in plugs into.
+- `benchmark/Matrix.mjs` -- extended (not rewritten): each SUBJECT gained a `dims` flag, and the
+  file now exports the SHARED SEEDED workload matrix (`buildWorkload` over uniform / skewed-weight
+  / skewed-cost), `SEEDS`, `SUBJECTS`, `SIZES`, and `measureThroughput`, reused by every dimension
+  file. The standalone throughput runner is behind a main guard so importing it runs no sweep.
+- `decisions/0008-benchmark-suite.md` -- the ADR: the parity framing, the real-competitors + foils
+  baseline, the drift-check teeth, and the ConsistentHash SKIP.
+- README: the *Evidence* section -- balance anchor + GC blast-radius headlines (fenced), the
+  consistent-hash disruption trust gate, the honest COLD-path cost table, and the vs-AWS NLB/ALB
+  "complementary, not a competitor" positioning.
+- devDependencies: `load-balancers@1.3.52`, `loadbalance@1.0.0`, `wrr@1.0.0` -- REAL npm
+  competitors, pinned to exact versions, loaded via `createRequire` (all three are CommonJS) and
+  timed into `results.json` beside our in-repo foils; a package that fails to load becomes a
+  labeled `unavailable` row rather than being silently dropped. Each incumbent is rendered side by
+  side with the SAME-complexity lite-pick strategy on the SAME n=1024 pool in the README
+  `<!-- bench:competitors -->` throughput fence. Parity is claimed only on EQUAL-work rows: P2C is
+  parity (~60k vs ~61k ops/ms); RoundRobin is ~22% slower (~260k vs ~335k) and the gap is OWNED --
+  `loadbalance` is a bare `i++ % n` with no liveness, while lite-pick's `RoundRobinBalancer`
+  forward-scans the eligibility bitmap to skip down nodes (never a dead pick), and that scan is the
+  constant-factor cost of a guarantee the incumbents do not offer. The weighted-random row is a
+  disclosed SKIP -- lite-pick's O(1) `WeightedRandom` (alias table) lands at M10, so `wrr` is not
+  raced against our O(cap) `SmoothWRRBalancer` (a different complexity class). No "faster"/"Nx".
+- Scripts: `bench:gc`, `bench:fairness`, `bench:disruption`, `bench:verify`, `soak`.
+
+### Changed
+
+- Version bumped to 0.6.0 in the three sync sites (`package.json`, `Pick.js` `VERSION`, `llms.txt`).
+  `peerDependencies` stays `{}`.
+
 ## [0.5.0] - 2026-09-23
 
 M5: the ergonomic request layer at the `@zakkster/lite-pick/pool` subpath -- dispatch/settle

package/Pick.js

@@ -46,7 +46,7 @@
  */
 
 /** Version stamp. Synced across package.json and llms.txt (three-place rule). */
-export const VERSION = '0.5.0';
+export const VERSION = '0.6.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.

package/README.md

@@ -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: M5 (v0.5.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**, and the **`@zakkster/lite-pick/pool`** request layer. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), and **SED tracks weight within 1%** -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M5 -> M10 path to 1.0.0, and [decisions/](./decisions) for the ownership boundary (ADR 0001), anti-flapping (ADR 0002), and the RoundRobin (0003), SmoothWRR (0004), P2C (0005), LeastConn-family (0006), and pool-adapter (0007) design forks.
+> **Status: M6 (v0.6.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**, the **`@zakkster/lite-pick/pool`** request layer, and now 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). The kernel `Pick.js` / `Pool.js` are byte-identical to v0.5.0 apart from the version stamp. Every strategy is gated: `pick()` proven **0 B/op** (torture + PerfGate), RoundRobin **perfectly fair** with **zero dead picks** vs the naive `i++ % n` foil, SmoothWRR **exactly weighted** and **smooth**, **P2C proves the `ln ln n` balance ceiling** (peak-to-mean gap ~2 vs a random foil's ~21 at n=1024), **LeastConn is greedy-perfect** (max-minus-min load <= 1), and **SED tracks weight within 1%** -- all held under a **seeded invariant fuzzer** (`test/fuzz.mjs`) that checks state-synchronisation after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M6 -> 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), and benchmark-suite (0008) design forks.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -139,6 +139,93 @@ The proof (from `test/balance.mjs`):
 
 Each `pick()` is **0 B/op** and **O(cap)** (NQ is O(1) when an early node is idle). Because these are the state-heaviest strategies so far, M4 also introduces the **invariant fuzzer** (`npm run fuzz`): a seeded state-machine attack that, after *every* `pick` / `setEligible` / weight / load op, asserts the chosen endpoint is the *exact* optimum, `live` stays exact, and `PICK_NONE` holds *iff* nothing is pickable -- printing the seed on any failure for byte-for-byte replay.
 
+## 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`.
+
+### Throughput parity vs the incumbents (ops/ms, same pool)
+
+The real pinned npm incumbents (`load-balancers`, `loadbalance`, `wrr`) run through the **same** harness on the **same** `n=1024` pool as the matching `lite-pick` strategy of the **same complexity class** -- ops/ms side by side, not a winner. On the same-work P2C row `lite-pick` holds parity (59591 vs 60956). On the RoundRobin row `lite-pick` is ~22% slower (260168 vs 334541), and that gap is owned, not hidden: `loadbalance@1.0.0` is a bare `i++ % n` with no liveness, while `lite-pick`'s `RoundRobinBalancer` forward-scans the eligibility bitmap to skip down nodes -- so it never returns a dead pick. That scan is the constant-factor cost of a guarantee none of these incumbents offer. `lite-pick` claims parity only where the work is equal; where it is slower, it is slower for the liveness contract, and the balance + tail wins above are the reason to pay it. The weighted-random row is a disclosed **SKIP**: `lite-pick`'s O(1) weighted-random (`WeightedRandom`, alias table) lands at **M10**, so it is not raced against here -- our shipped `SmoothWRRBalancer` is O(cap) *smooth* weighted round-robin (a different, stronger-smoothness guarantee), whose throughput is measured by `npm run witness` and `npm run bench`, not force-fit into this parity table.
+
+<!-- bench:competitors -->
+
+| family | lite-pick | lite-pick ops/ms | incumbent (npm) | incumbent ops/ms |
+| --- | --- | --- | --- | --- |
+| P2C (power-of-two-choices) | P2cBalancer | 59591 | load-balancers@1.3.52 | 60956 |
+| RoundRobin | RoundRobinBalancer | 260168 | loadbalance@1.0.0 | 334541 |
+| Weighted-random | WeightedRandom -- SKIP, ships M10 | -- | wrr@1.0.0 | 158395 |
+
+<!-- /bench:competitors -->
+
+### Balance quality -- the anchor (headline #1)
+
+The canonical balls-into-bins experiment (throw `m = 32*n` balls into `n` bins): P2C's peak load stays within an additive `ln ln n / ln 2` of the mean, while a single random draw's gap grows with the pool. **Peak-gap** = heaviest bin minus the mean (32); the ceiling column is `4*lnln(n)/ln2 + 4`.
+
+<!-- bench:balance -->
+
+| pool n | P2C peak-gap | random foil peak-gap | ceiling |
+| --- | --- | --- | --- |
+| 64 | 3 | 13 | 12.2 |
+| 1024 | 2 | 21 | 15.2 |
+| 4096 | 2 | 25 | 16.2 |
+
+<!-- /bench:balance -->
+
+P2C's peak-gap stays a small `ln ln n` constant while the random foil's grows with `n` -- the exponential improvement one extra probe buys, measured not asserted ([ADR 0008](./decisions/0008-benchmark-suite.md)).
+
+### GC blast-radius -- the tail (headline #2)
+
+The point of zero-GC is **not** the pick's own latency -- a major GC pause freezes **every in-flight request at once**, so an allocating balancer inflates the *service-level* tail. The **same** sustained mixed workload (`n=1024`, 2M requests) runs through two lanes: the zero-GC `lite-pick` lane vs the ordinary "collect candidates, sort, take the best" idiom that allocates a request context per pick (promoted to old gen while in flight -- exactly the garbage that forces mark-sweep).
+
+<!-- bench:gc -->
+
+| lane | major GC | pick B/op | max GC pause (ms) |
+| --- | --- | --- | --- |
+| lite-pick | 0 | 0 | 0.1 |
+| allocating foil | 13 | allocates | 2.9 |
+
+<!-- /bench:gc -->
+
+The `lite-pick` lane holds **0 major GC / 0 B/op** on the pick path; the allocating foil's promoted request state forces mark-sweep pauses that stall the whole service. **That contrast is the headline**, not ops/sec.
+
+### 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:
+
+<!-- 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 | -- |
+
+<!-- /bench:disruption -->
+
+### Honest cold-path cost (so the 0 B/op HOT-path claim stays bounded)
+
+`pick()` is **0 B/op** and that is the whole point -- so the cold-path costs are **named**, not hidden:
+
+| 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 |
+| `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` |
+| `Pool.run(fn)` (`/pool`) | per request | a promise + one small `held` array -- an async wrapper, **not** the kernel path ([ADR 0007](./decisions/0007-pool-adapter.md)) |
+
+### Complementary to AWS NLB / ALB (not a competitor)
+
+`lite-pick` does not replace a managed **ALB/NLB** -- it governs the *inner* hop those never see (your service fanning out to downstreams / shards / replicas / workers), bringing the **same algorithm family AWS bills for at the edge** to a zero-GC in-process selector you own:
+
+| AWS edge feature (managed, billed) | `lite-pick` equivalent (in-process, zero-GC) |
+| --- | --- |
+| ALB `least_outstanding_requests` (LOR) | `LeastConnBalancer` / `P2cBalancer` |
+| ALB `weighted_random` + anomaly mitigation | `WeightedRandom` + `BoundedLoad` (M9/M10) |
+| NLB flow-hash (5-tuple) | `ConsistentHash` (Maglev, M8) |
+
+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."
+
 ## The substrate (under every strategy)
 
 ```js
@@ -164,7 +251,7 @@ 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.4.0'
+VERSION;              // -> '0.6.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`) extends it and reads the same shared eligibility view; you subclass it the same way to add your own.

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.5.0
+Version: 0.6.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -14,7 +14,7 @@ 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.4.0 ships the substrate seams + six strategies: RoundRobin, SmoothWRR (the weighted
+0.6.0 ships the substrate seams + six strategies: RoundRobin, SmoothWRR (the weighted
 default), P2C (power-of-two-choices -- also the O(1) least-connections APPROXIMATION), and the
 EXACT LeastConn family (LeastConn, SED, NQ). It exports `VERSION`, the fail-closed sentinel
 `PICK_NONE` (-1), a deterministic `Prng` (xorshift32), `BalancerBase` (the shared read-only
@@ -24,6 +24,16 @@ session (see ROADMAP.md): PeakEWMA, ConsistentHash, BoundedLoad, WeightedRandom.
 n) fewest-in-flight variant is a deferred @zakkster/lite-logn `BinaryHeap` optional-peer seam
 (decisions/0006), not this exact-O(cap) scan.
 
+M6 (0.6.0) adds the BENCHMARK SUITE -- an evidence session, no API change: Pick.js / Pool.js are
+byte-identical to 0.5.0 apart from the VERSION stamp. It lives entirely under benchmark/ (NOT in
+the published tarball): the balance anchor + GC blast-radius headlines, weighted-fairness and
+consistent-hash-disruption trust gates, a seeded + Node/CPU/OS-stamped results.json, a
+bench:verify drift check (algorithmic EXACT, timing +/-15%), the naive-modulo disruption foil
+with an explicit ConsistentHash SKIP row (Maglev lands at M8), the endurance Soak.mjs scaffold
+(reuses test/invariants.mjs:checkBase), and REAL pinned npm competitors (load-balancers,
+loadbalance, wrr) as devDeps beside our in-repo foils. Framing: parity on speed, superiority on
+the contract + balance + tail -- never an "N times faster" headline (decisions/0008).
+
 ## Design ownership (decisions/0001, 0002)
 
 - IN-PROCESS first (workers, DI services); remote HTTP is a thin optional adapter.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Zero-dependency, zero-GC load-balancing selection kernel: one hot pick() -> endpoint index over a fixed pool, 0 B/op steady-state. A pure selector (consumes health/circuit state, never a proxy) for the in-process hop, complementary to AWS NLB/ALB. Tree-shakeable ESM roster: RoundRobin, SmoothWRR, P2C, LeastConn, SED, NQ, plus PeakEWMA and consistent hashing; the /pool subpath adds dispatch/settle counters + failover and a duck-typed query-cache fetcher.",
   "type": "module",
   "main": "./Pick.js",
@@ -40,7 +40,12 @@
     "fuzz": "node test/fuzz.mjs",
     "test:perf": "node --expose-gc --max-semi-space-size=4 --test test/perf/PerfGate.test.mjs",
     "bench": "node benchmark/Matrix.mjs",
-    "bench:report": "node benchmark/Matrix.mjs && node benchmark/Report.mjs",
+    "bench:gc": "node --expose-gc benchmark/GcBlastRadius.mjs",
+    "bench:fairness": "node benchmark/Fairness.mjs",
+    "bench:disruption": "node benchmark/Disruption.mjs",
+    "bench:report": "node benchmark/Matrix.mjs && node --expose-gc benchmark/Report.mjs",
+    "bench:verify": "node benchmark/Report.mjs --verify",
+    "soak": "node --expose-gc benchmark/Soak.mjs",
     "demo": "node demo/fanout.mjs",
     "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run balance && npm run fuzz && npm run test:perf"
   },
@@ -103,7 +108,10 @@
     "@zakkster/lite-gc-profiler": "^1.16.0",
     "@zakkster/lite-leak": "^1.10.0",
     "@zakkster/lite-perf-gate": "^1.4.2",
-    "typescript": "^7.0.2"
+    "load-balancers": "1.3.52",
+    "loadbalance": "1.0.0",
+    "typescript": "^7.0.2",
+    "wrr": "1.0.0"
   },
   "peerDependencies": {},
   "peerDependenciesMeta": {},