Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

269 KB
Raw Blame
//! ES-compatible query DSL parser.
//!
//! Converts raw `serde_json::Value` (from the HTTP request body) into a
//! [`QueryNode`] tree.  The parser is intentionally lenient in the same places
//! ES is lenient (e.g. a missing `query` field defaults to `match_all`) and
//! strict — with **readable** error messages — where ES gives cryptic Java
//! stack traces.
//!
//! ## Entry points
//!
//! | Function | Description |
//! |---|---|
//! | [`parse_request`] | Parse a full `{ "query": …, "from": …, … }` body. |
//! | [`parse_query`] | Parse just the `query` object. |

use base64::Engine as _;
use serde_json::Value;
use std::cell::Cell;
use tracing::trace;

use crate::ast::{
    BoolOperator, BoostMode, FieldValueFactor, FusionStrategy, Fuzziness, GeoShapeType,
    MinShouldMatch, Modifier, MultiMatchType, QueryNode, RandomScore, SavingsMode, ScoreFunction,
    ScoreMode, SearchRequest, SourceFilter, TrackTotalHits, WeightedQuery,
};
use crate::dates;
use crate::error::{ParseError, QueryError, Result};
use crate::sort::{SortField, SortMissing, SortMode, SortOrder};

// ── Recursion depth limit ──────────────────────────────────────────────────────
//
// Bool, dis_max, boosting and constant_score recurse into parse_query for every
// nested clause. Without a cap, a `{"bool":{"filter":[{"bool":{"filter":[…]}}]}}`
// payload of arbitrary depth blows the stack — a trivial unauthenticated DOS.
//
// ES uses a default of 20. We allow 64 (Rust frames are small relative to JVM
// frames). The counter is thread-local because parse_query is sync and runs on
// whichever tokio worker handles the request; parallel requests on different
// workers each get their own counter.
const MAX_QUERY_DEPTH: usize = 64;

/// Parse-time ceiling on `from + size`: the largest value ES's
/// `index.max_result_window` can take (a Java `int`). The real limit is the
/// index's `index.max_result_window`, else the node's
/// `limits.max_result_window` (default 10,000), and the engine enforces it
/// before anything is materialised. This bound only keeps the arithmetic
/// sane; it used to be a hardcoded 10,000, which silently overrode a larger
/// per-index setting. Deep pagination should use `search_after`/PIT.
pub const MAX_RESULT_WINDOW: usize = i32::MAX as usize;

// ── Boolean clause limit ──────────────────────────────────────────────────────
//
// Issue #122, second half. `MAX_QUERY_DEPTH` bounds how deeply a query nests;
// nothing bounded how WIDE it is, so a single `bool` could carry an unbounded
// number of clauses. That is not merely a big query: there is no compiled-script
// cache in this engine, so every `script` clause is re-tokenised and re-parsed
// for every document it is evaluated against, and the cost of a `bool` with N
// script clauses over D documents is N x D full script parses. The clause count
// is the only place that product can be bounded before any work starts.
//
// 1,024 is Elasticsearch's documented `indices.query.bool.max_clause_count`
// default, and ES answers `too_many_clauses` above it — so a query this
// rejects is a query that was already rejected by the system being emulated.
const MAX_CLAUSE_COUNT: usize = 1_024;

thread_local! {
    static QUERY_DEPTH: Cell<usize> = const { Cell::new(0) };
    /// Boolean clauses parsed so far in the current top-level query. Reset by
    /// the outermost [`parse_query`] rather than by an RAII guard: the limit
    /// is on the whole query's total width, so it must accumulate across
    /// sibling `bool`s instead of unwinding with each one.
    static CLAUSE_COUNT: Cell<usize> = const { Cell::new(0) };
}

/// Charge one boolean clause against [`MAX_CLAUSE_COUNT`].
fn charge_clause() -> Result<()> {
    let exceeded = CLAUSE_COUNT.with(|c| {
        let next = c.get() + 1;
        c.set(next);
        next > MAX_CLAUSE_COUNT
    });
    if exceeded {
        return Err(QueryError::Parse(ParseError::Invalid(format!(
            "too_many_clauses: maxClauseCount is set to {MAX_CLAUSE_COUNT}"
        ))));
    }
    Ok(())
}

/// RAII guard that increments the thread-local query-depth counter on
/// construction and decrements it on drop. Returns an error if the depth
/// exceeds `MAX_QUERY_DEPTH` so callers can `?` straight through.
struct DepthGuard;

impl DepthGuard {
    fn enter() -> Result<Self> {
        let exceeded = QUERY_DEPTH.with(|d| {
            let next = d.get() + 1;
            d.set(next);
            next > MAX_QUERY_DEPTH
        });
        if exceeded {
            QUERY_DEPTH.with(|d| d.set(d.get().saturating_sub(1)));
            return Err(QueryError::Parse(ParseError::Invalid(format!(
                "query nesting exceeds max depth of {MAX_QUERY_DEPTH}"
            ))));
        }
        Ok(DepthGuard)
    }
}

impl Drop for DepthGuard {
    fn drop(&mut self) {
        QUERY_DEPTH.with(|d| d.set(d.get().saturating_sub(1)));
    }
}

// ── Error helpers ──────────────────────────────────────────────────────────────

/// Construct `Err(QueryError::Parse(ParseError::Invalid(msg)))`.
#[inline(always)]
fn invalid<T>(msg: impl Into<String>) -> Result<T> {
    Err(QueryError::Parse(ParseError::Invalid(msg.into())))
}

/// Wrap a `QueryNode` in a `Named` node if `name` is `Some`, otherwise return it as-is.
#[inline(always)]
fn maybe_named(node: QueryNode, name: Option<String>) -> QueryNode {
    match name {
        Some(n) => QueryNode::Named {
            name: n,
            query: Box::new(node),
        },
        None => node,
    }
}

/// Construct `Err(QueryError::Parse(ParseError::UnknownQueryType(name)))`.
#[inline(always)]
fn unknown_type<T>(name: impl Into<String>) -> Result<T> {
    Err(QueryError::Parse(ParseError::UnknownQueryType(name.into())))
}

// ─────────────────────────────────────────────────────────────────────────────
// Capability manifest — the single source of truth for "what queries exist"
// ─────────────────────────────────────────────────────────────────────────────
//
// Issue #211: hand-maintained lists of supported query types drifted from the
// dispatch table in `parse_query`, in both directions — docs advertised
// `has_child`/`has_parent`, which are rejected with a 400, and omitted a dozen
// types that do run. Every such list now derives from these two constants, and
// `dispatch_table_matches_capability_manifest` (below) fails the build if a
// `parse_query` arm is added or removed without updating them. Docs are checked
// against the same constants by `xerj-engine/tests/docs_capability_lists.rs`.

/// Every query-type name [`parse_query`] dispatches to a real implementation.
///
/// **Acceptance, not fidelity.** A name here means the parser builds a
/// [`QueryNode`] the planner and executor will run; it is not a claim that the
/// semantics match Elasticsearch in every corner. Per-type gaps are tracked in
/// `ROADMAP.md`.
pub const SUPPORTED_QUERY_TYPES: &[&str] = &[
    "bool",
    "boosting",
    "combined_fields",
    "constant_score",
    "dis_max",
    "distance_feature",
    "exists",
    "function_score",
    "fuzzy",
    "geo_bounding_box",
    "geo_distance",
    "geo_polygon",
    "geo_shape",
    "hybrid",
    "ids",
    "intervals",
    "knn",
    "match",
    "match_all",
    "match_bool_prefix",
    "match_none",
    "match_phrase",
    "match_phrase_prefix",
    "more_like_this",
    "multi_match",
    "nested",
    "percolate",
    "pinned",
    "prefix",
    "query_string",
    "range",
    "rank_feature",
    "regexp",
    "script",
    "script_score",
    "semantic",
    "simple_query_string",
    "span_containing",
    "span_first",
    "span_near",
    "span_not",
    "span_or",
    "span_term",
    "span_within",
    "term",
    "terms",
    "terms_set",
    "type",
    "wildcard",
    "wrapper",
];

/// Query-type names [`parse_query`] recognises and **deliberately rejects**
/// with a 400.
///
/// These are listed separately rather than dropped so the rejection is a
/// documented contract: an ES client sending `has_child` gets a specific
/// "not supported, denormalize the relationship" message instead of the
/// generic unknown-query-type error — and never gets silently wrong hits.
pub const REJECTED_QUERY_TYPES: &[&str] = &["has_child", "has_parent"];

// ─────────────────────────────────────────────────────────────────────────────
// Public entry points
// ─────────────────────────────────────────────────────────────────────────────

/// Parse a complete ES search request body.
///
/// ```json
/// {
///   "query": { "match": { "title": "rust" } },
///   "from": 0,
///   "size": 10,
///   "sort": [{ "date": "desc" }],
///   "_source": ["title", "body"],
///   "aggs": { … }
/// }
/// ```
pub fn parse_request(body: &Value) -> Result<SearchRequest> {
    let obj = body.as_object().ok_or_else(|| {
        QueryError::Parse(ParseError::Invalid(
            "request body must be a JSON object".into(),
        ))
    })?;

    let query = match obj.get("query") {
        Some(q) => parse_query(q)?,
        None => QueryNode::MatchAll,
    };

    let from = match obj.get("from") {
        Some(v) => v.as_u64().ok_or_else(|| {
            QueryError::Parse(ParseError::Invalid(
                "`from` must be a non-negative integer".into(),
            ))
        })? as usize,
        None => 0,
    };

    let size = match obj.get("size") {
        Some(v) => v.as_u64().ok_or_else(|| {
            QueryError::Parse(ParseError::Invalid(
                "`size` must be a non-negative integer".into(),
            ))
        })? as usize,
        None => 10,
    };

    // The per-index / per-node window is checked by the engine (it needs the
    // index settings, which the parser does not have), ahead of every
    // allocation sized by `from + size`; see `MAX_RESULT_WINDOW`.
    if from.saturating_add(size) > MAX_RESULT_WINDOW {
        return invalid(format!(
            "from + size must be <= {MAX_RESULT_WINDOW} (got {})",
            from.saturating_add(size)
        ));
    }

    let sort = match obj.get("sort") {
        Some(v) => parse_sort(v)?,
        None => Vec::new(),
    };

    let search_after = match obj.get("search_after") {
        Some(Value::Array(arr)) => Some(arr.clone()),
        Some(_) => return invalid("`search_after` must be an array"),
        None => None,
    };

    let aggs = obj.get("aggs").or_else(|| obj.get("aggregations")).cloned();

    let explain = obj
        .get("explain")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);

    let source = match obj.get("_source") {
        Some(v) => parse_source_filter(v)?,
        None => SourceFilter::default(),
    };

    let timeout_ms = obj.get("timeout").and_then(parse_timeout);

    // Parse optional highlight configuration.
    let highlight = obj
        .get("highlight")
        .and_then(|v| serde_json::from_value(v.clone()).ok());

    // Parse track_total_hits: true | false | integer
    let track_total_hits = match obj.get("track_total_hits") {
        Some(Value::Bool(true)) | None => TrackTotalHits::True,
        Some(Value::Bool(false)) => TrackTotalHits::False,
        Some(Value::Number(n)) => {
            // ES accepts `track_total_hits: -1` as an alias for `true`
            // (track the exact total).
            if n.as_i64().map(|v| v < 0).unwrap_or(false) {
                TrackTotalHits::True
            } else {
                let limit = n.as_u64().unwrap_or(10_000);
                TrackTotalHits::Limit(limit)
            }
        }
        _ => TrackTotalHits::True,
    };

    // script_fields — opaque `{name: {script: {...}}}`; evaluated per hit
    // against the doc source by the ES-compat search handler.
    let script_fields = obj.get("script_fields").cloned();

    // fields — stored/doc-value fields to return alongside _source.
    let parse_field = |value: &Value| {
        value.as_str().map(String::from).or_else(|| {
            value
                .as_object()
                .and_then(|object| object.get("field"))
                .and_then(Value::as_str)
                .map(String::from)
        })
    };
    let fields: Vec<String> = match obj.get("fields") {
        Some(Value::Array(arr)) => arr.iter().filter_map(parse_field).collect(),
        Some(value) => parse_field(value).into_iter().collect(),
        None => Vec::new(),
    };

    // profile — include timing breakdown
    let profile = obj.get("profile").and_then(Value::as_bool).unwrap_or(false);

    Ok(SearchRequest {
        query,
        from,
        size,
        sort,
        search_after,
        aggs,
        explain,
        source,
        timeout_ms,
        highlight,
        track_total_hits,
        script_fields,
        fields,
        profile,
        collapse: None,
        rescore: Vec::new(),
        min_score: None,
        leaf_ts_field: None,
        // Never parsed off the wire body: the ES-compat `_search` handler
        // sets this from `?savings=`.
        savings: SavingsMode::Off,
        // #1019: ids-only is engine-internal and never arrives from the wire.
        ids_only: false,
    })
}

