Skip to main content

firstpass_proxy/
gate.rs

1//! The gate framework (SPEC §8 — the moat).
2//!
3//! A gate inspects a candidate [`ModelResponse`] and returns a [`GateResult`] verdict. Gates are
4//! **async** because a real gate is I/O: a subprocess plugin (§8.1), an LLM judge, a test run.
5//! Pure inline gates (non-empty, json-valid, schema) simply don't await. Gate execution is
6//! wrapped by an **error budget** ([`GateHealth`]): a gate that errors too often is auto-disabled
7//! with an alarm, so a broken gate can neither silently fail closed (burns money) nor silently
8//! fail open (burns trust) (§7.2).
9
10use crate::consistency::ConsistencyGate;
11use crate::decision::DecisionGate;
12use crate::judge::JudgeGate;
13use crate::provider::{Auth, ModelRequest, ModelResponse, ProviderRegistry};
14use crate::subprocess::SubprocessGate;
15use async_trait::async_trait;
16use firstpass_core::{AbstainPolicy, GateDef, GateResult, Verdict, cost::PriceTable};
17use std::collections::VecDeque;
18use std::sync::Mutex;
19use std::time::Duration;
20
21/// A verification gate. Object-safe + async so subprocess/model gates fit the same contract.
22#[async_trait]
23pub trait Gate: Send + Sync + std::fmt::Debug {
24    /// Stable gate id (matches the name used in routing config).
25    fn id(&self) -> &str;
26    /// Evaluate the candidate response, producing a verdict + evidence.
27    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult;
28    /// Whether an **abstain** from this gate blocks serving like a `Fail` (§7.2,
29    /// `on_abstain = "fail_closed"`). Default `false` = fail-open, the historical behavior.
30    /// The abstain verdict itself is still recorded honestly on the receipt; only the
31    /// aggregation treats it as blocking.
32    fn abstain_fails_closed(&self) -> bool {
33        false
34    }
35}
36
37/// Fails an empty (whitespace-only) completion. The cheapest possible sanity gate.
38#[derive(Debug, Clone, Copy)]
39pub struct NonEmptyGate;
40
41#[async_trait]
42impl Gate for NonEmptyGate {
43    fn id(&self) -> &str {
44        "non-empty"
45    }
46    async fn evaluate(&self, _req: &ModelRequest, resp: &ModelResponse) -> GateResult {
47        let verdict = if resp.text.trim().is_empty() {
48            Verdict::Fail
49        } else {
50            Verdict::Pass
51        };
52        GateResult::deterministic(self.id(), verdict, 0)
53    }
54}
55
56/// Passes only if the completion parses as JSON. Useful for structured-output routes.
57#[derive(Debug, Clone, Copy)]
58pub struct JsonValidGate;
59
60#[async_trait]
61impl Gate for JsonValidGate {
62    fn id(&self) -> &str {
63        "json-valid"
64    }
65    async fn evaluate(&self, _req: &ModelRequest, resp: &ModelResponse) -> GateResult {
66        let ok = serde_json::from_str::<serde_json::Value>(resp.text.trim()).is_ok();
67        GateResult::deterministic(self.id(), if ok { Verdict::Pass } else { Verdict::Fail }, 0)
68    }
69}
70
71/// Validates the candidate (parsed as JSON) against a minimal JSON-Schema subset: top-level
72/// `type`, `required`, and per-property `type`. Covers tool-call args and extraction tasks.
73///
74// ponytail: not full JSON Schema draft 2020-12 — just type/required/properties, the 90% that
75// structured-output routes need. Swap for the `jsonschema` crate if nested/`$ref` schemas appear.
76#[derive(Debug, Clone)]
77pub struct SchemaGate {
78    id: String,
79    schema: serde_json::Value,
80}
81
82impl SchemaGate {
83    /// Build a schema gate from a JSON Schema value, under the id a route references it by.
84    #[must_use]
85    pub fn new(id: impl Into<String>, schema: serde_json::Value) -> Self {
86        Self {
87            id: id.into(),
88            schema,
89        }
90    }
91
92    /// Check `value` against the minimal schema subset; returns the first violation, if any.
93    fn violation(&self, value: &serde_json::Value) -> Option<String> {
94        use serde_json::Value;
95        let type_ok = |v: &Value, ty: &str| match ty {
96            "object" => v.is_object(),
97            "array" => v.is_array(),
98            "string" => v.is_string(),
99            "number" => v.is_number(),
100            "integer" => v.is_i64() || v.is_u64(),
101            "boolean" => v.is_boolean(),
102            "null" => v.is_null(),
103            _ => true, // unknown type keyword: don't fail on it
104        };
105        if let Some(ty) = self.schema.get("type").and_then(Value::as_str)
106            && !type_ok(value, ty)
107        {
108            return Some(format!("root is not of type {ty}"));
109        }
110        if let Some(req) = self.schema.get("required").and_then(Value::as_array) {
111            for field in req.iter().filter_map(Value::as_str) {
112                if value.get(field).is_none() {
113                    return Some(format!("missing required field {field:?}"));
114                }
115            }
116        }
117        if let Some(props) = self.schema.get("properties").and_then(Value::as_object) {
118            for (name, subschema) in props {
119                if let (Some(actual), Some(ty)) = (
120                    value.get(name),
121                    subschema.get("type").and_then(Value::as_str),
122                ) && !type_ok(actual, ty)
123                {
124                    return Some(format!("property {name:?} is not of type {ty}"));
125                }
126            }
127        }
128        None
129    }
130}
131
132#[async_trait]
133impl Gate for SchemaGate {
134    fn id(&self) -> &str {
135        &self.id
136    }
137    async fn evaluate(&self, _req: &ModelRequest, resp: &ModelResponse) -> GateResult {
138        let Ok(value) = serde_json::from_str::<serde_json::Value>(resp.text.trim()) else {
139            let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
140            r.reason = Some("candidate is not valid JSON".to_owned());
141            return r;
142        };
143        match self.violation(&value) {
144            None => GateResult::deterministic(self.id(), Verdict::Pass, 0),
145            Some(reason) => {
146                let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
147                r.reason = Some(reason);
148                r
149            }
150        }
151    }
152}
153
154/// Rolling per-gate error budget (§7.2, §8.3.4). Tracks the last `window` outcomes; once the
155/// error (abstain) fraction over a full window exceeds `max_error_rate`, the gate is
156/// auto-disabled and an alarm is logged. A disabled gate is skipped by the runner (its verdict
157/// stops counting) rather than silently failing open or closed.
158#[derive(Debug)]
159pub struct GateHealth {
160    window: usize,
161    max_error_rate: f64,
162    outcomes: Mutex<VecDeque<bool>>, // true = error (abstain), false = ok
163    disabled: std::sync::atomic::AtomicBool,
164}
165
166impl GateHealth {
167    /// Create a health tracker. `max_error_rate` is the abstain fraction (over a full `window`)
168    /// beyond which the gate auto-disables.
169    #[must_use]
170    pub fn new(window: usize, max_error_rate: f64) -> Self {
171        Self {
172            window: window.max(1),
173            max_error_rate,
174            outcomes: Mutex::new(VecDeque::new()),
175            disabled: std::sync::atomic::AtomicBool::new(false),
176        }
177    }
178
179    /// Whether the gate is currently enabled (not auto-disabled).
180    #[must_use]
181    pub fn is_enabled(&self) -> bool {
182        !self.disabled.load(std::sync::atomic::Ordering::Relaxed)
183    }
184
185    /// Record one outcome (`errored` = the gate abstained/crashed) and re-evaluate the budget.
186    pub fn record(&self, gate_id: &str, errored: bool) {
187        // ponytail: a single global lock per gate-health; fine at proxy request rates. Shard by
188        // gate if a hot gate's lock ever shows up in a profile.
189        let Ok(mut q) = self.outcomes.lock() else {
190            return; // poisoned lock: skip accounting rather than panic on the request path
191        };
192        q.push_back(errored);
193        while q.len() > self.window {
194            q.pop_front();
195        }
196        if q.len() == self.window {
197            let errors = q.iter().filter(|e| **e).count();
198            let rate = errors as f64 / self.window as f64;
199            if rate > self.max_error_rate && self.is_enabled() {
200                self.disabled
201                    .store(true, std::sync::atomic::Ordering::Relaxed);
202                tracing::error!(
203                    gate = %gate_id,
204                    error_rate = rate,
205                    "gate exceeded its error budget — auto-disabled (ALARM)"
206                );
207            }
208        }
209    }
210}
211
212/// Per-`(tenant, gate)` error budgets for a running proxy (app-level, shared across requests;
213/// ADR 0004 §D6). Budgets (window + max abstain fraction) are registered per gate id at startup;
214/// the actual rolling-window accounting is a separate [`GateHealth`] per `(tenant, gate)` pair, so
215/// one tenant tripping a gate's budget auto-disables it only for that tenant, not globally. With
216/// auth off every request carries the tenant id `"default"`, so there is exactly one bucket per
217/// gate and behavior is unchanged from the pre-D6 global registry.
218///
219/// Unregistered gates default to enabled with no accounting (a gate the operator didn't register
220/// a budget for is simply never auto-disabled).
221#[derive(Debug, Default)]
222pub struct GateHealthRegistry {
223    budgets: std::collections::HashMap<String, (usize, f64)>,
224    state: Mutex<std::collections::HashMap<(String, String), GateHealth>>,
225}
226
227impl GateHealthRegistry {
228    /// Empty registry — every gate enabled, no accounting.
229    #[must_use]
230    pub fn new() -> Self {
231        Self::default()
232    }
233
234    /// Register an error budget for `gate_id` (window size + max abstain fraction).
235    #[must_use]
236    pub fn with_budget(
237        mut self,
238        gate_id: impl Into<String>,
239        window: usize,
240        max_error_rate: f64,
241    ) -> Self {
242        self.budgets
243            .insert(gate_id.into(), (window, max_error_rate));
244        self
245    }
246
247    /// Whether `gate_id` is currently enabled for `tenant` (unregistered gates are always
248    /// enabled; a poisoned accounting lock fails open rather than blocking every request).
249    #[must_use]
250    pub fn enabled(&self, tenant: &str, gate_id: &str) -> bool {
251        let Some(&(window, max_error_rate)) = self.budgets.get(gate_id) else {
252            return true;
253        };
254        let Ok(mut state) = self.state.lock() else {
255            return true;
256        };
257        state
258            .entry((tenant.to_owned(), gate_id.to_owned()))
259            .or_insert_with(|| GateHealth::new(window, max_error_rate))
260            .is_enabled()
261    }
262
263    /// Record one outcome for `(tenant, gate_id)` (`errored` = abstained/crashed). No-op if the
264    /// gate has no registered budget, or if the accounting lock is poisoned.
265    pub fn record(&self, tenant: &str, gate_id: &str, errored: bool) {
266        let Some(&(window, max_error_rate)) = self.budgets.get(gate_id) else {
267            return;
268        };
269        let Ok(mut state) = self.state.lock() else {
270            return;
271        };
272        state
273            .entry((tenant.to_owned(), gate_id.to_owned()))
274            .or_insert_with(|| GateHealth::new(window, max_error_rate))
275            .record(gate_id, errored);
276    }
277}
278
279/// Wraps any gate to make its abstains block serving (`on_abstain = "fail_closed"`, §7.2).
280/// Pure delegation except [`Gate::abstain_fails_closed`]; the underlying gate's verdicts —
281/// including the abstain itself — are recorded unchanged, so the receipt stays honest.
282#[derive(Debug)]
283struct FailClosed(Box<dyn Gate>);
284
285#[async_trait]
286impl Gate for FailClosed {
287    fn id(&self) -> &str {
288        self.0.id()
289    }
290    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
291        self.0.evaluate(req, resp).await
292    }
293    fn abstain_fails_closed(&self) -> bool {
294        true
295    }
296}
297
298/// Resolve a route's gate ids into runnable gates. Built-in ids (`non-empty`, `json-valid`) map to
299/// inline gates; any other id is looked up among the config's `[[gate]]` definitions and built as a
300/// [`SubprocessGate`] (`cmd`, SPEC §8.1), a [`JudgeGate`] (`judge`, §8.3), a [`ConsistencyGate`]
301/// (`consistency`), a [`SchemaGate`] (`schema`), or a [`DecisionGate`] (`decision`, TypeSafe's Jev
302/// — **unmeasured** precision/recall). Model-backed gates (judge/consistency) need a provider
303/// (from `registry`), the caller's credentials (`auth`, BYOK), and `prices` so their sample-call
304/// cost lands on the receipt; a decision gate needs its own API key, read from `api_key_env` via
305/// `http` (the shared client). An id that is neither built-in nor defined — a model gate whose
306/// provider isn't registered — or a decision gate whose API key env var is unset — is skipped
307/// with a warning rather than failing the request. A def with `on_abstain = "fail_closed"` is
308/// wrapped so its abstains block serving.
309#[must_use]
310pub fn resolve_gates(
311    names: &[String],
312    defs: &[GateDef],
313    registry: &ProviderRegistry,
314    auth: &Auth,
315    prices: &PriceTable,
316    http: &reqwest::Client,
317) -> Vec<Box<dyn Gate>> {
318    let mut gates: Vec<Box<dyn Gate>> = Vec::new();
319    let mut push = |gate: Box<dyn Gate>, def: Option<&GateDef>| {
320        if def.is_some_and(|d| d.on_abstain == AbstainPolicy::FailClosed) {
321            gates.push(Box::new(FailClosed(gate)));
322        } else {
323            gates.push(gate);
324        }
325    };
326    for name in names {
327        match name.as_str() {
328            "non-empty" => push(Box::new(NonEmptyGate), None),
329            "json-valid" => push(Box::new(JsonValidGate), None),
330            other => match defs.iter().find(|d| d.id == other) {
331                Some(def) if def.judge.is_some() => {
332                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
333                    if let Some(judge) = def.judge.as_ref() {
334                        let provider_id = judge.model.split('/').next().unwrap_or_default();
335                        match registry.get(provider_id) {
336                            Some(provider) => push(
337                                Box::new(JudgeGate::new(
338                                    def.id.clone(),
339                                    provider,
340                                    judge.model.clone(),
341                                    auth.clone(),
342                                    judge.threshold,
343                                    judge.rubric.clone().unwrap_or_default(),
344                                    prices.clone(),
345                                )),
346                                Some(def),
347                            ),
348                            None => tracing::warn!(
349                                gate = %other, provider = %provider_id,
350                                "judge gate provider not registered — skipped"
351                            ),
352                        }
353                    }
354                }
355                Some(def) if def.consistency.is_some() => {
356                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
357                    if let Some(cons) = def.consistency.as_ref() {
358                        let provider_id = cons.model.split('/').next().unwrap_or_default();
359                        match registry.get(provider_id) {
360                            Some(provider) => push(
361                                Box::new(ConsistencyGate::new(
362                                    def.id.clone(),
363                                    provider,
364                                    cons.model.clone(),
365                                    auth.clone(),
366                                    cons.k,
367                                    cons.threshold,
368                                    prices.clone(),
369                                )),
370                                Some(def),
371                            ),
372                            None => tracing::warn!(
373                                gate = %other, provider = %provider_id,
374                                "consistency gate provider not registered — skipped"
375                            ),
376                        }
377                    }
378                }
379                Some(def) if def.schema.is_some() => {
380                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
381                    if let Some(schema) = def.schema.as_ref() {
382                        push(
383                            Box::new(SchemaGate::new(def.id.clone(), schema.clone())),
384                            Some(def),
385                        );
386                    }
387                }
388                Some(def) if def.decision.is_some() => {
389                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
390                    if let Some(decision) = def.decision.as_ref() {
391                        match std::env::var(&decision.api_key_env) {
392                            Ok(api_key) => push(
393                                Box::new(DecisionGate::new(
394                                    def.id.clone(),
395                                    http.clone(),
396                                    decision,
397                                    api_key,
398                                )),
399                                Some(def),
400                            ),
401                            Err(_) => tracing::warn!(
402                                gate = %other, env_var = %decision.api_key_env,
403                                "decision gate API key env var is unset — skipped"
404                            ),
405                        }
406                    }
407                }
408                Some(def) => {
409                    let Some((program, args)) = def.cmd.split_first() else {
410                        tracing::warn!(gate = %other, "configured gate has empty cmd — skipped");
411                        continue;
412                    };
413                    push(
414                        Box::new(SubprocessGate::new(
415                            def.id.clone(),
416                            program.clone(),
417                            args.to_vec(),
418                            Duration::from_millis(def.timeout_ms),
419                        )),
420                        Some(def),
421                    );
422                }
423                None => tracing::warn!(
424                    gate = %other,
425                    "unknown gate id — not a built-in and not defined in [[gate]]; skipped"
426                ),
427            },
428        }
429    }
430    gates
431}
432
433/// Aggregate per-gate verdicts into the attempt's overall verdict, honoring each gate's
434/// abstain policy (§7.2): `Fail` if any gate fails **or** a `fail_closed` gate abstains;
435/// otherwise `Pass`. An empty gate set passes. `fail_closed_ids` is the set of gate ids whose
436/// abstains block serving (from [`Gate::abstain_fails_closed`]); a fail-open gate's abstain
437/// never blocks (the historical behavior).
438#[must_use]
439pub fn aggregate_with_policy(
440    results: &[GateResult],
441    fail_closed_ids: &std::collections::HashSet<&str>,
442) -> Verdict {
443    let blocking = |r: &GateResult| {
444        r.verdict == Verdict::Fail
445            || (r.verdict == Verdict::Abstain && fail_closed_ids.contains(r.gate_id.as_str()))
446    };
447    if results.iter().any(blocking) {
448        Verdict::Fail
449    } else {
450        Verdict::Pass
451    }
452}
453
454/// Aggregate per-gate verdicts with every gate fail-open — `Fail` iff any gate fails.
455#[must_use]
456pub fn aggregate(results: &[GateResult]) -> Verdict {
457    aggregate_with_policy(results, &std::collections::HashSet::new())
458}
459
460#[cfg(test)]
461mod tests {
462    use super::*;
463    use serde_json::{Value, json};
464
465    fn resp(text: &str) -> ModelResponse {
466        ModelResponse {
467            model: "anthropic/claude-haiku-4-5".to_owned(),
468            text: text.to_owned(),
469            in_tokens: 1,
470            cache_write_tokens: 0,
471            cache_read_tokens: 0,
472            out_tokens: 1,
473            raw: Value::Null,
474        }
475    }
476
477    fn req() -> ModelRequest {
478        ModelRequest {
479            model: "anthropic/claude-haiku-4-5".to_owned(),
480            system: None,
481            messages: vec![],
482            max_tokens: 16,
483            tools: Value::Null,
484            raw: Value::Null,
485            cache_prefix: false,
486        }
487    }
488
489    #[tokio::test]
490    async fn non_empty_gate() {
491        assert_eq!(
492            NonEmptyGate.evaluate(&req(), &resp("hi")).await.verdict,
493            Verdict::Pass
494        );
495        assert_eq!(
496            NonEmptyGate.evaluate(&req(), &resp("   ")).await.verdict,
497            Verdict::Fail
498        );
499    }
500
501    #[tokio::test]
502    async fn json_valid_gate() {
503        assert_eq!(
504            JsonValidGate
505                .evaluate(&req(), &resp(r#"{"ok":true}"#))
506                .await
507                .verdict,
508            Verdict::Pass
509        );
510        assert_eq!(
511            JsonValidGate.evaluate(&req(), &resp("nope")).await.verdict,
512            Verdict::Fail
513        );
514    }
515
516    #[tokio::test]
517    async fn schema_gate_type_and_required() {
518        let g = SchemaGate::new(
519            "schema",
520            json!({
521                "type": "object",
522                "required": ["name", "age"],
523                "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }
524            }),
525        );
526        assert_eq!(
527            g.evaluate(&req(), &resp(r#"{"name":"a","age":3}"#))
528                .await
529                .verdict,
530            Verdict::Pass
531        );
532        // missing required
533        assert_eq!(
534            g.evaluate(&req(), &resp(r#"{"name":"a"}"#)).await.verdict,
535            Verdict::Fail
536        );
537        // wrong property type
538        assert_eq!(
539            g.evaluate(&req(), &resp(r#"{"name":"a","age":"x"}"#))
540                .await
541                .verdict,
542            Verdict::Fail
543        );
544        // wrong root type
545        assert_eq!(g.evaluate(&req(), &resp("[]")).await.verdict, Verdict::Fail);
546        // not even JSON
547        assert_eq!(
548            g.evaluate(&req(), &resp("plain text")).await.verdict,
549            Verdict::Fail
550        );
551    }
552
553    fn empty_registry() -> ProviderRegistry {
554        ProviderRegistry::new("http://localhost", "http://localhost")
555    }
556
557    #[test]
558    fn resolve_skips_unknown_and_keeps_known() {
559        let gates = resolve_gates(
560            &[
561                "non-empty".to_owned(),
562                "judge-diff".to_owned(),
563                "json-valid".to_owned(),
564            ],
565            &[],
566            &empty_registry(),
567            &Auth::default(),
568            &PriceTable::default(),
569            &reqwest::Client::new(),
570        );
571        let ids: Vec<_> = gates.iter().map(|g| g.id()).collect();
572        assert_eq!(ids, ["non-empty", "json-valid"]);
573    }
574
575    #[test]
576    fn resolve_builds_configured_subprocess_gate() {
577        // A gate id that isn't built-in resolves to a SubprocessGate when defined in `[[gate]]`.
578        let defs = vec![GateDef {
579            id: "my-tests".to_owned(),
580            cmd: vec!["true".to_owned()],
581            timeout_ms: 1000,
582            judge: None,
583            consistency: None,
584            schema: None,
585            decision: None,
586            on_abstain: AbstainPolicy::FailOpen,
587        }];
588        let gates = resolve_gates(
589            &["my-tests".to_owned(), "undefined".to_owned()],
590            &defs,
591            &empty_registry(),
592            &Auth::default(),
593            &PriceTable::default(),
594            &reqwest::Client::new(),
595        );
596        let ids: Vec<_> = gates.iter().map(|g| g.id()).collect();
597        assert_eq!(
598            ids,
599            ["my-tests"],
600            "configured id resolves; unknown id skipped"
601        );
602    }
603
604    #[tokio::test]
605    async fn configured_subprocess_gate_runs_end_to_end() {
606        // A user-defined gate that fails iff the candidate text contains "BAD" — proving the config
607        // → SubprocessGate → verdict path works over stdin, no hard-coded gate name.
608        let script = r#"c=$(cat); case "$c" in *BAD*) echo '{"verdict":"fail"}';; *) echo '{"verdict":"pass"}';; esac"#;
609        let defs = vec![GateDef {
610            id: "no-bad".to_owned(),
611            cmd: vec!["bash".to_owned(), "-c".to_owned(), script.to_owned()],
612            timeout_ms: 5000,
613            judge: None,
614            consistency: None,
615            schema: None,
616            decision: None,
617            on_abstain: AbstainPolicy::FailOpen,
618        }];
619        let gates = resolve_gates(
620            &["no-bad".to_owned()],
621            &defs,
622            &empty_registry(),
623            &Auth::default(),
624            &PriceTable::default(),
625            &reqwest::Client::new(),
626        );
627        assert_eq!(gates.len(), 1);
628        let good = gates[0].evaluate(&req(), &resp("all good")).await;
629        assert_eq!(good.verdict, Verdict::Pass);
630        let bad = gates[0].evaluate(&req(), &resp("this is BAD")).await;
631        assert_eq!(bad.verdict, Verdict::Fail);
632    }
633
634    #[test]
635    fn resolve_builds_configured_judge_gate() {
636        use crate::provider::{MockProvider, Provider};
637        use std::collections::HashMap;
638        use std::sync::Arc;
639
640        let defs = vec![GateDef {
641            id: "quality".to_owned(),
642            cmd: vec![],
643            timeout_ms: 30_000,
644            judge: Some(firstpass_core::JudgeDef {
645                model: "anthropic/judge".to_owned(),
646                threshold: 0.7,
647                rubric: None,
648            }),
649            consistency: None,
650            schema: None,
651            decision: None,
652            on_abstain: AbstainPolicy::FailOpen,
653        }];
654
655        // Registry that serves `anthropic` → the judge gate is built.
656        let mut map: HashMap<String, Arc<dyn Provider>> = HashMap::new();
657        map.insert(
658            "anthropic".to_owned(),
659            Arc::new(MockProvider::new("anthropic", HashMap::new())),
660        );
661        let gates = resolve_gates(
662            &["quality".to_owned()],
663            &defs,
664            &ProviderRegistry::from_map(map),
665            &Auth::default(),
666            &PriceTable::default(),
667            &reqwest::Client::new(),
668        );
669        assert_eq!(
670            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
671            ["quality"]
672        );
673
674        // Registry without that provider → skipped, not a hard failure.
675        let skipped = resolve_gates(
676            &["quality".to_owned()],
677            &defs,
678            &ProviderRegistry::from_map(HashMap::new()),
679            &Auth::default(),
680            &PriceTable::default(),
681            &reqwest::Client::new(),
682        );
683        assert!(
684            skipped.is_empty(),
685            "judge with no registered provider is skipped"
686        );
687    }
688
689    #[test]
690    fn resolve_builds_configured_decision_gate() {
691        // No unsafe env::set_var (forbidden workspace-wide, and unsound in edition 2024): reuse
692        // `PATH`, guaranteed set in any test process, as a stand-in "the key env var is present"
693        // — resolve_gates only checks presence, never the value's shape. Mirrors the same trick
694        // already used in `provider.rs`'s tests.
695        let def = |api_key_env: &str| GateDef {
696            id: "verify".to_owned(),
697            cmd: vec![],
698            timeout_ms: 30_000,
699            judge: None,
700            consistency: None,
701            schema: None,
702            decision: Some(firstpass_core::DecisionDef {
703                provider: "typesafe".to_owned(),
704                model: "jev-latest".to_owned(),
705                api_key_env: api_key_env.to_owned(),
706                base_url: "https://api.typesafe.ai".to_owned(),
707                timeout_ms: 1_000,
708                threshold: 0.5,
709                instructions: None,
710            }),
711            on_abstain: AbstainPolicy::FailOpen,
712        };
713
714        let gates = resolve_gates(
715            &["verify".to_owned()],
716            &[def("PATH")],
717            &empty_registry(),
718            &Auth::default(),
719            &PriceTable::default(),
720            &reqwest::Client::new(),
721        );
722        assert_eq!(
723            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
724            ["verify"],
725            "decision gate resolves when its API key env var is set"
726        );
727
728        let gates = resolve_gates(
729            &["verify".to_owned()],
730            &[def("FIRSTPASS_TEST_DEFINITELY_UNSET_DECISION_KEY_XYZ")],
731            &empty_registry(),
732            &Auth::default(),
733            &PriceTable::default(),
734            &reqwest::Client::new(),
735        );
736        assert!(
737            gates.is_empty(),
738            "decision gate with an unset API key env var is skipped, not a hard failure"
739        );
740    }
741
742    #[test]
743    fn resolve_builds_configured_consistency_gate() {
744        use crate::provider::{MockProvider, Provider};
745        use std::collections::HashMap;
746        use std::sync::Arc;
747
748        let defs = vec![GateDef {
749            id: "uncertainty".to_owned(),
750            cmd: vec![],
751            timeout_ms: 30_000,
752            judge: None,
753            consistency: Some(firstpass_core::ConsistencyDef {
754                model: "anthropic/claude-haiku-4-5".to_owned(),
755                k: 3,
756                threshold: 0.6,
757            }),
758            schema: None,
759            decision: None,
760            on_abstain: AbstainPolicy::FailOpen,
761        }];
762
763        // Registry that serves `anthropic` → the consistency gate is built.
764        let mut map: HashMap<String, Arc<dyn Provider>> = HashMap::new();
765        map.insert(
766            "anthropic".to_owned(),
767            Arc::new(MockProvider::new("anthropic", HashMap::new())),
768        );
769        let gates = resolve_gates(
770            &["uncertainty".to_owned()],
771            &defs,
772            &ProviderRegistry::from_map(map),
773            &Auth::default(),
774            &PriceTable::default(),
775            &reqwest::Client::new(),
776        );
777        assert_eq!(
778            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
779            ["uncertainty"]
780        );
781
782        // Registry without the provider → skipped, not a hard failure.
783        let skipped = resolve_gates(
784            &["uncertainty".to_owned()],
785            &defs,
786            &ProviderRegistry::from_map(HashMap::new()),
787            &Auth::default(),
788            &PriceTable::default(),
789            &reqwest::Client::new(),
790        );
791        assert!(
792            skipped.is_empty(),
793            "consistency gate with no registered provider is skipped"
794        );
795    }
796
797    #[test]
798    fn aggregate_semantics() {
799        let pass = GateResult::deterministic("a", Verdict::Pass, 0);
800        let fail = GateResult::deterministic("b", Verdict::Fail, 0);
801        let abstain = GateResult::abstain("c", "x", 0);
802        assert_eq!(aggregate(&[]), Verdict::Pass);
803        assert_eq!(aggregate(std::slice::from_ref(&pass)), Verdict::Pass);
804        assert_eq!(aggregate(&[pass.clone(), fail]), Verdict::Fail);
805        assert_eq!(aggregate(&[pass, abstain]), Verdict::Pass);
806    }
807
808    #[test]
809    fn error_budget_auto_disables_past_threshold() {
810        let h = GateHealth::new(10, 0.5); // disable when >50% of the last 10 error
811        // Window fills to exactly 5 errors / 10 = 50% — NOT above threshold, still enabled.
812        for _ in 0..5 {
813            h.record("g", true);
814        }
815        for _ in 0..5 {
816            h.record("g", false);
817        }
818        assert!(h.is_enabled(), "50% is at, not above, the budget");
819        // Flood errors: the window slides until errors exceed 50% -> auto-disabled.
820        for _ in 0..6 {
821            h.record("g", true);
822        }
823        assert!(
824            !h.is_enabled(),
825            "gate should auto-disable once error rate exceeds budget"
826        );
827    }
828
829    #[test]
830    fn healthy_gate_stays_enabled() {
831        let h = GateHealth::new(20, 0.5);
832        for _ in 0..100 {
833            h.record("g", false);
834        }
835        assert!(h.is_enabled());
836    }
837
838    #[test]
839    fn gate_health_registry_default_tenant_is_a_single_bucket() {
840        // With auth off (single-operator), every request uses the same "default" tenant, so this
841        // is exactly the pre-D6 global-registry behavior.
842        let registry = GateHealthRegistry::new().with_budget("g", 4, 0.5);
843        for _ in 0..4 {
844            registry.record("default", "g", true);
845        }
846        assert!(!registry.enabled("default", "g"));
847    }
848
849    #[test]
850    fn gate_health_registry_scopes_budget_per_tenant() {
851        // ADR 0004 §D6: tenant A tripping the budget must not affect tenant B on the same gate.
852        let registry = GateHealthRegistry::new().with_budget("g", 4, 0.5);
853        for _ in 0..4 {
854            registry.record("tenant-a", "g", true);
855        }
856        assert!(!registry.enabled("tenant-a", "g"), "A should be disabled");
857        assert!(registry.enabled("tenant-b", "g"), "B must be unaffected");
858    }
859
860    #[test]
861    fn gate_health_registry_unregistered_gate_always_enabled() {
862        let registry = GateHealthRegistry::new();
863        assert!(registry.enabled("tenant-a", "unknown-gate"));
864        registry.record("tenant-a", "unknown-gate", true); // no-op, must not panic
865        assert!(registry.enabled("tenant-a", "unknown-gate"));
866    }
867
868    #[tokio::test]
869    async fn resolve_builds_configured_schema_gate() {
870        let defs = vec![GateDef {
871            id: "extract-shape".to_owned(),
872            cmd: vec![],
873            timeout_ms: 30_000,
874            judge: None,
875            consistency: None,
876            schema: Some(json!({"type": "object", "required": ["name"]})),
877            decision: None,
878            on_abstain: firstpass_core::AbstainPolicy::FailOpen,
879        }];
880        let gates = resolve_gates(
881            &["extract-shape".to_owned()],
882            &defs,
883            &empty_registry(),
884            &Auth::default(),
885            &PriceTable::default(),
886            &reqwest::Client::new(),
887        );
888        assert_eq!(
889            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
890            ["extract-shape"],
891            "a [[gate]] def with `schema` resolves to a runnable SchemaGate"
892        );
893        let ok = gates[0].evaluate(&req(), &resp(r#"{"name":"a"}"#)).await;
894        assert_eq!(ok.verdict, Verdict::Pass);
895        let missing = gates[0].evaluate(&req(), &resp(r#"{}"#)).await;
896        assert_eq!(missing.verdict, Verdict::Fail);
897    }
898
899    #[test]
900    fn resolve_wraps_fail_closed_gate() {
901        let mk = |on_abstain| {
902            vec![GateDef {
903                id: "tests".to_owned(),
904                cmd: vec!["true".to_owned()],
905                timeout_ms: 1000,
906                judge: None,
907                consistency: None,
908                schema: None,
909                decision: None,
910                on_abstain,
911            }]
912        };
913        let open = resolve_gates(
914            &["tests".to_owned()],
915            &mk(firstpass_core::AbstainPolicy::FailOpen),
916            &empty_registry(),
917            &Auth::default(),
918            &PriceTable::default(),
919            &reqwest::Client::new(),
920        );
921        assert!(!open[0].abstain_fails_closed(), "default stays fail-open");
922        let closed = resolve_gates(
923            &["tests".to_owned()],
924            &mk(firstpass_core::AbstainPolicy::FailClosed),
925            &empty_registry(),
926            &Auth::default(),
927            &PriceTable::default(),
928            &reqwest::Client::new(),
929        );
930        assert!(
931            closed[0].abstain_fails_closed(),
932            "on_abstain = fail_closed wraps the gate"
933        );
934        assert_eq!(closed[0].id(), "tests", "wrapper preserves the id");
935    }
936
937    #[test]
938    fn aggregate_with_policy_fail_closed_abstain_blocks() {
939        use std::collections::HashSet;
940        let pass = GateResult::deterministic("a", Verdict::Pass, 0);
941        let abstain = GateResult::abstain("c", "timeout", 0);
942        // Fail-open (empty set): abstain never blocks — historical behavior.
943        assert_eq!(
944            aggregate_with_policy(&[pass.clone(), abstain.clone()], &HashSet::new()),
945            Verdict::Pass
946        );
947        // Fail-closed: the same abstain blocks serving like a Fail.
948        let closed: HashSet<&str> = ["c"].into_iter().collect();
949        assert_eq!(
950            aggregate_with_policy(&[pass, abstain], &closed),
951            Verdict::Fail
952        );
953    }
954}