solana-resilience-kit 0.1.0

package/dist/fees/oracles.js

@@ -0,0 +1,88 @@
+/** Native estimate from getRecentPrioritizationFees over recent slots. */
+export class NativeFeeOracle {
+    rpc;
+    constructor(rpc) {
+        this.rpc = rpc;
+    }
+    /**
+     * Derives micro-lamports-per-CU percentiles from the cluster's recent
+     * prioritization-fee samples (`getRecentPrioritizationFees`). This is the
+     * free, backward-looking source: the node returns the smallest fee paid by a
+     * landed tx per recent slot. We sort the samples and pick percentiles by
+     * nearest-rank so the levels are monotonic.
+     */
+    async getPriorityFee(writableAccounts) {
+        const recent = await this.rpc
+            .getRecentPrioritizationFees(writableAccounts)
+            .send();
+        // Samples may arrive as bigint (kit MicroLamports) or number; normalize and
+        // sort ascending so percentile-by-rank produces monotonic levels.
+        const sorted = recent
+            .map((entry) => Number(entry.prioritizationFee))
+            .sort((a, b) => a - b);
+        if (sorted.length === 0) {
+            return {
+                levels: { min: 0, low: 0, medium: 0, high: 0, veryHigh: 0 },
+            };
+        }
+        // Nearest-rank percentile over (n - 1): p=0 -> first, p=100 -> last. The
+        // computed index is always in [0, n-1]; the `?? 0` only satisfies
+        // noUncheckedIndexedAccess and is never reached for a non-empty array.
+        const percentile = (p) => sorted[Math.round((p / 100) * (sorted.length - 1))] ?? 0;
+        return {
+            levels: {
+                min: percentile(0),
+                low: percentile(25),
+                medium: percentile(50),
+                high: percentile(75),
+                veryHigh: percentile(100),
+            },
+        };
+    }
+}
+/**
+ * Helius `getPriorityFeeEstimate` — account-aware percentile estimates. Helius
+ * already returns micro-lamports-per-CU figures keyed by the same level names we
+ * expose (`priorityFeeLevels`), so the mapping is direct. `fetchImpl` is
+ * injectable for deterministic tests and defaults to the global `fetch`; the
+ * API key, when provided, is appended to the request URL.
+ */
+export class HeliusFeeOracle {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async getPriorityFee(writableAccounts) {
+        const fetchImpl = this.config.fetchImpl ?? globalThis.fetch;
+        const url = this.config.apiKey
+            ? `${this.config.url}?api-key=${this.config.apiKey}`
+            : this.config.url;
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: "1",
+                method: "getPriorityFeeEstimate",
+                params: [
+                    {
+                        accountKeys: writableAccounts,
+                        options: { includeAllPriorityFeeLevels: true },
+                    },
+                ],
+            }),
+        });
+        const body = (await res.json());
+        const fees = body.result?.priorityFeeLevels ?? {};
+        const microLamports = (v) => Math.round(Number(v ?? 0));
+        return {
+            levels: {
+                min: microLamports(fees.min),
+                low: microLamports(fees.low),
+                medium: microLamports(fees.medium),
+                high: microLamports(fees.high),
+                veryHigh: microLamports(fees.veryHigh),
+            },
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * solana-resilience-kit — vendor-neutral, client-side resilience + observability
+ * layer for Solana dApps, built on @solana/kit (web3.js v2).
+ *
+ * Public API surface. Implementations are filled in during the build phase;
+ * the test suite under /test encodes the required behavior of every export.
+ */
+export * from "./errors.js";
+export { ResilientRpcPool } from "./rpc/pool.js";
+export type { ResilientEndpoint, ResilientRpcConfig } from "./rpc/pool.js";
+export { HealthMonitor } from "./rpc/health.js";
+export type { EndpointHealth, HealthMonitorConfig } from "./rpc/health.js";
+export { CreditRateLimiter, DEFAULT_METHOD_WEIGHTS } from "./rpc/rate-limit.js";
+export type { RateLimiterConfig } from "./rpc/rate-limit.js";
+export { TransactionSender } from "./tx/sender.js";
+export type { SendConfig, SendResult, SenderDeps } from "./tx/sender.js";
+export { ConfirmationTracker } from "./tx/confirmation.js";
+export type { TrackConfig, TrackResult, TerminalOutcome } from "./tx/confirmation.js";
+export { FeeEstimator } from "./fees/estimator.js";
+export type { ComputeBudget, EstimateConfig } from "./fees/estimator.js";
+export { NativeFeeOracle, HeliusFeeOracle } from "./fees/oracles.js";
+export type { FeeOracle, FeeLevel, PriorityFeeEstimate, HttpFeeOracleConfig } from "./fees/oracles.js";
+export { JitoRouter } from "./jito/router.js";
+export type { JitoEngineClient, JitoRouteConfig, JitoRouteResult } from "./jito/router.js";
+export { TipEstimator, MIN_TIP_LAMPORTS } from "./jito/tips.js";
+export type { TipFloor, TipPercentile, TipEstimatorConfig } from "./jito/tips.js";
+export { InMemoryMetrics, OtelMetrics } from "./observability/metrics.js";
+export type { Metrics, OtelMetricsConfig } from "./observability/metrics.js";
+export { ResilientWalletAdapter } from "./wallet/adapter.js";
+export type { WalletSigner, ResilientWalletConfig } from "./wallet/adapter.js";
+export { Diagnostics } from "./cli/diagnose.js";
+export type { ProbeTarget, EndpointProbe, ProbeReport, TxDiagnosis, DiagnosticsDeps, } from "./cli/diagnose.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * solana-resilience-kit — vendor-neutral, client-side resilience + observability
+ * layer for Solana dApps, built on @solana/kit (web3.js v2).
+ *
+ * Public API surface. Implementations are filled in during the build phase;
+ * the test suite under /test encodes the required behavior of every export.
+ */
+// Errors
+export * from "./errors.js";
+// RPC layer
+export { ResilientRpcPool } from "./rpc/pool.js";
+export { HealthMonitor } from "./rpc/health.js";
+export { CreditRateLimiter, DEFAULT_METHOD_WEIGHTS } from "./rpc/rate-limit.js";
+// Transactions
+export { TransactionSender } from "./tx/sender.js";
+export { ConfirmationTracker } from "./tx/confirmation.js";
+// Fees
+export { FeeEstimator } from "./fees/estimator.js";
+export { NativeFeeOracle, HeliusFeeOracle } from "./fees/oracles.js";
+// Jito / MEV
+export { JitoRouter } from "./jito/router.js";
+export { TipEstimator, MIN_TIP_LAMPORTS } from "./jito/tips.js";
+// Observability
+export { InMemoryMetrics, OtelMetrics } from "./observability/metrics.js";
+// Wallet
+export { ResilientWalletAdapter } from "./wallet/adapter.js";
+// Diagnostics
+export { Diagnostics } from "./cli/diagnose.js";

package/dist/jito/router.d.ts

@@ -0,0 +1,53 @@
+/**
+ * JitoRouter — routes a transaction/bundle through the Jito Block Engine for MEV
+ * protection, polls in-flight status, and FALLS BACK to normal RPC submission
+ * if the bundle does not land before the deadline. A bundle_id is only a receipt,
+ * not a landing guarantee, so fallback is mandatory for reliable confirmation.
+ */
+import type { TransactionSender, SendConfig, SendResult } from "../tx/sender.js";
+import type { TipEstimator, TipPercentile } from "./tips.js";
+export interface JitoEngineClient {
+    getTipAccounts(): Promise<string[]>;
+    sendBundle(wireTransactions: string[]): Promise<string>;
+    getInflightBundleStatuses(ids: string[]): Promise<Array<{
+        bundle_id: string;
+        status: string;
+    }>>;
+}
+export interface JitoRouteConfig extends SendConfig {
+    /** Tip percentile to target (default "p50"). */
+    tipPercentile?: TipPercentile;
+    /** Max status polls before falling back to RPC (default 10). */
+    maxBundlePolls?: number;
+}
+export interface JitoRouteResult extends SendResult {
+    /** "jito" if the bundle landed, "rpc" if we fell back. */
+    route: "jito" | "rpc";
+    bundleId: string | null;
+}
+export interface JitoRouterDeps {
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class JitoRouter {
+    private readonly engine;
+    private readonly tipEstimator;
+    private readonly fallbackSender;
+    private readonly sleep;
+    constructor(engine: JitoEngineClient, tipEstimator: TipEstimator, fallbackSender: TransactionSender, deps?: JitoRouterDeps);
+    /**
+     * Submit via Jito; fall back to RPC sender if the bundle doesn't land.
+     *
+     * Correctness invariants (see CLAUDE.md):
+     *  - A `bundle_id` is a receipt, NOT a landing guarantee. We poll in-flight
+     *    status a bounded number of times (`maxBundlePolls`) and, on anything
+     *    other than a confirmed "Landed", hand the SAME already-signed wire
+     *    transaction to the RPC `TransactionSender`. The fallback inherits the
+     *    sender's invariants (maxRetries:0, no re-sign, LVBH-bounded loop), so
+     *    there is no double-charge and the path is idempotent by signature.
+     *  - On the Jito-landed path we do NOT poll the cluster for confirmation:
+     *    a "Landed" bundle IS the confirmation. The transaction may never have
+     *    been broadcast to the RPC, so a getSignatureStatuses poll would falsely
+     *    expire it. We return outcome "confirmed" with slot null directly.
+     */
+    sendWithFallback(config: JitoRouteConfig): Promise<JitoRouteResult>;
+}

package/dist/jito/router.js

@@ -0,0 +1,53 @@
+export class JitoRouter {
+    engine;
+    tipEstimator;
+    fallbackSender;
+    sleep;
+    constructor(engine, tipEstimator, fallbackSender, deps) {
+        this.engine = engine;
+        this.tipEstimator = tipEstimator;
+        this.fallbackSender = fallbackSender;
+        this.sleep = deps?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    /**
+     * Submit via Jito; fall back to RPC sender if the bundle doesn't land.
+     *
+     * Correctness invariants (see CLAUDE.md):
+     *  - A `bundle_id` is a receipt, NOT a landing guarantee. We poll in-flight
+     *    status a bounded number of times (`maxBundlePolls`) and, on anything
+     *    other than a confirmed "Landed", hand the SAME already-signed wire
+     *    transaction to the RPC `TransactionSender`. The fallback inherits the
+     *    sender's invariants (maxRetries:0, no re-sign, LVBH-bounded loop), so
+     *    there is no double-charge and the path is idempotent by signature.
+     *  - On the Jito-landed path we do NOT poll the cluster for confirmation:
+     *    a "Landed" bundle IS the confirmation. The transaction may never have
+     *    been broadcast to the RPC, so a getSignatureStatuses poll would falsely
+     *    expire it. We return outcome "confirmed" with slot null directly.
+     */
+    async sendWithFallback(config) {
+        const maxBundlePolls = config.maxBundlePolls ?? 10;
+        const bundleId = await this.engine.sendBundle([config.wireTransaction]);
+        for (let i = 0; i < maxBundlePolls; i++) {
+            const statuses = await this.engine.getInflightBundleStatuses([bundleId]);
+            const status = statuses[0]?.status;
+            if (status === "Landed") {
+                return {
+                    signature: config.signature,
+                    outcome: "confirmed",
+                    slot: null,
+                    rebroadcasts: 0,
+                    route: "jito",
+                    bundleId,
+                };
+            }
+            // Unrecoverable on Jito -> stop polling and fall back to RPC.
+            if (status === "Failed" || status === "Invalid")
+                break;
+            await this.sleep(config.rebroadcastIntervalMs ?? 1000);
+        }
+        // Bundle never landed -> RPC fallback (the mandatory invariant). The
+        // sender owns the rebroadcast/confirm loop on the identical signed bytes.
+        const r = await this.fallbackSender.sendAndConfirm(config);
+        return { ...r, route: "rpc", bundleId };
+    }
+}

package/dist/jito/tips.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TipEstimator — sizes a Jito tip from live tip-floor percentiles, clamped to
+ * the protocol minimum (1000 lamports). Tips are economically distinct from
+ * priority fees and drive bundle auction priority.
+ */
+export declare const MIN_TIP_LAMPORTS = 1000;
+export type TipPercentile = "p25" | "p50" | "p75" | "p95" | "p99";
+export interface TipFloor {
+    p25: number;
+    p50: number;
+    p75: number;
+    p95: number;
+    p99: number;
+}
+export interface TipEstimatorConfig {
+    /** Endpoint serving tip-floor data (default Jito public tip_floor REST). */
+    tipFloorUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class TipEstimator {
+    private readonly config?;
+    constructor(config?: TipEstimatorConfig | undefined);
+    /**
+     * Fetches current tip-floor percentiles and returns them in lamports.
+     *
+     * The Jito public tip_floor REST endpoint returns an array whose first
+     * element carries `landed_tips_*_percentile` fields denominated in SOL. We
+     * are defensive about array-vs-object shape and convert SOL -> lamports.
+     */
+    getTipFloor(): Promise<TipFloor>;
+    /** Recommends a tip (lamports) at the chosen percentile, clamped to minimum. */
+    recommendTip(percentile?: TipPercentile): Promise<number>;
+}

package/dist/jito/tips.js

@@ -0,0 +1,40 @@
+/**
+ * TipEstimator — sizes a Jito tip from live tip-floor percentiles, clamped to
+ * the protocol minimum (1000 lamports). Tips are economically distinct from
+ * priority fees and drive bundle auction priority.
+ */
+export const MIN_TIP_LAMPORTS = 1000;
+const DEFAULT_TIP_FLOOR_URL = "https://bundles.jito.wtf/api/v1/bundles/tip_floor";
+export class TipEstimator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Fetches current tip-floor percentiles and returns them in lamports.
+     *
+     * The Jito public tip_floor REST endpoint returns an array whose first
+     * element carries `landed_tips_*_percentile` fields denominated in SOL. We
+     * are defensive about array-vs-object shape and convert SOL -> lamports.
+     */
+    async getTipFloor() {
+        const fetchImpl = this.config?.fetchImpl ?? globalThis.fetch;
+        const url = this.config?.tipFloorUrl ?? DEFAULT_TIP_FLOOR_URL;
+        const res = await fetchImpl(url);
+        const body = await res.json();
+        const record = (Array.isArray(body) ? body[0] : body) ?? {};
+        const toLamports = (sol) => Math.round((sol ?? 0) * 1e9);
+        return {
+            p25: toLamports(record.landed_tips_25th_percentile),
+            p50: toLamports(record.landed_tips_50th_percentile),
+            p75: toLamports(record.landed_tips_75th_percentile),
+            p95: toLamports(record.landed_tips_95th_percentile),
+            p99: toLamports(record.landed_tips_99th_percentile),
+        };
+    }
+    /** Recommends a tip (lamports) at the chosen percentile, clamped to minimum. */
+    async recommendTip(percentile = "p50") {
+        const floor = await this.getTipFloor();
+        return Math.max(floor[percentile], MIN_TIP_LAMPORTS);
+    }
+}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,62 @@
+import type { Meter } from "@opentelemetry/api";
+export interface Metrics {
+    /** Per-endpoint request latency (ms) with success/failure outcome. */
+    recordRequest(endpoint: string, method: string, latencyMs: number, ok: boolean): void;
+    /** A request was rate-limited (HTTP 429). */
+    recordRateLimited(endpoint: string): void;
+    /** A transaction was (re)broadcast to the network. */
+    recordRebroadcast(signature: string): void;
+    /** Terminal transaction outcome. */
+    recordLanding(signature: string, outcome: "confirmed" | "expired", slots: number): void;
+    /** Observed slot for an endpoint (drives slot-lag dashboards). */
+    recordSlot(endpoint: string, slot: bigint): void;
+}
+/** Trivial, fully-implemented metrics sink for tests and local debugging. */
+export declare class InMemoryMetrics implements Metrics {
+    readonly requests: Array<{
+        endpoint: string;
+        method: string;
+        latencyMs: number;
+        ok: boolean;
+    }>;
+    readonly rateLimited: string[];
+    readonly rebroadcasts: string[];
+    readonly landings: Array<{
+        signature: string;
+        outcome: "confirmed" | "expired";
+        slots: number;
+    }>;
+    readonly slots: Array<{
+        endpoint: string;
+        slot: bigint;
+    }>;
+    recordRequest(endpoint: string, method: string, latencyMs: number, ok: boolean): void;
+    recordRateLimited(endpoint: string): void;
+    recordRebroadcast(signature: string): void;
+    recordLanding(signature: string, outcome: "confirmed" | "expired", slots: number): void;
+    recordSlot(endpoint: string, slot: bigint): void;
+    /** Convenience aggregations the diagnostics CLI / dashboard will reuse. */
+    successRate(): number;
+}
+export interface OtelMetricsConfig {
+    serviceName?: string;
+    /** OTLP endpoint, e.g. a Datadog Agent or OTel Collector. */
+    otlpEndpoint?: string;
+    /** Inject a Meter for tests; defaults to the global OTel meter. */
+    meter?: Meter;
+}
+/** OpenTelemetry/Datadog-backed metrics. Bridges {@link Metrics} to OTel instruments. */
+export declare class OtelMetrics implements Metrics {
+    private readonly latency;
+    private readonly failures;
+    private readonly rateLimited;
+    private readonly rebroadcasts;
+    private readonly landings;
+    private readonly slot;
+    constructor(config?: OtelMetricsConfig);
+    recordRequest(endpoint: string, method: string, latencyMs: number, ok: boolean): void;
+    recordRateLimited(endpoint: string): void;
+    recordRebroadcast(signature: string): void;
+    recordLanding(signature: string, outcome: "confirmed" | "expired", slots: number): void;
+    recordSlot(endpoint: string, slot: bigint): void;
+}

package/dist/observability/metrics.js

@@ -0,0 +1,74 @@
+/**
+ * Observability surface. The SDK emits a small, fixed set of client-side
+ * signals — the metrics the ecosystem currently re-implements by hand. The
+ * `Metrics` interface decouples the SDK from any backend; `InMemoryMetrics` is
+ * a real implementation used by tests to assert the SDK emits the right
+ * signals, and `OtelMetrics` (to be implemented) bridges to OpenTelemetry /
+ * Datadog via the OTLP exporter.
+ */
+import { metrics } from "@opentelemetry/api";
+/** Trivial, fully-implemented metrics sink for tests and local debugging. */
+export class InMemoryMetrics {
+    requests = [];
+    rateLimited = [];
+    rebroadcasts = [];
+    landings = [];
+    slots = [];
+    recordRequest(endpoint, method, latencyMs, ok) {
+        this.requests.push({ endpoint, method, latencyMs, ok });
+    }
+    recordRateLimited(endpoint) {
+        this.rateLimited.push(endpoint);
+    }
+    recordRebroadcast(signature) {
+        this.rebroadcasts.push(signature);
+    }
+    recordLanding(signature, outcome, slots) {
+        this.landings.push({ signature, outcome, slots });
+    }
+    recordSlot(endpoint, slot) {
+        this.slots.push({ endpoint, slot });
+    }
+    /** Convenience aggregations the diagnostics CLI / dashboard will reuse. */
+    successRate() {
+        if (this.requests.length === 0)
+            return 1;
+        return this.requests.filter((r) => r.ok).length / this.requests.length;
+    }
+}
+/** OpenTelemetry/Datadog-backed metrics. Bridges {@link Metrics} to OTel instruments. */
+export class OtelMetrics {
+    latency;
+    failures;
+    rateLimited;
+    rebroadcasts;
+    landings;
+    slot;
+    constructor(config) {
+        const meter = config?.meter ?? metrics.getMeter(config?.serviceName ?? "solana-resilience-kit");
+        this.latency = meter.createHistogram("rpc.request.latency_ms");
+        this.failures = meter.createCounter("rpc.request.failures");
+        this.rateLimited = meter.createCounter("rpc.rate_limited");
+        this.rebroadcasts = meter.createCounter("tx.rebroadcasts");
+        this.landings = meter.createCounter("tx.landings");
+        this.slot = meter.createGauge("rpc.endpoint.slot");
+    }
+    recordRequest(endpoint, method, latencyMs, ok) {
+        this.latency.record(latencyMs, { endpoint, method, ok });
+        if (!ok)
+            this.failures.add(1, { endpoint, method });
+    }
+    recordRateLimited(endpoint) {
+        this.rateLimited.add(1, { endpoint });
+    }
+    recordRebroadcast(signature) {
+        this.rebroadcasts.add(1, { signature });
+    }
+    recordLanding(signature, outcome, slots) {
+        this.landings.add(1, { signature, outcome, slots });
+    }
+    recordSlot(endpoint, slot) {
+        // Slots are well within Number.MAX_SAFE_INTEGER; gauges take numbers.
+        this.slot.record(Number(slot), { endpoint });
+    }
+}

package/dist/rpc/health.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HealthMonitor — tracks per-endpoint freshness and reliability so the pool can
+ * route to healthy, up-to-date nodes and avoid the "lagging node drops your tx"
+ * failure mode. Freshness is judged by comparing observed slots across
+ * endpoints; an endpoint more than `maxSlotLag` behind the best is unhealthy.
+ */
+export interface EndpointHealth {
+    name: string;
+    healthy: boolean;
+    slot: bigint | null;
+    /** Exponentially-weighted mean latency in ms. */
+    latencyMs: number;
+    /** Rolling error rate in [0,1]. */
+    errorRate: number;
+    consecutiveFailures: number;
+    lastError: unknown | null;
+}
+export interface HealthMonitorConfig {
+    endpointNames: string[];
+    /** Slots behind the freshest node before an endpoint is deemed stale. */
+    maxSlotLag?: bigint;
+    /** Consecutive failures before an endpoint is ejected. */
+    failureThreshold?: number;
+    /** EWMA smoothing factor for latency (0..1). */
+    latencyAlpha?: number;
+}
+export declare class HealthMonitor {
+    private readonly maxSlotLag;
+    private readonly failureThreshold;
+    private readonly latencyAlpha;
+    private readonly states;
+    constructor(config: HealthMonitorConfig);
+    recordSuccess(endpoint: string, latencyMs: number, slot?: bigint): void;
+    recordFailure(endpoint: string, error: unknown): void;
+    isHealthy(endpoint: string): boolean;
+    /** Healthy endpoints ordered best-first (freshest slot, then lowest latency). */
+    rankByFreshness(): string[];
+    snapshot(): EndpointHealth[];
+    /** Max of all non-null observed slots across endpoints; 0n when none seen. */
+    private freshestSlot;
+}

package/dist/rpc/health.js

@@ -0,0 +1,120 @@
+/**
+ * HealthMonitor — tracks per-endpoint freshness and reliability so the pool can
+ * route to healthy, up-to-date nodes and avoid the "lagging node drops your tx"
+ * failure mode. Freshness is judged by comparing observed slots across
+ * endpoints; an endpoint more than `maxSlotLag` behind the best is unhealthy.
+ */
+/** Step applied to errorRate per success (down) / failure (up). Keeps the rate
+ * a bounded [0,1] rolling signal without needing a full window of samples. */
+const ERROR_RATE_STEP = 0.1;
+export class HealthMonitor {
+    maxSlotLag;
+    failureThreshold;
+    latencyAlpha;
+    states = new Map();
+    constructor(config) {
+        this.maxSlotLag = config.maxSlotLag ?? 150n;
+        this.failureThreshold = config.failureThreshold ?? 3;
+        this.latencyAlpha = config.latencyAlpha ?? 0.3;
+        for (const name of config.endpointNames) {
+            this.states.set(name, {
+                name,
+                slot: null,
+                latencyMs: 0,
+                latencySeeded: false,
+                errorRate: 0,
+                consecutiveFailures: 0,
+                lastError: null,
+            });
+        }
+    }
+    recordSuccess(endpoint, latencyMs, slot) {
+        const state = this.states.get(endpoint);
+        if (state === undefined)
+            return; // guard unknown endpoint names
+        state.consecutiveFailures = 0;
+        if (!state.latencySeeded) {
+            state.latencyMs = latencyMs;
+            state.latencySeeded = true;
+        }
+        else {
+            state.latencyMs =
+                this.latencyAlpha * latencyMs + (1 - this.latencyAlpha) * state.latencyMs;
+        }
+        if (slot !== undefined) {
+            state.slot = slot;
+        }
+        state.errorRate = clamp01(state.errorRate - ERROR_RATE_STEP);
+        state.lastError = null;
+    }
+    recordFailure(endpoint, error) {
+        const state = this.states.get(endpoint);
+        if (state === undefined)
+            return; // guard unknown endpoint names
+        state.consecutiveFailures += 1;
+        state.lastError = error;
+        state.errorRate = clamp01(state.errorRate + ERROR_RATE_STEP);
+    }
+    isHealthy(endpoint) {
+        const state = this.states.get(endpoint);
+        if (state === undefined)
+            return false; // unknown endpoint is never healthy
+        if (state.consecutiveFailures >= this.failureThreshold)
+            return false;
+        if (state.slot !== null) {
+            const lag = this.freshestSlot() - state.slot;
+            if (lag > this.maxSlotLag)
+                return false;
+        }
+        return true;
+    }
+    /** Healthy endpoints ordered best-first (freshest slot, then lowest latency). */
+    rankByFreshness() {
+        return [...this.states.values()]
+            .filter((s) => this.isHealthy(s.name))
+            .sort((a, b) => {
+            // Freshest slot first; nulls sort last.
+            if (a.slot !== b.slot) {
+                if (a.slot === null)
+                    return 1;
+                if (b.slot === null)
+                    return -1;
+                if (a.slot > b.slot)
+                    return -1;
+                if (a.slot < b.slot)
+                    return 1;
+            }
+            // Tie-break: lower latency first.
+            return a.latencyMs - b.latencyMs;
+        })
+            .map((s) => s.name);
+    }
+    snapshot() {
+        return [...this.states.values()].map((s) => ({
+            name: s.name,
+            healthy: this.isHealthy(s.name),
+            slot: s.slot,
+            latencyMs: s.latencyMs,
+            errorRate: s.errorRate,
+            consecutiveFailures: s.consecutiveFailures,
+            lastError: s.lastError,
+        }));
+    }
+    /** Max of all non-null observed slots across endpoints; 0n when none seen. */
+    freshestSlot() {
+        let max = 0n;
+        for (const state of this.states.values()) {
+            if (state.slot !== null && state.slot > max) {
+                max = state.slot;
+            }
+        }
+        return max;
+    }
+}
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}