Selection policy

A single JavaScript function (evalFunc) per network returns the ordered list of upstreams that should serve requests. The order IS the routing decision: position 0 is the primary, position N is the Nth retry / hedge candidate, anything missing is excluded for that tick.

How it works

                              every `evalInterval`
                                       ▼
upstreams + ctx (cross-tick state) ──► evalFunc() ──► ordered upstream[]
                                                            │
                                                            ▼
                            Network.Forward consumes the list on every
                            request (wait-free atomic load, O(1))

• The eval runs on a per-(network, method) timer.
• Output is cached atomically; the request path reads it lock-free.
• Every tick produces a decision record joined to requests via decision_id for incident triage (Prometheus + OTLP traces).

Configuration

projects:
  - id: main
    # Health-tracker rolling window for per-upstream metrics
    # (errorRate, latency quantiles, throttledRate, lag). 10 sub-buckets
    # slide forward every windowSize/10. Default 1m.
    scoreMetricsWindowSize: 1m
    upstreamDefaults:
      evm:
        # State-poller cadence. Each upstream gets eth_blockNumber +
        # eth_syncing on this interval (bypasses the selection policy
        # — even excluded upstreams stay sampled so the tracker never
        # blanks on idle nodes). Keep this <= scoreMetricsWindowSize.
        statePollerInterval: 2s
    upstreams:
      - endpoint: alchemy://...
      - endpoint: drpc-eth://...
        tags: [tier:fallback]      # ← convention: 2nd tier
    networks:
      - architecture: evm
        evm: { chainId: 1 }
        # The block below is the DEFAULT — omit `selectionPolicy`
        # entirely if you're happy with these settings.
        selectionPolicy:
          evalInterval: 15s
          evalTimeout: 100ms
          evalScope: network        # 'network' | 'network-method' | 'network-finality' | 'network-method-finality'
          evalFunc: |
            (upstreams, ctx) =>
              upstreams
                .removeCordoned()
                .excludeIf(all(samplesAbove(10), errorRateAbove(0.7)))
                .excludeIf(all(samplesAbove(10), throttleRateAbove(0.4)))
                .excludeIf(any(all(samplesAbove(20), latencyAbove(3000), latencyDeviationAbove(3, { mode: 'majority' })), latencyAbove(10_000)))
                .excludeIf(any(blockNumberLagAbove(16), blockSecondsLagAbove(30)))
                .whenEmpty(() => upstreams)
                .preferTag('!tier:fallback', { minHealthy: 1, fallback: 'tier:fallback' })
                .sortByScore(PREFER_FASTEST)
                .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '30s' })
                .probeExcluded({ sampleRate: 0.1, minSamples: 10, minSamplesWindow: '60s', maxConcurrent: 4, timeout: '10s' })

Investigations. Per-tick reasoning is exposed via OTLP tracing spans and the erpc_selection_* Prometheus metric family (selection counters, primary-switch counters, rejection counters, eval-duration histogram). DEBUG-level eRPC logs print one line per stdlib step + one per excluded upstream with its policyReason. The erpc-simulator renders the full per-step trail interactively.

The default policy

Omitting evalFunc applies a production-hardened, chain-agnostic policy. Each step addresses a distinct failure class — the absence of any one of them lets a degraded upstream keep receiving traffic:

