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