liter-llm 2.0.0

//! CEL (Common Expression Language) policy engine for guardrails.
//!
//! Provides [`CelGuardrail`], which evaluates a CEL expression against the
//! [`GuardrailContext`] and applies a configurable action when the expression
//! evaluates to `true`.
//!
//! # Feature gate
//!
//! This module is only compiled when the `guardrail-cel` feature is enabled:
//!
//! ```toml
//! [dependencies]
//! liter-llm = { features = ["guardrail-cel"] }
//! ```
//!
//! # Fail-closed vs fail-open
//!
//! By default [`CelGuardrail`] is **fail-closed**: if the CEL expression cannot
//! be evaluated at runtime (eval error, non-bool result), the guardrail returns
//! [`GuardrailDecision::Block`] with code `4001`. This is the only secure
//! default — an attacker who can craft a request that triggers an eval error
//! must not be able to bypass ALL guardrails as a result.
//!
//! To opt in to fail-open behaviour (e.g., in development environments where
//! guardrails are advisory), chain [`CelGuardrail::with_fail_open`]:
//!
//! ```rust,ignore
//! let guardrail = CelGuardrail::new(...)
//!     .expect("valid CEL")
//!     .with_fail_open(true); // SECURITY WARNING: only use in non-production
//! ```
//!
//! # Input bounding at construction time
//!
//! [`CelGuardrail::new`] rejects expressions that exceed [`MAX_CEL_EXPRESSION_LEN`]
//! bytes, nest `(`/`[`/`{` deeper than [`MAX_CEL_NESTING_DEPTH`], or chain more
//! than [`MAX_CEL_OPERATOR_TOKENS`] operators, *before* the expression is handed
//! to the parser. The parser is a recursive-descent ANTLR parser: a sufficiently
//! deep nesting can exhaust the native stack, which is an abort rather than a
//! panic and cannot be caught by `catch_unwind`. Bounding the input is the only
//! available defense against that failure mode.
//!
//! Depth and operator count are separate bounds because they describe different
//! shapes. Such a grammar descends once per operator in an unparenthesized
//! chain, so `!!!!…true` reaches thousands of frames at a bracket depth of zero
//! — the depth cap alone cannot see it.
//!
//! # CEL variables available in expressions
//!
//! | Variable | Type | Description |
//! |---|---|---|
//! | `request` | map | Full JSON request object |
//! | `response` | map | Full JSON response object (Output stage only; empty map otherwise) |
//! | `chunk` | string | Raw streaming chunk text (OutputChunk stage only; empty string otherwise) |
//! | `metadata` | map | Per-call tags (user_id, tenant_id, route, …) |
//!
//! # Example
//!
//! ```rust,ignore
//! use liter_llm::guardrail::cel::{CelAction, CelGuardrail};
//! use liter_llm::guardrail::GuardrailStage;
//!
//! // Block requests from non-premium tenants targeting gpt-4o.
//! let guardrail = CelGuardrail::new(
//!     "gpt4o-premium-only",
//!     r#"request.model == "gpt-4o" && metadata.tier != "premium""#,
//!     CelAction::Block { code: 1300, reason: "gpt-4o requires premium tier".into() },
//!     &[GuardrailStage::Input],
//! ).expect("invalid CEL expression");
//! ```

use std::collections::HashMap;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;

use cel_interpreter::objects::{Key, Map, Value};
use cel_interpreter::{Context, Program};

use super::{Guardrail, GuardrailContext, GuardrailDecision, GuardrailStage};

/// Numeric error code returned when a CEL expression cannot be evaluated and
/// the guardrail is configured to fail-closed (the default).
const CEL_EVAL_ERROR_CODE: u32 = 4001;

/// Maximum accepted length (in bytes) of a CEL expression string.
///
/// Bounds parser work and input size regardless of nesting shape. Chosen to
/// comfortably fit any realistic hand-written policy expression while
/// rejecting pathological inputs before they reach the parser.
const MAX_CEL_EXPRESSION_LEN: usize = 4096;