/// Parse just the query portion of a search body.
///
/// The `json` value should be the object **value** of the `"query"` key,
/// e.g. `{ "match": { "title": "hello" } }`.
pub fn parse_query(json: &Value) -> Result<QueryNode> {
    // Bail out early on excessive nesting. The guard decrements on drop so
    // an error return here does not leak the increment to a sibling call.
    let _depth = DepthGuard::enter()?;
    // Outermost call for this request: start a fresh clause budget. The
    // counter cannot unwind with an RAII guard the way depth does — the limit
    // is on the query's total width, which is a sum over siblings, not a
    // property of the current path.
    if QUERY_DEPTH.with(Cell::get) == 1 {
        CLAUSE_COUNT.with(|c| c.set(0));
    }

    let obj = json.as_object().ok_or_else(|| {
        QueryError::Parse(ParseError::Invalid("query must be a JSON object".into()))
    })?;

    if obj.len() != 1 {
        if obj.is_empty() {
            return Ok(QueryNode::MatchAll);
        }
        return invalid(format!(
            "query object must have exactly one key, found {}: {}",
            obj.len(),
            obj.keys().cloned().collect::<Vec<_>>().join(", ")
        ));
    }

    let (query_type, params) = obj.iter().next().unwrap();
    trace!(query_type = %query_type, "parsing query");

    match query_type.as_str() {
        "match_all" => parse_match_all(params),
        "match_none" => Ok(QueryNode::MatchNone),
        "match" => parse_match(params),
        "match_phrase" => parse_match_phrase(params),
        "multi_match" => parse_multi_match(params),
        // ES 7.13+ `combined_fields` — treats multiple text fields as a
        // single virtual field and runs a match query over their
        // concatenation. We map it to multi_match with `type: cross_fields`
        // (the closest existing behavior) so the query parses and executes;
        // scoring doesn't exactly match ES's term-statistics pooling.
        "combined_fields" => parse_combined_fields(params),
        "term" => parse_term(params),
        "terms" => parse_terms(params),
        "range" => parse_range(params),
        "prefix" => parse_prefix(params),
        "wildcard" => parse_wildcard(params),
        "exists" => parse_exists(params),
        "ids" => parse_ids(params),
        "script" => parse_script(params),
        "bool" => parse_bool(params),
        "query_string" => parse_query_string(params),
        "constant_score" => parse_constant_score(params),
        "boosting" => parse_boosting(params),
        "dis_max" => parse_dis_max(params),
        "knn" => parse_knn(params),
        "semantic" => parse_semantic(params),
        "hybrid" => parse_hybrid(params),
        "fuzzy" => parse_fuzzy(params),
        "regexp" => parse_regexp(params),
        "match_phrase_prefix" => parse_match_phrase_prefix(params),
        "simple_query_string" => parse_simple_query_string(params),
        "geo_distance" => parse_geo_distance(params),
        "geo_bounding_box" => parse_geo_bounding_box(params),
        "function_score" => parse_function_score(params),
        // ── Nested / join queries ──────────────────────────────────────────────
        "nested" => parse_nested(params),
        "has_child" => parse_has_child(params),
        "has_parent" => parse_has_parent(params),
        "more_like_this" => parse_more_like_this(params),
        "percolate" => parse_percolate(params),
        "pinned" => parse_pinned(params),
        // ── Span queries ───────────────────────────────────────────────────────
        "span_term" => parse_span_term(params),
        "span_near" => parse_span_near(params),
        "span_or" => parse_span_or(params),
        "span_not" => parse_span_not(params),
        "span_first" => parse_span_first(params),
        "span_containing" | "span_within" => parse_span_containing_like(query_type, params),
        // ── Geo shape queries ──────────────────────────────────────────────────
        "geo_polygon" => parse_geo_polygon(params),
        "geo_shape" => parse_geo_shape(params),
        // ── Specialised query types ────────────────────────────────────────────
        "match_bool_prefix" => parse_match_bool_prefix(params),
        "terms_set" => parse_terms_set(params),
        "intervals" => parse_intervals(params),
        "script_score" => parse_script_score(params),
        "distance_feature" => parse_distance_feature(params),
        "rank_feature" => parse_rank_feature(params),
        // ── Deprecated / pass-through queries ─────────────────────────────────
        "type" => Ok(QueryNode::MatchAll), // everything is type _doc in modern ES
        "wrapper" => parse_wrapper(params),
        unknown => unknown_type(unknown),
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Leaf parsers
// ─────────────────────────────────────────────────────────────────────────────

fn parse_match_all(params: &Value) -> Result<QueryNode> {
    if !params.is_object() && !params.is_null() {
        return invalid("`match_all` value must be an object");
    }
    // ES scores `match_all { boost }` as exactly `boost` per hit — the
    // same constant-score semantics as `constant_score { match_all }`
    // (live-verified vs ES 8.13.4: boost 3.5 → every _score 3.5, boost
    // 0.0 → 0.0). Dropping the boost scored every doc 1.0. Only wrap
    // when it changes anything so the plain `match_all` keeps its
    // dedicated fast paths.
    match params.get("boost").and_then(|v| v.as_f64()) {
        Some(b) if (b as f32) != 1.0 => Ok(QueryNode::Constant {
            score: b as f32,
            query: Box::new(QueryNode::MatchAll),
        }),
        _ => Ok(QueryNode::MatchAll),
    }
}

fn parse_match(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`match` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`match` query must have exactly one field");
    }

    let (field, value) = obj.iter().next().unwrap();
    let field = field.clone();

    // An empty query string is valid ES syntax that simply has no analyzed
    // terms to match — real ES treats it leniently (match_none), not as a
    // parse error. Kibana's own SavedObjectsClient `_find` builds exactly
    // this for a trailing-`*` search term (`"*".replace(/\*$/, '')` →
    // `""`), so without this every `_find?search=*` 400s.
    if matches!(value, Value::String(s) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    // Shorthand forms: `match: {field: "value"}`, `match: {field: 42}`,
    // `match: {field: true}`.  ES silently stringifies non-strings.
    if let Some(query) = scalar_to_string(value) {
        return Ok(QueryNode::Match {
            field,
            query,
            // No `operator` key exists in the shorthand. Log indices resolve
            // this to AND (#1504); every other index treats it as OR.
            operator: BoolOperator::Omitted,
            analyzer: None,
            boost: None,
            minimum_should_match: None,
            lenient: false,
        });
    }

    let vobj = value
        .as_object()
        .ok_or_else(|| qerr("`match` field value must be a scalar or object"))?;

    if matches!(vobj.get("query"), Some(Value::String(s)) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    // Inside the object form, `query` can also be a number / bool.
    let query = vobj
        .get("query")
        .and_then(scalar_to_string)
        .ok_or_else(|| qerr("`match.query` must be a non-empty scalar"))?;
    // Absent key → Omitted, not OR. An explicit "or" stays OR, including on
    // a log index whose default is AND (#1504).
    let operator = match vobj.get("operator") {
        None => BoolOperator::Omitted,
        some => parse_bool_operator(some)?,
    };
    let analyzer = vobj
        .get("analyzer")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let boost = vobj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
    let minimum_should_match = vobj
        .get("minimum_should_match")
        .map(parse_min_should_match)
        .transpose()?;
    let name = vobj
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    let node = QueryNode::Match {
        field,
        query,
        operator,
        analyzer,
        boost,
        minimum_should_match,
        lenient: parse_lenient(vobj.get("lenient")).unwrap_or(false),
    };
    Ok(maybe_named(node, name))
}

/// Read a clause's `lenient` flag (#1284). ES takes a JSON boolean or the
/// strings `"true"` / `"false"`; `None` means the caller applies its default.
fn parse_lenient(v: Option<&Value>) -> Option<bool> {
    match v? {
        Value::Bool(b) => Some(*b),
        Value::String(s) if s == "true" => Some(true),
        Value::String(s) if s == "false" => Some(false),
        _ => None,
    }
}

/// Whether a field list means "every field", the case where ES defaults
/// `lenient` to true for `multi_match`, `query_string` and
/// `simple_query_string` (#1284). An empty list counts: with no fields those
/// clauses fall back to `index.query.default_field`, whose default is `*`.
/// A narrower pattern (`b*`) does not, and ES stays strict for it.
fn targets_every_field(fields: &[String]) -> bool {
    match fields {
        [] => true,
        [only] => qs_split_boost(only).0 == "*",
        _ => false,
    }
}

/// Best-effort conversion of a JSON scalar to a string for query
/// shorthand (ES accepts `match: {foo: 42}` same as `match: {foo: "42"}`).
fn scalar_to_string(v: &Value) -> Option<String> {
    match v {
        Value::String(s) if !s.is_empty() => Some(s.clone()),
        Value::Number(n) => Some(n.to_string()),
        Value::Bool(b) => Some(b.to_string()),
        _ => None,
    }
}

fn parse_match_phrase(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`match_phrase` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`match_phrase` query must have exactly one field");
    }

    let (field, value) = obj.iter().next().unwrap();
    let field = field.clone();

    // Empty query string → match_none, not a parse error. See `parse_match`.
    if matches!(value, Value::String(s) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    // Shorthand forms: `match_phrase: {field: "value"}`, `match_phrase:
    // {field: 42}`, `match_phrase: {field: true}` — ES silently stringifies
    // non-strings, same as `match` (see `scalar_to_string`).
    if let Some(query) = scalar_to_string(value) {
        return Ok(QueryNode::MatchPhrase {
            field,
            query,
            slop: 0,
            analyzer: None,
            boost: None,
            lenient: false,
        });
    }

    let vobj = value
        .as_object()
        .ok_or_else(|| qerr("`match_phrase` field value must be a string or object"))?;

    if matches!(vobj.get("query"), Some(Value::String(s)) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    // Inside the object form, `query` can also be a number / bool — e.g.
    // OpenSearch Dashboards filtering on a boolean field sends
    // `match_phrase: {field: {query: true}}` verbatim (found empirically,
    // this is what a real OSD dashboard filter on a bool field produces).
    let query = vobj
        .get("query")
        .and_then(scalar_to_string)
        .ok_or_else(|| qerr("`match_phrase.query` must be a non-empty scalar"))?;
    let slop = parse_phrase_slop(vobj.get("slop"), "match_phrase")?;
    let analyzer = vobj
        .get("analyzer")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let boost = vobj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
    let name = vobj
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    // `match_phrase` has no `lenient` option in ES (it answers `[match_phrase]
    // query does not support [lenient]`), so a parsed phrase is always strict.
    let node = QueryNode::MatchPhrase {
        field,
        query,
        slop,
        analyzer,
        boost,
        lenient: false,
    };
    Ok(maybe_named(node, name))
}

/// Coerce a JSON scalar to an integer the way ES's `XContentParser.intValue()`
/// does under its default number policy (`DEFAULT_NUMBER_COERCE_POLICY = true`):
/// an integer is taken as written, a **float is truncated** toward zero, and a
/// numeric **string** is read as a double and then narrowed
/// (`libs/x-content/src/main/java/org/elasticsearch/xcontent/support/AbstractXContentParser.java`:
/// `:70` — "the 3rd party parsers we rely on are known to silently truncate
/// fractions", guarding `ensureNumberConversion` at `:74`, which only raises
/// when `coerce == false`; `:171` `intValue(coerce)`, whose `VALUE_STRING`
/// arm calls `:162` `parseInt`, itself a `Double.parseDouble` narrowed with
/// `(int)`; AGPL, read for semantics only, nothing copied).
///
/// Why it exists: JSON encoders that carry every number as a double emit
/// `"slop": 2.0`, and ES answers that query with slop 2. Reading it with
/// `as_i64()` alone leaves two bad options — a 400 on a request ES answers, or
/// a silent fall back to the default, which is the accept-and-ignore (#204)
/// this parser exists to remove.
///
/// The `as i64` cast saturates on an out-of-range float, so an absurd value
/// lands on the bound and the caller's range check turns it into a 400 rather
/// than a wrapped, silently honoured small number.
fn coerce_es_int(v: &Value) -> Option<i64> {
    if let Some(n) = v.as_i64() {
        return Some(n);
    }
    let d = match v {
        Value::Number(_) => v.as_f64()?,
        Value::String(s) => s.trim().parse::<f64>().ok()?,
        _ => return None,
    };
    d.is_finite().then(|| d.trunc() as i64)
}

/// Parse the `slop` parameter of a phrase-shaped query, identically at each of
/// the three entry points that accept one and lower it to a phrase:
/// `match_phrase`, `match_phrase_prefix`, `multi_match`.  Sharing it is the
/// point: the same JSON value must produce the same answer whichever of those
/// three wraps it, or a client gets a 400 from one spelling and a silently
/// different answer from the semantically identical other.
///
/// Deliberately **not** covered: `span_near`, which also takes a `slop` and
/// keeps its own `as_u64().unwrap_or(0)` read (see `parse_span_near`).  ES
/// applies no validation there either — `SpanNearQueryBuilder` stores the int
/// unchecked (`.../index/query/SpanNearQueryBuilder.java:62`), so a negative
/// `span_near` slop is a query ES *answers*, and routing it through here would
/// turn a 200 into a 400.  XERJ still coerces it to 0 instead of honouring it,
/// which is a real (pre-existing) gap — recorded in `parse_span_near`, not
/// papered over here.
///
/// ES rejects a negative slop from all three phrase builders
/// (`MatchPhraseQueryBuilder.slop` / `MatchPhrasePrefixQueryBuilder.slop:103`
/// / `MultiMatchQueryBuilder.slop:350` all throw "No negative slop allowed";
/// AGPL, read for semantics only).  `u32::try_from` rather than `as u32`
/// because a wrapping cast turns an out-of-range slop into a small honoured
/// one — a silently wrong answer, which is worse than a 400.
fn parse_phrase_slop(v: Option<&Value>, ctx: &str) -> Result<u32> {
    match v {
        None | Some(Value::Null) => Ok(0),
        Some(v) => match coerce_es_int(v) {
            Some(n) if n < 0 => invalid(format!("`{ctx}.slop` must not be negative")),
            Some(n) => u32::try_from(n).map_err(|_| qerr(format!("`{ctx}.slop` is out of range"))),
            None => invalid(format!("`{ctx}.slop` must be a number")),
        },
    }
}

/// Parse `max_expansions`, with the same refusal-to-ignore as
/// [`parse_phrase_slop`]: a value XERJ cannot read is a 400, never a silent
/// fall back to the default of 50.
///
/// The floor differs between the two entry points, and that asymmetry is ES's
/// rather than an oversight here: `MultiMatchQueryBuilder.maxExpansions`
/// throws on `<= 0` (`.../index/query/MultiMatchQueryBuilder.java:389`) while
/// `MatchPhrasePrefixQueryBuilder.maxExpansions` throws only on `< 0`
/// (`.../index/query/MatchPhrasePrefixQueryBuilder.java:118`, "No negative
/// maxExpansions allowed").  So `0` is a 400 on `multi_match` and an accepted
/// (expand-nothing) value on `match_phrase_prefix`; `allow_zero` carries that
/// distinction instead of us inventing one ES does not have.
fn parse_max_expansions(v: Option<&Value>, ctx: &str, allow_zero: bool) -> Result<u32> {
    match v {
        None | Some(Value::Null) => Ok(DEFAULT_MAX_EXPANSIONS),
        Some(v) => match coerce_es_int(v) {
            Some(n) if n < 0 => invalid(format!("`{ctx}.max_expansions` must not be negative")),
            Some(0) if !allow_zero => invalid(format!("`{ctx}.max_expansions` must be positive")),
            Some(n) => u32::try_from(n)
                .map_err(|_| qerr(format!("`{ctx}.max_expansions` is out of range"))),
            None => invalid(format!("`{ctx}.max_expansions` must be a number")),
        },
    }
}

/// ES's `FuzzyQuery.defaultMaxExpansions`, which both phrase-prefix builders
/// default to.
const DEFAULT_MAX_EXPANSIONS: u32 = 50;

/// ES `combined_fields` query — introduced in 7.13, treats N text fields as a
/// single virtual field for term-frequency scoring. Our approximation routes
/// it to `multi_match` with `type: "cross_fields"`, which is the closest
/// existing behavior. Accepts the same parameters ES does (query, fields,
/// operator, minimum_should_match, zero_terms_query).
fn parse_combined_fields(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`combined_fields` must be an object"))?;
    let mut rewritten = obj.clone();
    rewritten.insert(
        "type".to_string(),
        Value::String("cross_fields".to_string()),
    );
    parse_multi_match(&Value::Object(rewritten))
}

fn parse_multi_match(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`multi_match` must be an object"))?;

    let query = string_field(obj, "query")?;

    let fields = obj
        .get("fields")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`multi_match.fields` must be an array"))?
        .iter()
        .map(|v| {
            v.as_str()
                .ok_or_else(|| qerr("`multi_match.fields` must contain strings"))
                .map(str::to_string)
        })
        .collect::<Result<Vec<_>>>()?;

    if fields.is_empty() {
        return invalid("`multi_match.fields` must not be empty");
    }
    // #1284: explicit `lenient`, else ES's default: lenient only when the
    // clause targets every field (`["*"]`).
    let lenient = parse_lenient(obj.get("lenient")).unwrap_or_else(|| targets_every_field(&fields));

    let type_str = obj
        .get("type")
        .and_then(|v| v.as_str())
        .unwrap_or("best_fields");

    // `slop` / `max_expansions` are the phrase parameters of `multi_match`.
    // They used to be dropped here, so `{"type":"phrase","slop":2}` was
    // accepted and silently evaluated as slop 0 (issue #230) — parse them
    // and reject the values ES rejects instead of quietly mis-answering.
    // ES: negative slop and non-positive max_expansions are 400s, and
    // `slop` is not allowed with `type: bool_prefix`.
    let slop: u32 = parse_phrase_slop(obj.get("slop"), "multi_match")?;
    let max_expansions: u32 =
        parse_max_expansions(obj.get("max_expansions"), "multi_match", false)?;
    if slop != 0 && type_str == "bool_prefix" {
        // ES's own wording — `310_match_bool_prefix.yml` catches this exact
        // regex. The suite's runner only checks that the call is allowed to
        // fail, so this arm passed while XERJ silently ignored `slop`.
        return invalid("[slop] not allowed for type [bool_prefix]");
    }
    // `slop` with `type: phrase_prefix` is ACCEPTED and HONOURED, because ES
    // honours it: `MultiMatchQueryBuilder` rejects slop only for
    // `bool_prefix` (…/index/query/MultiMatchQueryBuilder.java:673) and
    // `TextFieldMapper.createPhrasePrefixQuery` calls
    // `MultiPhrasePrefixQuery.setSlop(slop)` (…/index/mapper/
    // TextFieldMapper.java:2019, `setSlop` at :2028, reached from the
    // `phrasePrefixQuery` entry at :1269 — AGPL, read for semantics only).
    // Both XERJ
    // evaluators now carry it: `PhrasePrefixQuery.slop` on the segment side
    // and the sloppy prefix walk in the stored-doc scan. Refusing it here
    // would have been a wire-compat break on a query ES answers, and would
    // have left the semantically identical single-field
    // `{"match_phrase_prefix": {"f": {"query": …, "slop": N}}}` — which
    // `parse_match_phrase_prefix` accepts — answering a different query.
    //
    // `slop` on the FIELD-CENTRIC types (best_fields / most_fields /
    // cross_fields) is accepted and unused, which is also what ES does:
    // those types lower to a BOOLEAN match query, and only the PHRASE and
    // PHRASE_PREFIX types lower to a phrase query that reads slop
    // (`MultiMatchQueryBuilder.Type`, elasticsearch/server/src/main/java/
    // org/elasticsearch/index/query/MultiMatchQueryBuilder.java:91 — AGPL,
    // read for semantics only). Same answer as ES, so there is nothing to
    // fail loudly about.

    // bool_prefix: rewrite to a Bool::should over per-field match_bool_prefix
    // clauses. Tokens except the last become Match queries, the last becomes
    // a Prefix query — matching ES `match_bool_prefix` semantics across all
    // supplied fields.
    if type_str == "bool_prefix" {
        let analyzer_opt = obj
            .get("analyzer")
            .and_then(|v| v.as_str())
            .map(str::to_string);
        let analyzer_lowercases = !matches!(
            analyzer_opt.as_deref(),
            Some("whitespace") | Some("keyword")
        );
        let operator_and = matches!(
            obj.get("operator")
                .and_then(Value::as_str)
                .map(|s| s.to_ascii_lowercase())
                .as_deref(),
            Some("and")
        );
        let mm_ms = obj
            .get("minimum_should_match")
            .and_then(|v| parse_min_should_match(v).ok());
        let fuzziness_opt = obj.get("fuzziness").map(|v| match v {
            Value::String(s) if s.eq_ignore_ascii_case("auto") => crate::ast::Fuzziness::Auto,
            Value::String(s) => s
                .parse::<u32>()
                .ok()
                .map(crate::ast::Fuzziness::Fixed)
                .unwrap_or(crate::ast::Fuzziness::Auto),
            Value::Number(n) => crate::ast::Fuzziness::Fixed(n.as_u64().unwrap_or(0) as u32),
            _ => crate::ast::Fuzziness::Auto,
        });
        // #848: `match` accepts `prefix_length` alongside `fuzziness`.
        let prefix_length = parse_prefix_length(obj);
        let raw_tokens: Vec<String> = if analyzer_opt.as_deref() == Some("keyword") {
            vec![query.to_string()]
        } else {
            query.split_whitespace().map(str::to_string).collect()
        };
        let tokens: Vec<String> = raw_tokens
            .into_iter()
            .map(|t| {
                if analyzer_lowercases {
                    t.to_lowercase()
                } else {
                    t
                }
            })
            .collect();
        if tokens.is_empty() {
            return Ok(QueryNode::MatchAll);
        }
        let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
        let mut should: Vec<QueryNode> = Vec::new();
        for raw_field in &fields {
            // Strip any ^boost suffix (e.g. "title^2").
            let (field, fb): (&str, Option<f32>) = match raw_field.rfind('^') {
                Some(idx) => (&raw_field[..idx], raw_field[idx + 1..].parse::<f32>().ok()),
                None => (raw_field.as_str(), None),
            };
            if tokens.len() == 1 {
                let prefix = QueryNode::Prefix {
                    field: field.to_string(),
                    value: tokens[0].clone(),
                    boost: fb,
                    constant_score: false,
                    case_insensitive: false,
                };
                should.push(prefix);
                continue;
            }
            let last = tokens.len() - 1;
            let build_leaf = |tok: &str| -> QueryNode {
                if let Some(fz) = fuzziness_opt {
                    QueryNode::Fuzzy {
                        field: field.to_string(),
                        value: tok.to_string(),
                        fuzziness: fz,
                        case_insensitive: false,
                        prefix_length,
                    }
                } else {
                    QueryNode::Match {
                        field: field.to_string(),
                        query: tok.to_string(),
                        operator: BoolOperator::Or,
                        boost: None,
                        analyzer: analyzer_opt.clone(),
                        minimum_should_match: None,
                        lenient,
                    }
                }
            };
            let mut inner_clauses: Vec<QueryNode> =
                tokens[..last].iter().map(|t| build_leaf(t)).collect();
            inner_clauses.push(QueryNode::Prefix {
                field: field.to_string(),
                value: tokens[last].clone(),
                boost: None,
                constant_score: false,
                case_insensitive: false,
            });
            let (im, is, imm) = if operator_and {
                (inner_clauses, vec![], None)
            } else {
                (vec![], inner_clauses, mm_ms.clone())
            };
            let inner_bool = QueryNode::Bool {
                must: im,
                should: is,
                filter: vec![],
                must_not: vec![],
                minimum_should_match: imm,
            };
            let field_clause = if let Some(b) = fb {
                QueryNode::Boosted {
                    boost: b,
                    query: Box::new(inner_bool),
                }
            } else {
                inner_bool
            };
            should.push(field_clause);
        }
        return Ok(QueryNode::Bool {
            must: vec![],
            should,
            filter: vec![],
            must_not: vec![],
            minimum_should_match: None,
        })
        .map(|n| match boost {
            Some(b) => QueryNode::Boosted {
                query: Box::new(n),
                boost: b,
            },
            None => n,
        });
    }

    let match_type = match type_str {
        "best_fields" => MultiMatchType::BestFields,
        "most_fields" => MultiMatchType::MostFields,
        "cross_fields" => MultiMatchType::CrossFields,
        "phrase" => MultiMatchType::Phrase,
        "phrase_prefix" => MultiMatchType::PhrasePrefix,
        other => return invalid(format!("unknown multi_match type `{other}`")),
    };

    let operator = parse_bool_operator(obj.get("operator")).ok();
    let analyzer = obj
        .get("analyzer")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);

    Ok(QueryNode::MultiMatch {
        fields,
        query,
        match_type,
        operator,
        analyzer,
        boost,
        slop,
        max_expansions,
        lenient,
    })
}

fn parse_term(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`term` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`term` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    if let Some(inner) = raw.as_object() {
        if let Some(value) = inner.get("value") {
            let boost = inner
                .get("boost")
                .and_then(|v| v.as_f64())
                .map(|b| b as f32);
            let name = inner
                .get("_name")
                .and_then(|v| v.as_str())
                .map(str::to_string);
            let case_insensitive = inner
                .get("case_insensitive")
                .and_then(Value::as_bool)
                .unwrap_or(false);
            // `term` with `case_insensitive:true` is semantically an
            // exact-match against the lowercased value. Our Wildcard
            // matcher already lowercases both sides before comparing and
            // treats a pattern with no `*` / `?` as an exact match, so
            // routing through Wildcard gives correct semantics without a
            // new QueryNode variant.
            if case_insensitive {
                let val_str = match value {
                    Value::String(s) => s.clone(),
                    other => other.to_string().trim_matches('"').to_string(),
                };
                let node = QueryNode::Wildcard {
                    field,
                    value: val_str,
                    boost,
                    // KNOWN DIFF (live-verified vs ES 8.13.4): ES lowers
                    // `term{case_insensitive:true}` to a case-insensitive
                    // automaton query with the CONSTANT_SCORE rewrite
                    // (max_score 1.0), while this keeps BM25 (1.2821425).
                    // `constant_score: true` here is NOT safe yet: it
                    // admits the shape to the columnar KeywordWildcard
                    // leaf, whose dictionary narrowing is CASE-SENSITIVE —
                    // a mixed-case value then returns 0 hits (hit-set
                    // regression ≫ score diff). Fixing the score requires
                    // threading `case_insensitive` through
                    // QueryNode::Wildcard into the columnar/FST arms.
                    constant_score: false,
                    case_insensitive: true,
                };
                return Ok(maybe_named(node, name));
            }
            let node = QueryNode::Term {
                field,
                value: value.clone(),
                boost,
            };
            return Ok(maybe_named(node, name));
        }
    }

    Ok(QueryNode::Term {
        field,
        value: raw.clone(),
        boost: None,
    })
}

fn parse_terms(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`terms` must be an object"))?;

    let field_entries: Vec<_> = obj.iter().filter(|(k, _)| k.as_str() != "boost").collect();

    if field_entries.len() != 1 {
        return invalid("`terms` query must have exactly one field");
    }

    let (field, raw) = field_entries[0];
    let field = field.clone();

    // Terms lookup: {"terms": {"category": {"index": "other", "id": "1", "path": "categories"}}}
    //
    // These are RESOLVED before parsing: the HTTP layer's
    // `resolve_terms_lookups` fetches the source doc and substitutes the
    // concrete value array, so a lookup object should not reach this parser on
    // a supported endpoint. Reaching here means an endpoint parsed the query
    // WITHOUT resolving first. Previously that returned `MatchNone` (empty
    // results) with only a `warn` — a silent wrong answer: `_count` returned 0
    // for a filter `_search` counted correctly. Fail loudly so the gap is
    // visible instead of silently miscounting; the real fix is to resolve at
    // the endpoint, as `_count` now does.
    if raw.is_object() {
        return invalid(format!(
            "terms lookup on `{field}` reached the query parser unresolved — \
             the calling endpoint did not resolve `{{index, id, path}}` before \
             parsing. It is supported on `_search`/`_count`; an endpoint that \
             hits this needs a `resolve_terms_lookups` step."
        ));
    }

    let values = raw
        .as_array()
        .ok_or_else(|| qerr("`terms` values must be an array"))?
        .clone();

    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);

    Ok(QueryNode::Terms {
        field,
        values,
        boost,
    })
}

/// The format string ES reports in `failed to parse date field` errors when
/// no explicit `format` was given.
const DEFAULT_DATE_FORMAT: &str = "strict_date_optional_time||epoch_millis";

/// Map a [`dates::DateResolveError`] to the exact ES error message.  `fmt` is
/// the explicit `format` parameter, if any.
fn date_resolve_err(e: dates::DateResolveError, fmt: Option<&str>, value: &str) -> QueryError {
    use dates::DateResolveError::*;
    let msg = match e {
        UnknownPatternLetter(c) => format!(
            "Invalid format: [{}]: Unknown pattern letter: {c}",
            fmt.unwrap_or_default()
        ),
        UnparseableValue(v) => {
            let f = fmt.unwrap_or(DEFAULT_DATE_FORMAT);
            format!(
                "failed to parse date field [{v}] with format [{f}]: \
                 [failed to parse date field [{v}] with format [{f}]]"
            )
        }
        BadDateMath(m) => {
            let _ = value; // value context already inside the math substring
            format!("operator not supported for date math [{m}]")
        }
        UnknownTimeZone(tz) => format!("Unknown time-zone ID: {tz}"),
    };
    QueryError::Parse(ParseError::Invalid(msg))
}

/// Resolve one range bound per ES date semantics (rounding, `format`,
/// date math).  `round_up` is true for `lte`/`gt` bounds.  Non-date-shaped
/// values under the default format pass through unchanged so keyword and
/// numeric ranges keep their comparator semantics.
fn resolve_range_bound(
    v: Value,
    round_up: bool,
    formats: Option<&[dates::DateFmt]>,
    fmt_raw: Option<&str>,
    tz: Option<&dates::TimeZone>,
) -> Result<Value> {
    match &v {
        Value::String(s) => match dates::resolve_date_bound_str_in(s, round_up, formats, tz) {
            Ok(Some(iso)) => Ok(Value::String(iso)),
            Ok(None) => Ok(v),
            Err(e) => Err(date_resolve_err(e, fmt_raw, s)),
        },
        Value::Number(n) => match formats {
            // ES stringifies numbers under an explicit date format
            // (`gte: 1500, format: "uuuu"` parses "1500" as a year).
            Some(fmts) => match dates::resolve_date_bound_num_in(n, round_up, fmts, tz) {
                Ok(Some(iso)) => Ok(Value::String(iso)),
                Ok(None) => Ok(v),
                Err(e) => Err(date_resolve_err(e, fmt_raw, &n.to_string())),
            },
            // Default format: numbers are epoch-millis instants — the
            // engine's numeric comparator already handles them exactly.
            None => Ok(v),
        },
        _ => Ok(v),
    }
}

fn parse_range(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`range` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`range` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`range` field value must be an object"))?;

    let mut gte = inner.get("gte").cloned();
    let mut gt = inner.get("gt").cloned();
    let mut lte = inner.get("lte").cloned();
    let mut lt = inner.get("lt").cloned();
    let boost = inner
        .get("boost")
        .and_then(|v| v.as_f64())
        .map(|b| b as f32);

    // ES date bound resolution — date math (`now-24h`, `2026-01-01||+1M/d`),
    // partial-date round-up/round-down fills (`lte: "2026-02"` covers through
    // 2026-02-01T23:59:59.999), and the `format` parameter (`uuuu`,
    // `dd/MM/yyyy`, `epoch_millis`, …).  Bounds resolve to canonical ISO
    // instants here so every downstream comparator (JSON-scan, doc-values
    // prefilter, memtable) sees the same concrete value.  An invalid
    // `format` or a value that fails an explicit format is a hard 400,
    // matching live ES 8.13.4.
    let fmt_raw = inner.get("format").and_then(|v| v.as_str());
    let formats = match fmt_raw {
        Some(f) => Some(dates::compile_formats(f).map_err(|e| date_resolve_err(e, fmt_raw, ""))?),
        None => None,
    };
    // `time_zone` applies to bounds without their own offset and to date
    // math rounding; an unknown zone is a 400, as in ES.
    let tz = match inner.get("time_zone").and_then(|v| v.as_str()) {
        Some(raw) => {
            Some(dates::TimeZone::parse(raw).map_err(|e| date_resolve_err(e, fmt_raw, raw))?)
        }
        None => None,
    };
    let tz = tz.as_ref();
    let fmts = formats.as_deref();
    // Round-up bounds: `lte` includes its whole covered interval, `gt`
    // excludes its whole covered interval.  `gte`/`lt` round down.
    if let Some(v) = gte.take() {
        gte = Some(resolve_range_bound(v, false, fmts, fmt_raw, tz)?);
    }
    if let Some(v) = gt.take() {
        gt = Some(resolve_range_bound(v, true, fmts, fmt_raw, tz)?);
    }
    if let Some(v) = lte.take() {
        lte = Some(resolve_range_bound(v, true, fmts, fmt_raw, tz)?);
    }
    if let Some(v) = lt.take() {
        lt = Some(resolve_range_bound(v, false, fmts, fmt_raw, tz)?);
    }

    if gte.is_none() && gt.is_none() && lte.is_none() && lt.is_none() {
        return invalid("`range` query must have at least one bound (gte, gt, lte, lt)");
    }

    Ok(QueryNode::Range {
        field,
        gte,
        gt,
        lte,
        lt,
        boost,
        lenient: false,
    })
}

fn parse_prefix(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`prefix` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`prefix` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    if let Some(value) = raw.as_str() {
        return Ok(QueryNode::Prefix {
            field,
            value: value.to_string(),
            boost: None,
            constant_score: true,
            case_insensitive: false,
        });
    }

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`prefix` field value must be a string or object"))?;

    let value = string_field(inner, "value")?;
    let boost = inner
        .get("boost")
        .and_then(|v| v.as_f64())
        .map(|b| b as f32);
    // #681: honor `_name` on the expanded form, like `parse_term`, so a named
    // prefix clause surfaces in `matched_queries`.
    let name = inner
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    Ok(maybe_named(
        QueryNode::Prefix {
            field,
            value,
            boost,
            constant_score: true,
            case_insensitive: inner
                .get("case_insensitive")
                .and_then(|v| v.as_bool())
                .unwrap_or(false),
        },
        name,
    ))
}

fn parse_wildcard(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`wildcard` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`wildcard` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    if let Some(value) = raw.as_str() {
        return Ok(QueryNode::Wildcard {
            field,
            value: value.to_string(),
            boost: None,
            constant_score: true,
            case_insensitive: false,
        });
    }

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`wildcard` field value must be a string or object"))?;

    let value = string_field(inner, "value")?;
    let boost = inner
        .get("boost")
        .and_then(|v| v.as_f64())
        .map(|b| b as f32);
    // #681: honor `_name` on the expanded form (like `parse_term`).
    let name = inner
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    Ok(maybe_named(
        QueryNode::Wildcard {
            field,
            value,
            boost,
            constant_score: true,
            case_insensitive: inner
                .get("case_insensitive")
                .and_then(|v| v.as_bool())
                .unwrap_or(false),
        },
        name,
    ))
}

fn parse_exists(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`exists` must be an object"))?;

    let field = string_field(obj, "field")?;
    Ok(QueryNode::Exists { field })
}

fn parse_ids(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`ids` must be an object"))?;

    let values = obj
        .get("values")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`ids.values` must be an array"))?
        .iter()
        .map(|v| match v {
            Value::String(s) => Ok(s.clone()),
            Value::Number(n) => Ok(n.to_string()),
            _ => Err(qerr("`ids.values` must contain strings or numbers")),
        })
        .collect::<Result<Vec<_>>>()?;

    let node = QueryNode::Ids { values };
    // `ids.boost` IS the hit score: ES scores an ids query as the constant
    // `boost` (default 1.0) — live-verified on 8.13.4: boost 2.0 / 0.37 /
    // 0.0 all come back verbatim as `_score`. Carried as a `Boosted`
    // wrapper (whose scorer arm already yields the constant `boost` on
    // match) instead of a new AST field, so match semantics are untouched.
    // Was silently dropped (always scored 1.0).
    if let Some(boost) = obj.get("boost").and_then(|v| v.as_f64()) {
        let boost = boost as f32;
        if boost != 1.0 {
            return Ok(QueryNode::Boosted {
                boost,
                query: Box::new(node),
            });
        }
    }
    Ok(node)
}

fn parse_script(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`script` must be an object"))?;
    let script = obj
        .get("script")
        .and_then(Value::as_object)
        .ok_or_else(|| qerr("`script.script` is required"))?;
    let source = script
        .get("source")
        .and_then(Value::as_str)
        .ok_or_else(|| qerr("`script.script.source` is required"))?
        .to_string();
    let params = script.get("params").cloned();
    Ok(QueryNode::Script { source, params })
}

fn parse_query_string(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`query_string` must be an object"))?;

    let query = string_field(obj, "query")?;
    // Defense-in-depth: bound the raw query string length before tokenizing.
    // The depth guard in `parse_qs_unary`'s `LParen` arm caps paren nesting to
    // `MAX_QUERY_DEPTH`, but a pathological non-paren query (e.g. millions of
    // juxtaposed terms) can still blow up the token stream. 64 KiB is far
    // above any realistic Lucene query string (ES effectively limits this too)
    // and well within the 100 MiB request body cap.
    const MAX_QUERY_STRING_LEN: usize = 65_536;
    if query.len() > MAX_QUERY_STRING_LEN {
        return Err(qerr(format!(
            "query_string.query length {} exceeds max of {} characters",
            query.len(),
            MAX_QUERY_STRING_LEN
        )));
    }
    let mut default_field = obj
        .get("default_field")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    // `fields` was accepted and ignored: the key never reached this parser, so
    // `query_string {"query":"x","fields":["title"]}` searched every field —
    // and, once `index: false` became a real rejection, disagreed with
    // `{"default_field":"title"}`, which is the same request written the other
    // way. It is now read and used, the way `simple_query_string` already used
    // its own `fields` list: an unqualified clause is searched over exactly
    // these fields (a `^boost` suffix is honoured), while a `field:value`
    // clause inside the string keeps naming its own field, as in ES.
    let fields: Vec<String> = obj
        .get("fields")
        .and_then(Value::as_array)
        .map(|arr| {
            arr.iter()
                .filter_map(Value::as_str)
                .map(str::to_string)
                .collect()
        })
        .unwrap_or_default();
    let default_operator = parse_bool_operator(obj.get("default_operator")).ok();
    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
    // #1284: explicit `lenient`, else ES's default, which is lenient only when
    // the clause's field set is every field. That is why `bytes:abc` with no
    // `default_field` is a 200 on ES even though the clause names `bytes`.
    let lenient =
        parse_lenient(obj.get("lenient")).unwrap_or_else(|| match default_field.as_deref() {
            Some(df) if fields.is_empty() => df == "*",
            _ => targets_every_field(&fields),
        });

    // Try to lower the query string into a Bool tree so downstream matchers
    // can honor `field:value` + OR/AND syntax.  Fall back to the opaque
    // QueryString node if lowering isn't possible (the FTS path still
    // tokenizes it) — but malformed range syntax is a hard parse error,
    // never a silent term-match fallback.
    if let Some(lowered) = try_lower_query_string(
        &query,
        QsFields {
            default_field: default_field.as_deref(),
            fields: &fields,
            lenient,
        },
        default_operator,
    )? {
        return Ok(match boost {
            Some(b) if b != 1.0 => QueryNode::Boosted {
                boost: b,
                query: Box::new(lowered),
            },
            _ => lowered,
        });
    }

    // Lowering declined (a string this tokenizer cannot handle, e.g. an
    // unterminated quote): the opaque node hands the whole string to the FTS
    // path. A one-element `fields` list means exactly what `default_field`
    // means, so it is carried across rather than dropped. A multi-element list
    // has no representation on this node — that residue is stated as a known
    // gap in the CHANGELOG rather than papered over.
    if default_field.is_none() && fields.len() == 1 {
        default_field = Some(qs_split_boost(&fields[0]).0);
    }

    Ok(QueryNode::QueryString {
        query,
        default_field,
        default_operator,
        boost,
    })
}

/// Split a `fields` entry into its field name and optional `^boost`.
///
/// `"title^3"` → `("title", Some(3.0))`, `"title"` → `("title", None)`. A
/// malformed suffix (`"title^x"`) keeps the whole spec as the name, which is
/// what ES's field-spec parser does with an unparseable boost.
fn qs_split_boost(spec: &str) -> (String, Option<f32>) {
    match spec.rsplit_once('^') {
        Some((name, b)) if !name.is_empty() => match b.parse::<f32>() {
            Ok(b) if b.is_finite() => (name.to_string(), Some(b)),
            _ => (spec.to_string(), None),
        },
        _ => (spec.to_string(), None),
    }
}

/// Where a clause that named no field of its own is searched.
///
/// `query_string` has two ways to say this and ES treats them as the same
/// thing: `default_field` (one field) and `fields` (a list, `^boost` allowed).
/// An empty `fields` with no `default_field` keeps the historical `"*"`
/// placeholder, which downstream means the field-less scan.
#[derive(Clone, Copy)]
struct QsFields<'a> {
    default_field: Option<&'a str>,
    fields: &'a [String],
    /// The clause's effective `lenient` (#1284), stamped on every leaf the
    /// string lowers to, field-qualified ones included: ES decides leniency
    /// once per `query_string`, not per clause.
    lenient: bool,
}

impl QsFields<'_> {
    /// The (field, boost) targets for an unqualified clause.
    fn targets(&self) -> Vec<(String, Option<f32>)> {
        if self.fields.is_empty() {
            return vec![(self.default_field.unwrap_or("*").to_string(), None)];
        }
        self.fields.iter().map(|s| qs_split_boost(s)).collect()
    }

    /// Whether an unqualified *range* has a concrete field to land on. A
    /// range needs one real field name; `"*"` is not one.
    fn has_concrete_target(&self) -> bool {
        if self.fields.is_empty() {
            return matches!(self.default_field, Some(df) if !df.is_empty() && df != "*");
        }
        self.fields
            .iter()
            .any(|s| !s.is_empty() && !qs_split_boost(s).0.contains('*'))
    }
}

/// The (field, boost) targets one query-string clause resolves to.
///
/// `explicit` is the `field:` prefix the clause carried, if any: ES keeps an
/// explicitly named field whatever `fields` / `default_field` say, and only an
/// unqualified clause fans out over them.
fn qs_targets(explicit: &str, ctx: QsFields<'_>) -> Vec<(String, Option<f32>)> {
    if explicit.is_empty() {
        ctx.targets()
    } else {
        vec![(explicit.to_string(), None)]
    }
}

/// Combine the per-field copies of one unqualified clause.
///
/// One target stays a bare leaf (the shape every existing query_string test
/// pins); several become a `dis_max`, which is how ES combines a
/// `query_string` over multiple fields — best field wins, no tie-breaker.
fn qs_combine(mut nodes: Vec<QueryNode>) -> Option<QueryNode> {
    match nodes.len() {
        0 => None,
        1 => nodes.pop(),
        _ => Some(QueryNode::DisMax {
            queries: nodes,
            tie_breaker: 0.0,
        }),
    }
}

/// Lower a Lucene-style query string into a QueryNode::Bool tree.
///
/// Supports:
///  - `field:value` → Match on that field
///  - `value` → Match on `default_field` / each entry of `fields` (a `dis_max`
///    when there is more than one), else the `"*"` field-less placeholder
///  - `A OR B` → Bool.should
///  - `A AND B` → Bool.must
///  - `+A` must, `-A` must_not
///  - parentheses for grouping
///  - quoted phrases `"foo bar"` → MatchPhrase
///  - range syntax: `field:>N`, `field:>=N`, `field:<N`, `field:<=N`,
///    `field:[A TO B]` (inclusive), `field:{A TO B}` (exclusive), mixed
///    `[A TO B}` forms, and `*` as an open end → Range
///
/// Returns `Ok(None)` for anything unrecognized (caller falls back to the
/// legacy opaque-QueryString path) and `Err` for malformed range syntax —
/// ranges must never silently degrade to a term match.
fn try_lower_query_string(
    q: &str,
    ctx: QsFields<'_>,
    default_op: Option<BoolOperator>,
) -> Result<Option<QueryNode>> {
    let Some(tokens) = tokenize_query_string(q)? else {
        return Ok(None);
    };
    if tokens.is_empty() {
        return Ok(None);
    }
    // Range clauses must target a concrete field: resolve unqualified
    // ranges against default_field / fields up-front so `>10` with no usable
    // target errors instead of degrading to a term match.
    // An unqualified range inside `field:( … )` lands on that field (#1298),
    // so track which open parens belong to a field group.
    let mut has_range = false;
    let mut groups: Vec<bool> = Vec::new();
    let mut pending_field_group = false;
    for t in &tokens {
        match t {
            QsTok::FieldGroup(_) => pending_field_group = true,
            QsTok::LParen => groups.push(std::mem::take(&mut pending_field_group)),
            QsTok::RParen => {
                groups.pop();
            }
            _ => {}
        }
        if let QsTok::Range { field, .. } = t {
            has_range = true;
            let in_field_group = groups.iter().any(|g| *g);
            if field.is_empty() && !in_field_group && !ctx.has_concrete_target() {
                return Err(qerr(
                    "query_string range requires an explicit field (e.g. `price:>10`) or a non-wildcard default_field",
                ));
            }
        }
    }
    let mut pos = 0;
    let parsed = parse_qs_or(&tokens, &mut pos, ctx, default_op);
    match parsed {
        Some(node) if pos == tokens.len() => Ok(Some(node)),
        _ if has_range => Err(qerr(format!(
            "failed to parse query_string with range syntax: `{q}`"
        ))),
        _ => Ok(None),
    }
}

#[derive(Debug, Clone)]
// `Range` (a field + four `Option<Value>` bounds) dwarfs the unit
// operator variants; QsTok is a short-lived per-parse token buffer, so
// boxing it would cost more indirection than the transient size saves.
#[allow(clippy::large_enum_variant)]
enum QsTok {
    Term(String, String),   // (field, value) — field empty if unqualified
    Phrase(String, String), // (field, value)
    Range {
        // field empty if unqualified
        field: String,
        gt: Option<Value>,
        gte: Option<Value>,
        lt: Option<Value>,
        lte: Option<Value>,
    },
    /// `field:` directly before a `(`: the group that follows is scoped to
    /// `field` (#1298). Always immediately followed by `LParen`.
    FieldGroup(String),
    Or,
    And,
    Not,
    Must,
    LParen,
    RParen,
}

