@albinocrabs/o-switcher 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2021 @@
+import { z } from 'zod';
+import pino from 'pino';
+import { EventEmitter } from 'eventemitter3';
+import { IBreaker, CircuitState } from 'cockatiel';
+import { ToolDefinition } from '@opencode-ai/plugin/tool';
+
+/**
+ * Zod 4 schemas for O-Switcher configuration.
+ *
+ * Defines validation schemas for the switcher configuration subtree
+ * within OpenCode's effective merged config (D-04, D-05, D-06).
+ * All optional fields have sensible defaults so minimal config works.
+ */
+
+/**
+ * Schema for exponential backoff configuration.
+ * All fields have defaults per D-10.
+ */
+declare const BackoffConfigSchema: z.ZodObject<{
+    base_ms: z.ZodDefault<z.ZodNumber>;
+    multiplier: z.ZodDefault<z.ZodNumber>;
+    max_ms: z.ZodDefault<z.ZodNumber>;
+    jitter: z.ZodDefault<z.ZodEnum<{
+        full: "full";
+        equal: "equal";
+        none: "none";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Schema for a single target definition.
+ * target_id and provider_id are required; all other fields have defaults.
+ * No credential fields -- provider_id is a pointer to OpenCode's auth store (D-13).
+ */
+declare const TargetConfigSchema: z.ZodObject<{
+    target_id: z.ZodString;
+    provider_id: z.ZodString;
+    profile: z.ZodOptional<z.ZodString>;
+    endpoint_id: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    operator_priority: z.ZodDefault<z.ZodNumber>;
+    policy_tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    retry_budget: z.ZodOptional<z.ZodNumber>;
+    failover_budget: z.ZodOptional<z.ZodNumber>;
+    backoff: z.ZodOptional<z.ZodObject<{
+        base_ms: z.ZodDefault<z.ZodNumber>;
+        multiplier: z.ZodDefault<z.ZodNumber>;
+        max_ms: z.ZodDefault<z.ZodNumber>;
+        jitter: z.ZodDefault<z.ZodEnum<{
+            full: "full";
+            equal: "equal";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    concurrency_limit: z.ZodOptional<z.ZodNumber>;
+    circuit_breaker: z.ZodOptional<z.ZodObject<{
+        failure_threshold: z.ZodDefault<z.ZodNumber>;
+        failure_rate_threshold: z.ZodDefault<z.ZodNumber>;
+        sliding_window_size: z.ZodDefault<z.ZodNumber>;
+        half_open_after_ms: z.ZodDefault<z.ZodNumber>;
+        half_open_max_probes: z.ZodDefault<z.ZodNumber>;
+        success_threshold: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Top-level schema for the O-Switcher configuration subtree.
+ * Targets are optional — when absent, auto-discovery populates them from OpenCode providers.
+ * When provided, at least one target is required (min 1).
+ * Shorthand fields `retry` and `timeout` map to retry_budget and max_expected_latency_ms.
+ */
+declare const SwitcherConfigSchema: z.ZodObject<{
+    targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        target_id: z.ZodString;
+        provider_id: z.ZodString;
+        profile: z.ZodOptional<z.ZodString>;
+        endpoint_id: z.ZodOptional<z.ZodString>;
+        capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        operator_priority: z.ZodDefault<z.ZodNumber>;
+        policy_tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        retry_budget: z.ZodOptional<z.ZodNumber>;
+        failover_budget: z.ZodOptional<z.ZodNumber>;
+        backoff: z.ZodOptional<z.ZodObject<{
+            base_ms: z.ZodDefault<z.ZodNumber>;
+            multiplier: z.ZodDefault<z.ZodNumber>;
+            max_ms: z.ZodDefault<z.ZodNumber>;
+            jitter: z.ZodDefault<z.ZodEnum<{
+                full: "full";
+                equal: "equal";
+                none: "none";
+            }>>;
+        }, z.core.$strip>>;
+        concurrency_limit: z.ZodOptional<z.ZodNumber>;
+        circuit_breaker: z.ZodOptional<z.ZodObject<{
+            failure_threshold: z.ZodDefault<z.ZodNumber>;
+            failure_rate_threshold: z.ZodDefault<z.ZodNumber>;
+            sliding_window_size: z.ZodDefault<z.ZodNumber>;
+            half_open_after_ms: z.ZodDefault<z.ZodNumber>;
+            half_open_max_probes: z.ZodDefault<z.ZodNumber>;
+            success_threshold: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    retry: z.ZodOptional<z.ZodNumber>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    retry_budget: z.ZodDefault<z.ZodNumber>;
+    failover_budget: z.ZodDefault<z.ZodNumber>;
+    backoff: z.ZodDefault<z.ZodObject<{
+        base_ms: z.ZodDefault<z.ZodNumber>;
+        multiplier: z.ZodDefault<z.ZodNumber>;
+        max_ms: z.ZodDefault<z.ZodNumber>;
+        jitter: z.ZodDefault<z.ZodEnum<{
+            full: "full";
+            equal: "equal";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    deployment_mode_hint: z.ZodDefault<z.ZodEnum<{
+        "plugin-only": "plugin-only";
+        "server-companion": "server-companion";
+        "sdk-control": "sdk-control";
+        auto: "auto";
+    }>>;
+    routing_weights: z.ZodDefault<z.ZodObject<{
+        health: z.ZodDefault<z.ZodNumber>;
+        latency: z.ZodDefault<z.ZodNumber>;
+        failure: z.ZodDefault<z.ZodNumber>;
+        priority: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    queue_limit: z.ZodDefault<z.ZodNumber>;
+    concurrency_limit: z.ZodDefault<z.ZodNumber>;
+    backpressure_threshold: z.ZodDefault<z.ZodNumber>;
+    circuit_breaker: z.ZodDefault<z.ZodObject<{
+        failure_threshold: z.ZodDefault<z.ZodNumber>;
+        failure_rate_threshold: z.ZodDefault<z.ZodNumber>;
+        sliding_window_size: z.ZodDefault<z.ZodNumber>;
+        half_open_after_ms: z.ZodDefault<z.ZodNumber>;
+        half_open_max_probes: z.ZodDefault<z.ZodNumber>;
+        success_threshold: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    max_expected_latency_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Inferred type for a validated backoff configuration. */
+type BackoffConfig = z.infer<typeof BackoffConfigSchema>;
+/** Inferred type for a validated target configuration. */
+type TargetConfig = z.infer<typeof TargetConfigSchema>;
+/** Inferred type for a validated switcher configuration. */
+type SwitcherConfig = z.infer<typeof SwitcherConfigSchema>;
+
+/**
+ * Configuration validation with field-path diagnostics.
+ *
+ * Validates raw configuration input against the SwitcherConfigSchema
+ * and returns a frozen, immutable config object on success.
+ * On failure, throws ConfigValidationError with structured diagnostics
+ * containing field paths, messages, and received values (D-05).
+ */
+
+/** A single diagnostic entry describing a validation failure. */
+interface ConfigDiagnostic {
+    readonly path: string;
+    readonly message: string;
+    readonly received: unknown;
+}
+/**
+ * Error thrown when configuration validation fails.
+ * Contains structured diagnostics with field paths and error messages.
+ */
+declare class ConfigValidationError extends Error {
+    readonly diagnostics: ReadonlyArray<ConfigDiagnostic>;
+    constructor(diagnostics: ReadonlyArray<ConfigDiagnostic>);
+}
+/**
+ * Validates raw input against the SwitcherConfigSchema.
+ *
+ * On success, returns a frozen (immutable) SwitcherConfig.
+ * On failure, throws ConfigValidationError with structured diagnostics.
+ */
+declare const validateConfig: (raw: unknown) => SwitcherConfig;
+
+/**
+ * Default configuration values for O-Switcher.
+ *
+ * These constants define sensible defaults for all optional configuration
+ * fields, ensuring minimal config works out of the box (D-10).
+ */
+/** Default maximum retry attempts per request. */
+declare const DEFAULT_RETRY_BUDGET = 3;
+/** Default maximum failover attempts per request. */
+declare const DEFAULT_FAILOVER_BUDGET = 2;
+/** Default base delay in milliseconds for exponential backoff. */
+declare const DEFAULT_BACKOFF_BASE_MS = 1000;
+/** Default multiplier for exponential backoff. */
+declare const DEFAULT_BACKOFF_MULTIPLIER = 2;
+/** Default maximum delay in milliseconds for exponential backoff. */
+declare const DEFAULT_BACKOFF_MAX_MS = 30000;
+/** Default jitter strategy for exponential backoff. */
+declare const DEFAULT_BACKOFF_JITTER: "full";
+/** Default retry shorthand value (maps to retry_budget). */
+declare const DEFAULT_RETRY = 3;
+/** Default timeout shorthand value in ms (maps to max_expected_latency_ms). */
+declare const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Profile storage types for O-Switcher.
+ *
+ * TODO (D-73): When OpenCode supports multiple credentials per provider
+ * natively, O-Switcher should read them directly. The watcher + copy mechanism
+ * becomes unnecessary.
+ */
+/** OAuth credential shape matching OpenCode auth.json OAuth entries. */
+interface OAuthCredential {
+    readonly type: 'oauth';
+    readonly refresh: string;
+    readonly access: string;
+    readonly expires: number;
+    readonly accountId?: string;
+}
+/** API key credential shape matching OpenCode auth.json API key entries. */
+interface ApiKeyCredential {
+    readonly type: 'api-key';
+    readonly key: string;
+}
+/** Union of all supported credential types. */
+type AuthCredential = OAuthCredential | ApiKeyCredential;
+/** A single stored profile entry. */
+interface ProfileEntry {
+    readonly id: string;
+    readonly provider: string;
+    readonly type: 'oauth' | 'api-key';
+    readonly credentials: AuthCredential;
+    readonly created: string;
+}
+/** Profile store keyed by profile ID (e.g., "openai-1"). */
+type ProfileStore = Record<string, ProfileEntry>;
+
+/**
+ * Auto-discovery of targets from OpenCode provider configuration.
+ *
+ * Pure functions: given a provider config map or a ProfileStore, produce arrays
+ * of TargetConfig objects with sensible defaults (D-55, D-56, D-71).
+ */
+
+/**
+ * Minimal interface for an OpenCode provider config entry.
+ * Only the fields needed for target discovery are required.
+ */
+interface ProviderConfigLike {
+    readonly id?: string;
+    readonly name?: string;
+    readonly options?: Record<string, unknown>;
+}
+/**
+ * Discovers targets from OpenCode provider configuration.
+ *
+ * For each provider entry in the map, creates a TargetConfig with:
+ * - target_id = the config key (e.g., "anthropic", "openai")
+ * - provider_id = provider.id if present, otherwise the config key
+ * - capabilities = ["chat"]
+ * - enabled = true
+ * - operator_priority = 0
+ * - policy_tags = []
+ *
+ * Skips falsy entries. Returns validated TargetConfig objects.
+ */
+declare const discoverTargets: (providerConfig: Record<string, ProviderConfigLike>) => TargetConfig[];
+/**
+ * Discovers targets from the O-Switcher profile store (D-71).
+ *
+ * For each profile entry in the store, creates a TargetConfig with:
+ * - target_id = profile.id (e.g., "openai-1")
+ * - provider_id = profile.provider (e.g., "openai")
+ * - profile = profile.id (links to profile for credential resolution)
+ * - capabilities = ["chat"]
+ * - enabled = true
+ * - operator_priority = 0
+ * - policy_tags = []
+ *
+ * Returns validated TargetConfig objects via TargetConfigSchema.parse().
+ */
+declare const discoverTargetsFromProfiles: (store: ProfileStore) => TargetConfig[];
+
+/**
+ * Target registry types.
+ *
+ * Defines the TargetEntry interface with all FOUN-02 fields,
+ * the TargetState enum, and RegistrySnapshot for read-only access.
+ *
+ * SECURITY: No credential fields (api_key, token, secret, password).
+ * provider_id is a pointer to OpenCode's auth store (D-13, SECU-01, SECU-02).
+ */
+/**
+ * All valid states for a target in the registry.
+ *
+ * - Active: healthy and available for routing
+ * - CoolingDown: temporarily unavailable after transient failure
+ * - ReauthRequired: authentication failure, awaiting credential refresh
+ * - PolicyBlocked: blocked by policy (403), no retry
+ * - CircuitOpen: circuit breaker tripped, no requests allowed
+ * - CircuitHalfOpen: circuit breaker probing with limited requests
+ * - Draining: operator-initiated drain, no new requests
+ * - Disabled: operator-disabled or config-disabled
+ */
+declare const TARGET_STATES: readonly ["Active", "CoolingDown", "ReauthRequired", "PolicyBlocked", "CircuitOpen", "CircuitHalfOpen", "Draining", "Disabled"];
+/** Target state type. */
+type TargetState = (typeof TARGET_STATES)[number];
+/**
+ * A single target entry in the registry.
+ *
+ * Contains all fields per FOUN-02: target_id, provider_id, endpoint_id,
+ * capabilities, enabled, state, health_score, cooldown_until, latency_ema_ms,
+ * failure_score, operator_priority, policy_tags.
+ *
+ * NO credential fields -- provider_id maps to OpenCode's credential store.
+ */
+interface TargetEntry {
+    readonly target_id: string;
+    readonly provider_id: string;
+    readonly profile: string | undefined;
+    readonly endpoint_id: string | undefined;
+    readonly capabilities: readonly string[];
+    readonly enabled: boolean;
+    readonly state: TargetState;
+    readonly health_score: number;
+    readonly cooldown_until: number | null;
+    readonly latency_ema_ms: number;
+    readonly failure_score: number;
+    readonly operator_priority: number;
+    readonly policy_tags: readonly string[];
+}
+/** Read-only snapshot of the entire registry. */
+interface RegistrySnapshot {
+    readonly targets: ReadonlyArray<Readonly<TargetEntry>>;
+}
+
+/**
+ * In-memory target registry.
+ *
+ * Initialized from validated SwitcherConfig. Single authoritative source
+ * of target state during runtime (D-09). All state mutations go through
+ * the registry.
+ *
+ * No credential material stored -- provider_id is a pointer only (D-13).
+ */
+
+/**
+ * Target registry managing per-target state.
+ *
+ * Provides methods for state mutation, health scoring, cooldown management,
+ * and read-only snapshot generation.
+ */
+declare class TargetRegistry {
+    private readonly targets;
+    constructor(config: SwitcherConfig);
+    /** Returns the target entry for the given id, or undefined if not found. */
+    getTarget(id: string): TargetEntry | undefined;
+    /** Returns a readonly array of all target entries. */
+    getAllTargets(): ReadonlyArray<Readonly<TargetEntry>>;
+    /**
+     * Updates the state of a target.
+     * @returns true if the target was found and updated, false otherwise.
+     */
+    updateState(id: string, newState: TargetState): boolean;
+    /**
+     * Records a success (1) or failure (0) observation for a target.
+     * Updates health_score via EMA.
+     */
+    recordObservation(id: string, observation: 0 | 1): void;
+    /** Sets the cooldown_until timestamp for a target. */
+    setCooldown(id: string, untilMs: number): void;
+    /** Updates the latency EMA for a target. */
+    updateLatency(id: string, ms: number): void;
+    /**
+     * Adds a new target entry to the registry.
+     * @returns true if added, false if target_id already exists.
+     */
+    addTarget(entry: TargetEntry): boolean;
+    /**
+     * Removes a target entry from the registry.
+     * @returns true if found and removed, false if not found.
+     */
+    removeTarget(id: string): boolean;
+    /** Returns a deep-frozen snapshot of all targets. */
+    getSnapshot(): RegistrySnapshot;
+}
+/** Factory function to create a registry from validated config. */
+declare const createRegistry: (config: SwitcherConfig) => TargetRegistry;
+
+/**
+ * Health score computation using Exponential Moving Average (EMA).
+ *
+ * Pure functions for updating health scores and latency EMAs.
+ * Health score ranges from 0.0 (completely unhealthy) to 1.0 (perfect health).
+ */
+/** Initial health score for newly registered targets. */
+declare const INITIAL_HEALTH_SCORE = 1;
+/** Default EMA smoothing factor (alpha). Higher = more reactive to recent observations. */
+declare const DEFAULT_ALPHA = 0.1;
+/**
+ * Updates health score using EMA formula.
+ *
+ * Formula: alpha * observation + (1 - alpha) * currentScore
+ *
+ * @param currentScore - Current health score (0.0 to 1.0)
+ * @param observation - 1 for success, 0 for failure
+ * @param alpha - EMA smoothing factor (default 0.1)
+ * @returns Updated health score
+ */
+declare const updateHealthScore: (currentScore: number, observation: 0 | 1, alpha?: number) => number;
+/**
+ * Updates latency EMA using the same EMA formula.
+ *
+ * @param currentEma - Current latency EMA in milliseconds
+ * @param observedMs - Observed latency in milliseconds
+ * @param alpha - EMA smoothing factor (default 0.1)
+ * @returns Updated latency EMA
+ */
+declare const updateLatencyEma: (currentEma: number, observedMs: number, alpha?: number) => number;
+
+/**
+ * Deployment mode types.
+ *
+ * Defines the three deployment modes, signal fidelity levels,
+ * and per-mode capability maps (FOUN-03, FOUN-04, D-16).
+ */
+/** The three supported deployment modes. */
+type DeploymentMode = 'plugin-only' | 'server-companion' | 'sdk-control';
+/**
+ * Signal fidelity indicates how error information is obtained.
+ *
+ * - 'direct': raw HTTP status codes and headers available
+ * - 'heuristic': classification from message patterns and events
+ */
+type SignalFidelity = 'direct' | 'heuristic';
+/** Capability map for a deployment mode. */
+interface ModeCapabilities {
+    readonly mode: DeploymentMode;
+    readonly signalFidelity: SignalFidelity;
+    readonly hasHttpStatus: boolean;
+    readonly hasRetryAfterHeader: boolean;
+    readonly hasOperatorApi: boolean;
+}
+
+/**
+ * Deployment mode detection.
+ *
+ * Determines the active deployment mode from a config hint.
+ * When hint is 'auto', defaults to 'plugin-only' (auto-detection
+ * logic will be refined in Phase 3 when mode adapters are built).
+ *
+ * Maps each mode to its signal fidelity and capability set (FOUN-03, FOUN-04).
+ */
+
+/**
+ * Detects the deployment mode from a configuration hint.
+ *
+ * If hint is not 'auto', returns the hint directly.
+ * If 'auto', defaults to 'plugin-only' (conservative default).
+ */
+declare const detectDeploymentMode: (hint: "plugin-only" | "server-companion" | "sdk-control" | "auto") => DeploymentMode;
+/**
+ * Returns the signal fidelity for a given deployment mode.
+ *
+ * - plugin-only: 'heuristic' (no raw HTTP status codes)
+ * - server-companion / sdk-control: 'direct' (full HTTP access)
+ */
+declare const getSignalFidelity: (mode: DeploymentMode) => SignalFidelity;
+/**
+ * Returns the full capability map for a deployment mode.
+ *
+ * plugin-only has no HTTP status, no Retry-After, no operator API.
+ * server-companion and sdk-control have all capabilities.
+ */
+declare const getModeCapabilities: (mode: DeploymentMode) => ModeCapabilities;
+
+/**
+ * Pino-based structured audit logger with credential redaction.
+ *
+ * Provides logger creation with automatic redaction of secret-pattern
+ * fields (SECU-04), child logger creation for per-request correlation IDs,
+ * and UUID v4 correlation ID generation.
+ */
+
+/**
+ * Pino redaction paths for secret-pattern fields.
+ *
+ * Includes both top-level paths (for direct log object fields)
+ * and wildcard paths (for nested objects) to ensure comprehensive
+ * credential redaction regardless of nesting depth.
+ */
+declare const REDACT_PATHS: readonly string[];
+/** Options for creating an audit logger. */
+interface AuditLoggerOptions {
+    readonly level?: string;
+    readonly destination?: pino.DestinationStream;
+}
+/**
+ * Creates a pino logger with secret redaction configured.
+ *
+ * All fields matching REDACT_PATHS patterns are replaced with '[Redacted]'
+ * in log output, preventing credential leakage (SECU-04).
+ */
+declare const createAuditLogger: (options?: AuditLoggerOptions) => pino.Logger;
+/**
+ * Creates a child logger with a request_id binding for correlation.
+ *
+ * All log entries from the child logger include the request_id field,
+ * enabling end-to-end request tracing in the audit trail.
+ */
+declare const createRequestLogger: (baseLogger: pino.Logger, requestId: string) => pino.Logger;
+/**
+ * Generates a UUID v4 correlation ID using Node.js crypto.
+ *
+ * @returns A UUID v4 string suitable for request correlation.
+ */
+declare const generateCorrelationId: () => string;
+
+/**
+ * Audit trail types.
+ *
+ * Defines the AuditEvent interface and CorrelationId type
+ * for structured logging with request correlation (SECU-04).
+ */
+/** Unique correlation identifier for request tracing. */
+type CorrelationId = string;
+/**
+ * Structured audit event for the O-Switcher audit trail.
+ *
+ * Every audit event includes a request_id for correlation,
+ * a timestamp, and an event_type discriminator.
+ * Additional fields are allowed via index signature.
+ */
+interface AuditEvent {
+    readonly request_id: string;
+    readonly timestamp: string;
+    readonly event_type: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Error taxonomy: 10 error classes as a Zod discriminated union.
+ *
+ * Defines NormalizedSignal (classifier input), ClassificationResult (classifier output),
+ * and helper functions for retry decisions and target state transitions.
+ *
+ * Per D-01, D-02, D-03, ERRC-01.
+ */
+
+/**
+ * Discriminated union of all 10 error classes.
+ * The 'class' field is the discriminator.
+ */
+declare const ErrorClassSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    class: z.ZodLiteral<"RateLimited">;
+    retryable: z.ZodLiteral<true>;
+    retry_after_ms: z.ZodOptional<z.ZodNumber>;
+    provider_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"QuotaExhausted">;
+    retryable: z.ZodLiteral<false>;
+    provider_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"AuthFailure">;
+    retryable: z.ZodLiteral<false>;
+    recovery_attempted: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"PermissionFailure">;
+    retryable: z.ZodLiteral<false>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"PolicyFailure">;
+    retryable: z.ZodLiteral<false>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"RegionRestriction">;
+    retryable: z.ZodLiteral<false>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"ModelUnavailable">;
+    retryable: z.ZodLiteral<false>;
+    failover_eligible: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"TransientServerFailure">;
+    retryable: z.ZodLiteral<true>;
+    http_status: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"TransportFailure">;
+    retryable: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+    class: z.ZodLiteral<"InterruptedExecution">;
+    retryable: z.ZodLiteral<true>;
+    partial_output_bytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "class">;
+/** Inferred type for any error class variant. */
+type ErrorClass = z.infer<typeof ErrorClassSchema>;
+/**
+ * Normalized signal: the common input format for the classifier.
+ *
+ * Direct adapters populate http_status and response_body.
+ * Heuristic adapters populate error_message and error_type.
+ * detection_mode is always set by the adapter (D-02).
+ */
+interface NormalizedSignal {
+    readonly http_status?: number;
+    readonly error_type?: string;
+    readonly error_message?: string;
+    readonly response_body?: unknown;
+    readonly detection_mode: 'direct' | 'heuristic';
+    readonly provider_id?: string;
+    readonly retry_after_ms?: number;
+}
+/**
+ * Classification result: the classifier output.
+ *
+ * Contains the error class, detection mode, confidence level,
+ * and the raw signal that produced it.
+ */
+interface ClassificationResult {
+    readonly error_class: ErrorClass;
+    readonly detection_mode: 'direct' | 'heuristic';
+    readonly confidence: 'high' | 'medium' | 'low';
+    readonly raw_signal: NormalizedSignal;
+}
+/**
+ * Checks whether an error class is retryable.
+ *
+ * @param errorClass - The classified error.
+ * @returns true if the error is retryable.
+ */
+declare const isRetryable: (errorClass: ErrorClass) => boolean;
+/**
+ * Maps an error class to the target state transition it triggers.
+ *
+ * Returns null when the error should not cause a target state change
+ * (e.g., transient failures that are handled by retry).
+ *
+ * @param errorClass - The classified error.
+ * @returns The new target state, or null if no transition.
+ */
+declare const getTargetStateTransition: (errorClass: ErrorClass) => TargetState | null;
+
+/**
+ * Mode-agnostic error classifier core.
+ *
+ * Accepts a NormalizedSignal and routes to direct (HTTP) or heuristic
+ * (message pattern) classification based on signal content.
+ *
+ * Per D-01, ERRC-01.
+ */
+
+/**
+ * Classifies a NormalizedSignal into an ErrorClass.
+ *
+ * Routes to direct (HTTP) or heuristic (message pattern) classification
+ * based on whether http_status is present in the signal.
+ *
+ * @param signal - The normalized error signal to classify.
+ * @returns ClassificationResult with error class, mode, confidence, and raw signal.
+ */
+declare const classify: (signal: NormalizedSignal) => ClassificationResult;
+
+/**
+ * Direct signal adapter: HTTP status + body to NormalizedSignal.
+ *
+ * Used in server-companion and SDK-control modes where raw HTTP
+ * status codes, response bodies, and headers are available.
+ *
+ * Per D-01, ERRC-02.
+ */
+
+/**
+ * Extracts Retry-After value from response headers as milliseconds.
+ *
+ * Supports integer seconds format. HTTP-date format is not supported
+ * (providers typically send integer seconds).
+ *
+ * @param headers - Response headers (case-insensitive lookup for retry-after).
+ * @returns Retry-After in milliseconds, or undefined if not present/parseable.
+ */
+declare const extractRetryAfterMs: (headers?: Record<string, string>) => number | undefined;
+/**
+ * Creates a NormalizedSignal from an HTTP response.
+ *
+ * Always sets detection_mode='direct' since we have raw HTTP access.
+ *
+ * @param status - HTTP status code.
+ * @param body - Parsed response body.
+ * @param headers - Response headers (optional; used for Retry-After).
+ * @returns NormalizedSignal ready for classifier.
+ */
+declare const directSignalFromResponse: (status: number, body: unknown, headers?: Record<string, string>) => NormalizedSignal;
+
+/**
+ * Heuristic signal adapter: message pattern to NormalizedSignal.
+ *
+ * Used in plugin-only mode where HTTP status codes are not available.
+ * Classification relies on message string matching against known patterns.
+ *
+ * Per D-01, ERRC-03.
+ */
+
+/**
+ * Creates a NormalizedSignal from a session event message.
+ *
+ * Always sets detection_mode='heuristic' since no HTTP access is available.
+ * No http_status field is set (not available in plugin-only mode).
+ *
+ * @param eventType - The event type (e.g., 'error', 'retry', 'status').
+ * @param message - The error or status message string.
+ * @param providerId - Optional provider identifier.
+ * @returns NormalizedSignal ready for classifier.
+ */
+declare const heuristicSignalFromEvent: (eventType: string, message: string, providerId?: string) => NormalizedSignal;
+
+/**
+ * Provider-specific error pattern corpus.
+ *
+ * Contains known error response patterns for Anthropic, OpenAI, Google,
+ * and AWS Bedrock (direct classification) and heuristic message patterns
+ * for plugin-only mode classification.
+ *
+ * Per ERRC-02, ERRC-05, Pitfalls 1-3.
+ */
+/** A provider-specific error response pattern for direct classification. */
+interface ProviderErrorPattern {
+    readonly provider: string;
+    readonly http_status: number;
+    readonly error_type_field: string;
+    readonly error_type_value: string;
+    readonly error_class: string;
+    readonly notes?: string;
+}
+/**
+ * Known provider error patterns for direct HTTP status classification.
+ *
+ * Order matters for matching: more specific patterns (with error_type_value)
+ * should be checked before generic status-code fallbacks.
+ */
+declare const PROVIDER_PATTERNS: ReadonlyArray<ProviderErrorPattern>;
+/** A heuristic pattern for plugin-only mode message classification. */
+interface HeuristicPattern {
+    readonly pattern: RegExp;
+    readonly error_class: string;
+    readonly confidence: 'high' | 'medium' | 'low';
+    readonly provider?: string;
+    readonly notes?: string;
+}
+/**
+ * Heuristic patterns for plugin-only mode classification.
+ *
+ * Order matters: more specific patterns should come first.
+ * TEMPORAL_QUOTA_PATTERN is checked separately before these patterns
+ * to correctly handle Pitfall 2.
+ */
+declare const HEURISTIC_PATTERNS: ReadonlyArray<HeuristicPattern>;
+/**
+ * Temporal quota pattern to distinguish quota exhaustion from transient rate limits.
+ *
+ * Matches messages like "Too many tokens per day" from Bedrock, which arrive as
+ * ThrottlingException but represent non-retryable quota exhaustion (Pitfall 2).
+ */
+declare const TEMPORAL_QUOTA_PATTERN: RegExp;
+
+/**
+ * Exponential backoff with jitter and Retry-After floor.
+ *
+ * Pure function that computes the delay before the next retry attempt.
+ * Supports full jitter, equal jitter, and no jitter modes.
+ *
+ * Per D-10, D-11, Pitfall 4.
+ */
+/** Configuration for backoff computation. */
+interface BackoffParams {
+    readonly base_ms: number;
+    readonly multiplier: number;
+    readonly max_ms: number;
+    readonly jitter: 'full' | 'equal' | 'none';
+}
+/** Default backoff parameters per D-10. */
+declare const DEFAULT_BACKOFF_PARAMS: BackoffParams;
+/**
+ * Computes the backoff delay in milliseconds for a given retry attempt.
+ *
+ * Formula: rawDelay = min(base_ms * multiplier^attempt, max_ms)
+ *
+ * Jitter modes:
+ * - 'full': Math.random() * rawDelay (uniform [0, rawDelay])
+ * - 'equal': rawDelay/2 + Math.random() * rawDelay/2 (uniform [rawDelay/2, rawDelay])
+ * - 'none': rawDelay (deterministic)
+ *
+ * The Retry-After value (if provided) is used as a floor: the result
+ * is at least retryAfterMs, preventing retry storms (Pitfall 4 fix).
+ *
+ * @param attempt - Zero-based retry attempt number.
+ * @param params - Backoff configuration parameters.
+ * @param retryAfterMs - Optional Retry-After value in ms to use as floor.
+ * @returns Delay in milliseconds before next retry.
+ */
+declare const computeBackoffMs: (attempt: number, params: BackoffParams, retryAfterMs?: number) => number;
+
+/**
+ * Bounded retry policy with budget tracking.
+ *
+ * Decides whether to retry, abort, or declare exhaustion based on
+ * the error classification and remaining budget.
+ *
+ * Per D-10, D-12, ERRC-06, ERRC-07, ERRC-08.
+ */
+
+/**
+ * A retry decision: retry with delay, abort immediately, or budget exhausted.
+ */
+type RetryDecision = {
+    readonly action: 'retry';
+    readonly delay_ms: number;
+    readonly attempt: number;
+} | {
+    readonly action: 'abort';
+    readonly reason: string;
+    readonly target_state: TargetState | null;
+} | {
+    readonly action: 'exhausted';
+    readonly attempts_used: number;
+};
+/**
+ * A retry policy with budget and backoff configuration.
+ */
+interface RetryPolicy {
+    readonly budget: number;
+    readonly backoffParams: BackoffParams;
+    readonly decide: (classification: ClassificationResult, attemptsSoFar: number) => RetryDecision;
+}
+/**
+ * Creates a bounded retry policy.
+ *
+ * Decision logic:
+ * 1. Non-retryable errors (AuthFailure, PermissionFailure, QuotaExhausted,
+ *    PolicyFailure, RegionRestriction, ModelUnavailable) -> abort immediately
+ *    with target state transition (D-12)
+ * 2. Budget exhausted -> return 'exhausted' with attempt count
+ * 3. Retryable errors -> compute backoff with Retry-After floor and return 'retry'
+ *
+ * AuthFailure special handling (ERRC-06): if recovery_attempted is true,
+ * abort with ReauthRequired state. The caller is responsible for setting
+ * recovery_attempted on the first recovery attempt.
+ *
+ * @param budget - Maximum number of retry attempts.
+ * @param backoffParams - Backoff configuration (defaults to full jitter).
+ * @returns A RetryPolicy instance.
+ */
+declare const createRetryPolicy: (budget: number, backoffParams?: BackoffParams) => RetryPolicy;
+
+/**
+ * Routing domain types for Phase 2.
+ *
+ * Defines ExclusionReason, AdmissionResult, SelectionRecord, RoutingWeights,
+ * CircuitBreakerConfig, CircuitBreaker, and ConcurrencyTrackerApi types.
+ *
+ * Per D-17, D-20, D-22, D-24, D-26.
+ */
+
+/** 7 exclusion reasons per ROUT-03, D-17. */
+declare const EXCLUSION_REASONS: readonly ["disabled", "policy_blocked", "reauth_required", "cooldown_active", "circuit_open", "capability_mismatch", "draining"];
+/** Why a target was excluded from routing. */
+type ExclusionReason = (typeof EXCLUSION_REASONS)[number];
+/** 4 admission outcomes per ADMC-02, D-20. */
+declare const ADMISSION_RESULTS: readonly ["admitted", "queued", "degraded", "rejected"];
+/** Admission control decision outcome. */
+type AdmissionResult = (typeof ADMISSION_RESULTS)[number];
+/** Admission decision with reason string. */
+interface AdmissionDecision {
+    readonly result: AdmissionResult;
+    readonly reason: string;
+}
+/** Scoring weights for target selection per D-17. */
+interface RoutingWeights {
+    readonly health: number;
+    readonly latency: number;
+    readonly failure: number;
+    readonly priority: number;
+}
+/** Circuit breaker configuration per D-22. */
+interface CircuitBreakerConfig {
+    readonly failure_threshold: number;
+    readonly failure_rate_threshold: number;
+    readonly sliding_window_size: number;
+    readonly half_open_after_ms: number;
+    readonly half_open_max_probes: number;
+    readonly success_threshold: number;
+}
+/** Full audit record for a target selection per D-26. */
+interface SelectionRecord {
+    readonly request_id: string;
+    readonly timestamp_ms: number;
+    readonly candidates: ReadonlyArray<{
+        readonly target_id: string;
+        readonly score: number;
+        readonly health_score: number;
+        readonly latency_ema_ms: number;
+    }>;
+    readonly excluded: ReadonlyArray<{
+        readonly target_id: string;
+        readonly reason: ExclusionReason;
+    }>;
+    readonly selected: {
+        readonly target_id: string;
+        readonly score: number;
+        readonly rank: number;
+    } | null;
+}
+/**
+ * Circuit breaker interface per D-18.
+ * recordSuccess/recordFailure are async because they use cockatiel's
+ * execute() internally to properly manage state transitions.
+ */
+interface CircuitBreaker {
+    state(): TargetState;
+    recordSuccess(): Promise<void>;
+    recordFailure(): Promise<void>;
+    allowRequest(): boolean;
+    reset(): void;
+}
+/** Concurrency tracker interface per D-24. */
+interface ConcurrencyTrackerApi {
+    acquire(target_id: string): boolean;
+    release(target_id: string): void;
+    headroom(target_id: string): number;
+    active(target_id: string): number;
+}
+
+/**
+ * Typed event bus for routing events per D-25.
+ *
+ * Uses eventemitter3 with a typed event map for type-safe emit/on.
+ * 6 event types: circuit_state_change, target_excluded, health_updated,
+ * admission_decision, cooldown_set, cooldown_expired.
+ */
+
+/** Typed event map for all routing events. */
+interface RoutingEventMap {
+    circuit_state_change: (payload: {
+        target_id: string;
+        from: TargetState;
+        to: TargetState;
+        reason: string;
+    }) => void;
+    target_excluded: (payload: {
+        target_id: string;
+        reason: ExclusionReason;
+    }) => void;
+    health_updated: (payload: {
+        target_id: string;
+        old_score: number;
+        new_score: number;
+    }) => void;
+    admission_decision: (payload: {
+        request_id: string;
+        result: AdmissionResult;
+        reason: string;
+    }) => void;
+    cooldown_set: (payload: {
+        target_id: string;
+        until_ms: number;
+        error_class: string;
+    }) => void;
+    cooldown_expired: (payload: {
+        target_id: string;
+    }) => void;
+}
+/** Creates a typed event bus for routing events. */
+declare const createRoutingEventBus: () => EventEmitter<RoutingEventMap>;
+
+/**
+ * DualBreaker: composite IBreaker for cockatiel circuit breaker.
+ *
+ * Composes ConsecutiveBreaker (N consecutive failures) with
+ * CountBreaker (failure rate in sliding window). The circuit opens
+ * if EITHER trigger fires (OR logic per D-22 dual trigger).
+ *
+ * Uses CountBreaker (not SamplingBreaker) because D-22's sliding_window
+ * refers to request count, not time duration (Pitfall 2 from research).
+ */
+
+/** Composite breaker that trips on consecutive failures OR failure rate. */
+declare class DualBreaker implements IBreaker {
+    private readonly consecutive;
+    private readonly count;
+    constructor(consecutiveThreshold: number, countOpts: {
+        threshold: number;
+        size: number;
+        minimumNumberOfCalls?: number;
+    });
+    /** Serializable state for both internal breakers. */
+    get state(): unknown;
+    /** Restore state for both internal breakers. */
+    set state(value: unknown);
+    /**
+     * Record success on both breakers.
+     * ConsecutiveBreaker.success() takes no args (resets counter).
+     * CountBreaker.success() takes CircuitState.
+     */
+    success(state: CircuitState): void;
+    /**
+     * Record failure on both breakers.
+     * Returns true if EITHER breaker trips (OR logic).
+     * ConsecutiveBreaker.failure() takes no args.
+     * CountBreaker.failure() takes CircuitState.
+     */
+    failure(state: CircuitState): boolean;
+}
+
+/**
+ * CircuitBreaker wrapper around cockatiel's CircuitBreakerPolicy.
+ *
+ * Wraps cockatiel internals behind the CircuitBreaker interface from types.ts.
+ * Maps cockatiel CircuitState to TargetState. Emits circuit_state_change events
+ * via the routing event bus.
+ *
+ * Per D-18: cockatiel in wrapper pattern. We do NOT use execute() for routing;
+ * instead we use recordSuccess/recordFailure to update the breaker state after
+ * external request completion. Internally, we call policy.execute() with
+ * success/failure functions to let cockatiel manage state transitions correctly.
+ *
+ * Note: cockatiel closes from HalfOpen after 1 success (native behavior).
+ * This is accepted per research recommendation. D-22's success_threshold:2
+ * is documented but not enforced at this layer.
+ */
+
+/**
+ * Create a circuit breaker for a specific target.
+ *
+ * @param targetId - Target identifier for event attribution.
+ * @param config - Circuit breaker configuration.
+ * @param eventBus - Optional event bus for state change notifications.
+ * @returns CircuitBreaker interface implementation.
+ */
+declare const createCircuitBreaker: (targetId: string, config: CircuitBreakerConfig, eventBus?: EventEmitter<RoutingEventMap>) => CircuitBreaker;
+
+/**
+ * Per-target concurrency tracking per D-24.
+ *
+ * Tracks in-flight request counts per target with acquire/release semantics.
+ * Each target has an independent slot counter with a configurable limit.
+ */
+
+/**
+ * Create a concurrency tracker with a default per-target limit.
+ *
+ * @param defaultLimit - Default concurrency limit for targets.
+ * @returns ConcurrencyTrackerApi with additional setLimit method for per-target overrides.
+ */
+declare const createConcurrencyTracker: (defaultLimit: number) => ConcurrencyTrackerApi & {
+    setLimit(target_id: string, limit: number): void;
+};
+
+/**
+ * Policy engine: filter-then-score target selection per D-17.
+ *
+ * Pure functions that select the best target from a registry snapshot.
+ * No I/O, no external state dependencies -- deterministic for identical inputs.
+ *
+ * Score formula (D-17):
+ *   score = w_health * health_score
+ *         - w_latency * normalizeLatency(latency_ema_ms, maxLatencyMs)
+ *         - w_failure * failure_score
+ *         + w_priority * operator_priority
+ *
+ * Tie-breaking: target_id lexicographic ascending for full determinism (Pitfall 5).
+ *
+ * Exclusion order:
+ *   1. !enabled -> 'disabled'
+ *   2. PolicyBlocked -> 'policy_blocked'
+ *   3. ReauthRequired -> 'reauth_required'
+ *   4. Draining -> 'draining'
+ *   5. Disabled state -> 'disabled'
+ *   6. Circuit breaker denies -> 'circuit_open'
+ *   7. Cooldown active -> 'cooldown_active'
+ *   8. Capability mismatch -> 'capability_mismatch'
+ *
+ * Targets in `excludeTargets` are silently filtered (failover loop, D-19).
+ */
+
+/**
+ * Normalizes latency to [0, 1] range using max expected latency.
+ * Clamps to 1.0 when latency exceeds maxExpectedMs.
+ *
+ * @param latencyEmaMs - Exponential moving average latency in ms.
+ * @param maxExpectedMs - Maximum expected latency for normalization.
+ * @returns Normalized latency in [0, 1].
+ */
+declare const normalizeLatency: (latencyEmaMs: number, maxExpectedMs: number) => number;
+/**
+ * Computes the routing score for a target using D-17 weighted formula.
+ *
+ * Higher score = better target.
+ *
+ * @param target - The target entry to score.
+ * @param weights - Scoring weights configuration.
+ * @param maxLatencyMs - Maximum expected latency for normalization.
+ * @returns Numeric score for ranking.
+ */
+declare const computeScore: (target: TargetEntry, weights: RoutingWeights, maxLatencyMs: number) => number;
+/**
+ * Checks a single target against all exclusion criteria.
+ *
+ * Returns the first matching ExclusionReason, or null if eligible.
+ * Check order matters -- earlier checks take priority.
+ *
+ * @param target - Target to evaluate.
+ * @param circuitBreakers - Circuit breaker map by target_id.
+ * @param requiredCapabilities - Capabilities the request needs.
+ * @param excludeTargets - Set of target_ids to silently skip (failover).
+ * @param nowMs - Current timestamp for cooldown evaluation.
+ * @returns ExclusionReason or null if eligible.
+ */
+declare const getExclusionReason: (target: TargetEntry, circuitBreakers: ReadonlyMap<string, CircuitBreaker>, requiredCapabilities: readonly string[], excludeTargets: ReadonlySet<string>, nowMs: number) => ExclusionReason | null;
+/**
+ * Selects the best target from a registry snapshot using filter-then-score.
+ *
+ * 1. Filter: exclude ineligible targets, recording reasons.
+ * 2. Silently filter targets in excludeTargets (failover re-selection prevention).
+ * 3. Score: compute weighted score for each eligible target.
+ * 4. Sort: by score DESC, then target_id ASC for determinism.
+ * 5. Return full SelectionRecord per D-26.
+ *
+ * @param snapshot - Registry snapshot with all targets.
+ * @param circuitBreakers - Circuit breaker map by target_id.
+ * @param requiredCapabilities - Capabilities the request requires.
+ * @param weights - Scoring weights for ranking.
+ * @param maxLatencyMs - Max expected latency for normalization.
+ * @param nowMs - Current timestamp for cooldown checks.
+ * @param request_id - Request identifier for audit trail.
+ * @param excludeTargets - Optional set of target_ids to silently skip.
+ * @param logger - Optional pino logger for selection audit logging.
+ * @returns SelectionRecord with full audit information.
+ */
+declare const selectTarget: (snapshot: RegistrySnapshot, circuitBreakers: ReadonlyMap<string, CircuitBreaker>, requiredCapabilities: readonly string[], weights: RoutingWeights, maxLatencyMs: number, nowMs: number, request_id: string, excludeTargets?: ReadonlySet<string>, logger?: pino.Logger) => SelectionRecord;
+
+/**
+ * Adaptive cooldown manager per D-23.
+ *
+ * computeCooldownMs: Pure function that calculates cooldown duration
+ * based on error class, consecutive failures, and backoff configuration.
+ * - RateLimited with retry_after_ms: uses retry_after as base
+ * - RateLimited without retry_after_ms: exponential backoff
+ * - TransientServerFailure: half the backoff duration
+ * - Other error classes: fixed 5000ms base
+ * - All results include jitter (10-25%) to prevent thundering herd (Pitfall 7)
+ * - All results clamped to maxMs
+ *
+ * CooldownManager: Coordinates cooldown state with TargetRegistry
+ * and event bus. Uses passive checking (no setTimeout, Pitfall 6).
+ */
+
+/**
+ * Computes the cooldown duration in milliseconds for a target.
+ *
+ * The duration adapts to the error class:
+ * - RateLimited + retry_after_ms: uses server-provided value as base
+ * - RateLimited (no retry_after): exponential backoff from consecutiveFailures
+ * - TransientServerFailure: half the exponential backoff
+ * - All others: fixed 5000ms base
+ *
+ * Jitter of 10-25% is added to prevent thundering herd.
+ * Result is clamped to maxMs.
+ *
+ * @param errorClass - The classified error that triggered cooldown.
+ * @param consecutiveFailures - Number of consecutive failures for this target.
+ * @param backoffParams - Backoff configuration parameters.
+ * @param maxMs - Maximum cooldown duration in ms.
+ * @returns Cooldown duration in ms with jitter applied.
+ */
+declare const computeCooldownMs: (errorClass: ErrorClass, consecutiveFailures: number, backoffParams: BackoffParams, maxMs: number) => number;
+/** CooldownManager interface for coordinating cooldown state. */
+interface CooldownManager {
+    /** Sets a target into cooldown for the given duration. */
+    setCooldown(target_id: string, durationMs: number, errorClass: string): void;
+    /** Checks all targets for expired cooldowns and transitions them to Active. */
+    checkExpired(nowMs: number): readonly string[];
+    /** Checks whether a specific target is currently in cooldown. */
+    isInCooldown(target_id: string, nowMs: number): boolean;
+}
+/**
+ * Creates a CooldownManager that coordinates with TargetRegistry and event bus.
+ *
+ * Uses passive checking (no setTimeout) per Pitfall 6.
+ * checkExpired should be called periodically or before routing decisions.
+ *
+ * @param registry - Target registry for state mutations.
+ * @param eventBus - Optional event bus for cooldown events.
+ * @returns CooldownManager instance.
+ */
+declare const createCooldownManager: (registry: TargetRegistry, eventBus?: EventEmitter<RoutingEventMap>) => CooldownManager;
+
+/**
+ * Layered admission controller per D-20.
+ *
+ * Three-layer design:
+ * 1. checkHardRejects: Pure function checking 4 preconditions (reject fast path)
+ * 2. Backpressure detection: queue.pending > threshold -> degraded
+ * 3. Concurrency gating via p-queue: bounded concurrency and queue capacity
+ *
+ * Uses queue.size for backpressure (queue depth = items waiting, not running).
+ * Note: p-queue semantics differ from plan assumption -- pending = running, size = waiting.
+ */
+
+/**
+ * Context for hard reject checks.
+ * All fields are readonly -- pure input for the pure checkHardRejects function.
+ */
+interface AdmissionContext {
+    readonly hasEligibleTargets: boolean;
+    readonly operatorPaused: boolean;
+    readonly retryBudgetRemaining: number;
+    readonly failoverBudgetRemaining: number;
+}
+/**
+ * Configuration for the admission controller.
+ */
+interface AdmissionConfig {
+    readonly concurrencyLimit: number;
+    readonly queueLimit: number;
+    readonly backpressureThreshold: number;
+}
+/**
+ * Admission controller interface.
+ *
+ * admit() checks admission without executing.
+ * execute() checks admission and runs the function through p-queue if admitted.
+ */
+interface AdmissionController {
+    admit(request_id: string, ctx: AdmissionContext): Promise<AdmissionDecision>;
+    execute<T>(fn: () => Promise<T>, request_id: string, ctx: AdmissionContext): Promise<{
+        decision: AdmissionDecision;
+        result?: T;
+    }>;
+    readonly pending: number;
+    readonly size: number;
+}
+/**
+ * Layer 1: Pure hard reject checks.
+ *
+ * Returns an AdmissionDecision with result 'rejected' if any precondition
+ * fails, or null if all checks pass (no hard reject).
+ *
+ * Check order:
+ * 1. No eligible targets
+ * 2. Operator pause active
+ * 3. Retry budget exhausted
+ * 4. Failover budget exhausted
+ *
+ * @param ctx - Admission context with current system state.
+ * @returns Rejection decision or null if no hard reject applies.
+ */
+declare const checkHardRejects: (ctx: AdmissionContext) => AdmissionDecision | null;
+/**
+ * Creates a layered admission controller with p-queue integration.
+ *
+ * Layer 1: checkHardRejects (pure, fast path)
+ * Layer 2: Backpressure detection (queue.pending vs threshold)
+ * Layer 3: Queue capacity check and p-queue concurrency gating
+ *
+ * @param config - Admission controller configuration.
+ * @param eventBus - Optional event bus for admission_decision events.
+ * @returns AdmissionController instance.
+ */
+declare const createAdmissionController: (config: AdmissionConfig, eventBus?: EventEmitter<RoutingEventMap>) => AdmissionController;
+
+/**
+ * Event bus log subscriber for routing events.
+ *
+ * Subscribes to all RoutingEventMap events and logs them via pino.
+ * Per D-74: child logger with component context.
+ * Per D-75: info for decisions, warn for degraded, debug for scoring.
+ * Per D-79: circuit breaker transitions at info.
+ * Per D-80: cooldown set/expired at info.
+ * Per D-81: admission at info (admitted) or warn (rejected/degraded).
+ */
+
+/**
+ * Creates a log subscriber for routing events.
+ *
+ * Subscribes to all 6 event types on the provided event bus and logs
+ * each at the appropriate level using a child logger with component context.
+ *
+ * @param eventBus - Typed routing event bus.
+ * @param logger - Base pino logger (child with component:'routing' is created).
+ * @returns A dispose function that removes all listeners.
+ */
+declare const createLogSubscriber: (eventBus: EventEmitter<RoutingEventMap>, logger: pino.Logger) => (() => void);
+
+/**
+ * Nested retry-failover orchestrator per D-19.
+ *
+ * Implements the two-loop structure:
+ * - Outer loop: failover across targets (bounded by failoverBudget)
+ * - Inner loop: retry on same target (bounded by retryBudget)
+ *
+ * Decision tree per attempt:
+ * 1. Success -> return immediately, record success
+ * 2. ModelUnavailable -> early failover (break inner, try next target)
+ * 3. Non-retryable (Auth, Permission, Quota, Policy, Region) -> abort entirely
+ * 4. Retryable + budget remaining -> retry with backoff
+ * 5. Retryable + budget exhausted -> failover to next target
+ *
+ * Composes: selectTarget (policy engine), createRetryPolicy (retry),
+ * circuit breakers, cooldown manager, concurrency tracker.
+ */
+
+/**
+ * Minimal registry interface used by the failover orchestrator.
+ * Decoupled from concrete TargetRegistry class for testability.
+ */
+interface FailoverRegistry {
+    getSnapshot(): RegistrySnapshot;
+    recordObservation(id: string, observation: 0 | 1): void;
+    updateLatency(id: string, ms: number): void;
+    updateState(id: string, newState: TargetState): boolean;
+    setCooldown(id: string, untilMs: number): void;
+}
+
+/**
+ * Record of a single attempt within the failover loop.
+ */
+interface FailoverAttempt {
+    readonly target_id: string;
+    /** 1-based attempt number within this target. */
+    readonly attempt_no: number;
+    /** 0-based failover iteration. */
+    readonly failover_no: number;
+    readonly outcome: 'success' | 'retry' | 'failover' | 'abort';
+    readonly error_class?: string;
+    readonly latency_ms: number;
+    readonly selection: SelectionRecord;
+}
+/**
+ * Result of the failover orchestrator: success with value or failure with reason.
+ */
+type FailoverResult = {
+    readonly outcome: 'success';
+    readonly target_id: string;
+    readonly attempts: readonly FailoverAttempt[];
+    readonly total_retries: number;
+    readonly total_failovers: number;
+    readonly value: unknown;
+} | {
+    readonly outcome: 'failure';
+    readonly reason: string;
+    readonly attempts: readonly FailoverAttempt[];
+    readonly total_retries: number;
+    readonly total_failovers: number;
+    readonly last_error_class?: string;
+};
+/**
+ * Function type for executing a request attempt against a target.
+ * Provided by the caller (Phase 3 execution layer).
+ */
+type AttemptFn = (target_id: string) => Promise<{
+    success: boolean;
+    value?: unknown;
+    error_class?: ErrorClass;
+    latency_ms: number;
+}>;
+/**
+ * Dependencies for the failover orchestrator.
+ */
+interface FailoverDeps {
+    readonly registry: FailoverRegistry;
+    readonly circuitBreakers: ReadonlyMap<string, CircuitBreaker>;
+    readonly concurrency: ConcurrencyTrackerApi;
+    readonly cooldownManager: CooldownManager;
+    readonly eventBus?: EventEmitter<RoutingEventMap>;
+    readonly weights: RoutingWeights;
+    readonly maxLatencyMs: number;
+    readonly retryBudget: number;
+    readonly failoverBudget: number;
+    readonly backoffParams: BackoffParams;
+    /** Optional pino logger for structured failover logging (Phase 8). */
+    readonly logger?: pino.Logger;
+}
+/**
+ * Failover orchestrator interface.
+ */
+interface FailoverOrchestrator {
+    execute(request_id: string, attemptFn: AttemptFn, requiredCapabilities: readonly string[]): Promise<FailoverResult>;
+}
+/**
+ * Creates a nested retry-failover orchestrator.
+ *
+ * The outer loop iterates up to failoverBudget + 1 targets.
+ * The inner loop iterates up to retryBudget + 1 attempts per target.
+ * Maximum theoretical attempts = (failoverBudget + 1) * (retryBudget + 1).
+ *
+ * @param deps - Orchestrator dependencies.
+ * @returns FailoverOrchestrator instance.
+ */
+declare const createFailoverOrchestrator: (deps: FailoverDeps) => FailoverOrchestrator;
+
+/**
+ * Execution layer types for Phase 3.
+ *
+ * Defines StreamChunk, AdapterRequest, AdapterResult, ModeAdapter,
+ * ContinuationMode, SegmentProvenance, StitchedOutput,
+ * ExecutionProvenance, and ExecutionResult.
+ *
+ * Per D-27 through D-38.
+ */
+
+/**
+ * A single chunk of streamed output with position and timing.
+ */
+interface StreamChunk {
+    readonly text: string;
+    readonly index: number;
+    readonly timestamp_ms: number;
+}
+/**
+ * Request payload for a mode adapter execution.
+ */
+interface AdapterRequest {
+    readonly request_id: string;
+    readonly prompt: string;
+    readonly params?: Record<string, unknown>;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Result from a mode adapter execution attempt.
+ *
+ * detection_mode indicates whether error classification used
+ * raw HTTP signals ('direct') or message pattern matching ('heuristic').
+ */
+interface AdapterResult {
+    readonly success: boolean;
+    readonly chunks: readonly StreamChunk[];
+    readonly error_class?: ErrorClass;
+    readonly latency_ms: number;
+    readonly http_status?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly detection_mode: 'direct' | 'heuristic';
+}
+/**
+ * Mode adapter interface per D-27.
+ *
+ * Each deployment mode (plugin-only, server-companion, sdk-control)
+ * provides an adapter that executes requests against a target.
+ */
+interface ModeAdapter {
+    execute(target_id: string, request: AdapterRequest): Promise<AdapterResult>;
+}
+/**
+ * Continuation mode per D-31.
+ *
+ * Describes how a resumed segment relates to the interrupted one:
+ * - same_target_resume: retry on the same target
+ * - same_model_alternate_target: same model, different provider target
+ * - cross_model_semantic: different model entirely (non-deterministic)
+ * - controlled_reexecution: full re-execution when no viable continuation exists
+ */
+type ContinuationMode = 'same_target_resume' | 'same_model_alternate_target' | 'cross_model_semantic' | 'controlled_reexecution';
+/**
+ * Provenance metadata for a single segment of stitched output per D-32, D-33.
+ *
+ * non_deterministic is true when continuation crosses model boundaries,
+ * meaning the output may not be semantically consistent with the prior segment.
+ */
+interface SegmentProvenance {
+    readonly request_id: string;
+    readonly segment_id: number;
+    readonly source_target_id: string;
+    readonly continuation_mode: ContinuationMode;
+    readonly failover_reason?: string;
+    readonly visible_offset: number;
+    readonly non_deterministic: boolean;
+}
+/**
+ * Assembled multi-segment output with provenance per STRM-05, D-33.
+ *
+ * continuation_boundaries marks character positions where segments join.
+ */
+interface StitchedOutput {
+    readonly text: string;
+    readonly segments: readonly SegmentProvenance[];
+    readonly continuation_boundaries: readonly number[];
+}
+/**
+ * Full execution provenance per D-37, D-38.
+ *
+ * Tracks all segments, continuation modes, involved targets,
+ * and whether the output is degraded.
+ */
+interface ExecutionProvenance {
+    readonly request_id: string;
+    readonly segments: readonly SegmentProvenance[];
+    readonly continuation_modes: readonly ContinuationMode[];
+    readonly targets_involved: readonly string[];
+    readonly total_attempts: number;
+    readonly degraded: boolean;
+    readonly degraded_reason?: string;
+    readonly heuristic_detection: boolean;
+}
+/**
+ * Final execution result combining output text with provenance.
+ */
+interface ExecutionResult {
+    readonly success: boolean;
+    readonly output: string;
+    readonly provenance: ExecutionProvenance;
+}
+/**
+ * StreamBuffer interface for accumulating stream chunks.
+ *
+ * Append-only buffer that provides confirmed text snapshot
+ * on interruption for stream resume/stitching.
+ */
+interface StreamBuffer {
+    append(chunk: StreamChunk): number;
+    confirmed(): readonly StreamChunk[];
+    confirmedCharCount(): number;
+    snapshot(): string;
+}
+
+/**
+ * Append-only stream buffer with confirmed boundary per D-30.
+ *
+ * Accumulates StreamChunks during a streaming response.
+ * On interruption, confirmed() returns all chunks received so far,
+ * and snapshot() returns the concatenated confirmed text for
+ * stream stitching.
+ */
+
+/**
+ * Creates a new StreamBuffer instance.
+ *
+ * The buffer is append-only: chunks can be added but never removed.
+ * This preserves a reliable confirmed boundary for stream resume.
+ *
+ * @returns A StreamBuffer instance.
+ */
+declare const createStreamBuffer: () => StreamBuffer;
+
+/**
+ * Multi-segment stream stitcher with provenance metadata per D-31 through D-33.
+ *
+ * Assembles output from multiple segments (potentially from different targets
+ * after failover) into a single StitchedOutput with per-segment provenance
+ * and continuation boundary markers.
+ *
+ * Cross-target continuations are annotated as non_deterministic per D-33/TRAN-02
+ * because the output may not be semantically consistent across model boundaries.
+ */
+
+/**
+ * StreamStitcher interface for assembling multi-segment output.
+ */
+interface StreamStitcher {
+    addSegment(buffer: StreamBuffer, provenance: Omit<SegmentProvenance, 'visible_offset'>): void;
+    assemble(): StitchedOutput;
+    segmentCount(): number;
+}
+/**
+ * Determines the continuation mode based on target and model relationship per D-31.
+ *
+ * - Same target: same_target_resume (deterministic)
+ * - Different target, same model: same_model_alternate_target
+ * - Different target, different model: cross_model_semantic (non-deterministic)
+ *
+ * Note: controlled_reexecution is set by the orchestrator when no viable
+ * continuation target exists, not by the stitcher.
+ *
+ * @param oldTargetId - The target ID of the previous segment.
+ * @param newTargetId - The target ID of the new segment.
+ * @param sameModel - Whether both targets serve the same model.
+ * @returns The appropriate ContinuationMode.
+ */
+declare const determineContinuationMode: (oldTargetId: string, newTargetId: string, sameModel: boolean) => ContinuationMode;
+/**
+ * Creates a new StreamStitcher instance.
+ *
+ * The stitcher accumulates segments via addSegment() and produces
+ * a final StitchedOutput via assemble() with:
+ * - Concatenated text from all segments
+ * - Per-segment provenance with computed visible_offset
+ * - continuation_boundaries marking join points between segments
+ *
+ * @param _requestId - The correlation request ID (reserved for future audit use).
+ * @returns A StreamStitcher instance.
+ */
+declare const createStreamStitcher: (_requestId: string) => StreamStitcher;
+
+/**
+ * Audit collector for per-request audit trail accumulation.
+ *
+ * Subscribes to routing events and accumulates FailoverAttempt
+ * and SegmentProvenance records per request. On flush(), emits
+ * a complete AuditRecord to pino with all AUDT-02 fields
+ * (request_id, attempt_no, segment_no, selected_target, candidates,
+ * selection_reason, failure_class, retry_no, failover_no, latency_ms, outcome).
+ *
+ * flush() is always called in a finally block even on zero-attempt
+ * failures per Pitfall 3.
+ */
+
+/**
+ * AuditCollector interface for accumulating and flushing audit records.
+ *
+ * Single-use per request: after flush(), the collector emits
+ * its accumulated data and is considered complete.
+ */
+interface AuditCollector {
+    /** Records a failover attempt. */
+    recordAttempt(attempt: FailoverAttempt): void;
+    /** Records a segment provenance entry. */
+    recordSegment(segment: SegmentProvenance): void;
+    /** Flushes the accumulated audit record to pino. */
+    flush(outcome: 'success' | 'failure', finalTarget?: string, stats?: {
+        total_retries?: number;
+        total_failovers?: number;
+        latency_ms?: number;
+    }): void;
+}
+/**
+ * Creates an AuditCollector for a specific request.
+ *
+ * The collector accumulates FailoverAttempt and SegmentProvenance
+ * records and flushes them as a single pino log entry with
+ * event_type 'request_complete'.
+ *
+ * @param logger - The base pino logger (a child logger with request_id is created internally).
+ * @param requestId - The correlation request ID for this request.
+ * @returns An AuditCollector instance.
+ */
+declare const createAuditCollector: (logger: pino.Logger, requestId: string) => AuditCollector;
+
+/**
+ * Execution orchestrator: wires ModeAdapter + FailoverOrchestrator +
+ * StreamStitcher + AuditCollector into a single execute call.
+ *
+ * Produces ExecutionResult with full provenance metadata including
+ * segments, continuation_modes, targets_involved, degraded flag (D-38),
+ * and heuristic_detection flag (D-37).
+ *
+ * AuditCollector.flush() is ALWAYS called via try/finally even on
+ * zero-attempt failures (Pitfall 3).
+ */
+
+/**
+ * Dependencies for the execution orchestrator.
+ */
+interface ExecutionDeps {
+    /** Mode adapter for executing requests against targets. */
+    readonly adapter: ModeAdapter;
+    /** Failover orchestrator for retry-failover logic. */
+    readonly failover: FailoverOrchestrator;
+    /** Base pino logger for audit trail. */
+    readonly logger: pino.Logger;
+    /** Current deployment mode. */
+    readonly mode: DeploymentMode;
+}
+/**
+ * Execution orchestrator interface.
+ */
+interface ExecutionOrchestrator {
+    /** Executes a request through the full pipeline. */
+    execute(request: AdapterRequest): Promise<ExecutionResult>;
+}
+/**
+ * Creates an execution orchestrator that composes adapter, failover,
+ * stream stitcher, and audit collector into an end-to-end pipeline.
+ *
+ * @param deps - Execution dependencies.
+ * @returns An ExecutionOrchestrator instance.
+ */
+declare const createExecutionOrchestrator: (deps: ExecutionDeps) => ExecutionOrchestrator;
+
+/**
+ * Shared adapter configuration types.
+ *
+ * Provides the dependency injection interface for all mode adapters.
+ */
+
+/**
+ * Dependencies injected into mode adapters.
+ *
+ * classifyError is the unified error classification function
+ * that routes to direct or heuristic classification.
+ */
+interface AdapterDeps {
+    readonly classifyError: (signal: NormalizedSignal) => ClassificationResult;
+}
+
+/**
+ * Adapter factory: selects the correct ModeAdapter by DeploymentMode.
+ *
+ * Provides a single entry point for creating the appropriate adapter
+ * based on the resolved deployment mode. Uses exhaustive switch
+ * with never default for type safety.
+ */
+
+/**
+ * Creates the appropriate ModeAdapter for the given deployment mode.
+ *
+ * @param mode - The resolved deployment mode.
+ * @param deps - Shared adapter dependencies.
+ * @returns The ModeAdapter implementation for the specified mode.
+ * @throws Error if an unknown deployment mode is provided (compile-time exhaustive check).
+ */
+declare const createModeAdapter: (mode: DeploymentMode, deps: AdapterDeps) => ModeAdapter;
+
+/**
+ * Operator command result types.
+ *
+ * All types are readonly interfaces per D-39. Operator commands
+ * return structured results for programmatic consumption.
+ */
+
+/** Dependencies injected into all operator commands. */
+interface OperatorDeps {
+    readonly registry: TargetRegistry;
+    readonly circuitBreakers: ReadonlyMap<string, CircuitBreaker>;
+    readonly configRef: ConfigRef;
+    readonly logger: pino.Logger;
+    readonly traceBuffer: RequestTraceBuffer;
+}
+/** Mutable config reference with atomic swap for reload. */
+interface ConfigRef {
+    current(): SwitcherConfig;
+    swap(config: SwitcherConfig): void;
+}
+/** Enriched target view returned by listTargets. */
+interface TargetView {
+    readonly target_id: string;
+    readonly provider_id: string;
+    readonly profile: string | undefined;
+    readonly state: TargetState;
+    readonly health_score: number;
+    readonly circuit_breaker_state: TargetState;
+    readonly cooldown_until: number | null;
+    readonly enabled: boolean;
+    readonly latency_ema_ms: number;
+    readonly failure_score: number;
+    readonly operator_priority: number;
+}
+/** Result of listTargets command. */
+interface ListTargetsResult {
+    readonly targets: ReadonlyArray<TargetView>;
+    readonly count: number;
+}
+/** Result of pauseTarget, resumeTarget, drainTarget, disableTarget commands. */
+interface TargetActionResult {
+    readonly success: boolean;
+    readonly target_id: string;
+    readonly action: string;
+    readonly error?: string;
+}
+/** Result of inspectRequest command. */
+interface InspectResult {
+    readonly found: boolean;
+    readonly request_id: string;
+    readonly trace?: RequestTraceEntry;
+}
+/** Result of reloadConfig command. */
+interface ReloadResult {
+    readonly success: boolean;
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    readonly modified: readonly string[];
+    readonly diagnostics?: ReadonlyArray<ConfigDiagnostic>;
+}
+/** A single request trace entry stored in the ring buffer. */
+interface RequestTraceEntry {
+    readonly request_id: string;
+    readonly timestamp_ms: number;
+    readonly outcome: string;
+    readonly target_id?: string;
+    readonly total_attempts: number;
+    readonly total_segments: number;
+    readonly attempts: readonly unknown[];
+    readonly segments: readonly unknown[];
+}
+/** Ring buffer interface for request trace storage. */
+interface RequestTraceBuffer {
+    /** Records a trace entry, evicting the oldest if at capacity. */
+    record(entry: RequestTraceEntry): void;
+    /** Looks up a trace entry by request ID. Returns undefined if not found. */
+    lookup(requestId: string): RequestTraceEntry | undefined;
+    /** Returns current number of entries in the buffer. */
+    size(): number;
+}
+
+/**
+ * Pure operator command functions per D-39.
+ *
+ * All commands take OperatorDeps and return structured results.
+ * No separate operator state -- all mutations go through TargetRegistry (D-40).
+ * All commands work without code changes (OPER-05) -- they are runtime function calls.
+ */
+
+/**
+ * Creates a ring buffer for request trace storage.
+ *
+ * Uses Map for O(1) lookup and array for insertion order tracking.
+ * When size exceeds capacity, oldest entries are evicted.
+ *
+ * @param capacity - Maximum number of entries to store.
+ */
+declare const createRequestTraceBuffer: (capacity: number) => RequestTraceBuffer;
+/**
+ * Lists all targets with enriched circuit breaker state.
+ * Per D-39: returns target_id, state, health_score, circuit_breaker_state,
+ * cooldown_until, enabled, latency_ema_ms, failure_score, operator_priority.
+ */
+declare const listTargets: (deps: OperatorDeps) => ListTargetsResult;
+/** Pauses a target by setting state to Disabled. Per research: reuse Disabled with semantic action name. */
+declare const pauseTarget: (deps: OperatorDeps, targetId: string) => TargetActionResult;
+/** Resumes a target by setting state to Active. */
+declare const resumeTarget: (deps: OperatorDeps, targetId: string) => TargetActionResult;
+/** Drains a target by setting state to Draining. No new requests will be routed. */
+declare const drainTarget: (deps: OperatorDeps, targetId: string) => TargetActionResult;
+/** Disables a target by setting state to Disabled. */
+declare const disableTarget: (deps: OperatorDeps, targetId: string) => TargetActionResult;
+/** Inspects a request by looking up its trace in the ring buffer. */
+declare const inspectRequest: (deps: OperatorDeps, requestId: string) => InspectResult;
+/**
+ * Reloads configuration with diff-apply logic.
+ *
+ * 1. Validates raw config via validateConfig
+ * 2. On validation failure: returns diagnostics, no changes applied (D-43)
+ * 3. On success: computes diff, applies to registry, swaps config reference
+ */
+declare const reloadConfig: (deps: OperatorDeps, rawConfig: unknown) => ReloadResult;
+
+/**
+ * Config reload with diff-apply logic per D-42, D-43.
+ *
+ * computeConfigDiff: Three-pass diff (added, removed, modified) per Pitfall 4.
+ * applyConfigDiff: Applies diff to registry. Removed targets are Disabled
+ * (not deleted) to protect in-flight requests per Pitfall 1.
+ */
+
+/** The result of diffing old and new configuration. */
+interface ConfigDiff {
+    readonly added: readonly TargetConfig[];
+    readonly removed: readonly string[];
+    readonly modified: readonly TargetConfig[];
+}
+/**
+ * Computes a three-pass diff between old and new configs per Pitfall 4.
+ *
+ * Pass 1: Find targets in newConfig not in oldConfig (added)
+ * Pass 2: Find targets in oldConfig not in newConfig (removed)
+ * Pass 3: For intersection, compare mutable fields (modified)
+ */
+declare const computeConfigDiff: (oldConfig: SwitcherConfig, newConfig: SwitcherConfig) => ConfigDiff;
+/**
+ * Applies a config diff to the registry.
+ *
+ * - Added targets: creates fresh TargetEntry with INITIAL_HEALTH_SCORE
+ * - Removed targets: sets state to Disabled (not deleted) per Pitfall 1
+ * - Modified targets: rebuilds entry with updated config fields
+ */
+declare const applyConfigDiff: (registry: TargetRegistry, diff: ConfigDiff) => void;
+
+/**
+ * Bearer token authentication middleware for server-companion mode.
+ *
+ * Per D-44: Server-companion mode operator endpoints require Bearer token
+ * authentication. Plugin-only mode commands inherit OpenCode session auth.
+ *
+ * Per Pitfall 3: Uses crypto.timingSafeEqual for constant-time token
+ * comparison to prevent timing attacks.
+ */
+/** Result of bearer token validation. */
+interface AuthResult {
+    readonly authorized: boolean;
+    readonly reason?: string;
+}
+/**
+ * Validates a Bearer token from the Authorization header.
+ *
+ * @param authHeader - The raw Authorization header value, or undefined if absent.
+ * @param expectedToken - The expected token to compare against.
+ * @returns AuthResult indicating whether the request is authorized.
+ */
+declare const validateBearerToken: (authHeader: string | undefined, expectedToken: string) => AuthResult;
+
+/**
+ * OpenCode plugin tool wrappers for operator commands.
+ *
+ * Per D-39 and OPER-05: Each operator command is exposed as an OpenCode
+ * plugin tool with Zod-validated args. Plugin tools return JSON-stringified
+ * results from the pure command functions.
+ *
+ * Uses @opencode-ai/plugin/tool for tool definition with Zod schema.
+ */
+
+/**
+ * Creates operator tool definitions bound to the given dependencies.
+ *
+ * Each tool wraps a pure operator command function, validates args via Zod,
+ * and returns JSON-stringified results.
+ *
+ * @param deps - Operator dependencies (registry, circuit breakers, config, logger, trace buffer).
+ */
+/** Map of all operator tool definitions keyed by command name. */
+interface OperatorTools {
+    readonly listTargets: ToolDefinition;
+    readonly pauseTarget: ToolDefinition;
+    readonly resumeTarget: ToolDefinition;
+    readonly drainTarget: ToolDefinition;
+    readonly disableTarget: ToolDefinition;
+    readonly inspectRequest: ToolDefinition;
+    readonly reloadConfig: ToolDefinition;
+}
+declare const createOperatorTools: (deps: OperatorDeps) => OperatorTools;
+
+/**
+ * Profile store CRUD operations.
+ *
+ * Pure functions for in-memory store manipulation (addProfile, removeProfile,
+ * listProfiles, nextProfileId) plus file I/O helpers (loadProfiles, saveProfiles).
+ *
+ * File writes are atomic: write to .tmp then rename (D-67).
+ * Default paths target ~/.local/share/o-switcher/profiles.json (D-62).
+ */
+
+/**
+ * Loads the profile store from disk.
+ * Returns empty store if file does not exist.
+ */
+declare const loadProfiles: (path?: string) => Promise<ProfileStore>;
+/**
+ * Saves the profile store to disk atomically.
+ * Writes to a .tmp file first, then renames to the target path (D-67).
+ * Creates parent directories if they do not exist.
+ *
+ * @param store - Profile store to persist.
+ * @param path - Target file path.
+ * @param logger - Optional pino logger for disk write logging.
+ */
+declare const saveProfiles: (store: ProfileStore, path?: string, logger?: pino.Logger) => Promise<void>;
+/**
+ * Adds a profile to the store. Pure function — returns a new store.
+ *
+ * Assigns a sequential ID via nextProfileId (e.g., openai-1, openai-2).
+ * Skips if credentials match an existing entry for the same provider (dedup).
+ */
+declare const addProfile: (store: ProfileStore, provider: string, credentials: AuthCredential) => ProfileStore;
+/**
+ * Removes a profile by ID. Pure function — returns new store and removal status.
+ */
+declare const removeProfile: (store: ProfileStore, id: string) => {
+    store: ProfileStore;
+    removed: boolean;
+};
+/**
+ * Lists all profiles sorted by created date (oldest first).
+ */
+declare const listProfiles: (store: ProfileStore) => ProfileEntry[];
+/**
+ * Computes the next sequential profile ID for a provider.
+ *
+ * Finds the maximum N in existing "provider-N" entries and returns "provider-(N+1)".
+ * Returns "provider-1" when no profiles exist for the provider.
+ */
+declare const nextProfileId: (store: ProfileStore, provider: string) => string;
+
+/**
+ * Auth.json file watcher with debounce and credential comparison.
+ *
+ * Watches OpenCode's auth.json for changes, saves the PREVIOUS credential
+ * to O-Switcher's profile store before accepting the new one (D-65, D-66).
+ *
+ * On first run with empty profiles, initializes from current auth.json (D-72).
+ * Debounce at 100ms collapses rapid fs.watch events (D-67).
+ */
+
+/** Watcher interface with start/stop lifecycle. */
+interface AuthWatcher {
+    start(): Promise<void>;
+    stop(): void;
+}
+/** Options for creating an auth watcher. */
+interface AuthWatcherOptions {
+    readonly authJsonPath?: string;
+    readonly profilesPath?: string;
+    readonly logger?: pino.Logger;
+}
+/**
+ * Creates a file watcher for OpenCode's auth.json.
+ *
+ * Watches for credential changes and saves previous credentials to the
+ * O-Switcher profile store before they are overwritten.
+ */
+declare const createAuthWatcher: (options?: AuthWatcherOptions) => AuthWatcher;
+
+/**
+ * OpenCode plugin tool definitions for profile management.
+ *
+ * Per D-68, D-69, D-70: profiles-list and profiles-remove tools.
+ * Follows the exact pattern from src/operator/plugin-tools.ts.
+ *
+ * Tools are stateless — they call loadProfiles/saveProfiles on each invocation,
+ * so they can be created eagerly before plugin state is initialized.
+ */
+
+/** Map of profile tool definitions keyed by command name. */
+interface ProfileTools {
+    readonly profilesList: ToolDefinition;
+    readonly profilesRemove: ToolDefinition;
+}
+/** Options for creating profile tools. */
+interface ProfileToolsOptions {
+    readonly profilesPath?: string;
+}
+/**
+ * Creates profile tool definitions.
+ *
+ * Each tool operates on the profiles.json file directly (load/save per call).
+ * No shared state required — tools are safe to create eagerly.
+ *
+ * @param options - Optional path override for profiles.json (useful for testing).
+ */
+declare const createProfileTools: (options?: ProfileToolsOptions) => ProfileTools;
+
+export { ADMISSION_RESULTS, type AdapterRequest, type AdapterResult, type AdmissionConfig, type AdmissionContext, type AdmissionController, type AdmissionDecision, type AdmissionResult, type ApiKeyCredential, type AttemptFn, type AuditCollector, type AuditEvent, type AuditLoggerOptions, type AuthCredential, type AuthResult, type AuthWatcher, type AuthWatcherOptions, type BackoffConfig, BackoffConfigSchema, type BackoffParams, type CircuitBreaker, type CircuitBreakerConfig, type ClassificationResult, type ConcurrencyTrackerApi, type ConfigDiagnostic, type ConfigDiff, type ConfigRef, ConfigValidationError, type ContinuationMode, type CooldownManager, type CorrelationId, DEFAULT_ALPHA, DEFAULT_BACKOFF_BASE_MS, DEFAULT_BACKOFF_JITTER, DEFAULT_BACKOFF_MAX_MS, DEFAULT_BACKOFF_MULTIPLIER, DEFAULT_BACKOFF_PARAMS, DEFAULT_FAILOVER_BUDGET, DEFAULT_RETRY, DEFAULT_RETRY_BUDGET, DEFAULT_TIMEOUT_MS, type DeploymentMode, DualBreaker, EXCLUSION_REASONS, type ErrorClass, ErrorClassSchema, type ExclusionReason, type ExecutionDeps, type ExecutionOrchestrator, type ExecutionProvenance, type ExecutionResult, type FailoverAttempt, type FailoverDeps, type FailoverOrchestrator, type FailoverRegistry, type FailoverResult, HEURISTIC_PATTERNS, INITIAL_HEALTH_SCORE, type InspectResult, type ListTargetsResult, type ModeAdapter, type ModeCapabilities, type NormalizedSignal, type OAuthCredential, type OperatorDeps, type OperatorTools, PROVIDER_PATTERNS, type ProfileEntry, type ProfileStore, type ProfileTools, type ProfileToolsOptions, type ProviderConfigLike, REDACT_PATHS, type RegistrySnapshot, type ReloadResult, type RequestTraceBuffer, type RequestTraceEntry, type RetryDecision, type RetryPolicy, type RoutingEventMap, type RoutingWeights, type SegmentProvenance, type SelectionRecord, type SignalFidelity, type StitchedOutput, type StreamBuffer, type StreamChunk, type StreamStitcher, type SwitcherConfig, SwitcherConfigSchema, TARGET_STATES, TEMPORAL_QUOTA_PATTERN, type TargetActionResult, type TargetConfig, TargetConfigSchema, type TargetEntry, TargetRegistry, type TargetState, type TargetView, addProfile, applyConfigDiff, checkHardRejects, classify, computeBackoffMs, computeConfigDiff, computeCooldownMs, computeScore, createAdmissionController, createAuditCollector, createAuditLogger, createAuthWatcher, createCircuitBreaker, createConcurrencyTracker, createCooldownManager, createExecutionOrchestrator, createFailoverOrchestrator, createLogSubscriber, createModeAdapter, createOperatorTools, createProfileTools, createRegistry, createRequestLogger, createRequestTraceBuffer, createRetryPolicy, createRoutingEventBus, createStreamBuffer, createStreamStitcher, detectDeploymentMode, determineContinuationMode, directSignalFromResponse, disableTarget, discoverTargets, discoverTargetsFromProfiles, drainTarget, extractRetryAfterMs, generateCorrelationId, getExclusionReason, getModeCapabilities, getSignalFidelity, getTargetStateTransition, heuristicSignalFromEvent, inspectRequest, isRetryable, listProfiles, listTargets, loadProfiles, nextProfileId, normalizeLatency, pauseTarget, reloadConfig, removeProfile, resumeTarget, saveProfiles, selectTarget, updateHealthScore, updateLatencyEma, validateBearerToken, validateConfig };