(upstreams, ctx) =>
  upstreams
    // Honour operator [cordon](/operation/cordoning) — intent-driven, sticky, ignores metrics until uncordoned.
    .removeCordoned()
    // Drop if >70 % errors over the rolling window. Gated on samplesAbove(10) so a single
    // failed call on a fresh-pod tracker (errorRate = 1/1 = 1.0) cannot cascade-evict
    // every upstream before the window has meaningful denominator.
    .excludeIf(all(samplesAbove(10), errorRateAbove(0.7)))
    // Drop if >40 % throttled — vendor is rate-limiting us; reroute before quota burns.
    // Same samplesAbove(10) guard as the error rule, same reason.
    .excludeIf(all(samplesAbove(10), throttleRateAbove(0.4)))
    // Drop latency outliers — TWO-STAGE gate:
    //   1. `latencyAbove(3000)` — absolute floor. Sub-3s upstreams stay in rotation
    //      regardless of how they compare to a faster peer; scoring puts them later
    //      and hedge catches the latency on the request path.
    //   2. `latencyDeviationAbove(3, majority)` — relative check, only after passing
    //      the floor. Excludes only when >50% of per-method comparisons are >3× the
    //      fastest peer, which is robust to per-tick spikes on a single rare method.
    // OR `latencyAbove(10_000)` — catastrophic safety net regardless of peers or
    // sample count. p70 matches the rank axis below so exclusion and ranking agree
    // on "fast".
    .excludeIf(any(all(samplesAbove(20), latencyAbove(3000), latencyDeviationAbove(3, { mode: 'majority' })), latencyAbove(10_000)))
    // Drop laggers: >16 blocks behind tip (chain-agnostic) OR >30 wall-clock seconds
    // (adapts to chain block-time via the tracker's EMA, no-op until ≥3 samples).
    .excludeIf(any(blockNumberLagAbove(16), blockSecondsLagAbove(30)))
    // Safety net: if all health excludes wiped the pool (project-wide outage), serve
    // from the raw set rather than fail closed. Only step ABOVE here can drop to
    // empty; everything BELOW only reorders or adds.
    .whenEmpty(() => upstreams)
    // Tier split: primary = NOT tier:fallback. Falls through to tier:fallback when no
    // primary survives.
    .preferTag('!tier:fallback', { minHealthy: 1, fallback: 'tier:fallback' })
    // Rank survivors by PREFER_FASTEST (weights: errorRate 4, respLatency 15,
    // throttledRate 4, blockHeadLag 1, finalizationLag 0, misbehaviors 2). Latency
    // dominates because excludes already dropped the bad apples; among survivors,
    // "how fast does this answer?" is the operator's strongest signal. Per-upstream
    // routing.scoreMultipliers flow through here automatically.
    .sortByScore(PREFER_FASTEST)
    // Anti-flap: challenger needs score > incumbent × 1.30 AND ≥30 s since last
    // switch. Cuts flap on close calls; the cost of churn (connection setup, cache
    // locality) outweighs marginal ranking gains.
    .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '30s' })
    // Shadow-mirror probing: sampled real traffic gets fanned out to any
    // currently-excluded upstream in the background. Their tracker counters
    // get fed indistinguishably from real traffic. Once they pass the
    // excludeIf predicates above, they fall out of the excluded set on the
    // next tick — no time-based readmit timer needed. Per-upstream opt-out
    // via routing.probe: 'off'.
    .probeExcluded({ sampleRate: 0.1, minSamples: 10, minSamplesWindow: '60s', maxConcurrent: 4, timeout: '10s' })

Why error / throttle are tolerant (0.7 / 0.4) and the latency check is two-stage. Failure costs are asymmetric:

• Error / throttle blips are already absorbed by retry / hedge / consensus (the failsafe layer). A 70 % / 40 % rolling rate is the threshold for "this isn't a blip, this is broken".
• Latency exclusion would over-trigger on a single-multiplier check: a moderately slow vendor (e.g. 500 ms p70 vs a fast peer's 20 ms — a 25× ratio) is not user-visibly broken — hedge catches it within ~200 ms. The two-stage gate (latencyAbove(3000) AND latencyDeviationAbove(3, majority)) lets scoring + hedge handle sub-3s upstreams while still catching upstreams that are BOTH absolutely slow AND consistently slower than their peers. The latencyAbove(10_000) catastrophic outer is the unconditional safety net (>10 s is broken regardless of peers).

Production tuning data: prod metrics on 2026-05-27 showed the previous latencyDeviationAbove(10, majority) excluding 100-500 ms vendors against 20 ms peers — exactly the case where scoring + hedge would have handled it correctly. The two-stage gate restores the operator-stated intent of "only exclude crazy outliers".

Source served at GET /admin/selection/default-policy.

Loosening the default for low-traffic / dev setups

If the defaults are too strict — e.g. you have only one upstream per network and would rather a degraded upstream serve traffic than fail closed — write an explicit evalFunc:

(upstreams, ctx) =>
  upstreams
    .removeCordoned()
    .excludeIf(errorRateAbove(0.8))         // looser error threshold
    .whenEmpty(() => upstreams)
    .sortByScore(PREFER_FASTEST)
    .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '30s' })
    .probeExcluded({ sampleRate: 0.5, maxConcurrent: 2, timeout: '10s' })

