/**
 * Routing telemetry emitter — T039.
 *
 * Maintains an append-only rolling window of routing decisions for
 * observability and audit. Window bounds: 168 hours (7 days), max 1111 entries.
 */
import { type ContextFitConfig } from '../../domain/routing/context-fit.js';
import type { ClusterMatcher } from '../../domain/matching/cluster-matcher.js';
import type { SessionPinner } from '../../domain/pinning/session-pinner.js';
import type { BreakevenObservability, ClusterMatchTableEntry, ContextFitObservability, ModelProfile, PlanningDelegateObservability, PlanningDelegatePath, PriceCatalog, RoutePath, RoutingDecision, RoutingRequest, RoutingTelemetry, SaarConfig, SaarObservability, Tier, TierSelectionObservability } from '../../domain/types/index.js';
import type { QuotaWindowPosition } from '../../domain/types/entities.js';
import type { VirtualCostV2Config } from '../../domain/types/schemas.js';
export declare const CONTEXT_FIT_PASS: "context_fit_pass";
export declare const CONTEXT_FIT_REJECTED_ALL: "context_fit_rejected_all";
export declare const CONTEXT_OVERFLOW_PIN_BREAK: "context_overflow_pin_break";
export declare const LOW_INTENSITY_STRUCTURAL: "low_intensity_structural";
export declare const HIGH_INTENSITY_STRUCTURAL: "high_intensity_structural";
export declare const P_SUCCESS_CHEAP: "p_success_cheap";
export declare const P_SUCCESS_UNCERTAIN: "p_success_uncertain";
/** Cache breakeven gate observability with virtual cost v2 scalars (SP-149). */
export interface BreakevenObservabilityV2 extends BreakevenObservability {
    readonly quota_premium_usd: number | null;
    readonly kv_cache_credit_usd: number | null;
}
export declare const BREAKEVEN_BLOCKED: "breakeven_blocked";
export declare const BREAKEVEN_PASS: "breakeven_pass";
export declare const SAAR_BUFFER_ACTIVE: "saar_buffer_active";
export declare const SAAR_HARD_LOCK: "saar_hard_lock";
export declare const FLIP_FLOP_TIER_FLIP: "flip_flop_tier_flip";
export declare const FLIP_FLOP_TIER_PINNED: "flip_flop_tier_pinned";
export declare const PLANNING_DELEGATE: "planning_delegate";
export declare const PLANNING_DIRECT_FRONTIER: "planning_direct_frontier";
export declare const PLANNING_DELEGATE_DISABLED: "planning_delegate_disabled";
export declare const PLANNING_DELEGATE_UNAVAILABLE: "planning_delegate_unavailable";
/** Reason recorded when a delegate sub-call exceeds its timeout budget (SP-213, #120). */
export declare const PLANNING_DELEGATE_TIMEOUT: "planning_delegate_timeout";
export declare const THROUGHPUT_BELOW_THRESHOLD: "throughput_below_threshold";
/** Pre-local_zero tool-use capability shortfall (SP-177, #98). */
export declare const TOOL_USE_CAPABILITY_SHORTFALL: "tool_use_capability_shortfall";
/** Operator disabled local_zero stage (SP-177, #98). */
export declare const LOCAL_ZERO_DISABLED: "local_zero_disabled";
/** Emergency pin-on-first-turn fallback reason code (#83, SP-161/162). */
export declare const PIN_ONLY_FALLBACK: "pin_only_fallback";
/**
 * Estimate per-request routing cost in USD from resolved model pricing (SP-085).
 * Uses estimated_input_tokens when present, otherwise prompt_text length as a token proxy.
 */