/// Parse a range bound value from a Lucene query_string range expression.
/// Numbers become JSON numbers (so the Range matcher compares numerically)
/// and everything else stays a string — date math / partial-date resolution
/// happens in the callers (`qs_parse_bracket_range` / `qs_parse_cmp_range`),
/// which know whether the bound rounds up or down. Surrounding quotes are
/// stripped; `*` / empty → open end.
fn qs_range_bound(raw: &str) -> Option<Value> {
    let mut t = raw.trim();
    if t.len() >= 2 && t.starts_with('"') && t.ends_with('"') {
        t = &t[1..t.len() - 1];
    }
    if t.is_empty() || t == "*" {
        return None;
    }
    if let Ok(n) = t.parse::<i64>() {
        return Some(Value::from(n));
    }
    if let Ok(f) = t.parse::<f64>() {
        if f.is_finite() {
            return Some(Value::from(f));
        }
    }
    Some(Value::String(t.to_string()))
}

/// Apply ES date semantics (rounding + date math, default format) to one
/// query_string range bound.
fn qs_resolve_bound(v: Option<Value>, round_up: bool) -> Result<Option<Value>> {
    match v {
        Some(b) => Ok(Some(resolve_range_bound(b, round_up, None, None, None)?)),
        None => Ok(None),
    }
}

/// Parse a bracket range (`[A TO B]` / `{A TO B}` / mixed) starting at byte
/// offset `open` in `q` (pointing at the opening bracket). Returns the token
/// and the byte offset just past the closing bracket.
fn qs_parse_bracket_range(q: &str, field: &str, open: usize) -> Result<(QsTok, usize)> {
    let bytes = q.as_bytes();
    let inclusive_lo = bytes[open] == b'[';
    let mut j = open + 1;
    while j < bytes.len() && bytes[j] != b']' && bytes[j] != b'}' {
        j += 1;
    }
    if j >= bytes.len() {
        return Err(qerr(format!(
            "unterminated range in query_string: `{}`",
            &q[open..]
        )));
    }
    let inclusive_hi = bytes[j] == b']';
    let inner = &q[open + 1..j];
    let parts: Vec<&str> = inner.split_whitespace().collect();
    if parts.len() != 3 || !parts[1].eq_ignore_ascii_case("TO") {
        return Err(qerr(format!(
            "malformed range in query_string: expected `[<lower> TO <upper>]`, got `{}`",
            &q[open..=j]
        )));
    }
    let lo = qs_range_bound(parts[0]);
    let hi = qs_range_bound(parts[2]);
    if lo.is_none() && hi.is_none() {
        return Err(qerr(
            "query_string range must have at least one non-`*` bound",
        ));
    }
    let (mut gt, mut gte, mut lt, mut lte) = (None, None, None, None);
    // ES rounding: exclusive lower (`gt`) and inclusive upper (`lte`) round
    // up; the other two round down.
    if inclusive_lo {
        gte = qs_resolve_bound(lo, false)?;
    } else {
        gt = qs_resolve_bound(lo, true)?;
    }
    if inclusive_hi {
        lte = qs_resolve_bound(hi, true)?;
    } else {
        lt = qs_resolve_bound(hi, false)?;
    }
    Ok((
        QsTok::Range {
            field: field.to_string(),
            gt,
            gte,
            lt,
            lte,
        },
        j + 1,
    ))
}

/// Parse a comparison range (`>N`, `>=N`, `<N`, `<=N`). `rest` is the text
/// after the `field:` prefix within the scanned token; `i` is the byte offset
/// in `q` where the token scanner stopped — the scanner breaks on `-`/`+`,
/// which are value characters here (negative numbers, dates like
/// `2020-01-01`), so the value is extended from the raw string. Returns the
/// token and the byte offset just past the value.
fn qs_parse_cmp_range(q: &str, field: &str, rest: &str, mut i: usize) -> Result<(QsTok, usize)> {
    let bytes = q.as_bytes();
    let (op, mut val) = if let Some(v) = rest.strip_prefix(">=") {
        (">=", v.to_string())
    } else if let Some(v) = rest.strip_prefix("<=") {
        ("<=", v.to_string())
    } else if let Some(v) = rest.strip_prefix('>') {
        (">", v.to_string())
    } else {
        ("<", rest[1..].to_string())
    };
    while i < bytes.len() {
        let c = bytes[i] as char;
        // ASCII-only: this returns `i` to `tokenize_query_string`, which
        // resumes scanning there and slices `&q[..]` from it. Stopping on a
        // Latin-1-looking continuation byte (0xA0) would hand back an offset in
        // the middle of a character and panic the caller's slice — see the
        // invariant documented on `tokenize_query_string`.
        if c.is_ascii_whitespace() || c == '(' || c == ')' {
            break;
        }
        val.push(c);
        i += 1;
    }
    let bound = qs_range_bound(&val).ok_or_else(|| {
        qerr(format!(
            "query_string range `{field}:{op}` is missing a value"
        ))
    })?;
    let (mut gt, mut gte, mut lt, mut lte) = (None, None, None, None);
    // ES rounding: `>` and `<=` round the bound up, `>=` and `<` round down.
    match op {
        ">" => gt = Some(resolve_range_bound(bound, true, None, None, None)?),
        ">=" => gte = Some(resolve_range_bound(bound, false, None, None, None)?),
        "<" => lt = Some(resolve_range_bound(bound, false, None, None, None)?),
        _ => lte = Some(resolve_range_bound(bound, true, None, None, None)?),
    }
    Ok((
        QsTok::Range {
            field: field.to_string(),
            gt,
            gte,
            lt,
            lte,
        },
        i,
    ))
}

/// Tokenize a Lucene query string. `Ok(None)` means "can't tokenize — fall
/// back to the opaque QueryString path"; `Err` is a hard parse error
/// (malformed range syntax must not degrade to a term match).
/// Tokenise a Lucene `query_string`.
///
/// SAFETY-OF-SLICING INVARIANT: this scanner walks BYTES — `bytes[i] as char`
/// reinterprets each byte as Latin-1 — but slices `&q[start..i]` as a `&str`.
/// That is only sound if every position it can stop at is a character
/// boundary, which is why every delimiter test below is `is_ascii_*`: the bytes
/// of a multi-byte UTF-8 character are all >= 0x80, so an ASCII test can never
/// match one, and the scan can never stop inside a character.
///
/// It used to test `is_whitespace()`, which is true for Latin-1 NBSP (0xA0) —
/// a *continuation byte*. `query_string: "…_٠…"` (U+0660, encoded D9 A0) broke
/// the token scan between the two bytes and panicked on the slice. The release
/// profile sets `panic = "abort"`, so that was not a 400 on an unauthenticated
/// `?q=`, it was the process. Found by the `query_string` fuzz target (#207).
///
/// Nothing is lost by the narrowing: the only non-ASCII bytes `is_whitespace()`
/// accepted were 0x85 and 0xA0, and both are continuation bytes, never a
/// standalone character in valid UTF-8. Real Unicode whitespace (U+3000 and
/// friends) was already token content here.
fn tokenize_query_string(q: &str) -> Result<Option<Vec<QsTok>>> {
    let bytes = q.as_bytes();
    let mut out: Vec<QsTok> = Vec::new();
    let mut i = 0;
    while i < bytes.len() {
        let c = bytes[i] as char;
        if c.is_ascii_whitespace() {
            i += 1;
            continue;
        }
        if c == '(' {
            out.push(QsTok::LParen);
            i += 1;
            continue;
        }
        if c == ')' {
            out.push(QsTok::RParen);
            i += 1;
            continue;
        }
        if c == '+' {
            out.push(QsTok::Must);
            i += 1;
            continue;
        }
        if c == '-' {
            out.push(QsTok::Not);
            i += 1;
            continue;
        }
        // Quoted phrase — optional `field:"value"` prefix handled below.
        if c == '"' {
            let start = i + 1;
            let mut j = start;
            while j < bytes.len() && bytes[j] as char != '"' {
                j += 1;
            }
            if j >= bytes.len() {
                return Ok(None);
            }
            let val = q[start..j].to_string();
            out.push(QsTok::Phrase(String::new(), val));
            i = j + 1;
            continue;
        }
        // Unqualified bracket range on the default field: `[A TO B]` / `{A TO B}`.
        if c == '[' || c == '{' {
            let (tok, next) = qs_parse_bracket_range(q, "", i)?;
            out.push(tok);
            i = next;
            continue;
        }
        // Bare token (possibly field:value or field:"value").
        //
        // NOTE: `+` / `-` are Lucene unary operators ONLY at the start of a
        // clause (handled by the top-of-loop checks above, which can only
        // fire at a fresh scan position). INSIDE a bare token they are
        // literal characters — `model:claude-haiku-4-5` is ONE term, not
        // `model:claude NOT haiku NOT 4 NOT 5`. Breaking on mid-token `-`
        // shredded hyphenated keyword values and made e.g.
        // `query_string: "model:claude-haiku-4-5 AND status:ok"` match a
        // garbage clause tree instead of the two field terms.
        let start = i;
        while i < bytes.len() {
            let ch = bytes[i] as char;
            // ASCII-only, per the slicing invariant on this function.
            if ch.is_ascii_whitespace() || ch == '(' || ch == ')' {
                break;
            }
            i += 1;
        }
        let tok = &q[start..i];
        // Keywords OR / AND / NOT (case-insensitive, must stand alone).
        match tok {
            "OR" | "or" | "||" => {
                out.push(QsTok::Or);
                continue;
            }
            "AND" | "and" | "&&" => {
                out.push(QsTok::And);
                continue;
            }
            "NOT" | "not" | "!" => {
                out.push(QsTok::Not);
                continue;
            }
            _ => {}
        }
        // Lucene query_string unescapes `\X` → `X` for any char X;
        // common cases are `\/`, `\+`, `\-`, `\(`, etc. Unescape here so
        // the downstream matcher compares against the literal value
        // rather than a value-with-stray-backslash.
        fn unescape_qs(s: &str) -> String {
            let mut out = String::with_capacity(s.len());
            let mut chars = s.chars();
            while let Some(c) = chars.next() {
                if c == '\\' {
                    if let Some(nxt) = chars.next() {
                        out.push(nxt);
                    }
                } else {
                    out.push(c);
                }
            }
            out
        }
        // field:value or field:"value"
        if let Some(colon) = tok.find(':') {
            let field = &tok[..colon];
            let rest = &tok[colon + 1..];
            if let Some(after_quote) = rest.strip_prefix('"') {
                // Consume continuation until matching quote (may have been split).
                let mut buf = after_quote.to_string();
                if buf.ends_with('"') {
                    buf.pop();
                    out.push(QsTok::Phrase(field.to_string(), buf));
                } else {
                    // Rejoin from original string.
                    let mut j = i;
                    while j < bytes.len() && bytes[j] as char != '"' {
                        j += 1;
                    }
                    if j >= bytes.len() {
                        return Ok(None);
                    }
                    let whole = format!("{} {}", buf, &q[i..j]);
                    out.push(QsTok::Phrase(field.to_string(), whole));
                    i = j + 1;
                }
            } else if rest.starts_with('[') || rest.starts_with('{') {
                // field:[A TO B] / field:{A TO B} — the bare-token scan stops
                // at whitespace, so re-scan the raw string from the bracket.
                let (rtok, next) = qs_parse_bracket_range(q, field, start + colon + 1)?;
                out.push(rtok);
                i = next;
            } else if rest.starts_with('>') || rest.starts_with('<') {
                // field:>N / field:>=N / field:<N / field:<=N
                let (rtok, next) = qs_parse_cmp_range(q, field, rest, i)?;
                out.push(rtok);
                i = next;
            } else if rest.is_empty()
                && q[i..]
                    .trim_start_matches(|c: char| c.is_ascii_whitespace())
                    .starts_with('(')
            {
                // `field:(a OR b)` (also `field: (…)`): the bare-token scan
                // stopped at the `(`, leaving `field:` with no value. Lucene
                // scopes the whole group to `field`; before #1298 this became
                // an empty-valued term and the group searched every field.
                out.push(QsTok::FieldGroup(field.to_string()));
                while bytes[i].is_ascii_whitespace() {
                    i += 1;
                }
            } else {
                out.push(QsTok::Term(field.to_string(), unescape_qs(rest)));
            }
        } else if tok.starts_with('>') || tok.starts_with('<') {
            // Unqualified comparison range on the default field: `>N`, `<=N`, …
            let (rtok, next) = qs_parse_cmp_range(q, "", tok, i)?;
            out.push(rtok);
            i = next;
        } else {
            out.push(QsTok::Term(String::new(), unescape_qs(tok)));
        }
    }
    Ok(Some(out))
}

/// How one clause of a query-string boolean takes part in it.
#[derive(Clone, Copy, PartialEq)]
enum QsOccur {
    Must,
    Should,
    MustNot,
}

/// The conjunction written before a clause.
#[derive(Clone, Copy, PartialEq)]
enum QsConj {
    None,
    And,
    Or,
}

/// Parse one boolean level of a query string: clauses up to the end of the
/// input or the closing `)` of the current group.
///
/// Every clause of one level lands in ONE boolean, with an occur decided the
/// way Lucene's classic query parser decides it (`QueryParserBase.addClause`,
/// Apache-2.0; approach only, nothing copied), which is what ES 8.13.4 runs:
///
/// - `AND` before a clause makes the clause before it required too, unless
///   that one is prohibited;
/// - with `default_operator: AND`, `OR` before a clause makes the clause
///   before it optional, unless it is prohibited;
/// - `-` / `NOT` make a clause prohibited (MUST_NOT) whatever the operator;
/// - otherwise, under `OR` a clause is required only with `+` or after
///   `AND`; under `AND` every clause not introduced by `OR` is required.
///
/// So `kiwi OR lime AND plum` is `kiwi +lime +plum`, not
/// `kiwi OR (lime AND plum)`. A prohibited clause excludes from the whole
/// level: before #1299, `alpha -beta` built `alpha OR (NOT beta)`, whose
/// pure-negative branch matched every document without `beta`.
fn parse_qs_or(
    toks: &[QsTok],
    pos: &mut usize,
    ctx: QsFields<'_>,
    default_op: Option<BoolOperator>,
) -> Option<QueryNode> {
    let default_and = matches!(default_op, Some(BoolOperator::And));
    let mut clauses: Vec<(QsOccur, QueryNode)> = Vec::new();
    while *pos < toks.len() && !matches!(toks[*pos], QsTok::RParen) {
        let mut conj = QsConj::None;
        while let Some(t) = toks.get(*pos) {
            match t {
                QsTok::And => conj = QsConj::And,
                QsTok::Or => conj = QsConj::Or,
                _ => break,
            }
            *pos += 1;
        }
        let (mut req_mod, mut not_mod) = (false, false);
        while let Some(t) = toks.get(*pos) {
            match t {
                QsTok::Must => req_mod = true,
                QsTok::Not => not_mod = true,
                _ => break,
            }
            *pos += 1;
        }
        // A dangling operator (`kiwi AND`, `kiwi -`) has no clause to apply
        // to: decline, and the caller falls back to the opaque node.
        // `default_op` is threaded so a `field:( … )` group inside a clause
        // (#1298) keeps the operator in effect.
        let node = parse_qs_unary(toks, pos, ctx, default_op)?;

        if let Some(prev) = clauses.last_mut() {
            if prev.0 != QsOccur::MustNot {
                if conj == QsConj::And {
                    prev.0 = QsOccur::Must;
                } else if conj == QsConj::Or && default_and {
                    prev.0 = QsOccur::Should;
                }
            }
        }
        let required = if default_and {
            !not_mod && conj != QsConj::Or
        } else {
            req_mod || (conj == QsConj::And && !not_mod)
        };
        let occur = if not_mod {
            QsOccur::MustNot
        } else if required {
            QsOccur::Must
        } else {
            QsOccur::Should
        };
        clauses.push((occur, node));
    }

    if clauses.len() == 1 && clauses[0].0 != QsOccur::MustNot {
        return clauses.pop().map(|(_, n)| n);
    }
    if clauses.is_empty() {
        return None;
    }
    let (mut must, mut should, mut must_not) = (Vec::new(), Vec::new(), Vec::new());
    for (occur, node) in clauses {
        match occur {
            QsOccur::Must => must.push(node),
            QsOccur::Should => should.push(node),
            QsOccur::MustNot => must_not.push(node),
        }
    }
    // With a required clause, the optional ones only add score (Lucene and
    // ES `bool`); with none, at least one of them must match.
    let minimum_should_match =
        (must.is_empty() && !should.is_empty()).then_some(MinShouldMatch::Fixed(1));
    Some(QueryNode::Bool {
        must,
        should,
        must_not,
        filter: vec![],
        minimum_should_match,
    })
}

fn parse_qs_unary(
    toks: &[QsTok],
    pos: &mut usize,
    ctx: QsFields<'_>,
    default_op: Option<BoolOperator>,
) -> Option<QueryNode> {
    if *pos >= toks.len() {
        return None;
    }
    match toks[*pos].clone() {
        QsTok::FieldGroup(field) => {
            // `field:( … )` (#1298): parse the group as if `field` were the
            // only default field, so every unqualified clause inside it
            // (terms, phrases, wildcards, ranges, nested groups) targets
            // `field`. A clause inside that names its own field keeps it,
            // as in ES. The tokenizer always emits `LParen` next.
            *pos += 1;
            if !matches!(toks.get(*pos), Some(QsTok::LParen)) {
                return None;
            }
            let scoped = QsFields {
                default_field: Some(&field),
                fields: &[],
                // Leniency is decided once per `query_string` (#1284), so the
                // scoped group inherits the parent clause's setting.
                lenient: ctx.lenient,
            };
            parse_qs_unary(toks, pos, scoped, default_op)
        }
        QsTok::LParen => {
            *pos += 1;
            // Bound paren-nesting depth. The shared thread-local `QUERY_DEPTH`
            // is already at 1 from the outer `parse_query` call that dispatched
            // to `parse_query_string` → `try_lower_query_string`. Each `LParen`
            // recurses `parse_qs_or → parse_qs_and → parse_qs_unary`, so without
            // this guard a ~100 k-paren query string overflows the tokio worker
            // stack (default 2 MiB) and aborts the process with SIGSEGV — not
            // catchable by `catch_unwind`. On overflow we return `None`, which
            // `try_lower_query_string` turns into a graceful fallback to the
            // opaque `QueryNode::QueryString` path (iterative tokenizer, no
            // recursion). The guard decrements on drop when this arm returns.
            let _depth_guard = DepthGuard::enter().ok()?;
            // `default_operator` applies inside a group too: on ES 8.13.4
            // `(alpha beta)` with `AND` needs both terms. Passing `None`
            // here made every group implicitly OR.
            let n = parse_qs_or(toks, pos, ctx, default_op)?;
            if *pos >= toks.len() || !matches!(toks[*pos], QsTok::RParen) {
                return None;
            }
            *pos += 1;
            Some(n)
        }
        QsTok::Term(field, value) => {
            *pos += 1;
            // A clause that named its own field keeps it; one that did not is
            // searched over every target `default_field` / `fields` supplies,
            // combined by `qs_combine`.
            let targets = qs_targets(&field, ctx);
            // A bare term containing `*` or `?` is a Lucene wildcard —
            // emit a Wildcard query so `q=shor*` / `q=te?t` match text
            // tokens with the expected substitution semantics.
            //
            // ES lowercases wildcard/prefix terms in `query_string` (the field's
            // search analyzer normalizes them) — e.g. `q=field:BA*` matches the
            // indexed lowercased token `bar`.  The raw `wildcard` query does NOT
            // analyze its pattern (case-sensitive), so this lowering lives HERE
            // in the query_string path only.  Harmless for keyword fields, whose
            // FST-wildcard route case-folds both sides regardless.
            if value.contains('*') || value.contains('?') {
                // ES's query_string parser produces a WildcardQuery (or
                // PrefixQuery for a trailing `*`) with the default
                // CONSTANT_SCORE rewrite — every match scores a flat 1.0
                // (× boost), no BM25 — exactly like the standalone
                // `wildcard` / `prefix` queries (4c69c05).  Live-verified
                // vs ES 8.13.4: `model:claude-*` → max_score 1.0,
                // `model:claude-* AND status:ok` → 1.0 + BM25(status:ok).
                // `constant_score: true` also admits the keyword shape to
                // the columnar Filtered plan (seq-ascending → ES tie order).
                let lowered = value.to_lowercase();
                return qs_combine(
                    targets
                        .into_iter()
                        .map(|(f, boost)| QueryNode::Wildcard {
                            field: f,
                            value: lowered.clone(),
                            boost,
                            constant_score: true,
                            case_insensitive: true,
                        })
                        .collect(),
                );
            }
            qs_combine(
                targets
                    .into_iter()
                    .map(|(f, boost)| QueryNode::Match {
                        field: f,
                        query: value.clone(),
                        operator: BoolOperator::Or,
                        analyzer: None,
                        boost,
                        minimum_should_match: None,
                        lenient: ctx.lenient,
                    })
                    .collect(),
            )
        }
        QsTok::Phrase(field, value) => {
            *pos += 1;
            qs_combine(
                qs_targets(&field, ctx)
                    .into_iter()
                    .map(|(f, boost)| QueryNode::MatchPhrase {
                        field: f,
                        query: value.clone(),
                        slop: 0,
                        analyzer: None,
                        boost,
                        lenient: ctx.lenient,
                    })
                    .collect(),
            )
        }
        QsTok::Range {
            field,
            gt,
            gte,
            lt,
            lte,
        } => {
            *pos += 1;
            // Unqualified ranges with no usable target were already rejected
            // in try_lower_query_string. A pattern entry in `fields` has no
            // meaning for a range, so those targets are dropped here rather
            // than turned into a `Range` on the literal field name `"*"`.
            let targets: Vec<(String, Option<f32>)> = qs_targets(&field, ctx)
                .into_iter()
                .filter(|(f, _)| !field.is_empty() || !f.contains('*'))
                .collect();
            qs_combine(
                targets
                    .into_iter()
                    .map(|(f, boost)| QueryNode::Range {
                        field: f,
                        gte: gte.clone(),
                        gt: gt.clone(),
                        lte: lte.clone(),
                        lt: lt.clone(),
                        boost,
                        lenient: ctx.lenient,
                    })
                    .collect(),
            )
        }
        _ => None,
    }
}

fn parse_fuzzy(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`fuzzy` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`fuzzy` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    // Shorthand: {"fuzzy": {"name": "prodct"}}
    if let Some(value) = raw.as_str() {
        return Ok(QueryNode::Fuzzy {
            field,
            value: value.to_string(),
            fuzziness: Fuzziness::Auto,
            case_insensitive: false,
            prefix_length: 0,
        });
    }

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`fuzzy` field value must be a string or object"))?;

    let value = string_field(inner, "value")?;
    let fuzziness = match inner.get("fuzziness") {
        Some(Value::String(s)) if s.to_uppercase() == "AUTO" => Fuzziness::Auto,
        Some(Value::String(s)) => {
            let n = s.parse::<u32>().map_err(|_| {
                qerr(format!(
                    "`fuzzy.fuzziness` must be 'AUTO' or an integer, got '{s}'"
                ))
            })?;
            Fuzziness::Fixed(n)
        }
        Some(Value::Number(n)) => {
            let n = n
                .as_u64()
                .ok_or_else(|| qerr("`fuzzy.fuzziness` must be a non-negative integer"))?
                as u32;
            Fuzziness::Fixed(n)
        }
        None => Fuzziness::Auto,
        _ => return invalid("`fuzzy.fuzziness` must be 'AUTO' or an integer"),
    };

    let case_insensitive = inner
        .get("case_insensitive")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let prefix_length = parse_prefix_length(inner);
    Ok(QueryNode::Fuzzy {
        field,
        value,
        fuzziness,
        case_insensitive,
        prefix_length,
    })
}

/// #848: read ES `prefix_length` off a fuzzy/match parameter object. Accepts a
/// non-negative number or its string spelling; defaults to `0` (no constraint).
fn parse_prefix_length(obj: &serde_json::Map<String, Value>) -> usize {
    match obj.get("prefix_length") {
        Some(Value::Number(n)) => n.as_u64().unwrap_or(0) as usize,
        Some(Value::String(s)) => s.parse::<usize>().unwrap_or(0),
        _ => 0,
    }
}

fn parse_regexp(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`regexp` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`regexp` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    if let Some(pattern) = raw.as_str() {
        return Ok(QueryNode::Regexp {
            field,
            pattern: pattern.to_string(),
            case_insensitive: false,
        });
    }

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`regexp` field value must be a string or object"))?;

    let pattern = string_field(inner, "value")?;
    let case_insensitive = inner
        .get("case_insensitive")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    Ok(QueryNode::Regexp {
        field,
        pattern,
        case_insensitive,
    })
}

