@zakkster/lite-pick 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-pick` are documented here. The format follows
+[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.1.0] - 2026-09-23
+
+M1: the first strategy, RoundRobin (ROADMAP.md M1). The M0 harness stubs become real,
+strategy-bearing gates.
+
+### Added
+
+- `RoundRobinBalancer extends BalancerBase` -- the baseline strategy. A wrapping cursor
+  that forward-scans the shared eligibility view, skipping down nodes, to hand each LIVE
+  endpoint an equal share in index order (true round-robin over the live set, not the raw
+  index space). Owns only its cursor; O(1) amortized (O(cap) worst case under sparse
+  eligibility); 0 B/op on `pick()`; fail-closed `PICK_NONE` when the pool is down.
+- `test/RoundRobin.test.js` -- boundary + behaviour suite (11 tests): perfect fairness,
+  round-robin order, skips down nodes, fail-closed, single-node, recovery, and a
+  never-returns-a-down-index proof under 200k picks of adversarial eligibility churn.
+- Gates wired for RoundRobin: `torture.mjs` (retention + 0 B/op `pick()` phase),
+  `test/perf/PerfGate.test.mjs` (`zgcSuite` scenario + a `mustFail` teeth-check),
+  `test/witness.mjs` (throughput flatness across the pool sweep), `test/balance.mjs`
+  (imbalance 1.0000 on all-up, zero dead picks under partial eligibility vs the
+  `i++ % n` foil's dead-pick trap).
+- `benchmark/Matrix.mjs` -- the SUBJECTS registration point (RoundRobin + the `i++ % n`
+  foil), a parity-check throughput slice ahead of the full M6 suite.
+- `decisions/0003-roundrobin-bitmap-scan.md` -- the stateless bitmap-scan (Option A) vs
+  maintained eligible-set (Option B) fork; A now, B revisited at M3 with the lite-o1 peer.
+
+### Changed
+
+- Version 0.0.1 -> 0.1.0 across `package.json`, `Pick.js` `VERSION`, and `llms.txt`.
+- Documented the composition model as OPTIONAL PEER dependencies (`peerDependenciesMeta`,
+  the LiteQuery model) -- zero HARD deps, never inlined/forked; kernel runs with zero peers.
+
+## [0.0.1] - 2026-09-22
+
+M0 scaffold: the substrate seams only, no strategy yet (ROADMAP.md M0). This release
+establishes the shared machinery every strategy (M1+) will ride and locks the ratified
+ownership boundary in place before any `pick()` is written.
+
+### Added
+
+- `Pick.js` single-file ESM kernel with:
+  - `VERSION` -- the source-of-truth version stamp (three-place sync with package.json + llms.txt).
+  - `PICK_NONE` (-1) -- the fail-closed sentinel: no endpoint is ever a dead pick.
+  - `Prng` -- an instance-local, deterministic xorshift32 (`next` / `nextBelow` / `reset`),
+    so a strategy can draw on the hot path without `Math.random` and the balance
+    benchmark stays reproducible.
+  - `BalancerBase` -- the shared eligibility seam: a fixed-capacity pool over a SHARED,
+    read-only `Uint8Array` eligibility view (written by `@zakkster/lite-di-health` /
+    circuit breakers, read by `pick()`), an O(1) `live` count, `isEligible` / `setEligible`,
+    and an abstract `pick()` that throws until a strategy overrides it.
+- `Pick.d.ts` -- TypeScript declarations for the substrate surface.
+- `llms.txt` -- LLM-oriented API + design summary.
+- Test harness: `test/Base.test.js` (substrate boundary suite), `test/torture.mjs`
+  (lite-leak retention + lite-gc-profiler 0 B/op on the substrate hot path),
+  `test/perf/PerfGate.test.mjs` (lite-perf-gate `zgcSuite` hard gate + a `mustFail`
+  teeth-check), `test/witness.mjs` (throughput flatness), `test/balance.mjs` (the
+  random-foil baseline the strategy ceilings assert against from M1), and the
+  `test/types` tsc surface check.
+- `decisions/0001-selection-kernel-boundary.md` -- the five ratified ownership forks.
+- `decisions/0002-anti-flapping.md` -- hysteresis/dwell/backoff on routing-state transitions.
+- `RESEARCH.md`, `ROADMAP.md`, `README.md`, `LICENSE`.
+
+### Notes
+
+- Zero runtime dependencies. ESM only. `sideEffects: false`. Node >= 18.
+- Published metadata points at `PeshoVurtoleta/lite-pick`.
+- Next: **M1 RoundRobin** (0.1.0) -- the first strategy, landing the throughput witness
+  and the balance gate.
+
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Pick.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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.
+ */
+
+/** The single source-of-truth version stamp. */
+export const VERSION: string;
+
+/**
+ * Fail-closed sentinel returned by `pick()` when no endpoint is eligible.
+ * A strategy never returns a down index; `PICK_NONE` (-1) means "no endpoint".
+ */
+export const PICK_NONE: -1;
+
+/**
+ * Instance-local, deterministic xorshift32 PRNG. Zero-alloc per step; seedable and
+ * `reset()`-able so the balance benchmark stays reproducible.
+ */
+export class Prng {
+    /** @param seed 32-bit seed; 0 is remapped to the default. */
+    constructor(seed?: number);
+    /** One xorshift32 step -> a uint32 in [1, 2^32). */
+    next(): number;
+    /** A uint32 in [0, n). */
+    nextBelow(n: number): number;
+    /** Restore the original seed. */
+    reset(): void;
+}
+
+/**
+ * The shared eligibility seam for every strategy. Owns the fixed capacity, a reference
+ * to a shared read-only eligibility `Uint8Array` (written by @zakkster/lite-di-health /
+ * circuit breakers, read by `pick()`), and an O(1) live count. Subclasses implement
+ * `pick()`; the base `pick()` throws.
+ */
+export class BalancerBase {
+    /**
+     * @param capacity endpoint count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     */
+    constructor(capacity: number, eligible: Uint8Array);
+    /** Endpoint count (fixed at construction). */
+    readonly capacity: number;
+    /** Number of currently eligible endpoints (O(1)). */
+    readonly live: number;
+    /** True iff endpoint `i` is currently pickable. */
+    isEligible(i: number): boolean;
+    /** Cold path: mark endpoint `i` up/down, keeping the live count exact. */
+    setEligible(i: number, up: boolean): void;
+    /** Choose an endpoint index, or `PICK_NONE`. Abstract in the base (throws). */
+    pick(): number;
+}
+
+/**
+ * RoundRobinBalancer -- the baseline strategy (M1). A wrapping cursor that forward-scans
+ * the shared eligibility view, skipping down nodes, to hand each LIVE endpoint an equal
+ * share in index order. Owns only its cursor; O(1) amortized, 0 B/op on `pick()`.
+ */
+export class RoundRobinBalancer extends BalancerBase {
+    /**
+     * @param capacity endpoint count (fixed).
+     * @param eligible shared view: 1 = pickable, 0 = down (length >= capacity).
+     */
+    constructor(capacity: number, eligible: Uint8Array);
+    /** Next eligible index in round-robin order, or `PICK_NONE` when the pool is down. */
+    pick(): number;
+}

package/Pick.js

@@ -0,0 +1,204 @@
+/**
+ * @zakkster/lite-pick -- zero-GC load-balancing SELECTION KERNEL.
+ *
+ * M1 (0.1.0): the substrate seams + the FIRST strategy, RoundRobin. 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.
+ *   - Prng           an instance-local, deterministic xorshift32 (seeded, reset()).
+ *   - BalancerBase   the eligibility seam: a fixed-capacity pool over a SHARED,
+ *                    read-only Uint8Array eligibility view (1 = pickable, 0 = down)
+ *                    written by @zakkster/lite-di-health / circuit breakers and only
+ *                    READ here, plus an O(1) live count and a cold-path setEligible().
+ *                    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.
+ *
+ * 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].
+ *
+ * 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';
+
+/**
+ * Fail-closed sentinel returned by pick() when no endpoint is eligible.
+ * null is not zero: a strategy never picks a down node "to be safe".
+ */
+export const PICK_NONE = -1;
+
+/**
+ * Prng -- instance-local, deterministic xorshift32.
+ *
+ * One PRNG step is a few integer ops and allocates nothing, so a strategy can draw
+ * on the hot path without touching Math.random (which is neither seedable nor
+ * gate-friendly) and the balance benchmark (the anchor) stays reproducible.
+ *
+ * Marsaglia's xorshift32: full period 2^32 - 1, never yields 0 once seeded non-zero.
+ */
+export class Prng {
+    /**
+     * @param {number} [seed=0x9e3779b9] 32-bit seed (0 is remapped to the default,
+     *   since xorshift stuck at 0 stays 0).
+     */
+    constructor(seed = 0x9e3779b9) {
+        const s = seed >>> 0;
+        this._seed = s === 0 ? 0x9e3779b9 : s;
+        this._s = this._seed;
+    }
+
+    /** One xorshift32 step -> a uint32 in [1, 2^32). Zero-alloc, deterministic. */
+    next() {
+        let x = this._s;
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        this._s = x >>> 0;
+        return this._s;
+    }
+
+    /** A uint32 in [0, n) via multiply-shift (no modulo bias for the balance gate). */
+    nextBelow(n) {
+        // (rand * n) >>> 32 -- unbiased enough for selection, one Math.imul-free mul.
+        return Math.floor((this.next() / 4294967296) * n);
+    }
+
+    /** Restore the original seed, so a benchmark run is byte-for-byte repeatable. */
+    reset() {
+        this._s = this._seed;
+    }
+}
+
+/**
+ * BalancerBase -- the shared eligibility seam for every strategy.
+ *
+ * It owns ONLY: the fixed capacity, a reference to the caller/sibling-owned eligibility
+ * Uint8Array (never copied), and an O(1) `_live` count maintained on the cold setEligible()
+ * path so a strategy can fail closed in O(1). It never allocates after construction and
+ * never calls into a health source -- writers mutate `eligible` at their own cadence; pick()
+ * only reads it.
+ *
+ * Subclasses (M1+) implement pick(). BalancerBase.pick() throws, so an unfinished strategy
+ * fails loudly rather than silently returning a dead index.
+ */
+export class BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed; add/remove is a cold rebuild).
+     * @param {Uint8Array} eligible  1 = pickable, 0 = down. SHARED, read-only to pick().
+     *   Written by @zakkster/lite-di-health probes / circuit breakers / admin.
+     */
+    constructor(capacity, eligible) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError('[lite-pick] capacity must be an integer >= 1');
+        }
+        if (!(eligible instanceof Uint8Array) || eligible.length < capacity) {
+            throw new RangeError('[lite-pick] eligible must be a Uint8Array of length >= capacity');
+        }
+        this._cap = capacity;
+        this._eligible = eligible;
+        this._live = 0;
+        for (let i = 0; i < capacity; i++) if (eligible[i]) this._live++;
+    }
+
+    /** Endpoint count (fixed at construction). */
+    get capacity() {
+        return this._cap;
+    }
+
+    /** Number of currently eligible endpoints (O(1), cold-path maintained). */
+    get live() {
+        return this._live;
+    }
+
+    /** True iff endpoint i is currently pickable. O(1), zero-alloc. */
+    isEligible(i) {
+        return i >= 0 && i < this._cap && this._eligible[i] !== 0;
+    }
+
+    /**
+     * Cold path: mark endpoint i up/down (delegated FROM lite-di-health), keeping the
+     * shared view and the O(1) `_live` count in lockstep. Idempotent. Zero-alloc.
+     * @param {number} i
+     * @param {boolean} up
+     */
+    setEligible(i, up) {
+        if (i < 0 || i >= this._cap) {
+            throw new RangeError('[lite-pick] index out of range: ' + i);
+        }
+        const was = this._eligible[i];
+        const now = up ? 1 : 0;
+        if (was !== now) {
+            this._eligible[i] = now;
+            this._live += now ? 1 : -1;
+        }
+    }
+
+    /**
+     * Choose an endpoint index, or PICK_NONE when the whole pool is down (fail closed).
+     * Not implemented in the base -- M1+ strategies override this.
+     * @returns {number}
+     */
+    pick() {
+        throw new Error('[lite-pick] BalancerBase.pick() is abstract -- use a strategy (M1+)');
+    }
+}
+
+/**
+ * RoundRobinBalancer -- the baseline strategy (M1).
+ *
+ * A single wrapping cursor over the shared eligibility view. `pick()` advances the
+ * cursor and forward-scans, skipping down nodes (`eligible[i] === 0`), until it lands
+ * on the next pickable endpoint. Over a run of picks this hands each eligible endpoint
+ * an equal share, in index order -- true round-robin over the LIVE set, not the raw
+ * index space (the distinction from a naive `i++ % n`, which would return down nodes).
+ *
+ * Ownership (ADR 0001): it owns ONLY the integer cursor. Eligibility is the shared,
+ * read-only Uint8Array from BalancerBase; `pick()` reads it and returns an index. No
+ * SparseSet of eligibles is maintained -- ADR 0003 chose the stateless bitmap-scan path
+ * (Option A) for M1; the lite-o1 RandomSet/SparseSet substrate (Option B, an optional
+ * PEER dep) arrives at M3 when P2C needs a random eligible draw.
+ *
+ * Bound: O(1) amortized (one step when the next index is eligible), worst case O(cap)
+ * when eligibility is sparse (bounded by a single wrap -- `_live > 0` guarantees a hit
+ * within `cap` steps). Steady-state pick(): a compare-wrap loop over the view, one
+ * cursor write. No object, closure, string, or array is created -- proven 0 B/op by
+ * test/torture.mjs and test/perf/PerfGate.test.mjs.
+ */
+export class RoundRobinBalancer extends BalancerBase {
+    /**
+     * @param {number} capacity  endpoint count (fixed; add/remove is a cold rebuild).
+     * @param {Uint8Array} eligible  shared view: 1 = pickable, 0 = down (length >= capacity).
+     */
+    constructor(capacity, eligible) {
+        super(capacity, eligible);
+        // Last index returned. -1 so the first pick starts the scan at index 0.
+        this._cursor = -1;
+    }
+
+    /**
+     * Next eligible endpoint index in round-robin order, or PICK_NONE when the whole
+     * pool is down (fail closed). O(1) amortized, O(cap) worst case, zero-alloc.
+     * @returns {number}
+     */
+    pick() {
+        if (this._live === 0) return PICK_NONE;   // whole pool down: fail closed
+        const cap = this._cap, el = this._eligible;
+        let i = this._cursor;
+        for (let steps = 0; steps < cap; steps++) {
+            i++;
+            if (i >= cap) i = 0;                   // wrap (cap is caller-given, not power-of-2)
+            if (el[i]) { this._cursor = i; return i; }
+        }
+        // Unreachable while `_live` is exact (setEligible maintains it): a positive live
+        // count guarantees a set bit within one wrap. Fail closed rather than loop.
+        return PICK_NONE;
+    }
+}

package/README.md

@@ -0,0 +1,140 @@
+# @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.
+
+[![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)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-pick?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-pick)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-pick?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-pick)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-pick?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-pick)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+
+## The load balancer the ecosystem was missing
+
+The npm landscape has old algorithm libraries (`load-balancers`, `loadbalance`, `wrr`) and heavy full proxies -- but **no package that ships a provably zero-GC `pick()` path with a measured balance-quality anchor.** Most algorithm libraries use ordinary objects and arrays and quietly allocate under sustained high call rates (millions of picks/sec in worker fan-out, high-QPS internal services, client-side routing). `lite-pick` fills that gap: a small, dependency-free, ESM-first selection **kernel** you drop into an HTTP client, a worker pool, or a custom proxy -- and it proves its two claims instead of asserting them.
+
+- **The `pick()` is the product.** One hot-path primitive: given a pool of endpoints, return the index of the one to use. Every strategy (round-robin, weighted, power-of-two-choices, least-connections, latency-aware, consistent-hash, bounded-load) is a different `pick()` over the same substrate.
+- **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).
+
+```bash
+npm install @zakkster/lite-pick
+```
+
+## RoundRobin (v0.1.0)
+
+```js
+import { RoundRobinBalancer, PICK_NONE } from '@zakkster/lite-pick';
+
+// A pool of 4 endpoints. The eligibility view is SHARED and read-only to pick():
+// lite-di-health probes / circuit breakers write it; the balancer only reads it.
+const eligible = Uint8Array.from([1, 1, 0, 1]); // endpoint 2 is down
+
+const rr = new RoundRobinBalancer(4, eligible);
+
+rr.pick();            // -> 0
+rr.pick();            // -> 1
+rr.pick();            // -> 3   (skips the down endpoint 2, never returns it)
+rr.pick();            // -> 0   (wraps)
+
+// A health source marks endpoint 2 back up (cold path; live count stays exact).
+rr.setEligible(2, true);
+rr.pick();            // -> 1, then 2, then 3, ... now that 2 is eligible
+
+// Whole pool down -> fail closed, never a dead pick.
+for (let i = 0; i < 4; i++) rr.setEligible(i, false);
+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.
+
+## The substrate (under every strategy)
+
+```js
+import { BalancerBase, Prng, PICK_NONE, VERSION } from '@zakkster/lite-pick';
+
+// A pool of 4 endpoints. The eligibility view is SHARED and read-only to pick():
+// lite-di-health probes / circuit breakers write it; the balancer only reads it.
+const eligible = Uint8Array.from([1, 1, 0, 1]); // endpoint 2 is down
+
+const base = new BalancerBase(4, eligible);
+base.capacity;        // -> 4
+base.live;            // -> 3  (O(1), cold-path maintained)
+base.isEligible(2);   // -> false  (out-of-range is false too, never a throw)
+
+// Cold path: a health source marks endpoint 2 back up. live stays exact.
+base.setEligible(2, true);
+base.live;            // -> 4
+
+// A deterministic PRNG so the balance benchmark is reproducible (no Math.random
+// on a gated path). Strategies draw from this on the hot path, zero-alloc.
+const rng = new Prng(0x1234abcd);
+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.1.0'
+```
+
+`BalancerBase.pick()` is **abstract** -- it throws, so an unfinished strategy fails loudly rather than returning a dead index; `RoundRobinBalancer` (above) overrides it. Here is the shape the headline **P2C** strategy will take (M3), for orientation:
+
+```js
+// SHAPE ONLY -- not shipped until M3. Two random eligible draws, return the lower
+// in-flight load. One extra probe over random buys the ln ln n balance ceiling.
+class P2cBalancer extends BalancerBase {
+  constructor(capacity, eligible, inflight, seed) {
+    super(capacity, eligible);
+    this._inflight = inflight;  // caller-owned Uint32Array; pick() only reads it
+    this._rng = new Prng(seed);
+  }
+  pick() {
+    if (this.live === 0) return PICK_NONE;      // fail closed
+    const a = this._draw(), b = this._draw();   // two distinct eligible draws
+    return this._inflight[b] < this._inflight[a] ? b : a;
+  }
+}
+```
+
+## Design ownership (ratified before any strategy)
+
+lite-pick owns **no mutable state it can avoid owning** ([ADR 0001](./decisions/0001-selection-kernel-boundary.md)):
+
+| Concern | Owner | lite-pick's role |
+| --- | --- | --- |
+| Liveness / eligibility | `@zakkster/lite-di-health` writes a shared `Uint8Array` | **reads** it, zero-copy |
+| Circuit state | `@zakkster/lite-statechart` (consumed) | never built in; sees only the bit |
+| In-flight / rtt counters | caller-owned `Uint32Array` / `Float64Array` | **reads** them; pure `pick()` |
+| Whole pool down | -- | fail-closed: returns `PICK_NONE` (-1) |
+| Routing flap | the layer that writes the shared view | hysteresis/dwell ([ADR 0002](./decisions/0002-anti-flapping.md)); `pick()` stays greedy |
+
+**In-process first** (workers, DI services, ECS-style systems); remote HTTP is served by a thin optional adapter that owns the observation loop and writes the same shared views. The zero-GC contract stays strict because the kernel never touches the request lifecycle.
+
+## Composes with
+
+The moat is not the algorithms -- it is that lite-pick wires already-proven zero-GC parts of the suite: [`lite-di-health`](https://www.npmjs.com/package/@zakkster/lite-di-health) (liveness), [`lite-o1`](https://www.npmjs.com/package/@zakkster/lite-o1) (`RandomSet` / `AliasTable` / `RingLog` substrate), [`lite-logn`](https://www.npmjs.com/package/@zakkster/lite-logn) (exact least-conn heap / Fenwick weights), [`lite-lru`](https://www.npmjs.com/package/@zakkster/lite-lru) (sticky affinity), [`lite-statechart`](https://www.npmjs.com/package/@zakkster/lite-statechart) (breaker), [`lite-query`](https://www.npmjs.com/package/@zakkster/lite-query) (the fetcher adapter), and [`lite-await`](https://www.npmjs.com/package/@zakkster/lite-await) (hedging). **None is a hard dependency** -- each is an *optional peer* (`peerDependenciesMeta.optional`), every seam is duck-typed over a shared TypedArray, and the kernel runs with zero peers installed.
+
+## Gates
+
+Every strategy session must pass, no exceptions:
+
+```bash
+npm test           # node:test boundary suite
+npm run test:types # tsc type-surface check (Pick.d.ts vs runtime)
+npm run torture    # lite-leak retention + lite-gc-profiler 0 B/op (needs --expose-gc)
+npm run test:perf  # lite-perf-gate HARD zero-alloc gate + a mustFail teeth-check
+npm run witness    # pick throughput flatness across a pool-size sweep
+npm run balance    # peak-to-average vs the strategy ceiling + random foil (the anchor)
+npm run verify     # all of the above
+```
+
+The zero-GC proof is two complementary tools kept separate (the suite's torture-harness discipline): a soak tester (`torture.mjs`, [`@zakkster/lite-leak`](https://www.npmjs.com/package/@zakkster/lite-leak) + [`@zakkster/lite-gc-profiler`](https://www.npmjs.com/package/@zakkster/lite-gc-profiler)) and a node:test-native hard gate (`test/perf/PerfGate.test.mjs`, [`@zakkster/lite-perf-gate`](https://www.npmjs.com/package/@zakkster/lite-perf-gate)), which includes a `mustFail` scenario proving the instrument has teeth.
+
+## License
+
+MIT (c) Zahary Shinikchiev

package/llms.txt

@@ -0,0 +1,80 @@
+# @zakkster/lite-pick
+
+Version: 0.1.0
+License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
+Node: >= 18.
+
+## What it is
+
+A zero-GC load-balancing SELECTION KERNEL: one hot `pick()` that returns an endpoint
+INDEX over a fixed pool and allocates zero bytes on the steady-state path. It is a pure
+selector, never a proxy -- it CONSUMES health and circuit state (it never owns them),
+reading pre-allocated views that siblings or the caller write, and returning an integer.
+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.
+
+## Design ownership (decisions/0001, 0002)
+
+- IN-PROCESS first (workers, DI services); remote HTTP is a thin optional adapter.
+- Eligibility is a SHARED read-only `Uint8Array` (1 = pickable, 0 = down), WRITTEN by
+  @zakkster/lite-di-health / circuit breakers, only READ by `pick()`. Zero-copy.
+- Load counters are CALLER-OWNED typed arrays (`Uint32Array` inflight, `Float64Array`
+  rtt/EWMA); the kernel holds no request state. `pick()` is pure-read.
+- The circuit breaker is CONSUMED (@zakkster/lite-statechart), never built in.
+- Fail-closed: whole pool down -> `pick()` returns `PICK_NONE` (-1), never a dead pick.
+- Anti-flapping is a first-class rule: routing-STATE transitions apply hysteresis/dwell;
+  `pick()` itself stays greedy and stateless.
+
+## Exports (from the single main file Pick.js)
+
+- `VERSION` -- string. The source-of-truth version stamp (synced with package.json + this file).
+- `PICK_NONE` -- the -1 fail-closed sentinel returned by `pick()` when no endpoint is eligible.
+- `Prng` -- class. Instance-local deterministic xorshift32.
+  - `new Prng(seed = 0x9e3779b9)` -- 0 is remapped to the default.
+  - `next()` -> uint32 in [1, 2^32). One xorshift32 step, zero-alloc.
+  - `nextBelow(n)` -> uint32 in [0, n).
+  - `reset()` -> void. Replays the original seed's stream (reproducible benches).
+- `BalancerBase` -- class. The shared eligibility seam; strategies (M1+) subclass it.
+  - `new BalancerBase(capacity, eligible)` -- `eligible` is a shared `Uint8Array`
+    (length >= capacity) owned/written externally; throws `RangeError` on a bad capacity
+    or an undersized / non-Uint8Array view.
+  - `capacity` -- readonly number. Fixed endpoint count.
+  - `live` -- readonly number. Currently eligible endpoints (O(1), cold-path maintained).
+  - `isEligible(i)` -> boolean. O(1); out-of-range is `false`, never a throw.
+  - `setEligible(i, up)` -> void. Cold path; keeps `live` exact and is idempotent; throws
+    `RangeError` on an out-of-range index.
+  - `pick()` -> number. ABSTRACT in the base (throws); overridden by each strategy.
+- `RoundRobinBalancer extends BalancerBase` -- class. The baseline strategy (M1).
+  - `new RoundRobinBalancer(capacity, eligible)` -- same shared-eligibility contract as the base.
+  - `pick()` -> number. Next eligible index in round-robin order (a wrapping cursor that
+    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).
+
+## Gates (every session)
+
+- `npm run torture`   -- `node --expose-gc test/torture.mjs`: lite-leak retention +
+  lite-gc-profiler 0 B/op on the hot path.
+- `npm run test:perf` -- `node --expose-gc --max-semi-space-size=4 --test test/perf/PerfGate.test.mjs`:
+  lite-perf-gate `zgcSuite` HARD zero-alloc gate + a `mustFail` teeth-check.
+- `npm run witness`   -- pick throughput flatness across a pool-size sweep.
+- `npm run balance`   -- peak-to-average load vs the strategy ceiling + random foil (the anchor).
+- `npm test` / `npm run test:types` -- node:test boundary suite + tsc type-surface check.
+
+## Composes with
+
+@zakkster/lite-di-health (eligibility writer), lite-statechart (breaker), lite-o1
+(RandomSet / AliasTable / RingLog substrate), lite-logn (exact least-conn heap / Fenwick
+weights), lite-lru (sticky affinity), lite-fastbit32 (optional small-pool bitset peer),
+lite-query (the fetcher adapter), lite-await (hedging), lite-worker-pool (in-process
+consumer), lite-di-signal / lite-signal-decorators (observability). None is a HARD
+dependency -- each is an OPTIONAL PEER dep (peerDependenciesMeta.optional, the LiteQuery
+model), every seam is duck-typed over a shared TypedArray, and the kernel runs with zero
+peers installed. A peer is declared only when a shipped code path imports it.

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@zakkster/lite-pick",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "version": "0.1.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",
+  "module": "./Pick.js",
+  "types": "./Pick.d.ts",
+  "exports": {
+    ".": {
+      "types": "./Pick.d.ts",
+      "node": "./Pick.js",
+      "import": "./Pick.js",
+      "default": "./Pick.js"
+    }
+  },
+  "files": [
+    "Pick.js",
+    "Pick.d.ts",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:types": "tsc -p test/types/tsconfig.json",
+    "torture": "node --expose-gc test/torture.mjs",
+    "witness": "node test/witness.mjs",
+    "balance": "node test/balance.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",
+    "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run balance && npm run test:perf"
+  },
+  "keywords": [
+    "load-balancer",
+    "load-balancing",
+    "load-balance",
+    "balancer",
+    "pick",
+    "selection",
+    "endpoint-selection",
+    "server-selection",
+    "round-robin",
+    "weighted-round-robin",
+    "smooth-weighted-round-robin",
+    "wrr",
+    "power-of-two-choices",
+    "p2c",
+    "two-random-choices",
+    "least-connections",
+    "least-conn",
+    "shortest-expected-delay",
+    "sed",
+    "never-queue",
+    "peak-ewma",
+    "latency-aware",
+    "consistent-hashing",
+    "maglev",
+    "bounded-load",
+    "weighted-random",
+    "sticky-routing",
+    "client-side-load-balancing",
+    "in-process",
+    "worker-pool",
+    "health-check",
+    "circuit-breaker",
+    "fail-closed",
+    "anti-flapping",
+    "hysteresis",
+    "deterministic",
+    "xorshift32",
+    "prng",
+    "zero-gc",
+    "zero-allocation",
+    "gc",
+    "garbage-collection",
+    "typed-array",
+    "performance",
+    "high-throughput",
+    "lightweight",
+    "tree-shakeable",
+    "esm",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-perf-gate": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {},
+  "peerDependenciesMeta": {},
+  "homepage": "https://github.com/PeshoVurtoleta/lite-pick#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-pick.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-pick/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false
+}