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/// True when the request's `tools` field is a non-empty array (Anthropic or OpenAI format).
38/// Used by inline gates to decide whether tool-call-only responses are valid for this request.
39fn request_has_declared_tools(req: &ModelRequest) -> bool {
40    req.tools.as_array().is_some_and(|a| !a.is_empty())
41}
42
43/// Fails an empty (whitespace-only) completion with no tool calls.
44/// Passes when the text is non-empty **or** the response contains at least one tool call AND
45/// the request declared tools — an undeclared tool call with empty text is a Fail.
46#[derive(Debug, Clone, Copy)]
47pub struct NonEmptyGate;
48
49#[async_trait]
50impl Gate for NonEmptyGate {
51    fn id(&self) -> &str {
52        "non-empty"
53    }
54    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
55        let verdict = if !resp.text.trim().is_empty() {
56            Verdict::Pass
57        } else if resp.has_tool_calls() && request_has_declared_tools(req) {
58            // Tool-call-only turn with declared tools: the tool call IS the non-empty output.
59            Verdict::Pass
60        } else {
61            Verdict::Fail
62        };
63        GateResult::deterministic(self.id(), verdict, 0)
64    }
65}
66
67/// Passes only if the completion parses as JSON. Useful for structured-output routes.
68///
69/// **Passes** (not Abstains) when the response has tool calls AND the request declared tools:
70/// there is no text payload to validate (the JSON answer IS the tool call). Abstain would count
71/// against GateHealth (auto-disabling the gate above 25% abstain rate) on every agent turn.
72///
73/// **Note**: preamble text alongside tool calls (tools declared) also passes — the text is not
74/// the structured JSON answer in that case. Use `tool-args-valid` to validate tool call args.
75#[derive(Debug, Clone, Copy)]
76pub struct JsonValidGate;
77
78#[async_trait]
79impl Gate for JsonValidGate {
80    fn id(&self) -> &str {
81        "json-valid"
82    }
83    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
84        let has_tools = request_has_declared_tools(req);
85        // Tool calls present AND tools were declared: the text (preamble or absent) is not the
86        // JSON answer — the tool call IS the structured output.
87        if resp.has_tool_calls() && has_tools {
88            return GateResult::deterministic(self.id(), Verdict::Pass, 0);
89        }
90        let ok = serde_json::from_str::<serde_json::Value>(resp.text.trim()).is_ok();
91        GateResult::deterministic(self.id(), if ok { Verdict::Pass } else { Verdict::Fail }, 0)
92    }
93}
94
95/// Recursive minimal JSON-Schema validator for the subset tool schemas use.
96///
97/// Supported keywords: `type` (string or array of strings, incl. `["x","null"]` for nullable),
98/// `required`, `properties` (recursive), `items` (recursive, for arrays), `enum`,
99/// `additionalProperties: false`. Unknown keywords are silently ignored — don't fail on them.
100///
101/// Pure function so it is used by both [`SchemaGate`] and [`validate_tool_args_against_tools`].
102fn schema_violation(
103    value: &serde_json::Value,
104    schema: &serde_json::Value,
105    path: &str,
106) -> Option<String> {
107    use serde_json::Value;
108
109    /// True when `v` matches a single JSON Schema type name.
110    fn type_matches(v: &Value, ty: &str) -> bool {
111        match ty {
112            "object" => v.is_object(),
113            "array" => v.is_array(),
114            "string" => v.is_string(),
115            // "integer" is strict: floats with fractional parts are not integers.
116            "integer" => v.is_i64() || v.is_u64() || v.as_f64().is_some_and(|f| f.fract() == 0.0),
117            "number" => v.is_number(),
118            "boolean" => v.is_boolean(),
119            "null" => v.is_null(),
120            _ => true, // unknown type keyword: don't fail on it
121        }
122    }
123
124    // `type` keyword — may be a string or an array of strings (e.g. ["string","null"]).
125    if let Some(type_kw) = schema.get("type") {
126        let ok = match type_kw {
127            Value::String(ty) => type_matches(value, ty),
128            Value::Array(types) => types
129                .iter()
130                .filter_map(Value::as_str)
131                .any(|ty| type_matches(value, ty)),
132            _ => true,
133        };
134        if !ok {
135            return Some(format!("{path} has wrong type"));
136        }
137    }
138
139    // `enum` keyword — value must be one of the listed literals.
140    if let Some(Value::Array(variants)) = schema.get("enum")
141        && !variants.contains(value)
142    {
143        return Some(format!("{path} is not one of the allowed enum values"));
144    }
145
146    if let Some(obj) = value.as_object() {
147        // `required` keyword — every listed field must be present.
148        if let Some(Value::Array(req)) = schema.get("required") {
149            for field in req.iter().filter_map(Value::as_str) {
150                if !obj.contains_key(field) {
151                    return Some(format!("{path}.{field:?} is required but missing"));
152                }
153            }
154        }
155
156        // `additionalProperties: false` — no keys outside `properties`.
157        let ap_false = schema.get("additionalProperties").and_then(Value::as_bool) == Some(false);
158        let defined_props: std::collections::HashSet<&str> = schema
159            .get("properties")
160            .and_then(Value::as_object)
161            .map(|p| p.keys().map(String::as_str).collect())
162            .unwrap_or_default();
163        if ap_false {
164            for key in obj.keys() {
165                if !defined_props.contains(key.as_str()) {
166                    return Some(format!(
167                        "{path}.{key:?} is an additional property not allowed by the schema"
168                    ));
169                }
170            }
171        } else if let Some(extra_schema) =
172            schema.get("additionalProperties").filter(|v| v.is_object())
173        {
174            // `additionalProperties: {schema}` — keys outside `properties` must match it.
175            for (key, child) in obj {
176                if !defined_props.contains(key.as_str())
177                    && let Some(v) = schema_violation(child, extra_schema, &format!("{path}.{key}"))
178                {
179                    return Some(v);
180                }
181            }
182        }
183
184        // `properties` keyword — recurse into each present property.
185        if let Some(props) = schema.get("properties").and_then(Value::as_object) {
186            for (name, subschema) in props {
187                if let Some(child) = obj.get(name) {
188                    let child_path = format!("{path}.{name}");
189                    if let Some(v) = schema_violation(child, subschema, &child_path) {
190                        return Some(v);
191                    }
192                }
193            }
194        }
195    }
196
197    // `items` keyword — recurse into each array element.
198    if let (Some(arr), Some(items_schema)) = (value.as_array(), schema.get("items")) {
199        for (i, elem) in arr.iter().enumerate() {
200            let child_path = format!("{path}[{i}]");
201            if let Some(v) = schema_violation(elem, items_schema, &child_path) {
202                return Some(v);
203            }
204        }
205    }
206
207    None
208}
209
210/// Validates the candidate (parsed as JSON) against a minimal JSON-Schema subset.
211///
212/// Supports: `type` (string or `["x","null"]`), `required`, `properties` (recursive),
213/// `items` (recursive), `enum`, `additionalProperties: false`. Unknown keywords ignored.
214///
215// ponytail: not full JSON Schema draft 2020-12 — no `$ref`, `if/then/else`, `anyOf`, `oneOf`.
216// Swap for the `jsonschema` crate if those are needed.
217#[derive(Debug, Clone)]
218pub struct SchemaGate {
219    id: String,
220    schema: serde_json::Value,
221}
222
223impl SchemaGate {
224    /// Build a schema gate from a JSON Schema value, under the id a route references it by.
225    #[must_use]
226    pub fn new(id: impl Into<String>, schema: serde_json::Value) -> Self {
227        Self {
228            id: id.into(),
229            schema,
230        }
231    }
232
233    /// Check `value` against the schema; returns the first violation, if any.
234    pub(crate) fn violation(&self, value: &serde_json::Value) -> Option<String> {
235        schema_violation(value, &self.schema, "root")
236    }
237}
238
239#[async_trait]
240impl Gate for SchemaGate {
241    fn id(&self) -> &str {
242        &self.id
243    }
244    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
245        let has_tools = request_has_declared_tools(req);
246        // Tool calls with declared tools: text (if any) is preamble, not the JSON answer.
247        // Pass without schema-checking it — use tool-args-valid to validate tool call args.
248        if resp.has_tool_calls() && has_tools {
249            return GateResult::deterministic(self.id(), Verdict::Pass, 0);
250        }
251        let Ok(value) = serde_json::from_str::<serde_json::Value>(resp.text.trim()) else {
252            let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
253            r.reason = Some("candidate is not valid JSON".to_owned());
254            return r;
255        };
256        match self.violation(&value) {
257            None => GateResult::deterministic(self.id(), Verdict::Pass, 0),
258            Some(reason) => {
259                let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
260                r.reason = Some(reason);
261                r
262            }
263        }
264    }
265}
266
267/// Extract `(tool_name, args_json_string)` pairs from a provider raw response.
268/// Handles Anthropic `content[*].type == "tool_use"` (input is a JSON object)
269/// and OpenAI `choices[0].message.tool_calls[*].function` (arguments is a JSON string).
270///
271/// Malformed entries (missing `name` in Anthropic, missing `function` in OpenAI) are recorded
272/// with an empty name so `ToolArgsValidGate` fails the hallucinated-tool check rather than
273/// silently skipping the entry and treating the call list as empty.
274fn extract_response_tool_calls(raw: &serde_json::Value) -> Vec<(String, String)> {
275    let mut out = Vec::new();
276    // Anthropic format
277    if let Some(blocks) = raw.get("content").and_then(serde_json::Value::as_array) {
278        for b in blocks {
279            if b.get("type").and_then(serde_json::Value::as_str) == Some("tool_use") {
280                // Missing `name` → empty string triggers hallucinated-tool Fail downstream.
281                let name = b
282                    .get("name")
283                    .and_then(serde_json::Value::as_str)
284                    .unwrap_or("")
285                    .to_owned();
286                // Missing `input` is malformed: an empty string fails the JSON parse, so the call
287                // fails the gate instead of passing as fabricated `{}` args.
288                let args = b
289                    .get("input")
290                    .map_or_else(String::new, std::string::ToString::to_string);
291                out.push((name, args));
292            }
293        }
294        return out;
295    }
296    // OpenAI format
297    if let Some(calls) = raw
298        .pointer("/choices/0/message/tool_calls")
299        .and_then(serde_json::Value::as_array)
300    {
301        for call in calls {
302            // Missing `function` → record entry with empty name to trigger Fail, not silent skip.
303            let (name, args) = if let Some(func) = call.get("function") {
304                (
305                    func.get("name")
306                        .and_then(serde_json::Value::as_str)
307                        .unwrap_or("")
308                        .to_owned(),
309                    // Missing or non-string `arguments` is malformed: an empty string fails the
310                    // JSON parse below, so the call fails the gate instead of passing as `{}`.
311                    func.get("arguments")
312                        .and_then(serde_json::Value::as_str)
313                        .unwrap_or("")
314                        .to_owned(),
315                )
316            } else {
317                (String::new(), String::new())
318            };
319            out.push((name, args));
320        }
321    }
322    out
323}
324
325/// Validate `tool_args` against a tool's `input_schema` (Anthropic) or `parameters` (OpenAI)
326/// using the recursive [`schema_violation`] validator. Returns `None` on success, or the
327/// first violation message.
328fn validate_tool_args_against_tools(
329    name: &str,
330    args: &serde_json::Value,
331    tools: &serde_json::Value,
332) -> Option<String> {
333    let arr = tools.as_array()?;
334    for tool in arr {
335        // Anthropic format: {"name": "...", "input_schema": {...}}
336        if let (Some(n), Some(schema)) = (
337            tool.get("name").and_then(serde_json::Value::as_str),
338            tool.get("input_schema"),
339        ) && n == name
340        {
341            return schema_violation(args, schema, "args");
342        }
343        // OpenAI Responses format: {"type":"function","name":"...","parameters":{...}}.
344        // `tool_name_is_known` already accepts this shape by its top-level `name`, so without this
345        // branch a known tool would skip schema validation entirely — fail-open.
346        if let (Some(n), Some(schema)) = (
347            tool.get("name").and_then(serde_json::Value::as_str),
348            tool.get("parameters"),
349        ) && n == name
350        {
351            return schema_violation(args, schema, "args");
352        }
353        // OpenAI format: {"type":"function","function":{"name":"...","parameters":{...}}}
354        if let Some(func) = tool.get("function")
355            && let (Some(n), Some(schema)) = (
356                func.get("name").and_then(serde_json::Value::as_str),
357                func.get("parameters"),
358            )
359            && n == name
360        {
361            return schema_violation(args, schema, "args");
362        }
363    }
364    None // unknown tool: no schema to validate against — don't fail
365}
366
367/// True if `name` appears in the request's `tools` array (Anthropic or OpenAI format).
368fn tool_name_is_known(name: &str, tools: &serde_json::Value) -> bool {
369    let Some(arr) = tools.as_array() else {
370        return false;
371    };
372    for tool in arr {
373        // Anthropic: {"name": "...", "input_schema": {...}}
374        if tool.get("name").and_then(serde_json::Value::as_str) == Some(name) {
375            return true;
376        }
377        // OpenAI: {"type": "function", "function": {"name": "...", "parameters": {...}}}
378        if tool
379            .pointer("/function/name")
380            .and_then(serde_json::Value::as_str)
381            == Some(name)
382        {
383            return true;
384        }
385    }
386    false
387}
388
389/// Validates every tool call's arguments against the request's tool schema.
390///
391/// - **Pass**: the response contains no tool calls (not applicable — counts as satisfied,
392///   not as an error), OR all tool calls have valid JSON arguments that satisfy their schema.
393/// - **Fail**: the response calls a tool that was not declared in the request (hallucinated
394///   tool), the request declares no tools but the response contains tool calls, any tool
395///   call's arguments are not valid JSON, or any call violates its schema.
396///
397/// Pass (not Abstain) on no-tool-call turns so GateHealth does not count this as an error
398/// and auto-disable the gate on agent traffic where most turns have no tool calls.
399///
400/// Registered as the built-in gate id `tool-args-valid`. See AGENTS.md gotchas.
401#[derive(Debug, Clone, Copy)]
402pub struct ToolArgsValidGate;
403
404#[async_trait]
405impl Gate for ToolArgsValidGate {
406    fn id(&self) -> &str {
407        "tool-args-valid"
408    }
409    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
410        let calls = extract_response_tool_calls(&resp.raw);
411        if calls.is_empty() {
412            // No tool calls — trivially satisfied. Pass (not Abstain: see doc comment).
413            return GateResult::deterministic(self.id(), Verdict::Pass, 0);
414        }
415
416        // Response has tool calls. Check that the request actually declared any tools.
417        let has_declared_tools = req.tools.as_array().is_some_and(|a| !a.is_empty());
418        if !has_declared_tools {
419            let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
420            r.reason = Some(
421                "response contains tool calls but request declared no tools (hallucinated)"
422                    .to_owned(),
423            );
424            return r;
425        }
426
427        for (name, args_str) in &calls {
428            // Fail on any call to a tool not declared in the request.
429            if !tool_name_is_known(name, &req.tools) {
430                let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
431                r.reason = Some(format!(
432                    "tool call {name:?}: tool not declared in request (hallucinated)"
433                ));
434                return r;
435            }
436            let args = match serde_json::from_str::<serde_json::Value>(args_str) {
437                Ok(v) => v,
438                Err(_) => {
439                    let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
440                    r.reason = Some(format!("tool call {name:?}: arguments is not valid JSON"));
441                    return r;
442                }
443            };
444            if let Some(violation) = validate_tool_args_against_tools(name, &args, &req.tools) {
445                let mut r = GateResult::deterministic(self.id(), Verdict::Fail, 0);
446                r.reason = Some(format!("tool call {name:?}: {violation}"));
447                return r;
448            }
449        }
450        GateResult::deterministic(self.id(), Verdict::Pass, 0)
451    }
452}
453
454/// Rolling per-gate error budget (§7.2, §8.3.4). Tracks the last `window` outcomes; once the
455/// error (abstain) fraction over a full window exceeds `max_error_rate`, the gate is
456/// auto-disabled and an alarm is logged. A disabled gate is skipped by the runner (its verdict
457/// stops counting) rather than silently failing open or closed.
458#[derive(Debug)]
459pub struct GateHealth {
460    window: usize,
461    max_error_rate: f64,
462    outcomes: Mutex<VecDeque<bool>>, // true = error (abstain), false = ok
463    disabled: std::sync::atomic::AtomicBool,
464}
465
466impl GateHealth {
467    /// Create a health tracker. `max_error_rate` is the abstain fraction (over a full `window`)
468    /// beyond which the gate auto-disables.
469    #[must_use]
470    pub fn new(window: usize, max_error_rate: f64) -> Self {
471        Self {
472            window: window.max(1),
473            max_error_rate,
474            outcomes: Mutex::new(VecDeque::new()),
475            disabled: std::sync::atomic::AtomicBool::new(false),
476        }
477    }
478
479    /// Whether the gate is currently enabled (not auto-disabled).
480    #[must_use]
481    pub fn is_enabled(&self) -> bool {
482        !self.disabled.load(std::sync::atomic::Ordering::Relaxed)
483    }
484
485    /// Record one outcome (`errored` = the gate abstained/crashed) and re-evaluate the budget.
486    pub fn record(&self, gate_id: &str, errored: bool) {
487        // ponytail: a single global lock per gate-health; fine at proxy request rates. Shard by
488        // gate if a hot gate's lock ever shows up in a profile.
489        let Ok(mut q) = self.outcomes.lock() else {
490            return; // poisoned lock: skip accounting rather than panic on the request path
491        };
492        q.push_back(errored);
493        while q.len() > self.window {
494            q.pop_front();
495        }
496        if q.len() == self.window {
497            let errors = q.iter().filter(|e| **e).count();
498            let rate = errors as f64 / self.window as f64;
499            if rate > self.max_error_rate && self.is_enabled() {
500                self.disabled
501                    .store(true, std::sync::atomic::Ordering::Relaxed);
502                tracing::error!(
503                    gate = %gate_id,
504                    error_rate = rate,
505                    "gate exceeded its error budget — auto-disabled (ALARM)"
506                );
507            }
508        }
509    }
510}
511
512/// Per-`(tenant, gate)` error budgets for a running proxy (app-level, shared across requests;
513/// ADR 0004 §D6). Budgets (window + max abstain fraction) are registered per gate id at startup;
514/// the actual rolling-window accounting is a separate [`GateHealth`] per `(tenant, gate)` pair, so
515/// one tenant tripping a gate's budget auto-disables it only for that tenant, not globally. With
516/// auth off every request carries the tenant id `"default"`, so there is exactly one bucket per
517/// gate and behavior is unchanged from the pre-D6 global registry.
518///
519/// Unregistered gates default to enabled with no accounting (a gate the operator didn't register
520/// a budget for is simply never auto-disabled).
521#[derive(Debug, Default)]
522pub struct GateHealthRegistry {
523    budgets: std::collections::HashMap<String, (usize, f64)>,
524    state: Mutex<std::collections::HashMap<(String, String), GateHealth>>,
525}
526
527impl GateHealthRegistry {
528    /// Empty registry — every gate enabled, no accounting.
529    #[must_use]
530    pub fn new() -> Self {
531        Self::default()
532    }
533
534    /// Register an error budget for `gate_id` (window size + max abstain fraction).
535    #[must_use]
536    pub fn with_budget(
537        mut self,
538        gate_id: impl Into<String>,
539        window: usize,
540        max_error_rate: f64,
541    ) -> Self {
542        self.budgets
543            .insert(gate_id.into(), (window, max_error_rate));
544        self
545    }
546
547    /// Whether `gate_id` is currently enabled for `tenant` (unregistered gates are always
548    /// enabled; a poisoned accounting lock fails open rather than blocking every request).
549    #[must_use]
550    pub fn enabled(&self, tenant: &str, gate_id: &str) -> bool {
551        let Some(&(window, max_error_rate)) = self.budgets.get(gate_id) else {
552            return true;
553        };
554        let Ok(mut state) = self.state.lock() else {
555            return true;
556        };
557        state
558            .entry((tenant.to_owned(), gate_id.to_owned()))
559            .or_insert_with(|| GateHealth::new(window, max_error_rate))
560            .is_enabled()
561    }
562
563    /// Record one outcome for `(tenant, gate_id)` (`errored` = abstained/crashed). No-op if the
564    /// gate has no registered budget, or if the accounting lock is poisoned.
565    pub fn record(&self, tenant: &str, gate_id: &str, errored: bool) {
566        let Some(&(window, max_error_rate)) = self.budgets.get(gate_id) else {
567            return;
568        };
569        let Ok(mut state) = self.state.lock() else {
570            return;
571        };
572        state
573            .entry((tenant.to_owned(), gate_id.to_owned()))
574            .or_insert_with(|| GateHealth::new(window, max_error_rate))
575            .record(gate_id, errored);
576    }
577}
578
579/// Wraps any gate to make its abstains block serving (`on_abstain = "fail_closed"`, §7.2).
580/// Pure delegation except [`Gate::abstain_fails_closed`]; the underlying gate's verdicts —
581/// including the abstain itself — are recorded unchanged, so the receipt stays honest.
582#[derive(Debug)]
583struct FailClosed(Box<dyn Gate>);
584
585#[async_trait]
586impl Gate for FailClosed {
587    fn id(&self) -> &str {
588        self.0.id()
589    }
590    async fn evaluate(&self, req: &ModelRequest, resp: &ModelResponse) -> GateResult {
591        self.0.evaluate(req, resp).await
592    }
593    fn abstain_fails_closed(&self) -> bool {
594        true
595    }
596}
597
598/// Resolve a route's gate ids into runnable gates. Built-in ids (`non-empty`, `json-valid`) map to
599/// inline gates; any other id is looked up among the config's `[[gate]]` definitions and built as a
600/// [`SubprocessGate`] (`cmd`, SPEC §8.1), a [`JudgeGate`] (`judge`, §8.3), a [`ConsistencyGate`]
601/// (`consistency`), a [`SchemaGate`] (`schema`), or a [`DecisionGate`] (`decision`, TypeSafe's Jev
602/// — **unmeasured** precision/recall). Model-backed gates (judge/consistency) need a provider
603/// (from `registry`), the caller's credentials (`auth`, BYOK), and `prices` so their sample-call
604/// cost lands on the receipt; a decision gate needs its own API key, read from `api_key_env` via
605/// `http` (the shared client). An id that is neither built-in nor defined — a model gate whose
606/// provider isn't registered — or a decision gate whose API key env var is unset — is skipped
607/// with a warning rather than failing the request. A def with `on_abstain = "fail_closed"` is
608/// wrapped so its abstains block serving.
609#[must_use]
610pub fn resolve_gates(
611    names: &[String],
612    defs: &[GateDef],
613    registry: &ProviderRegistry,
614    auth: &Auth,
615    prices: &PriceTable,
616    http: &reqwest::Client,
617) -> Vec<Box<dyn Gate>> {
618    let mut gates: Vec<Box<dyn Gate>> = Vec::new();
619    let mut push = |gate: Box<dyn Gate>, def: Option<&GateDef>| {
620        if def.is_some_and(|d| d.on_abstain == AbstainPolicy::FailClosed) {
621            gates.push(Box::new(FailClosed(gate)));
622        } else {
623            gates.push(gate);
624        }
625    };
626    for name in names {
627        match name.as_str() {
628            "non-empty" => push(Box::new(NonEmptyGate), None),
629            "json-valid" => push(Box::new(JsonValidGate), None),
630            "tool-args-valid" => push(Box::new(ToolArgsValidGate), None),
631            other => match defs.iter().find(|d| d.id == other) {
632                Some(def) if def.judge.is_some() => {
633                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
634                    if let Some(judge) = def.judge.as_ref() {
635                        let provider_id = judge.model.split('/').next().unwrap_or_default();
636                        match registry.get(provider_id) {
637                            Some(provider) => push(
638                                Box::new(JudgeGate::new(
639                                    def.id.clone(),
640                                    provider,
641                                    judge.model.clone(),
642                                    auth.clone(),
643                                    judge.threshold,
644                                    judge.rubric.clone().unwrap_or_default(),
645                                    prices.clone(),
646                                )),
647                                Some(def),
648                            ),
649                            None => tracing::warn!(
650                                gate = %other, provider = %provider_id,
651                                "judge gate provider not registered — skipped"
652                            ),
653                        }
654                    }
655                }
656                Some(def) if def.consistency.is_some() => {
657                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
658                    if let Some(cons) = def.consistency.as_ref() {
659                        let provider_id = cons.model.split('/').next().unwrap_or_default();
660                        match registry.get(provider_id) {
661                            Some(provider) => push(
662                                Box::new(ConsistencyGate::new(
663                                    def.id.clone(),
664                                    provider,
665                                    cons.model.clone(),
666                                    auth.clone(),
667                                    cons.k,
668                                    cons.threshold,
669                                    prices.clone(),
670                                )),
671                                Some(def),
672                            ),
673                            None => tracing::warn!(
674                                gate = %other, provider = %provider_id,
675                                "consistency gate provider not registered — skipped"
676                            ),
677                        }
678                    }
679                }
680                Some(def) if def.schema.is_some() => {
681                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
682                    if let Some(schema) = def.schema.as_ref() {
683                        push(
684                            Box::new(SchemaGate::new(def.id.clone(), schema.clone())),
685                            Some(def),
686                        );
687                    }
688                }
689                Some(def) if def.decision.is_some() => {
690                    // `Config::parse` guarantees exactly one kind, so this `if let` always binds.
691                    if let Some(decision) = def.decision.as_ref() {
692                        match std::env::var(&decision.api_key_env) {
693                            Ok(api_key) => push(
694                                Box::new(DecisionGate::new(
695                                    def.id.clone(),
696                                    http.clone(),
697                                    decision,
698                                    api_key,
699                                )),
700                                Some(def),
701                            ),
702                            Err(_) => tracing::warn!(
703                                gate = %other, env_var = %decision.api_key_env,
704                                "decision gate API key env var is unset — skipped"
705                            ),
706                        }
707                    }
708                }
709                Some(def) => {
710                    let Some((program, args)) = def.cmd.split_first() else {
711                        tracing::warn!(gate = %other, "configured gate has empty cmd — skipped");
712                        continue;
713                    };
714                    push(
715                        Box::new(SubprocessGate::new(
716                            def.id.clone(),
717                            program.clone(),
718                            args.to_vec(),
719                            Duration::from_millis(def.timeout_ms),
720                        )),
721                        Some(def),
722                    );
723                }
724                None => tracing::warn!(
725                    gate = %other,
726                    "unknown gate id — not a built-in and not defined in [[gate]]; skipped"
727                ),
728            },
729        }
730    }
731    gates
732}
733
734/// Aggregate per-gate verdicts into the attempt's overall verdict, honoring each gate's
735/// abstain policy (§7.2): `Fail` if any gate fails **or** a `fail_closed` gate abstains;
736/// otherwise `Pass`. An empty gate set passes. `fail_closed_ids` is the set of gate ids whose
737/// abstains block serving (from [`Gate::abstain_fails_closed`]); a fail-open gate's abstain
738/// never blocks (the historical behavior).
739#[must_use]
740pub fn aggregate_with_policy(
741    results: &[GateResult],
742    fail_closed_ids: &std::collections::HashSet<&str>,
743) -> Verdict {
744    let blocking = |r: &GateResult| {
745        r.verdict == Verdict::Fail
746            || (r.verdict == Verdict::Abstain && fail_closed_ids.contains(r.gate_id.as_str()))
747    };
748    if results.iter().any(blocking) {
749        Verdict::Fail
750    } else {
751        Verdict::Pass
752    }
753}
754
755/// Aggregate per-gate verdicts with every gate fail-open — `Fail` iff any gate fails.
756#[must_use]
757pub fn aggregate(results: &[GateResult]) -> Verdict {
758    aggregate_with_policy(results, &std::collections::HashSet::new())
759}
760
761#[cfg(test)]
762mod tests {
763    use super::*;
764    use serde_json::{Value, json};
765
766    fn resp(text: &str) -> ModelResponse {
767        ModelResponse {
768            model: "anthropic/claude-haiku-4-5".to_owned(),
769            text: text.to_owned(),
770            in_tokens: 1,
771            cache_write_tokens: 0,
772            cache_read_tokens: 0,
773            out_tokens: 1,
774            raw: Value::Null,
775        }
776    }
777
778    fn req() -> ModelRequest {
779        ModelRequest {
780            model: "anthropic/claude-haiku-4-5".to_owned(),
781            system: None,
782            messages: vec![],
783            max_tokens: 16,
784            tools: Value::Null,
785            raw: Value::Null,
786            cache_prefix: false,
787        }
788    }
789
790    #[tokio::test]
791    async fn non_empty_gate() {
792        assert_eq!(
793            NonEmptyGate.evaluate(&req(), &resp("hi")).await.verdict,
794            Verdict::Pass
795        );
796        assert_eq!(
797            NonEmptyGate.evaluate(&req(), &resp("   ")).await.verdict,
798            Verdict::Fail
799        );
800    }
801
802    #[tokio::test]
803    async fn json_valid_gate() {
804        assert_eq!(
805            JsonValidGate
806                .evaluate(&req(), &resp(r#"{"ok":true}"#))
807                .await
808                .verdict,
809            Verdict::Pass
810        );
811        assert_eq!(
812            JsonValidGate.evaluate(&req(), &resp("nope")).await.verdict,
813            Verdict::Fail
814        );
815    }
816
817    #[tokio::test]
818    async fn schema_gate_type_and_required() {
819        let g = SchemaGate::new(
820            "schema",
821            json!({
822                "type": "object",
823                "required": ["name", "age"],
824                "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }
825            }),
826        );
827        assert_eq!(
828            g.evaluate(&req(), &resp(r#"{"name":"a","age":3}"#))
829                .await
830                .verdict,
831            Verdict::Pass
832        );
833        // missing required
834        assert_eq!(
835            g.evaluate(&req(), &resp(r#"{"name":"a"}"#)).await.verdict,
836            Verdict::Fail
837        );
838        // wrong property type
839        assert_eq!(
840            g.evaluate(&req(), &resp(r#"{"name":"a","age":"x"}"#))
841                .await
842                .verdict,
843            Verdict::Fail
844        );
845        // wrong root type
846        assert_eq!(g.evaluate(&req(), &resp("[]")).await.verdict, Verdict::Fail);
847        // not even JSON
848        assert_eq!(
849            g.evaluate(&req(), &resp("plain text")).await.verdict,
850            Verdict::Fail
851        );
852    }
853
854    fn empty_registry() -> ProviderRegistry {
855        ProviderRegistry::new("http://localhost", "http://localhost")
856    }
857
858    #[test]
859    fn resolve_skips_unknown_and_keeps_known() {
860        let gates = resolve_gates(
861            &[
862                "non-empty".to_owned(),
863                "judge-diff".to_owned(),
864                "json-valid".to_owned(),
865            ],
866            &[],
867            &empty_registry(),
868            &Auth::default(),
869            &PriceTable::default(),
870            &reqwest::Client::new(),
871        );
872        let ids: Vec<_> = gates.iter().map(|g| g.id()).collect();
873        assert_eq!(ids, ["non-empty", "json-valid"]);
874    }
875
876    #[test]
877    fn resolve_builds_configured_subprocess_gate() {
878        // A gate id that isn't built-in resolves to a SubprocessGate when defined in `[[gate]]`.
879        let defs = vec![GateDef {
880            id: "my-tests".to_owned(),
881            cmd: vec!["true".to_owned()],
882            timeout_ms: 1000,
883            judge: None,
884            consistency: None,
885            schema: None,
886            decision: None,
887            on_abstain: AbstainPolicy::FailOpen,
888        }];
889        let gates = resolve_gates(
890            &["my-tests".to_owned(), "undefined".to_owned()],
891            &defs,
892            &empty_registry(),
893            &Auth::default(),
894            &PriceTable::default(),
895            &reqwest::Client::new(),
896        );
897        let ids: Vec<_> = gates.iter().map(|g| g.id()).collect();
898        assert_eq!(
899            ids,
900            ["my-tests"],
901            "configured id resolves; unknown id skipped"
902        );
903    }
904
905    #[tokio::test]
906    async fn configured_subprocess_gate_runs_end_to_end() {
907        // A user-defined gate that fails iff the candidate text contains "BAD" — proving the config
908        // → SubprocessGate → verdict path works over stdin, no hard-coded gate name.
909        let script = r#"c=$(cat); case "$c" in *BAD*) echo '{"verdict":"fail"}';; *) echo '{"verdict":"pass"}';; esac"#;
910        let defs = vec![GateDef {
911            id: "no-bad".to_owned(),
912            cmd: vec!["bash".to_owned(), "-c".to_owned(), script.to_owned()],
913            timeout_ms: 5000,
914            judge: None,
915            consistency: None,
916            schema: None,
917            decision: None,
918            on_abstain: AbstainPolicy::FailOpen,
919        }];
920        let gates = resolve_gates(
921            &["no-bad".to_owned()],
922            &defs,
923            &empty_registry(),
924            &Auth::default(),
925            &PriceTable::default(),
926            &reqwest::Client::new(),
927        );
928        assert_eq!(gates.len(), 1);
929        let good = gates[0].evaluate(&req(), &resp("all good")).await;
930        assert_eq!(good.verdict, Verdict::Pass);
931        let bad = gates[0].evaluate(&req(), &resp("this is BAD")).await;
932        assert_eq!(bad.verdict, Verdict::Fail);
933    }
934
935    #[test]
936    fn resolve_builds_configured_judge_gate() {
937        use crate::provider::{MockProvider, Provider};
938        use std::collections::HashMap;
939        use std::sync::Arc;
940
941        let defs = vec![GateDef {
942            id: "quality".to_owned(),
943            cmd: vec![],
944            timeout_ms: 30_000,
945            judge: Some(firstpass_core::JudgeDef {
946                model: "anthropic/judge".to_owned(),
947                threshold: 0.7,
948                rubric: None,
949            }),
950            consistency: None,
951            schema: None,
952            decision: None,
953            on_abstain: AbstainPolicy::FailOpen,
954        }];
955
956        // Registry that serves `anthropic` → the judge gate is built.
957        let mut map: HashMap<String, Arc<dyn Provider>> = HashMap::new();
958        map.insert(
959            "anthropic".to_owned(),
960            Arc::new(MockProvider::new("anthropic", HashMap::new())),
961        );
962        let gates = resolve_gates(
963            &["quality".to_owned()],
964            &defs,
965            &ProviderRegistry::from_map(map),
966            &Auth::default(),
967            &PriceTable::default(),
968            &reqwest::Client::new(),
969        );
970        assert_eq!(
971            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
972            ["quality"]
973        );
974
975        // Registry without that provider → skipped, not a hard failure.
976        let skipped = resolve_gates(
977            &["quality".to_owned()],
978            &defs,
979            &ProviderRegistry::from_map(HashMap::new()),
980            &Auth::default(),
981            &PriceTable::default(),
982            &reqwest::Client::new(),
983        );
984        assert!(
985            skipped.is_empty(),
986            "judge with no registered provider is skipped"
987        );
988    }
989
990    #[test]
991    fn resolve_builds_configured_decision_gate() {
992        // No unsafe env::set_var (forbidden workspace-wide, and unsound in edition 2024): reuse
993        // `PATH`, guaranteed set in any test process, as a stand-in "the key env var is present"
994        // — resolve_gates only checks presence, never the value's shape. Mirrors the same trick
995        // already used in `provider.rs`'s tests.
996        let def = |api_key_env: &str| GateDef {
997            id: "verify".to_owned(),
998            cmd: vec![],
999            timeout_ms: 30_000,
1000            judge: None,
1001            consistency: None,
1002            schema: None,
1003            decision: Some(firstpass_core::DecisionDef {
1004                provider: "typesafe".to_owned(),
1005                model: "jev-latest".to_owned(),
1006                api_key_env: api_key_env.to_owned(),
1007                base_url: "https://api.typesafe.ai".to_owned(),
1008                timeout_ms: 1_000,
1009                threshold: 0.5,
1010                instructions: None,
1011            }),
1012            on_abstain: AbstainPolicy::FailOpen,
1013        };
1014
1015        let gates = resolve_gates(
1016            &["verify".to_owned()],
1017            &[def("PATH")],
1018            &empty_registry(),
1019            &Auth::default(),
1020            &PriceTable::default(),
1021            &reqwest::Client::new(),
1022        );
1023        assert_eq!(
1024            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
1025            ["verify"],
1026            "decision gate resolves when its API key env var is set"
1027        );
1028
1029        let gates = resolve_gates(
1030            &["verify".to_owned()],
1031            &[def("FIRSTPASS_TEST_DEFINITELY_UNSET_DECISION_KEY_XYZ")],
1032            &empty_registry(),
1033            &Auth::default(),
1034            &PriceTable::default(),
1035            &reqwest::Client::new(),
1036        );
1037        assert!(
1038            gates.is_empty(),
1039            "decision gate with an unset API key env var is skipped, not a hard failure"
1040        );
1041    }
1042
1043    #[test]
1044    fn resolve_builds_configured_consistency_gate() {
1045        use crate::provider::{MockProvider, Provider};
1046        use std::collections::HashMap;
1047        use std::sync::Arc;
1048
1049        let defs = vec![GateDef {
1050            id: "uncertainty".to_owned(),
1051            cmd: vec![],
1052            timeout_ms: 30_000,
1053            judge: None,
1054            consistency: Some(firstpass_core::ConsistencyDef {
1055                model: "anthropic/claude-haiku-4-5".to_owned(),
1056                k: 3,
1057                threshold: 0.6,
1058            }),
1059            schema: None,
1060            decision: None,
1061            on_abstain: AbstainPolicy::FailOpen,
1062        }];
1063
1064        // Registry that serves `anthropic` → the consistency gate is built.
1065        let mut map: HashMap<String, Arc<dyn Provider>> = HashMap::new();
1066        map.insert(
1067            "anthropic".to_owned(),
1068            Arc::new(MockProvider::new("anthropic", HashMap::new())),
1069        );
1070        let gates = resolve_gates(
1071            &["uncertainty".to_owned()],
1072            &defs,
1073            &ProviderRegistry::from_map(map),
1074            &Auth::default(),
1075            &PriceTable::default(),
1076            &reqwest::Client::new(),
1077        );
1078        assert_eq!(
1079            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
1080            ["uncertainty"]
1081        );
1082
1083        // Registry without the provider → skipped, not a hard failure.
1084        let skipped = resolve_gates(
1085            &["uncertainty".to_owned()],
1086            &defs,
1087            &ProviderRegistry::from_map(HashMap::new()),
1088            &Auth::default(),
1089            &PriceTable::default(),
1090            &reqwest::Client::new(),
1091        );
1092        assert!(
1093            skipped.is_empty(),
1094            "consistency gate with no registered provider is skipped"
1095        );
1096    }
1097
1098    #[test]
1099    fn aggregate_semantics() {
1100        let pass = GateResult::deterministic("a", Verdict::Pass, 0);
1101        let fail = GateResult::deterministic("b", Verdict::Fail, 0);
1102        let abstain = GateResult::abstain("c", "x", 0);
1103        assert_eq!(aggregate(&[]), Verdict::Pass);
1104        assert_eq!(aggregate(std::slice::from_ref(&pass)), Verdict::Pass);
1105        assert_eq!(aggregate(&[pass.clone(), fail]), Verdict::Fail);
1106        assert_eq!(aggregate(&[pass, abstain]), Verdict::Pass);
1107    }
1108
1109    #[test]
1110    fn error_budget_auto_disables_past_threshold() {
1111        let h = GateHealth::new(10, 0.5); // disable when >50% of the last 10 error
1112        // Window fills to exactly 5 errors / 10 = 50% — NOT above threshold, still enabled.
1113        for _ in 0..5 {
1114            h.record("g", true);
1115        }
1116        for _ in 0..5 {
1117            h.record("g", false);
1118        }
1119        assert!(h.is_enabled(), "50% is at, not above, the budget");
1120        // Flood errors: the window slides until errors exceed 50% -> auto-disabled.
1121        for _ in 0..6 {
1122            h.record("g", true);
1123        }
1124        assert!(
1125            !h.is_enabled(),
1126            "gate should auto-disable once error rate exceeds budget"
1127        );
1128    }
1129
1130    #[test]
1131    fn healthy_gate_stays_enabled() {
1132        let h = GateHealth::new(20, 0.5);
1133        for _ in 0..100 {
1134            h.record("g", false);
1135        }
1136        assert!(h.is_enabled());
1137    }
1138
1139    #[test]
1140    fn gate_health_registry_default_tenant_is_a_single_bucket() {
1141        // With auth off (single-operator), every request uses the same "default" tenant, so this
1142        // is exactly the pre-D6 global-registry behavior.
1143        let registry = GateHealthRegistry::new().with_budget("g", 4, 0.5);
1144        for _ in 0..4 {
1145            registry.record("default", "g", true);
1146        }
1147        assert!(!registry.enabled("default", "g"));
1148    }
1149
1150    #[test]
1151    fn gate_health_registry_scopes_budget_per_tenant() {
1152        // ADR 0004 §D6: tenant A tripping the budget must not affect tenant B on the same gate.
1153        let registry = GateHealthRegistry::new().with_budget("g", 4, 0.5);
1154        for _ in 0..4 {
1155            registry.record("tenant-a", "g", true);
1156        }
1157        assert!(!registry.enabled("tenant-a", "g"), "A should be disabled");
1158        assert!(registry.enabled("tenant-b", "g"), "B must be unaffected");
1159    }
1160
1161    #[test]
1162    fn gate_health_registry_unregistered_gate_always_enabled() {
1163        let registry = GateHealthRegistry::new();
1164        assert!(registry.enabled("tenant-a", "unknown-gate"));
1165        registry.record("tenant-a", "unknown-gate", true); // no-op, must not panic
1166        assert!(registry.enabled("tenant-a", "unknown-gate"));
1167    }
1168
1169    #[tokio::test]
1170    async fn resolve_builds_configured_schema_gate() {
1171        let defs = vec![GateDef {
1172            id: "extract-shape".to_owned(),
1173            cmd: vec![],
1174            timeout_ms: 30_000,
1175            judge: None,
1176            consistency: None,
1177            schema: Some(json!({"type": "object", "required": ["name"]})),
1178            decision: None,
1179            on_abstain: firstpass_core::AbstainPolicy::FailOpen,
1180        }];
1181        let gates = resolve_gates(
1182            &["extract-shape".to_owned()],
1183            &defs,
1184            &empty_registry(),
1185            &Auth::default(),
1186            &PriceTable::default(),
1187            &reqwest::Client::new(),
1188        );
1189        assert_eq!(
1190            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
1191            ["extract-shape"],
1192            "a [[gate]] def with `schema` resolves to a runnable SchemaGate"
1193        );
1194        let ok = gates[0].evaluate(&req(), &resp(r#"{"name":"a"}"#)).await;
1195        assert_eq!(ok.verdict, Verdict::Pass);
1196        let missing = gates[0].evaluate(&req(), &resp(r#"{}"#)).await;
1197        assert_eq!(missing.verdict, Verdict::Fail);
1198    }
1199
1200    #[test]
1201    fn resolve_wraps_fail_closed_gate() {
1202        let mk = |on_abstain| {
1203            vec![GateDef {
1204                id: "tests".to_owned(),
1205                cmd: vec!["true".to_owned()],
1206                timeout_ms: 1000,
1207                judge: None,
1208                consistency: None,
1209                schema: None,
1210                decision: None,
1211                on_abstain,
1212            }]
1213        };
1214        let open = resolve_gates(
1215            &["tests".to_owned()],
1216            &mk(firstpass_core::AbstainPolicy::FailOpen),
1217            &empty_registry(),
1218            &Auth::default(),
1219            &PriceTable::default(),
1220            &reqwest::Client::new(),
1221        );
1222        assert!(!open[0].abstain_fails_closed(), "default stays fail-open");
1223        let closed = resolve_gates(
1224            &["tests".to_owned()],
1225            &mk(firstpass_core::AbstainPolicy::FailClosed),
1226            &empty_registry(),
1227            &Auth::default(),
1228            &PriceTable::default(),
1229            &reqwest::Client::new(),
1230        );
1231        assert!(
1232            closed[0].abstain_fails_closed(),
1233            "on_abstain = fail_closed wraps the gate"
1234        );
1235        assert_eq!(closed[0].id(), "tests", "wrapper preserves the id");
1236    }
1237
1238    #[test]
1239    fn aggregate_with_policy_fail_closed_abstain_blocks() {
1240        use std::collections::HashSet;
1241        let pass = GateResult::deterministic("a", Verdict::Pass, 0);
1242        let abstain = GateResult::abstain("c", "timeout", 0);
1243        // Fail-open (empty set): abstain never blocks — historical behavior.
1244        assert_eq!(
1245            aggregate_with_policy(&[pass.clone(), abstain.clone()], &HashSet::new()),
1246            Verdict::Pass
1247        );
1248        // Fail-closed: the same abstain blocks serving like a Fail.
1249        let closed: HashSet<&str> = ["c"].into_iter().collect();
1250        assert_eq!(
1251            aggregate_with_policy(&[pass, abstain], &closed),
1252            Verdict::Fail
1253        );
1254    }
1255
1256    // ── Defect 1: gates must handle tool-call-only responses correctly ────────
1257
1258    fn tool_use_resp() -> ModelResponse {
1259        ModelResponse {
1260            model: "anthropic/claude-haiku-4-5".to_owned(),
1261            text: String::new(), // tool-only: no text
1262            in_tokens: 10,
1263            cache_write_tokens: 0,
1264            cache_read_tokens: 0,
1265            out_tokens: 5,
1266            raw: serde_json::json!({
1267                "content": [{
1268                    "type": "tool_use",
1269                    "id": "t1",
1270                    "name": "search",
1271                    "input": { "q": "hello" }
1272                }]
1273            }),
1274        }
1275    }
1276
1277    fn tool_req_with_schema() -> ModelRequest {
1278        ModelRequest {
1279            model: "anthropic/claude-haiku-4-5".to_owned(),
1280            system: None,
1281            messages: vec![],
1282            max_tokens: 64,
1283            tools: serde_json::json!([{
1284                "name": "search",
1285                "input_schema": {
1286                    "type": "object",
1287                    "required": ["q"],
1288                    "properties": { "q": { "type": "string" } }
1289                }
1290            }]),
1291            raw: serde_json::Value::Null,
1292            cache_prefix: false,
1293        }
1294    }
1295
1296    #[tokio::test]
1297    async fn non_empty_passes_on_tool_use_when_tools_declared() {
1298        // A tool-call-only turn with declared tools is not "empty" — it must not escalate.
1299        // Uses tool_req_with_schema() which has a non-empty tools array.
1300        assert_eq!(
1301            NonEmptyGate
1302                .evaluate(&tool_req_with_schema(), &tool_use_resp())
1303                .await
1304                .verdict,
1305            Verdict::Pass
1306        );
1307    }
1308
1309    #[tokio::test]
1310    async fn non_empty_fails_on_tool_call_when_no_tools_declared() {
1311        // Finding 2: tool-call bypass only when request declared tools.
1312        // req() has tools: Value::Null — so tool call with empty text is treated as empty.
1313        assert_eq!(
1314            NonEmptyGate
1315                .evaluate(&req(), &tool_use_resp())
1316                .await
1317                .verdict,
1318            Verdict::Fail,
1319            "tool call without declared tools must Fail non-empty (undeclared/hallucinated)"
1320        );
1321    }
1322
1323    #[tokio::test]
1324    async fn non_empty_still_fails_on_truly_empty_response() {
1325        assert_eq!(
1326            NonEmptyGate.evaluate(&req(), &resp("")).await.verdict,
1327            Verdict::Fail
1328        );
1329        assert_eq!(
1330            NonEmptyGate.evaluate(&req(), &resp("   ")).await.verdict,
1331            Verdict::Fail
1332        );
1333    }
1334
1335    #[tokio::test]
1336    async fn json_valid_passes_on_tool_use_when_tools_declared() {
1337        // json-valid on a tool-only turn (tools declared) has nothing to parse → Pass, not Abstain.
1338        assert_eq!(
1339            JsonValidGate
1340                .evaluate(&tool_req_with_schema(), &tool_use_resp())
1341                .await
1342                .verdict,
1343            Verdict::Pass
1344        );
1345    }
1346
1347    #[tokio::test]
1348    async fn json_valid_fails_on_tool_call_when_no_tools_declared() {
1349        // Finding 2: tool-call bypass only when request declared tools.
1350        // req() has no tools, so the call is treated as a non-JSON text response.
1351        assert_eq!(
1352            JsonValidGate
1353                .evaluate(&req(), &tool_use_resp())
1354                .await
1355                .verdict,
1356            Verdict::Fail,
1357            "tool call without declared tools must Fail json-valid"
1358        );
1359    }
1360
1361    #[tokio::test]
1362    async fn json_valid_passes_on_preamble_text_plus_tool_calls() {
1363        // Finding 4: preamble text alongside tool calls (with declared tools) must Pass.
1364        // The text is not the JSON answer — tool-args-valid validates the call args instead.
1365        let resp_with_preamble = ModelResponse {
1366            text: "I will look that up for you.".to_owned(),
1367            raw: serde_json::json!({
1368                "content": [
1369                    {"type": "text", "text": "I will look that up for you."},
1370                    {"type": "tool_use", "id": "t1", "name": "search", "input": {"q": "hello"}}
1371                ]
1372            }),
1373            ..tool_use_resp()
1374        };
1375        assert_eq!(
1376            JsonValidGate
1377                .evaluate(&tool_req_with_schema(), &resp_with_preamble)
1378                .await
1379                .verdict,
1380            Verdict::Pass,
1381            "preamble text + tool calls with declared tools must Pass json-valid"
1382        );
1383    }
1384
1385    #[tokio::test]
1386    async fn json_valid_still_fails_on_non_json_text_response() {
1387        assert_eq!(
1388            JsonValidGate
1389                .evaluate(&req(), &resp("not json"))
1390                .await
1391                .verdict,
1392            Verdict::Fail
1393        );
1394    }
1395
1396    #[tokio::test]
1397    async fn schema_gate_passes_on_tool_use_when_tools_declared() {
1398        // Trivially passes (not Abstain) on tool-only turns when tools are declared.
1399        let g = SchemaGate::new(
1400            "extract",
1401            serde_json::json!({"type": "object", "required": ["name"]}),
1402        );
1403        assert_eq!(
1404            g.evaluate(&tool_req_with_schema(), &tool_use_resp())
1405                .await
1406                .verdict,
1407            Verdict::Pass
1408        );
1409    }
1410
1411    #[tokio::test]
1412    async fn schema_gate_passes_on_preamble_text_plus_tool_calls() {
1413        // Finding 4: preamble text alongside tool calls (with declared tools) must Pass schema-gate.
1414        let g = SchemaGate::new(
1415            "extract",
1416            serde_json::json!({"type": "object", "required": ["name"]}),
1417        );
1418        let resp_with_preamble = ModelResponse {
1419            text: "Here is the result:".to_owned(),
1420            raw: serde_json::json!({
1421                "content": [
1422                    {"type": "text", "text": "Here is the result:"},
1423                    {"type": "tool_use", "id": "t1", "name": "search", "input": {"q": "hello"}}
1424                ]
1425            }),
1426            ..tool_use_resp()
1427        };
1428        assert_eq!(
1429            g.evaluate(&tool_req_with_schema(), &resp_with_preamble)
1430                .await
1431                .verdict,
1432            Verdict::Pass,
1433            "preamble text + tool calls with declared tools must Pass schema-gate"
1434        );
1435    }
1436
1437    #[tokio::test]
1438    async fn tool_args_valid_passes_with_valid_args() {
1439        assert_eq!(
1440            ToolArgsValidGate
1441                .evaluate(&tool_req_with_schema(), &tool_use_resp())
1442                .await
1443                .verdict,
1444            Verdict::Pass
1445        );
1446    }
1447
1448    #[tokio::test]
1449    async fn tool_args_valid_passes_when_no_tool_calls() {
1450        // Text-only response: trivially satisfied (Pass, not Abstain — see doc comment).
1451        assert_eq!(
1452            ToolArgsValidGate
1453                .evaluate(&req(), &resp("hello"))
1454                .await
1455                .verdict,
1456            Verdict::Pass
1457        );
1458    }
1459
1460    #[tokio::test]
1461    async fn tool_args_valid_fails_on_hallucinated_tool_name() {
1462        // Response calls "unknown_tool" which is not in the request's tools list.
1463        let bad_resp = ModelResponse {
1464            text: String::new(),
1465            raw: serde_json::json!({
1466                "content": [{
1467                    "type": "tool_use",
1468                    "id": "t1",
1469                    "name": "unknown_tool",
1470                    "input": { "x": 1 }
1471                }]
1472            }),
1473            ..tool_use_resp()
1474        };
1475        let r = ToolArgsValidGate
1476            .evaluate(&tool_req_with_schema(), &bad_resp)
1477            .await;
1478        assert_eq!(r.verdict, Verdict::Fail);
1479        assert!(
1480            r.reason
1481                .as_deref()
1482                .is_some_and(|s| s.contains("unknown_tool")),
1483            "reason must name the hallucinated tool"
1484        );
1485    }
1486
1487    #[tokio::test]
1488    async fn tool_args_valid_fails_when_no_tools_declared_but_response_has_calls() {
1489        // Request declared no tools, but response contains tool calls.
1490        assert_eq!(
1491            ToolArgsValidGate
1492                .evaluate(&req(), &tool_use_resp()) // req() has no tools
1493                .await
1494                .verdict,
1495            Verdict::Fail
1496        );
1497    }
1498
1499    #[tokio::test]
1500    async fn tool_args_valid_fails_on_missing_required_field() {
1501        let bad_resp = ModelResponse {
1502            text: String::new(),
1503            raw: serde_json::json!({
1504                "content": [{
1505                    "type": "tool_use",
1506                    "id": "t1",
1507                    "name": "search",
1508                    "input": {} // missing required "q"
1509                }]
1510            }),
1511            ..tool_use_resp()
1512        };
1513        let r = ToolArgsValidGate
1514            .evaluate(&tool_req_with_schema(), &bad_resp)
1515            .await;
1516        assert_eq!(r.verdict, Verdict::Fail);
1517        assert!(
1518            r.reason.as_deref().is_some_and(|s| s.contains("search")),
1519            "reason must name the failing tool"
1520        );
1521    }
1522
1523    /// A `/v1/responses` request, routed exactly as the handler routes it (Responses → Chat body →
1524    /// `parse_openai_request`), has its `function_call` arguments checked against the Responses
1525    /// tool's `parameters`: bad args Fail, good args Pass.
1526    #[tokio::test]
1527    async fn tool_args_valid_checks_responses_function_call_args() {
1528        let responses_req = serde_json::json!({
1529            "model": "gpt-5.5", "input": "weather?", "stream": true,
1530            "tools": [{ "type": "function", "name": "get_weather", "parameters": {
1531                "type": "object", "required": ["city"],
1532                "properties": { "city": { "type": "string" } } } }],
1533        });
1534        let chat = crate::responses::request_to_chat(&responses_req).to_string();
1535        let req = crate::proxy::parse_openai_request(chat.as_bytes(), true).unwrap();
1536        let resp = |args: &str| ModelResponse {
1537            raw: serde_json::json!({ "choices": [{ "message": { "role": "assistant",
1538                "content": null, "tool_calls": [{ "id": "call_1", "type": "function",
1539                "function": { "name": "get_weather", "arguments": args } }] } }] }),
1540            ..tool_use_resp()
1541        };
1542        let bad = ToolArgsValidGate
1543            .evaluate(&req, &resp(r#"{"town":"Paris"}"#))
1544            .await;
1545        assert_eq!(bad.verdict, Verdict::Fail, "{:?}", bad.reason);
1546        let good = ToolArgsValidGate
1547            .evaluate(&req, &resp(r#"{"city":"Paris"}"#))
1548            .await;
1549        assert_eq!(good.verdict, Verdict::Pass, "{:?}", good.reason);
1550    }
1551
1552    /// A tool declared in the flat Responses shape (`{type, name, parameters}`) is schema-checked,
1553    /// not waved through: `tool_name_is_known` accepts it by name, so skipping the schema would be
1554    /// fail-open.
1555    #[tokio::test]
1556    async fn tool_args_valid_checks_flat_responses_tool_schema() {
1557        let req = ModelRequest {
1558            tools: serde_json::json!([{ "type": "function", "name": "search", "parameters": {
1559                "type": "object", "required": ["q"], "properties": { "q": { "type": "string" } } } }]),
1560            ..tool_req_with_schema()
1561        };
1562        let bad = ModelResponse {
1563            raw: serde_json::json!({ "content": [{ "type": "tool_use", "id": "t1",
1564                "name": "search", "input": {} }] }),
1565            ..tool_use_resp()
1566        };
1567        assert_eq!(
1568            ToolArgsValidGate.evaluate(&req, &bad).await.verdict,
1569            Verdict::Fail
1570        );
1571        assert_eq!(
1572            ToolArgsValidGate
1573                .evaluate(&req, &tool_use_resp())
1574                .await
1575                .verdict,
1576            Verdict::Pass
1577        );
1578    }
1579
1580    #[tokio::test]
1581    async fn tool_args_valid_resolves_as_builtin() {
1582        // "tool-args-valid" is a built-in id: resolve_gates must return it.
1583        let gates = resolve_gates(
1584            &["tool-args-valid".to_owned()],
1585            &[],
1586            &empty_registry(),
1587            &Auth::default(),
1588            &PriceTable::default(),
1589            &reqwest::Client::new(),
1590        );
1591        assert_eq!(
1592            gates.iter().map(|g| g.id()).collect::<Vec<_>>(),
1593            ["tool-args-valid"]
1594        );
1595    }
1596
1597    // ── Finding 1: recursive schema_violation ──────────────────────────────────────────────────
1598
1599    /// Nested required field missing → Fail.
1600    /// Guards: `schema_violation` required-check inside a `properties` child schema.
1601    #[test]
1602    fn schema_violation_nested_required_missing() {
1603        let schema = json!({
1604            "type": "object",
1605            "properties": {
1606                "address": {
1607                    "type": "object",
1608                    "required": ["street"],
1609                    "properties": { "street": {"type": "string"} }
1610                }
1611            }
1612        });
1613        // address.street is required but missing → violation
1614        assert!(
1615            schema_violation(&json!({"address": {}}), &schema, "root").is_some(),
1616            "nested required field must produce a violation"
1617        );
1618        // address.street present → no violation
1619        assert!(
1620            schema_violation(
1621                &json!({"address": {"street": "1 Main St"}}),
1622                &schema,
1623                "root"
1624            )
1625            .is_none(),
1626            "valid nested object must produce no violation"
1627        );
1628    }
1629
1630    /// Enum violation → Fail.
1631    /// Guards: `schema_violation` enum-keyword check.
1632    #[test]
1633    fn schema_violation_enum_check() {
1634        let schema = json!({ "enum": ["red", "green", "blue"] });
1635        assert!(
1636            schema_violation(&json!("purple"), &schema, "root").is_some(),
1637            "value outside enum must produce a violation"
1638        );
1639        assert!(
1640            schema_violation(&json!("red"), &schema, "root").is_none(),
1641            "value inside enum must produce no violation"
1642        );
1643    }
1644
1645    /// items type wrong → Fail.
1646    /// Guards: `schema_violation` items-keyword recursive check.
1647    #[test]
1648    fn schema_violation_items_type_wrong() {
1649        let schema = json!({
1650            "type": "array",
1651            "items": { "type": "integer" }
1652        });
1653        // Array containing a string → violation
1654        assert!(
1655            schema_violation(&json!([1, 2, "three"]), &schema, "root").is_some(),
1656            "array item of wrong type must produce a violation"
1657        );
1658        // All integers → no violation
1659        assert!(
1660            schema_violation(&json!([1, 2, 3]), &schema, "root").is_none(),
1661            "array of correct type must produce no violation"
1662        );
1663    }
1664
1665    /// additionalProperties: false with extra key → Fail.
1666    /// Guards: `schema_violation` additionalProperties-false check.
1667    #[test]
1668    fn schema_violation_additional_properties_subschema() {
1669        let schema = serde_json::json!({
1670            "type": "object",
1671            "properties": {"a": {"type": "string"}},
1672            "additionalProperties": {"type": "integer"}
1673        });
1674        assert!(
1675            schema_violation(&serde_json::json!({"a": "x", "b": 1}), &schema, "args").is_none()
1676        );
1677        assert!(
1678            schema_violation(&serde_json::json!({"a": "x", "b": "no"}), &schema, "args").is_some()
1679        );
1680    }
1681
1682    #[test]
1683    fn anthropic_tool_use_without_input_is_malformed() {
1684        let raw = serde_json::json!({"content": [{"type": "tool_use", "id": "t1", "name": "f"}]});
1685        let calls = extract_response_tool_calls(&raw);
1686        assert_eq!(calls.len(), 1);
1687        assert!(serde_json::from_str::<serde_json::Value>(&calls[0].1).is_err());
1688    }
1689
1690    #[test]
1691    fn openai_tool_call_without_string_arguments_is_malformed() {
1692        let raw = serde_json::json!({"choices": [{"message": {"tool_calls": [
1693            {"id": "c1", "type": "function", "function": {"name": "f"}},
1694            {"id": "c2", "type": "function", "function": {"name": "f", "arguments": {"x": 1}}}
1695        ]}}]});
1696        let calls = extract_response_tool_calls(&raw);
1697        assert_eq!(calls.len(), 2);
1698        for (_, args) in &calls {
1699            assert!(
1700                serde_json::from_str::<serde_json::Value>(args).is_err(),
1701                "missing/non-string arguments must not parse as an empty object"
1702            );
1703        }
1704    }
1705
1706    #[test]
1707    fn schema_violation_additional_properties_false() {
1708        let schema = json!({
1709            "type": "object",
1710            "properties": { "name": {"type": "string"} },
1711            "additionalProperties": false
1712        });
1713        // extra key "age" not in properties → violation
1714        assert!(
1715            schema_violation(&json!({"name": "Alice", "age": 30}), &schema, "root").is_some(),
1716            "extra key with additionalProperties:false must produce a violation"
1717        );
1718        // only declared keys → no violation
1719        assert!(
1720            schema_violation(&json!({"name": "Alice"}), &schema, "root").is_none(),
1721            "object with only declared keys must produce no violation"
1722        );
1723    }
1724
1725    /// Full nested valid value → Pass.
1726    /// Guards: all checks passing silently together.
1727    #[test]
1728    fn schema_violation_complex_valid_nested() {
1729        let schema = json!({
1730            "type": "object",
1731            "required": ["id", "tags"],
1732            "additionalProperties": false,
1733            "properties": {
1734                "id": {"type": "integer"},
1735                "tags": {
1736                    "type": "array",
1737                    "items": {"type": "string"}
1738                }
1739            }
1740        });
1741        assert!(
1742            schema_violation(
1743                &json!({"id": 1, "tags": ["rust", "agent"]}),
1744                &schema,
1745                "root"
1746            )
1747            .is_none(),
1748            "fully valid complex value must produce no violation"
1749        );
1750    }
1751
1752    // ── Finding 5: malformed tool calls produce Fail, not silent Pass ──────────────────────────
1753
1754    /// OpenAI tool call missing `function` → empty name → ToolArgsValidGate Fail.
1755    /// Guards: `extract_response_tool_calls` OpenAI missing-function branch (line 302-303).
1756    #[tokio::test]
1757    async fn tool_args_valid_fails_on_openai_tool_call_missing_function_key() {
1758        // An OpenAI-format tool_calls entry without a `function` key is malformed.
1759        // extract_response_tool_calls must record it as ("", "{}") rather than skipping it,
1760        // so ToolArgsValidGate can Fail the response (tool "" is not in the request schema).
1761        let malformed_resp = ModelResponse {
1762            text: String::new(),
1763            raw: serde_json::json!({
1764                "choices": [{
1765                    "message": {
1766                        "role": "assistant",
1767                        "tool_calls": [
1768                            // Missing "function" key entirely — malformed call
1769                            {"id": "call_1", "type": "function"}
1770                        ]
1771                    }
1772                }]
1773            }),
1774            ..tool_use_resp()
1775        };
1776        let r = ToolArgsValidGate
1777            .evaluate(&tool_req_with_schema(), &malformed_resp)
1778            .await;
1779        assert_eq!(
1780            r.verdict,
1781            Verdict::Fail,
1782            "malformed OpenAI tool call (missing function) must Fail, not Pass"
1783        );
1784    }
1785
1786    /// Anthropic tool_use missing `name` → empty name → ToolArgsValidGate Fail.
1787    /// Guards: `extract_response_tool_calls` Anthropic missing-name branch (line 273-275).
1788    #[tokio::test]
1789    async fn tool_args_valid_fails_on_anthropic_tool_use_missing_name() {
1790        let malformed_resp = ModelResponse {
1791            text: String::new(),
1792            raw: serde_json::json!({
1793                "content": [{
1794                    "type": "tool_use",
1795                    "id": "t1",
1796                    // "name" is absent — malformed
1797                    "input": {"q": "hello"}
1798                }]
1799            }),
1800            ..tool_use_resp()
1801        };
1802        let r = ToolArgsValidGate
1803            .evaluate(&tool_req_with_schema(), &malformed_resp)
1804            .await;
1805        assert_eq!(
1806            r.verdict,
1807            Verdict::Fail,
1808            "Anthropic tool_use missing name must Fail, not Pass"
1809        );
1810    }
1811}