fn parse_match_phrase_prefix(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`match_phrase_prefix` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`match_phrase_prefix` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    // Empty query string → match_none, not a parse error. See `parse_match`.
    // This is exactly what Kibana's own SavedObjectsClient `_find` builds
    // for a trailing-`*` search term.
    if matches!(raw, Value::String(s) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    // Shorthand forms: `match_phrase_prefix: {field: "value"}`, `{field:
    // 42}`, `{field: true}` — ES silently stringifies non-strings, same as
    // `match` (see `scalar_to_string`).
    if let Some(query) = scalar_to_string(raw) {
        return Ok(QueryNode::MatchPhrasePrefix {
            field,
            query,
            max_expansions: 50,
            slop: 0,
        });
    }

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`match_phrase_prefix` field value must be a string or object"))?;

    if matches!(inner.get("query"), Some(Value::String(s)) if s.is_empty()) {
        return Ok(QueryNode::MatchNone);
    }

    let query = inner
        .get("query")
        .and_then(scalar_to_string)
        .ok_or_else(|| qerr("`match_phrase_prefix.query` must be a non-empty scalar"))?;
    // `max_expansions` used to be read with `as_u64().unwrap_or(50)`, so
    // `-1`, `"7"` and `7.0` all silently became 50 — the same accept-and-ignore
    // (#204) as the dropped `slop` below, one line apart. It is now the shared
    // parse: a value we cannot read is a 400, and `0` stays accepted because
    // ES accepts it *here* (it rejects it on `multi_match`; the asymmetry is
    // ES's own, see `parse_max_expansions`).
    let max_expansions = parse_max_expansions(
        inner.get("max_expansions"),
        "match_phrase_prefix",
        /* allow_zero */ true,
    )?;
    // `slop` used to be read nowhere here, so
    // `{"match_phrase_prefix": {"f": {"query": …, "slop": 2}}}` was accepted
    // and answered as slop 0 — accept-and-ignore (#204 class), and a silent
    // disagreement with the `multi_match` form of the same query. ES parses
    // and honours it (`MatchPhrasePrefixQueryBuilder.fromXContent` →
    // `MatchQueryParser.setPhraseSlop`), and both XERJ evaluators now carry
    // it: `PhrasePrefixQuery.slop` on segments, the sloppy prefix walk in
    // the stored-doc scan.
    let slop = parse_phrase_slop(inner.get("slop"), "match_phrase_prefix")?;

    Ok(QueryNode::MatchPhrasePrefix {
        field,
        query,
        max_expansions,
        slop,
    })
}

#[derive(Debug, Clone, PartialEq)]
enum SqsTok {
    Term(String),
    Phrase(String),
    And,    // `+`
    Or,     // `|`
    Not,    // `-`
    LParen, // `(`
    RParen, // `)`
}

fn unescape_sqs(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut chars = s.chars();
    while let Some(c) = chars.next() {
        if c == '\\' {
            if let Some(nxt) = chars.next() {
                out.push(nxt);
            }
        } else {
            out.push(c);
        }
    }
    out
}

fn tokenize_simple_query_string(q: &str) -> Vec<SqsTok> {
    let bytes = q.as_bytes();
    let mut out: Vec<SqsTok> = Vec::new();
    let mut i = 0;
    while i < bytes.len() {
        let c = bytes[i] as char;
        if c.is_ascii_whitespace() {
            i += 1;
            continue;
        }
        if c == '(' {
            out.push(SqsTok::LParen);
            i += 1;
            continue;
        }
        if c == ')' {
            out.push(SqsTok::RParen);
            i += 1;
            continue;
        }
        if c == '|' {
            i += 1;
            if i < bytes.len() && bytes[i] as char == '|' {
                i += 1;
            }
            out.push(SqsTok::Or);
            continue;
        }
        if c == '+' {
            out.push(SqsTok::And);
            i += 1;
            continue;
        }
        if c == '-' {
            out.push(SqsTok::Not);
            i += 1;
            continue;
        }
        if c == '"' {
            let start = i + 1;
            let mut j = start;
            while j < bytes.len() {
                if bytes[j] as char == '\\' && j + 1 < bytes.len() {
                    j += 2;
                } else if bytes[j] as char == '"' {
                    break;
                } else {
                    j += 1;
                }
            }
            let phrase = unescape_sqs(&q[start..j]);
            if !phrase.is_empty() {
                out.push(SqsTok::Phrase(phrase));
            }
            if j < bytes.len() && bytes[j] as char == '"' {
                i = j + 1;
            } else {
                i = j;
            }
            continue;
        }

        // Bare term: read until whitespace, '(', ')', '|', or '"'
        // NOTE: '+' or '-' inside a term (e.g. "c++", "node-fetch", "2024-05-01")
        // is part of the term, so we do not stop on '+' or '-' mid-term.
        let start = i;
        while i < bytes.len() {
            let ch = bytes[i] as char;
            if ch.is_ascii_whitespace() || ch == '(' || ch == ')' || ch == '|' || ch == '"' {
                break;
            }
            if ch == '\\' && i + 1 < bytes.len() {
                i += 2;
                continue;
            }
            i += 1;
        }
        let tok = unescape_sqs(&q[start..i]);
        if !tok.is_empty() {
            out.push(SqsTok::Term(tok));
        }
    }
    out
}

fn parse_sqs_unary(
    toks: &[SqsTok],
    pos: &mut usize,
    fields: &[String],
    lenient: bool,
    default_and: bool,
) -> Option<QueryNode> {
    while *pos < toks.len() {
        match &toks[*pos] {
            SqsTok::LParen => {
                *pos += 1;
                let _depth_guard = DepthGuard::enter().ok()?;
                let inner = parse_sqs_level(toks, pos, fields, lenient, default_and);
                if *pos < toks.len() && matches!(toks[*pos], SqsTok::RParen) {
                    *pos += 1;
                }
                return inner;
            }
            SqsTok::RParen => {
                *pos += 1;
            }
            SqsTok::Term(term) => {
                *pos += 1;
                return Some(make_simple_query_node(term, false, fields, lenient));
            }
            SqsTok::Phrase(phrase) => {
                *pos += 1;
                return Some(make_simple_query_node(phrase, true, fields, lenient));
            }
            _ => return None,
        }
    }
    None
}

fn parse_sqs_level(
    toks: &[SqsTok],
    pos: &mut usize,
    fields: &[String],
    lenient: bool,
    default_and: bool,
) -> Option<QueryNode> {
    let mut clauses: Vec<(QsOccur, QueryNode)> = Vec::new();

    while *pos < toks.len() && !matches!(toks[*pos], SqsTok::RParen) {
        let mut conj = QsConj::None;
        let mut req_mod = false;
        let mut not_mod = false;

        while let Some(t) = toks.get(*pos) {
            match t {
                SqsTok::And => {
                    if clauses.is_empty() || conj != QsConj::None {
                        req_mod = true;
                    } else {
                        conj = QsConj::And;
                    }
                }
                SqsTok::Or => {
                    conj = QsConj::Or;
                }
                SqsTok::Not => {
                    not_mod = true;
                }
                _ => break,
            }
            *pos += 1;
        }

        if *pos >= toks.len() || matches!(toks[*pos], SqsTok::RParen) {
            break;
        }

        let Some(node) = parse_sqs_unary(toks, pos, fields, lenient, default_and) else {
            continue;
        };

        if let Some(prev) = clauses.last_mut() {
            if prev.0 != QsOccur::MustNot {
                if conj == QsConj::And {
                    prev.0 = QsOccur::Must;
                } else if conj == QsConj::Or && default_and {
                    prev.0 = QsOccur::Should;
                }
            }
        }

        let required = if default_and {
            !not_mod && conj != QsConj::Or
        } else {
            req_mod || (conj == QsConj::And && !not_mod)
        };

        let occur = if not_mod {
            QsOccur::MustNot
        } else if required {
            QsOccur::Must
        } else {
            QsOccur::Should
        };

        clauses.push((occur, node));
    }

    if clauses.is_empty() {
        return None;
    }

    let (mut must, mut should, mut must_not) = (Vec::new(), Vec::new(), Vec::new());
    for (occur, node) in clauses {
        match occur {
            QsOccur::Must => must.push(node),
            QsOccur::Should => should.push(node),
            QsOccur::MustNot => must_not.push(node),
        }
    }

    let minimum_should_match =
        (must.is_empty() && !should.is_empty()).then_some(MinShouldMatch::Fixed(1));

    Some(QueryNode::Bool {
        must,
        should,
        must_not,
        filter: Vec::new(),
        minimum_should_match,
    })
}

fn parse_simple_query_string(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`simple_query_string` must be an object"))?;

    let query = string_field(obj, "query")?;

    let fields: Vec<String> = obj
        .get("fields")
        .and_then(Value::as_array)
        .map(|arr| {
            arr.iter()
                .filter_map(Value::as_str)
                .map(str::to_string)
                .collect()
        })
        .unwrap_or_default();

    // ES default_operator: "or" (default) means tokens go into `should`
    // with `minimum_should_match`; "and" puts them all into `must`.
    let default_operator = obj
        .get("default_operator")
        .and_then(Value::as_str)
        .unwrap_or("or")
        .to_lowercase();

    let default_and = default_operator == "and";

    let mm: Option<MinShouldMatch> = obj
        .get("minimum_should_match")
        .and_then(|v| parse_min_should_match(v).ok());
    // #1284: same default as `multi_match` / `query_string`.
    let lenient = parse_lenient(obj.get("lenient")).unwrap_or_else(|| targets_every_field(&fields));

    let toks = tokenize_simple_query_string(&query);
    let mut pos = 0;
    let parsed = parse_sqs_level(&toks, &mut pos, &fields, lenient, default_and);

    let node = match parsed {
        Some(QueryNode::Bool {
            must,
            should,
            must_not,
            filter,
            minimum_should_match: auto_mm,
        }) => {
            let final_mm = if mm.is_some() { mm } else { auto_mm };
            QueryNode::Bool {
                must,
                should,
                must_not,
                filter,
                minimum_should_match: final_mm,
            }
        }
        Some(other) => other,
        None => make_simple_query_node(&query, false, &fields, lenient),
    };

    Ok(node)
}

/// Build a Match, MatchPhrase, or MultiMatch node for a term in a simple_query_string.
fn make_simple_query_node(
    term: &str,
    is_phrase: bool,
    fields: &[String],
    lenient: bool,
) -> QueryNode {
    if is_phrase {
        if fields.len() == 1 {
            QueryNode::MatchPhrase {
                field: fields[0].clone(),
                query: term.to_string(),
                slop: 0,
                analyzer: None,
                boost: None,
                lenient,
            }
        } else if fields.is_empty() {
            QueryNode::QueryString {
                query: format!("\"{}\"", term),
                default_field: None,
                default_operator: None,
                boost: None,
            }
        } else {
            QueryNode::MultiMatch {
                fields: fields.to_vec(),
                query: term.to_string(),
                match_type: crate::ast::MultiMatchType::Phrase,
                operator: None,
                analyzer: None,
                boost: None,
                slop: 0,
                max_expansions: 50,
                lenient,
            }
        }
    } else if targets_every_field(fields) {
        // No fields, or the bare `"*"` pattern (#2427). ES reads `["*"]` as
        // "every searchable field" — it is also what an absent `fields`
        // falls back to (`index.query.default_field` defaults to `*`) — so
        // both spellings lower to the same field-less placeholder, which the
        // engine projects onto every mapped text field of each segment's
        // inverted index.
        //
        // `["*"]` used to lower to `Match { field: "*" }` instead. No FTS
        // projection exists for a literal `"*"` field, so that node forced
        // the per-document stored-section scan on EVERY segment: on the
        // 1 GB autoindex gate one 5-hit query walked ~1.2M stored docs in
        // pg-docs and ran into the 30 s request deadline (raw-surface p95
        // 30.1 s). A `"*^2"` boost has no field to attach to on this node
        // and is dropped, as it is for the phrase placeholder below.
        //
        // Quoted phrases keep their own arm above: the field-less
        // placeholder is bag-of-words on the FTS path, so routing a phrase
        // through it would loosen phrase matching.
        QueryNode::QueryString {
            query: term.to_string(),
            default_field: None,
            default_operator: None,
            boost: None,
        }
    } else if fields.len() == 1 {
        QueryNode::Match {
            field: fields[0].clone(),
            query: term.to_string(),
            operator: BoolOperator::Or,
            analyzer: None,
            boost: None,
            minimum_should_match: None,
            lenient,
        }
    } else {
        QueryNode::MultiMatch {
            fields: fields.to_vec(),
            query: term.to_string(),
            match_type: crate::ast::MultiMatchType::BestFields,
            operator: None,
            analyzer: None,
            boost: None,
            slop: 0,
            max_expansions: 50,
            lenient,
        }
    }
}

/// Parse a `geo_distance` query.
///
/// ES format:
/// ```json
/// {
///   "geo_distance": {
///     "distance": "10km",
///     "location": { "lat": 40.7, "lon": -74.0 }
///   }
/// }
/// ```
///
/// The field name is inferred as the key that is not `"distance"`.
fn parse_geo_distance(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`geo_distance` must be an object"))?;

    // Parse the distance string (e.g. "10km", "5mi").
    let distance_str = obj
        .get("distance")
        .and_then(|v| v.as_str())
        .ok_or_else(|| qerr("`geo_distance` requires a `distance` field"))?;

    let distance_km = parse_distance_km(distance_str)?;

    // Find the field key (the one that is not "distance").
    let field_entry = obj
        .iter()
        .find(|(k, _)| k.as_str() != "distance")
        .ok_or_else(|| qerr("`geo_distance` requires a geo_point field"))?;

    let field = field_entry.0.clone();
    let location = field_entry.1;

    let (lat, lon) = parse_lat_lon(location)?;

    Ok(QueryNode::GeoDistance {
        field,
        lat,
        lon,
        distance_km,
    })
}

/// Parse a `geo_bounding_box` query.
///
/// ES format:
/// ```json
/// {
///   "geo_bounding_box": {
///     "location": {
///       "top_left": { "lat": 40.8, "lon": -74.0 },
///       "bottom_right": { "lat": 40.7, "lon": -73.9 }
///     }
///   }
/// }
/// ```
fn parse_geo_bounding_box(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`geo_bounding_box` must be an object"))?;

    // Find the field key (anything that is not a known option key).
    let known_keys = ["_name", "validation_method", "ignore_unmapped"];
    let field_entry = obj
        .iter()
        .find(|(k, _)| !known_keys.contains(&k.as_str()))
        .ok_or_else(|| qerr("`geo_bounding_box` requires a geo_point field"))?;

    let field = field_entry.0.clone();
    let bounds = field_entry.1;

    let bounds_obj = bounds
        .as_object()
        .ok_or_else(|| qerr("`geo_bounding_box` field value must be an object"))?;

    let tl_val = bounds_obj
        .get("top_left")
        .ok_or_else(|| qerr("`geo_bounding_box` requires `top_left`"))?;
    let br_val = bounds_obj
        .get("bottom_right")
        .ok_or_else(|| qerr("`geo_bounding_box` requires `bottom_right`"))?;

    let top_left = parse_lat_lon(tl_val)?;
    let bottom_right = parse_lat_lon(br_val)?;

    Ok(QueryNode::GeoBoundingBox {
        field,
        top_left,
        bottom_right,
    })
}

/// Parse a distance string like "10km", "5mi", "100m" into kilometres.
fn parse_distance_km(s: &str) -> Result<f64> {
    let s = s.trim();
    if let Some(km) = s.strip_suffix("km") {
        km.trim()
            .parse::<f64>()
            .map_err(|_| qerr(format!("invalid distance: `{s}`")))
    } else if let Some(mi) = s.strip_suffix("mi") {
        mi.trim()
            .parse::<f64>()
            .map(|m| m * 1.60934)
            .map_err(|_| qerr(format!("invalid distance: `{s}`")))
    } else if let Some(m) = s.strip_suffix('m') {
        m.trim()
            .parse::<f64>()
            .map(|m| m / 1000.0)
            .map_err(|_| qerr(format!("invalid distance: `{s}`")))
    } else {
        // Bare number interpreted as kilometres.
        s.parse::<f64>()
            .map_err(|_| qerr(format!("invalid distance: `{s}`")))
    }
}

/// Parse a lat/lon value from various ES formats:
///   - `{ "lat": 40.7, "lon": -74.0 }`
///   - `[lon, lat]` (GeoJSON order)
///   - `"40.7,-74.0"` (lat,lon string)
fn parse_lat_lon(value: &Value) -> Result<(f64, f64)> {
    match value {
        Value::Object(obj) => {
            let lat = obj
                .get("lat")
                .and_then(|v| v.as_f64())
                .ok_or_else(|| qerr("geo_point object requires `lat` as a number"))?;
            let lon = obj
                .get("lon")
                .and_then(|v| v.as_f64())
                .ok_or_else(|| qerr("geo_point object requires `lon` as a number"))?;
            Ok((lat, lon))
        }
        Value::Array(arr) if arr.len() == 2 => {
            // GeoJSON order: [lon, lat]
            let lon = arr[0]
                .as_f64()
                .ok_or_else(|| qerr("geo_point array element must be a number"))?;
            let lat = arr[1]
                .as_f64()
                .ok_or_else(|| qerr("geo_point array element must be a number"))?;
            Ok((lat, lon))
        }
        Value::String(s) => {
            // "lat,lon" string
            let parts: Vec<&str> = s.splitn(2, ',').collect();
            if parts.len() != 2 {
                return invalid(format!("geo_point string must be `lat,lon`, got `{s}`"));
            }
            let lat = parts[0]
                .trim()
                .parse::<f64>()
                .map_err(|_| qerr(format!("invalid lat in `{s}`")))?;
            let lon = parts[1]
                .trim()
                .parse::<f64>()
                .map_err(|_| qerr(format!("invalid lon in `{s}`")))?;
            Ok((lat, lon))
        }
        _ => invalid("geo_point must be an object {lat,lon}, array [lon,lat], or 'lat,lon' string"),
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Compound parsers
// ─────────────────────────────────────────────────────────────────────────────

fn parse_bool(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`bool` must be an object"))?;

    let must = parse_clause_list(obj, "must")?;
    let should = parse_clause_list(obj, "should")?;
    let must_not = parse_clause_list(obj, "must_not")?;
    let filter = parse_clause_list(obj, "filter")?;

    // A `boost` on a compound clause must PROPAGATE into the leaf
    // weights (Lucene multiplies the parent boost into each child's
    // weight — weights compose multiplicatively down the tree).
    // Previously dropped silently. The `Boosted` wrapper carries it;
    // every matching/filter path peels the wrapper, and the scored
    // paths compose it into the leaves.
    let boost = obj
        .get("boost")
        .and_then(|v| v.as_f64())
        .map(|b| b as f32)
        .filter(|b| *b != 1.0);

    // #681: honor `_name` on a bool clause (a top-level sibling of
    // must/should/must_not/filter), so a named bool surfaces in
    // matched_queries when it matches. `parse_bool` ignores unknown keys, so
    // this was silently dropped before.
    let name = obj
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    if must.is_empty() && should.is_empty() && must_not.is_empty() && filter.is_empty() {
        // Empty bool == match_all; with a boost, ES scores it `boost`
        // per hit (constant-score semantics), like `match_all{boost}`.
        return Ok(maybe_named(
            match boost {
                Some(b) => QueryNode::Constant {
                    score: b,
                    query: Box::new(QueryNode::MatchAll),
                },
                None => QueryNode::MatchAll,
            },
            name,
        ));
    }

    let minimum_should_match = obj
        .get("minimum_should_match")
        .map(parse_min_should_match)
        .transpose()?;

    let node = QueryNode::Bool {
        must,
        should,
        must_not,
        filter,
        minimum_should_match,
    };
    let node = match boost {
        Some(b) => QueryNode::Boosted {
            boost: b,
            query: Box::new(node),
        },
        None => node,
    };
    Ok(maybe_named(node, name))
}

fn parse_constant_score(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`constant_score` must be an object"))?;

    let filter_val = obj
        .get("filter")
        .ok_or_else(|| qerr("`constant_score` requires a `filter` clause"))?;
    let query = parse_query(filter_val)?;

    // Keep the Constant wrapper: ES scores every `constant_score` hit as
    // exactly `boost` (default 1.0) — flattening returned the INNER query's
    // score instead (live-diverged vs ES 8.13.4: constant_score(term,
    // boost=2.5) scored 1.693… where ES returns 2.5 per hit).  The fast
    // paths the old flatten protected (is_doc_scan_query,
    // try_doc_values_query, try_shortcut_count, query_node_to_fts,
    // doc_matches_query, query_node_to_agg_filter) all peel
    // `QueryNode::Constant` today, and the scored-family columnar path
    // serves the keyword-filter shape bit-exactly.
    let boost = obj.get("boost").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
    Ok(QueryNode::Constant {
        score: boost,
        query: Box::new(query),
    })
}

fn parse_boosting(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`boosting` must be an object"))?;

    let positive_val = obj
        .get("positive")
        .ok_or_else(|| qerr("`boosting` requires a `positive` clause"))?;
    let negative_val = obj
        .get("negative")
        .ok_or_else(|| qerr("`boosting` requires a `negative` clause"))?;

    let positive = parse_query(positive_val)?;
    let negative = parse_query(negative_val)?;
    let negative_boost = obj
        .get("negative_boost")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.1) as f32;

    Ok(QueryNode::Boosting {
        positive: Box::new(positive),
        negative: Box::new(negative),
        negative_boost,
    })
}

fn parse_dis_max(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`dis_max` must be an object"))?;

    let queries_val = obj
        .get("queries")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`dis_max.queries` must be an array"))?;

    let queries = queries_val
        .iter()
        .enumerate()
        .map(|(i, v)| {
            // `dis_max.queries` is a clause list by any other name: each entry
            // is scored against every document, so it multiplies per-document
            // work exactly as a `bool` clause does.
            charge_clause()?;
            parse_query(v).map_err(|e| {
                crate::error::QueryError::Parse(crate::error::ParseError::Invalid(format!(
                    "`dis_max.queries[{i}]`: {e}"
                )))
            })
        })
        .collect::<Result<Vec<_>>>()?;

    if queries.is_empty() {
        return invalid("`dis_max.queries` must not be empty");
    }

    let tie_breaker = obj
        .get("tie_breaker")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.0) as f32;

    let node = QueryNode::DisMax {
        queries,
        tie_breaker,
    };
    // Compound-clause boost — same propagation contract as `bool` (see
    // `parse_bool`): wrap, don't drop.
    Ok(match obj.get("boost").and_then(|v| v.as_f64()) {
        Some(b) if (b as f32) != 1.0 => QueryNode::Boosted {
            boost: b as f32,
            query: Box::new(node),
        },
        _ => node,
    })
}

fn parse_knn(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`knn` must be an object"))?;

    let field = string_field(obj, "field")?;
    let num_candidates = obj
        .get("num_candidates")
        .and_then(|v| v.as_u64())
        .map(|n| n as usize);
    // `k` derivation is unchanged: explicit `k`, else `num_candidates`, else 10.
    let k = obj
        .get("k")
        .and_then(|v| v.as_u64())
        .map(|n| n as usize)
        .or(num_candidates)
        .unwrap_or(10);

    let vector = obj
        .get("query_vector")
        .or_else(|| obj.get("vector"))
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`knn` requires `query_vector` (or `vector`) as a float array"))?
        .iter()
        .map(|v| {
            v.as_f64()
                .ok_or_else(|| qerr("`knn.query_vector` must contain numbers"))
                .map(|f| f as f32)
        })
        .collect::<Result<Vec<f32>>>()?;

    // ES accepts `filter` as a single query object OR an array of queries
    // (implicitly ANDed, exactly like `bool.filter`).
    let filter = match obj.get("filter") {
        None => None,
        Some(Value::Array(arr)) => {
            // Implicitly ANDed, so this is `bool.filter` spelled differently
            // and is charged the same way.
            let parsed: Vec<QueryNode> = arr
                .iter()
                .map(|v| {
                    charge_clause()?;
                    parse_query(v)
                })
                .collect::<Result<_>>()?;
            match parsed.len() {
                0 => None,
                1 => Some(Box::new(parsed.into_iter().next().unwrap())),
                _ => Some(Box::new(QueryNode::Bool {
                    must: Vec::new(),
                    should: Vec::new(),
                    filter: parsed,
                    must_not: Vec::new(),
                    minimum_should_match: None,
                })),
            }
        }
        Some(single) => Some(Box::new(parse_query(single)?)),
    };

    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);

    // ES `knn.similarity` — raw-metric similarity cutoff (docs below it
    // are not matches). Kept raw here; the executor converts it into the
    // equivalent transformed-score threshold per the field's metric.
    let similarity = obj
        .get("similarity")
        .and_then(|v| v.as_f64())
        .map(|s| s as f32);

    Ok(QueryNode::Knn {
        field,
        vector,
        k,
        num_candidates,
        filter,
        boost,
        similarity,
    })
}

fn parse_semantic(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`semantic` must be an object"))?;

    let field = string_field(obj, "field")?;
    let text = string_field(obj, "query")?;
    let k = obj.get("k").and_then(|v| v.as_u64()).unwrap_or(10) as usize;

    let filter = obj
        .get("filter")
        .map(parse_query)
        .transpose()?
        .map(Box::new);

    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);

    Ok(QueryNode::SemanticSearch {
        field,
        text,
        k,
        filter,
        boost,
    })
}

fn parse_hybrid(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`hybrid` must be an object"))?;

    let queries_val = obj
        .get("queries")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`hybrid.queries` must be an array"))?;

    let queries = queries_val
        .iter()
        .enumerate()
        .map(|(i, v)| {
            let entry = v.as_object().ok_or_else(|| {
                qerr(format!(
                    "`hybrid.queries[{i}]` must be an object {{\"query\": <clause>, \"weight\": <number>}}"
                ))
            })?;
            let q_val = entry.get("query").ok_or_else(|| {
                qerr(format!(
                    "`hybrid.queries[{i}]` missing `query`; each item is {{\"query\": <clause>, \"weight\": <number>}} (weight defaults to 1)"
                ))
            })?;
            let query = parse_query(q_val)?;
            let weight = entry.get("weight").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
            Ok(WeightedQuery { query, weight })
        })
        .collect::<Result<Vec<_>>>()?;

    if queries.is_empty() {
        return invalid("`hybrid.queries` must not be empty");
    }

    let fusion = match obj.get("fusion") {
        Some(Value::String(s)) => match s.as_str() {
            "rrf" => FusionStrategy::Rrf { k: 60 },
            "linear" => FusionStrategy::Linear,
            // Learned fusion is not implemented — fail loud rather than
            // silently substituting RRF (which would misrepresent the
            // ranking the caller asked for). AST variant kept for future.
            "learned" => {
                return invalid("hybrid fusion learned is not yet supported; use rrf or linear")
            }
            other => return invalid(format!("unknown hybrid fusion strategy `{other}`")),
        },
        Some(Value::Object(m)) => {
            let t = m.get("type").and_then(|v| v.as_str()).unwrap_or("rrf");
            match t {
                "rrf" => {
                    let k = m.get("k").and_then(|v| v.as_u64()).unwrap_or(60) as u32;
                    FusionStrategy::Rrf { k }
                }
                "linear" => FusionStrategy::Linear,
                // Learned fusion is not implemented — fail loud (see above).
                "learned" => {
                    return invalid("hybrid fusion learned is not yet supported; use rrf or linear")
                }
                other => return invalid(format!("unknown hybrid fusion strategy `{other}`")),
            }
        }
        None => FusionStrategy::default(),
        _ => return invalid("`hybrid.fusion` must be a string or object"),
    };

    Ok(QueryNode::Hybrid { queries, fusion })
}

/// Parse a `function_score` query.
///
/// ```json
/// {
///   "function_score": {
///     "query": { "match_all": {} },
///     "functions": [
///       { "filter": { "term": { "status": "published" } },
///         "field_value_factor": { "field": "popularity", "factor": 1.5, "modifier": "log1p" } },
///       { "weight": 2.0, "filter": { "term": { "featured": true } } }
///     ],
///     "score_mode": "sum",
///     "boost_mode": "multiply",
///     "max_boost": 10.0
///   }
/// }
/// ```
fn parse_function_score(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`function_score` must be an object"))?;

    let name = obj
        .get("_name")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    // Inner query (defaults to match_all).
    let query = match obj.get("query") {
        Some(q) => parse_query(q)?,
        None => QueryNode::MatchAll,
    };

    // Parse functions array.
    let functions: Vec<ScoreFunction> = match obj.get("functions") {
        Some(Value::Array(arr)) => arr
            .iter()
            .map(parse_score_function)
            .collect::<Result<Vec<_>>>()?,
        Some(_) => return invalid("`function_score.functions` must be an array"),
        None => {
            // Shorthand: a single function can be specified inline.
            let f = parse_score_function_inline(obj)?;
            if f.weight.is_none() && f.field_value_factor.is_none() && f.random_score.is_none() {
                Vec::new()
            } else {
                vec![f]
            }
        }
    };

    let score_mode = match obj
        .get("score_mode")
        .and_then(Value::as_str)
        .unwrap_or("multiply")
    {
        "multiply" => ScoreMode::Multiply,
        "sum" => ScoreMode::Sum,
        "avg" => ScoreMode::Avg,
        "first" => ScoreMode::First,
        "max" => ScoreMode::Max,
        "min" => ScoreMode::Min,
        other => return invalid(format!("unknown score_mode `{other}`")),
    };

    let boost_mode = match obj
        .get("boost_mode")
        .and_then(Value::as_str)
        .unwrap_or("multiply")
    {
        "multiply" => BoostMode::Multiply,
        "replace" => BoostMode::Replace,
        "sum" => BoostMode::Sum,
        "avg" => BoostMode::Avg,
        "max" => BoostMode::Max,
        "min" => BoostMode::Min,
        other => return invalid(format!("unknown boost_mode `{other}`")),
    };

    let max_boost = obj
        .get("max_boost")
        .and_then(|v| v.as_f64())
        .map(|b| b as f32);

    let mut node = QueryNode::FunctionScore {
        query: Box::new(query),
        functions,
        score_mode,
        boost_mode,
        max_boost,
    };
    // `function_score.boost` multiplies the BASE query score BEFORE the
    // boost_mode combine (Lucene propagates the boost into the subquery
    // weight; `_explain` shows `*:*^3.0` = 3.0 as the base branch).
    // Live-verified on ES 8.13.4: `{boost:3, fvf(rank=5)}` scores 15
    // (multiply), 8 (sum), 4 (avg), 5 (max), 3 (min), and 5 (replace —
    // the boost has NO effect when the base is discarded). The engine's
    // `peel_function_score_boosted` recovers this wrapper's boost and
    // applies it to the base with exactly those semantics. Was silently
    // dropped.
    if let Some(boost) = obj.get("boost").and_then(|v| v.as_f64()) {
        let boost = boost as f32;
        if boost != 1.0 {
            node = QueryNode::Boosted {
                boost,
                query: Box::new(node),
            };
        }
    }
    Ok(maybe_named(node, name))
}

/// Parse one entry in the `functions` array.
fn parse_score_function(v: &Value) -> Result<ScoreFunction> {
    let obj = v
        .as_object()
        .ok_or_else(|| qerr("each entry in `functions` must be an object"))?;
    parse_score_function_inline(obj)
}

/// Parse score function fields from an existing object map.
fn parse_score_function_inline(obj: &serde_json::Map<String, Value>) -> Result<ScoreFunction> {
    let filter = obj
        .get("filter")
        .map(parse_query)
        .transpose()?
        .map(Box::new);
    let weight = obj.get("weight").and_then(|v| v.as_f64()).map(|w| w as f32);

    let field_value_factor = match obj.get("field_value_factor") {
        Some(fvf_val) => {
            let fvf = fvf_val
                .as_object()
                .ok_or_else(|| qerr("`field_value_factor` must be an object"))?;
            let field = fvf
                .get("field")
                .and_then(Value::as_str)
                .ok_or_else(|| qerr("`field_value_factor.field` is required"))?
                .to_string();
            let factor = fvf.get("factor").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
            let modifier = match fvf
                .get("modifier")
                .and_then(Value::as_str)
                .unwrap_or("none")
            {
                "none" => Modifier::None,
                "log" => Modifier::Log,
                "log1p" => Modifier::Log1p,
                "log2p" => Modifier::Log2p,
                "ln" => Modifier::Ln,
                "ln1p" => Modifier::Ln1p,
                "ln2p" => Modifier::Ln2p,
                "square" => Modifier::Square,
                "sqrt" => Modifier::Sqrt,
                "reciprocal" => Modifier::Reciprocal,
                other => return invalid(format!("unknown modifier `{other}`")),
            };
            let missing = fvf.get("missing").and_then(|v| v.as_f64());
            Some(FieldValueFactor {
                field,
                factor,
                modifier,
                missing,
            })
        }
        None => None,
    };

    let random_score = match obj.get("random_score") {
        Some(rs_val) => {
            let seed = rs_val.get("seed").and_then(|v| v.as_u64());
            let field = rs_val
                .get("field")
                .and_then(Value::as_str)
                .map(str::to_string);
            Some(RandomScore { seed, field })
        }
        None => None,
    };

    // script_score within a function: literal numeric source goes into
    // the fast-path `script_score` field; richer Painless source goes
    // into `script_source` and is evaluated at score time.
    let script_obj = obj.get("script_score").and_then(|ss| ss.get("script"));
    let script_source_str = script_obj
        .and_then(|s| s.get("source"))
        .and_then(Value::as_str)
        .map(String::from);
    let script_params = script_obj.and_then(|s| s.get("params").cloned());
    let literal_score = script_source_str
        .as_ref()
        .and_then(|s| s.trim().parse::<f32>().ok());
    let (script_score, script_source) = if let Some(n) = literal_score {
        (Some(n), None)
    } else {
        (None, script_source_str)
    };

    let name = obj.get("_name").and_then(Value::as_str).map(String::from);

    Ok(ScoreFunction {
        filter: filter.map(|b| *b),
        weight,
        field_value_factor,
        random_score,
        script_score,
        script_source,
        script_params,
        name,
        distance_feature: None,
        rank_feature: None,
    })
}

// ─────────────────────────────────────────────────────────────────────────────
// Sort parsing
// ─────────────────────────────────────────────────────────────────────────────

fn parse_sort(value: &Value) -> Result<Vec<SortField>> {
    match value {
        Value::String(s) => Ok(vec![parse_sort_field_str(s)]),
        Value::Array(arr) => arr.iter().map(parse_sort_entry).collect(),
        _ => invalid("`sort` must be a string or array"),
    }
}

