@zakkster/lite-pick 0.9.0 → 1.0.1

package/Pool.d.ts

@@ -8,13 +8,31 @@
 /** 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). */
+/**
+ * The minimal abort-signal shape Pool reads (L15). A structural type -- NOT the global DOM
+ * `AbortSignal` -- so a consumer compiling with `lib: ["ES2022"]` only (no DOM, no @types/node)
+ * still type-checks. A real `AbortSignal` (DOM or node:) satisfies it.
+ */
+export interface AbortLike {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    throwIfAborted?(): void;
+}
+
+/**
+ * The minimal balancer shape Pool drives. A KEYED strategy (ConsistentHash / BoundedLoad) exposes a
+ * static `KEYED === true` and takes `pick(keyHash)`; a LATENCY strategy (PeakEWMA) exposes a static
+ * `LATENCY === true` and takes `pick(now)`; a plain strategy takes `pick()`. All lite-pick strategies
+ * satisfy this (their required-arg `pick` is bivariant-compatible with the zero-arg method here).
+ */
 export interface Balancer {
-    /** `now` (PeakEwma clock) or `keyHash` (ConsistentHash/BoundedLoad) when supplied via opts. */
+    /** `now` (latency clock) or `keyHash` (keyed) when the strategy requires it, else no argument. */
     pick(arg?: number): number;
     readonly capacity: number;
     readonly live: number;
-    /** Optional latency-feedback sink (PeakEwmaBalancer); fed on settle when a clock is supplied. */
+    /** True iff endpoint `i` is currently pickable (used by distinct failover's untried scan). */
+    isEligible?(i: number): boolean;
+    /** Optional latency-feedback sink (PeakEwmaBalancer); fed on settle when a clock is in use. */
     recordRtt?(i: number, sampleNs: number, now: number): void;
     /** Optional occupancy sink (BoundedLoadBalancer); fed +1 on dispatch, -1 on settle. */
     note?(i: number, delta: number): void;
@@ -22,21 +40,34 @@ export interface Balancer {
 
 /** Options for `Pool.run`. */
 export interface RunOptions {
-    /** Passed to `fn`; when already aborted after a failure, stops failover (abort propagates). */
-    signal?: AbortSignal;
+    /** Passed to `fn`; when already aborted, stops dispatch/failover (the abort propagates). */
+    signal?: AbortLike;
     /** Max distinct-endpoint attempts (default 1 = no failover). */
     tries?: number;
     /**
-     * A caller-owned nanosecond clock. When present it drives `pick(now)` and the opt-in
-     * `recordRtt` latency feedback for a latency-aware balancer (PeakEwma); otherwise inert.
+     * A caller-owned nanosecond clock. REQUIRED for a latency-aware balancer (PeakEWMA): `run`
+     * validates each reading is finite, drives `pick(now)`, and feeds `recordRtt` on settle (and a
+     * failure penalty on a throw). For a non-latency balancer it is optional and only feeds
+     * `recordRtt` if the balancer duck-types it; otherwise inert. Omitting it for a latency balancer
+     * is a runtime error.
      */
     clock?: () => number;
     /**
-     * An integer routing key for a keyed balancer (ConsistentHash / BoundedLoad). When present,
-     * `run` calls `pick(key)`; the opt-in `note` occupancy hook is driven on dispatch/settle for
-     * a bounded-load balancer. Ignored by non-keyed strategies.
+     * An integer routing key. REQUIRED for a keyed balancer (ConsistentHash / BoundedLoad): `run`
+     * drives `pick(key)` (sticky / bounded-load routing). Omitting it for a keyed balancer is a
+     * runtime error. It is NOT passed to a latency balancer as `now`, and is ignored by non-keyed,
+     * non-latency strategies. The `note` occupancy hook is driven whenever the balancer duck-types
+     * `note`, independently of `key`.
      */
     key?: number;
+    /**
+     * The minimum rtt penalty (nanoseconds) a thrown attempt feeds a latency-aware balancer via
+     * `recordRtt(i, max(elapsed, failurePenaltyNs), done)`, so a fast-failing endpoint stops being the
+     * cheapest pick. Finite, > 0. Default 1e9 (1 s). RECOVERY: the penalized estimate decays back to
+     * competitive after roughly `tauNs * ln(failurePenaltyNs / healthyRttNs)`, so the node is
+     * periodically RE-PROBED at that cadence (recovery works) while its steady-state share stays low.
+     */
+    failurePenaltyNs?: number;
 }
 
 /**
@@ -56,31 +87,46 @@ export class Pool {
     /** 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 `fn` against a chosen endpoint (in-flight incremented on dispatch, decremented on settle),
+     * with up to `opts.tries` genuinely DISTINCT-endpoint failover attempts on a throw (failover
+     * targets are spread across keys for a keyed run and cursor-rotated for an unkeyed run). A keyed
+     * balancer requires `opts.key` and a latency balancer requires `opts.clock` (a `LITE_PICK_KEY_REQUIRED`
+     * / `LITE_PICK_CLOCK_REQUIRED`-coded error otherwise).
+     *
+     * Rejections: `LITE_PICK_NONE` when no endpoint is eligible; the last error when every attempt
+     * fails; an already-aborted `signal` dispatches NOTHING and rejects (the signal's `reason`, or a
+     * `LITE_PICK_ABORTED`-coded error). Feedback is loud and never re-runs `fn`: if SETTLE-time feedback
+     * after a SUCCESS fails (clock throws / non-finite, or `recordRtt` throws), `run` rejects with a
+     * `LITE_PICK_FEEDBACK`-coded error carrying `.cause` (the feedback error) and `.result` (fn's
+     * resolved value). If PENALTY feedback after a FAILURE fails, `run` throws fn's error object
+     * unchanged (identity preserved) with the feedback error attached as a non-enumerable
+     * `liteFeedbackError`. A backwards-stepping but finite clock reading records NO rtt sample and
+     * resolves normally (a failed attempt still records the full penalty). `opts` may be omitted or `null`.
      */
-    run<T>(fn: (endpoint: number, signal?: AbortSignal) => Promise<T> | T, opts?: RunOptions): Promise<T>;
+    run<T>(fn: (endpoint: number, signal?: AbortLike) => Promise<T> | T, opts?: RunOptions | null): Promise<T>;
 }
 
 /** Context passed to the per-endpoint fetcher. */
 export interface PerEndpointContext {
     endpoint: number;
     key: any;
-    signal?: AbortSignal;
+    signal?: AbortLike;
 }
 
 /** Context a query cache passes to the produced fetcher (lite-query's fetcher shape). */
 export interface FetcherContext {
     key: any;
-    signal?: AbortSignal;
+    signal?: AbortLike;
 }
 
 /** Options for `liteQueryFetcher`. */
 export interface FetcherOptions {
     /** Spatial failover attempts across the pool (default 1). */
     tries?: number;
+    /** A nanosecond clock forwarded to a latency-aware balancer (PeakEWMA); otherwise inert. */
+    clock?: () => number;
+    /** Minimum rtt penalty a thrown attempt feeds a latency-aware balancer; forwarded to `pool.run`. */
+    failurePenaltyNs?: number;
 }
 
 /**

package/Pool.js

@@ -28,6 +28,53 @@ import { VERSION, PICK_NONE } from './Pick.js';
 /** Re-exported so a /pool-only importer can read the version without importing the core. */
 export { VERSION };
 
+/**
+ * Distinct-endpoint re-pick bound (M2): after a failed attempt Pool re-picks up to this many times
+ * while the strategy keeps returning an already-tried endpoint, before falling back to a linear scan
+ * for an eligible UNTRIED endpoint. Small: `tries` is small, and a keyed/deterministic strategy that
+ * always returns the same backend hits the scan after this bound rather than spinning.
+ */
+const REPICK_LIMIT = 8;
+
+/**
+ * Cold failover fallback (M2): the first ELIGIBLE endpoint NOT already tried this run, scanning the
+ * capacity from a rotating start (`from`) so failover does not always favour low indices. Uses the
+ * balancer's own `isEligible` (duck-typed; if absent, no scan is possible -> PICK_NONE). Returns
+ * PICK_NONE when every eligible endpoint has already been tried -- the caller then stops failing over
+ * rather than re-dispatching to an endpoint that already failed this run.
+ * @param {{ capacity: number, isEligible?(i: number): boolean }} b
+ * @param {number[]} tried  endpoints already dispatched this run
+ * @param {number} from  rotating scan start
+ * @returns {number}
+ */
+function _scanUntried(b, tried, from) {
+    if (typeof b.isEligible !== 'function') return PICK_NONE;
+    const cap = b.capacity;
+    for (let s = 0; s < cap; s++) {
+        let idx = from + s;
+        if (idx >= cap) idx -= cap;
+        if (b.isEligible(idx) && tried.indexOf(idx) < 0) return idx;
+    }
+    return PICK_NONE;
+}
+
+/**
+ * Attach a feedback error to fn's error WITHOUT replacing it (identity is preserved): when `err` is
+ * an extensible object, define a NON-enumerable `liteFeedbackError` property carrying `fe`. Never
+ * throws (a frozen/sealed or primitive `err` is left untouched) -- the caller still gets fn's error.
+ * @param {unknown} err  the value fn threw (returned unchanged)
+ * @param {unknown} fe   the feedback error to attach
+ */
+function _attachFeedback(err, fe) {
+    if (err !== null && (typeof err === 'object' || typeof err === 'function')) {
+        try {
+            Object.defineProperty(err, 'liteFeedbackError', {
+                value: fe, enumerable: false, configurable: true, writable: true,
+            });
+        } catch { /* frozen/sealed: leave fn's error untouched -- identity preserved */ }
+    }
+}
+
 /**
  * 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
@@ -51,6 +98,7 @@ export class Pool {
         }
         this._b = balancer;
         this._inflight = inflight;
+        this._scanCursor = 0;   // rotating failover-scan start for UNKEYED runs (spreads across runs)
     }
 
     /** The wrapped balancer. */
@@ -64,99 +112,247 @@ export class Pool {
     }
 
     /**
-     * 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).
+     * 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 fail over to a
+     * genuinely DISTINCT endpoint -- up to `tries` attempts, then throw the last error. Every count
+     * this run raised (and every applied `note(+1)`) is released before returning or throwing
+     * (net-zero on every path: success, throw, abort, feedback error).
      *
-     * A LATENCY-AWARE balancer (PeakEwmaBalancer -- anything duck-typing `recordRtt`) is fed on
-     * settle WHEN a `clock` is supplied: Pool reads `clock()` (caller-owned nanoseconds) before the
-     * attempt, passes it to `pick(now)`, and on a SUCCESSFUL settle records `recordRtt(i, elapsed,
-     * now2)`. Without a `clock`, or against a balancer with no `recordRtt`, the hook is INERT --
-     * Pool stays generic, the in-flight counter stays net-zero, and abort/failover are unaffected.
-     * The kernel `pick()` remains 0 B/op; this wrapper is not held to that bar.
+     * DISTINCT FAILOVER (M2): the endpoints already tried this run are tracked; after a failure Pool
+     * re-picks while the strategy repeats a tried endpoint (bounded by REPICK_LIMIT), then falls back
+     * to a scan for an eligible UNTRIED endpoint (`balancer.isEligible`). The scan start is derived
+     * from the KEY for a keyed run (deterministic per key -> a key's failover target is stable and
+     * cache-friendly, but spread ACROSS keys so one failing backend does not funnel every key onto a
+     * single neighbour) and from a rotating per-Pool cursor for an unkeyed run. If no untried eligible
+     * endpoint exists it stops failing over -- never re-dispatching to an endpoint that already failed
+     * this run.
      *
-     * An OCCUPANCY-AWARE balancer (BoundedLoadBalancer -- anything duck-typing `note`) has each
-     * dispatch mirrored as `note(i, +1)` and each settle as `note(i, -1)`, so its owned running mean
-     * stays current; against a balancer with no `note` the hook is fully INERT (same net-zero,
-     * generic behaviour). The two hooks are independent -- a balancer may duck-type neither, one, or
-     * both.
+     * CHANNELS (M3), read off the strategy's static markers so Pool stays duck-typed:
+     *   - A KEYED balancer (`constructor.KEYED === true`: ConsistentHash / BoundedLoad) REQUIRES a
+     *     numeric `opts.key`; Pool drives `pick(key)`. Missing/non-numeric key -> a clear error. A
+     *     clock reading is NEVER passed to a keyed pick.
+     *   - A LATENCY balancer (`constructor.LATENCY === true`: PeakEWMA) REQUIRES an `opts.clock`;
+     *     Pool reads `clock()` (validated finite BEFORE dispatch) and drives `pick(now)`.
+     *   - Otherwise, when a `clock` is supplied Pool passes its reading to `pick(now)` too (a
+     *     non-latency built-in ignores the argument; a duck-typed latency balancer that omitted the
+     *     marker still gets `now`, preserving 1.0.0 behaviour). The KEY still reaches ONLY a keyed pick.
      *
-     * A KEYED balancer (ConsistentHashBalancer / BoundedLoadBalancer -- CHBL) routes by an INTEGER
-     * key. When `opts.key` is supplied, Pool drives `pick(key)` (sticky / bounded-load routing);
-     * failover re-picks with the SAME key, and because the failed backend's occupancy stays elevated
-     * (its `note(+1)` held across attempts) a CHBL re-pick naturally OVERFLOWS to the next backend.
-     * Without `opts.key`, `pick()` / `pick(now)` behaviour is unchanged.
+     * FEEDBACK IS LOUD, never silent, and never re-runs fn (M4): the occupancy hook `note(i, +1/-1)`
+     * mirrors dispatch/settle, and the latency hook `recordRtt` is fed on settle when a clock is in use.
+     *   - On SUCCESS the settle feedback (read `clock()`, then `recordRtt(i, done - now, done)`; a
+     *     BACKWARDS finite reading `done < now` records NO sample -- neither a rejection nor a fake 0 ns
+     *     rtt; `done === now` is a real 0 reading and is recorded) runs OUTSIDE the attempt's try/catch, so it can never re-dispatch fn. If it fails (clock
+     *     throws or returns non-finite, or `recordRtt` throws) `run` REJECTS with a `LITE_PICK_FEEDBACK`
+     *     -coded error whose `.cause` is the feedback error and whose `.result` is fn's resolved value
+     *     (the caller loses nothing). fn ran exactly once.
+     *   - On FAILURE the penalty feedback `recordRtt(i, max(elapsed, failurePenaltyNs), done)` (H1)
+     *     runs in its OWN try/catch so fn's error object is preserved by identity as the thrown value.
+     *     If the penalty feedback fails (throwing/non-finite clock, throwing `recordRtt`) Pool stops
+     *     failing over (a broken clock would throw on the next attempt anyway), attaches the feedback
+     *     error to fn's error as a NON-enumerable `liteFeedbackError`, and throws fn's error unchanged.
+     *   - H1 recovery: a penalized node's estimate decays back to competitive after roughly
+     *     `tauNs * ln(failurePenaltyNs / healthyRttNs)`, so it is periodically RE-PROBED at that
+     *     cadence (recovery works) while its steady-state share stays low.
      *
      * @template T
-     * @param {(endpoint: number, signal?: AbortSignal) => (Promise<T>|T)} fn  the per-endpoint work.
-     * @param {{ signal?: AbortSignal, tries?: number, clock?: () => number, key?: number }} [opts]
-     *   `tries` (default 1 = no failover) is the max number of distinct-endpoint attempts; `signal` is
-     *   passed to `fn` and, when already aborted after a failure, stops failover (the abort
-     *   propagates, no re-pick); `clock` is a caller-owned nanosecond source that, when present,
-     *   drives `pick(now)` and the opt-in `recordRtt` latency feedback for a latency-aware balancer;
-     *   `key` is a caller-supplied INTEGER key that, when present, drives `pick(key)` for a keyed
-     *   balancer (sticky / CHBL routing).
+     * @param {(endpoint: number, signal?: { readonly aborted: boolean }) => (Promise<T>|T)} fn
+     * @param {{ signal?: { readonly aborted: boolean, reason?: unknown, throwIfAborted?(): void },
+     *   tries?: number, clock?: () => number, key?: number, failurePenaltyNs?: number } | null} [opts]
+     *   `tries` (default 1 = no failover) is the max distinct-endpoint attempts; `signal` is passed to
+     *   `fn` and, when already aborted, dispatches NOTHING (the abort always propagates); `clock`
+     *   (REQUIRED for a latency balancer) is a caller-owned nanosecond source driving `pick(now)` +
+     *   `recordRtt`; `key` (REQUIRED for a keyed balancer) is a caller-supplied INTEGER routing key;
+     *   `failurePenaltyNs` (default 1e9) is the minimum rtt penalty a thrown attempt feeds a
+     *   latency-aware balancer.
      * @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 o = opts != null ? opts : undefined;      // L1: run(fn, null) / run(fn) are valid
+        const rawTries = o && o.tries != null ? (o.tries | 0) : 1;
         const tries = rawTries > 0 ? rawTries : 1;
-        const signal = opts ? opts.signal : undefined;
-        const clock = opts && typeof opts.clock === 'function' ? opts.clock : undefined;
-        // A keyed balancer (ConsistentHash / BoundedLoad -- CHBL) picks by an INTEGER key. When
-        // `opts.key` is supplied, pick(key) drives selection; otherwise the existing pick()/pick(now)
-        // behaviour is unchanged. `keyed` is true exactly when a key was passed.
-        const keyed = opts !== undefined && opts.key !== undefined;
-        const key = keyed ? opts.key : undefined;
-        const inflight = this._inflight, b = this._b;
-        // Opt-in latency feedback: only when BOTH a clock is supplied AND the balancer duck-types
-        // recordRtt. Otherwise inert -- Pool stays generic and byte-for-byte behaviour is unchanged.
+        const signal = o ? o.signal : undefined;
+        const b = this._b, inflight = this._inflight;
+
+        // M3: separate, REQUIRED channels, read off the strategy's static markers (duck-typed --
+        // Pool imports nothing new). Validate BEFORE any dispatch (fail closed).
+        const ctor = b.constructor;
+        const keyed = !!(ctor && ctor.KEYED === true);
+        const latency = !!(ctor && ctor.LATENCY === true);
+
+        let key;
+        if (keyed) {
+            const k = o ? o.key : undefined;
+            if (typeof k !== 'number' || !Number.isFinite(k)) {
+                const e = new Error('[lite-pick] a keyed balancer (ConsistentHash/BoundedLoad) requires a numeric opts.key');
+                e.code = 'LITE_PICK_KEY_REQUIRED';
+                throw e;
+            }
+            key = k;
+        }
+
+        let clock;
+        if (latency) {
+            const c = o ? o.clock : undefined;
+            if (typeof c !== 'function') {
+                const e = new Error('[lite-pick] a latency-aware balancer (PeakEWMA) requires an opts.clock function');
+                e.code = 'LITE_PICK_CLOCK_REQUIRED';
+                throw e;
+            }
+            clock = c;
+        } else {
+            clock = o && typeof o.clock === 'function' ? o.clock : undefined;
+        }
+
+        // H1: a thrown attempt feeds a latency penalty so a fast-failing endpoint stops being the
+        // cheapest pick. Default 1 s; validated finite > 0 (fail closed -- never silently ignored).
+        let failurePenaltyNs = 1e9;
+        if (o && o.failurePenaltyNs !== undefined) {
+            const fp = o.failurePenaltyNs;
+            if (typeof fp !== 'number' || !Number.isFinite(fp) || fp <= 0) {
+                throw new RangeError('[lite-pick] failurePenaltyNs must be a finite number > 0');
+            }
+            failurePenaltyNs = fp;
+        }
+
+        // Opt-in feedback (duck-typed, independent): latency (recordRtt, only with a clock) and
+        // occupancy (note). Inert when the balancer does not duck-type the method. `useNow` is true
+        // when the clock reading is passed to pick() (any clocked run that is not keyed).
         const rtt = clock !== undefined && typeof b.recordRtt === 'function';
-        // Opt-in occupancy feedback (BoundedLoadBalancer): when the balancer duck-types note(), Pool
-        // mirrors each dispatch(+1)/settle(-1) into it so the balancer's owned _total mean stays
-        // O(1)-current. Otherwise inert -- Pool stays generic, in-flight stays net-zero, and
-        // abort/failover are unchanged. Follows the exact opt-in shape the recordRtt hook uses.
         const notes = typeof b.note === 'function';
-        const held = [];                 // endpoints incremented this run (kept elevated across failover)
+        const useNow = clock !== undefined && !keyed;
+
+        const held = [];         // endpoints incremented this run == the endpoints TRIED (kept elevated)
+        const noteApplied = [];   // per-held: whether note(+1) actually landed (so finally never unpairs)
         let lastErr;
         try {
             for (let attempt = 0; attempt < tries; attempt++) {
-                const now = clock !== undefined ? clock() : undefined;
-                // A keyed pick (opts.key) takes precedence -- sticky/CHBL routing; else pick(now)/pick().
-                const i = keyed ? b.pick(key) : b.pick(now);
+                // Item 5: abort before EVERY attempt -- an already-aborted signal dispatches NOTHING and
+                // ALWAYS throws (throwIfAborted is optional on the structural signal: call it when it is
+                // a function, then always throw the reason, else a coded abort error).
+                if (signal && signal.aborted) {
+                    if (typeof signal.throwIfAborted === 'function') signal.throwIfAborted();
+                    if (signal.reason !== undefined) throw signal.reason;
+                    const e = new Error('[lite-pick] run aborted before dispatch');
+                    e.code = 'LITE_PICK_ABORTED';
+                    throw e;
+                }
+
+                // Validate the clock reading BEFORE dispatch so a broken clock fails closed early.
+                let now;
+                if (clock !== undefined) {
+                    now = clock();
+                    if (!Number.isFinite(now)) {
+                        throw new Error('[lite-pick] clock() must return a finite number, got ' + now);
+                    }
+                }
+
+                // Choose an endpoint: the key goes ONLY to a keyed pick; a clock reading (now) never
+                // reaches a keyed pick but does drive pick(now) for any other clocked run (M3 + nit 7).
+                let i = keyed ? b.pick(key) : (useNow ? b.pick(now) : b.pick());
+                if (attempt > 0) {
+                    // M2: genuinely DISTINCT failover. Re-pick while the result repeats a tried
+                    // endpoint (bounded), then a scan for an eligible UNTRIED endpoint from a start that
+                    // is key-derived (keyed: stable per key, spread across keys) or cursor-rotated.
+                    for (let g = 0; i !== PICK_NONE && held.indexOf(i) >= 0 && g < REPICK_LIMIT; g++) {
+                        i = keyed ? b.pick(key) : (useNow ? b.pick(now) : b.pick());
+                    }
+                    if (i === PICK_NONE || held.indexOf(i) >= 0) {
+                        const cap = b.capacity;
+                        const from = keyed
+                            ? (Math.imul(key >>> 0, 0x9e3779b1) >>> 0) % cap
+                            : (this._scanCursor = (this._scanCursor + 1) & 0x3fffffff) % cap;   // stays an SMI
+                        i = _scanUntried(b, held, from);
+                    }
+                }
                 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
+                    break;   // no distinct untried endpoint left: surface the last error
                 }
+
                 inflight[i] = (inflight[i] + 1) >>> 0;
                 held.push(i);
-                if (notes) b.note(i, 1);       // mirror the dispatch into the balancer's occupancy sum
+                noteApplied.push(false);
+                if (notes) {
+                    // A throwing note(+1) propagates (loud); noteApplied stays false so the finally
+                    // never sends an UNPAIRED note(-1) for this dispatch (nit 8). inflight is released.
+                    b.note(i, 1);
+                    noteApplied[noteApplied.length - 1] = true;
+                }
+
+                let out;
+                let ok = false;
                 try {
-                    const out = await fn(i, signal);
-                    if (rtt) {           // successful settle: feed the measured rtt back to the balancer
-                        const done = clock();
-                        b.recordRtt(i, done > now ? done - now : 0, done);
-                    }
-                    return out;
+                    out = await fn(i, signal);
+                    ok = true;
                 } catch (err) {
                     lastErr = err;
+                    if (rtt) {
+                        // H1 penalty feedback in its OWN try/catch: fn's error identity is preserved.
+                        // Boolean flag, not a null sentinel: a hook that throws `null` is still a failure.
+                        let feFailed = false, feErr;
+                        try {
+                            const done = clock();
+                            if (!Number.isFinite(done)) {
+                                throw new Error('[lite-pick] clock() must return a finite number, got ' + done);
+                            }
+                            let elapsed = done - now;
+                            if (!(elapsed >= 0)) elapsed = 0;   // clamp (NaN-safe): backwards finite clock
+                            const pen = elapsed > failurePenaltyNs ? elapsed : failurePenaltyNs;
+                            b.recordRtt(i, pen, done);
+                        } catch (fe) {
+                            feFailed = true;
+                            feErr = fe;
+                        }
+                        if (feFailed) {
+                            // Broken clock/feedback: stop failing over (the pre-dispatch check would
+                            // throw next attempt anyway) and throw fn's error, unchanged, with the
+                            // feedback error attached non-enumerably (never replaced).
+                            _attachFeedback(err, feErr);
+                            throw err;
+                        }
+                    }
                     if (signal && signal.aborted) throw err;   // abort: stop failover, propagate
+                    continue;                                   // keep inflight[i] elevated, re-pick distinct
+                }
+                if (ok) {
+                    if (rtt) {
+                        // Settle feedback runs OUTSIDE the attempt's try/catch (never re-runs fn). If it
+                        // fails, REJECT loudly with LITE_PICK_FEEDBACK carrying .cause and .result.
+                        try {
+                            const done = clock();
+                            if (!Number.isFinite(done)) {
+                                throw new Error('[lite-pick] clock() must return a finite number, got ' + done);
+                            }
+                            // A backwards clock reading records NO sample: a fabricated 0 ns rtt would
+                            // make the node look instant (cost 0 while idle) and drag down the pool mean.
+                            // done === now is a real 0 reading from a coarse clock and IS recorded.
+                            if (done >= now) b.recordRtt(i, done - now, done);
+                        } catch (fe) {
+                            const e = new Error('[lite-pick] settle-time feedback failed after a successful call');
+                            e.code = 'LITE_PICK_FEEDBACK';
+                            e.cause = fe;
+                            e.result = out;
+                            throw e;
+                        }
+                    }
+                    return out;
                 }
-                // 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;
-                if (notes) b.note(j, -1);      // net-zero settle -- keeps _total in lockstep per run
+                // Settle note(-1) ONLY for a dispatch whose note(+1) landed (nit 8), and swallow a
+                // cleanup-time throw so it never masks the error being thrown (identity preserved).
+                if (notes && noteApplied[k]) {
+                    try { b.note(j, -1); } catch { /* best-effort net-zero cleanup */ }
+                }
             }
         }
     }
