rpc-bastion 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,324 @@
+import { BreakerState, EndpointHealth, LoadBalancerStrategy, CircuitBreakerOptions, RpcSubscriptionsApiLike, Clock } from '@rpc-bastion/core';
+import { ChaosPlan } from '@rpc-bastion/testkit';
+import { SenderRpc, Commitment, ConfirmationOutcome } from '@rpc-bastion/sender';
+
+/** The doctor only reads time; a `now()` source is all it needs. */
+type DoctorClock = {
+    now(): number;
+};
+/** The minimal per-endpoint RPC surface `doctor` probes. */
+interface DoctorRpc {
+    getSlot(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<bigint>;
+    };
+    getHealth(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<string>;
+    };
+    getVersion(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<{
+            'solana-core'?: string;
+            'feature-set'?: number;
+        }>;
+    };
+}
+/** Builds a {@link DoctorRpc} for an endpoint URL. */
+type DoctorRpcFactory = (url: string) => DoctorRpc;
+/** Per-endpoint diagnostic result. */
+interface EndpointDiagnostic {
+    url: string;
+    /** `true` if the endpoint answered every probe. */
+    reachable: boolean;
+    /** Median latency over the probes (ms), or null if unreachable. */
+    latencyP50Ms: number | null;
+    /** `getHealth` result (`ok` / a behind message), or null. */
+    health: string | null;
+    /** Latest slot seen, or null. */
+    slot: bigint | null;
+    /** Slots behind the freshest endpoint in this run, or null. */
+    slotLag: number | null;
+    /** `solana-core` version, or null. */
+    version: string | null;
+    /** First error message, if any probe failed. */
+    error: string | null;
+}
+/** The full doctor report (the `--json` payload). */
+interface DoctorReport {
+    endpoints: EndpointDiagnostic[];
+    /** Freshest slot across reachable endpoints, or null. */
+    clusterMaxSlot: bigint | null;
+    /** Count reachable / total. */
+    reachable: number;
+    total: number;
+}
+/** Options for {@link runDoctor}. */
+interface DoctorOptions {
+    /** Latency probes per endpoint (default 5). */
+    probes?: number;
+    rpcFactory: DoctorRpcFactory;
+    clock?: DoctorClock;
+    signal?: AbortSignal;
+}
+/** Median of a numeric array (linear interpolation not needed for ms). */
+declare function median(values: readonly number[]): number | null;
+/**
+ * Turns a probe failure into a human-readable message.
+ *
+ * Works around an upstream Solana Kit defect: when an endpoint answers HTTP 200
+ * with a JSON-RPC *error* whose code Kit's message template can't render (e.g. a
+ * keyless gateway returning `-32000 "needs an API key"`), Kit's own formatter
+ * (`@solana/errors` → `getHumanReadableErrorMessage`, reached via
+ * `getSolanaErrorFromJsonRpcError` → `new SolanaError`) throws a bare
+ * `TypeError: Cannot read properties of undefined (reading 'length')` *instead of*
+ * the intended SolanaError. That TypeError carries no `context`/`code`, so the
+ * real RPC message is unrecoverable — but its stack unambiguously identifies the
+ * cause. Detect that signature and report something actionable rather than leaking
+ * Kit's internal failure.
+ */
+declare function describeProbeError(e: unknown): string;
+/**
+ * Probes a single endpoint: `probes` latency-timed `getSlot` calls (p50), one
+ * `getHealth`, and one `getVersion`. Never throws — failures are captured in the
+ * returned diagnostic. Pure given an injected `rpcFactory` + `clock`.
+ */
+declare function probeEndpoint(url: string, options: {
+    probes: number;
+    rpc: DoctorRpc;
+    clock: DoctorClock;
+    signal?: AbortSignal;
+}): Promise<EndpointDiagnostic>;
+/**
+ * Runs `doctor` across all endpoints: probes each (in parallel), computes the
+ * cluster-max slot, and back-fills each endpoint's `slotLag`. Pure given the
+ * injected `rpcFactory`/`clock` — the rendering layer formats the result.
+ */
+declare function runDoctor(urls: readonly string[], options: DoctorOptions): Promise<DoctorReport>;
+/** Serializes a {@link DoctorReport} to stable JSON (bigint → string). */
+declare function doctorReportToJson(report: DoctorReport): string;
+
+/** The `bastion.config.json` shape. */
+interface BastionConfig {
+    endpoints: string[];
+    jito?: {
+        region?: string;
+        baseUrl?: string;
+    };
+}
+/**
+ * Parses + validates a `bastion.config.json` payload. Pure (takes the already-read
+ * text) so it's testable without filesystem access. Throws a clear error on a
+ * malformed config.
+ */
+declare function parseConfig(text: string): BastionConfig;
+/**
+ * Resolves endpoints from either `--endpoints` (comma-separated) or a parsed
+ * config. `--endpoints` wins when both are present.
+ */
+declare function resolveEndpoints(opts: {
+    endpoints?: string;
+    config?: BastionConfig;
+}): string[];
+
+/** A parsed command line: the command, positional args, and flags. */
+interface ParsedArgs {
+    command: string | null;
+    positionals: string[];
+    /** `--flag value` and `--bool` (→ `true`). */
+    flags: Record<string, string | boolean>;
+}
+/**
+ * A tiny, dependency-free argv parser. `--key value` → `{ key: 'value' }`;
+ * `--key=value` → same; a bare `--flag` (followed by another flag or nothing) →
+ * `{ flag: true }`. The first non-flag token is the command; the rest are
+ * positionals. Pure and fully testable.
+ */
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/** Reads a flag as a string, or returns `undefined`. */
+declare function flagString(args: ParsedArgs, name: string): string | undefined;
+/** Reads a flag as a boolean (presence or `true`). */
+declare function flagBool(args: ParsedArgs, name: string): boolean;
+/** Reads a flag as a positive integer, or `fallback`. */
+declare function flagInt(args: ParsedArgs, name: string, fallback: number): number;
+
+/** A formatted row for the monitor table (pure projection of EndpointHealth). */
+interface MonitorRow {
+    url: string;
+    /** Status dot category. */
+    dot: 'green' | 'yellow' | 'red';
+    latencyMs: number;
+    errorRatePct: number;
+    slotLag: number | null;
+    breaker: BreakerState;
+    inFlight: number;
+}
+/** A summary across the whole pool. */
+interface MonitorSummary {
+    rows: MonitorRow[];
+    healthy: number;
+    total: number;
+    /** Worst (highest) slot lag across endpoints, or null. */
+    maxSlotLag: number | null;
+}
+/** Categorizes an endpoint into a status dot from its health + breaker. */
+declare function statusDot(health: EndpointHealth): MonitorRow['dot'];
+/**
+ * Projects a pool health snapshot into renderable monitor rows + a summary.
+ * Pure — the rendering layer turns this into a table/sparkline. Reuses the same
+ * `EndpointHealth` the SDK pool produces (no parallel health model).
+ */
+declare function summarizeSnapshot(snapshot: readonly EndpointHealth[]): MonitorSummary;
+/**
+ * Appends a latency sample to a bounded ring buffer (for the monitor sparkline).
+ * Returns a NEW array (immutable), keeping at most `size` samples.
+ */
+declare function pushSample(history: readonly number[], sample: number, size?: number): number[];
+
+/** A named, scripted chaos scenario for `bastion simulate`. */
+interface Scenario {
+    name: string;
+    description: string;
+    endpoints: string[];
+    /** Per-endpoint chaos plan, keyed by endpoint url. */
+    plans: Record<string, ChaosPlan>;
+    /** How many probe ticks to run (default 10). */
+    ticks: number;
+    /** Load-balancer strategy (default the pool's `health-weighted`). */
+    strategy?: LoadBalancerStrategy;
+    /**
+     * User-level calls issued per tick (default 1). A small burst lets a failing
+     * endpoint accumulate enough failures to trip its breaker — the drama beat.
+     */
+    callsPerTick?: number;
+    /** Per-scenario breaker tuning, so a scenario can show open → half-open → closed. */
+    breaker?: CircuitBreakerOptions;
+}
+/** A narrative event observed during one tick, projected from the bus. */
+interface TickEvent {
+    /** Compact kind for the renderer to colour: which arc beat this is. */
+    kind: 'served' | 'error' | 'failover' | 'breaker-open' | 'breaker-half-open' | 'breaker-closed';
+    /** The endpoint this event is about (the `to` endpoint for a failover). */
+    endpoint: string;
+    /** A short human label, e.g. `rpc-a → rpc-b` or `OPEN`. */
+    detail: string;
+}
+/** A single tick of a simulation: the health snapshot after the tick's probe. */
+interface SimulationTick {
+    tick: number;
+    snapshot: EndpointHealth[];
+    /**
+     * The endpoint that ultimately served this tick's user-level call, or null if
+     * the call failed on every survivor. Drives the per-endpoint traffic counters.
+     */
+    servedBy?: string | null;
+    /** `false` only when the user-level call threw after all failover/retry. */
+    userCallOk?: boolean;
+    /** Narrative events the bus emitted during this tick (failover, breaker flips). */
+    events?: TickEvent[];
+}
+/** The aggregate verdict of a simulation run — the "0 failed user calls" thesis. */
+interface SimulationSummary {
+    /** Every tick is one user-level call. */
+    userCallsTotal: number;
+    /** Calls that threw after all failover + retry were exhausted. */
+    userCallsFailed: number;
+    /** Per-endpoint served count + error count over the run. */
+    perEndpoint: Array<{
+        url: string;
+        served: number;
+        errors: number;
+    }>;
+    /** Count of breaker open transitions observed. */
+    breakerOpens: number;
+}
+/** The built-in scenario catalogue. */
+declare const SCENARIOS: Record<string, Scenario>;
+/** Lists the available scenario names + descriptions. */
+declare function listScenarios(): Array<{
+    name: string;
+    description: string;
+}>;
+/** Options for {@link runSimulation}. */
+interface SimulationOptions {
+    /** Advances the simulated clock + mock chain by this many ms per tick (default 500). */
+    tickMs?: number;
+    seed?: number;
+    /** Called after each tick (for live rendering). */
+    onTick?: (tick: SimulationTick) => void;
+    /** Drives time + the mock chain forward between ticks (injected for tests). */
+    advance: (ms: number) => Promise<void> | void;
+    /** Reads "now" in ms (injected; defaults to a tick-counted clock). */
+    now: () => number;
+}
+/**
+ * Runs a named scenario against a resilient pool built over chaos transports
+ * (real SDK pool/health code), returning a snapshot per tick. The caller injects
+ * `advance`/`now` so tests drive it deterministically with fake timers + a
+ * ManualClock; the renderer just consumes the ticks.
+ */
+declare function runSimulation(scenario: Scenario, options: SimulationOptions): Promise<SimulationTick[]>;
+/**
+ * Projects a finished run into the headline verdict: how many user-level calls
+ * the SDK made, how many failed despite failover/retry (the thesis is **zero**),
+ * per-endpoint traffic, and how many times a breaker opened. Pure over the ticks.
+ */
+declare function summarizeSimulation(ticks: readonly SimulationTick[]): SimulationSummary;
+
+/** A point-in-time status line for the `watch-tx` UI. */
+interface WatchTxUpdate {
+    at: number;
+    state: 'watching' | 'confirmed' | 'failed' | 'expired' | 'aborted';
+    detail: string;
+}
+/** Final result of watching a transaction. */
+interface WatchTxResult {
+    signature: string;
+    outcome: ConfirmationOutcome['type'];
+    slot: bigint | null;
+    updates: WatchTxUpdate[];
+}
+/** Options for {@link watchTransaction}. */
+interface WatchTxOptions {
+    rpc: SenderRpc;
+    rpcSubscriptions?: RpcSubscriptionsApiLike;
+    lastValidBlockHeight: bigint;
+    commitment?: Commitment;
+    clock?: Clock;
+    pollIntervalMs?: number;
+    blockHeightIntervalMs?: number;
+    signal?: AbortSignal;
+    /** Called on each status update (for live rendering). */
+    onUpdate?: (update: WatchTxUpdate) => void;
+}
+/**
+ * Watches a transaction signature to a terminal state, reusing the SDK's
+ * confirmation engine (WS + polling race). Returns the outcome plus a timeline of
+ * updates. Pure given injected `rpc`/`clock` — no rendering here.
+ */
+declare function watchTransaction(signature: string, options: WatchTxOptions): Promise<WatchTxResult>;
+
+/** The set of known commands. */
+declare const COMMANDS: readonly ["doctor", "monitor", "watch-tx", "simulate", "help"];
+type Command = (typeof COMMANDS)[number];
+/**
+ * Resolves the command to run from parsed args. Pure + fully tested — this is the
+ * routing brain; the live `main()` (which does I/O) lives in `./ui/run`.
+ */
+declare function route(args: ParsedArgs): Command;
+
+/**
+ * rpc-bastion — the `bastion` diagnostics CLI: doctor, monitor, watch-tx, simulate.
+ *
+ * The data layer (endpoint probing, health aggregation, scenario simulation,
+ * config/arg parsing) is exported here for programmatic use and is fully
+ * unit-tested; the rendering + live-I/O layer lives under `src/ui/**` (excluded
+ * from coverage). The executable itself is `src/bin.ts` → `dist/bin.cjs`.
+ */
+/** Package semver, surfaced for diagnostics and the CLI `doctor` command. */
+declare const VERSION = "0.3.0";
+
+export { type BastionConfig, COMMANDS, type Command, type DoctorClock, type DoctorOptions, type DoctorReport, type DoctorRpc, type DoctorRpcFactory, type EndpointDiagnostic, type MonitorRow, type MonitorSummary, type ParsedArgs, SCENARIOS, type Scenario, type SimulationOptions, type SimulationSummary, type SimulationTick, type TickEvent, VERSION, type WatchTxOptions, type WatchTxResult, type WatchTxUpdate, describeProbeError, doctorReportToJson, flagBool, flagInt, flagString, listScenarios, median, parseArgs, parseConfig, probeEndpoint, pushSample, resolveEndpoints, route, runDoctor, runSimulation, statusDot, summarizeSimulation, summarizeSnapshot, watchTransaction };