fn parse_sort_entry(value: &Value) -> Result<SortField> {
    match value {
        Value::String(s) => Ok(parse_sort_field_str(s)),
        Value::Object(obj) => {
            if obj.len() != 1 {
                return invalid("each sort entry must have exactly one field");
            }
            let (field, spec) = obj.iter().next().unwrap();
            parse_sort_field_spec(field, spec)
        }
        _ => invalid("sort entry must be a string or object"),
    }
}

fn parse_sort_field_str(s: &str) -> SortField {
    match s {
        "_score" => SortField {
            field: "_score".to_string(),
            order: SortOrder::Desc,
            mode: SortMode::default(),
            missing: SortMissing::default(),
            format: None,
            unmapped_type: None,
            numeric_type: None,
        },
        "_doc" => SortField {
            field: "_doc".to_string(),
            order: SortOrder::Asc,
            mode: SortMode::default(),
            missing: SortMissing::default(),
            format: None,
            unmapped_type: None,
            numeric_type: None,
        },
        other => SortField {
            field: other.to_string(),
            order: SortOrder::Asc,
            mode: SortMode::default(),
            missing: SortMissing::default(),
            format: None,
            unmapped_type: None,
            numeric_type: None,
        },
    }
}

fn parse_sort_field_spec(field: &str, spec: &Value) -> Result<SortField> {
    if let Some(order_str) = spec.as_str() {
        let order = parse_sort_order(order_str)?;
        return Ok(SortField {
            field: field.to_string(),
            order,
            mode: SortMode::default(),
            missing: SortMissing::default(),
            format: None,
            unmapped_type: None,
            numeric_type: None,
        });
    }

    let obj = spec
        .as_object()
        .ok_or_else(|| qerr("sort field spec must be a string or object"))?;

    let order = match obj.get("order").and_then(|v| v.as_str()) {
        Some(s) => parse_sort_order(s)?,
        None => SortOrder::Asc,
    };

    let mode = match obj.get("mode").and_then(|v| v.as_str()) {
        Some("min") => SortMode::Min,
        Some("max") => SortMode::Max,
        Some("avg") => SortMode::Avg,
        Some("sum") => SortMode::Sum,
        Some("median") => SortMode::Median,
        None => SortMode::default(),
        Some(other) => return invalid(format!("unknown sort mode `{other}`")),
    };

    let missing = match obj.get("missing").and_then(|v| v.as_str()) {
        Some("_last") | None => SortMissing::Last,
        Some("_first") => SortMissing::First,
        Some(other) => SortMissing::Value(Value::String(other.to_string())),
    };

    let format = obj.get("format").and_then(|v| v.as_str()).map(String::from);
    let unmapped_type = obj
        .get("unmapped_type")
        .and_then(|v| v.as_str())
        .map(String::from);
    // ES `numeric_type` (#889): force the epoch scale this sort's values are
    // produced on, so a field mapped `date` in one index and `date_nanos` in
    // another compares on one scale instead of as raw longs.
    let numeric_type = obj
        .get("numeric_type")
        .and_then(|v| v.as_str())
        .map(|s| s.to_ascii_lowercase());

    Ok(SortField {
        field: field.to_string(),
        order,
        mode,
        missing,
        format,
        unmapped_type,
        numeric_type,
    })
}