/// Maximum accepted nesting depth of `(`, `[`, and `{` in a CEL expression.
///
/// The `cel-interpreter` parser is a recursive-descent ANTLR parser: each
/// nesting level consumes native stack. A crafted expression with enough
/// nested parentheses can exhaust the stack and abort the process — an abort
/// is not a panic, so `std::panic::catch_unwind` around `Program::compile`
/// cannot catch it. Rejecting deep nesting here, before the expression ever
/// reaches the parser, is the only defense available for that failure mode.
/// ~keep
const MAX_CEL_NESTING_DEPTH: usize = 64;

/// Maximum accepted count of operator characters in a CEL expression.
///
/// Bracket depth alone does not bound parser recursion. A recursive-descent
/// grammar descends once per operator in an unparenthesized chain, so
/// `!!!!…!!!!true` or `true&&true&&…&&true` reaches thousands of frames at a
/// bracket depth of zero — within [`MAX_CEL_EXPRESSION_LEN`] and completely
/// untouched by [`MAX_CEL_NESTING_DEPTH`]. This is the same stack-exhaustion
/// abort that the depth cap exists to prevent, reached by a different shape,
/// so it needs its own bound. ~keep
const MAX_CEL_OPERATOR_TOKENS: usize = 256;

/// The action taken when a [`CelGuardrail`]'s expression evaluates to `true`.
#[cfg_attr(alef, alef(skip))]
#[derive(Debug, Clone)]
pub enum CelAction {
    /// Block the request/response with the given code and reason.
    Block {
        /// Numeric error code (≥ 1000).
        code: u32,
        /// Human-readable reason.
        reason: String,
    },
    /// Replace the payload with a static JSON value (e.g., for redaction).
    Mutate {
        /// The replacement payload.
        new_payload: serde_json::Value,
    },
}

/// Evaluates a CEL expression against the [`GuardrailContext`] and applies
/// `on_true` when the expression evaluates to `true`.
///
/// The CEL expression is compiled at construction time so runtime evaluation
/// is fast. Construction returns an error if the expression is syntactically
/// invalid.
///
/// # Fail-closed behaviour (default, secure)
///
/// When the expression cannot be evaluated at runtime (eval error or non-bool
/// result), [`CelGuardrail`] returns [`GuardrailDecision::Block`] with code
/// `4001` and logs an `error`-level tracing event.
///
/// **SECURITY WARNING**: Call [`CelGuardrail::with_fail_open`] only in
/// non-production environments. Fail-open means a crafted request that triggers
/// an eval error bypasses ALL CEL guardrails on that instance.
#[cfg_attr(alef, alef(skip))]
pub struct CelGuardrail {
    guardrail_name: &'static str,
    program: Program,
    on_true: CelAction,
    stages: &'static [GuardrailStage],
    /// When `true`, runtime evaluation errors return `Allow` instead of `Block`.
    /// Defaults to `false` (fail-closed). Use [`with_fail_open`] to opt in.
    fail_open: bool,
}

