firstpass_proxy/run.rs
1//! Server bootstrap shared by the `firstpass` and `firstpass-proxy` binaries: build state from
2//! config, open the trace store, and serve until Ctrl-C. Keeping this in the lib means both the
3//! unified CLI (`firstpass up`) and the bare proxy binary start the server the exact same way.
4
5use std::sync::Arc;
6
7use crate::bandit::{ContextBucket, StartRungBandit};
8use crate::gate::GateHealthRegistry;
9use crate::provider::ProviderRegistry;
10use crate::{AppState, ProxyConfig, app, store};
11
12/// Initialize the global tracing subscriber from `RUST_LOG` (default `info`). Called by the
13/// binaries, not the library internals.
14pub fn init_tracing() {
15 tracing_subscriber::fmt()
16 .with_env_filter(
17 tracing_subscriber::EnvFilter::try_from_default_env()
18 .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
19 )
20 .init();
21}
22
23/// Register a default error budget for every gate named across enforce routes: auto-disable a gate
24/// whose abstain rate exceeds 25% over its last 50 runs (SPEC §7.2).
25#[must_use]
26pub fn build_gate_health(config: &ProxyConfig) -> GateHealthRegistry {
27 let mut gate_health = GateHealthRegistry::new();
28 if let Some(routing) = config.routing.as_ref() {
29 let mut seen = std::collections::HashSet::new();
30 for route in &routing.routes {
31 for gate in route.gates.iter().chain(&route.deferred_gates) {
32 if seen.insert(gate.clone()) {
33 gate_health = gate_health.with_budget(gate.clone(), 50, 0.25);
34 }
35 }
36 }
37 }
38 gate_health
39}
40
41/// Open the trace store, build [`AppState`], and serve the HTTP proxy until Ctrl-C.
42///
43/// # Errors
44/// Returns any error from opening the store, building the HTTP client, binding the listener, or
45/// serving.
46pub async fn serve(config: ProxyConfig) -> Result<(), Box<dyn std::error::Error>> {
47 let (traces, spill, writer) = store::open_with_receipts(&config.db_path, config.receipts_mode)?;
48 let bind = config.bind.clone();
49 // Build the provider registry from any `[[provider]]` entries in the routing config (Groq,
50 // Together, Ollama, …), on top of the built-in anthropic/openai defaults. No config => defaults.
51 let provider_defs = config
52 .routing
53 .as_ref()
54 .map(|r| r.providers.as_slice())
55 .unwrap_or_default();
56 let providers = ProviderRegistry::from_config(
57 provider_defs,
58 &config.upstream_anthropic,
59 &config.upstream_openai,
60 );
61 let gate_health = build_gate_health(&config);
62 // Online adaptive conformal (opt-in): seed the live threshold from the fixed one (or 0.5) and
63 // let /v1/feedback track it. Absent config => None => fixed-threshold behavior, byte-identical.
64 let adaptive = config
65 .routing
66 .as_ref()
67 .and_then(|r| r.escalation.adaptive.as_ref())
68 .map(|a| {
69 let init = config
70 .routing
71 .as_ref()
72 .and_then(|r| r.escalation.serve_threshold)
73 .unwrap_or(0.5);
74 Arc::new(std::sync::Mutex::new(
75 firstpass_core::conformal::AdaptiveConformal::new(a.alpha, a.gamma, init),
76 ))
77 });
78 let tenant_rate_limiter = crate::proxy::build_tenant_rate_limiter(&config);
79
80 // Anytime-valid risk control (opt-in, ADR 0011). Absent => None => existing behaviour,
81 // byte-identical. Present, it still contributes nothing until it certifies something, so
82 // enabling it cannot change serving until the evidence exists.
83 let eprocess = config
84 .routing
85 .as_ref()
86 .and_then(|r| r.escalation.eprocess.as_ref())
87 .map(|e| {
88 Arc::new(std::sync::Mutex::new(
89 firstpass_core::eprocess::EProcessRiskControl::new(
90 e.alpha, e.delta, e.bet, &e.grid,
91 ),
92 ))
93 });
94
95 // Session promotion (opt-in): in-memory and per-process by design. A promotion is a statement
96 // about a live conversation, so it should not outlive the process that observed it — and a
97 // stale pin restored from disk would start a fresh session on an expensive rung for reasons
98 // nobody can see. Built via the shared helper so tests cannot wire it differently.
99 let promoter = crate::proxy::build_promoter_async(&config).await?;
100
101 // Verified-response cache (opt-in): in-memory and per-process, like the promoter. A cached
102 // answer is a claim that a gate passed, and that claim should not outlive the process that
103 // witnessed it — restoring one from disk would replay a proof nobody in this run observed.
104 // Fails fast on an unreachable Redis rather than degrading to a per-replica cache: a cache
105 // that quietly stays local is indistinguishable from one that is working.
106 let verified_cache = crate::proxy::build_verified_cache(&config).await?;
107
108 // UCB1 start-rung bandit (opt-in): warm-start from stored traces so learning survives
109 // restarts. Forgiving: an unreadable or absent store simply yields an empty bandit.
110 // ponytail: operator-wide load (load_all_traces) is correct here — the bandit is also
111 // operator-wide, keyed by context bucket, not by tenant.
112 let bandit = config
113 .routing
114 .as_ref()
115 .and_then(|r| r.escalation.bandit.as_ref())
116 .map(|bc| {
117 let algorithm = match bc.algorithm {
118 firstpass_core::BanditAlgorithm::Ucb1 => crate::bandit::Algorithm::Ucb1,
119 firstpass_core::BanditAlgorithm::Thompson => crate::bandit::Algorithm::Thompson,
120 };
121 // Seed from a fresh UUID: per-process randomness, no new deps (tests seed explicitly).
122 let seed = uuid::Uuid::now_v7().as_u128() as u64;
123 let mut b = StartRungBandit::with_algorithm(
124 bc.min_observations,
125 bc.exploration,
126 algorithm,
127 bc.discount,
128 seed,
129 );
130 if let Ok(traces_history) = store::load_all_traces(&config.db_path) {
131 for trace in &traces_history {
132 // A challenger trace's rungs index a different ladder; feeding them would
133 // teach the incumbent ladder's bandit about models it never ran.
134 if trace
135 .experiment
136 .as_ref()
137 .is_some_and(|e| e.arm == firstpass_core::Arm::Challenger)
138 {
139 continue;
140 }
141 let ctx = ContextBucket::from_features(&trace.request.features);
142 b.feed_trace_attempts(&ctx, &trace.attempts);
143 }
144 tracing::info!(
145 n = traces_history.len(),
146 "bandit warm-started from trace store"
147 );
148 }
149 Arc::new(std::sync::Mutex::new(b))
150 });
151
152 // Per-query gate-pass predictor (ADR 0008 Phase 2, opt-in): warm-start from stored traces so
153 // the model survives restarts — every attempt with a clear Pass/Fail verdict is a training
154 // example. Forgiving: an unreadable or absent store simply yields a zero-init predictor.
155 let predictor = config
156 .routing
157 .as_ref()
158 .and_then(|r| r.escalation.predictor.as_ref())
159 .map(|pc| {
160 let mut p = firstpass_core::PassPredictor::new(pc.lr, pc.l2);
161 if let Ok(traces_history) = store::load_all_traces(&config.db_path) {
162 let mut n = 0usize;
163 for trace in &traces_history {
164 if trace
165 .experiment
166 .as_ref()
167 .is_some_and(|e| e.arm == firstpass_core::Arm::Challenger)
168 {
169 continue; // rung-indexed state belongs to the incumbent ladder
170 }
171 for attempt in &trace.attempts {
172 match attempt.verdict {
173 firstpass_core::Verdict::Pass => {
174 p.update(&trace.request.features, attempt.rung, true);
175 n += 1;
176 }
177 firstpass_core::Verdict::Fail => {
178 p.update(&trace.request.features, attempt.rung, false);
179 n += 1;
180 }
181 firstpass_core::Verdict::Abstain => {}
182 }
183 }
184 }
185 tracing::info!(examples = n, "predictor warm-started from trace store");
186 }
187 Arc::new(std::sync::Mutex::new(p))
188 });
189
190 // Verified predictive routing (opt-in, ADR): a pre-generation decision-model prior on the
191 // start rung. Fails open — a missing API key just disables the prior, it never blocks startup
192 // or serving, and the gate still verifies every output regardless.
193 let prior = config
194 .routing
195 .as_ref()
196 .and_then(|r| r.escalation.prior.as_ref())
197 .and_then(|pc| match std::env::var(&pc.api_key_env) {
198 Ok(api_key) => {
199 let http = reqwest::Client::builder()
200 .timeout(std::time::Duration::from_millis(pc.timeout_ms))
201 .build()
202 .ok()?;
203 Some(Arc::new(crate::prior::PriorClient::new(
204 http,
205 pc.clone(),
206 api_key,
207 )))
208 }
209 Err(_) => {
210 tracing::warn!(
211 env_var = %pc.api_key_env,
212 "escalation.prior configured but API key env var is unset — disabling prior (fail open)"
213 );
214 None
215 }
216 });
217
218 // Certified-selection experiments: rebuilt from receipts, so a restart cannot re-serve a
219 // challenger that was already proven worse. A no-op unless some route has a challenger.
220 //
221 // Optional shared log (redis-cache feature): if any challenger route sets `redis_url`, all
222 // replicas sync through the same Redis list so halt/certify is a cluster-wide decision.
223 // `build_experiment_log` fails fast on a missing or unreachable Redis rather than silently
224 // falling back to per-replica state — the same policy as `verified_cache` and `promoter`.
225 let experiment_log = crate::proxy::build_experiment_log(&config).await?;
226 let experiments = Arc::new({
227 let monitor = config
228 .routing
229 .as_ref()
230 .map_or_else(Default::default, |routing| {
231 crate::experiment::build_monitor_with(
232 &config.db_path,
233 routing,
234 experiment_log.is_some(),
235 )
236 });
237 if let Some(log) = experiment_log {
238 monitor.with_log(log)
239 } else {
240 monitor
241 }
242 });
243 // Background sync keeps all replicas ≤ 5 s stale. No-op when no log backend is configured.
244 experiments.start_sync_task(std::time::Duration::from_secs(5));
245 // Today's paired-challenger spend survives a restart, so the daily cap is a daily cap.
246 let paired_ledger = Arc::new(crate::proxy::build_paired_ledger(&config));
247
248 let state = AppState {
249 config: Arc::new(config),
250 // Observe passthrough may stream SSE, so only bound the CONNECT phase here — a total or
251 // read timeout would sever a long-lived stream. (The enforce providers, which never stream
252 // through the adapter, carry a full request timeout — see `ProviderRegistry::new`.)
253 http: reqwest::Client::builder()
254 .connect_timeout(std::time::Duration::from_secs(10))
255 .build()?,
256 providers,
257 gate_health: Arc::new(gate_health),
258 shadow_ledger: Arc::new(crate::shadow::ShadowLedger::new()),
259 paired_ledger,
260 experiments,
261 guardrails: Arc::new(crate::guard::GuardrailRegistry::new()),
262 traces,
263 adaptive,
264 eprocess,
265 verified_cache,
266 promoter,
267 bandit,
268 predictor,
269 prior,
270 tenant_rate_limiter,
271 spill,
272 };
273
274 let listener = tokio::net::TcpListener::bind(&bind).await?;
275 tracing::info!(%bind, "firstpass listening");
276 tracing::info!("offboard: unset ANTHROPIC_BASE_URL");
277
278 axum::serve(listener, app(state)?)
279 .with_graceful_shutdown(shutdown_signal())
280 .await?;
281
282 // Dropping `traces` (via `state`, already out of scope) closes the channel; wait for the
283 // writer to flush and exit before the process ends.
284 drop(writer);
285 Ok(())
286}
287
288async fn shutdown_signal() {
289 if let Err(err) = tokio::signal::ctrl_c().await {
290 tracing::warn!(%err, "failed to install Ctrl-C handler; shutting down anyway");
291 }
292}