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                    // Inside a join condition a comparison that reads
1691                    // the driver is a key comparison, unknown for a
1692                    // null on either side, the literal too (spec:
1693                    // Null keys): `[$$0::x != null && …]` admits no
1694                    // candidate. IS [NOT] NULL would answer, so the
1695                    // plan is not the scan's. (It was pushed so: five
1696                    // pairs from the plan, none from the scan.)
1697                    if self.in_on && self.subtree_has_driver(other) {
1698                        return Err(not_pushed(
1699                            Refusal::Join,
1700                            "a test of the driver's key for null inside the join condition (a \
1701                             key comparison never holds for a null there: test it on the \
1702                             driver, '/t/*[::x != null] <=> …')"
1703                                .into(),
1704                        ));
1705                    }
1706                    let col = self.operand(other, qual)?;
1707                    return Ok(if op == "=" {
1708                        format!("{col} IS NULL")
1709                    } else {
1710                        format!("{col} IS NOT NULL")
1711                    });
1712                }
1713                // JSON-column-path pushdown: `[/col/a/b:: = 'lit']`
1714                // navigates into a JSON column and compares a fixed
1715                // path to a string literal. Only this exact shape —
1716                // fixed object path, string equality, and a literal
1717                // that does NOT look numeric — is provably identical
1718                // to the client-side graft (each engine's scalar
1719                // extractor unquotes to text, and an absent path or
1720                // non-string value excludes the row on both sides,
1721                // matching Quarb's `value_eq` on non-numeric text).
1722                // Numeric casts, `!=`, wildcards, and deeper
1723                // predicates fall through to the ordinary operand
1724                // logic below, which refuses the navigation; the
1725                // partial-pushdown prefilter ladder picks those up
1726                // with superset semantics. Enabled only when a
1727                // dialect is set.
1728                if op == "="
1729                    && let Some(dialect) = self.dialect
1730                {
1731                    for (pi, li) in [(0usize, 1usize), (1, 0)] {
1732                        if self.is_text_literal(kids[li])
1733                            && let Some((col, path)) = self.json_path(kids[pi])
1734                        {
1735                            self.note_json_column(kids[pi], &col);
1736                            // Quarb's value_eq compares numeric-looking
1737                            // strings numerically — '150' matches the
1738                            // JSON number 150, and the string "150.0".
1739                            // No engine's text extractor coerces that
1740                            // way, so the pushed compare would drop
1741                            // rows the graft keeps. Refuse; the
1742                            // prefilter ladder handles it as a
1743                            // superset.
1744                            let raw = self
1745                                .prop(kids[li], "value")
1746                                .map(|v| v.to_string())
1747                                .unwrap_or_default();
1748                            if raw.trim().parse::<f64>().is_ok() {
1749                                return Err(mismatch(
1750                                    Refusal::Type,
1751                                    "a numeric-looking text literal against a \
1752                                     JSON path compares numerically in Quarb \
1753                                     (value coercion); no SQL extractor \
1754                                     matches that"
1755                                        .into(),
1756                                ));
1757                            }
1758                            // An extractor answers a container as
1759                            // its JSON text (SQLite `[1,2]`,
1760                            // PostgreSQL `[1, 2]`), so a literal that
1761                            // is such a text equalled the array or
1762                            // the object itself, which has no value
1763                            // in the graft: the push kept a row the
1764                            // scan drops. No scalar's text opens
1765                            // with a bracket or a brace that a
1766                            // container's does not, so such a
1767                            // literal rides the prefilter.
1768                            if raw.starts_with('[') || raw.starts_with('{') {
1769                                return Err(mismatch(
1770                                    Refusal::Type,
1771                                    "a text literal that opens like a JSON container \
1772                                     could equal an array's or an object's own text \
1773                                     in the extractor, which has no value in Quarb"
1774                                        .into(),
1775                                ));
1776                            }
1777                            let lit = self.operand(kids[li], qual)?;
1778                            let extract = json_extract(dialect, qual, &col, &path);
1779                            return Ok(json_valid_guard(
1780                                dialect,
1781                                qual,
1782                                &col,
1783                                format!("{extract} = {lit}"),
1784                            ));
1785                        }
1786                    }
1787                    // The property form, `[/col/a::b = 'lit']`: the
1788                    // same question on a scalar, and on an array of
1789                    // scalars the list, which equals the literal when
1790                    // any item does (an array that holds a container
1791                    // is no property). SQLite says both in one
1792                    // condition, exactly: the scalar branch by the
1793                    // value's type and text, the array branch by
1794                    // `json_each`. The other engines' array branches
1795                    // are not verified live, so there the shape rides
1796                    // the prefilter (PostgreSQL) or the scan.
1797                    for (pi, li) in [(0usize, 1usize), (1, 0)] {
1798                        if self.is_text_literal(kids[li])
1799                            && let Some((col, path)) = self.json_property_path(kids[pi])
1800                        {
1801                            self.note_json_column(kids[pi], &col);
1802                            let raw = self
1803                                .prop(kids[li], "value")
1804                                .map(|v| v.to_string())
1805                                .unwrap_or_default();
1806                            if raw.trim().parse::<f64>().is_ok() {
1807                                return Err(mismatch(
1808                                    Refusal::Type,
1809                                    "a numeric-looking text literal against a \
1810                                     JSON path compares numerically in Quarb \
1811                                     (value coercion); no SQL extractor \
1812                                     matches that"
1813                                        .into(),
1814                                ));
1815                            }
1816                            // `json_each` names its own columns; an
1817                            // unqualified JSON column of one of those
1818                            // names would read as them inside it.
1819                            let shadowed = qual.is_none()
1820                                && JSON_EACH_COLUMNS.contains(&col.to_ascii_lowercase().as_str());
1821                            if dialect != Dialect::Sqlite || shadowed {
1822                                return Err(mismatch(
1823                                    Refusal::Type,
1824                                    "a property of a JSON value may be a list (an \
1825                                     array of scalars equals the literal when any \
1826                                     item does); only SQLite's condition carries \
1827                                     that branch whole; this shape rides the \
1828                                     partial prefilter"
1829                                        .into(),
1830                                ));
1831                            }
1832                            let lit = self.operand(kids[li], qual)?;
1833                            let qcol = match qual {
1834                                Some(q) => format!("{q}.{col}"),
1835                                None => col.clone(),
1836                            };
1837                            let at = format!("'$.{}'", path.join("."));
1838                            let ty = format!("json_type({qcol}, {at})");
1839                            let ex = json_extract(dialect, qual, &col, &path);
1840                            return Ok(json_valid_guard(
1841                                dialect,
1842                                qual,
1843                                &col,
1844                                format!(
1845                                    "(({ty} = 'text' AND {ex} = {lit}) OR ({ty} = 'array' \
1846                                     AND EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1847                                     WHERE json_each.type = 'text' AND json_each.value = {lit}) \
1848                                     AND NOT EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1849                                     WHERE json_each.type IN ('array', 'object'))))"
1850                                ),
1851                            ));
1852                        }
1853                    }
1854                }
1855                // Any other JSON-path comparison: name the real
1856                // reason, not the generic flat-rows refusal — only
1857                // fixed-path string equality is provably identical
1858                // (Quarb coerces numeric-looking values; no
1859                // engine's extractor matches that). The partial
1860                // prefilter ladder covers these shapes.
1861                if self.dialect.is_some() {
1862                    for side in [kids[0], kids[1]] {
1863                        if self.json_path(side).is_some()
1864                            || self.json_path_loose(side).is_some()
1865                            || self.json_property_path(side).is_some()
1866                        {
1867                            return Err(mismatch(
1868                                Refusal::Type,
1869                                "a JSON-path comparison pushes whole only as \
1870                                 fixed-path string equality (Quarb coerces \
1871                                 numeric-looking values; no extractor matches \
1872                                 that); this shape rides the partial prefilter"
1873                                    .into(),
1874                            ));
1875                        }
1876                    }
1877                }
1878                // Quarb compares by value; SQL by the column's type.
1879                // A column against a numeric literal is the scan's
1880                // comparison only on a numeric-typed column, and
1881                // against a text literal only on a column that is
1882                // not (MySQL reads `n = 'abc'` as `n = 0`): the
1883                // catalog decides, so both are recorded for the
1884                // caller. A numeric-looking TEXT literal meets
1885                // numbers as a number in Quarb and compares as text
1886                // in SQL, on every engine, so it does not push. A
1887                // regex is no value: its refusal below is the
1888                // pattern's, whatever its text reads as.
1889                if self.strict && !matches!(op.as_str(), "==" | "!==") {
1890                    for (ci, li) in [(0usize, 1usize), (1, 0)] {
1891                        let Some(column) = self.column_operand(kids[ci]) else {
1892                            continue;
1893                        };
1894                        if self.kind(kids[li]) != "literal" {
1895                            continue;
1896                        }
1897                        let numeric = self
1898                            .prop(kids[li], "value")
1899                            .is_some_and(|v| Value::Str(v.to_string()).numeric_reading().is_some());
1900                        let list = match (self.prop_s(kids[li], "type").as_str(), numeric) {
1901                            ("null", _) => continue,
1902                            ("text", true) => {
1903                                return Err(mismatch(
1904                                    Refusal::Type,
1905                                    "a numeric-looking text literal compares \
1906                                     numerically in Quarb (value coercion); SQL \
1907                                     compares it as text"
1908                                        .into(),
1909                                ));
1910                            }
1911                            ("text", false) => &mut self.column_types.text,
1912                            (_, true) => &mut self.column_types.numeric,
1913                            (_, false) => continue,
1914                        };
1915                        if !list.contains(&column) {
1916                            list.push(column);
1917                        }
1918                    }
1919                }
1920                let l = self.operand(kids[0], qual)?;
1921                // Ruling #33: a pattern literal on `=` pushes as
1922                // LIKE — a `%` per star, each literal segment
1923                // escaped, in order. Anchoring matches exactly:
1924                // LIKE anchors both ends, a flanking star lifts
1925                // one. The case-folding caveat is `*=`'s; `!=`
1926                // with a pattern rides the scan (NOT LIKE drops
1927                // the NULL rows Quarb keeps).
1928                if self.kind(kids[1]) == "pattern" {
1929                    if op.as_str() != "=" {
1930                        return Err(not_pushed(
1931                            Refusal::Pattern,
1932                            format!("a pattern literal on '{op}' (only '=' pushes)"),
1933                        ));
1934                    }
1935                    // PostgreSQL's LIKE is case-sensitive under its
1936                    // deterministic collations — provably what the
1937                    // pattern test does — so the strict push is
1938                    // sound there (and a prefix pattern is
1939                    // index-sargable server-side). Everywhere else
1940                    // case folding is ambient state (SQLite pragma,
1941                    // MySQL/MSSQL collation), so strict refuses.
1942                    if self.strict && self.dialect != Some(Dialect::Postgres) {
1943                        return Err(mismatch(
1944                            Refusal::Pattern,
1945                            "LIKE case folding differs per engine \
1946                             (provably case-sensitive only on PostgreSQL)"
1947                                .into(),
1948                        ));
1949                    }
1950                    if !self.strict {
1951                        self.notes.push(
1952                            "pattern → LIKE: Quarb's pattern test is \
1953                             case-sensitive; LIKE folds case on \
1954                             SQLite/MySQL but not PostgreSQL"
1955                                .to_string(),
1956                        );
1957                    }
1958                    let mut like = String::new();
1959                    for kid in self.arbor.children(kids[1]) {
1960                        match self.kind(kid).as_str() {
1961                            "star" => like.push('%'),
1962                            _ => {
1963                                let raw = self
1964                                    .prop(kid, "value")
1965                                    .map(|v| v.to_string())
1966                                    .unwrap_or_default();
1967                                like.push_str(
1968                                    &raw.replace('\\', "\\\\")
1969                                        .replace('%', "\\%")
1970                                        .replace('_', "\\_")
1971                                        .replace('\'', "''"),
1972                                );
1973                            }
1974                        }
1975                    }
1976                    return Ok(format!("{l} LIKE '{like}' ESCAPE '\\'"));
1977                }
1978                let r = self.operand(kids[1], qual)?;
1979                // Which sides can be NULL: every side that is no
1980                // literal. And whether this is a key comparison of a
1981                // join condition, which the engine leaves unknown for
1982                // a null on either side, as SQL does: there the plain
1983                // operators are the engine's own.
1984                let nullable: Vec<&str> = [(kids[0], l.as_str()), (kids[1], r.as_str())]
1985                    .into_iter()
1986                    .filter(|(k, _)| self.kind(*k) != "literal")
1987                    .map(|(_, sql)| sql)
1988                    .collect();
1989                let keyed = self.in_on
1990                    && (self.subtree_has_driver(kids[0]) || self.subtree_has_driver(kids[1]));
1991                Ok(match op.as_str() {
1992                    // Two NULLs are equal in Quarb (`value_eq`), and
1993                    // SQL's `=` is UNKNOWN for them: an equality of
1994                    // two columns says the second case too. (It was
1995                    // pushed as the bare `a = b`, which dropped the
1996                    // row where both are NULL.)
1997                    "=" if self.strict && !keyed && nullable.len() == 2 => {
1998                        format!("({l} = {r} OR ({l} IS NULL AND {r} IS NULL))")
1999                    }
2000                    "=" => format!("{l} = {r}"),
2001                    // Quarb's `!=` holds for a NULL against a value
2002                    // and fails for two NULLs; SQL's `<>` is UNKNOWN
2003                    // for either. The plan adds the cases `<>` leaves
2004                    // out, in SQL every engine reads.
2005                    "!=" if self.strict && !keyed => match nullable.as_slice() {
2006                        [] => format!("{l} <> {r}"),
2007                        [one] => format!("({l} <> {r} OR {one} IS NULL)"),
2008                        _ => format!(
2009                            "({l} <> {r} OR ({l} IS NULL AND {r} IS NOT NULL) OR ({l} IS NOT \
2010                             NULL AND {r} IS NULL))"
2011                        ),
2012                    },
2013                    "!=" if self.strict => format!("{l} <> {r}"),
2014                    "!=" => {
2015                        // The display translation keeps `<>` and
2016                        // notes the divergence.
2017                        self.notes.push(
2018                            "'!=' → '<>': Quarb keeps rows whose column is NULL; \
2019                             SQL's '<>' drops them (use '!= null' for IS NOT NULL)"
2020                                .to_string(),
2021                        );
2022                        format!("{l} <> {r}")
2023                    }
2024                    "<" | "<=" | ">" | ">=" => format!("{l} {op} {r}"),
2025                    // SQLite's instr is a substring test by bytes,
2026                    // case and all, as `*=` is; the column is a text
2027                    // one (recorded above with the literal: a number
2028                    // would be searched in SQLite's rendering of it,
2029                    // not the engine's). A NULL has no substring on
2030                    // either side.
2031                    "*=" if self.strict
2032                        && self.dialect == Some(Dialect::Sqlite)
2033                        && self.is_text_literal(kids[1])
2034                        && self.column_operand(kids[0]).is_some() =>
2035                    {
2036                        format!("instr({l}, {r}) > 0")
2037                    }
2038                    "*=" => {
2039                        // The same PostgreSQL rung as the pattern
2040                        // literal above: LIKE is provably
2041                        // case-sensitive there, so `*=` pushes
2042                        // strict too.
2043                        if self.strict && self.dialect != Some(Dialect::Postgres) {
2044                            return Err(mismatch(
2045                                Refusal::Pattern,
2046                                "LIKE case folding differs per engine \
2047                                 (a substring test is pushed on SQLite as instr and on \
2048                                 PostgreSQL as LIKE)"
2049                                    .into(),
2050                            ));
2051                        }
2052                        // The pattern must be a text literal: a
2053                        // column or computed operand holds a value,
2054                        // not a pattern, and SQL LIKE cannot express
2055                        // "contains that value" portably.
2056                        if !self.is_text_literal(kids[1]) {
2057                            return Err(not_pushed(
2058                                Refusal::Pattern,
2059                                "'*=' with a non-literal pattern".into(),
2060                            ));
2061                        }
2062                        self.notes.push(
2063                            "*= → LIKE: Quarb's substring test is case-sensitive; LIKE \
2064                             folds case on SQLite/MySQL but not PostgreSQL"
2065                                .to_string(),
2066                        );
2067                        // Escape LIKE's metacharacters, then quote.
2068                        // The explicit ESCAPE makes '\' the escape
2069                        // everywhere — SQLite, MSSQL, and Oracle
2070                        // have no default escape character.
2071                        let raw = self
2072                            .prop(kids[1], "value")
2073                            .map(|v| v.to_string())
2074                            .unwrap_or_default();
2075                        let pat = raw
2076                            .replace('\\', "\\\\")
2077                            .replace('%', "\\%")
2078                            .replace('_', "\\_")
2079                            .replace('\'', "''");
2080                        format!("{l} LIKE '%{pat}%' ESCAPE '\\'")
2081                    }
2082                    "==" | "!==" | "=~" | "!~" => {
2083                        return Err(mismatch(
2084                            Refusal::Pattern,
2085                            "regex matching means a different REGEXP engine per \
2086                             backend; regexes run engine-side"
2087                                .into(),
2088                        ));
2089                    }
2090                    other => {
2091                        return Err(not_pushed(
2092                            Refusal::Operator,
2093                            format!("the '{other}' comparison"),
2094                        ));
2095                    }
2096                })
2097            }
2098            // A bare truthy operand.
2099            _ => {
2100                if self.strict {
2101                    return Err(mismatch(
2102                        Refusal::Type,
2103                        "truthiness diverges (0 and '' are falsy in Quarb)".into(),
2104                    ));
2105                }
2106                self.notes.push(
2107                    "truthiness: '[::c]' exports as IS NOT NULL, but Quarb also treats \
2108                     0 and '' as falsy"
2109                        .to_string(),
2110                );
2111                Ok(format!("{} IS NOT NULL", self.operand(e, qual)?))
2112            }
2113        }
2114    }
2115
2116    fn operand(&mut self, o: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
2117        match self.kind(o).as_str() {
2118            "literal" => {
2119                let v = self.prop(o, "value").unwrap_or(Value::Null);
2120                match self.prop_s(o, "type").as_str() {
2121                    "text" => {
2122                        let s = v.to_string();
2123                        // No single escaping is portable across the
2124                        // pushdown's target dialects: MySQL (default
2125                        // sql_mode) and BigQuery read `\` as an escape
2126                        // while SQLite/PostgreSQL/DuckDB take it
2127                        // literally, and BigQuery rejects the `''`
2128                        // quote-doubling the others require. A literal
2129                        // carrying either character cannot be pushed as
2130                        // provably identical SQL, so refuse it and let
2131                        // the caller scan. (The display translation
2132                        // keeps its best-effort `''`-doubling.)
2133                        if self.strict && (s.contains('\'') || s.contains('\\')) {
2134                            return Err(mismatch(
2135                                Refusal::Name,
2136                                "a text literal with a quote or backslash \
2137                                 has no escaping portable across SQL dialects"
2138                                    .into(),
2139                            ));
2140                        }
2141                        Ok(format!("'{}'", s.replace('\'', "''")))
2142                    }
2143                    "null" => Ok("NULL".to_string()),
2144                    _ => Ok(v.to_string()),
2145                }
2146            }
2147            "path" => {
2148                if self.kid(o, "step").is_some() {
2149                    // A step here is either navigation (refused) or
2150                    // a resolution chain (refused with the reason).
2151                    let s = self.kids(o, "step")[0];
2152                    if self.prop_s(s, "axis") == "-->" {
2153                        return Err(not_pushed(
2154                            Refusal::Resolution,
2155                            "a '-->' resolution chain: the foreign-key targets live in \
2156                             the schema, not the query — spell the join with '<=>' to \
2157                             export it"
2158                                .into(),
2159                        ));
2160                    }
2161                    return Err(not_pushed(
2162                        Refusal::Resolution,
2163                        "navigation inside a predicate (SQL rows are flat)".into(),
2164                    ));
2165                }
2166                let p = self
2167                    .kid(o, "projection")
2168                    .ok_or_else(|| not_pushed(Refusal::Operator, "an empty path operand".into()))?;
2169                let col = self.projection_col(p)?;
2170                let col = self.sql_ident(&col, "column name")?;
2171                // a read through a mark: the row the mark names
2172                let (named, any) = self.mark_anchor(o);
2173                if any {
2174                    let Some(name) = named else {
2175                        return Err(not_pushed(
2176                            Refusal::State,
2177                            "a mark read by position, or of several marks".into(),
2178                        ));
2179                    };
2180                    if self.join_marks.contains(&name) {
2181                        // `$$.al::col`: the witness, as `$$1::col`
2182                        if self.in_on {
2183                            return Err(not_pushed(
2184                                Refusal::Join,
2185                                "the joined expression's own mark inside its ON".into(),
2186                            ));
2187                        }
2188                        let Some(join) = self.join_sql.clone() else {
2189                            return Err(not_pushed(
2190                                Refusal::Join,
2191                                "a join mark outside a correlation join".into(),
2192                            ));
2193                        };
2194                        return Ok(format!("{join}.{col}"));
2195                    }
2196                    if self.from_marks.contains(&name) {
2197                        // `$$.t::col`: the driver's row, as `$$0::col`
2198                        // in the ON
2199                        return Ok(if self.join_sql.is_some() {
2200                            format!("{}.{col}", self.from_sql.clone())
2201                        } else {
2202                            match qual {
2203                                Some(q) => format!("{q}.{col}"),
2204                                None => col,
2205                            }
2206                        });
2207                    }
2208                    return Err(not_pushed(
2209                        Refusal::State,
2210                        format!("a read of the mark '.{name}' (not a row of the query's tables)"),
2211                    ));
2212                }
2213                Ok(match qual {
2214                    Some(q) => format!("{q}.{col}"),
2215                    None => col,
2216                })
2217            }
2218            "context" => {
2219                // `$$1::col` — the joined expression's witness, in
2220                // pipeline position: the joined table's column.
2221                // Anything else is outside the verified-safe set.
2222                let p = self
2223                    .kid(o, "projection")
2224                    .ok_or_else(|| not_pushed(Refusal::Join, "a bare '$$N' reference".into()))?;
2225                let col = self.projection_col(p)?;
2226                let col = self.sql_ident(&col, "column name")?;
2227                if matches!(self.prop(o, "index"), Some(Value::Int(0))) {
2228                    // `$$0::col` — the driver, legal only inside the
2229                    // joined expression's ON bracket (the parser
2230                    // refuses it anywhere else).
2231                    if !self.in_on {
2232                        return Err(not_pushed(
2233                            Refusal::Join,
2234                            "a '$$0' reference outside the join's ON".into(),
2235                        ));
2236                    }
2237                    if self.kid(o, "step").is_some() {
2238                        return Err(not_pushed(
2239                            Refusal::Join,
2240                            "a '$$0' reference beyond a plain column ($$0::col)".into(),
2241                        ));
2242                    }
2243                    return Ok(format!("{}.{col}", self.from_sql.clone()));
2244                }
2245                if self.in_on {
2246                    return Err(not_pushed(
2247                        Refusal::Join,
2248                        "a '$$N' reference inside the ON (the driver is '$$0')".into(),
2249                    ));
2250                }
2251                let Some(join) = self.join_sql.clone() else {
2252                    return Err(not_pushed(
2253                        Refusal::Join,
2254                        "a '$$N' reference outside a correlation join".into(),
2255                    ));
2256                };
2257                match self.prop(o, "index") {
2258                    Some(Value::Int(1)) => Ok(format!("{join}.{col}")),
2259                    None => Err(not_pushed(Refusal::Join, "a bare '$$N' reference".into())),
2260                    Some(v) => Err(not_pushed(
2261                        Refusal::Join,
2262                        format!("$${v} beyond a two-branch correlation"),
2263                    )),
2264                }
2265            }
2266            "invoking" => {
2267                // `$$__::col` — the invoking position of an enclosing
2268                // query body, never the driver (that is `$$0`, a
2269                // context of index 0, since draft 153). SQL has no
2270                // enclosing body to read.
2271                Err(not_pushed(
2272                    Refusal::Join,
2273                    "a '$$__' reference (the driver inside the ON is '$$0')".into(),
2274                ))
2275            }
2276            "arith" => {
2277                let op = self.prop_s(o, "op");
2278                let kids = self.arbor.children(o);
2279                let l = self.operand(kids[0], qual)?;
2280                let r = self.operand(kids[1], qual)?;
2281                Ok(match op.as_str() {
2282                    "+" | "-" | "*" => format!("({l} {op} {r})"),
2283                    "div" => format!("({l} / {r})"),
2284                    "mod" => format!("({l} % {r})"),
2285                    other => {
2286                        return Err(not_pushed(
2287                            Refusal::Operator,
2288                            format!("'{other}' arithmetic"),
2289                        ));
2290                    }
2291                })
2292            }
2293            other => Err(not_pushed(
2294                Refusal::State,
2295                format!(
2296                    "the '{other}' operand (registers, topics, and captures are Quarb-side state)"
2297                ),
2298            )),
2299        }
2300    }
2301
2302    fn projection_col(&mut self, p: NodeId) -> Result<String, SqlError> {
2303        match self.prop_s(p, "kind").as_str() {
2304            "property" => match self.prop(p, "key") {
2305                Some(k) => Ok(k.to_string()),
2306                None => Err(not_pushed(
2307                    Refusal::Operator,
2308                    "the bare '::' projection (name the column)".into(),
2309                )),
2310            },
2311            other => Err(not_pushed(
2312                Refusal::Operator,
2313                format!("the {other} metadata projection"),
2314            )),
2315        }
2316    }
2317
2318    /// The column a plain column operand names (`::col`, `$*1::col`):
2319    /// a path without a step, or a context reference, projecting a
2320    /// named property.
2321    /// A numeric reducer (`sum`, `mean`, `min`, `max`) pushed over a
2322    /// column is the scan's only on a numeric-typed column: the
2323    /// scan lifts unit text (`'18 parasang'` under a declared unit)
2324    /// to quantities and orders texts as texts, where SQL sums a
2325    /// text column by its leading digits and orders it by
2326    /// collation. Recorded for the caller's catalog as a
2327    /// comparison's assumption is.
2328    fn assume_numeric(&mut self, column: Option<String>) {
2329        if !self.strict {
2330            return;
2331        }
2332        if let Some(c) = column
2333            && !self.column_types.numeric.contains(&c)
2334        {
2335            self.column_types.numeric.push(c);
2336        }
2337    }
2338
2339    fn column_operand(&self, o: NodeId) -> Option<String> {
2340        match self.kind(o).as_str() {
2341            "path" if self.kid(o, "step").is_none() => {}
2342            "context" => {}
2343            _ => return None,
2344        }
2345        let p = self.kid(o, "projection")?;
2346        if self.prop_s(p, "kind") != "property" {
2347            return None;
2348        }
2349        self.prop(p, "key").map(|k| k.to_string())
2350    }
2351
2352    /// Whether `o` is a text string literal (`'London'`).
2353    fn is_text_literal(&self, o: NodeId) -> bool {
2354        self.kind(o) == "literal" && self.prop_s(o, "type") == "text"
2355    }
2356
2357    /// If `o` is the one JSON-column-path shape pushdown handles —
2358    /// `/col/seg/seg…::`, a plain-navigation path (every step `/`
2359    /// and a plain-identifier object key, no wildcards, no nested
2360    /// predicate), at least one segment past the column, ending in
2361    /// the bare `::` projection — return `(column, [json segments])`.
2362    /// Anything else is `None` (and falls back to the graft).
2363    fn json_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2364        if self.kind(o) != "path" {
2365            return None;
2366        }
2367        let steps = self.kids(o, "step");
2368        if steps.len() < 2 {
2369            return None;
2370        }
2371        // The projection must be the bare `::` (default value of
2372        // the JSON leaf), not `::key` or a `:::`/`:` metadata form.
2373        let proj = self.kid(o, "projection")?;
2374        if self.prop_s(proj, "kind") != "property" || self.prop(proj, "key").is_some() {
2375            return None;
2376        }
2377        let mut names = Vec::with_capacity(steps.len());
2378        for s in &steps {
2379            if self.prop_s(*s, "axis") != "/"
2380                || self.prop_s(*s, "matcher-kind") != "name"
2381                || self.kid(*s, "predicate").is_some()
2382            {
2383                return None;
2384            }
2385            let name = self.prop_s(*s, "matcher");
2386            // Plain object keys only — no array indices, no
2387            // characters that would need per-dialect path escaping.
2388            let plain = !name.is_empty()
2389                && name
2390                    .chars()
2391                    .next()
2392                    .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2393                && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
2394            if !plain {
2395                return None;
2396            }
2397            names.push(name);
2398        }
2399        let col = names.remove(0);
2400        Some((col, names))
2401    }
2402
2403    /// The property form of a JSON-column path, `/col/seg…::key`:
2404    /// plain-navigation steps as in [`json_path`], at least the
2405    /// column's own, ending in the projection of a plain-identifier
2406    /// property. It asks for the same value as `/col/seg…/key::`
2407    /// where that is a scalar; on an array of scalars it is the
2408    /// list (see [`json_property_prefilter`]). Returns
2409    /// `(column, [json segments, the key last])`.
2410    ///
2411    /// [`json_path`]: Self::json_path
2412    /// [`json_property_prefilter`]: Self::json_property_prefilter
2413    fn json_property_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2414        if self.kind(o) != "path" {
2415            return None;
2416        }
2417        let steps = self.kids(o, "step");
2418        if steps.is_empty() {
2419            return None;
2420        }
2421        let proj = self.kid(o, "projection")?;
2422        if self.prop_s(proj, "kind") != "property" {
2423            return None;
2424        }
2425        let key = self.prop(proj, "key")?.to_string();
2426        let plain = |name: &str| {
2427            !name.is_empty()
2428                && name
2429                    .chars()
2430                    .next()
2431                    .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2432                && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
2433        };
2434        if !plain(&key) {
2435            return None;
2436        }
2437        let mut names = Vec::with_capacity(steps.len() + 1);
2438        for s in &steps {
2439            if self.prop_s(*s, "axis") != "/"
2440                || self.prop_s(*s, "matcher-kind") != "name"
2441                || self.kid(*s, "predicate").is_some()
2442            {
2443                return None;
2444            }
2445            let name = self.prop_s(*s, "matcher");
2446            if !plain(&name) {
2447                return None;
2448            }
2449            names.push(name);
2450        }
2451        names.push(key);
2452        let col = names.remove(0);
2453        Some((col, names))
2454    }
2455
2456    /// A safe `AS` alias: bare when it is a plain identifier and
2457    /// not an SQL keyword; otherwise strict mode refuses (quoting
2458    /// dialects disagree) and export mode double-quotes, noting it.
2459    fn alias(&mut self, name: &str) -> Result<String, SqlError> {
2460        if is_plain_ident(name) {
2461            return Ok(name.to_string());
2462        }
2463        if self.strict {
2464            return Err(not_pushed(
2465                Refusal::Name,
2466                format!(
2467                    "field name {name:?} needs SQL quoting \
2468                 (dialects disagree); rename the field"
2469                ),
2470            ));
2471        }
2472        self.notes
2473            .push(format!("field name {name:?} double-quoted (ANSI)"));
2474        Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2475    }
2476
2477    /// A table or column name rendered into SQL. Bare when it is a
2478    /// plain identifier; otherwise strict mode refuses — a name
2479    /// like `a OR b` would silently rewrite the emitted SQL's
2480    /// meaning, breaking the provably-identical guarantee (and a
2481    /// portable quoting does not exist) — and export mode
2482    /// double-quotes with a note.
2483    fn sql_ident(&mut self, name: &str, what: &str) -> Result<String, SqlError> {
2484        if is_plain_ident(name) {
2485            return Ok(name.to_string());
2486        }
2487        if self.strict {
2488            return Err(not_pushed(
2489                Refusal::Name,
2490                format!("{what} {name:?} is not a plain SQL identifier"),
2491            ));
2492        }
2493        self.notes
2494            .push(format!("{what} {name:?} double-quoted (ANSI)"));
2495        Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2496    }
2497
2498    /// Split a joined-side predicate: `col = $*1::col2` equalities
2499    /// become the ON condition; everything else the WHERE.
2500    /// `ltable` and `rtable` are the tables' SQL renderings.
2501    fn split_join_pred(
2502        &mut self,
2503        p: NodeId,
2504        rtable: &str,
2505        on: &mut Vec<String>,
2506        wheres: &mut Vec<String>,
2507    ) -> Result<(), SqlError> {
2508        if self.prop_s(p, "kind") != "expr" {
2509            return Err(not_pushed(
2510                Refusal::Take,
2511                "a positional predicate on the joined side".into(),
2512            ));
2513        }
2514        // Flatten top-level ANDs; each conjunct routes to ON or
2515        // WHERE.
2516        fn conjuncts(ex: &Exporter, e: NodeId, out: &mut Vec<NodeId>) {
2517            if ex.kind(e) == "and" {
2518                for c in ex.arbor.children(e) {
2519                    conjuncts(ex, c, out);
2520                }
2521            } else {
2522                out.push(e);
2523            }
2524        }
2525        let mut parts = Vec::new();
2526        for c in self.arbor.children(p) {
2527            conjuncts(self, c, &mut parts);
2528        }
2529        for e in parts {
2530            let uses_driver = self.subtree_has_driver(e);
2531            self.in_on = true;
2532            let cond = self.pred_expr(e, Some(rtable));
2533            self.in_on = false;
2534            let cond = cond?;
2535            if uses_driver && self.kind(e) == "compare" && self.prop_s(e, "op") == "=" {
2536                // Record which joined-table columns the ON binds —
2537                // the uniqueness obligation (see
2538                // Pushdown::join_left). Collected from the arbor's
2539                // bare-column operand nodes, never from the
2540                // rendered SQL text, so neither a literal nor an
2541                // unusual column name can corrupt the obligation.
2542                self.collect_join_cols(e)?;
2543                on.push(cond);
2544            } else {
2545                wheres.push(cond);
2546            }
2547        }
2548        Ok(())
2549    }
2550
2551    /// The joined-table columns the ON equality binds: every bare
2552    /// column operand (`::col`) in `e`'s subtree, appended to the
2553    /// join obligation with their raw (catalog) names.
2554    fn collect_join_cols(&mut self, e: NodeId) -> Result<(), SqlError> {
2555        // The `$$0` side is the driver — not part of the joined
2556        // table's obligation.
2557        if self.is_driver(e) {
2558            return Ok(());
2559        }
2560        if self.kind(e) == "path"
2561            && self.kid(e, "step").is_none()
2562            && let Some(p) = self.kid(e, "projection")
2563        {
2564            let col = self.projection_col(p)?;
2565            self.join_on_cols.push(col);
2566        }
2567        for c in self.arbor.children(e) {
2568            self.collect_join_cols(c)?;
2569        }
2570        Ok(())
2571    }
2572
2573    /// `$$0`: a context operand of index 0 (the driver), or a read
2574    /// of the driver's row through its mark (`$$.t::col`).
2575    fn is_driver(&self, n: NodeId) -> bool {
2576        (self.kind(n) == "context" && matches!(self.prop(n, "index"), Some(Value::Int(0))))
2577            || (self.kind(n) == "path"
2578                && matches!(self.mark_anchor(n).0, Some(name) if self.from_marks.contains(&name)))
2579    }
2580
2581    fn subtree_has_driver(&self, n: NodeId) -> bool {
2582        self.is_driver(n)
2583            || self
2584                .arbor
2585                .children(n)
2586                .into_iter()
2587                .any(|c| self.subtree_has_driver(c))
2588    }
2589
2590    /// Consume the pipeline into SELECT clauses. `projected` is the
2591    /// driving path's own terminal projection, where it has one:
2592    /// the column as SQL and its name.
2593    fn pipeline(
2594        &mut self,
2595        q: NodeId,
2596        sel: &mut Select,
2597        join: Option<(&str, &str)>,
2598        projected: Option<(String, String)>,
2599    ) -> Result<(), SqlError> {
2600        let Some(pipe) = self.kid(q, "pipeline") else {
2601            return Ok(());
2602        };
2603        let commands: Vec<NodeId> = self.arbor.children(pipe);
2604        let mut i = 0;
2605        // A pending per-row value (`| ::col`) feeding an aggregate,
2606        // and the column it names where it is one. The path's own
2607        // projection is that value from the start, so the glued
2608        // spelling plans as the piped one: `/t/*::col @| max` is
2609        // `/t/* | ::col @| max` (it was refused as a reducer "over
2610        // row nodes", with a hint to write the piped form).
2611        let (mut pending_col, mut pending_name) = match projected {
2612            Some((col, name)) => (Some(col), Some(name)),
2613            None => (None, None),
2614        };
2615        // After a grouped reduction: (key, agg_sql, alias).
2616        let mut grouped: Option<(String, String, String)> = None;
2617        // A pushed key awaiting its fold: (the regula's name, key_sql).
2618        let mut pushed_key: Option<(String, String)> = None;
2619        // …and the column it is, where it is one plain column.
2620        let mut pushed_key_column: Option<String> = None;
2621        // The regula a fold went by: the name its key has in the
2622        // record `%.` answers.
2623        let mut grouped_reg: Option<String> = None;
2624
2625        while i < commands.len() {
2626            let s = commands[i];
2627            match self.kind(s).as_str() {
2628                "expr" => {
2629                    let kids = self.arbor.children(s);
2630                    pending_col = Some(self.operand(kids[0], join.map(|(l, _)| l))?);
2631                    pending_name = self.column_operand(kids[0]);
2632                }
2633                "cmd" => {
2634                    let name = self.prop_s(s, "name");
2635                    match name.as_str() {
2636                        "rec" | "record" => {
2637                            sel.select = self.record_fields(s, join)?;
2638                            self.order.record = true;
2639                        }
2640                        // `| %` on a row node is the record of its
2641                        // properties, which are the row's columns in
2642                        // the table's order: SELECT *, a record even
2643                        // of one field. It is the plan a bare
2644                        // selection of row nodes had before the
2645                        // ruling of 2026-11-18 gave that one its
2646                        // locators. Last in the pipeline and over
2647                        // the rows themselves: after a projection
2648                        // the thread holds a value, and a joined
2649                        // row's record is the driver's alone.
2650                        "%" if self.strict
2651                            && join.is_none()
2652                            && sel.select.is_empty()
2653                            && pending_col.is_none()
2654                            && grouped.is_none()
2655                            && pushed_key.is_none()
2656                            && !self.aggregate
2657                            && self.arbor.children(s).is_empty()
2658                            && i + 1 == commands.len() =>
2659                        {
2660                            sel.select = vec!["*".to_string()];
2661                            self.order.record = true;
2662                            self.order.properties = true;
2663                        }
2664                        // A reducing aggregate on the plain pipe:
2665                        // the grouped reduction.
2666                        "count" | "sum" | "mean" | "min" | "max" => {
2667                            let (key, _, _) = grouped.as_ref().ok_or_else(|| {
2668                                not_pushed(
2669                                    Refusal::Reducer,
2670                                    format!("'| {name}' outside a group (use '@| {name}')"),
2671                                )
2672                            })?;
2673                            // Quarb's count counts every member,
2674                            // nulls included: COUNT(*); the
2675                            // NULL-skipping COUNT(col) is
2676                            // `count(--values)`.
2677                            let values =
2678                                self.reducer_counts_values(s, &name, pending_col.is_some())?;
2679                            let col = if name == "count" {
2680                                pending_col.take().filter(|_| values)
2681                            } else {
2682                                self.assume_numeric(pending_name.take());
2683                                pending_col.take()
2684                            };
2685                            let agg = sql_agg(&name, col)?;
2686                            grouped = Some((key.clone(), agg.clone(), agg));
2687                        }
2688                        other => {
2689                            // sort/unique/top and kin are spellable
2690                            // in SQL but with the backend's own
2691                            // collation and duplicate semantics —
2692                            // name the divergence, not a missing
2693                            // feature.
2694                            if matches!(other, "sort" | "sort_by" | "unique" | "top" | "bottom") {
2695                                return Err(mismatch(
2696                                    if other == "unique" {
2697                                        Refusal::Unique
2698                                    } else {
2699                                        Refusal::Sort
2700                                    },
2701                                    format!(
2702                                        "'{other}' means the backend's collation and \
2703                                     duplicate semantics; one engine-side ordering \
2704                                     keeps it identical everywhere"
2705                                    ),
2706                                ));
2707                            }
2708                            return Err(not_pushed(
2709                                Refusal::Operator,
2710                                format!("the '{other}' pipeline command"),
2711                            ));
2712                        }
2713                    }
2714                }
2715                "push" => {
2716                    // An alias for the grouped aggregate.
2717                    if let Some((k, agg, _)) = grouped.take() {
2718                        let alias = self.prop_s(s, "name");
2719                        grouped = Some((k, agg, alias));
2720                    } else {
2721                        return Err(not_pushed(
2722                            Refusal::State,
2723                            "a register push (Quarb-side state)".into(),
2724                        ));
2725                    }
2726                }
2727                // `| .k(::k)` before a fold by `.k`: the GROUP BY key
2728                // (a projection body is a subcontext of one branch).
2729                "expr-push" if grouped.is_none() && pushed_key.is_none() => {
2730                    let kids = self.arbor.children(s);
2731                    let key = self.operand(kids[0], join.map(|(l, _)| l))?;
2732                    pushed_key = Some((self.prop_s(s, "name"), key));
2733                    pushed_key_column = self.column_operand(kids[0]);
2734                }
2735                "subcontext" if grouped.is_none() && pushed_key.is_none() => {
2736                    let key = self.pushed_column(s, join.map(|(l, _)| l))?;
2737                    // (unqualified, the SQL is the column's own name)
2738                    pushed_key_column = join.is_none().then(|| key.clone());
2739                    pushed_key = Some((self.prop_s(s, "name"), key));
2740                }
2741                "filter" => {
2742                    if grouped.is_some() {
2743                        // HAVING: `$_` / the alias refer to the
2744                        // aggregate.
2745                        let cond = self.having_cond(s)?;
2746                        sel.having = Some(cond);
2747                    } else {
2748                        return Err(not_pushed(
2749                            Refusal::State,
2750                            "a mid-pipeline filter (put it in the row predicate)".into(),
2751                        ));
2752                    }
2753                }
2754                "recall" => {
2755                    // `| %.` finalizes the grouped record.
2756                    if self.prop_s(s, "ref") != "%." {
2757                        return Err(not_pushed(
2758                            Refusal::State,
2759                            "a register recall (Quarb-side state)".into(),
2760                        ));
2761                    }
2762                    let (key, agg, alias) = grouped.clone().ok_or_else(|| {
2763                        not_pushed(Refusal::Fold, "'%.', with nothing grouped".into())
2764                    })?;
2765                    let alias = self.alias(&alias)?;
2766                    // The record names the key by its regula (`.a`),
2767                    // which need not be the column's name: the scan
2768                    // answers %(a = …), and so must the plan.
2769                    let key_field = match &grouped_reg {
2770                        Some(reg) if *reg != key => format!("{key} AS {}", self.alias(reg)?),
2771                        _ => key.clone(),
2772                    };
2773                    sel.select = vec![key_field, format!("{agg} AS {alias}")];
2774                    self.order.record = true;
2775                    // The HAVING condition compared the aggregate
2776                    // through $_ — substitute the real expression.
2777                    if let Some(h) = sel.having.take() {
2778                        sel.having = Some(h.replace("__AGG__", &agg));
2779                    }
2780                }
2781                "agg" if self.prop(s, "group").is_some() => {
2782                    // The plan takes its first rows last: a command
2783                    // over the rows a selection kept is the engine's.
2784                    if self.strict && self.order.limit.is_some() {
2785                        return Err(not_pushed(
2786                            Refusal::Take,
2787                            format!(
2788                                "the '{}' command after a positional selection (a plan \
2789                                 takes its first rows last)",
2790                                self.prop_s(s, "name")
2791                            ),
2792                        ));
2793                    }
2794                    // `@|{.k} agg`: the fold by the pushed key is the
2795                    // grouped reduction, GROUP BY key.
2796                    let name = self.prop_s(s, "name");
2797                    if !matches!(name.as_str(), "count" | "sum" | "mean" | "min" | "max") {
2798                        return Err(not_pushed(
2799                            Refusal::Fold,
2800                            format!("the '{name}' command per group (GROUP BY reduces)"),
2801                        ));
2802                    }
2803                    let selector = self.prop_s(s, "group");
2804                    if selector.contains(';') {
2805                        return Err(not_pushed(
2806                            Refusal::Fold,
2807                            "a fold by several regulae (one GROUP BY key translates)".into(),
2808                        ));
2809                    }
2810                    let (reg, key) = pushed_key.take().ok_or_else(|| {
2811                        not_pushed(
2812                            Refusal::Fold,
2813                            "a fold by a regula no push of a key made".into(),
2814                        )
2815                    })?;
2816                    grouped_reg = Some(reg.clone());
2817                    if selector != "." && selector != format!(".{reg}") {
2818                        return Err(not_pushed(
2819                            Refusal::Fold,
2820                            format!("a fold by '{selector}' (the pushed key is '.{reg}')"),
2821                        ));
2822                    }
2823                    if self.strict {
2824                        // SQL gives its groups in no stated order; the
2825                        // engine gives them as each first appears. A
2826                        // fold by one numeric column of the table is
2827                        // pushed with that order asked of the driver
2828                        // (the least key of each group). Numeric: two
2829                        // texts that read as one number are one key
2830                        // to the engine and two to GROUP BY.
2831                        let plain = join.is_none()
2832                            && self.order.sort.is_none()
2833                            && self.order.limit.is_none()
2834                            && !self.order.reversed;
2835                        match pushed_key_column.take() {
2836                            Some(column) if plain => {
2837                                self.assume_numeric(Some(column.clone()));
2838                                self.order.groups = true;
2839                                self.order.keyed_by = Some((Refusal::Fold, column));
2840                            }
2841                            _ => {
2842                                return Err(mismatch(
2843                                    Refusal::Fold,
2844                                    "a fold over a join, or after a sort or a selection, or by \
2845                                     anything but one column"
2846                                        .into(),
2847                                ));
2848                            }
2849                        }
2850                    }
2851                    sel.group_by = Some(key.clone());
2852                    let values = self.reducer_counts_values(s, &name, pending_col.is_some())?;
2853                    let col = if name == "count" {
2854                        // `count(--values)` over a projected column is
2855                        // COUNT(col); the bare count is every row
2856                        pending_col.take().filter(|_| values)
2857                    } else {
2858                        self.assume_numeric(pending_name.take());
2859                        pending_col.take()
2860                    };
2861                    let agg = sql_agg(&name, col)?;
2862                    grouped = Some((key, agg.clone(), agg));
2863                }
2864                "agg" => {
2865                    // The plan takes its first rows last: a command
2866                    // over the rows a selection kept is the engine's.
2867                    if self.strict && self.order.limit.is_some() {
2868                        return Err(not_pushed(
2869                            Refusal::Take,
2870                            format!(
2871                                "the '{}' command after a positional selection (a plan \
2872                                 takes its first rows last)",
2873                                self.prop_s(s, "name")
2874                            ),
2875                        ));
2876                    }
2877                    let name = self.prop_s(s, "name");
2878                    match name.as_str() {
2879                        "count" | "sum" | "mean" | "min" | "max" => {
2880                            // Quarb's count counts every row, nulls
2881                            // included: COUNT(*) regardless of a
2882                            // pending column. `count(--values)`
2883                            // counts the values other than null:
2884                            // COUNT(col) over a projected column.
2885                            let values =
2886                                self.reducer_counts_values(s, &name, pending_col.is_some())?;
2887                            let col = if name == "count" {
2888                                pending_col.take().filter(|_| values)
2889                            } else {
2890                                self.assume_numeric(pending_name.take());
2891                                pending_col.take()
2892                            };
2893                            sel.select = vec![sql_agg(&name, col)?];
2894                            self.aggregate = true;
2895                        }
2896                        "sort_by" if self.strict => {
2897                            // A database orders text by its own
2898                            // collation. A sort by one numeric column
2899                            // of the table has one order everywhere:
2900                            // it is pushed, the key recorded for the
2901                            // catalog to confirm, a null key last and
2902                            // the ties in the table's order, which the
2903                            // driver's ORDER BY says after the plan's.
2904                            let kids = self.arbor.children(s);
2905                            let column = kids.first().and_then(|&k| self.column_operand(k));
2906                            let plain = join.is_none()
2907                                && self.order.sort.is_none()
2908                                && self.order.limit.is_none()
2909                                && !self.order.reversed
2910                                && !self.order.groups
2911                                && !self.aggregate
2912                                && grouped.is_none();
2913                            let column = match (column, plain) {
2914                                (Some(column), true) => column,
2915                                // one column, and no place for its
2916                                // order in the plan
2917                                (Some(_), false) => {
2918                                    return Err(not_pushed(
2919                                        Refusal::Sort,
2920                                        "a sort over a join, or after a selection, a fold or \
2921                                         another sort (a plan has one order)"
2922                                            .into(),
2923                                    ));
2924                                }
2925                                (None, _) => {
2926                                    return Err(mismatch(
2927                                        Refusal::Sort,
2928                                        "ORDER BY collations differ per engine".into(),
2929                                    ));
2930                                }
2931                            };
2932                            let mut desc = false;
2933                            for &k in &kids[1..] {
2934                                let named =
2935                                    (self.kind(k) == "option").then(|| self.prop_s(k, "name"));
2936                                match named.as_deref() {
2937                                    Some("--desc" | "-d") => desc = true,
2938                                    _ => {
2939                                        return Err(mismatch(
2940                                            Refusal::Sort,
2941                                            "ORDER BY collations differ per engine".into(),
2942                                        ));
2943                                    }
2944                                }
2945                            }
2946                            let e = self.operand(kids[0], None)?;
2947                            self.assume_numeric(Some(column.clone()));
2948                            self.order.sort = Some((e, desc));
2949                            self.order.keyed_by = Some((Refusal::Sort, column));
2950                        }
2951                        "sort_by" => {
2952                            // A sort after a positional selection
2953                            // (or a second sort) cannot render: the
2954                            // fixed SELECT shape orders before
2955                            // LIMIT, and has one ORDER BY.
2956                            if sel.limit.is_some() {
2957                                return Err(not_pushed(
2958                                    Refusal::Sort,
2959                                    "a sort after a positional selection (SQL orders \
2960                                     before LIMIT)"
2961                                        .into(),
2962                                ));
2963                            }
2964                            if sel.order_by.is_some() {
2965                                return Err(not_pushed(
2966                                    Refusal::Sort,
2967                                    "a second sort (SQL has a single ORDER BY)".into(),
2968                                ));
2969                            }
2970                            let kids = self.arbor.children(s);
2971                            // The options are the command's own:
2972                            // `--desc` is the direction, a named
2973                            // collation (`--locale=tag`, ruling
2974                            // 2026-11-11) is the engine's order and no
2975                            // backend's; a second key has no place in
2976                            // the one ORDER BY this shape holds.
2977                            let mut desc = false;
2978                            for &k in &kids[1..] {
2979                                if self.kind(k) != "option" {
2980                                    return Err(not_pushed(
2981                                        Refusal::Sort,
2982                                        "a sort by several keys".into(),
2983                                    ));
2984                                }
2985                                match self.prop_s(k, "name").as_str() {
2986                                    "--desc" | "-d" => desc = true,
2987                                    "--locale" => {
2988                                        return Err(mismatch(
2989                                            Refusal::Sort,
2990                                            "sort_by(--locale=…) names the engine's collation; \
2991                                             a backend's differs"
2992                                                .into(),
2993                                        ));
2994                                    }
2995                                    // a case order is that
2996                                    // collation's (ruling 2026-11-12)
2997                                    "--upper-first" | "-u" | "--lower-first" | "-l"
2998                                    | "--ignore-case" | "-i" => {
2999                                        return Err(mismatch(
3000                                            Refusal::Sort,
3001                                            "sort_by's case order is the engine's collation's; \
3002                                             a backend's differs"
3003                                                .into(),
3004                                        ));
3005                                    }
3006                                    other => {
3007                                        return Err(not_pushed(
3008                                            Refusal::Sort,
3009                                            format!("the '{other}' option of sort_by"),
3010                                        ));
3011                                    }
3012                                }
3013                            }
3014                            let e = self.operand(kids[0], join.map(|(l, _)| l))?;
3015                            sel.order_by = Some((e, desc));
3016                        }
3017                        // The context reversed: every term of the
3018                        // plan's order turned, the keys too.
3019                        "reverse" if self.strict => {
3020                            if self.order.reversed
3021                                || self.order.limit.is_some()
3022                                || self.order.groups
3023                                || self.aggregate
3024                                || grouped.is_some()
3025                            {
3026                                return Err(not_pushed(
3027                                    Refusal::Sort,
3028                                    "reverse after a positional selection, a fold or another \
3029                                     reverse"
3030                                        .into(),
3031                                ));
3032                            }
3033                            self.order.reversed = true;
3034                        }
3035                        "reverse" => match &mut sel.order_by {
3036                            Some((_, desc)) => *desc = true,
3037                            None => {
3038                                return Err(not_pushed(
3039                                    Refusal::Sort,
3040                                    "reverse without an ORDER BY (rows are unordered)".into(),
3041                                ));
3042                            }
3043                        },
3044                        // `top(k; ::n)` and `bottom(k; ::n)` in a plan:
3045                        // the rows whose key is not null, by the key
3046                        // descending or ascending, the ties in the
3047                        // table's order, and the first k of them. A
3048                        // sort and a cut, so the sort's conditions:
3049                        // one numeric column of the table, nothing
3050                        // ordered or cut before.
3051                        "top" | "bottom" if self.strict => {
3052                            let kids = self.arbor.children(s);
3053                            let count = kids.first().and_then(|&k| {
3054                                (self.kind(k) == "literal")
3055                                    .then(|| self.prop(k, "value"))
3056                                    .flatten()
3057                            });
3058                            let column = kids.get(1).and_then(|&k| self.column_operand(k));
3059                            let plain = kids.len() == 2
3060                                && join.is_none()
3061                                && self.order.sort.is_none()
3062                                && self.order.limit.is_none()
3063                                && !self.order.reversed
3064                                && !self.order.groups
3065                                && !self.aggregate
3066                                && grouped.is_none();
3067                            let (Some(Value::Int(k)), Some(column), true) = (count, column, plain)
3068                            else {
3069                                return Err(not_pushed(
3070                                    Refusal::Sort,
3071                                    "'top' and 'bottom' by anything but one column of the \
3072                                     table, under an option, over a join, or after a sort, a \
3073                                     selection or a fold (a plan has one order)"
3074                                        .into(),
3075                                ));
3076                            };
3077                            if k < 1 {
3078                                return Err(not_pushed(
3079                                    Refusal::Sort,
3080                                    "'top' and 'bottom' of no rows".into(),
3081                                ));
3082                            }
3083                            let e = self.operand(kids[1], None)?;
3084                            sel.wheres.push(format!("{e} IS NOT NULL"));
3085                            self.assume_numeric(Some(column.clone()));
3086                            self.order.sort = Some((e, name == "top"));
3087                            self.order.limit = Some(k as u64);
3088                            self.order.keyed_by = Some((Refusal::Sort, column));
3089                        }
3090                        "top" => {
3091                            if sel.limit.is_some() {
3092                                return Err(not_pushed(
3093                                    Refusal::Sort,
3094                                    "'top' after a positional selection (SQL orders \
3095                                     before LIMIT)"
3096                                        .into(),
3097                                ));
3098                            }
3099                            if sel.order_by.is_some() {
3100                                return Err(not_pushed(
3101                                    Refusal::Sort,
3102                                    "a second sort (SQL has a single ORDER BY)".into(),
3103                                ));
3104                            }
3105                            let kids = self.arbor.children(s);
3106                            // the options name the engine's collation
3107                            // and its case order: no backend's (they
3108                            // were dropped, and the SQL ordered as the
3109                            // backend pleased)
3110                            if let Some(&k) = kids
3111                                .get(2..)
3112                                .and_then(|rest| rest.iter().find(|&&k| self.kind(k) == "option"))
3113                            {
3114                                return Err(mismatch(
3115                                    Refusal::Sort,
3116                                    format!(
3117                                        "top({}) names the engine's collation; a backend's differs",
3118                                        self.prop_s(k, "name")
3119                                    ),
3120                                ));
3121                            }
3122                            let n = self.prop_s(kids[0], "value");
3123                            let e = self.operand(kids[1], join.map(|(l, _)| l))?;
3124                            sel.order_by = Some((e, true));
3125                            sel.limit = Some(n);
3126                        }
3127                        "unique" => {
3128                            if self.strict {
3129                                // A count of the distinct values asks
3130                                // for no order: `| ::n @| unique @|
3131                                // count`, the last two commands of the
3132                                // pipeline. COUNT(DISTINCT n) leaves
3133                                // the NULLs out, and a null is one
3134                                // value to `unique`: the plan adds it.
3135                                // The column is a numeric one: two
3136                                // texts that read as one number
3137                                // ('300', '300.0') are one value to
3138                                // the engine and two to DISTINCT.
3139                                let counted = self.arbor.children(s).is_empty()
3140                                    && i + 2 == commands.len()
3141                                    && commands.get(i + 1).is_some_and(|&c| {
3142                                        self.kind(c) == "agg"
3143                                            && self.prop_s(c, "name") == "count"
3144                                            && self.prop(c, "group").is_none()
3145                                            && self.arbor.children(c).is_empty()
3146                                    });
3147                                match (counted, pending_col.take(), pending_name.take()) {
3148                                    (true, Some(col), Some(name)) => {
3149                                        self.assume_numeric(Some(name.clone()));
3150                                        self.order.keyed_by = Some((Refusal::Unique, name));
3151                                        sel.select = vec![format!(
3152                                            "COUNT(DISTINCT {col}) + COALESCE(MAX(CASE WHEN \
3153                                             {col} IS NULL THEN 1 ELSE 0 END), 0)"
3154                                        )];
3155                                        self.aggregate = true;
3156                                        // the count is taken with it
3157                                        i += 2;
3158                                        continue;
3159                                    }
3160                                    _ => {
3161                                        return Err(not_pushed(
3162                                            Refusal::Unique,
3163                                            "DISTINCT returns rows in no stated order (a count \
3164                                             of the distinct values of a numeric column is \
3165                                             pushed: '| ::col @| unique @| count')"
3166                                                .into(),
3167                                        ));
3168                                    }
3169                                }
3170                            }
3171                            // Quarb dedups the limited rows; SQL
3172                            // applies DISTINCT before LIMIT.
3173                            if sel.limit.is_some() {
3174                                return Err(not_pushed(
3175                                    Refusal::Unique,
3176                                    "'unique' after a positional selection (SQL applies \
3177                                     DISTINCT before LIMIT)"
3178                                        .into(),
3179                                ));
3180                            }
3181                            if let Some(c) = pending_col.take() {
3182                                sel.select = vec![c];
3183                            }
3184                            sel.distinct = true;
3185                        }
3186                        other => {
3187                            return Err(not_pushed(
3188                                Refusal::Reducer,
3189                                format!("the '{other}' aggregate"),
3190                            ));
3191                        }
3192                    }
3193                }
3194                // `@| [..n]` in a plan: the first rows of the order the
3195                // driver writes (the plan's own sort, then the keys),
3196                // so the rows the scan's context begins with.
3197                "select" if self.strict => {
3198                    if self.order.limit.is_some()
3199                        || self.order.groups
3200                        || self.aggregate
3201                        || grouped.is_some()
3202                        || pushed_key.is_some()
3203                    {
3204                        return Err(not_pushed(
3205                            Refusal::Take,
3206                            "a positional selection after a reducer, a fold or another \
3207                             selection"
3208                                .into(),
3209                        ));
3210                    }
3211                    let p = self.arbor.children(s)[0];
3212                    match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3213                        ("range", Some(Value::Int(n)))
3214                            if self.prop(p, "from").is_none() && n > 0 =>
3215                        {
3216                            self.order.limit = Some(n as u64);
3217                        }
3218                        _ => {
3219                            return Err(not_pushed(
3220                                Refusal::Take,
3221                                "positional selection beyond '@| [..n]'".into(),
3222                            ));
3223                        }
3224                    }
3225                }
3226                "select" => {
3227                    // `@| [..n]` → LIMIT.
3228                    if sel.limit.is_some() {
3229                        return Err(not_pushed(
3230                            Refusal::Take,
3231                            "a second positional selection".into(),
3232                        ));
3233                    }
3234                    let p = self.arbor.children(s)[0];
3235                    match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3236                        ("range", Some(Value::Int(n)))
3237                            if self.prop(p, "from").is_none() && n > 0 =>
3238                        {
3239                            sel.limit = Some(n.to_string());
3240                        }
3241                        _ => {
3242                            return Err(not_pushed(
3243                                Refusal::Take,
3244                                "positional selection beyond '@| [..n]'".into(),
3245                            ));
3246                        }
3247                    }
3248                }
3249                other => {
3250                    return Err(not_pushed(
3251                        Refusal::Operator,
3252                        format!(
3253                            "the '{other}' command (windows, subcontexts, and registers are \
3254                         Quarb-side state)"
3255                        ),
3256                    ));
3257                }
3258            }
3259            i += 1;
3260        }
3261        // A pending column with no aggregate is a one-column select.
3262        if let Some(c) = pending_col
3263            && sel.select.is_empty()
3264        {
3265            sel.select = vec![c];
3266        }
3267        // A plan answers row nodes as their rows, where the scan
3268        // answers the nodes: a sorted, reversed or cut selection of
3269        // nodes was the scan's to answer, and stays so; with a
3270        // projection or a record after it, it is the plan's.
3271        if self.strict
3272            && sel.select.is_empty()
3273            && (self.order.sort.is_some() || self.order.reversed || self.order.limit.is_some())
3274        {
3275            let word = if self.order.limit.is_some() {
3276                Refusal::Take
3277            } else {
3278                Refusal::Sort
3279            };
3280            return Err(not_pushed(
3281                word,
3282                "a sorted, reversed or cut selection of row nodes (project a column or build \
3283                 a record after it: '| ::col', '| %(…)')"
3284                    .into(),
3285            ));
3286        }
3287        // A grouped reduction never recorded (`@|{.k} count` with no
3288        // `| .n | %.`) answers one value per group: the aggregate
3289        // alone, grouped by the key.
3290        if let Some((_, agg, _)) = grouped
3291            && sel.select.is_empty()
3292        {
3293            sel.select = vec![agg];
3294        }
3295        Ok(())
3296    }
3297
3298    /// The column a pushed projection body names — `.k(::k)` is a
3299    /// subcontext whose one branch is the bare projection; any
3300    /// other body is Quarb-side state.
3301    fn pushed_column(&mut self, s: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
3302        let body = || {
3303            let q = self.kid(s, "query")?;
3304            let b = self.kid(q, "branch")?;
3305            let p = self.kid(b, "projection")?;
3306            let bare = self.kids(q, "branch").len() == 1
3307                && self.kids(q, "pipeline").is_empty()
3308                && self.arbor.children(b).len() == 1
3309                && self.prop_s(p, "kind") == "property";
3310            bare.then_some(p)
3311        };
3312        let p = body()
3313            .ok_or_else(|| not_pushed(Refusal::State, "a pushed body (Quarb-side state)".into()))?;
3314        let col = self.projection_col(p)?;
3315        let col = self.sql_ident(&col, "column name")?;
3316        Ok(match qual {
3317            Some(q) => format!("{q}.{col}"),
3318            None => col,
3319        })
3320    }
3321
3322    /// A HAVING filter: `$_` and `$.name` refer to the aggregate.
3323    fn having_cond(&mut self, s: NodeId) -> Result<String, SqlError> {
3324        let kids = self.arbor.children(s);
3325        if kids.len() != 1 || self.kind(kids[0]) != "compare" {
3326            return Err(not_pushed(
3327                Refusal::Fold,
3328                "HAVING translates for a single comparison".into(),
3329            ));
3330        }
3331        let e = kids[0];
3332        let op = self.prop_s(e, "op");
3333        let cmp_kids = self.arbor.children(e);
3334        let l = match self.kind(cmp_kids[0]).as_str() {
3335            "topic" | "recall" => "__AGG__".to_string(),
3336            _ => {
3337                return Err(not_pushed(
3338                    Refusal::Fold,
3339                    "HAVING compares the aggregate ($_ or its register)".into(),
3340                ));
3341            }
3342        };
3343        let r = self.operand(cmp_kids[1], None)?;
3344        Ok(format!("{l} {op} {r}"))
3345    }
3346
3347    /// `rec(...)` fields as a select list.
3348    fn record_fields(
3349        &mut self,
3350        s: NodeId,
3351        join: Option<(&str, &str)>,
3352    ) -> Result<Vec<String>, SqlError> {
3353        let kids = self.arbor.children(s);
3354        let mut fields = Vec::new();
3355        let mut i = 0;
3356        while i < kids.len() {
3357            let k = kids[i];
3358            if self.kind(k) == "literal" {
3359                let name = self.prop_s(k, "value");
3360                let value = self.operand(kids[i + 1], join.map(|(l, _)| l))?;
3361                let name = self.alias(&name)?;
3362                fields.push(format!("{value} AS {name}"));
3363                i += 2;
3364            } else {
3365                let value = self.operand(k, join.map(|(l, _)| l))?;
3366                fields.push(value);
3367                i += 1;
3368            }
3369        }
3370        Ok(fields)
3371    }
3372}
3373
3374impl Exporter {
3375    /// What a reducer's own arguments ask of the plan. A pushed
3376    /// reducer is the bare command: `count` is COUNT(*), `sum` is
3377    /// SUM(col). `count(--values)` counts the values other than
3378    /// null, which over a projected column is what COUNT(col)
3379    /// counts.
3380    /// Any other option, and any operand, changes what is reduced
3381    /// (`--nulls`, `--of=`, `--by=`), and the reducer stays with the
3382    /// engine. The plan took no notice of them until 0.68:
3383    /// `count(--values)` and `count(--nulls)` were both answered as
3384    /// COUNT(*), where the scan counts five and one of six.
3385    fn reducer_counts_values(
3386        &self,
3387        s: NodeId,
3388        name: &str,
3389        projected: bool,
3390    ) -> Result<bool, SqlError> {
3391        let mut values = false;
3392        for k in self.arbor.children(s) {
3393            if self.kind(k) != "option" {
3394                return Err(not_pushed(
3395                    Refusal::Reducer,
3396                    format!("an operand of '{name}'"),
3397                ));
3398            }
3399            match (name, self.prop_s(k, "name").as_str()) {
3400                ("count", "--values" | "-v") => values = true,
3401                (_, option) => {
3402                    return Err(not_pushed(
3403                        Refusal::Reducer,
3404                        format!("the '{option}' option of '{name}'"),
3405                    ));
3406                }
3407            }
3408        }
3409        // a row node is no value: what the count answers there is
3410        // the engine's to say
3411        if values && !projected {
3412            return Err(not_pushed(
3413                Refusal::Reducer,
3414                "'count(--values)' over row nodes (project a column: '/table/*::col @| \
3415                 count(--values)')"
3416                    .into(),
3417            ));
3418        }
3419        Ok(values)
3420    }
3421}
3422
3423fn sql_agg(name: &str, col: Option<String>) -> Result<String, SqlError> {
3424    let f = match name {
3425        "count" => "COUNT",
3426        "sum" => "SUM",
3427        "mean" => "AVG",
3428        "min" => "MIN",
3429        "max" => "MAX",
3430        _ => unreachable!("checked by caller"),
3431    };
3432    match col {
3433        Some(c) => Ok(format!("{f}({c})")),
3434        // Only COUNT aggregates bare rows; SUM(*) and friends are
3435        // not SQL.
3436        None if f == "COUNT" => Ok("COUNT(*)".to_string()),
3437        None => Err(not_pushed(
3438            Refusal::Reducer,
3439            format!("'{name}' over row nodes (project a column: '/table/*::col @| {name}')"),
3440        )),
3441    }
3442}
3443
3444#[cfg(test)]
3445mod null_and_literal_tests {
3446    use super::{Dialect, export, partial_pushdown, pushdown};
3447
3448    // Grouped pipeline that never pushes, so `partial_pushdown` hinges
3449    // only on the leading predicate (mirrors the crate's partial gate).
3450    const GROUPED: &str = " | ::x | .g(::x) @|{.g} count | .n | %.";
3451
3452    #[test]
3453    fn pattern_literal_pushes_as_like() {
3454        // Ruling #33: segments in order, a `%` per star, LIKE's
3455        // metacharacters escaped. Strict push only where LIKE is
3456        // provably case-sensitive (PostgreSQL); everywhere else the
3457        // pattern rides the scan.
3458        let q = "/users/*[::name == 'app-'*]::id";
3459        let p = pushdown(q, Some(Dialect::Postgres)).unwrap();
3460        assert_eq!(
3461            p.sql,
3462            "SELECT id FROM users WHERE name LIKE 'app-%' ESCAPE '\\'"
3463        );
3464        assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3465        assert!(pushdown(q, Some(Dialect::MySql)).is_none());
3466        // contains and multi-segment shapes
3467        let p = pushdown("/users/*[::name == *'web'*]::id", Some(Dialect::Postgres)).unwrap();
3468        assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3469        let p = pushdown(
3470            "/users/*[::name == *'a'*'.gz']::id",
3471            Some(Dialect::Postgres),
3472        )
3473        .unwrap();
3474        assert!(p.sql.contains("LIKE '%a%.gz'"), "{}", p.sql);
3475        // LIKE metacharacters in a segment are escaped
3476        let p = pushdown("/users/*[::name == *'50%_x'*]::id", Some(Dialect::Postgres)).unwrap();
3477        assert!(p.sql.contains("LIKE '%50\\%\\_x%'"), "{}", p.sql);
3478        // `!=` with a pattern rides the scan
3479        assert!(pushdown("/users/*[::name !== *'web'*]::id", Some(Dialect::Postgres)).is_none());
3480        // the `*=` alias gains the same PostgreSQL rung
3481        let p = pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Postgres)).unwrap();
3482        assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3483        // and on SQLite it is instr, a substring test by bytes and by
3484        // case as `*=` is; MySQL's INSTR folds case, and scans
3485        assert_eq!(
3486            pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Sqlite))
3487                .unwrap()
3488                .sql,
3489            "SELECT id FROM users WHERE instr(name, 'web') > 0"
3490        );
3491        assert!(pushdown("/users/*[::name *= 'web']::id", Some(Dialect::MySql)).is_none());
3492        assert!(pushdown("/users/*[::name *= 'web']::id", None).is_none());
3493    }
3494
3495    #[test]
3496    fn json_column_path_pushdown_per_dialect() {
3497        // `[/col/a/b:: = 'lit']` navigates into a JSON column; each
3498        // dialect extracts the fixed path to text and compares.
3499        // Verified live against all five engines to match the graft.
3500        let q = "/orders/*[/data/meta/tier:: = 'gold']::id";
3501        let sql = |d| pushdown(q, Some(d)).unwrap().sql;
3502        assert_eq!(
3503            sql(Dialect::Postgres),
3504            "SELECT id FROM orders WHERE ((data::jsonb #>> '{meta,tier}') = 'gold')"
3505        );
3506        assert_eq!(
3507            sql(Dialect::MySql),
3508            "SELECT id FROM orders WHERE (JSON_VALID(data) AND \
3509             JSON_UNQUOTE(JSON_EXTRACT(data, '$.meta.tier')) = 'gold')"
3510        );
3511        assert_eq!(
3512            sql(Dialect::Sqlite),
3513            "SELECT id FROM orders WHERE (json_valid(data) AND \
3514             json_extract(data, '$.meta.tier') = 'gold')"
3515        );
3516        assert_eq!(
3517            sql(Dialect::Mssql),
3518            "SELECT id FROM orders WHERE (ISJSON(data) = 1 AND \
3519             JSON_VALUE(data, '$.meta.tier') = 'gold')"
3520        );
3521        assert_eq!(
3522            sql(Dialect::Oracle),
3523            "SELECT id FROM orders WHERE (JSON_VALUE(data, '$.meta.tier') = 'gold')"
3524        );
3525        // With no dialect, the JSON navigation is not pushable — it
3526        // falls back to the client-side graft.
3527        assert!(pushdown(q, None).is_none());
3528    }
3529
3530    #[test]
3531    fn json_pushdown_only_string_equality() {
3532        // Numeric comparison, `!=`, and a wildcard step stay off the
3533        // pushdown path (they are not provably identical to the
3534        // graft), so they refuse and scan even with a dialect set.
3535        let d = Some(Dialect::Sqlite);
3536        assert!(pushdown("/o/*[/data/n:: > 2]::id", d).is_none());
3537        assert!(pushdown("/o/*[/data/tier:: != 'gold']::id", d).is_none());
3538        assert!(pushdown("/o/*[/data/items/*/sku:: = 'A1']::id", d).is_none());
3539    }
3540
3541    #[test]
3542    fn json_pushdown_refuses_numeric_looking_literal() {
3543        // value_eq coerces numeric-looking strings ('150' matches
3544        // the JSON number 150 and the string "150.0"); no engine's
3545        // extractor does, so the push would drop rows.
3546        let q = "/orders/*[/data/total:: = '150']::id";
3547        assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3548        assert!(pushdown(q, Some(Dialect::Postgres)).is_none());
3549    }
3550
3551    #[test]
3552    fn a_regex_names_the_literals_it_cannot_match_without() {
3553        let lits = |p: &str| super::required_literals(p);
3554        assert_eq!(lits("^Ma.*s$"), ["Ma", "s"]);
3555        assert_eq!(lits("(us)+$"), ["us"]);
3556        assert_eq!(lits("a?b"), ["b"]);
3557        assert_eq!(lits("(?:foo|bar)baz"), ["baz"]);
3558        assert_eq!(lits("fo{2,}"), ["f", "o"]);
3559        assert_eq!(lits(r"\d+-\d+"), ["-"]);
3560        assert_eq!(lits(r"\bfoo\b"), ["foo"]);
3561        assert_eq!(lits(r"No\.1"), ["No.1"]);
3562        assert_eq!(lits("na\u{ef}ve"), ["na\u{ef}ve"]);
3563        assert_eq!(lits("(?x) a b"), ["ab"]);
3564        assert_eq!(lits("(a|b)c*d"), ["d"]);
3565        assert_eq!(lits("x{0}y"), ["y"]);
3566        assert_eq!(lits("ab(ab)"), ["ab"]);
3567        // nothing promised: a class, an alternation, an optional
3568        // part, a letter under (?i), a pattern that does not parse
3569        for p in ["(?i)ma", "Ven|Jup", "a*", "[ab]", "(ab)?", ".*", "", "["] {
3570            assert!(lits(p).is_empty(), "{p}");
3571        }
3572    }
3573
3574    #[test]
3575    fn a_regex_is_narrowed_by_its_literals() {
3576        let part = |q: &str, d: Dialect| {
3577            partial_pushdown(q, Some(d)).map(|p| (p.where_sql, p.column_types.text))
3578        };
3579        assert_eq!(
3580            part("/t/*[::a == (/^Ma.*s$/)]::b", Dialect::Sqlite),
3581            Some((
3582                "instr(a, 'Ma') > 0 AND instr(a, 's') > 0".to_string(),
3583                vec!["a".to_string()]
3584            ))
3585        );
3586        assert_eq!(
3587            part("/t/*[::a == (/50%_off/)]::b", Dialect::Postgres).map(|p| p.0),
3588            Some(r"a LIKE '%50\%\_off%' ESCAPE '\'".to_string())
3589        );
3590        // a conjunction keeps the side that translates; a
3591        // disjunction needs both
3592        assert_eq!(
3593            part("/t/*[::n > 2 && ::a == (/on/)]::b", Dialect::Sqlite).map(|p| p.0),
3594            Some("(n > 2 AND instr(a, 'on') > 0)".to_string())
3595        );
3596        assert_eq!(
3597            part(
3598                "/t/*[::a == (/(?i)x/) && ::a == (/on/)]::b",
3599                Dialect::Sqlite
3600            )
3601            .map(|p| p.0),
3602            Some("(instr(a, 'on') > 0)".to_string())
3603        );
3604        assert_eq!(
3605            part("/t/*[::a == (/Ven/) || ::a == (/Jup/)]::b", Dialect::Sqlite).map(|p| p.0),
3606            Some("(instr(a, 'Ven') > 0 OR instr(a, 'Jup') > 0)".to_string())
3607        );
3608        for q in [
3609            // one side promises nothing: the disjunction is not narrowed
3610            "/t/*[::a == (/Ven/) || ::a == (/(?i)jup/)]::b",
3611            // a negation is never narrowed, nor a non-match
3612            "/t/*[!(::a == (/Ven/))]::b",
3613            "/t/*[::a !== (/Ven/)]::b",
3614            // a literal a SQL string would not carry everywhere
3615            "/t/*[::a == (/it's/)]::b",
3616            // no literal at all
3617            "/t/*[::a == (/(?i)ven/)]::b",
3618            "/t/*[::a == (/Ven|Jup/)]::b",
3619        ] {
3620            assert_eq!(part(q, Dialect::Sqlite), None, "{q}");
3621        }
3622        // no function says "holds, by bytes and case" on MySQL
3623        assert_eq!(part("/t/*[::a == (/Ven/)]::b", Dialect::MySql), None);
3624    }
3625
3626    #[test]
3627    fn partial_json_prefilters_sqlite() {
3628        // Exact string equality rides the strict gate.
3629        let p = partial_pushdown(
3630            "/orders/*[/payload/customer/geo/city:: = 'Lyon']::id",
3631            Some(Dialect::Sqlite),
3632        )
3633        .unwrap();
3634        assert_eq!(p.table, "orders");
3635        assert_eq!(
3636            p.where_sql,
3637            "(json_valid(payload) AND \
3638             json_extract(payload, '$.customer.geo.city') = 'Lyon')"
3639        );
3640        // Numeric comparison: typed compare, text values escape.
3641        let p = partial_pushdown(
3642            "/orders/*[/payload/total:: > 150]::id",
3643            Some(Dialect::Sqlite),
3644        )
3645        .unwrap();
3646        assert_eq!(
3647            p.where_sql,
3648            "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3649             OR json_type(payload, '$.total') = 'text'))"
3650        );
3651        // Bare existence.
3652        let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Sqlite)).unwrap();
3653        assert_eq!(
3654            p.where_sql,
3655            "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3656        );
3657        // != floors at existence.
3658        let p = partial_pushdown(
3659            "/orders/*[/payload/status:: != 'x']::id",
3660            Some(Dialect::Sqlite),
3661        )
3662        .unwrap();
3663        assert_eq!(
3664            p.where_sql,
3665            "(json_valid(payload) AND json_type(payload, '$.status') IS NOT NULL)"
3666        );
3667        // A flipped literal flips the operator.
3668        let p = partial_pushdown(
3669            "/orders/*[150 < /payload/total::]::id",
3670            Some(Dialect::Sqlite),
3671        )
3672        .unwrap();
3673        assert!(p.where_sql.contains("> 150"), "{}", p.where_sql);
3674        // Without a dialect, JSON predicates stay on the engine.
3675        assert!(partial_pushdown("/orders/*[/payload/gift]::id", None).is_none());
3676    }
3677
3678    #[test]
3679    fn partial_json_prefilters_postgres() {
3680        let p = partial_pushdown(
3681            "/orders/*[/payload/total:: > 150]::id",
3682            Some(Dialect::Postgres),
3683        )
3684        .unwrap();
3685        assert_eq!(
3686            p.where_sql,
3687            "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3688             THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3689             WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'string' \
3690             THEN true ELSE false END)"
3691        );
3692        let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Postgres)).unwrap();
3693        assert_eq!(
3694            p.where_sql,
3695            "(jsonb_typeof(payload::jsonb #> '{gift}') IS NOT NULL)"
3696        );
3697    }
3698
3699    #[test]
3700    fn json_property_path_pushdown() {
3701        // `[/col/a::b = 'lit']`, the property form: the scalar's
3702        // question and, on an array of scalars, the list's (any item
3703        // equals). SQLite's condition says both whole.
3704        let q = "/orders/*[/payload/customer/geo::city = 'Lyon']::id";
3705        assert_eq!(
3706            pushdown(q, Some(Dialect::Sqlite)).unwrap().sql,
3707            "SELECT id FROM orders WHERE (json_valid(payload) AND \
3708             ((json_type(payload, '$.customer.geo.city') = 'text' AND \
3709             json_extract(payload, '$.customer.geo.city') = 'Lyon') OR \
3710             (json_type(payload, '$.customer.geo.city') = 'array' AND \
3711             EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3712             WHERE json_each.type = 'text' AND json_each.value = 'Lyon') AND \
3713             NOT EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3714             WHERE json_each.type IN ('array', 'object')))))"
3715        );
3716        // a property of the column's own value
3717        assert!(
3718            pushdown(
3719                "/orders/*[/payload::city = 'Lyon']::id",
3720                Some(Dialect::Sqlite)
3721            )
3722            .unwrap()
3723            .sql
3724            .contains("json_extract(payload, '$.city') = 'Lyon'")
3725        );
3726        // the other engines' array branches are not verified: no
3727        // whole push there, and none with no dialect
3728        for d in [
3729            Dialect::Postgres,
3730            Dialect::MySql,
3731            Dialect::Mssql,
3732            Dialect::Oracle,
3733        ] {
3734            assert!(pushdown(q, Some(d)).is_none(), "{d:?}");
3735        }
3736        assert!(pushdown(q, None).is_none());
3737        // a numeric-looking literal compares by value: no whole push
3738        assert!(
3739            pushdown(
3740                "/orders/*[/payload::total = '150']::id",
3741                Some(Dialect::Sqlite)
3742            )
3743            .is_none()
3744        );
3745        // a column named as one of json_each's own columns would be
3746        // read as that column inside the subquery
3747        assert!(
3748            pushdown(
3749                "/orders/*[/value::city = 'Lyon']::id",
3750                Some(Dialect::Sqlite)
3751            )
3752            .is_none()
3753        );
3754    }
3755
3756    #[test]
3757    fn partial_json_property_prefilters() {
3758        let sqlite = |q: &str| partial_pushdown(q, Some(Dialect::Sqlite)).map(|p| p.where_sql);
3759        // a comparison lets the arrays through with the text values:
3760        // a list matches when any item does, and the engine decides
3761        assert_eq!(
3762            sqlite("/orders/*[/payload::total > 150]::id").unwrap(),
3763            "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3764             OR json_type(payload, '$.total') IN ('text', 'array')))"
3765        );
3766        assert_eq!(
3767            sqlite("/orders/*[/payload/customer::tier < 'm']::id").unwrap(),
3768            "(json_valid(payload) AND (json_extract(payload, '$.customer.tier') < 'm' \
3769             OR json_type(payload, '$.customer.tier') = 'array'))"
3770        );
3771        // a bare property: present, as the child form
3772        assert_eq!(
3773            sqlite("/orders/*[/payload::gift]::id").unwrap(),
3774            "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3775        );
3776        // `!=` keeps a row whose key is absent: its floor is the node
3777        // the property is read on, and on the column itself there is
3778        // none
3779        assert_eq!(
3780            sqlite("/orders/*[/payload/customer::tier != 'x']::id").unwrap(),
3781            "(json_valid(payload) AND json_type(payload, '$.customer') IS NOT NULL)"
3782        );
3783        assert!(sqlite("/orders/*[/payload::status != 'x']::id").is_none());
3784        // PostgreSQL: the equality as a prefilter, the arrays through
3785        assert_eq!(
3786            partial_pushdown(
3787                "/orders/*[/payload/customer/geo::city = 'Lyon']::id",
3788                Some(Dialect::Postgres)
3789            )
3790            .unwrap()
3791            .where_sql,
3792            "(CASE WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'string' \
3793             THEN (payload::jsonb #>> '{customer,geo,city}') = 'Lyon' \
3794             WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'array' \
3795             THEN true ELSE false END)"
3796        );
3797        assert_eq!(
3798            partial_pushdown(
3799                "/orders/*[/payload::total > 150]::id",
3800                Some(Dialect::Postgres)
3801            )
3802            .unwrap()
3803            .where_sql,
3804            "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3805             THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3806             WHEN jsonb_typeof(payload::jsonb #> '{total}') IN ('string', 'array') \
3807             THEN true ELSE false END)"
3808        );
3809        // no type probe, no prefilter
3810        assert!(
3811            partial_pushdown("/orders/*[/payload::total > 150]::id", Some(Dialect::MySql))
3812                .is_none()
3813        );
3814    }
3815
3816    #[test]
3817    fn json_pushdown_refuses_a_container_looking_literal() {
3818        // An extractor answers an array or an object as its JSON
3819        // text, so `'[1,2]'` equalled the array itself, which has no
3820        // value in the graft: the whole push kept a row the scan
3821        // drops. It rides the prefilter (a superset, re-checked).
3822        for q in [
3823            "/orders/*[/data/a:: = '[1,2]']::id",
3824            "/orders/*[/data/a:: = '{\"k\":1}']::id",
3825        ] {
3826            assert!(pushdown(q, Some(Dialect::Sqlite)).is_none(), "{q}");
3827            assert!(pushdown(q, Some(Dialect::Postgres)).is_none(), "{q}");
3828        }
3829        assert_eq!(
3830            partial_pushdown("/orders/*[/data/a:: = '[1,2]']::id", Some(Dialect::Sqlite))
3831                .unwrap()
3832                .where_sql,
3833            "(json_valid(data) AND json_extract(data, '$.a') = '[1,2]')"
3834        );
3835    }
3836
3837    #[test]
3838    fn partial_skips_untranslatable_keeps_prefix() {
3839        // A refused predicate no prefilter covers is skipped — the
3840        // shorter conjunction is still a superset (the engine
3841        // re-applies the original) — rather than aborting the plan.
3842        let p = partial_pushdown(
3843            "/orders/*[::status = 'shipped'][/payload/line_items/*/sku:: = 'X']::id",
3844            Some(Dialect::Sqlite),
3845        )
3846        .unwrap();
3847        assert_eq!(p.where_sql, "status = 'shipped'");
3848    }
3849
3850    #[test]
3851    fn null_literal_compares_use_is_null() {
3852        // `= null` / `!= null` are provably identical to Quarb's
3853        // value_eq(NULL, …) semantics, never the always-UNKNOWN
3854        // `x = NULL`; they translate — and push — in both modes.
3855        assert_eq!(
3856            export("/t/*[::x = null] | ::x").unwrap().query,
3857            "SELECT x FROM t WHERE x IS NULL"
3858        );
3859        assert_eq!(
3860            export("/t/*[::x != null] | ::x").unwrap().query,
3861            "SELECT x FROM t WHERE x IS NOT NULL"
3862        );
3863        assert_eq!(
3864            pushdown("/t/*[::x = null] | ::x", None).unwrap().sql,
3865            "SELECT x FROM t WHERE x IS NULL"
3866        );
3867        assert_eq!(
3868            pushdown("/t/*[::x != null] | ::x", None).unwrap().sql,
3869            "SELECT x FROM t WHERE x IS NOT NULL"
3870        );
3871    }
3872
3873    #[test]
3874    fn ne_and_not_push_in_the_form_that_keeps_the_null_rows() {
3875        // `!=` against a value and `!(...)` hold for a NULL in Quarb
3876        // and are UNKNOWN in SQL. The plan says the cases SQL's
3877        // operators leave out, in SQL every engine reads (the scan's
3878        // answers beside the plan's: tests/sql.rs).
3879        assert_eq!(
3880            pushdown("/t/*[::x != 5] | ::x", None).unwrap().sql,
3881            "SELECT x FROM t WHERE (x <> 5 OR x IS NULL)"
3882        );
3883        assert_eq!(
3884            pushdown("/t/*[::x != ::y] | ::x", None).unwrap().sql,
3885            "SELECT x FROM t WHERE (x <> y OR (x IS NULL AND y IS NOT NULL) OR (x IS NOT NULL \
3886             AND y IS NULL))"
3887        );
3888        assert_eq!(
3889            pushdown("/t/*[!::x = 5] | ::x", None).unwrap().sql,
3890            "SELECT x FROM t WHERE (CASE WHEN x = 5 THEN 0 ELSE 1 END = 1)"
3891        );
3892        // two NULLs are equal in Quarb: an equality of two columns
3893        // says so
3894        assert_eq!(
3895            pushdown("/t/*[::x = ::y] | ::x", None).unwrap().sql,
3896            "SELECT x FROM t WHERE (x = y OR (x IS NULL AND y IS NULL))"
3897        );
3898        // the prefilter takes them too
3899        assert_eq!(
3900            partial_pushdown(&format!("/t/*[::x != 5]{GROUPED}"), None)
3901                .unwrap()
3902                .where_sql,
3903            "(x <> 5 OR x IS NULL)"
3904        );
3905        // The display translation still emits `<>`, flagged with a note.
3906        let t = export("/t/*[::x != 5] | ::x").unwrap();
3907        assert_eq!(t.query, "SELECT x FROM t WHERE x <> 5");
3908        assert!(t.notes.iter().any(|n| n.contains("NULL")));
3909    }
3910
3911    #[test]
3912    fn unescapable_text_literal_refuses_pushdown() {
3913        // A backslash (MySQL/BigQuery escape) or an apostrophe
3914        // (BigQuery rejects '' doubling) has no portable escaping, so
3915        // pushdown refuses; a clean literal still pushes.
3916        assert!(pushdown("/files/*[::path = \"C:\\temp\"] | ::path", None).is_none());
3917        assert!(pushdown("/t/*[::name = \"it's\"] | ::name", None).is_none());
3918        assert!(partial_pushdown(&format!("/t/*[::name = \"it's\"]{GROUPED}"), None).is_none());
3919        assert_eq!(
3920            pushdown("/t/*[::name = \"rare\"] | ::name", None)
3921                .unwrap()
3922                .sql,
3923            "SELECT name FROM t WHERE name = 'rare'"
3924        );
3925    }
3926}