/// Error returned when a CEL expression cannot be compiled.
///
/// `TooLong` and `TooDeep` are rejected before the expression ever reaches
/// the `cel-interpreter` parser (see [`MAX_CEL_EXPRESSION_LEN`] and
/// [`MAX_CEL_NESTING_DEPTH`]). `Invalid` wraps the underlying parser's
/// message as an owned, opaque string — it does not expose the third-party
/// error type, keeping the public surface `Send + Sync` and FFI-friendly.
/// Some malformed inputs cause the parser to panic rather than return an
/// error; those panics are caught and surfaced as `Invalid` so construction
/// never aborts.
#[cfg_attr(alef, alef(skip))]
#[derive(Debug, thiserror::Error)]
pub enum CelCompileError {
    /// The expression exceeded [`MAX_CEL_EXPRESSION_LEN`] bytes.
    #[error("CEL expression exceeds maximum length of {max} bytes (got {actual})")]
    TooLong {
        /// The length of the rejected expression, in bytes.
        actual: usize,
        /// The maximum accepted length, in bytes.
        max: usize,
    },
    /// The expression's `(`/`[`/`{` nesting exceeded [`MAX_CEL_NESTING_DEPTH`].
    #[error("CEL expression exceeds maximum nesting depth of {max} (got {actual})")]
    TooDeep {
        /// The nesting depth reached before rejection.
        actual: usize,
        /// The maximum accepted nesting depth.
        max: usize,
    },
    /// The expression's operator count exceeded [`MAX_CEL_OPERATOR_TOKENS`].
    #[error("CEL expression exceeds maximum operator count of {max} (got {actual})")]
    TooManyOperators {
        /// The operator count reached before rejection.
        actual: usize,
        /// The maximum accepted operator count.
        max: usize,
    },
    /// The parser rejected the expression as syntactically invalid, or
    /// panicked while attempting to parse it.
    #[error("invalid CEL expression: {0}")]
    Invalid(String),
}

/// Reject a CEL expression before it reaches the parser if it is too long,
/// nests `(`/`[`/`{` too deeply, or chains too many operators.
///
/// This is a defense-in-depth measure for a parser that recurses on nesting
/// depth: bounding the input here costs O(length) time and O(1) additional
/// stack, regardless of how the parser itself is implemented. See
/// [`MAX_CEL_NESTING_DEPTH`] for why this matters. ~keep
fn validate_expression(expression: &str) -> Result<(), CelCompileError> {
    if expression.len() > MAX_CEL_EXPRESSION_LEN {
        return Err(CelCompileError::TooLong {
            actual: expression.len(),
            max: MAX_CEL_EXPRESSION_LEN,
        });
    }

    let mut depth: usize = 0;
    let mut operators: usize = 0;
    for ch in expression.chars() {
        match ch {
            '(' | '[' | '{' => {
                depth += 1;
                if depth > MAX_CEL_NESTING_DEPTH {
                    return Err(CelCompileError::TooDeep {
                        actual: depth,
                        max: MAX_CEL_NESTING_DEPTH,
                    });
                }
            }
            ')' | ']' | '}' => {
                depth = depth.saturating_sub(1);
            }
            // ~keep Counts characters, not parsed tokens, so `&&` scores 2 and a string
            // ~keep literal containing `+` is counted too. Both directions are safe for a
            // ~keep bound whose only job is to keep the chain far below the native stack
            // ~keep limit; being approximate here is much cheaper than tokenising CEL.
            '!' | '&' | '|' | '+' | '-' | '*' | '/' | '%' | '<' | '>' | '=' | '?' => {
                operators += 1;
                if operators > MAX_CEL_OPERATOR_TOKENS {
                    return Err(CelCompileError::TooManyOperators {
                        actual: operators,
                        max: MAX_CEL_OPERATOR_TOKENS,
                    });
                }
            }
            _ => {}
        }
    }

    Ok(())
}