Eval inputs

Inside the function body, two variables are in scope: upstreams and ctx.

type Upstream = {
  readonly id: string
  readonly vendor: string                  // "alchemy", "infura", "drpc", ...
  readonly type: 'evm' | string
  readonly tags: string[]                  // "tier:main", "region:us-east", ...
 
  readonly metrics: UpstreamMetrics        // tick-start snapshot (see below)
 
  // Diagnostic methods:
  readonly hasTag: (tag: string) => boolean
  readonly is: (tag: string) => boolean    // alias of hasTag
 
  // Attached by std-lib steps:
  readonly score?: number                  // sortByScore (higher = better)
 
  // Per-upstream weight overrides resolved from routing.scoreMultipliers
  // for this tick's (network, method, finality). sortByScore reads it.
  readonly scoreMultipliers?: {
    overall?: number
    errorRate?: number; respLatency?: number; throttledRate?: number
    blockHeadLag?: number; finalizationLag?: number; misbehaviors?: number
  }
}
 
type UpstreamMetrics = {
  errorRate: number                        // 0..1
  errorsTotal: number
  requestsTotal: number
  throttledRate: number                    // 0..1
  misbehaviorRate: number
  p50ResponseSeconds: number
  p70ResponseSeconds: number
  p90ResponseSeconds: number
  p95ResponseSeconds: number
  p99ResponseSeconds: number
  blockHeadLag: number                     // BLOCK-number delta behind tip
  finalizationLag: number                  // block-number delta behind finalized
  blockHeadLagSeconds: number              // blockHeadLag × tracker's EMA block-time
  finalizationLagSeconds: number
  cordonedReason: string | null            // set by admin via erpc_cordonUpstream RPC
  latencyP: (quantile: number) => number   // quantile in 0..100 or 0..1, returns ms
}
 
type EvalContext = {
  network: string                          // "evm:1"
  method: string                           // "*" unless evalScope includes "method"
  finality: 'realtime' | 'unfinalized' | 'finalized' | 'unknown'
  now: number                              // unix ms
 
  // Cross-tick state — the ONLY carrier of state between ticks.
  previousOrder: string[]
  lastSwitchAt: number | null
  tickCount: number
}

The metrics object is captured ONCE at tick start, so chained std-lib steps see a consistent view.

Globals: PREFER_FASTEST, PREFER_FRESHEST, PREFER_LEAST_ERRORS; REALTIME / UNFINALIZED / FINALIZED / UNKNOWN; REASON_* reason codes; process.env; console.log/info/warn/error; standard ECMAScript.

Health-tracker rolling window

Every observed per-upstream metric (errorRate, latency quantiles, throttledRate, misbehaviorRate, request counts) lives in a 10-bucket sliding window of duration scoreMetricsWindowSize (default 1m). Every windowSize / 10 (= 6 s at 1 m), one bucket rotates out and a fresh one opens. Data drips out continuously — no tumble cliff.

The DDSketch quantile estimator lives per sub-bucket and merges on read, so a longer window means more samples per sketch — tighter p70 / p95 / p99 estimates — but also more stale data anchoring the ranking.

