Skip to main content

quarb_sql/
export.rs

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