impl CelGuardrail {
    /// Create a new [`CelGuardrail`].
    ///
    /// `expression` is parsed and compiled at construction time.
    ///
    /// The guardrail defaults to **fail-closed**: eval errors and non-bool
    /// results return [`GuardrailDecision::Block`] with code 4001. Use
    /// [`with_fail_open`] to override.
    ///
    /// # Errors
    ///
    /// Returns an error if `expression` is not a valid CEL expression.
    pub fn new(
        name: &'static str,
        expression: &str,
        on_true: CelAction,
        stages: &'static [GuardrailStage],
    ) -> Result<Self, CelCompileError> {
        // ~keep Bound length/nesting BEFORE the parser ever sees the expression: this is the
        // only defense against a stack-overflow abort, which catch_unwind below cannot catch.
        validate_expression(expression)?;

        // ~keep Catch both parse errors and ANTLR parser panics so bad CEL cannot abort startup.
        let compiled = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| Program::compile(expression)));
        let program = match compiled {
            Ok(Ok(program)) => program,
            Ok(Err(parse_errors)) => return Err(CelCompileError::Invalid(parse_errors.to_string())),
            Err(_panic) => {
                return Err(CelCompileError::Invalid(format!(
                    "parser panicked on expression {expression:?}"
                )));
            }
        };
        Ok(Self {
            guardrail_name: name,
            program,
            on_true,
            stages,
            fail_open: false,
        })
    }

    /// Set the fail-open mode for this guardrail.
    ///
    /// When `fail_open` is `true`, runtime evaluation errors and non-bool
    /// results return [`GuardrailDecision::Allow`] instead of blocking.
    ///
    /// **SECURITY WARNING**: Only use `fail_open(true)` in non-production
    /// environments where guardrails are advisory. In production, the default
    /// fail-closed behaviour prevents eval errors from becoming a bypass vector.
    #[must_use]
    pub fn with_fail_open(mut self, fail_open: bool) -> Self {
        self.fail_open = fail_open;
        self
    }
}

impl Guardrail for CelGuardrail {
    fn name(&self) -> &'static str {
        self.guardrail_name
    }

    fn supported_stages(&self) -> &'static [GuardrailStage] {
        self.stages
    }

    fn check<'a>(
        &'a self,
        stage: GuardrailStage,
        ctx: &'a GuardrailContext<'a>,
    ) -> Pin<Box<dyn Future<Output = GuardrailDecision> + Send + 'a>> {
        Box::pin(async move {
            let mut cel_ctx = Context::default();

            cel_ctx.add_variable_from_value("request", json_value_to_cel(ctx.request));

            let response_val = ctx.response.map(json_value_to_cel).unwrap_or_else(|| {
                Value::Map(Map {
                    map: Arc::new(HashMap::new()),
                })
            });
            cel_ctx.add_variable_from_value("response", response_val);

            let chunk_str = ctx.chunk.unwrap_or("").to_string();
            cel_ctx.add_variable_from_value("chunk", Value::String(Arc::new(chunk_str)));

            cel_ctx.add_variable_from_value("metadata", metadata_to_cel(ctx.metadata));

            match self.program.execute(&cel_ctx) {
                Ok(Value::Bool(true)) => match &self.on_true {
                    CelAction::Block { code, reason } => GuardrailDecision::Block {
                        reason: reason.clone(),
                        code: *code,
                    },
                    CelAction::Mutate { new_payload } => GuardrailDecision::Mutate {
                        new_payload: new_payload.clone(),
                    },
                },

                Ok(Value::Bool(false)) => GuardrailDecision::Allow,

                Ok(non_bool) => {
                    tracing::error!(
                        guardrail = self.guardrail_name,
                        stage = ?stage,
                        result = ?non_bool,
                        "CEL expression returned non-bool value; \
                         defaulting to fail-closed (Block/4001) — \
                         set fail_open=true to suppress"
                    );

                    if self.fail_open {
                        GuardrailDecision::Allow
                    } else {
                        GuardrailDecision::Block {
                            reason: "policy evaluation error".to_owned(),
                            code: CEL_EVAL_ERROR_CODE,
                        }
                    }
                }

                Err(e) => {
                    tracing::error!(
                        guardrail = self.guardrail_name,
                        stage = ?stage,
                        error = %e,
                        "CEL expression evaluation error; \
                         defaulting to fail-closed (Block/4001) — \
                         set fail_open=true to suppress"
                    );

                    if self.fail_open {
                        GuardrailDecision::Allow
                    } else {
                        GuardrailDecision::Block {
                            reason: "policy evaluation error".to_owned(),
                            code: CEL_EVAL_ERROR_CODE,
                        }
                    }
                }
            }
        })
    }
}