Pair with statePollerInterval. The state poller (default 30 s, override per project via upstreamDefaults.evm.statePollerInterval) fires eth_blockNumber + eth_syncing per upstream regardless of client traffic AND regardless of selection-policy exclusion. Those calls feed the tracker, so an idle or excluded upstream still has fresh samples in the rolling window. Keep statePollerInterval ≤ scoreMetricsWindowSize so the window is never empty for a low-traffic upstream.

Advanced tuning: coupling between evalInterval, scoreMetricsWindowSize + probe window

Three knobs interact and should be tuned together, not individually:

The symmetry that makes the defaults work —

• scoreMetricsWindowSize ≈ probeExcluded.minSamplesWindow keeps re-admission decisions aligned with ranking decisions (the prober sees "enough samples to re-admit" at roughly the same time the ranking sees "enough recovery to actually re-admit").
• scoreMetricsWindowSize should be ≥ ~3× evalInterval so each eval tick sees ≥3 fresh sub-buckets of samples (otherwise quantile estimates flicker between ticks).
• scoreMetricsWindowSize should be ≤ idleEvictionAfter (default 30m), to ensure the tracker doesn't evict entries that are still contributing to the window.

Workload-aware recommendations:

Pitfalls to avoid:

• Long scoreMetricsWindowSize + short probeExcluded.minSamplesWindow → the prober sees enough recovery samples to want to re-admit, but the ranking still has stale bad samples in its long window. Re-admission feels stuck.
• Short scoreMetricsWindowSize + per-method scope on rare methods → small sample counts (1-10 samples per window for a rare method) → noisy quantile estimates → flickering exclusion. Use a wider window OR keep evalScope: network so all methods pool into one aggregate.
• evalInterval ≥ scoreMetricsWindowSize → only one or two sample points per eval. Quantile reads jump between two halves of the window. Don't do this.
• Bumping evalInterval above 30s without also widening the metric window. The eval ends up reading nearly the same window each tick, but you've also delayed the slot-cache refresh — net effect is just slower reaction with no stability gain.

Pin samplesAbove(N) to your traffic shape. The default policy uses samplesAbove(10) (per-upstream-per-window guard against "1 bad request out of 3 → 33% error rate → excluded" flakiness). For per-method workloads with evalScope: network-method, set this threshold to at least 5% of typical method traffic in your scoreMetricsWindowSize:

// Example for a network seeing ~200 req/s of eth_call with
// scoreMetricsWindowSize=1m. 200 × 60 × 0.05 = 600 samples
// before exclusion considers this upstream.
upstreams.excludeIf(all(samplesAbove(600), errorRateAbove(0.7)))

For rare methods (e.g. debug_*), use a smaller absolute threshold like samplesAbove(20) — you'd never accumulate hundreds of samples in a window, so the guard becomes "10× typical method volume".

Per-method routing

Set evalScope: 'network-method' to run the policy separately per (network, method) instead of one ranking for the whole network. Each method's slot snapshots metrics for THAT specific method, so:

• A slow-eth_getLogs upstream can still serve eth_blockNumber from a different primary.
• u.metrics references the method-specific bucket (not the aggregate).
• Slots are created lazily on first request for a method; the wildcard "*" slot answers until the method-specific slot's first tick lands.

Default is evalScope: 'network' — most workloads benefit from one aggregate ranking and the per-method overhead (one eval per method per tick) isn't free. Predicates that need apples-to-apples per-method comparison (latencyDeviationAbove) handle that internally via u.metricsByMethod regardless of evalScope.

Per-finality routing

Set evalScope: 'network-finality' (or 'network-method-finality' to combine with per-method) to run the policy separately per finality bucket (realtime / unfinalized / finalized / unknown). The eval sees ctx.finality set to its bucket value, so different finality classes can use different presets/thresholds without the eval branching on ctx.finality itself.

A typical pattern:

