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