/// Convert a [`serde_json::Value`] to a CEL [`Value`].
///
/// Complex nested objects become CEL maps; arrays become CEL lists.
fn json_value_to_cel(value: &serde_json::Value) -> Value {
    match value {
        serde_json::Value::Null => Value::Null,
        serde_json::Value::Bool(b) => Value::Bool(*b),
        serde_json::Value::Number(n) => {
            if let Some(i) = n.as_i64() {
                Value::Int(i)
            } else if let Some(f) = n.as_f64() {
                Value::Float(f)
            } else {
                Value::Null
            }
        }
        serde_json::Value::String(s) => Value::String(Arc::new(s.clone())),
        serde_json::Value::Array(arr) => {
            let items: Vec<Value> = arr.iter().map(json_value_to_cel).collect();
            Value::List(Arc::new(items))
        }
        serde_json::Value::Object(obj) => {
            let mut map: HashMap<Key, Value> = HashMap::new();
            for (key, val) in obj {
                map.insert(Key::String(Arc::new(key.clone())), json_value_to_cel(val));
            }
            Value::Map(Map { map: Arc::new(map) })
        }
    }
}

/// Convert a `HashMap<String, String>` metadata map to a CEL [`Value::Map`].
fn metadata_to_cel(metadata: &HashMap<String, String>) -> Value {
    let mut map: HashMap<Key, Value> = HashMap::new();
    for (key, val) in metadata {
        map.insert(Key::String(Arc::new(key.clone())), Value::String(Arc::new(val.clone())));
    }
    Value::Map(Map { map: Arc::new(map) })
}

#[cfg(test)]
mod tests {
    use std::collections::HashMap;

    use super::*;
    use crate::guardrail::{GuardrailContext, GuardrailStage};

    static INPUT_STAGES: &[GuardrailStage] = &[GuardrailStage::Input];

    fn meta_with(pairs: &[(&str, &str)]) -> HashMap<String, String> {
        pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect()
    }