(upstreams, ctx) =>
  upstreams
    .removeCordoned()
    .excludeIf(all(samplesAbove(10), errorRateAbove(0.7)))
    .sortByScore(
      ctx.finality === 'realtime' ? PREFER_FRESHEST :
      ctx.finality === 'finalized' ? PREFER_FASTEST :
      PREFER_FASTEST
    )
    .stickyPrimary({ hysteresis: 0.3, minSwitchInterval: '30s' })

With finality-scoped evaluation each bucket has its OWN sticky-primary state, score cache, and metric labels (erpc_selection_score{..., finality} etc.). The realtime bucket can hold one primary while the finalized bucket holds a different one — no cross-contamination. The underlying health tracker also splits its rolling-window counters by finality once the policy needs them, so per-finality predicates (errorRateAbove, latencyDeviationAbove, etc.) operate on the correct bucket without you having to opt in separately.

Slots are lazy-created on first request for a bucket. A network that never receives finalized queries pays zero overhead for that bucket. Use evalScope: 'network-method-finality' to get one slot per (method, finality) — useful for indexers that classify their workload precisely.

Common patterns

Cost-tier routing

// Cheap pool first; fall through to fast pool when cheap is exhausted.
// Upstreams declare their tier via `tags: [tier:cheap]` or `tags: [tier:fast]`.
(upstreams, ctx) =>
  upstreams
    .removeCordoned()
    .excludeIf(errorRateAbove(0.5))
    .preferTag('tier:cheap', { minHealthy: 2, fallback: 'tier:fast' })
    .sortByScore(PREFER_FASTEST)
    .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '30s' })

Per-method override

// Upstreams declare their capability via `tags: [tier:archive]`.
(upstreams, ctx) => {
  if (methodMatches(['eth_getLogs', 'eth_getBlockByNumber']))
    return upstreams.byTag('tier:archive').sortByScore(PREFER_FASTEST)
  return upstreams.sortByScore(PREFER_FASTEST).stickyPrimary()
}

Per-upstream weights via a function

// Illustrative — adjust to your actual vendor characteristics.
const w = {
  alchemy: { errorRate: 4, respLatency: 12 },   // weight latency MORE here
  drpc:    { errorRate: 6, respLatency: 4 },    // weight errors MORE here
}
(upstreams, ctx) =>
  upstreams.sortByScore((u) => w[u.vendor] || PREFER_FASTEST)

For the declarative-config alternative, see routing.scoreMultipliers on the upstream config — covered next.

Per-upstream score multipliers (config-driven)

Instead of branching inside the eval, declare per-upstream weight overrides on the upstream config under routing.scoreMultipliers. The engine resolves the matching entry for each (network, method, finality) and exposes it as u.scoreMultipliers; sortByScore folds it in. Most policies (including the default) need no eval change at all — multipliers flow through sortByScore's default 'merge' mode:

# Nudge priority without touching the weight shape — both keep the preset's
# latency-dominant weights, but `overall` biases the final score.
upstreams:
  - id: premium
    routing: { scoreMultipliers: [{ overall: 2 }] }     # strongly preferred
  - id: backup
    routing: { scoreMultipliers: [{ overall: 0.5 }] }   # only when premium degrades

// The eval is just the usual chain — nothing multiplier-specific needed.
(upstreams, ctx) =>
  upstreams.removeCordoned().sortByScore(PREFER_FASTEST).stickyPrimary()

Switch how the config combines with the base via opts.multipliers:

// 'override': upstreams that set scoreMultipliers rank by THEIR weights
// only; everyone else falls back to the preset.
(upstreams, ctx) =>
  upstreams.removeCordoned().sortByScore(PREFER_FASTEST, { multipliers: 'override' })
 
// 'off': ignore per-upstream config entirely (e.g. on a canary policy).
(upstreams, ctx) => upstreams.sortByScore(PREFER_FRESHEST, { multipliers: 'off' })

Custom inline predicate with a human-readable label

(upstreams, ctx) =>
  upstreams
    .excludeIf(u => u.id.startsWith('old-vendor-'), 'old vendor phase-out')
    .sortByScore(PREFER_FASTEST)

