@zakkster/lite-pick 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.5.0] - 2026-09-23
+
+M5: the ergonomic request layer at the `@zakkster/lite-pick/pool` subpath -- dispatch/settle
+in-flight counters + distinct-endpoint failover + a duck-typed query-cache fetcher (ROADMAP.md M5).
+
+### Added
+
+- `@zakkster/lite-pick/pool` (`Pool.js`) -- a new SUBPATH export (the kernel `Pick.js` stays a
+  single 0 B/op file; the async layer lives outside it, the lite-query `/stream` + `/await`
+  precedent, ADR 0007).
+- `Pool` -- wraps a balancer + the caller-owned in-flight view. `run(fn, opts?)` picks an endpoint,
+  increments in-flight on dispatch, awaits `fn(endpoint, signal)`, decrements on settle (in a
+  `finally` -- net-zero per run, even on throw). On a thrown error it keeps the failed endpoint's
+  count ELEVATED and re-picks, so a load-aware strategy (P2C/LeastConn/SED/NQ) steers the next
+  attempt to a DISTINCT endpoint -- up to `opts.tries` attempts (default 1 = no failover), then
+  rejects with the last error. Rejects a `code:'LITE_PICK_NONE'` error when no endpoint is eligible;
+  `opts.signal` is passed to `fn` and, once aborted after a failure, stops failover. NOT a 0 B/op
+  path (the kernel `pick()` is) -- a normal async wrapper, disclosed.
+- `liteQueryFetcher(pool, perEndpoint, opts?)` -- returns a `({ key, signal }) => Promise` fetcher
+  for a query cache (lite-query's `fetcher`, or any fetcher-shaped consumer). Imports NOTHING from
+  lite-query -- duck-typed, so `peerDependencies` stays empty. `opts.tries` is the spatial failover
+  count. BOUNDARY: Pool owns SPATIAL failover across the pool; the cache owns TEMPORAL retry/backoff.
+- `test/Pool.test.js` -- 12 tests: dispatch/settle in-flight balance (success AND throw), fail-closed
+  coding, distinct-endpoint failover, tries exhaustion (last error), abort-stops-failover, signal
+  passthrough, a 200-way CONCURRENT-consistency check (in-flight drains to all-zero -- no leak), and
+  the duck-typed fetcher.
+- `Pool.d.ts` + `test/types/pool.test-d.ts` -- the typed surface (the type-test tsconfig gains the
+  `DOM` lib for `AbortSignal`).
+- `demo/fanout.mjs` (`npm run demo`) -- the integration moat: least-connections fan-out over a flaky
+  pool with a replica killed mid-run, proving 0 dead picks + 0 leaked in-flight + live failover, and
+  showing the lite-query fetcher wiring. (`demo/` is not in `files[]`.)
+- `decisions/0007-pool-adapter.md` -- the /pool-subpath home, spatial-vs-temporal retry ownership,
+  the explicit 0 B/op boundary, and the duck-typed (zero-peer) fetcher.
+
+### Changed
+
+- Version 0.4.0 -> 0.5.0 across `package.json`, `Pick.js` `VERSION` (re-exported by `Pool.js`), and
+  `llms.txt`. `exports` gains `./pool`; `files[]` gains `Pool.js` + `Pool.d.ts`.
+- `peerDependencies` stays `{}` -- the fetcher adapter is duck-typed (ADR 0007 Fork 4).
+
 ## [0.4.0] - 2026-09-23
 
 M4: the exact LeastConn family (IPVS `lc` / `sed` / `nq` made zero-GC) + the seeded invariant

package/Pick.js

@@ -37,11 +37,16 @@
  *   [planned]. The EXACT-O(log n) fewest-in-flight variant is a deferred @zakkster/lite-logn
  *   BinaryHeap optional-peer seam (decisions/0006), not this exact-O(cap) scan.
  *
+ * M5 (0.5.0) adds the ergonomic request layer at the @zakkster/lite-pick/pool subpath (a
+ * SEPARATE file, Pool.js -- the async dispatch/settle counter wrapper + distinct-endpoint
+ * failover + a duck-typed query-cache fetcher). This kernel file stays PURE and 0 B/op; the
+ * async Pool lives outside it (decisions/0007, the lite-query /stream + /await subpath precedent).
+ *
  * 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.4.0';
+export const VERSION = '0.5.0';
 
 /**
  * Fail-closed sentinel returned by pick() when no endpoint is eligible.

package/Pool.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @zakkster/lite-pick/pool -- TypeScript declarations (M5).
+ *
+ * The async request layer over the 0 B/op kernel: dispatch/settle in-flight counter
+ * ergonomics + distinct-endpoint failover, plus a duck-typed query-cache fetcher adapter.
+ */
+
+/** The source-of-truth version stamp (re-exported from the core). */
+export const VERSION: string;
+
+/** The minimal balancer shape Pool drives (any lite-pick strategy satisfies it). */
+export interface Balancer {
+    pick(): number;
+    readonly capacity: number;
+    readonly live: number;
+}
+
+/** Options for `Pool.run`. */
+export interface RunOptions {
+    /** Passed to `fn`; when already aborted after a failure, stops failover (abort propagates). */
+    signal?: AbortSignal;
+    /** Max distinct-endpoint attempts (default 1 = no failover). */
+    tries?: number;
+}
+
+/**
+ * Pool -- wraps a balancer + the caller-owned in-flight view with dispatch/settle counter
+ * ergonomics and distinct-endpoint failover. `run` increments in-flight on dispatch, decrements
+ * on settle, and on a thrown error keeps the failed endpoint elevated so a load-aware strategy
+ * steers the next attempt elsewhere. NOT a 0 B/op path (the kernel `pick()` is).
+ */
+export class Pool {
+    /**
+     * @param balancer a lite-pick strategy (or duck-compatible) with `pick()`, `capacity`, `live`.
+     * @param inflight the SAME caller-owned in-flight view the balancer reads (length >= capacity).
+     */
+    constructor(balancer: Balancer, inflight: Uint32Array);
+    /** The wrapped balancer. */
+    readonly balancer: Balancer;
+    /** The shared in-flight view Pool increments on dispatch and decrements on settle. */
+    readonly inflight: Uint32Array;
+    /**
+     * Run `fn` against a chosen endpoint (in-flight incremented on dispatch, decremented on
+     * settle), with up to `opts.tries` distinct-endpoint failover attempts on a throw. Rejects
+     * with a `LITE_PICK_NONE`-coded error when no endpoint is eligible, or the last error when
+     * every attempt fails.
+     */
+    run<T>(fn: (endpoint: number, signal?: AbortSignal) => Promise<T> | T, opts?: RunOptions): Promise<T>;
+}
+
+/** Context passed to the per-endpoint fetcher. */
+export interface PerEndpointContext {
+    endpoint: number;
+    key: any;
+    signal?: AbortSignal;
+}
+
+/** Context a query cache passes to the produced fetcher (lite-query's fetcher shape). */
+export interface FetcherContext {
+    key: any;
+    signal?: AbortSignal;
+}
+
+/** Options for `liteQueryFetcher`. */
+export interface FetcherOptions {
+    /** Spatial failover attempts across the pool (default 1). */
+    tries?: number;
+}
+
+/**
+ * Adapt a Pool into a `({ key, signal }) => Promise` fetcher for a query cache (lite-query, or
+ * any fetcher-shaped consumer). Imports nothing from lite-query -- duck-typed, zero peers.
+ */
+export function liteQueryFetcher<T>(
+    pool: Pool,
+    perEndpoint: (ctx: PerEndpointContext) => Promise<T> | T,
+    opts?: FetcherOptions,
+): (ctx: FetcherContext) => Promise<T>;

package/Pool.js

@@ -0,0 +1,147 @@
+/**
+ * @zakkster/lite-pick/pool -- the ergonomic request wrapper (M5).
+ *
+ *     import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+ *
+ * The kernel (Pick.js) is a PURE, 0 B/op selector: pick() -> index. Real callers also need
+ * the counter ergonomics ADR 0001 always promised -- increment in-flight on DISPATCH,
+ * decrement on SETTLE, and on a failure re-pick a DIFFERENT endpoint. That layer is async
+ * (it wraps the request lifecycle), so it lives OUTSIDE the single-file 0 B/op kernel, in
+ * this separate subpath file (the lite-query precedent: /stream, /await are subpath entries).
+ *
+ * BOUNDARY (decisions/0007): Pool owns SPATIAL failover -- try up to `tries` DISTINCT endpoints,
+ * once each, on a thrown error. It does NOT own TEMPORAL retry (backoff, staleness) -- that
+ * belongs to the caller / a query cache (lite-query's `retry`). The two never double-own: Pool
+ * moves ACROSS the pool once; the caller retries the whole operation over TIME.
+ *
+ * ZERO-GC boundary: the kernel `pick()` is 0 B/op; `Pool.run` is a NORMAL async wrapper -- the
+ * request it wraps already allocates a promise -- adding only O(1) integer counter ops per
+ * attempt plus one small per-run bookkeeping array. It is NOT held to the kernel's 0 B/op bar.
+ *
+ * Duck-typed, zero HARD deps, zero peers: `liteQueryFetcher` returns a value shaped like
+ * lite-query's `fetcher` (`({ key, signal }) => Promise`) WITHOUT importing lite-query, so
+ * `peerDependencies` stays empty and the same helper serves any fetcher-shaped consumer.
+ */
+
+import { VERSION, PICK_NONE } from './Pick.js';
+
+/** Re-exported so a /pool-only importer can read the version without importing the core. */
+export { VERSION };
+
+/**
+ * Pool -- wraps a balancer + the caller-owned in-flight view with the dispatch/settle counter
+ * ergonomics and distinct-endpoint failover. The balancer is duck-typed (anything with
+ * `pick() -> number`, `capacity`, and `live`), so a Pool can drive any lite-pick strategy or a
+ * compatible custom one.
+ */
+export class Pool {
+    /**
+     * @param {{ pick(): number, capacity: number, live: number }} balancer  a lite-pick
+     *   strategy (RoundRobin / SmoothWRR / P2C / LeastConn / SED / NQ) or a duck-compatible one.
+     * @param {Uint32Array} inflight  the SAME caller-owned in-flight view the balancer reads
+     *   (length >= balancer.capacity). Pool is the increment/decrement authority around run().
+     */
+    constructor(balancer, inflight) {
+        if (!balancer || typeof balancer.pick !== 'function' ||
+            typeof balancer.capacity !== 'number' || typeof balancer.live !== 'number') {
+            throw new TypeError('[lite-pick] Pool needs a balancer with pick(), capacity, and live');
+        }
+        if (!(inflight instanceof Uint32Array) || inflight.length < balancer.capacity) {
+            throw new RangeError('[lite-pick] inflight must be a Uint32Array of length >= balancer.capacity');
+        }
+        this._b = balancer;
+        this._inflight = inflight;
+    }
+
+    /** The wrapped balancer. */
+    get balancer() {
+        return this._b;
+    }
+
+    /** The shared in-flight view Pool increments on dispatch and decrements on settle. */
+    get inflight() {
+        return this._inflight;
+    }
+
+    /**
+     * Run `fn` against a chosen endpoint, incrementing its in-flight on dispatch and decrementing
+     * on settle. On a thrown error, keep the failed endpoint's count ELEVATED and re-pick -- so a
+     * load-aware strategy (P2C / LeastConn / SED / NQ) naturally steers the next attempt to a
+     * DIFFERENT endpoint -- up to `tries` attempts, then throw the last error. All counts this run
+     * raised are released before returning or throwing (net-zero per run).
+     *
+     * @template T
+     * @param {(endpoint: number, signal?: AbortSignal) => (Promise<T>|T)} fn  the per-endpoint work.
+     * @param {{ signal?: AbortSignal, tries?: 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).
+     * @returns {Promise<T>}
+     */
+    async run(fn, opts) {
+        if (typeof fn !== 'function') throw new TypeError('[lite-pick] Pool.run needs a function');
+        const rawTries = opts && opts.tries != null ? (opts.tries | 0) : 1;
+        const tries = rawTries > 0 ? rawTries : 1;
+        const signal = opts ? opts.signal : undefined;
+        const inflight = this._inflight, b = this._b;
+        const held = [];                 // endpoints incremented this run (kept elevated across failover)
+        let lastErr;
+        try {
+            for (let attempt = 0; attempt < tries; attempt++) {
+                const i = b.pick();
+                if (i === PICK_NONE) {
+                    if (attempt === 0) {
+                        const e = new Error('[lite-pick] no eligible endpoint');
+                        e.code = 'LITE_PICK_NONE';
+                        throw e;
+                    }
+                    break;               // pool went fully down mid-failover: surface the last error
+                }
+                inflight[i] = (inflight[i] + 1) >>> 0;
+                held.push(i);
+                try {
+                    return await fn(i, signal);
+                } catch (err) {
+                    lastErr = err;
+                    if (signal && signal.aborted) throw err;   // abort: stop failover, propagate
+                }
+                // keep inflight[i] elevated so the next pick() steers to a different endpoint
+            }
+            throw lastErr;
+        } finally {
+            for (let k = 0; k < held.length; k++) {
+                const j = held[k];
+                inflight[j] = inflight[j] > 0 ? inflight[j] - 1 : 0;
+            }
+        }
+    }
+}
+
+/**
+ * liteQueryFetcher -- adapt a Pool into a fetcher for a query cache (lite-query's `fetcher`, or
+ * any `({ key, signal }) => Promise` consumer). Duck-typed: imports NOTHING from lite-query.
+ *
+ *     const fetcher = liteQueryFetcher(pool, ({ endpoint, key, signal }) =>
+ *         fetch(urls[endpoint] + '/' + key[0], { signal }).then(r => r.json()), { tries: 2 });
+ *     query(qc, { key: ['users'], fetcher });
+ *
+ * The query cache owns TEMPORAL retry/backoff/staleness; the Pool owns SPATIAL failover across
+ * the pool (`tries`). Wiring both is deliberate layering, never double-ownership (ADR 0007).
+ *
+ * @template T
+ * @param {Pool} pool
+ * @param {(ctx: { endpoint: number, key: any, signal?: AbortSignal }) => (Promise<T>|T)} perEndpoint
+ * @param {{ tries?: number }} [opts]  spatial failover attempts (default 1).
+ * @returns {(ctx: { key: any, signal?: AbortSignal }) => Promise<T>}
+ */
+export function liteQueryFetcher(pool, perEndpoint, opts) {
+    if (!(pool instanceof Pool)) throw new TypeError('[lite-pick] liteQueryFetcher needs a Pool');
+    if (typeof perEndpoint !== 'function') {
+        throw new TypeError('[lite-pick] liteQueryFetcher needs a per-endpoint function');
+    }
+    const tries = opts && opts.tries != null ? opts.tries : 1;
+    return function fetcher(ctx) {
+        const key = ctx ? ctx.key : undefined;
+        const signal = ctx ? ctx.signal : undefined;
+        return pool.run((endpoint, sig) => perEndpoint({ endpoint, key, signal: sig }), { signal, tries });
+    };
+}

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.4.0 ships six strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family** -- on the substrate seams (`VERSION`, `PICK_NONE`, a deterministic `Prng`, and `BalancerBase`'s shared read-only eligibility view). The rest of the roster -- 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.5.0 ships six strategies -- `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family** -- 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 -- 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: M4 (v0.4.0).** Ships the substrate seams **plus `RoundRobinBalancer`, `SmoothWRRBalancer`, `P2cBalancer`, and the exact `LeastConnBalancer` / `SedBalancer` / `NqBalancer` family**. 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%**. New in M4: a **seeded invariant fuzzer** (`test/fuzz.mjs`) that asserts each strategy's state-synchronisation invariants after *every* op. See [ROADMAP.md](./ROADMAP.md) for the M4 -> 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), and LeastConn-family (0006) design forks.
+> **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.
 
 ```bash
 npm install @zakkster/lite-pick
@@ -169,6 +169,37 @@ VERSION;              // -> '0.4.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.
 
+## Wiring it up -- `@zakkster/lite-pick/pool` (v0.5.0)
+
+The kernel gives you `pick() -> index`. Real callers also need the counter ergonomics: **increment in-flight on dispatch, decrement on settle, and re-pick a *different* endpoint on failure.** That layer is async (it wraps the request), so it lives in a separate subpath -- `@zakkster/lite-pick/pool` -- and the kernel stays 0 B/op.
+
+```js
+import { LeastConnBalancer } from '@zakkster/lite-pick';
+import { Pool, liteQueryFetcher } from '@zakkster/lite-pick/pool';
+
+const eligible = Uint8Array.from([1, 1, 1, 1]);
+const inflight = new Uint32Array(4);
+const balancer = new LeastConnBalancer(4, eligible, inflight);
+const pool = new Pool(balancer, inflight);      // Pool is the inc/dec authority around run()
+
+// run(): pick -> inflight++ -> await fn -> inflight-- (in a finally). tries=2 re-picks a
+// DIFFERENT endpoint if the first throws (a load-aware strategy steers off the failed node).
+const res = await pool.run((i, signal) => fetch(urls[i], { signal }), { tries: 2 });
+
+// Drop-in for a query cache (lite-query, or any `({ key, signal }) => Promise` fetcher).
+// Duck-typed -- imports NOTHING from lite-query, so peerDependencies stays empty.
+const fetcher = liteQueryFetcher(pool,
+  ({ endpoint, key, signal }) => fetch(urls[endpoint] + '/' + key[0], { signal }).then(r => r.json()),
+  { tries: 2 });
+// query(qc, { key: ['users'], fetcher });
+```
+
+**Two layers, no overlap** ([ADR 0007](./decisions/0007-pool-adapter.md)): the pool owns **spatial** failover (try a different endpoint *now*); your query cache owns **temporal** retry (backoff, staleness). `run()` is a normal async wrapper -- it adds O(1) counter ops per attempt, **it is not held to the kernel's 0 B/op bar** (that's `pick()`). See it end-to-end -- least-conn fan-out over a flaky pool with a node killed mid-run, proving 0 dead picks and 0 leaked in-flight:
+
+```bash
+npm run demo
+```
+
 ## Design ownership (ratified before any strategy)
 
 lite-pick owns **no mutable state it can avoid owning** ([ADR 0001](./decisions/0001-selection-kernel-boundary.md)):

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-pick
 
-Version: 0.4.0
+Version: 0.5.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -107,6 +107,35 @@ n) fewest-in-flight variant is a deferred @zakkster/lite-logn `BinaryHeap` optio
     exists -- never queueing while a server is free -- else the SED minimum, else `PICK_NONE`.
     O(cap) worst case, O(1) when an early node is idle. 0 B/op.
 
+## Subpath: @zakkster/lite-pick/pool -- the ergonomic request layer (M5, Pool.js)
+
+The kernel is a PURE 0 B/op selector; `/pool` is the ASYNC layer over it -- dispatch/settle
+in-flight counter ergonomics + distinct-endpoint failover + a duck-typed query-cache fetcher.
+It is a SEPARATE subpath file (the lite-query /stream + /await precedent), NOT part of the
+0 B/op single-file kernel (decisions/0007). Zero HARD deps, zero peers: the fetcher adapter is
+duck-typed and imports NOTHING from lite-query.
+
+- `VERSION` -- string. Re-exported from the core (same three-place stamp).
+- `Pool` -- class. Wraps a balancer + the caller-owned in-flight view.
+  - `new Pool(balancer, inflight)` -- `balancer` is duck-typed (any `{ pick(): number, capacity,
+    live }` -- every lite-pick strategy qualifies); `inflight` is the SAME caller-owned Uint32Array
+    the balancer reads (length >= balancer.capacity). Throws on a bad balancer / undersized view.
+  - `balancer` / `inflight` -- readonly getters.
+  - `run(fn, opts?)` -> Promise. Picks an endpoint, increments its in-flight on DISPATCH, awaits
+    `fn(endpoint, signal)`, decrements on SETTLE (in a finally -- net-zero per run, even on throw).
+    On a thrown error it keeps the failed endpoint's count ELEVATED and re-picks, so a load-aware
+    strategy (P2C/LeastConn/SED/NQ) steers the next attempt to a DIFFERENT endpoint -- up to
+    `opts.tries` attempts (default 1 = no failover), then rejects with the LAST error. Rejects with
+    a `code:'LITE_PICK_NONE'` error when no endpoint is eligible. `opts.signal` is passed to `fn`;
+    once aborted after a failure, failover stops and the abort propagates. NOT a 0 B/op path (the
+    kernel `pick()` is): a normal async wrapper adding O(1) counter ops + one small per-run array.
+    BOUNDARY: Pool owns SPATIAL failover (across the pool); the caller / query cache owns TEMPORAL
+    retry (backoff, staleness). Never double-owned (decisions/0007).
+- `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.
+  Imports nothing from lite-query -- duck-typed, so `peerDependencies` stays empty.
+
 ## Gates (every session)
 
 - `npm run torture`   -- `node --expose-gc test/torture.mjs`: lite-leak retention +

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-pick",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.4.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.",
+  "version": "0.5.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",
   "module": "./Pick.js",
@@ -13,11 +13,19 @@
       "node": "./Pick.js",
       "import": "./Pick.js",
       "default": "./Pick.js"
+    },
+    "./pool": {
+      "types": "./Pool.d.ts",
+      "node": "./Pool.js",
+      "import": "./Pool.js",
+      "default": "./Pool.js"
     }
   },
   "files": [
     "Pick.js",
     "Pick.d.ts",
+    "Pool.js",
+    "Pool.d.ts",
     "llms.txt",
     "README.md",
     "CHANGELOG.md",
@@ -33,6 +41,7 @@
     "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",
+    "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"
   },
   "keywords": [