@@ -173,11 +369,18 @@ export class Pool {
  * 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).
  *
+ * `ctx.key` is the QUERY-CACHE key (arbitrary), passed through to `perEndpoint`; it is NOT the
+ * integer ROUTING key a keyed balancer needs, so this generic adapter does not drive `pick(key)` --
+ * a keyed balancer wired through it fails closed (supply routing keys via `pool.run` directly). A
+ * `clock` (for a latency balancer) is forwarded when supplied in `opts`.
+ *
  * @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>}
+ * @param {(ctx: { endpoint: number, key: any, signal?: { readonly aborted: boolean } }) => (Promise<T>|T)} perEndpoint
+ * @param {{ tries?: number, clock?: () => number, failurePenaltyNs?: number }} [opts]  spatial failover
+ *   attempts (default 1), an optional nanosecond clock, and the failure penalty -- all forwarded to
+ *   `pool.run` (the clock/penalty feed a latency-aware balancer).
+ * @returns {(ctx: { key: any, signal?: { readonly aborted: boolean } }) => Promise<T>}
  */
 export function liteQueryFetcher(pool, perEndpoint, opts) {
     if (!(pool instanceof Pool)) throw new TypeError('[lite-pick] liteQueryFetcher needs a Pool');
@@ -185,9 +388,19 @@ export function liteQueryFetcher(pool, perEndpoint, opts) {
         throw new TypeError('[lite-pick] liteQueryFetcher needs a per-endpoint function');
     }
     const tries = opts && opts.tries != null ? opts.tries : 1;
+    const clock = opts && typeof opts.clock === 'function' ? opts.clock : undefined;
+    const failurePenaltyNs = opts && opts.failurePenaltyNs !== undefined ? opts.failurePenaltyNs : undefined;
+    // Validate once at creation (fail closed early), not on every fetch.
+    if (failurePenaltyNs !== undefined &&
+        (typeof failurePenaltyNs !== 'number' || !Number.isFinite(failurePenaltyNs) || failurePenaltyNs <= 0)) {
+        throw new RangeError('[lite-pick] failurePenaltyNs must be a finite number > 0');
+    }
     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 });
+        return pool.run(
+            (endpoint, sig) => perEndpoint({ endpoint, key, signal: sig }),
+            { signal, tries, clock, failurePenaltyNs },
+        );
     };
 }