Auditioning a new rule with shadowExcludeIf

shadowExcludeIf is the dry-run counterpart of excludeIf. The predicate runs every tick, but no upstream is actually dropped — every would-have-been-excluded trip is surfaced as erpc_selection_shadow_exclusion_total{upstream, reason=<leaf-slug>} (same per-leaf attribution as the real counter). Use it to safely roll out a new exclusion rule (or audit the impact of removing an existing one) before flipping the call to excludeIf for real.

(upstreams, ctx) =>
  upstreams
    .removeCordoned()
    .excludeIf(errorRateAbove(0.5))                     // real
    .shadowExcludeIf(errorRateAbove(0.3))               // shadow: would a tighter bar be safe?
    .shadowExcludeIf(any(blockSecondsLagAbove(15), latencyAbove(15_000, 95)))
    .sortByScore(PREFER_FASTEST)
    .stickyPrimary()
    .probeExcluded()

Operator workflow:

1. Deploy with the new rule as shadowExcludeIf. Watch erpc_selection_shadow_exclusion_total{reason=<your-rule-slug>} for N days; compare to the current real-exclusion counter on the same upstreams.
2. Once the shadow rate matches your expectation (no false positives, no over-firing), flip the call to excludeIf and redeploy.
3. To audit removal of an existing rule: shadow what's currently real, deploy, confirm the shadow rate drops to zero on healthy upstreams before deleting it.

Shadow trips never touch stickyPrimary / probeExcluded — the upstream stays in rotation in its original position, so a shadow rule cannot accidentally affect routing.

Observability

The selection policy emits one tick's worth of decision data into Prometheus on every eval. Bounded cardinality — labels stay within (project, network, method, upstream) plus a small reason enum on the exclusion counter. See Monitoring → selection-policy decision metrics for the full table plus PromQL queries.

Admin RPCs

Per-upstream metrics

Per-leaf exclusion attribution

erpc_selection_exclusion_total{upstream, reason} emits one increment per leaf predicate that tripped — so an any(errorRateAbove(0.5), latencyAbove(30_000)) excluding an upstream because the latency leaf was true increments reason="latency_p70_above" (p70 is the default-quantile slug), not the combinator. AND-semantics (all(A,B)) increments every leaf since each must be true to trip. not(A) increments reason="not_<A.slug>".

Operators see exactly which signal caused each exclusion. The reason slug is threshold-free (error_rate_above, not errorRate>0.5) so cardinality stays bounded by the predicate-factory set, not by the powerset of thresholds.

Network-level metrics

Logs + simulator

DEBUG-level eRPC logs print one line per stdlib step + one per excluded upstream with its policyReason. The erpc-simulator (opens in a new tab) renders the full per-step trail interactively.

Reference

The selection-policy stdlib is installed on Array.prototype within the sobek runtime. Every chainable method returns an Upstream[] so chains compose. Predicate factories return functions usable with excludeIf / combinators. Glob patterns (*, ?, !negation) work everywhere a string | string[] is accepted.

Constants

Identity & label selection

.where(filter: { id?, tag?, vendor?, type? })   // AND across fields
.whereNot(filter)                                // inverse
.byId(id: string | string[])
.byTag(pat: string | string[])
.byVendor(name: string | string[])
.byType(type: string | string[])
.excludeId / .excludeTag / .excludeVendor        // negation forms

Filters & exclusion

.excludeIf(predicate: (u) => boolean, reason?: string)

.excludeIf(errorRateAbove(0.5))                                       // factory: auto-labels "errorRate>0.5"
.excludeIf(any(latencyDeviationAbove(10), latencyAbove(30_000)))   // combinator: auto-labels "any(p70>10xFastest(geomean),p70>30000ms)"
.excludeIf(u => u.id.startsWith('old-vendor-'), 'old vendor')         // inline: explicit reason

