Skip to main content

quarb_sql/
export.rs

1//! The reverse direction: Quarb → SQL.
2//!
3//! Walks the query's *reflection arbor* — the locked vocabulary is
4//! the stable surface for query-rewriting tooling — and emits an
5//! equivalent `SELECT` statement, refusing what the SQL query core
6//! cannot express. Fragments and pure macros expand before
7//! reflection, so they translate for free.
8//!
9//! The translatable subset mirrors the importer: `/table/*`
10//! branches with predicates (→ `WHERE`), witness joins (`<=>` with
11//! `$*1` equality → `JOIN ... ON`, remaining conditions → `WHERE`,
12//! `$*k` select fields qualified), `rec(...)` select lists,
13//! whole-table and grouped aggregates (`GROUP BY`, a filter after
14//! the reduction → `HAVING`), `sort_by`/`reverse`/`top` →
15//! `ORDER BY`/`LIMIT`, `@| [..n]` → `LIMIT`, and single-column
16//! `unique` → `DISTINCT`.
17//!
18//! Deliberately refused: `-->` resolution chains — the foreign-key
19//! targets live in the *schema*, not the query text, so a chain
20//! cannot be compiled to a join without a database at hand; spell
21//! the join explicitly with `<=>` to export it. Also refused:
22//! registers beyond the grouped-aggregate pattern, windows,
23//! captures, and regex matching (`LIKE` dialects disagree).
24//!
25//! Notes carry the standing divergences: truthiness (`[::c]` →
26//! `IS NOT NULL`, but Quarb also treats `0` and `''` as falsy),
27//! `*=` → `LIKE` case-folding dialects, and join cardinality
28//! (Quarb's existential binding never multiplies rows; SQL `JOIN`
29//! does when several left rows match).
30
31use crate::{SqlError, Translation};
32use quarb::reflect::QueryArbor;
33use quarb::{AstAdapter, NodeId, Value};
34
35/// Translate a Quarb query to a SQL `SELECT` statement.
36pub fn export(quarb: &str) -> Result<Translation, SqlError> {
37    refuse_marker(quarb)?;
38    let arbor =
39        QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
40    refuse_groups(&arbor)?;
41    let mut ex = Exporter {
42        arbor,
43        notes: Vec::new(),
44        strict: false,
45        dialect: None,
46        from_table: String::new(),
47        join_on_cols: Vec::new(),
48        join_table: None,
49        join_every: false,
50        column_types: ColumnTypes::default(),
51        from_sql: String::new(),
52        join_sql: None,
53        in_on: false,
54        aggregate: false,
55        keyed_hops: false,
56        from_marks: Vec::new(),
57        join_marks: Vec::new(),
58    };
59    let query = ex.query()?;
60    Ok(Translation {
61        query,
62        notes: ex.notes,
63    })
64}
65
66/// The exporter rewrites `__LEFT__` (the join's left table) and
67/// `__AGG__` (the HAVING aggregate) as internal placeholders.
68/// Query text containing either marker would be rewritten inside
69/// its own string literals — and could spoof the emitted SQL — so
70/// such queries stay on the scan path.
71fn refuse_marker(quarb: &str) -> Result<(), SqlError> {
72    for marker in ["__LEFT__", "__AGG__"] {
73        if quarb.contains(marker) {
74            return Err(SqlError::Unsupported(format!(
75                "query text contains the reserved marker \"{marker}\""
76            )));
77        }
78    }
79    Ok(())
80}
81
82/// A pushdown plan: SQL whose execution is provably identical to
83/// the Quarb query's — plus the table whose primary key must order
84/// the rows (`None` for a single aggregate row, where order is
85/// moot). The driver appends the `ORDER BY`, since the key lives in
86/// its catalog.
87pub struct Pushdown {
88    pub sql: String,
89    pub order_table: Option<String>,
90    /// Present when the plan contains a witness JOIN: the joined
91    /// table and the columns its ON equalities bind on it
92    /// (collected structurally from the arbor, so query text
93    /// cannot spoof them).
94    /// The plan is only sound if those columns form a unique key
95    /// of the joined table — each FROM row must find at most one
96    /// witness, else SQL multiplies rows where Quarb's existential
97    /// binding does not. The *driver* must verify against its
98    /// catalog before executing, and fall back to the scan if it
99    /// cannot.
100    pub join_left: Option<(String, Vec<String>)>,
101    /// Present when the plan is an every-witness JOIN (`<=>*`,
102    /// ruling 2026-11-11): the joined table. Such a JOIN is what the
103    /// query asks, so it carries no uniqueness obligation
104    /// (`join_left` is absent); its obligation is the ORDER: the
105    /// rows of one driver stand in the joined table's own order,
106    /// after the driver's (`order_table`'s key, then this table's).
107    /// A driver that cannot order by both must decline the plan.
108    pub order_then: Option<String>,
109    /// What the plan takes for granted about column types. Quarb
110    /// compares by value (a numeric-looking text and a number meet
111    /// as numbers, a number and other text never meet); SQL
112    /// compares by the column's type, and the loosely typed engines
113    /// (SQLite, MySQL) coerce by rules of their own. The plan is
114    /// the scan's only where the columns it compares with a number
115    /// are numeric-typed and those it compares with text are not:
116    /// the caller asks its catalog and scans when one is otherwise.
117    /// (A strictly typed engine rejects the mismatch itself, which
118    /// sends the caller to the scan as well.)
119    pub column_types: ColumnTypes,
120    /// The tables the plan reads (the FROM table, then a joined one).
121    pub tables: Vec<String>,
122}
123
124/// The column types a pushed plan assumes (see
125/// [`Pushdown::column_types`]).
126#[derive(Clone, Debug, Default, PartialEq, Eq)]
127pub struct ColumnTypes {
128    /// Columns compared with a numeric literal.
129    pub numeric: Vec<String>,
130    /// Columns compared with a text literal.
131    pub text: Vec<String>,
132    /// Columns the plan extracts a JSON path from on the strength
133    /// of the column's declaration alone (the hop carried no
134    /// `<json>`): the pushed `json_extract` is the scan's only where
135    /// the catalog declares the column json, since the scan grafts
136    /// a leaf only as declared (spec: Grafting).
137    pub json: Vec<String>,
138}
139
140impl ColumnTypes {
141    pub fn is_empty(&self) -> bool {
142        self.numeric.is_empty() && self.text.is_empty() && self.json.is_empty()
143    }
144
145    /// The assumptions a catalog does not bear out: the columns
146    /// compared with a number that are not numeric-typed, and those
147    /// compared with text that are. `catalog` lists every column of
148    /// the tables read, with whether its type is numeric and
149    /// whether it is declared json; names meet without regard to
150    /// case. A column the catalog does not list is unknown, and
151    /// counts as unmet.
152    pub fn unmet(&self, catalog: &[(String, bool, bool)]) -> Vec<String> {
153        let met = |column: &str, pick: fn(&(String, bool, bool)) -> bool, want: bool| {
154            let mut found = catalog
155                .iter()
156                .filter(|(name, ..)| name.eq_ignore_ascii_case(column))
157                .peekable();
158            found.peek().is_some() && found.all(|entry| pick(entry) == want)
159        };
160        let numeric = |e: &(String, bool, bool)| e.1;
161        let json = |e: &(String, bool, bool)| e.2;
162        let mut out: Vec<String> = Vec::new();
163        for (columns, pick, want) in [
164            (
165                &self.numeric,
166                numeric as fn(&(String, bool, bool)) -> bool,
167                true,
168            ),
169            (&self.text, numeric, false),
170            (&self.json, json, true),
171        ] {
172            for c in columns {
173                if !met(c, pick, want) && !out.contains(c) {
174                    out.push(c.clone());
175                }
176            }
177        }
178        out
179    }
180}
181
182/// The target SQL dialect, for the one construct whose emitted
183/// SQL is not portable: a filter that navigates *into* a JSON
184/// column, which each engine extracts with its own operator.
185/// The rest of a pushdown is dialect-agnostic. A query with no
186/// JSON-column filter emits identical SQL regardless of dialect.
187#[derive(Clone, Copy, PartialEq, Eq, Debug)]
188pub enum Dialect {
189    Postgres,
190    MySql,
191    Sqlite,
192    Mssql,
193    Oracle,
194}
195
196/// Attempt the pushdown translation: `Some` only when every
197/// construct in the query is in the verified-safe set. Anything
198/// else — including everything `export` would merely annotate with
199/// a divergence note — returns `None`, and the caller scans.
200///
201/// `dialect` enables JSON-column-path pushdown for that engine
202/// (fixed-path string equality only); `None` keeps such filters
203/// on the client-side graft.
204pub fn pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Pushdown> {
205    pushdown_explained(quarb, dialect).ok()
206}
207
208/// [`pushdown`], keeping the refusal: the error names the first
209/// construct that kept the query on the scan path.
210pub fn pushdown_explained(quarb: &str, dialect: Option<Dialect>) -> Result<Pushdown, SqlError> {
211    refuse_marker(quarb)?;
212    let arbor =
213        QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
214    refuse_groups(&arbor)?;
215    let mut ex = Exporter {
216        arbor,
217        notes: Vec::new(),
218        strict: true,
219        dialect,
220        from_table: String::new(),
221        join_on_cols: Vec::new(),
222        join_table: None,
223        join_every: false,
224        column_types: ColumnTypes::default(),
225        from_sql: String::new(),
226        join_sql: None,
227        in_on: false,
228        aggregate: false,
229        keyed_hops: false,
230        from_marks: Vec::new(),
231        join_marks: Vec::new(),
232    };
233    let sql = ex.query()?;
234    let order_table = if ex.aggregate {
235        None
236    } else {
237        // Rows come back in the driver's document order — the FROM
238        // table's (driver-first correlation).
239        Some(ex.from_table.clone())
240    };
241    // an every-witness JOIN multiplies rows by design: no uniqueness
242    // to verify, the joined table's order to keep instead
243    let join_left = if ex.join_every {
244        None
245    } else {
246        ex.join_table.clone().map(|t| (t, ex.join_on_cols.clone()))
247    };
248    let order_then = if ex.join_every && !ex.aggregate {
249        ex.join_table.clone()
250    } else {
251        None
252    };
253    let mut tables = vec![ex.from_table.clone()];
254    tables.extend(ex.join_table.clone());
255    Ok(Pushdown {
256        sql,
257        order_table,
258        join_left,
259        order_then,
260        column_types: ex.column_types.clone(),
261        tables,
262    })
263}
264
265/// The dialect-specific SQL that extracts a JSON scalar at a
266/// fixed object path, unquoted to text. `path` holds plain
267/// object keys (identifier-safe, per `json_path`), so no
268/// per-dialect path-escaping is needed. Each engine's operator
269/// returns the value as text and yields NULL for an absent path
270/// or a non-scalar — matching the graft, which excludes those
271/// rows too.
272fn json_extract(dialect: Dialect, qual: Option<&str>, col: &str, path: &[String]) -> String {
273    let qcol = match qual {
274        Some(q) => format!("{q}.{col}"),
275        None => col.to_string(),
276    };
277    match dialect {
278        // `#>>` takes a text-array path and returns text; the
279        // `::jsonb` cast lets it work on json, jsonb, and
280        // text-holding-JSON columns alike (an invalid-JSON row
281        // errors, and the driver falls back to the scan).
282        Dialect::Postgres => format!("({qcol}::jsonb #>> '{{{}}}')", path.join(",")),
283        // JSON_UNQUOTE(JSON_EXTRACT(...)) is the `->>` shorthand
284        // spelled out — portable across MySQL and MariaDB, where
285        // the `->>` operator itself is not.
286        Dialect::MySql => {
287            format!("JSON_UNQUOTE(JSON_EXTRACT({qcol}, '$.{}'))", path.join("."))
288        }
289        Dialect::Sqlite => format!("json_extract({qcol}, '$.{}')", path.join(".")),
290        // JSON_VALUE returns a scalar as text (lax mode: NULL on a
291        // missing path or a non-scalar, no error).
292        Dialect::Mssql | Dialect::Oracle => format!("JSON_VALUE({qcol}, '$.{}')", path.join(".")),
293    }
294}
295
296/// Wrap a JSON-path condition in the dialect's validity guard,
297/// where a cheap one exists. SQLite and MySQL error the whole
298/// statement on one malformed-JSON row — which turned every
299/// pushdown over a dirty table into a silent fallback scan — and
300/// the graft excludes such rows anyway (no parse, no subtree), so
301/// the guard is observationally identical. SQL Server gets ISJSON;
302/// Oracle's JSON_VALUE is lax already; PostgreSQL has no guard
303/// short of the ::jsonb cast itself (an invalid row errors and the
304/// caller falls back to the scan).
305fn json_valid_guard(dialect: Dialect, qual: Option<&str>, col: &str, cond: String) -> String {
306    let qcol = match qual {
307        Some(q) => format!("{q}.{col}"),
308        None => col.to_string(),
309    };
310    match dialect {
311        Dialect::Sqlite => format!("(json_valid({qcol}) AND {cond})"),
312        Dialect::MySql => format!("(JSON_VALID({qcol}) AND {cond})"),
313        Dialect::Mssql => format!("(ISJSON({qcol}) = 1 AND {cond})"),
314        Dialect::Postgres | Dialect::Oracle => format!("({cond})"),
315    }
316}
317
318/// The dialect's JSON type probe at a fixed path — non-NULL iff
319/// the path exists. A JSON `null` value reports its type ('null'),
320/// so existence still sees it, matching the graft, where a
321/// null-valued key is a node. Only the dialects with a native
322/// probe participate.
323fn json_type_probe(
324    dialect: Dialect,
325    qual: Option<&str>,
326    col: &str,
327    path: &[String],
328) -> Option<String> {
329    let qcol = match qual {
330        Some(q) => format!("{q}.{col}"),
331        None => col.to_string(),
332    };
333    match dialect {
334        Dialect::Sqlite => Some(format!("json_type({qcol}, '$.{}')", path.join("."))),
335        Dialect::Postgres => Some(format!(
336            "jsonb_typeof({qcol}::jsonb #> '{{{}}}')",
337            path.join(",")
338        )),
339        Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
340    }
341}
342
343/// Flip a comparison for a swapped operand order (`lit OP path` →
344/// `path OP' lit`).
345fn flip_op(op: &str) -> String {
346    match op {
347        "<" => ">".into(),
348        "<=" => ">=".into(),
349        ">" => "<".into(),
350        ">=" => "<=".into(),
351        other => other.into(),
352    }
353}
354
355/// SQL keywords that must not appear as a bare identifier or `AS`
356/// alias — quoting them portably differs by dialect, so strict
357/// mode refuses and export mode quotes with double quotes plus a
358/// note.
359const SQL_KEYWORDS: &[&str] = &[
360    "all",
361    "and",
362    "as",
363    "asc",
364    "by",
365    "case",
366    "cross",
367    "desc",
368    "distinct",
369    "else",
370    "end",
371    "except",
372    "exists",
373    "from",
374    "group",
375    "having",
376    "in",
377    "index",
378    "inner",
379    "intersect",
380    "into",
381    "is",
382    "join",
383    "left",
384    "like",
385    "limit",
386    "not",
387    "null",
388    "offset",
389    "on",
390    "or",
391    "order",
392    "outer",
393    "right",
394    "select",
395    "set",
396    "table",
397    "then",
398    "union",
399    "unique",
400    "update",
401    "using",
402    "values",
403    "when",
404    "where",
405];
406
407/// A bare SQL identifier, portable across the target dialects: a
408/// letter or underscore, then letters, digits, and underscores,
409/// and not a reserved word.
410fn is_plain_ident(name: &str) -> bool {
411    !name.is_empty()
412        && name
413            .chars()
414            .next()
415            .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
416        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
417        && !SQL_KEYWORDS.contains(&name.to_ascii_lowercase().as_str())
418}
419
420/// The SELECT under construction.
421#[derive(Default)]
422struct Select {
423    select: Vec<String>,
424    distinct: bool,
425    from: String,
426    join: Option<(String, String)>, // (table, ON condition)
427    /// The join keeps every FROM row (`<=>?`, the outer
428    /// correlation): a LEFT JOIN.
429    join_outer: bool,
430    wheres: Vec<String>,
431    group_by: Option<String>,
432    having: Option<String>,
433    order_by: Option<(String, bool)>, // (expr, desc)
434    limit: Option<String>,
435}
436
437impl Select {
438    fn render(&self) -> String {
439        let mut out = String::from("SELECT ");
440        if self.distinct {
441            out.push_str("DISTINCT ");
442        }
443        if self.select.is_empty() {
444            out.push('*');
445        } else {
446            out.push_str(&self.select.join(", "));
447        }
448        out.push_str(&format!(" FROM {}", self.from));
449        if let Some((t, on)) = &self.join {
450            let kind = if self.join_outer { "LEFT JOIN" } else { "JOIN" };
451            out.push_str(&format!(" {kind} {t} ON {on}"));
452        }
453        if !self.wheres.is_empty() {
454            out.push_str(&format!(" WHERE {}", self.wheres.join(" AND ")));
455        }
456        if let Some(g) = &self.group_by {
457            out.push_str(&format!(" GROUP BY {g}"));
458        }
459        if let Some(h) = &self.having {
460            out.push_str(&format!(" HAVING {h}"));
461        }
462        if let Some((e, desc)) = &self.order_by {
463            out.push_str(&format!(" ORDER BY {e}"));
464            if *desc {
465                out.push_str(" DESC");
466            }
467        }
468        if let Some(n) = &self.limit {
469            out.push_str(&format!(" LIMIT {n}"));
470        }
471        out
472    }
473}
474
475/// A partial-pushdown plan: the leading row predicates as a WHERE
476/// clause for `table`'s fetch. The caller runs the *original* query
477/// against the filtered adapter — the engine re-applies the pushed
478/// predicates (a no-op on pre-filtered rows), so no rewriting.
479pub struct Partial {
480    pub table: String,
481    pub where_sql: String,
482    /// As [`Pushdown::column_types`]: the prefilter keeps every row
483    /// the scan would only where these assumptions hold.
484    pub column_types: ColumnTypes,
485}
486
487/// Attempt a partial pushdown: `Some` when the query's leading row
488/// predicates translate strictly and the rest of the query provably
489/// cannot observe the filtering. The gates, each with its reason:
490/// a single `/table/*` branch with no correlations (other shapes
491/// address other data); only the *leading* run of expression
492/// predicates pushes (a positional predicate before an expression
493/// one sees unfiltered rows on the scan path); the table's name
494/// appears exactly once among the query's steps (a second reach —
495/// `^`-anchored subcontexts, self-references — would see the
496/// filtered subset); no crosslink or resolution axes anywhere
497/// (backlinks and reverse resolution into the table would too);
498/// and no `:` / `:::` metadata anywhere (a filtered `:::n-rows`
499/// would lie).
500pub fn partial_pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Partial> {
501    partial_pushdown_explained(quarb, dialect).ok()
502}
503
504/// [`partial_pushdown`], keeping the refusal reason. `dialect`
505/// enables the JSON-column prefilters — the strict fixed-path
506/// string equality, plus the relaxed superset forms (numeric
507/// comparisons, existence) that are safe here and only here,
508/// because the caller re-runs the original query over the
509/// fetched subset.
510pub fn partial_pushdown_explained(
511    quarb: &str,
512    dialect: Option<Dialect>,
513) -> Result<Partial, SqlError> {
514    partial_pushdown_with(quarb, dialect, false)
515}
516
517/// [`partial_pushdown_explained`] for an adapter that reads hops by
518/// key and filters only the table's listing
519/// (`RelationalModel::with_filtered_listing`): crosslinks and
520/// resolutions no longer refuse the prefilter, since a hop into the
521/// filtered table reads its row unfiltered. What still refuses: a
522/// second navigation into the table, and a `<--` or `=>` scope that
523/// could list it.
524pub fn partial_pushdown_keyed(quarb: &str, dialect: Option<Dialect>) -> Result<Partial, SqlError> {
525    partial_pushdown_with(quarb, dialect, true)
526}
527
528fn partial_pushdown_with(
529    quarb: &str,
530    dialect: Option<Dialect>,
531    keyed_hops: bool,
532) -> Result<Partial, SqlError> {
533    refuse_marker(quarb)?;
534    let arbor =
535        QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
536    refuse_groups(&arbor)?;
537    let mut ex = Exporter {
538        arbor,
539        notes: Vec::new(),
540        strict: true,
541        dialect,
542        from_table: String::new(),
543        join_on_cols: Vec::new(),
544        join_table: None,
545        join_every: false,
546        column_types: ColumnTypes::default(),
547        from_sql: String::new(),
548        join_sql: None,
549        in_on: false,
550        aggregate: false,
551        keyed_hops,
552        from_marks: Vec::new(),
553        join_marks: Vec::new(),
554    };
555    ex.partial()
556}
557
558/// Refuse a query carrying path-pattern groups: neither the SQL
559/// translation nor the pushdown safe set covers them, and the shape
560/// checks below count only `step` children — an unguarded group
561/// would silently vanish from the translation. Refused queries fall
562/// back to the scan path, which evaluates groups correctly.
563fn refuse_groups(arbor: &QueryArbor) -> Result<(), SqlError> {
564    let mut stack = vec![arbor.root()];
565    while let Some(n) = stack.pop() {
566        if arbor.name(n).as_deref() == Some("group") {
567            return Err(SqlError::Unsupported(
568                "path patterns (groups and quantifiers)".into(),
569            ));
570        }
571        stack.extend(arbor.children(n));
572    }
573    Ok(())
574}
575
576struct Exporter {
577    arbor: QueryArbor,
578    notes: Vec<String>,
579    /// Pushdown mode: refuse every construct whose SQL semantics
580    /// are not provably identical to Quarb's (LIKE case folding,
581    /// truthiness, group/distinct/sort ordering).
582    strict: bool,
583    /// The target dialect for JSON-column-path pushdown; `None`
584    /// leaves such filters on the client-side graft.
585    dialect: Option<Dialect>,
586    from_table: String,
587    join_on_cols: Vec<String>,
588    join_table: Option<String>,
589    /// The correlation is `<=>*`: every witness, the SQL JOIN itself.
590    join_every: bool,
591    /// What the comparisons assume of column types (see
592    /// [`Pushdown::column_types`]).
593    column_types: ColumnTypes,
594    from_sql: String,
595    join_sql: Option<String>,
596    in_on: bool,
597    aggregate: bool,
598    /// The adapter reads hops by key (the pushed-down WHERE filters
599    /// the table's listing only), so crosslinks and resolutions are
600    /// safe beside the prefilter.
601    keyed_hops: bool,
602    /// The names the driver's rows are marked under (`/tracks/* .t`)
603    /// and the names the joined expression files its witness under
604    /// (`<=> /albums/*[…] .al`): `$$.t::col` is the FROM table's
605    /// column, `$$.al::col` the joined table's.
606    from_marks: Vec<String>,
607    join_marks: Vec<String>,
608}
609
610impl Exporter {
611    fn kids(&self, n: NodeId, kind: &str) -> Vec<NodeId> {
612        self.arbor
613            .children(n)
614            .into_iter()
615            .filter(|&c| self.arbor.name(c).as_deref() == Some(kind))
616            .collect()
617    }
618
619    fn kid(&self, n: NodeId, kind: &str) -> Option<NodeId> {
620        self.kids(n, kind).into_iter().next()
621    }
622
623    fn prop(&self, n: NodeId, key: &str) -> Option<Value> {
624        self.arbor.property(n, key)
625    }
626
627    fn prop_s(&self, n: NodeId, key: &str) -> String {
628        self.prop(n, key).map(|v| v.to_string()).unwrap_or_default()
629    }
630
631    fn kind(&self, n: NodeId) -> String {
632        self.arbor.name(n).unwrap_or_default()
633    }
634
635    /// Whether `n` is a bare `null` literal operand.
636    fn is_null_literal(&self, n: NodeId) -> bool {
637        self.kind(n) == "literal" && self.prop_s(n, "type") == "null"
638    }
639
640    /// The partial-pushdown analysis (see [`partial_pushdown`]).
641    fn partial(&mut self) -> Result<Partial, SqlError> {
642        let root = self.arbor.root();
643        let q = self
644            .kid(root, "query")
645            .ok_or_else(|| SqlError::Unsupported("empty query".into()))?;
646        // A correlation does not forbid the prefilter: the driver's
647        // own predicates restrict the driver's rows whatever the join
648        // then binds. What must not happen is the join (or anything
649        // else) reaching the filtered table a second time — a
650        // self-join would see only the filtered rows — and the
651        // whole-query gates below refuse exactly that: they walk the
652        // correlation entries too.
653        let branches = self.kids(q, "branch");
654        if branches.len() != 1 {
655            return Err(SqlError::Unsupported("a branch union".into()));
656        }
657        let (table, preds) = self.table_branch_lead(branches[0], self.keyed_hops)?;
658
659        // Whole-query gates.
660        let all = self.walk_all(root);
661        let mut table_mentions = 0;
662        for n in &all {
663            match self.kind(*n).as_str() {
664                "step" => {
665                    let axis = self.prop_s(*n, "axis");
666                    // A crosslink, a resolution or a value match may
667                    // land in (or search) the filtered table and would
668                    // see only its filtered rows: `=>` and the scoped
669                    // `<--` carry their scope as text, so the table
670                    // count below cannot see them.
671                    if matches!(axis.as_str(), "->" | "<-" | "--" | "-->" | "<--" | "=>") {
672                        // Where hops are read by key they are exact
673                        // beside the prefilter. A scope is a listing,
674                        // though: it is safe only when it plainly
675                        // lists another table (`/other/…`), and an
676                        // unscoped `=>` walks every table.
677                        let scope = self.prop_s(*n, "scope");
678                        let lists_other_table = scope
679                            .strip_prefix('/')
680                            .and_then(|rest| rest.split(['/', '[', '<']).next())
681                            .is_some_and(|first| {
682                                !first.is_empty()
683                                    && first != table
684                                    && first.chars().all(|c| c.is_alphanumeric() || c == '_')
685                            });
686                        let safe = self.keyed_hops
687                            && if scope.is_empty() {
688                                axis != "=>"
689                            } else {
690                                lists_other_table
691                            };
692                        if !safe {
693                            return Err(SqlError::Unsupported(
694                                "crosslink/resolution axes could reach \
695                                 the filtered table"
696                                    .into(),
697                            ));
698                        }
699                    }
700                    if self.prop_s(*n, "matcher") == table {
701                        table_mentions += 1;
702                    }
703                }
704                "projection" if self.prop_s(*n, "kind") != "property" => {
705                    return Err(SqlError::Unsupported(
706                        "metadata would observe the filtering \
707                         (:::n-rows, :index)"
708                            .into(),
709                    ));
710                }
711                _ => {}
712            }
713        }
714        if table_mentions != 1 {
715            return Err(SqlError::Unsupported(
716                "the table is reached more than once".into(),
717            ));
718        }
719
720        // The leading run of expression predicates. Strict
721        // translation first; a predicate the strict translator
722        // refuses tries the relaxed prefilter ladder — superset
723        // semantics: the fetched set may hold extra rows, because
724        // the caller re-runs the ORIGINAL query, which re-applies
725        // every predicate; it must never lose a matching row. An
726        // untranslatable predicate is skipped, not fatal — a
727        // shorter conjunction is still a superset filter. A
728        // positional predicate (index/range) ends the run:
729        // predicates after it filter a positionally-selected
730        // subsequence.
731        let mut conds = Vec::new();
732        for p in preds {
733            if self.prop_s(p, "kind") != "expr" {
734                break;
735            }
736            match self.predicate_cond(p, None) {
737                Ok(c) => conds.push(c),
738                Err(_) => {
739                    if let Some(c) = self.prefilter_cond(p) {
740                        conds.push(c);
741                    }
742                }
743            }
744        }
745        if conds.is_empty() {
746            return Err(SqlError::Unsupported(
747                "no leading expression predicates to push".into(),
748            ));
749        }
750        Ok(Partial {
751            table,
752            where_sql: conds.join(" AND "),
753            column_types: self.column_types.clone(),
754        })
755    }
756
757    /// The relaxed prefilter for one refused expression predicate:
758    /// the AND of whatever conjuncts translate, each a superset of
759    /// the rows its Quarb counterpart keeps. None when nothing
760    /// does — the predicate stays entirely on the engine.
761    fn prefilter_cond(&mut self, p: NodeId) -> Option<String> {
762        let parts: Vec<String> = self
763            .arbor
764            .children(p)
765            .into_iter()
766            .filter_map(|c| {
767                self.pred_expr(c, None)
768                    .ok()
769                    .or_else(|| self.prefilter_expr(c))
770            })
771            .collect();
772        if parts.is_empty() {
773            None
774        } else {
775            Some(parts.join(" AND "))
776        }
777    }
778
779    /// One conjunct's superset prefilter — fixed-path JSON shapes
780    /// only, per dialect. Every form here is proven to keep every
781    /// row the graft would match (extras are fine; the engine
782    /// re-checks). The proofs lean on three graft facts: absent
783    /// paths match no comparison; `value_eq`/`value_cmp` coerce
784    /// numeric-looking strings numerically; and Str-to-Str
785    /// ordering is bytewise.
786    fn prefilter_expr(&mut self, e: NodeId) -> Option<String> {
787        let dialect = self.dialect?;
788        match self.kind(e).as_str() {
789            // A bare truthy path: existence (with `::`, value
790            // truthiness — existence is its superset). The type
791            // probe sees JSON null too, as the graft does.
792            "path" => {
793                let (col, path) = self.json_path_loose(e)?;
794                self.note_json_column(e, &col);
795                let probe = json_type_probe(dialect, None, &col, &path)?;
796                Some(json_valid_guard(
797                    dialect,
798                    None,
799                    &col,
800                    format!("{probe} IS NOT NULL"),
801                ))
802            }
803            "compare" => {
804                let op = self.prop_s(e, "op");
805                let kids = self.arbor.children(e);
806                if kids.len() != 2 {
807                    return None;
808                }
809                for (pi, li) in [(0usize, 1usize), (1, 0)] {
810                    let Some((col, path)) = self.json_path(kids[pi]) else {
811                        continue;
812                    };
813                    if self.kind(kids[li]) != "literal" {
814                        continue;
815                    }
816                    let ty = self.prop_s(kids[li], "type");
817                    if ty == "null" {
818                        return None;
819                    }
820                    let raw = self
821                        .prop(kids[li], "value")
822                        .map(|v| v.to_string())
823                        .unwrap_or_default();
824                    let op = if pi == 0 { op.clone() } else { flip_op(&op) };
825                    self.note_json_column(kids[pi], &col);
826                    return self.json_prefilter(dialect, &col, &path, &op, &ty, &raw);
827                }
828                None
829            }
830            _ => None,
831        }
832    }
833
834    /// Build the dialect's superset prefilter for
835    /// `json_path OP literal`.
836    fn json_prefilter(
837        &self,
838        d: Dialect,
839        col: &str,
840        path: &[String],
841        op: &str,
842        lit_ty: &str,
843        raw: &str,
844    ) -> Option<String> {
845        if !matches!(op, "=" | "!=" | "<" | "<=" | ">" | ">=") {
846            return None;
847        }
848        // `!=` matches every present path whose value isn't the
849        // literal — including JSON null and cross-typed values —
850        // so its floor is existence.
851        if op == "!=" {
852            let probe = json_type_probe(d, None, col, path)?;
853            return Some(json_valid_guard(
854                d,
855                None,
856                col,
857                format!("{probe} IS NOT NULL"),
858            ));
859        }
860        let numeric_lit = raw.trim().parse::<f64>().is_ok_and(|f| f.is_finite())
861            && (lit_ty != "text" || !raw.trim().is_empty());
862        if numeric_lit {
863            let num: f64 = raw.trim().parse().ok()?;
864            // Past 2^53 the engines' exact integers and the
865            // graft's f64 part ways at the boundary.
866            if num.abs() >= 9_007_199_254_740_992.0 {
867                return None;
868            }
869            let lit = raw.trim();
870            match d {
871                // Typed extract: JSON numbers compare numerically
872                // (both sides parse the same source text to f64);
873                // string values escape through the type probe —
874                // the graft may coerce them, the server must not
875                // drop them.
876                Dialect::Sqlite => {
877                    let ex = json_extract(d, None, col, path);
878                    let ty = json_type_probe(d, None, col, path)?;
879                    Some(json_valid_guard(
880                        d,
881                        None,
882                        col,
883                        format!("({ex} {op} {lit} OR {ty} = 'text')"),
884                    ))
885                }
886                // float8 is the graft's f64; jsonb numbers print
887                // exactly, so the cast parses the same decimal.
888                // Strings escape; everything else can't match.
889                Dialect::Postgres => {
890                    let text = json_extract(d, None, col, path);
891                    let ty = json_type_probe(d, None, col, path)?;
892                    Some(format!(
893                        "(CASE WHEN {ty} = 'number' THEN ({text})::float8 {op} {lit} \
894                         WHEN {ty} = 'string' THEN true ELSE false END)"
895                    ))
896                }
897                Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
898            }
899        } else if lit_ty == "text" {
900            if raw.contains('\'') || raw.contains('\\') {
901                return None;
902            }
903            match d {
904                // Typed extract again: string values order bytewise
905                // on both sides; numbers and booleans sit below
906                // text in SQLite's cross-type order, so `<` keeps
907                // them (extras, re-checked) and `>` drops them
908                // (the graft refuses to order Str against them).
909                Dialect::Sqlite => {
910                    let ex = json_extract(d, None, col, path);
911                    Some(json_valid_guard(d, None, col, format!("{ex} {op} '{raw}'")))
912                }
913                // Text ordering elsewhere runs into collation; the
914                // engine keeps those.
915                _ => None,
916            }
917        } else {
918            None
919        }
920    }
921
922    /// [`json_path`], loosened for existence: the projection may
923    /// be absent (a bare structural path) as well as the bare
924    /// `::`.
925    /// Whether a JSON path under a column reads the column as JSON
926    /// on the strength of its declaration alone: the column hop
927    /// (the first step) carries no `<json>` trait. Such a column is
928    /// an assumption of the plan ([`ColumnTypes::json`]); with the
929    /// trait the graft is declared on the hop and holds on both
930    /// roads.
931    fn note_json_column(&mut self, o: NodeId, col: &str) {
932        let declared_on_hop = self.kids(o, "step").first().is_some_and(|s| {
933            self.kids(*s, "trait").iter().any(|t| {
934                matches!(self.prop(*t, "alts"), Some(Value::List(alts))
935                    if alts.iter().any(|a| matches!(a, Value::Str(x) if x == "json")))
936            })
937        });
938        if !declared_on_hop && !self.column_types.json.iter().any(|c| c == col) {
939            self.column_types.json.push(col.to_string());
940        }
941    }
942
943    fn json_path_loose(&self, o: NodeId) -> Option<(String, Vec<String>)> {
944        if self.json_path(o).is_some() {
945            return self.json_path(o);
946        }
947        if self.kind(o) != "path" || self.kid(o, "projection").is_some() {
948            return None;
949        }
950        let steps = self.kids(o, "step");
951        if steps.len() < 2 {
952            return None;
953        }
954        let mut names = Vec::with_capacity(steps.len());
955        for s in &steps {
956            if self.prop_s(*s, "axis") != "/"
957                || self.prop_s(*s, "matcher-kind") != "name"
958                || self.kid(*s, "predicate").is_some()
959            {
960                return None;
961            }
962            let name = self.prop_s(*s, "matcher");
963            let plain = !name.is_empty()
964                && name
965                    .chars()
966                    .next()
967                    .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
968                && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
969            if !plain {
970                return None;
971            }
972            names.push(name);
973        }
974        let col = names.remove(0);
975        Some((col, names))
976    }
977
978    fn walk_all(&self, n: NodeId) -> Vec<NodeId> {
979        let mut out = vec![n];
980        let mut i = 0;
981        while i < out.len() {
982            out.extend(self.arbor.children(out[i]));
983            i += 1;
984        }
985        out
986    }
987
988    fn query(&mut self) -> Result<String, SqlError> {
989        let root = self.arbor.root();
990        let q = self
991            .kid(root, "query")
992            .ok_or_else(|| SqlError::Unsupported("empty query".into()))?;
993        let mut sel = Select::default();
994
995        // Correlations: exactly one becomes the JOIN's left table.
996        let corrs = self.kids(q, "query");
997        let branches = self.kids(q, "branch");
998        if branches.len() != 1 {
999            return Err(SqlError::Unsupported(
1000                "a branch union (SQL has UNION, but result shapes differ; export one branch)"
1001                    .into(),
1002            ));
1003        }
1004
1005        if corrs.len() > 1 {
1006            return Err(SqlError::Unsupported(
1007                "more than one correlation context".into(),
1008            ));
1009        }
1010        if let Some(corr) = corrs.first() {
1011            // Driver-first: the query's own branch is the FROM
1012            // table (the driver); the correlation entry is the
1013            // joined table, whose `$$` equalities form the ON.
1014            let (ltable, lpreds) = self.table_branch(branches[0])?;
1015            let (rtable, rpreds) = self.table_branch(self.kids(*corr, "branch")[0])?;
1016            self.from_marks = self.row_marks(branches[0])?;
1017            self.join_marks = self.row_marks(self.kids(*corr, "branch")[0])?;
1018            // a joined expression with a pipeline of its own binds
1019            // what that pipeline leaves: not a row of its table
1020            if self.kid(*corr, "pipeline").is_some() {
1021                return Err(SqlError::Unsupported(
1022                    "a joined expression with a pipeline of its own".into(),
1023                ));
1024            }
1025            // The SQL renderings of the two table names (validated
1026            // or quoted); the raw names stay in the plan metadata,
1027            // which the driver matches against its catalog.
1028            let lsql = self.sql_ident(&ltable, "table name")?;
1029            let rsql = self.sql_ident(&rtable, "table name")?;
1030            self.from_sql = lsql.clone();
1031            self.join_sql = Some(rsql.clone());
1032            // The driver's own predicates are plain WHERE.
1033            let driver_conds: Vec<NodeId> = lpreds;
1034            // Split the joined expression's predicates: `$$`
1035            // equalities form the ON, the rest the WHERE.
1036            let mut on = Vec::new();
1037            let mut wheres = Vec::new();
1038            for p in rpreds {
1039                self.split_join_pred(p, &rsql, &mut on, &mut wheres)?;
1040            }
1041            // `<=>?` — the outer correlation keeps a driver row no
1042            // joined row admits, its witness null: a LEFT JOIN. The
1043            // joined expression's own predicates then select the
1044            // witness, so they belong to the ON; in a WHERE they
1045            // would discard the unmatched rows again.
1046            let outer = matches!(self.prop(*corr, "outer"), Some(Value::Bool(true)));
1047            if outer {
1048                on.append(&mut wheres);
1049            }
1050            sel.join_outer = outer;
1051            if on.is_empty() {
1052                return Err(SqlError::Unsupported(
1053                    "a correlation without a '$$' equality (no JOIN condition)".into(),
1054                ));
1055            }
1056            for p in driver_conds {
1057                let cond = self.predicate_cond(p, Some(&lsql.clone()))?;
1058                wheres.push(cond);
1059            }
1060            // `<=>*` — every witness: the JOIN as SQL means it, one
1061            // row per matching pair; the plain `<=>` binds one.
1062            self.join_every = matches!(self.prop(*corr, "every"), Some(Value::Bool(true)));
1063            if !self.join_every {
1064                self.notes.push(
1065                    "JOIN: Quarb's binding is existential (one row per FROM row, \
1066                     bound to its first witness); SQL multiplies rows when \
1067                     several joined rows match"
1068                        .to_string(),
1069                );
1070            }
1071            sel.from = lsql.clone();
1072            self.from_table = ltable;
1073            self.join_table = Some(rtable);
1074            sel.join = Some((rsql.clone(), on.join(" AND ")));
1075            sel.wheres = wheres;
1076            // A terminal projection on the driving branch is a
1077            // one-column select of the FROM table.
1078            if let Some(proj) = self.kid(branches[0], "projection") {
1079                let col = self.projection_col(proj)?;
1080                let col = self.sql_ident(&col, "column name")?;
1081                sel.select.push(format!("{lsql}.{col}"));
1082            }
1083            if self
1084                .kid(self.kids(*corr, "branch")[0], "projection")
1085                .is_some()
1086            {
1087                return Err(SqlError::Unsupported(
1088                    "a projection on the joined expression (project the witness \
1089                     in the pipeline: '$$1::col')"
1090                        .into(),
1091                ));
1092            }
1093            self.pipeline(q, &mut sel, Some((&lsql, &rsql)))?;
1094        } else {
1095            let (table, preds) = self.table_branch(branches[0])?;
1096            self.from_marks = self.row_marks(branches[0])?;
1097            sel.from = self.sql_ident(&table, "table name")?;
1098            self.from_table = table;
1099            for p in preds {
1100                let cond = self.predicate_cond(p, None)?;
1101                sel.wheres.push(cond);
1102            }
1103            // A terminal projection is a one-column select.
1104            if let Some(proj) = self.kid(branches[0], "projection") {
1105                let col = self.projection_col(proj)?;
1106                sel.select.push(self.sql_ident(&col, "column name")?);
1107            }
1108            self.pipeline(q, &mut sel, None)?;
1109        }
1110        Ok(sel.render())
1111    }
1112
1113    /// A `/table/*[preds]` branch: the table name and the row-step
1114    /// predicate nodes.
1115    fn table_branch(&mut self, b: NodeId) -> Result<(String, Vec<NodeId>), SqlError> {
1116        self.table_branch_lead(b, false)
1117    }
1118
1119    /// [`table_branch`]; with `more`, the branch may go on after
1120    /// `/table/*[…]` (a hop, a cell): the prefilter concerns its
1121    /// first two steps only, and the steps after them are held to
1122    /// the whole-query gates.
1123    fn table_branch_lead(
1124        &mut self,
1125        b: NodeId,
1126        more: bool,
1127    ) -> Result<(String, Vec<NodeId>), SqlError> {
1128        let steps = self.kids(b, "step");
1129        if steps.len() < 2 || (steps.len() > 2 && !more) {
1130            return Err(SqlError::Unsupported(
1131                "navigation beyond /table/* (SQL sees tables and rows)".into(),
1132            ));
1133        }
1134        let (t, rows) = (steps[0], steps[1]);
1135        if self.prop_s(t, "axis") != "/"
1136            || self.prop_s(t, "matcher-kind") != "name"
1137            || self.prop_s(rows, "axis") != "/"
1138            || self.prop_s(rows, "matcher-kind") != "any"
1139        {
1140            return Err(SqlError::Unsupported(
1141                "navigation beyond /table/* (SQL sees tables and rows)".into(),
1142            ));
1143        }
1144        if self.kid(t, "predicate").is_some() {
1145            return Err(SqlError::Unsupported("a predicate on the table hop".into()));
1146        }
1147        Ok((self.prop_s(t, "matcher"), self.kids(rows, "predicate")))
1148    }
1149
1150    /// The names a `/table/*` branch marks its rows under: the marks
1151    /// standing after the row step. A mark anywhere else names a
1152    /// node SQL has no row for (the table) and is not translated.
1153    fn row_marks(&self, b: NodeId) -> Result<Vec<String>, SqlError> {
1154        let kids = self.arbor.children(b);
1155        let rows = self.kids(b, "step").get(1).copied();
1156        let after = rows
1157            .and_then(|r| kids.iter().position(|k| *k == r))
1158            .unwrap_or(kids.len());
1159        let mut names = Vec::new();
1160        for (i, k) in kids.iter().enumerate() {
1161            if self.kind(*k) != "mark" {
1162                continue;
1163            }
1164            if i < after {
1165                return Err(SqlError::Unsupported(
1166                    "a mark before the rows (SQL sees tables and rows)".into(),
1167                ));
1168            }
1169            // (a mark with no name is read by position alone, and
1170            // a read by position is not translated)
1171            if let Some(Value::Str(n)) = self.prop(*k, "name") {
1172                names.push(n);
1173            }
1174        }
1175        Ok(names)
1176    }
1177
1178    /// A path operand read through the capsa's node side (`$$.al`,
1179    /// `$$.2`, `((@))`): the mark's name where the anchor is one
1180    /// mark by name, and whether it is any mark anchor at all.
1181    fn mark_anchor(&self, o: NodeId) -> (Option<String>, bool) {
1182        let named = match self.prop(o, "mark") {
1183            Some(Value::Str(n)) => Some(n),
1184            _ => None,
1185        };
1186        let any = named.is_some()
1187            || [
1188                "mark-index",
1189                "mark-top",
1190                "mark-back",
1191                "marks-all",
1192                "marks-name",
1193                "edge-end",
1194                "node-id",
1195            ]
1196            .iter()
1197            .any(|k| self.prop(o, k).is_some());
1198        (named, any)
1199    }
1200
1201    /// One row predicate as a WHERE condition (qualify columns with
1202    /// `qualifier` when joining).
1203    fn predicate_cond(&mut self, p: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1204        if self.prop_s(p, "kind") != "expr" {
1205            return Err(SqlError::Unsupported(
1206                "a positional predicate on rows (SQL rows are unordered; ORDER BY + LIMIT)".into(),
1207            ));
1208        }
1209        let parts: Vec<String> = self
1210            .arbor
1211            .children(p)
1212            .into_iter()
1213            .map(|c| self.pred_expr(c, qual))
1214            .collect::<Result<_, _>>()?;
1215        Ok(parts.join(" AND "))
1216    }
1217
1218    fn pred_expr(&mut self, e: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1219        match self.kind(e).as_str() {
1220            "and" | "or" => {
1221                let op = self.kind(e).to_uppercase();
1222                let kids: Vec<String> = self
1223                    .arbor
1224                    .children(e)
1225                    .into_iter()
1226                    .map(|c| self.pred_expr(c, qual))
1227                    .collect::<Result<_, _>>()?;
1228                Ok(format!("({})", kids.join(&format!(" {op} "))))
1229            }
1230            "not" => {
1231                // SQL's `NOT` propagates UNKNOWN: `NOT (x = 5)` is
1232                // UNKNOWN for a NULL `x` and drops the row, but Quarb's
1233                // negation keeps it (the inner `value_eq` is false, so
1234                // its negation is true). Not provably identical without
1235                // the schema — the pushdown paths refuse it and scan.
1236                if self.strict {
1237                    return Err(SqlError::Semantics(
1238                        "SQL NOT propagates UNKNOWN, dropping the NULL rows \
1239                         Quarb keeps"
1240                            .into(),
1241                    ));
1242                }
1243                let inner: Vec<String> = self
1244                    .arbor
1245                    .children(e)
1246                    .into_iter()
1247                    .map(|c| self.pred_expr(c, qual))
1248                    .collect::<Result<_, _>>()?;
1249                Ok(format!("NOT ({})", inner.join(" AND ")))
1250            }
1251            "parens" => {
1252                let inner: Vec<String> = self
1253                    .arbor
1254                    .children(e)
1255                    .into_iter()
1256                    .map(|c| self.pred_expr(c, qual))
1257                    .collect::<Result<_, _>>()?;
1258                Ok(format!("({})", inner.join(" AND ")))
1259            }
1260            "compare" => {
1261                let op = self.prop_s(e, "op");
1262                let kids = self.arbor.children(e);
1263                // A comparison against a bare `null` literal. Quarb's
1264                // `value_eq` treats NULL as an ordinary value
1265                // (`value_eq(NULL, NULL)` is true, `value_eq(NULL, x)`
1266                // false), so `= null` keeps exactly the NULL rows and
1267                // `!= null` the non-NULL rows. SQL's `= NULL` / `<>
1268                // NULL` are always UNKNOWN and drop every row; the
1269                // `IS [NOT] NULL` forms are provably identical (and
1270                // portable across every target dialect).
1271                if matches!(op.as_str(), "=" | "!=")
1272                    && (self.is_null_literal(kids[0]) || self.is_null_literal(kids[1]))
1273                {
1274                    let other = if self.is_null_literal(kids[0]) {
1275                        kids[1]
1276                    } else {
1277                        kids[0]
1278                    };
1279                    let col = self.operand(other, qual)?;
1280                    return Ok(if op == "=" {
1281                        format!("{col} IS NULL")
1282                    } else {
1283                        format!("{col} IS NOT NULL")
1284                    });
1285                }
1286                // JSON-column-path pushdown: `[/col/a/b:: = 'lit']`
1287                // navigates into a JSON column and compares a fixed
1288                // path to a string literal. Only this exact shape —
1289                // fixed object path, string equality, and a literal
1290                // that does NOT look numeric — is provably identical
1291                // to the client-side graft (each engine's scalar
1292                // extractor unquotes to text, and an absent path or
1293                // non-string value excludes the row on both sides,
1294                // matching Quarb's `value_eq` on non-numeric text).
1295                // Numeric casts, `!=`, wildcards, and deeper
1296                // predicates fall through to the ordinary operand
1297                // logic below, which refuses the navigation; the
1298                // partial-pushdown prefilter ladder picks those up
1299                // with superset semantics. Enabled only when a
1300                // dialect is set.
1301                if op == "="
1302                    && let Some(dialect) = self.dialect
1303                {
1304                    for (pi, li) in [(0usize, 1usize), (1, 0)] {
1305                        if self.is_text_literal(kids[li])
1306                            && let Some((col, path)) = self.json_path(kids[pi])
1307                        {
1308                            self.note_json_column(kids[pi], &col);
1309                            // Quarb's value_eq compares numeric-looking
1310                            // strings numerically — '150' matches the
1311                            // JSON number 150, and the string "150.0".
1312                            // No engine's text extractor coerces that
1313                            // way, so the pushed compare would drop
1314                            // rows the graft keeps. Refuse; the
1315                            // prefilter ladder handles it as a
1316                            // superset.
1317                            let raw = self
1318                                .prop(kids[li], "value")
1319                                .map(|v| v.to_string())
1320                                .unwrap_or_default();
1321                            if raw.trim().parse::<f64>().is_ok() {
1322                                return Err(SqlError::Semantics(
1323                                    "a numeric-looking text literal against a \
1324                                     JSON path compares numerically in Quarb \
1325                                     (value coercion); no SQL extractor \
1326                                     matches that"
1327                                        .into(),
1328                                ));
1329                            }
1330                            let lit = self.operand(kids[li], qual)?;
1331                            let extract = json_extract(dialect, qual, &col, &path);
1332                            return Ok(json_valid_guard(
1333                                dialect,
1334                                qual,
1335                                &col,
1336                                format!("{extract} = {lit}"),
1337                            ));
1338                        }
1339                    }
1340                }
1341                // Any other JSON-path comparison: name the real
1342                // reason, not the generic flat-rows refusal — only
1343                // fixed-path string equality is provably identical
1344                // (Quarb coerces numeric-looking values; no
1345                // engine's extractor matches that). The partial
1346                // prefilter ladder covers these shapes.
1347                if self.dialect.is_some() {
1348                    for side in [kids[0], kids[1]] {
1349                        if self.json_path(side).is_some() || self.json_path_loose(side).is_some() {
1350                            return Err(SqlError::Semantics(
1351                                "a JSON-path comparison pushes whole only as \
1352                                 fixed-path string equality (Quarb coerces \
1353                                 numeric-looking values; no extractor matches \
1354                                 that); this shape rides the partial prefilter"
1355                                    .into(),
1356                            ));
1357                        }
1358                    }
1359                }
1360                // Quarb compares by value; SQL by the column's type.
1361                // A column against a numeric literal is the scan's
1362                // comparison only on a numeric-typed column, and
1363                // against a text literal only on a column that is
1364                // not (MySQL reads `n = 'abc'` as `n = 0`): the
1365                // catalog decides, so both are recorded for the
1366                // caller. A numeric-looking TEXT literal meets
1367                // numbers as a number in Quarb and compares as text
1368                // in SQL, on every engine, so it does not push.
1369                if self.strict {
1370                    for (ci, li) in [(0usize, 1usize), (1, 0)] {
1371                        let Some(column) = self.column_operand(kids[ci]) else {
1372                            continue;
1373                        };
1374                        if self.kind(kids[li]) != "literal" {
1375                            continue;
1376                        }
1377                        let numeric = self
1378                            .prop(kids[li], "value")
1379                            .is_some_and(|v| Value::Str(v.to_string()).numeric_reading().is_some());
1380                        let list = match (self.prop_s(kids[li], "type").as_str(), numeric) {
1381                            ("null", _) => continue,
1382                            ("text", true) => {
1383                                return Err(SqlError::Semantics(
1384                                    "a numeric-looking text literal compares \
1385                                     numerically in Quarb (value coercion); SQL \
1386                                     compares it as text"
1387                                        .into(),
1388                                ));
1389                            }
1390                            ("text", false) => &mut self.column_types.text,
1391                            (_, true) => &mut self.column_types.numeric,
1392                            (_, false) => continue,
1393                        };
1394                        if !list.contains(&column) {
1395                            list.push(column);
1396                        }
1397                    }
1398                }
1399                let l = self.operand(kids[0], qual)?;
1400                // Ruling #33: a pattern literal on `=` pushes as
1401                // LIKE — a `%` per star, each literal segment
1402                // escaped, in order. Anchoring matches exactly:
1403                // LIKE anchors both ends, a flanking star lifts
1404                // one. The case-folding caveat is `*=`'s; `!=`
1405                // with a pattern rides the scan (NOT LIKE drops
1406                // the NULL rows Quarb keeps).
1407                if self.kind(kids[1]) == "pattern" {
1408                    if op.as_str() != "=" {
1409                        return Err(SqlError::Unsupported(format!(
1410                            "a pattern literal on '{op}' (only '=' pushes)"
1411                        )));
1412                    }
1413                    // PostgreSQL's LIKE is case-sensitive under its
1414                    // deterministic collations — provably what the
1415                    // pattern test does — so the strict push is
1416                    // sound there (and a prefix pattern is
1417                    // index-sargable server-side). Everywhere else
1418                    // case folding is ambient state (SQLite pragma,
1419                    // MySQL/MSSQL collation), so strict refuses.
1420                    if self.strict && self.dialect != Some(Dialect::Postgres) {
1421                        return Err(SqlError::Semantics(
1422                            "LIKE case folding differs per engine \
1423                             (provably case-sensitive only on PostgreSQL)"
1424                                .into(),
1425                        ));
1426                    }
1427                    if !self.strict {
1428                        self.notes.push(
1429                            "pattern → LIKE: Quarb's pattern test is \
1430                             case-sensitive; LIKE folds case on \
1431                             SQLite/MySQL but not PostgreSQL"
1432                                .to_string(),
1433                        );
1434                    }
1435                    let mut like = String::new();
1436                    for kid in self.arbor.children(kids[1]) {
1437                        match self.kind(kid).as_str() {
1438                            "star" => like.push('%'),
1439                            _ => {
1440                                let raw = self
1441                                    .prop(kid, "value")
1442                                    .map(|v| v.to_string())
1443                                    .unwrap_or_default();
1444                                like.push_str(
1445                                    &raw.replace('\\', "\\\\")
1446                                        .replace('%', "\\%")
1447                                        .replace('_', "\\_")
1448                                        .replace('\'', "''"),
1449                                );
1450                            }
1451                        }
1452                    }
1453                    return Ok(format!("{l} LIKE '{like}' ESCAPE '\\'"));
1454                }
1455                let r = self.operand(kids[1], qual)?;
1456                Ok(match op.as_str() {
1457                    "=" => format!("{l} = {r}"),
1458                    "!=" => {
1459                        // Quarb keeps rows whose operand is NULL (its
1460                        // `value_eq` is false there, so `!=` is true);
1461                        // SQL's `<>` is UNKNOWN for a NULL operand and
1462                        // drops those rows. Not provably identical
1463                        // without the schema, so pushdown refuses it;
1464                        // the display translation keeps `<>` and notes
1465                        // the divergence.
1466                        if self.strict {
1467                            return Err(SqlError::Semantics(
1468                                "'!=' drops the NULL rows Quarb keeps \
1469                                 (SQL '<>' is UNKNOWN for NULL; use '!= null' \
1470                                 for IS NOT NULL)"
1471                                    .into(),
1472                            ));
1473                        }
1474                        self.notes.push(
1475                            "'!=' → '<>': Quarb keeps rows whose column is NULL; \
1476                             SQL's '<>' drops them (use '!= null' for IS NOT NULL)"
1477                                .to_string(),
1478                        );
1479                        format!("{l} <> {r}")
1480                    }
1481                    "<" | "<=" | ">" | ">=" => format!("{l} {op} {r}"),
1482                    "*=" => {
1483                        // The same PostgreSQL rung as the pattern
1484                        // literal above: LIKE is provably
1485                        // case-sensitive there, so `*=` pushes
1486                        // strict too.
1487                        if self.strict && self.dialect != Some(Dialect::Postgres) {
1488                            return Err(SqlError::Semantics(
1489                                "LIKE case folding differs per engine \
1490                                 (provably case-sensitive only on PostgreSQL)"
1491                                    .into(),
1492                            ));
1493                        }
1494                        // The pattern must be a text literal: a
1495                        // column or computed operand holds a value,
1496                        // not a pattern, and SQL LIKE cannot express
1497                        // "contains that value" portably.
1498                        if !self.is_text_literal(kids[1]) {
1499                            return Err(SqlError::Unsupported(
1500                                "'*=' with a non-literal pattern".into(),
1501                            ));
1502                        }
1503                        self.notes.push(
1504                            "*= → LIKE: Quarb's substring test is case-sensitive; LIKE \
1505                             folds case on SQLite/MySQL but not PostgreSQL"
1506                                .to_string(),
1507                        );
1508                        // Escape LIKE's metacharacters, then quote.
1509                        // The explicit ESCAPE makes '\' the escape
1510                        // everywhere — SQLite, MSSQL, and Oracle
1511                        // have no default escape character.
1512                        let raw = self
1513                            .prop(kids[1], "value")
1514                            .map(|v| v.to_string())
1515                            .unwrap_or_default();
1516                        let pat = raw
1517                            .replace('\\', "\\\\")
1518                            .replace('%', "\\%")
1519                            .replace('_', "\\_")
1520                            .replace('\'', "''");
1521                        format!("{l} LIKE '%{pat}%' ESCAPE '\\'")
1522                    }
1523                    "==" | "!==" | "=~" | "!~" => {
1524                        return Err(SqlError::Semantics(
1525                            "regex matching means a different REGEXP engine per \
1526                             backend; regexes run engine-side"
1527                                .into(),
1528                        ));
1529                    }
1530                    other => {
1531                        return Err(SqlError::Unsupported(format!("the '{other}' comparison")));
1532                    }
1533                })
1534            }
1535            // A bare truthy operand.
1536            _ => {
1537                if self.strict {
1538                    return Err(SqlError::Semantics(
1539                        "truthiness diverges (0 and '' are falsy in Quarb)".into(),
1540                    ));
1541                }
1542                self.notes.push(
1543                    "truthiness: '[::c]' exports as IS NOT NULL, but Quarb also treats \
1544                     0 and '' as falsy"
1545                        .to_string(),
1546                );
1547                Ok(format!("{} IS NOT NULL", self.operand(e, qual)?))
1548            }
1549        }
1550    }
1551
1552    fn operand(&mut self, o: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1553        match self.kind(o).as_str() {
1554            "literal" => {
1555                let v = self.prop(o, "value").unwrap_or(Value::Null);
1556                match self.prop_s(o, "type").as_str() {
1557                    "text" => {
1558                        let s = v.to_string();
1559                        // No single escaping is portable across the
1560                        // pushdown's target dialects: MySQL (default
1561                        // sql_mode) and BigQuery read `\` as an escape
1562                        // while SQLite/PostgreSQL/DuckDB take it
1563                        // literally, and BigQuery rejects the `''`
1564                        // quote-doubling the others require. A literal
1565                        // carrying either character cannot be pushed as
1566                        // provably identical SQL, so refuse it and let
1567                        // the caller scan. (The display translation
1568                        // keeps its best-effort `''`-doubling.)
1569                        if self.strict && (s.contains('\'') || s.contains('\\')) {
1570                            return Err(SqlError::Semantics(
1571                                "a text literal with a quote or backslash \
1572                                 has no escaping portable across SQL dialects"
1573                                    .into(),
1574                            ));
1575                        }
1576                        Ok(format!("'{}'", s.replace('\'', "''")))
1577                    }
1578                    "null" => Ok("NULL".to_string()),
1579                    _ => Ok(v.to_string()),
1580                }
1581            }
1582            "path" => {
1583                if self.kid(o, "step").is_some() {
1584                    // A step here is either navigation (refused) or
1585                    // a resolution chain (refused with the reason).
1586                    let s = self.kids(o, "step")[0];
1587                    if self.prop_s(s, "axis") == "-->" {
1588                        return Err(SqlError::Unsupported(
1589                            "a '-->' resolution chain: the foreign-key targets live in \
1590                             the schema, not the query — spell the join with '<=>' to \
1591                             export it"
1592                                .into(),
1593                        ));
1594                    }
1595                    return Err(SqlError::Unsupported(
1596                        "navigation inside a predicate (SQL rows are flat)".into(),
1597                    ));
1598                }
1599                let p = self
1600                    .kid(o, "projection")
1601                    .ok_or_else(|| SqlError::Unsupported("an empty path operand".into()))?;
1602                let col = self.projection_col(p)?;
1603                let col = self.sql_ident(&col, "column name")?;
1604                // a read through a mark: the row the mark names
1605                let (named, any) = self.mark_anchor(o);
1606                if any {
1607                    let Some(name) = named else {
1608                        return Err(SqlError::Unsupported(
1609                            "a mark read by position, or of several marks".into(),
1610                        ));
1611                    };
1612                    if self.join_marks.contains(&name) {
1613                        // `$$.al::col`: the witness, as `$$1::col`
1614                        if self.in_on {
1615                            return Err(SqlError::Unsupported(
1616                                "the joined expression's own mark inside its ON".into(),
1617                            ));
1618                        }
1619                        let Some(join) = self.join_sql.clone() else {
1620                            return Err(SqlError::Unsupported(
1621                                "a join mark outside a correlation join".into(),
1622                            ));
1623                        };
1624                        return Ok(format!("{join}.{col}"));
1625                    }
1626                    if self.from_marks.contains(&name) {
1627                        // `$$.t::col`: the driver's row, as `$$0::col`
1628                        // in the ON
1629                        return Ok(if self.join_sql.is_some() {
1630                            format!("{}.{col}", self.from_sql.clone())
1631                        } else {
1632                            match qual {
1633                                Some(q) => format!("{q}.{col}"),
1634                                None => col,
1635                            }
1636                        });
1637                    }
1638                    return Err(SqlError::Unsupported(format!(
1639                        "a read of the mark '.{name}' (not a row of the query's tables)"
1640                    )));
1641                }
1642                Ok(match qual {
1643                    Some(q) => format!("{q}.{col}"),
1644                    None => col,
1645                })
1646            }
1647            "context" => {
1648                // `$$1::col` — the joined expression's witness, in
1649                // pipeline position: the joined table's column.
1650                // Anything else is outside the verified-safe set.
1651                let p = self
1652                    .kid(o, "projection")
1653                    .ok_or_else(|| SqlError::Unsupported("a bare '$$N' reference".into()))?;
1654                let col = self.projection_col(p)?;
1655                let col = self.sql_ident(&col, "column name")?;
1656                if matches!(self.prop(o, "index"), Some(Value::Int(0))) {
1657                    // `$$0::col` — the driver, legal only inside the
1658                    // joined expression's ON bracket (the parser
1659                    // refuses it anywhere else).
1660                    if !self.in_on {
1661                        return Err(SqlError::Unsupported(
1662                            "a '$$0' reference outside the join's ON".into(),
1663                        ));
1664                    }
1665                    if self.kid(o, "step").is_some() {
1666                        return Err(SqlError::Unsupported(
1667                            "a '$$0' reference beyond a plain column ($$0::col)".into(),
1668                        ));
1669                    }
1670                    return Ok(format!("{}.{col}", self.from_sql.clone()));
1671                }
1672                if self.in_on {
1673                    return Err(SqlError::Unsupported(
1674                        "a '$$N' reference inside the ON (the driver is '$$0')".into(),
1675                    ));
1676                }
1677                let Some(join) = self.join_sql.clone() else {
1678                    return Err(SqlError::Unsupported(
1679                        "a '$$N' reference outside a correlation join".into(),
1680                    ));
1681                };
1682                match self.prop(o, "index") {
1683                    Some(Value::Int(1)) => Ok(format!("{join}.{col}")),
1684                    None => Err(SqlError::Unsupported("a bare '$$N' reference".into())),
1685                    Some(v) => Err(SqlError::Unsupported(format!(
1686                        "pushdown: $${v} beyond a two-branch correlation"
1687                    ))),
1688                }
1689            }
1690            "invoking" => {
1691                // `$$__::col` — the invoking position of an enclosing
1692                // query body, never the driver (that is `$$0`, a
1693                // context of index 0, since draft 153). SQL has no
1694                // enclosing body to read.
1695                Err(SqlError::Unsupported(
1696                    "a '$$__' reference (the driver inside the ON is '$$0')".into(),
1697                ))
1698            }
1699            "arith" => {
1700                let op = self.prop_s(o, "op");
1701                let kids = self.arbor.children(o);
1702                let l = self.operand(kids[0], qual)?;
1703                let r = self.operand(kids[1], qual)?;
1704                Ok(match op.as_str() {
1705                    "+" | "-" | "*" => format!("({l} {op} {r})"),
1706                    "div" => format!("({l} / {r})"),
1707                    "mod" => format!("({l} % {r})"),
1708                    other => return Err(SqlError::Unsupported(format!("'{other}' arithmetic"))),
1709                })
1710            }
1711            other => Err(SqlError::Unsupported(format!(
1712                "the '{other}' operand (registers, topics, and captures are Quarb-side state)"
1713            ))),
1714        }
1715    }
1716
1717    fn projection_col(&mut self, p: NodeId) -> Result<String, SqlError> {
1718        match self.prop_s(p, "kind").as_str() {
1719            "property" => match self.prop(p, "key") {
1720                Some(k) => Ok(k.to_string()),
1721                None => Err(SqlError::Unsupported(
1722                    "the bare '::' projection (name the column)".into(),
1723                )),
1724            },
1725            other => Err(SqlError::Unsupported(format!(
1726                "the {other} metadata projection"
1727            ))),
1728        }
1729    }
1730
1731    /// The column a plain column operand names (`::col`, `$*1::col`):
1732    /// a path without a step, or a context reference, projecting a
1733    /// named property.
1734    /// A numeric reducer (`sum`, `mean`, `min`, `max`) pushed over a
1735    /// column is the scan's only on a numeric-typed column: the
1736    /// scan lifts unit text (`'18 parasang'` under a declared unit)
1737    /// to quantities and orders texts as texts, where SQL sums a
1738    /// text column by its leading digits and orders it by
1739    /// collation. Recorded for the caller's catalog as a
1740    /// comparison's assumption is.
1741    fn assume_numeric(&mut self, column: Option<String>) {
1742        if !self.strict {
1743            return;
1744        }
1745        if let Some(c) = column
1746            && !self.column_types.numeric.contains(&c)
1747        {
1748            self.column_types.numeric.push(c);
1749        }
1750    }
1751
1752    fn column_operand(&self, o: NodeId) -> Option<String> {
1753        match self.kind(o).as_str() {
1754            "path" if self.kid(o, "step").is_none() => {}
1755            "context" => {}
1756            _ => return None,
1757        }
1758        let p = self.kid(o, "projection")?;
1759        if self.prop_s(p, "kind") != "property" {
1760            return None;
1761        }
1762        self.prop(p, "key").map(|k| k.to_string())
1763    }
1764
1765    /// Whether `o` is a text string literal (`'London'`).
1766    fn is_text_literal(&self, o: NodeId) -> bool {
1767        self.kind(o) == "literal" && self.prop_s(o, "type") == "text"
1768    }
1769
1770    /// If `o` is the one JSON-column-path shape pushdown handles —
1771    /// `/col/seg/seg…::`, a plain-navigation path (every hop `/`
1772    /// and a plain-identifier object key, no wildcards, no nested
1773    /// predicate), at least one segment past the column, ending in
1774    /// the bare `::` projection — return `(column, [json segments])`.
1775    /// Anything else is `None` (and falls back to the graft).
1776    fn json_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
1777        if self.kind(o) != "path" {
1778            return None;
1779        }
1780        let steps = self.kids(o, "step");
1781        if steps.len() < 2 {
1782            return None;
1783        }
1784        // The projection must be the bare `::` (default value of
1785        // the JSON leaf), not `::key` or a `:::`/`:` metadata form.
1786        let proj = self.kid(o, "projection")?;
1787        if self.prop_s(proj, "kind") != "property" || self.prop(proj, "key").is_some() {
1788            return None;
1789        }
1790        let mut names = Vec::with_capacity(steps.len());
1791        for s in &steps {
1792            if self.prop_s(*s, "axis") != "/"
1793                || self.prop_s(*s, "matcher-kind") != "name"
1794                || self.kid(*s, "predicate").is_some()
1795            {
1796                return None;
1797            }
1798            let name = self.prop_s(*s, "matcher");
1799            // Plain object keys only — no array indices, no
1800            // characters that would need per-dialect path escaping.
1801            let plain = !name.is_empty()
1802                && name
1803                    .chars()
1804                    .next()
1805                    .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
1806                && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
1807            if !plain {
1808                return None;
1809            }
1810            names.push(name);
1811        }
1812        let col = names.remove(0);
1813        Some((col, names))
1814    }
1815
1816    /// A safe `AS` alias: bare when it is a plain identifier and
1817    /// not an SQL keyword; otherwise strict mode refuses (quoting
1818    /// dialects disagree) and export mode double-quotes, noting it.
1819    fn alias(&mut self, name: &str) -> Result<String, SqlError> {
1820        if is_plain_ident(name) {
1821            return Ok(name.to_string());
1822        }
1823        if self.strict {
1824            return Err(SqlError::Unsupported(format!(
1825                "pushdown: field name {name:?} needs SQL quoting \
1826                 (dialects disagree); rename the field"
1827            )));
1828        }
1829        self.notes
1830            .push(format!("field name {name:?} double-quoted (ANSI)"));
1831        Ok(format!("\"{}\"", name.replace('"', "\"\"")))
1832    }
1833
1834    /// A table or column name rendered into SQL. Bare when it is a
1835    /// plain identifier; otherwise strict mode refuses — a name
1836    /// like `a OR b` would silently rewrite the emitted SQL's
1837    /// meaning, breaking the provably-identical guarantee (and a
1838    /// portable quoting does not exist) — and export mode
1839    /// double-quotes with a note.
1840    fn sql_ident(&mut self, name: &str, what: &str) -> Result<String, SqlError> {
1841        if is_plain_ident(name) {
1842            return Ok(name.to_string());
1843        }
1844        if self.strict {
1845            return Err(SqlError::Unsupported(format!(
1846                "pushdown: {what} {name:?} is not a plain SQL identifier"
1847            )));
1848        }
1849        self.notes
1850            .push(format!("{what} {name:?} double-quoted (ANSI)"));
1851        Ok(format!("\"{}\"", name.replace('"', "\"\"")))
1852    }
1853
1854    /// Split a joined-side predicate: `col = $*1::col2` equalities
1855    /// become the ON condition; everything else the WHERE.
1856    /// `ltable` and `rtable` are the tables' SQL renderings.
1857    fn split_join_pred(
1858        &mut self,
1859        p: NodeId,
1860        rtable: &str,
1861        on: &mut Vec<String>,
1862        wheres: &mut Vec<String>,
1863    ) -> Result<(), SqlError> {
1864        if self.prop_s(p, "kind") != "expr" {
1865            return Err(SqlError::Unsupported(
1866                "a positional predicate on the joined side".into(),
1867            ));
1868        }
1869        // Flatten top-level ANDs; each conjunct routes to ON or
1870        // WHERE.
1871        fn conjuncts(ex: &Exporter, e: NodeId, out: &mut Vec<NodeId>) {
1872            if ex.kind(e) == "and" {
1873                for c in ex.arbor.children(e) {
1874                    conjuncts(ex, c, out);
1875                }
1876            } else {
1877                out.push(e);
1878            }
1879        }
1880        let mut parts = Vec::new();
1881        for c in self.arbor.children(p) {
1882            conjuncts(self, c, &mut parts);
1883        }
1884        for e in parts {
1885            let uses_driver = self.subtree_has_driver(e);
1886            self.in_on = true;
1887            let cond = self.pred_expr(e, Some(rtable));
1888            self.in_on = false;
1889            let cond = cond?;
1890            if uses_driver && self.kind(e) == "compare" && self.prop_s(e, "op") == "=" {
1891                // Record which joined-table columns the ON binds —
1892                // the uniqueness obligation (see
1893                // Pushdown::join_left). Collected from the arbor's
1894                // bare-column operand nodes, never from the
1895                // rendered SQL text, so neither a literal nor an
1896                // unusual column name can corrupt the obligation.
1897                self.collect_join_cols(e)?;
1898                on.push(cond);
1899            } else {
1900                wheres.push(cond);
1901            }
1902        }
1903        Ok(())
1904    }
1905
1906    /// The joined-table columns the ON equality binds: every bare
1907    /// column operand (`::col`) in `e`'s subtree, appended to the
1908    /// join obligation with their raw (catalog) names.
1909    fn collect_join_cols(&mut self, e: NodeId) -> Result<(), SqlError> {
1910        // The `$$0` side is the driver — not part of the joined
1911        // table's obligation.
1912        if self.is_driver(e) {
1913            return Ok(());
1914        }
1915        if self.kind(e) == "path"
1916            && self.kid(e, "step").is_none()
1917            && let Some(p) = self.kid(e, "projection")
1918        {
1919            let col = self.projection_col(p)?;
1920            self.join_on_cols.push(col);
1921        }
1922        for c in self.arbor.children(e) {
1923            self.collect_join_cols(c)?;
1924        }
1925        Ok(())
1926    }
1927
1928    /// `$$0`: a context operand of index 0 (the driver), or a read
1929    /// of the driver's row through its mark (`$$.t::col`).
1930    fn is_driver(&self, n: NodeId) -> bool {
1931        (self.kind(n) == "context" && matches!(self.prop(n, "index"), Some(Value::Int(0))))
1932            || (self.kind(n) == "path"
1933                && matches!(self.mark_anchor(n).0, Some(name) if self.from_marks.contains(&name)))
1934    }
1935
1936    fn subtree_has_driver(&self, n: NodeId) -> bool {
1937        self.is_driver(n)
1938            || self
1939                .arbor
1940                .children(n)
1941                .into_iter()
1942                .any(|c| self.subtree_has_driver(c))
1943    }
1944
1945    /// Consume the pipeline into SELECT clauses.
1946    fn pipeline(
1947        &mut self,
1948        q: NodeId,
1949        sel: &mut Select,
1950        join: Option<(&str, &str)>,
1951    ) -> Result<(), SqlError> {
1952        let Some(pipe) = self.kid(q, "pipeline") else {
1953            return Ok(());
1954        };
1955        let commands: Vec<NodeId> = self.arbor.children(pipe);
1956        let mut i = 0;
1957        // A pending per-row value (`| ::col`) feeding an aggregate,
1958        // and the column it names where it is one.
1959        let mut pending_col: Option<String> = None;
1960        let mut pending_name: Option<String> = None;
1961        // After a grouped reduction: (key, agg_sql, alias).
1962        let mut grouped: Option<(String, String, String)> = None;
1963        // A pushed key awaiting its fold: (the regula's name, key_sql).
1964        let mut pushed_key: Option<(String, String)> = None;
1965
1966        while i < commands.len() {
1967            let s = commands[i];
1968            match self.kind(s).as_str() {
1969                "expr" => {
1970                    let kids = self.arbor.children(s);
1971                    pending_col = Some(self.operand(kids[0], join.map(|(l, _)| l))?);
1972                    pending_name = self.column_operand(kids[0]);
1973                }
1974                "cmd" => {
1975                    let name = self.prop_s(s, "name");
1976                    match name.as_str() {
1977                        "rec" | "record" => {
1978                            sel.select = self.record_fields(s, join)?;
1979                        }
1980                        // A reducing aggregate on the plain pipe:
1981                        // the grouped reduction.
1982                        "count" | "sum" | "mean" | "avg" | "min" | "max" => {
1983                            let (key, _, _) = grouped.as_ref().ok_or_else(|| {
1984                                SqlError::Unsupported(format!(
1985                                    "'| {name}' outside a group (use '@| {name}')"
1986                                ))
1987                            })?;
1988                            // Quarb's count counts every member,
1989                            // nulls included: COUNT(*), never the
1990                            // NULL-skipping COUNT(col).
1991                            let col = if name == "count" {
1992                                pending_col = None;
1993                                None
1994                            } else {
1995                                self.assume_numeric(pending_name.take());
1996                                pending_col.take()
1997                            };
1998                            let agg = sql_agg(&name, col)?;
1999                            grouped = Some((key.clone(), agg.clone(), agg));
2000                        }
2001                        other => {
2002                            // sort/unique/top and kin are spellable
2003                            // in SQL but with the backend's own
2004                            // collation and duplicate semantics —
2005                            // name the divergence, not a missing
2006                            // feature.
2007                            if matches!(other, "sort" | "sort_by" | "unique" | "top" | "bottom") {
2008                                return Err(SqlError::Semantics(format!(
2009                                    "'{other}' means the backend's collation and \
2010                                     duplicate semantics; one engine-side ordering \
2011                                     keeps it identical everywhere"
2012                                )));
2013                            }
2014                            return Err(SqlError::Unsupported(format!(
2015                                "the '{other}' pipeline command"
2016                            )));
2017                        }
2018                    }
2019                }
2020                "push" => {
2021                    // An alias for the grouped aggregate.
2022                    if let Some((k, agg, _)) = grouped.take() {
2023                        let alias = self.prop_s(s, "name");
2024                        grouped = Some((k, agg, alias));
2025                    } else {
2026                        return Err(SqlError::Unsupported(
2027                            "a register push (Quarb-side state)".into(),
2028                        ));
2029                    }
2030                }
2031                // `| .k(::k)` before a fold by `.k`: the GROUP BY key
2032                // (a projection body is a subcontext of one branch).
2033                "expr-push" if grouped.is_none() && pushed_key.is_none() => {
2034                    let kids = self.arbor.children(s);
2035                    let key = self.operand(kids[0], join.map(|(l, _)| l))?;
2036                    pushed_key = Some((self.prop_s(s, "name"), key));
2037                }
2038                "subcontext" if grouped.is_none() && pushed_key.is_none() => {
2039                    let key = self.pushed_column(s, join.map(|(l, _)| l))?;
2040                    pushed_key = Some((self.prop_s(s, "name"), key));
2041                }
2042                "filter" => {
2043                    if grouped.is_some() {
2044                        // HAVING: `$_` / the alias refer to the
2045                        // aggregate.
2046                        let cond = self.having_cond(s)?;
2047                        sel.having = Some(cond);
2048                    } else {
2049                        return Err(SqlError::Unsupported(
2050                            "a mid-pipeline filter (put it in the row predicate)".into(),
2051                        ));
2052                    }
2053                }
2054                "recall" => {
2055                    // `| %.` finalizes the grouped record.
2056                    if self.prop_s(s, "ref") != "%." {
2057                        return Err(SqlError::Unsupported(
2058                            "a register recall (Quarb-side state)".into(),
2059                        ));
2060                    }
2061                    let (key, agg, alias) = grouped.clone().ok_or_else(|| {
2062                        SqlError::Unsupported("'%.', with nothing grouped".into())
2063                    })?;
2064                    let alias = self.alias(&alias)?;
2065                    sel.select = vec![key.clone(), format!("{agg} AS {alias}")];
2066                    // The HAVING condition compared the aggregate
2067                    // through $_ — substitute the real expression.
2068                    if let Some(h) = sel.having.take() {
2069                        sel.having = Some(h.replace("__AGG__", &agg));
2070                    }
2071                }
2072                "agg" if self.prop(s, "group").is_some() => {
2073                    // `@|{.k} agg`: the fold by the pushed key is the
2074                    // grouped reduction, GROUP BY key.
2075                    let name = self.prop_s(s, "name");
2076                    if !matches!(
2077                        name.as_str(),
2078                        "count" | "sum" | "mean" | "avg" | "min" | "max"
2079                    ) {
2080                        return Err(SqlError::Unsupported(format!(
2081                            "the '{name}' command per group (GROUP BY reduces)"
2082                        )));
2083                    }
2084                    let selector = self.prop_s(s, "group");
2085                    if selector.contains(';') {
2086                        return Err(SqlError::Unsupported(
2087                            "a fold by several regulae (one GROUP BY key translates)".into(),
2088                        ));
2089                    }
2090                    let (reg, key) = pushed_key.take().ok_or_else(|| {
2091                        SqlError::Unsupported("a fold by a regula no push of a key made".into())
2092                    })?;
2093                    if selector != "." && selector != format!(".{reg}") {
2094                        return Err(SqlError::Unsupported(format!(
2095                            "a fold by '{selector}' (the pushed key is '.{reg}')"
2096                        )));
2097                    }
2098                    if self.strict {
2099                        return Err(SqlError::Semantics(
2100                            "GROUP BY result order is unordered in SQL".into(),
2101                        ));
2102                    }
2103                    sel.group_by = Some(key.clone());
2104                    let col = if name == "count" {
2105                        pending_col = None;
2106                        None
2107                    } else {
2108                        self.assume_numeric(pending_name.take());
2109                        pending_col.take()
2110                    };
2111                    let agg = sql_agg(&name, col)?;
2112                    grouped = Some((key, agg.clone(), agg));
2113                }
2114                "agg" => {
2115                    let name = self.prop_s(s, "name");
2116                    match name.as_str() {
2117                        "count" | "sum" | "mean" | "avg" | "min" | "max" => {
2118                            // Quarb's count counts every row, nulls
2119                            // included: COUNT(*) regardless of a
2120                            // pending column.
2121                            let col = if name == "count" {
2122                                pending_col = None;
2123                                None
2124                            } else {
2125                                self.assume_numeric(pending_name.take());
2126                                pending_col.take()
2127                            };
2128                            sel.select = vec![sql_agg(&name, col)?];
2129                            self.aggregate = true;
2130                        }
2131                        "sort_by" => {
2132                            if self.strict {
2133                                return Err(SqlError::Semantics(
2134                                    "ORDER BY collations differ per engine".into(),
2135                                ));
2136                            }
2137                            // A sort after a positional selection
2138                            // (or a second sort) cannot render: the
2139                            // fixed SELECT shape orders before
2140                            // LIMIT, and has one ORDER BY.
2141                            if sel.limit.is_some() {
2142                                return Err(SqlError::Unsupported(
2143                                    "a sort after a positional selection (SQL orders \
2144                                     before LIMIT)"
2145                                        .into(),
2146                                ));
2147                            }
2148                            if sel.order_by.is_some() {
2149                                return Err(SqlError::Unsupported(
2150                                    "a second sort (SQL has a single ORDER BY)".into(),
2151                                ));
2152                            }
2153                            let kids = self.arbor.children(s);
2154                            // The options are the command's own:
2155                            // `--desc` is the direction, a named
2156                            // collation (`--locale=tag`, ruling
2157                            // 2026-11-11) is the engine's order and no
2158                            // backend's; a second key has no place in
2159                            // the one ORDER BY this shape holds.
2160                            let mut desc = false;
2161                            for &k in &kids[1..] {
2162                                if self.kind(k) != "option" {
2163                                    return Err(SqlError::Unsupported(
2164                                        "a sort by several keys".into(),
2165                                    ));
2166                                }
2167                                match self.prop_s(k, "name").as_str() {
2168                                    "--desc" | "-d" => desc = true,
2169                                    "--locale" => {
2170                                        return Err(SqlError::Semantics(
2171                                            "sort_by(--locale=…) names the engine's collation; \
2172                                             a backend's differs"
2173                                                .into(),
2174                                        ));
2175                                    }
2176                                    // a case order is that
2177                                    // collation's (ruling 2026-11-12)
2178                                    "--upper-first" | "-u" | "--lower-first" | "-l"
2179                                    | "--ignore-case" | "-i" => {
2180                                        return Err(SqlError::Semantics(
2181                                            "sort_by's case order is the engine's collation's; \
2182                                             a backend's differs"
2183                                                .into(),
2184                                        ));
2185                                    }
2186                                    other => {
2187                                        return Err(SqlError::Unsupported(format!(
2188                                            "the '{other}' option of sort_by"
2189                                        )));
2190                                    }
2191                                }
2192                            }
2193                            let e = self.operand(kids[0], join.map(|(l, _)| l))?;
2194                            sel.order_by = Some((e, desc));
2195                        }
2196                        "reverse" => match &mut sel.order_by {
2197                            Some((_, desc)) => *desc = true,
2198                            None => {
2199                                return Err(SqlError::Unsupported(
2200                                    "reverse without an ORDER BY (rows are unordered)".into(),
2201                                ));
2202                            }
2203                        },
2204                        "top" => {
2205                            if self.strict {
2206                                return Err(SqlError::Semantics(
2207                                    "ORDER BY collations differ per engine".into(),
2208                                ));
2209                            }
2210                            if sel.limit.is_some() {
2211                                return Err(SqlError::Unsupported(
2212                                    "'top' after a positional selection (SQL orders \
2213                                     before LIMIT)"
2214                                        .into(),
2215                                ));
2216                            }
2217                            if sel.order_by.is_some() {
2218                                return Err(SqlError::Unsupported(
2219                                    "a second sort (SQL has a single ORDER BY)".into(),
2220                                ));
2221                            }
2222                            let kids = self.arbor.children(s);
2223                            // the options name the engine's collation
2224                            // and its case order: no backend's (they
2225                            // were dropped, and the SQL ordered as the
2226                            // backend pleased)
2227                            if let Some(&k) = kids
2228                                .get(2..)
2229                                .and_then(|rest| rest.iter().find(|&&k| self.kind(k) == "option"))
2230                            {
2231                                return Err(SqlError::Semantics(format!(
2232                                    "top({}) names the engine's collation; a backend's differs",
2233                                    self.prop_s(k, "name")
2234                                )));
2235                            }
2236                            let n = self.prop_s(kids[0], "value");
2237                            let e = self.operand(kids[1], join.map(|(l, _)| l))?;
2238                            sel.order_by = Some((e, true));
2239                            sel.limit = Some(n);
2240                        }
2241                        "unique" => {
2242                            if self.strict {
2243                                return Err(SqlError::Unsupported(
2244                                    "pushdown: DISTINCT result order is unordered in SQL".into(),
2245                                ));
2246                            }
2247                            // Quarb dedups the limited rows; SQL
2248                            // applies DISTINCT before LIMIT.
2249                            if sel.limit.is_some() {
2250                                return Err(SqlError::Unsupported(
2251                                    "'unique' after a positional selection (SQL applies \
2252                                     DISTINCT before LIMIT)"
2253                                        .into(),
2254                                ));
2255                            }
2256                            if let Some(c) = pending_col.take() {
2257                                sel.select = vec![c];
2258                            }
2259                            sel.distinct = true;
2260                        }
2261                        other => {
2262                            return Err(SqlError::Unsupported(format!("the '{other}' aggregate")));
2263                        }
2264                    }
2265                }
2266                "select" => {
2267                    if self.strict {
2268                        return Err(SqlError::Unsupported(
2269                            "pushdown: LIMIT without a guaranteed order".into(),
2270                        ));
2271                    }
2272                    // `@| [..n]` → LIMIT.
2273                    if sel.limit.is_some() {
2274                        return Err(SqlError::Unsupported(
2275                            "a second positional selection".into(),
2276                        ));
2277                    }
2278                    let p = self.arbor.children(s)[0];
2279                    match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
2280                        ("range", Some(Value::Int(n)))
2281                            if self.prop(p, "from").is_none() && n > 0 =>
2282                        {
2283                            sel.limit = Some(n.to_string());
2284                        }
2285                        _ => {
2286                            return Err(SqlError::Unsupported(
2287                                "positional selection beyond '@| [..n]'".into(),
2288                            ));
2289                        }
2290                    }
2291                }
2292                other => {
2293                    return Err(SqlError::Unsupported(format!(
2294                        "the '{other}' command (windows, subcontexts, and registers are \
2295                         Quarb-side state)"
2296                    )));
2297                }
2298            }
2299            i += 1;
2300        }
2301        // A pending column with no aggregate is a one-column select.
2302        if let Some(c) = pending_col
2303            && sel.select.is_empty()
2304        {
2305            sel.select = vec![c];
2306        }
2307        // A grouped reduction never recorded (`@|{.k} count` with no
2308        // `| .n | %.`) answers one value per group: the aggregate
2309        // alone, grouped by the key.
2310        if let Some((_, agg, _)) = grouped
2311            && sel.select.is_empty()
2312        {
2313            sel.select = vec![agg];
2314        }
2315        Ok(())
2316    }
2317
2318    /// The column a pushed projection body names — `.k(::k)` is a
2319    /// subcontext whose one branch is the bare projection; any
2320    /// other body is Quarb-side state.
2321    fn pushed_column(&mut self, s: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
2322        let body = || {
2323            let q = self.kid(s, "query")?;
2324            let b = self.kid(q, "branch")?;
2325            let p = self.kid(b, "projection")?;
2326            let bare = self.kids(q, "branch").len() == 1
2327                && self.kids(q, "pipeline").is_empty()
2328                && self.arbor.children(b).len() == 1
2329                && self.prop_s(p, "kind") == "property";
2330            bare.then_some(p)
2331        };
2332        let p = body()
2333            .ok_or_else(|| SqlError::Unsupported("a pushed body (Quarb-side state)".into()))?;
2334        let col = self.projection_col(p)?;
2335        let col = self.sql_ident(&col, "column name")?;
2336        Ok(match qual {
2337            Some(q) => format!("{q}.{col}"),
2338            None => col,
2339        })
2340    }
2341
2342    /// A HAVING filter: `$_` and `$.name` refer to the aggregate.
2343    fn having_cond(&mut self, s: NodeId) -> Result<String, SqlError> {
2344        let kids = self.arbor.children(s);
2345        if kids.len() != 1 || self.kind(kids[0]) != "compare" {
2346            return Err(SqlError::Unsupported(
2347                "HAVING translates for a single comparison".into(),
2348            ));
2349        }
2350        let e = kids[0];
2351        let op = self.prop_s(e, "op");
2352        let cmp_kids = self.arbor.children(e);
2353        let l = match self.kind(cmp_kids[0]).as_str() {
2354            "topic" | "recall" => "__AGG__".to_string(),
2355            _ => {
2356                return Err(SqlError::Unsupported(
2357                    "HAVING compares the aggregate ($_ or its register)".into(),
2358                ));
2359            }
2360        };
2361        let r = self.operand(cmp_kids[1], None)?;
2362        Ok(format!("{l} {op} {r}"))
2363    }
2364
2365    /// `rec(...)` fields as a select list.
2366    fn record_fields(
2367        &mut self,
2368        s: NodeId,
2369        join: Option<(&str, &str)>,
2370    ) -> Result<Vec<String>, SqlError> {
2371        let kids = self.arbor.children(s);
2372        let mut fields = Vec::new();
2373        let mut i = 0;
2374        while i < kids.len() {
2375            let k = kids[i];
2376            if self.kind(k) == "literal" {
2377                let name = self.prop_s(k, "value");
2378                let value = self.operand(kids[i + 1], join.map(|(l, _)| l))?;
2379                let name = self.alias(&name)?;
2380                fields.push(format!("{value} AS {name}"));
2381                i += 2;
2382            } else {
2383                let value = self.operand(k, join.map(|(l, _)| l))?;
2384                fields.push(value);
2385                i += 1;
2386            }
2387        }
2388        Ok(fields)
2389    }
2390}
2391
2392fn sql_agg(name: &str, col: Option<String>) -> Result<String, SqlError> {
2393    let f = match name {
2394        "count" => "COUNT",
2395        "sum" => "SUM",
2396        "mean" | "avg" => "AVG",
2397        "min" => "MIN",
2398        "max" => "MAX",
2399        _ => unreachable!("checked by caller"),
2400    };
2401    match col {
2402        Some(c) => Ok(format!("{f}({c})")),
2403        // Only COUNT aggregates bare rows; SUM(*) and friends are
2404        // not SQL.
2405        None if f == "COUNT" => Ok("COUNT(*)".to_string()),
2406        None => Err(SqlError::Unsupported(format!(
2407            "'{name}' over row nodes (project a column first: '| ::col @| {name}')"
2408        ))),
2409    }
2410}
2411
2412#[cfg(test)]
2413mod null_and_literal_tests {
2414    use super::{Dialect, export, partial_pushdown, pushdown};
2415
2416    // Grouped pipeline that never pushes, so `partial_pushdown` hinges
2417    // only on the leading predicate (mirrors the crate's partial gate).
2418    const GROUPED: &str = " | ::x | .g(::x) @|{.g} count | .n | %.";
2419
2420    #[test]
2421    fn pattern_literal_pushes_as_like() {
2422        // Ruling #33: segments in order, a `%` per star, LIKE's
2423        // metacharacters escaped. Strict push only where LIKE is
2424        // provably case-sensitive (PostgreSQL); everywhere else the
2425        // pattern rides the scan.
2426        let q = "/users/*[::name == 'app-'*]::id";
2427        let p = pushdown(q, Some(Dialect::Postgres)).unwrap();
2428        assert_eq!(
2429            p.sql,
2430            "SELECT id FROM users WHERE name LIKE 'app-%' ESCAPE '\\'"
2431        );
2432        assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
2433        assert!(pushdown(q, Some(Dialect::MySql)).is_none());
2434        // contains and multi-segment shapes
2435        let p = pushdown("/users/*[::name == *'web'*]::id", Some(Dialect::Postgres)).unwrap();
2436        assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
2437        let p = pushdown(
2438            "/users/*[::name == *'a'*'.gz']::id",
2439            Some(Dialect::Postgres),
2440        )
2441        .unwrap();
2442        assert!(p.sql.contains("LIKE '%a%.gz'"), "{}", p.sql);
2443        // LIKE metacharacters in a segment are escaped
2444        let p = pushdown("/users/*[::name == *'50%_x'*]::id", Some(Dialect::Postgres)).unwrap();
2445        assert!(p.sql.contains("LIKE '%50\\%\\_x%'"), "{}", p.sql);
2446        // `!=` with a pattern rides the scan
2447        assert!(pushdown("/users/*[::name !== *'web'*]::id", Some(Dialect::Postgres)).is_none());
2448        // the `*=` alias gains the same PostgreSQL rung
2449        let p = pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Postgres)).unwrap();
2450        assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
2451        assert!(pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Sqlite)).is_none());
2452    }
2453
2454    #[test]
2455    fn json_column_path_pushdown_per_dialect() {
2456        // `[/col/a/b:: = 'lit']` navigates into a JSON column; each
2457        // dialect extracts the fixed path to text and compares.
2458        // Verified live against all five engines to match the graft.
2459        let q = "/orders/*[/data/meta/tier:: = 'gold']::id";
2460        let sql = |d| pushdown(q, Some(d)).unwrap().sql;
2461        assert_eq!(
2462            sql(Dialect::Postgres),
2463            "SELECT id FROM orders WHERE ((data::jsonb #>> '{meta,tier}') = 'gold')"
2464        );
2465        assert_eq!(
2466            sql(Dialect::MySql),
2467            "SELECT id FROM orders WHERE (JSON_VALID(data) AND \
2468             JSON_UNQUOTE(JSON_EXTRACT(data, '$.meta.tier')) = 'gold')"
2469        );
2470        assert_eq!(
2471            sql(Dialect::Sqlite),
2472            "SELECT id FROM orders WHERE (json_valid(data) AND \
2473             json_extract(data, '$.meta.tier') = 'gold')"
2474        );
2475        assert_eq!(
2476            sql(Dialect::Mssql),
2477            "SELECT id FROM orders WHERE (ISJSON(data) = 1 AND \
2478             JSON_VALUE(data, '$.meta.tier') = 'gold')"
2479        );
2480        assert_eq!(
2481            sql(Dialect::Oracle),
2482            "SELECT id FROM orders WHERE (JSON_VALUE(data, '$.meta.tier') = 'gold')"
2483        );
2484        // With no dialect, the JSON navigation is not pushable — it
2485        // falls back to the client-side graft.
2486        assert!(pushdown(q, None).is_none());
2487    }
2488
2489    #[test]
2490    fn json_pushdown_only_string_equality() {
2491        // Numeric comparison, `!=`, and a wildcard hop stay off the
2492        // pushdown path (they are not provably identical to the
2493        // graft), so they refuse and scan even with a dialect set.
2494        let d = Some(Dialect::Sqlite);
2495        assert!(pushdown("/o/*[/data/n:: > 2]::id", d).is_none());
2496        assert!(pushdown("/o/*[/data/tier:: != 'gold']::id", d).is_none());
2497        assert!(pushdown("/o/*[/data/items/*/sku:: = 'A1']::id", d).is_none());
2498    }
2499
2500    #[test]
2501    fn json_pushdown_refuses_numeric_looking_literal() {
2502        // value_eq coerces numeric-looking strings ('150' matches
2503        // the JSON number 150 and the string "150.0"); no engine's
2504        // extractor does, so the push would drop rows.
2505        let q = "/orders/*[/data/total:: = '150']::id";
2506        assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
2507        assert!(pushdown(q, Some(Dialect::Postgres)).is_none());
2508    }
2509
2510    #[test]
2511    fn partial_json_prefilters_sqlite() {
2512        // Exact string equality rides the strict gate.
2513        let p = partial_pushdown(
2514            "/orders/*[/payload/customer/geo/city:: = 'Lyon']::id",
2515            Some(Dialect::Sqlite),
2516        )
2517        .unwrap();
2518        assert_eq!(p.table, "orders");
2519        assert_eq!(
2520            p.where_sql,
2521            "(json_valid(payload) AND \
2522             json_extract(payload, '$.customer.geo.city') = 'Lyon')"
2523        );
2524        // Numeric comparison: typed compare, text values escape.
2525        let p = partial_pushdown(
2526            "/orders/*[/payload/total:: > 150]::id",
2527            Some(Dialect::Sqlite),
2528        )
2529        .unwrap();
2530        assert_eq!(
2531            p.where_sql,
2532            "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
2533             OR json_type(payload, '$.total') = 'text'))"
2534        );
2535        // Bare existence.
2536        let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Sqlite)).unwrap();
2537        assert_eq!(
2538            p.where_sql,
2539            "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
2540        );
2541        // != floors at existence.
2542        let p = partial_pushdown(
2543            "/orders/*[/payload/status:: != 'x']::id",
2544            Some(Dialect::Sqlite),
2545        )
2546        .unwrap();
2547        assert_eq!(
2548            p.where_sql,
2549            "(json_valid(payload) AND json_type(payload, '$.status') IS NOT NULL)"
2550        );
2551        // A flipped literal flips the operator.
2552        let p = partial_pushdown(
2553            "/orders/*[150 < /payload/total::]::id",
2554            Some(Dialect::Sqlite),
2555        )
2556        .unwrap();
2557        assert!(p.where_sql.contains("> 150"), "{}", p.where_sql);
2558        // Without a dialect, JSON predicates stay on the engine.
2559        assert!(partial_pushdown("/orders/*[/payload/gift]::id", None).is_none());
2560    }
2561
2562    #[test]
2563    fn partial_json_prefilters_postgres() {
2564        let p = partial_pushdown(
2565            "/orders/*[/payload/total:: > 150]::id",
2566            Some(Dialect::Postgres),
2567        )
2568        .unwrap();
2569        assert_eq!(
2570            p.where_sql,
2571            "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
2572             THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
2573             WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'string' \
2574             THEN true ELSE false END)"
2575        );
2576        let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Postgres)).unwrap();
2577        assert_eq!(
2578            p.where_sql,
2579            "(jsonb_typeof(payload::jsonb #> '{gift}') IS NOT NULL)"
2580        );
2581    }
2582
2583    #[test]
2584    fn partial_skips_untranslatable_keeps_prefix() {
2585        // A refused predicate no prefilter covers is skipped — the
2586        // shorter conjunction is still a superset (the engine
2587        // re-applies the original) — rather than aborting the plan.
2588        let p = partial_pushdown(
2589            "/orders/*[::status = 'shipped'][/payload/line_items/*/sku:: = 'X']::id",
2590            Some(Dialect::Sqlite),
2591        )
2592        .unwrap();
2593        assert_eq!(p.where_sql, "status = 'shipped'");
2594    }
2595
2596    #[test]
2597    fn null_literal_compares_use_is_null() {
2598        // `= null` / `!= null` are provably identical to Quarb's
2599        // value_eq(NULL, …) semantics, never the always-UNKNOWN
2600        // `x = NULL`; they translate — and push — in both modes.
2601        assert_eq!(
2602            export("/t/*[::x = null] | ::x").unwrap().query,
2603            "SELECT x FROM t WHERE x IS NULL"
2604        );
2605        assert_eq!(
2606            export("/t/*[::x != null] | ::x").unwrap().query,
2607            "SELECT x FROM t WHERE x IS NOT NULL"
2608        );
2609        assert_eq!(
2610            pushdown("/t/*[::x = null] | ::x", None).unwrap().sql,
2611            "SELECT x FROM t WHERE x IS NULL"
2612        );
2613        assert_eq!(
2614            pushdown("/t/*[::x != null] | ::x", None).unwrap().sql,
2615            "SELECT x FROM t WHERE x IS NOT NULL"
2616        );
2617    }
2618
2619    #[test]
2620    fn ne_and_not_refuse_pushdown_but_display_diverges() {
2621        // `!=` against a non-null value and `not(...)` drop the NULL
2622        // rows Quarb keeps under SQL three-valued logic: the pushdown
2623        // paths refuse (and scan), full and partial alike.
2624        assert!(pushdown("/t/*[::x != 5] | ::x", None).is_none());
2625        assert!(pushdown("/t/*[!::x = 5] | ::x", None).is_none());
2626        assert!(partial_pushdown(&format!("/t/*[::x != 5]{GROUPED}"), None).is_none());
2627        assert!(partial_pushdown(&format!("/t/*[!::x = 5]{GROUPED}"), None).is_none());
2628        // The display translation still emits `<>`, flagged with a note.
2629        let t = export("/t/*[::x != 5] | ::x").unwrap();
2630        assert_eq!(t.query, "SELECT x FROM t WHERE x <> 5");
2631        assert!(t.notes.iter().any(|n| n.contains("NULL")));
2632    }
2633
2634    #[test]
2635    fn unescapable_text_literal_refuses_pushdown() {
2636        // A backslash (MySQL/BigQuery escape) or an apostrophe
2637        // (BigQuery rejects '' doubling) has no portable escaping, so
2638        // pushdown refuses; a clean literal still pushes.
2639        assert!(pushdown("/files/*[::path = \"C:\\temp\"] | ::path", None).is_none());
2640        assert!(pushdown("/t/*[::name = \"it's\"] | ::name", None).is_none());
2641        assert!(partial_pushdown(&format!("/t/*[::name = \"it's\"]{GROUPED}"), None).is_none());
2642        assert_eq!(
2643            pushdown("/t/*[::name = \"rare\"] | ::name", None)
2644                .unwrap()
2645                .sql,
2646            "SELECT name FROM t WHERE name = 'rare'"
2647        );
2648    }
2649}