camel_language_jsonpath/

lib.rs

//! JSONPath language for rust-camel — evaluates `jsonpath_rust` queries against exchange bodies.
//!
//! Main types: `JsonPathLanguage`, `JsonPathConfig`, `JsonPathExpression`, `JsonPathPredicate`.
//! Provides expressions and predicates for JSON-based routing and transformation.

use async_trait::async_trait;
use camel_language_api::{Body, Exchange, ExpressionErrorClass, Value};
use camel_language_api::{Expression, Language, LanguageError, Predicate};
use jsonpath_rust::parser::model::JpQuery;
use jsonpath_rust::parser::parse_json_path;
use jsonpath_rust::query::js_path_process;
use serde_json::Value as JsonValue;
#[cfg(test)]
thread_local! {
    static COMPILE_COUNT: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

/// Default maximum nesting depth for JSON values.
const DEFAULT_MAX_DEPTH: usize = 64;

/// Default maximum input size in bytes for text-to-JSON conversion (M-L2).
/// Matches the spirit of the XPath language's input cap.
const DEFAULT_MAX_INPUT_BYTES: usize = 16 * 1024 * 1024; // 16 MiB

/// How a JSONPath predicate converts its query result to a boolean.
///
/// Selected through [`JsonPathConfig::predicate_mode`].
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum JsonPathPredicateMode {
    /// Only a JSON boolean result is a valid predicate result. Any other
    /// value kind is a `type-mismatch` error; no truthiness coercion is
    /// applied (change `language-value-boundary`, sealed Q3).
    #[default]
    Strict,
    /// Cardinality coercion over the raw match sequence: zero matches
    /// (including a missing path) are `false`; exactly one boolean match is
    /// that boolean; every other non-empty match sequence is `true`. No
    /// value-based truthiness is imported (empty strings and `0` stay
    /// `true` — this is not XPath `boolean()` value semantics).
    Matches,
}

/// Configuration for [`JsonPathLanguage`] resource limits.
#[derive(Debug, Clone)]
pub struct JsonPathConfig {
    /// Maximum allowed input size in bytes for text-to-JSON conversion.
    /// When `None`, no size limit is enforced.
    pub max_input_bytes: Option<usize>,
    /// Maximum allowed nesting depth for JSON values.
    /// Defaults to `DEFAULT_MAX_DEPTH` (64).
    pub max_depth: Option<usize>,
    /// Predicate conversion mode. Defaults to
    /// [`JsonPathPredicateMode::Strict`].
    pub predicate_mode: JsonPathPredicateMode,
}

impl JsonPathConfig {
    /// Returns the effective max depth, applying the default when not explicitly set.
    fn effective_max_depth(&self) -> usize {
        self.max_depth.unwrap_or(DEFAULT_MAX_DEPTH)
    }
}

impl Default for JsonPathConfig {
    fn default() -> Self {
        Self {
            max_input_bytes: Some(DEFAULT_MAX_INPUT_BYTES),
            max_depth: None,
            predicate_mode: JsonPathPredicateMode::default(),
        }
    }
}

/// JSONPath language implementation for rust-camel.
pub struct JsonPathLanguage {
    config: JsonPathConfig,
}

impl JsonPathLanguage {
    /// Create a new instance with default configuration.
    pub fn new() -> Self {
        Self {
            config: JsonPathConfig::default(),
        }
    }

    /// Create a new instance with the given configuration.
    pub fn with_config(config: JsonPathConfig) -> Self {
        Self { config }
    }
}

impl Default for JsonPathLanguage {
    fn default() -> Self {
        Self::new()
    }
}

struct JsonPathExpression {
    query: JpQuery,
    config: JsonPathConfig,
}

struct JsonPathPredicate {
    query: JpQuery,
    config: JsonPathConfig,
}

/// Check that a [`JsonValue`] does not exceed the given nesting depth.
fn check_depth(value: &JsonValue, max_depth: usize) -> Result<(), LanguageError> {
    fn recurse(value: &JsonValue, max_depth: usize, current: usize) -> Result<(), LanguageError> {
        if current > max_depth {
            return Err(LanguageError::EvalError(format!(
                "JSON nesting depth {current} exceeds limit of {max_depth}"
            )));
        }
        match value {
            JsonValue::Object(map) => {
                for v in map.values() {
                    recurse(v, max_depth, current + 1)?;
                }
                Ok(())
            }
            JsonValue::Array(arr) => {
                for v in arr {
                    recurse(v, max_depth, current + 1)?;
                }
                Ok(())
            }
            _ => Ok(()),
        }
    }
    recurse(value, max_depth, 0)
}

/// Extract and validate JSON from an exchange body.
///
/// Applies resource limits from `config`:
/// - `max_input_bytes` is checked against text body length before parsing.
/// - `max_depth` is checked against the resulting JSON value (both pre-parsed and newly-parsed).
fn extract_json(exchange: &Exchange, config: &JsonPathConfig) -> Result<JsonValue, LanguageError> {
    let max_depth = config.effective_max_depth();

    match &exchange.input.body {
        Body::Json(v) => {
            // Already-parsed JSON: check depth only (no input_bytes limit applies).
            check_depth(v, max_depth)?;
            Ok(v.clone())
        }
        Body::Text(s) => {
            // Check input size before parsing.
            if let Some(limit) = config.max_input_bytes
                && s.len() > limit
            {
                return Err(LanguageError::EvalError(format!(
                    "input size {} bytes exceeds limit of {limit} bytes",
                    s.len()
                )));
            }
            // Redacted: serde's Display can quote a body fragment. Class +
            // static detail only (change `language-value-boundary`).
            let value: JsonValue =
                serde_json::from_str(s).map_err(|_| LanguageError::EvalFailure {
                    class: ExpressionErrorClass::Conversion,
                    position: None,
                    detail: Some("body is not valid JSON".to_string()),
                })?;
            check_depth(&value, max_depth)?;
            Ok(value)
        }
        other => other
            .clone()
            .try_into_json()
            .map_err(|e| {
                LanguageError::EvalError(format!("body is not JSON and cannot be coerced: {e}"))
            })
            .and_then(|b| match b {
                Body::Json(v) => {
                    check_depth(&v, max_depth)?;
                    Ok(v)
                }
                _ => Err(LanguageError::EvalError(
                    "body coercion did not produce JSON".into(),
                )),
            }),
    }
}

/// Run a parsed JSONPath query and return every raw match in order.
fn run_query_all(query: &JpQuery, json: &JsonValue) -> Result<Vec<JsonValue>, LanguageError> {
    let results = js_path_process(query, json)
        .map_err(|e| LanguageError::EvalError(format!("jsonpath query '{query}' failed: {e}")))?;
    Ok(results.into_iter().map(|r| r.val.clone()).collect())
}

/// Collapse the raw match sequence into the value-source result shape:
/// zero matches are `null`, a single match keeps its type, and multiple
/// matches become an array.
fn run_query(query: &JpQuery, json: &JsonValue) -> Result<JsonValue, LanguageError> {
    let values = run_query_all(query, json)?;
    Ok(match values.as_slice() {
        [] => JsonValue::Null,
        [one] => one.clone(),
        _ => JsonValue::Array(values),
    })
}

#[async_trait]
impl Expression for JsonPathExpression {
    // TODO(JPT-004): The return type is currently raw serde_json::Value. For better
    // interoperability with Camel routing (e.g. header assignments, simple expressions),
    // the result should be coerced: single scalars unwrapped to their native types
    // (string, number, bool), arrays preserved, and Null mapped to a clear sentinel.
    async fn evaluate(&self, exchange: &Exchange) -> Result<Value, LanguageError> {
        let json = extract_json(exchange, &self.config)?;
        run_query(&self.query, &json)
    }
}

#[async_trait]
impl Predicate for JsonPathPredicate {
    async fn matches(&self, exchange: &Exchange) -> Result<bool, LanguageError> {
        let json = extract_json(exchange, &self.config)?;
        match self.config.predicate_mode {
            JsonPathPredicateMode::Matches => {
                // Cardinality coercion over the raw match sequence, before
                // value-source normalization: zero matches (missing path) are
                // false, a sole boolean keeps its value (a literal `false`
                // stays false), and every other non-empty sequence is true.
                let values = run_query_all(&self.query, &json)?;
                Ok(match values.as_slice() {
                    [] => false,
                    [JsonValue::Bool(b)] => *b,
                    _ => true,
                })
            }
            JsonPathPredicateMode::Strict => {
                let result = run_query(&self.query, &json)?;
                // Strict bool: only a JSON boolean is a valid predicate
                // result. No truthiness coercion — `"false"`, `0`, `[]`,
                // `{}`, and `null` are all type errors (change
                // `language-value-boundary`, sealed Q3).
                match &result {
                    JsonValue::Bool(b) => Ok(*b),
                    other => Err(LanguageError::TypeMismatch {
                        expected: "bool".to_string(),
                        actual: json_type_name(other).to_string(),
                        position: None,
                    }),
                }
            }
        }
    }
}

/// Type name of a [`JsonValue`] for `TypeMismatch` diagnostics. Type names
/// only — never runtime values.
fn json_type_name(value: &JsonValue) -> &'static str {
    match value {
        JsonValue::Null => "null",
        JsonValue::Bool(_) => "bool",
        JsonValue::Number(_) => "number",
        JsonValue::String(_) => "string",
        JsonValue::Array(_) => "array",
        JsonValue::Object(_) => "object",
    }
}