.removeByErrorRate(max: number)              // drop if errorRate > max
.removeByLatency({ p50Ms?, p70Ms?, p90Ms?, p95Ms?, p99Ms? })
.removeByThrottling(max: number)
.removeByMisbehavior(max: number)
.removeByLag({ blockHead?: number, finalization?: number })
.removeByMinRequests(min: number)            // require ≥ min samples
 
.keepHealthy({                               // composite shortcut
  maxErrorRate?: number     = 0.5,
  maxBlockHeadLag?: number  = 10,
  maxP95Ms?: number         = 5000,
  maxThrottledRate?: number = 0.3,
})

Tiering

.preferTag(pat: string, opts?: { minHealthy?: number = 1, fallback?: string })
.preferVendor(name: string, opts?: same)

.spreadAcrossTags(prefix: string)

// Top 3 by score might all share cohort:op-base-sequencer. Without
// spread, a sequencer outage kills primary + first 2 fallbacks. With
// spread: position 0 = best in cohort A, position 1 = best in cohort B,
// position 2 = second-best in cohort A, etc.
upstreams.sortByScore(PREFER_FASTEST).spreadAcrossTags('cohort:')

Sorting

.sortByScore(
  base?: ScoreWeights | preset | ((u) => ScoreWeights),   // default PREFER_FASTEST
  opts?: {
    multipliers?: 'merge' | 'override' | 'off'             // default 'merge'
    latencyQuantile?: 'p50' | 'p70' | 'p90' | 'p95' | 'p99' // default 'p70'
    overall?: (u) => number                                 // extra dial (advanced)
  }
)

.sortBy(fn, opts?: { desc?: boolean }) · .sortByDesc(fn)
.sortByLatency(quantile?) · .sortByErrorRate() · .sortByThrottling()
.sortByMisbehavior() · .sortByHeadLag() · .sortByFinalizationLag()

Stability across ticks

.stickyPrimary({
  hysteresis?: number = 0.30,             // challenger must be this fraction better
  minSwitchInterval?: Duration = '30s'    // cooldown between switches
})

Probing & forced inclusion

.probeExcluded({
  sampleRate?: number = 0.1,           // 0.0–1.0, per-(request, excluded-upstream) probability
  minSamples?: number = 10,            // per-upstream floor on probes within minSamplesWindow
  minSamplesWindow?: Duration = '60s', // rolling window for minSamples
  maxConcurrent?: number = 4,          // in-flight probes per excluded upstream
  timeout?: Duration = '10s',          // per-probe deadline
})

.forceInclude(
  idOrFn: string | string[] | ((u) => boolean),
  position?: 'head' | 'tail' = 'tail',
)

Slicing & limits

.pickTop(n) · .pickBottom(n) · .dropTop(n) · .dropBottom(n)
.take(n) / .skip(n)     // aliases of pickTop / dropTop

Chain control

.if(cond, thenFn, elseFn?)             // cond is boolean | (arr) => boolean
.unless(cond, fn)
.whenEmpty(() => Upstream[])           // run only if currently empty
.whenNotEmpty(fn)
.fallbackTo(arrOrFn)                   // replace with alternative if empty
.ensureMin(n, fn)                      // run fn to expand if length < n

.byFinality({
  realtime?:    (u) => Upstream[],
  unfinalized?: (u) => Upstream[],
  finalized?:   (u) => Upstream[],
  unknown?:     (u) => Upstream[],
})

upstreams.byFinality({
  finalized: u => u.sortByScore(PREFER_FASTEST),
  realtime:  u => u.removeByLag({ blockHead: 5 }).sortByScore(PREFER_FRESHEST),
})
.sortByScore(PREFER_FASTEST)                 // applies to unfinalized + unknown only

Predicate factories

Predicates are functions (u) => boolean consumed by excludeIf and combinators. Every factory below stamps a policyReason string on the returned closure so excludeIf auto-labels the dropped upstream with both a stable leaf slug (drives selection_exclusion_total{reason}) and a human-readable display string (visible in DEBUG logs + Decision.Output.Excluded[].Reason).