package/dist/index.d.ts

@@ -0,0 +1,324 @@
+import { BreakerState, EndpointHealth, LoadBalancerStrategy, CircuitBreakerOptions, RpcSubscriptionsApiLike, Clock } from '@rpc-bastion/core';
+import { ChaosPlan } from '@rpc-bastion/testkit';
+import { SenderRpc, Commitment, ConfirmationOutcome } from '@rpc-bastion/sender';
+
+/** The doctor only reads time; a `now()` source is all it needs. */
+type DoctorClock = {
+    now(): number;
+};
+/** The minimal per-endpoint RPC surface `doctor` probes. */
+interface DoctorRpc {
+    getSlot(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<bigint>;
+    };
+    getHealth(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<string>;
+    };
+    getVersion(config?: Record<string, unknown>): {
+        send(opts?: {
+            abortSignal?: AbortSignal;
+        }): Promise<{
+            'solana-core'?: string;
+            'feature-set'?: number;
+        }>;
+    };
+}
+/** Builds a {@link DoctorRpc} for an endpoint URL. */
+type DoctorRpcFactory = (url: string) => DoctorRpc;
+/** Per-endpoint diagnostic result. */
+interface EndpointDiagnostic {
+    url: string;
+    /** `true` if the endpoint answered every probe. */
+    reachable: boolean;
+    /** Median latency over the probes (ms), or null if unreachable. */
+    latencyP50Ms: number | null;
+    /** `getHealth` result (`ok` / a behind message), or null. */
+    health: string | null;
+    /** Latest slot seen, or null. */
+    slot: bigint | null;
+    /** Slots behind the freshest endpoint in this run, or null. */
+    slotLag: number | null;
+    /** `solana-core` version, or null. */
+    version: string | null;
+    /** First error message, if any probe failed. */
+    error: string | null;
+}
+/** The full doctor report (the `--json` payload). */
+interface DoctorReport {
+    endpoints: EndpointDiagnostic[];
+    /** Freshest slot across reachable endpoints, or null. */
+    clusterMaxSlot: bigint | null;
+    /** Count reachable / total. */
+    reachable: number;
+    total: number;
+}
+/** Options for {@link runDoctor}. */
+interface DoctorOptions {
+    /** Latency probes per endpoint (default 5). */
+    probes?: number;
+    rpcFactory: DoctorRpcFactory;
+    clock?: DoctorClock;
+    signal?: AbortSignal;
+}
+/** Median of a numeric array (linear interpolation not needed for ms). */
+declare function median(values: readonly number[]): number | null;
+/**
+ * Turns a probe failure into a human-readable message.
+ *
+ * Works around an upstream Solana Kit defect: when an endpoint answers HTTP 200
+ * with a JSON-RPC *error* whose code Kit's message template can't render (e.g. a
+ * keyless gateway returning `-32000 "needs an API key"`), Kit's own formatter
+ * (`@solana/errors` → `getHumanReadableErrorMessage`, reached via
+ * `getSolanaErrorFromJsonRpcError` → `new SolanaError`) throws a bare
+ * `TypeError: Cannot read properties of undefined (reading 'length')` *instead of*
+ * the intended SolanaError. That TypeError carries no `context`/`code`, so the
+ * real RPC message is unrecoverable — but its stack unambiguously identifies the
+ * cause. Detect that signature and report something actionable rather than leaking
+ * Kit's internal failure.
+ */
+declare function describeProbeError(e: unknown): string;
+/**
+ * Probes a single endpoint: `probes` latency-timed `getSlot` calls (p50), one
+ * `getHealth`, and one `getVersion`. Never throws — failures are captured in the
+ * returned diagnostic. Pure given an injected `rpcFactory` + `clock`.
+ */
+declare function probeEndpoint(url: string, options: {
+    probes: number;
+    rpc: DoctorRpc;
+    clock: DoctorClock;
+    signal?: AbortSignal;
+}): Promise<EndpointDiagnostic>;
+/**
+ * Runs `doctor` across all endpoints: probes each (in parallel), computes the
+ * cluster-max slot, and back-fills each endpoint's `slotLag`. Pure given the
+ * injected `rpcFactory`/`clock` — the rendering layer formats the result.
+ */
+declare function runDoctor(urls: readonly string[], options: DoctorOptions): Promise<DoctorReport>;
+/** Serializes a {@link DoctorReport} to stable JSON (bigint → string). */
+declare function doctorReportToJson(report: DoctorReport): string;
+
+/** The `bastion.config.json` shape. */
+interface BastionConfig {
+    endpoints: string[];
+    jito?: {
+        region?: string;
+        baseUrl?: string;
+    };
+}
+/**
+ * Parses + validates a `bastion.config.json` payload. Pure (takes the already-read
+ * text) so it's testable without filesystem access. Throws a clear error on a
+ * malformed config.
+ */
+declare function parseConfig(text: string): BastionConfig;
+/**
+ * Resolves endpoints from either `--endpoints` (comma-separated) or a parsed
+ * config. `--endpoints` wins when both are present.
+ */
+declare function resolveEndpoints(opts: {
+    endpoints?: string;
+    config?: BastionConfig;
+}): string[];
+
+/** A parsed command line: the command, positional args, and flags. */
+interface ParsedArgs {
+    command: string | null;
+    positionals: string[];
+    /** `--flag value` and `--bool` (→ `true`). */
+    flags: Record<string, string | boolean>;
+}
+/**
+ * A tiny, dependency-free argv parser. `--key value` → `{ key: 'value' }`;
+ * `--key=value` → same; a bare `--flag` (followed by another flag or nothing) →
+ * `{ flag: true }`. The first non-flag token is the command; the rest are
+ * positionals. Pure and fully testable.
+ */
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/** Reads a flag as a string, or returns `undefined`. */
+declare function flagString(args: ParsedArgs, name: string): string | undefined;
+/** Reads a flag as a boolean (presence or `true`). */
+declare function flagBool(args: ParsedArgs, name: string): boolean;
+/** Reads a flag as a positive integer, or `fallback`. */
+declare function flagInt(args: ParsedArgs, name: string, fallback: number): number;
+
+/** A formatted row for the monitor table (pure projection of EndpointHealth). */
+interface MonitorRow {
+    url: string;
+    /** Status dot category. */
+    dot: 'green' | 'yellow' | 'red';
+    latencyMs: number;
+    errorRatePct: number;
+    slotLag: number | null;
+    breaker: BreakerState;
+    inFlight: number;
+}
+/** A summary across the whole pool. */
+interface MonitorSummary {
+    rows: MonitorRow[];
+    healthy: number;
+    total: number;
+    /** Worst (highest) slot lag across endpoints, or null. */
+    maxSlotLag: number | null;
+}
+/** Categorizes an endpoint into a status dot from its health + breaker. */
+declare function statusDot(health: EndpointHealth): MonitorRow['dot'];
+/**
+ * Projects a pool health snapshot into renderable monitor rows + a summary.
+ * Pure — the rendering layer turns this into a table/sparkline. Reuses the same
+ * `EndpointHealth` the SDK pool produces (no parallel health model).
+ */
+declare function summarizeSnapshot(snapshot: readonly EndpointHealth[]): MonitorSummary;
+/**
+ * Appends a latency sample to a bounded ring buffer (for the monitor sparkline).
+ * Returns a NEW array (immutable), keeping at most `size` samples.
+ */
+declare function pushSample(history: readonly number[], sample: number, size?: number): number[];
+
+/** A named, scripted chaos scenario for `bastion simulate`. */
+interface Scenario {
+    name: string;
+    description: string;
+    endpoints: string[];
+    /** Per-endpoint chaos plan, keyed by endpoint url. */
+    plans: Record<string, ChaosPlan>;
+    /** How many probe ticks to run (default 10). */
+    ticks: number;
+    /** Load-balancer strategy (default the pool's `health-weighted`). */
+    strategy?: LoadBalancerStrategy;
+    /**
+     * User-level calls issued per tick (default 1). A small burst lets a failing
+     * endpoint accumulate enough failures to trip its breaker — the drama beat.
+     */
+    callsPerTick?: number;
+    /** Per-scenario breaker tuning, so a scenario can show open → half-open → closed. */
+    breaker?: CircuitBreakerOptions;
+}
+/** A narrative event observed during one tick, projected from the bus. */
+interface TickEvent {
+    /** Compact kind for the renderer to colour: which arc beat this is. */
+    kind: 'served' | 'error' | 'failover' | 'breaker-open' | 'breaker-half-open' | 'breaker-closed';
+    /** The endpoint this event is about (the `to` endpoint for a failover). */
+    endpoint: string;
+    /** A short human label, e.g. `rpc-a → rpc-b` or `OPEN`. */
+    detail: string;
+}
+/** A single tick of a simulation: the health snapshot after the tick's probe. */
+interface SimulationTick {
+    tick: number;
+    snapshot: EndpointHealth[];
+    /**
+     * The endpoint that ultimately served this tick's user-level call, or null if
+     * the call failed on every survivor. Drives the per-endpoint traffic counters.
+     */
+    servedBy?: string | null;
+    /** `false` only when the user-level call threw after all failover/retry. */
+    userCallOk?: boolean;
+    /** Narrative events the bus emitted during this tick (failover, breaker flips). */
+    events?: TickEvent[];
+}
+/** The aggregate verdict of a simulation run — the "0 failed user calls" thesis. */
+interface SimulationSummary {
+    /** Every tick is one user-level call. */
+    userCallsTotal: number;
+    /** Calls that threw after all failover + retry were exhausted. */
+    userCallsFailed: number;
+    /** Per-endpoint served count + error count over the run. */
+    perEndpoint: Array<{
+        url: string;
+        served: number;
+        errors: number;
+    }>;
+    /** Count of breaker open transitions observed. */
+    breakerOpens: number;
+}
+/** The built-in scenario catalogue. */
+declare const SCENARIOS: Record<string, Scenario>;
+/** Lists the available scenario names + descriptions. */
+declare function listScenarios(): Array<{
+    name: string;
+    description: string;
+}>;
+/** Options for {@link runSimulation}. */
+interface SimulationOptions {
+    /** Advances the simulated clock + mock chain by this many ms per tick (default 500). */
+    tickMs?: number;
+    seed?: number;
+    /** Called after each tick (for live rendering). */
+    onTick?: (tick: SimulationTick) => void;
+    /** Drives time + the mock chain forward between ticks (injected for tests). */
+    advance: (ms: number) => Promise<void> | void;
+    /** Reads "now" in ms (injected; defaults to a tick-counted clock). */
+    now: () => number;
+}
+/**
+ * Runs a named scenario against a resilient pool built over chaos transports
+ * (real SDK pool/health code), returning a snapshot per tick. The caller injects
+ * `advance`/`now` so tests drive it deterministically with fake timers + a
+ * ManualClock; the renderer just consumes the ticks.
+ */
+declare function runSimulation(scenario: Scenario, options: SimulationOptions): Promise<SimulationTick[]>;
+/**
+ * Projects a finished run into the headline verdict: how many user-level calls
+ * the SDK made, how many failed despite failover/retry (the thesis is **zero**),
+ * per-endpoint traffic, and how many times a breaker opened. Pure over the ticks.
+ */
+declare function summarizeSimulation(ticks: readonly SimulationTick[]): SimulationSummary;
+
+/** A point-in-time status line for the `watch-tx` UI. */
+interface WatchTxUpdate {
+    at: number;
+    state: 'watching' | 'confirmed' | 'failed' | 'expired' | 'aborted';
+    detail: string;
+}
+/** Final result of watching a transaction. */
+interface WatchTxResult {
+    signature: string;
+    outcome: ConfirmationOutcome['type'];
+    slot: bigint | null;
+    updates: WatchTxUpdate[];
+}
+/** Options for {@link watchTransaction}. */
+interface WatchTxOptions {
+    rpc: SenderRpc;
+    rpcSubscriptions?: RpcSubscriptionsApiLike;
+    lastValidBlockHeight: bigint;
+    commitment?: Commitment;
+    clock?: Clock;
+    pollIntervalMs?: number;
+    blockHeightIntervalMs?: number;
+    signal?: AbortSignal;
+    /** Called on each status update (for live rendering). */
+    onUpdate?: (update: WatchTxUpdate) => void;
+}
+/**
+ * Watches a transaction signature to a terminal state, reusing the SDK's
+ * confirmation engine (WS + polling race). Returns the outcome plus a timeline of
+ * updates. Pure given injected `rpc`/`clock` — no rendering here.
+ */
+declare function watchTransaction(signature: string, options: WatchTxOptions): Promise<WatchTxResult>;
+
+/** The set of known commands. */
+declare const COMMANDS: readonly ["doctor", "monitor", "watch-tx", "simulate", "help"];
+type Command = (typeof COMMANDS)[number];
+/**
+ * Resolves the command to run from parsed args. Pure + fully tested — this is the
+ * routing brain; the live `main()` (which does I/O) lives in `./ui/run`.
+ */
+declare function route(args: ParsedArgs): Command;
+
+/**
+ * rpc-bastion — the `bastion` diagnostics CLI: doctor, monitor, watch-tx, simulate.
+ *
+ * The data layer (endpoint probing, health aggregation, scenario simulation,
+ * config/arg parsing) is exported here for programmatic use and is fully
+ * unit-tested; the rendering + live-I/O layer lives under `src/ui/**` (excluded
+ * from coverage). The executable itself is `src/bin.ts` → `dist/bin.cjs`.
+ */
+/** Package semver, surfaced for diagnostics and the CLI `doctor` command. */
+declare const VERSION = "0.3.0";
+
+export { type BastionConfig, COMMANDS, type Command, type DoctorClock, type DoctorOptions, type DoctorReport, type DoctorRpc, type DoctorRpcFactory, type EndpointDiagnostic, type MonitorRow, type MonitorSummary, type ParsedArgs, SCENARIOS, type Scenario, type SimulationOptions, type SimulationSummary, type SimulationTick, type TickEvent, VERSION, type WatchTxOptions, type WatchTxResult, type WatchTxUpdate, describeProbeError, doctorReportToJson, flagBool, flagInt, flagString, listScenarios, median, parseArgs, parseConfig, probeEndpoint, pushSample, resolveEndpoints, route, runDoctor, runSimulation, statusDot, summarizeSimulation, summarizeSnapshot, watchTransaction };