    #[tokio::test]
    async fn cel_guardrail_blocks_when_expression_is_true() {
        let meta = meta_with(&[("tier", "free")]);
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "gpt4o-premium-only",
            r#"request.model == "gpt-4o" && metadata.tier != "premium""#,
            CelAction::Block {
                code: 1300,
                reason: "gpt-4o requires premium tier".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        match decision {
            GuardrailDecision::Block { code, reason } => {
                assert_eq!(code, 1300);
                assert!(reason.contains("premium"), "reason should mention premium tier");
            }
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn cel_guardrail_allows_when_expression_is_false() {
        let meta = meta_with(&[("tier", "premium")]);
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "gpt4o-premium-only",
            r#"request.model == "gpt-4o" && metadata.tier != "premium""#,
            CelAction::Block {
                code: 1300,
                reason: "gpt-4o requires premium tier".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        assert!(decision.is_allow(), "premium tier should be allowed");
    }

    #[tokio::test]
    async fn cel_guardrail_allows_when_model_does_not_match() {
        let meta = meta_with(&[("tier", "free")]);
        let req = serde_json::json!({ "model": "gpt-3.5-turbo" });

        let guardrail = CelGuardrail::new(
            "gpt4o-premium-only",
            r#"request.model == "gpt-4o" && metadata.tier != "premium""#,
            CelAction::Block {
                code: 1300,
                reason: "gpt-4o requires premium tier".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        assert!(
            decision.is_allow(),
            "non-gpt-4o model should be allowed regardless of tier"
        );
    }

    #[tokio::test]
    async fn cel_guardrail_returns_error_for_invalid_expression() {
        let result = CelGuardrail::new(
            "broken",
            "this is not valid !!! CEL $$$",
            CelAction::Block {
                code: 1399,
                reason: "test".into(),
            },
            INPUT_STAGES,
        );
        assert!(result.is_err(), "invalid CEL should fail at construction");
    }

    #[tokio::test]
    async fn cel_guardrail_simple_boolean_true_expression_blocks() {
        let meta = HashMap::new();
        let req = serde_json::json!({});

        let guardrail = CelGuardrail::new(
            "always-block",
            "true",
            CelAction::Block {
                code: 1399,
                reason: "always blocked".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };
        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        assert!(decision.is_block());
    }

    #[tokio::test]
    async fn cel_guardrail_simple_boolean_false_expression_allows() {
        let meta = HashMap::new();
        let req = serde_json::json!({});

        let guardrail = CelGuardrail::new(
            "never-block",
            "false",
            CelAction::Block {
                code: 1399,
                reason: "never blocked".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };
        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        assert!(decision.is_allow());
    }

    /// A CEL expression that references an undeclared variable triggers an
    /// `ExecutionError::UndeclaredReference` at eval time. Default (fail-closed)
    /// must return Block/4001.
    #[tokio::test]
    async fn cel_guardrail_eval_error_defaults_to_block() {
        let meta = HashMap::new();
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "undeclared-var-guardrail",
            "undeclared_var == true",
            CelAction::Block {
                code: 1500,
                reason: "blocked by policy".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        match decision {
            GuardrailDecision::Block { code, reason } => {
                assert_eq!(code, CEL_EVAL_ERROR_CODE, "eval error must use code 4001");
                assert_eq!(
                    reason, "policy evaluation error",
                    "eval error reason must be opaque; got: {reason}"
                );
                assert!(
                    !reason.contains("guardrail evaluation error"),
                    "old verbose reason must not appear in caller response; got: {reason}"
                );
            }
            other => panic!("expected Block(4001) on eval error (fail-closed default), got {other:?}"),
        }
    }

    /// Same eval-error scenario, but with `with_fail_open(true)`: must return Allow.
    #[tokio::test]
    async fn cel_guardrail_eval_error_with_fail_open_returns_allow() {
        let meta = HashMap::new();
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "undeclared-var-fail-open",
            "undeclared_var == true",
            CelAction::Block {
                code: 1500,
                reason: "blocked by policy".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression")
        .with_fail_open(true);

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        assert!(
            decision.is_allow(),
            "with_fail_open(true) must return Allow on eval error, got {decision:?}"
        );
    }

    /// An expression that returns a string (non-bool) must Block by default.
    /// With fail_open=true it must Allow.
    #[tokio::test]
    async fn cel_guardrail_non_bool_result_blocks_by_default() {
        let meta = HashMap::new();
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail_default = CelGuardrail::new(
            "non-bool-default",
            "request.model",
            CelAction::Block {
                code: 1500,
                reason: "blocked by policy".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let guardrail_fail_open = CelGuardrail::new(
            "non-bool-fail-open",
            "request.model",
            CelAction::Block {
                code: 1500,
                reason: "blocked by policy".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression")
        .with_fail_open(true);

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision_default = guardrail_default.check(GuardrailStage::Input, &ctx).await;
        match &decision_default {
            GuardrailDecision::Block { code, .. } => {
                assert_eq!(*code, CEL_EVAL_ERROR_CODE, "non-bool must use code 4001");
            }
            other => panic!("expected Block(4001) for non-bool result (fail-closed default), got {other:?}"),
        }

        let decision_open = guardrail_fail_open.check(GuardrailStage::Input, &ctx).await;
        assert!(
            decision_open.is_allow(),
            "fail_open=true must return Allow for non-bool result, got {decision_open:?}"
        );
    }

    /// Malformed CEL expression must fail at construction time (existing behaviour preserved).
    #[tokio::test]
    async fn cel_guardrail_compile_error_still_blocks_construction() {
        let result = CelGuardrail::new(
            "bad-syntax",
            "request.model ==",
            CelAction::Block {
                code: 1399,
                reason: "test".into(),
            },
            INPUT_STAGES,
        );
        assert!(
            result.is_err(),
            "malformed CEL expression must fail at construction, not at eval time"
        );
    }

    /// Induce a CEL eval error via an undeclared variable reference and assert
    /// that the reason returned to the caller is the opaque sentinel string,
    /// NOT the internal `format!("guardrail evaluation error: {e}")` form.
    ///
    /// This prevents CEL runtime errors (which can reflect user-controlled
    /// expression internals) from reaching the API caller.
    #[tokio::test]
    async fn cel_error_reason_not_leaked_to_caller() {
        let meta = HashMap::new();
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "leaky-error-guardrail",
            "undeclared_internal_var == true",
            CelAction::Block {
                code: 1500,
                reason: "should not appear — error path taken".into(),
            },
            INPUT_STAGES,
        )
        .expect("syntactically valid CEL");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        match decision {
            GuardrailDecision::Block { code, reason } => {
                assert_eq!(code, CEL_EVAL_ERROR_CODE, "eval error must use code 4001");

                assert_eq!(
                    reason, "policy evaluation error",
                    "reason must be opaque sentinel, not internal error detail; got: {reason:?}"
                );

                assert!(
                    !reason.contains("guardrail evaluation error"),
                    "old verbose reason must not leak to caller; got: {reason:?}"
                );

                assert!(
                    !reason.contains("undeclared_internal_var"),
                    "internal CEL variable name must not leak to caller; got: {reason:?}"
                );
            }
            other => panic!("expected Block(4001) from eval error, got {other:?}"),
        }
    }

    /// Same test for the non-bool result path: a CEL expression that returns
    /// a string must produce the opaque reason, not the actual CEL result value.
    #[tokio::test]
    async fn cel_non_bool_reason_not_leaked_to_caller() {
        let meta = HashMap::new();
        let req = serde_json::json!({ "model": "gpt-4o" });

        let guardrail = CelGuardrail::new(
            "non-bool-leak-check",
            "request.model",
            CelAction::Block {
                code: 1500,
                reason: "should not appear".into(),
            },
            INPUT_STAGES,
        )
        .expect("valid CEL expression");

        let ctx = GuardrailContext {
            request: &req,
            response: None,
            chunk: None,
            metadata: &meta,
        };

        let decision = guardrail.check(GuardrailStage::Input, &ctx).await;
        match decision {
            GuardrailDecision::Block { code, reason } => {
                assert_eq!(code, CEL_EVAL_ERROR_CODE);
                assert_eq!(
                    reason, "policy evaluation error",
                    "non-bool reason must be opaque; got: {reason:?}"
                );
                assert!(
                    !reason.contains("gpt-4o"),
                    "CEL result value must not leak to caller; got: {reason:?}"
                );
            }
            other => panic!("expected Block(4001), got {other:?}"),
        }
    }

    /// A short expression that nests `(` far past [`MAX_CEL_NESTING_DEPTH`] must be
    /// rejected by depth bounding — proving the nesting check fires independently
    /// of the length check (an attacker packing deep nesting into few bytes cannot
    /// slip past a length-only guard).
    #[tokio::test]
    async fn cel_guardrail_rejects_deeply_nested_expression_without_reaching_parser() {
        let depth = MAX_CEL_NESTING_DEPTH + 1;
        let expression = format!("{}true{}", "(".repeat(depth), ")".repeat(depth));
        assert!(
            expression.len() < MAX_CEL_EXPRESSION_LEN,
            "test expression must stay under the length bound so only depth is exercised"
        );

        let result = CelGuardrail::new(
            "too-deep",
            &expression,
            CelAction::Block {
                code: 1399,
                reason: "test".into(),
            },
            INPUT_STAGES,
        );

        match result {
            Err(CelCompileError::TooDeep { actual, max }) => {
                assert_eq!(max, MAX_CEL_NESTING_DEPTH);
                assert!(actual > max, "reported depth {actual} should exceed the limit {max}");
            }
            Ok(_) => panic!("expected CelCompileError::TooDeep, got a compiled guardrail"),
            Err(other) => panic!("expected CelCompileError::TooDeep, got {other:?}"),
        }
    }

    /// A flat (unnested) expression whose length alone exceeds
    /// [`MAX_CEL_EXPRESSION_LEN`] must be rejected before parsing.
    #[tokio::test]
    async fn cel_guardrail_rejects_oversized_expression_without_reaching_parser() {
        let filler = "a".repeat(MAX_CEL_EXPRESSION_LEN + 1);
        let expression = format!("\"{filler}\" == \"{filler}\"");

        let result = CelGuardrail::new(
            "too-long",
            &expression,
            CelAction::Block {
                code: 1399,
                reason: "test".into(),
            },
            INPUT_STAGES,
        );

        match result {
            Err(CelCompileError::TooLong { actual, max }) => {
                assert_eq!(max, MAX_CEL_EXPRESSION_LEN);
                assert!(actual > max, "reported length {actual} should exceed the limit {max}");
            }
            Ok(_) => panic!("expected CelCompileError::TooLong, got a compiled guardrail"),
            Err(other) => panic!("expected CelCompileError::TooLong, got {other:?}"),
        }
    }

    /// Regression for the claimed stack-overflow-abort vector (~5000 nested
    /// parentheses). This does NOT prove the abort itself reproduces — that is
    /// unverified and cannot be verified without running the parser under a
    /// crash-observing harness. It proves the defensive bound rejects this
    /// exact input shape with a typed error, quickly, before the expression
    /// ever reaches `Program::compile`.
    #[tokio::test]
    async fn cel_guardrail_rejects_five_thousand_nested_parens() {
        let expression = format!("{}true{}", "(".repeat(5000), ")".repeat(5000));

        let result = CelGuardrail::new(
            "pathological-nesting",
            &expression,
            CelAction::Block {
                code: 1399,
                reason: "test".into(),
            },
            INPUT_STAGES,
        );

        assert!(
            result.is_err(),
            "5000 nested parens must be rejected before reaching the CEL parser"
        );
    }

    /// A recursive-descent grammar descends once per operator in an
    /// unparenthesized chain, so these reach thousands of parser frames at a
    /// bracket depth of zero — inside `MAX_CEL_EXPRESSION_LEN` and invisible to
    /// the nesting-depth cap, which counts only brackets. Same stack-exhaustion
    /// abort as the nested-paren case, reached by a shape the depth cap alone
    /// does not see.
    #[tokio::test]
    async fn cel_guardrail_rejects_long_operator_chains_that_bracket_depth_cannot_see() {
        for expression in [
            "!".repeat(2000) + "true",
            "true".to_owned() + &"&&true".repeat(600),
            "1".to_owned() + &"+1".repeat(1500),
        ] {
            assert_eq!(
                count_brackets(&expression),
                0,
                "the chain must stay at bracket depth zero, or it would be caught by the \
                 depth cap and this test would prove nothing"
            );

            let result = CelGuardrail::new(
                "pathological-operator-chain",
                &expression,
                CelAction::Block {
                    code: 1399,
                    reason: "test".into(),
                },
                INPUT_STAGES,
            );

            // ~keep `CelGuardrail` has no `Debug`, so the Ok arm cannot be formatted;
            // ~keep match rather than `assert!(matches!(..), "{result:?}")`.
            match result {
                Err(CelCompileError::TooManyOperators { .. }) => {}
                Ok(_) => panic!("an operator chain must be rejected before reaching the CEL parser"),
                Err(other) => panic!("expected TooManyOperators, got {other:?}"),
            }
        }
    }

    fn count_brackets(expression: &str) -> usize {
        expression.chars().filter(|c| matches!(c, '(' | '[' | '{')).count()
    }
}