errorRateAbove(rate)        errorRateBelow(rate)
throttleRateAbove(rate)     throttleRateBelow(rate)
misbehaviorRateAbove(rate)

// value is the first arg; quantile is optional (defaults to p70).
// quantile accepts a 0..1 fraction or 0..100 number.
latencyAbove(ms, quantile?)

// Default — p70, geomean across methods, ratio > 10, damping at 30ms
latencyDeviationAbove(10)
 
// 2nd arg as a number is a quantile shorthand
latencyDeviationAbove(10, 95)
 
// Modes for resolving disagreement across methods
latencyDeviationAbove(10, { mode: 'geomean' })   // default
latencyDeviationAbove(10, { mode: 'majority' })
latencyDeviationAbove(10, { mode: 'veto' })
 
// Tune the damping scale (default 30ms — sub-30ms latencies have
// their ratio damped so micro-differences below human perception
// don't trip)
latencyDeviationAbove(10, { dampingMs: 50 })
 
// Combine
latencyDeviationAbove(10, { quantile: 95, mode: 'majority', dampingMs: 100 })

effective_ratio = (my / peer) × (1 − exp(−my / dampingMs))

blockNumberLagAbove(blocks)      finalizationLagAbove(blocks)

blockSecondsLagAbove(seconds)         finalizationSecondsLagAbove(seconds)

samplesBelow(n)        samplesAbove(n)

all(...preds)    // AND
any(...preds)    // OR
not(pred)        // NOT

Generic functional

.filter(fn) · .reject(fn) · .partition(fn): [yes, no]
.unique(keyFn?) · .union(other) · .intersect(other) · .difference(other)
.slice(start, end?) · .reverse() · .isEmpty

Randomization & rotation

.shuffle(seed?)
.rotateBy(n)                  // left-rotate by n; pair with ctx.tickCount for round-robin

Debug helpers

.tap(fn)                               // side effect; returns arr unchanged
.dump(level?: 'debug' | 'info' | 'warn' | 'error')

Free helpers (globals)

methodMatches(pattern: string | string[]): boolean    // glob ctx.method
isFinalityRequest(): boolean                          // ctx.finality === FINALIZED
durationMs(d: Duration | string): number              // parse '5m' → 300000

Worked examples

// Upstreams declare their tier via `tags: [tier:cheap]` or `tags: [tier:fast]`.
(upstreams, ctx) => {
  const cheapHours = inWindow('09:00', '18:00') && (new Date().getDay() % 6) !== 0
  return upstreams
    .removeCordoned()
    .excludeIf(errorRateAbove(0.5))
    .preferTag(cheapHours ? 'tier:cheap' : 'tier:fast',
               { minHealthy: 1, fallback: 'tier:cheap' })
    .sortByScore(PREFER_FASTEST)
    .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '2m' })
}

// Upstreams declare their capability via `tags: [tier:archive]`.
(upstreams, ctx) => {
  if (methodMatches(['eth_getLogs', 'eth_getBlockByNumber']))
    return upstreams.byTag('tier:archive').sortByScore(PREFER_FASTEST)
  if (methodMatches('eth_getBalance'))
    return upstreams.sortByScore(PREFER_LEAST_ERRORS)
  return upstreams.sortByScore(PREFER_FASTEST).stickyPrimary()
}

(upstreams, ctx) =>
  upstreams
    .removeCordoned()
    .excludeIf(errorRateAbove(0.5))
    .sortByScore(PREFER_FASTEST)
    .probeExcluded({ sampleRate: 0.5, maxConcurrent: 2, timeout: '10s' })
    .forceInclude('canary-rpc', 'tail')

(upstreams, ctx) =>
  upstreams
    .excludeIf(blockNumberLagAbove(5)).label('lag-filter')
    .sortByScore(PREFER_FASTEST).label('score')
    .stickyPrimary().label('sticky')
    .dump('debug')

Planned primitives (not yet shipped)