package/dist/index.js

@@ -0,0 +1,10 @@
+export { SCENARIOS, describeProbeError, doctorReportToJson, listScenarios, median, parseConfig, probeEndpoint, pushSample, resolveEndpoints, runDoctor, runSimulation, statusDot, summarizeSimulation, summarizeSnapshot, watchTransaction } from './chunk-F5AAJEDR.js';
+export { flagBool, flagInt, flagString, parseArgs } from './chunk-Q2OA5HXD.js';
+export { COMMANDS, route } from './chunk-WU3Q4ZC6.js';
+
+// src/index.ts
+var VERSION = "0.3.0";
+
+export { VERSION };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAUO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["/**\n * rpc-bastion — the `bastion` diagnostics CLI: doctor, monitor, watch-tx, simulate.\n *\n * The data layer (endpoint probing, health aggregation, scenario simulation,\n * config/arg parsing) is exported here for programmatic use and is fully\n * unit-tested; the rendering + live-I/O layer lives under `src/ui/**` (excluded\n * from coverage). The executable itself is `src/bin.ts` → `dist/bin.cjs`.\n */\n\n/** Package semver, surfaced for diagnostics and the CLI `doctor` command. */\nexport const VERSION = '0.3.0';\n\n// Public data-layer API.\nexport * from './data/doctor';\nexport * from './data/config';\nexport * from './data/args';\nexport * from './data/monitor';\nexport * from './data/simulate';\nexport * from './data/watch-tx';\nexport { COMMANDS, route, type Command } from './cli';\n"]}