impl Language for JsonPathLanguage {
    fn name(&self) -> &'static str {
        "jsonpath"
    }

    fn create_expression(&self, script: &str) -> Result<Box<dyn Expression>, LanguageError> {
        if !script.starts_with('$') {
            return Err(LanguageError::ParseError {
                expr: script.to_string(),
                reason: "JsonPath expression must start with '$'".into(),
            });
        }
        let parsed = parse_json_path(script).map_err(|e| LanguageError::ParseError {
            expr: script.to_string(),
            reason: e.to_string(),
        })?;
        #[cfg(test)]
        {
            COMPILE_COUNT.with(|c| c.set(c.get() + 1));
        }
        Ok(Box::new(JsonPathExpression {
            query: parsed,
            config: self.config.clone(),
        }))
    }

    fn create_predicate(&self, script: &str) -> Result<Box<dyn Predicate>, LanguageError> {
        if !script.starts_with('$') {
            return Err(LanguageError::ParseError {
                expr: script.to_string(),
                reason: "JsonPath expression must start with '$'".into(),
            });
        }
        let parsed = parse_json_path(script).map_err(|e| LanguageError::ParseError {
            expr: script.to_string(),
            reason: e.to_string(),
        })?;
        #[cfg(test)]
        {
            COMPILE_COUNT.with(|c| c.set(c.get() + 1));
        }
        Ok(Box::new(JsonPathPredicate {
            query: parsed,
            config: self.config.clone(),
        }))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use camel_language_api::Message;

    async fn exchange_with_json(json: &str) -> Exchange {
        let value: JsonValue = serde_json::from_str(json).unwrap();
        Exchange::new(Message::new(Body::Json(value)))
    }

    async fn exchange_with_text_body(text: &str) -> Exchange {
        Exchange::new(Message::new(Body::Text(text.to_string())))
    }

    async fn empty_exchange() -> Exchange {
        Exchange::new(Message::default())
    }

    async fn default_lang() -> JsonPathLanguage {
        JsonPathLanguage::new()
    }

    #[tokio::test]
    async fn expression_simple_path() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.store.name").unwrap();
        let ex = exchange_with_json(r#"{"store":{"name":"books"}}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::String("books".to_string()));
    }

    #[tokio::test]
    async fn expression_nested_path() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.a.b.c").unwrap();
        let ex = exchange_with_json(r#"{"a":{"b":{"c":42}}}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::Number(42.into()));
    }

    #[tokio::test]
    async fn expression_array_index() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.items[0]").unwrap();
        let ex = exchange_with_json(r#"{"items":["a","b","c"]}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::String("a".to_string()));
    }

    #[tokio::test]
    async fn expression_wildcard() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.items[*].name").unwrap();
        let ex = exchange_with_json(r#"{"items":[{"name":"a"},{"name":"b"}]}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(
            result,
            JsonValue::Array(vec![
                JsonValue::String("a".to_string()),
                JsonValue::String("b".to_string())
            ])
        );
    }

    #[tokio::test]
    async fn expression_root_path() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$").unwrap();
        let ex = exchange_with_json(r#"{"x":1}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result["x"], JsonValue::Number(1.into()));
    }

    #[tokio::test]
    async fn expression_text_body_with_valid_json() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.name").unwrap();
        let ex = exchange_with_text_body(r#"{"name":"test"}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::String("test".to_string()));
    }

    #[tokio::test]
    async fn expression_empty_body_is_error() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.x").unwrap();
        let ex = empty_exchange().await;
        let result = expr.evaluate(&ex).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn expression_invalid_jsonpath_syntax() {
        let lang = default_lang().await;
        let result = lang.create_expression("$[invalid");
        let err = match result {
            Err(e) => e,
            Ok(_) => panic!("expected ParseError"),
        };
        match err {
            LanguageError::ParseError { expr, reason } => {
                assert!(!expr.is_empty());
                assert!(!reason.is_empty());
            }
            other => panic!("expected ParseError, got {other:?}"),
        }
    }

    // --- JPT-005: $ prefix validation ---

    #[tokio::test]
    async fn expression_without_dollar_prefix_is_rejected() {
        let lang = default_lang().await;
        let result = lang.create_expression("store.name");
        assert!(result.is_err(), "expected error for missing $ prefix");
        let err = match result {
            Err(e) => e,
            Ok(_) => panic!("expected ParseError"),
        };
        match err {
            LanguageError::ParseError { expr, reason } => {
                assert_eq!(expr, "store.name");
                assert!(
                    reason.contains("'$'"),
                    "reason should mention '$', got: {reason}"
                );
            }
            other => panic!("expected ParseError, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn predicate_without_dollar_prefix_is_rejected() {
        let lang = default_lang().await;
        let result = lang.create_predicate("store.name");
        assert!(result.is_err(), "expected error for missing $ prefix");
        let err = match result {
            Err(e) => e,
            Ok(_) => panic!("expected ParseError"),
        };
        match err {
            LanguageError::ParseError { reason, .. } => {
                assert!(
                    reason.contains("'$'"),
                    "reason should mention '$', got: {reason}"
                );
            }
            other => panic!("expected ParseError, got {other:?}"),
        }
    }

    // --- JPT-006: Nested path and array index tests ---

    #[tokio::test]
    async fn expression_deeply_nested_path() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.a.b.c.d").unwrap();
        let ex = exchange_with_json(r#"{"a":{"b":{"c":{"d":"deep"}}}}"#).await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::String("deep".to_string()));
    }

    #[tokio::test]
    async fn expression_array_index_nested() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.data.items[1].name").unwrap();
        let ex = exchange_with_json(
            r#"{"data":{"items":[{"name":"first"},{"name":"second"},{"name":"third"}]}}"#,
        )
        .await;
        let result = expr.evaluate(&ex).await.unwrap();
        assert_eq!(result, JsonValue::String("second".to_string()));
    }

    #[tokio::test]
    async fn jsonpath_predicate_non_bool_is_type_mismatch() {
        // Sealed Q3: only JSON booleans are valid predicate results. Strings,
        // numbers, arrays, objects, and null are all type errors — including
        // the old `[]` false vs `{}` true asymmetry.
        let lang = default_lang().await;
        for (json_body, actual) in [
            (r#"{"val":"false"}"#, "string"),
            (r#"{"val":"x"}"#, "string"),
            (r#"{"val":0}"#, "number"),
            (r#"{"val":1}"#, "number"),
            (r#"{"val":[]}"#, "array"),
            (r#"{"val":{}}"#, "object"),
            (r#"{"other":1}"#, "null"),
        ] {
            let pred = lang.create_predicate("$.val").unwrap();
            let ex = exchange_with_json(json_body).await;
            match pred.matches(&ex).await {
                Err(LanguageError::TypeMismatch {
                    expected,
                    actual: got,
                    position: None,
                }) => {
                    assert_eq!(expected, "bool");
                    assert_eq!(got, actual, "body {json_body}");
                }
                other => panic!("expected TypeMismatch for {json_body}, got: {other:?}"),
            }
        }

        // Real booleans still work.
        let pred = lang.create_predicate("$.active").unwrap();
        assert!(
            pred.matches(&exchange_with_json(r#"{"active":true}"#).await)
                .await
                .unwrap()
        );
        let pred = lang.create_predicate("$.active").unwrap();
        assert!(
            !pred
                .matches(&exchange_with_json(r#"{"active":false}"#).await)
                .await
                .unwrap()
        );
    }

    #[tokio::test]
    async fn jsonpath_invalid_body_error_is_conversion_class_no_snippet() {
        let lang = default_lang().await;
        let expr = lang.create_expression("$.key").unwrap();
        let mut ex = Exchange::new(Message::default());
        ex.input.body = Body::Text("SECRETVAL not json".to_string());
        let err = expr.evaluate(&ex).await.expect_err("must fail");
        match &err {
            LanguageError::EvalFailure {
                class: ExpressionErrorClass::Conversion,
                position: None,
                detail: Some(detail),
            } => {
                assert_eq!(detail, "body is not valid JSON");
            }
            other => panic!("expected Conversion EvalFailure, got: {other:?}"),
        }
        assert!(!err.to_string().contains("SECRETVAL"), "body leaked: {err}");
    }

    // --- Resource limit tests (A-26) ---

    #[tokio::test]
    async fn oversized_input_is_rejected() {
        let config = JsonPathConfig {
            max_input_bytes: Some(100),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let expr = lang.create_expression("$.key").unwrap();
        // Build a valid JSON string that exceeds 100 bytes
        let big_value = "x".repeat(200);
        let big_json = format!(r#"{{"key":"{}"}}"#, big_value);
        assert!(big_json.len() > 100);
        let ex = exchange_with_text_body(&big_json).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_err(),
            "expected error for oversized input, got {result:?}"
        );
    }

    #[tokio::test]
    async fn input_under_limit_is_accepted() {
        let config = JsonPathConfig {
            max_input_bytes: Some(1024),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let expr = lang.create_expression("$.key").unwrap();
        let ex = exchange_with_text_body(r#"{"key":"value"}"#).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_ok(),
            "expected success for input under limit, got {result:?}"
        );
    }

    #[tokio::test]
    async fn deeply_nested_input_is_rejected() {
        let config = JsonPathConfig {
            max_depth: Some(5),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let expr = lang.create_expression("$.a").unwrap();
        // Build nesting of depth 10: {"a":{"a":{"a":...}}}
        let mut json = "1".to_string();
        for _ in 0..10 {
            json = format!(r#"{{"a":{json}}}"#);
        }
        let ex = exchange_with_text_body(&json).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_err(),
            "expected error for deeply nested input, got {result:?}"
        );
    }

    #[tokio::test]
    async fn nesting_within_depth_limit_is_accepted() {
        let config = JsonPathConfig {
            max_depth: Some(10),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let expr = lang.create_expression("$.a").unwrap();
        // Build nesting of depth 5
        let mut json = "1".to_string();
        for _ in 0..5 {
            json = format!(r#"{{"a":{json}}}"#);
        }
        let ex = exchange_with_text_body(&json).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_ok(),
            "expected success for nesting within limit, got {result:?}"
        );
    }

    #[tokio::test]
    async fn default_config_has_safe_defaults() {
        // M-L2: max_input_bytes defaults to 16 MiB (was None).
        let config = JsonPathConfig::default();
        assert_eq!(config.max_input_bytes, Some(16 * 1024 * 1024));
        // max_depth still defaults to DEFAULT_MAX_DEPTH via effective_max_depth().
        assert_eq!(config.max_depth, None);
    }

    #[tokio::test]
    async fn default_config_rejects_oversized_text_body() {
        // Default config must reject a >16 MiB text body without an explicit cap.
        let lang = JsonPathLanguage::new(); // default config
        let expr = lang.create_expression("$.key").unwrap();
        let big_value = "x".repeat(16 * 1024 * 1024 + 10);
        let big_json = format!(r#"{{"key":"{}"}}"#, big_value);
        let ex = exchange_with_text_body(&big_json).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_err(),
            "default config must reject oversized input, got {result:?}"
        );
    }

    #[tokio::test]
    async fn oversized_input_also_rejected_for_predicate() {
        let config = JsonPathConfig {
            max_input_bytes: Some(100),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let pred = lang.create_predicate("$.key").unwrap();
        let big_value = "x".repeat(200);
        let big_json = format!(r#"{{"key":"{}"}}"#, big_value);
        let ex = exchange_with_text_body(&big_json).await;
        let result = pred.matches(&ex).await;
        assert!(
            result.is_err(),
            "expected error for oversized input in predicate, got {result:?}"
        );
    }

    #[tokio::test]
    async fn deeply_nested_input_rejected_for_predicate() {
        let config = JsonPathConfig {
            max_depth: Some(3),
            ..Default::default()
        };
        let lang = JsonPathLanguage::with_config(config);
        let pred = lang.create_predicate("$.a").unwrap();
        let mut json = "1".to_string();
        for _ in 0..5 {
            json = format!(r#"{{"a":{json}}}"#);
        }
        let ex = exchange_with_text_body(&json).await;
        let result = pred.matches(&ex).await;
        assert!(
            result.is_err(),
            "expected error for deeply nested input in predicate, got {result:?}"
        );
    }

    #[tokio::test]
    async fn body_json_no_input_size_check_but_depth_checked() {
        // When body is already Body::Json (already parsed), skip input_bytes check
        // but still enforce depth limit
        let config = JsonPathConfig {
            max_input_bytes: Some(10), // very small — but body is already JSON
            max_depth: Some(3),
            predicate_mode: JsonPathPredicateMode::Strict,
        };
        let lang = JsonPathLanguage::with_config(config);
        let expr = lang.create_expression("$.a").unwrap();
        // Build a JSON value with nesting depth 5
        let mut json_str = "1".to_string();
        for _ in 0..5 {
            json_str = format!(r#"{{"a":{json_str}}}"#);
        }
        let ex = exchange_with_json(&json_str).await;
        let result = expr.evaluate(&ex).await;
        assert!(
            result.is_err(),
            "expected depth error for pre-parsed JSON, got {result:?}"
        );
    }

    // --- FC-LANG-RECOMPILE: compile-once regression tests ---

    /// Compile-time assertion that the compile-once implementation
    /// produces `Send + Sync` types, matching the `Expression` /
    /// `Predicate` trait contract.
    #[test]
    fn compile_once_types_are_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<JsonPathExpression>();
        assert_send_sync::<JsonPathPredicate>();
        assert_send_sync::<JpQuery>();
    }

    /// Regression test for FC-LANG-RECOMPILE: `create_expression` and
    /// `create_predicate` must parse the script exactly once at creation
    /// time. Re-evaluating the resulting `Expression` / `Predicate`
    /// against new exchanges must NOT re-parse the query. The
    /// `COMPILE_COUNT` thread-local is incremented inside
    /// `create_expression` / `create_predicate` under `#[cfg(test)]`, so
    /// a re-introduction of per-evaluation compilation would show up as
    /// additional increments on this thread.
    #[tokio::test]
    async fn compilation_happens_only_once_for_expression() {
        let before = COMPILE_COUNT.with(std::cell::Cell::get);
        let lang = JsonPathLanguage::new();
        let expr = lang.create_expression("$.foo.bar").unwrap();
        let after_create = COMPILE_COUNT.with(std::cell::Cell::get);
        assert_eq!(
            after_create,
            before + 1,
            "create_expression must compile exactly once"
        );

        // Evaluate many times — compilation count must stay flat.
        for _ in 0..50 {
            let ex = exchange_with_json(r#"{"foo":{"bar":"baz"}}"#).await;
            let result = expr.evaluate(&ex).await.unwrap();
            assert_eq!(result, JsonValue::String("baz".to_string()));
        }
        assert_eq!(
            COMPILE_COUNT.with(std::cell::Cell::get),
            after_create,
            "evaluate must NOT trigger re-compilation"
        );
    }

    #[tokio::test]
    async fn compilation_happens_only_once_for_predicate() {
        let before = COMPILE_COUNT.with(std::cell::Cell::get);
        let lang = JsonPathLanguage::new();
        let pred = lang.create_predicate("$.active").unwrap();
        let after_create = COMPILE_COUNT.with(std::cell::Cell::get);
        assert_eq!(
            after_create,
            before + 1,
            "create_predicate must compile exactly once"
        );

        for _ in 0..50 {
            let ex = exchange_with_json(r#"{"active":true}"#).await;
            assert!(pred.matches(&ex).await.unwrap());
        }
        assert_eq!(
            COMPILE_COUNT.with(std::cell::Cell::get),
            after_create,
            "matches must NOT trigger re-compilation"
        );
    }

    fn matches_mode_lang() -> JsonPathLanguage {
        JsonPathLanguage::with_config(JsonPathConfig {
            predicate_mode: JsonPathPredicateMode::Matches,
            ..JsonPathConfig::default()
        })
    }

    #[tokio::test]
    async fn matches_mode_cardinality_table() {
        // Ruling (mission 399, oracle 2026-10-24): in `matches` mode the raw
        // match sequence decides — zero matches are false, a sole boolean
        // keeps its value, every other non-empty sequence is true. No value
        // truthiness: empty strings and 0 are true; an existing null value
        // is true.
        let lang = matches_mode_lang();
        let table = [
            // (body, query, expected)
            (
                r#"{"items":[{"price":20},{"price":5}]}"#,
                "$.items[?@.price>10]",
                true,
            ),
            (r#"{"items":[{"price":20}]}"#, "$.items[?@.price>10]", true),
            (r#"{"items":[{"price":5}]}"#, "$.items[?@.price>10]", false),
            (r#"{"items":[1,2]}"#, "$.missing", false),
            (r#"{"val":{}}"#, "$.val", true),
            (r#"{"val":[]}"#, "$.val", true),
            (r#"{"val":""}"#, "$.val", true),
            (r#"{"val":"false"}"#, "$.val", true),
            (r#"{"val":0}"#, "$.val", true),
            (r#"{"val":null}"#, "$.val", true),
            (r#"{"val":true}"#, "$.val", true),
            (r#"{"val":false}"#, "$.val", false),
        ];
        for (body, query, expected) in table {
            let pred = lang.create_predicate(query).unwrap();
            let ex = exchange_with_json(body).await;
            let got = pred.matches(&ex).await.unwrap_or_else(|e| {
                panic!("matches mode must not error for {query} on {body}: {e:?}")
            });
            assert_eq!(got, expected, "query {query} on {body}");
        }
    }

    #[tokio::test]
    async fn strict_stays_default_and_repro_cases_remain_type_errors() {
        // The owner-approved strict default is unchanged: the two mission
        // repro cases stay type errors unless `Matches` is configured.
        let lang = default_lang().await;
        let ex = exchange_with_json(r#"{"items":[{"price":20},{"price":5}]}"#).await;
        let pred = lang.create_predicate("$.items[?@.price>10]").unwrap();
        match pred.matches(&ex).await {
            Err(LanguageError::TypeMismatch {
                actual,
                position: None,
                ..
            }) => {
                // One item (price 20) matches the filter; the single match
                // collapses to that object.
                assert_eq!(actual, "object");
            }
            other => panic!("strict default must stay a type error, got: {other:?}"),
        }
        let pred = lang.create_predicate("$.missing").unwrap();
        match pred.matches(&ex).await {
            Err(LanguageError::TypeMismatch {
                actual,
                position: None,
                ..
            }) => {
                assert_eq!(actual, "null");
            }
            other => panic!("strict default must stay a type error, got: {other:?}"),
        }
    }

    #[tokio::test]
    async fn matches_mode_evaluation_failure_stays_typed_error() {
        // Coercion applies to match results only: a body that cannot be
        // evaluated still fails with a typed error and is NOT coerced to
        // false.
        let lang = matches_mode_lang();
        let pred = lang.create_predicate("$.val").unwrap();
        let ex = exchange_with_text_body("not json at all").await;
        assert!(
            pred.matches(&ex).await.is_err(),
            "evaluation failure must not coerce to false"
        );
    }
}