export declare function estimateRoutingCost(model: ModelProfile, request: RoutingRequest, catalog: PriceCatalog | null): number;
export { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, TELEMETRY_MAX_ENTRIES, TELEMETRY_WINDOW_HOURS, TELEMETRY_WINDOW_MS, } from './telemetry-limits.js';
export interface TelemetryEmitterOptions {
    readonly maxEntries?: number;
    readonly windowMs?: number;
    readonly clock?: () => string;
    readonly onRecord?: (record: RoutingTelemetry) => void;
    readonly fleet?: readonly ModelProfile[];
    readonly contextFitConfig?: ContextFitConfig;
    readonly sessionPinner?: SessionPinner;
    readonly saarConfig?: SaarConfig;
    readonly priceCatalog?: PriceCatalog | null;
    readonly quotaWindowPosition?: QuotaWindowPosition;
    readonly virtualCostV2Config?: VirtualCostV2Config;
}
export interface ContextFitObservabilityInput {
    readonly request: RoutingRequest;
    readonly decision: RoutingDecision;
    readonly fleet?: readonly ModelProfile[] | undefined;
    readonly contextFitConfig?: ContextFitConfig | undefined;
}
/** Build privacy-safe context-fit observability from a routing decision (SP-110). */
export declare function buildContextFitObservability(input: ContextFitObservabilityInput): ContextFitObservability | null;
/** Normalize tier-selection reason codes for telemetry and explain (SP-113). */
export declare function resolveTierSelectionReasonCode(features: RoutingDecision['features']): string | null;
/** Infer why local_zero did not dispatch when another stage won (SP-113). */
export declare function buildLocalZeroSkipReasons(decision: RoutingDecision, features: RoutingDecision['features']): readonly string[];
export interface TierSelectionObservabilityInput {
    readonly decision: RoutingDecision;
    readonly clusterMatchTable?: readonly ClusterMatchTableEntry[] | null;
}
/** Build privacy-safe tier/cluster observability from routing decision features (SP-113). */
export declare function buildTierSelectionObservability(input: TierSelectionObservabilityInput): TierSelectionObservability | null;
export interface PinEconomicsObservabilityInput {
    readonly request: RoutingRequest;
    readonly decision: RoutingDecision;
    readonly fleet?: readonly ModelProfile[] | undefined;
    readonly sessionPinner?: SessionPinner | undefined;
    readonly saarConfig?: SaarConfig | undefined;
    readonly priceCatalog?: PriceCatalog | null;
    readonly quotaWindowPosition?: QuotaWindowPosition;
    readonly virtualCostV2Config?: VirtualCostV2Config;
}
/** Build planning delegate observability from routing decision features (SP-142). */
export declare function buildPlanningDelegateObservability(decision: RoutingDecision): PlanningDelegateObservability | null;
/** Construct planning delegate observability for pipeline and tests (SP-142). */
export declare function createPlanningDelegateObservability(input: {
    path: PlanningDelegatePath;
    primary_model_id?: string | null;
    delegate_model_id?: string | null;
    compressed_context?: PlanningDelegateObservability['compressed_context'];
    planning_delegate_reason_code: string;
    fallback_reason?: string | null;
    /** Worker telemetry analogs (SP-213, #120); null when not yet executed. */
    workers_spawned?: number | null;
    workers_succeeded?: number | null;
    worker_timeout_count?: number | null;
}): PlanningDelegateObservability;
/** Attach planning delegate observability to routing decision features (SP-142). */
export declare function enrichRoutingDecisionWithPlanningDelegate(decision: RoutingDecision, planningDelegate?: PlanningDelegateObservability | null): RoutingDecision;
/** Flip-flop shadow log observability (SP-155, #82). */
export interface FlipFlopObservability {
    readonly consecutive_tier_flips: number;
    readonly tier_pinned: Tier | null;
    readonly shadow_event: string | null;
}
/** Build privacy-safe SAAR pin state for explain and telemetry (SP-126). */
export declare function buildSaarObservability(input: PinEconomicsObservabilityInput): SaarObservability | null;
/** Build flip-flop shadow log observability from session pinner state (SP-155). */
export declare function buildFlipFlopObservability(input: PinEconomicsObservabilityInput): FlipFlopObservability | null;
/** Build cache breakeven breakdown when a pin would switch tiers (SP-126, SP-149). */
export declare function buildBreakevenObservability(input: PinEconomicsObservabilityInput): BreakevenObservabilityV2 | null;
/** Default breakeven telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_BREAKEVEN_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "marginal_savings" | "future_cache_value" | "cache_reprime_cost" | "breakeven_reason_code" | "breakeven_decision">;
/** Default SAAR telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_SAAR_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "turn_index_in_session" | "saar_reason_code" | "saar_buffer_active" | "saar_hard_lock">;
/** Default planning delegate telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_PLANNING_DELEGATE_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "planning_delegate_reason_code" | "planning_delegate_path" | "planning_delegate_primary_model_id" | "planning_delegate_model_id" | "planning_delegate_fallback_reason" | "planning_delegate_max_messages" | "planning_delegate_max_tokens" | "planning_delegate_exclude_execution_history" | "planning_delegate_workers_spawned" | "planning_delegate_workers_succeeded" | "planning_delegate_worker_timeout_count">;
/** Default pin-only fallback telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_PIN_ONLY_FALLBACK_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "pin_only_fallback_active">;
declare function defaultPrewarmTelemetry(): Pick<RoutingTelemetry, 'prewarm_attempted' | 'prewarm_accepted' | 'prewarm_disabled_reason'>;
/** Default speculative prewarm telemetry scalars for tests and legacy store reads (SP-217). */
export declare const DEFAULT_PREWARM_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "prewarm_attempted" | "prewarm_accepted" | "prewarm_disabled_reason">;
/** Prewarm explain/telemetry fields from the decision feature sidecar (SP-217, #117). */
export declare function prewarmTelemetryFromDecision(decision: RoutingDecision): ReturnType<typeof defaultPrewarmTelemetry>;
/** True when routing used emergency pin-only fallback for this decision (SP-162). */
export declare function resolvePinOnlyFallbackActive(decision: RoutingDecision): boolean;
/** Attach breakeven and SAAR observability to routing decision features (SP-126). */
export declare function enrichRoutingDecisionWithPinEconomics(request: RoutingRequest, decision: RoutingDecision, options?: Omit<PinEconomicsObservabilityInput, 'request' | 'decision'>): RoutingDecision;
/** Attach tier-selection observability to a routing decision features sidecar (SP-113). */
export declare function enrichRoutingDecisionWithTierSelection(decision: RoutingDecision, clusterMatchTable?: readonly ClusterMatchTableEntry[] | null): RoutingDecision;
export interface ExplainEnrichmentOptions {
    readonly fleet?: readonly ModelProfile[];
    readonly contextFitConfig?: ContextFitConfig;
    readonly clusterMatcher?: ClusterMatcher;
    readonly sessionPinner?: SessionPinner;
    readonly saarConfig?: SaarConfig;
    readonly priceCatalog?: PriceCatalog | null;
    readonly quotaWindowPosition?: QuotaWindowPosition;
    readonly virtualCostV2Config?: VirtualCostV2Config;
}
/** Attach context-fit and tier-selection observability for explain responses (SP-110, SP-113). */
export declare function enrichRoutingDecisionForExplain(request: RoutingRequest, decision: RoutingDecision, options?: ExplainEnrichmentOptions): Promise<RoutingDecision>;
/** Attach context-fit observability to a routing decision features sidecar (SP-110). */
export declare function enrichRoutingDecisionWithContextFit(request: RoutingRequest, decision: RoutingDecision, fleet?: readonly ModelProfile[], contextFitConfig?: ContextFitConfig): RoutingDecision;
export interface RoutingDecisionLogDelegate {
    readonly provider: string;
    readonly modelId: string;
    readonly api: string;
}
/** JSON payload for SMART_ROUTER_LOG_ROUTING=1 stderr lines (SP-110). */
export declare function buildRoutingDecisionLogPayload(request: RoutingRequest, decision: RoutingDecision, delegate?: RoutingDecisionLogDelegate, fleet?: readonly ModelProfile[], contextFitConfig?: ContextFitConfig, pinEconomics?: Omit<PinEconomicsObservabilityInput, 'request' | 'decision' | 'fleet'>): Record<string, unknown>;
/** Default context-fit telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_CONTEXT_FIT_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "estimated_input_tokens" | "context_fit_viable_count" | "context_fit_rejected_json" | "context_overflow_pin_break" | "selected_model_max_input_tokens" | "context_fit_reason_code">;
/** Default tier-selection telemetry scalars for tests and legacy store reads. */
export declare const DEFAULT_TIER_SELECTION_TELEMETRY_FIELDS: Pick<RoutingTelemetry, "cluster_id" | "tier_hint" | "tier_selection_reason_code" | "p_success_cheap" | "cluster_similarity" | "cluster_margin" | "low_intensity_score" | "local_eligible_reason">;
/** Default context-fit dataset scalars for tests and legacy store reads. */
export declare const DEFAULT_CONTEXT_FIT_DATASET_FIELDS: {
    readonly estimated_input_tokens_gate: null;
    readonly context_fit_viable_count: null;
    readonly context_fit_rejected_json: null;
    readonly context_overflow_pin_break: false;
    readonly selected_model_max_input_tokens: null;
    readonly context_fit_reason_code: null;
};
/** Default tier-selection dataset scalars for tests and legacy store reads. */
export declare const DEFAULT_TIER_SELECTION_DATASET_FIELDS: {
    readonly cluster_id: null;
    readonly cluster_similarity: null;
    readonly cluster_margin: null;
    readonly low_intensity_score: null;
    readonly tier_hint: null;
    readonly p_success_cheap: null;
    readonly local_eligible_reason: null;
    readonly tier_selection_reason_code: null;
};
/** Optional route_path classification supplied by the pipeline (SP-212, #119). */
export interface RoutePathTelemetryExtras {
    readonly routePath?: RoutePath | null;
    readonly routePathConfidence?: number | null;
}
export declare class RoutingTelemetryEmitter {
    private readonly entries;
    private readonly maxEntries;
    private readonly windowMs;
    private readonly clock;
    private readonly onRecord;
    private readonly fleet;
    private readonly contextFitConfig;
    private readonly sessionPinner;
    private readonly saarConfig;
    private readonly priceCatalog;
    private readonly quotaWindowPosition;
    private readonly virtualCostV2Config;
    constructor(options?: TelemetryEmitterOptions);
    /**
     * Emit a telemetry record from a completed routing decision.
     * Enforces the rolling window (time + count) before appending.
     */
    emit(request: RoutingRequest, decision: RoutingDecision, extras?: RoutePathTelemetryExtras): RoutingTelemetry;
    /**
     * Emit telemetry when a pipeline stage throws and routing degrades to safe default.
     */
    emitPipelineError(request: RoutingRequest, failedStage: string, fallback: RoutingDecision, extras?: RoutePathTelemetryExtras): RoutingTelemetry;
    private appendRecord;
    /** Current number of retained entries. */
    get size(): number;
    /** Snapshot of all retained entries (newest last). */
    snapshot(): readonly RoutingTelemetry[];
}
//# sourceMappingURL=routing-telemetry.d.ts.map