fn parse_sort_order(s: &str) -> Result<SortOrder> {
    match s {
        "asc" => Ok(SortOrder::Asc),
        "desc" => Ok(SortOrder::Desc),
        other => invalid(format!(
            "unknown sort order `{other}` (expected `asc` or `desc`)"
        )),
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Source filter parsing
// ─────────────────────────────────────────────────────────────────────────────

fn parse_source_filter(value: &Value) -> Result<SourceFilter> {
    match value {
        Value::Bool(b) => Ok(SourceFilter::Enabled(*b)),
        Value::String(s) => Ok(SourceFilter::Includes(vec![s.clone()])),
        Value::Array(arr) => {
            let fields = arr
                .iter()
                .map(|v| {
                    v.as_str()
                        .ok_or_else(|| qerr("`_source` array must contain strings"))
                        .map(str::to_string)
                })
                .collect::<Result<Vec<_>>>()?;
            Ok(SourceFilter::Includes(fields))
        }
        Value::Object(obj) => {
            let includes = parse_string_list(obj.get("includes"))?;
            let excludes = parse_string_list(obj.get("excludes"))?;
            Ok(SourceFilter::Fields { includes, excludes })
        }
        _ => invalid("`_source` must be a bool, string, array, or object"),
    }
}

fn parse_string_list(value: Option<&Value>) -> Result<Vec<String>> {
    match value {
        None => Ok(vec![]),
        Some(Value::String(s)) => Ok(vec![s.clone()]),
        Some(Value::Array(arr)) => arr
            .iter()
            .map(|v| {
                v.as_str()
                    .ok_or_else(|| qerr("field list must contain strings"))
                    .map(str::to_string)
            })
            .collect(),
        _ => invalid("field list must be a string or array of strings"),
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Helpers
// ─────────────────────────────────────────────────────────────────────────────

/// Construct a `QueryError` for use with `ok_or_else`.
#[inline(always)]
fn qerr(msg: impl Into<String>) -> QueryError {
    QueryError::Parse(ParseError::Invalid(msg.into()))
}

/// Parse a `minimum_should_match` value.
fn parse_min_should_match(v: &Value) -> Result<MinShouldMatch> {
    match v {
        // #846: a negative JSON integer (`-1`) is "all but N", not an error.
        Value::Number(n) => {
            if let Some(i) = n.as_u64() {
                Ok(MinShouldMatch::Fixed(i as u32))
            } else if let Some(neg) = n.as_i64().filter(|x| *x < 0) {
                Ok(MinShouldMatch::Negative(neg.unsigned_abs() as u32))
            } else {
                Err(qerr("`minimum_should_match` must be an integer"))
            }
        }
        Value::String(s) => parse_min_should_match_str(s.trim()),
        _ => invalid("`minimum_should_match` must be a number or string"),
    }
}

/// Parse the string spelling of `minimum_should_match`: a plain or negative
/// integer, a plain or negative percentage, or a `pivot<spec [pivot<spec ...]`
/// combination (#846). Combination specs recurse (their `spec` is any of the
/// non-combination forms).
fn parse_min_should_match_str(s: &str) -> Result<MinShouldMatch> {
    let s = s.trim();
    // Combination: whitespace-separated `pivot<spec` conditions.
    if s.contains('<') {
        let mut conds = Vec::new();
        for tok in s.split_whitespace() {
            let (pivot, spec) = tok.split_once('<').ok_or_else(|| {
                qerr(format!("invalid `minimum_should_match` combination: `{s}`"))
            })?;
            let pivot: u32 = pivot
                .trim()
                .parse()
                .map_err(|_| qerr(format!("invalid `minimum_should_match` pivot in `{tok}`")))?;
            let spec = parse_min_should_match_str(spec.trim())?;
            conds.push(crate::ast::CombCond {
                pivot,
                spec: Box::new(spec),
            });
        }
        return Ok(MinShouldMatch::Combination(conds));
    }
    // Percentage, possibly negative.
    if let Some(pct) = s.strip_suffix('%') {
        let pct = pct.trim();
        if let Some(neg) = pct.strip_prefix('-') {
            let p: u32 = neg
                .trim()
                .parse()
                .map_err(|_| qerr(format!("invalid `minimum_should_match` percentage: `{s}`")))?;
            return Ok(MinShouldMatch::NegativePercentage(p));
        }
        let p: u32 = pct
            .parse()
            .map_err(|_| qerr(format!("invalid `minimum_should_match` percentage: `{s}`")))?;
        return Ok(MinShouldMatch::Percentage(p));
    }
    // Plain integer, possibly negative.
    if let Some(neg) = s.strip_prefix('-') {
        let k: u32 = neg
            .trim()
            .parse()
            .map_err(|_| qerr(format!("invalid `minimum_should_match` value: `{s}`")))?;
        return Ok(MinShouldMatch::Negative(k));
    }
    let n: u32 = s
        .parse()
        .map_err(|_| qerr(format!("invalid `minimum_should_match` value: `{s}`")))?;
    Ok(MinShouldMatch::Fixed(n))
}

fn parse_bool_operator(v: Option<&Value>) -> Result<BoolOperator> {
    match v {
        None => Ok(BoolOperator::Or),
        Some(Value::String(s)) => match s.to_uppercase().as_str() {
            "AND" => Ok(BoolOperator::And),
            "OR" => Ok(BoolOperator::Or),
            other => invalid(format!(
                "unknown boolean operator `{other}` (expected AND or OR)"
            )),
        },
        _ => invalid("`operator` must be a string"),
    }
}

/// Parse a bool clause list.  ES allows a single object or an array.
///
/// Every clause is charged against [`MAX_CLAUSE_COUNT`] *before* it is parsed,
/// so an oversized list is refused after 1,024 clauses rather than after all
/// of them.
fn parse_clause_list(obj: &serde_json::Map<String, Value>, key: &str) -> Result<Vec<QueryNode>> {
    match obj.get(key) {
        None => Ok(vec![]),
        Some(Value::Array(arr)) => arr
            .iter()
            .map(|clause| {
                charge_clause()?;
                parse_query(clause)
            })
            .collect(),
        Some(single) => {
            charge_clause()?;
            Ok(vec![parse_query(single)?])
        }
    }
}

fn string_field(obj: &serde_json::Map<String, Value>, key: &str) -> Result<String> {
    obj.get(key)
        .and_then(|v| v.as_str())
        .map(str::to_string)
        .ok_or_else(|| qerr(format!("`{key}` must be a non-empty string")))
}

/// Parse ES timeout strings like "1s", "100ms", "2m".
fn parse_timeout(v: &Value) -> Option<u64> {
    let s = v.as_str()?;
    if let Some(ms) = s.strip_suffix("ms") {
        ms.parse().ok()
    } else if let Some(s_str) = s.strip_suffix('s') {
        s_str.parse::<u64>().ok().map(|n| n * 1_000)
    } else if let Some(m) = s.strip_suffix('m') {
        m.parse::<u64>().ok().map(|n| n * 60_000)
    } else {
        s.parse().ok()
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// New query type parsers
// ─────────────────────────────────────────────────────────────────────────────

/// Parse a `nested` query.
///
/// ```json
/// {
///   "nested": {
///     "path": "comments",
///     "query": { "match": { "comments.text": "great" } },
///     "score_mode": "avg"
///   }
/// }
/// ```
fn parse_nested(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`nested` must be an object"))?;

    let path = string_field(obj, "path")?;
    let query_val = obj
        .get("query")
        .ok_or_else(|| qerr("`nested` requires a `query` clause"))?;
    let query = parse_query(query_val)?;
    let score_mode = obj
        .get("score_mode")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    Ok(QueryNode::Nested {
        path,
        query: Box::new(query),
        score_mode,
    })
}

/// Parse a `more_like_this` query.
///
/// ```json
/// {
///   "more_like_this": {
///     "fields": ["title", "body"],
///     "like": ["a very interesting document"],
///     "min_term_freq": 1,
///     "max_query_terms": 12
///   }
/// }
/// ```
fn parse_more_like_this(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`more_like_this` must be an object"))?;

    let fields: Vec<String> = obj
        .get("fields")
        .and_then(|v| v.as_array())
        .map(|arr| {
            arr.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .unwrap_or_default();

    // `like` can be a string, an array of strings, or an array of mixed
    // strings / {"_index":…,"_id":…} objects (we only use text strings).
    let like: Vec<String> = match obj.get("like") {
        Some(Value::String(s)) => vec![s.clone()],
        Some(Value::Array(arr)) => arr
            .iter()
            .filter_map(|v| match v {
                Value::String(s) => Some(s.clone()),
                Value::Object(o) => o.get("doc").and_then(|d| {
                    // Inline document: extract text from all string fields.
                    if let Some(doc_obj) = d.as_object() {
                        let text: Vec<String> = doc_obj
                            .values()
                            .filter_map(|v| v.as_str().map(str::to_string))
                            .collect();
                        if text.is_empty() {
                            None
                        } else {
                            Some(text.join(" "))
                        }
                    } else {
                        None
                    }
                }),
                _ => None,
            })
            .collect(),
        _ => return invalid("`more_like_this.like` must be a string or array"),
    };

    if like.is_empty() {
        return invalid("`more_like_this.like` must contain at least one text string");
    }

    let min_term_freq = obj
        .get("min_term_freq")
        .and_then(|v| v.as_u64())
        .unwrap_or(2) as u32;

    let max_query_terms = obj
        .get("max_query_terms")
        .and_then(|v| v.as_u64())
        .unwrap_or(25) as u32;

    // Rewrite `more_like_this` into a `bool.should` of `match` clauses — one
    // per (field × like-text) — exactly as Elasticsearch lowers MLT to a
    // disjunction of term queries over the analyzed like-text. This routes MLT
    // through the postings + scored path instead of an O(N) per-doc substring
    // scan, and produces BM25 scores bit-identical to ES (a keyword-field MLT
    // reduces to the same `term` query ES emits) instead of the old flat 1.0.
    // `match` handles both keyword (exact-token) and analyzed-text fields, so
    // no schema lookup is needed here. When `fields` is unspecified we cannot
    // build the disjunction, so we fall back to the legacy MoreLikeThis node
    // (which scans all string fields on the brute path).
    if !fields.is_empty() {
        // Bound the cross-product. `fields.len() × like.len()` QueryNode entries
        // are pre-allocated below; without a cap a ~200 KB body with 10 000
        // fields × 10 000 like-texts forces a 10^8-entry Vec (~10 GiB) and
        // aborts the process on OOM. ES effectively bounds MLT `fields` to a
        // handful; we enforce hard limits and reject oversized requests
        // with a 400-style parse error instead of allocating.
        const MAX_MLT_FIELDS: usize = 64;
        const MAX_MLT_LIKE: usize = 1_024;
        const MAX_MLT_CROSS_PRODUCT: usize = 4_096;
        if fields.len() > MAX_MLT_FIELDS {
            return invalid(format!(
                "`more_like_this.fields` has {} entries; max is {}",
                fields.len(),
                MAX_MLT_FIELDS
            ));
        }
        if like.len() > MAX_MLT_LIKE {
            return invalid(format!(
                "`more_like_this.like` has {} entries; max is {}",
                like.len(),
                MAX_MLT_LIKE
            ));
        }
        let cross = fields.len().saturating_mul(like.len());
        if cross > MAX_MLT_CROSS_PRODUCT {
            return invalid(format!(
                "`more_like_this` cross-product ({} fields × {} like = {}) exceeds max of {}",
                fields.len(),
                like.len(),
                cross,
                MAX_MLT_CROSS_PRODUCT
            ));
        }
        let mut should: Vec<QueryNode> = Vec::with_capacity(cross);
        for field in &fields {
            for text in &like {
                should.push(QueryNode::Match {
                    field: field.clone(),
                    query: text.clone(),
                    operator: BoolOperator::Or,
                    analyzer: None,
                    boost: None,
                    minimum_should_match: None,
                    // ES refuses a numeric `more_like_this` field with a
                    // different error (`only supports text/keyword fields`);
                    // #1284's type check is not that refusal, so stay out.
                    lenient: true,
                });
            }
        }
        // Bool with only `should` clauses defaults to "≥1 should must match",
        // matching ES's MLT default (`minimum_should_match: "30%"` still lands
        // at 1 for a single interesting term; we keep the engine default here).
        return Ok(QueryNode::Bool {
            must: vec![],
            should,
            must_not: vec![],
            filter: vec![],
            minimum_should_match: None,
        });
    }

    Ok(QueryNode::MoreLikeThis {
        fields,
        like,
        min_term_freq,
        max_query_terms,
    })
}

/// Parse a `pinned` query.
///
/// ```json
/// {
///   "pinned": {
///     "ids": ["1", "2"],
///     "organic": { "match": { "title": "search" } }
///   }
/// }
/// ```
/// Parse a `percolate` query.
///
/// Only the inline-document form is supported:
/// ```json
/// { "field": "query", "document": { … } }
/// { "field": "query", "documents": [ { … }, … ] }
/// ```
/// The index/id fetch form (`{ "field": "query", "index": "...", "id": "..." }`)
/// is rejected with a 400 rather than silently returning nothing.
fn parse_percolate(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`percolate` must be an object"))?;

    let field = string_field(obj, "field")?;

    let documents: Vec<Value> = if let Some(doc) = obj.get("document") {
        if !doc.is_object() {
            return invalid("`percolate.document` must be an object");
        }
        vec![doc.clone()]
    } else if let Some(docs) = obj.get("documents") {
        let arr = docs
            .as_array()
            .ok_or_else(|| qerr("`percolate.documents` must be an array"))?;
        if arr.iter().any(|d| !d.is_object()) {
            return invalid("`percolate.documents` must contain only objects");
        }
        arr.clone()
    } else {
        return invalid(
            "`percolate` requires an inline `document` or `documents`; the \
             index/id document-fetch form is not supported",
        );
    };

    if documents.is_empty() {
        return invalid("`percolate` requires at least one document");
    }

    Ok(QueryNode::Percolate { field, documents })
}

fn parse_pinned(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`pinned` must be an object"))?;

    let ids: Vec<String> = obj
        .get("ids")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`pinned` requires an `ids` array"))?
        .iter()
        .map(|v| match v {
            Value::String(s) => Ok(s.clone()),
            Value::Number(n) => Ok(n.to_string()),
            _ => Err(qerr("`pinned.ids` must contain strings or numbers")),
        })
        .collect::<Result<Vec<_>>>()?;

    let organic_val = obj
        .get("organic")
        .ok_or_else(|| qerr("`pinned` requires an `organic` query"))?;
    let organic = parse_query(organic_val)?;

    Ok(QueryNode::Pinned {
        ids,
        organic: Box::new(organic),
    })
}

/// Parse a `wrapper` query — base64-encodes a query JSON string.
///
/// ```json
/// { "wrapper": { "query": "eyJtYXRjaF9hbGwiOiB7fX0=" } }
/// ```
fn parse_wrapper(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`wrapper` must be an object"))?;

    let encoded = obj
        .get("query")
        .and_then(|v| v.as_str())
        .ok_or_else(|| qerr("`wrapper.query` must be a base64-encoded query string"))?;

    let decoded_bytes = base64::engine::general_purpose::STANDARD
        .decode(encoded)
        .map_err(|_| qerr("`wrapper.query` is not valid base64"))?;

    let decoded_str = std::str::from_utf8(&decoded_bytes)
        .map_err(|_| qerr("`wrapper.query` base64 payload is not valid UTF-8"))?;

    let inner_json: Value = serde_json::from_str(decoded_str)
        .map_err(|_| qerr("`wrapper.query` base64 payload is not valid JSON"))?;

    // The decoded JSON may be a full query object {"match": {…}} or a
    // SearchRequest-style envelope {"query": {…}}.  Try both.
    if let Some(q) = inner_json.as_object().and_then(|o| o.get("query")) {
        parse_query(q)
    } else {
        parse_query(&inner_json)
    }
}

/// Parse a `span_term` query.
///
/// Accepts:
/// - `{"span_term": {"field": "value"}}` — shorthand string form
/// - `{"span_term": {"field": {"value": "text"}}}` — long form
fn parse_span_term(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`span_term` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`span_term` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    let value = if let Some(s) = raw.as_str() {
        s.to_string()
    } else if let Some(inner) = raw.as_object() {
        if let Some(v) = inner.get("value").and_then(|v| v.as_str()) {
            v.to_string()
        } else {
            return invalid("`span_term` object form requires a `value` string");
        }
    } else {
        return invalid("`span_term` field value must be a string or object");
    };

    Ok(QueryNode::SpanTerm { field, value })
}

/// Parse a `span_near` query.
///
/// `{"span_near": {"clauses": [...], "slop": 5, "in_order": true}}`
fn parse_span_near(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`span_near` must be an object"))?;

    let clauses = parse_span_clauses(obj, "span_near")?;

    if clauses.is_empty() {
        return Ok(QueryNode::MatchNone);
    }

    // KNOWN GAP (pre-existing, deliberately not changed by #230): this read
    // accepts anything and silently substitutes 0 — `slop: -1`, `slop: 2.0`
    // and `slop: "2"` all answer as slop 0. It is NOT routed through
    // `parse_phrase_slop`, and the phrase work in #230 does not cover it.
    //
    // It is left alone rather than "fixed" because ES applies no validation
    // here either: `SpanNearQueryBuilder` takes the int unchecked
    // (`.../index/query/SpanNearQueryBuilder.java:62`, no negative test)
    // while every phrase builder throws on a negative slop. So a negative
    // `span_near` slop is a query ES answers, and rejecting it would be a
    // wire-compat break on a request that works today. Closing it properly
    // means honouring the value (float coercion via `coerce_es_int`, and a
    // decision about what a negative span slop should match), which is a
    // span-query change, not a phrase one.
    let slop = obj.get("slop").and_then(|v| v.as_u64()).unwrap_or(0) as u32;
    let in_order = obj
        .get("in_order")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);

    Ok(QueryNode::SpanNear {
        clauses,
        slop,
        in_order,
    })
}

/// Parse a `span_or` query.
///
/// `{"span_or": {"clauses": [...]}}`
fn parse_span_or(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`span_or` must be an object"))?;

    let clauses = parse_span_clauses(obj, "span_or")?;

    if clauses.is_empty() {
        return Ok(QueryNode::MatchNone);
    }

    Ok(QueryNode::SpanOr { clauses })
}

/// Parse the `clauses` array shared by `span_near` and `span_or`.
///
/// Both used to collect with `filter_map(|v| parse_query(v).ok())`, which
/// discards a clause the parser refused and keeps going. That is how a *limit*
/// becomes a correctness bug rather than an error: [`MAX_CLAUSE_COUNT`] is a
/// parse error, so a `span_or` whose first clause is an over-wide `bool` used
/// to answer 200 OK with that clause silently missing — a different query than
/// the one asked for, scored against and returned as if it were the answer. A
/// query that is refused is a query the caller can fix; a query that is
/// quietly rewritten is not. Every clause error propagates.
///
/// Clauses are charged against [`MAX_CLAUSE_COUNT`] here for the same reason
/// they are in `bool`: width is what multiplies per-document work, and a span
/// clause list is as wide as a `should` list.
fn parse_span_clauses(obj: &serde_json::Map<String, Value>, _what: &str) -> Result<Vec<QueryNode>> {
    let Some(arr) = obj.get("clauses").and_then(|v| v.as_array()) else {
        return Ok(Vec::new());
    };
    // The clause CAP is fatal — a `MAX_CLAUSE_COUNT` trip must refuse, not
    // silently drop (that was the #122 defect: `filter_map(..ok())` turned an
    // over-cap span into a different query). The cap can trip in TWO places:
    // `charge_clause()` for the span's own clauses, and INSIDE `parse_query`
    // when a clause is itself a wide `bool` — both must propagate.
    //
    // But an ordinary parse error for a clause type this engine does not
    // implement (`span_multi`) or a malformed clause stays LENIENT and is
    // dropped, because that is the pre-#122 behaviour ES-compat conformance
    // depends on: `search/190_index_prefix_search` sends a `span_near` holding
    // a `span_multi` and expects the search to run, not to 400. So: propagate
    // ONLY the cap error; drop every other parse failure.
    let mut out = Vec::with_capacity(arr.len());
    for v in arr {
        charge_clause()?;
        match parse_query(v) {
            Ok(node) => out.push(node),
            Err(e) if e.to_string().contains("too_many_clauses") => return Err(e),
            Err(_) => { /* unsupported/malformed clause: dropped, as before */ }
        }
    }
    Ok(out)
}

/// Parse a `span_not` query.
///
/// `{"span_not": {"include": {...}, "exclude": {...}}}`
fn parse_span_not(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`span_not` must be an object"))?;

    let include = obj
        .get("include")
        .ok_or_else(|| qerr("`span_not` requires an `include` clause"))
        .and_then(parse_query)?;
    let exclude = obj
        .get("exclude")
        .ok_or_else(|| qerr("`span_not` requires an `exclude` clause"))
        .and_then(parse_query)?;

    Ok(QueryNode::SpanNot {
        include: Box::new(include),
        exclude: Box::new(exclude),
    })
}

/// Parse a `span_first` query.
///
/// `{"span_first": {"match": {...}, "end": 3}}`
fn parse_span_first(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`span_first` must be an object"))?;

    let match_query = obj
        .get("match")
        .ok_or_else(|| qerr("`span_first` requires a `match` clause"))
        .and_then(parse_query)?;
    let end = obj.get("end").and_then(|v| v.as_u64()).unwrap_or(1) as u32;

    Ok(QueryNode::SpanFirst {
        match_query: Box::new(match_query),
        end,
    })
}

/// Parse `span_containing` / `span_within`. Both take a `little` and a `big`
/// span clause; the difference is only which span must enclose the other,
/// which is captured by the returned variant.
fn parse_span_containing_like(query_type: &str, params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr(format!("`{}` must be an object", query_type)))?;

    let little = obj
        .get("little")
        .ok_or_else(|| qerr(format!("`{}` requires a `little` clause", query_type)))
        .and_then(parse_query)?;
    let big = obj
        .get("big")
        .ok_or_else(|| qerr(format!("`{}` requires a `big` clause", query_type)))
        .and_then(parse_query)?;

    let little = Box::new(little);
    let big = Box::new(big);

    Ok(match query_type {
        "span_within" => QueryNode::SpanWithin { little, big },
        // "span_containing"
        _ => QueryNode::SpanContaining { little, big },
    })
}

/// Parse a `has_child` query.
///
/// `{"has_child": {"type": "answer", "query": {...}, "score_mode": "avg"}}`
///
/// Parent-child joins are NOT supported. XERJ is single-type per index
/// and never materializes the parent/child join structure, so both the
/// planner and executor branches for `HasChild` would silently fall back
/// to running the inner query on flat docs (wrong results). We fail loud
/// (400) at parse time instead — the `QueryNode::HasChild` AST variant is
/// therefore never built, and the downstream branches are unreachable.
fn parse_has_child(_params: &Value) -> Result<QueryNode> {
    invalid(
        "parent-child join queries (has_child/has_parent) are not supported; \
         index as a single flat type or denormalize the relationship",
    )
}

/// Parse a `has_parent` query.
///
/// `{"has_parent": {"parent_type": "question", "query": {...}, "score": true}}`
///
/// See `parse_has_child`: parent-child joins are unsupported and rejected
/// with a 400 at parse time, so the `QueryNode::HasParent` variant is
/// never constructed.
fn parse_has_parent(_params: &Value) -> Result<QueryNode> {
    invalid(
        "parent-child join queries (has_child/has_parent) are not supported; \
         index as a single flat type or denormalize the relationship",
    )
}

/// Parse a `geo_polygon` query.
///
/// `{"geo_polygon": {"location": {"points": [{"lat":40,"lon":-74}, ...]}}}`
fn parse_geo_polygon(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`geo_polygon` must be an object"))?;

    // Find the field name (the first key that isn't "boost"/"_name").
    let (field, field_params) = obj
        .iter()
        .find(|(k, _)| k.as_str() != "boost" && k.as_str() != "_name")
        .ok_or_else(|| qerr("`geo_polygon` must specify a field"))?;

    let field = field.clone();

    let points_arr = field_params
        .get("points")
        .and_then(|v| v.as_array())
        .ok_or_else(|| qerr("`geo_polygon` field must have a `points` array"))?;

    let points = points_arr
        .iter()
        .map(parse_lat_lon_obj)
        .collect::<Result<Vec<_>>>()?;

    Ok(QueryNode::GeoPolygon { field, points })
}

/// Parse a geo point from a JSON object like `{"lat": 40, "lon": -74}`.
fn parse_lat_lon_obj(v: &Value) -> Result<(f64, f64)> {
    let obj = v
        .as_object()
        .ok_or_else(|| qerr("geo point must be an object {lat, lon}"))?;
    let lat = obj
        .get("lat")
        .and_then(|x| x.as_f64())
        .ok_or_else(|| qerr("geo point missing `lat`"))?;
    let lon = obj
        .get("lon")
        .and_then(|x| x.as_f64())
        .ok_or_else(|| qerr("geo point missing `lon`"))?;
    Ok((lat, lon))
}

/// Parse a `geo_shape` query.
///
/// `{"geo_shape": {"location": {"shape": {"type": "envelope", "coordinates": [[lon,lat],[lon,lat]]}}}}`
fn parse_geo_shape(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`geo_shape` must be an object"))?;

    let (field, field_params) = obj
        .iter()
        .find(|(k, _)| {
            k.as_str() != "boost" && k.as_str() != "_name" && k.as_str() != "ignore_unmapped"
        })
        .ok_or_else(|| qerr("`geo_shape` must specify a field"))?;

    let field = field.clone();

    // The shape may be under "shape" or "indexed_shape" key; we only support "shape".
    let shape_val = field_params
        .get("shape")
        .ok_or_else(|| qerr("`geo_shape` field must have a `shape` object"))?;

    let shape_type = shape_val
        .get("type")
        .and_then(|v| v.as_str())
        .unwrap_or("")
        .to_lowercase();

    let shape = match shape_type.as_str() {
        "point" => {
            // coordinates: [lon, lat]
            let coords = shape_val
                .get("coordinates")
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` point needs `coordinates`"))?;
            let lon = coords.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
            let lat = coords.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
            GeoShapeType::Point { lat, lon }
        }
        "envelope" => {
            // coordinates: [[top_left_lon, top_left_lat], [bottom_right_lon, bottom_right_lat]]
            let coords = shape_val
                .get("coordinates")
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` envelope needs `coordinates`"))?;
            let tl = coords
                .first()
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` envelope top-left missing"))?;
            let br = coords
                .get(1)
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` envelope bottom-right missing"))?;
            let tl_lon = tl.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
            let tl_lat = tl.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
            let br_lon = br.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
            let br_lat = br.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
            GeoShapeType::Envelope {
                top_left: (tl_lat, tl_lon),
                bottom_right: (br_lat, br_lon),
            }
        }
        "polygon" => {
            // coordinates: [[[lon, lat], ...]] (outer ring only)
            let rings = shape_val
                .get("coordinates")
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` polygon needs `coordinates`"))?;
            let outer = rings
                .first()
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` polygon outer ring missing"))?;
            let points = outer
                .iter()
                .filter_map(|p| {
                    let arr = p.as_array()?;
                    let lon = arr.first()?.as_f64()?;
                    let lat = arr.get(1)?.as_f64()?;
                    Some((lat, lon))
                })
                .collect();
            GeoShapeType::Polygon { points }
        }
        "circle" => {
            // coordinates: [lon, lat], radius: "10km" or number
            let coords = shape_val
                .get("coordinates")
                .and_then(|v| v.as_array())
                .ok_or_else(|| qerr("`geo_shape` circle needs `coordinates`"))?;
            let lon = coords.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
            let lat = coords.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
            let radius_km = parse_distance_to_km(
                shape_val
                    .get("radius")
                    .ok_or_else(|| qerr("`geo_shape` circle needs `radius`"))?,
            )?;
            GeoShapeType::Circle {
                center: (lat, lon),
                radius_km,
            }
        }
        other => return invalid(format!("unsupported geo_shape type `{}`", other)),
    };

    Ok(QueryNode::GeoShape { field, shape })
}

/// Parse a distance value to kilometres. Accepts "10km", "5mi", or a bare number (metres).
fn parse_distance_to_km(v: &Value) -> Result<f64> {
    if let Some(n) = v.as_f64() {
        return Ok(n / 1000.0); // assume metres
    }
    if let Some(s) = v.as_str() {
        let s = s.trim().to_lowercase();
        if let Some(stripped) = s.strip_suffix("km") {
            return stripped
                .trim()
                .parse::<f64>()
                .map_err(|_| qerr("invalid distance km"));
        }
        if let Some(stripped) = s.strip_suffix("mi") {
            let miles: f64 = stripped
                .trim()
                .parse()
                .map_err(|_| qerr("invalid distance mi"))?;
            return Ok(miles * 1.60934);
        }
        if let Some(stripped) = s.strip_suffix('m') {
            let metres: f64 = stripped
                .trim()
                .parse()
                .map_err(|_| qerr("invalid distance m"))?;
            return Ok(metres / 1000.0);
        }
        if let Ok(n) = s.parse::<f64>() {
            return Ok(n / 1000.0);
        }
    }
    invalid("unrecognised distance format")
}

// ─────────────────────────────────────────────────────────────────────────────
// Gap 2: Additional ES query type parsers
// ─────────────────────────────────────────────────────────────────────────────

/// `match_bool_prefix` — tokenise the query string; the last token becomes a
/// `prefix` query and all preceding tokens become `term` queries, combined in a
/// `bool { should: [...] }`.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-bool-prefix-query.html>
fn parse_match_bool_prefix(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`match_bool_prefix` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`match_bool_prefix` query must have exactly one field");
    }

    let (field, raw) = obj.iter().next().unwrap();
    let field = field.clone();

    // Long-form accepts the same options as `match` + `operator` + mm.
    let (query_str, mm, operator_and, analyzer, fuzziness, prefix_length) =
        if let Some(s) = raw.as_str() {
            (s.to_string(), None, false, None, None, 0usize)
        } else {
            let inner = raw.as_object().ok_or_else(|| {
                qerr("`match_bool_prefix` field value must be a string or object")
            })?;
            let q = string_field(inner, "query")?;
            // #846: go through the shared `minimum_should_match` parser so
            // negative / negative-% / combination specs reach the evaluator
            // from this site too. It used to inline a number/percentage-only
            // subset, which silently dropped every other spec to `None` (=
            // plain OR) instead of honouring it.
            let mm_val = inner
                .get("minimum_should_match")
                .and_then(|v| parse_min_should_match(v).ok());
            let op_and = matches!(
                inner
                    .get("operator")
                    .and_then(Value::as_str)
                    .map(|s| s.to_ascii_lowercase())
                    .as_deref(),
                Some("and")
            );
            let analyzer = inner
                .get("analyzer")
                .and_then(Value::as_str)
                .map(str::to_string);
            let fuzziness = inner.get("fuzziness").map(|v| match v {
                Value::String(s) if s.eq_ignore_ascii_case("auto") => crate::ast::Fuzziness::Auto,
                Value::String(s) => s
                    .parse::<u32>()
                    .ok()
                    .map(crate::ast::Fuzziness::Fixed)
                    .unwrap_or(crate::ast::Fuzziness::Auto),
                Value::Number(n) => crate::ast::Fuzziness::Fixed(n.as_u64().unwrap_or(0) as u32),
                _ => crate::ast::Fuzziness::Auto,
            });
            let prefix_length = parse_prefix_length(inner);
            (q, mm_val, op_and, analyzer, fuzziness, prefix_length)
        };

    // Analyzer semantics: "whitespace" preserves case, "keyword" treats
    // input as single token, default/standard lowercases. We approximate
    // by case-folding unless the requested analyzer is case-preserving.
    let analyzer_lowercases = !matches!(analyzer.as_deref(), Some("whitespace") | Some("keyword"));
    let fold = |t: &str| -> String {
        if analyzer_lowercases {
            t.to_lowercase()
        } else {
            t.to_string()
        }
    };

    let raw_tokens: Vec<String> = if analyzer.as_deref() == Some("keyword") {
        vec![query_str.clone()]
    } else {
        query_str.split_whitespace().map(str::to_string).collect()
    };
    if raw_tokens.is_empty() {
        return Ok(QueryNode::MatchAll);
    }

    if raw_tokens.len() == 1 {
        // Single token: the whole match_bool_prefix collapses to one
        // standalone prefix clause, which ES rewrites to ConstantScore
        // (flat 1.0, no BM25) exactly like a top-level `prefix` query —
        // the same MultiTermQuery rewrite 4c69c05 threaded through
        // parse_prefix/parse_wildcard; this site was missed (live: xerj
        // max_score 2.5210621 vs ES 1.0).  Multi-token keeps BM25 (the
        // trailing prefix is one clause among scored Match clauses).
        return Ok(QueryNode::Prefix {
            field,
            value: fold(&raw_tokens[0]),
            boost: None,
            constant_score: true,
            case_insensitive: false,
        });
    }

    let last_idx = raw_tokens.len() - 1;
    let build_leaf = |tok: &str| -> QueryNode {
        let folded = fold(tok);
        if let Some(fz) = fuzziness {
            QueryNode::Fuzzy {
                field: field.clone(),
                value: folded,
                fuzziness: fz,
                case_insensitive: true,
                prefix_length,
            }
        } else {
            QueryNode::Match {
                field: field.clone(),
                query: folded,
                operator: BoolOperator::Or,
                boost: None,
                analyzer: analyzer.clone(),
                minimum_should_match: None,
                // `match_bool_prefix` has no `lenient` option in ES.
                lenient: false,
            }
        }
    };
    let mut clauses: Vec<QueryNode> = raw_tokens[..last_idx]
        .iter()
        .map(|t| build_leaf(t))
        .collect();
    clauses.push(QueryNode::Prefix {
        field: field.clone(),
        value: fold(&raw_tokens[last_idx]),
        boost: None,
        constant_score: false,
        // `match_bool_prefix` lowers to an internal prefix over ANALYZED
        // tokens — no user-facing `case_insensitive` option to thread.
        case_insensitive: false,
    });

    // operator:and → every clause must match; otherwise should + mm.
    let (must, should, mm_final) = if operator_and {
        (clauses, vec![], None)
    } else {
        (vec![], clauses, mm)
    };

    Ok(QueryNode::Bool {
        must,
        should,
        filter: vec![],
        must_not: vec![],
        minimum_should_match: mm_final,
    })
}

/// `terms_set` — like `terms` but with a per-query `minimum_should_match`.
/// Parsed as `Bool { should: [term1, term2, ...], minimum_should_match: N }`.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-set-query.html>
fn parse_terms_set(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`terms_set` must be an object"))?;

    let field_entries: Vec<_> = obj.iter().filter(|(k, _)| k.as_str() != "boost").collect();

    if field_entries.len() != 1 {
        return invalid("`terms_set` query must have exactly one field entry");
    }

    let (field, raw) = field_entries[0];
    let field = field.clone();

    let inner = raw
        .as_object()
        .ok_or_else(|| qerr("`terms_set` field value must be an object"))?;

    let terms = inner
        .get("terms")
        .and_then(Value::as_array)
        .ok_or_else(|| qerr("`terms_set.terms` must be an array"))?
        .clone();

    // `minimum_should_match_field` reads the per-doc required count from a
    // numeric field; `minimum_should_match_script` computes it from a
    // Painless script. Fall back to a literal `minimum_should_match`.
    let minimum_should_match = if let Some(field_name) = inner
        .get("minimum_should_match_field")
        .and_then(Value::as_str)
    {
        Some(crate::ast::MinShouldMatch::Field(field_name.to_string()))
    } else if let Some(script) = inner.get("minimum_should_match_script") {
        let source = script
            .get("source")
            .and_then(Value::as_str)
            .ok_or_else(|| qerr("`terms_set.minimum_should_match_script` requires a `source`"))?
            .to_string();
        let params = script.get("params").cloned();
        Some(crate::ast::MinShouldMatch::Script { source, params })
    } else {
        inner
            .get("minimum_should_match")
            .map(parse_min_should_match)
            .and_then(|r| r.ok())
    };

    let should: Vec<QueryNode> = terms
        .iter()
        .map(|v| QueryNode::Term {
            field: field.clone(),
            value: v.clone(),
            boost: None,
        })
        .collect();

    Ok(QueryNode::Bool {
        must: vec![],
        should,
        filter: vec![],
        must_not: vec![],
        minimum_should_match,
    })
}

/// `intervals` — position-aware match query.  xerj does not implement a full
/// interval automaton; we translate each rule to the closest Bool/Match/Phrase
/// equivalent.
///
/// * `match`: `ordered: true` → `match_phrase` with slop from `max_gaps`
///   (unset → large, effectively ordered-anywhere).
///   `ordered: false` (default) → `match` with operator AND
///   (all query tokens must be present; we do not model gap bounds here).
/// * `prefix`: → `prefix` query.
/// * `wildcard`: → `wildcard` query.
/// * `all_of` / `any_of`: → bool { must / should }.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-intervals-query.html>
fn parse_intervals(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`intervals` must be an object"))?;
    if obj.len() != 1 {
        return invalid("`intervals` query must have exactly one field");
    }
    let (field, raw) = obj.iter().next().unwrap();
    // Emit a specialised `Intervals` node — the executor evaluates the
    // rule (match/all_of/any_of/prefix/wildcard/fuzzy, with optional
    // filter:) against the field's tokenised positions at query time.
    Ok(QueryNode::Intervals {
        field: field.clone(),
        rule: raw.clone(),
    })
}

/// `script_score` — wrap the inner query and apply a Painless script
/// to compute each matched doc's score. The script's returned value
/// REPLACES the BM25 score (boost_mode: Replace).
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-script-score-query.html>
fn parse_script_score(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`script_score` must be an object"))?;

    let inner_query_val = obj
        .get("query")
        .ok_or_else(|| qerr("`script_score.query` is required"))?;

    let inner = parse_query(inner_query_val)?;

    // Pull out the script source + params if present.
    let script = obj.get("script").and_then(|s| s.as_object());
    let source = script.and_then(|s| s.get("source").and_then(|v| v.as_str()).map(String::from));
    let s_params = script.and_then(|s| s.get("params").cloned());

    // If the script is just a numeric literal (e.g. `"3"`), shortcut
    // into the existing literal-score fast path.
    let literal_score = source.as_ref().and_then(|s| s.trim().parse::<f32>().ok());

    let func = ScoreFunction {
        filter: None,
        weight: None,
        field_value_factor: None,
        random_score: None,
        script_score: literal_score,
        script_source: if literal_score.is_some() {
            None
        } else {
            source
        },
        script_params: s_params,
        name: None,
        distance_feature: None,
        rank_feature: None,
    };

    Ok(QueryNode::FunctionScore {
        query: Box::new(inner),
        functions: vec![func],
        score_mode: crate::ast::ScoreMode::Multiply,
        // `script_score` replaces the inner query score with the script's
        // returned value (the script can incorporate `_score` if it
        // wants to combine with the inner score).
        boost_mode: crate::ast::BoostMode::Replace,
        max_boost: None,
    })
}

/// `distance_feature` — date/geo distance proximity scoring.  xerj converts
/// this to a `function_score` with a `field_value_factor` on the target field
/// so the query still filters correctly (the proximity score boost is not
/// computed exactly but the field is at least scored).
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-distance-feature-query.html>
fn parse_distance_feature(params: &Value) -> Result<QueryNode> {
    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`distance_feature` must be an object"))?;

    let field = string_field(obj, "field")?;
    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
    let pivot = string_field(obj, "pivot")?;
    let origin = obj
        .get("origin")
        .cloned()
        .ok_or_else(|| qerr("`distance_feature.origin` is required"))?;

    let df = crate::ast::DistanceFeature {
        field: field.clone(),
        pivot,
        origin,
    };

    Ok(QueryNode::FunctionScore {
        // Hybrid: the inner query returns every doc that has the field
        // (so the function_score runs on the full candidate set) and
        // `boost_mode: replace` substitutes the distance score.
        query: Box::new(QueryNode::Exists { field }),
        functions: vec![ScoreFunction {
            filter: None,
            weight: boost,
            field_value_factor: None,
            random_score: None,
            script_score: None,
            script_source: None,
            script_params: None,
            name: None,
            distance_feature: Some(df),
            rank_feature: None,
        }],
        score_mode: ScoreMode::Multiply,
        boost_mode: BoostMode::Replace,
        max_boost: None,
    })
}

/// `rank_feature` — logarithmic proximity scoring on a numeric field.
/// Converted to a `function_score` with a `field_value_factor` and `log1p`
/// modifier so the field is scored proportionally to its value.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rank-feature-query.html>
fn parse_rank_feature(params: &Value) -> Result<QueryNode> {
    use crate::ast::{RankFeature, RankFeatureFn};

    let obj = params
        .as_object()
        .ok_or_else(|| qerr("`rank_feature` must be an object"))?;

    let field = string_field(obj, "field")?;
    let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);

    // Detect which of the four ES functions is requested. Default to
    // `saturation` (with the field's default pivot) when none is given.
    let function = if let Some(sat) = obj.get("saturation") {
        let pivot = sat.get("pivot").and_then(|v| v.as_f64());
        RankFeatureFn::Saturation { pivot }
    } else if let Some(log) = obj.get("log") {
        let scaling_factor = log
            .get("scaling_factor")
            .and_then(|v| v.as_f64())
            .ok_or_else(|| qerr("`rank_feature.log` requires a `scaling_factor`"))?;
        RankFeatureFn::Log { scaling_factor }
    } else if let Some(sig) = obj.get("sigmoid") {
        let pivot = sig
            .get("pivot")
            .and_then(|v| v.as_f64())
            .ok_or_else(|| qerr("`rank_feature.sigmoid` requires a `pivot`"))?;
        let exponent = sig
            .get("exponent")
            .and_then(|v| v.as_f64())
            .ok_or_else(|| qerr("`rank_feature.sigmoid` requires an `exponent`"))?;
        RankFeatureFn::Sigmoid { pivot, exponent }
    } else if obj.contains_key("linear") {
        RankFeatureFn::Linear
    } else {
        RankFeatureFn::Saturation { pivot: None }
    };

    let rank_feature = RankFeature {
        field: field.clone(),
        function,
    };

    Ok(QueryNode::FunctionScore {
        // The inner Exists query supplies the candidate set (all docs that
        // have the rank_feature field); `boost_mode: replace` substitutes
        // the feature's own score for the query score.
        query: Box::new(QueryNode::Exists { field }),
        functions: vec![ScoreFunction {
            filter: None,
            weight: boost,
            field_value_factor: None,
            random_score: None,
            script_score: None,
            script_source: None,
            script_params: None,
            name: None,
            distance_feature: None,
            rank_feature: Some(rank_feature),
        }],
        score_mode: ScoreMode::Multiply,
        boost_mode: BoostMode::Replace,
        max_boost: None,
    })
}

// ─────────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn q(j: serde_json::Value) -> QueryNode {
        parse_query(&j).expect("parse failed")
    }

    /// The window is the engine's to enforce (per-index setting, then the node
    /// limit); the parser only bounds the arithmetic at the setting's largest
    /// value. A hardcoded 10,000 here overruled `index.max_result_window`.
    #[test]
    fn parser_leaves_the_result_window_to_the_index() {
        let r = parse_request(&json!({ "from": 20_000, "size": 10 }))
            .expect("from 20,000 is legal for an index whose window allows it");
        assert_eq!((r.from, r.size), (20_000, 10));
        assert!(parse_request(&json!({ "from": i32::MAX as u64, "size": 1 })).is_err());
    }

    // ── #846: minimum_should_match negative / combination specs ───────────────

    #[test]
    fn msm_parses_negative_and_combination_specs() {
        use crate::ast::CombCond;
        let p = |v: serde_json::Value| parse_min_should_match(&v).expect("parse msm");

        // Negative integer (number AND string spellings) — before #846 the
        // number errored ("must be non-negative") and the string dropped to
        // Fixed-parse failure; both are now Negative(N) = all-but-N.
        assert_eq!(p(json!(-1)), MinShouldMatch::Negative(1));
        assert_eq!(p(json!("-2")), MinShouldMatch::Negative(2));
        // Plain forms unchanged.
        assert_eq!(p(json!(3)), MinShouldMatch::Fixed(3));
        assert_eq!(p(json!("75%")), MinShouldMatch::Percentage(75));
        // Negative percentage — distinct from Percentage (they round differently).
        assert_eq!(p(json!("-25%")), MinShouldMatch::NegativePercentage(25));
        // Combination — single and multiple conditions.
        assert_eq!(
            p(json!("3<90%")),
            MinShouldMatch::Combination(vec![CombCond {
                pivot: 3,
                spec: Box::new(MinShouldMatch::Percentage(90)),
            }])
        );
        assert_eq!(
            p(json!("2<-25% 9<-3")),
            MinShouldMatch::Combination(vec![
                CombCond {
                    pivot: 2,
                    spec: Box::new(MinShouldMatch::NegativePercentage(25)),
                },
                CombCond {
                    pivot: 9,
                    spec: Box::new(MinShouldMatch::Negative(3)),
                },
            ])
        );
    }

    #[test]
    fn msm_required_resolves_es_semantics() {
        // Negative: required = n - N (floored at 0).
        assert_eq!(MinShouldMatch::Negative(1).required(4), Some(3));
        assert_eq!(MinShouldMatch::Negative(9).required(4), Some(0));
        // Negative percentage: required = n - floor(n*P/100); differs from the
        // same-looking Percentage on non-divisible counts.
        assert_eq!(MinShouldMatch::NegativePercentage(25).required(5), Some(4));
        assert_eq!(MinShouldMatch::Percentage(75).required(5), Some(3));
        // Combination: n <= every pivot ⇒ all required; else highest pivot < n.
        let c = MinShouldMatch::Combination(vec![
            crate::ast::CombCond {
                pivot: 2,
                spec: Box::new(MinShouldMatch::NegativePercentage(25)),
            },
            crate::ast::CombCond {
                pivot: 9,
                spec: Box::new(MinShouldMatch::Negative(3)),
            },
        ]);
        assert_eq!(c.required(2), Some(2)); // n <= smallest pivot → all
        assert_eq!(c.required(5), Some(4)); // pivot 2 applies: 5 - floor(1.25)
        assert_eq!(c.required(10), Some(7)); // pivot 9 applies: 10 - 3
    }

    #[test]
    fn msm_negative_survives_through_bool_parse() {
        // End-to-end: a bool with `minimum_should_match: -1` no longer errors
        // or drops — it lands as Negative(1) on the AST.
        match q(json!({"bool": {"should": [
            {"term": {"a": "x"}}, {"term": {"b": "y"}}, {"term": {"c": "z"}}
        ], "minimum_should_match": -1}}))
        {
            QueryNode::Bool {
                minimum_should_match,
                ..
            } => assert_eq!(minimum_should_match, Some(MinShouldMatch::Negative(1))),
            other => panic!("expected Bool, got {other:?}"),
        }
    }

    // ── match_all ─────────────────────────────────────────────────────────────

    #[test]
    fn test_match_all() {
        assert_eq!(q(json!({"match_all": {}})), QueryNode::MatchAll);
    }

    #[test]
    fn test_match_all_with_boost() {
        // ES scores match_all{boost} as `boost` per hit (constant-score
        // semantics) — the boost must not be dropped.
        assert_eq!(
            q(json!({"match_all": {"boost": 2.0}})),
            QueryNode::Constant {
                score: 2.0,
                query: Box::new(QueryNode::MatchAll),
            }
        );
    }

    #[test]
    fn test_match_none() {
        assert_eq!(q(json!({"match_none": {}})), QueryNode::MatchNone);
    }

    #[test]
    fn test_unresolved_terms_lookup_is_a_loud_error_not_silent_empty() {
        // An UNRESOLVED lookup object should never reach the parser on a
        // supported endpoint (`_search`/`_count` substitute the value array
        // first). If it does — an endpoint that forgot to resolve — this used
        // to parse to MatchNone and log a warning, i.e. silently match nothing.
        // It must be a hard parse error so the gap is visible.
        let err = parse_query(&json!({
            "terms": {"user_id": {"index": "customers", "id": "1", "path": "user_id"}}
        }));
        assert!(
            err.is_err(),
            "unresolved terms lookup must error, not MatchNone"
        );
        let msg = format!("{}", err.unwrap_err());
        assert!(
            msg.contains("terms lookup") && msg.contains("unresolved"),
            "error should explain the unresolved-lookup gap, got: {msg}"
        );
    }

    #[test]
    fn test_plain_terms_still_parses() {
        // The literal-array form is unaffected.
        assert!(matches!(
            q(json!({"terms": {"svc": ["auth", "checkout"]}})),
            QueryNode::Terms { .. }
        ));
    }

    // ── match ─────────────────────────────────────────────────────────────────

    #[test]
    fn test_match_shorthand() {
        let node = q(json!({"match": {"title": "hello world"}}));
        assert!(
            matches!(node, QueryNode::Match { ref field, ref query, operator: BoolOperator::Omitted, .. }
            if field == "title" && query == "hello world")
        );
    }

    #[test]
    fn test_match_long_form() {
        let node = q(json!({
            "match": {
                "title": {
                    "query": "hello world",
                    "operator": "AND",
                    "analyzer": "english"
                }
            }
        }));
        if let QueryNode::Match {
            field,
            query,
            operator,
            analyzer,
            ..
        } = node
        {
            assert_eq!(field, "title");
            assert_eq!(query, "hello world");
            assert_eq!(operator, BoolOperator::And);
            assert_eq!(analyzer, Some("english".to_string()));
        } else {
            panic!("wrong variant");
        }
    }

    /// #1504: a long-form `match` that leaves `operator` out is not the same
    /// node as one that says `"operator": "or"`. The log-index default can
    /// fill the gap; it must not override an explicit OR.
    #[test]
    fn match_without_an_operator_is_omitted_and_explicit_or_is_or() {
        let omitted = q(json!({"match": {"message": {"query": "SIP 403 Forbidden"}}}));
        match omitted {
            QueryNode::Match { operator, .. } => assert_eq!(operator, BoolOperator::Omitted),
            other => panic!("expected match, got {other:?}"),
        }
        let explicit = q(json!({
            "match": {"message": {"query": "SIP 403 Forbidden", "operator": "or"}}
        }));
        match explicit {
            QueryNode::Match { operator, .. } => assert_eq!(operator, BoolOperator::Or),
            other => panic!("expected match, got {other:?}"),
        }
    }

    // ── track_total_hits ──────────────────────────────────────────────────────

    #[test]
    fn test_track_total_hits_parsing() {
        // Absent → exact tracking at the parser level (the ES 10k default is
        // injected by the HTTP layer, NOT here — `_count` and internal
        // sub-searches rely on the parser staying exact when unset).
        let req = parse_request(&json!({"query": {"match_all": {}}})).unwrap();
        assert_eq!(req.track_total_hits, TrackTotalHits::True);

        // true → exact.
        let req = parse_request(&json!({"track_total_hits": true})).unwrap();
        assert_eq!(req.track_total_hits, TrackTotalHits::True);

        // false → don't track.
        let req = parse_request(&json!({"track_total_hits": false})).unwrap();
        assert_eq!(req.track_total_hits, TrackTotalHits::False);

        // Integer N → cap at N.
        let req = parse_request(&json!({"track_total_hits": 10_000})).unwrap();
        assert_eq!(req.track_total_hits, TrackTotalHits::Limit(10_000));

        // -1 is the ES alias for `true` (exact), NOT a 10k cap.
        let req = parse_request(&json!({"track_total_hits": -1})).unwrap();
        assert_eq!(req.track_total_hits, TrackTotalHits::True);
    }

    // ── match_phrase ──────────────────────────────────────────────────────────

    #[test]
    fn test_match_phrase_shorthand() {
        let node = q(json!({"match_phrase": {"body": "quick brown fox"}}));
        assert!(
            matches!(node, QueryNode::MatchPhrase { ref field, slop: 0, .. }
            if field == "body")
        );
    }

    #[test]
    fn test_match_phrase_with_slop() {
        let node = q(json!({"match_phrase": {"body": {"query": "quick fox", "slop": 2}}}));
        assert!(matches!(node, QueryNode::MatchPhrase { slop: 2, .. }));
    }

    // ── multi_match ───────────────────────────────────────────────────────────

    #[test]
    fn test_multi_match_basic() {
        let node = q(json!({
            "multi_match": {
                "query": "hello",
                "fields": ["title", "body^2"]
            }
        }));
        if let QueryNode::MultiMatch {
            fields,
            query,
            match_type,
            ..
        } = node
        {
            assert_eq!(query, "hello");
            assert_eq!(fields, vec!["title", "body^2"]);
            assert_eq!(match_type, MultiMatchType::BestFields);
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_multi_match_cross_fields() {
        let node = q(json!({
            "multi_match": {
                "query": "Will Smith",
                "fields": ["first_name", "last_name"],
                "type": "cross_fields",
                "operator": "AND"
            }
        }));
        assert!(matches!(
            node,
            QueryNode::MultiMatch {
                match_type: MultiMatchType::CrossFields,
                ..
            }
        ));
    }

    /// #230 — `slop` and `max_expansions` are phrase parameters of
    /// `multi_match`. They used to be dropped here, so `{"type":"phrase",
    /// "slop":2}` was accepted and silently answered as an exact phrase.
    #[test]
    fn test_multi_match_phrase_params_are_parsed() {
        let node = q(json!({
            "multi_match": {
                "query": "quick fox", "fields": ["body"],
                "type": "phrase", "slop": 3
            }
        }));
        assert!(matches!(
            node,
            QueryNode::MultiMatch {
                match_type: MultiMatchType::Phrase,
                slop: 3,
                max_expansions: 50,
                ..
            }
        ));

        let node = q(json!({
            "multi_match": {
                "query": "quick fo", "fields": ["body"],
                "type": "phrase_prefix", "max_expansions": 7
            }
        }));
        assert!(matches!(
            node,
            QueryNode::MultiMatch {
                match_type: MultiMatchType::PhrasePrefix,
                slop: 0,
                max_expansions: 7,
                ..
            }
        ));
    }

    /// Values ES rejects must be rejected here too, not silently coerced.
    #[test]
    fn test_multi_match_phrase_params_are_validated() {
        for bad in [
            json!({"multi_match": {"query": "a b", "fields": ["body"],
                                   "type": "phrase", "slop": -1}}),
            json!({"multi_match": {"query": "a b", "fields": ["body"],
                                   "type": "phrase", "slop": 4294967296i64}}),
            json!({"multi_match": {"query": "a b", "fields": ["body"],
                                   "type": "phrase_prefix", "max_expansions": 0}}),
            // ES rejects slop for bool_prefix ONLY
            // (MultiMatchQueryBuilder.java:673).
            json!({"multi_match": {"query": "a b", "fields": ["body"],
                                   "type": "bool_prefix", "slop": 2}}),
            // The same values are rejected on the single-field phrase
            // entry points — one JSON value, one answer, whichever query
            // wraps it.
            json!({"match_phrase": {"body": {"query": "a b", "slop": -1}}}),
            json!({"match_phrase_prefix": {"body": {"query": "a b", "slop": -1}}}),
            json!({"match_phrase_prefix": {"body": {"query": "a b", "slop": 4294967296i64}}}),
            // `max_expansions` used to be read here as
            // `as_u64().unwrap_or(50)`, so both of these were accepted and
            // silently answered with 50 (#204 class).  ES throws "No negative
            // maxExpansions allowed" (MatchPhrasePrefixQueryBuilder.java:118).
            json!({"match_phrase_prefix": {"body": {"query": "a b", "max_expansions": -1}}}),
            json!({"match_phrase_prefix": {"body": {"query": "a b", "max_expansions": "many"}}}),
            json!({"match_phrase": {"body": {"query": "a b", "slop": "two"}}}),
        ] {
            assert!(
                parse_query(&bad).is_err(),
                "expected a parse error for {bad}"
            );
        }
    }

    /// Values ES *accepts by coercing* must be accepted here too. ES reads
    /// `slop` and `max_expansions` with `XContentParser.intValue()` under the
    /// default coercing policy, which truncates a float token and narrows a
    /// numeric string (`AbstractXContentParser.java:171` `intValue(coerce)`,
    /// `:162` `parseInt`, `:70`), so
    /// `{"slop": 2.0}` is a request ES answers with slop 2. Refusing it would
    /// be a new 400 on a query that works today, and reading it as 0 would be
    /// the accept-and-ignore this parser exists to remove — both are wrong.
    #[test]
    fn test_phrase_params_are_coerced_like_es() {
        for (v, want) in [(json!(2.0), 2u32), (json!(2.9), 2), (json!("2"), 2)] {
            let node = q(json!({"match_phrase": {"body": {"query": "a b", "slop": v}}}));
            assert!(
                matches!(node, QueryNode::MatchPhrase { slop, .. } if slop == want),
                "slop {v} must coerce to {want}, parsed to {node:?}"
            );
            let node = q(json!({"multi_match": {"query": "a b", "fields": ["body"],
                                                "type": "phrase", "slop": v}}));
            assert!(
                matches!(node, QueryNode::MultiMatch { slop, .. } if slop == want),
                "multi_match slop {v} must coerce to {want}, parsed to {node:?}"
            );
        }

        // `max_expansions: 0` is a 400 on `multi_match`
        // (MultiMatchQueryBuilder.java:389 rejects `<= 0`) and ACCEPTED on
        // `match_phrase_prefix` (MatchPhrasePrefixQueryBuilder.java:118
        // rejects only `< 0`). The asymmetry is ES's; XERJ mirrors it rather
        // than inventing a rule ES does not have.
        let node = q(json!({"match_phrase_prefix": {"body": {"query": "a b",
                                                             "max_expansions": 0}}}));
        assert!(
            matches!(node, QueryNode::MatchPhrasePrefix { max_expansions, .. }
                     if max_expansions == 0),
            "ES accepts max_expansions 0 on match_phrase_prefix, parsed to {node:?}"
        );
        assert!(
            parse_query(&json!({"multi_match": {"query": "a b", "fields": ["body"],
                                                "type": "phrase_prefix",
                                                "max_expansions": 0}}))
            .is_err(),
            "ES rejects max_expansions 0 on multi_match"
        );
    }

    /// `slop` + `type: phrase_prefix` is ACCEPTED and carried, at BOTH
    /// entry points. ES honours it (`MultiMatchQueryBuilder` rejects slop
    /// only for `bool_prefix`; `TextFieldMapper.createPhrasePrefixQuery`
    /// calls `MultiPhrasePrefixQuery.setSlop`), so refusing it would be a
    /// wire-compat break — and dropping it, as `parse_match_phrase_prefix`
    /// used to, is the accept-and-ignore defect class of #204.
    #[test]
    fn test_phrase_prefix_slop_is_carried_at_both_entry_points() {
        let node = q(json!({
            "multi_match": {"query": "quick fo", "fields": ["body"],
                            "type": "phrase_prefix", "slop": 2}
        }));
        assert!(
            matches!(
                node,
                QueryNode::MultiMatch {
                    match_type: MultiMatchType::PhrasePrefix,
                    slop: 2,
                    ..
                }
            ),
            "multi_match phrase_prefix must carry slop, got {node:?}"
        );

        let node = q(json!({
            "match_phrase_prefix": {"body": {"query": "quick fo", "slop": 2}}
        }));
        assert!(
            matches!(node, QueryNode::MatchPhrasePrefix { slop: 2, .. }),
            "match_phrase_prefix must carry slop, got {node:?}"
        );

        // Absent slop is 0 at both entry points.
        let node = q(json!({"match_phrase_prefix": {"body": "quick fo"}}));
        assert!(matches!(node, QueryNode::MatchPhrasePrefix { slop: 0, .. }));
    }

    // ── term ──────────────────────────────────────────────────────────────────

    #[test]
    fn test_term_shorthand() {
        let node = q(json!({"term": {"status": "active"}}));
        assert!(matches!(node, QueryNode::Term { ref field, ref value, .. }
            if field == "status" && *value == json!("active")));
    }

    #[test]
    fn test_term_long_form() {
        let node = q(json!({"term": {"status": {"value": "active", "boost": 1.5}}}));
        assert!(matches!(node, QueryNode::Term { boost: Some(b), .. } if (b - 1.5).abs() < 0.001));
    }

    #[test]
    fn test_term_numeric() {
        let node = q(json!({"term": {"age": 30}}));
        assert!(matches!(node, QueryNode::Term { ref field, ref value, .. }
            if field == "age" && *value == json!(30)));
    }

    // ── terms ─────────────────────────────────────────────────────────────────

    #[test]
    fn test_terms() {
        let node = q(json!({"terms": {"status": ["active", "pending"]}}));
        if let QueryNode::Terms { field, values, .. } = node {
            assert_eq!(field, "status");
            assert_eq!(values, vec![json!("active"), json!("pending")]);
        } else {
            panic!("wrong variant");
        }
    }

    // ── range ─────────────────────────────────────────────────────────────────

    #[test]
    fn test_range_numeric() {
        let node = q(json!({"range": {"age": {"gte": 18, "lt": 65}}}));
        if let QueryNode::Range {
            field,
            gte,
            lt,
            gt,
            lte,
            ..
        } = node
        {
            assert_eq!(field, "age");
            assert_eq!(gte, Some(json!(18)));
            assert_eq!(lt, Some(json!(65)));
            assert_eq!(gt, None);
            assert_eq!(lte, None);
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_range_date_time_zone() {
        let node = q(json!({"range": {"date": {
            "gte": "2024-03-10", "lt": "2024-03-11", "time_zone": "+05:30"
        }}}));
        if let QueryNode::Range { gte, lt, .. } = node {
            assert_eq!(gte, Some(json!("2024-03-09T18:30:00.000Z")));
            assert_eq!(lt, Some(json!("2024-03-10T18:30:00.000Z")));
        } else {
            panic!("wrong variant");
        }
        let err = parse_query(
            &json!({"range": {"date": {"gte": "2024-03-10", "time_zone": "Mars/Base"}}}),
        );
        assert!(err.is_err(), "an unknown time_zone must be rejected");
    }

    #[test]
    fn test_range_date() {
        let node = q(json!({"range": {"date": {"gte": "2024-01-01", "lte": "2024-12-31"}}}));
        assert!(matches!(node, QueryNode::Range { ref field, .. } if field == "date"));
    }

    #[test]
    fn test_range_no_bounds_fails() {
        assert!(parse_query(&json!({"range": {"age": {}}})).is_err());
    }

    // ── prefix ────────────────────────────────────────────────────────────────

    #[test]
    fn test_prefix_shorthand() {
        let node = q(json!({"prefix": {"name": "Joh"}}));
        assert!(
            matches!(node, QueryNode::Prefix { ref field, ref value, .. }
            if field == "name" && value == "Joh")
        );
    }

    #[test]
    fn test_prefix_long_form() {
        let node = q(json!({"prefix": {"name": {"value": "Joh", "boost": 2.0}}}));
        assert!(matches!(node, QueryNode::Prefix { ref value, .. } if value == "Joh"));
    }

    // ── wildcard ──────────────────────────────────────────────────────────────

    #[test]
    fn test_wildcard() {
        let node = q(json!({"wildcard": {"name": "Jo*n"}}));
        assert!(
            matches!(node, QueryNode::Wildcard { ref field, ref value, .. }
            if field == "name" && value == "Jo*n")
        );
    }

    // ── exists ────────────────────────────────────────────────────────────────

    #[test]
    fn test_exists() {
        let node = q(json!({"exists": {"field": "email"}}));
        assert!(matches!(node, QueryNode::Exists { ref field } if field == "email"));
    }

    // ── ids ───────────────────────────────────────────────────────────────────

    #[test]
    fn test_ids() {
        let node = q(json!({"ids": {"values": ["abc", "def", "123"]}}));
        if let QueryNode::Ids { values } = node {
            assert_eq!(values, vec!["abc", "def", "123"]);
        } else {
            panic!("wrong variant");
        }
    }

    // ── script ────────────────────────────────────────────────────────────────

    #[test]
    fn test_script_query() {
        let node = q(json!({
            "script": {
                "script": {
                    "source": "doc['x'].value > params.min",
                    "params": {"min": 5}
                }
            }
        }));
        if let QueryNode::Script { source, params } = node {
            assert_eq!(source, "doc['x'].value > params.min");
            assert_eq!(params, Some(json!({"min": 5})));
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_script_query_no_params() {
        let node = q(json!({"script": {"script": {"source": "true"}}}));
        if let QueryNode::Script { source, params } = node {
            assert_eq!(source, "true");
            assert_eq!(params, None);
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_script_query_missing_source_errs() {
        let result = parse_query(&json!({"script": {"script": {}}}));
        assert!(result.is_err());
    }

    // ── bool ──────────────────────────────────────────────────────────────────

    #[test]
    fn test_bool_basic() {
        let node = q(json!({
            "bool": {
                "must": [{"term": {"status": "active"}}],
                "must_not": [{"term": {"deleted": true}}],
                "filter": [{"range": {"age": {"gte": 18}}}]
            }
        }));
        if let QueryNode::Bool {
            must,
            must_not,
            filter,
            should,
            ..
        } = node
        {
            assert_eq!(must.len(), 1);
            assert_eq!(must_not.len(), 1);
            assert_eq!(filter.len(), 1);
            assert!(should.is_empty());
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_bool_single_must_not_array() {
        let node = q(json!({
            "bool": {
                "must": {"match": {"title": "rust"}}
            }
        }));
        if let QueryNode::Bool { must, .. } = node {
            assert_eq!(must.len(), 1);
        }
    }

    #[test]
    fn test_bool_empty_is_match_all() {
        let node = q(json!({"bool": {}}));
        assert_eq!(node, QueryNode::MatchAll);
    }

    #[test]
    fn test_bool_minimum_should_match() {
        let node = q(json!({
            "bool": {
                "should": [
                    {"term": {"tag": "a"}},
                    {"term": {"tag": "b"}},
                    {"term": {"tag": "c"}}
                ],
                "minimum_should_match": 2
            }
        }));
        if let QueryNode::Bool {
            minimum_should_match,
            ..
        } = node
        {
            assert_eq!(minimum_should_match, Some(MinShouldMatch::Fixed(2)));
        }
    }

    #[test]
    fn test_bool_minimum_should_match_pct() {
        let node = q(json!({
            "bool": {
                "should": [{"term": {"tag": "a"}}],
                "minimum_should_match": "75%"
            }
        }));
        if let QueryNode::Bool {
            minimum_should_match,
            ..
        } = node
        {
            assert_eq!(minimum_should_match, Some(MinShouldMatch::Percentage(75)));
        }
    }

    // ── constant_score ────────────────────────────────────────────────────────

    #[test]
    fn test_constant_score() {
        // constant_score keeps its Constant wrapper: ES scores every hit as
        // exactly `boost` (default 1.0), NOT the inner query's score — the
        // old flatten returned the inner term's brute score (live-diverged
        // vs ES 8.13.4). Matching fast paths peel the wrapper instead.
        let node = q(json!({
            "constant_score": {
                "filter": {"term": {"status": "active"}},
                "boost": 1.5
            }
        }));
        match node {
            QueryNode::Constant { score, query } => {
                assert_eq!(score, 1.5);
                assert!(matches!(*query, QueryNode::Term { .. }));
            }
            other => panic!("expected Constant wrapper, got {other:?}"),
        }
    }

    #[test]
    fn test_constant_score_default_boost() {
        let node = q(json!({
            "constant_score": {"filter": {"term": {"status": "active"}}}
        }));
        match node {
            QueryNode::Constant { score, .. } => assert_eq!(score, 1.0),
            other => panic!("expected Constant wrapper, got {other:?}"),
        }
    }

    // ── parent-child join (unsupported) ────────────────────────────────────────

    #[test]
    fn test_has_child_rejected() {
        // Parent-child joins are not materialized in XERJ; parsing must
        // fail loud (400) rather than build an AST node that silently runs
        // the inner query on flat docs.
        let err = parse_query(&json!({
            "has_child": {
                "type": "answer",
                "query": { "match": { "body": "hello" } }
            }
        }))
        .unwrap_err();
        assert!(
            format!("{err}").contains("parent-child join queries"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn test_has_parent_rejected() {
        let err = parse_query(&json!({
            "has_parent": {
                "parent_type": "question",
                "query": { "match": { "body": "hello" } }
            }
        }))
        .unwrap_err();
        assert!(
            format!("{err}").contains("parent-child join queries"),
            "unexpected error: {err}"
        );
    }

    // ── query_string ──────────────────────────────────────────────────────────

    #[test]
    fn test_query_string() {
        // `field:value AND field:value` is lowered into a Bool tree by
        // try_lower_query_string so the FTS / planner fast paths apply.
        // The opaque QueryString variant is kept only for inputs the
        // lowerer can't translate.
        let node = q(json!({
            "query_string": {
                "query": "title:rust AND body:ownership",
                "default_field": "title"
            }
        }));
        assert!(matches!(node, QueryNode::Bool { .. }));
    }

    fn qs(query: &str) -> QueryNode {
        q(json!({"query_string": {"query": query}}))
    }

    fn expect_range(
        node: QueryNode,
    ) -> (
        String,
        Option<Value>,
        Option<Value>,
        Option<Value>,
        Option<Value>,
    ) {
        match node {
            QueryNode::Range {
                field,
                gt,
                gte,
                lt,
                lte,
                ..
            } => (field, gt, gte, lt, lte),
            other => panic!("expected Range, got {other:?}"),
        }
    }

    #[test]
    fn test_query_string_range_gt() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:>1"));
        assert_eq!(field, "n");
        assert_eq!(gt, Some(json!(1)));
        assert!(gte.is_none() && lt.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_gte() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:>=2"));
        assert_eq!(field, "n");
        assert_eq!(gte, Some(json!(2)));
        assert!(gt.is_none() && lt.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_lt() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:<5"));
        assert_eq!(field, "n");
        assert_eq!(lt, Some(json!(5)));
        assert!(gt.is_none() && gte.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_lte() {
        let (field, _, _, _, lte) = expect_range(qs("n:<=5"));
        assert_eq!(field, "n");
        assert_eq!(lte, Some(json!(5)));
    }

    /// The `query` of each bare `Match` in `nodes`, in order.
    fn match_terms(nodes: &[QueryNode]) -> Vec<&str> {
        nodes
            .iter()
            .map(|n| match n {
                QueryNode::Match { query, .. } => query.as_str(),
                other => panic!("expected a bare match, got {other:?}"),
            })
            .collect()
    }

    /// One query-string boolean level as (must, should, must_not, msm).
    fn occurs(
        query: &str,
        default_operator: Option<&str>,
    ) -> (
        Vec<String>,
        Vec<String>,
        Vec<String>,
        Option<MinShouldMatch>,
    ) {
        let mut body = json!({"query": query, "default_field": "t"});
        if let Some(op) = default_operator {
            body["default_operator"] = json!(op);
        }
        match q(json!({ "query_string": body })) {
            QueryNode::Bool {
                must,
                should,
                must_not,
                minimum_should_match,
                ..
            } => {
                let own = |v: &[QueryNode]| match_terms(v).into_iter().map(String::from).collect();
                (
                    own(&must),
                    own(&should),
                    own(&must_not),
                    minimum_should_match,
                )
            }
            other => panic!("{query}: expected a Bool, got {other:?}"),
        }
    }

    fn strs(v: &[&str]) -> Vec<String> {
        v.iter().map(|s| s.to_string()).collect()
    }

    /// #1299: a prohibited clause excludes from its whole level. `alpha
    /// -beta` used to lower to `alpha OR (NOT beta)`, whose pure-negative
    /// branch matched every document without `beta`.
    #[test]
    fn query_string_negation_excludes_from_the_whole_level() {
        let one = Some(MinShouldMatch::Fixed(1));
        for query in [
            "alpha -beta",
            "-beta alpha",
            "alpha NOT beta",
            "alpha OR -beta",
        ] {
            assert_eq!(
                occurs(query, None),
                (vec![], strs(&["alpha"]), strs(&["beta"]), one.clone()),
                "{query}"
            );
        }
        assert_eq!(
            occurs("alpha beta -gamma", None),
            (vec![], strs(&["alpha", "beta"]), strs(&["gamma"]), one)
        );
        // `+` makes a clause required and the rest only score.
        assert_eq!(
            occurs("+alpha beta -gamma", None),
            (strs(&["alpha"]), strs(&["beta"]), strs(&["gamma"]), None)
        );
    }

    /// Mixed `AND` / `OR` follow Lucene's classic parser, as ES 8.13.4 does:
    /// `AND` makes the clause before it required too, and under
    /// `default_operator: AND` an `OR` makes the clause before it optional.
    #[test]
    fn query_string_mixed_operators_follow_the_classic_parser() {
        assert_eq!(
            occurs("kiwi OR lime AND plum", None),
            (strs(&["lime", "plum"]), strs(&["kiwi"]), vec![], None)
        );
        assert_eq!(
            occurs("kiwi AND lime OR plum", None),
            (strs(&["kiwi", "lime"]), strs(&["plum"]), vec![], None)
        );
        assert_eq!(
            occurs("kiwi AND NOT lime OR plum", None),
            (strs(&["kiwi"]), strs(&["plum"]), strs(&["lime"]), None)
        );
        assert_eq!(
            occurs("kiwi OR lime plum", Some("AND")),
            (strs(&["plum"]), strs(&["kiwi", "lime"]), vec![], None)
        );
        assert_eq!(
            occurs("-kiwi lime OR plum", Some("AND")),
            (
                vec![],
                strs(&["lime", "plum"]),
                strs(&["kiwi"]),
                Some(MinShouldMatch::Fixed(1))
            )
        );
    }

    /// Every (field, value) leaf of a lowered query_string, in tree order.
    fn qs_leaves(node: &QueryNode) -> Vec<(String, String)> {
        fn walk(n: &QueryNode, out: &mut Vec<(String, String)>) {
            match n {
                QueryNode::Match { field, query, .. }
                | QueryNode::MatchPhrase { field, query, .. } => {
                    out.push((field.clone(), query.clone()))
                }
                QueryNode::Wildcard { field, value, .. } => {
                    out.push((field.clone(), value.clone()))
                }
                QueryNode::Range { field, .. } => out.push((field.clone(), "<range>".into())),
                QueryNode::Bool {
                    must,
                    should,
                    must_not,
                    filter,
                    ..
                } => {
                    for c in must.iter().chain(should).chain(must_not).chain(filter) {
                        walk(c, out);
                    }
                }
                QueryNode::DisMax { queries, .. } => queries.iter().for_each(|c| walk(c, out)),
                QueryNode::Boosted { query, .. } => walk(query, out),
                other => panic!("unexpected leaf {other:?}"),
            }
        }
        let mut out = Vec::new();
        walk(node, &mut out);
        out
    }

    fn pairs(v: &[(&str, &str)]) -> Vec<(String, String)> {
        v.iter()
            .map(|(f, q)| (f.to_string(), q.to_string()))
            .collect()
    }

    /// #1298: `field:( … )` scopes the whole group to `field`. It used to
    /// lower to an empty-valued `Match` on `field` plus the group's terms on
    /// the `*` placeholder, so the group searched every field.
    #[test]
    fn query_string_field_group_is_scoped_to_the_field() {
        assert_eq!(qs_leaves(&qs("title:(beta)")), pairs(&[("title", "beta")]));
        assert_eq!(qs_leaves(&qs("title: (beta)")), pairs(&[("title", "beta")]));
        assert_eq!(
            qs_leaves(&qs("title:(alpha OR (beta AND gamma))")),
            pairs(&[("title", "alpha"), ("title", "beta"), ("title", "gamma")])
        );
        // Phrases and wildcards inside the group land on the field too.
        assert_eq!(
            qs_leaves(&qs("title:(\"alpha beta\" alp*)")),
            pairs(&[("title", "alpha beta"), ("title", "alp*")])
        );
        // A clause that names its own field keeps it, as in ES.
        assert_eq!(
            qs_leaves(&qs("title:(alpha OR body:gamma)")),
            pairs(&[("title", "alpha"), ("body", "gamma")])
        );
        // The group's field beats `default_field` / `fields`.
        let with_default =
            q(json!({"query_string": {"query": "title:(beta)", "default_field": "body"}}));
        assert_eq!(qs_leaves(&with_default), pairs(&[("title", "beta")]));
        let with_fields =
            q(json!({"query_string": {"query": "title:(beta)", "fields": ["body", "x"]}}));
        assert_eq!(qs_leaves(&with_fields), pairs(&[("title", "beta")]));
    }

    /// #1298: an unqualified range inside `n:( … )` has a concrete field and
    /// lowers to a `Range` on it. It used to be refused ("requires an
    /// explicit field").
    #[test]
    fn query_string_range_inside_a_field_group_targets_the_field() {
        assert_eq!(qs_leaves(&qs("n:(>4)")), pairs(&[("n", "<range>")]));
        assert_eq!(qs_leaves(&qs("n:([2 TO 8])")), pairs(&[("n", "<range>")]));
        // Outside any field group the old refusal still holds.
        assert!(parse_query(&json!({"query_string": {"query": "(>4)"}})).is_err());
    }

    /// `default_operator` reaches inside a group: ES 8.13.4 requires both
    /// terms for `(alpha beta)` with `AND`. Groups used to be implicitly OR.
    #[test]
    fn query_string_default_operator_applies_inside_a_group() {
        for query in ["title:(alpha beta)", "(alpha beta)"] {
            let node = q(json!({"query_string": {
                "query": query, "default_field": "title", "default_operator": "AND"
            }}));
            match node {
                QueryNode::Bool { must, should, .. } => {
                    assert_eq!(must.len(), 2, "{query}: {must:?}");
                    assert!(should.is_empty(), "{query}: {should:?}");
                }
                other => panic!("{query}: expected a Bool, got {other:?}"),
            }
        }
    }

    /// `query_string`'s `fields` was accepted and ignored — the key never
    /// reached this parser, so the query ran over every field regardless. It
    /// now selects the targets for an unqualified clause, the same way
    /// `simple_query_string`'s `fields` already did.
    #[test]
    fn test_query_string_fields_select_the_unqualified_targets() {
        // One field is exactly `default_field`.
        match q(json!({"query_string": {"query": "hello", "fields": ["title"]}})) {
            QueryNode::Match { field, query, .. } => {
                assert_eq!(field, "title");
                assert_eq!(query, "hello");
            }
            other => panic!("expected Match on title, got {other:?}"),
        }

        // Several become a dis_max over one leaf per field, and `^boost` on a
        // spec lands on that leaf.
        match q(json!({"query_string": {"query": "hello", "fields": ["title^3", "body"]}})) {
            QueryNode::DisMax { queries, .. } => {
                assert_eq!(queries.len(), 2);
                match &queries[0] {
                    QueryNode::Match { field, boost, .. } => {
                        assert_eq!(field, "title");
                        assert_eq!(*boost, Some(3.0));
                    }
                    other => panic!("expected boosted Match on title, got {other:?}"),
                }
                match &queries[1] {
                    QueryNode::Match { field, boost, .. } => {
                        assert_eq!(field, "body");
                        assert_eq!(*boost, None);
                    }
                    other => panic!("expected Match on body, got {other:?}"),
                }
            }
            other => panic!("expected DisMax, got {other:?}"),
        }

        // A clause that names its own field keeps it: `fields` only supplies
        // the target for clauses that named none, as in ES.
        match q(json!({"query_string": {"query": "body:hello", "fields": ["title"]}})) {
            QueryNode::Match { field, .. } => assert_eq!(field, "body"),
            other => panic!("expected Match on body, got {other:?}"),
        }

        // With no `fields` and no `default_field` nothing changes: the
        // field-less `"*"` placeholder is still what an unqualified clause
        // resolves to.
        match qs("hello") {
            QueryNode::Match { field, .. } => assert_eq!(field, "*"),
            other => panic!("expected Match on *, got {other:?}"),
        }

        // An unqualified range now resolves against `fields` too, instead of
        // erroring for want of a `default_field`.
        match q(json!({"query_string": {"query": ">10", "fields": ["n"]}})) {
            QueryNode::Range { field, gt, .. } => {
                assert_eq!(field, "n");
                assert_eq!(gt, Some(json!(10)));
            }
            other => panic!("expected Range on n, got {other:?}"),
        }
    }

    #[test]
    fn test_query_string_range_inclusive_brackets() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO 5]"));
        assert_eq!(field, "n");
        assert_eq!(gte, Some(json!(2)));
        assert_eq!(lte, Some(json!(5)));
        assert!(gt.is_none() && lt.is_none());
    }

    #[test]
    fn test_query_string_range_exclusive_brackets() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:{2 TO 5}"));
        assert_eq!(field, "n");
        assert_eq!(gt, Some(json!(2)));
        assert_eq!(lt, Some(json!(5)));
        assert!(gte.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_mixed_brackets() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO 5}"));
        assert_eq!(field, "n");
        assert_eq!(gte, Some(json!(2)));
        assert_eq!(lt, Some(json!(5)));
        assert!(gt.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_open_upper() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO *]"));
        assert_eq!(field, "n");
        assert_eq!(gte, Some(json!(2)));
        assert!(gt.is_none() && lt.is_none() && lte.is_none());
    }

    #[test]
    fn test_query_string_range_open_lower() {
        let (field, gt, gte, lt, lte) = expect_range(qs("n:[* TO 5]"));
        assert_eq!(field, "n");
        assert_eq!(lte, Some(json!(5)));
        assert!(gt.is_none() && gte.is_none() && lt.is_none());
    }

    #[test]
    fn test_query_string_range_negative_and_float() {
        let (_, gt, ..) = expect_range(qs("n:>-1"));
        assert_eq!(gt, Some(json!(-1)));
        let (_, gt, ..) = expect_range(qs("n:>1.5"));
        assert_eq!(gt, Some(json!(1.5)));
    }

    #[test]
    fn test_query_string_range_date() {
        // Date bounds resolve with ES rounding semantics: `>` (exclusive
        // lower) rounds UP to the last ms of the covered day, `>=`/`<=`
        // round down/up respectively — live-verified vs ES 8.13.4.
        let (field, gt, ..) = expect_range(qs("ts:>2020-01-01"));
        assert_eq!(field, "ts");
        assert_eq!(gt, Some(json!("2020-01-01T23:59:59.999Z")));
        let (field, _, gte, _, lte) = expect_range(qs("ts:[2020-01-01 TO 2020-12-31]"));
        assert_eq!(field, "ts");
        assert_eq!(gte, Some(json!("2020-01-01T00:00:00.000Z")));
        assert_eq!(lte, Some(json!("2020-12-31T23:59:59.999Z")));
    }

    #[test]
    fn test_query_string_range_combined_and() {
        // "msg:foo AND n:>1" → Bool.must = [Match(msg), Range(n, gt 1)]
        let node = qs("msg:foo AND n:>1");
        let QueryNode::Bool {
            must,
            must_not,
            should,
            ..
        } = node
        else {
            panic!("expected Bool");
        };
        assert!(must_not.is_empty() && should.is_empty());
        assert_eq!(must.len(), 2);
        assert!(matches!(&must[0], QueryNode::Match { field, .. } if field == "msg"));
        let (field, gt, ..) = expect_range(must[1].clone());
        assert_eq!(field, "n");
        assert_eq!(gt, Some(json!(1)));
    }

    #[test]
    fn test_query_string_range_combined_bracket_and() {
        let node = qs("msg:foo AND n:[2 TO *]");
        let QueryNode::Bool { must, .. } = node else {
            panic!("expected Bool")
        };
        assert_eq!(must.len(), 2);
        let (field, _, gte, ..) = expect_range(must[1].clone());
        assert_eq!(field, "n");
        assert_eq!(gte, Some(json!(2)));
    }

    #[test]
    fn test_query_string_range_default_field() {
        // Unqualified range resolves against default_field.
        let node = q(json!({
            "query_string": {"query": ">10", "default_field": "n"}
        }));
        let (field, gt, ..) = expect_range(node);
        assert_eq!(field, "n");
        assert_eq!(gt, Some(json!(10)));
    }

    #[test]
    fn test_query_string_range_errors_do_not_degrade() {
        // Malformed / unrepresentable ranges must be parse errors,
        // never a silent term match.
        for bad in [
            "n:[2 TO",    // unterminated bracket
            "n:[2 5]",    // missing TO
            "n:>",        // missing value
            "n:[* TO *]", // no usable bound
            ">10",        // no field and no default_field
        ] {
            let res = parse_query(&json!({"query_string": {"query": bad}}));
            assert!(
                res.is_err(),
                "expected parse error for {bad:?}, got {res:?}"
            );
        }
    }

    // ── knn ───────────────────────────────────────────────────────────────────

    #[test]
    fn test_knn() {
        let node = q(json!({
            "knn": {
                "field": "embedding",
                "query_vector": [0.1, 0.2, 0.3],
                "k": 5
            }
        }));
        if let QueryNode::Knn {
            field,
            vector,
            k,
            filter,
            ..
        } = node
        {
            assert_eq!(field, "embedding");
            assert_eq!(k, 5);
            assert_eq!(vector.len(), 3);
            assert!(filter.is_none());
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn test_knn_num_candidates_independent_of_k() {
        // num_candidates is carried through as its own value; k stays explicit.
        let node = q(json!({
            "knn": {
                "field": "embedding",
                "query_vector": [0.1, 0.2, 0.3],
                "k": 3,
                "num_candidates": 50
            }
        }));
        match node {
            QueryNode::Knn {
                k, num_candidates, ..
            } => {
                assert_eq!(k, 3);
                assert_eq!(num_candidates, Some(50));
            }
            other => panic!("expected knn, got {:?}", other),
        }
    }

    #[test]
    fn test_knn_k_defaults_to_num_candidates_when_k_omitted() {
        // With k omitted, k still derives from num_candidates (unchanged).
        let node = q(json!({
            "knn": {
                "field": "embedding",
                "query_vector": [0.1],
                "num_candidates": 7
            }
        }));
        match node {
            QueryNode::Knn {
                k, num_candidates, ..
            } => {
                assert_eq!(k, 7);
                assert_eq!(num_candidates, Some(7));
            }
            other => panic!("expected knn, got {:?}", other),
        }
    }

    #[test]
    fn test_knn_with_filter() {
        let node = q(json!({
            "knn": {
                "field": "embedding",
                "query_vector": [0.1, 0.2],
                "k": 10,
                "filter": {"term": {"status": "active"}}
            }
        }));
        assert!(matches!(
            node,
            QueryNode::Knn {
                filter: Some(_),
                ..
            }
        ));
    }

    // ── full request ──────────────────────────────────────────────────────────

    #[test]
    fn test_parse_full_request() {
        let body = json!({
            "query": {
                "bool": {
                    "must": [{"match": {"title": "rust"}}],
                    "filter": [{"term": {"status": "published"}}]
                }
            },
            "from": 20,
            "size": 5,
            "sort": [{"date": "desc"}, "_score"],
            "_source": ["title", "date"],
            "explain": true
        });
        let req = parse_request(&body).expect("parse_request failed");
        assert_eq!(req.from, 20);
        assert_eq!(req.size, 5);
        assert_eq!(req.sort.len(), 2);
        assert!(req.explain);
        assert!(matches!(req.query, QueryNode::Bool { .. }));
    }

    #[test]
    fn test_parse_request_defaults() {
        let req = parse_request(&json!({})).expect("should default to match_all");
        assert_eq!(req.query, QueryNode::MatchAll);
        assert_eq!(req.from, 0);
        assert_eq!(req.size, 10);
    }

    // ── error cases ───────────────────────────────────────────────────────────

    #[test]
    fn test_unknown_query_type_error() {
        let err = parse_query(&json!({"fuzzy_wuzzy": {}})).unwrap_err();
        assert!(err.to_string().contains("fuzzy_wuzzy"));
    }

    #[test]
    fn test_multi_key_object_error() {
        let err = parse_query(&json!({"match": {}, "term": {}})).unwrap_err();
        assert!(err.to_string().contains("exactly one key"));
    }

    #[test]
    fn test_hybrid_query() {
        let node = q(json!({
            "hybrid": {
                "queries": [
                    {"query": {"match": {"title": "rust"}}, "weight": 0.7},
                    {"query": {"knn": {"field": "vec", "query_vector": [0.1], "k": 5}}, "weight": 0.3}
                ],
                "fusion": "rrf"
            }
        }));
        if let QueryNode::Hybrid { queries, fusion } = node {
            assert_eq!(queries.len(), 2);
            assert!((queries[0].weight - 0.7).abs() < 0.001);
            assert!(matches!(fusion, FusionStrategy::Rrf { k: 60 }));
        } else {
            panic!("wrong variant");
        }
    }

    #[test]
    fn hybrid_item_missing_query_names_the_query_weight_shape() {
        let err = parse_query(&json!({
            "hybrid": {
                "queries": [
                    {"weight": 1.0},
                    {"query": {"match_all": {}}}
                ]
            }
        }))
        .unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("`hybrid.queries[0]` missing `query`"), "{msg}");
        assert!(
            msg.contains("{\"query\": <clause>, \"weight\": <number>}"),
            "{msg}"
        );
        assert!(msg.contains("weight defaults to 1"), "{msg}");

        let err = parse_query(&json!({
            "hybrid": { "queries": ["rotate keys"] }
        }))
        .unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains(
                "`hybrid.queries[0]` must be an object {\"query\": <clause>, \"weight\": <number>}"
            ),
            "{msg}"
        );
    }

    #[test]
    fn test_hybrid_learned_rejected() {
        // Learned fusion is not implemented — must fail loud rather than
        // silently substituting RRF. Both the string and object forms.
        for fusion in [json!("learned"), json!({ "type": "learned" })] {
            let err = parse_query(&json!({
                "hybrid": {
                    "queries": [
                        {"query": {"match": {"title": "rust"}}},
                        {"query": {"match": {"title": "go"}}}
                    ],
                    "fusion": fusion
                }
            }))
            .unwrap_err();
            assert!(
                format!("{err}").contains("learned is not yet supported"),
                "unexpected error: {err}"
            );
        }
    }

    #[test]
    fn test_nested_bool() {
        let node = q(json!({
            "bool": {
                "must": [
                    {
                        "bool": {
                            "should": [
                                {"term": {"tag": "rust"}},
                                {"term": {"tag": "systems"}}
                            ]
                        }
                    },
                    {"range": {"year": {"gte": 2020}}}
                ]
            }
        }));
        assert!(matches!(node, QueryNode::Bool { .. }));
    }

    // ── percolate ─────────────────────────────────────────────────────────────

    #[test]
    fn test_percolate_single_document() {
        let node = q(json!({
            "percolate": { "field": "query", "document": { "message": "hi" } }
        }));
        match node {
            QueryNode::Percolate { field, documents } => {
                assert_eq!(field, "query");
                assert_eq!(documents.len(), 1);
                assert_eq!(documents[0]["message"], json!("hi"));
            }
            other => panic!("expected percolate, got {:?}", other),
        }
    }

    #[test]
    fn test_percolate_multiple_documents() {
        let node = q(json!({
            "percolate": {
                "field": "query",
                "documents": [ { "message": "a" }, { "message": "b" } ]
            }
        }));
        match node {
            QueryNode::Percolate { documents, .. } => assert_eq!(documents.len(), 2),
            other => panic!("expected percolate, got {:?}", other),
        }
    }

    #[test]
    fn test_percolate_missing_document_is_400() {
        // Neither `document` nor `documents` present.
        assert!(parse_query(&json!({ "percolate": { "field": "query" } })).is_err());
        // Index/id fetch form is rejected.
        assert!(parse_query(&json!({
            "percolate": { "field": "query", "index": "i", "id": "1" }
        }))
        .is_err());
        // Missing field is rejected.
        assert!(parse_query(&json!({
            "percolate": { "document": { "m": "x" } }
        }))
        .is_err());
    }

    // ── span_containing / span_within ───────────────────────────────────────

    #[test]
    fn test_span_containing_parses_little_and_big() {
        let node = q(json!({
            "span_containing": {
                "little": { "span_term": { "text": "brown" } },
                "big": {
                    "span_near": {
                        "clauses": [
                            { "span_term": { "text": "quick" } },
                            { "span_term": { "text": "fox" } }
                        ],
                        "slop": 3,
                        "in_order": true
                    }
                }
            }
        }));
        match node {
            QueryNode::SpanContaining { little, big } => {
                assert!(matches!(*little, QueryNode::SpanTerm { .. }));
                assert!(matches!(*big, QueryNode::SpanNear { .. }));
            }
            other => panic!("expected span_containing, got {:?}", other),
        }
    }

    #[test]
    fn test_span_within_variant() {
        let node = q(json!({
            "span_within": {
                "little": { "span_term": { "text": "brown" } },
                "big": { "span_term": { "text": "quick" } }
            }
        }));
        assert!(matches!(node, QueryNode::SpanWithin { .. }));
    }

    #[test]
    fn test_span_containing_missing_clause_is_400() {
        assert!(parse_query(&json!({
            "span_containing": { "big": { "span_term": { "text": "x" } } }
        }))
        .is_err());
        assert!(parse_query(&json!({
            "span_within": { "little": { "span_term": { "text": "x" } } }
        }))
        .is_err());
    }

    // ── terms_set minimum_should_match_field / _script ──────────────────────

    #[test]
    fn test_terms_set_minimum_should_match_field() {
        let node = q(json!({
            "terms_set": {
                "codes": {
                    "terms": ["a", "b", "c"],
                    "minimum_should_match_field": "required"
                }
            }
        }));
        match node {
            QueryNode::Bool {
                minimum_should_match: Some(MinShouldMatch::Field(name)),
                should,
                ..
            } => {
                assert_eq!(name, "required");
                assert_eq!(should.len(), 3);
            }
            other => panic!("expected bool w/ field msm, got {:?}", other),
        }
    }

    #[test]
    fn test_terms_set_minimum_should_match_script() {
        let node = q(json!({
            "terms_set": {
                "codes": {
                    "terms": ["a", "b"],
                    "minimum_should_match_script": { "source": "params.num_terms" }
                }
            }
        }));
        match node {
            QueryNode::Bool {
                minimum_should_match: Some(MinShouldMatch::Script { source, .. }),
                ..
            } => assert_eq!(source, "params.num_terms"),
            other => panic!("expected bool w/ script msm, got {:?}", other),
        }
    }

    // ── rank_feature ────────────────────────────────────────────────────────

    fn rank_feature_fn(body: serde_json::Value) -> crate::ast::RankFeatureFn {
        use crate::ast::QueryNode;
        match q(body) {
            QueryNode::FunctionScore {
                functions,
                boost_mode,
                ..
            } => {
                assert_eq!(boost_mode, crate::ast::BoostMode::Replace);
                functions[0]
                    .rank_feature
                    .as_ref()
                    .expect("rank_feature payload present")
                    .function
                    .clone()
            }
            other => panic!("expected function_score, got {:?}", other),
        }
    }

    #[test]
    fn test_rank_feature_saturation_with_pivot() {
        let f = rank_feature_fn(json!({
            "rank_feature": { "field": "pagerank", "saturation": { "pivot": 8 } }
        }));
        assert_eq!(
            f,
            crate::ast::RankFeatureFn::Saturation { pivot: Some(8.0) }
        );
    }

    #[test]
    fn test_rank_feature_defaults_to_saturation() {
        let f = rank_feature_fn(json!({ "rank_feature": { "field": "pagerank" } }));
        assert_eq!(f, crate::ast::RankFeatureFn::Saturation { pivot: None });
    }

    #[test]
    fn test_rank_feature_log_sigmoid_linear() {
        assert_eq!(
            rank_feature_fn(json!({
                "rank_feature": { "field": "pr", "log": { "scaling_factor": 4 } }
            })),
            crate::ast::RankFeatureFn::Log {
                scaling_factor: 4.0
            }
        );
        assert_eq!(
            rank_feature_fn(json!({
                "rank_feature": { "field": "pr", "sigmoid": { "pivot": 7, "exponent": 0.6 } }
            })),
            crate::ast::RankFeatureFn::Sigmoid {
                pivot: 7.0,
                exponent: 0.6
            }
        );
        assert_eq!(
            rank_feature_fn(json!({ "rank_feature": { "field": "pr", "linear": {} } })),
            crate::ast::RankFeatureFn::Linear
        );
    }

    #[test]
    fn test_rank_feature_log_missing_scaling_is_400() {
        assert!(parse_query(&json!({
            "rank_feature": { "field": "pr", "log": {} }
        }))
        .is_err());
    }

    #[test]
    fn fields_accept_scalar_array_and_object_forms() {
        for (body, expected) in [
            (json!({"fields": "_passage"}), vec!["_passage"]),
            (
                json!({"fields": ["company", "_passage"]}),
                vec!["company", "_passage"],
            ),
            (
                json!({"fields": [{"field": "_passage", "format": "ignored"}]}),
                vec!["_passage"],
            ),
        ] {
            assert_eq!(parse_request(&body).unwrap().fields, expected);
        }
    }

    // ── Security regression tests ───────────────────────────────────────────

    /// F1: deeply nested parens in `query_string` must not overflow the stack.
    /// Pre-fix, ~100 k nested `(` caused a SIGSEGV process abort. The depth
    /// guard in `parse_qs_unary`'s `LParen` arm caps nesting to
    /// `MAX_QUERY_DEPTH` (64) and falls back to the opaque `QueryString` path.
    #[test]
    fn test_query_string_deep_paren_nesting_does_not_overflow() {
        // 5000 nested parens is well above the 64-depth cap but well below
        // the stack-overflow threshold (~100 k). Pre-fix this would have
        // recursed 5000 deep; post-fix the depth guard trips at 64 and the
        // parser falls back to QueryString without crashing.
        let deep = "(".repeat(5000) + "a" + &")".repeat(5000);
        let node = q(json!({"query_string": {"query": &deep}}));
        // The fallback is opaque QueryString (the depth guard returns None
        // from parse_qs_unary, try_lower_query_string returns Ok(None), and
        // parse_query_string wraps the raw query in QueryNode::QueryString).
        // It must NOT panic / abort.
        match &node {
            QueryNode::QueryString { query, .. } => assert_eq!(query, &deep),
            other => panic!("expected QueryString fallback, got {other:?}"),
        }
    }

    /// F1: a `query_string.query` longer than 64 KiB is rejected with a parse
    /// error (defense-in-depth before tokenizing).
    #[test]
    fn test_query_string_over_length_cap_rejected() {
        let too_long = "a ".repeat(40_000); // 80_000 chars > 65_536
        let res = parse_query(&json!({
            "query_string": { "query": too_long }
        }));
        assert!(res.is_err(), "oversized query_string should be rejected");
    }

    /// F1: a legitimate moderately-nested query still lowers into a Bool tree.
    /// Ensures the depth guard doesn't trip on reasonable nesting (10 levels).
    #[test]
    fn test_query_string_moderate_paren_nesting_still_parses() {
        let mut qs = String::new();
        for _ in 0..10 {
            qs.push_str("(title:foo OR ");
        }
        qs.push_str("title:bar");
        for _ in 0..10 {
            qs.push(')');
        }
        let node = q(json!({"query_string": {"query": &qs}}));
        // 10 levels of nesting is well within the 64-depth cap, so it should
        // lower into a Bool tree (not fall back to opaque QueryString).
        assert!(
            matches!(node, QueryNode::Bool { .. }),
            "moderate nesting should parse to Bool, got {node:?}"
        );
    }

    /// F6: `more_like_this` with an oversized `fields × like` cross-product
    /// is rejected with a parse error instead of pre-allocating a huge Vec.
    /// Pre-fix, 10 000 × 10 000 would try to allocate ~10 GiB and abort.
    #[test]
    fn test_more_like_this_cross_product_capped() {
        let fields: Vec<String> = (0..200).map(|i| format!("f{i}")).collect();
        let like: Vec<String> = (0..200).map(|i| format!("text{i}")).collect();
        let res = parse_query(&json!({
            "more_like_this": { "fields": fields, "like": like }
        }));
        assert!(
            res.is_err(),
            "200×200=40000 cross-product exceeds 4096 cap and must be rejected"
        );
    }

    /// F6: `more_like_this` with too many fields is rejected.
    #[test]
    fn test_more_like_this_fields_cap() {
        let fields: Vec<String> = (0..65).map(|i| format!("f{i}")).collect();
        let res = parse_query(&json!({
            "more_like_this": { "fields": fields, "like": ["text"] }
        }));
        assert!(res.is_err(), "65 fields exceeds the 64-field cap");
    }

    /// F6: `more_like_this` within the caps still parses successfully.
    #[test]
    fn test_more_like_this_within_caps_parses() {
        let fields = vec!["title".to_string(), "body".to_string()];
        let like = vec!["interesting text".to_string(), "more text".to_string()];
        // 2 fields × 2 like = 4 cross-product, well within 4096.
        let res = parse_query(&json!({
            "more_like_this": { "fields": fields, "like": like }
        }));
        assert!(res.is_ok(), "2×2 cross-product should parse fine");
    }

    // ── bool clause count (issue #122) ────────────────────────────────────

    fn bool_with_clauses(n: usize) -> serde_json::Value {
        let clauses: Vec<serde_json::Value> = (0..n)
            .map(|i| json!({ "term": { format!("f{i}"): format!("v{i}") } }))
            .collect();
        json!({ "bool": { "should": clauses } })
    }

    /// `MAX_QUERY_DEPTH` bounds how deep a query nests; nothing bounded how
    /// wide it is. Width is what multiplies per-document work: with no
    /// compiled-script cache in the engine, N script clauses over D documents
    /// is N x D full script parses, and the clause count is the only place
    /// that product can be bounded before any of it happens.
    #[test]
    fn a_bool_query_may_not_carry_unbounded_clauses() {
        let err = parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT + 1))
            .expect_err("an over-wide bool must be refused");
        assert!(
            err.to_string().contains("too_many_clauses"),
            "the error must be ES's own, got {err}"
        );
    }

    /// Exactly at the cap still parses — the limit is a cap, not an off-by-one
    /// haircut on legitimate queries.
    #[test]
    fn a_bool_query_at_the_clause_cap_still_parses() {
        parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT))
            .expect("a query at exactly the cap must parse");
    }

    /// The width is the whole query's, not one `bool`'s: two sibling bools of
    /// 600 clauses each are 1,200 clauses of work however they are spelled.
    #[test]
    fn the_clause_cap_is_summed_across_sibling_bools() {
        let query = json!({
            "bool": {
                "must": [ bool_with_clauses(600), bool_with_clauses(600) ]
            }
        });
        let err = parse_query(&query).expect_err("1,200 clauses must be refused");
        assert!(err.to_string().contains("too_many_clauses"), "got {err}");
    }

    /// The counter is a thread-local, so a rejected query must not poison the
    /// next request that happens to land on the same worker.
    #[test]
    fn a_rejected_query_does_not_poison_the_next_one() {
        let _ = parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT + 1));
        parse_query(&bool_with_clauses(8))
            .expect("an ordinary query after a rejected one must still parse");
    }

    /// Span clause lists, `dis_max.queries` and an array `knn.filter` are all
    /// clause lists under other names, and all count towards the same width.
    /// The cap is exercised through each of them — together with the refusal
    /// semantics that go with it — in `tests/span_clause_refusal.rs`, which
    /// survives a revert of this file and so can show what the fix is worth.
    #[test]
    fn the_cap_is_reachable_through_every_clause_list_shape() {
        let wide: Vec<serde_json::Value> = (0..MAX_CLAUSE_COUNT + 1)
            .map(|i| json!({ "term": { "f": format!("v{i}") } }))
            .collect();
        for query in [
            json!({ "span_or": { "clauses": wide } }),
            json!({ "dis_max": { "queries": wide } }),
            json!({ "knn": {
                "field": "vec", "query_vector": [0.1, 0.2], "k": 3, "filter": wide
            }}),
        ] {
            let err = parse_query(&query).expect_err("an over-wide clause list must be refused");
            assert!(err.to_string().contains("too_many_clauses"), "got {err}");
        }
    }

    /// Regression for the crash the `query_string` fuzz target found (#207).
    ///
    /// The tokeniser walks bytes and slices `&q[start..i]` as a `&str`, and it
    /// used to break on `is_whitespace()` — which is true for Latin-1 NBSP
    /// (0xA0). In valid UTF-8 that byte is only ever a *continuation* byte, so
    /// `_٠` (U+0660, encoded D9 A0) stopped the scan between the two bytes and
    /// the slice panicked on a character boundary. `query_string` is reachable
    /// unauthenticated from a request body and from `?q=`, and the release
    /// profile sets `panic = "abort"` — so this was the process, not a 400.
    ///
    /// Before the fix these abort the test process rather than failing.
    #[test]
    fn a_non_ascii_query_string_is_parsed_or_refused_but_never_panics() {
        // The character libFuzzer landed on, plus other multi-byte widths and
        // the two bytes `is_whitespace()` used to accept (0x85, 0xA0).
        for query in [
            "?:\"i(`:\"||+(l0O)_\u{660}\u{556}_ti(?:\"kk:))",
            "_\u{660}",
            "\u{660}",
            "a\u{660}b c",
            "field:\u{660}",
            "field:>\u{660}",
            "field:[\u{660} TO \u{661}]",
            "\u{4e2d}\u{6587} AND \u{e9}t\u{e9}",
            "caf\u{e9}\u{85}bar",
            "caf\u{e9}\u{a0}bar",
            "\u{1f600}",
        ] {
            for body in [
                json!({ "query_string": { "query": query, "default_field": "body" } }),
                json!({ "query_string": { "query": query } }),
                json!({ "simple_query_string": { "query": query } }),
            ] {
                // Parsing may fail. It may not take the process with it.
                let _ = parse_query(&body);
            }
        }

        // ASCII query strings still parse to the same shapes.
        let node = q(json!({
            "query_string": { "query": "title:quick AND body:fox", "default_field": "body" }
        }));
        assert!(
            matches!(node, QueryNode::Bool { .. }),
            "an ordinary fielded query_string must still lower to a bool: {node:?}"
        );
    }

    // ── Capability manifest (issue #211) ─────────────────────────────────────

    /// Names in `parse_query`'s dispatch table, read out of this file's own
    /// source at compile time.
    ///
    /// A pattern line is one whose text before `=>` is nothing but quoted
    /// string literals, `|` and whitespace — which is true of every match arm
    /// head and of no arm body, so no marker comments are needed and nothing
    /// has to be kept in sync by hand. The scan is bounded by the `match` head
    /// and the catch-all arm that closes it.
    fn dispatch_table_names() -> Vec<String> {
        const SRC: &str = include_str!("parser.rs");
        const START: &str = "match query_type.as_str() {";
        const END: &str = "unknown => unknown_type(unknown),";

        let start = SRC.find(START).expect("parse_query dispatch head moved") + START.len();
        let end = SRC[start..]
            .find(END)
            .expect("parse_query catch-all arm moved")
            + start;

        let mut names = Vec::new();
        for line in SRC[start..end].lines() {
            let code = line.split("//").next().unwrap_or("");
            let head = code.split("=>").next().unwrap_or("");
            if !head.contains('"') {
                continue;
            }
            // Everything that is not a string literal must be `|`/whitespace,
            // otherwise this is an arm body that merely mentions a literal.
            let mut literals = Vec::new();
            let mut rest = String::new();
            let mut in_str = false;
            let mut current = String::new();
            for ch in head.chars() {
                match (ch, in_str) {
                    ('"', false) => in_str = true,
                    ('"', true) => {
                        in_str = false;
                        literals.push(std::mem::take(&mut current));
                    }
                    (c, true) => current.push(c),
                    (c, false) => rest.push(c),
                }
            }
            if in_str || rest.chars().any(|c| c != '|' && !c.is_whitespace()) {
                continue;
            }
            names.extend(literals);
        }
        names
    }

    /// The drift guard. `SUPPORTED_QUERY_TYPES` + `REJECTED_QUERY_TYPES` must
    /// be exactly the dispatch table — no more, no less.
    ///
    /// Without this, adding a `parse_query` arm leaves every published list
    /// silently short (the pipeline-aggregation half of issue #211) and
    /// deleting one leaves them advertising a query that 400s.
    #[test]
    fn dispatch_table_matches_capability_manifest() {
        use std::collections::BTreeSet;

        let dispatched: BTreeSet<String> = dispatch_table_names().into_iter().collect();
        assert!(
            dispatched.len() > 40,
            "scraper found only {} arms — the dispatch table shape changed and the \
             scan is silently under-reading it",
            dispatched.len()
        );

        let supported: BTreeSet<String> = SUPPORTED_QUERY_TYPES
            .iter()
            .map(|s| s.to_string())
            .collect();
        let rejected: BTreeSet<String> =
            REJECTED_QUERY_TYPES.iter().map(|s| s.to_string()).collect();
        assert_eq!(
            supported.len(),
            SUPPORTED_QUERY_TYPES.len(),
            "SUPPORTED_QUERY_TYPES contains duplicates"
        );
        assert!(
            supported.is_disjoint(&rejected),
            "a query type cannot be both supported and rejected: {:?}",
            supported.intersection(&rejected).collect::<Vec<_>>()
        );

        let manifest: BTreeSet<String> = supported.union(&rejected).cloned().collect();
        let missing: Vec<_> = dispatched.difference(&manifest).collect();
        let extra: Vec<_> = manifest.difference(&dispatched).collect();
        assert!(
            missing.is_empty() && extra.is_empty(),
            "capability manifest has drifted from parse_query's dispatch table.\n  \
             dispatched but not in the manifest: {missing:?}\n  \
             in the manifest but not dispatched: {extra:?}\n  \
             Fix SUPPORTED_QUERY_TYPES / REJECTED_QUERY_TYPES in this file; the \
             docs are checked against them by xerj-engine/tests/docs_capability_lists.rs."
        );
    }

    /// Behavioural half: the manifest's two halves must actually behave the
    /// way they are labelled — in **both** directions. A supported type must
    /// neither answer `unknown query type` nor refuse with a `not supported`
    /// message, and a rejected type must refuse with exactly that message.
    /// Checking only the first of those let a recognised-and-refused type be
    /// relabelled supported with the whole manifest suite green.
    #[test]
    fn manifest_labels_match_observed_behaviour() {
        // `{ "<type>": {} }` — the minimal body that reaches the dispatch arm.
        // Most arms then reject it for missing parameters; what matters here is
        // only whether the *type* was recognised.
        fn bare(name: &str) -> Value {
            let mut obj = serde_json::Map::new();
            obj.insert(name.to_string(), json!({}));
            Value::Object(obj)
        }

        for name in SUPPORTED_QUERY_TYPES {
            let err = parse_query(&bare(name)).err();
            if let Some(QueryError::Parse(ParseError::UnknownQueryType(t))) = &err {
                panic!(
                    "`{name}` is listed as supported but parse_query rejects it as unknown: {t}"
                );
            }
            // The unknown-query-type check alone does not prove the *supported*
            // label: a type that is recognised and then refused with a 400 —
            // exactly what `has_child` does — never produces
            // `UnknownQueryType`, so moving it into SUPPORTED_QUERY_TYPES used
            // to pass here and then oblige the docs guard to publish it as a
            // capability. That is the #211 defect in the direction this test
            // exists to catch, so the refusal wording is checked too: the
            // phrase REJECTED_QUERY_TYPES is required to carry is the phrase
            // SUPPORTED_QUERY_TYPES is forbidden to carry.
            if let Some(e) = &err {
                let msg = e.to_string();
                assert!(
                    !msg.contains("not supported"),
                    "`{name}` is listed as supported but refuses with a not-supported \
                     message: {msg}\n  A recognised-and-refused type belongs in \
                     REJECTED_QUERY_TYPES, or the docs will advertise a query that 400s."
                );
            }
        }
        for name in REJECTED_QUERY_TYPES {
            let err = parse_query(&bare(name))
                .err()
                .unwrap_or_else(|| panic!("`{name}` is listed as rejected but parsed cleanly"));
            assert!(
                err.to_string().contains("not supported"),
                "`{name}` must refuse with an explanatory message, got: {err}"
            );
        }
    }

    // ── #1751: simple_query_string standalone and infix operators ──────────────

    #[test]
    fn simple_query_string_honors_operators_grouping_and_phrases() {
        // `fox | bear` under `default_operator: and` must be OR (should clauses).
        let node = q(json!({
            "simple_query_string": {
                "query": "fox | bear",
                "fields": ["title"],
                "default_operator": "and"
            }
        }));
        match node {
            QueryNode::Bool {
                should,
                must,
                minimum_should_match,
                ..
            } => {
                assert!(
                    must.is_empty(),
                    "must be empty under OR conjunction: {must:?}"
                );
                assert_eq!(should.len(), 2);
                assert_eq!(minimum_should_match, Some(MinShouldMatch::Fixed(1)));
            }
            other => panic!("expected Bool, got {other:?}"),
        }

        // `fox + lazy` under default operator must be AND (must clauses).
        let node = q(json!({
            "simple_query_string": {
                "query": "fox + lazy",
                "fields": ["title"]
            }
        }));
        match node {
            QueryNode::Bool { must, should, .. } => {
                assert_eq!(must.len(), 2, "both terms must be required: {must:?}");
                assert!(should.is_empty());
            }
            other => panic!("expected Bool, got {other:?}"),
        }

        // `"quick brown" | bear` under `default_operator: and` must produce MatchPhrase and Match in should.
        let node = q(json!({
            "simple_query_string": {
                "query": "\"quick brown\" | bear",
                "fields": ["title"],
                "default_operator": "and"
            }
        }));
        match node {
            QueryNode::Bool { should, must, .. } => {
                assert!(must.is_empty());
                assert_eq!(should.len(), 2);
                assert!(
                    matches!(&should[0], QueryNode::MatchPhrase { ref query, .. } if query == "quick brown")
                );
                assert!(
                    matches!(&should[1], QueryNode::Match { ref query, .. } if query == "bear")
                );
            }
            other => panic!("expected Bool, got {other:?}"),
        }

        // `(fox | bear) + brown` under `default_operator: and` must group (fox | bear) and require brown.
        let node = q(json!({
            "simple_query_string": {
                "query": "(fox | bear) + brown",
                "fields": ["title"],
                "default_operator": "and"
            }
        }));
        match node {
            QueryNode::Bool { must, .. } => {
                assert_eq!(must.len(), 2);
                assert!(
                    matches!(&must[0], QueryNode::Bool { ref should, .. } if should.len() == 2)
                );
                assert!(matches!(&must[1], QueryNode::Match { ref query, .. } if query == "brown"));
            }
            other => panic!("expected Bool, got {other:?}"),
        }

        // Negation with `-`
        let node = q(json!({
            "simple_query_string": {
                "query": "+fox -dog",
                "fields": ["title"]
            }
        }));
        match node {
            QueryNode::Bool { must, must_not, .. } => {
                assert_eq!(must.len(), 1);
                assert_eq!(must_not.len(), 1);
            }
            other => panic!("expected Bool, got {other:?}"),
        }

        // Resilient to trailing/standalone operators and unclosed quotes/parens
        let _ = q(json!({ "simple_query_string": { "query": "fox |" } }));
        let _ = q(json!({ "simple_query_string": { "query": "(fox | bear" } }));
        let _ = q(json!({ "simple_query_string": { "query": "\"unclosed phrase" } }));
        let _ = q(json!({ "simple_query_string": { "query": "++ -- ||" } }));
    }
}