pylon_core/ir/

compiler.rs

//
// This source file is part of the Pylon open source project.
//
// Copyright (c) 2026 Jaldis B.V.
//
// Licensed under the MIT OR Apache-2.0 license (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://opensource.org/licenses/MIT
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

use crate::error::{
    Position, PyQLError, PyQLResolutionError, PyQLTypeError, PyQLUnknownFieldError, PyQLUnknownTypeError,
};
use crate::parse::ast::{self, Expr, Literal, NonesOrder, ShapeElement, ShapeOp, SortDirection, Stmt};
use crate::schema::{
    FunctionDescriptor, LinkDescriptor, MultiLinkDescriptor, PropertyDescriptor, SchemaDescriptor, SearchBackend,
    TypeDescriptor,
};

use std::collections::{HashMap, HashSet};

use super::{
    IrArraySource, IrAssertedPointer, IrBinOp, IrComputedGlobalCte, IrComputedPointer, IrConflict, IrCteDef, IrDelete,
    IrExpr, IrFor, IrForIterator, IrFreeExpr, IrFtsSearch, IrFunctionCall, IrFunctionSelect, IrGlobalCte, IrGroup,
    IrGroupOutput, IrGroupProjection, IrIfElse, IrInsert, IrLinkProp, IrLiteral, IrLockClause, IrLockStrength,
    IrLockWait, IrMultiLinkClear, IrMultiLinkJoin, IrMultiLinkMutation, IrMultiLinkPointer, IrMultiLinkValueSource,
    IrMultiLinkValues, IrNulls, IrOutput, IrPathJoin, IrPathResult, IrPathSelect, IrPolyFanout, IrPolyImplementor,
    IrRowSource, IrScalarPointer, IrScalarSetPointer, IrSelect, IrSessionGlobalCte, IrShapePointer,
    IrSingleLinkCorrelation, IrSingleLinkPointer, IrSort, IrSortDir, IrSource, IrStmt, IrTypeCast, IrUnaryOp, IrUpdate,
    IrVectorSearch, SearchEnqueueInfo, TupleCastShape, VectorEnqueueInfo,
};

// ── Compiled-clause tuples ──────────────────────────────────────────────────────
//
// The three helpers that pull a statement's trailing clauses apart all return
// the same shape: the pieces in source order, each optional because a query
// need not spell any of them out. Named here so the signatures read as one
// concept rather than as an anonymous 4-tuple repeated three times.

/// `(filter, order_by, offset, limit)` — a plain `select`'s trailing clauses.
type SelectModifiers = (Option<IrExpr>, Vec<IrSort>, Option<IrExpr>, Option<IrExpr>);

/// `(filter, distance/rank direction, offset, limit)` — the trailing clauses of
/// a `vector::search`/`fts::search` select, where `order by` is constrained to
/// the search score rather than an arbitrary sort list.
type SearchModifiers = (Option<IrExpr>, Option<IrSortDir>, Option<IrExpr>, Option<IrExpr>);

/// `(type name, shape elements, sub-statement, link-property alias)` — the
/// parts of an expression that names a type and optionally shapes it.
type TypeAndShape<'e> = (String, &'e [ShapeElement], Option<&'e Stmt>, Option<String>);

// ── Public entry point ──────────────────────────────────────────────────────────

/// Compile a parsed PyQL statement against the schema, using default session
/// config (see `crate::ir::SessionConfig`) — used throughout this crate's own
/// tests and schema-time compilation, which never has a live client-supplied
/// config to honor. `compile_with_config` is the real entry a live query
/// request uses.
/// Returns the IR plan and the ordered list of parameter names (matching $1, $2, …).
pub fn compile(stmt: &Stmt, schema: &SchemaDescriptor) -> Result<IrOutput, PyQLError> {
    compile_with_config(stmt, schema, &crate::ir::SessionConfig::default())
}

/// Like `compile`, but honors a caller-supplied `SessionConfig` (e.g.
/// `allow_user_specified_id`) for this one statement.
pub fn compile_with_config(
    stmt: &Stmt,
    schema: &SchemaDescriptor,
    config: &crate::ir::SessionConfig,
) -> Result<IrOutput, PyQLError> {
    let mut c = Compiler::with_config(schema, config.clone());

    // Unwrap top-level WITH block: compile each CTE binding, then the main statement.
    let (ctes, ir) = if let Stmt::With(w) = stmt {
        // Special case: `with search := vector::search(…); select search { … } …`
        // Merge into a single IrVectorSearch rather than going through the CTE machinery.
        if let Some(ir) = try_compile_vs_with_pattern(&mut c, w)? {
            return Ok(IrOutput {
                subtype_fanouts: c.subtype_fanouts(),
                stmt: ir,
                params: c.params,
                ctes: vec![],
                global_ctes: c.global_ctes,
                warnings: c.warnings,
                uses_globals_arg: c.used_globals_arg,
            });
        }
        // Special case: `with search := fts::search(…); select search { … } …`
        if let Some(ir) = try_compile_fts_with_pattern(&mut c, w)? {
            return Ok(IrOutput {
                subtype_fanouts: c.subtype_fanouts(),
                stmt: ir,
                params: c.params,
                ctes: vec![],
                global_ctes: c.global_ctes,
                warnings: c.warnings,
                uses_globals_arg: c.used_globals_arg,
            });
        }

        let mut cte_defs = vec![];
        for alias in &w.aliases {
            if let Some(declared) = declared_pointers_of(&alias.expr) {
                c.cte_declared_pointers.insert(alias.name.clone(), declared);
            }
            if c.bind_group(&alias.name, &alias.expr)? {
                continue;
            }
            let ir_stmt = compile_cte_binding(&mut c, &alias.expr)?;
            let sql_name = c.claim_cte_sql_name(&alias.name);
            let type_name = c.register_cte(&alias.name, &ir_stmt);
            // What the binding hoisted (`p := existing ?? (insert …)`) goes
            // right before it: a CTE only sees the ones ahead of it.
            cte_defs.append(&mut c.hoisted_ctes);
            cte_defs.push(IrCteDef {
                name: sql_name,
                stmt: ir_stmt,
                type_name,
                correlated_to: None,
            });
        }
        let main = c.compile_stmt(&w.stmt)?;
        (cte_defs, main)
    } else {
        (vec![], c.compile_stmt(stmt)?)
    };

    let mut ctes = ctes;
    ctes.extend(std::mem::take(&mut c.hoisted_ctes));
    Ok(IrOutput {
        subtype_fanouts: c.subtype_fanouts(),
        stmt: ir,
        params: c.params,
        ctes,
        global_ctes: c.global_ctes,
        warnings: c.warnings,
        uses_globals_arg: c.used_globals_arg,
    })
}

/// Detect `with <var> := vector::search(Type, $vec); select <var> { object { … }, distance }`.
/// When matched, compile the whole thing to a single `IrVectorSearch`.
fn try_compile_vs_with_pattern(c: &mut Compiler<'_>, w: &ast::WithStmt) -> Result<Option<IrStmt>, PyQLError> {
    // Only handle exactly one alias that is a bare function call (not a subquery).
    if w.aliases.len() != 1 {
        return Ok(None);
    }
    let alias_def = &w.aliases[0];
    let fc = match &alias_def.expr {
        Expr::FunctionCall(fc) => fc,
        _ => return Ok(None),
    };
    if fc.module.as_deref() != Some("vector") || fc.name != "search" {
        return Ok(None);
    }

    // Main statement must be `select <alias_name> { … }`.
    let select_stmt = match w.stmt.as_ref() {
        Stmt::Select(s) => s,
        _ => return Ok(None),
    };
    // Unwrap optional Shape wrapper around the result expression.
    let (elements, result_inner): (&[ast::ShapeElement], &Expr) = match &select_stmt.result {
        Expr::Shape(sh) => {
            let inner = sh.expr.as_ref().unwrap_or(&select_stmt.result);
            (sh.elements.as_slice(), inner)
        }
        other => (&[], other),
    };
    // The inner expression should be a path referencing the WITH alias.
    match result_inner {
        Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
            if let ast::PathStep::Name(n) = &p.steps[0] {
                if n != &alias_def.name {
                    return Ok(None);
                }
            } else {
                return Ok(None);
            }
        }
        _ => return Ok(None),
    }

    if let Some(ir) = c.try_compile_vector_search(fc, elements, select_stmt)? {
        Ok(Some(IrStmt::VectorSearch(ir)))
    } else {
        Ok(None)
    }
}

fn try_compile_fts_with_pattern(c: &mut Compiler<'_>, w: &ast::WithStmt) -> Result<Option<IrStmt>, PyQLError> {
    if w.aliases.len() != 1 {
        return Ok(None);
    }
    let alias_def = &w.aliases[0];
    let fc = match &alias_def.expr {
        Expr::FunctionCall(fc) => fc,
        _ => return Ok(None),
    };
    if fc.module.as_deref() != Some("fts") || fc.name != "search" {
        return Ok(None);
    }

    let select_stmt = match w.stmt.as_ref() {
        Stmt::Select(s) => s,
        _ => return Ok(None),
    };
    let (elements, result_inner): (&[ast::ShapeElement], &Expr) = match &select_stmt.result {
        Expr::Shape(sh) => {
            let inner = sh.expr.as_ref().unwrap_or(&select_stmt.result);
            (sh.elements.as_slice(), inner)
        }
        other => (&[], other),
    };
    match result_inner {
        Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
            if let ast::PathStep::Name(n) = &p.steps[0] {
                if n != &alias_def.name {
                    return Ok(None);
                }
            } else {
                return Ok(None);
            }
        }
        _ => return Ok(None),
    }

    if let Some(ir) = c.try_compile_fts_search(fc, elements, select_stmt)? {
        Ok(Some(IrStmt::FtsSearch(ir)))
    } else {
        Ok(None)
    }
}

/// How many times a path may expand a computed pointer into its own path
/// before we call it a cycle. Chains are normal (a computed over a computed);
/// a chain this long is a schema that refers to itself.
/// AND a path traversal's own FILTER together with whatever conditions the
/// computed pointers spliced into it contributed. Every join in a path
/// select is inner, so a spliced computed's filter means the same thing as a
/// WHERE condition on the whole traversal.
/// `__subject__.p ?? (insert T { … })` — a rewrite that fills `p` with a new
/// object when the statement gives it none. The insert has no place in an
/// expression, so on insert it becomes `p := (insert …)` instead; `None`
/// for any other rewrite.
fn subject_default_insert(handler: &str, pointer: &str) -> Option<Expr> {
    fn holds_insert(expr: &Expr) -> bool {
        match expr {
            Expr::SubQuery(stmt) => match stmt.as_ref() {
                Stmt::Insert(_) => true,
                Stmt::Select(sel) => holds_insert(&sel.result),
                _ => false,
            },
            _ => false,
        }
    }
    let Ok(Expr::BinOp(b)) = crate::parse::parse_pointer_expr(handler) else {
        return None;
    };
    let reads_itself = matches!(&b.left, Expr::Path(p) if matches!(p.steps.as_slice(),
        [ast::PathStep::Name(subject), ast::PathStep::Name(name)] if subject == "__subject__" && name == pointer));
    (matches!(b.op, ast::BinOpKind::Coalesce) && reads_itself && holds_insert(&b.right)).then_some(b.right)
}

/// A sub-select's own `limit 1`: what makes it one object rather than a set.
fn limits_to_one(sel: Option<&ast::SelectStmt>) -> bool {
    sel.is_some_and(|sel| matches!(sel.limit, Some(Expr::Literal(ast::Literal::Int(1)))))
}

/// True when a select can yield at most one row: `limit 1`, or a filter that
/// pins an exclusive property (`.id = …`) in one of its `and`-ed conditions.
fn selects_at_most_one(sel: &ast::SelectStmt, td: &TypeDescriptor) -> bool {
    fn pins_exclusive(expr: &Expr, td: &TypeDescriptor) -> bool {
        let Expr::BinOp(b) = expr else { return false };
        match b.op {
            ast::BinOpKind::And => pins_exclusive(&b.left, td) || pins_exclusive(&b.right, td),
            ast::BinOpKind::Eq => [&b.left, &b.right].into_iter().any(|side| {
                matches!(side, Expr::Path(p) if p.partial
                    && matches!(p.steps.as_slice(), [ast::PathStep::Name(name)]
                        if td.properties.iter().any(|d| &d.name == name && (d.is_exclusive || d.is_pk))))
            }),
            _ => false,
        }
    }
    matches!(sel.limit, Some(Expr::Literal(ast::Literal::Int(1))))
        || sel.filter.as_ref().is_some_and(|f| pins_exclusive(f, td))
}

/// `(select .teams … limit 1) if cond else {}` as `(select .teams filter cond …
/// limit 1)`, carrying along a shape written on the branch or on the whole
/// if/else. `None` unless exactly one branch is empty and the other is a
/// relative walk or a select over one, and `cond` reads no relative path --
/// moved into the branch's filter, one would read the branch's rows instead.
fn guarded_object_branch(expr: &Expr) -> Option<Expr> {
    fn reads_relative(expr: &Expr) -> bool {
        match expr {
            Expr::Path(p) => p.partial,
            Expr::Literal(_) | Expr::Parameter(_) | Expr::Global(_) => false,
            Expr::BinOp(b) => reads_relative(&b.left) || reads_relative(&b.right),
            Expr::UnaryOp(u) => reads_relative(&u.operand),
            Expr::TypeCast(c) => reads_relative(&c.expr),
            Expr::FunctionCall(f) => f.args.iter().chain(f.kwargs.iter().map(|(_, v)| v)).any(reads_relative),
            Expr::IfElse(ie) => {
                reads_relative(&ie.if_expr) || reads_relative(&ie.condition) || reads_relative(&ie.else_expr)
            }
            _ => true,
        }
    }
    fn empty(expr: &Expr) -> bool {
        match expr {
            Expr::Set(items) => items.is_empty(),
            Expr::TypeCast(c) => matches!(&c.expr, Expr::Set(items) if items.is_empty()),
            _ => false,
        }
    }
    let (ie, outer_shape) = match expr {
        Expr::IfElse(ie) => (ie.as_ref(), None),
        Expr::Shape(sh) => match sh.expr.as_ref()? {
            Expr::IfElse(ie) => (ie.as_ref(), Some(sh.elements.clone())),
            _ => return None,
        },
        _ => return None,
    };
    if reads_relative(&ie.condition) {
        return None;
    }
    let (branch, condition) = match (empty(&ie.if_expr), empty(&ie.else_expr)) {
        (false, true) => (&ie.if_expr, ie.condition.clone()),
        (true, false) => (
            &ie.else_expr,
            Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: ast::UnaryOpKind::Not,
                operand: ie.condition.clone(),
            })),
        ),
        _ => return None,
    };
    let (branch, branch_shape) = match branch {
        Expr::Shape(sh) => (sh.expr.as_ref()?, Some(sh.elements.clone())),
        other => (other, None),
    };
    let mut select = match branch {
        Expr::Path(p) if p.partial => ast::SelectStmt {
            result: branch.clone(),
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            lock: None,
        },
        Expr::SubQuery(stmt) => match stmt.as_ref() {
            Stmt::Select(sel) if matches!(&sel.result, Expr::Path(p) if p.partial) => sel.clone(),
            _ => return None,
        },
        _ => return None,
    };
    select.filter = Some(match select.filter.take() {
        Some(filter) => Expr::BinOp(Box::new(ast::BinOp {
            left: filter,
            op: ast::BinOpKind::And,
            right: condition,
        })),
        None => condition,
    });
    let guarded = Expr::SubQuery(Box::new(Stmt::Select(select)));
    Some(match outer_shape.or(branch_shape) {
        Some(elements) => Expr::Shape(Box::new(ast::ShapeExpr {
            expr: Some(guarded),
            elements,
            marker_offset: None,
        })),
        None => guarded,
    })
}

/// `.grants.account = a and not .grants.deleted` as the multi-link `grants`
/// and the condition on one of its elements (`.account = a and not
/// .deleted`, a bare `.grants` becoming the element's `.id`). `None` unless
/// every relative path in the condition walks that same multi-link — one
/// reading the outer row would rebind to the element inside the sub-select —
/// and the condition holds no sub-statement.
fn per_element_of_one_multilink(condition: &Expr, td: &TypeDescriptor) -> Option<(Vec<ast::PathStep>, Expr)> {
    // The steps that reach the elements: a link name, or a backlink with the
    // type intersection that narrows it (`.<brand[is Assignment]`).
    fn prefix_len(steps: &[ast::PathStep]) -> Option<usize> {
        match steps {
            [ast::PathStep::Name(_), ..] => Some(1),
            [ast::PathStep::Backlink(_), ast::PathStep::TypeIntersection(_), ..] => Some(2),
            _ => None,
        }
    }
    fn rewrite(expr: &Expr, link: &mut Option<Vec<ast::PathStep>>) -> Option<Expr> {
        Some(match expr {
            Expr::Path(p) if p.partial => {
                let split = prefix_len(&p.steps)?;
                let prefix = p.steps[..split].to_vec();
                if *link.get_or_insert_with(|| prefix.clone()) != prefix {
                    return None;
                }
                // A condition on the link itself (`.posts = p`, no tail) has
                // no element to rebind; `all` over one takes the per-element
                // route in `try_elementwise_in` instead.
                let rest = p.steps[split..].to_vec();
                if rest.is_empty() {
                    return None;
                }
                Expr::Path(ast::Path {
                    steps: rest,
                    partial: true,
                })
            }
            Expr::Path(_) | Expr::Literal(_) | Expr::Parameter(_) | Expr::Global(_) => expr.clone(),
            Expr::BinOp(b) => Expr::BinOp(Box::new(ast::BinOp {
                left: rewrite(&b.left, link)?,
                op: b.op.clone(),
                // A set literal on the right of `in` is the haystack the test
                // reads, not a second set the quantifier ranges over, so it
                // carries through whole. Rewritten as an ordinary operand it
                // would be refused below, which is what made `all(.posts.title
                // in {'a', 'b'})` fall back to the `any` reading.
                right: match (&b.op, &b.right) {
                    (ast::BinOpKind::In | ast::BinOpKind::NotIn, set @ Expr::Set(_)) => set.clone(),
                    (_, other) => rewrite(other, link)?,
                },
            })),
            Expr::UnaryOp(u) => Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: u.op.clone(),
                operand: rewrite(&u.operand, link)?,
            })),
            Expr::TypeCast(c) => Expr::TypeCast(Box::new(ast::TypeCast {
                expr: rewrite(&c.expr, link)?,
                ty: c.ty.clone(),
            })),
            Expr::TypeIs { expr, ty } => Expr::TypeIs {
                expr: Box::new(rewrite(expr, link)?),
                ty: ty.clone(),
            },
            // A set-returning call (`array_unpack`) is a second set the
            // quantifier ranges over, so turning the condition into one asked
            // per link element would change what it asks.
            Expr::FunctionCall(f)
                if crate::stdlib::lookup(f.module.as_deref().unwrap_or("std"), &f.name)
                    .iter()
                    .any(|d| d.returns_set()) =>
            {
                return None;
            }
            Expr::FunctionCall(f) => Expr::FunctionCall(ast::FunctionCall {
                module: f.module.clone(),
                name: f.name.clone(),
                args: f.args.iter().map(|a| rewrite(a, link)).collect::<Option<_>>()?,
                kwargs: f
                    .kwargs
                    .iter()
                    .map(|(k, v)| Some((k.clone(), rewrite(v, link)?)))
                    .collect::<Option<_>>()?,
            }),
            _ => return None,
        })
    }
    let mut link = None;
    let element_condition = rewrite(condition, &mut link)?;
    let link = link?;
    let many = match link.first()? {
        ast::PathStep::Name(name) => td.multilinks.iter().any(|m| &m.name == name),
        ast::PathStep::Backlink(_) => true,
        _ => false,
    };
    many.then_some((link, element_condition))
}

/// A shape's subject written in a longer form than it needs, rewritten to the
/// form the select routes already take; `None` when there is nothing to
/// rewrite.
///
/// - `(select E) { … }` with no clauses of its own is `E { … }`, for the
///   subjects only a select over them spells: an if/else, a union, a shape.
/// - `X { a := … } { a: { … } }` is one shape. The outer one says what comes
///   back; a name it lists that the inner one computed keeps that computation
///   and takes the outer one's nested shape and modifiers.
fn flatten_shape_subject(expr: &Expr) -> Option<Expr> {
    let Expr::Shape(outer) = expr else { return None };
    match outer.expr.as_ref()? {
        Expr::SubQuery(stmt) => {
            let Stmt::Select(sel) = stmt.as_ref() else { return None };
            let bare = sel.filter.is_none()
                && sel.order_by.is_empty()
                && sel.offset.is_none()
                && sel.limit.is_none()
                && sel.lock.is_none();
            if !bare || !matches!(sel.result, Expr::IfElse(_) | Expr::Union(_, _) | Expr::Shape(_)) {
                return None;
            }
            let mut flat = outer.as_ref().clone();
            flat.expr = Some(sel.result.clone());
            Some(Expr::Shape(Box::new(flat)))
        }
        Expr::Shape(inner) => {
            let elements = outer
                .elements
                .iter()
                .map(|el| {
                    let declared = match (&el.compexpr, el.path.steps.as_slice()) {
                        (None, [ast::PathStep::Name(name)]) => inner.elements.iter().find(|d| {
                            d.compexpr.is_some()
                                && matches!(d.path.steps.as_slice(), [ast::PathStep::Name(n)] if n == name)
                        }),
                        _ => None,
                    };
                    match declared {
                        Some(d) => ShapeElement {
                            nested: el.nested.clone().or_else(|| d.nested.clone()),
                            filter: el.filter.clone().or_else(|| d.filter.clone()),
                            order_by: if el.order_by.is_empty() {
                                d.order_by.clone()
                            } else {
                                el.order_by.clone()
                            },
                            offset: el.offset.clone().or_else(|| d.offset.clone()),
                            limit: el.limit.clone().or_else(|| d.limit.clone()),
                            ..d.clone()
                        },
                        None => el.clone(),
                    }
                })
                .collect();
            Some(Expr::Shape(Box::new(ast::ShapeExpr {
                expr: inner.expr.clone(),
                elements,
                marker_offset: inner.marker_offset,
            })))
        }
        _ => None,
    }
}

/// The name `.key.<name>` of a group is read through while its shape
/// compiles — not one a query can spell, so it shadows nothing.
fn group_key_binding(name: &str) -> String {
    format!("<group key {name}>")
}

fn and_conditions(filter: Option<IrExpr>, extra: Vec<IrExpr>) -> Option<IrExpr> {
    extra.into_iter().fold(filter, |acc, cond| match acc {
        Some(existing) => Some(IrExpr::BinOp(Box::new(IrBinOp {
            left: existing,
            op: ast::BinOpKind::And,
            right: cond,
        }))),
        None => Some(cond),
    })
}

const MAX_COMPUTED_SPLICES: usize = 32;

/// `sum`, `any`, `all` and `array_agg` over no rows: SQL gives NULL, PyQL the
/// empty set's own value. `'{}'` rather than `ARRAY[]`, whose element type
/// PostgreSQL cannot infer on its own — inside a `coalesce` it takes the one
/// the aggregate already carries.
fn aggregate_over_nothing_sql(name: &str) -> Option<&'static str> {
    match name {
        "sum" => Some("0"),
        "any" => Some("false"),
        "all" => Some("true"),
        "array_agg" => Some("'{}'"),
        _ => None,
    }
}

fn aggregate_over_nothing(name: &str, aggregate: IrExpr) -> IrExpr {
    let Some(value) = aggregate_over_nothing_sql(name) else {
        return aggregate;
    };
    IrExpr::FunctionCall(IrFunctionCall {
        return_pg_type: None,
        schema: None,
        name: "coalesce".to_string(),
        args: vec![aggregate, IrExpr::RawSql(value.to_string())],
        sql_template: None,
    })
}

/// An expression whose value is a whole set, gathered as an array.
/// A set-valued walk gathered as an array, read back as a scalar subquery
/// instead — what an ordering comparison against a single value needs.
///
/// `(.installation.<installation[is RateLimitState].backoff_until < now) ?? true`
/// is conduit's backoff gate, and it reads element-wise: empty set →
/// `{}` → the `??` supplies `true`. Rendered as an array the comparison is
/// `timestamptz[] < timestamptz`, which PostgreSQL has no operator for, so the
/// statement failed outright. As a scalar subquery the empty case is NULL, the
/// comparison is NULL, and `COALESCE` supplies the default — right for
/// the nought-or-one sets these walks actually produce (an `exclusive`
/// constraint guarantees it here). A genuinely many-valued walk now raises
/// PostgreSQL's own "more than one row returned by a subquery" rather than
/// comparing element-wise; that is a narrower gap than emitting SQL that
/// cannot run at all.
fn set_walk_as_scalar(expr: IrExpr) -> IrExpr {
    match expr {
        IrExpr::ArrayFromSelect(source) => match *source {
            IrArraySource::PathSelect(ps) => IrExpr::PathSubquery(ps),
            other => IrExpr::ArrayFromSelect(Box::new(other)),
        },
        other => other,
    }
}

fn yields_array(expr: &IrExpr) -> bool {
    match expr {
        IrExpr::ArrayFromSelect(_) => true,
        IrExpr::IfElse(ie) => {
            (yields_array(&ie.if_) || matches!(ie.if_, IrExpr::Null))
                && (yields_array(&ie.else_) || matches!(ie.else_, IrExpr::Null))
                && !(matches!(ie.if_, IrExpr::Null) && matches!(ie.else_, IrExpr::Null))
        }
        _ => false,
    }
}

/// Look through the `coalesce` an aggregate over no rows is wrapped in — see
/// `aggregate_over_nothing`. The default only stands in for the aggregate, so
/// the type is the aggregate's.
fn through_coalesce(expr: &IrExpr) -> &IrExpr {
    match expr {
        IrExpr::FunctionCall(f) if f.schema.is_none() && f.name == "coalesce" => {
            f.args.first().map(through_coalesce).unwrap_or(expr)
        }
        other => other,
    }
}

fn ir_value_type_name(expr: &IrExpr) -> String {
    ir_value_type(expr).unwrap_or_default()
}

/// The pg type a bound value carries, including the array types
/// `infer_ir_type` has no spelling for — a `with` binding that loses its
/// array-ness resolves no overload at all, so `contains(ids, .id)` reports a
/// call nobody wrote.
fn ir_value_type(expr: &IrExpr) -> Option<String> {
    let expr = through_coalesce(expr);
    match expr {
        IrExpr::Array(elements) => {
            let element = elements.first().and_then(infer_ir_type).unwrap_or("text");
            Some(format!("{}[]", literal_sentinel_to_pg(element)))
        }
        // `ids := array_agg(r.id)` binds an array of what it aggregates, which
        // is what lets `contains(ids, .id)` pick the array overload over `str`'s.
        IrExpr::FunctionCall(f) if f.schema.is_none() && f.name == "array_agg" => {
            let element = f.args.first().and_then(infer_ir_type)?;
            Some(format!("{}[]", literal_sentinel_to_pg(element)))
        }
        // `array_agg((select …))` aggregates inside a correlated select, so
        // the array is what that select projects rather than the call itself.
        IrExpr::PathSubquery(ps) => match &ps.result {
            IrPathResult::Scalar(inner, _) => ir_value_type(inner),
            IrPathResult::Object { .. } => None,
        },
        IrExpr::ArrayFromSelect(source) => array_source_element_type(source).map(|element| format!("{element}[]")),
        // `xs if cond else ys` is typed by whichever branch can say — the
        // other is routinely the empty set.
        IrExpr::IfElse(ie) => ir_value_type(&ie.if_).or_else(|| ir_value_type(&ie.else_)),
        other => infer_ir_type(other).map(|t| t.to_string()),
    }
}

/// The pg type of one row of an `ARRAY(SELECT …)`. `None` for a source that
/// aggregates whole objects: those rows are composites with no scalar name.
fn array_source_element_type(source: &IrArraySource) -> Option<String> {
    match source {
        IrArraySource::Select(sel) => match sel.rows.as_slice() {
            [IrRowSource::Bound { shape, .. }] => match shape.first() {
                // Mirrors the emitter: the first scalar pointer is the
                // element, and a shape with none of them projects the id.
                Some(IrShapePointer::Scalar(scalar)) => Some(scalar.pg_type.clone()),
                _ => Some("uuid".to_string()),
            },
            _ => None,
        },
        IrArraySource::PathSelect(ps) => match &ps.result {
            IrPathResult::Scalar(expr, _) => infer_ir_type(expr).map(|t| literal_sentinel_to_pg(t).to_string()),
            IrPathResult::Object { .. } => None,
        },
        _ => None,
    }
}

/// The computed pointers a `with` binding's own shape declares, if any.
fn declared_pointers_of(expr: &Expr) -> Option<Vec<ShapeElement>> {
    // `(select T { x := … }) if cond else {}` declares what its select does.
    if let Expr::IfElse(ie) = expr {
        return declared_pointers_of(&ie.if_expr).or_else(|| declared_pointers_of(&ie.else_expr));
    }
    let Expr::SubQuery(stmt) = expr else {
        return None;
    };
    let shape = match innermost_select(stmt)? {
        ast::SelectStmt {
            result: Expr::Shape(sh),
            ..
        } => sh,
        _ => return None,
    };
    let declared: Vec<ShapeElement> = shape
        .elements
        .iter()
        .filter(|el| el.compexpr.is_some())
        .cloned()
        .collect();
    (!declared.is_empty()).then_some(declared)
}

/// The select a statement ultimately is, past any `with` blocks.
fn innermost_select(stmt: &Stmt) -> Option<&ast::SelectStmt> {
    match stmt {
        Stmt::Select(sel) => Some(sel),
        Stmt::With(w) => innermost_select(&w.stmt),
        _ => None,
    }
}

fn cte_stmt_type(stmt: &IrStmt) -> String {
    match stmt {
        IrStmt::Insert(ins) => ins.target.type_name.clone(),
        IrStmt::Update(upd) => upd.target.type_name.clone(),
        IrStmt::Delete(del) => del.target.type_name.clone(),
        IrStmt::Select(sel) => match sel.rows.first() {
            Some(IrRowSource::Bound { source, .. }) => source.type_name.clone(),
            // Infer the scalar pg_type from the first free item so the type
            // is available for UNION mismatch error messages. Returns empty
            // string if unknown.
            Some(IrRowSource::Free(IrFreeExpr::Scalar(expr))) => ir_value_type_name(expr),
            _ => String::new(),
        },
        // What a path select *yields*, not what it starts from: `with xs :=
        // (select Person.name)` binds text, not `default::Person`, and the
        // difference decides whether a reference to it reads the CTE's
        // `result` column or its `id` (see `resolve_name_ref`).
        IrStmt::PathSelect(ps) => match &ps.result {
            IrPathResult::Scalar(expr, _) => ir_value_type_name(expr),
            IrPathResult::Object { type_name, .. } => type_name.clone(),
        },
        IrStmt::For(f) => cte_stmt_type(&f.body),
        IrStmt::ScalarUnion(branches) => branches.first().map(cte_stmt_type).unwrap_or_default(),
        IrStmt::Group(g) => g.source.type_name.clone(),
        IrStmt::FunctionSelect(fs) => fs.type_name.clone(),
        IrStmt::VectorSearch(vs) => format!("__vs__{}", vs.source.type_name),
        IrStmt::FtsSearch(fs) => format!("__fts__{}", fs.source.type_name),
    }
}

/// Compile a WITH binding value: a subquery becomes its statement; any other
/// expression is wrapped in a synthetic `select expr` so it can be used as a CTE.
fn compile_cte_binding(c: &mut Compiler<'_>, expr: &Expr) -> Result<IrStmt, PyQLError> {
    let stmt = compile_cte_binding_stmt(c, expr)?;
    Ok(hoist_binding_dml(c, stmt))
}

/// `g := (insert T { … }) if cond else {}` — the binding's value compiles to a
/// select *over* a mutation. A data-modifying statement may only sit at the top
/// level of a `WITH`, never inside another CTE's body, so the mutation becomes a
/// CTE of its own ahead of this binding — where `g := existing ?? (insert T { …
/// })` already puts one — and the binding reads its rows back from there.
/// Emitted as-is, the mutation was dropped and the binding read the whole table.
fn hoist_binding_dml(c: &mut Compiler<'_>, stmt: IrStmt) -> IrStmt {
    let IrStmt::Select(mut select) = stmt else {
        return stmt;
    };
    let Some(dml) = select
        .dml_source
        .take_if(|dml| matches!(dml.as_ref(), IrStmt::Insert(_) | IrStmt::Update(_) | IrStmt::Delete(_)))
    else {
        return IrStmt::Select(select);
    };
    let cte_name = c.fresh_nested_cte_name();
    for row in &mut select.rows {
        if let IrRowSource::Bound { source, .. } = row {
            source.table = format!("@cte:{cte_name}");
            // The CTE's rows are already the concrete ones the mutation
            // touched, each carrying its own `__type__`.
            source.poly = None;
        }
    }
    c.hoisted_ctes.push(IrCteDef {
        name: cte_name,
        type_name: cte_stmt_type(&dml),
        stmt: *dml,
        correlated_to: None,
    });
    IrStmt::Select(select)
}

fn compile_cte_binding_stmt(c: &mut Compiler<'_>, expr: &Expr) -> Result<IrStmt, PyQLError> {
    if let Expr::SubQuery(s) = expr {
        let stmt = c.compile_stmt(s)?;
        if let IrStmt::Group(grp) = &stmt
            && !matches!(grp.output, IrGroupOutput::Elements)
        {
            return Err(c.type_err("a `group` cannot be bound in a `with` except to iterate it with `for`"));
        }
        return Ok(stmt);
    }
    // `existing ?? (insert Tag { … })` — on sets `A ?? B` is `A if exists A
    // else B`, the upsert idiom the if/else route already guards the
    // mutation for.
    let expr = match expr {
        Expr::BinOp(b)
            if b.op == ast::BinOpKind::Coalesce
                && matches!(&b.right, Expr::SubQuery(s) if matches!(s.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_))) =>
        {
            &Expr::IfElse(Box::new(ast::IfElse {
                if_expr: b.left.clone(),
                condition: Expr::UnaryOp(Box::new(ast::UnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: b.left.clone(),
                })),
                else_expr: b.right.clone(),
            }))
        }
        other => other,
    };
    // Non-statement expression (e.g. `<default::Company><uuid>'...'`):
    // treat as `select expr`.
    let fake_sel = ast::SelectStmt {
        result: expr.clone(),
        filter: None,
        order_by: vec![],
        offset: None,
        limit: None,
        lock: None,
    };
    c.compile_stmt(&Stmt::Select(fake_sel))
}

/// Qualified names of the functions that take `GLOBALS_ARG`.
///
/// A function needs it when its body reads a session global, *or* when it calls
/// a function that needs it — so this is a fixpoint, not a single pass: the
/// first pass finds the direct readers, later passes find their callers. A body
/// that fails to compile is skipped; that failure is reported by validation,
/// and guessing at its globals here would only produce a second, worse error.
pub fn functions_needing_globals(schema: &SchemaDescriptor) -> &std::collections::HashSet<String> {
    schema
        .functions_needing_globals
        .get_or_init(|| find_functions_needing_globals(schema))
}

fn find_functions_needing_globals(schema: &SchemaDescriptor) -> std::collections::HashSet<String> {
    let mut needs: std::collections::HashSet<String> = std::collections::HashSet::new();
    loop {
        let mut changed = false;
        for fd in &schema.functions {
            let qualified = format!("{}::{}", fd.module, fd.name);
            if needs.contains(&qualified) {
                continue;
            }
            if let Ok(out) = compile_fn_body_with(fd, schema, &needs)
                && out.uses_globals_arg
            {
                needs.insert(qualified);
                changed = true;
            }
        }
        if !changed {
            return needs;
        }
    }
}

/// Compile the PyQL body of a user-defined function for DDL emission.
///
/// Sets `fn_params` on the compiler so that parameter names resolve as `FnParam`
/// nodes rather than raising "expression is not valid in free SELECT context".
pub fn compile_fn_body(
    fn_desc: &crate::schema::FunctionDescriptor,
    schema: &SchemaDescriptor,
) -> Result<super::IrOutput, crate::error::PyQLError> {
    compile_fn_body_with(fn_desc, schema, functions_needing_globals(schema))
}

/// `compile_fn_body` with the globals-argument set supplied, so the fixpoint in
/// `functions_needing_globals` can call this without recursing into itself.
pub fn compile_fn_body_with(
    fn_desc: &crate::schema::FunctionDescriptor,
    schema: &SchemaDescriptor,
    fns_needing_globals: &std::collections::HashSet<String>,
) -> Result<super::IrOutput, crate::error::PyQLError> {
    use crate::parse;
    use crate::parse::ast::Stmt;

    let body = fn_desc.body.trim().to_string();
    // A body that is already a statement stands on its own; only a bare
    // expression needs the `select` that turns it into one. Wrapping a
    // statement instead would bury it as a sub-select and lose its clauses.
    let starts_a_stmt = ["select", "with", "for", "group", "insert", "update", "delete"]
        .iter()
        .any(|keyword| {
            body.len() > keyword.len()
                && body[..keyword.len()].eq_ignore_ascii_case(keyword)
                && !body.as_bytes()[keyword.len()].is_ascii_alphanumeric()
                && body.as_bytes()[keyword.len()] != b'_'
        });
    let body = if starts_a_stmt {
        body
    } else {
        format!("select {}", body)
    };

    let ast = parse::parse(&body)?;
    let mut c = Compiler::new(schema);
    c.in_fn_body = true;
    c.fns_needing_globals = Some(fns_needing_globals.clone());
    for p in &fn_desc.params {
        c.fn_params.insert(p.name.clone(), p.pg_type.clone());
    }

    let (ctes, ir) = if let Stmt::With(w) = &ast {
        let mut cte_defs = vec![];
        for alias in &w.aliases {
            let ir_stmt = compile_cte_binding(&mut c, &alias.expr)?;
            let type_name = cte_stmt_type(&ir_stmt);
            c.cte_types.insert(alias.name.clone(), type_name.clone());
            c.note_cte_cardinality(&alias.name, &ir_stmt);
            cte_defs.push(super::IrCteDef {
                name: alias.name.clone(),
                stmt: ir_stmt,
                type_name,
                correlated_to: None,
            });
        }
        let main = c.compile_stmt(&w.stmt)?;
        (cte_defs, main)
    } else {
        (vec![], c.compile_stmt(&ast)?)
    };

    let mut ctes = ctes;
    ctes.extend(std::mem::take(&mut c.hoisted_ctes));
    Ok(super::IrOutput {
        subtype_fanouts: c.subtype_fanouts(),
        stmt: ir,
        params: c.params,
        ctes,
        global_ctes: c.global_ctes,
        warnings: c.warnings,
        uses_globals_arg: c.used_globals_arg,
    })
}

/// Compile a schema `Trigger`'s `handler` PyQL statement for DDL emission —
/// same shape as `compile_fn_body`, but instead of `fn_params` this binds
/// `__new__`/`__old__` as the inserted/updated/deleted row (see
/// `Compiler::special_anchors`'s own doc comment), gated by `on_mask`
/// (Pylon's `On` bitmask: 1=Insert, 2=Update, 4=Delete): `__old__` is bound whenever
/// `on_mask` does *not* include Insert (so Update-only, Delete-only, and
/// Update+Delete all get it — but never a mask that includes Insert, even
/// combined with Update, since a shared trigger function has no old row on
/// the Insert branch of that combination); `__new__` is bound whenever
/// `on_mask` does *not* include Delete, by the mirror-image argument. A
/// mask combining Insert and Delete (with no Update) legally binds
/// neither. Referencing an anchor that isn't bound is a compile error, not
/// a runtime NULL.
/// One compiled rewrite: the column it writes and the value it writes there.
pub struct RewriteAssignment {
    pub pointer: String,
    pub column: String,
    pub ir: IrExpr,
    pub sql: String,
    /// True when the expression reads one of the owner's multi-links. Those
    /// rows live in a junction table the statement writes *after* the row
    /// itself, so a `BEFORE` trigger reading one sums an empty set — see
    /// `export::rewrite_trigger_infos`.
    pub reads_a_multi_link: bool,
}

/// A type's rewrites for one event (`on_mask`: 1 = insert, 2 = update), each
/// compiled against the row being written (`NEW`) as `(column, SQL)`, for
/// the `BEFORE` trigger that applies them. Evaluated on the row as the
/// statement left it, every rewrite sees the others' inputs, not their
/// results.
pub fn compile_rewrite_assignments(
    type_name: &str,
    on_mask: u8,
    schema: &SchemaDescriptor,
) -> Result<Vec<RewriteAssignment>, crate::error::PyQLError> {
    let mut c = Compiler::new(schema);
    c.in_fn_body = true;
    let owner_td = c.resolve_type(type_name)?;
    c.special_anchors
        .insert("__new__".to_string(), (owner_td, "NEW".to_string()));
    if on_mask & 1 == 0 {
        c.special_anchors
            .insert("__old__".to_string(), (owner_td, "OLD".to_string()));
    }
    let pointers = owner_td
        .properties
        .iter()
        .map(|p| (p.name.clone(), p.name.clone(), &p.rewrites))
        .chain(
            owner_td
                .links
                .iter()
                .filter(|l| !l.is_junction_backed())
                .map(|l| (l.name.clone(), format!("{}_id", l.name), &l.rewrites)),
        );
    let fanouts = c.subtype_fanouts();
    let mut out = Vec::new();
    for (name, column, rewrites) in pointers {
        for rw in rewrites.iter().filter(|rw| rw.on & on_mask != 0) {
            // Carried out by `compile_insert` as an assignment.
            if on_mask == 1 && subject_default_insert(&rw.handler, &name).is_some() {
                continue;
            }
            let expr = crate::parse::parse_pointer_expr(&rw.handler)?;
            let ir = c.compile_expr(&expr, owner_td, "NEW")?;
            if !c.params.is_empty() || !c.hoisted_ctes.is_empty() {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: format!(
                        "the rewrite of '{type_name}.{name}' has nowhere to bind a parameter or a binding"
                    ),
                    position: Position { line: 0, col: 0 },
                }));
            }
            let sql = crate::sql::emit_expr_with_fanouts(&ir, &fanouts);
            // Read off the emitted SQL rather than the expression: a walk
            // reaches a junction through computeds, subtypes and `through`
            // types, and what it actually joins is the one answer all of
            // those agree on.
            let junctions = c.junction_tables_of(owner_td)?;
            let reads_a_multi_link = junctions.iter().any(|table| sql.contains(table.as_str()));
            out.push(RewriteAssignment {
                pointer: name.clone(),
                column: column.clone(),
                ir,
                sql,
                reads_a_multi_link,
            });
        }
    }
    Ok(out)
}

pub fn compile_trigger_handler(
    handler: &str,
    type_name: &str,
    on_mask: u8,
    schema: &SchemaDescriptor,
) -> Result<super::IrOutput, crate::error::PyQLError> {
    use crate::parse;
    use crate::parse::ast::Stmt;

    let ast = parse::parse(handler.trim())?;
    let mut c = Compiler::new(schema);
    // A trigger has no parameters to bind a session global to; it reads them
    // from `GLOBALS_ARG`, which its function declares from `pylon.globals`.
    c.in_fn_body = true;
    // The trigger's own type — `__new__`/`__old__` always resolve against
    // this, regardless of what type happens to be the ambient `td` where
    // the anchor is textually used (e.g. inside `insert Note { note :=
    // __new__.name }`, the ambient td at that point is `Note`, not this).
    let owner_td = c.resolve_type(type_name)?;
    if on_mask & 4 == 0 {
        c.special_anchors
            .insert("__new__".to_string(), (owner_td, "NEW".to_string()));
    }
    if on_mask & 1 == 0 {
        c.special_anchors
            .insert("__old__".to_string(), (owner_td, "OLD".to_string()));
    }

    let (ctes, ir) = if let Stmt::With(w) = &ast {
        let mut cte_defs = vec![];
        for alias in &w.aliases {
            // `resolved := (__new__.status = …)` — a value read off the row
            // the trigger fired for, which a CTE has no way to see; it
            // stands in for its value wherever the name is used.
            if !matches!(alias.expr, ast::Expr::SubQuery(_)) {
                let anchor = if on_mask & 4 == 0 { "NEW" } else { "OLD" };
                let value = c.compile_expr(&alias.expr, owner_td, anchor)?;
                c.inline_bindings.insert(alias.name.clone(), value);
                continue;
            }
            let ir_stmt = compile_cte_binding(&mut c, &alias.expr)?;
            let sql_name = c.claim_cte_sql_name(&alias.name);
            let cte_type_name = cte_stmt_type(&ir_stmt);
            c.cte_types.insert(alias.name.clone(), cte_type_name.clone());
            c.note_cte_cardinality(&alias.name, &ir_stmt);
            cte_defs.push(super::IrCteDef {
                name: sql_name,
                stmt: ir_stmt,
                type_name: cte_type_name,
                correlated_to: None,
            });
        }
        let main = c.compile_stmt(&w.stmt)?;
        (cte_defs, main)
    } else {
        (vec![], c.compile_stmt(&ast)?)
    };

    let recursive_kind = recursive_dml_event(&ir, type_name)
        .or_else(|| ctes.iter().find_map(|cte| recursive_dml_event(&cte.stmt, type_name)));
    if let Some(kind) = recursive_kind
        && kind & on_mask != 0
    {
        return Err(crate::error::PyQLError::Fragment(crate::error::PyQLFragmentError {
            message: format!(
                "trigger on {type_name} is recursive: its handler {}s its own type, \
                     which this trigger also fires on",
                dml_event_word(kind),
            ),
            context: type_name.to_string(),
            position: crate::error::Position { line: 0, col: 0 },
        }));
    }

    let mut ctes = ctes;
    ctes.extend(std::mem::take(&mut c.hoisted_ctes));
    Ok(super::IrOutput {
        subtype_fanouts: c.subtype_fanouts(),
        stmt: ir,
        params: c.params,
        ctes,
        global_ctes: c.global_ctes,
        warnings: c.warnings,
        uses_globals_arg: c.used_globals_arg,
    })
}

fn dml_event_word(kind: u8) -> &'static str {
    match kind {
        1 => "insert",
        2 => "update",
        4 => "delete",
        _ => "mutate",
    }
}

/// Walks a compiled trigger handler's IR looking for a nested `INSERT`/
/// `UPDATE`/`DELETE` targeting `owner_type` — the same type the trigger
/// itself is declared on. Returns that DML's own event bit (1/2/4) the
/// first time one is found, so the caller can check it against the
/// trigger's own `on_mask`: a handler that inserts into its own type only
/// matters if this trigger *also* fires on Insert — the mask determines
/// what would actually refire, not just "does it touch itself at all".
///
/// Deliberately not exhaustive: covers the direct statement, a `SELECT
/// (INSERT/UPDATE/DELETE …) { … }` wrapper, and `for x in … union (…)`
/// loop bodies — the shapes every trigger handler in this codebase's own
/// test suite actually uses. A DML nested inside a free tuple/set literal
/// (`select { (insert A {...}), (insert B {...}) }`) isn't walked; a
/// handler written that way relies on Postgres's own runtime recursion-
/// depth guard instead, same fallback as before this check existed.
fn recursive_dml_event(stmt: &IrStmt, owner_type: &str) -> Option<u8> {
    match stmt {
        IrStmt::Insert(ins) if ins.target.type_name == owner_type => Some(1),
        IrStmt::Update(upd) if upd.target.type_name == owner_type => Some(2),
        IrStmt::Delete(del) if del.target.type_name == owner_type => Some(4),
        IrStmt::Select(sel) => sel
            .dml_source
            .as_deref()
            .and_then(|inner| recursive_dml_event(inner, owner_type)),
        IrStmt::For(for_stmt) => recursive_dml_event(&for_stmt.body, owner_type),
        _ => None,
    }
}

/// Compile a single PyQL expression in the context of a named type.
/// Used for schema fragments: computed pointers, rewrite handlers, constraint exprs.
pub fn compile_expr_in_type(
    expr: &Expr,
    type_name: &str,
    schema: &SchemaDescriptor,
) -> Result<(IrExpr, Vec<String>), PyQLError> {
    let mut c = Compiler::new(schema);
    let td = c.resolve_type(type_name)?;
    let alias = c.fresh_alias();
    let ir = c.compile_expr(expr, td, &alias)?;
    Ok((ir, c.params))
}

/// Compile a schema-declared computed pointer the same way a shape that
/// included it would, for validation.
///
/// Returns the scalar expression when the computed is scalar-valued, and
/// `None` when it compiles to an object (link) pointer — `(select .emails
/// filter .primary limit 1)` and friends, which have no scalar type for a
/// declared return type to be checked against.
pub fn compile_computed_in_type(
    cd: &crate::schema::ComputedDescriptor,
    type_name: &str,
    schema: &SchemaDescriptor,
) -> Result<Option<IrExpr>, PyQLError> {
    let mut c = Compiler::new(schema);
    let td = c.resolve_type(type_name)?;
    let module = td.module.clone();
    let alias = c.fresh_alias();
    match c.compile_declared_computed(cd, td, &alias, &module, None, &[])? {
        IrShapePointer::Computed(p) => Ok(Some(p.expr)),
        _ => Ok(None),
    }
}

/// Like `compile_expr_in_type` but uses an empty table alias, so that column
/// references emit as bare column names (`"col"` rather than `"a1"."col"`).
/// Used for fill expressions in migration UPDATE SET clauses.
pub fn compile_expr_unaliased(
    expr: &Expr,
    type_name: &str,
    schema: &SchemaDescriptor,
) -> Result<(IrExpr, Vec<String>), PyQLError> {
    let mut c = Compiler::new(schema);
    let td = c.resolve_type(type_name)?;
    let ir = c.compile_expr(expr, td, "")?;
    Ok((ir, c.params))
}

/// Compile a PyQL scalar expression to a SQL string for use as a column DEFAULT.
///
/// Wraps the expression in `SELECT <expr>`, compiles it as a free scalar, and
/// returns the emitted SQL expression (without the SELECT wrapper).
pub fn compile_scalar_default(pyql: &str, schema: &SchemaDescriptor) -> Result<String, String> {
    compile_scalar_default_typed(pyql, schema).map(|(sql, _ir)| sql)
}

/// Like `compile_scalar_default`, but also returns the compiled `IrExpr` —
/// used by schema-type-consistency validation (`crate::validate`) to infer
/// the default's actual produced type via `infer_ir_type`.
/// Compile a PyQL boolean expression in a type's context into the SQL a CHECK
/// constraint needs.
///
/// Columns emit unqualified (via `compile_expr_unaliased`), which is what a
/// table-level CHECK wants — it has no alias to qualify against.
pub fn compile_constraint_expr(
    pyql: &str,
    type_name: &str,
    schema: &SchemaDescriptor,
) -> Result<String, crate::error::PyQLError> {
    use crate::parse::ast::Stmt;
    let ast = crate::parse::parse(&format!("SELECT {pyql}"))?;
    let Stmt::Select(sel) = &ast else {
        return Err(PyQLError::Type(PyQLTypeError {
            message: "constraint expression must be an expression".into(),
            position: Position { line: 0, col: 0 },
        }));
    };
    let (ir, _params) = compile_expr_unaliased(&sel.result, type_name, schema)?;
    Ok(crate::sql::emit_expr(&ir))
}

pub fn compile_scalar_default_typed(pyql: &str, schema: &SchemaDescriptor) -> Result<(String, IrExpr), String> {
    use crate::parse::ast::Stmt;
    let full = format!("SELECT {}", pyql);
    let ast = crate::parse::parse(&full).map_err(|e| e.message)?;
    let Stmt::Select(sel) = &ast else {
        return Err("default expression must be a select statement".into());
    };
    let mut c = Compiler::new(schema);
    let ir = c.compile_free_expr(&sel.result).map_err(|e| e.to_string())?;
    let sql = crate::sql::emit_expr(&ir);
    Ok((sql, ir))
}

/// What in `expr` disqualifies it from being a column DEFAULT, if anything.
///
/// PostgreSQL evaluates a column default with no row and no query in scope,
/// so it rejects a sub-select outright ("cannot use subquery in DEFAULT
/// expression") and has nothing to resolve another column's name against.
pub fn default_blocker(expr: &IrExpr) -> Option<&'static str> {
    use IrExpr as E;
    match expr {
        E::Subquery(_)
        | E::ObjectSubquery(_)
        | E::ObjectPathSubquery(_)
        | E::ObjectPathUnion { .. }
        | E::PathSubquery(_)
        | E::FnSubquery(_)
        | E::ArrayFromSelect(_)
        | E::ScalarSubquery(_)
        | E::AggOverQuery { .. }
        | E::AggOverCte { .. }
        | E::ExistsOverCte { .. }
        | E::SetOp { .. }
        | E::AggOverSet { .. }
        | E::CteRef { .. }
        | E::CteFieldRef { .. }
        | E::GlobalRef { .. } => Some("a sub-select"),
        E::ColumnRef { .. } => Some("a reference to another pointer"),
        E::Param { .. } | E::GlobalParam { .. } => Some("a query parameter"),
        E::ForVar { .. } => Some("a for-loop variable"),
        E::FnParam { .. } => Some("a function parameter"),
        E::BinOp(b) => default_blocker(&b.left).or_else(|| default_blocker(&b.right)),
        E::UnaryOp(u) => default_blocker(&u.operand),
        E::TypeCast(c) => default_blocker(&c.expr),
        E::IfElse(i) => default_blocker(&i.condition)
            .or_else(|| default_blocker(&i.if_))
            .or_else(|| default_blocker(&i.else_)),
        E::FunctionCall(f) => f.args.iter().find_map(default_blocker),
        E::Array(items) | E::Tuple(items) => items.iter().find_map(default_blocker),
        E::NamedTuple { fields, .. } => fields.iter().find_map(|(_, e)| default_blocker(e)),
        E::Subscript { expr, index, .. } => default_blocker(expr).or_else(|| default_blocker(index)),
        E::JsonbField { expr, .. } | E::JsonbIndex { expr, .. } => default_blocker(expr),
        E::Slice { expr, lower, upper, .. } => default_blocker(expr)
            .or_else(|| lower.as_deref().and_then(default_blocker))
            .or_else(|| upper.as_deref().and_then(default_blocker)),
        E::Literal(_) | E::Null | E::EnumLiteral { .. } | E::RawSql(_) => None,
    }
}

/// The SQL for a pointer's PyQL default as a column DEFAULT clause, or `None`
/// when a column DEFAULT cannot hold it — it reads a session global, selects
/// an object, or otherwise needs the query around it. Those are applied by
/// `compile_insert` instead; see `inlined_pointer_defaults`.
pub fn column_default_sql(pyql: &str, schema: &SchemaDescriptor) -> Option<String> {
    let (sql, ir) = compile_scalar_default_typed(pyql, schema).ok()?;
    default_blocker(&ir).is_none().then_some(sql)
}

/// The pointers whose PyQL default an insert has to expand into its own shape,
/// paired with that default, because `column_default_sql` cannot render it.
///
/// Expanding a default means adding one shape element per unspecified pointer,
/// which is what makes an object-returning default like
/// `created_by := account_of_transaction()` work at all. Here the defaults a
/// column DEFAULT does hold keep using it, so only the remainder needs the
/// query.
pub fn inlined_pointer_defaults(td: &TypeDescriptor, schema: &SchemaDescriptor) -> Vec<(String, String)> {
    let properties = td
        .properties
        .iter()
        .filter(|p| !p.is_pk)
        .filter_map(|p| p.default_pyql.as_ref().map(|d| (p.name.clone(), d.clone())));
    let links = td
        .links
        .iter()
        .filter(|l| !l.is_junction_backed())
        .filter_map(|l| l.default_pyql.as_ref().map(|d| (l.name.clone(), d.clone())));
    properties
        .chain(links)
        .filter(|(_, pyql)| column_default_sql(pyql, schema).is_none())
        .collect()
}

/// One inlined default as the insert shape carries it: `pointer := <default>`.
fn default_shape_element(pointer: &str, value: Expr) -> ShapeElement {
    ShapeElement {
        path: ast::Path::relative(pointer),
        splat: None,
        nested: None,
        compexpr: Some(value),
        op: ShapeOp::Assign,
        filter: None,
        order_by: vec![],
        offset: None,
        limit: None,
        marker_offset: None,
    }
}

/// One inlined default, compiled the way `compile_insert` expands it into an
/// insert's shape — so a default that cannot compile there is caught by schema
/// validation rather than by the first insert that omits the pointer.
///
/// One pointer at a time, because the caller reporting the failure has to be
/// able to name which declaration caused it.
pub fn compile_inlined_default(
    type_name: &str,
    pointer: &str,
    pyql: &str,
    schema: &SchemaDescriptor,
) -> Result<(String, IrExpr), PyQLError> {
    let mut c = Compiler::new(schema);
    let td = c.resolve_type(type_name)?;
    let alias = c.fresh_alias();
    let element = default_shape_element(pointer, crate::parse::parse_pointer_expr(pyql)?);
    let mut assignments = c.compile_assignments(&[element], td, &alias)?;
    Ok(assignments.remove(0))
}

// ── Compiler context ────────────────────────────────────────────────────────────

struct Compiler<'a> {
    schema: &'a SchemaDescriptor,
    /// Ordered parameter names — index + 1 is the $N position in SQL.
    params: Vec<String>,
    alias_counter: usize,
    /// CTE names registered in the enclosing WITH block → qualified type name.
    cte_types: HashMap<String, String>,
    /// `with g := (group …)` bindings. A group's rows are no schema object, so
    /// nothing can read them as a CTE; a `for` over one compiles the group
    /// again in its own terms instead.
    group_bindings: HashMap<String, IrGroup>,
    /// CTE names bound to a single free row (free object/scalar/tuple, not
    /// a schema object) → that row's `IrFreeExpr` — lets `root.field`
    /// resolve to `IrExpr::CteFieldRef` when `root` is such a binding,
    /// instead of failing as an unresolvable schema-path root.
    cte_free_items: HashMap<String, IrFreeExpr>,
    /// CTE names whose binding can hold more than one row. Comparing a value
    /// against one has to become set membership: `IrExpr::CteRef` reads the
    /// binding as a scalar subquery, which Postgres aborts on the second row
    /// ("more than one row returned by a subquery used as an expression").
    multi_row_ctes: HashSet<String>,
    /// FOR loop variables in scope: variable name → pg_type of the scalar iterator.
    for_vars: HashMap<String, String>,
    /// For-loop variables that iterate objects, by qualified type name. The
    /// variable itself holds the row's key (see `compile_for`), so a path
    /// rooted at one reads its table back by that key.
    for_var_types: HashMap<String, String>,
    /// For a loop over a `with` binding, the binding each variable's rows come
    /// from. The rows a sibling CTE has just written are not in the base table
    /// yet -- Postgres runs every CTE against the snapshot the statement
    /// started with -- so a walk off the variable has to read the binding.
    for_var_ctes: HashMap<String, String>,
    /// The name each loop variable's iterator CTE is emitted under. Two
    /// sibling loops may use the same variable name, and a WITH clause cannot
    /// hold the same CTE name twice.
    for_var_slots: HashMap<String, String>,
    /// The condition a `(insert …) if cond else {}` puts on the insert about
    /// to be compiled — see `IrInsert::guard`.
    pending_insert_guard: Option<Expr>,
    /// The condition a guarded `update` has to carry itself, for the same
    /// reason an insert does: a data-modifying CTE runs whether or not
    /// anything reads it, so filtering what is read back changes nothing.
    pending_update_guard: Option<Expr>,
    /// See `pending_update_guard` — the same, for a guarded delete.
    pending_delete_guard: Option<Expr>,
    /// Pointers a `with` binding declared in its own shape (`offering := (
    /// select Offering { publisher := … })`). They exist nowhere on the type,
    /// so a later `offering { publisher }` has to find them here.
    cte_declared_pointers: HashMap<String, Vec<ShapeElement>>,
    /// Those of the binding whose shape is being compiled right now.
    active_declared_pointers: Vec<ShapeElement>,
    /// Computed pointers a path is reading as a value right now, as
    /// `module::Type.name` — one that names itself would otherwise recurse
    /// without end.
    expanding_computeds: Vec<String>,
    /// The schema-bound selects currently being compiled, innermost last.
    ///
    /// Only consulted for `detached`: an absolute `TypeName.prop` inside a
    /// detached select means the *enclosing* select's row, so the innermost
    /// entry is skipped and the next matching one used.
    anchors: Vec<SelectAnchor>,
    /// CTE definitions a nested `with` contributed from somewhere the
    /// emitter has no WITH clause of its own — an expression, say. They are
    /// appended to the statement's own CTEs at the top-level boundary.
    hoisted_ctes: Vec<IrCteDef>,
    /// What each hoisted binding was defined as, so the same one arriving
    /// twice (one computed inlined from two places) is recognised as the same
    /// rather than emitted twice under one CTE name.
    hoisted_binding_sources: HashMap<String, Expr>,
    /// The WITH name a binding is actually emitted under. Two `for` bodies may
    /// each declare `line`; one WITH clause cannot hold that name twice, so the
    /// second is emitted under a suffixed one and every reference to it reads
    /// from here.
    cte_sql_names: HashMap<String, String>,
    /// Every WITH name this statement will carry, whoever asked for it — a
    /// user binding, a loop's iterator, a hoisted mutation. One set so no two
    /// can claim the same name and no guard has to know about the others.
    cte_namespace: std::collections::HashSet<String>,
    /// Loop slots whose variable has been read since the last time this was
    /// cleared — see `for_var_ref`.
    for_vars_read: std::collections::HashSet<String>,
    /// SQL CTE name → the loop slot its rows belong to one iteration of, for
    /// every per-iteration binding registered so far.
    correlated_bindings: HashMap<String, String>,
    /// Slots of the per-iteration bindings read since this was last cleared.
    /// Interior mutability because a read is noticed from `&self` name
    /// resolution — see `cte_sql_name`.
    correlated_reads: std::cell::RefCell<std::collections::HashSet<String>>,
    /// The loops whose bodies are being compiled, innermost last.
    for_scope: Vec<String>,
    /// `(through type, junction alias)` of the multi-link whose own
    /// modifiers are being compiled — what a bare `@prop` in `filter
    /// (@primary = true)` resolves against. `None` on the stack means a link
    /// with no through type, which has no link properties at all.
    link_prop_scope: Vec<Option<(String, String)>>,
    /// Set when `compile_stmt` strips a select-level `detached`, and taken by
    /// the `compile_path_modifiers` that compiles that select's own clauses.
    pending_detached: bool,
    /// Set while a path continues past a sub-select's own subject, e.g. the
    /// `.plan.tier` of `(select .licences filter not exists .ended_at limit
    /// 1).plan.tier`: the subject's landing row is what FILTER/ORDER BY/LIMIT
    /// scope to, not the type the whole path ends on.
    modifier_anchor: Option<(String, String)>,
    /// The `order by` the *outer* select wrote around such a path, which
    /// speaks about what the path projects rather than about the anchored
    /// subject — `(select Cart filter .id = $c).applied_promotions order by
    /// .code` orders applications, having filtered carts.
    tail_sorts: Vec<ast::SortExpr>,
    /// WITH bindings that name a path off the enclosing object. They read that
    /// object's alias, which a CTE emitted ahead of the FROM clause cannot
    /// see, so they stand in for their value wherever the name is used.
    inline_bindings: std::collections::HashMap<String, IrExpr>,
    /// True while compiling a `@pylon.function` body. A session global cannot
    /// be a query parameter there — a `CREATE FUNCTION` body has nothing to
    /// bind one to — so it is read out of the `__pylon_json_globals__`
    /// argument instead. See `GLOBALS_ARG`.
    in_fn_body: bool,
    /// Qualified names of functions that take the globals argument, so a call
    /// to one can be given it.
    ///
    /// Computed on first use rather than up front: working it out means
    /// compiling every function body in the schema, and the overwhelming
    /// majority of queries never call a user function at all. Function-body
    /// compilation seeds it explicitly (`compile_fn_body_with`), which is also
    /// what keeps the fixpoint from recursing into itself.
    fns_needing_globals: Option<std::collections::HashSet<String>>,
    /// Set when this body read a global or forwarded the argument to a callee
    /// — i.e. when the function being compiled needs the argument itself.
    used_globals_arg: bool,
    /// User-defined function parameters in scope (only set during body compilation).
    fn_params: HashMap<String, String>,
    /// `__new__`/`__old__` row-context bindings, only set during trigger-handler
    /// compilation (`compile_trigger_handler`) — maps the anchor name to
    /// *the trigger's own type* and the table alias its properties/links
    /// should resolve against (`"NEW"`/`"OLD"`). Stored explicitly (not just
    /// the alias string) because `__new__.x`/`__old__.x` can appear nested
    /// inside a sub-statement targeting a *different* type (e.g. `insert Note
    /// { note := __new__.name }` — the ambient `td` at that point is `Note`,
    /// not the trigger's own type), so resolution can't rely on whatever
    /// `td` happens to be in scope where the anchor is used. An anchor not
    /// legal for the trigger's `on` mask (e.g. `__old__` in an Insert-only
    /// trigger) is simply absent from this map, and fails resolution the
    /// same way any other unknown identifier does.
    special_anchors: HashMap<String, (&'a TypeDescriptor, String)>,
    /// Global CTEs collected during compilation (session and computed), in dependency order.
    global_ctes: Vec<IrGlobalCte>,
    /// Nested DML hoisted out of a link-assignment value currently being
    /// compiled (`author := (select (insert Person {...}) { id })`) — see
    /// `compile_link_subquery`'s doc comment. `compile_insert`/
    /// `compile_update` save-and-clear this on entry and drain it back into
    /// their own `IrInsert`/`IrUpdate::nested_ctes` on exit, so nesting
    /// (a nested insert whose own link value nests another insert) attaches
    /// each level's discoveries to the right statement.
    pending_nested_ctes: Vec<IrCteDef>,
    /// Junction tables this statement also *writes*, mapped to the CTE that
    /// wrote them — installed only while a walk off a hoisted mutation is
    /// being compiled. Postgres does not show a sibling CTE's inserts in the
    /// base table, so `(update T set { multi += … }).multi` has to read the
    /// rows back out of the append CTE or it sees none of them.
    junction_read_overrides: HashMap<String, JunctionReadOverride>,
    nested_cte_counter: usize,
    /// Non-fatal warnings collected during compilation.
    warnings: Vec<String>,
    /// Depth of `any()`/`all()` arguments currently being compiled. Wrapping a
    /// set-valued comparison in one of those *is* the explicit intent the
    /// multi-link FILTER warning asks for, so the warning stays quiet inside.
    explicit_set_depth: usize,
    /// Of those, the `all()` ones. `any()` is what an EXISTS already says, so
    /// a set-valued comparison may fold into one there; `all()` needs the
    /// answers one at a time to reduce them, since an EXISTS over a negated
    /// test is not the same question. See `try_elementwise_in`.
    universal_set_depth: usize,
    /// User-configurable session options — see `SessionConfig`. Always
    /// `default()` for every entry point except `compile_with_config`.
    config: crate::ir::SessionConfig,
    /// Whether a shape compiled right now gets an `id` it did not ask for —
    /// see `prepend_implicit_id`. True at the top level and cleared for the
    /// two places that cannot carry it: a mutation's own body, where a link
    /// value compiles to a one-column correlated subquery that a second column
    /// would break, and under a cast to `json`, which is an output sink whose
    /// text an added key would change.
    implicit_id_in_shapes: bool,
    /// Whether the expression being compiled stands where a *value* is
    /// expected — a computed pointer's right-hand side, say — rather than
    /// where a condition is. `in` asks its question once per element of its
    /// left operand, so over a set it yields a set of booleans; only a
    /// condition collapses that set to the single "any of them" answer an
    /// EXISTS gives. Set by `in_value_position`, cleared by `as_condition`.
    value_position: bool,
}

/// One schema-bound select in the enclosing chain — see `Compiler::anchors`.
struct SelectAnchor {
    type_name: String,
    qualified: String,
    alias: String,
    detached: bool,
    /// The ancestor an inherited computed is declared on, set only for the
    /// anchor that computed is compiled under.
    ///
    /// A computed is compiled once, against the type that declares it, so
    /// `BrandAddon.bundle := (BrandAddon is BrandAddonBundle)` reads its own
    /// row there and keeps doing so through every subtype that inherits it.
    /// Pylon materialises an inherited computed onto each subtype and compiles
    /// it again there, where `BrandAddon` no longer names the subject -- and a
    /// bare type name that anchors nothing reads the whole table. Naming a
    /// supertype does *not* otherwise mean the subject
    /// (`select BrandAddonBundle { n := count(BrandAddon) }` is the full count,
    /// while the same shape naming `BrandAddonBundle` is 1), so this is scoped
    /// to the one anchor rather than folded into the general name match.
    declared_on: Option<(String, String)>,
}

impl SelectAnchor {
    /// Whether this anchor answers to `root` as a path root.
    fn answers_to(&self, root: &str) -> bool {
        self.type_name == root
            || self.qualified == root
            || self
                .declared_on
                .as_ref()
                .is_some_and(|(name, qualified)| name == root || qualified == root)
    }
}

/// The synthetic argument carrying session globals into a function body.
///
/// A session global is normally a query parameter, which a `CREATE FUNCTION`
/// body cannot have — it would emit a bare `$1` nothing binds. Instead the
/// caller packs the globals into one jsonb value and passes it as a leading
/// argument. One opaque argument rather than one
/// per global keeps the function's signature independent of which globals its
/// body happens to mention, so editing a body does not churn its signature
/// (and, with PostgreSQL overloading, leave a stale one behind).
pub const GLOBALS_ARG: &str = "__pylon_json_globals__";

/// SQL reading one global out of `GLOBALS_ARG`.
fn globals_arg_read(qualified: &str, pg_type: &str) -> String {
    let key = qualified.replace('\'', "''");
    if let Some(element) = pg_type.strip_suffix("[]") {
        // `->>` would hand back the JSON array's text, not an array, so the
        // elements are unpacked instead. The `jsonb_typeof` guard matters: an
        // unset global arrives as JSON null, and unpacking that raises "cannot
        // extract elements from a scalar". The `coalesce` keeps an empty array
        // an empty array rather than letting `array_agg` turn it into NULL.
        format!(
            "(case when jsonb_typeof({GLOBALS_ARG} -> '{key}') = 'array' \
             then coalesce((select array_agg(value::{element}) \
             from jsonb_array_elements_text({GLOBALS_ARG} -> '{key}') as value), '{{}}'::{pg_type}) \
             else null end)"
        )
    } else {
        format!("(({GLOBALS_ARG} ->> '{key}')::{pg_type})")
    }
}

impl<'a> Compiler<'a> {
    fn new(schema: &'a SchemaDescriptor) -> Self {
        Self::with_config(schema, crate::ir::SessionConfig::default())
    }

    fn with_config(schema: &'a SchemaDescriptor, config: crate::ir::SessionConfig) -> Self {
        Compiler {
            schema,
            params: vec![],
            alias_counter: 0,
            cte_types: HashMap::new(),
            group_bindings: HashMap::new(),
            cte_free_items: HashMap::new(),
            multi_row_ctes: HashSet::new(),
            for_vars: HashMap::new(),
            for_var_types: HashMap::new(),
            for_var_ctes: HashMap::new(),
            for_var_slots: HashMap::new(),
            pending_insert_guard: None,
            pending_update_guard: None,
            pending_delete_guard: None,
            cte_declared_pointers: HashMap::new(),
            active_declared_pointers: vec![],
            expanding_computeds: vec![],
            fn_params: HashMap::new(),
            special_anchors: HashMap::new(),
            global_ctes: vec![],
            pending_nested_ctes: vec![],
            junction_read_overrides: HashMap::new(),
            nested_cte_counter: 0,
            warnings: vec![],
            explicit_set_depth: 0,
            universal_set_depth: 0,
            config,
            implicit_id_in_shapes: true,
            value_position: false,
            anchors: Vec::new(),
            link_prop_scope: Vec::new(),
            hoisted_ctes: Vec::new(),
            hoisted_binding_sources: HashMap::new(),
            cte_sql_names: HashMap::new(),
            cte_namespace: std::collections::HashSet::new(),
            for_vars_read: std::collections::HashSet::new(),
            correlated_bindings: HashMap::new(),
            correlated_reads: std::cell::RefCell::new(std::collections::HashSet::new()),
            for_scope: Vec::new(),
            pending_detached: false,
            modifier_anchor: None,
            tail_sorts: vec![],
            inline_bindings: std::collections::HashMap::new(),
            in_fn_body: false,
            fns_needing_globals: None,
            used_globals_arg: false,
        }
    }

    /// Register a compiled WITH binding under `name`: records its type (or
    /// empty string for a free binding) in `cte_types`, and — when it's a
    /// single free row — its `IrFreeExpr` in `cte_free_items` so a later
    /// `name.field` reference can resolve to `IrExpr::CteFieldRef`.
    /// True when `name` is bound to a value rather than to an object set —
    /// a scalar WITH binding, or one inlined by `bind_inline_if_correlated`.
    fn is_value_binding(&self, name: &str) -> bool {
        self.inline_bindings.contains_key(name) || self.cte_types.get(name).is_some_and(|t| !t.contains("::"))
    }

    /// Bind `name` to the value of a relative path off the enclosing object —
    /// `with handle_id := .id`. Returns false when the binding is anything
    /// else, which the caller hoists into a CTE as usual.
    /// `ctx` is the row the enclosing sub-select is correlated to, when it
    /// has one: a relative path in its bindings reads that row, not whichever
    /// select happens to enclose it.
    fn bind_inline_if_correlated(
        &mut self,
        name: &str,
        expr: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<bool, PyQLError> {
        if (self.anchors.is_empty() && ctx.is_none()) || !matches!(expr, Expr::Path(p) if p.partial) {
            return Ok(false);
        }
        let ir = self.compile_expr_ctx(expr, ctx)?;
        self.inline_bindings.insert(name.to_string(), ir);
        Ok(true)
    }

    /// The WITH name `name` is emitted under — itself, unless it collided.
    fn cte_sql_name(&self, name: &str) -> String {
        let sql_name = self
            .cte_sql_names
            .get(name)
            .cloned()
            .unwrap_or_else(|| name.to_string());
        if let Some(slot) = self.correlated_bindings.get(&sql_name) {
            self.correlated_reads.borrow_mut().insert(slot.clone());
        }
        sql_name
    }

    /// The `@cte:` source sentinel for `cte`, noting the read so that a
    /// binding compiled around it inherits the iteration `cte` belongs to.
    fn cte_source_table(&self, cte: &str) -> String {
        if let Some(slot) = self.correlated_bindings.get(cte) {
            self.correlated_reads.borrow_mut().insert(slot.clone());
        }
        format!("@cte:{cte}")
    }

    /// Compile a `with` binding, reporting the loop slot it reads if it reads
    /// one. A binding that names the loop variable holds a different value
    /// each iteration, which is not something a statement-level CTE can be.
    fn compile_binding_in_scope(&mut self, expr: &Expr) -> Result<(IrStmt, Option<String>), PyQLError> {
        let before = std::mem::take(&mut self.for_vars_read);
        let before_correlated = std::mem::take(&mut *self.correlated_reads.borrow_mut());
        let ir_stmt = compile_cte_binding(self, expr);
        let mut read = std::mem::replace(&mut self.for_vars_read, before);
        let correlated_read = std::mem::replace(&mut *self.correlated_reads.borrow_mut(), before_correlated);
        // Reading a per-iteration binding makes this one per-iteration too,
        // even where it never names the loop variable itself: its rows are
        // picked by the iteration key the one it reads carries.
        read.extend(correlated_read.iter().cloned());
        // The innermost loop read is the one it belongs to; an outer loop's
        // variable is reachable from there anyway.
        let correlated_to = self
            .for_scope
            .iter()
            .rev()
            .find(|slot| read.contains(*slot))
            .map(|slot| format!("_for_{slot}"));
        self.for_vars_read.extend(read);
        self.correlated_reads.borrow_mut().extend(correlated_read);
        Ok((ir_stmt?, correlated_to))
    }

    /// Claim a WITH name, suffixing `base` until it is free. Names the SQL
    /// emitter derives from a claimed one — `x__ids`, `x__rows`,
    /// `x__ml_add_0` — are claimed with it, which is why anything under a
    /// taken name's `__` prefix counts as taken too.
    fn claim_in_cte_namespace(&mut self, base: &str) -> String {
        // A suffixed candidate is itself an extension of `base`, so `base` is
        // the one claimed name that never rules its own suffixes out.
        let taken = |namespace: &std::collections::HashSet<String>, candidate: &String| {
            namespace.contains(candidate)
                || namespace
                    .iter()
                    .any(|claimed| claimed != base && candidate.starts_with(&format!("{claimed}__")))
        };
        let mut candidate = base.to_string();
        let mut suffix = 1;
        while taken(&self.cte_namespace, &candidate) {
            candidate = format!("{base}__{suffix}");
            suffix += 1;
        }
        self.cte_namespace.insert(candidate.clone());
        candidate
    }

    /// Claim a WITH name the compiler spelled itself — a loop's iterator, a
    /// hoisted mutation. These already live in the underscore-prefixed space
    /// that user names are kept out of, so they are claimed as written.
    fn claim_generated_cte_name(&mut self, preferred: &str) -> String {
        self.claim_in_cte_namespace(preferred)
    }

    /// Claim a WITH name for a `with` binding, recording the name to read it
    /// back by when the one it asked for was already spoken for.
    fn claim_cte_sql_name(&mut self, name: &str) -> String {
        // Every generated WITH name starts with an underscore. Keeping user
        // names out of that space is what makes the two sets disjoint, so a
        // binding named `_dml` cannot collide with the wrapper of that name.
        let base = match name.starts_with('_') {
            true => format!("w{name}"),
            false => name.to_string(),
        };
        let claimed = self.claim_in_cte_namespace(&base);
        if claimed == name {
            self.cte_sql_names.remove(name);
        } else {
            self.cte_sql_names.insert(name.to_string(), claimed.clone());
        }
        claimed
    }

    fn register_cte(&mut self, name: &str, ir_stmt: &IrStmt) -> String {
        let type_name = cte_stmt_type(ir_stmt);
        self.cte_types.insert(name.to_string(), type_name.clone());
        if let IrStmt::Select(sel) = ir_stmt
            && let [IrRowSource::Free(item)] = sel.rows.as_slice()
        {
            self.cte_free_items.insert(name.to_string(), item.clone());
        }
        self.note_cte_cardinality(name, ir_stmt);
        type_name
    }

    /// True when `sel`'s filter pins an exclusive property to one value, which
    /// makes it single-valued however many rows the table holds. It is why
    /// `(select Installation filter .id = <uuid>$x).connector.provider.staff`
    /// is a value rather than a one-element set.
    fn pins_an_exclusive_property(&self, sel: &IrSelect) -> bool {
        let [IrRowSource::Bound { source, .. }] = sel.rows.as_slice() else {
            return false;
        };
        let Some(filter) = &sel.filter else { return false };
        let Ok(td) = self.resolve_type(&source.type_name) else {
            return false;
        };
        Self::pins_exclusive(td, filter)
    }

    /// Walks the conjuncts of `filter` for an equality against an exclusive or
    /// primary-key column. Only `and` is descended: under `or` either side
    /// could match a different row, so neither pins anything.
    fn pins_exclusive(td: &TypeDescriptor, filter: &IrExpr) -> bool {
        let IrExpr::BinOp(binop) = filter else { return false };
        match binop.op {
            ast::BinOpKind::And => Self::pins_exclusive(td, &binop.left) || Self::pins_exclusive(td, &binop.right),
            ast::BinOpKind::Eq => {
                let column = match (&binop.left, &binop.right) {
                    (IrExpr::ColumnRef { column, .. }, _) => column,
                    (_, IrExpr::ColumnRef { column, .. }) => column,
                    _ => return false,
                };
                td.properties
                    .iter()
                    .any(|p| &p.name == column && (p.is_exclusive || p.is_pk))
            }
            _ => false,
        }
    }

    /// Record `name` when its binding can hold more than one row, so a later
    /// comparison against it compiles to membership rather than a scalar
    /// subquery read. Anything whose row count isn't statically one counts as
    /// multi: a needless membership test still answers correctly, a needless
    /// scalar read aborts the query.
    fn note_cte_cardinality(&mut self, name: &str, ir_stmt: &IrStmt) {
        let single = match ir_stmt {
            IrStmt::Insert(_) => true,
            IrStmt::Select(sel) => {
                matches!(sel.limit, Some(IrExpr::Literal(IrLiteral::Int(1))))
                    || matches!(
                        sel.rows.as_slice(),
                        [IrRowSource::Free(
                            IrFreeExpr::Scalar(_)
                                | IrFreeExpr::FreeObject(_)
                                | IrFreeExpr::NamedTupleRow(_)
                                | IrFreeExpr::Tuple(_)
                        )]
                    )
                    || self.pins_an_exclusive_property(sel)
            }
            _ => false,
        };
        if !single {
            self.multi_row_ctes.insert(name.to_string());
        }
    }

    /// Resolve `root.field1.field2. ... fieldN` where `root` is a WITH-bound
    /// free object (e.g. `with x := { a := { b := 1 } } select x.a.b`) —
    /// `None` when `root` isn't such a binding, so callers fall back to
    /// their normal path resolution. The first step reads the CTE's own
    /// per-field column (`IrExpr::CteFieldRef`, materialized once); any
    /// further steps index into that value as jsonb (`IrExpr::JsonbField`),
    /// since a nested free-object *field* is jsonb the moment it's not the
    /// top-level row itself — validated statically wherever the nesting is
    /// itself a free-object literal (so a typo like `x.a.typo` still gets a
    /// compile error instead of silently returning SQL NULL).
    fn resolve_cte_field_chain(&self, root: &str, steps: &[&str]) -> Option<Result<IrExpr, PyQLError>> {
        let (first, rest) = steps.split_first()?;
        let fields = match self.cte_free_items.get(root)? {
            IrFreeExpr::FreeObject(fields) => fields,
            _ => return None,
        };
        let mut current: &IrExpr = match fields.iter().find(|(n, _)| n == first) {
            Some((_, e)) => e,
            None => {
                return Some(Err(
                    self.type_err(&format!("free object '{root}' has no field '{first}'"))
                ));
            }
        };
        let mut expr = IrExpr::CteFieldRef {
            name: root.to_string(),
            field: first.to_string(),
            pg_type: infer_ir_type(current).map(str::to_string),
        };
        for step in rest {
            if let IrExpr::NamedTuple {
                fields: nested,
                is_free_object: true,
            } = current
            {
                match nested.iter().find(|(n, _)| n == step) {
                    Some((_, next)) => current = next,
                    None => {
                        return Some(Err(
                            self.type_err(&format!("{step} is not a member of the nested free object"))
                        ));
                    }
                }
            }
            expr = IrExpr::JsonbField {
                expr: Box::new(expr),
                field: step.to_string(),
            };
        }
        Some(Ok(expr))
    }

    /// `resolve_cte_field_chain`, but taking the whole `root.f1.f2...` path
    /// directly — `None` when the path isn't an absolute multi-step name
    /// chain (so, in particular, whenever a step is anything other than a
    /// plain name, e.g. a type intersection or backlink).
    fn resolve_cte_path(&self, p: &ast::Path) -> Option<Result<IrExpr, PyQLError>> {
        if p.partial || p.steps.len() < 2 {
            return None;
        }
        let ast::PathStep::Name(root) = &p.steps[0] else {
            return None;
        };
        let mut steps = Vec::with_capacity(p.steps.len() - 1);
        for step in &p.steps[1..] {
            match step {
                ast::PathStep::Name(n) => steps.push(n.as_str()),
                _ => return None,
            }
        }
        self.resolve_cte_field_chain(root, &steps)
    }

    /// Return the CTE name if `expr` is a bare identifier that matches a registered CTE.
    fn resolve_cte_name<'e>(&self, expr: &'e Expr) -> Option<&'e str> {
        if let Expr::Path(p) = expr
            && !p.partial
            && p.steps.len() == 1
            && let ast::PathStep::Name(n) = &p.steps[0]
            && self.cte_types.contains_key(n.as_str())
        {
            return Some(n.as_str());
        }
        None
    }

    /// A reference to the loop variable `name`, under the CTE name its loop
    /// was emitted with. Recorded as read, which is what tells a `with`
    /// binding compiled around it that it belongs to one iteration rather
    /// than to the statement.
    fn for_var_ref(&mut self, name: &str) -> IrExpr {
        let slot = self
            .for_var_slots
            .get(name)
            .cloned()
            .unwrap_or_else(|| name.to_string());
        self.for_vars_read.insert(slot.clone());
        let pg_type = self.for_vars.get(name).cloned();
        IrExpr::ForVar { name: slot, pg_type }
    }

    fn fresh_alias(&mut self) -> String {
        let a = format!("t{}", self.alias_counter);
        self.alias_counter += 1;
        a
    }

    /// A distinct naming scheme from `fresh_alias`'s `t0`, `t1`, ... (table
    /// aliases) so a hoisted nested-DML CTE name can never collide with one
    /// — see `pending_nested_ctes`.
    fn fresh_nested_cte_name(&mut self) -> String {
        let n = self.nested_cte_counter;
        self.nested_cte_counter += 1;
        self.claim_generated_cte_name(&format!("_nested_dml_{n}"))
    }

    /// Register a named parameter and return its 0-based index.
    fn param_index(&mut self, name: &str) -> usize {
        if let Some(i) = self.params.iter().position(|n| n == name) {
            return i;
        }
        let i = self.params.len();
        self.params.push(name.to_string());
        i
    }

    // ── Global variable resolution ────────────────────────────────────────────────

    /// `scalar_type` is a PyQL-style type-name string built by the Python
    /// walker's `_pyql_type_name` (e.g. `"std::str"`, `"std::uuid"`,
    /// `"cal::local_date"`, `"default::Gender"`, `"array<std::str>"`) — never
    /// a bare Python class name. Mirrors every shape `_pyql_type_name` can
    /// produce for a `Global[T]` annotation.
    fn resolve_global_pg_type(&self, scalar_type: &str) -> String {
        // `datetime` and `std::datetime` name the same type.
        let builtin = match scalar_type.strip_prefix("std::").unwrap_or(scalar_type) {
            "str" => Some("text"),
            "int16" => Some("int2"),
            "int32" => Some("int4"),
            "int64" => Some("int8"),
            "float32" => Some("float4"),
            "float64" => Some("float8"),
            "decimal" => Some("numeric"),
            "bool" => Some("boolean"),
            "datetime" => Some("timestamptz"),
            "cal::local_datetime" => Some("timestamp"),
            "cal::local_date" => Some("date"),
            "cal::local_time" => Some("time"),
            "uuid" => Some("uuid"),
            "bytes" => Some("bytea"),
            "json" => Some("jsonb"),
            "duration" => Some("interval"),
            _ => None,
        };
        if let Some(t) = builtin {
            return t.to_string();
        }
        if let Some(inner) = scalar_type.strip_prefix("array<").and_then(|s| s.strip_suffix('>')) {
            return format!("{}[]", self.resolve_global_pg_type(inner));
        }
        if scalar_type.starts_with("tuple<") {
            return "jsonb".to_string();
        }
        if let Some(ed) = self.resolve_enum(scalar_type) {
            return format!("{}.\"{}\"", crate::sql::pg_schema_str(&ed.module), ed.name);
        }
        if self.resolve_named_tuple(scalar_type).is_some() {
            return "jsonb".to_string();
        }
        // Fall back to a registered custom scalar lookup.
        self.schema
            .scalars
            .iter()
            .find(|s| s.name == scalar_type || format!("{}::{}", s.module, s.name) == scalar_type)
            .map(|s| s.pg_type.clone())
            .unwrap_or_else(|| "text".to_string())
    }

    /// When `global name` (or `global name { shape }`) appears as the top-level
    /// SELECT subject, inline the computed expression rather than going through a
    /// CTE — this returns a full object, not just its id.
    fn try_compile_global_select(
        &mut self,
        outer: &ast::SelectStmt,
        result: &Expr,
        _distinct: bool,
    ) -> Result<Option<IrStmt>, PyQLError> {
        let (global_name, shape_elements): (&str, &[ast::ShapeElement]) = match result {
            Expr::Global(name) => (name.as_str(), &[]),
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::Global(name)) => (name.as_str(), sh.elements.as_slice()),
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };

        let global = self
            .schema
            .globals
            .iter()
            .find(|g| g.name == global_name || format!("{}::{}", g.module, g.name) == global_name);
        let global = match global {
            Some(g) => g.clone(),
            None => return Ok(None),
        };
        let computed_expr = match global.computed_expr {
            Some(e) => e,
            None => return Ok(None), // scalar session global — fall through
        };

        let inner_ast = crate::parse::parse(&computed_expr)?;
        let inner_sel = match inner_ast {
            Stmt::Select(sel) => sel,
            _ => return Ok(None),
        };

        let merged_result = if shape_elements.is_empty() {
            inner_sel.result.clone()
        } else {
            Expr::Shape(Box::new(ast::ShapeExpr {
                expr: Some(inner_sel.result.clone()),
                elements: shape_elements.to_vec(),
                marker_offset: None,
            }))
        };

        let merged_filter = match (&inner_sel.filter, &outer.filter) {
            (Some(a), Some(b)) => Some(Expr::BinOp(Box::new(ast::BinOp {
                left: a.clone(),
                op: ast::BinOpKind::And,
                right: b.clone(),
            }))),
            (Some(a), None) => Some(a.clone()),
            (None, b) => b.clone(),
        };

        let merged = ast::SelectStmt {
            result: merged_result,
            filter: merged_filter,
            order_by: if outer.order_by.is_empty() {
                inner_sel.order_by.clone()
            } else {
                outer.order_by.clone()
            },
            offset: outer.offset.clone().or(inner_sel.offset.clone()),
            limit: outer.limit.clone().or(inner_sel.limit.clone()),
            lock: outer.lock.clone().or(inner_sel.lock.clone()),
        };

        let ir = self.compile_stmt(&Stmt::Select(merged))?;
        Ok(Some(ir))
    }

    /// Reading one field off a free object. A free shape is a real object
    /// type, so `{ device := d { id }, … }.device` is an ordinary
    /// path step through a pointer and yields whatever that pointer holds —
    /// an object stays an object. Extracting it out of the jsonb the free
    /// object would otherwise build flattens it back to raw JSON. Any field
    /// left unread still runs: a mutation among them is a data-modifying CTE,
    /// which Postgres executes whether or not the outer query reads it.
    fn project_free_object_field(expr: IrExpr, field: &str) -> IrExpr {
        if let IrExpr::NamedTuple {
            fields,
            is_free_object: true,
        } = &expr
            && let Some((_, value)) = fields.iter().find(|(name, _)| name == field)
        {
            return value.clone();
        }
        IrExpr::JsonbField {
            expr: Box::new(expr),
            field: field.to_string(),
        }
    }

    /// The operands of a union written entirely of relative paths, which are
    /// correlated to the enclosing row and so cannot be hoisted.
    fn union_of_relative_paths(expr: &Expr) -> Option<Vec<ast::Path>> {
        fn walk(expr: &Expr, out: &mut Vec<ast::Path>) -> bool {
            match expr {
                Expr::Union(a, b) => walk(a, out) && walk(b, out),
                Expr::Path(p) if p.partial => {
                    out.push(p.clone());
                    true
                }
                _ => false,
            }
        }
        if !matches!(expr, Expr::Union(_, _)) {
            return None;
        }
        let mut out = vec![];
        walk(expr, &mut out).then_some(out)
    }

    /// `([is Conditional].configs ?? [is Loop].configs)` — the operands of a
    /// coalesce, when every one is a path off the enclosing row. Unlike a
    /// union each operand but the first only contributes when the ones before
    /// it are empty, which is what the caller guards them with.
    fn coalesce_of_relative_paths(expr: &Expr) -> Option<Vec<ast::Path>> {
        fn walk(expr: &Expr, out: &mut Vec<ast::Path>) -> bool {
            match expr {
                Expr::BinOp(b) if b.op == ast::BinOpKind::Coalesce => walk(&b.left, out) && walk(&b.right, out),
                Expr::Path(p) if p.partial => {
                    out.push(p.clone());
                    true
                }
                _ => false,
            }
        }
        if !matches!(expr, Expr::BinOp(b) if b.op == ast::BinOpKind::Coalesce) {
            return None;
        }
        let mut out = vec![];
        walk(expr, &mut out).then_some(out)
    }

    /// `(select Licence filter …) { id }` — a shape written after a
    /// parenthesised sub-select rather than inside it.
    ///
    /// The two mean the same thing, so the shape is pushed onto the inner
    /// statement's own result and the whole thing compiled as the select it
    /// already was. A `with` block is carried through to its inner statement.
    fn shape_over_subquery(&mut self, sh: &ast::ShapeExpr) -> Result<Option<IrExpr>, PyQLError> {
        fn push_shape(stmt: &Stmt, elements: &[ShapeElement]) -> Option<Stmt> {
            match stmt {
                Stmt::Select(sel) => {
                    if matches!(sel.result, Expr::Shape(_)) {
                        return None;
                    }
                    let mut shaped = sel.clone();
                    shaped.result = Expr::Shape(Box::new(ast::ShapeExpr {
                        expr: Some(sel.result.clone()),
                        elements: elements.to_vec(),
                        marker_offset: None,
                    }));
                    Some(Stmt::Select(shaped))
                }
                Stmt::With(w) => {
                    let inner = push_shape(&w.stmt, elements)?;
                    let mut carried = w.clone();
                    carried.stmt = Box::new(inner);
                    Some(Stmt::With(carried))
                }
                _ => None,
            }
        }
        let Some(Expr::SubQuery(stmt)) = sh.expr.as_ref() else {
            return Ok(None);
        };
        let Some(shaped) = push_shape(stmt.as_ref(), &sh.elements) else {
            return Ok(None);
        };
        let single = matches!(
            innermost_select(&shaped).and_then(|s| s.limit.as_ref()),
            Some(Expr::Literal(ast::Literal::Int(1)))
        );
        let IrStmt::Select(select) = self.compile_stmt(&shaped)? else {
            return Ok(None);
        };
        if !matches!(select.rows.as_slice(), [IrRowSource::Bound { .. }]) {
            return Ok(None);
        }
        Ok(Some(if single {
            IrExpr::ObjectSubquery(Box::new(select))
        } else {
            IrExpr::ArrayFromSelect(Box::new(IrArraySource::ObjectSelect(Box::new(select))))
        }))
    }

    /// `(select … limit 1).account { id, name }` — a shape written on what a
    /// projection off a sub-select lands on. Returns the sub-statement and
    /// the field chain, so the shape can ride along with the splice instead
    /// of being rejected as a shape in expression position.
    fn shape_over_subquery_projection(sh: &ast::ShapeExpr) -> Option<(&Stmt, Vec<String>)> {
        let inner = sh.expr.as_ref()?;
        if !matches!(inner, Expr::FieldAccess { .. }) {
            return None;
        }
        let (base, fields) = Self::peel_field_access_chain(inner);
        match base {
            Expr::SubQuery(stmt) => Some((stmt.as_ref(), fields)),
            _ => None,
        }
    }

    /// Peel nested `Expr::FieldAccess` layers (`X.a.b` parses as
    /// `FieldAccess{FieldAccess{X, "a"}, "b"}`) into the innermost root
    /// expression plus the ordered chain of field names.
    /// The junction tables `dml` writes, mapped to the CTE the emitter names
    /// for each append (`{cte}__ml_add_{i}`, see `emit_ml_append_cte`). A walk
    /// off that mutation reads them from there, because Postgres shows a
    /// sibling CTE's inserts nowhere else. Only appends carrying no link
    /// properties qualify: the append CTE returns just the two id columns, so
    /// a walk reading `@prop` off one would name a column it does not have.
    fn junction_overrides_for(dml: &IrStmt, cte_name: &str) -> HashMap<String, JunctionReadOverride> {
        let appends = match dml {
            IrStmt::Insert(ins) => &ins.multi_link_appends,
            IrStmt::Update(upd) => &upd.multi_link_appends,
            _ => return HashMap::new(),
        };
        appends
            .iter()
            .enumerate()
            .filter(|(_, append)| append.values.link_props.is_empty())
            .map(|(i, append)| {
                // The targets themselves may also have been inserted by this
                // statement, in which case they are only in their own CTE too.
                let targets = match &append.values.source {
                    IrMultiLinkValueSource::CteRef(target_cte) => Some(format!("@cte:{target_cte}")),
                    _ => None,
                };
                (
                    append.junction_table.clone(),
                    JunctionReadOverride {
                        junction: format!("@cte:{cte_name}__ml_add_{i}"),
                        targets,
                    },
                )
            })
            .collect()
    }

    /// `(select …).provider[is Individual].staff` — a walk off a sub-select
    /// that includes a step with no expression form of its own. The select is
    /// hoisted into the statement's own WITH and the walk re-rooted at that
    /// binding, which is the `with i := (select …) select i.provider[is …].staff`
    /// spelling that already compiles.
    ///
    /// `None` when this is not that shape — in particular a walk made only of
    /// `.field` steps, which the `FieldAccess` arm already handles and must go
    /// on handling: re-rooting one of those reads the trailing field as jsonb
    /// off an object id instead of as a column.
    fn try_compile_walk_off_subquery(
        &mut self,
        expr: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        if !matches!(expr, Expr::PathStepOn { .. } | Expr::FieldAccess { .. }) {
            return Ok(None);
        }
        let (base, steps) = Self::peel_path_step_chain(expr);
        if !steps.iter().any(|step| !matches!(step, ast::PathStep::Name(_))) {
            return Ok(None);
        }
        let Expr::SubQuery(inner_stmt) = base else {
            return Ok(None);
        };
        // Bound exactly as a `with` alias would be, not via `compile_stmt`.
        let inner = compile_cte_binding(self, &Expr::SubQuery(inner_stmt.clone()))?;
        let cte_name = self.fresh_nested_cte_name();
        let overrides = Self::junction_overrides_for(&inner, &cte_name);
        let type_name = self.register_cte(&cte_name, &inner);
        self.hoisted_ctes.push(IrCteDef {
            name: cte_name.clone(),
            stmt: inner,
            type_name,
            correlated_to: None,
        });
        let mut path_steps = vec![ast::PathStep::Name(cte_name)];
        path_steps.extend(steps);
        let path = ast::Path {
            steps: path_steps,
            partial: false,
        };
        let previous = std::mem::replace(&mut self.junction_read_overrides, overrides);
        let ir = match ctx {
            Some((td, alias)) => self.compile_path(&path, td, alias),
            None => self.compile_free_path(&path),
        };
        self.junction_read_overrides = previous;
        Ok(Some(ir?))
    }

    /// Peel a mixed `.field` / `[is T]` / `@prop` / `.<backlink` walk off a
    /// base that is not itself a path, outermost step last. The counterpart of
    /// `peel_field_access_chain` for a chain that contains a step with no
    /// expression form of its own (see `ast::Expr::PathStepOn`).
    fn peel_path_step_chain(expr: &Expr) -> (&Expr, Vec<ast::PathStep>) {
        let mut steps = Vec::new();
        let mut current = expr;
        loop {
            match current {
                Expr::FieldAccess { expr: inner, field } => {
                    steps.push(ast::PathStep::Name(field.clone()));
                    current = inner;
                }
                Expr::PathStepOn { expr: inner, step } => {
                    steps.push((**step).clone());
                    current = inner;
                }
                _ => break,
            }
        }
        steps.reverse();
        (current, steps)
    }

    fn peel_field_access_chain(expr: &Expr) -> (&Expr, Vec<String>) {
        let mut fields = Vec::new();
        let mut current = expr;
        while let Expr::FieldAccess { expr: inner, field } = current {
            fields.push(field.clone());
            current = inner;
        }
        fields.reverse();
        (current, fields)
    }

    /// Resolve `expr` to the inner `select Type filter ...` statement it
    /// stands for, if any — either a literal subquery (`(select Type filter
    /// ...)`) or a computed global whose defining expression is such a
    /// select. Only bare object-type results are recognized (`select Type
    /// ...`, not `select Type { shape }` or a free expression) — that's the
    /// only shape `.field` access after it can be spliced onto as an
    /// additional path step.
    fn resolve_field_owner_select(&self, expr: &Expr) -> Option<ast::SelectStmt> {
        let sel = match expr {
            Expr::SubQuery(stmt) => match stmt.as_ref() {
                Stmt::Select(sel) => sel.clone(),
                _ => return None,
            },
            Expr::Global(name) => {
                let global = self
                    .schema
                    .globals
                    .iter()
                    .find(|g| g.name == *name || format!("{}::{}", g.module, g.name) == *name)?;
                let computed_expr = global.computed_expr.as_ref()?;
                match crate::parse::parse(computed_expr).ok()? {
                    Stmt::Select(sel) => sel,
                    _ => return None,
                }
            }
            _ => return None,
        };
        // `(select detached T filter … limit 1).field` — at the top level the
        // marker says nothing a field access changes, and the path underneath
        // is the subject to splice the chain onto.
        let mut sel = sel;
        if let Expr::Detached(inner) = &sel.result {
            sel.result = inner.as_ref().clone();
        }
        match &sel.result {
            Expr::Path(p) if !p.partial => Some(sel),
            _ => None,
        }
    }

    /// `global name.field` or `(select Type filter ...).field` (and deeper
    /// chains like `.link.field`) used as the top-level SELECT subject:
    /// rather than treating `.field` as jsonb extraction on an opaque value
    /// (which only makes sense for tuple-typed properties — see
    /// `resolve_property_tuple_shape`), splice the field chain onto the
    /// inner select as additional path steps and recompile as an ordinary
    /// path-select. Mirrors `try_compile_global_select`'s filter/modifier
    /// merge, generalized to a field-access result instead of a bare/shape
    /// global reference.
    /// `(select T filter … limit 1).a.b { … }` compiled as though it were
    /// written `with head := (select T filter … limit 1) select head.a.b { … }`:
    /// the head becomes a binding of its own, so its own row count stays on it
    /// and the walk off it keeps every row it reaches.
    fn compile_walk_off_bound_head(
        &mut self,
        outer: &ast::SelectStmt,
        inner_sel: &ast::SelectStmt,
        fields: &[String],
        trailing_shape: &[ShapeElement],
    ) -> Result<Option<IrStmt>, PyQLError> {
        let head = Expr::SubQuery(Box::new(Stmt::Select(inner_sel.clone())));
        let inner = compile_cte_binding(self, &head)?;
        let cte_name = self.fresh_nested_cte_name();
        let overrides = Self::junction_overrides_for(&inner, &cte_name);
        let type_name = self.register_cte(&cte_name, &inner);
        self.hoisted_ctes.push(IrCteDef {
            name: cte_name.clone(),
            stmt: inner,
            type_name,
            correlated_to: None,
        });
        let mut steps = vec![ast::PathStep::Name(cte_name)];
        steps.extend(fields.iter().cloned().map(ast::PathStep::Name));
        let walk = Expr::Path(ast::Path { steps, partial: false });
        let result = if trailing_shape.is_empty() {
            walk
        } else {
            Expr::Shape(Box::new(ast::ShapeExpr {
                expr: Some(walk),
                elements: trailing_shape.to_vec(),
                marker_offset: None,
            }))
        };
        let rerooted = ast::SelectStmt {
            result,
            filter: outer.filter.clone(),
            order_by: outer.order_by.clone(),
            offset: outer.offset.clone(),
            limit: outer.limit.clone(),
            lock: outer.lock.clone(),
        };
        let previous = std::mem::replace(&mut self.junction_read_overrides, overrides);
        let ir = self.compile_stmt(&Stmt::Select(rerooted));
        self.junction_read_overrides = previous;
        Ok(Some(ir?))
    }

    fn try_compile_field_access_select(
        &mut self,
        outer: &ast::SelectStmt,
        result: &Expr,
    ) -> Result<Option<IrStmt>, PyQLError> {
        // `(select T).chapter { … }` — the parser folds a trailing shape around
        // the whole field access, so the chain has to be peeled out of it or
        // the select reads as one with no type for a subject.
        let (result, trailing_shape): (&Expr, &[ShapeElement]) = match result {
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(inner @ Expr::FieldAccess { .. }) => (inner, sh.elements.as_slice()),
                _ => (result, &[]),
            },
            other => (other, &[]),
        };
        let (root, fields) = Self::peel_field_access_chain(result);
        if fields.is_empty() {
            return Ok(None);
        }
        let inner_sel = match self.resolve_field_owner_select(root) {
            Some(sel) => sel,
            None => return Ok(None),
        };
        let Expr::Path(type_path) = &inner_sel.result else {
            return Ok(None);
        };
        // A sub-select's own `limit`/`offset` counts its rows, not the walk's:
        // `(select Cart filter .id = $c limit 1).applied_promotions` is every
        // promotion of that one cart. Spliced onto the walk the count lands on
        // the result instead and takes one promotion, so the head is bound on
        // its own and walked from there — the `with` spelling, which scopes it.
        if inner_sel.limit.is_some() || inner_sel.offset.is_some() {
            return self.compile_walk_off_bound_head(outer, &inner_sel, &fields, trailing_shape);
        }
        let mut steps = type_path.steps.clone();
        let field_count = fields.len();
        steps.extend(fields.into_iter().map(ast::PathStep::Name));
        let merged_result = Expr::Path(ast::Path { steps, partial: false });

        let merged_filter = match (&inner_sel.filter, &outer.filter) {
            (Some(a), Some(b)) => Some(Expr::BinOp(Box::new(ast::BinOp {
                left: a.clone(),
                op: ast::BinOpKind::And,
                right: b.clone(),
            }))),
            (Some(a), None) => Some(a.clone()),
            (None, b) => b.clone(),
        };

        let merged = ast::SelectStmt {
            result: merged_result,
            filter: merged_filter,
            order_by: if outer.order_by.is_empty() {
                inner_sel.order_by.clone()
            } else {
                outer.order_by.clone()
            },
            offset: outer.offset.clone().or(inner_sel.offset.clone()),
            limit: outer.limit.clone().or(inner_sel.limit.clone()),
            lock: outer.lock.clone().or(inner_sel.lock.clone()),
        };

        // The inner select's own filter and ordering speak about its subject,
        // not about what the field chain projects off it: `(select Individual
        // filter .id = $a).credentials.password` filters Individuals, not
        // Credentials. `tail` is what pins them there. Only safe when the
        // outer select contributed no filter of its own — the merge folds
        // both into one clause, and an outer filter does belong at the end.
        // An outer `order by` belongs at the end too, so it rides along
        // separately rather than costing the inner filter its subject.
        if outer.filter.is_none() {
            let merged = ast::SelectStmt {
                order_by: inner_sel.order_by.clone(),
                ..merged
            };
            let Expr::Path(merged_path) = &merged.result else {
                unreachable!("built as a path just above")
            };
            let ps = self.compile_path_select_with_tail(
                &merged,
                merged_path,
                trailing_shape,
                false,
                field_count,
                &outer.order_by,
            )?;
            return Ok(Some(IrStmt::PathSelect(ps)));
        }

        let merged = if trailing_shape.is_empty() {
            merged
        } else {
            ast::SelectStmt {
                result: Expr::Shape(Box::new(ast::ShapeExpr {
                    expr: Some(merged.result.clone()),
                    elements: trailing_shape.to_vec(),
                    marker_offset: None,
                })),
                ..merged
            }
        };
        let ir = self.compile_stmt(&Stmt::Select(merged))?;
        Ok(Some(ir))
    }

    fn try_compile_alias_select(
        &mut self,
        outer: &ast::SelectStmt,
        result: &Expr,
        distinct: bool,
    ) -> Result<Option<IrStmt>, PyQLError> {
        // Extract the bare path name and any outer shape elements.
        let (path_name, shape_elements): (&str, &[ast::ShapeElement]) = match result {
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    (n.as_str(), &[])
                } else {
                    return Ok(None);
                }
            }
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::Path(p)) if !p.partial && p.steps.len() == 1 => {
                    if let ast::PathStep::Name(n) = &p.steps[0] {
                        (n.as_str(), sh.elements.as_slice())
                    } else {
                        return Ok(None);
                    }
                }
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };

        // Match against schema aliases (bare name or module::name).
        let alias = self
            .schema
            .aliases
            .iter()
            .find(|a| a.name == path_name || format!("{}::{}", a.module, a.name) == path_name);
        let alias = match alias {
            Some(a) => a.clone(),
            None => return Ok(None),
        };

        let inner_ast = crate::parse::parse(&alias.expr)?;
        let inner_sel = match inner_ast {
            Stmt::Select(sel) => sel,
            _ => return Err(self.type_err(&format!("alias '{}' expression must be a select statement", alias.name))),
        };

        // Merge outer shape / filter / modifiers over the alias's select.
        // `inner_sel.result` is itself an `Expr::Shape` whenever the
        // alias's own body declares a shape (e.g. `select Type { field }
        // order by ... limit ...`, a legitimate, documented pattern — an
        // alias's own body may combine a shape with modifiers) — wrapping
        // it wholesale as the outer shape's own `expr` would nest a Shape
        // inside a Shape, which the compiler's SELECT-subject resolution
        // rejects ("expected a type name as SELECT subject", confirmed
        // live). The outer shape must bind to the same underlying *type*
        // reference the alias's own shape does, not to the alias's shape
        // node itself — so unwrap through it first.
        let inner_base = match &inner_sel.result {
            Expr::Shape(sh) => sh.expr.clone(),
            other => Some(other.clone()),
        };
        let merged_result = if shape_elements.is_empty() {
            inner_sel.result.clone()
        } else {
            Expr::Shape(Box::new(ast::ShapeExpr {
                expr: inner_base,
                elements: shape_elements.to_vec(),
                marker_offset: None,
            }))
        };

        let merged_filter = match (&inner_sel.filter, &outer.filter) {
            (Some(a), Some(b)) => Some(Expr::BinOp(Box::new(ast::BinOp {
                left: a.clone(),
                op: ast::BinOpKind::And,
                right: b.clone(),
            }))),
            (Some(a), None) => Some(a.clone()),
            (None, b) => b.clone(),
        };

        let merged = ast::SelectStmt {
            result: merged_result,
            filter: merged_filter,
            order_by: if outer.order_by.is_empty() {
                inner_sel.order_by.clone()
            } else {
                outer.order_by.clone()
            },
            offset: outer.offset.clone().or(inner_sel.offset.clone()),
            limit: outer.limit.clone().or(inner_sel.limit.clone()),
            lock: outer.lock.clone().or(inner_sel.lock.clone()),
        };

        let _ = distinct; // alias selects honour the outer distinct if applied
        let ir = self.compile_stmt(&Stmt::Select(merged))?;
        Ok(Some(ir))
    }

    fn compile_global(&mut self, raw_name: &str) -> Result<IrExpr, PyQLError> {
        let global = self
            .schema
            .globals
            .iter()
            .find(|g| g.name == raw_name || format!("{}::{}", g.module, g.name) == raw_name);
        let global = global
            .ok_or_else(|| {
                PyQLError::Resolution(PyQLResolutionError::UnknownField(PyQLUnknownFieldError {
                    message: format!("unknown global: {:?}", raw_name),
                    position: Position { line: 0, col: 0 },
                }))
            })?
            .clone();

        let qualified = format!("{}::{}", global.module, global.name);
        let cte_name = format!("__global__{}", qualified);

        if let Some(computed_expr) = global.computed_expr {
            // Computed global — check for duplicate before compiling
            if self.global_ctes.iter().any(|g| g.cte_name() == cte_name) {
                return Ok(IrExpr::GlobalRef { cte_name });
            }
            // Recursively compile the PyQL expression (shares params and global_ctes)
            let inner_ast = crate::parse::parse(&computed_expr)?;
            let inner_stmt = self.compile_stmt(&inner_ast)?;
            self.global_ctes
                .push(IrGlobalCte::Computed(Box::new(IrComputedGlobalCte {
                    cte_name: cte_name.clone(),
                    qualified_name: qualified,
                    stmt: inner_stmt,
                })));
            Ok(IrExpr::GlobalRef { cte_name })
        } else if self.in_fn_body {
            // Inside a function body there is no parameter to bind, so the
            // value is read out of the `__pylon_json_globals__` argument the
            // caller packs.
            let pg_type = self.resolve_global_pg_type(&global.scalar_type);
            self.used_globals_arg = true;
            // Wrapped in a cast rather than returned bare: `RawSql` carries no
            // type, so overload resolution fell back to text and picked the
            // `str` `find` for an `array<str>` global (`strpos(text[], text)
            // does not exist`).
            Ok(IrExpr::TypeCast(Box::new(super::IrTypeCast {
                expr: IrExpr::RawSql(globals_arg_read(&qualified, &pg_type)),
                pg_type,
                tuple_shape: None,
            })))
        } else {
            // Session global — allocate parameter slot
            let pg_type = self.resolve_global_pg_type(&global.scalar_type);
            let param_name = format!("__global__{}", qualified);
            let index = self.param_index(&param_name);
            // Register CTE only once
            if !self.global_ctes.iter().any(|g| g.cte_name() == cte_name) {
                self.global_ctes.push(IrGlobalCte::Session(IrSessionGlobalCte {
                    cte_name,
                    qualified_name: qualified,
                    param_index: index,
                    pg_type: pg_type.clone(),
                }));
            }
            Ok(IrExpr::GlobalParam { index, pg_type })
        }
    }

    // ── Schema lookups ────────────────────────────────────────────────────────────

    /// The object type a WITH binding names, if it binds one — object type
    /// strings are qualified, free/scalar bindings' are not.
    fn cte_object_type(&self, name: &str) -> Option<String> {
        self.cte_types.get(name).filter(|t| t.contains("::")).cloned()
    }

    fn resolve_type(&self, name: &str) -> Result<&'a TypeDescriptor, PyQLError> {
        // Accept both "TypeName" and "module::TypeName"
        self.schema
            .types
            .iter()
            .find(|t| t.name == name || format!("{}::{}", t.module, t.name) == name)
            .ok_or_else(|| {
                PyQLError::Resolution(PyQLResolutionError::UnknownType(PyQLUnknownTypeError {
                    message: format!("unknown type '{name}'"),
                    position: Position { line: 0, col: 0 },
                }))
            })
    }

    /// A schema enum, or failing that one the stdlib defines (`std::Endian`).
    /// The stdlib's are `&'static`, which coerces to `&'a` for any shorter
    /// `'a`, so both live behind one lookup and every site that recognizes
    /// enum member access picks them up without its own special case.
    fn resolve_enum(&self, name: &str) -> Option<&'a crate::schema::EnumDescriptor> {
        self.schema
            .enums
            .iter()
            .find(|e| e.name == name || format!("{}::{}", e.module, e.name) == name)
            .or_else(|| crate::stdlib::lookup_enum(name))
    }

    /// Resolve a `Channel` by name (bare or `module::Name`) — used by
    /// `notify()` to find the declared payload shape its second argument
    /// must match.
    fn resolve_channel(&self, name: &str) -> Option<&'a crate::schema::ChannelDescriptor> {
        self.schema.find_channel(name)
    }

    /// Resolve a registered custom scalar (`pylon.scalar(..., name=...)` or
    /// the `@pylon.scalar` decorator form) by name — used to recognize a
    /// cast target as that scalar's own PostgreSQL DOMAIN (see
    /// `resolve_cast_pg_type`); an anonymous (unregistered) scalar has no
    /// name reachable here at all, so it's never a valid cast target.
    fn resolve_scalar(&self, name: &str) -> Option<&'a crate::schema::ScalarDescriptor> {
        self.schema
            .scalars
            .iter()
            .find(|s| s.name == name || format!("{}::{}", s.module, s.name) == name)
    }

    /// Resolve a registered (nominal) `@pylon.named_tuple` type by name — used only
    /// to recognize a cast target as a named tuple (member structure isn't
    /// validated here; the value is trusted the same way a plain `<json>` cast is).
    fn resolve_named_tuple(&self, name: &str) -> Option<&'a crate::schema::NamedTupleDescriptor> {
        self.schema
            .named_tuples
            .iter()
            .find(|nt| nt.name == name || format!("{}::{}", nt.module, nt.name) == name)
    }

    /// Convert a schema-level `TupleMemberDescriptor` into a decode-time
    /// `JsonMember` — recurses for a nested tuple member, resolving a nested
    /// *nominal* member's own registered members too.
    fn tuple_member_to_json_member(&self, m: &crate::schema::TupleMemberDescriptor) -> crate::query::JsonMember {
        use crate::schema::TupleMemberKind;
        let kind = match &m.kind {
            TupleMemberKind::Scalar { .. } => crate::query::JsonMemberKind::Scalar,
            TupleMemberKind::Enum { module, name } => crate::query::JsonMemberKind::Enum {
                enum_type: format!("{}::{}", module, name),
            },
            TupleMemberKind::NamedTuple { module, name } => {
                let qname = format!("{}::{}", module, name);
                let nested_members = self
                    .resolve_named_tuple(&qname)
                    .map(|nt| {
                        nt.members
                            .iter()
                            .map(|mm| self.tuple_member_to_json_member(mm))
                            .collect()
                    })
                    .unwrap_or_default();
                crate::query::JsonMemberKind::Tuple {
                    type_name: Some(qname),
                    members: nested_members,
                }
            }
            TupleMemberKind::Tuple { members } => crate::query::JsonMemberKind::Tuple {
                type_name: None,
                members: members.iter().map(|mm| self.tuple_member_to_json_member(mm)).collect(),
            },
        };
        crate::query::JsonMember {
            key: m.name.clone(),
            kind,
        }
    }

    /// Convert a parsed cast-target `ast::TupleTypeElement` into a decode-time
    /// `JsonMember` — the cast-syntax counterpart of `tuple_member_to_json_member`.
    fn ast_tuple_element_to_json_member(&self, elem: &ast::TupleTypeElement) -> crate::query::JsonMember {
        crate::query::JsonMember {
            key: elem.name.clone(),
            kind: self.ast_type_expr_to_json_member_kind(&elem.ty),
        }
    }

    fn ast_type_expr_to_json_member_kind(&self, ty: &ast::TypeExpr) -> crate::query::JsonMemberKind {
        if let ast::TypeExpr::Tuple { elements } = ty {
            return crate::query::JsonMemberKind::Tuple {
                type_name: None,
                members: elements
                    .iter()
                    .map(|e| self.ast_tuple_element_to_json_member(e))
                    .collect(),
            };
        }
        let Some((module, name)) = ty.as_named() else {
            return crate::query::JsonMemberKind::Scalar;
        };
        let qname = match module {
            Some(m) => format!("{}::{}", m, name),
            None => name.to_string(),
        };
        if let Some(ed) = self.resolve_enum(&qname) {
            return crate::query::JsonMemberKind::Enum {
                enum_type: format!("{}::{}", ed.module, ed.name),
            };
        }
        if let Some(nt) = self.resolve_named_tuple(&qname) {
            return crate::query::JsonMemberKind::Tuple {
                type_name: Some(format!("{}::{}", nt.module, nt.name)),
                members: nt.members.iter().map(|m| self.tuple_member_to_json_member(m)).collect(),
            };
        }
        crate::query::JsonMemberKind::Scalar
    }

    /// Resolve a cast's own target-type shape for decode-time `ShapeNode`
    /// building — a structural `tuple<...>` cast resolves its elements
    /// directly; a nominal `<module::Name>` cast resolves via the registered
    /// `NamedTupleDescriptor`'s members. `None` for a plain scalar/enum
    /// cast target.
    fn resolve_tuple_cast_shape(&self, ty: &ast::TypeExpr) -> Option<TupleCastShape> {
        match ty {
            ast::TypeExpr::Tuple { elements } => Some(TupleCastShape {
                type_name: None,
                members: elements
                    .iter()
                    .map(|e| self.ast_tuple_element_to_json_member(e))
                    .collect(),
            }),
            _ => {
                let (module, name) = ty.as_named()?;
                let qname = match module {
                    Some(m) => format!("{}::{}", m, name),
                    None => name.to_string(),
                };
                let nt = self.resolve_named_tuple(&qname)?;
                Some(TupleCastShape {
                    type_name: Some(format!("{}::{}", nt.module, nt.name)),
                    members: nt.members.iter().map(|m| self.tuple_member_to_json_member(m)).collect(),
                })
            }
        }
    }

    /// Render a cast target `TypeExpr` for error messages, e.g.
    /// `tuple<std::int64, std::str>` or `default::Point` — used by the
    /// compile-time tuple-index bounds check.
    fn type_expr_to_display_str(&self, ty: &ast::TypeExpr) -> String {
        match ty {
            ast::TypeExpr::Tuple { elements } => {
                let inner = elements
                    .iter()
                    .map(|e| match &e.name {
                        Some(n) => format!("{}: {}", n, self.type_expr_to_display_str(&e.ty)),
                        None => self.type_expr_to_display_str(&e.ty),
                    })
                    .collect::<Vec<_>>()
                    .join(", ");
                format!("tuple<{}>", inner)
            }
            ast::TypeExpr::Array { element } => format!("array<{}>", self.type_expr_to_display_str(element)),
            ast::TypeExpr::Named { module, name } => match module {
                Some(m) => format!("{}::{}", m, name),
                None => type_expr_to_pg(ty)
                    .map(|pg| pg_type_to_pyql(&pg).to_string())
                    .unwrap_or_else(|_| name.clone()),
            },
        }
    }

    /// Resolve a property's tuple-type shape for decode-time `ShapeNode`
    /// building — a nominal `__nt__:module::Name` `pg_type` marker resolves
    /// via the registered `NamedTupleDescriptor`'s own members; a structural
    /// `pylon.Tuple[...]` property carries its own `tuple_members` directly.
    fn resolve_property_tuple_shape(&self, prop: &PropertyDescriptor) -> Option<TupleCastShape> {
        if let Some(qname) = prop.pg_type.strip_prefix("__nt__:") {
            let nt = self.resolve_named_tuple(qname)?;
            return Some(TupleCastShape {
                type_name: Some(qname.to_string()),
                members: nt.members.iter().map(|m| self.tuple_member_to_json_member(m)).collect(),
            });
        }
        prop.tuple_members.as_ref().map(|members| TupleCastShape {
            type_name: None,
            members: members.iter().map(|m| self.tuple_member_to_json_member(m)).collect(),
        })
    }

    /// Emit a bare `<pg_type>expr` scalar cast as a free-select statement — shared
    /// by the enum/named-tuple/structural-tuple cast cases in `compile_stmt`'s
    /// top-level `Expr::TypeCast` handling. For a structural tuple cast whose
    /// source is itself a tuple/named-tuple literal, applies each element's
    /// own cast by position (see `try_compile_tuple_literal_cast_ctx`)
    /// instead of jsonb-wrapping the raw uncast literal values.
    fn scalar_cast_free_select(
        &mut self,
        tc: &ast::TypeCast,
        pg_type: String,
        distinct: bool,
    ) -> Result<IrStmt, PyQLError> {
        let cast_expr = match &tc.ty {
            ast::TypeExpr::Tuple { elements } => {
                let tuple_shape = self.resolve_tuple_cast_shape(&tc.ty);
                match self.try_compile_tuple_literal_cast_ctx(elements, &tc.expr, None)? {
                    // The literal-decompose path already applies each element's own
                    // cast — still wrap in TypeCast so `tuple_shape` reaches SQL
                    // emission for decode-time ShapeNode building (jsonb_build_*
                    // already produces jsonb, so the outer `::jsonb` is a no-op).
                    Some(ir) => IrExpr::TypeCast(Box::new(IrTypeCast {
                        expr: ir,
                        pg_type,
                        tuple_shape,
                    })),
                    None => {
                        let inner = self.compile_expr_ctx(&tc.expr, None)?;
                        IrExpr::TypeCast(Box::new(IrTypeCast {
                            expr: inner,
                            pg_type,
                            tuple_shape,
                        }))
                    }
                }
            }
            _ => {
                let inner = self.compile_expr_ctx(&tc.expr, None)?;
                let tuple_shape = self.resolve_tuple_cast_shape(&tc.ty);
                IrExpr::TypeCast(Box::new(IrTypeCast {
                    expr: inner,
                    pg_type,
                    tuple_shape,
                }))
            }
        };
        Ok(IrStmt::Select(IrSelect {
            rows: vec![IrRowSource::Free(IrFreeExpr::Scalar(cast_expr))],
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            distinct,
            dml_source: None,
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: vec![],
            lock: None,
        }))
    }

    /// Resolve a cast's target `pg_type` string — shared by both `Expr::TypeCast`
    /// compile sites (`compile_free_expr`/`compile_expr`). A structural tuple
    /// always resolves to jsonb; an array resolves to its element's own pg_type
    /// with a `[]` suffix — a real Postgres array, not jsonb, so it decodes
    /// natively (the driver already returns a Python list) with no per-member
    /// shape-tracking needed the way tuples require; a named type checks enum,
    /// then registered named tuple, then falls back to the built-in
    /// scalar/pgvector/cal type list.
    fn resolve_cast_pg_type(&self, ty: &ast::TypeExpr) -> Result<String, PyQLError> {
        if matches!(ty, ast::TypeExpr::Tuple { .. }) {
            return Ok("jsonb".to_string());
        }
        if let ast::TypeExpr::Array { element } = ty {
            let element_pg = self.resolve_cast_pg_type(element)?;
            return Ok(format!("{}[]", element_pg));
        }
        let (module, name) = ty.as_named().expect("checked above: not Tuple/Array");
        let qname = match module {
            Some(m) => format!("{}::{}", m, name),
            None => name.to_string(),
        };
        if let Some(ed) = self.resolve_enum(&qname) {
            return Ok(format!("{}.\"{}\"", crate::sql::pg_schema_str(&ed.module), ed.name));
        }
        if self.resolve_named_tuple(&qname).is_some() {
            return Ok("jsonb".to_string());
        }
        // A registered custom scalar casts directly to its own DOMAIN (not
        // just its base type) — Postgres enforces the domain's CHECK right
        // at cast time, the same way it would on column assignment (see
        // `PropertyDescriptor.column_type`'s own doc comment for why this
        // is safe to do everywhere else too).
        if let Some(sd) = self.resolve_scalar(&qname) {
            return Ok(format!("{}.\"{}\"", crate::sql::pg_schema_str(&sd.module), sd.name));
        }
        type_expr_to_pg(ty)
    }

    /// Cast one tuple-type element's source value to `target_ty` — recurses
    /// via `try_compile_tuple_literal_cast_ctx` when both the element's own
    /// type and its source value are themselves a nested tuple/named-tuple
    /// literal, so nesting applies per-element casts all the way down;
    /// otherwise a plain scalar/enum/nominal-named-tuple cast.
    fn compile_tuple_element_cast_ctx(
        &mut self,
        target_ty: &ast::TypeExpr,
        value: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        if let ast::TypeExpr::Tuple { elements } = target_ty
            && let Some(ir) = self.try_compile_tuple_literal_cast_ctx(elements, value, ctx)?
        {
            return Ok(ir);
        }
        let inner = self.compile_expr_ctx(value, ctx)?;
        let pg_type = self.resolve_cast_pg_type(target_ty)?;
        Ok(IrExpr::TypeCast(Box::new(IrTypeCast {
            expr: inner,
            pg_type,
            tuple_shape: None,
        })))
    }

    /// When casting a tuple/named-tuple *literal* to a structural tuple type,
    /// apply each target element's own cast to its corresponding source value
    /// by position — e.g. `<tuple<int64, str>>('1', 3)` must coerce '1' to
    /// int64 and 3 to str, not just jsonb-wrap the raw literal values
    /// unchanged. Returns `None` when the source isn't a literal tuple/named-
    /// tuple of matching arity (e.g. a `$param`) — the whole value already
    /// arrives pre-shaped in that case, so the caller's generic jsonb-cast
    /// path handles it instead.
    fn try_compile_tuple_literal_cast_ctx(
        &mut self,
        target_elements: &[ast::TupleTypeElement],
        source: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        let source_values: Vec<&Expr> = match source {
            Expr::Tuple(vals) if vals.len() == target_elements.len() => vals.iter().collect(),
            Expr::NamedTuple(fields) if fields.len() == target_elements.len() => {
                fields.iter().map(|(_, v)| v).collect()
            }
            _ => return Ok(None),
        };
        let named = target_elements.iter().all(|e| e.name.is_some());
        let mut casted = Vec::with_capacity(target_elements.len());
        for (elem, value) in target_elements.iter().zip(source_values) {
            casted.push(self.compile_tuple_element_cast_ctx(&elem.ty, value, ctx)?);
        }
        if named {
            let fields = target_elements
                .iter()
                .zip(casted)
                .map(|(e, v)| (e.name.clone().unwrap(), v))
                .collect();
            Ok(Some(IrExpr::NamedTuple {
                fields,
                is_free_object: false,
            }))
        } else {
            Ok(Some(IrExpr::Tuple(casted)))
        }
    }

    /// When casting an array *literal* to `array<T>`, apply the element
    /// type's own cast to each element by position — e.g.
    /// `<array<int64>>['1', '3']` must coerce each string element to int64,
    /// not just emit a raw untyped `ARRAY[...]`. Reuses
    /// `compile_tuple_element_cast_ctx` for the per-element cast since
    /// casting "this value to this target type" is exactly the same
    /// operation regardless of whether the target is a tuple element or an
    /// array element (including decomposing a nested tuple-literal element).
    /// Returns `None` when the source isn't a literal array (e.g. a
    /// `$param` or a sub-select) — the caller's generic cast path handles
    /// those instead.
    fn try_compile_array_literal_cast_ctx(
        &mut self,
        element_ty: &ast::TypeExpr,
        source: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        let Expr::Array(elems) = source else { return Ok(None) };
        let casted = elems
            .iter()
            .map(|e| self.compile_tuple_element_cast_ctx(element_ty, e, ctx))
            .collect::<Result<Vec<_>, _>>()?;
        Ok(Some(IrExpr::Array(casted)))
    }

    fn compile_enum_access(&self, type_ref: &str, variant: &str) -> Result<IrExpr, PyQLError> {
        let ed = self
            .resolve_enum(type_ref)
            .ok_or_else(|| self.type_err(&format!("unknown type '{}'", type_ref)))?;
        if !ed.members.iter().any(|m| m == variant) {
            return Err(self.type_err(&format!(
                "enum '{}::{}' has no member '{}'",
                ed.module, ed.name, variant
            )));
        }
        // A stdlib enum has no PostgreSQL enum type to cast to — the function
        // taking it switches on the label as text.
        let pg_type = if crate::stdlib::lookup_enum(&format!("{}::{}", ed.module, ed.name)).is_some() {
            "text".to_string()
        } else {
            format!("{}.\"{}\"", crate::sql::pg_schema_str(&ed.module), ed.name)
        };
        Ok(IrExpr::EnumLiteral {
            pg_type,
            variant: variant.to_string(),
        })
    }

    /// The row source a name reads from: the binding it is bound to, if any,
    /// else the type's own table.
    fn row_source_table(&self, name: &str, td: &TypeDescriptor) -> String {
        if let Some(cte) = self.for_var_ctes.get(name) {
            return self.cte_source_table(cte);
        }
        if self.cte_object_type(name).is_some() {
            return self.cte_source_table(&self.cte_sql_name(name));
        }
        td.table.clone()
    }

    /// The type a path's root names — a real type, or the object type a
    /// `with` binding stands for.
    ///
    /// A binding is a row source just like a type name, so anything that
    /// re-resolves a root after `compile_path_select` has already accepted it
    /// has to look it up the same way, or a bound alias reads as an unknown
    /// type.
    fn resolve_path_root(&self, root_name: &str) -> Result<&'a TypeDescriptor, PyQLError> {
        if let Some(qualified) = self.for_var_types.get(root_name) {
            return self.resolve_type(qualified);
        }
        match self.cte_types.get(root_name).filter(|t| t.contains("::")).cloned() {
            Some(bound) => self.resolve_type(&bound),
            None => self.resolve_type(root_name),
        }
    }

    fn find_poly_implementors(&self, iface_qname: &str) -> Vec<IrPolyImplementor> {
        self.schema
            .types
            .iter()
            .filter(|t| !t.abstract_ && Self::is_or_implements(t, iface_qname))
            .map(|t| IrPolyImplementor {
                type_name: format!("{}::{}", t.module, t.name),
                table: t.table.clone(),
                module: t.module.clone(),
            })
            .collect()
    }

    fn resolve_property<'t>(td: &'t TypeDescriptor, name: &str) -> Option<&'t PropertyDescriptor> {
        td.properties.iter().find(|p| p.name == name)
    }

    fn resolve_link<'t>(td: &'t TypeDescriptor, name: &str) -> Option<&'t LinkDescriptor> {
        td.links.iter().find(|l| l.name == name)
    }

    fn resolve_multilink<'t>(td: &'t TypeDescriptor, name: &str) -> Option<&'t MultiLinkDescriptor> {
        td.multilinks.iter().find(|m| m.name == name)
    }

    /// `@prop` read off the junction row of the multi-link currently in
    /// scope (`link_prop_scope`). Only its own modifiers put one there —
    /// anywhere else there is no junction row to read.
    fn compile_link_prop_ref(&mut self, prop_name: &str) -> Result<IrExpr, PyQLError> {
        let Some(scope) = self.link_prop_scope.last().cloned() else {
            return Err(self.type_err(&format!(
                "'@{prop_name}' is a link property, so it is only valid in the modifiers or shape of the \
                 link it belongs to, e.g. 'locators: {{ … }} filter @{prop_name}'"
            )));
        };
        let Some((through_qname, junction_alias)) = scope else {
            return Err(self.type_err(&format!(
                "this link has no link properties, so '@{prop_name}' cannot be read — \
                 declare the link with a `Through[...]` type to give it some"
            )));
        };
        let through_td = self.resolve_type(&through_qname)?;
        let Some(prop) = Self::resolve_property(through_td, prop_name) else {
            return Err(self.field_err(prop_name, &through_qname));
        };
        Ok(IrExpr::ColumnRef {
            alias: junction_alias,
            column: prop.name.clone(),
            pg_type: prop.pg_type.clone(),
        })
    }

    /// Whether a link declared with `target` reaches the type named
    /// `current_qname` — directly, or because that type implements the
    /// interface the link points at. A link to an interface accepts every
    /// implementor, so a backlink from one is exactly as valid as a backlink
    /// from the interface itself.
    fn link_target_reaches(&self, target: &str, current_qname: &str) -> bool {
        if target == current_qname {
            return true;
        }
        self.resolve_type(current_qname)
            .is_ok_and(|td| td.interfaces.iter().any(|i| i == target))
    }

    /// A computed pointer visible on `td` — its own, or one declared on an
    /// interface it implements. An interface's computeds are not copied into
    /// its implementors the way its stored pointers are, so without the
    /// second lookup `.account.tier` reported that `tier` was missing while
    /// suggesting `tier` (the suggester already searched interfaces).
    fn resolve_computed(&self, td: &TypeDescriptor, name: &str) -> Option<crate::schema::ComputedDescriptor> {
        if let Some(cd) = td.computed.iter().find(|c| c.name == name) {
            return Some(cd.clone());
        }
        td.interfaces
            .iter()
            .filter_map(|iface| self.resolve_type(iface).ok())
            .find_map(|itd| itd.computed.iter().find(|c| c.name == name))
            .cloned()
    }

    // ── Statement dispatch ────────────────────────────────────────────────────────

    fn compile_stmt(&mut self, stmt: &Stmt) -> Result<IrStmt, PyQLError> {
        match stmt {
            Stmt::Select(s) => {
                let (distinct, result) = match &s.result {
                    Expr::UnaryOp(u) if u.op == ast::UnaryOpKind::Distinct => (true, &u.operand),
                    // `detached` marks this select as independent of the one
                    // enclosing it. At the top level that is already true, but
                    // for a select nested in a filter it is the whole point:
                    // it is what lets `select X filter not exists (select
                    // detached X filter .k = X.k)` mean "no *other* X", rather
                    // than comparing the inner row with itself. Stripping the
                    // wrapper outright made that anti-join a tautology
                    // (`"t1"."label" = "t1"."label"`) with no error.
                    Expr::Detached(inner) => {
                        self.pending_detached = true;
                        (false, inner.as_ref())
                    }
                    other => (false, other),
                };

                // `select assert_distinct(f(…)) { … }` — the function's rows,
                // with the assert run once over all of them: the select's own
                // filter narrows what comes back, not what is checked.
                if let Expr::Shape(sh) = result
                    && let Some(Expr::FunctionCall(assert)) = &sh.expr
                    && assert.module.as_deref().is_none_or(|m| m == "std")
                    && matches!(assert.name.as_str(), "assert_exists" | "assert_distinct")
                    && let [Expr::FunctionCall(inner)] = assert.args.as_slice()
                    && let Some(mut fs) = self.try_compile_fn_object_select(inner, &sh.elements, s, distinct)?
                {
                    let message = self.assert_message(assert, None)?;
                    let unchecked = ast::SelectStmt {
                        result: Expr::FunctionCall(inner.clone()),
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        lock: None,
                    };
                    let every_row = self
                        .try_compile_fn_object_select(inner, &[], &unchecked, false)?
                        .ok_or_else(|| self.type_err("assert subject is not an object-returning function"))?;
                    let checked = IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: Some("_pylon".to_string()),
                        name: assert.name.clone(),
                        args: std::iter::once(IrExpr::ArrayFromSelect(Box::new(IrArraySource::StmtColumn {
                            stmt: Box::new(IrStmt::FunctionSelect(every_row)),
                            column: "id".to_string(),
                        })))
                        .chain(message)
                        .collect(),
                        sql_template: None,
                    });
                    let check = IrExpr::BinOp(Box::new(IrBinOp {
                        left: IrExpr::FunctionCall(IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: "cardinality".to_string(),
                            args: vec![checked],
                            sql_template: None,
                        }),
                        op: ast::BinOpKind::Ge,
                        right: IrExpr::Literal(IrLiteral::Int(0)),
                    }));
                    fs.filter = and_conditions(fs.filter, vec![check]);
                    return Ok(IrStmt::FunctionSelect(fs));
                }
                if let Some(flattened) = flatten_shape_subject(result) {
                    let mut flat = s.clone();
                    flat.result = match distinct {
                        true => Expr::UnaryOp(Box::new(ast::UnaryOp {
                            op: ast::UnaryOpKind::Distinct,
                            operand: flattened,
                        })),
                        false => flattened,
                    };
                    return self.compile_stmt(&Stmt::Select(flat));
                }
                if let Expr::Shape(sh) = result
                    && let Some(Expr::SubQuery(inner)) = &sh.expr
                    && let Stmt::Group(g) = inner.as_ref()
                {
                    return self.compile_group_projection(s, g, &sh.elements).map(IrStmt::Group);
                }

                // `select alias_name [{ shape }]` — inline the alias expression.
                if let Some(ir) = self.try_compile_alias_select(s, result, distinct)? {
                    return Ok(ir);
                }

                // `select global name [{ shape }]` — inline the computed expression.
                if let Some(ir) = self.try_compile_global_select(s, result, distinct)? {
                    return Ok(ir);
                }

                // `global name.field` / `(select Type filter ...).field` — splice the
                // field access onto the inner type-select as an additional path step.
                if let Some(ir) = self.try_compile_field_access_select(s, result)? {
                    return Ok(ir);
                }

                // select fn() { shape } — user-defined object-returning function with shape.
                if let Expr::Shape(sh) = result
                    && let Some(Expr::FunctionCall(fc)) = sh.expr.as_ref()
                    && let Some(ir) = self.try_compile_fn_object_select(fc, &sh.elements, s, distinct)?
                {
                    return Ok(IrStmt::FunctionSelect(ir));
                }

                // select fn() — bare user-defined object-returning function (no shape).
                if let Expr::FunctionCall(fc) = result
                    && let Some(ir) = self.try_compile_fn_object_select(fc, &[], s, distinct)?
                {
                    return Ok(IrStmt::FunctionSelect(ir));
                }

                // select vector::search(Type, $vec) { object { … }, distance }
                if let Expr::Shape(sh) = result
                    && let Some(Expr::FunctionCall(fc)) = sh.expr.as_ref()
                {
                    if let Some(ir) = self.try_compile_vector_search(fc, &sh.elements, s)? {
                        return Ok(IrStmt::VectorSearch(ir));
                    }
                    if let Some(ir) = self.try_compile_fts_search(fc, &sh.elements, s)? {
                        return Ok(IrStmt::FtsSearch(ir));
                    }
                }
                // bare vector::search / fts::search without shape
                if let Expr::FunctionCall(fc) = result {
                    if let Some(ir) = self.try_compile_vector_search(fc, &[], s)? {
                        return Ok(IrStmt::VectorSearch(ir));
                    }
                    if let Some(ir) = self.try_compile_fts_search(fc, &[], s)? {
                        return Ok(IrStmt::FtsSearch(ir));
                    }
                }

                // (<Module::Type>expr) { shape } — parenthesised id-lookup with shape.
                // The parens are stripped by the parser, leaving Shape { expr: TypeCast }.
                // Only meaningful for a named schema type — a structural tuple cast
                // never denotes an object-type lookup.
                if let Expr::Shape(sh) = result
                    && let Some(Expr::TypeCast(tc)) = sh.expr.as_ref()
                    && let Some((module, name)) = tc.ty.as_named()
                    && module
                        .map(|m| !["std", "cal", "math", "sys", "pgvector", "crypto", "postgis"].contains(&m))
                        .unwrap_or(false)
                {
                    let id_filter = Expr::BinOp(Box::new(ast::BinOp {
                        left: Expr::Path(ast::Path::relative("id")),
                        op: ast::BinOpKind::Eq,
                        right: tc.expr.clone(),
                    }));
                    let merged_filter = match &s.filter {
                        None => Some(id_filter),
                        Some(existing) => Some(Expr::BinOp(Box::new(ast::BinOp {
                            left: id_filter,
                            op: ast::BinOpKind::And,
                            right: existing.clone(),
                        }))),
                    };
                    // Keep the module qualification so an unknown
                    // target reports its full name, not a bare one.
                    let qname = match module {
                        Some(m) => format!("{}::{}", m, name),
                        None => name.to_string(),
                    };
                    let synthetic = ast::SelectStmt {
                        result: Expr::Shape(Box::new(ast::ShapeExpr {
                            expr: Some(Expr::Path(ast::Path::absolute(&qname))),
                            elements: sh.elements.clone(),
                            marker_offset: None,
                        })),
                        filter: merged_filter,
                        order_by: s.order_by.clone(),
                        offset: s.offset.clone(),
                        limit: s.limit.clone(),
                        lock: s.lock.clone(),
                    };
                    return self
                        .compile_select(&synthetic, &synthetic.result, distinct)
                        .map(IrStmt::Select);
                }
                // <Module::Type>expr — schema object lookup by id, or a scalar cast
                // (enum, registered named tuple, or a bare structural `tuple<...>`).
                // Stdlib modules are handled by compile_free_expr; only user schema
                // modules (or a structural tuple, which has no module at all) route here.
                const STDLIB_MODULES: &[&str] = &["std", "cal", "math", "sys", "pgvector", "crypto", "postgis"];
                if let Expr::TypeCast(tc) = result {
                    // A structural tuple cast is always a plain scalar (jsonb) cast —
                    // never an object-type lookup — so it's handled directly, before
                    // any of the qname-based (named-type-only) checks below.
                    if matches!(&tc.ty, ast::TypeExpr::Tuple { .. }) {
                        return self.scalar_cast_free_select(tc, "jsonb".to_string(), distinct);
                    }
                    if let Some((module, name)) = tc.ty.as_named() {
                        let qname = match module {
                            Some(m) => format!("{}::{}", m, name),
                            None => name.to_string(),
                        };
                        if let Some(ed) = self.resolve_enum(&qname) {
                            let pg_type = format!("{}.\"{}\"", crate::sql::pg_schema_str(&ed.module), ed.name);
                            return self.scalar_cast_free_select(tc, pg_type, distinct);
                        }
                        if self.resolve_named_tuple(&qname).is_some() {
                            return self.scalar_cast_free_select(tc, "jsonb".to_string(), distinct);
                        }
                        if let Some(sd) = self.resolve_scalar(&qname) {
                            let pg_type = format!("{}.\"{}\"", crate::sql::pg_schema_str(&sd.module), sd.name);
                            return self.scalar_cast_free_select(tc, pg_type, distinct);
                        }
                        if module.map(|m| !STDLIB_MODULES.contains(&m)).unwrap_or(false) {
                            return self.compile_schema_cast_select(s, tc).map(IrStmt::Select);
                        }
                    }
                }
                // Path traversal: `select TypeName.link.prop` or `select TypeName.link { shape }`.
                if let Expr::Path(p) = result {
                    if !p.partial
                        && p.steps.len() == 2
                        && let [ast::PathStep::Name(type_ref), ast::PathStep::Name(variant)] = p.steps.as_slice()
                        && self.resolve_enum(type_ref).is_some()
                    {
                        let expr = self.compile_enum_access(type_ref, variant)?;
                        return Ok(IrStmt::Select(IrSelect {
                            rows: vec![IrRowSource::Free(IrFreeExpr::Scalar(expr))],
                            filter: None,
                            order_by: vec![],
                            offset: None,
                            limit: None,
                            distinct,
                            dml_source: None,
                            polymorphic: false,
                            poly_implementors: vec![],
                            poly_columns: vec![],
                            lock: None,
                        }));
                    }
                    // `root.field1.field2...` where `root` is a WITH-bound
                    // free object (not a real/CTE-bound schema type) —
                    // resolve to a field reference (possibly chained through
                    // nested free objects) instead of falling into
                    // compile_path_select, which only knows schema paths.
                    if let Some(resolved) = self.resolve_cte_path(p) {
                        let expr = resolved?;
                        return Ok(IrStmt::Select(IrSelect {
                            rows: vec![IrRowSource::Free(IrFreeExpr::Scalar(expr))],
                            filter: None,
                            order_by: vec![],
                            offset: None,
                            limit: None,
                            distinct,
                            dml_source: None,
                            polymorphic: false,
                            poly_implementors: vec![],
                            poly_columns: vec![],
                            lock: None,
                        }));
                    }
                    if !p.partial && p.steps.len() > 1 {
                        return self.compile_path_select(s, p, &[], distinct).map(IrStmt::PathSelect);
                    }
                }
                if let Expr::Shape(sh) = result
                    && let Some(Expr::Path(p)) = sh.expr.as_ref()
                    && !p.partial
                    && p.steps.len() > 1
                {
                    return self
                        .compile_path_select(s, p, &sh.elements, distinct)
                        .map(IrStmt::PathSelect);
                }
                // assert_exists/assert_distinct with SubQuery arg → set-returning assert
                if let Expr::FunctionCall(f) = result
                    && (f.module.is_none() || f.module.as_deref() == Some("std"))
                    && matches!(f.name.as_str(), "assert_exists" | "assert_distinct")
                    && !f.args.is_empty()
                    && let Expr::SubQuery(inner_stmt) = &f.args[0]
                {
                    let offset = s.offset.as_ref().map(|e| self.compile_free_expr(e)).transpose()?;
                    let limit = s.limit.as_ref().map(|e| self.compile_free_expr(e)).transpose()?;
                    let message = self.assert_message(f, None)?;
                    // A set of objects has to come back as rows, not as the
                    // bare ids the array form carries — so the assert vets the
                    // ids and the type's own rows are selected by them.
                    if let Ok(type_name) = self.dml_subject_type(inner_stmt)
                        && let Ok(td) = self.resolve_type(&type_name)
                    {
                        let td_module = td.module.clone();
                        let td_name = td.name.clone();
                        let td_table = td.table.clone();
                        let pk = td
                            .properties
                            .iter()
                            .find(|p| p.is_pk)
                            .map(|p| (p.name.clone(), p.pg_type.clone()))
                            .unwrap_or_else(|| ("id".to_string(), "uuid".to_string()));
                        let inner_ir = self.compile_stmt(inner_stmt)?;
                        let alias = self.fresh_alias();
                        let vetted = IrExpr::FunctionCall(IrFunctionCall {
                            return_pg_type: None,
                            schema: Some("_pylon".to_string()),
                            name: f.name.clone(),
                            args: std::iter::once(IrExpr::ArrayFromSelect(Box::new(IrArraySource::StmtColumn {
                                stmt: Box::new(inner_ir),
                                column: pk.0.clone(),
                            })))
                            .chain(message)
                            .collect(),
                            sql_template: None,
                        });
                        let filter = IrExpr::BinOp(Box::new(IrBinOp {
                            left: IrExpr::ColumnRef {
                                alias: alias.clone(),
                                column: pk.0.clone(),
                                pg_type: pk.1.clone(),
                            },
                            op: ast::BinOpKind::In,
                            right: vetted,
                        }));
                        let shape = vec![IrShapePointer::Scalar(IrScalarPointer {
                            implicit_id: false,
                            marker_offset: None,
                            alias: "id".to_string(),
                            column: pk.0,
                            pg_type: pk.1,
                            tuple_shape: None,
                        })];
                        let source = IrSource {
                            poly: None,
                            type_name: format!("{td_module}::{td_name}"),
                            table: td_table,
                            alias,
                        };
                        let mut select = IrSelect::schema_bound(source, shape, Some(filter));
                        select.offset = offset;
                        select.limit = limit;
                        select.distinct = distinct;
                        return Ok(IrStmt::Select(select));
                    }
                    let inner = self.compile_subquery_to_array_source(inner_stmt)?;
                    return Ok(IrStmt::Select(IrSelect {
                        rows: vec![IrRowSource::Free(IrFreeExpr::AssertSet {
                            fn_name: f.name.clone(),
                            inner: Box::new(inner),
                            message,
                        })],
                        filter: None,
                        order_by: vec![],
                        offset,
                        limit,
                        distinct,
                        dml_source: None,
                        polymorphic: false,
                        poly_implementors: vec![],
                        poly_columns: vec![],
                        lock: None,
                    }));
                }
                // `array_agg(array_unpack(teams.permissions))` — the unpacking
                // has to happen in a row source, so the aggregate is left with
                // no walk of its own and the select stands free.
                if let Some(expr) = self.aggregate_over_unpacked(s, result, distinct)? {
                    return Ok(IrStmt::Select(IrSelect {
                        rows: vec![IrRowSource::Free(IrFreeExpr::Scalar(expr))],
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        distinct: false,
                        dml_source: None,
                        polymorphic: false,
                        poly_implementors: vec![],
                        poly_columns: vec![],
                        lock: None,
                    }));
                }
                // `select individuals in accounts` — `in` answers once per
                // element of the set on its left, so that set is this
                // select's row source and the membership test is what each
                // row carries. Read as a plain value the left side collapses
                // into a single scalar subquery, which Postgres rejects the
                // moment the binding holds more than one row. The comparison
                // is on identity, so the walk the source needs is `.id`.
                if let Expr::BinOp(b) = result
                    && matches!(b.op, ast::BinOpKind::In | ast::BinOpKind::NotIn)
                    && let Some(root) = self.object_set_name(&b.left)
                {
                    let rewritten = Expr::BinOp(Box::new(ast::BinOp {
                        left: Expr::Path(ast::Path {
                            steps: vec![ast::PathStep::Name(root.clone()), ast::PathStep::Name("id".into())],
                            partial: false,
                        }),
                        op: b.op.clone(),
                        right: b.right.clone(),
                    }));
                    return self
                        .compile_expr_as_path_select(s, &rewritten, &root, distinct)
                        .map(IrStmt::PathSelect);
                }
                // Expression containing a type-rooted path: `select fn(TypeName.link.prop, ...)`.
                if let Some(root) = self.find_path_root_in_expr(result) {
                    return self
                        .compile_expr_as_path_select(s, result, &root, distinct)
                        .map(IrStmt::PathSelect);
                }
                // `select TypeName is CheckType` — iterate source type, return bool per row.
                if let Expr::TypeIs { expr, ty } = result
                    && let Expr::Path(p) = expr.as_ref()
                    && !p.partial
                    && p.steps.len() == 1
                    && let ast::PathStep::Name(src_name) = &p.steps[0]
                    && self.resolve_name_ref(src_name, true).is_none()
                {
                    let src_td = self.resolve_type(src_name)?;
                    {
                        let src_qname = format!("{}::{}", src_td.module, src_td.name);
                        let (ty_module, ty_name) = ty
                            .as_named()
                            .ok_or_else(|| self.type_err("cannot use IS with a tuple or array type"))?;
                        let check_module = ty_module.unwrap_or(&src_td.module);
                        let check_name = format!("{}::{}", check_module, ty_name);
                        self.resolve_type(&check_name)?;
                        let check_qname = check_name;
                        let src_table = src_td.table.clone();
                        let src_alias = self.fresh_alias();
                        let src_td = self.resolve_type(&src_qname)?;
                        let poly_implementors = if self.is_polymorphic(src_td) {
                            self.find_poly_implementors(&src_qname)
                        } else {
                            vec![]
                        };
                        let bool_expr = self.type_check_bool_expr(&src_qname, &check_qname, src_td, &src_alias);
                        let ps = IrPathSelect {
                            root: IrSource {
                                poly: None,
                                type_name: src_qname,
                                table: src_table,
                                alias: src_alias,
                            },
                            joins: vec![],
                            result: IrPathResult::Scalar(bool_expr, None),
                            filter: s
                                .filter
                                .as_ref()
                                .map(|_| Err(self.type_err("FILTER is not supported on type-is SELECT")))
                                .transpose()?,
                            order_by: vec![],
                            offset: None,
                            limit: None,
                            distinct,
                            poly_implementors,
                        };
                        return Ok(IrStmt::PathSelect(ps));
                    }
                }
                if let Expr::Union(a, b) = result
                    && !distinct
                    && s.filter.is_none()
                    && s.order_by.is_empty()
                    && s.offset.is_none()
                    && s.limit.is_none()
                    && (self.is_scalar_walk(a) || self.is_scalar_walk(b))
                {
                    return self.compile_scalar_union(result);
                }
                // `select (l.addon { c := … }).c` — the values, one row each.
                if !distinct
                    && s.filter.is_none()
                    && s.order_by.is_empty()
                    && s.offset.is_none()
                    && s.limit.is_none()
                    && let Some(ps) = self.compile_shape_field_select(result, None)?
                {
                    return Ok(IrStmt::PathSelect(ps));
                }
                // `select (update T … ).link { … }` — the subject walks off a
                // mutation. Hoist the mutation into the statement's own WITH
                // and re-root the walk at that binding, which is the
                // `with a := (update …) select a.link { … }` spelling that
                // already compiles. A walk off a plain sub-select needs none
                // of this.
                if let Expr::Shape(sh) = result
                    && let Some(subject) = sh.expr.as_ref()
                    && !matches!(subject, Expr::Path(_))
                {
                    let (base, fields) = Self::peel_field_access_chain(subject);
                    if let Expr::SubQuery(inner_stmt) = base
                        && !fields.is_empty()
                        && matches!(inner_stmt.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_))
                    {
                        let inner = self.compile_stmt(inner_stmt)?;
                        let cte_name = self.fresh_nested_cte_name();
                        // The walk may read a junction this very mutation
                        // appended to; those rows live only in the append CTE.
                        let overrides = Self::junction_overrides_for(&inner, &cte_name);
                        let type_name = self.register_cte(&cte_name, &inner);
                        self.hoisted_ctes.push(IrCteDef {
                            name: cte_name.clone(),
                            stmt: inner,
                            type_name,
                            correlated_to: None,
                        });
                        let mut steps = vec![ast::PathStep::Name(cte_name)];
                        steps.extend(fields.into_iter().map(ast::PathStep::Name));
                        let rerooted = ast::SelectStmt {
                            result: Expr::Shape(Box::new(ast::ShapeExpr {
                                expr: Some(Expr::Path(ast::Path { steps, partial: false })),
                                elements: sh.elements.clone(),
                                marker_offset: None,
                            })),
                            filter: s.filter.clone(),
                            order_by: s.order_by.clone(),
                            offset: s.offset.clone(),
                            limit: s.limit.clone(),
                            lock: s.lock.clone(),
                        };
                        let previous = std::mem::replace(&mut self.junction_read_overrides, overrides);
                        let compiled = self.compile_stmt(&Stmt::Select(rerooted));
                        self.junction_read_overrides = previous;
                        return compiled;
                    }
                }
                // `select (select (A union B) { … } limit 1) { … }` — a nested
                // select whose own subject is a union has no single type name
                // for the outer select to take. Hoisting it into a binding and
                // reading that back is the `with l := (select …) select l { … }`
                // spelling, which already compiles.
                if let Expr::Shape(sh) = result
                    && let Some(Expr::SubQuery(inner_stmt)) = sh.expr.as_ref()
                    && matches!(inner_stmt.as_ref(), Stmt::Select(_))
                    && self.dml_subject_type(inner_stmt).is_err()
                {
                    let inner = self.compile_stmt(inner_stmt)?;
                    let cte_name = self.fresh_nested_cte_name();
                    let type_name = self.register_cte(&cte_name, &inner);
                    self.hoisted_ctes.push(IrCteDef {
                        name: cte_name.clone(),
                        stmt: inner,
                        type_name,
                        correlated_to: None,
                    });
                    let rerooted = ast::SelectStmt {
                        result: Expr::Shape(Box::new(ast::ShapeExpr {
                            expr: Some(Expr::Path(ast::Path {
                                steps: vec![ast::PathStep::Name(cte_name)],
                                partial: false,
                            })),
                            elements: sh.elements.clone(),
                            marker_offset: None,
                        })),
                        filter: s.filter.clone(),
                        order_by: s.order_by.clone(),
                        offset: s.offset.clone(),
                        limit: s.limit.clone(),
                        lock: s.lock.clone(),
                    };
                    return self.compile_stmt(&Stmt::Select(rerooted));
                }
                // `select (for … union …)` — the select adds nothing the loop has
                // not already produced, so it *is* the loop. Written with a
                // shape or modifiers of its own the loop is this select's
                // source instead, and a mutating one has to be bound to a CTE
                // first — see `bind_mutating_loop_source`.
                if let Expr::SubQuery(inner) = result
                    && matches!(inner.as_ref(), Stmt::For(_))
                    && !distinct
                    && s.filter.is_none()
                    && s.order_by.is_empty()
                    && s.offset.is_none()
                    && s.limit.is_none()
                {
                    return self.compile_stmt(inner);
                }
                // Catch mixed object/scalar UNION before dispatching further.
                self.check_union_type_compat(result)?;
                if self.is_free_result(result) {
                    self.compile_free_select(s, result, distinct).map(IrStmt::Select)
                } else {
                    self.compile_select(s, result, distinct).map(IrStmt::Select)
                }
            }
            Stmt::Insert(s) => self.compile_insert(s).map(IrStmt::Insert),
            Stmt::Update(s) => self.compile_update(s).map(IrStmt::Update),
            Stmt::Delete(s) => self.compile_delete(s).map(IrStmt::Delete),
            Stmt::Group(s) => self.compile_group(s).map(IrStmt::Group),
            // Nested WITH blocks (e.g. inside a subquery): inline the CTE types
            // into the current compiler scope so references resolve correctly.
            // The actual CTE SQL is handled at the top-level compile() boundary.
            Stmt::With(w) => {
                for alias in &w.aliases {
                    if self.bind_inline_if_correlated(&alias.name, &alias.expr, None)?
                        || self.bind_group(&alias.name, &alias.expr)?
                    {
                        continue;
                    }
                    let (ir_inner, correlated_to) = self.compile_binding_in_scope(&alias.expr)?;
                    let sql_name = self.claim_cte_sql_name(&alias.name);
                    if let Some(slot) = correlated_to.as_deref().and_then(|i| i.strip_prefix("_for_")) {
                        self.correlated_bindings.insert(sql_name.clone(), slot.to_string());
                    }
                    let type_name = self.register_cte(&alias.name, &ir_inner);
                    self.hoisted_binding_sources
                        .insert(sql_name.clone(), alias.expr.clone());
                    self.hoisted_ctes.push(IrCteDef {
                        name: sql_name,
                        stmt: ir_inner,
                        type_name,
                        correlated_to,
                    });
                }
                self.compile_stmt(&w.stmt)
            }
            Stmt::For(f) => match self.compile_group_elements(f)? {
                Some(grp) => Ok(IrStmt::Group(grp)),
                None => self.compile_for(f).map(IrStmt::For),
            },
            // `analyze` only changes how the query is *executed* (see
            // `analyze.rs`) — the inner statement's IR is identical either
            // way, so this layer just unwraps and compiles it normally.
            Stmt::Analyze(inner) => self.compile_stmt(inner),
        }
    }

    /// `<Module::Type>expr` in SELECT position is a schema object lookup:
    /// select the object whose `id` equals `expr`.  Semantically identical to
    /// `SELECT Type FILTER .id = expr` plus any modifiers on the outer SELECT.
    fn compile_schema_cast_select(&mut self, sel: &ast::SelectStmt, tc: &ast::TypeCast) -> Result<IrSelect, PyQLError> {
        let id_filter = Expr::BinOp(Box::new(ast::BinOp {
            left: Expr::Path(ast::Path::relative("id")),
            op: ast::BinOpKind::Eq,
            right: tc.expr.clone(),
        }));
        let merged_filter = match &sel.filter {
            None => Some(id_filter),
            Some(existing) => Some(Expr::BinOp(Box::new(ast::BinOp {
                left: id_filter,
                op: ast::BinOpKind::And,
                right: existing.clone(),
            }))),
        };
        // Callers only reach this function after confirming `tc.ty` is `Named`
        // (a structural tuple is never an object-type lookup).
        let (module, name) = tc
            .ty
            .as_named()
            .ok_or_else(|| self.type_err("cannot use a tuple or array type as a schema object cast"))?;
        // Keep the module qualification in the synthetic path so a genuinely
        // unknown target (neither an object type, enum, scalar, nor named
        // tuple) reports its full name via `resolve_type`'s own error,
        // instead of silently dropping the module and reporting a bare name.
        let qname = match module {
            Some(m) => format!("{}::{}", m, name),
            None => name.to_string(),
        };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(ast::Path::absolute(&qname)),
            filter: merged_filter,
            order_by: sel.order_by.clone(),
            offset: sel.offset.clone(),
            limit: sel.limit.clone(),
            lock: sel.lock.clone(),
        };
        self.compile_select(&synthetic, &synthetic.result, false)
    }

    // ── PATH SELECT ───────────────────────────────────────────────────────────────

    /// `select TypeName.link.prop` / `select TypeName.link { shape }`.
    /// Walks the path, building JOIN steps, then projects the final pointer or object.
    /// `compile_shape` with the type the walk landed on anchored, so a
    /// relative path written inside the shape — a `with` binding's value, a
    /// nested sub-select's filter — has an enclosing object to resolve
    /// against. A plain `select` pushes the same anchor for its own shape.
    fn compile_shape_anchored(
        &mut self,
        elements: &[ShapeElement],
        td: &'a TypeDescriptor,
        alias: &str,
        module: &str,
    ) -> Result<Vec<IrShapePointer>, PyQLError> {
        self.anchors.push(SelectAnchor {
            type_name: td.name.clone(),
            qualified: format!("{}::{}", td.module, td.name),
            alias: alias.to_string(),
            detached: false,
            declared_on: None,
        });
        let result = self.compile_shape(elements, td, alias, module);
        self.anchors.pop();
        result
    }

    fn compile_path_select(
        &mut self,
        sel: &ast::SelectStmt,
        path: &ast::Path,
        shape_elements: &[ShapeElement],
        distinct: bool,
    ) -> Result<IrPathSelect, PyQLError> {
        self.compile_path_select_with_tail(sel, path, shape_elements, distinct, 0, &[])
    }

    /// `compile_path_select` where the last `tail` steps were appended by a
    /// projection off a sub-select — `(select … limit 1).plan.tier` — so
    /// `sel`'s own modifiers belong to the step before them, not to the end
    /// of the path.
    fn compile_path_select_with_tail(
        &mut self,
        sel: &ast::SelectStmt,
        path: &ast::Path,
        shape_elements: &[ShapeElement],
        distinct: bool,
        tail: usize,
        tail_sorts: &[ast::SortExpr],
    ) -> Result<IrPathSelect, PyQLError> {
        let outer_anchor = self.modifier_anchor.take();
        // Swapped rather than assigned, so a path select compiled inside this
        // one gets its own (empty) list and hands these back untouched.
        let outer_sorts = std::mem::replace(&mut self.tail_sorts, tail_sorts.to_vec());
        let mut result = self.compile_path_select_inner(sel, path, shape_elements, distinct, tail);
        self.tail_sorts = outer_sorts;
        self.modifier_anchor = outer_anchor;
        if let Ok(path_select) = &mut result {
            self.resolve_join_fanouts(path_select);
        }
        result
    }

    fn compile_path_select_inner(
        &mut self,
        sel: &ast::SelectStmt,
        path: &ast::Path,
        shape_elements: &[ShapeElement],
        distinct: bool,
        mut tail: usize,
    ) -> Result<IrPathSelect, PyQLError> {
        use ast::PathStep;

        let root_name = match &path.steps[0] {
            PathStep::Name(n) => n.as_str(),
            _ => return Err(self.type_err("path traversal must start with a type name")),
        };
        // A WITH-block CTE bound to an object type (e.g. `with user :=
        // (select global current_user) select user.gender`) can be
        // traversed just like a real type name — resolve its underlying
        // type and source from the `@cte:` sentinel table (the same
        // mechanism `compile_select`'s bare-CTE-object-select case uses)
        // instead of failing with "unknown type '{root_name}'".
        let root_td = self.resolve_path_root(root_name)?;
        let root_alias = self.fresh_alias();
        let root = IrSource {
            poly: None,
            type_name: format!("{}::{}", root_td.module, root_td.name),
            table: self.row_source_table(root_name, root_td),
            alias: root_alias.clone(),
        };
        // `for c in (select Person) union (select c.name)` — the loop variable
        // holds the row's key, so the walk starts from that row rather than
        // from the whole table.
        let for_var_root = self.for_var_types.contains_key(root_name).then(|| {
            IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: root_alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: self.for_var_ref(root_name),
            }))
        });

        let mut joins: Vec<IrPathJoin> = vec![];
        let mut current_td = root_td;
        let mut current_alias = root_alias;

        // Owned rather than borrowed: traversing *through* a computed
        // pointer splices that computed's own path in place of the step
        // naming it (see the computed branch at the bottom of the loop).
        let mut steps: Vec<PathStep> = path.steps[1..].to_vec();
        // `(step index, filter)` a spliced computed contributed, to compile
        // against the type that step lands on once the loop reaches it.
        let mut pending_filters: Vec<(usize, Expr)> = vec![];
        let mut extra_conditions: Vec<IrExpr> = for_var_root.into_iter().collect();
        // The junction the traversal last crossed, for a bare `@prop` in the
        // select's own modifiers.
        let mut junction_scope: Option<(String, String)> = None;
        let mut splices = 0usize;
        let mut idx = 0;
        if tail > 0 && tail >= steps.len() {
            self.modifier_anchor = Some((
                format!("{}::{}", current_td.module, current_td.name),
                current_alias.clone(),
            ));
        }
        while idx < steps.len() {
            let owned_step = steps[idx].clone();
            let step = &owned_step;
            let n_steps = steps.len();
            let is_last = |extra: usize| idx + extra == n_steps - 1;
            if tail > 0 && idx == n_steps - tail {
                self.modifier_anchor = Some((
                    format!("{}::{}", current_td.module, current_td.name),
                    current_alias.clone(),
                ));
            }

            // A spliced computed's own filter belongs to the step it landed
            // on, which is the one just processed.
            while let Some(pos) = pending_filters.iter().position(|(i, _)| *i + 1 == idx) {
                let (_, f) = pending_filters.remove(pos);
                let cond = self.as_condition(|c| c.compile_expr(&f, current_td, &current_alias))?;
                extra_conditions.push(cond);
            }

            // Type intersection standalone (not after backlink): narrows current_td.
            if let PathStep::TypeIntersection(type_ref) = step {
                let type_name = match &type_ref.module {
                    Some(m) => format!("{}::{}", m, type_ref.name),
                    None => type_ref.name.clone(),
                };
                let narrowed = self.resolve_type(&type_name)?;
                // Narrowing to a type with a relation of its own moves to that
                // relation, joined on the shared id: an interface's view has
                // none of its implementors' own columns, and two unrelated
                // types share no ids at all, so the join finds nothing — which
                // is exactly what an impossible intersection yields. A mixin
                // has no relation; its columns are already on the current row.
                let narrowed_has_relation = !Self::backs_no_relation(narrowed);
                if narrowed_has_relation && narrowed.table != current_td.table {
                    let target_alias = self.fresh_alias();
                    let target = IrSource {
                        poly: None,
                        type_name: format!("{}::{}", narrowed.module, narrowed.name),
                        table: narrowed.table.clone(),
                        alias: target_alias.clone(),
                    };
                    joins.push(IrPathJoin::Single {
                        source_alias: current_alias.clone(),
                        fk_col: "id".to_string(),
                        target,
                    });
                    current_alias = target_alias;
                }
                current_td = narrowed;
                idx += 1;
                continue;
            }

            // Backlink: .<link_name — optionally followed by [is OwnerType].
            if let PathStep::Backlink(link_name) = step {
                // Peek ahead: if the next step is [is Type], use it to identify the owner.
                let owner_hint = steps.get(idx + 1).and_then(|s| {
                    if let PathStep::TypeIntersection(tr) = s {
                        Some(tr.clone())
                    } else {
                        None
                    }
                });
                let consumed_extra = if owner_hint.is_some() { 1 } else { 0 };

                let owner_td: &TypeDescriptor = if let Some(ref tr) = owner_hint {
                    let type_name = match &tr.module {
                        Some(m) => format!("{}::{}", m, tr.name),
                        None => tr.name.clone(),
                    };
                    let td = self.resolve_type(&type_name)?;
                    let current_qname = format!("{}::{}", current_td.module, current_td.name);
                    let link_targets_current =
                        td.links
                            .iter()
                            .any(|l| l.name == *link_name && self.link_target_reaches(&l.target, &current_qname))
                            || td.multilinks.iter().any(|ml| {
                                ml.name == *link_name && self.link_target_reaches(&ml.target, &current_qname)
                            });
                    if link_targets_current {
                        td
                    } else {
                        // `.<memberships[is account::Account]` — declared further
                        // down, by the one type under the narrowing that has it.
                        let narrowed = format!("{}::{}", td.module, td.name);
                        let declaring: Vec<&'a TypeDescriptor> = self
                            .schema
                            .types
                            .iter()
                            .filter(|t| !t.abstract_ && Self::is_or_implements(t, &narrowed))
                            .filter(|t| self.declares_backlink(t, link_name, &current_qname))
                            .collect();
                        match Self::without_inherited_owners(declaring).as_slice() {
                            [only] => only,
                            _ => {
                                return Err(self.type_err(&format!(
                                    "link '{}::{}' does not target '{}'; backlink is not valid here",
                                    type_name, link_name, current_qname,
                                )));
                            }
                        }
                    }
                } else {
                    // No hint — search for any type whose link/multilink targets current_td.
                    let current_qname = format!("{}::{}", current_td.module, current_td.name);
                    self.schema
                        .types
                        .iter()
                        // The base, not a subtype inheriting the link from it.
                        .filter(|t| {
                            t.bases.is_empty()
                                || !t.bases.iter().any(|base| {
                                    self.resolve_type(base).is_ok_and(|b| {
                                        b.links.iter().any(|l| l.name == *link_name)
                                            || b.multilinks.iter().any(|ml| ml.name == *link_name)
                                    })
                                })
                        })
                        .find(|t| {
                            t.links
                                .iter()
                                .any(|l| l.name == *link_name && self.link_target_reaches(&l.target, &current_qname))
                                || t.multilinks.iter().any(|ml| {
                                    ml.name == *link_name && self.link_target_reaches(&ml.target, &current_qname)
                                })
                        })
                        .ok_or_else(|| {
                            self.type_err(&format!(
                                "no type has a link '{}' targeting '{}'",
                                link_name, current_qname,
                            ))
                        })?
                };

                let target_alias = self.fresh_alias();
                let target = IrSource {
                    poly: None,
                    type_name: format!("{}::{}", owner_td.module, owner_td.name),
                    table: owner_td.table.clone(),
                    alias: target_alias.clone(),
                };

                // Determine if the link is single (FK), junction-backed
                // single (same shape as a backlinked multi-link), or multi
                // (junction).
                if let Some(l) = owner_td.links.iter().find(|l| l.name == *link_name) {
                    if l.is_junction_backed() {
                        let junction_alias = self.fresh_alias();
                        let (junction_table, module, owner_col, current_col, _) =
                            self.link_junction_info(owner_td, l)?;
                        joins.push(IrPathJoin::BacklinkMulti {
                            source_alias: current_alias.clone(),
                            junction_alias,
                            junction_table,
                            module,
                            owner_col,
                            current_col,
                            target,
                        });
                    } else {
                        joins.push(IrPathJoin::BacklinkSingle {
                            source_alias: current_alias.clone(),
                            fk_col: format!("{}_id", link_name),
                            target,
                        });
                    }
                } else {
                    let ml = owner_td
                        .multilinks
                        .iter()
                        .find(|ml| ml.name == *link_name)
                        .unwrap()
                        .clone();
                    let junction_alias = self.fresh_alias();
                    let (junction_table, module, _, _, _) = self.multilink_junction_info(owner_td, &ml)?;
                    joins.push(IrPathJoin::BacklinkMulti {
                        source_alias: current_alias.clone(),
                        junction_alias,
                        junction_table,
                        module,
                        owner_col: "source".to_string(),
                        current_col: "target".to_string(),
                        target,
                    });
                }

                if is_last(consumed_extra) {
                    let shape =
                        self.compile_shape_anchored(shape_elements, owner_td, &target_alias, &owner_td.module.clone())?;
                    let result = IrPathResult::Object {
                        alias: target_alias.clone(),
                        type_name: format!("{}::{}", owner_td.module, owner_td.name),
                        shape,
                    };
                    let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                        sel,
                        owner_td,
                        &target_alias,
                        junction_scope.clone(),
                        shape_elements,
                    )?;
                    return Ok(IrPathSelect {
                        root,
                        joins,
                        result,
                        filter: and_conditions(filter, extra_conditions),
                        order_by,
                        offset,
                        limit,
                        distinct,
                        poly_implementors: vec![],
                    });
                }
                current_td = owner_td;
                current_alias = target_alias;
                idx += 1 + consumed_extra;
                continue;
            }

            let step_name = match step {
                PathStep::Name(n) => n.as_str(),
                _ => return Err(self.type_err("only name steps are supported in path traversal")),
            };

            // `__type__` is a virtual scalar property holding the
            // fully-qualified type name: a real discriminator column on a
            // polymorphic (interface) source, a constant on a concrete one.
            if step_name == "__type__" {
                if !is_last(0) {
                    return Err(
                        self.type_err("'__type__' is the type's name, not an object — it cannot be traversed further")
                    );
                }
                let polymorphic = self.is_polymorphic(current_td);
                let expr = if polymorphic {
                    IrExpr::ColumnRef {
                        alias: current_alias.clone(),
                        column: "__type__".to_string(),
                        pg_type: "text".to_string(),
                    }
                } else {
                    IrExpr::Literal(IrLiteral::Str(format!("{}::{}", current_td.module, current_td.name)))
                };
                // A CTE-backed root already carries the discriminator column
                // from the binding's own polymorphic expansion; re-expanding it
                // here would read the base type again and drop the binding's
                // filter.
                let poly_implementors = if polymorphic && joins.is_empty() && !root.table.starts_with("@cte:") {
                    self.find_poly_implementors(&root.type_name.clone())
                } else {
                    vec![]
                };
                let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                    sel,
                    current_td,
                    &current_alias,
                    junction_scope.clone(),
                    shape_elements,
                )?;
                return Ok(IrPathSelect {
                    root,
                    joins,
                    result: IrPathResult::Scalar(expr, None),
                    filter: and_conditions(filter, extra_conditions),
                    order_by,
                    offset,
                    limit,
                    distinct,
                    poly_implementors,
                });
            }

            // Check scalar property first.
            if let Some(p) = current_td.properties.iter().find(|p| p.name == step_name) {
                if !is_last(0) {
                    // Named tuple properties (nominal `__nt__:` marker) and structural
                    // tuple properties (`tuple_members`) both allow further field
                    // access via jsonb operators.
                    if p.pg_type.starts_with("__nt__:") || p.tuple_members.is_some() {
                        let base = IrExpr::ColumnRef {
                            alias: current_alias.clone(),
                            column: p.name.clone(),
                            pg_type: p.pg_type.clone(),
                        };
                        let remaining = &steps[idx + 1..];
                        let mut ir: IrExpr = base;
                        for step in remaining {
                            let field = match step {
                                ast::PathStep::Name(n) => n.clone(),
                                _ => return Err(self.type_err("only field name steps are valid inside a named tuple")),
                            };
                            ir = IrExpr::JsonbField {
                                expr: Box::new(ir),
                                field,
                            };
                        }
                        let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                            sel,
                            current_td,
                            &current_alias,
                            junction_scope.clone(),
                            shape_elements,
                        )?;
                        return Ok(IrPathSelect {
                            root,
                            joins,
                            result: IrPathResult::Scalar(ir, None),
                            filter: and_conditions(filter, extra_conditions),
                            order_by,
                            offset,
                            limit,
                            distinct,
                            poly_implementors: vec![],
                        });
                    }
                    return Err(self.type_err(&format!(
                        "'{step_name}' is a scalar property, not a link — cannot traverse further"
                    )));
                }
                let tuple_shape = self.resolve_property_tuple_shape(p);
                let result = IrPathResult::Scalar(
                    IrExpr::ColumnRef {
                        alias: current_alias.clone(),
                        column: p.name.clone(),
                        pg_type: p.pg_type.clone(),
                    },
                    tuple_shape,
                );
                let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                    sel,
                    current_td,
                    &current_alias,
                    junction_scope.clone(),
                    shape_elements,
                )?;
                return Ok(IrPathSelect {
                    root,
                    joins,
                    result,
                    filter: and_conditions(filter, extra_conditions),
                    order_by,
                    offset,
                    limit,
                    distinct,
                    poly_implementors: vec![],
                });
            }

            // Single link.
            if let Some(l) = Self::resolve_link(current_td, step_name) {
                let target_td = self.resolve_type(&l.target)?;
                let target_alias = self.fresh_alias();
                let target = IrSource {
                    poly: None,
                    type_name: format!("{}::{}", target_td.module, target_td.name),
                    table: target_td.table.clone(),
                    alias: target_alias.clone(),
                };
                if l.is_junction_backed() {
                    // Same join shape a multi-link's own path step uses
                    // (D1) — `PRIMARY KEY (source)` on the junction table
                    // already guarantees at most one matching row, so no
                    // extra cardinality handling is needed here.
                    let join = self.build_multilink_join(current_td, &l.name, &l.target, &l.through)?;
                    let junction_alias = self.fresh_alias();
                    junction_scope = l.through.clone().map(|t| (t, junction_alias.clone()));
                    joins.push(IrPathJoin::Multi {
                        source_alias: current_alias.clone(),
                        junction_alias,
                        join,
                        target,
                    });
                } else {
                    joins.push(IrPathJoin::Single {
                        source_alias: current_alias.clone(),
                        fk_col: format!("{}_id", l.name),
                        target,
                    });
                }
                if is_last(0) {
                    let shape = self.compile_shape_anchored(
                        shape_elements,
                        target_td,
                        &target_alias,
                        &target_td.module.clone(),
                    )?;
                    let result = IrPathResult::Object {
                        alias: target_alias.clone(),
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        shape,
                    };
                    let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                        sel,
                        target_td,
                        &target_alias,
                        junction_scope.clone(),
                        shape_elements,
                    )?;
                    return Ok(IrPathSelect {
                        root,
                        joins,
                        result,
                        filter: and_conditions(filter, extra_conditions),
                        order_by,
                        offset,
                        limit,
                        distinct,
                        poly_implementors: vec![],
                    });
                }
                current_td = target_td;
                current_alias = target_alias;
                idx += 1;
                continue;
            }

            // Multi-link.
            if let Some(ml) = Self::resolve_multilink(current_td, step_name) {
                let target_td = self.resolve_type(&ml.target)?;
                let target_alias = self.fresh_alias();
                let junction_alias = self.fresh_alias();
                // Set only while walking off a mutation this statement made:
                // both the junction rows and, when they were inserted here
                // too, the targets live in CTEs rather than their tables.
                let override_for_step = self
                    .junction_read_overrides
                    .get(&self.owner_junction(current_td, &ml.name, None))
                    .cloned();
                let target = IrSource {
                    poly: None,
                    type_name: format!("{}::{}", target_td.module, target_td.name),
                    table: match override_for_step.as_ref().and_then(|o| o.targets.clone()) {
                        Some(cte) => cte,
                        None => target_td.table.clone(),
                    },
                    alias: target_alias.clone(),
                };
                let join_info = if let Some(through_qname) = &ml.through {
                    let through_td = self.resolve_type(through_qname)?;
                    if through_td.junction {
                        // See `junction_info_for`'s doc comment: owner-derived,
                        // never `through_td.table` itself.
                        IrMultiLinkJoin::Standard {
                            junction_table: self.owner_junction(current_td, &ml.name, Some(through_td)),
                            module: current_td.module.clone(),
                        }
                    } else {
                        let source_qname = format!("{}::{}", current_td.module, current_td.name);
                        let source_col = through_td
                            .links
                            .iter()
                            .find(|l| l.target == source_qname)
                            .ok_or_else(|| {
                                PyQLError::Type(PyQLTypeError {
                                    message: format!("through type {through_qname} has no link to {source_qname}"),
                                    position: Position { line: 0, col: 0 },
                                })
                            })?
                            .name
                            .clone();
                        let target_col = through_td
                            .links
                            .iter()
                            .find(|l| l.target == ml.target && l.name != source_col)
                            .or_else(|| through_td.links.iter().find(|l| l.target == ml.target))
                            .ok_or_else(|| {
                                PyQLError::Type(PyQLTypeError {
                                    message: format!(
                                        "through type {through_qname} has no link to target {}",
                                        ml.target
                                    ),
                                    position: Position { line: 0, col: 0 },
                                })
                            })?
                            .name
                            .clone();
                        IrMultiLinkJoin::Through {
                            junction_table: through_td.table.clone(),
                            module: through_td.module.clone(),
                            source_col,
                            target_col,
                        }
                    }
                } else {
                    let junction_table = self.owner_junction(current_td, &ml.name, None);
                    IrMultiLinkJoin::Standard {
                        junction_table: match &override_for_step {
                            Some(o) => o.junction.clone(),
                            None => junction_table,
                        },
                        module: current_td.module.clone(),
                    }
                };
                junction_scope = ml.through.clone().map(|t| (t, junction_alias.clone()));
                joins.push(IrPathJoin::Multi {
                    source_alias: current_alias.clone(),
                    junction_alias,
                    join: join_info,
                    target,
                });
                if is_last(0) {
                    let shape = self.compile_shape_anchored(
                        shape_elements,
                        target_td,
                        &target_alias,
                        &target_td.module.clone(),
                    )?;
                    let result = IrPathResult::Object {
                        alias: target_alias.clone(),
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        shape,
                    };
                    let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                        sel,
                        target_td,
                        &target_alias,
                        junction_scope.clone(),
                        shape_elements,
                    )?;
                    return Ok(IrPathSelect {
                        root,
                        joins,
                        result,
                        filter: and_conditions(filter, extra_conditions),
                        order_by,
                        offset,
                        limit,
                        distinct,
                        poly_implementors: vec![],
                    });
                }
                current_td = target_td;
                current_alias = target_alias;
                idx += 1;
                continue;
            }

            // A computed pointer declared on the type reached so far (or on
            // an interface it implements) — or, at the root only, one the
            // shape in scope declared, which is on no type at all:
            // `r { revision := … }` read back as `.revision.created_at`.
            let declared = match self.resolve_computed(current_td, step_name) {
                Some(cd) => Some(crate::parse::parse_pointer_expr(&cd.expression).map_err(PyQLError::Syntax)?),
                None if idx == 0 => self
                    .active_declared_pointers
                    .iter()
                    .find(|d| path_leaf(&d.path).is_ok_and(|n| n == step_name))
                    .and_then(|d| d.compexpr.clone()),
                None => None,
            };
            if let Some(parsed) = declared {
                // `(select .parents … limit 1).parent` reads as the select over
                // the walk those two make together.
                let rewritten = Self::field_access_over_select(&parsed);
                let expr_ast = match &rewritten {
                    Some((sel, _)) => Expr::SubQuery(Box::new(Stmt::Select(sel.clone()))),
                    None => parsed,
                };
                let field_steps = rewritten.as_ref().map(|(_, n)| *n).unwrap_or(0);

                // Traversing *through* it: a computed has no stored column
                // for a join to hang off, but if it just names a link — with
                // or without a filter — its own path can take the step's
                // place, and its filter rides along on the spliced segment.
                // Chaining computeds this way is routine, so the splice
                // re-enters the loop and expands again if it lands on
                // another one.
                // As the last step too, when what it names lands on an object:
                // the shape and the select's own modifiers belong to that
                // object, and reading it as an expression instead binds them to
                // the type that declares the computed.
                if let Some((p, _, modifiers)) = Self::pointer_subject(&expr_ast)
                    && p.partial
                    && !p.steps.is_empty()
                    && (!is_last(0)
                        || self
                            .walk_path_types(current_td, &p.steps, MAX_COMPUTED_SPLICES)
                            .1
                            .is_some())
                {
                    // Order/offset/limit of its own pick one row *per source
                    // row*, which no plain join expresses — so the computed's
                    // own traversal becomes a correlated LATERAL and the path
                    // continues from its result.
                    if let Some(m) = modifiers
                        && (m.limit.is_some() || m.offset.is_some() || !m.order_by.is_empty())
                    {
                        let mut inner_steps =
                            vec![PathStep::Name(format!("{}::{}", current_td.module, current_td.name))];
                        inner_steps.extend(p.steps.iter().cloned());
                        let inner_path = ast::Path {
                            steps: inner_steps,
                            partial: false,
                        };
                        let inner_sel = ast::SelectStmt {
                            result: Expr::Path(inner_path.clone()),
                            filter: m.filter.clone(),
                            order_by: m.order_by.clone(),
                            offset: m.offset.clone(),
                            limit: m.limit.clone(),
                            lock: None,
                        };
                        let mut inner =
                            self.compile_path_select_with_tail(&inner_sel, &inner_path, &[], false, field_steps, &[])?;
                        Self::correlate_path_select(&mut inner, &current_alias);
                        let IrPathResult::Object { type_name, .. } = &inner.result else {
                            return Err(self.type_err(&format!(
                                "computed pointer '{step_name}' is a scalar — a path cannot continue through it"
                            )));
                        };
                        let target_td = self.resolve_type(&type_name.clone())?;
                        let target_alias = self.fresh_alias();
                        let target = IrSource {
                            poly: None,
                            type_name: format!("{}::{}", target_td.module, target_td.name),
                            table: target_td.table.clone(),
                            alias: target_alias.clone(),
                        };
                        joins.push(IrPathJoin::Lateral {
                            inner: Box::new(inner),
                            target,
                        });
                        if is_last(0) {
                            let module = target_td.module.clone();
                            let shape =
                                self.compile_shape_anchored(shape_elements, target_td, &target_alias, &module)?;
                            let result = IrPathResult::Object {
                                alias: target_alias.clone(),
                                type_name: format!("{}::{}", target_td.module, target_td.name),
                                shape,
                            };
                            let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                                sel,
                                target_td,
                                &target_alias,
                                junction_scope,
                                shape_elements,
                            )?;
                            return Ok(IrPathSelect {
                                root,
                                joins,
                                result,
                                filter: and_conditions(filter, extra_conditions),
                                order_by,
                                offset,
                                limit,
                                distinct,
                                poly_implementors: vec![],
                            });
                        }
                        current_td = target_td;
                        current_alias = target_alias;
                        idx += 1;
                        continue;
                    }
                    splices += 1;
                    if splices > MAX_COMPUTED_SPLICES {
                        return Err(self.type_err(&format!(
                            "computed pointer '{step_name}' expands into itself — \
                             a path cannot be resolved through a cycle of computed pointers"
                        )));
                    }
                    let filter = modifiers.and_then(|m| m.filter.clone());
                    let spliced = p.steps.clone();
                    if tail > 0 && idx >= steps.len() - tail {
                        tail += spliced.len() - 1;
                    }
                    let landing = idx + spliced.len() - 1;
                    steps.splice(idx..idx + 1, spliced);
                    // Every filter already queued for a later step shifts
                    // along with it.
                    let shift = landing - idx;
                    for (i, _) in pending_filters.iter_mut() {
                        if *i > idx {
                            *i += shift;
                        }
                    }
                    if let Some(f) = filter {
                        pending_filters.push((landing, f));
                    }
                    continue;
                }

                // A computed backed by an object-returning function —
                // `translation := latest(.id)`. There is no path to splice
                // in, so the call itself becomes the next row source: a
                // LATERAL join, since its arguments read the alias the
                // traversal has reached.
                if let Some((fc, modifiers)) = Self::function_subject(&expr_ast)
                    && let Some(fd) = self.resolve_object_fn(fc)
                {
                    if fd.params.len() != fc.args.len() {
                        return Err(self.type_err(&format!(
                            "function '{}::{}' expects {} argument(s), got {}",
                            fd.module,
                            fd.name,
                            fd.params.len(),
                            fc.args.len()
                        )));
                    }
                    let (fn_module, fn_name, return_type_name) =
                        (fd.module.clone(), fd.name.clone(), fd.return_pg_type.clone());
                    let mut args = fc
                        .args
                        .iter()
                        .map(|a| self.compile_expr(a, current_td, &current_alias))
                        .collect::<Result<Vec<_>, _>>()?;
                    let qualified = format!("{fn_module}::{fn_name}");
                    if let Some(globals) = self.globals_arg_for_call(&qualified)? {
                        args.insert(0, globals);
                    }
                    let target_td = self.resolve_type(&return_type_name)?;
                    let target_alias = self.fresh_alias();
                    let target = IrSource {
                        poly: None,
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        table: target_td.table.clone(),
                        alias: target_alias.clone(),
                    };
                    joins.push(IrPathJoin::Function {
                        fn_module,
                        fn_name,
                        args,
                        target,
                    });
                    if let Some(f) = modifiers.and_then(|m| m.filter.clone()) {
                        let cond = self.as_condition(|c| c.compile_expr(&f, target_td, &target_alias))?;
                        extra_conditions.push(cond);
                    }
                    if is_last(0) {
                        let shape = self.compile_shape_anchored(
                            shape_elements,
                            target_td,
                            &target_alias,
                            &target_td.module.clone(),
                        )?;
                        let result = IrPathResult::Object {
                            alias: target_alias.clone(),
                            type_name: format!("{}::{}", target_td.module, target_td.name),
                            shape,
                        };
                        let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                            sel,
                            target_td,
                            &target_alias,
                            junction_scope.clone(),
                            shape_elements,
                        )?;
                        return Ok(IrPathSelect {
                            root,
                            joins,
                            result,
                            filter: and_conditions(filter, extra_conditions),
                            order_by,
                            offset,
                            limit,
                            distinct,
                            poly_implementors: vec![],
                        });
                    }
                    current_td = target_td;
                    current_alias = target_alias;
                    idx += 1;
                    continue;
                }

                if !is_last(0) {
                    return Err(self.type_err(&format!(
                        "'{step_name}' is a computed pointer — it has no stored column to traverse further through"
                    )));
                }
                let expanding = format!("{}::{}.{step_name}", current_td.module, current_td.name);
                if self.expanding_computeds.contains(&expanding) {
                    return Err(self.type_err(&format!(
                        "computed pointer '{step_name}' expands into itself — \
                         a path cannot be resolved through a cycle of computed pointers"
                    )));
                }
                self.expanding_computeds.push(expanding);
                let expr = self.compile_expr(&expr_ast, current_td, &current_alias);
                self.expanding_computeds.pop();
                let expr = expr?;
                let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                    sel,
                    current_td,
                    &current_alias,
                    junction_scope.clone(),
                    shape_elements,
                )?;
                return Ok(IrPathSelect {
                    root,
                    joins,
                    result: IrPathResult::Scalar(expr, None),
                    filter: and_conditions(filter, extra_conditions),
                    order_by,
                    offset,
                    limit,
                    distinct,
                    poly_implementors: vec![],
                });
            }

            return Err(self.field_err(step_name, &format!("{}::{}", current_td.module, current_td.name)));
        }

        // Every step consumed with nothing returned means the path *ended* on a
        // narrowing (`a.respondents[is GuestRespondent]`, or a bare `[is T]`).
        // The loop has already joined to the narrowed relation, so what it
        // landed on is the answer — read with the shape, like any other object
        // step.
        if matches!(steps.last(), Some(PathStep::TypeIntersection(_))) {
            let module = current_td.module.clone();
            let type_name = format!("{}::{}", current_td.module, current_td.name);
            let shape = self.compile_shape_anchored(shape_elements, current_td, &current_alias, &module)?;
            let (filter, order_by, offset, limit) = self.compile_path_modifiers_scoped(
                sel,
                current_td,
                &current_alias,
                junction_scope.clone(),
                shape_elements,
            )?;
            return Ok(IrPathSelect {
                root,
                joins,
                result: IrPathResult::Object {
                    alias: current_alias,
                    type_name,
                    shape,
                },
                filter: and_conditions(filter, extra_conditions),
                order_by,
                offset,
                limit,
                distinct,
                poly_implementors: vec![],
            });
        }

        // Should be unreachable: steps is non-empty (we checked len > 1 before dispatch).
        Err(self.type_err("empty path traversal"))
    }

    /// `compile_path_modifiers` with the junction the traversal last crossed
    /// in scope, so a bare `@prop` in the select's own FILTER/ORDER BY can
    /// read it. Pushes nothing when there is no junction, leaving `@prop` to
    /// report that it has no link to belong to.
    fn compile_path_modifiers_scoped(
        &mut self,
        sel: &ast::SelectStmt,
        td: &TypeDescriptor,
        alias: &str,
        junction: Option<(String, String)>,
        shape: &[ShapeElement],
    ) -> Result<SelectModifiers, PyQLError> {
        let pushed = junction.is_some();
        if pushed {
            self.link_prop_scope.push(junction);
        }
        // `select .applied_promotions { name := .promotion.name } order by .name`
        // — the shape's own computeds are in scope for the clauses beside it,
        // the same as for a schema select. Added only now, after the shape has
        // been compiled, so one shape pointer still cannot read another.
        let outer_declared = self.active_declared_pointers.clone();
        self.active_declared_pointers
            .extend(shape.iter().filter(|el| el.compexpr.is_some()).cloned());
        let anchored = self.modifier_anchor.take();
        let tail_sorts = std::mem::take(&mut self.tail_sorts);
        let result = match &anchored {
            Some((qualified, anchor_alias)) => {
                let anchor_td = self.resolve_type(qualified)?;
                let anchor_alias = anchor_alias.clone();
                self.compile_path_modifiers(sel, anchor_td, &anchor_alias)
            }
            None => self.compile_path_modifiers(sel, td, alias),
        };
        let result = result.and_then(|(filter, mut order_by, offset, limit)| {
            if !tail_sorts.is_empty() {
                let sorting = ast::SelectStmt {
                    result: sel.result.clone(),
                    filter: None,
                    order_by: tail_sorts,
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let (_, sorts, _, _) = self.compile_path_modifiers(&sorting, td, alias)?;
                order_by = sorts;
            }
            Ok((filter, order_by, offset, limit))
        });
        if pushed {
            self.link_prop_scope.pop();
        }
        self.active_declared_pointers = outer_declared;
        result
    }

    fn compile_path_modifiers(
        &mut self,
        sel: &ast::SelectStmt,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<SelectModifiers, PyQLError> {
        self.anchors.push(SelectAnchor {
            type_name: td.name.clone(),
            qualified: format!("{}::{}", td.module, td.name),
            alias: alias.to_string(),
            detached: std::mem::take(&mut self.pending_detached),
            declared_on: None,
        });
        let result = self.compile_path_modifiers_inner(sel, td, alias);
        self.anchors.pop();
        result
    }

    fn compile_path_modifiers_inner(
        &mut self,
        sel: &ast::SelectStmt,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<SelectModifiers, PyQLError> {
        let filter = sel
            .filter
            .as_ref()
            .map(|f| self.as_condition(|c| c.compile_expr(f, td, alias)))
            .transpose()?;
        let order_by = sel
            .order_by
            .iter()
            .map(|s| self.compile_sort(s, td, alias))
            .collect::<Result<Vec<_>, _>>()?;
        let offset = sel
            .offset
            .as_ref()
            .map(|e| self.compile_expr(e, td, alias))
            .transpose()?;
        let limit = sel
            .limit
            .as_ref()
            .map(|e| self.compile_expr(e, td, alias))
            .transpose()?;
        Ok((filter, order_by, offset, limit))
    }

    // ── Expression-over-type dispatch ─────────────────────────────────────────────

    /// The name of the set of objects `expr` stands for, when it is nothing
    /// but that name: a `with` binding of objects, or a type. Anything that
    /// walks off one (`accounts.owner`) is a path, not the set itself, and
    /// `find_path_root_in_expr` is what reads those.
    fn object_set_name(&self, expr: &Expr) -> Option<String> {
        let Expr::Path(p) = expr else { return None };
        if p.partial || p.steps.len() != 1 {
            return None;
        }
        let ast::PathStep::Name(name) = &p.steps[0] else {
            return None;
        };
        if self.cte_object_type(name).is_some() {
            return Some(name.clone());
        }
        // A bare name is a type only when nothing nearer claims it — the same
        // precedence `resolve_name_ref` gives for-vars, bindings and function
        // parameters over a schema type of the same name.
        let bound = self.for_vars.contains_key(name)
            || self.cte_free_items.contains_key(name)
            || self.inline_bindings.contains_key(name)
            || self.cte_types.contains_key(name)
            || self.fn_params.contains_key(name);
        if !bound && self.resolve_type(name).is_ok() {
            return Some(name.clone());
        }
        None
    }

    /// Recursively find the first absolute path (non-partial, multi-step) in an expression
    /// and return its root type name if it resolves to a known schema type.
    fn find_path_root_in_expr(&self, expr: &Expr) -> Option<String> {
        match expr {
            Expr::Path(p) if !p.partial && p.steps.len() > 1 => {
                if let ast::PathStep::Name(root) = &p.steps[0]
                    && (self.resolve_type(root).is_ok() || self.cte_object_type(root).is_some())
                {
                    return Some(root.clone());
                }
                None
            }
            Expr::FunctionCall(f) => f.args.iter().find_map(|a| self.find_path_root_in_expr(a)),
            Expr::BinOp(b) => self
                .find_path_root_in_expr(&b.left)
                .or_else(|| self.find_path_root_in_expr(&b.right)),
            Expr::UnaryOp(u) => self.find_path_root_in_expr(&u.operand),
            _ => None,
        }
    }

    /// Rewrite absolute paths rooted at `root_name` to relative (partial) paths.
    fn rewrite_abs_to_partial(expr: Expr, root_name: &str) -> Expr {
        match expr {
            Expr::Path(ref p) if !p.partial => {
                if let ast::PathStep::Name(first) = &p.steps[0]
                    && first == root_name
                    && p.steps.len() > 1
                {
                    return Expr::Path(ast::Path {
                        steps: p.steps[1..].to_vec(),
                        partial: true,
                    });
                }
                expr
            }
            Expr::FunctionCall(f) => Expr::FunctionCall(ast::FunctionCall {
                module: f.module,
                name: f.name,
                args: f
                    .args
                    .into_iter()
                    .map(|a| Self::rewrite_abs_to_partial(a, root_name))
                    .collect(),
                kwargs: f.kwargs,
            }),
            Expr::BinOp(b) => Expr::BinOp(Box::new(ast::BinOp {
                left: Self::rewrite_abs_to_partial(b.left, root_name),
                op: b.op,
                right: Self::rewrite_abs_to_partial(b.right, root_name),
            })),
            Expr::UnaryOp(u) => Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: u.op,
                operand: Self::rewrite_abs_to_partial(u.operand, root_name),
            })),
            other => other,
        }
    }

    /// The pointers a sub-select's shape declares, as the relative paths they
    /// stand for: `{ handle := [is Handle].handle }` → `handle` → `[is
    /// Handle].handle`. `None` when any element is something other than a
    /// named pointer defined by a relative path, which this substitution
    /// cannot stand in for.
    fn shape_alias_paths(elements: &[ShapeElement]) -> Option<Vec<(String, ast::Path)>> {
        let mut defs = Vec::with_capacity(elements.len());
        for element in elements {
            let [ast::PathStep::Name(name)] = element.path.steps.as_slice() else {
                return None;
            };
            match &element.compexpr {
                Some(Expr::Path(p)) if p.partial => defs.push((name.clone(), p.clone())),
                _ => return None,
            }
        }
        Some(defs)
    }

    /// Replace each `.alias` a sub-select's shape declares with the path it
    /// stands for, so the select's own FILTER/ORDER BY read the same thing the
    /// shape projects.
    fn substitute_shape_aliases(expr: Expr, defs: &[(String, ast::Path)]) -> Expr {
        match expr {
            Expr::Path(ref p) if p.partial => {
                let Some(ast::PathStep::Name(first)) = p.steps.first() else {
                    return expr;
                };
                let Some((_, definition)) = defs.iter().find(|(name, _)| name == first) else {
                    return expr;
                };
                let mut steps = definition.steps.clone();
                steps.extend(p.steps[1..].iter().cloned());
                Expr::Path(ast::Path { steps, partial: true })
            }
            Expr::FunctionCall(f) => Expr::FunctionCall(ast::FunctionCall {
                module: f.module,
                name: f.name,
                args: f
                    .args
                    .into_iter()
                    .map(|a| Self::substitute_shape_aliases(a, defs))
                    .collect(),
                kwargs: f.kwargs,
            }),
            Expr::BinOp(b) => Expr::BinOp(Box::new(ast::BinOp {
                left: Self::substitute_shape_aliases(b.left, defs),
                op: b.op,
                right: Self::substitute_shape_aliases(b.right, defs),
            })),
            Expr::UnaryOp(u) => Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: u.op,
                operand: Self::substitute_shape_aliases(u.operand, defs),
            })),
            other => other,
        }
    }

    /// `array_agg(array_unpack(X))` — the aggregate runs over the elements the
    /// array unpacks to. PostgreSQL rejects a set-returning call inside an
    /// aggregate ("aggregate function calls cannot contain set-returning
    /// function calls"), so the unpacking moves to a row source of its own and
    /// the aggregate reads that from outside. `None` when the result is not an
    /// aggregate over an unpacked array, leaving the ordinary routes to it.
    fn aggregate_over_unpacked(
        &mut self,
        sel: &ast::SelectStmt,
        result: &Expr,
        distinct: bool,
    ) -> Result<Option<IrExpr>, PyQLError> {
        let Expr::FunctionCall(f) = result else {
            return Ok(None);
        };
        let [Expr::FunctionCall(unpack)] = f.args.as_slice() else {
            return Ok(None);
        };
        if !f.kwargs.is_empty()
            || !unpack.kwargs.is_empty()
            || unpack.module.as_deref().unwrap_or("std") != "std"
            || unpack.name != "array_unpack"
        {
            return Ok(None);
        }
        let [array] = unpack.args.as_slice() else {
            return Ok(None);
        };
        let namespace = f.module.as_deref().unwrap_or("std");
        let Some(sql_name) =
            crate::stdlib::lookup(namespace, &f.name)
                .into_iter()
                .find_map(|d| match &d.impl_strategy {
                    crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => Some(sql_name.to_string()),
                    _ => None,
                })
        else {
            return Ok(None);
        };

        // A walk is unpacked one row at a time, so the unnest belongs in that
        // walk's own projection; anything else is a single array standing on
        // its own and unnests directly.
        let elements = match array {
            Expr::Path(path) if !path.partial && path.steps.len() > 1 => {
                let walk = ast::Path {
                    partial: false,
                    steps: path.steps.clone(),
                };
                let mut path_select = self.compile_path_select(sel, &walk, &[], distinct)?;
                let IrPathResult::Scalar(column, _) = path_select.result else {
                    return Ok(None);
                };
                path_select.result = IrPathResult::Scalar(
                    IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: None,
                        name: "unnest".to_string(),
                        args: vec![column],
                        sql_template: None,
                    }),
                    None,
                );
                IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(path_select))))
            }
            _ if sel.filter.is_none()
                && sel.order_by.is_empty()
                && sel.offset.is_none()
                && sel.limit.is_none()
                && !distinct =>
            {
                self.compile_expr_ctx(array, None)?
            }
            _ => return Ok(None),
        };

        // Over no rows SQL's aggregates give NULL where PyQL's give the empty
        // set's own value.
        let over_nothing = aggregate_over_nothing_sql(&f.name).unwrap_or("NULL");
        Ok(Some(IrExpr::FunctionCall(IrFunctionCall {
            return_pg_type: None,
            schema: None,
            name: sql_name.clone(),
            args: vec![elements],
            sql_template: Some(format!(
                "(SELECT coalesce({sql_name}(\"_s\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_s\"(\"v\"))"
            )),
        })))
    }

    /// Compile an expression that contains a type-rooted absolute path as a flat
    /// path select, iterating over the root type and projecting the expression as
    /// a scalar computed pointer.
    fn compile_expr_as_path_select(
        &mut self,
        sel: &ast::SelectStmt,
        result: &Expr,
        root_type_name: &str,
        distinct: bool,
    ) -> Result<IrPathSelect, PyQLError> {
        // `array_agg(a.sessions.id)` — a single-argument aggregate over a
        // path. The aggregate applies to the set the path traverses *to*, so
        // the traversal becomes this select's own row source and the aggregate
        // wraps the column it lands on. Compiling the path as an expression
        // instead yields the array it stands for, and aggregating that nests it
        // one level deep.
        // `array_agg(distinct X.p)` — the DISTINCT belongs *inside* the
        // aggregate. The unary `distinct` emits its operand unchanged (it is
        // normally applied where the set is built, which an aggregate argument
        // is not), so left here it silently keeps the duplicates.
        let (agg_arg, agg_distinct) = match result {
            Expr::FunctionCall(f) if f.args.len() == 1 => match &f.args[0] {
                Expr::UnaryOp(u) if matches!(u.op, ast::UnaryOpKind::Distinct) => (Some(&u.operand), true),
                other => (Some(other), false),
            },
            _ => (None, false),
        };
        if let Expr::FunctionCall(f) = result
            && f.args.len() == 1
            && let Some(Expr::Path(p)) = agg_arg
            && !p.partial
            && p.steps.len() > 1
        {
            let arg_path = ast::Path {
                partial: false,
                steps: p.steps.clone(),
            };
            let mut ps = self.compile_path_select(sel, &arg_path, &[], distinct)?;
            // A walk onto objects (`count(.<brand[is Licence])`) is counted by
            // its rows, which is its key. Falling through instead put the
            // aggregate back through the expression route that sent it here.
            let aggregated = match ps.result.clone() {
                IrPathResult::Scalar(column, _) => Some(column),
                IrPathResult::Object { alias, .. } => Some(IrExpr::ColumnRef {
                    alias,
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                }),
            };
            if let Some(column) = aggregated {
                let mut args = vec![column];
                if !f.kwargs.is_empty() {
                    if !matches!(f.name.as_str(), "assert_single" | "assert_exists" | "assert_distinct") {
                        return Err(self.type_err(&format!(
                            "function '{}' does not take named arguments, got '{}'",
                            f.name, f.kwargs[0].0
                        )));
                    }
                    args.extend(self.assert_message(f, None)?);
                }
                let mut call = self.resolve_fn_call(f.module.as_deref(), &f.name, args)?;
                if agg_distinct {
                    let IrExpr::FunctionCall(fc) = &mut call else {
                        return Err(self.type_err(&format!(
                            "'{}' does not take a distinct argument — it does not resolve to an aggregate",
                            f.name
                        )));
                    };
                    if fc.schema.is_some() || fc.sql_template.is_some() {
                        return Err(self.type_err(&format!(
                            "'distinct' inside '{}' is not supported — only a plain SQL aggregate can take it",
                            f.name
                        )));
                    }
                    fc.sql_template = Some(format!("{}(DISTINCT $1)", fc.name));
                }
                ps.result = IrPathResult::Scalar(aggregate_over_nothing(&f.name, call), None);
                return Ok(ps);
            }
        }

        // BinOp where one side is the absolute type-rooted path:
        // Build the join chain for the path side, then apply the comparison
        // element-wise so we get one boolean per traversal element (not one EXISTS per root).
        if let Expr::BinOp(b) = result {
            let (path_expr, value_expr, flip) = match (&b.left, &b.right) {
                (Expr::Path(p), v) if !p.partial => (p, v, false),
                (v, Expr::Path(p)) if !p.partial => (p, v, true),
                _ => return self.compile_expr_as_path_select_fallback(sel, result, root_type_name, distinct),
            };
            // Compile value side first so we can report its type in errors
            let root_td = match self.cte_object_type(root_type_name) {
                Some(t) => self.resolve_type(&t)?,
                None => self.resolve_type(root_type_name)?,
            };
            // Build PathSelect for the path (builds root + joins + scalar/object result)
            let ast_path = ast::Path {
                partial: false,
                steps: path_expr.steps.clone(),
            };
            let mut ps = self.compile_path_select(sel, &ast_path, &[], distinct)?;
            let val_ir = self.compile_expr(value_expr, root_td, &ps.root.alias)?;
            // Extract the scalar result from the path
            let scalar_col = match ps.result {
                IrPathResult::Scalar(e, _) => e,
                IrPathResult::Object { type_name, .. } => {
                    let val_type = infer_ir_type(&val_ir).map(pg_type_to_pyql).unwrap_or("unknown");
                    return Err(PyQLError::Type(PyQLTypeError {
                        message: format!(
                            "operator '{}' cannot be applied to operands of type '{}' and '{}'",
                            b.op, type_name, val_type,
                        ),
                        position: Position { line: 0, col: 0 },
                    }));
                }
            };
            let (l, r) = if flip {
                (val_ir, scalar_col)
            } else {
                (scalar_col, val_ir)
            };
            ps.result = IrPathResult::Scalar(
                IrExpr::BinOp(Box::new(IrBinOp {
                    left: true_division_operand(&b.op, l, &r),
                    op: b.op.clone(),
                    right: r,
                })),
                None,
            );
            return Ok(ps);
        }
        self.compile_expr_as_path_select_fallback(sel, result, root_type_name, distinct)
    }

    fn compile_expr_as_path_select_fallback(
        &mut self,
        sel: &ast::SelectStmt,
        result: &Expr,
        root_type_name: &str,
        distinct: bool,
    ) -> Result<IrPathSelect, PyQLError> {
        let cte_object_type = self.cte_object_type(root_type_name);
        let td = match &cte_object_type {
            Some(t) => self.resolve_type(t)?,
            None => self.resolve_type(root_type_name)?,
        };
        let alias = self.fresh_alias();
        let root = IrSource {
            poly: None,
            type_name: format!("{}::{}", td.module, td.name),
            table: match &cte_object_type {
                Some(_) => self.cte_source_table(root_type_name),
                None => td.table.clone(),
            },
            alias: alias.clone(),
        };
        let rewritten = Self::rewrite_abs_to_partial(result.clone(), root_type_name);
        let expr = self.compile_expr(&rewritten, td, &alias)?;
        let (filter, order_by, offset, limit) = self.compile_path_modifiers(sel, td, &alias)?;
        Ok(IrPathSelect {
            root,
            joins: vec![],
            result: IrPathResult::Scalar(expr, None),
            filter,
            order_by,
            offset,
            limit,
            distinct,
            poly_implementors: vec![],
        })
    }

    /// Compile a SubQuery stmt to an `IrArraySource` for use in assert functions.
    /// The result is `ARRAY(SELECT scalar FROM compiled_inner)`.
    fn compile_subquery_to_array_source(&mut self, stmt: &Stmt) -> Result<IrArraySource, PyQLError> {
        match self.compile_stmt(stmt)? {
            IrStmt::Select(s) if matches!(s.rows.as_slice(), [IrRowSource::Bound { .. }]) => {
                Ok(IrArraySource::Select(s))
            }
            IrStmt::PathSelect(ps) => Ok(IrArraySource::PathSelect(Box::new(ps))),
            _ => Err(self.type_err("assert functions require a schema-bound SELECT as argument")),
        }
    }

    /// `exists` in either schema-bound (FILTER, computed pointer, etc. —
    /// `ctx = Some((td, alias))`) or free (`ctx = None`) expression context.
    /// The `Path`-based arms (backlink / prop / link / multilink existence)
    /// only apply schema-bound — guarded on `ctx.is_some()` — since none of
    /// those concepts exist without a schema type in scope; everything else
    /// (`Parameter`, `TypeCast`, `SubQuery`, and the scalar-expression
    /// fallback) is identical either way and just threads `ctx` through.
    fn compile_exists_ctx(
        &mut self,
        operand: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        match operand {
            // exists $param  /  exists <type>$param → $N IS NOT NULL
            Expr::Parameter(name) => {
                let idx = self.param_index(name);
                Ok(ir_is_not_null(IrExpr::Param { index: idx }))
            }
            // exists <type>expr → expr IS NOT NULL (cast result is always a scalar)
            Expr::TypeCast(_) => {
                let inner = self.compile_expr_ctx(operand, ctx)?;
                Ok(ir_is_not_null(inner))
            }

            // exists .<link[is Type] → EXISTS(SELECT 1 FROM type WHERE type.link_id = alias.id)
            Expr::Path(p)
                if ctx.is_some() && p.partial && matches!(p.steps.first(), Some(ast::PathStep::Backlink(_))) =>
            {
                let (td, alias) = ctx.unwrap();
                let current_qname = format!("{}::{}", td.module, td.name);
                let exists = self.compile_backlink_as_exists(&p.steps, None, &current_qname, alias)?;
                Ok(exists)
            }

            // exists .prop → alias.col IS NOT NULL
            // exists .link → alias.link_id IS NOT NULL
            // exists .multilink → EXISTS(SELECT 1 FROM junction WHERE src = alias.id)
            Expr::Path(p) if ctx.is_some() && p.partial && p.steps.len() == 1 => {
                let (td, alias) = ctx.unwrap();
                // `exists @dismissed` — a link property is a column on the
                // junction row the multi-link's own modifiers are being
                // compiled against, so whether it is set is an ordinary null
                // check on it.
                if let ast::PathStep::LinkProp(prop_name) = &p.steps[0] {
                    let prop = self.compile_link_prop_ref(prop_name)?;
                    return Ok(ir_is_not_null(prop));
                }
                // `filter exists .n` where the shape in scope declared `n` —
                // the pointer is on no type, so it is read as the expression it
                // was written as.
                if let ast::PathStep::Name(n) = &p.steps[0]
                    && Self::resolve_property(td, n).is_none()
                    && Self::resolve_link(td, n).is_none()
                    && Self::resolve_multilink(td, n).is_none()
                    && self.resolve_computed(td, n).is_none()
                    && let Some(expr) = self
                        .active_declared_pointers
                        .iter()
                        .find(|d| path_leaf(&d.path).is_ok_and(|name| name == n))
                        .and_then(|d| d.compexpr.clone())
                {
                    let inner = self.compile_expr(&expr, td, alias)?;
                    return Ok(ir_is_not_null(inner));
                }
                // `exists [is contact::IndividualContact]` — a bare narrowing
                // is the current row seen as that type, so whether it exists is
                // whether the row *is* one.
                if let ast::PathStep::TypeIntersection(type_ref) = &p.steps[0] {
                    let narrowed = self.resolve_type(&type_ref.qualified_name())?;
                    let check = format!("{}::{}", narrowed.module, narrowed.name);
                    let source = format!("{}::{}", td.module, td.name);
                    return Ok(self.type_check_bool_expr(&source, &check, td, alias));
                }
                let pointer_name = match &p.steps[0] {
                    ast::PathStep::Name(n) => n.as_str(),
                    _ => return Err(self.type_err("exists: invalid path step")),
                };
                if let Some(prop) = Self::resolve_property(td, pointer_name) {
                    return Ok(ir_is_not_null(IrExpr::ColumnRef {
                        alias: alias.to_string(),
                        column: prop.name.clone(),
                        pg_type: prop.pg_type.clone(),
                    }));
                }
                if let Some(link) = Self::resolve_link(td, pointer_name) {
                    if link.is_junction_backed() {
                        return self.compile_junction_link_exists_check(link, td, alias);
                    }
                    return Ok(ir_is_not_null(IrExpr::ColumnRef {
                        alias: alias.to_string(),
                        column: format!("{}_id", link.name),
                        pg_type: "uuid".to_string(),
                    }));
                }
                if Self::resolve_multilink(td, pointer_name).is_some() {
                    return self.compile_multilink_exists_check(pointer_name, td, alias);
                }
                // `exists .primary_email` — a computed pointer stands for the
                // path it names, and whether *that* is empty is the question.
                // Checked last, so a stored pointer of the same name still
                // wins; without it the suggester could see the name the
                // resolver had just reported as unknown.
                if let Some(cd) = self.resolve_computed(td, pointer_name) {
                    let expr_ast = crate::parse::parse_pointer_expr(&cd.expression).map_err(PyQLError::Syntax)?;
                    return self.compile_exists_ctx(&expr_ast, ctx);
                }
                Err(self.field_err(pointer_name, &format!("{}::{}", td.module, td.name)))
            }

            // `exists ((select .prices filter …))` — a sub-select over a
            // relative path is relative to the enclosing object, so it needs
            // the same rooting and correlation `count((select .prices))`
            // already gets. Compiled without them it resolves in free context
            // and reports the pointer as unknown.
            Expr::SubQuery(stmt)
                if ctx.is_some()
                    && matches!(
                        stmt.as_ref(),
                        Stmt::Select(inner) if matches!(&inner.result, Expr::Path(p) if p.partial)
                    ) =>
            {
                let Stmt::Select(inner) = stmt.as_ref() else {
                    unreachable!("checked by the guard")
                };
                let Expr::Path(path) = &inner.result else {
                    unreachable!("checked by the guard")
                };
                let (td, alias) = ctx.expect("checked by the guard");
                let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
                steps.extend(path.steps.iter().cloned());
                let full_path = ast::Path { steps, partial: false };
                let rooted = ast::SelectStmt {
                    result: Expr::Path(full_path.clone()),
                    filter: inner.filter.clone(),
                    order_by: inner.order_by.clone(),
                    offset: inner.offset.clone(),
                    limit: inner.limit.clone(),
                    lock: None,
                };
                let mut ps = self.compile_path_select(&rooted, &full_path, &[], false)?;
                Self::correlate_path_select(&mut ps, alias);
                Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: IrExpr::PathSubquery(Box::new(ps)),
                })))
            }

            // exists (select ...) → EXISTS(SELECT 1 FROM ...)
            Expr::SubQuery(stmt) => self.compile_subquery_exists(stmt),

            // `exists licenses` — a binding names a set, so it exists when it
            // has a row; the fallback's scalar subquery aborts on the second.
            operand if let Some(name) = self.resolve_cte_name(operand) => {
                let object = self.cte_types.get(name).is_some_and(|bound| bound.contains("::"));
                Ok(IrExpr::ExistsOverCte {
                    cte: name.to_string(),
                    column: (!object).then(|| "v".to_string()),
                })
            }

            // Fallback: any scalar expression → expr IS NOT NULL. When `ctx`
            // is `None` and `operand` is a partial `Path` not caught above
            // (guards failed since ctx.is_some() was false), this recurses
            // into the free-context Path handling, which itself produces the
            // "not valid in free SELECT" error — same as before the merge.
            other => {
                let inner = self.compile_expr_ctx(other, ctx)?;
                // A set operation already knows how to ask whether it yields
                // anything; going through the array would build it first.
                if let IrExpr::SetOp { op, left, right, .. } = inner {
                    return Ok(IrExpr::SetOp {
                        op,
                        left,
                        right,
                        mode: super::SetOpMode::Exists,
                    });
                }
                Ok(ir_is_not_null(inner))
            }
        }
    }

    /// Compile `exists (select ...)` → `EXISTS(SELECT 1 FROM ... WHERE ...)`.
    fn compile_subquery_exists(&mut self, stmt: &Stmt) -> Result<IrExpr, PyQLError> {
        match self.compile_stmt(stmt)? {
            IrStmt::Select(s) => {
                let mut rows = s.rows;
                if rows.len() != 1 {
                    return Err(self.type_err("exists requires a schema-bound SELECT expression"));
                }
                let IrRowSource::Bound { source, .. } = rows.remove(0) else {
                    return Err(self.type_err("exists requires a schema-bound SELECT expression"));
                };
                let inner = IrExpr::Subquery(Box::new(IrSelect::schema_bound(source, vec![], s.filter)));
                Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: inner,
                })))
            }
            IrStmt::PathSelect(ps) => {
                // EXISTS(SELECT 1 FROM root [JOINs] WHERE filter)
                // Reuse the path select but signal "exists" via a dedicated IR node
                Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(ps.root, vec![], ps.filter))),
                })))
            }
            _ => Err(self.type_err("exists requires a SELECT expression")),
        }
    }

    /// `EXISTS(SELECT 1 FROM junction WHERE junction.source = alias.id)` for a multi-link.
    /// Build the `IrSelect` over the junction/FK-target rows for a multilink,
    /// correlated to the current row (`alias.id`) — shared by `exists
    /// .multilink` and `count(.multilink)`.
    /// `EXISTS(SELECT 1 FROM junction WHERE junction.<source_col> = alias.id)`,
    /// correlated to the current row — shared by a multi-link's own `exists
    /// .multilink`/`count(.multilink)` and a junction-backed single link's
    /// `exists .link` (D2: same junction-info resolution either way).
    fn junction_correlation_select(
        &mut self,
        td: &TypeDescriptor,
        alias: &str,
        name: &str,
        target: &str,
        through: &Option<String>,
    ) -> Result<IrSelect, PyQLError> {
        let jt_alias = self.fresh_alias();
        let (jt_table, jt_module, jt_src_col, _, _) = self.junction_info_for(td, name, target, through)?;

        let filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: jt_alias.clone(),
                column: jt_src_col,
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        }));
        Ok(IrSelect::schema_bound(
            IrSource {
                poly: None,
                type_name: format!("{}::__jt__", jt_module),
                table: jt_table,
                alias: jt_alias,
            },
            vec![],
            Some(filter),
        ))
    }

    fn multilink_correlation_select(
        &mut self,
        ml_name: &str,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrSelect, PyQLError> {
        let ml = Self::resolve_multilink(td, ml_name).unwrap();
        let (name, target, through) = (ml.name.clone(), ml.target.clone(), ml.through.clone());
        self.junction_correlation_select(td, alias, &name, &target, &through)
    }

    fn compile_multilink_exists_check(
        &mut self,
        ml_name: &str,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let inner = self.multilink_correlation_select(ml_name, td, alias)?;
        Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: IrExpr::Subquery(Box::new(inner)),
        })))
    }

    /// Same as `compile_multilink_exists_check`, for `exists .link` where
    /// `link` is a junction-backed single link.
    fn compile_junction_link_exists_check(
        &mut self,
        l: &LinkDescriptor,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let (name, target, through) = (l.name.clone(), l.target.clone(), l.through.clone());
        let inner = self.junction_correlation_select(td, alias, &name, &target, &through)?;
        Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: IrExpr::Subquery(Box::new(inner)),
        })))
    }

    /// A junction-backed single link's target id, as a scalar correlated
    /// subquery — `(SELECT jt.<target_col> FROM junction AS jt WHERE
    /// jt.<source_col> = alias.id)`. Stands in wherever a plain single
    /// link's `{name}_id` FK column would otherwise be referenced directly
    /// as a scalar uuid expression (bare `.link` in a filter/order-by,
    /// `.link.id`, or correlating `.link.<other prop>`).
    fn junction_target_id_expr(
        &mut self,
        td: &TypeDescriptor,
        l: &LinkDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let (name, target, through) = (l.name.clone(), l.target.clone(), l.through.clone());
        let (jt_table, jt_module, jt_src_col, jt_tgt_col, _) = self.junction_info_for(td, &name, &target, &through)?;
        let jt_alias = self.fresh_alias();
        let filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: jt_alias.clone(),
                column: jt_src_col,
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        }));
        let select = IrSelect::schema_bound(
            IrSource {
                poly: None,
                type_name: format!("{}::__jt__", jt_module),
                table: jt_table,
                alias: jt_alias,
            },
            vec![IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: false,
                marker_offset: None,
                alias: "target".to_string(),
                column: jt_tgt_col,
                pg_type: "uuid".to_string(),
                tuple_shape: None,
            })],
            Some(filter),
        );
        Ok(IrExpr::Subquery(Box::new(select)))
    }

    /// Returns true when the SELECT result expression is not a schema type reference.
    /// Check that a UNION expression doesn't mix object types with scalars.
    /// Called before dispatch so we can give a clear error instead of "expected a type name".
    fn check_union_type_compat(&self, expr: &Expr) -> Result<(), PyQLError> {
        let Expr::Union(a, b) = expr else { return Ok(()) };
        let a_free = self.is_free_result(a);
        let b_free = self.is_free_result(b);
        if a_free != b_free {
            let left = self.union_operand_type_display(a);
            let right = self.union_operand_type_display(b);
            return Err(PyQLError::Type(PyQLTypeError {
                message: format!(
                    "operator 'UNION' cannot be applied to operands of type '{}' and '{}'",
                    left, right,
                ),
                position: Position { line: 0, col: 0 },
            }));
        }
        Ok(())
    }

    fn union_operand_type_display(&self, expr: &Expr) -> String {
        match expr {
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0]
                    && let Some(t) = self.cte_types.get(n.as_str())
                {
                    if t.contains("::") {
                        return t.clone(); // object CTE: "default::Person"
                    }
                    if !t.is_empty() {
                        return pg_type_to_pyql(t).to_string(); // scalar CTE: "std::int64"
                    }
                }
                // Bare type name reference
                if let Ok(td) = self.resolve_type(
                    p.steps
                        .first()
                        .and_then(|s| {
                            if let ast::PathStep::Name(n) = s {
                                Some(n.as_str())
                            } else {
                                None
                            }
                        })
                        .unwrap_or(""),
                ) {
                    return format!("{}::{}", td.module, td.name);
                }
            }
            Expr::Literal(Literal::Int(_)) => return "std::int64".to_string(),
            Expr::Literal(Literal::Str(_)) => return "std::str".to_string(),
            Expr::Literal(Literal::Float(_)) => return "std::float64".to_string(),
            Expr::Literal(Literal::Bool(_)) => return "std::bool".to_string(),
            _ => {}
        }
        "unknown".to_string()
    }

    fn is_free_result(&self, expr: &Expr) -> bool {
        let expr = match expr {
            Expr::UnaryOp(u) if u.op == ast::UnaryOpKind::Distinct => &u.operand,
            Expr::Detached(inner) => inner.as_ref(),
            other => other,
        };
        match expr {
            Expr::Path(p) if !p.partial => {
                if p.steps.len() == 1
                    && let ast::PathStep::Name(n) = &p.steps[0]
                {
                    // A for-loop variable over values is a scalar; one over
                    // objects stands for a row, and `select c` is a schema-
                    // bound select of its type.
                    if self.for_vars.contains_key(n.as_str()) {
                        return !self.for_var_types.contains_key(n.as_str());
                    }
                    // Scalar CTE: type string has no "::" (object types always do).
                    if self.is_value_binding(n.as_str()) {
                        return true;
                    }
                    // Function parameter — only populated while compiling a
                    // function body (see `compile_fn_body`), so a bare `select a`
                    // where `a` is a param must resolve as the param, not be
                    // misread as a schema-type-name select.
                    if self.fn_params.contains_key(n.as_str()) {
                        return true;
                    }
                }
                false
            }
            Expr::Shape(s) if s.expr.is_some() => false,
            Expr::SubQuery(_) => false,
            Expr::Union(a, b) => self.is_free_result(a) && self.is_free_result(b),
            // `A if cond else B` picks between two *sets*; when those are
            // object sets the result is an object set too, not the scalar an
            // if/else over values gives. An empty branch says nothing about
            // which it is, so it does not get a vote.
            Expr::IfElse(ie) => {
                let empty = |e: &Expr| matches!(e, Expr::Set(items) if items.is_empty());
                match (empty(&ie.if_expr), empty(&ie.else_expr)) {
                    (true, true) => true,
                    (true, false) => self.is_free_result(&ie.else_expr),
                    (false, true) => self.is_free_result(&ie.if_expr),
                    (false, false) => self.is_free_result(&ie.if_expr) || self.is_free_result(&ie.else_expr),
                }
            }
            _ => true,
        }
    }

    /// True when `expr` is a bare 1-step name bound to a free (non-object)
    /// WITH binding — the same "scalar CTE" check `is_free_result` uses for
    /// its `Expr::Path` arm, factored out so `Expr::Shape`'s handling of
    /// "shape applied to a non-object" can reuse it too.
    fn is_free_cte_ref(&self, expr: &Expr) -> bool {
        let Expr::Path(p) = expr else { return false };
        if p.partial || p.steps.len() != 1 {
            return false;
        }
        let ast::PathStep::Name(n) = &p.steps[0] else {
            return false;
        };
        self.is_value_binding(n.as_str())
    }

    // ── FREE SELECT ───────────────────────────────────────────────────────────────

    /// A mutation standing where a value is expected. Postgres cannot run DML
    /// in a value list, so it becomes a data-modifying CTE — which it runs to
    /// completion whether or not the outer query reads it — and what stands
    /// here reads the ids back, so the value still names the rows the
    /// mutation touched.
    fn dml_as_value(&mut self, stmt: &Stmt) -> Result<IrExpr, PyQLError> {
        let (cte_name, type_name) = self.hoist_dml_as_cte(stmt)?;
        // Read back through a subquery rather than naming the CTE's column
        // directly: a free select has no FROM of its own for the reference to
        // resolve against.
        let source = IrSource {
            poly: None,
            type_name,
            table: self.cte_source_table(&cte_name),
            alias: self.fresh_alias(),
        };
        Ok(IrExpr::Subquery(Box::new(IrSelect::schema_bound(
            source,
            // An empty shape would emit the `SELECT 1` an EXISTS wants, which
            // says nothing about which rows the value stands for.
            vec![IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: false,
                marker_offset: None,
                alias: "id".to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
                tuple_shape: None,
            })],
            None,
        ))))
    }

    fn collect_union_items(&mut self, expr: &Expr, items: &mut Vec<IrFreeExpr>) -> Result<(), PyQLError> {
        match expr {
            Expr::Union(a, b) => {
                self.collect_union_items(a, items)?;
                self.collect_union_items(b, items)?;
            }
            Expr::Set(exprs) => {
                for e in exprs {
                    self.collect_union_items(e, items)?;
                }
            }
            // `select { (update A set …), (update B set …) }` — several
            // mutations in one statement. Postgres cannot run DML in a value
            // list, so each becomes a data-modifying CTE, which it runs to
            // completion whether or not the outer query reads it; the item
            // itself reads back the id, so the set still stands for the rows
            // the mutations touched.
            Expr::SubQuery(stmt) if matches!(stmt.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) => {
                items.push(IrFreeExpr::Scalar(self.dml_as_value(stmt.as_ref())?));
            }
            other => {
                items.push(IrFreeExpr::Scalar(self.compile_free_expr(other)?));
            }
        }
        Ok(())
    }

    /// `metadata := metadata { author }` — a shape over a `with` binding or a
    /// for-loop variable. Both name a row source, so the shape reads their
    /// rows; a bare type name is deliberately not accepted here, because in an
    /// enclosing scope that prefix is factored (see `outer_anchor`) and would
    /// mean the outer row rather than the whole table.
    fn shape_over_binding(&mut self, expr: &Expr) -> Result<Option<IrExpr>, PyQLError> {
        let Expr::Shape(sh) = expr else {
            return Ok(None);
        };
        let Some(Expr::Path(p)) = sh.expr.as_ref() else {
            return Ok(None);
        };
        let Some(ast::PathStep::Name(root)) = p.steps.first() else {
            return Ok(None);
        };
        if p.partial || (self.cte_object_type(root).is_none() && !self.for_var_types.contains_key(root)) {
            return Ok(None);
        }
        self.free_object_link_field(expr)
    }

    /// A free object's field holding an object with a shape (`{ device := d
    /// { id } }`). A free shape is a real object type whose fields are real
    /// pointers, so an object field stays an object; without
    /// this it would compile to the object's bare id, which is not what was
    /// asked for.
    fn free_object_link_field(&mut self, expr: &Expr) -> Result<Option<IrExpr>, PyQLError> {
        let Expr::Shape(sh) = expr else {
            return Ok(None);
        };
        let Some(Expr::Path(p)) = sh.expr.as_ref() else {
            return Ok(None);
        };
        if p.partial {
            return Ok(None);
        }
        let rest_steps = p.steps.as_slice();
        let Some(ast::PathStep::Name(name)) = rest_steps.first() else {
            return Ok(None);
        };
        let cte_name = self.cte_object_type(name).map(|_| name.clone());
        let Ok(td) = self.resolve_path_root(name) else {
            return Ok(None);
        };
        let table = self.row_source_table(name, td);
        // `account := resource.account { id }` — the field holds what a walk
        // off the binding lands on, so it is that walk with the shape on it
        // rather than a plain read of the binding.
        if rest_steps.len() > 1 {
            let synthetic = ast::SelectStmt {
                result: Expr::Path(p.clone()),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            let path_select = self.compile_path_select(&synthetic, p, &sh.elements, false)?;
            return Ok(Some(IrExpr::ObjectPathSubquery(Box::new(path_select))));
        }
        let alias = self.fresh_alias();
        let source = IrSource {
            poly: self.poly_fanout_for(&format!("{}::{}", td.module, td.name)),
            type_name: format!("{}::{}", td.module, td.name),
            table,
            alias: alias.clone(),
        };
        // Same as reading the binding by name: its own shape may have
        // declared pointers that exist on no type.
        let outer_declared = std::mem::replace(
            &mut self.active_declared_pointers,
            cte_name
                .as_deref()
                .and_then(|n| self.cte_declared_pointers.get(n).cloned())
                .unwrap_or_default(),
        );
        let shape = self.compile_shape(&sh.elements, td, &alias, &td.module);
        self.active_declared_pointers = outer_declared;
        // A for-loop variable holds one row's key, so the select has to be
        // narrowed to it -- unfiltered it would read the whole table.
        let filter = self.for_var_types.contains_key(name).then(|| {
            IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: self.for_var_ref(name),
            }))
        });
        Ok(Some(IrExpr::ObjectSubquery(Box::new(IrSelect::schema_bound(
            source, shape?, filter,
        )))))
    }

    /// One field of a free object written as a whole SELECT's result. A
    /// mutation is allowed here for the same reason it is allowed as an item
    /// of a free set — see `dml_as_value`.
    fn free_object_field(&mut self, expr: &Expr) -> Result<IrExpr, PyQLError> {
        if let Some(object) = self.free_object_link_field(expr)? {
            return Ok(object);
        }
        match expr {
            Expr::SubQuery(stmt) if matches!(stmt.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) => {
                self.dml_as_value(stmt.as_ref())
            }
            other => self.compile_free_expr(other),
        }
    }

    fn compile_free_select(
        &mut self,
        sel: &ast::SelectStmt,
        result_expr: &Expr,
        distinct: bool,
    ) -> Result<IrSelect, PyQLError> {
        // `{ a := 1 } if cond else {}` — read as a scalar `CASE` it comes back
        // as a bare record instead of an object, so the object is the row and
        // the condition decides whether there is one.
        if let Expr::IfElse(ie) = result_expr {
            let is_empty_set = |expr: &Expr| matches!(expr, Expr::Set(items) if items.is_empty());
            let is_free_object = |expr: &Expr| matches!(expr, Expr::Shape(sh) if sh.expr.is_none());
            let guarded = if is_free_object(&ie.if_expr) && is_empty_set(&ie.else_expr) {
                Some((&ie.if_expr, false))
            } else if is_empty_set(&ie.if_expr) && is_free_object(&ie.else_expr) {
                Some((&ie.else_expr, true))
            } else {
                None
            };
            if let Some((object, negated)) = guarded {
                let condition = self.compile_free_expr(&ie.condition)?;
                let condition = if negated {
                    IrExpr::UnaryOp(Box::new(IrUnaryOp {
                        op: ast::UnaryOpKind::Not,
                        operand: condition,
                    }))
                } else {
                    condition
                };
                let mut select = self.compile_free_select(sel, object, distinct)?;
                select.filter = and_conditions(select.filter, vec![condition]);
                return Ok(select);
            }
        }
        let items: Vec<IrFreeExpr> = match result_expr {
            Expr::Union(_, _) | Expr::Set(_) => {
                let mut union_items = vec![];
                self.collect_union_items(result_expr, &mut union_items)?;
                // Type-check UNION operands: all scalar branches must be in the same type family.
                let mut first: Option<(String, String)> = None; // (pg_type, pyql_name)
                for item in &union_items {
                    if let IrFreeExpr::Scalar(expr) = item
                        && let Some(t) = infer_ir_type(expr)
                    {
                        let t = t.to_string();
                        if let Some((ft, fq)) = &first {
                            if !types_compatible(ft, &t) {
                                return Err(PyQLError::Type(PyQLTypeError {
                                    message: format!(
                                        "operator 'UNION' cannot be applied to operands of type '{}' and '{}'",
                                        fq,
                                        pg_type_to_pyql(&t),
                                    ),
                                    position: Position { line: 0, col: 0 },
                                }));
                            }
                        } else {
                            first = Some((t.clone(), pg_type_to_pyql(&t).to_string()));
                        }
                    }
                }
                union_items
            }
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    if self
                        .cte_types
                        .get(n.as_str())
                        .map(|t| !t.contains("::"))
                        .unwrap_or(false)
                    {
                        vec![IrFreeExpr::CtePassthrough(n.clone())]
                    } else {
                        vec![IrFreeExpr::Scalar(self.compile_free_expr(result_expr)?)]
                    }
                } else {
                    vec![IrFreeExpr::Scalar(self.compile_free_expr(result_expr)?)]
                }
            }
            Expr::Shape(s) if s.expr.is_none() => {
                let fields = s
                    .elements
                    .iter()
                    .map(|el| -> Result<(String, IrExpr), PyQLError> {
                        let name = path_leaf(&el.path)?.to_string();
                        let expr = el.compexpr.as_ref().ok_or_else(|| {
                            self.type_err("free object field must have a value expression (':= expr')")
                        })?;
                        Ok((name, self.free_object_field(expr)?))
                    })
                    .collect::<Result<Vec<_>, _>>()?;
                vec![IrFreeExpr::FreeObject(fields)]
            }
            Expr::Tuple(exprs) => {
                // An element may hold an object with a shape
                // (`select (offering { id }, revision { id })`), which is the
                // same question a free object's field asks.
                let ir = exprs
                    .iter()
                    .map(|e| self.free_object_field(e))
                    .collect::<Result<_, _>>()?;
                vec![IrFreeExpr::Tuple(ir)]
            }
            Expr::NamedTuple(fields) => {
                let ir = fields
                    .iter()
                    .map(|(name, e)| Ok((name.clone(), self.free_object_field(e)?)))
                    .collect::<Result<Vec<_>, PyQLError>>()?;
                // jsonb has no member kind for an object, so a tuple holding
                // one is emitted as a composite row instead; the rest stay on
                // the jsonb encoding they have always had.
                // An array of objects (`brands := array_agg((select b { * }))`)
                // flattens in jsonb the same way.
                let holds_an_object = ir.iter().any(|(_, e)| match e {
                    IrExpr::ObjectSubquery(_) | IrExpr::ObjectPathSubquery(_) => true,
                    IrExpr::ArrayFromSelect(source) => match source.as_ref() {
                        IrArraySource::ObjectSelect(_) | IrArraySource::ObjectFunction(_) | IrArraySource::Group(_) => {
                            true
                        }
                        IrArraySource::PathSelect(ps) => matches!(ps.result, IrPathResult::Object { .. }),
                        _ => false,
                    },
                    _ => false,
                });
                if holds_an_object {
                    vec![IrFreeExpr::NamedTupleRow(ir)]
                } else {
                    vec![IrFreeExpr::Scalar(IrExpr::NamedTuple {
                        fields: ir,
                        is_free_object: false,
                    })]
                }
            }
            other => vec![IrFreeExpr::Scalar(self.compile_free_expr(other)?)],
        };

        let order_by = sel
            .order_by
            .iter()
            .map(|s| self.compile_sort_ctx(s, None))
            .collect::<Result<Vec<_>, _>>()?;

        let offset = sel.offset.as_ref().map(|e| self.compile_free_expr(e)).transpose()?;
        let limit = sel.limit.as_ref().map(|e| self.compile_free_expr(e)).transpose()?;
        let filter = sel.filter.as_ref().map(|f| self.compile_free_filter(f)).transpose()?;

        Ok(IrSelect {
            rows: items.into_iter().map(IrRowSource::Free).collect(),
            filter,
            order_by,
            offset,
            limit,
            distinct,
            dml_source: None,
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: vec![],
            lock: None,
        })
    }

    /// The FILTER of a free SELECT, which has no row to apply itself to: it
    /// gates the result the select already produced.
    ///
    /// A condition over a type-rooted path is a *set* of booleans, one per row
    /// of that type, so the result survives when any of them holds — the same
    /// reading PyQL gives it, and the reason for the warning: a filter is
    /// meant to be one boolean, and `any()` says so outright.
    fn compile_free_filter(&mut self, filter: &Expr) -> Result<IrExpr, PyQLError> {
        self.as_condition(|c| c.compile_free_filter_inner(filter))
    }

    fn compile_free_filter_inner(&mut self, filter: &Expr) -> Result<IrExpr, PyQLError> {
        let Some(root) = self.find_path_root_in_expr(filter) else {
            return self.compile_free_expr(filter);
        };
        // A binding roots a path here as readily as a type name does; resolved
        // as a type it is simply unknown.
        let td = self.resolve_path_root(&root)?;
        let table = self.row_source_table(&root, td);
        let alias = self.fresh_alias();
        let source = IrSource {
            poly: None,
            type_name: format!("{}::{}", td.module, td.name),
            table,
            alias: alias.clone(),
        };
        let condition = self.compile_expr(&Self::rewrite_abs_to_partial(filter.clone(), &root), td, &alias)?;
        self.warnings.push(format!(
            "possibly more than one element returned by an expression in a FILTER clause \
             (every '{root}'); wrap with any() to make intent explicit",
        ));
        Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(source, vec![], Some(condition)))),
        })))
    }

    // ── SELECT ────────────────────────────────────────────────────────────────────

    /// The `(qualified type, source table)` of each branch of an object-set
    /// union, or `None` if any branch is something other than a direct
    /// reference to an object set (a WITH binding or a bare type name).
    /// The type a union of object sets carries: the one branch type every
    /// other branch is or implements. `A union (insert B)` where B implements
    /// A is an A-set, which is how PyQL reads it; requiring the branches
    /// to name the same type refuses a get-or-create over an interface.
    fn common_union_type(&self, branches: &[(String, String)]) -> Option<String> {
        let covers_all = |candidate: &String| {
            branches.iter().all(|(t, _)| {
                t == candidate
                    || self
                        .resolve_type(t)
                        .map(|td| Self::is_or_implements(td, candidate))
                        .unwrap_or(false)
            })
        };
        if let Some(branch) = branches.iter().map(|(t, _)| t.clone()).find(&covers_all) {
            return Some(branch);
        }
        // None of the branches is the others' supertype, but they may still
        // share one — `IncomingTransformer union OutgoingTransformer` are both
        // `Transformer`. The first branch's ancestors are the only candidates,
        // since a common type has to be among them.
        let first = self.resolve_type(&branches.first()?.0).ok()?;
        first
            .interfaces
            .iter()
            .chain(first.parents.iter())
            .find(|ancestor| covers_all(ancestor))
            .cloned()
    }

    fn object_union_branches(&self, expr: &Expr) -> Option<Vec<(String, String)>> {
        fn flatten<'e>(expr: &'e Expr, out: &mut Vec<&'e Expr>) {
            match expr {
                Expr::Union(a, b) => {
                    flatten(a, out);
                    flatten(b, out);
                }
                other => out.push(other),
            }
        }
        if !matches!(expr, Expr::Union(_, _)) {
            return None;
        }
        let mut operands: Vec<&Expr> = vec![];
        flatten(expr, &mut operands);

        let mut branches: Vec<(String, String)> = vec![];
        for operand in operands {
            let Expr::Path(path) = operand else { return None };
            if path.partial || path.steps.len() != 1 {
                return None;
            }
            let ast::PathStep::Name(name) = &path.steps[0] else {
                return None;
            };
            match self.cte_object_type(name) {
                Some(qualified) => branches.push((qualified, self.cte_source_table(&self.cte_sql_name(name)))),
                None => match self.resolve_type(name) {
                    Ok(td) => branches.push((format!("{}::{}", td.module, td.name), td.table.clone())),
                    Err(_) => return None,
                },
            }
        }
        Some(branches)
    }

    /// `select (a union b) { shape }` where every branch is a set of the same
    /// object type — a WITH binding or a bare type name. Each branch becomes
    /// its own bound row; the SQL layer unions them in the FROM clause, so the
    /// shape and modifiers are compiled once, against the shared type.
    ///
    /// `Ok(None)` when the result isn't an object union, leaving the ordinary
    /// single-source path (and its own errors) in charge.
    /// Give every operand of an object union a name to be read by.
    ///
    /// `object_union_branches` recognises operands that already name a
    /// relation -- a type, or a `with` binding -- because a union is emitted
    /// as one relation per branch. An operand written inline (a sub-select, or
    /// an insert in a get-or-create) names nothing yet, so it is hoisted into
    /// a CTE of its own and replaced by that name, leaving an ordinary union
    /// of names behind.
    fn name_union_operands(&mut self, expr: &Expr) -> Result<Option<Expr>, PyQLError> {
        let Expr::Union(left, right) = expr else {
            return Ok(None);
        };
        let mut rewritten = false;
        let mut name_one = |compiler: &mut Self, operand: &Expr| -> Result<Expr, PyQLError> {
            match operand {
                Expr::Union(_, _) => match compiler.name_union_operands(operand)? {
                    Some(inner) => {
                        rewritten = true;
                        Ok(inner)
                    }
                    None => Ok(operand.clone()),
                },
                Expr::SubQuery(stmt) => {
                    let (cte_name, type_name) = compiler.hoist_dml_as_cte(stmt.as_ref())?;
                    // An insert names its subject unqualified (`Credentials`),
                    // a select yields an already-qualified name; a branch that
                    // resolves to no object type is not one of these at all.
                    let Ok(td) = compiler.resolve_type(&type_name) else {
                        return Ok(operand.clone());
                    };
                    compiler
                        .cte_types
                        .insert(cte_name.clone(), format!("{}::{}", td.module, td.name));
                    rewritten = true;
                    Ok(Expr::Path(ast::Path {
                        steps: vec![ast::PathStep::Name(cte_name)],
                        partial: false,
                    }))
                }
                // `a.answers.question union a.current_question` — a walk names
                // no relation either, so it is hoisted the same way an inline
                // select is.
                Expr::Path(path) if !path.partial && path.steps.len() > 1 => {
                    let synthetic = Stmt::Select(ast::SelectStmt {
                        result: operand.clone(),
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        lock: None,
                    });
                    let Ok((cte_name, type_name)) = compiler.hoist_dml_as_cte(&synthetic) else {
                        return Ok(operand.clone());
                    };
                    let Ok(td) = compiler.resolve_type(&type_name) else {
                        return Ok(operand.clone());
                    };
                    compiler
                        .cte_types
                        .insert(cte_name.clone(), format!("{}::{}", td.module, td.name));
                    rewritten = true;
                    Ok(Expr::Path(ast::Path {
                        steps: vec![ast::PathStep::Name(cte_name)],
                        partial: false,
                    }))
                }
                other => Ok(other.clone()),
            }
        };
        let left = name_one(self, left)?;
        let right = name_one(self, right)?;
        if !rewritten {
            return Ok(None);
        }
        Ok(Some(Expr::Union(Box::new(left), Box::new(right))))
    }

    /// `A if cond else B` over object sets, as the union it is.
    ///
    /// Picking between two *sets* is not the scalar `CASE` an if/else over
    /// values compiles to: it stands for A's rows when the condition holds and
    /// B's when it does not, which is `(A filter cond) union (B filter not
    /// cond)`. Rewritten here rather than given its own IR, so it reaches the
    /// union machinery that already knows how to read one relation per branch.
    /// Hand a guarded mutation its condition: an insert folds it into its own
    /// `WHERE`, an update or a delete ANDs it onto the rows it narrows to.
    fn set_mutation_guard(&mut self, branch: &Expr, condition: Expr) {
        let stmt = match branch {
            Expr::SubQuery(stmt) => Some(stmt.as_ref()),
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::SubQuery(stmt)) => Some(stmt.as_ref()),
                _ => None,
            },
            _ => None,
        };
        match stmt {
            Some(Stmt::Update(_)) => self.pending_update_guard = Some(condition),
            Some(Stmt::Delete(_)) => self.pending_delete_guard = Some(condition),
            _ => self.pending_insert_guard = Some(condition),
        }
    }

    fn object_if_else_as_union(&mut self, expr: &Expr) -> Option<Expr> {
        let Expr::IfElse(ie) = expr else {
            return None;
        };
        fn is_empty_set(expr: &Expr) -> bool {
            matches!(expr, Expr::Set(items) if items.is_empty())
        }
        let yields_objects = |branch: &Expr| match branch {
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => match &p.steps[0] {
                ast::PathStep::Name(n) => self.cte_object_type(n).is_some() || self.resolve_type(n).is_ok(),
                _ => false,
            },
            Expr::SubQuery(stmt) => {
                // A select over a walk (`select resource.revisions`) yields
                // objects too, and names no type for `dml_subject_type` to
                // report; what it lands on is what the branch carries.
                if let Some(ast::SelectStmt {
                    result: Expr::Path(path),
                    ..
                }) = innermost_select(stmt.as_ref())
                    && !path.partial
                    && path.steps.len() > 1
                    && let Some(ast::PathStep::Name(root)) = path.steps.first()
                    && let Ok(root_td) = self.resolve_path_root(root)
                {
                    return matches!(
                        self.walk_path_types(root_td, &path.steps[1..], MAX_COMPUTED_SPLICES),
                        (_, Some(_))
                    );
                }
                matches!(
                    self.dml_subject_type(stmt.as_ref()),
                    Ok(name) if self.resolve_type(&name).is_ok()
                )
            }
            // A branch may carry the shape the result is read with.
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::SubQuery(stmt)) => {
                    matches!(self.dml_subject_type(stmt.as_ref()), Ok(name) if self.resolve_type(&name).is_ok())
                }
                Some(Expr::Path(p)) if !p.partial && p.steps.len() == 1 => match &p.steps[0] {
                    ast::PathStep::Name(n) => self.cte_object_type(n).is_some() || self.resolve_type(n).is_ok(),
                    _ => false,
                },
                _ => false,
            },
            _ => false,
        };
        // `{}` contributes no rows, so the union degenerates to the other
        // branch under its own guard -- which is what the full rewrite
        // (`SELECT A WHERE Cond UNION ALL SELECT B WHERE NOT Cond`) reduces
        // to when one side is empty.
        // A mutation under a condition is *not* handled here. Guarding the
        // branch only filters what is read back: the mutation is its own CTE
        // and Postgres runs it regardless, so `(insert …) if cond else {}`
        // would insert even when the condition is false -- silently, which is
        // far worse than the compile error it replaced. It needs the
        // condition folded into the mutation itself.
        fn mutating_stmt(branch: &Expr) -> Option<&Stmt> {
            match branch {
                Expr::SubQuery(stmt) => Some(stmt.as_ref()),
                Expr::Shape(sh) => match sh.expr.as_ref() {
                    Some(Expr::SubQuery(stmt)) => Some(stmt.as_ref()),
                    _ => None,
                },
                _ => None,
            }
            .filter(|stmt| matches!(stmt, Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)))
        }
        // Guarding a branch only filters what is read back, while the
        // mutation is its own CTE that Postgres runs regardless -- so the
        // condition has to go into the mutation itself, which is what
        // `set_mutation_guard` arranges for all three.
        let (if_yields_objects, else_yields_objects) = (yields_objects(&ie.if_expr), yields_objects(&ie.else_expr));
        let guard = |branch: &Expr, condition: Expr| {
            Expr::SubQuery(Box::new(Stmt::Select(ast::SelectStmt {
                result: branch.clone(),
                filter: Some(condition),
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            })))
        };
        let negated = Expr::UnaryOp(Box::new(ast::UnaryOp {
            op: ast::UnaryOpKind::Not,
            operand: ie.condition.clone(),
        }));
        let guarded_insert = |branch: &Expr, other: &Expr| {
            mutating_stmt(branch).is_some() && matches!(other, Expr::Set(items) if items.is_empty())
        };
        if guarded_insert(&ie.if_expr, &ie.else_expr) {
            self.set_mutation_guard(&ie.if_expr, ie.condition.clone());
            return Some(ie.if_expr.clone());
        }
        if guarded_insert(&ie.else_expr, &ie.if_expr) {
            let negated = Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: ast::UnaryOpKind::Not,
                operand: ie.condition.clone(),
            }));
            self.set_mutation_guard(&ie.else_expr, negated);
            return Some(ie.else_expr.clone());
        }
        // `(insert …) if not exists existing else (update existing set …)` —
        // the upsert idiom. Both branches mutate, so both carry their own
        // condition; each statement kind has its own pending slot, so two of
        // different kinds can be guarded at once. Two of the *same* kind would
        // have one guard overwrite the other, and fall through to the refusal
        // below rather than compile to a mutation that runs regardless.
        if let (Some(if_stmt), Some(else_stmt)) = (mutating_stmt(&ie.if_expr), mutating_stmt(&ie.else_expr))
            && std::mem::discriminant(if_stmt) != std::mem::discriminant(else_stmt)
        {
            self.set_mutation_guard(&ie.if_expr, ie.condition.clone());
            self.set_mutation_guard(&ie.else_expr, negated);
            return Some(Expr::Union(
                Box::new(ie.if_expr.clone()),
                Box::new(ie.else_expr.clone()),
            ));
        }
        // `existing if exists existing else (insert …)` — the insert still has
        // to carry the condition itself, but the other branch is a set of its
        // own, so the result is the full rewrite: both branches under
        // opposite guards, unioned.
        let reads_objects = |branch: &Expr, yields: bool| mutating_stmt(branch).is_none() && yields;
        if mutating_stmt(&ie.if_expr).is_some() && reads_objects(&ie.else_expr, else_yields_objects) {
            self.set_mutation_guard(&ie.if_expr, ie.condition.clone());
            return Some(Expr::Union(
                Box::new(ie.if_expr.clone()),
                Box::new(guard(&ie.else_expr, negated)),
            ));
        }
        if mutating_stmt(&ie.else_expr).is_some() && reads_objects(&ie.if_expr, if_yields_objects) {
            self.set_mutation_guard(&ie.else_expr, negated);
            return Some(Expr::Union(
                Box::new(guard(&ie.if_expr, ie.condition.clone())),
                Box::new(ie.else_expr.clone()),
            ));
        }
        if mutating_stmt(&ie.if_expr).is_some() || mutating_stmt(&ie.else_expr).is_some() {
            return None;
        }
        let (if_empty, else_empty) = (is_empty_set(&ie.if_expr), is_empty_set(&ie.else_expr));
        if if_empty && else_empty {
            return None;
        }
        if !(if_empty || if_yields_objects) || !(else_empty || else_yields_objects) {
            return None;
        }
        if else_empty {
            return Some(guard(&ie.if_expr, ie.condition.clone()));
        }
        if if_empty {
            return Some(guard(&ie.else_expr, negated));
        }
        Some(Expr::Union(
            Box::new(guard(&ie.if_expr, ie.condition.clone())),
            Box::new(guard(&ie.else_expr, negated)),
        ))
    }

    /// `granted ?? existing` over object sets is the choice `A if exists A
    /// else B` spells, so it reaches the same union machinery. A scalar
    /// coalesce rewritten this way is simply not an object union, and the
    /// caller falls back to compiling what was written.
    fn object_coalesce_as_if_else(expr: &Expr) -> Option<Expr> {
        fn as_if_else(b: &ast::BinOp) -> Option<Expr> {
            (b.op == ast::BinOpKind::Coalesce).then(|| {
                Expr::IfElse(Box::new(ast::IfElse {
                    condition: Expr::UnaryOp(Box::new(ast::UnaryOp {
                        op: ast::UnaryOpKind::Exists,
                        operand: b.left.clone(),
                    })),
                    if_expr: b.left.clone(),
                    else_expr: b.right.clone(),
                }))
            })
        }
        match expr {
            Expr::BinOp(b) => as_if_else(b),
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::BinOp(b)) => Some(Expr::Shape(Box::new(ast::ShapeExpr {
                    expr: Some(as_if_else(b)?),
                    elements: sh.elements.clone(),
                    marker_offset: sh.marker_offset,
                }))),
                _ => None,
            },
            _ => None,
        }
    }

    fn try_compile_object_union_select(
        &mut self,
        sel: &ast::SelectStmt,
        result_expr: &Expr,
        distinct: bool,
    ) -> Result<Option<IrSelect>, PyQLError> {
        let coalesced;
        let result_expr = match Self::object_coalesce_as_if_else(result_expr) {
            Some(rewritten) => {
                coalesced = rewritten;
                &coalesced
            }
            None => result_expr,
        };
        let as_union;
        let (union_expr, shape_elements): (&Expr, &[ShapeElement]) = match result_expr {
            Expr::Union(_, _) => (result_expr, &[]),
            Expr::IfElse(_) => match self.object_if_else_as_union(result_expr) {
                // One branch empty leaves a single guarded set, not a union;
                // that is an ordinary select over what the branch names.
                Some(rewritten @ Expr::SubQuery(_)) => {
                    return self.compile_select(sel, &rewritten, distinct).map(Some);
                }
                Some(rewritten) if !matches!(rewritten, Expr::Union(_, _)) => {
                    return self.compile_select(sel, &rewritten, distinct).map(Some);
                }
                Some(rewritten) => {
                    as_union = rewritten;
                    (&as_union, &[] as &[ShapeElement])
                }
                None => return Ok(None),
            },
            Expr::Shape(shape) => match &shape.expr {
                Some(inner @ Expr::Union(_, _)) => (inner, shape.elements.as_slice()),
                Some(inner @ Expr::IfElse(_)) => match self.object_if_else_as_union(inner) {
                    Some(Expr::SubQuery(stmt)) => {
                        let shaped = Expr::Shape(Box::new(ast::ShapeExpr {
                            expr: Some(Expr::SubQuery(stmt)),
                            elements: shape.elements.clone(),
                            marker_offset: None,
                        }));
                        return self.compile_select(sel, &shaped, distinct).map(Some);
                    }
                    Some(rewritten) if !matches!(rewritten, Expr::Union(_, _)) => {
                        let shaped = match rewritten {
                            Expr::Shape(_) => rewritten,
                            other => Expr::Shape(Box::new(ast::ShapeExpr {
                                expr: Some(other),
                                elements: shape.elements.clone(),
                                marker_offset: None,
                            })),
                        };
                        return self.compile_select(sel, &shaped, distinct).map(Some);
                    }
                    Some(rewritten) => {
                        as_union = rewritten;
                        (&as_union, shape.elements.as_slice())
                    }
                    None => return Ok(None),
                },
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };

        let named;
        let union_expr = match self.name_union_operands(union_expr)? {
            Some(rewritten) => {
                named = rewritten;
                &named
            }
            None => union_expr,
        };
        let Some(branches) = self.object_union_branches(union_expr) else {
            return Ok(None);
        };

        let Some(first_type) = self.common_union_type(&branches) else {
            let (first_type, _) = &branches[0];
            let (other, _) = branches
                .iter()
                .find(|(t, _)| t != first_type)
                .expect("no common type means at least two differ");
            return Err(self.type_err(&format!(
                "operator 'UNION' cannot be applied to operands of type '{first_type}' and '{other}'"
            )));
        };
        let first_type = &first_type;
        if sel.lock.is_some() {
            return Err(self.type_err(
                "FOR UPDATE/SHARE cannot be used on a UNION — its rows come from more than one \
                 source, which a single locking clause can't target",
            ));
        }
        let td = self.resolve_type(first_type)?;
        let alias = self.fresh_alias();

        self.anchors.push(SelectAnchor {
            type_name: td.name.clone(),
            qualified: format!("{}::{}", td.module, td.name),
            alias: alias.clone(),
            detached: std::mem::take(&mut self.pending_detached),
            declared_on: None,
        });
        let clauses = (|compiler: &mut Self| -> Result<_, PyQLError> {
            let shape = compiler.compile_shape(shape_elements, td, &alias, &td.module)?;
            let filter = sel
                .filter
                .as_ref()
                .map(|f| compiler.compile_expr(f, td, &alias))
                .transpose()?;
            let order_by = sel
                .order_by
                .iter()
                .map(|o| compiler.compile_sort(o, td, &alias))
                .collect::<Result<Vec<_>, _>>()?;
            let offset = sel
                .offset
                .as_ref()
                .map(|e| compiler.compile_expr(e, td, &alias))
                .transpose()?;
            let limit = sel
                .limit
                .as_ref()
                .map(|e| compiler.compile_expr(e, td, &alias))
                .transpose()?;
            Ok((shape, filter, order_by, offset, limit))
        })(self);
        self.anchors.pop();
        let (shape, mut filter, order_by, offset, limit) = clauses?;
        // A select whose subject is a for-loop variable reads the one row that
        // variable holds, not the whole table.
        if let Some(var) = Self::subject_name(result_expr).filter(|n| self.for_var_types.contains_key(n)) {
            let narrowed = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: self.for_var_ref(&var),
            }));
            filter = and_conditions(filter, vec![narrowed]);
        }

        // `brands union offerings` — types that only share an ancestor carry
        // different columns, so each branch is read as that ancestor: its
        // columns, and the concrete type each row has. An abstract branch's
        // rows already say which type they are.
        let heterogeneous = branches.iter().any(|(t, _)| t != first_type);
        let common_columns = if heterogeneous {
            self.collect_poly_info(first_type).1
        } else {
            vec![]
        };
        let rows = branches
            .into_iter()
            .map(|(type_name, table)| IrRowSource::Bound {
                source: IrSource {
                    poly: if heterogeneous {
                        self.poly_fanout_for(&type_name)
                    } else {
                        None
                    },
                    type_name,
                    table,
                    alias: alias.clone(),
                },
                shape: shape.clone(),
            })
            .collect();

        Ok(Some(IrSelect {
            rows,
            filter,
            order_by,
            offset,
            limit,
            distinct,
            dml_source: None,
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: common_columns,
            lock: None,
        }))
    }

    /// The bare name a select's result is written as, whether it carries a
    /// shape or not.
    fn subject_name(result_expr: &Expr) -> Option<String> {
        let path = match result_expr {
            Expr::Path(p) => p,
            Expr::Shape(sh) => match sh.expr.as_ref()? {
                Expr::Path(p) => p,
                _ => return None,
            },
            _ => return None,
        };
        if path.partial {
            return None;
        }
        match path.steps.as_slice() {
            [ast::PathStep::Name(n)] => Some(n.clone()),
            _ => None,
        }
    }

    fn compile_select(
        &mut self,
        sel: &ast::SelectStmt,
        result_expr: &Expr,
        distinct: bool,
    ) -> Result<IrSelect, PyQLError> {
        if let Some(union_select) = self.try_compile_object_union_select(sel, result_expr, distinct)? {
            return Ok(union_select);
        }
        if let Some(rerooted) = self.bind_mutating_loop_source(result_expr)? {
            return self.compile_select(sel, &rerooted, distinct);
        }
        let (type_name, shape_elements, inner_stmt, cte_name) = self.extract_type_and_shape(result_expr)?;
        let td = self.resolve_type(&type_name)?;
        let alias = self.fresh_alias();
        let table = match cte_name {
            Some(ref cte) => self.cte_source_table(cte),
            None => Self::subject_name(result_expr)
                .map(|name| self.row_source_table(&name, td))
                .unwrap_or_else(|| td.table.clone()),
        };
        let source = IrSource {
            poly: self.poly_fanout_for(&format!("{}::{}", td.module, td.name)),
            type_name: format!("{}::{}", td.module, td.name),
            table,
            alias: alias.clone(),
        };

        // On the stack for as long as this select's own clauses are being
        // compiled, so a `detached` select nested in one of them can find the
        // row it is being compared against. See `enclosing_anchor`.
        self.anchors.push(SelectAnchor {
            type_name: td.name.clone(),
            qualified: format!("{}::{}", td.module, td.name),
            alias: alias.clone(),
            detached: std::mem::take(&mut self.pending_detached),
            declared_on: None,
        });
        // A binding read back by name brings whatever its own shape declared
        // (`offering { publisher }`), which is on no type and has to be found
        // through the binding it was written on.
        let declared = match cte_name.as_deref() {
            Some(name) => self.cte_declared_pointers.get(name).cloned().unwrap_or_default(),
            // `select (select T { x := … }) filter .x…` — a nested select's
            // shape declares pointers on no type, just as a binding's does, and
            // the outer select's clauses read them the same way.
            None => inner_stmt
                .and_then(innermost_select)
                .and_then(|inner| match &inner.result {
                    Expr::Shape(sh) => Some(sh.elements.clone()),
                    _ => None,
                })
                .unwrap_or_default(),
        };
        // `*` on a binding takes in what the binding's shape computed, too.
        let splat_over_declared: Vec<ShapeElement>;
        let shape_elements = if shape_elements
            .iter()
            .any(|el| el.splat.is_some() && !matches!(el.path.steps.first(), Some(ast::PathStep::TypeIntersection(_))))
        {
            let named = |name: &str| {
                shape_elements
                    .iter()
                    .any(|el| el.splat.is_none() && path_leaf(&el.path).is_ok_and(|n| n == name))
            };
            let extra: Vec<ShapeElement> = declared
                .iter()
                .filter(|d| d.compexpr.is_some())
                .filter_map(|d| {
                    let name = path_leaf(&d.path).ok()?;
                    (!named(name)).then(|| ShapeElement {
                        path: ast::Path::relative(name),
                        splat: None,
                        nested: None,
                        compexpr: None,
                        op: ast::ShapeOp::Assign,
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        marker_offset: None,
                    })
                })
                .collect();
            splat_over_declared = shape_elements.iter().cloned().chain(extra).collect();
            &splat_over_declared[..]
        } else {
            shape_elements
        };
        let outer_declared = std::mem::replace(&mut self.active_declared_pointers, declared);
        let clauses = (|compiler: &mut Self| -> Result<_, PyQLError> {
            let shape = compiler.compile_shape(shape_elements, td, &alias, &td.module)?;
            // This select's own shape declares pointers the same way, and its
            // clauses read them the same way: `select T { x := … } order by .x`
            // is legal, while one shape pointer reading another is not. Added
            // only now, after the shape is compiled, so the scope stops at the
            // clauses.
            compiler
                .active_declared_pointers
                .extend(shape_elements.iter().filter(|el| el.compexpr.is_some()).cloned());
            let filter = sel
                .filter
                .as_ref()
                .map(|f| compiler.as_condition(|c| c.compile_expr(f, td, &alias)))
                .transpose()?;
            let order_by = sel
                .order_by
                .iter()
                .map(|s| compiler.compile_sort(s, td, &alias))
                .collect::<Result<Vec<_>, _>>()?;
            let offset = sel
                .offset
                .as_ref()
                .map(|e| compiler.compile_expr(e, td, &alias))
                .transpose()?;
            let limit = sel
                .limit
                .as_ref()
                .map(|e| compiler.compile_expr(e, td, &alias))
                .transpose()?;
            Ok((shape, filter, order_by, offset, limit))
        })(self);
        self.anchors.pop();
        self.active_declared_pointers = outer_declared;
        let (shape, mut filter, order_by, offset, limit) = clauses?;

        // A select whose subject is a for-loop variable reads the one row that
        // variable holds; unfiltered it would read the whole table.
        if let Some(var) = Self::subject_name(result_expr).filter(|n| self.for_var_types.contains_key(n)) {
            let narrowed = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: self.for_var_ref(&var),
            }));
            filter = and_conditions(filter, vec![narrowed]);
        }

        // Compile the inner DML if this is a SELECT-over-DML / SELECT-over-SELECT.
        let dml_source = inner_stmt.map(|s| self.compile_stmt(s).map(Box::new)).transpose()?;
        let mut shape = shape;
        if let Some(dml) = &dml_source {
            // `SELECT (INSERT …)` has no user-written CTE name: the emitter
            // wraps the DML in one of its own (`sql::DML_CTE`), and the
            // junction CTEs are named after it.
            let dml_cte = cte_name.as_deref().unwrap_or(crate::sql::DML_CTE);
            Self::read_nested_links_from_their_ctes(dml, Some(dml_cte), &mut shape);
        }

        let polymorphic = self.is_polymorphic(td);
        let (poly_implementors, poly_columns) = if polymorphic {
            let iface_qname = format!("{}::{}", td.module, td.name);
            (self.find_poly_implementors(&iface_qname), Self::poly_dml_columns(td))
        } else {
            (vec![], vec![])
        };

        // `FOR UPDATE`/`FOR SHARE`/... — only valid when every output row
        // maps 1:1 to a single physical table row, the same restriction
        // Postgres itself enforces (it rejects the same combinations with
        // its own "FOR UPDATE is not allowed with ..." errors). `DISTINCT`
        // and an interface (polymorphic) target both break that mapping;
        // `SELECT (INSERT/UPDATE/DELETE …) { ... }` has nothing left to
        // lock, since the DML already ran by the time this SELECT reads it.
        let lock = match &sel.lock {
            None => None,
            Some(lc) => {
                if distinct {
                    return Err(self.type_err(
                        "FOR UPDATE/SHARE cannot be combined with DISTINCT — Postgres can't \
                         guarantee the result rows map 1:1 to physical table rows",
                    ));
                }
                if polymorphic {
                    return Err(self.type_err(
                        "FOR UPDATE/SHARE cannot be used on an interface type — its rows span \
                         multiple underlying tables, which a single locking clause can't target",
                    ));
                }
                if dml_source.is_some() {
                    return Err(self.type_err(
                        "FOR UPDATE/SHARE cannot be used on SELECT (INSERT/UPDATE/DELETE …) — \
                         there's nothing left to lock once the DML has already run",
                    ));
                }
                Some(IrLockClause {
                    strength: match lc.strength {
                        ast::LockStrength::Update => IrLockStrength::Update,
                        ast::LockStrength::NoKeyUpdate => IrLockStrength::NoKeyUpdate,
                        ast::LockStrength::Share => IrLockStrength::Share,
                        ast::LockStrength::KeyShare => IrLockStrength::KeyShare,
                    },
                    wait: match lc.wait {
                        ast::LockWait::Block => IrLockWait::Block,
                        ast::LockWait::NoWait => IrLockWait::NoWait,
                        ast::LockWait::SkipLocked => IrLockWait::SkipLocked,
                    },
                })
            }
        };

        Ok(IrSelect {
            rows: vec![IrRowSource::Bound { source, shape }],
            filter,
            order_by,
            offset,
            limit,
            distinct,
            dml_source,
            polymorphic,
            poly_implementors,
            poly_columns,
            lock,
        })
    }

    /// Unwrap `Shape(expr, elements)` or bare `Path` from a SELECT result.
    /// Returns (type_name, shape_elements, optional_inner_stmt, optional_cte_name).
    /// The inner stmt is Some when the subject is `(INSERT …)` / `(SELECT …)` etc.
    /// The cte_name is Some when the subject is a WITH-block CTE reference.
    fn extract_type_and_shape<'e>(&self, expr: &'e Expr) -> Result<TypeAndShape<'e>, PyQLError> {
        match expr {
            Expr::Shape(s) => {
                // s.expr is Option<Expr> (not Box), so use as_ref() not as_deref()
                let (type_name, cte_name, inner) = match s.expr.as_ref() {
                    Some(Expr::SubQuery(stmt)) => (self.dml_subject_type(stmt)?, None, Some(stmt.as_ref())),
                    Some(Expr::Path(p)) if !p.partial && p.steps.len() == 1 => {
                        if let ast::PathStep::Name(n) = &p.steps[0] {
                            if let Some(t) = self.for_var_types.get(n.as_str()) {
                                (t.clone(), None, None)
                            } else if let Some(t) = self.cte_types.get(n.as_str()) {
                                if t.contains("::") {
                                    (t.clone(), Some(n.clone()), None)
                                } else {
                                    (self.expr_as_type_name(s.expr.as_ref().unwrap())?, None, None)
                                }
                            } else {
                                (self.expr_as_type_name(s.expr.as_ref().unwrap())?, None, None)
                            }
                        } else {
                            (self.expr_as_type_name(s.expr.as_ref().unwrap())?, None, None)
                        }
                    }
                    Some(inner) => (self.expr_as_type_name(inner)?, None, None),
                    None => {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: "shape without subject expression".into(),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                };
                Ok((type_name, &s.elements, inner, cte_name))
            }
            // Bare `SELECT (DML)` without an outer shape
            Expr::SubQuery(stmt) => Ok((self.dml_subject_type(stmt)?, &[], Some(stmt.as_ref()), None)),
            // Bare CTE object reference: `select cte_name`
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    if let Some(t) = self.for_var_types.get(n.as_str()) {
                        return Ok((t.clone(), &[], None, None));
                    }
                    if let Some(t) = self.cte_types.get(n.as_str())
                        && t.contains("::")
                    {
                        return Ok((t.clone(), &[], None, Some(n.clone())));
                    }
                }
                Ok((self.expr_as_type_name(expr)?, &[], None, None))
            }
            _ => Ok((self.expr_as_type_name(expr)?, &[], None, None)),
        }
    }

    /// True when `expr` is known to hold json, so `expr[…]` reaches into it
    /// with `->` rather than indexing a string or an array. A loop variable
    /// carries no type in the IR, so its `for` registration answers for it.
    fn is_json_expr(&self, ast: &Expr, ir: &IrExpr) -> bool {
        if matches!(infer_ir_type(ir), Some("jsonb")) {
            return true;
        }
        let Expr::Path(path) = ast else {
            return false;
        };
        if path.partial || path.steps.len() != 1 {
            return false;
        }
        let ast::PathStep::Name(name) = &path.steps[0] else {
            return false;
        };
        self.for_vars.get(name.as_str()).is_some_and(|t| t == "jsonb")
    }

    /// The pg type one row of a set-returning call yields. An overload that
    /// names its element type (`json_array_unpack` yields json) answers for
    /// itself; one declared `set of any` (`array_unpack`) takes the type from
    /// the array it unpacks. `None` when the call is not set-returning, or
    /// when neither the overload nor the argument names a scalar type.
    fn set_returning_element_type(&mut self, expr: &Expr) -> Result<Option<String>, PyQLError> {
        if !expr_returns_set(expr) {
            return Ok(None);
        }
        let Expr::FunctionCall(call) = expr else {
            return Ok(None);
        };
        // Overloads that disagree on the element type say nothing between
        // them, so only one answer shared by all of them counts.
        let mut declared = crate::stdlib::lookup(call.module.as_deref().unwrap_or("std"), &call.name)
            .into_iter()
            .map(|descriptor| match &descriptor.return_type {
                crate::stdlib::PylonType::Set(element) => element.scalar_pg_type(),
                _ => None,
            });
        if let Some(element) = declared.next().flatten()
            && declared.all(|other| other == Some(element))
        {
            return Ok(Some(element.to_string()));
        }
        let [argument] = call.args.as_slice() else {
            return Ok(None);
        };
        let compiled = self.compile_free_expr(argument)?;
        let Some(array_type) = infer_ir_type(&compiled) else {
            return Ok(None);
        };
        Ok(array_type
            .strip_suffix("[]")
            .map(|element| literal_sentinel_to_pg(element).to_string()))
    }

    fn compile_for(&mut self, f: &ast::ForStmt) -> Result<IrFor, PyQLError> {
        // A loop straight over a binding: the rows are that binding's, so a
        // walk off the variable reads it rather than the type's own table.
        let iterated_binding = self.resolve_cte_name(&f.iterator).map(|name| self.cte_sql_name(name));
        // Compile the iterator to determine what one loop variable binds to.
        let (iterator, pg_type, yielded_object_type) = match &f.iterator {
            Expr::Set(elems) => {
                let compiled: Result<Vec<_>, _> = elems.iter().map(|e| self.compile_free_expr(e)).collect();
                let exprs = compiled?;
                let raw = exprs.first().and_then(|e| infer_ir_type(e)).unwrap_or("text");
                let pg_type = literal_sentinel_to_pg(raw).to_string();
                (
                    IrForIterator::Values {
                        exprs,
                        pg_type: pg_type.clone(),
                    },
                    pg_type,
                    None,
                )
            }
            // A derived set — every row of it, not the single value a scalar
            // subquery in a one-row `VALUES` would collapse it to.
            Expr::SubQuery(stmt) => {
                let inner = self.compile_stmt(stmt)?;
                if !matches!(inner, IrStmt::Select(_) | IrStmt::PathSelect(_)) {
                    return Err(self.type_err(
                        "for-loop iterator: only a select can be iterated over — \
                         bind the statement in a `with` first",
                    ));
                }
                let yielded = cte_stmt_type(&inner);
                let scalar = !yielded.contains("::");
                let pg_type = if scalar {
                    let raw = if yielded.is_empty() { "text" } else { yielded.as_str() };
                    literal_sentinel_to_pg(raw).to_string()
                } else {
                    "uuid".to_string()
                };
                (
                    IrForIterator::Query {
                        stmt: Box::new(inner),
                        scalar,
                    },
                    pg_type,
                    (!scalar).then_some(yielded),
                )
            }
            // A WITH binding names a set, so the loop runs once per row of
            // it — not once over the single value a scalar subquery would
            // collapse it to.
            Expr::Path(p)
                if !p.partial
                    && p.steps.len() == 1
                    && matches!(&p.steps[0], ast::PathStep::Name(n) if self.cte_types.contains_key(n.as_str())) =>
            {
                let ast::PathStep::Name(name) = &p.steps[0] else {
                    unreachable!("checked by the guard")
                };
                let yielded = self.cte_types.get(name.as_str()).cloned().unwrap_or_default();
                let scalar = !yielded.contains("::");
                let pg_type = if scalar {
                    let raw = if yielded.is_empty() { "text" } else { yielded.as_str() };
                    literal_sentinel_to_pg(raw).to_string()
                } else {
                    "uuid".to_string()
                };
                let source = IrSource {
                    poly: None,
                    type_name: yielded.clone(),
                    table: self.cte_source_table(&self.cte_sql_name(name)),
                    alias: self.fresh_alias(),
                };
                (
                    IrForIterator::Query {
                        stmt: Box::new(IrStmt::Select(IrSelect::schema_bound(source, vec![], None))),
                        scalar,
                    },
                    pg_type,
                    (!scalar).then_some(yielded),
                )
            }
            // `for o in invitations.organizations union (…)` — a walk off a
            // binding names a set to iterate just as a sub-select does; it is
            // only written without the parentheses.
            Expr::Path(p) if !p.partial && p.steps.len() > 1 => {
                let synthetic = ast::SelectStmt {
                    result: Expr::Path(p.clone()),
                    filter: None,
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let inner = self.compile_stmt(&Stmt::Select(synthetic))?;
                let yielded = cte_stmt_type(&inner);
                let scalar = !yielded.contains("::");
                let pg_type = if scalar {
                    let raw = if yielded.is_empty() { "text" } else { yielded.as_str() };
                    literal_sentinel_to_pg(raw).to_string()
                } else {
                    "uuid".to_string()
                };
                (
                    IrForIterator::Query {
                        stmt: Box::new(inner),
                        scalar,
                    },
                    pg_type,
                    (!scalar).then_some(yielded),
                )
            }
            other => {
                let e = self.compile_free_expr(other)?;
                // A set-returning call is registered as `set of any`, so its
                // own type says nothing — the rows are the argument array's
                // elements, which is where the type comes from.
                let raw = match self.set_returning_element_type(other)? {
                    Some(element) => element,
                    None => literal_sentinel_to_pg(infer_ir_type(&e).unwrap_or("text")).to_string(),
                };
                let pg_type = raw;
                let iterator = if expr_returns_set(other) {
                    IrForIterator::SetReturning {
                        expr: e,
                        pg_type: pg_type.clone(),
                    }
                } else {
                    IrForIterator::Values {
                        exprs: vec![e],
                        pg_type: pg_type.clone(),
                    }
                };
                (iterator, pg_type, None)
            }
        };

        // The CTE name this loop's iterator is emitted under, claimed from the
        // statement's one namespace so no sibling loop and no binding can end
        // up under it too. The emitter spells it `_for_<slot>`.
        let slot = self
            .claim_generated_cte_name(&format!("_for_{}", f.var))
            .strip_prefix("_for_")
            .unwrap_or(&f.var)
            .to_string();
        let prev_slot = self.for_var_slots.insert(f.var.clone(), slot.clone());
        // Register the for variable so the body can reference it.
        let prev = self.for_vars.insert(f.var.clone(), pg_type.clone());
        let prev_cte = match iterated_binding {
            Some(name) => self.for_var_ctes.insert(f.var.clone(), name),
            None => self.for_var_ctes.remove(&f.var),
        };
        let prev_type = match yielded_object_type {
            Some(qualified) => self.for_var_types.insert(f.var.clone(), qualified),
            None => self.for_var_types.remove(&f.var),
        };
        let hoisted_before = self.hoisted_ctes.len();
        self.for_scope.push(slot.clone());
        let body = self.compile_stmt(&f.body);
        self.for_scope.pop();
        let body = body?;
        let body_ctes: Vec<IrCteDef> = self.hoisted_ctes.split_off(hoisted_before);
        // Restore previous for-var (or remove if none existed).
        match prev {
            Some(old) => {
                self.for_vars.insert(f.var.clone(), old);
            }
            None => {
                self.for_vars.remove(&f.var);
            }
        }
        match prev_type {
            Some(old) => {
                self.for_var_types.insert(f.var.clone(), old);
            }
            None => {
                self.for_var_types.remove(&f.var);
            }
        }
        match prev_cte {
            Some(old) => {
                self.for_var_ctes.insert(f.var.clone(), old);
            }
            None => {
                self.for_var_ctes.remove(&f.var);
            }
        }
        match prev_slot {
            Some(old) => {
                self.for_var_slots.insert(f.var.clone(), old);
            }
            None => {
                self.for_var_slots.remove(&f.var);
            }
        }

        // Checked here rather than left to the SQL emitter: `emit_for_stmt`
        // only implements these three body kinds, and reaching it with any
        // other one used to abort the process instead of reporting a PyQL
        // error the caller could act on.
        let body_kind = match &body {
            IrStmt::Insert(_) | IrStmt::Select(_) | IrStmt::PathSelect(_) => None,
            // An update is driven from the iteration itself (`UPDATE … FROM
            // <iterated set>`) rather than from a LATERAL, which cannot hold
            // DML. A multi-link mutation inside one would need its junction
            // rows driven from the iteration too, which it is not yet.
            // An append whose value is the loop variable itself can be driven
            // from the iteration (`emit_for_ml_append_cte`); anything more
            // would need its junction rows correlated in a way they are not.
            IrStmt::Update(upd)
                if upd.assignments.is_empty()
                    && upd.rewrites.is_empty()
                    && !upd.multi_link_appends.is_empty()
                    && upd
                        .multi_link_appends
                        .iter()
                        .all(|a| crate::sql::append_value_is_the_loop_variable(&a.values, &f.var))
                    && upd.multi_link_clears.is_empty()
                    && upd.multi_link_replaces.is_empty()
                    && upd.multi_link_removals.is_empty()
                    && upd.poly_implementors.is_empty() =>
            {
                None
            }
            // An interface target fans out into one UPDATE per implementor,
            // each driven from the iteration the same way.
            IrStmt::Update(upd)
                if upd.multi_link_appends.is_empty()
                    && upd.multi_link_clears.is_empty()
                    && upd.multi_link_replaces.is_empty()
                    && upd.multi_link_removals.is_empty() =>
            {
                None
            }
            IrStmt::Update(_) if std::env::var("PYLON_DBG_FORUPD").is_ok() => None,
            // `update x set { ml += (insert T { … }) }` — the insert runs once
            // per iteration, driven from the same rows the update is, and the
            // junction pairs each with the id that iteration generated. Only
            // appends: a clear/remove/replace has no such pairing.
            IrStmt::Update(upd)
                if upd.assignments.is_empty()
                    && upd.rewrites.is_empty()
                    && !upd.multi_link_appends.is_empty()
                    && upd.multi_link_clears.is_empty()
                    && upd.multi_link_replaces.is_empty()
                    && upd.multi_link_removals.is_empty()
                    && upd.poly_implementors.is_empty()
                    && upd
                        .multi_link_appends
                        .iter()
                        .all(|a| crate::sql::per_iteration_insert(a, &upd.nested_ctes).is_some()) =>
            {
                None
            }
            IrStmt::Update(_) => Some("update"),
            IrStmt::Delete(_) => Some("delete"),
            // `for line in … union (for component in … union (insert …))` —
            // one iterator CTE per loop, joined on the key the inner carries.
            // Only an insert innermost: anything else would need its own rows
            // driven from the pair, which they are not.
            IrStmt::For(inner) if matches!(inner.body.as_ref(), IrStmt::Insert(_)) => None,
            IrStmt::For(_) => Some("nested for"),
            IrStmt::Group(_) => Some("group"),
            _ => Some("this statement"),
        };
        if let Some(kind) = body_kind {
            return Err(self.type_err(&format!(
                "for-loop body: {kind} is not supported as a `for` body — use insert or select"
            )));
        }

        Ok(IrFor {
            var_name: slot,
            iterator,
            body: Box::new(body),
            body_ctes,
        })
    }

    fn compile_group(&mut self, g: &ast::GroupStmt) -> Result<IrGroup, PyQLError> {
        // Resolve the subject type — may be a schema type, a CTE alias, or a
        // walk. A walk (`group a.names by …`) names rows rather than a type:
        // the group runs over what it lands on, narrowed below to the rows it
        // yields, the same way `update a.preferences` narrows its own target.
        // The steps used to be joined with `::` and looked up as a type name,
        // which reported `a.names` as an unknown type `a::names`.
        let mut walked: Option<&ast::Path> = None;
        let (type_name, cte_name) = match &g.subject {
            Expr::Path(p) if !p.partial => match p.steps.as_slice() {
                [ast::PathStep::Name(n)] => {
                    if let Some(t) = self.cte_types.get(n.as_str()) {
                        (t.clone(), Some(n.clone()))
                    } else {
                        (n.clone(), None)
                    }
                }
                [ast::PathStep::Name(root), rest @ ..]
                    if !rest.is_empty()
                        && let Ok(root_td) = self.resolve_path_root(root)
                        && let (_, Some(target)) = self.walk_path_types(root_td, rest, MAX_COMPUTED_SPLICES) =>
                {
                    walked = Some(p);
                    (format!("{}::{}", target.module, target.name), None)
                }
                _ => {
                    return Err(PyQLError::Type(PyQLTypeError {
                        message: format!("unsupported group subject: {:?}", g.subject),
                        position: Position { line: 0, col: 0 },
                    }));
                }
            },
            _ => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: "group subject must be a type name".to_string(),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };

        let td = self.resolve_type(&type_name)?;
        let alias = self.fresh_alias();
        let fq_type_name = format!("{}::{}", td.module, td.name);
        let table = match cte_name {
            Some(ref cte) => self.cte_source_table(cte),
            None => td.table.clone(),
        };
        let source = IrSource {
            poly: self.poly_fanout_for(&fq_type_name),
            type_name: fq_type_name.clone(),
            table,
            alias: alias.clone(),
        };
        let module = td.module.clone();

        // Compile the element shape. No explicit shape → implicit { id }.
        let shape = self.compile_shape(g.shape.as_deref().unwrap_or(&[]), td, &alias, &module)?;

        // Build a map from using-alias → compiled expression.
        let td = self.resolve_type(&type_name)?;
        let mut using_map: HashMap<String, IrExpr> = HashMap::new();
        for (alias_name, expr) in &g.using {
            let ir = self.compile_expr(expr, td, &alias)?;
            using_map.insert(alias_name.clone(), ir);
        }

        // Compile BY keys: each is either an Ident (using-alias ref) or a partial Path (.prop).
        let mut keys: Vec<(String, IrExpr)> = vec![];
        let td = self.resolve_type(&type_name)?;
        for by_expr in &g.by {
            match by_expr {
                Expr::Path(p) if p.partial && p.steps.len() == 1 => {
                    if let ast::PathStep::Name(prop) = &p.steps[0] {
                        // `.prop` shorthand: infer alias = prop name, expr = column ref.
                        let ir = self.compile_expr(by_expr, td, &alias)?;
                        keys.push((prop.clone(), ir));
                    } else {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: "group by path must be a simple property".to_string(),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                }
                Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                    if let ast::PathStep::Name(name) = &p.steps[0] {
                        // Bare ident: must be a using alias.
                        let ir = using_map.get(name).ok_or_else(|| {
                            PyQLError::Type(PyQLTypeError {
                                message: format!("group by references unknown alias '{}'", name),
                                position: Position { line: 0, col: 0 },
                            })
                        })?;
                        keys.push((name.clone(), ir.clone()));
                    } else {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: "group by identifier must be a simple name".to_string(),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                }
                _ => {
                    return Err(PyQLError::Type(PyQLTypeError {
                        message: format!("unsupported group by expression: {:?}", by_expr),
                        position: Position { line: 0, col: 0 },
                    }));
                }
            }
        }

        // `filter` restricts the grouped rows; `order by`/`offset`/`limit`
        // apply within each group, so they're compiled against the same
        // element scope the shape is.
        let td = self.resolve_type(&type_name)?;
        let synthetic = ast::SelectStmt {
            result: g.subject.clone(),
            filter: g.filter.clone(),
            order_by: g.order_by.clone(),
            offset: g.offset.clone(),
            limit: g.limit.clone(),
            lock: None,
        };
        let (filter, order_by, offset, limit) = self.compile_path_modifiers(&synthetic, td, &alias)?;
        // A walked subject groups only the rows the walk reaches, not every
        // row of the type it happens to land on.
        let filter = match walked {
            Some(subject) => {
                let subject = subject.clone();
                let rows = self.compile_subject_path_rows(&subject, &alias)?;
                and_conditions(filter, vec![rows])
            }
            None => filter,
        };

        Ok(IrGroup {
            source,
            shape,
            keys,
            filter,
            order_by,
            offset,
            limit,
            output: IrGroupOutput::Groups,
        })
    }

    fn bind_group(&mut self, name: &str, expr: &Expr) -> Result<bool, PyQLError> {
        let Expr::SubQuery(stmt) = expr else {
            return Ok(false);
        };
        let Stmt::Group(g) = stmt.as_ref() else {
            return Ok(false);
        };
        let grp = self.compile_group(g)?;
        self.group_bindings.insert(name.to_string(), grp);
        Ok(true)
    }

    /// `select (group S using k := E by k) { n := count(.elements) }`. Each
    /// pointer is compiled over the grouped rows of `S`: `.key.k` stands for
    /// `E` itself, which is constant within a group, and an aggregate over
    /// `.elements.p` for the same aggregate over `.p`, which the `GROUP BY`
    /// then takes per group.
    fn compile_group_projection(
        &mut self,
        sel: &ast::SelectStmt,
        g: &ast::GroupStmt,
        elements: &[ShapeElement],
    ) -> Result<IrGroup, PyQLError> {
        if sel.filter.is_some() {
            return Err(self.type_err("a shape over a `group` does not support filter"));
        }
        if !g.order_by.is_empty() || g.offset.is_some() || g.limit.is_some() {
            return Err(self.type_err(
                "a `group` read through a shape does not support order by, offset or limit on its elements",
            ));
        }
        let mut grp = self.compile_group(g)?;
        // `.key.k` reads the key as the `GROUP BY` already compiled it:
        // compiling it a second time would give a walk fresh aliases, and
        // Postgres only accepts a grouped expression it can match verbatim.
        let keys: Vec<String> = grp.keys.iter().map(|(name, _)| name.clone()).collect();
        for (name, key) in &grp.keys {
            self.inline_bindings.insert(group_key_binding(name), key.clone());
        }
        let compiled = self.compile_group_projection_parts(sel, &grp, &keys, elements);
        for name in &keys {
            self.inline_bindings.remove(&group_key_binding(name));
        }
        let (pointers, order_by, offset, limit) = compiled?;
        grp.output = IrGroupOutput::Projection(Box::new(IrGroupProjection {
            pointers,
            order_by,
            offset,
            limit,
        }));
        Ok(grp)
    }

    #[allow(clippy::type_complexity)]
    fn compile_group_projection_parts(
        &mut self,
        sel: &ast::SelectStmt,
        grp: &IrGroup,
        keys: &[String],
        elements: &[ShapeElement],
    ) -> Result<(Vec<IrShapePointer>, Vec<IrSort>, Option<IrExpr>, Option<IrExpr>), PyQLError> {
        let td = self.resolve_type(&grp.source.type_name)?;
        let mut rewritten = Vec::with_capacity(elements.len());
        for element in elements {
            let (Some(compexpr), [ast::PathStep::Name(_)]) = (&element.compexpr, element.path.steps.as_slice()) else {
                return Err(self.type_err(
                    "only computed pointers (`name := …`) can be read off a `group` — e.g. `k := .key.name`",
                ));
            };
            let mut element = element.clone();
            element.compexpr = Some(self.rewrite_group_refs(compexpr, keys, td)?);
            rewritten.push(element);
        }
        let alias = grp.source.alias.clone();
        let module = td.module.clone();
        // `td` is here so `.key`/`.elements` resolve, but the row this
        // projects is the group's, not one of `td`'s: an `id` added to it
        // reads a column no GROUP BY covers.
        let pointers = self.without_implicit_id(|this| this.compile_shape(&rewritten, td, &alias, &module))?;
        let order_by = sel
            .order_by
            .iter()
            .map(|sort| {
                Ok(ast::SortExpr {
                    expr: self.rewrite_group_refs(&sort.expr, keys, td)?,
                    direction: sort.direction.clone(),
                    nones: sort.nones.clone(),
                })
            })
            .collect::<Result<Vec<_>, PyQLError>>()?;
        let synthetic = ast::SelectStmt {
            result: Expr::Path(ast::Path::absolute(grp.source.type_name.clone())),
            filter: None,
            order_by,
            offset: sel.offset.clone(),
            limit: sel.limit.clone(),
            lock: None,
        };
        let (_, order_by, offset, limit) = self.compile_path_modifiers(&synthetic, td, &alias)?;
        Ok((pointers, order_by, offset, limit))
    }

    fn rewrite_group_refs(&self, expr: &Expr, keys: &[String], td: &TypeDescriptor) -> Result<Expr, PyQLError> {
        const AGGREGATES: &[&str] = &["count", "sum", "min", "max", "avg", "array_agg", "all", "any"];
        let rewrite = |e: &Expr| self.rewrite_group_refs(e, keys, td);
        Ok(match expr {
            Expr::Path(p) if p.partial => {
                let name = match p.steps.first() {
                    Some(ast::PathStep::Name(name)) => name.as_str(),
                    _ => "",
                };
                match (name, p.steps.get(1..).unwrap_or_default()) {
                    ("key", [ast::PathStep::Name(key)]) if keys.contains(key) => {
                        Expr::Path(ast::Path::absolute(group_key_binding(key)))
                    }
                    ("key", [ast::PathStep::Name(key)]) => {
                        return Err(self.type_err(&format!("'{key}' is not a key of this group")));
                    }
                    ("elements", _) => {
                        return Err(self.type_err(
                            "`.elements` of a group can only be read through an aggregate over one \
                             of their properties — e.g. `count(.elements)`, `sum(.elements.amount)`",
                        ));
                    }
                    _ => {
                        return Err(self.type_err(&format!(
                            "a group has no pointer '{name}' — read `.key.<name>` or aggregate over `.elements`"
                        )));
                    }
                }
            }
            Expr::FunctionCall(f)
                if f.args.len() == 1
                    && f.kwargs.is_empty()
                    && f.module.as_deref().is_none_or(|m| m == "std")
                    && AGGREGATES.contains(&f.name.as_str())
                    && let Expr::Path(p) = &f.args[0]
                    && p.partial
                    && matches!(p.steps.first(), Some(ast::PathStep::Name(n)) if n == "elements") =>
            {
                let property = match p.steps.get(1..).unwrap_or_default() {
                    [] => "id",
                    [ast::PathStep::Name(prop)] if td.properties.iter().any(|d| &d.name == prop) => prop.as_str(),
                    _ => {
                        return Err(self.type_err(&format!(
                            "'{}' over a group's elements only reads one of their own properties",
                            f.name
                        )));
                    }
                };
                Expr::FunctionCall(ast::FunctionCall {
                    module: f.module.clone(),
                    name: f.name.clone(),
                    args: vec![Expr::Path(ast::Path::relative(property))],
                    kwargs: vec![],
                })
            }
            Expr::FunctionCall(f) => Expr::FunctionCall(ast::FunctionCall {
                module: f.module.clone(),
                name: f.name.clone(),
                args: f.args.iter().map(rewrite).collect::<Result<_, _>>()?,
                kwargs: f
                    .kwargs
                    .iter()
                    .map(|(k, v)| Ok((k.clone(), rewrite(v)?)))
                    .collect::<Result<_, PyQLError>>()?,
            }),
            Expr::BinOp(b) => Expr::BinOp(Box::new(ast::BinOp {
                left: rewrite(&b.left)?,
                op: b.op.clone(),
                right: rewrite(&b.right)?,
            })),
            Expr::UnaryOp(u) => Expr::UnaryOp(Box::new(ast::UnaryOp {
                op: u.op.clone(),
                operand: rewrite(&u.operand)?,
            })),
            Expr::TypeCast(c) => Expr::TypeCast(Box::new(ast::TypeCast {
                expr: rewrite(&c.expr)?,
                ty: c.ty.clone(),
            })),
            Expr::IfElse(ie) => Expr::IfElse(Box::new(ast::IfElse {
                if_expr: rewrite(&ie.if_expr)?,
                condition: rewrite(&ie.condition)?,
                else_expr: rewrite(&ie.else_expr)?,
            })),
            other => other.clone(),
        })
    }

    /// `for g in (group S by k) union (select g.elements order by … limit n)`
    /// — the first `n` rows of `S` per key. `None` for any other `for`.
    fn compile_group_elements(&mut self, f: &ast::ForStmt) -> Result<Option<IrGroup>, PyQLError> {
        let Stmt::Select(body) = f.body.as_ref() else {
            return Ok(None);
        };
        let unmodified =
            body.filter.is_none() && body.order_by.is_empty() && body.offset.is_none() && body.limit.is_none();
        let (inner, shape) = match &body.result {
            Expr::Shape(sh) if unmodified => match &sh.expr {
                Some(Expr::SubQuery(stmt)) => match stmt.as_ref() {
                    Stmt::Select(inner) => (inner, Some(sh.elements.as_slice())),
                    _ => return Ok(None),
                },
                _ => return Ok(None),
            },
            _ => (body, None),
        };
        let reads_elements = matches!(&inner.result, Expr::Path(p) if !p.partial
            && matches!(p.steps.as_slice(), [ast::PathStep::Name(var), ast::PathStep::Name(elements)]
                if var == &f.var && elements == "elements"));
        if !reads_elements {
            return Ok(None);
        }
        let mut grp = match &f.iterator {
            Expr::SubQuery(stmt) => match stmt.as_ref() {
                Stmt::Group(g) => self.compile_group(g)?,
                _ => return Ok(None),
            },
            Expr::Path(p) if !p.partial => match p.steps.as_slice() {
                [ast::PathStep::Name(name)] => match self.group_bindings.get(name) {
                    Some(grp) => grp.clone(),
                    None => return Ok(None),
                },
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };
        let ordered = !inner.order_by.is_empty() || inner.offset.is_some() || inner.limit.is_some();
        if ordered && (!grp.order_by.is_empty() || grp.offset.is_some() || grp.limit.is_some()) {
            return Err(self.type_err(
                "a group that already orders or limits its elements cannot be ordered or limited again by a `for` over it",
            ));
        }
        let td = self.resolve_type(&grp.source.type_name)?;
        let alias = grp.source.alias.clone();
        let synthetic = ast::SelectStmt {
            result: Expr::Path(ast::Path::absolute(grp.source.type_name.clone())),
            ..inner.clone()
        };
        let (filter, order_by, offset, limit) = self.compile_path_modifiers(&synthetic, td, &alias)?;
        grp.filter = and_conditions(grp.filter, filter.into_iter().collect());
        if ordered {
            grp.order_by = order_by;
            grp.offset = offset;
            grp.limit = limit;
        }
        if let Some(shape) = shape {
            let module = td.module.clone();
            grp.shape = self.compile_shape(shape, td, &alias, &module)?;
        }
        grp.output = IrGroupOutput::Elements;
        Ok(Some(grp))
    }

    /// The key a single-link assignment stores, for the values that name a
    /// row rather than compute one. `None` for anything the generic
    /// expression route already handles.
    fn compile_link_key(&mut self, expr: &Expr, td: &TypeDescriptor, alias: &str) -> Result<Option<IrExpr>, PyQLError> {
        // A one-element set is that element — `credentials := {
        // (insert Credentials { … }) }` says the same thing as assigning the
        // insert directly.
        let value = match expr {
            Expr::Set(elements) if elements.len() == 1 => &elements[0],
            other => other,
        };
        match value {
            // `link := (select { <T>a.id, <T>b.id } limit 1)` — a set literal
            // of keys, read for the one value its clauses leave.
            Expr::SubQuery(inner_stmt)
                if matches!(inner_stmt.as_ref(), Stmt::Select(sel) if matches!(sel.result, Expr::Set(_))) =>
            {
                let IrStmt::Select(select) = self.compile_stmt(inner_stmt)? else {
                    return Ok(None);
                };
                if !select.rows.iter().all(|r| matches!(r, IrRowSource::Free(IrFreeExpr::Scalar(_)))) {
                    return Ok(None);
                }
                Ok(Some(IrExpr::ScalarSubquery(Box::new(select))))
            }
            // Link assignment via subquery: `company := (SELECT Company FILTER ...)`
            // Compile as a scalar subquery returning the target pk (the FK uuid).
            Expr::SubQuery(inner_stmt) => self.compile_link_subquery(inner_stmt).map(Some),
            // `created_by := account_of_transaction()` — an object-returning
            // function names the row to link to, so what is stored is its key,
            // the same as for a select. The schema itself writes this as a
            // link default.
            Expr::FunctionCall(fc) => self.try_compile_fn_scalar_subquery(fc, &["id".to_string()], None, None),
            // `credentials := (update c set { … }) if exists(c) else (insert
            // Credentials { … })` — each mutation carries its own condition,
            // so exactly one branch yields the row to link.
            Expr::IfElse(ie)
                if [&ie.if_expr, &ie.else_expr].iter().any(|b| {
                    matches!(b, Expr::SubQuery(s) if matches!(s.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)))
                }) =>
            {
                let Some(rewritten) = self.object_if_else_as_union(value) else {
                    return Ok(None);
                };
                self.compile_link_key(&rewritten, td, alias)
            }
            Expr::Union(a, b) => {
                let (Some(left), Some(right)) = (self.compile_link_key(a, td, alias)?, self.compile_link_key(b, td, alias)?)
                else {
                    return Ok(None);
                };
                // A hoisted mutation's key is read by subquery: joined into
                // the statement instead, the branch that wrote nothing would
                // leave no row to update.
                let hoisted = |key: IrExpr| match key {
                    IrExpr::ColumnRef { alias, column, .. } if column == "id" => IrExpr::CteRef {
                        name: alias,
                        scalar: false,
                        pg_type: None,
                    },
                    other => other,
                };
                Ok(Some(IrExpr::FunctionCall(IrFunctionCall {
                    return_pg_type: None,
                    schema: None,
                    name: "coalesce".to_string(),
                    args: vec![hoisted(left), hoisted(right)],
                    sql_template: None,
                })))
            }
            // `by := account_of_transaction() if cond else {}` — each branch
            // names a row (or none) the same way.
            Expr::IfElse(ie) => {
                if ![&ie.if_expr, &ie.else_expr].iter().any(|b| matches!(b, Expr::FunctionCall(_))) {
                    return Ok(None);
                }
                Ok(Some(IrExpr::IfElse(Box::new(IrIfElse {
                    condition: self.compile_expr(&ie.condition, td, alias)?,
                    if_: self.compile_link_branch(&ie.if_expr, td, alias)?,
                    else_: self.compile_link_branch(&ie.else_expr, td, alias)?,
                }))))
            }
            _ => Ok(None),
        }
    }

    fn compile_link_branch(&mut self, branch: &Expr, td: &TypeDescriptor, alias: &str) -> Result<IrExpr, PyQLError> {
        if matches!(branch, Expr::Set(elements) if elements.is_empty()) {
            return Ok(IrExpr::Null);
        }
        match self.compile_link_key(branch, td, alias)? {
            Some(key) => Ok(key),
            None => self.compile_expr(branch, td, alias),
        }
    }

    /// `.teams { owning := … }.owning` — a walk, and a pointer its shape
    /// declares read back off each row it lands on. `None` for anything
    /// else, including a field the shape does not compute.
    fn compile_shape_field_select(
        &mut self,
        expr: &Expr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrPathSelect>, PyQLError> {
        let Expr::FieldAccess { expr: inner, field } = expr else {
            return Ok(None);
        };
        let Expr::Shape(sh) = inner.as_ref() else {
            return Ok(None);
        };
        let Some(Expr::Path(base)) = sh.expr.as_ref() else {
            return Ok(None);
        };
        let Some(value) = sh
            .elements
            .iter()
            .find(|el| matches!(el.path.steps.as_slice(), [ast::PathStep::Name(n)] if n == field))
            .and_then(|el| el.compexpr.clone())
        else {
            return Ok(None);
        };
        let (rooted, correlate) = if base.partial {
            let Some((td, alias)) = ctx else {
                return Ok(None);
            };
            let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
            steps.extend(base.steps.iter().cloned());
            (ast::Path { steps, partial: false }, Some(alias.to_string()))
        } else if base.steps.len() > 1 {
            (base.clone(), None)
        } else if let [ast::PathStep::Name(root)] = base.steps.as_slice()
            && let Ok(root_td) = self.resolve_path_root(root)
        {
            // A walk needs a step: `T[is T]` lands on the same objects.
            let narrowing = ast::PathStep::TypeIntersection(ast::ObjectRef {
                module: Some(root_td.module.clone()),
                name: root_td.name.clone(),
            });
            (
                ast::Path {
                    steps: vec![base.steps[0].clone(), narrowing],
                    partial: false,
                },
                None,
            )
        } else {
            return Ok(None);
        };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(rooted.clone()),
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            lock: None,
        };
        let mut ps = self.compile_path_select(&synthetic, &rooted, &[], false)?;
        if let Some(alias) = correlate {
            Self::correlate_path_select(&mut ps, &alias);
        }
        let IrPathResult::Object { alias, type_name, .. } = &ps.result else {
            return Err(self.type_err(&format!(
                "'{field}' is read off a walk that lands on a value, which has no shape"
            )));
        };
        let (alias, type_name) = (alias.clone(), type_name.clone());
        let td = self.resolve_type(&type_name)?;
        let value = self.compile_expr(&value, td, &alias)?;
        // A computed standing for a set is an array per row; the field reads
        // its elements, so the rows of all of them make up one set.
        let value = if yields_array(&value) {
            IrExpr::FunctionCall(IrFunctionCall {
                return_pg_type: None,
                schema: None,
                name: "unnest".to_string(),
                args: vec![value],
                sql_template: None,
            })
        } else {
            value
        };
        ps.result = IrPathResult::Scalar(value, None);
        Ok(Some(ps))
    }

    /// `l.addon.id` — an absolute walk that lands on a property, so it yields
    /// values rather than objects.
    fn is_scalar_walk(&self, expr: &Expr) -> bool {
        let Expr::Path(p) = expr else { return false };
        let (Some(ast::PathStep::Name(root)), false) = (p.steps.first(), p.partial) else {
            return false;
        };
        let (Some(ast::PathStep::Name(leaf)), [_, middle @ .., _]) = (p.steps.last(), p.steps.as_slice()) else {
            return false;
        };
        let Ok(root_td) = self.resolve_path_root(root) else {
            return false;
        };
        let owner = if middle.is_empty() {
            Some(root_td)
        } else {
            self.walk_path_types(root_td, middle, MAX_COMPUTED_SPLICES).1
        };
        owner.is_some_and(|td| Self::resolve_property(td, leaf).is_some())
    }

    /// `a.id union b.id` — each operand compiled as the select it stands
    /// for, the rows of all of them concatenated.
    fn compile_scalar_union(&mut self, expr: &Expr) -> Result<IrStmt, PyQLError> {
        fn operands<'e>(expr: &'e Expr, out: &mut Vec<&'e Expr>) {
            match expr {
                Expr::Union(a, b) => {
                    operands(a, out);
                    operands(b, out);
                }
                other => out.push(other),
            }
        }
        let mut exprs = vec![];
        operands(expr, &mut exprs);
        let mut branches = Vec::with_capacity(exprs.len());
        for operand in exprs {
            let stmt = match operand {
                Expr::SubQuery(stmt) => stmt.as_ref().clone(),
                other => Stmt::Select(ast::SelectStmt {
                    result: other.clone(),
                    filter: None,
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                }),
            };
            branches.push(self.compile_stmt(&stmt)?);
        }
        let types: Vec<String> = branches.iter().map(cte_stmt_type).collect();
        let first = types.iter().find(|t| !t.is_empty()).cloned().unwrap_or_default();
        if let Some(other) = types
            .iter()
            .find(|t| t.contains("::") || (!t.is_empty() && **t != first))
        {
            let display = |t: &str| {
                if t.contains("::") {
                    t.to_string()
                } else {
                    pg_type_to_pyql(t).to_string()
                }
            };
            return Err(self.type_err(&format!(
                "operator 'UNION' cannot be applied to operands of type '{}' and '{}'",
                display(&first),
                display(other)
            )));
        }
        Ok(IrStmt::ScalarUnion(branches))
    }

    /// Extract the target type name from a DML or inner SELECT statement.
    fn dml_subject_type(&self, stmt: &Stmt) -> Result<String, PyQLError> {
        match stmt {
            Stmt::Insert(ins) => Ok(ins.subject.qualified_name()),
            Stmt::Update(upd) => self.subject_type_name(&upd.subject),
            Stmt::Delete(del) => self.subject_type_name(&del.subject),
            Stmt::With(w) => self.dml_subject_type(&w.stmt),
            Stmt::For(f) => self.dml_subject_type(&f.body),
            Stmt::Analyze(inner) => self.dml_subject_type(inner),
            Stmt::Group(g) => self.expr_as_type_name(&g.subject),
            Stmt::Select(sel) => {
                // <Module::Type>expr — type name comes from the cast target
                if let Expr::TypeCast(tc) = &sel.result
                    && let Some((module, name)) = tc.ty.as_named()
                    && module.map(|m| m != "std").unwrap_or(false)
                {
                    return Ok(name.to_string());
                }
                // `select resource.revisions` — a walk names no type of its
                // own; what it lands on is the type the statement yields.
                if let Expr::Path(path) = &sel.result
                    && !path.partial
                    && path.steps.len() > 1
                    && let Some(ast::PathStep::Name(root)) = path.steps.first()
                    && let Ok(root_td) = self.resolve_path_root(root)
                    && let (_, Some(target)) = self.walk_path_types(root_td, &path.steps[1..], MAX_COMPUTED_SPLICES)
                {
                    return Ok(format!("{}::{}", target.module, target.name));
                }
                // SELECT-over-SELECT: get the type from the inner select's result
                let (type_name, _, _, _) = self.extract_type_and_shape(&sel.result)?;
                Ok(type_name)
            }
        }
    }

    /// `id in (…)` over the rows a DML subject path traverses to, so a
    /// mutation written against a traversal touches those rows and no others.
    fn compile_subject_path_rows(&mut self, subject: &ast::Path, target_alias: &str) -> Result<IrExpr, PyQLError> {
        // Traversing to `.id` rather than stopping at the objects: a path that
        // ends on a link or a type intersection has nothing to project, and the
        // ids are what the narrowing compares against anyway.
        let mut steps = subject.steps.clone();
        steps.push(ast::PathStep::Name("id".to_string()));
        let ids = ast::Path { steps, partial: false };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(ids.clone()),
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            lock: None,
        };
        let rows = self.compile_path_select(&synthetic, &ids, &[], false)?;
        Ok(IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: target_alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::In,
            right: IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(rows)))),
        })))
    }

    /// The type a DML subject names, however it is written: a type, a `with`
    /// binding, or a traversal that ends on one.
    fn subject_type_name(&self, subject: &Expr) -> Result<String, PyQLError> {
        if let Expr::Path(p) = subject
            && p.steps.len() > 1
            && let Some(ast::PathStep::Name(root)) = p.steps.first()
            && let Ok(root_td) = self.resolve_path_root(root)
            && let (_, Some(target)) = self.walk_path_types(root_td, &p.steps[1..], MAX_COMPUTED_SPLICES)
        {
            return Ok(format!("{}::{}", target.module, target.name));
        }
        // A subject that is just a `with` binding names rows, not a type, so
        // the type is the one the binding was bound to. `compile_update`
        // wants the binding's own name (it narrows the update to those rows);
        // a reader asking what type the statement yields wants this.
        if let Expr::Path(p) = subject
            && !p.partial
            && let [ast::PathStep::Name(root)] = p.steps.as_slice()
            && let Some(bound) = self.cte_object_type(root)
        {
            return Ok(bound);
        }
        self.expr_as_type_name(subject)
    }

    fn expr_as_type_name(&self, expr: &Expr) -> Result<String, PyQLError> {
        if std::env::var("PYLON_DBG_SUBJ").is_ok() {
            eprintln!(
                "DBG subj {:.90?}
{}",
                expr,
                std::backtrace::Backtrace::force_capture()
            );
        }
        match expr {
            // `detached T` names the same type; the prefix only says the set
            // is not correlated with the enclosing one.
            Expr::Detached(inner) => self.expr_as_type_name(inner),
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    return Ok(n.clone());
                }
                Err(self.type_err("expected a type name"))
            }
            // `select (a union b)` as a SELECT-over-SELECT subject: every
            // branch carries the same object type, and that is the subject.
            Expr::Union(_, _) => {
                let branches = self
                    .object_union_branches(expr)
                    .ok_or_else(|| self.type_err("expected a type name as SELECT subject"))?;
                self.common_union_type(&branches)
                    .ok_or_else(|| self.type_err("expected a type name as SELECT subject"))
            }
            // `placed.line_items` — a walk names no type of its own; the type
            // meant is the one it lands on, which is how `dml_subject_type`
            // already reads the same path.
            Expr::Path(p)
                if !p.partial
                    && p.steps.len() > 1
                    && let Some(ast::PathStep::Name(root)) = p.steps.first()
                    && let Ok(root_td) = self.resolve_path_root(root)
                    && let (_, Some(target)) = self.walk_path_types(root_td, &p.steps[1..], MAX_COMPUTED_SPLICES) =>
            {
                Ok(format!("{}::{}", target.module, target.name))
            }
            _ => Err(self.type_err("expected a type name as SELECT subject")),
        }
    }

    // ── INSERT ────────────────────────────────────────────────────────────────────

    fn compile_insert(&mut self, ins: &ast::InsertStmt) -> Result<IrInsert, PyQLError> {
        // Taken before anything nested is compiled, so a nested statement
        // cannot pick up a guard meant for this one — `compile_update` and
        // `compile_delete` take theirs the same way.
        let pending_guard = self.pending_insert_guard.take();
        // Isolate this insert's own nested-DML discoveries (see
        // `pending_nested_ctes`'s doc comment) from whatever an enclosing
        // compile (e.g. this insert itself being the nested DML inside an
        // *outer* insert's link value) had pending, so each level attaches
        // only its own CTEs to its own `IrInsert`.
        let outer_pending_nested_ctes = std::mem::take(&mut self.pending_nested_ctes);
        let type_name = ins.subject.qualified_name();
        let td = self.resolve_type(&type_name)?;
        if td.abstract_ && td.materialized {
            return Err(self.type_err(&format!(
                "cannot insert into interface type '{}::{}'; insert into a concrete type instead",
                td.module, td.name
            )));
        }
        let alias = self.fresh_alias();
        let target = IrSource {
            poly: None,
            type_name: format!("{}::{}", td.module, td.name),
            table: td.table.clone(),
            alias: alias.clone(),
        };

        // Multi-link shape elements (`tags := ...` / `tags += ...`) populate
        // the junction table once the row exists; everything else goes
        // through the normal scalar/link assignment path.
        let mut shape = ins.shape.clone();
        for link in &td.links {
            let unset = !shape.iter().any(|el| path_leaf(&el.path).is_ok_and(|n| n == link.name));
            for rw in link.rewrites.iter().filter(|rw| rw.on & 1 != 0) {
                if let Some(value) = subject_default_insert(&rw.handler, &link.name)
                    && unset
                {
                    shape.push(ShapeElement {
                        path: ast::Path::relative(&link.name),
                        splat: None,
                        nested: None,
                        compexpr: Some(value),
                        op: ShapeOp::Assign,
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        marker_offset: None,
                    });
                }
            }
        }
        // Pointer defaults the shape leaves out. Every default is applied by
        // expanding it into the insert's own shape;
        // the ones a column DEFAULT can hold are left to it here, so only the
        // rest — a default reading a session global, or selecting the object to
        // link to — is expanded.
        for (pointer, pyql) in inlined_pointer_defaults(td, self.schema) {
            if shape.iter().any(|el| path_leaf(&el.path).is_ok_and(|n| n == pointer)) {
                continue;
            }
            let value = crate::parse::parse_pointer_expr(&pyql)?;
            shape.push(default_shape_element(&pointer, value));
        }
        let mut multi_link_appends = vec![];
        let mut scalar_elements: Vec<ShapeElement> = vec![];
        for el in &shape {
            let pointer_name = match path_leaf(&el.path) {
                Ok(n) => n,
                Err(_) => {
                    scalar_elements.push(el.clone());
                    continue;
                }
            };
            if let Some(ml) = Self::resolve_multilink(td, pointer_name) {
                match el.op {
                    ShapeOp::Remove => {
                        return Err(self.type_err(&format!(
                            "cannot use `-=` for multi-link '{pointer_name}' in an insert; \
                         there is nothing to remove from yet"
                        )));
                    }
                    ShapeOp::Assign | ShapeOp::Append => {
                        if let Some(expr) = &el.compexpr {
                            let (jt, module, src_col, tgt_col, through_td) =
                                self.own_multilink_junction_info(td, ml)?;
                            let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                            multi_link_appends.push(IrMultiLinkMutation {
                                junction_table: jt,
                                module,
                                source_col: src_col,
                                target_col: tgt_col,
                                values,
                                single: false,
                            });
                        }
                    }
                }
            } else if let Some(l) = Self::resolve_link(td, pointer_name).filter(|l| l.is_junction_backed()) {
                // A junction-backed single link is "a multi-link capped to
                // one row" (D1) — on insert there's nothing to replace yet,
                // so `:=` populates the junction table the same way a
                // multi-link's own `:=`/`+=` does above.
                if matches!(el.op, ShapeOp::Remove) {
                    return Err(self.type_err(&format!(
                        "cannot use `-=` for link '{pointer_name}' in an insert; \
                         there is nothing to remove from yet"
                    )));
                }
                if let Some(expr) = &el.compexpr {
                    // `:= {}` / `:= <Type>{}` at insert time — same as
                    // omitting the pointer entirely: nothing to append, no
                    // junction row created yet.
                    if !is_empty_set_expr(expr) {
                        let (jt, module, src_col, tgt_col, through_td) = self.own_link_junction_info(td, l)?;
                        let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                        multi_link_appends.push(IrMultiLinkMutation {
                            junction_table: jt,
                            module,
                            source_col: src_col,
                            target_col: tgt_col,
                            values,
                            single: true,
                        });
                    }
                }
            } else {
                scalar_elements.push(el.clone());
            }
        }

        let assignments = self.compile_assignments(&scalar_elements, td, &alias)?;
        // Rewrites apply in the table's own `BEFORE` trigger — see
        // `export::rewrite_trigger_infos`.
        let rewrites = vec![];
        let unless_conflict = match ins.unless_conflict.as_ref() {
            Some(uc) => {
                let (conflict, else_appends) = self.compile_conflict(uc, td)?;
                multi_link_appends.extend(else_appends);
                Some(conflict)
            }
            None => None,
        };
        let returning = Self::pk_returning(td);
        let type_name = format!("{}::{}", td.module, td.name);
        let enqueue_vector = td
            .vector_indexes
            .iter()
            .map(|vi| VectorEnqueueInfo {
                type_name: type_name.clone(),
                index_name: vi.index_name.clone(),
            })
            .collect();
        let enqueue_search = collect_search_enqueue(td, &type_name, "index");
        let mut nested_ctes = std::mem::replace(&mut self.pending_nested_ctes, outer_pending_nested_ctes);

        let guard = match pending_guard {
            Some(condition) => Some(self.compile_expr(&condition, td, &alias)?),
            None => None,
        };
        // A nested insert exists only to fill this row's values, so it writes
        // when this one does and not otherwise. Without the condition it would
        // leave a row behind with nothing pointing at it. Applied to any
        // depth: a line item's own attributes are two loops down.
        if let Some(condition) = &guard {
            fn cte_refs(appends: &[IrMultiLinkMutation], into: &mut Vec<String>) {
                into.extend(appends.iter().filter_map(|append| match &append.values.source {
                    IrMultiLinkValueSource::CteRef(name) => Some(name.clone()),
                    _ => None,
                }));
            }
            fn carry_guard(stmt: &mut IrStmt, condition: &IrExpr, pending: &mut Vec<String>) {
                // A loop's own bindings can mutate too — a line item's
                // attributes are bound inside the loop that writes the line.
                if let IrStmt::For(loop_) = stmt {
                    for def in &mut loop_.body_ctes {
                        carry_guard(&mut def.stmt, condition, pending);
                    }
                }
                let nested = match stmt {
                    IrStmt::Insert(nested) => Some(nested),
                    IrStmt::For(loop_) => match loop_.body.as_mut() {
                        IrStmt::Insert(nested) => Some(nested),
                        _ => None,
                    },
                    _ => None,
                };
                let Some(nested) = nested else { return };
                if nested.guard.is_none() {
                    nested.guard = Some(condition.clone());
                }
                cte_refs(&nested.multi_link_appends, pending);
                for def in &mut nested.nested_ctes {
                    carry_guard(&mut def.stmt, condition, pending);
                }
            }
            // A multi-link's rows are hoisted beside this statement rather than
            // into its own nested CTEs, so they are reached by name instead.
            let mut pending: Vec<String> = vec![];
            cte_refs(&multi_link_appends, &mut pending);
            for def in &mut nested_ctes {
                carry_guard(&mut def.stmt, condition, &mut pending);
            }
            let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
            while let Some(name) = pending.pop() {
                if !seen.insert(name.clone()) {
                    continue;
                }
                if let Some(index) = self.hoisted_ctes.iter().position(|def| def.name == name) {
                    carry_guard(&mut self.hoisted_ctes[index].stmt, condition, &mut pending);
                }
            }
        }
        // Only a `for` body's nested insert needs to name its own id (see
        // `IrInsert::id_default_sql`); carried here because the schema is in
        // scope, and ignored everywhere else.
        let id_default_sql =
            Self::resolve_property(td, "id").map(|p| p.default_sql.clone().unwrap_or_else(|| "uuidv7()".to_string()));
        Ok(IrInsert {
            guard,
            target,
            assignments,
            unless_conflict,
            rewrites,
            id_default_sql,
            returning,
            enqueue_vector,
            enqueue_search,
            multi_link_appends,
            nested_ctes,
        })
    }

    fn compile_assignments(
        &mut self,
        elements: &[ShapeElement],
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<Vec<(String, IrExpr)>, PyQLError> {
        self.compile_assignments_inner(elements, td, alias, false)
    }

    fn compile_assignments_for_update(
        &mut self,
        elements: &[ShapeElement],
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<Vec<(String, IrExpr)>, PyQLError> {
        self.compile_assignments_inner(elements, td, alias, true)
    }

    fn compile_assignments_inner(
        &mut self,
        elements: &[ShapeElement],
        td: &TypeDescriptor,
        alias: &str,
        deny_readonly: bool,
    ) -> Result<Vec<(String, IrExpr)>, PyQLError> {
        // A value assigned in a mutation body is not output, and a link value
        // among them compiles to a one-column correlated subquery — an implicit
        // `id` beside the column it selects would make that subquery illegal.
        self.without_implicit_id(|this| this.compile_assignments_rows(elements, td, alias, deny_readonly))
    }

    fn compile_assignments_rows(
        &mut self,
        elements: &[ShapeElement],
        td: &TypeDescriptor,
        alias: &str,
        deny_readonly: bool,
    ) -> Result<Vec<(String, IrExpr)>, PyQLError> {
        elements
            .iter()
            .map(|el| {
                let pointer_name = path_leaf(&el.path)?;
                let expr = el.compexpr.as_ref().ok_or_else(|| {
                    PyQLError::Type(PyQLTypeError {
                        message: format!("INSERT pointer '{pointer_name}' has no value expression"),
                        position: Position { line: 0, col: 0 },
                    })
                })?;

                // Validate the pointer exists
                let column = if let Some(p) = Self::resolve_property(td, pointer_name) {
                    // A primary-key ("id") property: an UPDATE never allows
                    // reassigning it (deny_readonly is true there, regardless
                    // of the session config); an INSERT only allows an
                    // explicit value when allow_user_specified_id is set.
                    if p.is_pk && (deny_readonly || !self.config.allow_user_specified_id) {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: "cannot assign to property 'id'".to_string(),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                    if deny_readonly && p.is_readonly {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: format!("cannot update property '{pointer_name}': it is declared as read-only"),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                    p.name.clone()
                } else if let Some(l) = Self::resolve_link(td, pointer_name) {
                    if deny_readonly && l.is_readonly {
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: format!("cannot update link '{pointer_name}': it is declared as read-only"),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                    if l.is_junction_backed() {
                        // Reachable only via `UNLESS CONFLICT ... ELSE (UPDATE
                        // ... SET { ... })` — `compile_insert`/`compile_update`'s
                        // own shape-classification loop intercepts a junction-
                        // backed link before it ever reaches this generic
                        // scalar-assignment path; the ELSE clause has no
                        // junction-mutation mechanism of its own to reuse.
                        return Err(PyQLError::Type(PyQLTypeError {
                            message: format!(
                                "'{pointer_name}' is a junction-backed link and cannot be \
                                 assigned inside an UNLESS CONFLICT ELSE clause"
                            ),
                            position: Position { line: 0, col: 0 },
                        }));
                    }
                    // Link assignment via subquery: `company := (SELECT Company FILTER ...)`
                    // Compile as a scalar subquery returning the target pk (the FK uuid).
                    // A one-element set is that element — `credentials := {
                    // (insert Credentials { … }) }` says the same thing as
                    // assigning the insert directly.
                    let fk_col = format!("{}_id", l.name);
                    if let Some(ir_expr) = self.compile_link_key(expr, td, alias)? {
                        return Ok((fk_col, ir_expr));
                    }
                    fk_col
                } else if Self::resolve_multilink(td, pointer_name).is_some() {
                    // Same reach as the junction-backed link above: the
                    // shape-classification loop in `compile_insert` and
                    // `compile_update` takes multi-links first, so one only
                    // arrives here from an `UNLESS CONFLICT ... ELSE` clause,
                    // which has no junction-mutation mechanism to reuse.
                    // Saying the pointer does not exist sends the reader
                    // looking for a typo in a name that is plainly right.
                    return Err(PyQLError::Type(PyQLTypeError {
                        message: format!(
                            "'{pointer_name}' is a multi-link and cannot be mutated inside an \
                             UNLESS CONFLICT ELSE clause"
                        ),
                        position: Position { line: 0, col: 0 },
                    }));
                } else if Self::resolve_multilink(td, pointer_name).is_some() {
                    return Err(self.field_err(pointer_name, &format!("{}::{}", td.module, td.name)));
                } else if self.resolve_computed(td, pointer_name).is_some() {
                    // Reported as "no link or property 'x'. Did you mean 'x'?"
                    // before: the suggester's name list includes computeds,
                    // the resolution above does not, so it handed back the very
                    // name it had just refused.
                    return Err(self.type_err(&format!(
                        "cannot assign to '{pointer_name}': it is a computed pointer on \
                         {}::{}, which has no stored column to write",
                        td.module, td.name
                    )));
                } else {
                    return Err(self.field_err(pointer_name, &format!("{}::{}", td.module, td.name)));
                };

                // `{}` (empty set) in assignment position means NULL.
                let ir_expr = if matches!(expr, Expr::Set(v) if v.is_empty()) {
                    IrExpr::Null
                } else {
                    self.compile_expr(expr, td, alias)?
                };
                Ok((column, ir_expr))
            })
            .collect()
    }

    // ── UPDATE ────────────────────────────────────────────────────────────────────

    fn compile_update(&mut self, upd: &ast::UpdateStmt) -> Result<IrUpdate, PyQLError> {
        // Taken before anything nested is compiled, so a nested statement
        // cannot pick up a guard meant for this one.
        let pending_guard = self.pending_update_guard.take();
        // See `compile_insert`'s identical save/restore of `pending_nested_ctes`.
        let outer_pending_nested_ctes = std::mem::take(&mut self.pending_nested_ctes);
        // `update (select T filter …).link set { … }` — the subject walks off a
        // sub-select rather than off a named root. The select is hoisted into
        // the statement's own WITH and the walk re-rooted at that binding,
        // giving the `with s := (select …) update s.link set { … }` spelling
        // the path branch below already handles.
        if !matches!(&upd.subject, Expr::Path(_)) {
            let (base, fields) = Self::peel_field_access_chain(&upd.subject);
            if let Expr::SubQuery(inner_stmt) = base
                && !fields.is_empty()
                && matches!(inner_stmt.as_ref(), Stmt::Select(_))
            {
                let inner = self.compile_stmt(inner_stmt)?;
                let cte_name = self.fresh_nested_cte_name();
                let type_name = self.register_cte(&cte_name, &inner);
                self.hoisted_ctes.push(IrCteDef {
                    name: cte_name.clone(),
                    stmt: inner,
                    type_name,
                    correlated_to: None,
                });
                let mut steps = vec![ast::PathStep::Name(cte_name)];
                steps.extend(fields.into_iter().map(ast::PathStep::Name));
                let rerooted = ast::UpdateStmt {
                    subject: Expr::Path(ast::Path { steps, partial: false }),
                    filter: upd.filter.clone(),
                    shape: upd.shape.clone(),
                };
                self.pending_nested_ctes = outer_pending_nested_ctes;
                self.pending_update_guard = pending_guard;
                return self.compile_update(&rerooted);
            }
        }
        // `update account.preferences[is IndividualPreferences] set …` — the
        // subject is a traversal rather than a name, so the rows to update are
        // the ones it lands on: the table is the type the walk ends on, and the
        // update is narrowed to the ids the traversal yields.
        if let Expr::Path(subject) = &upd.subject
            && subject.steps.len() > 1
            && let Some(ast::PathStep::Name(root)) = subject.steps.first()
            && let Ok(root_td) = self.resolve_path_root(root)
            && let (_, Some(target_td)) = self.walk_path_types(root_td, &subject.steps[1..], MAX_COMPUTED_SPLICES)
        {
            let narrowed = ast::UpdateStmt {
                subject: Expr::Path(ast::Path {
                    steps: vec![ast::PathStep::Name(format!("{}::{}", target_td.module, target_td.name))],
                    partial: false,
                }),
                filter: upd.filter.clone(),
                shape: upd.shape.clone(),
            };
            self.pending_nested_ctes = outer_pending_nested_ctes;
            self.pending_update_guard = pending_guard;
            let mut ir = self.compile_update(&narrowed)?;
            // Built after the update, so the comparison names that update's own
            // alias: with a nested statement's CTE in the FROM, a bare `id`
            // could mean either relation.
            let rows = self.compile_subject_path_rows(subject, &ir.target.alias)?;
            ir.filter = Some(and_conditions(ir.filter.take(), vec![rows]).expect("row set is present"));
            return Ok(ir);
        }
        let type_name = self.expr_as_type_name(&upd.subject)?;
        // `update account set …` where `account` is a `with` binding: the
        // binding names the rows to update, so it decides the table *and*
        // narrows the update to its own rows. Without the narrowing this would
        // resolve to the type and rewrite every row in the table.
        let bound_rows = self.cte_object_type(&type_name);
        // `for p in … union (update p set …)` — the same for a loop variable,
        // which names the one row this iteration holds. Without it the UPDATE
        // went out with no WHERE at all and rewrote every row of the table.
        let iterated = self
            .for_var_types
            .contains_key(&type_name)
            .then(|| self.for_var_ref(&type_name));
        let td = self.resolve_path_root(&type_name)?;
        let alias = self.fresh_alias();
        let target = IrSource {
            poly: None,
            type_name: format!("{}::{}", td.module, td.name),
            table: td.table.clone(),
            alias: alias.clone(),
        };

        let declared_filter = upd
            .filter
            .as_ref()
            .map(|f| self.as_condition(|c| c.compile_expr(f, td, &alias)))
            .transpose()?;
        let filter = match bound_rows {
            Some(_) => {
                let membership = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::In,
                    right: IrExpr::ArrayFromSelect(Box::new(IrArraySource::Select(IrSelect::schema_bound(
                        IrSource {
                            poly: None,
                            type_name: format!("{}::{}", td.module, td.name),
                            table: format!("@cte:{type_name}"),
                            alias: self.fresh_alias(),
                        },
                        vec![],
                        None,
                    )))),
                }));
                Some(and_conditions(declared_filter, vec![membership]).expect("membership is present"))
            }
            None => declared_filter,
        };
        let filter = match iterated {
            Some(value) => {
                let this_row = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: value,
                }));
                Some(and_conditions(filter, vec![this_row]).expect("the row condition is present"))
            }
            None => filter,
        };
        // `(update cart set { … }) if not exists(existing) else {}` — the
        // condition narrows the rows this update touches. Left to filter what
        // is read back instead, the update would still run.
        let filter = match pending_guard {
            Some(condition) => {
                let guard = self.compile_expr(&condition, td, &alias)?;
                and_conditions(filter, vec![guard])
            }
            None => filter,
        };

        // Classify shape elements by kind.
        let mut multi_link_clears = vec![];
        let mut multi_link_replaces = vec![];
        let mut multi_link_appends = vec![];
        let mut multi_link_removals = vec![];
        let mut scalar_elements: Vec<ShapeElement> = vec![];

        for el in &upd.shape {
            let pointer_name = match path_leaf(&el.path) {
                Ok(n) => n,
                Err(_) => {
                    scalar_elements.push(el.clone());
                    continue;
                }
            };

            if let Some(ml) = Self::resolve_multilink(td, pointer_name) {
                let (jt, module, src_col, tgt_col, through_td) = self.own_multilink_junction_info(td, ml)?;

                match el.op {
                    ShapeOp::Assign => {
                        let is_empty = el
                            .compexpr
                            .as_ref()
                            .map(|e| matches!(e, Expr::Set(v) if v.is_empty()))
                            .unwrap_or(false);
                        if is_empty {
                            // := {} — clear all junction rows
                            multi_link_clears.push(IrMultiLinkClear {
                                junction_table: jt,
                                module,
                                source_col: src_col,
                            });
                        } else if let Some(expr) = &el.compexpr {
                            // := expr — replace (clear + insert)
                            multi_link_clears.push(IrMultiLinkClear {
                                junction_table: jt.clone(),
                                module: module.clone(),
                                source_col: src_col.clone(),
                            });
                            let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                            multi_link_replaces.push(IrMultiLinkMutation {
                                junction_table: jt,
                                module,
                                source_col: src_col,
                                target_col: tgt_col,
                                values,
                                single: false,
                            });
                        }
                    }
                    ShapeOp::Append => {
                        if let Some(expr) = &el.compexpr {
                            let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                            multi_link_appends.push(IrMultiLinkMutation {
                                junction_table: jt,
                                module,
                                source_col: src_col,
                                target_col: tgt_col,
                                values,
                                single: false,
                            });
                        }
                    }
                    ShapeOp::Remove => {
                        if let Some(expr) = &el.compexpr {
                            let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                            if has_any_link_props(&values) {
                                return Err(self.type_err(
                                    "link properties (`@prop := value`) cannot be assigned \
                                     when removing a link (`-=`)",
                                ));
                            }
                            multi_link_removals.push(IrMultiLinkMutation {
                                junction_table: jt,
                                module,
                                source_col: src_col,
                                target_col: tgt_col,
                                values,
                                single: false,
                            });
                        }
                    }
                }
            } else if let Some(l) = Self::resolve_link(td, pointer_name).filter(|l| l.is_junction_backed()) {
                // Same replace-via-clear-then-insert shape a multi-link's
                // own `:=` uses — only `:=` is meaningful for a single
                // link, whether FK-backed or junction-backed.
                if !matches!(el.op, ShapeOp::Assign) {
                    return Err(self.type_err(&format!(
                        "'{pointer_name}' is a single link; only `:=` is supported, not `+=`/`-=`"
                    )));
                }
                let (jt, module, src_col, tgt_col, through_td) = self.own_link_junction_info(td, l)?;
                let is_empty = el.compexpr.as_ref().map(is_empty_set_expr).unwrap_or(false);
                if is_empty {
                    // := {} — clear the junction row
                    multi_link_clears.push(IrMultiLinkClear {
                        junction_table: jt,
                        module,
                        source_col: src_col,
                    });
                } else if let Some(expr) = &el.compexpr {
                    multi_link_clears.push(IrMultiLinkClear {
                        junction_table: jt.clone(),
                        module: module.clone(),
                        source_col: src_col.clone(),
                    });
                    let values = self.compile_multilink_values(expr, td, &alias, through_td)?;
                    multi_link_replaces.push(IrMultiLinkMutation {
                        junction_table: jt,
                        module,
                        source_col: src_col,
                        target_col: tgt_col,
                        values,
                        single: true,
                    });
                }
            } else {
                scalar_elements.push(el.clone());
            }
        }

        let assignments = self.compile_assignments_for_update(&scalar_elements, td, &alias)?;
        // See the insert's own: rewrites apply in the table's `BEFORE` trigger.
        let rewrites = vec![];
        let returning = Self::pk_returning(td);

        let (poly_implementors, poly_columns) = if self.is_polymorphic(td) {
            (
                self.find_poly_implementors(&format!("{}::{}", td.module, td.name)),
                Self::poly_dml_columns(td),
            )
        } else {
            (vec![], vec![])
        };

        // Only enqueue indexes whose source pointers are touched by this update.
        let written_cols: std::collections::HashSet<&str> = assignments.iter().map(|(c, _)| c.as_str()).collect();
        let type_name = format!("{}::{}", td.module, td.name);
        let enqueue_vector: Vec<VectorEnqueueInfo> = td
            .vector_indexes
            .iter()
            .filter(|vi| vi.pointers.iter().any(|f| written_cols.contains(f.as_str())))
            .map(|vi| VectorEnqueueInfo {
                type_name: type_name.clone(),
                index_name: vi.index_name.clone(),
            })
            .collect();
        let enqueue_search = collect_search_enqueue(td, &type_name, "index");
        // Nested-DML CTEs (see IrUpdate::nested_ctes) compose with every
        // other UPDATE shape — multi-link mutation, interface-type fan-out,
        // and vector/search enqueue each have their own emitter branch
        // (emit_update_stmt / emit_poly_update_stmt) that now prepends
        // these CTEs and adds the FROM clause a hoisted CTE reference needs.
        let nested_ctes = std::mem::replace(&mut self.pending_nested_ctes, outer_pending_nested_ctes);

        Ok(IrUpdate {
            target,
            filter,
            assignments,
            rewrites,
            returning,
            multi_link_clears,
            multi_link_replaces,
            multi_link_appends,
            multi_link_removals,
            poly_implementors,
            poly_columns,
            enqueue_vector,
            enqueue_search,
            nested_ctes,
        })
    }

    /// Extract junction table info for a multi-link (or a junction-backed
    /// single link, which shares this exact storage shape — D2):
    /// (junction_table, module, source_col, target_col, through_td).
    /// `through_td` is the junction type's own TypeDescriptor for a
    /// `Through[...]` link (needed to validate/compile `@prop := expr`
    /// link-property assignments against its real properties) — `None` for
    /// a Standard (implicit) junction table, which has no user-declared
    /// properties at all.
    fn junction_info_for(
        &mut self,
        td: &TypeDescriptor,
        name: &str,
        target: &str,
        through: &Option<String>,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        let (junction_table, module, source_col, target_col, through_td) =
            self.own_junction_info_for(td, name, target, through)?;
        let owner_derived = through_td.is_none_or(|through_td| through_td.junction);
        let junction_table = if owner_derived {
            self.owner_junction(td, name, through_td)
        } else {
            junction_table
        };
        Ok((junction_table, module, source_col, target_col, through_td))
    }

    /// Every junction table a read of `td`'s multi-links can name, quoted as
    /// the emitter spells it. A `through` type brings its own table; an
    /// owner-derived junction is named after the owner, and a subtype's
    /// carries that subtype's table, so each implementor contributes one.
    fn junction_tables_of(&mut self, td: &TypeDescriptor) -> Result<Vec<String>, PyQLError> {
        let mut tables = vec![];
        for multilink in &td.multilinks {
            match &multilink.through {
                Some(through) => {
                    let through_td = self.resolve_type(through)?;
                    tables.push(format!("\"{}\"", through_td.table));
                }
                None => {
                    tables.push(format!("\"{}.{}\"", td.table, multilink.name));
                    for implementor in self.find_poly_implementors(&format!("{}::{}", td.module, td.name)) {
                        tables.push(format!("\"{}.{}\"", implementor.table, multilink.name));
                    }
                }
            }
        }
        Ok(tables)
    }

    /// The junction a read of `td`'s multi-link `name` goes through: its own
    /// table, or, when `td` has subtypes, the union of theirs beside it.
    fn owner_junction(&self, td: &TypeDescriptor, name: &str, through_td: Option<&TypeDescriptor>) -> String {
        let own = format!("{}.{}", td.table, name);
        if !self.has_subtypes(td) {
            return own;
        }
        let tables = self
            .find_poly_implementors(&format!("{}::{}", td.module, td.name))
            .into_iter()
            .map(|implementor| (implementor.module, format!("{}.{}", implementor.table, name)))
            .collect::<Vec<_>>();
        let mut columns = vec!["source".to_string(), "target".to_string()];
        if let Some(through_td) = through_td {
            columns.extend(Self::poly_dml_columns(through_td).into_iter().filter(|c| c != "id"));
        }
        super::inherited_junction(&tables, &columns)
    }

    /// `junction_info_for` naming the owner's own junction table, which is
    /// the one a write to that owner's rows goes to.
    fn own_junction_info_for(
        &mut self,
        td: &TypeDescriptor,
        name: &str,
        target: &str,
        through: &Option<String>,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        match through {
            None => Ok((
                format!("{}.{}", td.table, name),
                td.module.clone(),
                "source".to_string(),
                "target".to_string(),
                None,
            )),
            Some(through_qname) => {
                let through_td = self.resolve_type(through_qname)?;
                let src_type = format!("{}::{}", td.module, td.name);
                let source_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == src_type)
                    .map(|l| l.name.clone())
                    .unwrap_or_else(|| "source".to_string());
                // A self-referencing through-link (source type == target
                // type, e.g. Person.friends via a PersonFriend with two
                // Person-typed links) would otherwise match the same link
                // for both sides — prefer a differently-named one first,
                // matching the tie-break already used for the read-side
                // join resolution elsewhere in this file.
                let target_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == target && l.name != source_col)
                    .or_else(|| through_td.links.iter().find(|l| l.target == target))
                    .map(|l| l.name.clone())
                    .unwrap_or_else(|| "target".to_string());
                // A dedicated `@pylon.junction` type has no physical table
                // of its own — `emit_one_junction_table` always names it
                // `"{owner.table}.{name}"`, one per *owner* (so that e.g.
                // an interface-inherited junction-backed link gets one
                // physically separate table per concrete implementor,
                // never a single table shared — and thus impossibly
                // FK'd — across several). `through_td.table` only holds
                // the right name here by accident, for the common case of
                // exactly one owner ever referencing that junction type
                // (the Python walker pre-renames it for that one owner).
                // A non-junction "through" type, in contrast, *is* a real,
                // independently-queryable object with its own genuine
                // table — `through_td.table` is correct for that case and
                // must stay as-is.
                let (junction_table, junction_module) = if through_td.junction {
                    (format!("{}.{}", td.table, name), td.module.clone())
                } else {
                    (through_td.table.clone(), through_td.module.clone())
                };
                Ok((
                    junction_table,
                    junction_module,
                    source_col,
                    target_col,
                    Some(through_td),
                ))
            }
        }
    }

    fn multilink_junction_info(
        &mut self,
        td: &TypeDescriptor,
        ml: &MultiLinkDescriptor,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        self.junction_info_for(td, &ml.name, &ml.target, &ml.through)
    }

    fn own_multilink_junction_info(
        &mut self,
        td: &TypeDescriptor,
        ml: &MultiLinkDescriptor,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        self.own_junction_info_for(td, &ml.name, &ml.target, &ml.through)
    }

    fn own_link_junction_info(
        &mut self,
        td: &TypeDescriptor,
        l: &LinkDescriptor,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        self.own_junction_info_for(td, &l.name, &l.target, &l.through)
    }

    /// Same as `multilink_junction_info`, for a junction-backed single link.
    fn link_junction_info(
        &mut self,
        td: &TypeDescriptor,
        l: &LinkDescriptor,
    ) -> Result<(String, String, String, String, Option<&'a TypeDescriptor>), PyQLError> {
        self.junction_info_for(td, &l.name, &l.target, &l.through)
    }

    /// Build the `IrMultiLinkJoin` a multi-link or junction-backed single
    /// link's forward read-side join uses (`IrPathJoin::Multi`, a shape's
    /// `IrMultiLinkPointer`, or — for a junction-backed single link — the
    /// junction variant of `IrSingleLinkCorrelation`).
    fn build_multilink_join(
        &mut self,
        td: &TypeDescriptor,
        name: &str,
        target: &str,
        through: &Option<String>,
    ) -> Result<IrMultiLinkJoin, PyQLError> {
        if let Some(through_qname) = through {
            let through_td = self.resolve_type(through_qname)?;
            if through_td.junction {
                // See `junction_info_for`'s doc comment: a dedicated
                // junction type's physical table is always owner-derived
                // (one per concrete implementor), never `through_td.table`
                // itself.
                Ok(IrMultiLinkJoin::Standard {
                    junction_table: self.owner_junction(td, name, Some(through_td)),
                    module: td.module.clone(),
                })
            } else {
                let source_qname = format!("{}::{}", td.module, td.name);
                let source_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == source_qname)
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to {source_qname}"),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                let target_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == target && l.name != source_col)
                    .or_else(|| through_td.links.iter().find(|l| l.target == target))
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to target {target}"),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                Ok(IrMultiLinkJoin::Through {
                    junction_table: through_td.table.clone(),
                    module: through_td.module.clone(),
                    source_col,
                    target_col,
                })
            }
        } else {
            let junction_table = self.owner_junction(td, name, None);
            Ok(IrMultiLinkJoin::Standard {
                junction_table: match self.junction_read_overrides.get(&junction_table) {
                    Some(o) => o.junction.clone(),
                    None => junction_table,
                },
                module: td.module.clone(),
            })
        }
    }

    /// Compile the RHS of a multilink `+=`, `-=`, or `:= expr` into an
    /// `IrMultiLinkValues`. `td`/`alias` are the record being updated (link-
    /// property value expressions like `@weight := <float64>$w` compile
    /// against this scope, same as any other UPDATE SET assignment — they
    /// cannot reference the linked target's own properties, only the outer
    /// record's or bound params/literals). `through_td` is the junction
    /// type's own TypeDescriptor for a `Through[...]` multi-link, or `None`
    /// for a Standard junction (which has no properties to assign).
    fn compile_multilink_values(
        &mut self,
        expr: &Expr,
        td: &'a TypeDescriptor,
        alias: &str,
        through_td: Option<&'a TypeDescriptor>,
    ) -> Result<IrMultiLinkValues, PyQLError> {
        // Same reason as `compile_assignments_inner`: these rows are the
        // junction's target ids, not output, and each value is read as one
        // column.
        self.without_implicit_id(|this| this.compile_multilink_values_inner(expr, td, alias, through_td))
    }

    fn compile_multilink_values_inner(
        &mut self,
        expr: &Expr,
        td: &'a TypeDescriptor,
        alias: &str,
        through_td: Option<&'a TypeDescriptor>,
    ) -> Result<IrMultiLinkValues, PyQLError> {
        // `a union b` — combine both sides; each keeps its own link_props
        // (different targets in one `+=` can carry different property values).
        if let Expr::Union(a, b) = expr {
            let left = self.compile_multilink_values(a, td, alias, through_td)?;
            let right = self.compile_multilink_values(b, td, alias, through_td)?;
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::Union(Box::new(left), Box::new(right)),
                link_props: vec![],
            });
        }

        // `emails := (insert …) if exists($email) else {}` — the same choice
        // between two sets the select path reads, and the same rewrite: the
        // insert carries the condition itself, since Postgres runs a
        // data-modifying CTE whether or not anything reads it.
        if matches!(expr, Expr::IfElse(_))
            && let Some(rewritten) = self.object_if_else_as_union(expr)
        {
            return self.compile_multilink_values(&rewritten, td, alias, through_td);
        }

        // `notifications += (select .notifications { @read_at := … } filter …)`
        // — the link properties sit *inside* the select. Lifted out, the shape
        // branch below assigns them and the bare select goes down the
        // relative-path branch, which is what each already knows how to do.
        if let Expr::SubQuery(inner) = expr
            && let Stmt::Select(sel) = inner.as_ref()
            && let Expr::Shape(sh) = &sel.result
            && !sh.elements.is_empty()
            && sh
                .elements
                .iter()
                .all(|el| matches!(el.path.steps.as_slice(), [ast::PathStep::LinkProp(_)]))
            && let Some(base) = sh.expr.clone()
        {
            let lifted = Expr::Shape(Box::new(ast::ShapeExpr {
                expr: Some(Expr::SubQuery(Box::new(Stmt::Select(ast::SelectStmt {
                    result: base,
                    ..sel.clone()
                })))),
                elements: sh.elements.clone(),
                marker_offset: sh.marker_offset,
            }));
            return self.compile_multilink_values(&lifted, td, alias, through_td);
        }

        // `expr { @prop := value, ... }` — link-property assignments layered
        // onto an inner target-selecting expression.
        if let Expr::Shape(shape) = expr {
            let inner_expr = shape
                .expr
                .as_ref()
                .ok_or_else(|| self.type_err("multilink value shape must have a base expression"))?;
            let mut inner = self.compile_multilink_values(inner_expr, td, alias, through_td)?;
            // `(select .notifications { @read_at := … @read_at })` — over a
            // walk of a link with properties, `@prop` reads the row's current
            // value off the junction that walk crosses.
            let walked_junction = match (&inner.source, inner_expr) {
                (IrMultiLinkValueSource::PathSelect(ps), Expr::SubQuery(stmt)) => {
                    match (stmt.as_ref(), ps.joins.last()) {
                        (Stmt::Select(sel), Some(IrPathJoin::Multi { junction_alias, .. })) => match &sel.result {
                            Expr::Path(p) if p.partial => match p.steps.as_slice() {
                                [ast::PathStep::Name(link)] => Self::resolve_multilink(td, link)
                                    .and_then(|m| m.through.clone())
                                    .map(|through| (through, junction_alias.clone())),
                                _ => None,
                            },
                            _ => None,
                        },
                        _ => None,
                    }
                }
                _ => None,
            };

            let Some(through) = through_td else {
                return Err(self.type_err(
                    "link properties (`@prop := value`) are only valid on a multi-link \
                     declared with `Through[...]`",
                ));
            };

            for el in &shape.elements {
                let prop_name = match el.path.steps.as_slice() {
                    [ast::PathStep::LinkProp(name)] => name.clone(),
                    _ => return Err(self.type_err("only `@prop := value` link-property assignments are valid here")),
                };
                let prop = Self::resolve_property(through, &prop_name)
                    .ok_or_else(|| self.field_err(&prop_name, &format!("{}::{}", through.module, through.name)))?;
                if prop.is_readonly {
                    return Err(self.type_err(&format!(
                        "cannot set link property '{prop_name}': it is declared as read-only"
                    )));
                }
                let value_expr = el
                    .compexpr
                    .as_ref()
                    .ok_or_else(|| self.type_err(&format!("link property '{prop_name}' must be assigned a value")))?;
                let scoped = walked_junction.is_some();
                if scoped {
                    self.link_prop_scope.push(walked_junction.clone());
                }
                let ir_expr = self.compile_expr(value_expr, td, alias);
                if scoped {
                    self.link_prop_scope.pop();
                }
                inner.link_props.push((prop.name.clone(), ir_expr?));
            }
            return Ok(inner);
        }

        // `prices := assert_distinct(<union>)` — the assert checks the targets
        // before they become junction rows, and passes them through otherwise.
        if let Expr::FunctionCall(f) = expr
            && (f.module.is_none() || f.module.as_deref() == Some("std"))
            && matches!(f.name.as_str(), "assert_exists" | "assert_distinct")
            && let [arg] = f.args.as_slice()
        {
            let arg = arg.clone();
            let inner = self.compile_multilink_values(&arg, td, alias, through_td)?;
            // The ids travel through the check as a plain array and come back
            // unnested, which leaves no row for a per-target link property to
            // ride along on.
            let mut props = vec![];
            crate::sql::collect_link_prop_names(&inner, &mut props);
            if !props.is_empty() {
                return Err(self.type_err(&format!(
                    "'{}' cannot be applied to a link that carries link properties ({}) —                      the check reads the targets alone",
                    f.name,
                    props.join(", "),
                )));
            }
            let message = self.assert_message(f, Some((td, alias)))?;
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::Asserted {
                    fn_name: f.name.clone(),
                    inner: Box::new(inner),
                    message,
                },
                link_props: vec![],
            });
        }

        // `translations := (select { teaser, title })` — a select with no
        // clauses of its own is the expression it wraps, and the forms below
        // already know what to do with that. Left wrapped, a free row source
        // (a set literal, a union) reaches the generic subquery arm and is
        // refused, while the identical unwrapped `{ teaser, title }` compiles.
        if let Expr::SubQuery(inner) = expr
            && let Stmt::Select(sel) = inner.as_ref()
            && sel.filter.is_none()
            && sel.order_by.is_empty()
            && sel.offset.is_none()
            && sel.limit.is_none()
            && matches!(sel.result, Expr::Set(_) | Expr::Union(_, _))
        {
            let result = sel.result.clone();
            return self.compile_multilink_values(&result, td, alias, through_td);
        }

        // CTE reference: bare name matching a registered CTE
        if let Some(name) = self.resolve_cte_name(expr) {
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::CteRef(name.to_string()),
                link_props: vec![],
            });
        }

        // `{ a, b }` — a set literal of targets, each contributing its own rows.
        if let Expr::Set(elements) = expr
            && !elements.is_empty()
        {
            let mut combined: Option<IrMultiLinkValues> = None;
            for element in elements {
                let one = self.compile_multilink_values(element, td, alias, through_td)?;
                combined = Some(match combined {
                    None => one,
                    Some(previous) => IrMultiLinkValues {
                        source: IrMultiLinkValueSource::Union(Box::new(previous), Box::new(one)),
                        link_props: vec![],
                    },
                });
            }
            return Ok(combined.expect("elements is non-empty"));
        }

        // `social_accounts := (for p in … union (insert …))` — the loop's rows
        // are the link's targets, read back from the CTE it is hoisted into,
        // the same way a bare nested insert is.
        if let Expr::SubQuery(inner) = expr
            && let Stmt::For(_) = inner.as_ref()
        {
            let (cte_name, _) = self.hoist_dml_as_cte(inner.as_ref())?;
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::CteRef(cte_name),
                link_props: vec![],
            });
        }

        // `emails := (insert Email { … })` — a nested insert whose rows become
        // the link's targets, read back from the CTE it is hoisted into.
        if let Expr::SubQuery(inner) = expr
            && matches!(inner.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_))
        {
            let cte_name = self.hoist_nested_dml(inner)?;
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::CteRef(cte_name),
                link_props: vec![],
            });
        }

        // `emails := (select .emails filter .primary)` — a relative path here
        // is relative to the row being written, so it is rooted at that type
        // and correlated back to it; compiled bare it has no object to
        // resolve against and reads as a free select.
        if let Expr::SubQuery(inner) = expr
            && let Stmt::Select(sel) = inner.as_ref()
            && let Expr::Path(path) = &sel.result
            && path.partial
        {
            let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
            steps.extend(path.steps.iter().cloned());
            let rooted = ast::Path { steps, partial: false };
            let synthetic = ast::SelectStmt {
                result: Expr::Path(rooted.clone()),
                filter: sel.filter.clone(),
                order_by: sel.order_by.clone(),
                offset: sel.offset.clone(),
                limit: sel.limit.clone(),
                lock: None,
            };
            let mut ps = self.compile_path_select(&synthetic, &rooted, &[], false)?;
            Self::correlate_path_select(&mut ps, alias);
            return Ok(IrMultiLinkValues {
                source: IrMultiLinkValueSource::PathSelect(Box::new(ps)),
                link_props: vec![],
            });
        }

        // Parenthesised subquery
        if let Expr::SubQuery(inner) = expr {
            return match self.compile_stmt(inner)? {
                IrStmt::Select(s) if matches!(s.rows.as_slice(), [IrRowSource::Bound { .. }]) => {
                    Ok(IrMultiLinkValues {
                        source: IrMultiLinkValueSource::Select(Box::new(s)),
                        link_props: vec![],
                    })
                }
                IrStmt::PathSelect(ps) => Ok(IrMultiLinkValues {
                    source: IrMultiLinkValueSource::PathSelect(Box::new(ps)),
                    link_props: vec![],
                }),
                _ => Err(self.type_err("multilink value must resolve to a SELECT or path query")),
            };
        }

        if let Expr::FunctionCall(fc) = expr {
            let synthetic = ast::SelectStmt {
                result: expr.clone(),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            if let Some(fs) = self.try_compile_fn_object_select(fc, &[], &synthetic, false)? {
                return Ok(IrMultiLinkValues {
                    source: IrMultiLinkValueSource::Function(Box::new(fs)),
                    link_props: vec![],
                });
            }
        }

        // Absolute path expression (type reference or path traversal)
        if let Expr::Path(p) = expr
            && !p.partial
        {
            let fake_sel = ast::SelectStmt {
                result: expr.clone(),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            return match self.compile_stmt(&Stmt::Select(fake_sel))? {
                IrStmt::PathSelect(ps) => Ok(IrMultiLinkValues {
                    source: IrMultiLinkValueSource::PathSelect(Box::new(ps)),
                    link_props: vec![],
                }),
                IrStmt::Select(s) if matches!(s.rows.as_slice(), [IrRowSource::Bound { .. }]) => {
                    Ok(IrMultiLinkValues {
                        source: IrMultiLinkValueSource::Select(Box::new(s)),
                        link_props: vec![],
                    })
                }
                _ => Err(self.type_err("expected a path expression for multilink value")),
            };
        }

        Err(self.type_err("multilink value must be a CTE reference, parenthesised subquery, or type path"))
    }

    // ── DELETE ────────────────────────────────────────────────────────────────────

    fn compile_delete(&mut self, del: &ast::DeleteStmt) -> Result<IrDelete, PyQLError> {
        // Taken before anything nested is compiled, so a nested statement
        // cannot pick up a guard meant for this one.
        let pending_guard = self.pending_delete_guard.take();
        let type_name = self.expr_as_type_name(&del.subject)?;
        // `delete previous` where `previous` is a `with` binding: the binding
        // names the rows to delete, so it decides the table *and* narrows the
        // delete to its own rows — exactly as `compile_update` does. Without
        // the narrowing this would resolve to the type and empty the table.
        let bound_rows = self.cte_object_type(&type_name);
        let td = self.resolve_path_root(&type_name)?;
        let alias = self.fresh_alias();
        let target = IrSource {
            poly: None,
            type_name: format!("{}::{}", td.module, td.name),
            table: td.table.clone(),
            alias: alias.clone(),
        };

        let declared_filter = del
            .filter
            .as_ref()
            .map(|f| self.as_condition(|c| c.compile_expr(f, td, &alias)))
            .transpose()?;
        let filter = match bound_rows {
            Some(_) => {
                let membership = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::In,
                    right: IrExpr::ArrayFromSelect(Box::new(IrArraySource::Select(IrSelect::schema_bound(
                        IrSource {
                            poly: None,
                            type_name: format!("{}::{}", td.module, td.name),
                            table: format!("@cte:{type_name}"),
                            alias: self.fresh_alias(),
                        },
                        vec![],
                        None,
                    )))),
                }));
                Some(and_conditions(declared_filter, vec![membership]).expect("membership is present"))
            }
            None => declared_filter,
        };
        let filter = match pending_guard {
            Some(condition) => {
                let guard = self.compile_expr(&condition, td, &alias)?;
                and_conditions(filter, vec![guard])
            }
            None => filter,
        };

        let returning = Self::pk_returning(td);

        let (poly_implementors, poly_columns) = if self.is_polymorphic(td) {
            (
                self.find_poly_implementors(&format!("{}::{}", td.module, td.name)),
                Self::poly_dml_columns(td),
            )
        } else {
            (vec![], vec![])
        };
        let qname = format!("{}::{}", td.module, td.name);
        let enqueue_search = collect_search_enqueue(td, &qname, "delete");

        Ok(IrDelete {
            target,
            filter,
            returning,
            poly_implementors,
            poly_columns,
            enqueue_search,
        })
    }

    // ── Shape compilation ─────────────────────────────────────────────────────────

    fn compile_shape(
        &mut self,
        elements: &[ShapeElement],
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
    ) -> Result<Vec<IrShapePointer>, PyQLError> {
        if elements.is_empty() {
            // No explicit shape: implicit { id } only.
            return Ok(Self::pk_returning(td));
        }

        let mut pointers = vec![];
        for el in elements {
            if let Some(splat) = &el.splat {
                // Check if this is a type-intersection splat: [is Type].*
                if let Some(ast::PathStep::TypeIntersection(type_ref)) = el.path.steps.first() {
                    let type_ref = type_ref.clone();
                    pointers.extend(self.compile_type_intersection_splat(&type_ref, splat, td, alias)?);
                } else {
                    pointers.extend(self.compile_splat(splat, td, alias, module)?);
                }
            } else {
                pointers.push(self.compile_shape_element(el, td, alias, module)?);
            }
        }
        self.prepend_implicit_id(&mut pointers, td);
        Ok(pointers)
    }

    /// Put `id` at the front of a shape that did not select one, which every
    /// binary-protocol query carries whether or not it asked. Without it,
    /// `o.id` on a shape like `options: { value }` reads as unset rather than
    /// as the row's id.
    ///
    /// Skipped in the two places that cannot carry it: inside a mutation's own body and under
    /// a cast to `json` — see `implicit_id_in_shapes`. A shape that names `id`
    /// itself keeps its own pointer, and its position, untouched.
    fn prepend_implicit_id(&self, pointers: &mut Vec<IrShapePointer>, td: &TypeDescriptor) {
        if !self.implicit_id_in_shapes {
            return;
        }
        let Some(pk) = td.properties.iter().find(|p| p.is_pk) else {
            return;
        };
        if pointers.iter().any(|p| p.alias() == pk.name) {
            return;
        }
        pointers.insert(
            0,
            IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: true,
                marker_offset: None,
                alias: pk.name.clone(),
                column: pk.name.clone(),
                pg_type: pk.pg_type.clone(),
                tuple_shape: None,
            }),
        );
    }

    /// Run `body` with implicit ids suppressed, restoring the previous setting
    /// however it ends.
    fn without_implicit_id<T>(&mut self, body: impl FnOnce(&mut Self) -> Result<T, PyQLError>) -> Result<T, PyQLError> {
        let saved = std::mem::replace(&mut self.implicit_id_in_shapes, false);
        let result = body(self);
        self.implicit_id_in_shapes = saved;
        result
    }

    /// Expand `*` → all scalars; `**` → all scalars + all single links with implicit `{ id }`.
    fn compile_splat(
        &mut self,
        splat: &ast::Splat,
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
    ) -> Result<Vec<IrShapePointer>, PyQLError> {
        let mut pointers: Vec<IrShapePointer> = td
            .properties
            .iter()
            .map(|p| {
                IrShapePointer::Scalar(IrScalarPointer {
                    implicit_id: false,
                    marker_offset: None,
                    alias: p.name.clone(),
                    column: p.name.clone(),
                    pg_type: p.pg_type.clone(),
                    tuple_shape: self.resolve_property_tuple_shape(p),
                })
            })
            .collect();

        for cd in &td.computed.clone() {
            // `*` is properties; links arrive only with `**`. A computed
            // standing for objects is a link however it is written, so it
            // waits for the deep form too.
            if matches!(splat, ast::Splat::Shallow) && self.computed_is_object_valued(cd, td) {
                continue;
            }
            pointers.push(self.compile_declared_computed(cd, td, alias, module, None, &[])?);
        }

        if matches!(splat, ast::Splat::Deep) {
            for l in &td.links {
                let target_td = self.resolve_type(&l.target)?;
                let sub_alias = self.fresh_alias();
                // `**` fetches every property (not further nested links) of
                // a linked object — a `Shallow` (`*`) expansion of the
                // target type, one level deep. Recursing with `Deep` here
                // instead would walk the target's own links too, which for
                // a two-way or cyclic link graph never terminates.
                let target_module = target_td.module.clone();
                let sub_shape = self.compile_splat(&ast::Splat::Shallow, target_td, &sub_alias, &target_module)?;
                let subquery = IrSelect::schema_bound(
                    IrSource {
                        poly: self.link_target_fanout(target_td),
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        table: target_td.table.clone(),
                        alias: sub_alias.clone(),
                    },
                    sub_shape,
                    None,
                );
                let correlation = if l.is_junction_backed() {
                    let join = self.build_multilink_join(td, &l.name, &l.target, &l.through)?;
                    IrSingleLinkCorrelation::Junction {
                        join,
                        target_pk: "id".to_string(),
                    }
                } else {
                    IrSingleLinkCorrelation::Fk {
                        fk_column: format!("{}_id", l.name),
                        target_pk: "id".to_string(),
                    }
                };
                pointers.push(IrShapePointer::SingleLink(IrSingleLinkPointer {
                    marker_offset: None,
                    alias: l.name.clone(),
                    correlation,
                    subquery,
                    link_properties: vec![],
                }));
            }

            for ml in &td.multilinks {
                let sub_alias = self.fresh_alias();
                let target_td = self.resolve_type(&ml.target)?;
                // See the single-link loop above — same Shallow-not-Deep
                // reasoning applies to multilink targets.
                let target_module = target_td.module.clone();
                let sub_shape = self.compile_splat(&ast::Splat::Shallow, target_td, &sub_alias, &target_module)?;

                let join = if let Some(through_qname) = &ml.through {
                    let through_td = self.resolve_type(through_qname)?;
                    if through_td.junction {
                        // See `junction_info_for`'s doc comment: owner-derived.
                        IrMultiLinkJoin::Standard {
                            junction_table: self.owner_junction(td, &ml.name, Some(through_td)),
                            module: td.module.clone(),
                        }
                    } else {
                        let source_qname = format!("{}::{}", td.module, td.name);
                        let source_col = through_td
                            .links
                            .iter()
                            .find(|l| l.target == source_qname)
                            .ok_or_else(|| {
                                PyQLError::Type(PyQLTypeError {
                                    message: format!(
                                        "through type {through_qname} has no link to source type {source_qname}"
                                    ),
                                    position: Position { line: 0, col: 0 },
                                })
                            })?
                            .name
                            .clone();
                        let target_col = through_td
                            .links
                            .iter()
                            .find(|l| l.target == ml.target && l.name != source_col)
                            .or_else(|| through_td.links.iter().find(|l| l.target == ml.target))
                            .ok_or_else(|| {
                                PyQLError::Type(PyQLTypeError {
                                    message: format!(
                                        "through type {through_qname} has no link to target type {}",
                                        ml.target
                                    ),
                                    position: Position { line: 0, col: 0 },
                                })
                            })?
                            .name
                            .clone();
                        IrMultiLinkJoin::Through {
                            junction_table: through_td.table.clone(),
                            module: through_td.module.clone(),
                            source_col,
                            target_col,
                        }
                    }
                } else {
                    // See `junction_info_for`: the junction table is named
                    // after the owner and lives in the owner's schema, which a
                    // splat reaching in from another module is not.
                    IrMultiLinkJoin::Standard {
                        junction_table: self.owner_junction(td, &ml.name, None),
                        module: td.module.clone(),
                    }
                };

                let subquery = self.link_target_select(
                    target_td,
                    IrSource {
                        poly: None,
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        table: target_td.table.clone(),
                        alias: sub_alias.clone(),
                    },
                    sub_shape,
                );

                let link_properties = self.splat_link_properties(ml)?;
                pointers.push(IrShapePointer::MultiLink(IrMultiLinkPointer {
                    marker_offset: None,
                    alias: ml.name.clone(),
                    join,
                    subquery,
                    link_properties,
                    single: false,
                }));
            }
        }

        Ok(pointers)
    }

    /// The link properties a splat over a multi-link's targets carries: every
    /// property of its `@pylon.junction` through type.
    fn splat_link_properties(&self, ml: &MultiLinkDescriptor) -> Result<Vec<IrLinkProp>, PyQLError> {
        let Some(through_qname) = &ml.through else {
            return Ok(vec![]);
        };
        let through_td = self.resolve_type(through_qname)?;
        if !through_td.junction {
            return Ok(vec![]);
        }
        Ok(through_td
            .properties
            .iter()
            .filter(|p| p.name != "id")
            .map(|p| IrLinkProp { name: p.name.clone() })
            .collect())
    }

    // ── Type-intersection helpers ─────────────────────────────────────────────────

    /// Expand `[is ConcreteType].*` → scalar subqueries for each non-inherited property.
    fn compile_type_intersection_splat(
        &mut self,
        type_ref: &ast::ObjectRef,
        splat: &ast::Splat,
        parent_td: &TypeDescriptor,
        parent_alias: &str,
    ) -> Result<Vec<IrShapePointer>, PyQLError> {
        let type_name = match &type_ref.module {
            Some(m) => format!("{}::{}", m, type_ref.name),
            None => type_ref.name.clone(),
        };
        let concrete_td = self.resolve_type(&type_name)?;
        let concrete_qname = format!("{}::{}", concrete_td.module, concrete_td.name);
        let concrete_table = concrete_td.table.clone();

        // Interface properties: those in the parent (interface) td
        let interface_props: std::collections::HashSet<String> =
            parent_td.properties.iter().map(|p| p.name.clone()).collect();

        // Emit scalar subquery for each property not already in the interface
        let props: Vec<_> = concrete_td
            .properties
            .iter()
            .filter(|p| !interface_props.contains(&p.name))
            .cloned()
            .collect();

        // Same for computed pointers not already defined on the interface —
        // `[is Concrete].*` must include the concrete type's own computed
        // properties (e.g. `full_name`), not just its stored properties.
        let interface_computed: std::collections::HashSet<String> =
            parent_td.computed.iter().map(|c| c.name.clone()).collect();
        let computed: Vec<_> = concrete_td
            .computed
            .iter()
            .filter(|c| !interface_computed.contains(&c.name))
            .filter(|c| !matches!(splat, ast::Splat::Shallow) || !self.computed_is_object_valued(c, concrete_td))
            .cloned()
            .collect();

        // For deep splat, also include links
        let links: Vec<_> = if matches!(splat, ast::Splat::Deep) {
            concrete_td.links.to_vec()
        } else {
            vec![]
        };

        let mut pointers = vec![];
        for prop in props {
            let sub_alias = self.fresh_alias();
            let filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: sub_alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: IrExpr::ColumnRef {
                    alias: parent_alias.to_string(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
            }));
            let subquery = IrSelect::schema_bound(
                IrSource {
                    poly: None,
                    type_name: concrete_qname.clone(),
                    table: concrete_table.clone(),
                    alias: sub_alias,
                },
                vec![IrShapePointer::Scalar(IrScalarPointer {
                    implicit_id: false,
                    marker_offset: None,
                    alias: prop.name.clone(),
                    column: prop.name.clone(),
                    pg_type: prop.pg_type.clone(),
                    tuple_shape: self.resolve_property_tuple_shape(&prop),
                })],
                Some(filter),
            );
            pointers.push(IrShapePointer::Computed(IrComputedPointer {
                marker_offset: None,
                alias: prop.name.clone(),
                expr: IrExpr::Subquery(Box::new(subquery)),
            }));
        }

        for cd in computed {
            let sub_alias = self.fresh_alias();
            let filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: sub_alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: IrExpr::ColumnRef {
                    alias: parent_alias.to_string(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
            }));
            let expr_ast = crate::parse::parse_pointer_expr(&cd.expression).map_err(PyQLError::Syntax)?;
            let inner_ir = self.compile_expr(&expr_ast, concrete_td, &sub_alias)?;
            let subquery = IrSelect::schema_bound(
                IrSource {
                    poly: None,
                    type_name: concrete_qname.clone(),
                    table: concrete_table.clone(),
                    alias: sub_alias,
                },
                vec![IrShapePointer::Computed(IrComputedPointer {
                    marker_offset: None,
                    alias: cd.name.clone(),
                    expr: inner_ir,
                })],
                Some(filter),
            );
            pointers.push(IrShapePointer::Computed(IrComputedPointer {
                marker_offset: None,
                alias: cd.name.clone(),
                expr: IrExpr::Subquery(Box::new(subquery)),
            }));
        }

        // For deep splat, include single-link pointers as subqueries
        for link in links {
            let target_td = self.resolve_type(&link.target)?;
            let sub_alias = self.fresh_alias();
            let filter = if link.is_junction_backed() {
                let (jt_table, jt_module, jt_src_col, jt_tgt_col, _) =
                    self.junction_info_for(concrete_td, &link.name, &link.target, &link.through)?;
                let jt_alias = self.fresh_alias();
                let jt_filter = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::BinOp(Box::new(IrBinOp {
                        left: IrExpr::ColumnRef {
                            alias: jt_alias.clone(),
                            column: jt_src_col,
                            pg_type: "uuid".to_string(),
                        },
                        op: ast::BinOpKind::Eq,
                        right: IrExpr::ColumnRef {
                            alias: parent_alias.to_string(),
                            column: "id".to_string(),
                            pg_type: "uuid".to_string(),
                        },
                    })),
                    op: ast::BinOpKind::And,
                    right: IrExpr::BinOp(Box::new(IrBinOp {
                        left: IrExpr::ColumnRef {
                            alias: jt_alias.clone(),
                            column: jt_tgt_col,
                            pg_type: "uuid".to_string(),
                        },
                        op: ast::BinOpKind::Eq,
                        right: IrExpr::ColumnRef {
                            alias: sub_alias.clone(),
                            column: "id".to_string(),
                            pg_type: "uuid".to_string(),
                        },
                    })),
                }));
                let exists_select = IrSelect::schema_bound(
                    IrSource {
                        poly: None,
                        type_name: format!("{}::__jt__", jt_module),
                        table: jt_table,
                        alias: jt_alias,
                    },
                    vec![],
                    Some(jt_filter),
                );
                IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: IrExpr::Subquery(Box::new(exists_select)),
                }))
            } else {
                IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: sub_alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: IrExpr::ColumnRef {
                        alias: parent_alias.to_string(),
                        column: format!("{}_id", link.name),
                        pg_type: "uuid".to_string(),
                    },
                }))
            };
            let sub_shape = Self::pk_returning(target_td);
            let subquery = IrSelect::schema_bound(
                IrSource {
                    poly: self.link_target_fanout(target_td),
                    type_name: format!("{}::{}", target_td.module, target_td.name),
                    table: target_td.table.clone(),
                    alias: sub_alias,
                },
                sub_shape,
                Some(filter),
            );
            pointers.push(IrShapePointer::Computed(IrComputedPointer {
                marker_offset: None,
                alias: link.name.clone(),
                expr: IrExpr::Subquery(Box::new(subquery)),
            }));
        }

        Ok(pointers)
    }

    /// Compile `[is ConcreteType].pointer_name` → `IrShapePointer`.
    fn compile_type_intersection_pointer(
        &mut self,
        type_ref: &ast::ObjectRef,
        tail_steps: &[ast::PathStep],
        parent_alias: &str,
        marker_offset: Option<usize>,
    ) -> Result<IrShapePointer, PyQLError> {
        let expr = self.compile_type_intersection_expr_steps(type_ref, tail_steps, parent_alias)?;
        // Alias is the last Name step
        let alias = match tail_steps.last() {
            Some(ast::PathStep::Name(n)) => n.clone(),
            _ => return Err(self.type_err("type intersection must end with a pointer name")),
        };
        Ok(IrShapePointer::Computed(IrComputedPointer {
            alias,
            expr,
            marker_offset,
        }))
    }

    /// Compile `[is Type].name` as an `IrExpr` (for computed pointer / expression context).
    fn compile_type_intersection_expr(
        &mut self,
        steps: &[ast::PathStep],
        td: &TypeDescriptor,
        parent_alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        use ast::PathStep;
        let type_ref = match steps.first() {
            Some(PathStep::TypeIntersection(tr)) => tr.clone(),
            _ => return Err(self.type_err("expected type intersection")),
        };
        // The fast path reads one stored column off the narrowed type.
        // Anything else — a computed, a link, further traversal — falls
        // through to the general builder, rooted at the narrowed type
        // (whose rows share the interface row's id).
        match self.compile_type_intersection_expr_steps(&type_ref, &steps[1..], parent_alias) {
            Ok(ir) => Ok(ir),
            Err(fast_path_err) => {
                let p = ast::Path {
                    steps: steps.to_vec(),
                    partial: true,
                };
                self.compile_partial_path_as_subquery(&p, td, parent_alias)
                    .map_err(|_| fast_path_err)
            }
        }
    }

    /// Shared: build scalar subquery for `[is ConcreteType]` + tail pointer steps.
    fn compile_type_intersection_expr_steps(
        &mut self,
        type_ref: &ast::ObjectRef,
        tail_steps: &[ast::PathStep],
        parent_alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        use ast::PathStep;
        let type_name = match &type_ref.module {
            Some(m) => format!("{}::{}", m, type_ref.name),
            None => type_ref.name.clone(),
        };
        let concrete_td = self.resolve_type(&type_name)?;
        let concrete_qname = format!("{}::{}", concrete_td.module, concrete_td.name);
        let concrete_table = concrete_td.table.clone();

        let pointer_name = match tail_steps.first() {
            Some(PathStep::Name(n)) => n.as_str(),
            _ => return Err(self.type_err("type intersection must be followed by a pointer name, e.g. [is Type].name")),
        };

        let prop = concrete_td
            .properties
            .iter()
            .find(|p| p.name == pointer_name)
            .ok_or_else(|| self.field_err(pointer_name, &concrete_qname))?;
        let prop_name = prop.name.clone();
        let prop_type = prop.pg_type.clone();

        let sub_alias = self.fresh_alias();
        let filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: sub_alias.clone(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: parent_alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        }));

        let poly = self.poly_fanout_for(&concrete_qname);
        Ok(IrExpr::Subquery(Box::new(IrSelect::schema_bound(
            IrSource {
                poly,
                type_name: concrete_qname,
                table: concrete_table,
                alias: sub_alias,
            },
            vec![IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: false,
                marker_offset: None,
                alias: prop_name.clone(),
                column: prop_name,
                pg_type: prop_type,
                tuple_shape: self.resolve_property_tuple_shape(prop),
            })],
            Some(filter),
        ))))
    }

    fn compile_shape_element(
        &mut self,
        el: &ShapeElement,
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
    ) -> Result<IrShapePointer, PyQLError> {
        // Type intersection pointer: [is Type].pointer_name (without compexpr)
        if let Some(ast::PathStep::TypeIntersection(type_ref)) = el.path.steps.first()
            && el.compexpr.is_none()
            && el.path.steps.len() >= 2
        {
            // `[is T].configs: { … }` — a shape says the pointer is read as
            // objects, which the scalar route below cannot give: it resolves
            // a stored property and nothing else.
            if let Some(nested) = el.nested.as_deref()
                && !nested.is_empty()
                && let Some(ast::PathStep::Name(leaf)) = el.path.steps.last()
                && let Some(ptr) = self.try_compile_pointer_expr(
                    &leaf.clone(),
                    &Expr::Path(el.path.clone()),
                    td,
                    alias,
                    module,
                    el.marker_offset,
                    nested,
                )?
            {
                return Ok(ptr);
            }
            let type_ref = type_ref.clone();
            return self.compile_type_intersection_pointer(&type_ref, &el.path.steps[1..], alias, el.marker_offset);
        }

        let pointer_name = path_leaf(&el.path)?;

        // __type__ is a virtual property: the fully-qualified type name as a string.
        // It's always injected at position 0 for internal use; explicit inclusion adds
        // it as a regular computed pointer at a later position so Python can read it.
        if pointer_name == "__type__" && el.compexpr.is_none() {
            let expr = if self.is_polymorphic(td) {
                IrExpr::ColumnRef {
                    alias: alias.to_string(),
                    column: "__type__".to_string(),
                    pg_type: "text".to_string(),
                }
            } else {
                IrExpr::Literal(IrLiteral::Str(format!("{}::{}", td.module, td.name)))
            };
            return Ok(IrShapePointer::Computed(IrComputedPointer {
                marker_offset: el.marker_offset,
                alias: "__type__".to_string(),
                expr,
            }));
        }

        // `p := assert_exists(.prices { … })` — the assert is a check on the
        // pointer's own set, not part of a value expression, so the pointer is
        // compiled from the argument and the check reads the rows it
        // aggregates. Taken as an expression instead, an object-valued
        // argument is "part of a larger expression", which is exactly what an
        // object-returning function refuses.
        if let Some(compexpr) = &el.compexpr
            && let Some((call, value_expr, check_expr)) =
                Self::asserted_pointer_expr(compexpr, el.nested.as_deref().unwrap_or(&[]))
        {
            let element_for = |expr: Expr| ShapeElement {
                compexpr: Some(expr),
                nested: None,
                ..el.clone()
            };
            // Compiled speculatively: a scalar argument's assert is an ordinary
            // function call and belongs on the expression path below, and an
            // argument that does not compile at all should report its own error
            // from there rather than this one.
            if let Ok(ptr) = self.compile_shape_element(&element_for(value_expr), td, alias, module)
                && ptr.is_object_pointer()
            {
                let check = match check_expr {
                    Some(expr) => Some(self.compile_shape_element(&element_for(expr), td, alias, module)?),
                    None => None,
                };
                let message = self.assert_message(&call, Some((td, alias)))?;
                return Ok(IrShapePointer::Asserted(Box::new(IrAssertedPointer {
                    fn_name: call.name,
                    inner: ptr,
                    check,
                    message,
                })));
            }
        }

        // `t := (select .teams limit 1) if cond else {}` — one branch names
        // objects and the other nothing, so the pointer is that branch with
        // the condition folded into its own filter.
        if let Some(compexpr) = &el.compexpr
            && let Some(guarded) = guarded_object_branch(compexpr)
        {
            let element = ShapeElement {
                compexpr: Some(guarded),
                ..el.clone()
            };
            return self.compile_shape_element(&element, td, alias, module);
        }

        // Computed override: `pointer := expr`
        if let Some(compexpr) = &el.compexpr {
            // A link-valued RHS (`.multilink`, `.<backlink[is T] { … }`,
            // `(select .link filter … limit 1)`) is a pointer in its own
            // right, not an expression — see `try_compile_pointer_expr`.
            // `(select .resource { rev := … }) { changed_at := .rev.created_at }`
            // — a shape written at the point of use replaces the one the
            // subject carries, so whatever that one declared has to stay in
            // scope or the replacement cannot read it.
            let inner_declared: Vec<ShapeElement> = Self::replaced_subject_shape(compexpr)
                .iter()
                .filter(|e| e.compexpr.is_some())
                .cloned()
                .collect();
            let restore = (!inner_declared.is_empty()).then(|| {
                let mut scope = self.active_declared_pointers.clone();
                scope.extend(inner_declared);
                std::mem::replace(&mut self.active_declared_pointers, scope)
            });
            let pointer = self.try_compile_pointer_expr(
                pointer_name,
                compexpr,
                td,
                alias,
                module,
                el.marker_offset,
                el.nested.as_deref().unwrap_or(&[]),
            );
            if let Some(previous) = restore {
                self.active_declared_pointers = previous;
            }
            if let Some(ptr) = pointer? {
                return Ok(ptr);
            }
            // `p := marketplace::retrieve_listing_prices(.id) { amount }` — an
            // object-returning call written inline. A declared computed with
            // the same body already takes this route; a shape written on it
            // belongs to the rows it yields.
            if let Some((fc, call_nested)) = Self::object_call_with_shape(compexpr, el.nested.as_deref())
                && let Some(fs) = self.compile_fn_object_source(fc, &call_nested)?
            {
                return Ok(IrShapePointer::Computed(IrComputedPointer {
                    marker_offset: el.marker_offset,
                    alias: pointer_name.to_string(),
                    expr: IrExpr::ArrayFromSelect(Box::new(IrArraySource::ObjectFunction(Box::new(fs)))),
                }));
            }
            // A `T is U` naming a type other than this scope's answers once
            // per row of `T`; a shape keeps all of them, so ask for the set
            // form rather than the single value a boolean position takes.
            let ir = match compexpr {
                Expr::TypeIs { expr, ty } => self.compile_type_is_set(expr, ty, Some((td, alias)))?,
                _ => self.in_value_position(|c| c.compile_expr(compexpr, td, alias))?,
            };
            // Cross-scope TypeIs: promote to set-valued shape pointer.
            if let IrExpr::ArrayFromSelect(src) = ir {
                if let IrArraySource::RawExpr {
                    source,
                    poly_implementors,
                    poly_columns,
                    expr,
                } = *src
                {
                    return Ok(IrShapePointer::ScalarSet(IrScalarSetPointer {
                        alias: pointer_name.to_string(),
                        source,
                        poly_implementors,
                        poly_columns,
                        bool_expr: expr,
                    }));
                }
                return Ok(IrShapePointer::Computed(IrComputedPointer {
                    marker_offset: el.marker_offset,
                    alias: pointer_name.to_string(),
                    expr: IrExpr::ArrayFromSelect(src),
                }));
            }
            return Ok(IrShapePointer::Computed(IrComputedPointer {
                marker_offset: el.marker_offset,
                alias: pointer_name.to_string(),
                expr: ir,
            }));
        }

        // Scalar property
        if let Some(p) = Self::resolve_property(td, pointer_name) {
            return Ok(IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: false,
                marker_offset: el.marker_offset,
                alias: pointer_name.to_string(),
                column: p.name.clone(),
                pg_type: p.pg_type.clone(),
                tuple_shape: self.resolve_property_tuple_shape(p),
            }));
        }

        // Single link
        if let Some(l) = Self::resolve_link(td, pointer_name) {
            let target_td = self.resolve_type(&l.target)?;
            let sub_alias = self.fresh_alias();
            let nested_elements = el.nested.as_deref().unwrap_or(&[]);

            // A junction-backed link can carry `@prop` read references
            // (e.g. `spouse: { name, @since }`), the same as a multi-link's
            // own nested shape (`compile_multilink_pointer`) — partition
            // those out before compiling the rest as a regular shape.
            let (regular_els, link_properties): (Vec<ShapeElement>, Vec<IrLinkProp>) = if l.is_junction_backed() {
                let mut regular = Vec::new();
                let mut props = Vec::new();
                for nel in nested_elements {
                    if let [ast::PathStep::LinkProp(name)] = nel.path.steps.as_slice() {
                        props.push(IrLinkProp { name: name.clone() });
                    } else {
                        regular.push(nel.clone());
                    }
                }
                (regular, props)
            } else {
                (nested_elements.to_vec(), vec![])
            };

            let sub_shape = self.compile_shape(&regular_els, target_td, &sub_alias, &target_td.module.clone())?;
            let subquery = self.link_target_select(
                target_td,
                IrSource {
                    poly: None,
                    type_name: format!("{}::{}", target_td.module, target_td.name),
                    table: target_td.table.clone(),
                    alias: sub_alias,
                },
                sub_shape,
            );
            let correlation = if l.is_junction_backed() {
                let join = self.build_multilink_join(td, &l.name, &l.target, &l.through)?;
                IrSingleLinkCorrelation::Junction {
                    join,
                    target_pk: "id".to_string(),
                }
            } else {
                IrSingleLinkCorrelation::Fk {
                    fk_column: format!("{}_id", l.name),
                    target_pk: "id".to_string(),
                }
            };
            return Ok(IrShapePointer::SingleLink(IrSingleLinkPointer {
                marker_offset: el.marker_offset,
                alias: pointer_name.to_string(),
                correlation,
                subquery,
                link_properties,
            }));
        }

        // Multi-link
        if Self::resolve_multilink(td, pointer_name).is_some() {
            return self.compile_multilink_pointer(pointer_name, pointer_name, td, alias, module, el);
        }

        // Schema-defined computed pointer
        if let Some(cd) = self.resolve_computed(td, pointer_name) {
            return self.compile_declared_computed(
                &cd,
                td,
                alias,
                module,
                el.marker_offset,
                el.nested.as_deref().unwrap_or(&[]),
            );
        }

        // Declared by the binding this shape is read off, rather than by the
        // type — compiled against the binding's own row, as it was written.
        if let Some(declared) = self
            .active_declared_pointers
            .iter()
            .find(|d| path_leaf(&d.path).is_ok_and(|n| n == pointer_name))
            .cloned()
            && let Some(expr) = declared.compexpr.clone()
        {
            let nested = if el.nested.as_deref().unwrap_or(&[]).is_empty() {
                declared.nested.clone().unwrap_or_default()
            } else {
                el.nested.clone().unwrap_or_default()
            };
            return self.compile_computed_expr(pointer_name, &expr, td, alias, module, el.marker_offset, &nested, None);
        }

        Err(self.field_err(pointer_name, &format!("{}::{}", td.module, td.name)))
    }

    /// A computed pointer whose path walks *through* a multi-valued step before
    /// landing on objects — `members := .memberships.member`.
    ///
    /// Rooted at the enclosing type and correlated back to the enclosing row,
    /// exactly as `compile_partial_path_as_subquery` does for a value, then
    /// aggregated so the rows survive as rows.
    #[allow(clippy::too_many_arguments)]
    fn compile_chained_link_pointer(
        &mut self,
        pointer_name: &str,
        path: &ast::Path,
        td: &TypeDescriptor,
        alias: &str,
        nested: &[ShapeElement],
        modifiers: Option<&ast::SelectStmt>,
        multi: bool,
        tail: usize,
    ) -> Result<IrShapePointer, PyQLError> {
        let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
        steps.extend(path.steps.iter().cloned());
        let full_path = ast::Path { steps, partial: false };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(full_path.clone()),
            filter: modifiers.and_then(|m| m.filter.clone()),
            order_by: modifiers.map(|m| m.order_by.clone()).unwrap_or_default(),
            offset: modifiers.and_then(|m| m.offset.clone()),
            limit: modifiers.and_then(|m| m.limit.clone()),
            lock: None,
        };
        let mut path_select = self.compile_path_select_with_tail(&synthetic, &full_path, nested, false, tail, &[])?;
        Self::correlate_path_select(&mut path_select, alias);
        // A walk that crosses a multi step stands for a set, so it is
        // aggregated; one that cannot is a single object and is read as one,
        // rather than an array of length one.
        let expr = if multi {
            IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(path_select))))
        } else {
            IrExpr::ObjectPathSubquery(Box::new(path_select))
        };
        Ok(IrShapePointer::Computed(IrComputedPointer {
            marker_offset: None,
            alias: pointer_name.to_string(),
            expr,
        }))
    }

    fn compile_multilink_pointer(
        &mut self,
        output_alias: &str,
        ml_name: &str,
        td: &TypeDescriptor,
        _parent_alias: &str,
        module: &str,
        el: &ShapeElement,
    ) -> Result<IrShapePointer, PyQLError> {
        let ml = Self::resolve_multilink(td, ml_name)
            .expect("caller verified multilink exists")
            .clone();
        let target_td = self.resolve_type(&ml.target)?;
        let sub_alias = self.fresh_alias();
        let nested_elements = el.nested.as_deref().unwrap_or(&[]);

        // Partition @prop link-property elements from regular shape elements.
        let mut link_properties: Vec<IrLinkProp> = Vec::new();
        let mut regular_els: Vec<ShapeElement> = Vec::new();
        for nel in nested_elements {
            if let [ast::PathStep::LinkProp(name)] = nel.path.steps.as_slice() {
                link_properties.push(IrLinkProp { name: name.clone() });
            } else {
                regular_els.push(nel.clone());
            }
        }
        let has_splat = nested_elements.iter().any(|nel| {
            nel.splat.is_some() && !matches!(nel.path.steps.first(), Some(ast::PathStep::TypeIntersection(_)))
        });
        if has_splat {
            for prop in self.splat_link_properties(&ml)? {
                if !link_properties.iter().any(|existing| existing.name == prop.name) {
                    link_properties.push(prop);
                }
            }
        }

        let sub_shape = self.compile_shape(&regular_els, target_td, &sub_alias, &target_td.module.clone())?;

        let join = if let Some(through_qname) = &ml.through {
            let through_td = self.resolve_type(through_qname)?;
            if through_td.junction {
                // Junction type: columns are always named `source` and
                // `target`. See `junction_info_for`'s doc comment: the
                // physical table is owner-derived, never `through_td.table`.
                IrMultiLinkJoin::Standard {
                    junction_table: self.owner_junction(td, ml_name, Some(through_td)),
                    module: td.module.clone(),
                }
            } else {
                let source_qname = format!("{}::{}", td.module, td.name);
                let source_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == source_qname)
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to source type {source_qname}"),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                let target_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == ml.target && l.name != source_col)
                    .or_else(|| through_td.links.iter().find(|l| l.target == ml.target))
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to target type {}", ml.target),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                IrMultiLinkJoin::Through {
                    junction_table: through_td.table.clone(),
                    module: through_td.module.clone(),
                    source_col,
                    target_col,
                }
            }
        } else {
            IrMultiLinkJoin::Standard {
                junction_table: self.owner_junction(td, ml_name, None),
                module: module.to_string(),
            }
        };

        // `@prop` in this link's own modifiers reads the junction row, so
        // the through type has to be in scope while they compile.
        self.link_prop_scope
            .push(ml.through.clone().map(|t| (t, "jt".to_string())));
        let modifiers = (|c: &mut Self| -> Result<SelectModifiers, PyQLError> {
            Ok((
                el.filter
                    .as_ref()
                    .map(|f| c.compile_expr(f, target_td, &sub_alias))
                    .transpose()?,
                el.order_by
                    .iter()
                    .map(|s| c.compile_sort(s, target_td, &sub_alias))
                    .collect::<Result<_, _>>()?,
                el.offset
                    .as_ref()
                    .map(|e| c.compile_expr(e, target_td, &sub_alias))
                    .transpose()?,
                el.limit
                    .as_ref()
                    .map(|e| c.compile_expr(e, target_td, &sub_alias))
                    .transpose()?,
            ))
        })(self);
        self.link_prop_scope.pop();
        let (filter, order_by, offset, limit) = modifiers?;
        let subquery = IrSelect {
            rows: vec![IrRowSource::Bound {
                source: IrSource {
                    poly: self.link_target_fanout(target_td),
                    type_name: format!("{}::{}", target_td.module, target_td.name),
                    table: target_td.table.clone(),
                    alias: sub_alias.clone(),
                },
                shape: sub_shape,
            }],
            filter,
            order_by,
            offset,
            limit,
            distinct: false,
            dml_source: None,
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: vec![],
            lock: None,
        };

        Ok(IrShapePointer::MultiLink(IrMultiLinkPointer {
            marker_offset: el.marker_offset,
            alias: output_alias.to_string(),
            join,
            subquery,
            link_properties,
            single: false,
        }))
    }

    /// Compile `pointer := .<backlink_name[is OwnerType] { shape }` (a
    /// backlink used as a computed pointer inside another type's shape —
    /// the missing piece that made backlinks unusable for anything beyond
    /// `filter exists .<...>`). Mirrors `compile_multilink_pointer`'s
    /// shape/subquery construction, but the owner type's rows are
    /// correlated in reverse: via their own FK column for a single-link
    /// backlink source (`IrMultiLinkJoin::BacklinkFk`), or via the same
    /// junction table a forward multi-link would use with the owner/current
    /// column roles swapped (`IrMultiLinkJoin::BacklinkJunction`).
    fn compile_backlink_pointer(
        &mut self,
        output_alias: &str,
        path: &ast::Path,
        current_qname: &str,
        nested_elements: &[ShapeElement],
        marker_offset: Option<usize>,
        modifiers: Option<&ast::SelectStmt>,
    ) -> Result<IrShapePointer, PyQLError> {
        use ast::PathStep;

        let backlink_name = match path.steps.first() {
            Some(PathStep::Backlink(n)) => n.clone(),
            _ => return Err(self.type_err("internal: expected backlink step")),
        };
        let type_ref = match path.steps.get(1) {
            Some(PathStep::TypeIntersection(tr)) => tr,
            _ => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: format!(
                        "backlink '.< {backlink_name}' requires a type intersection, \
                     e.g.: .< {backlink_name}[is SomeType]"
                    ),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };
        if path.steps.len() > 2 {
            return Err(self.type_err(
                "further path traversal after a backlink shape is not yet supported \
                 (e.g. '.<link[is Type].property') — attach a nested shape instead: \
                 '.<link[is Type] { property }'",
            ));
        }

        let type_name = match &type_ref.module {
            Some(m) => format!("{}::{}", m, type_ref.name),
            None => type_ref.name.clone(),
        };
        let owner_td = self.backlink_owner(self.resolve_type(&type_name)?, &backlink_name, current_qname)?;
        let owner_qname = format!("{}::{}", owner_td.module, owner_td.name);

        let join = if let Some(l) = owner_td
            .links
            .iter()
            .find(|l| l.name == backlink_name && self.link_target_reaches(&l.target, current_qname))
        {
            if l.is_junction_backed() {
                let (junction_table, module, owner_col, current_col, _) = self.link_junction_info(owner_td, l)?;
                IrMultiLinkJoin::BacklinkJunction {
                    junction_table,
                    module,
                    owner_col,
                    current_col,
                }
            } else {
                IrMultiLinkJoin::BacklinkFk {
                    fk_col: format!("{}_id", backlink_name),
                }
            }
        } else if let Some(ml) = owner_td
            .multilinks
            .iter()
            .find(|ml| ml.name == backlink_name && self.link_target_reaches(&ml.target, current_qname))
            .cloned()
        {
            let (junction_table, module, _, _, _) = self.multilink_junction_info(owner_td, &ml)?;
            IrMultiLinkJoin::BacklinkJunction {
                junction_table,
                module,
                owner_col: "source".to_string(),
                current_col: "target".to_string(),
            }
        } else {
            return Err(PyQLError::Type(PyQLTypeError {
                message: format!(
                    "type {} has no link or multi-link '{}' pointing to {}",
                    owner_qname, backlink_name, current_qname,
                ),
                position: Position { line: 0, col: 0 },
            }));
        };

        let sub_alias = self.fresh_alias();
        let sub_shape = self.compile_shape(nested_elements, owner_td, &sub_alias, &owner_td.module.clone())?;

        // The `pointer := expr` grammar (`parse_shape_element`'s `:=`
        // branch) never parses trailing FILTER/ORDER BY/OFFSET/LIMIT after
        // the RHS expression — those per-link modifiers only exist on the
        // separate no-`:=` "bare inclusion with nested shape" parse path
        // that `compile_multilink_pointer`'s other call site reads
        // `el.filter` etc. from. Writing the RHS as a sub-select
        // (`pointer := (select .<link[is T] { … } filter … limit 1)`) is the
        // way to get them here, and `modifiers` carries that inner select.
        let (filter, order_by, offset, limit) = match modifiers {
            Some(sel) => self.compile_path_modifiers(sel, owner_td, &sub_alias)?,
            None => (None, vec![], None, None),
        };
        let subquery = IrSelect {
            rows: vec![IrRowSource::Bound {
                source: IrSource {
                    poly: self.poly_fanout_for(&owner_qname),
                    type_name: owner_qname,
                    table: owner_td.table.clone(),
                    alias: sub_alias.clone(),
                },
                shape: sub_shape,
            }],
            filter,
            order_by,
            offset,
            limit,
            distinct: false,
            dml_source: None,
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: vec![],
            lock: None,
        };

        Ok(IrShapePointer::MultiLink(IrMultiLinkPointer {
            alias: output_alias.to_string(),
            join,
            subquery,
            link_properties: vec![],
            marker_offset,
            single: self.backlink_is_single(owner_td, &backlink_name, current_qname) || limits_to_one(modifiers),
        }))
    }

    /// Compile a pointer the *schema* declares as computed (as opposed to one
    /// written inline in the query). A declared computed whose expression is
    /// a sub-select over a link — `(select .emails filter .primary limit 1)`
    /// — is an object pointer, exactly as if it had been written inline, so
    /// it takes the same route; everything else is a scalar expression.
    /// An object-returning function call as a row source, with the shape the
    /// pointer asked for (its target's own pk when none was written).
    fn compile_fn_object_source(
        &mut self,
        fc: &ast::FunctionCall,
        nested: &[ShapeElement],
    ) -> Result<Option<IrFunctionSelect>, PyQLError> {
        let Some(fd) = self.schema.functions.iter().find(|f| {
            let module_matches = fc.module.as_deref().map(|m| m == f.module.as_str()).unwrap_or(true);
            module_matches && f.name == fc.name && f.return_is_object
        }) else {
            return Ok(None);
        };
        let (fn_module, fn_name, return_type_name) = (fd.module.clone(), fd.name.clone(), fd.return_pg_type.clone());
        let return_td = self.resolve_type(&return_type_name)?;
        let alias = self.fresh_alias();
        let shape = if nested.is_empty() {
            Self::pk_returning(return_td)
        } else {
            self.compile_shape(nested, return_td, &alias, &return_td.module)?
        };
        let mut args = fc
            .args
            .iter()
            .map(|a| self.compile_free_expr(a))
            .collect::<Result<Vec<_>, _>>()?;
        // A function reading a session global takes them as its first
        // argument — the same forwarding a select over the call gets.
        if let Some(globals) = self.globals_arg_for_call(&format!("{fn_module}::{fn_name}"))? {
            args.insert(0, globals);
        }
        Ok(Some(IrFunctionSelect {
            fn_module,
            fn_name,
            fn_args: args,
            alias,
            type_name: format!("{}::{}", return_td.module, return_td.name),
            polymorphic: false,
            poly_implementors: vec![],
            poly_columns: vec![],
            shape,
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            distinct: false,
        }))
    }

    /// `assert_exists(x)`, `assert_exists(x { … })`, `assert_distinct(x) { … }`
    /// — the assert, the set it checks, and the shape to read that set with.
    ///
    /// Only the one-argument forms, and not `assert_single`: the message
    /// overload takes a second argument the wrapper would have to carry, and
    /// `assert_single` returns the element rather than the array, so it does
    /// not fit the check `IrShapePointer::Asserted` emits.
    fn asserted_pointer_expr(expr: &Expr, nested: &[ShapeElement]) -> Option<(ast::FunctionCall, Expr, Option<Expr>)> {
        // `(select assert_distinct(X) { … } limit 1)` — the assert is the
        // select's subject, so it sees the whole set, while the modifiers
        // narrow only what is read back. The two coincide unless a limit or
        // offset is written, and then the check needs its own copy without
        // them, or it would be asserting over the one row that survives.
        // `(select assert_exists(X)) { … }` — the shape after the select is
        // the one its subject passes through.
        if let Expr::Shape(sh) = expr
            && let Some(subquery @ Expr::SubQuery(_)) = sh.expr.as_ref()
        {
            return Self::asserted_pointer_expr(subquery, &sh.elements);
        }
        if let Expr::SubQuery(stmt) = expr
            && let Stmt::Select(sel) = stmt.as_ref()
        {
            let (call, inner, _) = Self::asserted_pointer_expr(&sel.result, nested)?;
            let rebuild = |offset: Option<Expr>, limit: Option<Expr>| {
                Expr::SubQuery(Box::new(Stmt::Select(ast::SelectStmt {
                    result: inner.clone(),
                    filter: sel.filter.clone(),
                    order_by: sel.order_by.clone(),
                    offset,
                    limit,
                    lock: sel.lock.clone(),
                })))
            };
            let value = rebuild(sel.offset.clone(), sel.limit.clone());
            let check = (sel.offset.is_some() || sel.limit.is_some()).then(|| rebuild(None, None));
            return Some((call, value, check));
        }
        // A shape written after the call (`assert_distinct(f(.id)) { amount }`)
        // belongs to the set the assert passes through, so it becomes the
        // inner pointer's shape.
        let (call, nested) = match expr {
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::FunctionCall(f)) => (f, sh.elements.clone()),
                _ => return None,
            },
            Expr::FunctionCall(f) => (f, nested.to_vec()),
            _ => return None,
        };
        if call.module.is_some() && call.module.as_deref() != Some("std") {
            return None;
        }
        if !matches!(call.name.as_str(), "assert_exists" | "assert_distinct") {
            return None;
        }
        let [arg] = call.args.as_slice() else {
            return None;
        };
        // A shape written after the call belongs to the set the assert passes
        // through, so it is folded onto the argument rather than left as the
        // element's nested shape: a union only reads as objects when the shape
        // sits directly on it.
        let inner = match (&arg, nested.is_empty()) {
            (Expr::Shape(_), _) | (_, true) => arg.clone(),
            _ => Expr::Shape(Box::new(ast::ShapeExpr {
                expr: Some(arg.clone()),
                elements: nested.clone(),
                marker_offset: None,
            })),
        };
        Some((call.clone(), inner, None))
    }

    /// A function call written as a pointer's value, with the shape its rows
    /// are read through — whether that shape sits after the call
    /// (`f(.id) { amount }`) or was parsed as the element's nested shape.
    fn object_call_with_shape<'e>(
        expr: &'e Expr,
        nested: Option<&[ShapeElement]>,
    ) -> Option<(&'e ast::FunctionCall, Vec<ShapeElement>)> {
        match expr {
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::FunctionCall(f)) => Some((f, sh.elements.clone())),
                _ => None,
            },
            Expr::FunctionCall(f) => Some((f, nested.unwrap_or(&[]).to_vec())),
            _ => None,
        }
    }

    fn compile_declared_computed(
        &mut self,
        cd: &crate::schema::ComputedDescriptor,
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
        marker_offset: Option<usize>,
        nested: &[ShapeElement],
    ) -> Result<IrShapePointer, PyQLError> {
        let expr_ast = crate::parse::parse_pointer_expr(&cd.expression).map_err(PyQLError::Syntax)?;
        let declared_on = self.computed_declared_on(td, &cd.name);
        self.compile_computed_expr(
            &cd.name,
            &expr_ast,
            td,
            alias,
            module,
            marker_offset,
            nested,
            declared_on,
        )
    }

    /// The ancestor `td` inherited computed `name` from, nearest first, or
    /// `None` when `td` declares it itself. See `SelectAnchor::declared_on`.
    fn computed_declared_on(&self, td: &TypeDescriptor, name: &str) -> Option<(String, String)> {
        td.bases
            .iter()
            .chain(td.parents.iter())
            .chain(td.interfaces.iter())
            .filter_map(|qualified| self.resolve_type(qualified).ok())
            .find(|ancestor| ancestor.computed.iter().any(|c| c.name == name))
            .map(|ancestor| (ancestor.name.clone(), format!("{}::{}", ancestor.module, ancestor.name)))
    }

    /// The body of `compile_declared_computed`, for a pointer whose expression
    /// is already parsed — a `with` binding's own shape declares one that way.
    #[allow(clippy::too_many_arguments)]
    fn compile_computed_expr(
        &mut self,
        name: &str,
        expr_ast: &Expr,
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
        marker_offset: Option<usize>,
        nested: &[ShapeElement],
        declared_on: Option<(String, String)>,
    ) -> Result<IrShapePointer, PyQLError> {
        // The object the pointer is computed on stays in scope for the whole
        // expression, including any part of it compiled without a type in
        // hand — a `with` binding's right-hand side, say.
        self.anchors.push(SelectAnchor {
            type_name: td.name.clone(),
            qualified: format!("{}::{}", td.module, td.name),
            alias: alias.to_string(),
            detached: false,
            declared_on,
        });
        let result = (|compiler: &mut Self| -> Result<IrShapePointer, PyQLError> {
            if let Some(ptr) =
                compiler.try_compile_pointer_expr(name, expr_ast, td, alias, module, marker_offset, nested)?
            {
                return Ok(ptr);
            }
            // `manifest := retrieve_connector_manifest(.id)` — a computed whose
            // expression is an object-returning call. The rows it yields are
            // the pointer's objects; read as a plain expression the call is
            // "part of a larger expression", which such a function refuses.
            if let Expr::FunctionCall(fc) = expr_ast
                && let Some(fs) = compiler.compile_fn_object_source(fc, nested)?
            {
                return Ok(IrShapePointer::Computed(IrComputedPointer {
                    marker_offset,
                    alias: name.to_string(),
                    expr: IrExpr::ArrayFromSelect(Box::new(IrArraySource::ObjectFunction(Box::new(fs)))),
                }));
            }
            let ir = compiler.in_value_position(|c| c.compile_expr(expr_ast, td, alias))?;
            Ok(IrShapePointer::Computed(IrComputedPointer {
                marker_offset,
                alias: name.to_string(),
                expr: ir,
            }))
        })(self);
        self.anchors.pop();
        result
    }

    /// Split a sub-select's result into the path it traverses and the nested
    /// shape attached to it: `select .posts { title }` → `.posts` + `{ title }`,
    /// `select .posts` → `.posts` + no shape.
    fn split_path_result(result: &Expr) -> Option<(&ast::Path, &[ShapeElement])> {
        match result {
            Expr::Path(p) => Some((p, &[])),
            // `(select detached T filter … limit 1).field` — the marker says
            // the set is not correlated with the enclosing one, which is
            // already true of a subject named by its own type.
            Expr::Detached(inner) => Self::split_path_result(inner),
            Expr::Shape(sh) => match &sh.expr {
                Some(Expr::Path(p)) => Some((p, sh.elements.as_slice())),
                _ => None,
            },
            _ => None,
        }
    }

    /// Peel a computed pointer's right-hand side down to the function call
    /// it names and the sub-select's modifiers, if that is its shape:
    /// `latest(.id)` / `(select latest(.id) filter …)`.
    fn function_subject(e: &Expr) -> Option<(&ast::FunctionCall, Option<&ast::SelectStmt>)> {
        match e {
            Expr::FunctionCall(fc) => Some((fc, None)),
            Expr::SubQuery(stmt) => match stmt.as_ref() {
                Stmt::Select(sel) => match &sel.result {
                    Expr::FunctionCall(fc) => Some((fc, Some(sel))),
                    _ => None,
                },
                _ => None,
            },
            _ => None,
        }
    }

    /// The object-returning user function `fc` names, if any.
    fn resolve_object_fn(&self, fc: &ast::FunctionCall) -> Option<&'a FunctionDescriptor> {
        self.schema.functions.iter().find(|f| {
            let module_matches = fc.module.as_deref().map(|m| m == f.module.as_str()).unwrap_or(true);
            module_matches && f.name == fc.name && f.return_is_object
        })
    }

    /// The shape a pointer's subject carried, when a shape written at the
    /// point of use replaced it: `(select .resource { rev := … }) { … }`.
    /// `pointer_subject` drops it, but its declarations are what the
    /// replacement reads `.rev` from.
    fn replaced_subject_shape(e: &Expr) -> &[ShapeElement] {
        let Expr::Shape(sh) = e else { return &[] };
        if sh.elements.is_empty() {
            return &[];
        }
        match sh.expr.as_ref() {
            Some(inner) => Self::pointer_subject(inner).map(|(_, nested, _)| nested).unwrap_or(&[]),
            None => &[],
        }
    }

    /// Peel a computed pointer's right-hand side down to the path it names,
    /// the shape attached to it, and the sub-select carrying its modifiers
    /// (if any): `.posts` / `.posts { title }` / `(select .posts limit 1)` /
    /// `(select .posts { title } limit 1)` / `(select .posts limit 1) { title }`.
    fn pointer_subject(e: &Expr) -> Option<(&ast::Path, &[ShapeElement], Option<&ast::SelectStmt>)> {
        match e {
            Expr::Path(p) => Some((p, &[], None)),
            Expr::SubQuery(stmt) => match stmt.as_ref() {
                Stmt::Select(sel) => {
                    let (p, inner) = Self::split_path_result(&sel.result)?;
                    Some((p, inner, Some(sel)))
                }
                _ => None,
            },
            Expr::Shape(sh) => {
                let (path, inner, modifiers) = Self::pointer_subject(sh.expr.as_ref()?)?;
                let nested = if sh.elements.is_empty() {
                    inner
                } else {
                    sh.elements.as_slice()
                };
                Some((path, nested, modifiers))
            }
            _ => None,
        }
    }

    /// `((select .parents filter … limit 1)).parent` — a computed whose value
    /// is a field access off its own sub-select. Rewritten as the select over
    /// the extended path, plus how many steps the field access contributed:
    /// the modifiers belong to the step *before* them, which is what a walk's
    /// `tail` pins them to.
    fn field_access_over_select(expr: &Expr) -> Option<(ast::SelectStmt, usize)> {
        let (root, fields) = Self::peel_field_access_chain(expr);
        if fields.is_empty() {
            return None;
        }
        let Expr::SubQuery(stmt) = root else { return None };
        let Stmt::Select(sel) = stmt.as_ref() else {
            return None;
        };
        let Expr::Path(path) = &sel.result else { return None };
        if !path.partial {
            return None;
        }
        let mut steps = path.steps.clone();
        let count = fields.len();
        steps.extend(fields.into_iter().map(ast::PathStep::Name));
        Some((
            ast::SelectStmt {
                result: Expr::Path(ast::Path { steps, partial: true }),
                ..sel.clone()
            },
            count,
        ))
    }

    /// A computed pointer whose right-hand side names a *link* rather than
    /// computing a value — `pointer := .multilink`, `:= .multilink { … }`,
    /// `:= .<backlink[is T] { … }`, and any of those wrapped in a sub-select
    /// carrying FILTER/ORDER BY/OFFSET/LIMIT.
    ///
    /// These are pointers in their own right, so they route to the same
    /// builders a bare `pointer: { … } filter … limit N` inclusion uses and
    /// come back as real object pointers (arrays of hydrated objects) rather
    /// than the bare id or EXISTS boolean that compiling them as an
    /// expression would produce. A sub-select's modifiers are exactly the
    /// per-link modifiers that inclusion form already carries, which is what
    /// makes the re-use exact — the `:=` grammar has no trailing-modifier
    /// form of its own.
    ///
    /// Shared by inline `pointer := …` shape elements and schema-declared
    /// computeds, so both kinds behave identically.
    ///
    /// `Ok(None)` means "not a link-valued RHS": the caller compiles it as
    /// an ordinary expression, which is where `(select …).field` — a scalar
    /// — is handled.
    #[allow(clippy::too_many_arguments)]
    fn try_compile_pointer_expr(
        &mut self,
        pointer_name: &str,
        compexpr: &Expr,
        td: &TypeDescriptor,
        alias: &str,
        module: &str,
        marker_offset: Option<usize>,
        nested_override: &[ShapeElement],
    ) -> Result<Option<IrShapePointer>, PyQLError> {
        // A nested shape can sit inside the parens (`(select .posts
        // { title })`) or after them (`(select .posts) { title }`, `.posts
        // { title }`) — the parser folds a trailing `{ }` into an
        // `Expr::Shape` wrapping whatever precedes it, never into
        // `el.nested` (that field is only populated by the separate no-`:=`
        // "bare inclusion with nested shape" parse path).
        // `((select .history order by … limit 1)).release` — the field access
        // continues the walk, and the modifiers stay on the step they were
        // written on.
        if let Some((sel, tail)) = Self::field_access_over_select(compexpr)
            && let Expr::Path(path) = &sel.result
        {
            let (head_steps, tail_steps) = path.steps.split_at(path.steps.len() - tail);
            let (head_multi, head_target) = self.walk_path_types(td, head_steps, MAX_COMPUTED_SPLICES);
            let Some(head_target) = head_target else {
                return Ok(None);
            };
            let (tail_multi, target) = self.walk_path_types(head_target, tail_steps, MAX_COMPUTED_SPLICES);
            if target.is_none() {
                return Ok(None);
            }
            let multi = tail_multi || (head_multi && !limits_to_one(Some(&sel)));
            if !multi && nested_override.is_empty() {
                return Ok(None);
            }
            let path = path.clone();
            return self
                .compile_chained_link_pointer(pointer_name, &path, td, alias, nested_override, Some(&sel), multi, tail)
                .map(Some);
        }
        let Some((path, declared_nested, modifiers)) = Self::pointer_subject(compexpr) else {
            return Ok(None);
        };
        if !path.partial {
            return Ok(None);
        }
        // A shape written at the point of use (`authors { name }` on a
        // declared computed) wins over the one the declaration itself
        // carries, which acts as the default.
        let nested = if nested_override.is_empty() {
            declared_nested
        } else {
            nested_override
        };

        // Only a link pointer of the current type becomes an object pointer;
        // a property (`x := .name`, `x := (select .name)`) is a scalar and
        // belongs on the expression path.
        let ml_name = match path.steps.as_slice() {
            [ast::PathStep::Name(n)] if Self::resolve_multilink(td, n).is_some() => n.clone(),
            // `.<link[is Owner]` — the objects on the other side of the
            // link. Traversing *past* the intersection (`.<link[is
            // Owner].name`) is a value, not an object pointer, so it goes
            // the expression route instead.
            [ast::PathStep::Backlink(_)] | [ast::PathStep::Backlink(_), ast::PathStep::TypeIntersection(_)] => {
                let current_qname = format!("{}::{}", td.module, td.name);
                let path = path.clone();
                let nested = nested.to_vec();
                return self
                    .compile_backlink_pointer(pointer_name, &path, &current_qname, &nested, marker_offset, modifiers)
                    .map(Some);
            }
            // `.memberships.member` — a chain no single-step builder can
            // express: the junction it would need belongs to no one link but
            // to the whole walk. Compiled as a path select and aggregated, so
            // it stays an object pointer instead of collapsing to the bare ids
            // an expression-position path gives — which, worse, was a scalar
            // subquery that failed outright the moment a second row matched.
            // A leading `[is T]` narrows what the walk starts from
            // (`brand := [is BrandOrderLineItem].brand { * }`); the walk
            // itself is the same one a bare name starts.
            steps
                if matches!(
                    steps.first(),
                    Some(ast::PathStep::Name(_) | ast::PathStep::TypeIntersection(_))
                ) =>
            {
                let (multi, target) = self.walk_path_types(td, steps, MAX_COMPUTED_SPLICES);
                // A single-valued walk takes this route only when a shape was
                // written on it (`account := resource.account { id }`), which
                // is what says an object was meant. Without one, a bare
                // `x := .link` still stands for the link's value, as it did
                // before there was an object route at all.
                if target.is_none() || (!multi && nested.is_empty()) {
                    return Ok(None);
                }
                let path = path.clone();
                let nested = nested.to_vec();
                return self
                    .compile_chained_link_pointer(
                        pointer_name,
                        &path,
                        td,
                        alias,
                        &nested,
                        modifiers,
                        multi && !limits_to_one(modifiers),
                        0,
                    )
                    .map(Some);
            }
            _ => return Ok(None),
        };

        let synthetic = ShapeElement {
            path: path.clone(),
            splat: None,
            nested: Some(nested.to_vec()),
            compexpr: None,
            op: ast::ShapeOp::Assign,
            filter: modifiers.and_then(|s| s.filter.clone()),
            order_by: modifiers.map(|s| s.order_by.clone()).unwrap_or_default(),
            offset: modifiers.and_then(|s| s.offset.clone()),
            limit: modifiers.and_then(|s| s.limit.clone()),
            marker_offset,
        };
        let mut pointer = self.compile_multilink_pointer(pointer_name, &ml_name, td, alias, module, &synthetic)?;
        if let IrShapePointer::MultiLink(link) = &mut pointer {
            link.single = limits_to_one(modifiers);
        }
        Ok(Some(pointer))
    }

    /// A sub-statement used as an expression: `(select .emails filter
    /// .primary limit 1).email`, `(select .posts order by .created desc
    /// limit 1).title`.
    ///
    /// Compiles the inner select as a flat path traversal
    /// (`compile_path_select` — the same builder a top-level `select
    /// Person.company.name` uses, so forward links, multi-links, backlinks,
    /// junction-backed links and type intersections all come along) and
    /// returns it as one correlated scalar subquery.
    ///
    /// A *partial* subject path (`.emails`) is relative to the enclosing
    /// object, so it is rooted at the enclosing type and correlated back to
    /// the enclosing row by primary key; an absolute one (`Person.name`) is
    /// independent and needs no correlation.
    ///
    /// `extra_fields` are the `.field` steps of an enclosing field-access
    /// chain. They are spliced onto the subject path rather than applied to
    /// its result, so the subquery projects the scalar column itself instead
    /// of an opaque object id.
    fn compile_subquery_expr(
        &mut self,
        stmt: &Stmt,
        extra_fields: &[String],
        ctx: Option<(&TypeDescriptor, &str)>,
        outer_shape: &[ShapeElement],
    ) -> Result<IrExpr, PyQLError> {
        // `(with x := … select …)` — the bindings have nowhere to live in
        // expression position, so they're hoisted to the enclosing
        // statement's own WITH clause and the inner statement takes over.
        if let Stmt::With(w) = stmt {
            for alias in &w.aliases {
                if self.bind_inline_if_correlated(&alias.name, &alias.expr, ctx)?
                    || self.bind_group(&alias.name, &alias.expr)?
                {
                    continue;
                }
                // The same computed inlined twice — `select M { * } filter … .role`
                // reaches `Membership.role` from both the splat and the filter —
                // hoists its `with` bindings once per inlining, and two CTEs of
                // one name is "WITH query name specified more than once". The
                // bindings are identical, so the first one stands for both; a
                // *different* binding under a name already taken is a real
                // collision and says so rather than silently shadowing.
                match self.hoisted_binding_sources.get(&alias.name) {
                    Some(existing) if *existing == alias.expr => continue,
                    Some(_) => {
                        return Err(self.type_err(&format!(
                            "two different `with` bindings named '{}' end up in one statement; \
                             rename one of them",
                            alias.name
                        )));
                    }
                    None => {}
                }
                let (ir_stmt, correlated_to) = self.compile_binding_in_scope(&alias.expr)?;
                let sql_name = self.claim_cte_sql_name(&alias.name);
                if let Some(slot) = correlated_to.as_deref().and_then(|i| i.strip_prefix("_for_")) {
                    self.correlated_bindings.insert(sql_name.clone(), slot.to_string());
                }
                let type_name = self.register_cte(&alias.name, &ir_stmt);
                self.hoisted_binding_sources
                    .insert(alias.name.clone(), alias.expr.clone());
                self.hoisted_ctes.push(IrCteDef {
                    name: sql_name,
                    stmt: ir_stmt,
                    type_name,
                    correlated_to,
                });
            }
            let inner = (*w.stmt).clone();
            return self.compile_subquery_expr(&inner, extra_fields, ctx, outer_shape);
        }

        if extra_fields.is_empty()
            && let Stmt::Select(sel) = stmt
            && let Expr::Shape(sh) = &sel.result
            && let Some(Expr::SubQuery(subject)) = &sh.expr
            && matches!(subject.as_ref(), Stmt::Group(_))
            && let IrStmt::Group(grp) = self.compile_stmt(stmt)?
        {
            return Ok(IrExpr::ArrayFromSelect(Box::new(IrArraySource::Group(Box::new(grp)))));
        }

        // `(select (.<a[is T] union .<b[is T]) { id } limit 1)` — the union's
        // operands are correlated to the enclosing row, so the whole thing is
        // read as one set rather than hoisted branch by branch.
        if let Stmt::Select(inner) = stmt
            && let Expr::Shape(sh) = &inner.result
            && let Some(subject) = sh.expr.as_ref()
            && let Some(operands) = Self::union_of_relative_paths(subject)
            && let Some((td, alias)) = ctx
        {
            let elements = sh.elements.clone();
            let operands_reach_many = self.relative_paths_reach_many(td, &operands);
            let mut branches = Vec::with_capacity(operands.len());
            for path in operands {
                let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
                steps.extend(path.steps.iter().cloned());
                let rooted = ast::Path { steps, partial: false };
                let synthetic = ast::SelectStmt {
                    result: Expr::Path(rooted.clone()),
                    filter: inner.filter.clone(),
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let mut ps = self.compile_path_select(&synthetic, &rooted, &elements, false)?;
                Self::correlate_path_select(&mut ps, alias);
                branches.push(ps);
            }
            let limit = inner
                .limit
                .as_ref()
                .map(|l| self.compile_free_expr(l))
                .transpose()?
                .map(Box::new);
            let multi = !matches!(limit.as_deref(), Some(IrExpr::Literal(IrLiteral::Int(1)))) && operands_reach_many;
            return Ok(IrExpr::ObjectPathUnion { branches, limit, multi });
        }
        // `(insert T { … }).id` — a mutation read through a path. The statement
        // itself may only run at the top level of a WITH, so it is hoisted into
        // one and the path is read back off that binding: exactly what the
        // `with x := (insert …) select x.id` spelling already compiles to. With
        // no path to read there is nothing for the mutation to stand in for,
        // which stays an error.
        // Only in free context. Inside a schema-bound shape element
        // (`select Person { x := (insert Company { … }).name }`) the mutation
        // would run once while every row read its result, which is not what
        // writing it there says — that stays rejected.
        if matches!(stmt, Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_))
            && !extra_fields.is_empty()
            && ctx.is_none()
        {
            let type_name = self.dml_subject_type(stmt)?;
            let inner = self.compile_stmt(stmt)?;
            let cte_name = self.fresh_nested_cte_name();
            // `hoisted_ctes`, not `pending_nested_ctes`: this mutation came out
            // of an expression in the enclosing statement, not out of another
            // statement's link assignment, so it belongs to that statement's
            // own WITH. Registering it is what lets the path below resolve
            // against it like any other binding.
            self.register_cte(&cte_name, &inner);
            self.hoisted_ctes.push(IrCteDef {
                name: cte_name.clone(),
                stmt: inner,
                type_name,
                correlated_to: None,
            });
            let mut steps = vec![ast::PathStep::Name(cte_name)];
            steps.extend(extra_fields.iter().cloned().map(ast::PathStep::Name));
            return self.compile_free_path(&ast::Path { steps, partial: false });
        }

        let Stmt::Select(sel) = stmt else {
            return Err(self.subquery_expr_err(stmt));
        };
        let has_modifiers =
            sel.filter.is_some() || !sel.order_by.is_empty() || sel.offset.is_some() || sel.limit.is_some();

        let Some((path, shape_els)) = Self::split_path_result(&sel.result) else {
            // `(select account::owner(.id) filter … limit 1).name` — the
            // function call is the row source the modifiers apply to.
            if let Expr::FunctionCall(fc) = &sel.result {
                let fc = fc.clone();
                if let Some(ir) = self.try_compile_fn_scalar_subquery(&fc, extra_fields, Some(sel), ctx)? {
                    return Ok(ir);
                }
            }
            // `(select <expression>)` with nothing to traverse is just the
            // expression itself. With modifiers to honour it is a statement,
            // not an expression — `(select count(Visit) filter …)` — so it is
            // hoisted into the enclosing WITH and read back by name.
            if has_modifiers {
                let inner = self.compile_stmt(stmt)?;
                let IrStmt::Select(select) = inner else {
                    return Err(self.subquery_expr_err(stmt));
                };
                if !select
                    .rows
                    .iter()
                    .all(|r| matches!(r, IrRowSource::Free(IrFreeExpr::Scalar(_))))
                {
                    return Err(self.subquery_expr_err(stmt));
                }
                let mut ir = IrExpr::ScalarSubquery(Box::new(select));
                for field in extra_fields {
                    ir = Self::project_free_object_field(ir, field);
                }
                return Ok(ir);
            }
            let mut ir = self.compile_expr_ctx(&sel.result, ctx)?;
            for field in extra_fields {
                ir = Self::project_free_object_field(ir, field);
            }
            return Ok(ir);
        };
        // A shape whose pointers are relative paths declares local names for
        // them, readable by the select's own FILTER/ORDER BY and by whatever
        // projects off it — `(select .locators { handle := [is Handle].handle,
        // latest := [is Handle].latest } filter .latest limit 1).handle`. Each
        // is substituted back into its readers, leaving an ordinary shapeless
        // sub-select behind.
        let rewritten_sel;
        let mut sel = sel;
        let mut shape_els = shape_els;
        let mut extra_steps: Vec<ast::PathStep> = extra_fields.iter().map(|f| ast::PathStep::Name(f.clone())).collect();
        if !shape_els.is_empty()
            && let Some(defs) = Self::shape_alias_paths(shape_els)
        {
            extra_steps = extra_fields
                .iter()
                .flat_map(|field| match defs.iter().find(|(name, _)| name == field) {
                    Some((_, definition)) => definition.steps.clone(),
                    None => vec![ast::PathStep::Name(field.clone())],
                })
                .collect();
            rewritten_sel = ast::SelectStmt {
                result: sel.result.clone(),
                filter: sel.filter.clone().map(|f| Self::substitute_shape_aliases(f, &defs)),
                order_by: sel
                    .order_by
                    .iter()
                    .map(|o| ast::SortExpr {
                        expr: Self::substitute_shape_aliases(o.expr.clone(), &defs),
                        direction: o.direction.clone(),
                        nones: o.nones.clone(),
                    })
                    .collect(),
                offset: sel.offset.clone(),
                limit: sel.limit.clone(),
                lock: sel.lock.clone(),
            };
            sel = &rewritten_sel;
            shape_els = &[];
        }

        // A shape only matters when the sub-select's own value is the
        // result. `(select .emails { address } limit 1).address` projects a
        // column straight back out of it, so the shape says nothing the
        // projection doesn't — the same reading PyQL gives it.
        // `answer := (select brand::AssessmentAnswer { … } filter … limit 1)`
        // — a select over a named type, carrying the shape its rows are read
        // with. That is an object, not the bare key the branch below gives a
        // shapeless one, so the shape has somewhere to go after all.
        // `(select names { * })` over an object `with` binding reads the
        // binding's rows the same way.
        if !shape_els.is_empty()
            && extra_fields.is_empty()
            && !path.partial
            && let [ast::PathStep::Name(type_name)] = path.steps.as_slice()
            && let Some(root_td) = match self.cte_object_type(type_name) {
                Some(_) => self.resolve_path_root(type_name).ok(),
                None => self.resolve_type(type_name).ok(),
            }
        {
            let alias = self.fresh_alias();
            let binding = self.cte_object_type(type_name).map(|_| type_name.clone());
            let table = match &binding {
                Some(name) => self.row_source_table(name, root_td),
                None => root_td.table.clone(),
            };
            let outer_declared = binding.as_ref().map(|name| {
                let declared = self.cte_declared_pointers.get(name).cloned().unwrap_or_default();
                std::mem::replace(&mut self.active_declared_pointers, declared)
            });
            let modifiers = self.compile_path_modifiers(sel, root_td, &alias);
            let module = root_td.module.clone();
            let shape = self.compile_shape(shape_els, root_td, &alias, &module);
            if let Some(outer) = outer_declared {
                self.active_declared_pointers = outer;
            }
            let (filter, order_by, offset, limit) = modifiers?;
            let shape = shape?;
            let source = IrSource {
                poly: self.poly_fanout_for(&format!("{}::{}", root_td.module, root_td.name)),
                type_name: format!("{}::{}", root_td.module, root_td.name),
                table,
                alias,
            };
            let single = selects_at_most_one(sel, root_td);
            let mut select = IrSelect::schema_bound(source, shape, filter);
            select.order_by = order_by;
            select.offset = offset;
            select.limit = limit;
            // Read as one object, a select yielding several rows aborts the
            // query ("more than one row returned by a subquery").
            return Ok(if single {
                IrExpr::ObjectSubquery(Box::new(select))
            } else {
                IrExpr::ArrayFromSelect(Box::new(IrArraySource::ObjectSelect(Box::new(select))))
            });
        }

        if !shape_els.is_empty() && extra_fields.is_empty() {
            return Err(self.type_err(
                "a sub-select with a shape is not valid in expression context — \
                 assign it to a computed pointer instead, or project a property \
                 off it, e.g. '(select .emails limit 1).address'",
            ));
        }

        // `(with c := … select c)` — the result is the binding itself, which
        // is a value already, not something to traverse from.
        if !path.partial
            && let [ast::PathStep::Name(name)] = path.steps.as_slice()
            && self.is_value_binding(name)
        {
            let mut ir = self.compile_expr_ctx(&sel.result, ctx)?;
            for field in extra_fields {
                ir = Self::project_free_object_field(ir, field);
            }
            return Ok(ir);
        }

        // `(select Company filter .name = 'Acme' limit 1)` — a bare type
        // select has nothing to traverse; in expression position it stands
        // for the object's primary key, which is what a link's value is.
        if !path.partial
            && extra_fields.is_empty()
            && let [ast::PathStep::Name(type_name)] = path.steps.as_slice()
            && let Ok(root_td) = self.resolve_type(type_name)
        {
            let alias = self.fresh_alias();
            let (filter, order_by, offset, limit) = self.compile_path_modifiers(sel, root_td, &alias)?;
            let source = IrSource {
                poly: None,
                type_name: format!("{}::{}", root_td.module, root_td.name),
                table: root_td.table.clone(),
                alias,
            };
            // Never `pk_returning` here: an empty shape is how the emitter
            // spells an EXISTS inner, so a type with no declared pk would
            // quietly become `SELECT 1` instead of a key.
            let pk = root_td.properties.iter().find(|p| p.is_pk);
            let shape = vec![IrShapePointer::Scalar(IrScalarPointer {
                implicit_id: false,
                marker_offset: None,
                alias: "id".to_string(),
                column: pk.map(|p| p.name.clone()).unwrap_or_else(|| "id".to_string()),
                pg_type: pk.map(|p| p.pg_type.clone()).unwrap_or_else(|| "uuid".to_string()),
                tuple_shape: None,
            })];
            let mut select = IrSelect::schema_bound(source, shape, filter);
            select.order_by = order_by;
            select.offset = offset;
            select.limit = limit;
            return Ok(IrExpr::Subquery(Box::new(select)));
        }

        let mut steps = path.steps.clone();
        let correlate = if path.partial {
            let Some((td, alias)) = ctx else {
                return Err(self.type_err(
                    "a relative path in a sub-select needs an enclosing object — \
                     write the type name explicitly, e.g. '(select Person.name)'",
                ));
            };
            steps.insert(0, ast::PathStep::Name(format!("{}::{}", td.module, td.name)));
            Some(alias.to_string())
        } else {
            None
        };
        steps.extend(extra_steps.iter().cloned());
        let full_path = ast::Path { steps, partial: false };

        let mut ps = self.compile_path_select_with_tail(sel, &full_path, outer_shape, false, extra_steps.len(), &[])?;
        if let Some(outer_alias) = correlate {
            Self::correlate_path_select(&mut ps, &outer_alias);
        }
        // A shape written after the projection (`(select … limit 1).account
        // { id, name }`) says the object was wanted, not its id, so the walk
        // comes back as one rather than being reduced the way a bare path in
        // expression position is.
        if !outer_shape.is_empty() && matches!(ps.result, IrPathResult::Object { .. }) {
            return Ok(IrExpr::ObjectPathSubquery(Box::new(ps)));
        }
        // `limit 1` is what makes a sub-select over a multi-link single-
        // valued — that is the whole point of `(select .emails filter
        // .primary limit 1).address`. Any other limit, or none, still stands
        // for a set, so it comes back as an array rather than a subquery
        // Postgres would reject the moment a second row showed up.
        let single = matches!(&sel.limit, Some(Expr::Literal(ast::Literal::Int(1))));
        let multi = match &full_path.steps[0] {
            ast::PathStep::Name(root) => {
                let root_td = self.resolve_path_root(root)?;
                // `(select T filter …).field` reads every `T` the filter
                // keeps, unless it pins an exclusive pointer.
                let every_row_of_a_type = !path.partial
                    && self.cte_object_type(root).is_none()
                    && self.resolve_type(root).is_ok()
                    && !selects_at_most_one(sel, root_td);
                every_row_of_a_type || self.path_crosses_multi(root_td, &full_path.steps[1..])
            }
            _ => false,
        };
        if multi && !single && matches!(ps.result, IrPathResult::Scalar(..)) {
            return Ok(IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(
                ps,
            )))));
        }
        Ok(IrExpr::PathSubquery(Box::new(ps)))
    }

    /// `account::owner(.id).name` and `(select account::owner(.id) filter …
    /// limit 1).name` — an object-returning user function used inside a
    /// larger expression, projected down to one of its return type's
    /// columns.
    ///
    /// The call itself stays object-valued (there is no way to inline a
    /// function that returns a row set), so it becomes the FROM clause of a
    /// scalar subquery and `field` becomes what that subquery selects. Only
    /// a property of the return type can be projected — reaching further
    /// (`fn(x).company.name`) would need joins the function row source has
    /// no way to express.
    ///
    /// `Ok(None)` when `fc` doesn't name an object-returning function, so
    /// the caller can fall through to ordinary function-call resolution.
    fn try_compile_fn_scalar_subquery(
        &mut self,
        fc: &ast::FunctionCall,
        fields: &[String],
        modifiers: Option<&ast::SelectStmt>,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        let fd = self.schema.functions.iter().find(|f| {
            let module_matches = fc.module.as_deref().map(|m| m == f.module.as_str()).unwrap_or(true);
            module_matches && f.name == fc.name && f.return_is_object
        });
        let Some(fd) = fd else { return Ok(None) };
        let (fn_module, fn_name, return_type_name, polymorphic, params) = (
            fd.module.clone(),
            fd.name.clone(),
            fd.return_pg_type.clone(),
            fd.return_is_polymorphic,
            fd.params.clone(),
        );

        let qualified = format!("{fn_module}::{fn_name}");
        let [field] = fields else {
            return Err(self.type_err(&format!(
                "function '{qualified}' returns objects, so using it inside an expression needs \
                 one of its properties, e.g. '{qualified}(…).name'"
            )));
        };
        if params.len() != fc.args.len() {
            return Err(self.type_err(&format!(
                "function '{qualified}' expects {} argument(s), got {}",
                params.len(),
                fc.args.len()
            )));
        }

        let mut fn_args = fc
            .args
            .iter()
            .map(|a| self.compile_expr_ctx(a, ctx))
            .collect::<Result<Vec<_>, _>>()?;
        if let Some(globals) = self.globals_arg_for_call(&qualified)? {
            fn_args.insert(0, globals);
        }

        let td = self.resolve_type(&return_type_name)?;
        let alias = self.fresh_alias();
        let Some(prop) = Self::resolve_property(td, field) else {
            return Err(self.field_err(field, &return_type_name));
        };
        let projected = IrShapePointer::Computed(IrComputedPointer {
            marker_offset: None,
            alias: field.clone(),
            expr: IrExpr::ColumnRef {
                alias: alias.clone(),
                column: prop.name.clone(),
                pg_type: prop.pg_type.clone(),
            },
        });

        let (poly_implementors, poly_columns) = if polymorphic {
            self.collect_poly_info(&return_type_name)
        } else {
            (vec![], vec![])
        };
        let (filter, order_by, offset, limit) = match modifiers {
            Some(sel) => {
                let td = self.resolve_type(&return_type_name)?;
                self.compile_path_modifiers(sel, td, &alias)?
            }
            None => (None, vec![], None, None),
        };

        Ok(Some(IrExpr::FnSubquery(Box::new(IrFunctionSelect {
            fn_module,
            fn_name,
            fn_args,
            alias,
            type_name: return_type_name,
            polymorphic,
            poly_implementors,
            poly_columns,
            shape: vec![projected],
            filter,
            order_by,
            offset,
            limit,
            distinct: false,
        }))))
    }

    /// Whether a declared computed pointer stands for *objects* rather than a
    /// value — `members := .memberships.member`, `primary_email := (select
    /// .emails filter .primary limit 1)`.
    ///
    /// `*` expands to properties and `**` adds links, so a computed belongs to
    /// whichever side its expression lands on. `ComputedDescriptor` carries no
    /// flag saying which, so the expression has to be walked.
    fn computed_is_object_valued(&self, cd: &crate::schema::ComputedDescriptor, td: &TypeDescriptor) -> bool {
        let Ok(expr) = crate::parse::parse_pointer_expr(&cd.expression) else {
            return false;
        };
        let expr = match Self::field_access_over_select(&expr) {
            Some((sel, _)) => Expr::SubQuery(Box::new(Stmt::Select(sel))),
            None => expr,
        };
        let Some((path, _, _)) = Self::pointer_subject(&expr) else {
            return false;
        };
        if !path.partial {
            return false;
        }
        match path.steps.as_slice() {
            // A backlink names the objects on the other side of the link.
            // Traversing past it (`.<author[is Post].title`) is a value again,
            // which the walk below works out for itself.
            [ast::PathStep::Backlink(_)] | [ast::PathStep::Backlink(_), ast::PathStep::TypeIntersection(_)] => true,
            steps => self.walk_path_types(td, steps, MAX_COMPUTED_SPLICES).1.is_some(),
        }
    }

    /// True when traversing `steps` from `td` crosses a multi-valued step —
    /// a multi-link or a backlink. Such a path stands for a *set*, so in
    /// expression position it has to come back as an array rather than a
    /// scalar subquery (which Postgres would reject at run time the moment a
    /// second row showed up).
    fn path_crosses_multi(&self, td: &TypeDescriptor, steps: &[ast::PathStep]) -> bool {
        self.walk_path_types(td, steps, MAX_COMPUTED_SPLICES).0
    }

    /// One correlated walk per operand of a coalesce of relative paths, each
    /// one filtered to the rows where every operand before it came up empty —
    /// which is what makes the arms, read together, mean what `??` means.
    fn coalesce_path_branches(
        &mut self,
        td: &TypeDescriptor,
        alias: &str,
        operands: &[ast::Path],
        elements: &[ast::ShapeElement],
    ) -> Result<Vec<IrPathSelect>, PyQLError> {
        let mut branches: Vec<IrPathSelect> = Vec::with_capacity(operands.len());
        for path in operands {
            let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
            steps.extend(path.steps.iter().cloned());
            let rooted = ast::Path { steps, partial: false };
            let synthetic = ast::SelectStmt {
                result: Expr::Path(rooted.clone()),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            let mut ps = self.compile_path_select(&synthetic, &rooted, elements, false)?;
            Self::correlate_path_select(&mut ps, alias);
            let guards: Vec<IrExpr> = branches
                .iter()
                .map(|earlier| {
                    IrExpr::UnaryOp(Box::new(IrUnaryOp {
                        op: ast::UnaryOpKind::Not,
                        operand: IrExpr::UnaryOp(Box::new(IrUnaryOp {
                            op: ast::UnaryOpKind::Exists,
                            operand: IrExpr::PathSubquery(Box::new(earlier.clone())),
                        })),
                    }))
                })
                .collect();
            if !guards.is_empty() {
                ps.filter = and_conditions(ps.filter, guards);
            }
            branches.push(ps);
        }
        Ok(branches)
    }

    /// Whether a relative path lands on objects rather than on values — its
    /// last named step is a link, a multi-link or a backlink. A coalesce over
    /// values is a choice between two sets of scalars, which the ordinary
    /// binary-operator path already reads as one.
    fn path_lands_on_objects(&self, td: &TypeDescriptor, path: &ast::Path) -> bool {
        let Some(last) = path
            .steps
            .iter()
            .rposition(|step| matches!(step, ast::PathStep::Name(_) | ast::PathStep::Backlink(_)))
        else {
            return false;
        };
        match &path.steps[last] {
            ast::PathStep::Backlink(_) => true,
            ast::PathStep::Name(name) => self
                .walk_path_types(td, &path.steps[..last], MAX_COMPUTED_SPLICES)
                .1
                .is_some_and(|owner| {
                    Self::resolve_multilink(owner, name).is_some() || Self::resolve_link(owner, name).is_some()
                }),
            _ => false,
        }
    }

    /// Whether the operands of a union or coalesce of relative paths reach
    /// more than one object between them. A leading type intersection roots
    /// the walk at the intersected type, as `compile_partial_path_as_subquery`
    /// does, so `[is Loop].condition_configs` is read off `Loop`.
    fn relative_paths_reach_many(&self, td: &TypeDescriptor, operands: &[ast::Path]) -> bool {
        operands.iter().any(|path| {
            let (root_td, rest) = match path.steps.first() {
                Some(ast::PathStep::TypeIntersection(tr)) => {
                    let name = match &tr.module {
                        Some(module) => format!("{}::{}", module, tr.name),
                        None => tr.name.clone(),
                    };
                    match self.resolve_type(&name) {
                        Ok(resolved) => (resolved, &path.steps[1..]),
                        Err(_) => return true,
                    }
                }
                _ => (td, &path.steps[..]),
            };
            self.path_crosses_multi(root_td, rest)
        })
    }

    /// Walk `steps` from `td` without compiling anything, reporting whether
    /// any step is multi-valued and what type the walk ends on. A computed
    /// pointer is expanded into the path it stands for — the same splice
    /// `compile_path_select` performs — so `.published.title` is recognized
    /// as multi-valued when `published` resolves to a multi-link.
    ///
    /// Gives up (`None` target) rather than guessing on anything it can't
    /// resolve; the real compile reports the error.
    fn walk_path_types(
        &self,
        td: &'a TypeDescriptor,
        steps: &[ast::PathStep],
        depth: usize,
    ) -> (bool, Option<&'a TypeDescriptor>) {
        let mut current = td;
        let mut multi = false;
        for (i, step) in steps.iter().enumerate() {
            match step {
                // `.<link[is Owner]` names the owner type; a bare `.<link`
                // spans every type declaring it, so that one lands nowhere in
                // particular.
                ast::PathStep::Backlink(backlink_name) => {
                    let Some(ast::PathStep::TypeIntersection(tr)) = steps.get(i + 1) else {
                        return (true, None);
                    };
                    let owner_name = match &tr.module {
                        Some(m) => format!("{}::{}", m, tr.name),
                        None => tr.name.clone(),
                    };
                    let current_qname = format!("{}::{}", current.module, current.name);
                    let single = self
                        .resolve_type(&owner_name)
                        .is_ok_and(|owner| self.backlink_is_single(owner, backlink_name, &current_qname));
                    multi |= !single;
                    continue;
                }
                ast::PathStep::TypeIntersection(tr) => {
                    let name = match &tr.module {
                        Some(m) => format!("{}::{}", m, tr.name),
                        None => tr.name.clone(),
                    };
                    match self.resolve_type(&name) {
                        Ok(t) => current = t,
                        Err(_) => return (multi, None),
                    }
                }
                ast::PathStep::Name(n) => {
                    if let Some(ml) = Self::resolve_multilink(current, n) {
                        multi = true;
                        match self.resolve_type(&ml.target) {
                            Ok(t) => current = t,
                            Err(_) => return (multi, None),
                        }
                        continue;
                    }
                    if let Some(target) = Self::resolve_link(current, n).map(|l| l.target.clone()) {
                        match self.resolve_type(&target) {
                            Ok(t) => current = t,
                            Err(_) => return (multi, None),
                        }
                        continue;
                    }
                    // A computed pointer stands for its own path, or for the
                    // object-returning function it calls.
                    if depth > 0
                        && let Some(cd) = self.resolve_computed(current, n)
                        && let Ok(expr) = crate::parse::parse_pointer_expr(&cd.expression)
                    {
                        if let Some((p, _, modifiers)) = Self::pointer_subject(&expr)
                            && p.partial
                        {
                            let (m, t) = self.walk_path_types(current, &p.steps, depth - 1);
                            // `limit 1` of its own caps the computed at one
                            // row however many its path crosses.
                            let capped = modifiers
                                .is_some_and(|m| matches!(&m.limit, Some(Expr::Literal(ast::Literal::Int(1)))));
                            multi = multi || (m && !capped);
                            match t {
                                Some(t) => current = t,
                                None => return (multi, None),
                            }
                            continue;
                        }
                        if let Some((fc, _)) = Self::function_subject(&expr)
                            && let Some(fd) = self.resolve_object_fn(fc)
                        {
                            multi = multi || fd.return_is_set;
                            match self.resolve_type(&fd.return_pg_type) {
                                Ok(t) => current = t,
                                Err(_) => return (multi, None),
                            }
                            continue;
                        }
                    }
                    // A property (or something unresolvable): the walk ends.
                    return (multi, None);
                }
                _ => return (multi, None),
            }
        }
        (multi, Some(current))
    }

    /// Compile a relative path that the step-by-step expression rules can't
    /// resolve on their own — deeper than two steps, a computed pointer on a
    /// linked type, anything following a backlink — as a single correlated
    /// subquery over the whole traversal.
    ///
    /// `compile_path_select` already implements the general case (forward
    /// links, multi-links, backlinks, junction-backed links, type
    /// intersections, nested tuple fields, "did you mean" on a typo), so the
    /// work here is only to root the path at the enclosing type and
    /// correlate it back to the enclosing row by primary key.
    ///
    /// A leading type intersection is rooted at the *intersected* type
    /// instead: `[is Concrete].col` has to read from Concrete's own table,
    /// which shares the interface row's id.
    fn compile_partial_path_as_subquery(
        &mut self,
        p: &ast::Path,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let (root_name, rest) = match p.steps.first() {
            Some(ast::PathStep::TypeIntersection(tr)) => {
                let name = match &tr.module {
                    Some(m) => format!("{}::{}", m, tr.name),
                    None => tr.name.clone(),
                };
                (name, &p.steps[1..])
            }
            _ => (format!("{}::{}", td.module, td.name), &p.steps[..]),
        };
        let root_td = self.resolve_type(&root_name)?;
        let multi = self.path_crosses_multi(root_td, rest);

        let mut steps = vec![ast::PathStep::Name(root_name)];
        steps.extend(rest.iter().cloned());
        let full_path = ast::Path { steps, partial: false };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(full_path.clone()),
            filter: None,
            order_by: vec![],
            offset: None,
            limit: None,
            lock: None,
        };
        let mut ps = self.compile_path_select(&synthetic, &full_path, &[], false)?;
        Self::correlate_path_select(&mut ps, alias);
        if multi && matches!(ps.result, IrPathResult::Scalar(..)) {
            Ok(IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(
                ps,
            )))))
        } else {
            Ok(IrExpr::PathSubquery(Box::new(ps)))
        }
    }

    /// A sub-select written relative to the enclosing object (`(select
    /// .emails filter .primary)`, with or without a shape), as a path select
    /// rooted at that object and correlated back to its row.
    ///
    /// Several places compile a sub-select with no context and so lose the
    /// object a relative path hangs off -- it then resolves in free context
    /// and reports the pointer as unknown. `None` when the statement is not
    /// of that shape, so the caller can carry on as before.
    fn relative_subselect(
        &mut self,
        stmt: &Stmt,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrPathSelect>, PyQLError> {
        let (Some((td, alias)), Stmt::Select(sel)) = (ctx, stmt) else {
            return Ok(None);
        };
        let (path, shape): (&ast::Path, &[ShapeElement]) = match &sel.result {
            Expr::Path(p) if p.partial => (p, &[]),
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::Path(p)) if p.partial => (p, sh.elements.as_slice()),
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };
        let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
        steps.extend(path.steps.iter().cloned());
        let rooted = ast::Path { steps, partial: false };
        let synthetic = ast::SelectStmt {
            result: Expr::Path(rooted.clone()),
            filter: sel.filter.clone(),
            order_by: sel.order_by.clone(),
            offset: sel.offset.clone(),
            limit: sel.limit.clone(),
            lock: None,
        };
        let mut ps = self.compile_path_select(&synthetic, &rooted, shape, false)?;
        Self::correlate_path_select(&mut ps, alias);
        Ok(Some(ps))
    }

    /// Tie a path select's root row to the enclosing row by primary key —
    /// what makes a relative path's subquery see only the current object's
    /// side of the graph.
    fn correlate_path_select(ps: &mut IrPathSelect, outer_alias: &str) {
        // A trigger's own row may not be in its table yet (`BEFORE INSERT`):
        // the walk starts from the row itself.
        if outer_alias == "NEW" || outer_alias == "OLD" {
            ps.root.table = format!("@row:{outer_alias}");
            ps.root.poly = None;
        }
        let correlation = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: ps.root.alias.clone(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: outer_alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        }));
        ps.filter = Some(match ps.filter.take() {
            Some(existing) => IrExpr::BinOp(Box::new(IrBinOp {
                left: correlation,
                op: ast::BinOpKind::And,
                right: existing,
            })),
            None => correlation,
        });
    }

    /// Names the kind of sub-statement that can't stand in for a value, so
    /// the message points at the actual blocker instead of listing every
    /// statement keyword.
    fn subquery_expr_err(&self, stmt: &Stmt) -> PyQLError {
        let what = match stmt {
            Stmt::Insert(_) => "an insert",
            Stmt::Update(_) => "an update",
            Stmt::Delete(_) => "a delete",
            Stmt::With(_) => "a `with` block",
            Stmt::For(_) => "a `for` loop",
            Stmt::Group(_) => "a `group`",
            _ => "this sub-statement",
        };
        self.type_err(&format!(
            "{what} cannot stand in for a value — a sub-statement is only valid in expression \
             position as a select over a path, e.g. '(select .emails filter .primary limit 1).address'"
        ))
    }

    // ── Expression compilation ────────────────────────────────────────────────────

    /// The operands an aggregate reads when its argument is spelled as a set:
    /// the elements of a set literal, or the flattened arms of a `union` chain.
    /// `min({a, b})` and `min((a union b))` mean the same thing and both read
    /// two values, which is the shape `AggOverSet` wants either way. `None` for
    /// anything else, leaving the ordinary single-value routes to it.
    fn set_operands(expr: &Expr) -> Option<Vec<&Expr>> {
        match expr {
            // An empty set has no operands to aggregate over, and the row
            // source it would emit is not valid SQL -- leave it to the arms
            // that give `{}` its own meaning.
            Expr::Set(elems) if elems.is_empty() => None,
            Expr::Set(elems) => Some(elems.iter().collect()),
            Expr::Union(left, right) => {
                let mut operands = Self::set_operands(left).unwrap_or_else(|| vec![left.as_ref()]);
                operands.extend(Self::set_operands(right).unwrap_or_else(|| vec![right.as_ref()]));
                Some(operands)
            }
            _ => None,
        }
    }

    /// Run `f` with `value_position` set — the expression it compiles stands
    /// where a value is expected, so a set-valued `in` keeps its one answer
    /// per element instead of collapsing to an EXISTS.
    fn in_value_position<R>(&mut self, f: impl FnOnce(&mut Self) -> R) -> R {
        let previous = std::mem::replace(&mut self.value_position, true);
        let result = f(self);
        self.value_position = previous;
        result
    }

    /// Run `f` with `value_position` cleared — a FILTER, or any other place
    /// that wants a single boolean out of the whole set. A computed pointer's
    /// expression may carry a sub-select with a filter of its own, so the flag
    /// has to be taken back off on the way down, not just put on at the top.
    fn as_condition<R>(&mut self, f: impl FnOnce(&mut Self) -> R) -> R {
        let previous = std::mem::replace(&mut self.value_position, false);
        let result = f(self);
        self.value_position = previous;
        result
    }

    /// Single expression compiler for both free and schema-bound contexts.
    /// `ctx = Some((td, alias))` when a schema type + SQL alias are in scope
    /// (enables `.property`/`.link` resolution via `compile_path`); `ctx =
    /// None` for free expressions (set literals, tuples, free objects,
    /// scalar function calls not touching a table), via `compile_free_path`
    /// for the `Path` variant. Most arms are identical either way and just
    /// thread `ctx` through recursive calls; the handful that genuinely
    /// diverge (`Path`, `BinOp`, `FunctionCall`, `Set`, `Detached`, `TypeIs`)
    /// branch internally on `ctx` — see each arm's own comment.
    fn compile_expr_ctx(&mut self, expr: &Expr, ctx: Option<(&TypeDescriptor, &str)>) -> Result<IrExpr, PyQLError> {
        match expr {
            // The main free/schema divergence — kept genuinely two-branched
            // (`compile_path` needs a schema type + alias throughout:
            // __type__, absolute-path rewrite, 2-step link/property
            // traversal, computed-pointer recursion; `compile_free_path`
            // only ever resolves for-vars/CTEs/fn-params/enum members).
            // Both share the bare-name lookup via `resolve_name_ref`.
            Expr::Path(p) => match ctx {
                Some((td, alias)) => self.compile_path(p, td, alias),
                None => self.compile_free_path(p),
            },

            // `(select … limit 1).connector.provider[is Individual].staff` — a
            // walk off a sub-select including a step with no expression form.
            Expr::PathStepOn { .. } => match self.try_compile_walk_off_subquery(expr, ctx)? {
                Some(ir) => Ok(ir),
                None => Err(self.type_err(
                    "a type intersection, link property or backlink needs a path, a binding \
                     or a sub-select to walk off",
                )),
            },

            Expr::Literal(lit) => Ok(IrExpr::Literal(match lit {
                Literal::Str(s) => IrLiteral::Str(s.clone()),
                Literal::Int(n) => IrLiteral::Int(*n),
                Literal::Float(f) => IrLiteral::Float(*f),
                Literal::Bool(b) => IrLiteral::Bool(*b),
            })),

            Expr::Parameter(name) => {
                let index = self.param_index(name);
                Ok(IrExpr::Param { index })
            }

            Expr::Global(name) => self.compile_global(name),

            Expr::Index { expr: e, index: i } => {
                let ir_expr = self.compile_expr_ctx(e, ctx)?;
                if self.is_json_expr(e, &ir_expr) {
                    return match &**i {
                        Expr::Literal(Literal::Str(key)) => Ok(IrExpr::JsonbField {
                            expr: Box::new(ir_expr),
                            field: key.clone(),
                        }),
                        Expr::Literal(Literal::Int(n)) if *n >= 0 => Ok(IrExpr::JsonbIndex {
                            expr: Box::new(ir_expr),
                            index: *n as usize,
                        }),
                        _ => Err(self.type_err("indexing json needs a literal key or a literal position")),
                    };
                }
                let ir_index = self.compile_expr_ctx(i, ctx)?;
                let is_array = is_array_expr(&ir_expr);
                Ok(IrExpr::Subscript {
                    expr: Box::new(ir_expr),
                    index: Box::new(ir_index),
                    is_array,
                })
            }

            Expr::Slice {
                expr: e,
                lower: lo,
                upper: hi,
            } => {
                let ir_expr = self.compile_expr_ctx(e, ctx)?;
                let is_array = is_array_expr(&ir_expr);
                let ir_lower = lo.as_ref().map(|x| self.compile_expr_ctx(x, ctx)).transpose()?;
                let ir_upper = hi.as_ref().map(|x| self.compile_expr_ctx(x, ctx)).transpose()?;
                Ok(IrExpr::Slice {
                    expr: Box::new(ir_expr),
                    lower: ir_lower.map(Box::new),
                    upper: ir_upper.map(Box::new),
                    is_array,
                })
            }

            Expr::TypeCast(tc) => {
                // `<AnyType>{}` — an empty set cast to any type, e.g. clearing
                // an optional link (`<Company>{}`) — is always just NULL,
                // regardless of what pg_type the cast target would otherwise
                // resolve to (a schema object type name isn't a scalar cast
                // target at all, so resolve_cast_pg_type couldn't handle it
                // below anyway). Generalizes the same bare-`{}`-in-assignment-
                // position special case in compile_assignments_inner to any
                // expression context.
                if matches!(&tc.expr, Expr::Set(elems) if elems.is_empty()) {
                    return Ok(IrExpr::Null);
                }
                if let ast::TypeExpr::Tuple { elements } = &tc.ty
                    && let Some(ir) = self.try_compile_tuple_literal_cast_ctx(elements, &tc.expr, ctx)?
                {
                    let pg_type = self.resolve_cast_pg_type(&tc.ty)?;
                    let tuple_shape = self.resolve_tuple_cast_shape(&tc.ty);
                    return Ok(IrExpr::TypeCast(Box::new(IrTypeCast {
                        expr: ir,
                        pg_type,
                        tuple_shape,
                    })));
                }
                if let ast::TypeExpr::Array { element } = &tc.ty
                    && let Some(ir) = self.try_compile_array_literal_cast_ctx(element, &tc.expr, ctx)?
                {
                    let pg_type = self.resolve_cast_pg_type(&tc.ty)?;
                    return Ok(IrExpr::TypeCast(Box::new(IrTypeCast {
                        expr: ir,
                        pg_type,
                        tuple_shape: None,
                    })));
                }
                // `<marketplace::BrandAddon>line.listing.id` — casting a key to
                // an object type names the row that key identifies, and in
                // expression position (a link's value, a comparison) the row
                // *is* its key. There is no scalar pg type to cast to, so
                // `resolve_cast_pg_type` below reports the object type as
                // unknown.
                const STDLIB_MODULES: &[&str] = &["std", "cal", "math", "sys", "pgvector", "crypto", "postgis"];
                if let Some((module, name)) = tc.ty.as_named()
                    && module.map(|m| !STDLIB_MODULES.contains(&m)).unwrap_or(false)
                {
                    let qname = match module {
                        Some(m) => format!("{m}::{name}"),
                        None => name.to_string(),
                    };
                    if self.resolve_enum(&qname).is_none()
                        && self.resolve_scalar(&qname).is_none()
                        && self.resolve_named_tuple(&qname).is_none()
                        && self.resolve_type(&qname).is_ok()
                    {
                        return self.compile_expr_ctx(&tc.expr, ctx);
                    }
                }
                // A cast to `json` is an output sink: the text it produces is
                // the value, so an `id` nobody asked for would show up in it.
                // So the flag is cleared for the whole cast.
                let inner = if casts_to_json(&tc.ty) {
                    self.without_implicit_id(|this| this.compile_expr_ctx(&tc.expr, ctx))?
                } else {
                    self.compile_expr_ctx(&tc.expr, ctx)?
                };
                let pg_type = self.resolve_cast_pg_type(&tc.ty)?;

                // PostgreSQL has no native jsonb -> {uuid, date/time family,
                // interval, array<T>} cast (only jsonb -> {bool, numeric
                // family, text} are native as of PG17+) — there's nothing
                // generic to defer to the way `to_jsonb(x)` covers every
                // scalar in the opposite direction, so extract via `#>>'{}'`
                // (the value's raw text form) and cast that, matching what
                // `to_json`'s own emitted text already round-trips (ISO 8601
                // for datetimes, PG's native interval text, a bare UUID
                // string — see `to_jsonb`'s emission for `<json>x`).
                if infer_ir_type(&inner) == Some("jsonb") {
                    if let ast::TypeExpr::Array { element } = &tc.ty {
                        let elem_pg = self.resolve_cast_pg_type(element)?;
                        let sql_template =
                            format!("ARRAY(SELECT (elem #>> '{{}}')::{elem_pg} FROM jsonb_array_elements($1) AS elem)");
                        return Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: "jsonb_array_cast".to_string(),
                            args: vec![inner],
                            sql_template: Some(sql_template),
                        }));
                    }
                    if matches!(
                        pg_type.as_str(),
                        "uuid" | "timestamptz" | "timestamp" | "date" | "time" | "interval"
                    ) {
                        let sql_template = format!("(($1 #>> '{{}}'))::{pg_type}");
                        return Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: "jsonb_scalar_cast".to_string(),
                            args: vec![inner],
                            sql_template: Some(sql_template),
                        }));
                    }
                }

                // The mirror of the `<str>x` routing below: every
                // str → date/time cast goes through a function, and those
                // are stricter than PostgreSQL's own input parsers, which
                // accept `01/16/2026`, a zone-less datetime, or `1 month` as
                // a duration. Keyed on the type as written, because
                // `duration`, `cal::relative_duration` and
                // `cal::date_duration` are all `interval` and each takes a
                // different set of units.
                if infer_ir_type(&inner) == Some("text")
                    && let Some((module, name)) = tc.ty.as_named()
                {
                    let parser = match (module, name) {
                        (None | Some("std"), "datetime") => Some(("std", "to_datetime")),
                        (Some("cal"), "local_datetime") => Some(("cal", "to_local_datetime")),
                        (Some("cal"), "local_date") => Some(("cal", "to_local_date")),
                        (Some("cal"), "local_time") => Some(("cal", "to_local_time")),
                        _ => None,
                    };
                    if let Some((ns, fn_name)) = parser {
                        return self.resolve_fn_call(Some(ns), fn_name, vec![inner]);
                    }
                    // Neither is reachable as a function, only as a cast, so
                    // they are internal helpers rather than stdlib
                    // overloads (which would also be indistinguishable, both
                    // taking one `interval`).
                    let helper = match (module, name) {
                        (None | Some("std"), "duration") => Some("duration_in"),
                        (Some("cal"), "date_duration") => Some("date_duration_in"),
                        _ => None,
                    };
                    if let Some(helper) = helper {
                        return Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                            return_pg_type: Some("interval".to_string()),
                            schema: Some("_pylon".to_string()),
                            name: helper.to_string(),
                            args: vec![inner],
                            sql_template: None,
                        }));
                    }
                }

                // `<str>` of a date/time value is `to_str` of it, so that the
                // cast and the function cannot disagree. `::text`
                // gives a different answer for the same value — a datetime
                // renders as `2026-01-16 12:34:56+00` rather than ISO 8601 —
                // and the two spellings must not disagree. The rest of the
                // family is routed too, where `to_str` *is* `::text`, so the
                // rule is about the types rather than about which
                // implementations happen to differ today.
                if pg_type == "text"
                    && matches!(
                        infer_ir_type(&inner),
                        Some("timestamptz" | "timestamp" | "date" | "time" | "interval")
                    )
                {
                    return self.resolve_fn_call(Some("std"), "to_str", vec![inner]);
                }

                // PostgreSQL casts a boolean to `int4` and to nothing else, so
                // the narrower and wider integers go through it.
                let inner = match (pg_type.as_str(), infer_ir_type(&inner)) {
                    ("int2" | "int8", Some("boolean")) => IrExpr::TypeCast(Box::new(IrTypeCast {
                        expr: inner,
                        pg_type: "int4".to_string(),
                        tuple_shape: None,
                    })),
                    _ => inner,
                };

                let tuple_shape = self.resolve_tuple_cast_shape(&tc.ty);
                Ok(IrExpr::TypeCast(Box::new(IrTypeCast {
                    expr: inner,
                    pg_type,
                    tuple_shape,
                })))
            }

            // The same coalesce with no shape after it — `(… ?? …)` standing
            // for the ids of the set it reaches. SQL's own COALESCE, which an
            // ordinary binary operator compiles to, takes one value per side,
            // so a walk reaching many rows has to be read as a set instead.
            Expr::BinOp(b)
                if b.op == ast::BinOpKind::Coalesce
                    && ctx.is_some()
                    && Self::coalesce_of_relative_paths(expr).is_some_and(|operands| {
                        let td = ctx.expect("checked").0;
                        self.relative_paths_reach_many(td, &operands)
                            && operands.iter().all(|path| self.path_lands_on_objects(td, path))
                    }) =>
            {
                let (td, alias) = ctx.expect("checked by the guard");
                let operands = Self::coalesce_of_relative_paths(expr).expect("checked by the guard");
                let branches = self.coalesce_path_branches(td, alias, &operands, &[])?;
                Ok(IrExpr::ObjectPathUnion {
                    branches,
                    limit: None,
                    multi: true,
                })
            }

            Expr::BinOp(b) => {
                // Only a condition can become an EXISTS — `.<pins.updated_at ??
                // .<pins.created_at` is a set of values, not a test on each pin.
                let yields_values = matches!(
                    b.op,
                    ast::BinOpKind::Add
                        | ast::BinOpKind::Sub
                        | ast::BinOpKind::Mul
                        | ast::BinOpKind::Div
                        | ast::BinOpKind::FloorDiv
                        | ast::BinOpKind::Mod
                        | ast::BinOpKind::Pow
                        | ast::BinOpKind::Coalesce
                        | ast::BinOpKind::Concat
                );
                // `addons := .required_addons in licensed_addons` — `in` is
                // asked once per element of the set on its left, so where a
                // value is wanted it answers with a set of booleans, not with
                // the single "any of them" the EXISTS below would give. That
                // one is still what a FILTER means, and `all(…)`/`any(…)` are
                // how a query asks for it here.
                if let Some(elementwise) = self.try_elementwise_in(b, ctx)? {
                    return Ok(elementwise);
                }
                if let Some((td, alias)) = ctx
                    && !yields_values
                {
                    if let Some(exists) = self.try_backlink_exists(b, td, alias)? {
                        return Ok(exists);
                    }
                    if let Some(exists) = self.try_multilink_exists(b, td, alias)? {
                        return Ok(exists);
                    }
                }
                // `x in {a, b, c}` / `x not in {a, b, c}`: a set *literal*
                // specifically on the right of in/not-in compiles to a
                // Postgres array, not through the generic Set-literal path
                // below (which hard-errors on any bare set literal in
                // expression position) — In/NotIn's own SQL emission
                // (`= ANY(...)`/`<> ALL(...)`, sql/mod.rs) already expects
                // an array-typed right operand, so this is the one
                // expression position a set literal is actually meaningful
                // in, in either schema-bound or free context.
                if matches!(b.op, ast::BinOpKind::In | ast::BinOpKind::NotIn)
                    && let Expr::Set(elems) = &b.right
                {
                    let left = self.compile_expr_ctx(&b.left, ctx)?;
                    let items = elems
                        .iter()
                        .map(|e| self.compile_expr_ctx(e, ctx))
                        .collect::<Result<Vec<_>, _>>()?;
                    let right = IrExpr::Array(items);
                    return Ok(IrExpr::BinOp(Box::new(IrBinOp {
                        left,
                        op: b.op.clone(),
                        right,
                    })));
                }
                // `.account = account_of_transaction()` — comparing objects
                // compares identity, so an object-returning function on either
                // side stands for the id of the row it returns. Left whole it
                // is a function call with nowhere to go but the subject of a
                // select.
                if matches!(b.op, ast::BinOpKind::Eq | ast::BinOpKind::Ne) {
                    let id = ["id".to_string()];
                    let left_id = match &b.left {
                        Expr::FunctionCall(fc) => self.try_compile_fn_scalar_subquery(fc, &id, None, ctx)?,
                        _ => None,
                    };
                    let right_id = match &b.right {
                        Expr::FunctionCall(fc) => self.try_compile_fn_scalar_subquery(fc, &id, None, ctx)?,
                        _ => None,
                    };
                    if left_id.is_some() || right_id.is_some() {
                        let left = match left_id {
                            Some(e) => e,
                            None => self.compile_expr_ctx(&b.left, ctx)?,
                        };
                        let right = match right_id {
                            Some(e) => e,
                            None => self.compile_expr_ctx(&b.right, ctx)?,
                        };
                        return Ok(IrExpr::BinOp(Box::new(IrBinOp {
                            left,
                            op: b.op.clone(),
                            right,
                        })));
                    }
                }
                let mut left = self.compile_expr_ctx(&b.left, ctx)?;
                let mut right = self.compile_expr_ctx(&b.right, ctx)?;
                // An ordering comparison takes one value a side, so a walk
                // gathered as an array is read back as a scalar subquery — see
                // `set_walk_as_scalar`.
                if matches!(
                    b.op,
                    ast::BinOpKind::Lt | ast::BinOpKind::Le | ast::BinOpKind::Gt | ast::BinOpKind::Ge
                ) && yields_array(&left) != yields_array(&right)
                {
                    left = set_walk_as_scalar(left);
                    right = set_walk_as_scalar(right);
                }
                // `A ?? B` over sets is A unless A is empty. An empty set
                // gathered as an array is `{}`, not NULL, so `COALESCE` would
                // never fall through to B.
                if b.op == ast::BinOpKind::Coalesce && (yields_array(&left) || yields_array(&right)) {
                    let as_set = |value: IrExpr| {
                        if yields_array(&value) {
                            value
                        } else {
                            IrExpr::FunctionCall(IrFunctionCall {
                                return_pg_type: None,
                                schema: None,
                                name: "array_remove".to_string(),
                                args: vec![value],
                                sql_template: Some("array_remove(ARRAY[$1], NULL)".to_string()),
                            })
                        }
                    };
                    let left = as_set(left);
                    let condition = IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: None,
                        name: "cardinality".to_string(),
                        args: vec![left.clone()],
                        sql_template: Some("(cardinality($1) > 0)".to_string()),
                    });
                    return Ok(IrExpr::IfElse(Box::new(IrIfElse {
                        condition,
                        if_: left,
                        else_: as_set(right),
                    })));
                }
                // Comparing a value against a *set* — a path that crosses a
                // multi-link or a backlink, which arrives here as an array of
                // its elements — holds when any element matches, which is what
                // the equality means in PyQL and what `= ANY` says in SQL.
                if matches!(b.op, ast::BinOpKind::Eq | ast::BinOpKind::Ne) {
                    // A `with` binding of more than one row is the same kind
                    // of set, reached through its CTE rather than an array.
                    let is_set = |e: &IrExpr| match e {
                        IrExpr::ArrayFromSelect(_) => true,
                        IrExpr::CteRef { name, .. } => self.multi_row_ctes.contains(name),
                        _ => false,
                    };
                    let flipped = is_set(&left) && !is_set(&right) && !is_array_expr(&right);
                    let straight = is_set(&right) && !is_set(&left) && !is_array_expr(&left);
                    if flipped || straight {
                        let (value, set) = if straight { (left, right) } else { (right, left) };
                        let membership = IrExpr::BinOp(Box::new(IrBinOp {
                            left: value,
                            op: ast::BinOpKind::In,
                            right: set,
                        }));
                        return Ok(if matches!(b.op, ast::BinOpKind::Ne) {
                            IrExpr::UnaryOp(Box::new(IrUnaryOp {
                                op: ast::UnaryOpKind::Not,
                                operand: membership,
                            }))
                        } else {
                            membership
                        });
                    }
                }
                if let (Some(lt), Some(rt)) = (infer_ir_type(&left), infer_ir_type(&right))
                    && !types_compatible(lt, rt)
                    && !datetime_arithmetic_compatible(&b.op, lt, rt)
                {
                    return Err(PyQLError::Type(PyQLTypeError {
                        message: format!(
                            "operator '{op}' cannot be applied to operands of type \
                                 '{lq}' and '{rq}'",
                            op = b.op,
                            lq = pg_type_to_pyql(lt),
                            rq = pg_type_to_pyql(rt),
                        ),
                        position: Position { line: 0, col: 0 },
                    }));
                }
                Ok(IrExpr::BinOp(Box::new(IrBinOp {
                    left: true_division_operand(&b.op, left, &right),
                    op: b.op.clone(),
                    right,
                })))
            }

            Expr::FunctionCall(f) => {
                // notify(Channel, payload) / notify_raw(name, payload) → pg_notify(...).
                // Works in both free and schema-bound context (unlike sequence_next
                // below) since a trigger handler's payload needs __new__/__old__,
                // which only ever resolves schema-bound.
                if (f.module.is_none() || f.module.as_deref() == Some("std")) && f.name == "notify" {
                    return self.compile_notify(f, ctx);
                }
                if (f.module.is_none() || f.module.as_deref() == Some("std")) && f.name == "notify_raw" {
                    return self.compile_notify_raw(f, ctx);
                }

                // sequence_next / sequence_reset: type-ref arg → nextval/setval SQL
                // (free-only: schema-bound context never special-cased this).
                if ctx.is_none()
                    && (f.module.is_none() || f.module.as_deref() == Some("std"))
                    && (f.name == "sequence_next" || f.name == "sequence_reset")
                {
                    return self.compile_sequence_fn(f);
                }

                // assert_single(subquery) [free-only] / assert_single|assert_exists|
                // assert_distinct(subquery) [schema-bound] → _pylon.<fn>(ARRAY(subquery)).
                // Preserves the existing asymmetry: free context only ever recognized
                // "assert_single" here, not the other two.
                let assert_names: &[&str] = if ctx.is_some() {
                    &["assert_single", "assert_exists", "assert_distinct"]
                } else {
                    &["assert_single"]
                };
                if (f.module.is_none() || f.module.as_deref() == Some("std"))
                    && assert_names.contains(&f.name.as_str())
                    && !f.args.is_empty()
                    && let Expr::SubQuery(inner_stmt) = &f.args[0]
                {
                    let inner = match self.relative_subselect(inner_stmt, ctx)? {
                        Some(ps) => IrArraySource::PathSelect(Box::new(ps)),
                        None => self.compile_subquery_to_array_source(inner_stmt)?,
                    };
                    let fn_pg = match f.name.as_str() {
                        "assert_single" => "assert_single",
                        "assert_exists" => "assert_exists",
                        _ => "assert_distinct",
                    };
                    let mut args = vec![IrExpr::ArrayFromSelect(Box::new(inner))];
                    args.extend(self.assert_message(f, ctx)?);
                    return Ok(IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: Some("_pylon".to_string()),
                        name: fn_pg.to_string(),
                        args,
                        sql_template: None,
                    }));
                }

                // contains(.multilink.scalar, value) → EXISTS (set-membership
                // semantics; schema-bound only, needs td/alias to resolve the
                // multilink).
                if let Some((td, alias)) = ctx
                    && (f.module.is_none() || f.module.as_deref() == Some("std"))
                    && f.name == "contains"
                    && f.args.len() == 2
                    && let Expr::Path(p) = &f.args[0]
                    && p.partial
                    && p.steps.len() >= 2
                    && let ast::PathStep::Name(ln) = &p.steps[0]
                    && Self::resolve_multilink(td, ln).is_some()
                {
                    let synthetic = ast::BinOp {
                        left: f.args[0].clone(),
                        op: ast::BinOpKind::Eq,
                        right: f.args[1].clone(),
                    };
                    if let Some(exists) = self.try_multilink_exists(&synthetic, td, alias)? {
                        return Ok(exists);
                    }
                }

                // Single-arg aggregate over a schema-shaped source →
                // AggOverQuery. Schema-bound: count(.multilink) correlates via
                // the junction/FK table (`.multilink` isn't an ordinary scalar
                // path). Free: count(TypeName) / count((select TypeName ...))
                // resolves the arg as a schema type reference or subquery.
                if f.args.len() == 1
                    && f.kwargs.is_empty()
                    && let Some(mut ps) = self.compile_shape_field_select(&f.args[0], ctx)?
                {
                    let IrPathResult::Scalar(column, _) = ps.result else {
                        return Err(self.type_err("a shape's pointer read off a walk is a value"));
                    };
                    let ns = f.module.as_deref().unwrap_or("std");
                    let aggregate =
                        crate::stdlib::lookup(ns, &f.name)
                            .into_iter()
                            .find_map(|d| match &d.impl_strategy {
                                crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => {
                                    Some(sql_name.to_string())
                                }
                                _ => None,
                            });
                    let Some(sql_name) = aggregate else {
                        return Err(self.type_err(&format!(
                            "'{}' over a shape's pointer read off a walk needs an aggregate",
                            f.name
                        )));
                    };
                    // Over no rows SQL's aggregates give NULL where PyQL's
                    // give the empty set's own value.
                    let over_nothing = aggregate_over_nothing_sql(&f.name);
                    // An unnested set cannot sit inside the aggregate call;
                    // the walk's rows are aggregated from outside instead.
                    let subquery = if matches!(&column, IrExpr::FunctionCall(f) if f.name == "unnest" && f.sql_template.is_none())
                    {
                        ps.result = IrPathResult::Scalar(column, None);
                        IrExpr::FunctionCall(IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: sql_name.clone(),
                            args: vec![IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(
                                ps,
                            ))))],
                            sql_template: Some(format!(
                                "(SELECT {sql_name}(\"_s\".\"v\") FROM unnest($1) AS \"_s\"(\"v\"))"
                            )),
                        })
                    } else {
                        let aggregate = IrExpr::FunctionCall(IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: sql_name,
                            args: vec![column],
                            sql_template: None,
                        });
                        ps.result = IrPathResult::Scalar(aggregate, None);
                        IrExpr::PathSubquery(Box::new(ps))
                    };
                    return Ok(match over_nothing {
                        Some(value) => IrExpr::FunctionCall(IrFunctionCall {
                            return_pg_type: None,
                            schema: None,
                            name: "coalesce".to_string(),
                            args: vec![subquery, IrExpr::RawSql(value.to_string())],
                            sql_template: None,
                        }),
                        None => subquery,
                    });
                }
                if f.args.len() == 1 {
                    let arg = &f.args[0];
                    // `count(a intersect b)` counts what the operation yields.
                    // Read as an array it would count the array: always one.
                    if matches!(arg, Expr::Intersect(_, _) | Expr::Except(_, _)) {
                        use crate::stdlib::{ImplStrategy, lookup};
                        let ns = f.module.as_deref().unwrap_or("std");
                        let best = lookup(ns, &f.name)
                            .iter()
                            .find(|d| d.params.len() == 1)
                            .map(|d| d.impl_strategy.clone());
                        if let Some(ImplStrategy::SqlBuiltin(sql_name)) = best
                            && let IrExpr::SetOp { op, left, right, .. } = self.compile_expr_ctx(arg, ctx)?
                        {
                            return Ok(IrExpr::SetOp {
                                op,
                                left,
                                right,
                                mode: super::SetOpMode::Aggregate(sql_name.to_string()),
                            });
                        }
                    }
                    // `array_agg(array_unpack(.permissions))` — the elements
                    // of one row's array. PostgreSQL rejects a set-returning
                    // call inside an aggregate, so the unpacking becomes the
                    // row source the aggregate reads.
                    if let Expr::FunctionCall(unpack) = arg
                        && unpack.module.as_deref().unwrap_or("std") == "std"
                        && unpack.name == "array_unpack"
                        && unpack.kwargs.is_empty()
                        && let [array] = unpack.args.as_slice()
                        && let Some(sql_name) = crate::stdlib::lookup(f.module.as_deref().unwrap_or("std"), &f.name)
                            .into_iter()
                            .find_map(|d| match &d.impl_strategy {
                                crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => {
                                    Some(sql_name.to_string())
                                }
                                _ => None,
                            })
                    {
                        let values = self.compile_expr_ctx(array, ctx)?;
                        // A walk gathered as an array holds one array per row,
                        // which `unnest` would only flatten one level; that
                        // shape is aggregated where the walk is built instead.
                        if !yields_array(&values) {
                            let over_nothing = aggregate_over_nothing_sql(&f.name).unwrap_or("NULL");
                            return Ok(IrExpr::FunctionCall(IrFunctionCall {
                                return_pg_type: None,
                                schema: None,
                                name: sql_name.clone(),
                                args: vec![values],
                                sql_template: Some(format!(
                                    "(SELECT coalesce({sql_name}(\"_s\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_s\"(\"v\"))"
                                )),
                            }));
                        }
                    }
                    // `sum((select T filter …).amount)` — the sub-select's
                    // values arrive gathered as an array; the aggregate
                    // takes its elements.
                    if matches!(arg, Expr::FieldAccess { .. })
                        && matches!(Self::peel_field_access_chain(arg).0, Expr::SubQuery(_))
                    {
                        let ns = f.module.as_deref().unwrap_or("std");
                        let aggregate =
                            crate::stdlib::lookup(ns, &f.name)
                                .into_iter()
                                .find_map(|d| match &d.impl_strategy {
                                    crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => {
                                        Some(sql_name.to_string())
                                    }
                                    _ => None,
                                });
                        if let Some(sql_name) = aggregate {
                            let values = self.compile_expr_ctx(arg, ctx)?;
                            if matches!(values, IrExpr::ArrayFromSelect(_)) {
                                let over_nothing = aggregate_over_nothing_sql(&f.name).unwrap_or("NULL");
                                return Ok(IrExpr::FunctionCall(IrFunctionCall {
                                    return_pg_type: None,
                                    schema: None,
                                    name: sql_name.clone(),
                                    args: vec![values],
                                    sql_template: Some(format!(
                                        "(SELECT coalesce({sql_name}(\"_s\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_s\"(\"v\"))"
                                    )),
                                }));
                            }
                            return Ok(IrExpr::FunctionCall(IrFunctionCall {
                                return_pg_type: None,
                                schema: None,
                                name: sql_name,
                                args: vec![values],
                                sql_template: None,
                            }));
                        }
                    }
                    // `max(.<pins.updated_at ?? .<pins.created_at)` — the
                    // coalesce picks one whole set, gathered as an array, and
                    // the aggregate takes its elements.
                    if let Expr::BinOp(b) = arg
                        && b.op == ast::BinOpKind::Coalesce
                    {
                        let values = self.compile_expr_ctx(arg, ctx)?;
                        let ns = f.module.as_deref().unwrap_or("std");
                        let aggregate =
                            crate::stdlib::lookup(ns, &f.name)
                                .into_iter()
                                .find_map(|d| match &d.impl_strategy {
                                    crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => {
                                        Some(sql_name.to_string())
                                    }
                                    _ => None,
                                });
                        if let Some(sql_name) = aggregate
                            && yields_array(&values)
                        {
                            let over_nothing = aggregate_over_nothing_sql(&f.name).unwrap_or("NULL");
                            return Ok(IrExpr::FunctionCall(IrFunctionCall {
                                return_pg_type: None,
                                schema: None,
                                name: sql_name.clone(),
                                args: vec![values],
                                sql_template: Some(format!(
                                    "(SELECT coalesce({sql_name}(\"_s\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_s\"(\"v\"))"
                                )),
                            }));
                        }
                        return self.resolve_fn_call(f.module.as_deref(), &f.name, vec![values]);
                    }
                    // `count(memberships)` — a binding names a set, so the
                    // aggregate runs over its rows. Compiled as an ordinary
                    // expression it becomes a scalar subquery over the CTE,
                    // which any binding of more than one row aborts on.
                    if let Some(name) = self.resolve_cte_name(arg) {
                        use crate::stdlib::{ImplStrategy, lookup};
                        let ns = f.module.as_deref().unwrap_or("std");
                        let overloads = lookup(ns, &f.name);
                        let best = overloads
                            .iter()
                            .find(|d| d.params.len() == 1)
                            .or_else(|| overloads.first());
                        if let Some(ImplStrategy::SqlBuiltin(sql_name)) = best.map(|d| &d.impl_strategy)
                            && best.is_some_and(|d| d.params.first().is_some_and(|p| p.ty.is_set()))
                        {
                            let object = self.cte_types.get(name).is_some_and(|bound| bound.contains("::"));
                            return Ok(IrExpr::AggOverCte {
                                fn_name: sql_name.to_string(),
                                cte: name.to_string(),
                                column: (!object).then(|| "v".to_string()),
                            });
                        }
                    }
                    if let Some((td, alias)) = ctx {
                        // `count((select .<promotion filter …))` — compiled as an
                        // expression the sub-select is a scalar subquery, and a
                        // bare aggregate around it aggregates the enclosing select.
                        if let Expr::SubQuery(stmt) = arg
                            && f.name != "array_agg"
                            && let Some(sql_name) = crate::stdlib::lookup(f.module.as_deref().unwrap_or("std"), &f.name)
                                .into_iter()
                                .find_map(|d| match &d.impl_strategy {
                                    crate::stdlib::ImplStrategy::SqlBuiltin(sql_name) if d.is_aggregate() => {
                                        Some(sql_name.to_string())
                                    }
                                    _ => None,
                                })
                            && let Some(mut ps) = self.relative_subselect(stmt, ctx)?
                        {
                            // An object row is an anonymous record, which `unnest` cannot expand.
                            if let IrPathResult::Object { alias, .. } = &ps.result {
                                let id = IrExpr::ColumnRef {
                                    alias: alias.clone(),
                                    column: "id".to_string(),
                                    pg_type: "uuid".to_string(),
                                };
                                ps.result = IrPathResult::Scalar(id, None);
                            }
                            let aggregate = IrExpr::FunctionCall(IrFunctionCall {
                                return_pg_type: None,
                                schema: None,
                                name: sql_name.clone(),
                                args: vec![IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(
                                    ps,
                                ))))],
                                sql_template: Some(format!(
                                    "(SELECT {sql_name}(\"_s\".\"v\") FROM unnest($1) AS \"_s\"(\"v\"))"
                                )),
                            });
                            return Ok(aggregate_over_nothing(&f.name, aggregate));
                        }
                        // `max(items.created_at)` inside a FILTER: the
                        // aggregate takes the whole set the path names, so it
                        // belongs inside a subquery over that set — a bare
                        // `max(...)` here is an aggregate in a WHERE clause,
                        // which Postgres rejects outright.
                        if let Expr::Path(p) = arg
                            && !p.partial
                            && p.steps.len() > 1
                            && let Some(root) = self.find_path_root_in_expr(arg)
                        {
                            let synthetic = ast::SelectStmt {
                                result: Expr::FunctionCall(f.clone()),
                                filter: None,
                                order_by: vec![],
                                offset: None,
                                limit: None,
                                lock: None,
                            };
                            let ps = self.compile_expr_as_path_select(&synthetic, &synthetic.result, &root, false)?;
                            return Ok(aggregate_over_nothing(&f.name, IrExpr::PathSubquery(Box::new(ps))));
                        }
                        // `sum(.applied_promotions.amount)` — the aggregate
                        // takes the set the walk lands on, so the walk becomes
                        // the row source of a correlated subquery the aggregate
                        // sits inside. Compiled as an expression the walk stands
                        // for the array of its elements, leaving the aggregate
                        // with an array argument and no overload to match.
                        // A backlink is as many-valued: `count(.<revisions)`.
                        // So is a computed selecting a set
                        // (`Computed[MultiLink[Member], '.staff']`) — one step,
                        // but the junction-only count below cannot see through
                        // it to a junction table, so it walks the path the
                        // computed splices into instead.
                        if let Expr::Path(p) = arg
                            && p.partial
                            && (p.steps.len() > 1 && self.path_crosses_multi(td, &p.steps)
                                || matches!(p.steps.first(), Some(ast::PathStep::Backlink(_)))
                                || matches!(p.steps.as_slice(), [ast::PathStep::Name(name)]
                                    if Self::resolve_multilink(td, name).is_none()
                                        && self.path_crosses_multi(td, &p.steps)))
                        {
                            let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
                            steps.extend(p.steps.iter().cloned());
                            let rooted = ast::Path { steps, partial: false };
                            let mut call = f.clone();
                            call.args[0] = Expr::Path(rooted);
                            let synthetic = ast::SelectStmt {
                                result: Expr::FunctionCall(call),
                                filter: None,
                                order_by: vec![],
                                offset: None,
                                limit: None,
                                lock: None,
                            };
                            let root = format!("{}::{}", td.module, td.name);
                            let mut ps =
                                self.compile_expr_as_path_select(&synthetic, &synthetic.result, &root, false)?;
                            Self::correlate_path_select(&mut ps, alias);
                            return Ok(aggregate_over_nothing(&f.name, IrExpr::PathSubquery(Box::new(ps))));
                        }
                        if let Expr::Path(p) = arg
                            && p.partial
                            && p.steps.len() == 1
                            && let ast::PathStep::Name(ml_name) = &p.steps[0]
                            && Self::resolve_multilink(td, ml_name).is_some()
                        {
                            use crate::stdlib::{ImplStrategy, lookup};
                            let ns = f.module.as_deref().unwrap_or("std");
                            let overloads = lookup(ns, &f.name);
                            let best = overloads
                                .iter()
                                .find(|d| d.params.len() == 1)
                                .or_else(|| overloads.first());
                            if let Some(ImplStrategy::SqlBuiltin(sql_name)) = best.map(|d| &d.impl_strategy) {
                                let fn_name = sql_name.to_string();
                                let inner = self.multilink_correlation_select(ml_name, td, alias)?;
                                return Ok(IrExpr::AggOverQuery {
                                    fn_name,
                                    inner: Box::new(inner),
                                });
                            }
                        }
                    } else {
                        // `array_agg(a.sessions.id)` with no type in scope: the
                        // aggregate takes the whole set the path names, so it
                        // belongs in a subquery over that traversal. Compiled as
                        // an expression instead, a multi-valued path stands for
                        // the array of its elements, and aggregating *that*
                        // nests it one level deep — the same reason the
                        // schema-bound branch above routes this way.
                        if let Expr::Path(p) = arg
                            && !p.partial
                            && p.steps.len() > 1
                            && let Some(root) = self.find_path_root_in_expr(arg)
                        {
                            let synthetic = ast::SelectStmt {
                                result: Expr::FunctionCall(f.clone()),
                                filter: None,
                                order_by: vec![],
                                offset: None,
                                limit: None,
                                lock: None,
                            };
                            let ps = self.compile_expr_as_path_select(&synthetic, &synthetic.result, &root, false)?;
                            return Ok(aggregate_over_nothing(&f.name, IrExpr::PathSubquery(Box::new(ps))));
                        }
                        // `count((delete AuthLink filter .expired))` — the rows
                        // a mutation touched are countable like any other set.
                        // The mutation becomes its own data-modifying CTE, which
                        // Postgres runs regardless, and the aggregate reads it.
                        if let Expr::SubQuery(stmt) = arg
                            && matches!(stmt.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_))
                        {
                            use crate::stdlib::{ImplStrategy, lookup};
                            let ns = f.module.as_deref().unwrap_or("std");
                            let overloads = lookup(ns, &f.name);
                            let best = overloads
                                .iter()
                                .find(|d| d.params.len() == 1)
                                .or_else(|| overloads.first())
                                .cloned();
                            if let Some(d) = best
                                && let ImplStrategy::SqlBuiltin(sql_name) = &d.impl_strategy
                            {
                                let fn_name = sql_name.to_string();
                                let (cte_name, type_name) = self.hoist_dml_as_cte(stmt.as_ref())?;
                                let td = self.resolve_type(&type_name)?;
                                let source = IrSource {
                                    poly: None,
                                    type_name: format!("{}::{}", td.module, td.name),
                                    table: self.cte_source_table(&cte_name),
                                    alias: self.fresh_alias(),
                                };
                                let inner = IrSelect::schema_bound(source, Self::pk_returning(td), None);
                                return Ok(IrExpr::AggOverQuery {
                                    fn_name,
                                    inner: Box::new(inner),
                                });
                            }
                        }
                        let inner_sel: Option<ast::SelectStmt> = match arg {
                            Expr::Path(p) if !p.partial => {
                                // Resolve as a schema type if it matches a known type (not enum).
                                let qname = p
                                    .steps
                                    .iter()
                                    .filter_map(|s| {
                                        if let ast::PathStep::Name(n) = s {
                                            Some(n.as_str())
                                        } else {
                                            None
                                        }
                                    })
                                    .collect::<Vec<_>>()
                                    .join("::");
                                let is_schema_type = self
                                    .schema
                                    .types
                                    .iter()
                                    .any(|t| format!("{}::{}", t.module, t.name) == qname || t.name == qname);
                                if is_schema_type {
                                    Some(ast::SelectStmt {
                                        result: arg.clone(),
                                        filter: None,
                                        order_by: vec![],
                                        offset: None,
                                        limit: None,
                                        lock: None,
                                    })
                                } else {
                                    None
                                }
                            }
                            Expr::SubQuery(stmt) => {
                                if let ast::Stmt::Select(inner) = stmt.as_ref() {
                                    Some(inner.clone())
                                } else {
                                    None
                                }
                            }
                            _ => None,
                        };
                        if let Some(sel) = inner_sel {
                            use crate::stdlib::{ImplStrategy, lookup};
                            let ns = f.module.as_deref().unwrap_or("std");
                            let overloads = lookup(ns, &f.name);
                            let best = overloads
                                .iter()
                                .find(|d| d.params.len() == 1)
                                .or_else(|| overloads.first());
                            // `array_agg((select Type.prop))` — the sub-select
                            // walks to a scalar, which has no type name to be a
                            // schema select's subject. It is the same thing as
                            // `array_agg(Type.prop)` with the select's own
                            // modifiers on the walk, which is what
                            // `compile_expr_as_path_select` already builds.
                            // A `distinct` inside the sub-select means the
                            // same as one on the argument, and that is where the
                            // aggregate can act on it.
                            let (inner_result, inner_distinct) = match &sel.result {
                                Expr::UnaryOp(u) if matches!(u.op, ast::UnaryOpKind::Distinct) => (&u.operand, true),
                                other => (other, false),
                            };
                            if let Expr::Path(inner_path) = inner_result
                                && !inner_path.partial
                                && inner_path.steps.len() > 1
                                && let Some(ast::PathStep::Name(root)) = inner_path.steps.first()
                                && let Ok(root_td) = self.resolve_path_root(root)
                                && self
                                    .walk_path_types(root_td, &inner_path.steps[1..], MAX_COMPUTED_SPLICES)
                                    .1
                                    .is_none()
                            {
                                let root = root.clone();
                                let mut inner_call = f.clone();
                                inner_call.args = vec![if inner_distinct {
                                    Expr::UnaryOp(Box::new(ast::UnaryOp {
                                        op: ast::UnaryOpKind::Distinct,
                                        operand: inner_result.clone(),
                                    }))
                                } else {
                                    inner_result.clone()
                                }];
                                let call = ast::SelectStmt {
                                    result: Expr::FunctionCall(inner_call),
                                    ..sel.clone()
                                };
                                let ps = self.compile_expr_as_path_select(&call, &call.result, &root, false)?;
                                return Ok(IrExpr::PathSubquery(Box::new(ps)));
                            }
                            if let Some(d) = best
                                && let ImplStrategy::SqlBuiltin(sql_name) = &d.impl_strategy
                            {
                                let fn_name = sql_name.to_string();
                                let inner_ir = self.compile_select(&sel, &sel.result, false)?;
                                // `array_agg((select brands { * } filter …))` —
                                // an array of the objects, rows and shape
                                // whole; `array_agg(*)` is not an aggregate
                                // Postgres has.
                                if fn_name == "array_agg"
                                    && matches!(inner_ir.rows.as_slice(), [IrRowSource::Bound { .. }])
                                {
                                    return Ok(IrExpr::ArrayFromSelect(Box::new(IrArraySource::ObjectSelect(
                                        Box::new(inner_ir),
                                    ))));
                                }
                                return Ok(IrExpr::AggOverQuery {
                                    fn_name,
                                    inner: Box::new(inner_ir),
                                });
                            }
                        }
                    }
                }

                // A set-valued argument → AggOverSet. Schema-bound as much as
                // free: an aggregate's argument is a set wherever it is written,
                // and each operand is compiled with `ctx` so `.started_at` and
                // the like still resolve. The set/shape arm below used to reject
                // this outright once a schema was in scope, so `set { x :=
                // min({cap, .y}) }` failed where the same call at the top level
                // compiled.
                if let Some(operands) = f.args.iter().find_map(Self::set_operands) {
                    use crate::stdlib::{ImplStrategy, lookup};
                    let ns = f.module.as_deref().unwrap_or("std");
                    let overloads = lookup(ns, &f.name);
                    let best = overloads
                        .iter()
                        .find(|d| d.params.len() == f.args.len())
                        .or_else(|| overloads.first());
                    let (schema, fn_name) = match best.map(|d| &d.impl_strategy) {
                        Some(ImplStrategy::SqlBuiltin(sql_name)) => (None, sql_name.to_string()),
                        Some(_) => {
                            return Err(self.type_err(&format!(
                                "function '{}::{}' cannot be called with a set literal in this context",
                                ns, f.name
                            )));
                        }
                        None => return Err(self.type_err(&format!("function '{}::{}' does not exist", ns, f.name))),
                    };
                    let elems = operands
                        .iter()
                        .map(|e| self.compile_expr_ctx(e, ctx))
                        .collect::<Result<Vec<_>, _>>()?;
                    return Ok(IrExpr::AggOverSet { fn_name, schema, elems });
                }

                // `any(...)`/`all(...)` say outright that the argument is a
                // set, so the comparison inside must not also be warned about.
                // The argument is compiled before `resolve_fn_call` ever sees
                // which function this is, which is why the guard goes here.
                // `any(.grants.account = a and not .grants.deleted)` — every
                // `.grants` in it is the same grant, so the condition holds
                // per grant; compiled term by term, each walked the link on
                // its own.
                if let Some((td, _)) = ctx
                    && f.module.as_deref().unwrap_or("std") == "std"
                    && matches!(f.name.as_str(), "any" | "all")
                    && f.kwargs.is_empty()
                    && let [condition] = f.args.as_slice()
                    && let Some(per_element) = per_element_of_one_multilink(condition, td)
                {
                    let (link, element_condition) = per_element;
                    let condition = if f.name == "all" {
                        Expr::UnaryOp(Box::new(ast::UnaryOp {
                            op: ast::UnaryOpKind::Not,
                            operand: element_condition,
                        }))
                    } else {
                        element_condition
                    };
                    let exists = Expr::UnaryOp(Box::new(ast::UnaryOp {
                        op: ast::UnaryOpKind::Exists,
                        operand: Expr::SubQuery(Box::new(Stmt::Select(ast::SelectStmt {
                            result: Expr::Path(ast::Path {
                                steps: link,
                                partial: true,
                            }),
                            filter: Some(condition),
                            order_by: vec![],
                            offset: None,
                            limit: None,
                            lock: None,
                        }))),
                    }));
                    let exists = if f.name == "all" {
                        Expr::UnaryOp(Box::new(ast::UnaryOp {
                            op: ast::UnaryOpKind::Not,
                            operand: exists,
                        }))
                    } else {
                        exists
                    };
                    return self.compile_expr_ctx(&exists, ctx);
                }
                // `any(.<company.posts is Post)` — one answer per object the
                // path reaches, gathered as an array, so aggregate its elements.
                if f.module.as_deref().unwrap_or("std") == "std"
                    && matches!(f.name.as_str(), "any" | "all")
                    && f.kwargs.is_empty()
                    && let [Expr::TypeIs { expr: subject, ty }] = f.args.as_slice()
                    && let answers @ IrExpr::ArrayFromSelect(_) = self.compile_type_is_set(subject, ty, ctx)?
                {
                    let (aggregate, over_nothing) = if f.name == "all" {
                        ("bool_and", "true")
                    } else {
                        ("bool_or", "false")
                    };
                    return Ok(IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: None,
                        name: aggregate.to_string(),
                        args: vec![answers],
                        sql_template: Some(format!(
                            "(SELECT coalesce({aggregate}(\"_unnested\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_unnested\"(\"v\"))"
                        )),
                    }));
                }
                // `all(array_unpack($tags) in .tags.label)` — the comparison is
                // made once per element, then aggregated. Inlined as `unnest()`
                // the array is a set-returning call, which Postgres refuses in a
                // WHERE; over no elements `all` is true and `any` false.
                if f.module.as_deref().unwrap_or("std") == "std"
                    && matches!(f.name.as_str(), "any" | "all")
                    && f.kwargs.is_empty()
                    && let [Expr::BinOp(comparison)] = f.args.as_slice()
                    && let Expr::FunctionCall(unpack) = &comparison.left
                    && unpack.module.as_deref().unwrap_or("std") == "std"
                    && unpack.name == "array_unpack"
                    && let [array] = unpack.args.as_slice()
                {
                    let array = self.compile_expr_ctx(array, ctx)?;
                    let element = "<unnested element>".to_string();
                    self.inline_bindings
                        .insert(element.clone(), IrExpr::RawSql("\"_unnested\".\"v\"".to_string()));
                    let per_element = self.compile_expr_ctx(
                        &Expr::BinOp(Box::new(ast::BinOp {
                            left: Expr::Path(ast::Path::absolute(element.clone())),
                            op: comparison.op.clone(),
                            right: comparison.right.clone(),
                        })),
                        ctx,
                    );
                    self.inline_bindings.remove(&element);
                    let (aggregate, over_nothing) = if f.name == "all" {
                        ("bool_and", "true")
                    } else {
                        ("bool_or", "false")
                    };
                    return Ok(IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: None,
                        name: aggregate.to_string(),
                        args: vec![per_element?, array],
                        sql_template: Some(format!(
                            "(SELECT coalesce({aggregate}($1), {over_nothing}) FROM unnest($2) AS \"_unnested\"(\"v\"))"
                        )),
                    }));
                }
                if let Some(args) = self.compile_named_call_args(f, ctx)? {
                    return self.resolve_fn_call(f.module.as_deref(), &f.name, args);
                }
                let is_explicit_set = f.module.as_deref().unwrap_or("std") == "std"
                    && matches!(f.name.as_str(), "any" | "all")
                    && f.args.len() == 1;
                let is_universal = is_explicit_set && f.name == "all";
                if is_explicit_set {
                    self.explicit_set_depth += 1;
                }
                if is_universal {
                    self.universal_set_depth += 1;
                }
                let args = f
                    .args
                    .iter()
                    .map(|a| self.compile_expr_ctx(a, ctx))
                    .collect::<Result<Vec<_>, _>>();
                if is_universal {
                    self.universal_set_depth -= 1;
                }
                if is_explicit_set {
                    self.explicit_set_depth -= 1;
                }
                let args = args?;
                // `all(.required_addons in licensed_addons)` — the argument is
                // a set of booleans, gathered as an array the way every other
                // multi-valued expression is, and the quantifier ranges over
                // its elements. Handed the array itself, `bool_and` would
                // aggregate the enclosing query's rows instead.
                if is_explicit_set
                    && let [values] = args.as_slice()
                    && yields_array(values)
                {
                    let (aggregate, over_nothing) = if f.name == "all" {
                        ("bool_and", "true")
                    } else {
                        ("bool_or", "false")
                    };
                    return Ok(IrExpr::FunctionCall(IrFunctionCall {
                        return_pg_type: None,
                        schema: None,
                        name: aggregate.to_string(),
                        args: vec![values.clone()],
                        sql_template: Some(format!(
                            "(SELECT coalesce({aggregate}(\"_s\".\"v\"), {over_nothing}) FROM unnest($1) AS \"_s\"(\"v\"))"
                        )),
                    }));
                }
                self.resolve_fn_call(f.module.as_deref(), &f.name, args)
            }

            Expr::UnaryOp(u) if u.op == ast::UnaryOpKind::Exists => self.compile_exists_ctx(&u.operand, ctx),

            // `distinct` in expression position: a set-producing operand
            // dedupes its own rows, and a single value — an array, a global, a
            // column — is already distinct, so it stands for itself. (A
            // statement-level `select distinct …` never reaches here; it is
            // unwrapped into the select's own `distinct` flag.)
            Expr::UnaryOp(u) if u.op == ast::UnaryOpKind::Distinct => {
                let operand = self.compile_expr_ctx(&u.operand, ctx)?;
                Ok(match operand {
                    IrExpr::PathSubquery(mut ps) => {
                        ps.distinct = true;
                        IrExpr::PathSubquery(ps)
                    }
                    IrExpr::ArrayFromSelect(src) => IrExpr::ArrayFromSelect(Box::new(match *src {
                        IrArraySource::Select(mut sel) => {
                            sel.distinct = true;
                            IrArraySource::Select(sel)
                        }
                        IrArraySource::PathSelect(mut ps) => {
                            ps.distinct = true;
                            IrArraySource::PathSelect(ps)
                        }
                        other => other,
                    })),
                    other => other,
                })
            }

            Expr::UnaryOp(u) => {
                let operand = self.compile_expr_ctx(&u.operand, ctx)?;
                Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: u.op.clone(),
                    operand,
                })))
            }

            Expr::IfElse(ie) => {
                let condition = self.compile_expr_ctx(&ie.condition, ctx)?;
                let if_ = self.compile_expr_ctx(&ie.if_expr, ctx)?;
                let else_ = self.compile_expr_ctx(&ie.else_expr, ctx)?;
                Ok(IrExpr::IfElse(Box::new(IrIfElse { condition, if_, else_ })))
            }

            Expr::Array(elems) => {
                // Each element is one value: `[<uuid>$p, snippet.id]` is two
                // uuids, not a uuid beside an array of them — PostgreSQL
                // refuses to mix the two in one literal.
                let items = elems
                    .iter()
                    .map(|e| self.compile_expr_ctx(e, ctx).map(set_walk_as_scalar))
                    .collect::<Result<Vec<_>, _>>()?;
                Ok(IrExpr::Array(items))
            }

            Expr::NamedTuple(fields) => {
                let ir = fields
                    .iter()
                    .map(|(name, e)| Ok((name.clone(), self.compile_expr_ctx(e, ctx)?)))
                    .collect::<Result<Vec<_>, PyQLError>>()?;
                Ok(IrExpr::NamedTuple {
                    fields: ir,
                    is_free_object: false,
                })
            }

            Expr::Tuple(elems) => {
                let ir = elems
                    .iter()
                    .map(|e| self.compile_expr_ctx(e, ctx))
                    .collect::<Result<Vec<_>, PyQLError>>()?;
                Ok(IrExpr::Tuple(ir))
            }

            Expr::FieldAccess { expr: inner, field } => {
                // `(select …).provider[is Individual].staff` arrives here, not
                // at the `PathStepOn` arm: the trailing `.staff` is outermost.
                if let Some(ir) = self.try_compile_walk_off_subquery(expr, ctx)? {
                    return Ok(ir);
                }
                if let Expr::NamedTuple(fields) = inner.as_ref() {
                    let (_, val) = fields.iter().find(|(k, _)| k == field).ok_or_else(|| {
                        self.type_err(&format!("{field} is not a member of {}", named_tuple_type_str(fields)))
                    })?;
                    return self.compile_expr_ctx(val, ctx);
                }
                if let Some(ps) = self.compile_shape_field_select(expr, ctx)? {
                    return Ok(IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(
                        ps,
                    )))));
                }
                // `(select .emails filter .primary limit 1).address` — the
                // field chain is spliced onto the sub-select's own path so
                // the subquery projects that column, rather than being read
                // as jsonb extraction off an object id.
                let (base, fields) = Self::peel_field_access_chain(expr);
                if let Expr::SubQuery(stmt) = base {
                    let stmt = stmt.as_ref().clone();
                    return self.compile_subquery_expr(&stmt, &fields, ctx, &[]);
                }
                // `account::owner(.id).name` — an object-returning function
                // projected to one of its columns.
                if let Expr::FunctionCall(fc) = base {
                    let fc = fc.clone();
                    if let Some(ir) = self.try_compile_fn_scalar_subquery(&fc, &fields, None, ctx)? {
                        return Ok(ir);
                    }
                }
                let ir = self.compile_expr_ctx(inner, ctx)?;
                Ok(Self::project_free_object_field(ir, field))
            }

            Expr::TupleIndex { expr: inner, index } => {
                match inner.as_ref() {
                    Expr::Tuple(elems) => {
                        let elem = elems.get(*index).ok_or_else(|| {
                            self.type_err(&format!(
                                "{index} is not a member of {}",
                                positional_tuple_type_str(elems)
                            ))
                        })?;
                        self.compile_expr_ctx(elem, ctx)
                    }
                    Expr::NamedTuple(fields) => {
                        let (_, val) = fields.get(*index).ok_or_else(|| {
                            self.type_err(&format!("{index} is not a member of {}", named_tuple_type_str(fields)))
                        })?;
                        self.compile_expr_ctx(val, ctx)
                    }
                    // Not a literal to constant-fold — emit a generic runtime
                    // jsonb positional access (`$param.1`, `(<tuple<...>>expr).1`, …).
                    // When the source is a cast to a statically-known tuple type,
                    // bounds-check the index against its arity at compile time
                    // (e.g. `2 is not a member of tuple<std::int64, std::str>`).
                    _ => {
                        if let Expr::TypeCast(tc) = inner.as_ref()
                            && let Some(shape) = self.resolve_tuple_cast_shape(&tc.ty)
                            && *index >= shape.members.len()
                        {
                            return Err(self.type_err(&format!(
                                "{index} is not a member of {}",
                                self.type_expr_to_display_str(&tc.ty)
                            )));
                        }
                        let ir = self.compile_expr_ctx(inner, ctx)?;
                        Ok(IrExpr::JsonbIndex {
                            expr: Box::new(ir),
                            index: *index,
                        })
                    }
                }
            }

            // `detached` bypasses the implicit root-matches-td correlation
            // rewrite. Schema-bound: if `inner` contains a type-rooted path,
            // compile it as an independent PathSubquery; otherwise (or when
            // already free) fall back to compiling `inner` with NO schema
            // binding — note this fallback is deliberately `None`, not
            // `ctx`, since `detached` means "evaluate independently of the
            // enclosing scope" and free context has no rooted path to find
            // in the first place (`find_path_root_in_expr` only ever matches
            // against a resolvable schema type name).
            Expr::Detached(inner) => {
                if ctx.is_some()
                    && let Some(root) = self.find_path_root_in_expr(inner)
                {
                    let synthetic = ast::SelectStmt {
                        result: (**inner).clone(),
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        lock: None,
                    };
                    let ps = self.compile_expr_as_path_select(&synthetic, inner, &root, false)?;
                    return Ok(IrExpr::PathSubquery(Box::new(ps)));
                }
                self.compile_expr_ctx(inner, None)
            }

            // Free context tolerates an empty set (-> Null) or a singleton
            // set (-> its one element) as a convenience; a schema-bound
            // expression position hard-errors on ANY set literal instead
            // (see the generic Shape|Set arm below) — a plausibly
            // intentional semantic difference, preserved exactly as-is.
            Expr::Set(elems) if ctx.is_none() && elems.is_empty() => Ok(IrExpr::Null),

            Expr::Set(elems) if ctx.is_none() => {
                let compiled: Result<Vec<_>, _> = elems.iter().map(|e| self.compile_expr_ctx(e, ctx)).collect();
                let mut compiled = compiled?;
                if compiled.len() == 1 {
                    Ok(compiled.remove(0))
                } else {
                    Err(self.type_err("multi-element set literal is not supported in free SELECT context"))
                }
            }

            // A free object literal (`{ foo := 'bar' }`, no subject type) is
            // valid anywhere an expression is, not just as a whole SELECT's
            // result — e.g. nested inside a computed shape element. Compiled
            // the same way `compile_free_select` treats it at the top level
            // (each field compiled independently, ctx propagated so a
            // schema-bound nested free object can still reference `.name`
            // etc.), just wrapped as `IrExpr::NamedTuple` (jsonb) instead of
            // a whole result row, since here it's a value, not a row source.
            // is_free_object: true — this came from curly-brace shape syntax,
            // not a paren tuple literal, so the value-shape-tag tree
            // (pylon/query.py's shape_value_tags) can tell the frontend to
            // render it as an expandable "Object {...}", not a `(...)`
            // tuple literal (see ShapeNode::NamedTuple's own doc comment).
            Expr::Shape(s) if s.expr.is_none() => {
                let fields = s
                    .elements
                    .iter()
                    .map(|el| -> Result<(String, IrExpr), PyQLError> {
                        let name = path_leaf(&el.path)?.to_string();
                        let expr = el.compexpr.as_ref().ok_or_else(|| {
                            self.type_err("free object field must have a value expression (':= expr')")
                        })?;
                        let compiled = match expr {
                            Expr::SubQuery(stmt)
                                if matches!(stmt.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) =>
                            {
                                self.dml_as_value(stmt.as_ref())?
                            }
                            other => match self.free_object_link_field(other)? {
                                Some(object) => object,
                                None => self.compile_expr_ctx(other, ctx)?,
                            },
                        };
                        Ok((name, compiled))
                    })
                    .collect::<Result<Vec<_>, _>>()?;
                Ok(IrExpr::NamedTuple {
                    fields,
                    is_free_object: true,
                })
            }

            // A shape applied to a WITH-bound free object (`test := test {
            // test2 }` where `test` isn't a schema object, just a free
            // binding) projects the named fields out of it — each element
            // either reads the underlying field (by name, via the same
            // per-field CTE column `.field` access uses) or, with a `:=`
            // override, compiles a brand new value in the current context,
            // exactly like a fresh free-object-literal field would.
            Expr::Shape(s) if matches!(&s.expr, Some(inner) if self.is_free_cte_ref(inner)) => {
                let Some(Expr::Path(root_path)) = &s.expr else {
                    unreachable!()
                };
                let ast::PathStep::Name(root) = &root_path.steps[0] else {
                    unreachable!()
                };
                let fields = s
                    .elements
                    .iter()
                    .map(|el| -> Result<(String, IrExpr), PyQLError> {
                        let name = path_leaf(&el.path)?.to_string();
                        let expr = match &el.compexpr {
                            Some(over) => self.compile_expr_ctx(over, ctx)?,
                            None => match self.resolve_cte_field_chain(root, &[name.as_str()]) {
                                Some(result) => result?,
                                None => {
                                    return Err(self.type_err(&format!("free object '{root}' has no field '{name}'")));
                                }
                            },
                        };
                        Ok((name, expr))
                    })
                    .collect::<Result<Vec<_>, _>>()?;
                Ok(IrExpr::NamedTuple {
                    fields,
                    is_free_object: true,
                })
            }

            // `(.<prices[is Listing] union .<sale_prices[is Listing]) { id }`
            // — each operand hangs off the enclosing row, so none can be
            // hoisted into a CTE the way a standalone union's operands are.
            Expr::Shape(sh)
                if ctx.is_some()
                    && matches!(sh.expr.as_ref(), Some(Expr::Union(_, _)))
                    && Self::union_of_relative_paths(sh.expr.as_ref().expect("checked")).is_some() =>
            {
                let (td, alias) = ctx.expect("checked by the guard");
                let operands =
                    Self::union_of_relative_paths(sh.expr.as_ref().expect("checked")).expect("checked by the guard");
                let elements = sh.elements.clone();
                let multi = self.relative_paths_reach_many(td, &operands);
                let mut branches = Vec::with_capacity(operands.len());
                for path in operands {
                    let mut steps = vec![ast::PathStep::Name(format!("{}::{}", td.module, td.name))];
                    steps.extend(path.steps.iter().cloned());
                    let rooted = ast::Path { steps, partial: false };
                    let synthetic = ast::SelectStmt {
                        result: Expr::Path(rooted.clone()),
                        filter: None,
                        order_by: vec![],
                        offset: None,
                        limit: None,
                        lock: None,
                    };
                    let mut ps = self.compile_path_select(&synthetic, &rooted, &elements, false)?;
                    Self::correlate_path_select(&mut ps, alias);
                    branches.push(ps);
                }
                Ok(IrExpr::ObjectPathUnion {
                    branches,
                    limit: None,
                    multi,
                })
            }

            // `([is Conditional].configs ?? [is Loop].configs) { … }` — the
            // same correlated walks a union of them gives, except each operand
            // after the first only stands in when the ones before it are empty.
            Expr::Shape(sh)
                if ctx.is_some() && sh.expr.as_ref().and_then(Self::coalesce_of_relative_paths).is_some() =>
            {
                let (td, alias) = ctx.expect("checked by the guard");
                let operands =
                    Self::coalesce_of_relative_paths(sh.expr.as_ref().expect("checked")).expect("checked by the guard");
                let multi = self.relative_paths_reach_many(td, &operands);
                let branches = self.coalesce_path_branches(td, alias, &operands, &sh.elements)?;
                Ok(IrExpr::ObjectPathUnion {
                    branches,
                    limit: None,
                    multi,
                })
            }

            Expr::Shape(sh) if matches!(sh.expr.as_ref(), Some(Expr::SubQuery(_))) => {
                let sh = sh.clone();
                match self.shape_over_subquery(&sh)? {
                    Some(ir) => Ok(ir),
                    None => Err(PyQLError::Type(PyQLTypeError {
                        message: "shapes and set literals are not valid in expression context".into(),
                        position: Position { line: 0, col: 0 },
                    })),
                }
            }

            Expr::Shape(sh) if Self::shape_over_subquery_projection(sh).is_some() => {
                let (stmt, fields) = Self::shape_over_subquery_projection(sh).expect("checked by the guard");
                let stmt = stmt.clone();
                let elements = sh.elements.clone();
                self.compile_subquery_expr(&stmt, &fields, ctx, &elements)
            }

            // `account := account if cond else {}` — the empty set is a legal
            // expression and means "no value", which is what the
            // assignment paths already spell `IrExpr::Null`. Only a *non-empty*
            // set literal has no expression-position meaning.
            Expr::Set(items) if items.is_empty() => Ok(IrExpr::Null),

            Expr::Shape(sh)
                if matches!(sh.expr.as_ref(), Some(Expr::Path(p))
                    if !p.partial
                        && matches!(p.steps.first(), Some(ast::PathStep::Name(n))
                            if self.cte_object_type(n).is_some() || self.for_var_types.contains_key(n))) =>
            {
                let expr = expr.clone();
                match self.shape_over_binding(&expr)? {
                    Some(ir) => Ok(ir),
                    None => Err(PyQLError::Type(PyQLTypeError {
                        message: "shapes and set literals are not valid in expression context".into(),
                        position: Position { line: 0, col: 0 },
                    })),
                }
            }

            // A bare shape or set literal is never valid in expression
            // position, in either context — preserved exactly as the
            // schema-bound side always enforced (the free side's more
            // permissive empty/singleton-set handling above is the one
            // deliberate exception, handled before this arm).
            Expr::Shape(_) | Expr::Set(_) => Err(PyQLError::Type(PyQLTypeError {
                message: "shapes and set literals are not valid in expression context".into(),
                position: Position { line: 0, col: 0 },
            })),

            // A `select` over a path compiles to a correlated subquery; DML
            // and everything else still has no expression-position meaning.
            // Union/Except previously fell through free's generic "not valid
            // in free SELECT context" catch-all — these explicit,
            // purpose-written messages (already used schema-bound) apply
            // equally well with no schema in scope, so they're unconditional
            // here rather than ctx-gated.
            Expr::SubQuery(stmt) => {
                let stmt = stmt.as_ref().clone();
                self.compile_subquery_expr(&stmt, &[], ctx, &[])
            }

            Expr::Union(_, _) => Err(PyQLError::Type(PyQLTypeError {
                message: "union is not valid in expression context".into(),
                position: Position { line: 0, col: 0 },
            })),

            // `array_unpack(a) intersect array_unpack(b)` — a set operation
            // between two set-valued expressions is itself a set, which in
            // expression position is the array of what it yields.
            Expr::Except(left, right) | Expr::Intersect(left, right) => {
                let op = if matches!(expr, Expr::Intersect(_, _)) {
                    super::SetOpKind::Intersect
                } else {
                    super::SetOpKind::Except
                };
                let left = self.compile_expr_ctx(left, ctx)?;
                let right = self.compile_expr_ctx(right, ctx)?;
                Ok(IrExpr::SetOp {
                    op,
                    left: Box::new(left),
                    right: Box::new(right),
                    mode: super::SetOpMode::Array,
                })
            }

            // TypeIs (`expr is Type`) is schema-exclusive — compile_type_is
            // deeply needs td/alias throughout (interface checks, __type__
            // column, alias-scoped bool expr). No free-context equivalent
            // existed before the merge (fell to the generic catch-all); this
            // is a new, clearer explicit error for that case.
            Expr::TypeIs { expr, ty } => match ctx {
                Some((td, alias)) => self.compile_type_is(expr, ty, td, alias),
                None => match expr.as_ref() {
                    Expr::Path(p) => self.compile_path_type_is(p, ty, None),
                    _ => Err(self.type_err("'is' type check is not valid in free SELECT context")),
                },
            },
        }
    }

    fn compile_expr(&mut self, expr: &Expr, td: &TypeDescriptor, alias: &str) -> Result<IrExpr, PyQLError> {
        self.compile_expr_ctx(expr, Some((td, alias)))
    }

    fn compile_free_expr(&mut self, expr: &Expr) -> Result<IrExpr, PyQLError> {
        self.compile_expr_ctx(expr, None)
    }

    /// `path is T`: whether the objects `path` reaches are of `T` or one of
    /// its subtypes, read off their own `__type__`.
    fn compile_path_type_is(
        &mut self,
        path: &ast::Path,
        ty: &ast::TypeExpr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        let (ty_module, ty_name) = ty
            .as_named()
            .ok_or_else(|| self.type_err("cannot use IS with a tuple or array type"))?;
        let check_qname = match (ty_module, ctx) {
            (Some(module), _) => format!("{module}::{ty_name}"),
            (None, Some((td, _))) => format!("{}::{}", td.module, ty_name),
            (None, None) => ty_name.to_string(),
        };
        let check_td = self.resolve_type(&check_qname)?;
        let check_qname = format!("{}::{}", check_td.module, check_td.name);
        let mut type_path = path.clone();
        type_path.steps.push(ast::PathStep::Name("__type__".to_string()));
        let own_type = self.compile_expr_ctx(&Expr::Path(type_path), ctx)?;
        let implementors: Vec<String> = self
            .find_poly_implementors(&check_qname)
            .into_iter()
            .map(|implementor| implementor.type_name)
            .collect();
        let is_one_of = |own_type: IrExpr| {
            implementors
                .iter()
                .map(|implementor| {
                    IrExpr::BinOp(Box::new(IrBinOp {
                        left: own_type.clone(),
                        op: ast::BinOpKind::Eq,
                        right: IrExpr::Literal(IrLiteral::Str(implementor.clone())),
                    }))
                })
                .reduce(|left, right| {
                    IrExpr::BinOp(Box::new(IrBinOp {
                        left,
                        op: ast::BinOpKind::Or,
                        right,
                    }))
                })
                .unwrap_or(IrExpr::Literal(IrLiteral::Bool(false)))
        };
        // A path that reaches many objects yields one answer per object.
        Ok(match own_type {
            IrExpr::ArrayFromSelect(source) => match *source {
                IrArraySource::PathSelect(mut path_select) => {
                    let IrPathResult::Scalar(element, cast) = path_select.result else {
                        return Err(self.type_err("'__type__' is read as a value"));
                    };
                    path_select.result = IrPathResult::Scalar(is_one_of(element), cast);
                    IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(path_select)))
                }
                other => is_one_of(IrExpr::ArrayFromSelect(Box::new(other))),
            },
            single => is_one_of(single),
        })
    }

    fn compile_type_is(
        &mut self,
        expr: &Expr,
        ty: &ast::TypeExpr,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        self.compile_type_is_inner(expr, ty, td, alias, false)
    }

    /// `expr is T` read as every answer it gives rather than as one value:
    /// naming a type other than the scope's asks the question once per row
    /// of that type. A shape pointer keeps that whole set and `any()`/`all()`
    /// fold it, where a boolean position — a FILTER, an `if` condition — can
    /// only take a single value and goes through `compile_type_is`.
    fn compile_type_is_set(
        &mut self,
        expr: &Expr,
        ty: &ast::TypeExpr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        match ctx {
            Some((td, alias)) => self.compile_type_is_inner(expr, ty, td, alias, true),
            None => match expr {
                Expr::Path(p) => self.compile_path_type_is(p, ty, None),
                _ => Err(self.type_err("'is' type check is not valid in free SELECT context")),
            },
        }
    }

    fn compile_type_is_inner(
        &mut self,
        expr: &Expr,
        ty: &ast::TypeExpr,
        td: &TypeDescriptor,
        alias: &str,
        set_valued: bool,
    ) -> Result<IrExpr, PyQLError> {
        let self_qname = format!("{}::{}", td.module, td.name);

        // `.listing is T`, `x is T`: the objects the path reaches are tested,
        // not the current row — through their own `__type__`.
        let reaches_other_objects = match expr {
            Expr::Path(p) if p.partial || p.steps.len() > 1 => {
                !matches!(p.steps.last(), Some(ast::PathStep::Name(n)) if n == "__type__")
            }
            Expr::Path(p) => matches!(
                p.steps.as_slice(),
                [ast::PathStep::Name(n)] if n != &td.name && n != &self_qname && self.resolve_type(n).is_err()
                    && self.resolve_name_ref(n, true).is_some()
            ),
            _ => false,
        };
        if reaches_other_objects && let Expr::Path(p) = expr {
            return self.compile_path_type_is(p, ty, Some((td, alias)));
        }

        // Determine whether `expr` refers to the current scope or a different type.
        // A 1-step absolute path matching the current td → same scope.
        let (source_qname, cross_scope) = match expr {
            Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    if n == &td.name || n == &self_qname || self.scope_answers_to(n, &self_qname) {
                        (self_qname.clone(), false)
                    } else {
                        // Attempt to resolve as another type.
                        match self.resolve_type(n) {
                            Ok(other) => (format!("{}::{}", other.module, other.name), true),
                            Err(_) => (self_qname.clone(), false),
                        }
                    }
                } else {
                    (self_qname.clone(), false)
                }
            }
            _ => (self_qname.clone(), false),
        };

        let (ty_module, ty_name) = ty
            .as_named()
            .ok_or_else(|| self.type_err("cannot use IS with a tuple or array type"))?;
        let check_module = ty_module.unwrap_or(td.module.as_str());
        let check_qname = format!("{}::{}", check_module, ty_name);
        self.resolve_type(&check_qname)?;

        if !cross_scope {
            // Scalar bool using the current alias.
            return Ok(self.type_check_bool_expr(&source_qname, &check_qname, td, alias));
        }

        // Cross-scope: ARRAY(SELECT bool_expr FROM source_table).
        // Collect everything needed before calling fresh_alias (which needs &mut self).
        let src_alias = self.fresh_alias();
        let src_td = self.resolve_type(&source_qname)?;
        let source_table = src_td.table.clone();
        let (poly_implementors, poly_columns) = if self.is_polymorphic(src_td) {
            (
                self.find_poly_implementors(&source_qname),
                Self::poly_dml_columns(src_td),
            )
        } else {
            (vec![], vec![])
        };
        let bool_expr = self.type_check_bool_expr(&source_qname, &check_qname, src_td, &src_alias);

        // Whenever the answer is the same for every row of the source,
        // `type_check_bool_expr` settles it with a literal. There is nothing
        // to iterate then, and a constant is what a boolean position can
        // consume: `ARRAY(SELECT FALSE FROM "Brand")` is a `boolean[]`, which
        // Postgres refuses outright as a CASE/WHEN condition or a WHERE
        // clause.
        if !set_valued && matches!(bool_expr, IrExpr::Literal(IrLiteral::Bool(_))) {
            return Ok(bool_expr);
        }

        let source = IrSource {
            poly: None,
            type_name: source_qname.clone(),
            table: source_table,
            alias: src_alias,
        };

        let answers = IrExpr::ArrayFromSelect(Box::new(IrArraySource::RawExpr {
            source,
            poly_implementors,
            poly_columns,
            expr: bool_expr,
        }));
        if set_valued {
            return Ok(answers);
        }
        // What is left really does differ per row of the source, so it still
        // has to collapse to one value here — empty answers nothing, more
        // than one row aborts. The message says which check asked and over
        // what, since `assert_single` appears nowhere in the query that
        // triggers it and its own wording sends the reader looking for a call
        // they never wrote.
        Ok(IrExpr::FunctionCall(IrFunctionCall {
            return_pg_type: None,
            schema: Some("_pylon".to_string()),
            name: "assert_single".to_string(),
            args: vec![
                answers,
                IrExpr::Literal(IrLiteral::Str(format!(
                    "'{source_qname} is {check_qname}' is asked once for every {source_qname} object, \
                     so it is not the single value a filter or an 'if' condition needs — narrow it to \
                     one object, or name the type being selected"
                ))),
            ],
            sql_template: None,
        }))
    }

    /// Build the boolean `IrExpr` for `source_qname is check_qname` in the current row's scope.
    fn type_check_bool_expr(&self, source_qname: &str, check_qname: &str, td: &TypeDescriptor, alias: &str) -> IrExpr {
        if check_qname == source_qname || Self::is_or_implements(td, check_qname) {
            return IrExpr::Literal(IrLiteral::Bool(true));
        }
        if !self.is_polymorphic(td) {
            return IrExpr::Literal(IrLiteral::Bool(false));
        }
        // A row is of the checked type when its own type is that type or one
        // of its subtypes — but only the ones this source can actually hold
        // are worth asking about, since its rows carry one of *its* own
        // implementors in `__type__` and nothing else. Across two disjoint
        // hierarchies (`brand::Brand is brand::CustomBrief`) nothing is left
        // and the answer is false for every row; where nothing is ruled out
        // it is true for every row. Both are decided here rather than per
        // row, which is what keeps a check over another type out of the
        // per-row machinery in `compile_type_is_inner` — asking it once per
        // row of a three-row table is what made a filter fail the
        // single-value check it has to pass.
        let reachable: Vec<String> = self
            .find_poly_implementors(source_qname)
            .into_iter()
            .map(|implementor| implementor.type_name)
            .collect();
        let matching: Vec<String> = self
            .find_poly_implementors(check_qname)
            .into_iter()
            .map(|implementor| implementor.type_name)
            .filter(|type_name| reachable.contains(type_name))
            .collect();
        if matching.is_empty() {
            return IrExpr::Literal(IrLiteral::Bool(false));
        }
        if matching.len() == reachable.len() {
            return IrExpr::Literal(IrLiteral::Bool(true));
        }
        matching
            .into_iter()
            .map(|type_name| {
                IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: alias.to_string(),
                        column: "__type__".into(),
                        pg_type: "text".into(),
                    },
                    op: crate::parse::ast::BinOpKind::Eq,
                    right: IrExpr::Literal(IrLiteral::Str(type_name)),
                }))
            })
            .reduce(|left, right| {
                IrExpr::BinOp(Box::new(IrBinOp {
                    left,
                    op: crate::parse::ast::BinOpKind::Or,
                    right,
                }))
            })
            .unwrap_or(IrExpr::Literal(IrLiteral::Bool(false)))
    }

    /// Shared lookup for a bare 1-step name: for-loop variable, CTE binding,
    /// or function parameter. Used by both `compile_path`'s schema-bound
    /// prefix and `compile_free_path`.
    ///
    /// `allow_fn_param` used to be `false` from `compile_path`, so a parameter
    /// resolved only in free context. An object-returning body like
    /// `select Item filter .rank = v` compiles its filter against a schema
    /// anchor, so it never consulted `fn_params` and rejected the bare `v` as
    /// "absolute paths are not valid in expression context" — while the same
    /// parameter in a scalar-returning body worked, which is why the gap went
    /// unnoticed. A bare one-step name can only be a variable, CTE binding or
    /// parameter in either context (a property is always written `.name`), so
    /// there is nothing here for a parameter to shadow.
    fn resolve_name_ref(&mut self, name: &str, allow_fn_param: bool) -> Option<IrExpr> {
        if self.for_vars.contains_key(name) {
            return Some(self.for_var_ref(name));
        }
        // A free-object-bound CTE (`with x := { a := 1 } select ... x ...`),
        // referenced bare with no shape to project through, has nothing to
        // expose — a free *object* needs an explicit shape to know what to
        // return (unlike a tuple/named tuple, it has no "default"
        // projection), so this collapses to an empty free object, the same
        // as `Expr::Shape`'s `is_free_cte_ref` case for `x { ... }`.
        // It also sidesteps a real problem: this CTE has no "v" column
        // (only `IrFreeExpr::Scalar` CTEs get one), so falling through to
        // the generic `IrExpr::CteRef` below would reference a column that
        // doesn't exist.
        if let Some(IrFreeExpr::FreeObject(_)) = self.cte_free_items.get(name) {
            return Some(IrExpr::NamedTuple {
                fields: vec![],
                is_free_object: true,
            });
        }
        if let Some(ir) = self.inline_bindings.get(name) {
            return Some(ir.clone());
        }
        if let Some(t) = self.cte_types.get(name) {
            // A scalar binding records its pg type here (see `cte_stmt_type`);
            // an object binding records a `module::Type` name, which is not a
            // pg type and must not be handed to type inference.
            let scalar = !t.contains("::");
            return Some(IrExpr::CteRef {
                name: self.cte_sql_name(name),
                scalar,
                pg_type: (scalar && !t.is_empty()).then(|| literal_sentinel_to_pg(t).to_string()),
            });
        }
        if allow_fn_param && let Some(pg_type) = self.fn_params.get(name) {
            return Some(IrExpr::FnParam {
                name: name.to_string(),
                pg_type: pg_type.clone(),
            });
        }
        None
    }

    /// The `(qualified type, alias)` an absolute `root.prop` should resolve
    /// against when the innermost select is `detached`.
    ///
    /// `None` in the ordinary case — the innermost select is not detached, or
    /// nothing outside it binds that type, in which case naming the type still
    /// means the current row.
    fn enclosing_anchor(&self, root: &str) -> Option<(String, String)> {
        let innermost = self.anchors.last()?;
        if !innermost.detached || !innermost.answers_to(root) {
            return None;
        }
        self.anchors
            .iter()
            .rev()
            .skip(1)
            .find(|a| a.answers_to(root))
            .map(|a| (a.qualified.clone(), a.alias.clone()))
    }

    /// Whether `root` names the scope `self_qname` stands for, beyond its own
    /// two spellings — an inherited computed names its declaring type, which
    /// is the subject there too. See `SelectAnchor::declared_on`.
    fn scope_answers_to(&self, root: &str, self_qname: &str) -> bool {
        self.anchors
            .last()
            .is_some_and(|anchor| anchor.qualified == self_qname && anchor.answers_to(root))
    }

    /// The innermost enclosing select binding `root` as its subject.
    fn outer_anchor(&self, root: &str) -> Option<(String, String)> {
        self.anchors
            .iter()
            .rev()
            .find(|a| a.answers_to(root))
            .map(|a| (a.qualified.clone(), a.alias.clone()))
    }

    fn compile_path(&mut self, p: &ast::Path, td: &TypeDescriptor, alias: &str) -> Result<IrExpr, PyQLError> {
        if !p.partial {
            if p.steps.len() == 1
                && let ast::PathStep::Name(n) = &p.steps[0]
            {
                if let Some(ir) = self.resolve_name_ref(n, true) {
                    return Ok(ir);
                }
                // __type__ without a leading dot still means the current object's type.
                if n == "__type__" {
                    return Ok(if self.is_polymorphic(td) {
                        IrExpr::ColumnRef {
                            alias: alias.to_string(),
                            column: "__type__".to_string(),
                            pg_type: "text".to_string(),
                        }
                    } else {
                        IrExpr::Literal(IrLiteral::Str(format!("{}::{}", td.module, td.name)))
                    });
                }
            }
            // Enum member access: `default::Gender.Female`
            if p.steps.len() == 2
                && let [ast::PathStep::Name(type_ref), ast::PathStep::Name(variant)] = p.steps.as_slice()
                && self.resolve_enum(type_ref).is_some()
            {
                return self.compile_enum_access(type_ref, variant);
            }
            // `root.field1.field2...` where `root` is a WITH-bound free object.
            if let Some(resolved) = self.resolve_cte_path(p) {
                return resolved;
            }
            // `root.field1.field2...` where `root` is a WITH-bound *schema
            // object* (`with person := (select detached Person filter ...)
            // select ... person.company.name ...`). `compile_path_select`
            // already treats a CTE-bound root exactly like a real type name
            // (it checks `cte_types` before falling back to `resolve_type`,
            // via the `@cte:` source-table sentinel — see its own doc
            // comment and `compile_expr_as_path_select`'s sibling case for
            // `Detached`), so it already implements the *entire* general
            // path-traversal feature set here — forward links, multilinks,
            // backlinks, junction-backed links, nested tuple field access,
            // "did you mean" on a typo'd name — not just a one-property
            // special case. Wrapping its result as `IrExpr::PathSubquery`
            // (the same vehicle `Detached` uses for a type-rooted path in
            // expression position) turns the whole traversal into one
            // correlated scalar/id expression.
            if p.steps.len() > 1
                && let ast::PathStep::Name(root) = &p.steps[0]
                && self
                    .cte_types
                    .get(root.as_str())
                    .map(|t| t.contains("::"))
                    .unwrap_or(false)
            {
                let full_path = ast::Path {
                    steps: p.steps.clone(),
                    partial: false,
                };
                let synthetic = ast::SelectStmt {
                    result: Expr::Path(full_path.clone()),
                    filter: None,
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let ps = self.compile_path_select(&synthetic, &full_path, &[], false)?;
                return Ok(IrExpr::PathSubquery(Box::new(ps)));
            }
            // `__new__.prop` / `__old__.prop` — the inserted/updated/deleted
            // row a trigger handler is compiled against (see
            // `compile_trigger_handler`, which populates `special_anchors`
            // per the trigger's declared `on` events). Same rewrite-and-
            // recurse trick as the `TypeName.prop` case below, just handing
            // `compile_path` the anchor's own alias ("NEW"/"OLD") instead
            // of `td`'s. Outside trigger-handler compilation (or for the
            // anchor the current trigger's events don't legally bind —
            // e.g. `__old__` in an Insert-only trigger) `special_anchors`
            // is empty/missing that entry, so this falls through to the
            // explicit error below rather than the generic "absolute
            // paths" message: `__old__`/`__new__` cannot be used in
            // this expression.
            if p.steps.len() > 1
                && let ast::PathStep::Name(root) = &p.steps[0]
                && (root == "__new__" || root == "__old__")
            {
                if let Some((anchor_td, anchor_alias)) = self.special_anchors.get(root).cloned() {
                    let relative = ast::Path {
                        steps: p.steps[1..].to_vec(),
                        partial: true,
                    };
                    return self.compile_path(&relative, anchor_td, &anchor_alias);
                }
                return Err(PyQLError::Resolution(PyQLResolutionError::UnknownField(
                    PyQLUnknownFieldError {
                        message: format!("{root} cannot be used in this expression"),
                        position: Position { line: 0, col: 0 },
                    },
                )));
            }
            // `__subject__` is the row a constraint is checked against, which
            // is the same row a relative path reads.
            if p.steps.len() > 1 && matches!(&p.steps[0], ast::PathStep::Name(root) if root == "__subject__") {
                let relative = ast::Path {
                    steps: p.steps[1..].to_vec(),
                    partial: true,
                };
                return self.compile_path(&relative, td, alias);
            }
            // Absolute path rooted at the current td: `TypeName.prop` inside a schema-bound
            // expression (e.g. the value side of a BinOp in compile_expr_as_path_select).
            // Rewrite to a relative path and compile normally.
            if p.steps.len() > 1
                && let ast::PathStep::Name(root) = &p.steps[0]
            {
                let qualified = format!("{}::{}", td.module, td.name);
                if *root == td.name || *root == qualified {
                    let relative = ast::Path {
                        steps: p.steps[1..].to_vec(),
                        partial: true,
                    };
                    // Inside a `detached` select, naming its own type means the
                    // enclosing select's row — that is what makes an anti-join
                    // compare two different rows.
                    if let Some((outer_qualified, outer_alias)) = self.enclosing_anchor(root) {
                        let outer_td = self.resolve_type(&outer_qualified)?.clone();
                        return self.compile_path(&relative, &outer_td, &outer_alias);
                    }
                    return self.compile_path(&relative, td, alias);
                }
                // A prefix naming a type an *enclosing* select already binds —
                // `select Font { styles: { font := Font.id } }`. Such a prefix
                // factors out to the scope that binds it, so it reads that row
                // rather than every row of the type.
                if let Some((outer_qualified, outer_alias)) = self.outer_anchor(root) {
                    let relative = ast::Path {
                        steps: p.steps[1..].to_vec(),
                        partial: true,
                    };
                    let outer_td = self.resolve_type(&outer_qualified)?.clone();
                    return self.compile_path(&relative, &outer_td, &outer_alias);
                }
            }
            // `membership.account.id` — a walk off a for-loop variable in
            // expression position. `compile_path_select` already knows to
            // start such a walk from the row the variable holds, so this is
            // that walk read as one subquery.
            if let Some(ast::PathStep::Name(var)) = p.steps.first()
                && p.steps.len() > 1
                && self.for_var_types.contains_key(var)
                && !matches!(p.steps[1], ast::PathStep::TypeIntersection(_))
            {
                let synthetic = ast::SelectStmt {
                    result: Expr::Path(p.clone()),
                    filter: None,
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let ps = self.compile_path_select(&synthetic, p, &[], false)?;
                return Ok(IrExpr::PathSubquery(Box::new(ps)));
            }
            // `o[is Organization]` on a for-loop variable — the narrowing is
            // a filter, not a traversal: the row is read from the narrowed
            // type's own table by the key the variable holds, so a variable
            // bound to something else yields nothing, as it should.
            // `line[is BrandOrderLineItem].brand` — the narrowing picks the row
            // out of the narrowed type's own table, and the walk continues from
            // there. Without the tail this is the row itself, handled below.
            if let [
                ast::PathStep::Name(var),
                ast::PathStep::TypeIntersection(type_ref),
                rest @ ..,
            ] = p.steps.as_slice()
                && !rest.is_empty()
                && self.for_var_types.contains_key(var)
            {
                let type_name = match &type_ref.module {
                    Some(m) => format!("{}::{}", m, type_ref.name),
                    None => type_ref.name.clone(),
                };
                let narrowed = self.resolve_type(&type_name)?;
                let mut steps = vec![ast::PathStep::Name(format!("{}::{}", narrowed.module, narrowed.name))];
                steps.extend(rest.iter().cloned());
                let rooted = ast::Path { steps, partial: false };
                let synthetic = ast::SelectStmt {
                    result: Expr::Path(rooted.clone()),
                    filter: None,
                    order_by: vec![],
                    offset: None,
                    limit: None,
                    lock: None,
                };
                let mut ps = self.compile_path_select(&synthetic, &rooted, &[], false)?;
                let correlation = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: ps.root.alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: self.for_var_ref(var),
                }));
                ps.filter = and_conditions(ps.filter, vec![correlation]);
                return Ok(IrExpr::PathSubquery(Box::new(ps)));
            }
            if let [ast::PathStep::Name(var), ast::PathStep::TypeIntersection(type_ref)] = p.steps.as_slice()
                && self.for_var_types.contains_key(var)
            {
                let type_name = match &type_ref.module {
                    Some(m) => format!("{}::{}", m, type_ref.name),
                    None => type_ref.name.clone(),
                };
                let narrowed = self.resolve_type(&type_name)?;
                let narrowed_alias = self.fresh_alias();
                let source = IrSource {
                    poly: self.poly_fanout_for(&format!("{}::{}", narrowed.module, narrowed.name)),
                    type_name: format!("{}::{}", narrowed.module, narrowed.name),
                    table: narrowed.table.clone(),
                    alias: narrowed_alias.clone(),
                };
                let filter = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: narrowed_alias,
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: self.for_var_ref(var),
                }));
                return Ok(IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                    source,
                    Self::pk_returning(narrowed),
                    Some(filter),
                ))));
            }
            return Err(PyQLError::Type(PyQLTypeError {
                message: "absolute paths are not valid in expression context; use .name".into(),
                position: Position { line: 0, col: 0 },
            }));
        }

        // A bare `@prop` — the junction row of the multi-link whose own
        // modifiers are being compiled. Read from the junction alias the
        // emitter puts in scope there ("jt"), the same one a `@prop` in the
        // nested shape reads.
        if p.partial
            && let [ast::PathStep::LinkProp(prop_name)] = p.steps.as_slice()
        {
            return self.compile_link_prop_ref(prop_name);
        }

        // Type intersection in expression: [is Type].name — scalar subquery
        if p.partial && matches!(p.steps.first(), Some(ast::PathStep::TypeIntersection(_))) {
            return self.compile_type_intersection_expr(&p.steps, td, alias);
        }

        // `.<assessment[is brand::AssessmentRespondent]` — a backlink read as a
        // value, with or without a narrowing. No column holds it, so it is the
        // traversal as a correlated subquery; the builders below only know
        // forward links and reject the intersection outright.
        if p.partial && matches!(p.steps.first(), Some(ast::PathStep::Backlink(_))) {
            return self.compile_partial_path_as_subquery(p, td, alias);
        }
        // `.ca.name` where `ca := a if cond else b` — the condition does not
        // depend on which branch is taken, so the field access distributes
        // over both and the walk happens inside each. Left whole, the walk
        // builder has no column to traverse through.
        if p.partial
            && p.steps.len() > 1
            && let Some(ast::PathStep::Name(first)) = p.steps.first()
            && let Some(Expr::IfElse(ie)) = self
                .active_declared_pointers
                .iter()
                .find(|d| path_leaf(&d.path).is_ok_and(|name| name == first))
                .and_then(|d| d.compexpr.clone())
        {
            let extend = |branch: &Expr| match branch {
                Expr::Path(bp) => {
                    let mut steps = bp.steps.clone();
                    steps.extend(p.steps[1..].iter().cloned());
                    Some(Expr::Path(ast::Path {
                        steps,
                        partial: bp.partial,
                    }))
                }
                // `(select .<brand[is T] … limit 1).priority` — the walk's
                // remaining steps projected off the sub-select.
                Expr::SubQuery(_) => p.steps[1..].iter().try_fold(branch.clone(), |expr, step| match step {
                    ast::PathStep::Name(field) => Some(Expr::FieldAccess {
                        expr: Box::new(expr),
                        field: field.clone(),
                    }),
                    _ => None,
                }),
                // Nothing to walk from, so nothing is reached.
                Expr::Set(items) if items.is_empty() => Some(Expr::Set(vec![])),
                Expr::TypeCast(cast) if matches!(&cast.expr, Expr::Set(items) if items.is_empty()) => {
                    Some(Expr::Set(vec![]))
                }
                _ => None,
            };
            if let (Some(if_expr), Some(else_expr)) = (extend(&ie.if_expr), extend(&ie.else_expr)) {
                let distributed = Expr::IfElse(Box::new(ast::IfElse {
                    condition: ie.condition.clone(),
                    if_expr,
                    else_expr,
                }));
                return self.compile_expr(&distributed, td, alias);
            }
        }

        // A walk that ends in a type intersection (`exists .provider[is
        // account::Individual]`) narrows to objects rather than reading a
        // pointer, so there is no trailing column for the two-step form to
        // read and it goes the way a longer traversal already does.
        let narrows_last = matches!(p.steps.last(), Some(ast::PathStep::TypeIntersection(_)));

        if p.steps.len() == 2 && !narrows_last {
            return self.compile_path_2step(p, td, alias);
        }

        // Three or more steps: no single column to read, so the whole
        // traversal becomes one correlated subquery.
        if p.steps.len() != 1 {
            return self.compile_partial_path_as_subquery(p, td, alias);
        }

        let pointer_name = match &p.steps[0] {
            ast::PathStep::Name(n) => n.as_str(),
            _ => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: "type intersections are not valid in expression context".into(),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };

        // __type__ as an expression: for polymorphic (interface) types, read from the
        // inline union column; for concrete types, emit the static qualified name.
        if pointer_name == "__type__" {
            return Ok(if self.is_polymorphic(td) {
                IrExpr::ColumnRef {
                    alias: alias.to_string(),
                    column: "__type__".to_string(),
                    pg_type: "text".to_string(),
                }
            } else {
                IrExpr::Literal(IrLiteral::Str(format!("{}::{}", td.module, td.name)))
            });
        }

        if let Some(prop) = Self::resolve_property(td, pointer_name) {
            return Ok(IrExpr::ColumnRef {
                alias: alias.to_string(),
                column: prop.name.clone(),
                pg_type: prop.pg_type.clone(),
            });
        }

        if let Some(link) = Self::resolve_link(td, pointer_name) {
            if link.is_junction_backed() {
                return self.junction_target_id_expr(td, link, alias);
            }
            // FK column reference (uuid) — e.g. `.company` → `t0."company_id"`
            return Ok(IrExpr::ColumnRef {
                alias: alias.to_string(),
                column: format!("{}_id", link.name),
                pg_type: "uuid".to_string(),
            });
        }

        // Schema-defined computed pointer: inline the expression in place.
        if let Some(cd) = self.resolve_computed(td, pointer_name) {
            let expr_ast = crate::parse::parse_pointer_expr(&cd.expression).map_err(PyQLError::Syntax)?;
            return self.compile_expr(&expr_ast, td, alias);
        }

        // `o in .organizations` — a multi-link read as a value is the set of
        // rows on the other side, which no column holds; the same traversal a
        // longer walk already becomes. Only property, link and computed were
        // resolved here, so a bare multi-link reported itself as unknown —
        // while the suggester, which does know them, offered the name back.
        if Self::resolve_multilink(td, pointer_name).is_some() {
            return self.compile_partial_path_as_subquery(p, td, alias);
        }

        // `select (select T { a := … }) filter .a = …` — a pointer the shape
        // in scope declared is on no type, so it is read as the expression it
        // was written as. The shape route already resolves these; a filter or
        // order-by naming one arrives here instead.
        if let Some(expr) = self
            .active_declared_pointers
            .iter()
            .find(|d| path_leaf(&d.path).is_ok_and(|n| n == pointer_name))
            .and_then(|d| d.compexpr.clone())
        {
            return self.compile_expr(&expr, td, alias);
        }

        Err(self.field_err(pointer_name, &format!("{}::{}", td.module, td.name)))
    }

    /// Free-context counterpart of `compile_path` — no schema type/alias in
    /// scope, so only for-loop variables, CTE bindings, function parameters,
    /// and enum member access (`default::Gender.Female`) are resolvable;
    /// anything property/link-shaped is a hard error.
    fn compile_free_path(&mut self, p: &ast::Path) -> Result<IrExpr, PyQLError> {
        if p.partial {
            // A WITH binding inside a computed pointer or a nested SELECT is
            // compiled without a type in scope, but `.name` there still means
            // the innermost enclosing set — the one the anchor stack holds.
            if let Some((qualified, alias)) = self.anchors.last().map(|a| (a.qualified.clone(), a.alias.clone())) {
                let td = self.resolve_type(&qualified)?;
                return self.compile_path(p, td, &alias);
            }
            return Err(self.type_err(
                "property reference (.name) is not valid in free SELECT; \
                 use a schema-bound SELECT instead",
            ));
        }
        if p.steps.len() == 2
            && let [ast::PathStep::Name(type_ref), ast::PathStep::Name(variant)] = p.steps.as_slice()
            && self.resolve_enum(type_ref).is_some()
        {
            return self.compile_enum_access(type_ref, variant);
        }
        // `root.field1.field2...` where `root` is a WITH-bound free object
        // (any length >= 2, including chains through nested free objects).
        if let Some(resolved) = self.resolve_cte_path(p) {
            return resolved;
        }
        if p.steps.len() == 1
            && let ast::PathStep::Name(n) = &p.steps[0]
            && let Some(ir) = self.resolve_name_ref(n, true)
        {
            return Ok(ir);
        }
        // `assessment.current_question` in a free shape's field or filter — a
        // walk off an object binding. It is the same traversal a bound select
        // makes, read back as one subquery; there is no enclosing row to
        // resolve it against, and nothing else here knows a binding can root a
        // path.
        if !p.partial
            && p.steps.len() > 1
            && let Some(ast::PathStep::Name(root)) = p.steps.first()
            && self.cte_object_type(root).is_some()
        {
            let synthetic = ast::SelectStmt {
                result: Expr::Path(p.clone()),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            let ps = self.compile_path_select(&synthetic, p, &[], false)?;
            // A walk made only of forward single links does not multiply rows,
            // so its cardinality is the root binding's. Treating every join as
            // widening made `(select T filter .id = $x).link.prop` a
            // one-element set rather than the value itself.
            let widens = ps.joins.iter().any(|join| !matches!(join, IrPathJoin::Single { .. }));
            let root_is_multi = self.multi_row_ctes.contains(root.as_str());
            let multi = matches!(ps.result, IrPathResult::Scalar(..)) && (widens || root_is_multi);
            return Ok(if multi {
                IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(Box::new(ps))))
            } else {
                IrExpr::PathSubquery(Box::new(ps))
            });
        }
        Err(self.type_err("expression is not valid in free SELECT context"))
    }

    fn compile_path_2step(&mut self, p: &ast::Path, td: &TypeDescriptor, alias: &str) -> Result<IrExpr, PyQLError> {
        let link_name = match &p.steps[0] {
            ast::PathStep::Name(n) => n.as_str(),
            _ => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: "type intersections are not valid in expression context".into(),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };
        let pointer_name = match &p.steps[1] {
            ast::PathStep::Name(n) => n.as_str(),
            _ => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: "type intersections are not valid in expression context".into(),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };

        if let Some(link) = Self::resolve_link(td, link_name) {
            if pointer_name == "id" {
                if link.is_junction_backed() {
                    return self.junction_target_id_expr(td, link, alias);
                }
                return Ok(IrExpr::ColumnRef {
                    alias: alias.to_string(),
                    column: format!("{}_id", link_name),
                    pg_type: "uuid".to_string(),
                });
            }
            let target_td = self.resolve_type(&link.target)?;
            if let Some(prop) = Self::resolve_property(target_td, pointer_name) {
                let ft_alias = self.fresh_alias();
                let target_id_expr = if link.is_junction_backed() {
                    self.junction_target_id_expr(td, link, alias)?
                } else {
                    IrExpr::ColumnRef {
                        alias: alias.to_string(),
                        column: format!("{}_id", link_name),
                        pg_type: "uuid".to_string(),
                    }
                };
                return Ok(IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                    IrSource {
                        poly: None,
                        type_name: format!("{}::{}", target_td.module, target_td.name),
                        table: target_td.table.clone(),
                        alias: ft_alias.clone(),
                    },
                    vec![IrShapePointer::Scalar(IrScalarPointer {
                        implicit_id: false,
                        marker_offset: None,
                        alias: prop.name.clone(),
                        column: prop.name.clone(),
                        pg_type: prop.pg_type.clone(),
                        tuple_shape: self.resolve_property_tuple_shape(prop),
                    })],
                    Some(IrExpr::BinOp(Box::new(IrBinOp {
                        left: IrExpr::ColumnRef {
                            alias: ft_alias.clone(),
                            column: "id".to_string(),
                            pg_type: "uuid".to_string(),
                        },
                        op: ast::BinOpKind::Eq,
                        right: target_id_expr,
                    }))),
                ))));
            }
            // Not a stored column on the target — a computed pointer, or a
            // further link. The general traversal builder resolves both.
            return self.compile_partial_path_as_subquery(p, td, alias);
        }

        // A multi-link path stands for a set of values. Inside a comparison
        // it has already been rewritten to an EXISTS (`try_multilink_exists`,
        // which runs first); everywhere else it is an array.
        if Self::resolve_multilink(td, link_name).is_some() {
            return self.compile_partial_path_as_subquery(p, td, alias);
        }

        // Not a stored pointer at all — a computed one, most likely, which
        // the general builder can traverse through by splicing in the path
        // it stands for. It raises the same "no link or property" error this
        // used to when the name really is unknown (which is what made a
        // computed head read as `has no link or property 'x'. Did you mean
        // 'x'?` — the suggester could see it, the resolver couldn't).
        self.compile_partial_path_as_subquery(p, td, alias)
    }

    // ── Backlink compilation ─────────────────────────────────────────────────────

    /// Detect a backlink path on either side of a BinOp and compile as EXISTS.
    fn try_backlink_exists(
        &mut self,
        b: &ast::BinOp,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<Option<IrExpr>, PyQLError> {
        use ast::PathStep;
        fn is_backlink(p: &ast::Path) -> bool {
            p.partial && matches!(p.steps.first(), Some(PathStep::Backlink(_)))
        }
        let (path_steps, value_ast, flip) = if let Expr::Path(p) = &b.left {
            if is_backlink(p) {
                (p.steps.as_slice(), &b.right, false)
            } else {
                return Ok(None);
            }
        } else if let Expr::Path(p) = &b.right {
            if is_backlink(p) {
                (p.steps.as_slice(), &b.left, true)
            } else {
                return Ok(None);
            }
        } else {
            return Ok(None);
        };
        let value_expr = self.compile_comparison_value(value_ast, &b.op, td, alias)?;
        let current_qname = format!("{}::{}", td.module, td.name);
        let exists = self.compile_backlink_as_exists(
            path_steps,
            Some((b.op.clone(), value_expr, flip)),
            &current_qname,
            alias,
        )?;
        Ok(Some(exists))
    }

    /// Compile a path `[Backlink(name), TypeIntersect(type), ...rest]` into EXISTS.
    /// `comparison` is `Some((op, value_expr, flip))` when used in a comparison filter.
    /// `current_qname` is the fully-qualified name of the object type being filtered.
    fn compile_backlink_as_exists(
        &mut self,
        steps: &[ast::PathStep],
        comparison: Option<(ast::BinOpKind, IrExpr, bool)>,
        current_qname: &str,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        use ast::PathStep;

        let backlink_name = match steps.first() {
            Some(PathStep::Backlink(n)) => n.clone(),
            _ => return Err(self.type_err("internal: expected backlink step")),
        };
        // Without a type intersection the backlink spans every type that
        // declares the link at this target, so the row qualifies if any one of
        // them points at it.
        let Some(PathStep::TypeIntersection(type_ref)) = steps.get(1) else {
            // Without a type intersection the backlink spans every type that
            // declares the link at this target.
            return self.backlink_exists_over_owners(
                None,
                &backlink_name,
                &steps[1..],
                comparison,
                current_qname,
                alias,
            );
        };

        let type_name = match &type_ref.module {
            Some(m) => format!("{}::{}", m, type_ref.name),
            None => type_ref.name.clone(),
        };
        let target_td = self.resolve_type(&type_name)?;
        if self.declares_backlink(target_td, &backlink_name, current_qname) {
            return self.backlink_exists_for_owner(
                target_td,
                &backlink_name,
                &steps[2..],
                comparison,
                current_qname,
                alias,
            );
        }
        // The intersection narrows to an interface or mixin that does not
        // declare the link itself — its implementors do, and a row of one of
        // them satisfies `[is ThatType]` all the same. Qualified, because that
        // is how an implementor names what it implements.
        let narrow_to = format!("{}::{}", target_td.module, target_td.name);
        self.backlink_exists_over_owners(
            Some(&narrow_to),
            &backlink_name,
            &steps[2..],
            comparison,
            current_qname,
            alias,
        )
    }

    /// The type that declares the link a backlink narrowed to `owner_td`
    /// reads through.
    fn backlink_owner(
        &self,
        owner_td: &'a TypeDescriptor,
        backlink_name: &str,
        current_qname: &str,
    ) -> Result<&'a TypeDescriptor, PyQLError> {
        // `.<passkeys[is account::Account]` — the intersection narrows what
        // comes back, and the link itself may be declared further down: here
        // `passkeys` is Individual's, and an Individual is an Account. So the
        // owner is the concrete type that actually declares it, the same way
        // `backlink_exists_over_owners` resolves one.
        Ok(if self.declares_backlink(owner_td, backlink_name, current_qname) {
            owner_td
        } else {
            // Qualified, because that is how a type records the interfaces it
            // implements; the query may well have written the bare name.
            let narrowed = format!("{}::{}", owner_td.module, owner_td.name);
            let declaring: Vec<&'a TypeDescriptor> = self
                .schema
                .types
                .iter()
                .filter(|t| !t.abstract_ && Self::is_or_implements(t, &narrowed))
                .filter(|t| self.declares_backlink(t, backlink_name, current_qname))
                .collect();
            let declaring = Self::without_inherited_owners(declaring);
            match declaring.as_slice() {
                [only] => only,
                [] => owner_td,
                several => {
                    return Err(self.type_err(&format!(
                        "'{backlink_name}' pointing to {current_qname} is declared by {} types under \
                         {narrowed} ({}), so a backlink narrowed to it has no single source to read \
                         — narrow to one of them instead",
                        several.len(),
                        several
                            .iter()
                            .map(|t| format!("{}::{}", t.module, t.name))
                            .collect::<Vec<_>>()
                            .join(", "),
                    )));
                }
            }
        })
    }

    /// Whether a backlink narrowed to `owner_td` reaches at most one object,
    /// which it does through an exclusive link.
    fn backlink_is_single(&self, owner_td: &'a TypeDescriptor, backlink_name: &str, current_qname: &str) -> bool {
        let Ok(owner) = self.backlink_owner(owner_td, backlink_name, current_qname) else {
            return false;
        };
        owner
            .links
            .iter()
            .any(|l| l.name == backlink_name && l.is_exclusive && self.link_target_reaches(&l.target, current_qname))
            || owner.multilinks.iter().any(|ml| {
                ml.name == backlink_name && ml.is_exclusive && self.link_target_reaches(&ml.target, current_qname)
            })
    }

    /// Does `td` declare the link a backlink names, pointing at the type the
    /// traversal is standing on?
    fn declares_backlink(&self, td: &TypeDescriptor, backlink_name: &str, current_qname: &str) -> bool {
        td.links
            .iter()
            .any(|l| l.name == backlink_name && self.link_target_reaches(&l.target, current_qname))
            || td
                .multilinks
                .iter()
                .any(|ml| ml.name == backlink_name && self.link_target_reaches(&ml.target, current_qname))
    }

    /// EXISTS over every type that declares the backlink's link, OR-ed
    /// together: a row qualifies if any one of them points at it. `narrow_to`
    /// keeps only the types that satisfy an `[is …]` the path asked for.
    #[allow(clippy::too_many_arguments)]
    /// Drops the owners that only inherit the link from another owner in the
    /// list: reading the base already reads its subtypes' rows.
    fn without_inherited_owners(owners: Vec<&'a TypeDescriptor>) -> Vec<&'a TypeDescriptor> {
        let qnames: Vec<String> = owners.iter().map(|t| format!("{}::{}", t.module, t.name)).collect();
        owners
            .into_iter()
            .filter(|t| !t.bases.iter().any(|base| qnames.contains(base)))
            .collect()
    }

    fn backlink_exists_over_owners(
        &mut self,
        narrow_to: Option<&str>,
        backlink_name: &str,
        rest: &[ast::PathStep],
        comparison: Option<(ast::BinOpKind, IrExpr, bool)>,
        current_qname: &str,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let schema = self.schema;
        let owners: Vec<&'a TypeDescriptor> = schema
            .types
            .iter()
            .filter(|t| !t.abstract_)
            .filter(|t| narrow_to.is_none_or(|q| Self::is_or_implements(t, q)))
            .filter(|t| self.declares_backlink(t, backlink_name, current_qname))
            .collect();
        let owners = Self::without_inherited_owners(owners);
        if owners.is_empty() {
            return Err(self.type_err(&match narrow_to {
                Some(q) => format!("type {q} has no link or multi-link '{backlink_name}' pointing to {current_qname}"),
                None => format!("no type has a link or multi-link '{backlink_name}' pointing to {current_qname}"),
            }));
        }
        let mut combined: Option<IrExpr> = None;
        for owner_td in owners {
            let one = self.backlink_exists_for_owner(
                owner_td,
                backlink_name,
                rest,
                comparison.clone(),
                current_qname,
                alias,
            )?;
            combined = Some(match combined {
                None => one,
                Some(previous) => IrExpr::BinOp(Box::new(IrBinOp {
                    left: previous,
                    op: ast::BinOpKind::Or,
                    right: one,
                })),
            });
        }
        Ok(combined.expect("owners is non-empty"))
    }

    /// Is `td` the type `qname` names, or one that implements/extends it?
    fn is_or_implements(td: &TypeDescriptor, qname: &str) -> bool {
        format!("{}::{}", td.module, td.name) == qname
            || td.interfaces.iter().any(|i| i == qname)
            || td.parents.iter().any(|p| p == qname)
            || td.bases.iter().any(|b| b == qname)
    }

    /// A concrete type another concrete type extends (`BrandAddon`, which
    /// `BrandAddonBundle` extends). Its own table holds only its own rows, so
    /// reading the type means reading the subtypes' tables beside it.
    fn has_subtypes(&self, td: &TypeDescriptor) -> bool {
        let qname = format!("{}::{}", td.module, td.name);
        !td.abstract_ && self.schema.types.iter().any(|t| t.bases.contains(&qname))
    }

    /// A plain `@pylon.abstract` mixin, materialised as nothing at all.
    /// Unlike an interface it backs no view, so naming its table reaches a
    /// relation that does not exist.
    fn backs_no_relation(td: &TypeDescriptor) -> bool {
        td.abstract_ && !td.materialized
    }

    /// See `IrOutput::subtype_fanouts`.
    fn subtype_fanouts(&self) -> HashMap<(String, String), IrPolyFanout> {
        self.schema
            .types
            .iter()
            .filter(|t| self.has_subtypes(t) || Self::backs_no_relation(t))
            .filter_map(|t| {
                let fanout = self.poly_fanout_for(&format!("{}::{}", t.module, t.name))?;
                Some(((t.module.clone(), t.table.clone()), fanout))
            })
            .collect()
    }

    /// Whether the type's rows come from more than one table — an interface,
    /// an abstract type (which has no table of its own), or a concrete type
    /// with subtypes — and so are read through the union that carries each
    /// row's own `__type__`.
    fn is_polymorphic(&self, td: &TypeDescriptor) -> bool {
        td.abstract_ || self.has_subtypes(td)
    }

    /// One owner type's half of `compile_backlink_as_exists`: EXISTS over the
    /// rows of `target_td` that link back to `alias`, plus whatever the
    /// remaining path steps and comparison require of them.
    #[allow(clippy::too_many_arguments)]
    fn backlink_exists_for_owner(
        &mut self,
        target_td: &'a TypeDescriptor,
        backlink_name: &str,
        rest: &[ast::PathStep],
        comparison: Option<(ast::BinOpKind, IrExpr, bool)>,
        current_qname: &str,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        let backlink_name = backlink_name.to_string();
        let target_qname = format!("{}::{}", target_td.module, target_td.name);
        let target_table = target_td.table.clone();
        let t_alias = self.fresh_alias();

        // Backlink source is either a single (FK) link or a multi-link
        // (junction table) on the target type — mirrors the equivalent
        // link-vs-multilink resolution the general shape-position backlink
        // code already does (see the `PathStep::Backlink` handling above in
        // `compile_path_expr`/similar), which this filter/exists-specific
        // path previously didn't: it only ever checked `target_td.links`,
        // so a self-referential-multilink backlink like `Person.friends`
        // failed to compile here even though it worked in a shape position.
        let join_cond = if let Some(l) = target_td
            .links
            .iter()
            .find(|l| l.name == backlink_name && self.link_target_reaches(&l.target, current_qname))
        {
            if l.is_junction_backed() {
                // Same junction-table EXISTS shape the multi-link branch
                // below uses — no direct FK column, since this link is
                // itself junction-backed.
                let (jt_table, jt_module, jt_owner_col, jt_current_col, _) = self.link_junction_info(target_td, l)?;
                let jt_alias = self.fresh_alias();
                IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                        IrSource {
                            poly: None,
                            type_name: format!("{}::__jt__", jt_module),
                            table: jt_table,
                            alias: jt_alias.clone(),
                        },
                        vec![],
                        Some(IrExpr::BinOp(Box::new(IrBinOp {
                            left: IrExpr::BinOp(Box::new(IrBinOp {
                                left: IrExpr::ColumnRef {
                                    alias: jt_alias.clone(),
                                    column: jt_owner_col,
                                    pg_type: "uuid".to_string(),
                                },
                                op: ast::BinOpKind::Eq,
                                right: IrExpr::ColumnRef {
                                    alias: t_alias.clone(),
                                    column: "id".to_string(),
                                    pg_type: "uuid".to_string(),
                                },
                            })),
                            op: ast::BinOpKind::And,
                            right: IrExpr::BinOp(Box::new(IrBinOp {
                                left: IrExpr::ColumnRef {
                                    alias: jt_alias,
                                    column: jt_current_col,
                                    pg_type: "uuid".to_string(),
                                },
                                op: ast::BinOpKind::Eq,
                                right: IrExpr::ColumnRef {
                                    alias: alias.to_string(),
                                    column: "id".to_string(),
                                    pg_type: "uuid".to_string(),
                                },
                            })),
                        }))),
                    ))),
                }))
            } else {
                let fk_col = format!("{}_id", backlink_name);
                // Join condition: target.fk_col = current.id
                IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: t_alias.clone(),
                        column: fk_col,
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: IrExpr::ColumnRef {
                        alias: alias.to_string(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                }))
            }
        } else if let Some(ml) = target_td
            .multilinks
            .iter()
            .find(|ml| ml.name == backlink_name && self.link_target_reaches(&ml.target, current_qname))
            .cloned()
        {
            // Junction row connects t_alias (as the multi-link's owner/
            // "source") to the current row (as its "target") — no direct FK
            // column on either table, so this is a nested EXISTS over the
            // junction table rather than a simple column comparison.
            let (jt_table, jt_module, _, _, _) = self.multilink_junction_info(target_td, &ml)?;
            let jt_alias = self.fresh_alias();
            IrExpr::UnaryOp(Box::new(IrUnaryOp {
                op: ast::UnaryOpKind::Exists,
                operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                    IrSource {
                        poly: None,
                        type_name: format!("{}::__jt__", jt_module),
                        table: jt_table,
                        alias: jt_alias.clone(),
                    },
                    vec![],
                    Some(IrExpr::BinOp(Box::new(IrBinOp {
                        left: IrExpr::BinOp(Box::new(IrBinOp {
                            left: IrExpr::ColumnRef {
                                alias: jt_alias.clone(),
                                column: "source".to_string(),
                                pg_type: "uuid".to_string(),
                            },
                            op: ast::BinOpKind::Eq,
                            right: IrExpr::ColumnRef {
                                alias: t_alias.clone(),
                                column: "id".to_string(),
                                pg_type: "uuid".to_string(),
                            },
                        })),
                        op: ast::BinOpKind::And,
                        right: IrExpr::BinOp(Box::new(IrBinOp {
                            left: IrExpr::ColumnRef {
                                alias: jt_alias,
                                column: "target".to_string(),
                                pg_type: "uuid".to_string(),
                            },
                            op: ast::BinOpKind::Eq,
                            right: IrExpr::ColumnRef {
                                alias: alias.to_string(),
                                column: "id".to_string(),
                                pg_type: "uuid".to_string(),
                            },
                        })),
                    }))),
                ))),
            }))
        } else {
            return Err(PyQLError::Type(PyQLTypeError {
                message: format!(
                    "type {} has no link or multi-link '{}' pointing to {}",
                    target_qname, backlink_name, current_qname,
                ),
                position: Position { line: 0, col: 0 },
            }));
        };

        let tail_cond = self.compile_backlink_tail(rest, comparison, &target_qname, &t_alias)?;

        let filter = match tail_cond {
            Some(tc) => IrExpr::BinOp(Box::new(IrBinOp {
                left: join_cond,
                op: ast::BinOpKind::And,
                right: tc,
            })),
            None => join_cond,
        };

        Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                IrSource {
                    poly: None,
                    type_name: target_qname,
                    table: target_table,
                    alias: t_alias,
                },
                vec![],
                Some(filter),
            ))),
        })))
    }

    /// Compile the tail steps after `[Backlink, TypeIntersect]`.
    fn compile_backlink_tail(
        &mut self,
        steps: &[ast::PathStep],
        comparison: Option<(ast::BinOpKind, IrExpr, bool)>,
        target_qname: &str,
        t_alias: &str,
    ) -> Result<Option<IrExpr>, PyQLError> {
        use ast::PathStep;

        // `.<contacts[is Account] = account` — nothing after the backlink, so
        // the objects it reaches are what is compared, by identity. Returning
        // nothing here dropped the comparison, leaving "any account links to
        // this row" in its place.
        if steps.is_empty() {
            return Ok(comparison.map(|(op, value, flip)| {
                let key = IrExpr::ColumnRef {
                    alias: t_alias.to_string(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                };
                let (left, right) = if flip { (value, key) } else { (key, value) };
                IrExpr::BinOp(Box::new(IrBinOp { left, op, right }))
            }));
        }

        // Chained backlink: recurse (current_qname is now target_qname of the outer backlink)
        if matches!(steps.first(), Some(PathStep::Backlink(_))) {
            let inner = self.compile_backlink_as_exists(steps, comparison, target_qname, t_alias)?;
            return Ok(Some(inner));
        }

        let target_td = self.resolve_type(target_qname)?;

        // Single property or link FK
        if let [PathStep::Name(pointer_name)] = steps {
            if let Some(prop) = Self::resolve_property(target_td, pointer_name) {
                let col = IrExpr::ColumnRef {
                    alias: t_alias.to_string(),
                    column: prop.name.clone(),
                    pg_type: prop.pg_type.clone(),
                };
                return Ok(Some(self.apply_comparison(col, comparison)));
            }
            if let Some(link) = Self::resolve_link(target_td, pointer_name) {
                let col = if link.is_junction_backed() {
                    self.junction_target_id_expr(target_td, link, t_alias)?
                } else {
                    IrExpr::ColumnRef {
                        alias: t_alias.to_string(),
                        column: format!("{}_id", link.name),
                        pg_type: "uuid".to_string(),
                    }
                };
                return Ok(Some(self.apply_comparison(col, comparison)));
            }
            // Not a property or a link: a multi-link has no single column to
            // read, so it falls through to the general tail walk below, which
            // reports the same error for a name that is none of the three.
        }

        // Two forward steps: link then property (single FK join)
        if let [PathStep::Name(link_name), PathStep::Name(prop_name)] = steps
            && let Some(link) = Self::resolve_link(target_td, link_name)
        {
            let link_target = link.target.clone();
            let target_id_expr = if link.is_junction_backed() {
                self.junction_target_id_expr(target_td, link, t_alias)?
            } else {
                IrExpr::ColumnRef {
                    alias: t_alias.to_string(),
                    column: format!("{}_id", link_name),
                    pg_type: "uuid".to_string(),
                }
            };
            let link_target_td = self.resolve_type(&link_target)?;
            let link_target_qname = format!("{}::{}", link_target_td.module, link_target_td.name);
            let link_target_table = link_target_td.table.clone();
            if let Some(prop) = Self::resolve_property(link_target_td, prop_name) {
                let l_alias = self.fresh_alias();
                let id_cond = IrExpr::BinOp(Box::new(IrBinOp {
                    left: IrExpr::ColumnRef {
                        alias: l_alias.clone(),
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    },
                    op: ast::BinOpKind::Eq,
                    right: target_id_expr,
                }));
                let col = IrExpr::ColumnRef {
                    alias: l_alias.clone(),
                    column: prop.name.clone(),
                    pg_type: prop.pg_type.clone(),
                };
                let prop_cond = self.apply_comparison(col, comparison);
                let full = IrExpr::BinOp(Box::new(IrBinOp {
                    left: id_cond,
                    op: ast::BinOpKind::And,
                    right: prop_cond,
                }));
                return Ok(Some(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                    op: ast::UnaryOpKind::Exists,
                    operand: IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                        IrSource {
                            poly: None,
                            type_name: link_target_qname,
                            table: link_target_table,
                            alias: l_alias,
                        },
                        vec![],
                        Some(full),
                    ))),
                }))));
            }
        }

        // Anything else is an ordinary path from the backlink's target type, so
        // it is compiled as one rather than enumerated arity by arity. The two
        // cases above stay because each reads a single column; a step that
        // crosses a multi-link has none to read.
        let tail = ast::Path {
            steps: steps.to_vec(),
            partial: true,
        };
        let walked = self.compile_path(&tail, target_td, t_alias)?;
        Ok(Some(self.apply_comparison(walked, comparison)))
    }

    /// Whether `e` stands for a *set* rather than one value: a walk gathered
    /// as an array, or a `with` binding of more than one row, which arrives as
    /// a reference to its CTE. Reading only the first of those left `filter
    /// .posts = ps` comparing against `(SELECT id FROM ps)` — one value, and
    /// an error from Postgres as soon as the binding held two.
    fn is_set_expr(&self, e: &IrExpr) -> bool {
        match e {
            IrExpr::ArrayFromSelect(_) => true,
            IrExpr::CteRef { name, .. } => self.multi_row_ctes.contains(name),
            _ => false,
        }
    }

    /// Apply an optional comparison to a column ref, defaulting to IS NOT NULL.
    fn apply_comparison(&self, col: IrExpr, comparison: Option<(ast::BinOpKind, IrExpr, bool)>) -> IrExpr {
        let is_set = |e: &IrExpr| self.is_set_expr(e);
        match comparison {
            Some((op, val, flip)) => {
                let (l, r) = if flip { (val, col) } else { (col, val) };
                // A walk that crosses a multi-link stands for a *set*, which
                // an equality holds against when any element matches — the
                // same reading `compile_expr_ctx` gives one anywhere else.
                if matches!(op, ast::BinOpKind::Eq | ast::BinOpKind::Ne) && is_set(&l) != is_set(&r) {
                    let (value, set) = if is_set(&r) { (l, r) } else { (r, l) };
                    let membership = IrExpr::BinOp(Box::new(IrBinOp {
                        left: value,
                        op: ast::BinOpKind::In,
                        right: set,
                    }));
                    return if matches!(op, ast::BinOpKind::Ne) {
                        IrExpr::UnaryOp(Box::new(IrUnaryOp {
                            op: ast::UnaryOpKind::Not,
                            operand: membership,
                        }))
                    } else {
                        membership
                    };
                }
                IrExpr::BinOp(Box::new(IrBinOp { left: l, op, right: r }))
            }
            None => ir_is_not_null(col),
        }
    }

    /// The other side of a comparison whose path crosses a multi-link or a
    /// backlink, ready to sit inside the EXISTS that walk becomes.
    ///
    /// A set literal is meaningless as an expression anywhere else, so the
    /// general compiler hard-errors on one — but on the right of `in` it is
    /// exactly the array `= ANY(…)` wants, the same reading the `In`/`NotIn`
    /// arm of `compile_expr_ctx` gives it. Without this, `filter .posts.title
    /// in {'a', 'b'}` failed to compile at all: the walk reaches this builder
    /// before that arm is ever tried.
    fn compile_comparison_value(
        &mut self,
        value: &Expr,
        op: &ast::BinOpKind,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<IrExpr, PyQLError> {
        match value {
            Expr::Set(elems) if matches!(op, ast::BinOpKind::In | ast::BinOpKind::NotIn) => Ok(IrExpr::Array(
                elems
                    .iter()
                    .map(|e| self.compile_expr(e, td, alias))
                    .collect::<Result<Vec<_>, _>>()?,
            )),
            other => self.compile_expr(other, td, alias),
        }
    }

    /// `X in Y` where `X` is a set and a *value* is what the position wants:
    /// one boolean per element of `X`, gathered as the array every other
    /// multi-valued expression comes back as. `Y` is the set membership is
    /// tested against, so it stays whole.
    ///
    /// Only the left operand's walk is rebuilt — it already compiles to
    /// `ARRAY(SELECT <element> FROM <walk>)`, and what this does is move the
    /// comparison inside that select, where it is made once per row rather
    /// than once for the array. `Ok(None)` for anything else, including every
    /// condition position, which still collapses to the EXISTS below.
    fn try_elementwise_in(
        &mut self,
        b: &ast::BinOp,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        // `=`/`!=` against a *set* is the same membership question spelled
        // differently — the reading `apply_comparison` already gives it — so
        // `all(.posts = ps)` has to answer per element too. Whether the other
        // side really is a set is only known once compiled, which the walk arm
        // below checks; the bare-binding arm takes `in` alone.
        let membership = matches!(b.op, ast::BinOpKind::In | ast::BinOpKind::NotIn);
        if !membership && !matches!(b.op, ast::BinOpKind::Eq | ast::BinOpKind::Ne) {
            return Ok(None);
        }
        // `individuals in accounts` — the left operand is the whole set a
        // binding or a type names, so what answers per element is a select
        // over that set. Available with or without a schema type in scope,
        // since neither operand needs one.
        //
        // A quantifier's argument is a set position by definition, so this
        // holds inside one whether or not the surrounding position asked for
        // a value: `any(individuals in accounts)` is how those answers are
        // reduced back to one, and it has the same set to reduce either way.
        // A walk (below) has an EXISTS to fold into instead, which says the
        // same thing more directly, so only this arm needs the quantifier.
        if membership
            && (self.value_position || self.explicit_set_depth > 0)
            && let Some(root) = self.object_set_name(&b.left)
        {
            let rewritten = Expr::BinOp(Box::new(ast::BinOp {
                left: Expr::Path(ast::Path {
                    steps: vec![ast::PathStep::Name(root.clone()), ast::PathStep::Name("id".into())],
                    partial: false,
                }),
                op: b.op.clone(),
                right: b.right.clone(),
            }));
            let over_the_set = ast::SelectStmt {
                result: rewritten.clone(),
                filter: None,
                order_by: vec![],
                offset: None,
                limit: None,
                lock: None,
            };
            let ps = self.compile_expr_as_path_select(&over_the_set, &rewritten, &root, false)?;
            return Ok(Some(IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(
                Box::new(ps),
            )))));
        }
        // A walk answers `any` with an EXISTS over its junction, which says
        // the same thing more directly, so outside a value position it only
        // takes the per-element route for `all` — where an EXISTS is the
        // wrong question and the answers have to be reduced one at a time.
        if !self.value_position && self.universal_set_depth == 0 {
            return Ok(None);
        }
        let Some((td, _)) = ctx else { return Ok(None) };
        // Checked before compiling anything: a walk that turns out to be
        // single-valued has to reach the ordinary path below, and compiling it
        // twice would burn aliases and re-hoist whatever it bound.
        let Expr::Path(p) = &b.left else { return Ok(None) };
        if !p.partial || !self.path_crosses_multi(td, &p.steps) {
            return Ok(None);
        }
        // The walk is compiled speculatively — whether it can be rebuilt this
        // way is only visible once it has been — so anything it bound on the
        // way is rolled back when it turns out it cannot.
        let hoisted = self.hoisted_ctes.len();
        let left = self.compile_expr_ctx(&b.left, ctx)?;
        // A walk onto objects arrives as the bare correlated subquery its rows
        // are; one onto values arrives already gathered into an array. Either
        // way what comes back from here is a set of booleans, so both leave as
        // an array.
        let mut ps = match left {
            IrExpr::PathSubquery(ps) | IrExpr::ObjectPathSubquery(ps) => ps,
            IrExpr::ArrayFromSelect(source) => match *source {
                IrArraySource::PathSelect(ps) => ps,
                _ => {
                    self.hoisted_ctes.truncate(hoisted);
                    return Ok(None);
                }
            },
            _ => {
                self.hoisted_ctes.truncate(hoisted);
                return Ok(None);
            }
        };
        // A set literal on the right is the one expression position one is
        // meaningful in — see the `In`/`NotIn` arm of `compile_expr_ctx`,
        // which reads it as the array `= ANY(…)` wants.
        let right = match &b.right {
            Expr::Set(elems) => IrExpr::Array(
                elems
                    .iter()
                    .map(|e| self.compile_expr_ctx(e, ctx))
                    .collect::<Result<Vec<_>, _>>()?,
            ),
            other => self.compile_expr_ctx(other, ctx)?,
        };
        // An equality earns this route only by really being a membership
        // test; against a single value it is an ordinary comparison, which
        // the EXISTS fold below already reads correctly.
        if !membership && !self.is_set_expr(&right) {
            self.hoisted_ctes.truncate(hoisted);
            return Ok(None);
        }
        // Objects are compared by identity, which is the id the walk's last
        // step lands on — the same reading `in` gives them anywhere else.
        let element = match &ps.result {
            IrPathResult::Scalar(expr, _) => expr.clone(),
            IrPathResult::Object { alias, .. } => IrExpr::ColumnRef {
                alias: alias.clone(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        };
        // `apply_comparison` turns the equality into the membership it stands
        // for; `in` it leaves alone.
        let per_element = self.apply_comparison(element, Some((b.op.clone(), right, false)));
        ps.result = IrPathResult::Scalar(per_element, None);
        Ok(Some(IrExpr::ArrayFromSelect(Box::new(IrArraySource::PathSelect(ps)))))
    }

    /// If `b` has a multi-link path (any depth) on either side, compile as EXISTS over the junction.
    fn try_multilink_exists(
        &mut self,
        b: &ast::BinOp,
        td: &TypeDescriptor,
        alias: &str,
    ) -> Result<Option<IrExpr>, PyQLError> {
        // A bare `.multilink` counts: comparing the link itself to an object
        // (`filter any(.emails = email)`) is the same set-membership question
        // as comparing something reached through it, just with no tail.
        fn ml_first_name(steps: &[ast::PathStep]) -> Option<&str> {
            match steps.first()? {
                ast::PathStep::Name(n) => Some(n.as_str()),
                _ => None,
            }
        }

        let (path_steps, value_ast, flip) = if let Expr::Path(p) = &b.left {
            if p.partial {
                if let Some(ln) = ml_first_name(&p.steps) {
                    if Self::resolve_multilink(td, ln).is_some() {
                        (p.steps.as_slice(), &b.right, false)
                    } else {
                        return Ok(None);
                    }
                } else {
                    return Ok(None);
                }
            } else {
                return Ok(None);
            }
        } else if let Expr::Path(p) = &b.right {
            if p.partial {
                if let Some(ln) = ml_first_name(&p.steps) {
                    if Self::resolve_multilink(td, ln).is_some() {
                        (p.steps.as_slice(), &b.left, true)
                    } else {
                        return Ok(None);
                    }
                } else {
                    return Ok(None);
                }
            } else {
                return Ok(None);
            }
        } else {
            return Ok(None);
        };

        let value_expr = self.compile_comparison_value(value_ast, &b.op, td, alias)?;
        let ml_name = match &path_steps[0] {
            ast::PathStep::Name(n) => n.clone(),
            _ => return Ok(None),
        };
        let ml = Self::resolve_multilink(td, &ml_name).unwrap();

        // Warn: multi-link traversal in a comparison returns a set, not a single boolean.
        // The query works (compiled as EXISTS), but `any()` makes the intent explicit.
        if self.explicit_set_depth == 0 {
            // Rendered back the way it was written — a path the reader cannot
            // find in their own query is worse than no path at all.
            let mut pointer_path = String::new();
            for step in path_steps {
                match step {
                    ast::PathStep::Name(n) => {
                        pointer_path.push('.');
                        pointer_path.push_str(n);
                    }
                    ast::PathStep::Backlink(n) => {
                        pointer_path.push_str(".<");
                        pointer_path.push_str(n);
                    }
                    ast::PathStep::LinkProp(n) => {
                        pointer_path.push('@');
                        pointer_path.push_str(n);
                    }
                    ast::PathStep::TypeIntersection(t) => {
                        pointer_path.push_str("[is ");
                        pointer_path.push_str(&t.qualified_name());
                        pointer_path.push(']');
                    }
                }
            }
            self.warnings.push(format!(
                "possibly more than one element returned by an expression in a FILTER clause \
                 (multi-link '{pointer_path}'); wrap with any() to make intent explicit",
            ));
        }

        // Clone what we need to avoid borrow conflicts with self below.
        let ml_target = ml.target.clone();
        let ml_through = ml.through.clone();
        let td_module = td.module.clone();
        let td_name = td.name.clone();
        let td_table = td.table.clone();

        // tail steps are everything after the multi-link name (path_steps[1..])
        let tail_steps: Vec<ast::PathStep> = path_steps[1..].to_vec();

        let jt_alias = self.fresh_alias();

        // Resolve junction table columns.
        let (jt_table, jt_module, jt_src_col, jt_tgt_col) = if let Some(through_qname) = &ml_through {
            let through_td = self.resolve_type(through_qname)?;
            if through_td.junction {
                // See `junction_info_for`'s doc comment: owner-derived,
                // never `through_td.table` itself.
                (
                    format!("{}.{}", td_table, ml_name),
                    td_module.clone(),
                    "source".to_string(),
                    "target".to_string(),
                )
            } else {
                let source_qname = format!("{}::{}", td_module, td_name);
                let src_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == source_qname)
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to {source_qname}"),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                let tgt_col = through_td
                    .links
                    .iter()
                    .find(|l| l.target == ml_target && l.name != src_col)
                    .or_else(|| through_td.links.iter().find(|l| l.target == ml_target))
                    .ok_or_else(|| {
                        PyQLError::Type(PyQLTypeError {
                            message: format!("through type {through_qname} has no link to {ml_target}"),
                            position: Position { line: 0, col: 0 },
                        })
                    })?
                    .name
                    .clone();
                (
                    through_td.table.clone(),
                    through_td.module.clone(),
                    format!("{}_id", src_col),
                    format!("{}_id", tgt_col),
                )
            }
        } else {
            (
                format!("{}.{}", td_table, ml_name),
                td_module.clone(),
                "source".to_string(),
                "target".to_string(),
            )
        };

        // source filter: jt.src_col = parent.id
        let src_filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: jt_alias.clone(),
                column: jt_src_col,
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: alias.to_string(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
        }));

        // Build tail filter: what to compare inside the junction/target EXISTS
        let tail_filter = self.compile_path_tail_filter(
            &tail_steps,
            b.op.clone(),
            value_expr,
            flip,
            &ml_target,
            &jt_alias,
            &jt_tgt_col,
        )?;

        let full_filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: src_filter,
            op: ast::BinOpKind::And,
            right: tail_filter,
        }));

        // EXISTS(SELECT 1 FROM junction jt WHERE ...)
        let jt_source = IrSource {
            poly: None,
            type_name: format!("{}::__jt__", jt_module),
            table: jt_table,
            alias: jt_alias,
        };
        let inner = IrExpr::Subquery(Box::new(IrSelect::schema_bound(jt_source, vec![], Some(full_filter))));

        Ok(Some(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: inner,
        }))))
    }

    /// Build a filter expression for the tail steps after the multi-link in an EXISTS context.
    ///
    /// `steps` = path steps after the multi-link name (e.g. ["company", "id"] for .friends.company.id)
    /// `jt_alias` = alias of the junction table row
    /// `jt_tgt_col` = column in the junction table holding the target id (e.g. "target" or "friend_id")
    /// `target_type` = qualified name of the multi-link's target type (e.g. "default::Person")
    #[allow(clippy::too_many_arguments)]
    fn compile_path_tail_filter(
        &mut self,
        steps: &[ast::PathStep],
        op: ast::BinOpKind,
        value_expr: IrExpr,
        flip: bool,
        target_type: &str,
        jt_alias: &str,
        jt_tgt_col: &str,
    ) -> Result<IrExpr, PyQLError> {
        // No tail at all — the multi-link itself is what is being compared,
        // so the junction row's target id is the whole answer.
        if steps.is_empty() {
            let col_ref = IrExpr::ColumnRef {
                alias: jt_alias.to_string(),
                column: jt_tgt_col.to_string(),
                pg_type: "uuid".to_string(),
            };
            // Through `apply_comparison` rather than built here, so an
            // equality against a *set* — a binding of more than one row —
            // reads as membership instead of comparing against the one value
            // a scalar subquery can return.
            return Ok(self.apply_comparison(col_ref, Some((op, value_expr, flip))));
        }

        // `.emails[is account::Email].email` — an intersection narrows what the
        // walk continues from. The remaining steps read against the narrowed
        // type, and because its own table is what they join to, a row of any
        // other type drops out on its own: the narrowing needs no separate
        // check.
        if let Some(ast::PathStep::TypeIntersection(type_ref)) = steps.first() {
            let narrowed = self.resolve_type(&type_ref.qualified_name())?;
            let narrowed_qname = format!("{}::{}", narrowed.module, narrowed.name);
            return self.compile_path_tail_filter(
                &steps[1..],
                op,
                value_expr,
                flip,
                &narrowed_qname,
                jt_alias,
                jt_tgt_col,
            );
        }

        let first_name = match steps.first() {
            Some(ast::PathStep::Name(n)) => n.clone(),
            _ => return Err(self.type_err("expected a property or link name in path")),
        };

        let target_td = self.resolve_type(target_type)?;
        let target_table = target_td.table.clone();

        if steps.len() == 1 {
            // Terminal step: must be a scalar property or "id"
            if first_name == "id" {
                // FK optimisation: compare jt.target directly
                let col_ref = IrExpr::ColumnRef {
                    alias: jt_alias.to_string(),
                    column: jt_tgt_col.to_string(),
                    pg_type: "uuid".to_string(),
                };
                let (l, r) = if flip {
                    (value_expr, col_ref)
                } else {
                    (col_ref, value_expr)
                };
                return Ok(IrExpr::BinOp(Box::new(IrBinOp { left: l, op, right: r })));
            }
            // Check if it's a link (object) rather than a scalar
            // A single link is compared by the foreign key it stores, the
            // same way `.link = obj` is one step higher up
            // (`any(.access_grants.account = account)`). A multi-link has no
            // column to compare and would need a junction of its own.
            let single_link = target_td
                .links
                .iter()
                .find(|l| l.name == first_name && !l.is_junction_backed());
            if single_link.is_none() && target_td.multilinks.iter().any(|l| l.name == first_name) {
                let target_display = target_type.replace("::", ".");
                return Err(PyQLError::Type(PyQLTypeError {
                    message: format!(
                        "operator '{op}' cannot be applied to operands of type '{target_display}' and the value type",
                        op = op,
                    ),
                    position: Position { line: 0, col: 0 },
                }));
            }
            let (prop_name, prop_pg) = match single_link {
                Some(link) => (format!("{}_id", link.name), "uuid".to_string()),
                None => {
                    let prop = target_td
                        .properties
                        .iter()
                        .find(|p| p.name == first_name)
                        .ok_or_else(|| self.field_err(&first_name, target_type))?;
                    (prop.name.clone(), prop.pg_type.clone())
                }
            };
            let tgt_alias = self.fresh_alias();
            // Build EXISTS(SELECT 1 FROM target WHERE target.id = jt.target AND target.prop op value)
            let id_filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: tgt_alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: IrExpr::ColumnRef {
                    alias: jt_alias.to_string(),
                    column: jt_tgt_col.to_string(),
                    pg_type: "uuid".to_string(),
                },
            }));
            let prop_col = IrExpr::ColumnRef {
                alias: tgt_alias.clone(),
                column: prop_name,
                pg_type: prop_pg,
            };
            let (pl, pr) = if flip {
                (value_expr, prop_col)
            } else {
                (prop_col, value_expr)
            };
            let prop_filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: pl,
                op,
                right: pr,
            }));
            let full = IrExpr::BinOp(Box::new(IrBinOp {
                left: id_filter,
                op: ast::BinOpKind::And,
                right: prop_filter,
            }));
            let inner = IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                IrSource {
                    poly: None,
                    type_name: target_type.to_string(),
                    table: target_table,
                    alias: tgt_alias,
                },
                vec![],
                Some(full),
            )));
            return Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                op: ast::UnaryOpKind::Exists,
                operand: inner,
            })));
        }

        // steps.len() >= 2: first_name must be a single link (not multi)
        if target_td.multilinks.iter().any(|l| l.name == first_name) {
            return Err(self.type_err("nested multi-link traversal in comparison is not yet supported"));
        }
        let link = target_td
            .links
            .iter()
            .find(|l| l.name == first_name)
            .ok_or_else(|| self.field_err(&first_name, target_type))?;
        if link.is_junction_backed() {
            // A junction-backed link's correlation is a subquery, not a
            // plain FK column, and this recursive path-tail resolver is
            // built entirely around passing a (alias, column) pair down to
            // the next level — supporting it here would need a broader
            // signature change. Fail loudly rather than silently reference
            // a `{name}_id` column that doesn't exist for this link.
            return Err(self.type_err(&format!(
                "filtering through a junction-backed single link ('{first_name}') nested inside \
                 a multi-link path comparison is not yet supported — filter on '.{first_name}' \
                 directly instead"
            )));
        }
        let next_target = link.target.clone();
        let fk_col = format!("{}_id", first_name);
        let tgt_alias = self.fresh_alias();

        // FK optimisation for [single_link, "id"]:
        if steps.len() == 2
            && let Some(ast::PathStep::Name(n)) = steps.get(1)
            && n == "id"
        {
            // Compare tgt.{fk_col} (the FK in current target) directly
            // We need an EXISTS over the target to access fk_col
            // Actually: EXISTS(target WHERE target.id = jt.target AND target.{fk_col} op value)
            let id_filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: IrExpr::ColumnRef {
                    alias: tgt_alias.clone(),
                    column: "id".to_string(),
                    pg_type: "uuid".to_string(),
                },
                op: ast::BinOpKind::Eq,
                right: IrExpr::ColumnRef {
                    alias: jt_alias.to_string(),
                    column: jt_tgt_col.to_string(),
                    pg_type: "uuid".to_string(),
                },
            }));
            let fk_ref = IrExpr::ColumnRef {
                alias: tgt_alias.clone(),
                column: fk_col,
                pg_type: "uuid".to_string(),
            };
            let (fl, fr) = if flip {
                (value_expr, fk_ref)
            } else {
                (fk_ref, value_expr)
            };
            let fk_filter = IrExpr::BinOp(Box::new(IrBinOp {
                left: fl,
                op,
                right: fr,
            }));
            let full = IrExpr::BinOp(Box::new(IrBinOp {
                left: id_filter,
                op: ast::BinOpKind::And,
                right: fk_filter,
            }));
            let inner = IrExpr::Subquery(Box::new(IrSelect::schema_bound(
                IrSource {
                    poly: None,
                    type_name: target_type.to_string(),
                    table: target_table,
                    alias: tgt_alias,
                },
                vec![],
                Some(full),
            )));
            return Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
                op: ast::UnaryOpKind::Exists,
                operand: inner,
            })));
        }

        // General case: EXISTS(target WHERE target.id = jt.jt_tgt_col AND <tail_filter for steps[1..]>)
        // Recursive call uses tgt_alias.fk_col as the "pointer to the next type's id"
        let id_filter = IrExpr::BinOp(Box::new(IrBinOp {
            left: IrExpr::ColumnRef {
                alias: tgt_alias.clone(),
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            },
            op: ast::BinOpKind::Eq,
            right: IrExpr::ColumnRef {
                alias: jt_alias.to_string(),
                column: jt_tgt_col.to_string(),
                pg_type: "uuid".to_string(),
            },
        }));
        let nested_filter =
            self.compile_path_tail_filter(&steps[1..], op, value_expr, flip, &next_target, &tgt_alias, &fk_col)?;
        let full = IrExpr::BinOp(Box::new(IrBinOp {
            left: id_filter,
            op: ast::BinOpKind::And,
            right: nested_filter,
        }));
        let inner = IrExpr::Subquery(Box::new(IrSelect::schema_bound(
            IrSource {
                poly: None,
                type_name: target_type.to_string(),
                table: target_table,
                alias: tgt_alias,
            },
            vec![],
            Some(full),
        )));
        Ok(IrExpr::UnaryOp(Box::new(IrUnaryOp {
            op: ast::UnaryOpKind::Exists,
            operand: inner,
        })))
    }
}

/// Where a walk reads a multi-link this statement also wrote: the CTE holding
/// the junction rows, and — when the targets were inserted here too — the CTE
/// holding those.
#[derive(Clone)]
struct JunctionReadOverride {
    junction: String,
    targets: Option<String>,
}

/// What an `UNLESS CONFLICT … ELSE (UPDATE …)` clause contributes: the
/// `DO UPDATE SET` assignments, and the predicate deciding whether the
/// conflicting row is touched at all when the ELSE UPDATE carried a filter.
struct ConflictElse {
    sets: Vec<(String, IrExpr)>,
    predicate: Option<IrExpr>,
}

impl<'a> Compiler<'a> {
    /// Compile `UNLESS CONFLICT [ON expr] [ELSE (UPDATE …)]` into `IrConflict`.
    fn compile_conflict(
        &mut self,
        uc: &ast::UnlessConflict,
        td: &TypeDescriptor,
    ) -> Result<(IrConflict, Vec<IrMultiLinkMutation>), PyQLError> {
        // ON clause: compile with empty alias → bare column name (`"col"` not `"t0"."col"`)
        // so the emitter produces `ON CONFLICT ("name")` not `ON CONFLICT ("t0"."name")`.
        let on = uc.on.as_ref().map(|e| self.compile_expr(e, td, "")).transpose()?;
        let mut appends = vec![];
        let mut do_update_where = None;
        let do_update = match uc.else_.as_ref() {
            Some(e) => {
                let resolved = self.compile_conflict_else(e, &mut appends)?;
                do_update_where = resolved.predicate;
                Some(resolved.sets)
            }
            None => None,
        };
        Ok((
            IrConflict {
                on,
                do_update,
                do_update_where,
            },
            appends,
        ))
    }

    /// Compile the ELSE clause of UNLESS CONFLICT, which must be `(UPDATE Type SET { … })`.
    ///
    /// Assignments are compiled with the target table's own bare name (not
    /// schema-qualified, and not the usual `t0`-style fresh alias) as the
    /// qualifying "alias" so a self-referencing RHS (`.stock` in `stock :=
    /// .stock + 1`) resolves unambiguously to the *existing* conflicting
    /// row. A genuinely bare, unqualified column reference here is
    /// ambiguous in Postgres between the existing row and the `excluded`
    /// pseudo-row (confirmed live: "column reference ... is ambiguous")
    /// even though only one of the two is ever actually reachable this way
    /// (nothing here ever compiles a reference to `excluded`) — Postgres's
    /// own docs describe exactly this qualification: "the existing row
    /// using the table's name (or an alias)," no explicit `AS` needed on
    /// the INSERT target for that self-reference to work.
    fn compile_conflict_else(
        &mut self,
        expr: &Expr,
        appends: &mut Vec<IrMultiLinkMutation>,
    ) -> Result<ConflictElse, PyQLError> {
        let Expr::SubQuery(stmt) = expr else {
            return Err(self.type_err("UNLESS CONFLICT ELSE must be an UPDATE expression, e.g. ELSE (UPDATE …)"));
        };
        // `else (select usage::Allowance)` — yield the conflicting row rather
        // than change it. `DO NOTHING` returns nothing at all, so the row is
        // read back by assigning its own key to itself, which is what makes
        // `RETURNING` see it.
        if let Stmt::Select(sel) = stmt.as_ref()
            && sel.filter.is_none()
            && sel.limit.is_none()
            && sel.offset.is_none()
            && let Ok(type_name) = self.expr_as_type_name(&sel.result)
            && let Ok(sel_td) = self.resolve_type(&type_name)
        {
            let table = sel_td.table.clone();
            let pk = sel_td
                .properties
                .iter()
                .find(|p| p.is_pk)
                .ok_or_else(|| self.type_err(&format!("type '{type_name}' has no primary key to read back")))?;
            return Ok(ConflictElse {
                sets: vec![(
                    pk.name.clone(),
                    IrExpr::ColumnRef {
                        alias: table,
                        column: pk.name.clone(),
                        pg_type: pk.pg_type.clone(),
                    },
                )],
                predicate: None,
            });
        }
        let Stmt::Update(upd) = stmt.as_ref() else {
            return Err(self.type_err(
                "UNLESS CONFLICT ELSE must be an UPDATE that changes the conflicting row, or a \
                 SELECT of its type to read it back unchanged",
            ));
        };
        let type_name = self.expr_as_type_name(&upd.subject)?;
        let upd_td = self.resolve_type(&type_name)?;
        let table = upd_td.table.clone();
        // The ON CONFLICT target says *which* row conflicts; the ELSE UPDATE's
        // own filter says whether to touch it at all, and it is honoured.
        // Dropping it silently turned `unless conflict on .key else (update T
        // filter .expires_at < now() set { … })` into an unconditional steal of
        // a live advisory lock. Compiled against the table name, which is what
        // refers to the *existing* row inside `DO UPDATE` (`excluded` is the
        // proposed one).
        let do_update_where = upd
            .filter
            .as_ref()
            .map(|f| self.as_condition(|c| c.compile_expr(f, upd_td, &table)))
            .transpose()?;
        // A multi-link cannot be written by `DO UPDATE SET` — junction rows
        // are separate DML. Appending them to the enclosing insert instead
        // applies them to whichever row comes back, inserted or conflicting,
        // and the junction insert is `ON CONFLICT DO NOTHING`, so the
        // inserted branch (which already wrote the same rows from its own
        // shape) is unaffected.
        let mut scalar_shape = vec![];
        for el in &upd.shape {
            let pointer_name = path_leaf(&el.path)?;
            let Some(ml) = Self::resolve_multilink(upd_td, pointer_name) else {
                scalar_shape.push(el.clone());
                continue;
            };
            if el.op == ShapeOp::Remove {
                return Err(self.type_err(&format!(
                    "cannot use `-=` for multi-link '{pointer_name}' inside an UNLESS CONFLICT \
                     ELSE clause; the rows to remove are not known until the conflict resolves"
                )));
            }
            let Some(value) = &el.compexpr else { continue };
            let (jt, module, src_col, tgt_col, through_td) = self.own_multilink_junction_info(upd_td, ml)?;
            let values = self.compile_multilink_values(value, upd_td, &table, through_td)?;
            appends.push(IrMultiLinkMutation {
                junction_table: jt,
                module,
                source_col: src_col,
                target_col: tgt_col,
                values,
                single: false,
            });
        }
        let sets = self.compile_assignments_for_update(&scalar_shape, upd_td, &table)?;
        Ok(ConflictElse {
            sets,
            predicate: do_update_where,
        })
    }

    /// Compile a nested INSERT/UPDATE/DELETE into its own CTE and return that
    /// CTE's name. Postgres cannot run DML inside another statement's value
    /// list, so it is hoisted into the enclosing statement's `WITH` and read
    /// back from there — see `pending_nested_ctes`.
    /// Compile a DML statement into a CTE of the query's own `WITH`.
    ///
    /// Unlike `hoist_nested_dml`, whose CTE belongs to the enclosing
    /// INSERT/UPDATE it was nested inside, this one has no enclosing statement
    /// to attach to — the select that names it *is* the top level.
    fn hoist_dml_as_cte(&mut self, stmt: &Stmt) -> Result<(String, String), PyQLError> {
        let type_name = self.dml_subject_type(stmt)?;
        let before = std::mem::take(&mut self.for_vars_read);
        let inner = self.compile_stmt(stmt);
        let read = std::mem::replace(&mut self.for_vars_read, before);
        let correlated_to = self
            .for_scope
            .iter()
            .rev()
            .find(|slot| read.contains(*slot))
            .map(|slot| format!("_for_{slot}"));
        self.for_vars_read.extend(read);
        let cte_name = self.fresh_nested_cte_name();
        if let Some(slot) = correlated_to.as_deref().and_then(|i| i.strip_prefix("_for_")) {
            self.correlated_bindings.insert(cte_name.clone(), slot.to_string());
        }
        self.hoisted_ctes.push(IrCteDef {
            name: cte_name.clone(),
            stmt: inner?,
            type_name: type_name.clone(),
            correlated_to,
        });
        Ok((cte_name, type_name))
    }

    /// True when a `for`'s body ultimately mutates, through however many
    /// nested loops. A loop over loops over a `select` mutates nothing.
    fn for_body_mutates(stmt: &Stmt) -> bool {
        match stmt {
            Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_) => true,
            Stmt::For(inner) => Self::for_body_mutates(&inner.body),
            _ => false,
        }
    }

    /// `select (for x in S union (insert T { … })) { id }` — a loop whose body
    /// mutates cannot be a select's source as written: the source is emitted as
    /// a `CROSS JOIN LATERAL`, and Postgres allows a data-modifying statement
    /// only at the top level of a `WITH`. So the loop is bound to a CTE of its
    /// own and the select re-rooted at that name, which is the `with c := (for
    /// … union (insert …)) select c { id }` spelling the binding path already
    /// builds. Compiling the loop up front also puts its variable in scope
    /// before the body's subject is resolved, which an `update x` body needs.
    /// Returns the re-rooted result expression, or `None` when the select's
    /// source is not such a loop.
    fn bind_mutating_loop_source(&mut self, result_expr: &Expr) -> Result<Option<Expr>, PyQLError> {
        let (subject, shape) = match result_expr {
            Expr::SubQuery(stmt) => (stmt.as_ref(), None),
            Expr::Shape(sh) => match sh.expr.as_ref() {
                Some(Expr::SubQuery(stmt)) => (stmt.as_ref(), Some(sh.as_ref())),
                _ => return Ok(None),
            },
            _ => return Ok(None),
        };
        if !matches!(subject, Stmt::For(f) if Self::for_body_mutates(&f.body)) {
            return Ok(None);
        }
        // An enclosing loop's variable read from inside this one makes the CTE
        // correlated to that iteration, the same bookkeeping `hoist_dml_as_cte`
        // does for a mutation hoisted out of a loop.
        let before = std::mem::take(&mut self.for_vars_read);
        let inner = self.compile_stmt(subject);
        let read = std::mem::replace(&mut self.for_vars_read, before);
        let correlated_to = self
            .for_scope
            .iter()
            .rev()
            .find(|slot| read.contains(*slot))
            .map(|slot| format!("_for_{slot}"));
        self.for_vars_read.extend(read);
        let inner = inner?;
        let cte_name = self.fresh_nested_cte_name();
        if let Some(slot) = correlated_to.as_deref().and_then(|i| i.strip_prefix("_for_")) {
            self.correlated_bindings.insert(cte_name.clone(), slot.to_string());
        }
        let type_name = self.register_cte(&cte_name, &inner);
        self.hoisted_ctes.push(IrCteDef {
            name: cte_name.clone(),
            stmt: inner,
            type_name,
            correlated_to,
        });
        let bound = Expr::Path(ast::Path {
            steps: vec![ast::PathStep::Name(cte_name)],
            partial: false,
        });
        Ok(Some(match shape {
            Some(sh) => Expr::Shape(Box::new(ast::ShapeExpr {
                expr: Some(bound),
                elements: sh.elements.clone(),
                marker_offset: sh.marker_offset,
            })),
            None => bound,
        }))
    }

    fn hoist_nested_dml(&mut self, stmt: &Stmt) -> Result<String, PyQLError> {
        let type_name = self.dml_subject_type(stmt)?;
        let inner = self.compile_stmt(stmt)?;
        let cte_name = self.fresh_nested_cte_name();
        self.pending_nested_ctes.push(IrCteDef {
            name: cte_name.clone(),
            stmt: inner,
            type_name,
            correlated_to: None,
        });
        Ok(cte_name)
    }

    /// Compile `(SELECT TargetType FILTER …)` as a scalar subquery for use in a
    /// link assignment (`company := (SELECT Company FILTER .name = $co)`).
    /// Returns `IrExpr::Subquery` whose shape is the target pk — the SQL emitter
    /// renders this as `(SELECT "alias"."id" FROM … WHERE …)`.
    fn compile_link_subquery(&mut self, stmt: &Stmt) -> Result<IrExpr, PyQLError> {
        // `preferences := (insert Preferences { … })` — the nested DML used
        // directly as the value, which is the same hoist the wrapped
        // `select (insert …) { id }` form below goes through.
        if matches!(stmt, Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) {
            let cte_name = self.hoist_nested_dml(stmt)?;
            return Ok(IrExpr::ColumnRef {
                alias: cte_name,
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            });
        }
        let Stmt::Select(sel) = stmt else {
            return Err(self.type_err(
                "only SELECT is valid as a link assignment value; \
                 use SELECT (INSERT …) { id } to assign from a DML result",
            ));
        };

        // `SELECT (INSERT …) { id }` / `SELECT (UPDATE …) { id }` /
        // `SELECT (DELETE …) { id }` — the exact workaround this function's
        // own error message above recommends. Postgres has no way to run a
        // nested INSERT/UPDATE/DELETE inside another statement's value list
        // without hoisting it into a `WITH` CTE first, so that's what this
        // does: compile the inner DML as its own statement, stash it in
        // `self.pending_nested_ctes` under a fresh CTE name (drained by
        // whichever `compile_insert`/`compile_update` is compiling the
        // assignment this value belongs to — see those functions' own doc
        // comments — and prepended as a `WITH` CTE by the emitter, which
        // also switches the outer statement's own row source from
        // `VALUES (...)` / a bare `SET` to something that can actually
        // reference it), and return a plain reference to that CTE's `id`
        // column in place of the subquery.
        //
        // A prior attempt to handle this by delegating to `compile_select`
        // (which does know how to chain a `dml_source`, but only for a
        // *top-level* `SELECT (INSERT …) { ... }` statement) compiled
        // without error but silently emitted a subquery that dropped the
        // nested INSERT and selected an unrelated, arbitrary pre-existing
        // row instead — do not repeat that approach.
        let nested_dml = match &sel.result {
            Expr::SubQuery(inner) if matches!(inner.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) => {
                Some(inner.as_ref())
            }
            Expr::Shape(s) => match s.expr.as_ref() {
                Some(Expr::SubQuery(inner))
                    if matches!(inner.as_ref(), Stmt::Insert(_) | Stmt::Update(_) | Stmt::Delete(_)) =>
                {
                    Some(inner.as_ref())
                }
                _ => None,
            },
            _ => None,
        };
        if let Some(inner_stmt) = nested_dml {
            let cte_name = self.hoist_nested_dml(inner_stmt)?;
            return Ok(IrExpr::ColumnRef {
                alias: cte_name,
                column: "id".to_string(),
                pg_type: "uuid".to_string(),
            });
        }

        let type_name = self.expr_as_type_name(&sel.result)?;
        let td = self.resolve_type(&type_name)?;
        let alias = self.fresh_alias();

        // `(select T filter … order by … limit 1)` — every clause decides
        // which row is linked, not just the filter.
        let (filter, order_by, offset, limit) = self.compile_path_modifiers(sel, td, &alias)?;
        let mut select = IrSelect::schema_bound(
            IrSource {
                poly: None,
                type_name: format!("{}::{}", td.module, td.name),
                table: td.table.clone(),
                alias,
            },
            Self::pk_returning(td),
            filter,
        );
        select.order_by = order_by;
        select.offset = offset;
        select.limit = limit;
        Ok(IrExpr::Subquery(Box::new(select)))
    }

    /// Shared `IrSort` builder for both schema-bound (`compile_sort`) and
    /// free (`compile_free_select`'s order-by) contexts — direction/nulls
    /// translation is identical either way, only the expr compiler ctx differs.
    fn compile_sort_ctx(
        &mut self,
        s: &ast::SortExpr,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrSort, PyQLError> {
        Ok(IrSort {
            expr: self.compile_expr_ctx(&s.expr, ctx)?,
            direction: match s.direction {
                SortDirection::Asc => IrSortDir::Asc,
                SortDirection::Desc => IrSortDir::Desc,
            },
            nulls: match s.nones {
                NonesOrder::First => IrNulls::First,
                NonesOrder::Last => IrNulls::Last,
            },
        })
    }

    fn compile_sort(&mut self, s: &ast::SortExpr, td: &TypeDescriptor, alias: &str) -> Result<IrSort, PyQLError> {
        self.compile_sort_ctx(s, Some((td, alias)))
    }

    // ── Stdlib function resolution ────────────────────────────────────────────────

    /// Look up `name` in the stdlib (namespace = `module` or `"std"`) and produce
    /// the correct `IrExpr::FunctionCall` based on the matching `ImplStrategy`.
    /// Falls through to a plain call if no overload is found (unknown / PG built-in).
    /// `message := …` of an assert handled outside the generic call route,
    /// which would otherwise drop it and raise the assert's own text.
    fn assert_message(
        &mut self,
        f: &ast::FunctionCall,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<IrExpr>, PyQLError> {
        let mut message = None;
        for (name, value) in &f.kwargs {
            if name != "message" {
                return Err(self.type_err(&format!("function 'std::{}' has no parameter '{name}'", f.name)));
            }
            message = Some(self.compile_expr_ctx(value, ctx)?);
        }
        Ok(message)
    }

    /// A stdlib call against its named-only parameters — `message :=` of the
    /// asserts, every parameter of `cal::to_relative_duration`. The arguments
    /// come back in parameter order, each named-only one left out standing
    /// at its default. `None` for a call that names nothing and needs no
    /// default, which the positional route handles as it always has.
    fn compile_named_call_args(
        &mut self,
        f: &ast::FunctionCall,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<Option<Vec<IrExpr>>, PyQLError> {
        use crate::stdlib::NamedDefault;

        let ns = f.module.as_deref().unwrap_or("std");
        let overloads = crate::stdlib::lookup(ns, &f.name);
        let positional = |d: &crate::stdlib::FnDescriptor| d.params.iter().filter(|p| p.named_only.is_none()).count();
        let named = |d: &crate::stdlib::FnDescriptor| d.params.iter().filter(|p| p.named_only.is_some()).count();
        // A variadic parameter absorbs any number of the positional arguments,
        // so it fixes only a floor on how many a call may pass.
        let takes_positionally = |d: &crate::stdlib::FnDescriptor| {
            if d.is_variadic() {
                f.args.len() + 1 >= positional(d)
            } else {
                positional(d) == f.args.len()
            }
        };
        if f.kwargs.is_empty() {
            if overloads.iter().any(|d| takes_positionally(d) && named(d) == 0) {
                return Ok(None);
            }
            // Only when the call passed *more* positionally than an overload's
            // positions hold, and no more than its whole parameter list: that
            // is a call writing the named-only ones by position, as opposed to
            // one whose argument count is simply wrong.
            let wrote_a_named_one_positionally =
                |d: &crate::stdlib::FnDescriptor| positional(d) < f.args.len() && f.args.len() <= d.params.len();
            if !overloads.iter().any(|d| takes_positionally(d))
                && let Some(param) = overloads
                    .iter()
                    .filter(|d| wrote_a_named_one_positionally(d))
                    .flat_map(|d| d.params.iter())
                    .find(|p| p.named_only.is_some())
                    .map(|p| p.keyword())
            {
                return Err(self.type_err(&format!(
                    "function '{ns}::{}' takes '{param}' as a named argument only — e.g. '{param} := …'",
                    f.name
                )));
            }
        }
        let fits = |d: &&&crate::stdlib::FnDescriptor| {
            takes_positionally(d)
                && named(d) > 0
                && f.kwargs
                    .iter()
                    .all(|(name, _)| d.params.iter().any(|p| p.keyword() == name && p.named_only.is_some()))
        };
        let Some(desc) = overloads.iter().find(fits) else {
            if let Some((name, _)) = f.kwargs.first() {
                let message = if overloads.iter().all(|d| named(d) == 0) {
                    format!(
                        "function '{ns}::{}' does not take named arguments, got '{name}'",
                        f.name
                    )
                } else {
                    format!("function '{ns}::{}' has no parameter '{name}'", f.name)
                };
                return Err(self.type_err(&message));
            }
            return Ok(None);
        };
        let mut args = f
            .args
            .iter()
            .map(|a| self.compile_expr_ctx(a, ctx))
            .collect::<Result<Vec<_>, _>>()?;
        for param in desc.params.iter().filter(|p| p.named_only.is_some()) {
            let arg = match (
                f.kwargs.iter().find(|(name, _)| name == param.keyword()),
                param.named_only,
            ) {
                (Some((_, value)), _) => self.compile_expr_ctx(value, ctx)?,
                (None, Some(NamedDefault::Required)) => {
                    let keyword = param.keyword();
                    return Err(self.type_err(&format!(
                        "function '{ns}::{}' requires the named argument '{keyword}' — e.g. '{keyword} := …'",
                        f.name
                    )));
                }
                (None, Some(NamedDefault::Int(n))) => IrExpr::Literal(IrLiteral::Int(n)),
                (None, Some(NamedDefault::Bool(b))) => IrExpr::Literal(IrLiteral::Bool(b)),
                (None, Some(NamedDefault::Str(s))) => IrExpr::Literal(IrLiteral::Str(s.to_string())),
                (None, _) => IrExpr::Null,
            };
            args.push(arg);
        }
        Ok(Some(args))
    }

    fn resolve_fn_call(&mut self, module: Option<&str>, name: &str, args: Vec<IrExpr>) -> Result<IrExpr, PyQLError> {
        use crate::stdlib::{ImplStrategy, lookup};

        let ns = module.unwrap_or("std");
        // `any`/`all` aggregate a *set* of booleans. Everything that reaches
        // here is a single value — a multi-link comparison has already become
        // its own EXISTS — and a single boolean is its own any()/all();
        // `bool_or` over it would be an aggregate where SQL allows none.
        if ns == "std" && matches!(name, "any" | "all") && args.len() == 1 && !is_array_expr(&args[0]) {
            return Ok(args.into_iter().next().expect("checked by the guard"));
        }
        let overloads = lookup(ns, name);

        // Arity is decided first and on its own, so a call no overload could
        // accept is never type-matched against one anyway. Named-only
        // parameters are already materialized into `args` by
        // `compile_named_call_args`, so the comparison is against the full
        // parameter list; a trailing variadic absorbs zero or more, matching
        // `pylon.stdlib._arity_matches`, the same rule the Python surface
        // has always applied to `std.foo(...)`.
        let by_arity: Vec<&crate::stdlib::FnDescriptor> = overloads
            .iter()
            .copied()
            .filter(|d| {
                if d.is_variadic() {
                    args.len() + 1 >= d.params.len()
                } else {
                    d.params.len() == args.len()
                }
            })
            .collect();

        // Pick the overload whose parameter types best match the argument
        // types. An overload whose declared types are exactly what is known
        // of the arguments beats one that merely accepts them:
        // `to_str(<bytes>)` is the bytes overload, not the first one whose
        // parameter type no check rejects.
        let exact = by_arity.iter().copied().find(|d| {
            params_for_args(d, args.len())
                .zip(&args)
                .any(|(p, a)| p.ty.scalar_pg_type().is_some() && infer_ir_type(a).is_some())
                && params_for_args(d, args.len()).zip(&args).all(|(p, a)| {
                    match (p.ty.scalar_pg_type(), infer_ir_type(a)) {
                        (Some(declared), Some(known)) => declared == known,
                        _ => pylon_type_matches(a, &p.ty),
                    }
                })
        });
        let best = exact.or_else(|| {
            by_arity.iter().copied().find(|d| {
                params_for_args(d, args.len())
                    .zip(&args)
                    .all(|(p, a)| pylon_type_matches(a, &p.ty))
            })
        });

        // A parameter that takes one value takes the walk's value, not the
        // array its rows were gathered into: `contains(ids, .<menus.id)`
        // compares uuids. A `set of …`/`array<…>` parameter asked for the
        // whole set and keeps it.
        let args_len = args.len();
        let args: Vec<IrExpr> = match best {
            Some(descriptor) => args
                .into_iter()
                .enumerate()
                .map(
                    |(i, arg)| match params_for_args(descriptor, args_len).nth(i).map(|p| &p.ty) {
                        Some(crate::stdlib::PylonType::Set(_)) | Some(crate::stdlib::PylonType::Array(_)) | None => arg,
                        Some(_) => set_walk_as_scalar(arg),
                    },
                )
                .collect(),
            None => args,
        };
        let args = match best {
            Some(descriptor) => pack_variadic_args(descriptor, args),
            None => args,
        };

        // An `optional<…>` return still travels as its own scalar — a call
        // that may yield nothing (`json_get`) is typed by what it yields when
        // it does, or every cast and overload over it reads as untyped.
        let stdlib_return = best
            .map(|d| match &d.return_type {
                crate::stdlib::PylonType::Optional(inner) => inner.as_ref(),
                other => other,
            })
            .and_then(|ty| ty.scalar_pg_type())
            .map(str::to_string);
        let (schema, resolved_name, sql_template) = if let Some(desc) = best {
            match &desc.impl_strategy {
                ImplStrategy::SqlBuiltin(sql_name) => (None, sql_name.to_string(), None),
                ImplStrategy::SqlExpression(tmpl) => (None, name.to_string(), Some(tmpl.to_string())),
                ImplStrategy::PylonFunction(def) => (Some("_pylon".to_string()), def.name.to_string(), None),
                // Binary infix operator: emit as a template so sql/mod.rs's
                // generic FunctionCall path (which only ever calls
                // `schema.name(args)`) doesn't swallow the operator symbol —
                // previously unreachable in practice (only `std::overlaps`
                // used this strategy, untested, and would have silently
                // resolved to a nonexistent `"std".overlaps(...)` call).
                ImplStrategy::SqlOperator(op) if args.len() == 2 => {
                    (None, name.to_string(), Some(format!("($1 {op} $2)")))
                }
                ImplStrategy::TranspilerIntrinsic(intrinsic) => {
                    return self.compile_range_intrinsic(intrinsic, name, args);
                }
                // TranspilerIntrinsic: pass through; handled elsewhere
                _ => (module.map(str::to_string), name.to_string(), None),
            }
        } else {
            // Fall back to user-defined scalar functions. Overload
            // resolution is by (module, name, argument count) only — true
            // Postgres-style resolution by argument *type* isn't
            // implemented (a call whose args happen to have the right
            // count for the wrong-typed overload still picks that one,
            // relying on the forced TypeCast below rather than erroring).
            // Candidates are searched for one whose param count actually
            // matches the call — taking just the first (module, name)
            // match regardless of arg count used to silently pick the
            // wrong overload's signature (and then error on arg count)
            // whenever an earlier-declared overload happened to have a
            // different arity than the one actually being called
            // (confirmed live: a 2-arg call to an overload set whose
            // first-declared member takes 1 arg reported "expects 1
            // argument(s), got 2" even though a 2-arg overload existed).
            let candidates: Vec<&FunctionDescriptor> = self
                .schema
                .functions
                .iter()
                .filter(|f| {
                    let module_matches = module.map(|m| m == f.module.as_str()).unwrap_or(true);
                    module_matches && f.name == name && !f.return_is_object
                })
                .collect();
            let user_fn = candidates
                .iter()
                .find(|f| f.params.len() == args.len())
                .copied()
                .or_else(|| candidates.first().copied());
            if let Some(fd) = user_fn {
                if fd.params.len() != args.len() {
                    return Err(self.type_err(&format!(
                        "function '{}::{}' expects {} argument(s), got {}",
                        fd.module,
                        fd.name,
                        fd.params.len(),
                        args.len()
                    )));
                }
                let cast_args = fd
                    .params
                    .iter()
                    .zip(args)
                    .map(|(p, a)| {
                        IrExpr::TypeCast(Box::new(super::IrTypeCast {
                            expr: a,
                            pg_type: p.pg_type.clone(),
                            tuple_shape: None,
                        }))
                    })
                    .collect();
                let qualified = format!("{}::{}", fd.module, fd.name);
                let fn_module = fd.module.clone();
                let fn_name = fd.name.clone();
                let mut call_args: Vec<IrExpr> = cast_args;
                if let Some(globals) = self.globals_arg_for_call(&qualified)? {
                    call_args.insert(0, globals);
                }
                // A set-returning function has no single value to type, and
                // the declared type of an object-returning one names a type,
                // not a column — neither is a scalar `infer_ir_type` may
                // report.
                let return_pg_type = (!fd.return_is_set).then(|| fd.return_pg_type.clone());
                return Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                    return_pg_type,
                    schema: Some(fn_module),
                    name: fn_name,
                    args: call_args,
                    sql_template: None,
                }));
            }
            // An object-returning function is deliberately not a candidate
            // above — it compiles through `try_compile_fn_object_select`, which
            // only runs when the call is a select's subject. Saying "does not
            // exist" for one that plainly does (and naming `default::` for a
            // call the user wrote unqualified) sent people looking for a typo
            // instead of at the restriction.
            if let Some(fd) = self.schema.functions.iter().find(|f| {
                let module_matches = module.map(|m| m == f.module.as_str()).unwrap_or(true);
                module_matches && f.name == name && f.return_is_object
            }) {
                return Err(self.type_err(&format!(
                    "function '{}::{}' returns objects, so it can only be the subject of a \
                     select (`select {}::{}(…) {{ … }}`), not part of a larger expression",
                    fd.module, fd.name, fd.module, fd.name
                )));
            }
            let qualified = match module {
                Some(m) => format!("{m}::{name}"),
                None => name.to_string(),
            };
            // The name is real and only the call is wrong — say which,
            // rather than resolving to whichever overload happened to be
            // registered first and letting PostgreSQL reject the emitted
            // SQL at query time with a signature the author never wrote.
            if !overloads.is_empty() {
                return Err(self.type_err(&if by_arity.is_empty() {
                    format!(
                        "function '{qualified}' takes {}, got {}",
                        describe_arities(&overloads),
                        args.len()
                    )
                } else {
                    format!(
                        "function '{qualified}' has no overload accepting ({}) — it accepts {}",
                        describe_args(&args),
                        describe_signatures(&by_arity),
                    )
                }));
            }
            return Err(self.type_err(&format!(
                "function '{qualified}' does not exist{}",
                self.suggest_function_name(ns, name)
            )));
        };

        Ok(IrExpr::FunctionCall(super::IrFunctionCall {
            return_pg_type: stdlib_return,
            schema,
            name: resolved_name,
            args,
            sql_template,
        }))
    }

    /// Resolve `std::range(...)`/`std::multirange(...)` — `TranspilerIntrinsic`
    /// entries with no real backing function anywhere (no `_pylon` function,
    /// no bare PostgreSQL builtin of that literal name). PostgreSQL has no
    /// single polymorphic range constructor — the concrete constructor
    /// (`int8range`, `numrange`, `tsrange`, `tstzrange`, `daterange`, and
    /// their multirange counterparts) is chosen here from the resolved
    /// element type of the arguments, since there's nothing generic to defer
    /// to at the SQL level the way `to_jsonb(x)` covers "cast to json".
    fn compile_range_intrinsic(&self, intrinsic: &str, name: &str, args: Vec<IrExpr>) -> Result<IrExpr, PyQLError> {
        match intrinsic {
            "range" => {
                // Either endpoint names the element type, since a range open
                // on one side carries it only on the other.
                let bounds = args.len().saturating_sub(3);
                let point_ty = args[..bounds].iter().find_map(infer_ir_type).ok_or_else(|| {
                    self.type_err(
                        "range(): cannot infer the element type from either bound — \
                     use an explicit cast, e.g. range(<int64>$lower, <int64>$upper)",
                    )
                })?;
                let ctor = range_ctor_for_pg_type(point_ty).ok_or_else(|| {
                    self.type_err(&format!(
                        "range(): unsupported element type '{point_ty}' — PostgreSQL only has native \
                     ranges over int64, decimal, datetime, cal::local_datetime, and cal::local_date"
                    ))
                })?;
                // `inc_lower`/`inc_upper`/`empty` are named-only and so always
                // present, defaults included: four arguments is the form that
                // gave only a lower bound, five the one that gave both.
                let upper = match args.len() {
                    4 => "NULL",
                    5 => "$2",
                    n => return Err(self.type_err(&format!("range(): unexpected argument count {n}"))),
                };
                let flags: Vec<Option<bool>> = args[args.len() - 3..].iter().map(bool_literal).collect();
                // Written out or defaulted, the three are constants at nearly
                // every call site, and folding them keeps a plain `range(a, b)`
                // emitting a plain constructor instead of a CASE over literals.
                let sql_template = match flags[..] {
                    [Some(_), Some(_), Some(true)] => format!("'empty'::{ctor}"),
                    [Some(true), Some(false), Some(false)] => format!("{ctor}($1, {upper})"),
                    [Some(inc_lower), Some(inc_upper), Some(false)] => format!(
                        "{ctor}($1, {upper}, '{}{}')",
                        if inc_lower { '[' } else { '(' },
                        if inc_upper { ']' } else { ')' },
                    ),
                    _ => {
                        let (lower_inc, upper_inc, empty) = match args.len() {
                            4 => ("$2", "$3", "$4"),
                            _ => ("$3", "$4", "$5"),
                        };
                        format!(
                            "(CASE WHEN {empty} THEN 'empty'::{ctor} ELSE {ctor}($1, {upper}, \
                             (CASE WHEN {lower_inc} THEN '[' ELSE '(' END) \
                             || (CASE WHEN {upper_inc} THEN ']' ELSE ')' END)) END)"
                        )
                    }
                };
                // `.name` carries the *resolved* constructor (not the
                // original `range`) so a wrapping `multirange([range(...)])`
                // call can identify the element family — emission always
                // goes through `sql_template` above, so this doesn't change
                // the SQL text.
                // A PostgreSQL range constructor shares its name with the
                // type it builds (`int8range(…)` is an `int8range`), so the
                // ctor doubles as the return type — which is what lets a
                // range reach a `range<anypoint>` parameter as itself rather
                // than as an untyped expression.
                Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                    return_pg_type: Some(ctor.to_string()),
                    schema: None,
                    name: ctor.to_string(),
                    args,
                    sql_template: Some(sql_template),
                }))
            }
            "multirange" => {
                let Some(IrExpr::Array(elems)) = args.first() else {
                    return Err(self.type_err("multirange(): argument must be an array literal of ranges"));
                };
                let first_ctor = elems
                    .first()
                    .and_then(|e| match e {
                        IrExpr::FunctionCall(fc) => Some(fc.name.as_str()),
                        _ => None,
                    })
                    .ok_or_else(|| {
                        self.type_err(
                            "multirange(): cannot infer the element range type from an empty or non-range \
                     array — pass at least one range(...) call, e.g. multirange([range(1, 3)])",
                        )
                    })?;
                let ctor = multirange_ctor_for_range_ctor(first_ctor).ok_or_else(|| {
                    self.type_err(&format!("multirange(): unrecognized range constructor '{first_ctor}'"))
                })?;
                // PostgreSQL's multirange constructors (int8multirange, etc.)
                // are VARIADIC — they don't accept a plain array argument
                // without the VARIADIC keyword.
                Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                    return_pg_type: Some(ctor.to_string()),
                    schema: None,
                    name: name.to_string(),
                    args,
                    sql_template: Some(format!("{ctor}(VARIADIC $1)")),
                }))
            }
            other => Err(self.type_err(&format!("internal error: unhandled TranspilerIntrinsic '{other}'"))),
        }
    }

    // ── Sequence function helpers ──────────────────────────────────────────────────

    /// Compile `sequence_next(SeqType)` → `nextval('"module"."Name_seq"')`
    /// and `sequence_reset(SeqType[, val])` → `setval(...)`.
    fn compile_sequence_fn(&mut self, fc: &ast::FunctionCall) -> Result<IrExpr, PyQLError> {
        let (module, scalar_name) = self.resolve_sequence_scalar_arg(fc)?;

        if fc.name == "sequence_next" {
            if fc.args.len() != 1 {
                return Err(self.type_err("sequence_next takes exactly 1 argument"));
            }
            let sql = format!("nextval('\"{}\".\"{}_seq\"')", module, scalar_name);
            return Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                return_pg_type: None,
                schema: None,
                name: "nextval".into(),
                args: vec![],
                sql_template: Some(sql),
            }));
        }

        // sequence_reset
        match fc.args.len() {
            1 => {
                let sql = format!("setval('\"{}\".\"{}_seq\"', 1, false)", module, scalar_name);
                Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                    return_pg_type: None,
                    schema: None,
                    name: "setval".into(),
                    args: vec![],
                    sql_template: Some(sql),
                }))
            }
            2 => {
                let val = self.compile_free_expr(&fc.args[1])?;
                let sql = format!("setval('\"{}\".\"{}_seq\"', $1, true)", module, scalar_name);
                Ok(IrExpr::FunctionCall(super::IrFunctionCall {
                    return_pg_type: None,
                    schema: None,
                    name: "setval".into(),
                    args: vec![val],
                    sql_template: Some(sql),
                }))
            }
            _ => Err(self.type_err("sequence_reset takes 1 or 2 arguments")),
        }
    }

    /// Resolve the first argument of a sequence function to `(module, scalar_name)`.
    /// The argument must be an unqualified path that names a sequence scalar in the schema.
    fn resolve_sequence_scalar_arg(&self, fc: &ast::FunctionCall) -> Result<(String, String), PyQLError> {
        use crate::parse::ast::{Expr, Path, PathStep};

        let arg = fc.args.first().ok_or_else(|| {
            self.type_err(&format!(
                "{}() requires a sequence scalar type as its first argument",
                fc.name
            ))
        })?;

        // The parser encodes `module::Name` as a single PathStep::Name("module::Name"),
        // so we split on "::" here to recover the module part.
        let (arg_module, arg_name): (Option<&str>, &str) = match arg {
            Expr::Path(Path { steps, partial: false }) => match steps.as_slice() {
                [PathStep::Name(s)] => {
                    if let Some((m, n)) = s.split_once("::") {
                        (Some(m), n)
                    } else {
                        (None, s.as_str())
                    }
                }
                _ => return Err(self.type_err(&format!(
                    "{}(): first argument must be a sequence scalar type name (e.g. OrderNumber or default::OrderNumber)",
                    fc.name
                ))),
            },
            _ => return Err(self.type_err(&format!(
                "{}(): first argument must be a sequence scalar type name (e.g. OrderNumber or default::OrderNumber)",
                fc.name
            ))),
        };

        let scalar = self.schema.scalars.iter().find(|s| {
            s.is_sequence && s.name == arg_name && arg_module.map(|m| m == s.module.as_str()).unwrap_or(true)
        });

        match scalar {
            Some(s) => Ok((s.module.clone(), s.name.clone())),
            None => Err(self.type_err(&format!(
                "{}(): '{}' is not a known sequence scalar type",
                fc.name, arg_name
            ))),
        }
    }

    // ── Channel notify() helpers ────────────────────────────────────────────────

    /// PostgreSQL's hard per-NOTIFY-payload limit (`NOTIFY_PAYLOAD_MAX_LENGTH`
    /// in the Postgres source) — a payload at or over this is rejected by the
    /// server at runtime, always, for every session. Checked here only when
    /// the payload is a literal string (the one case actually decidable at
    /// compile time — see `static_min_payload_bytes` for how much of an
    /// arbitrary payload expression can be sized without running it.
    const NOTIFY_PAYLOAD_MAX_BYTES: usize = 8000;

    /// The rejection every non-object payload for a Type channel shares.
    fn notify_type_payload_err(&self, channel: &str, qname: &str) -> PyQLError {
        self.type_err(&format!(
            "notify(): payload for Channel '{channel}' (a '{qname}' object channel) must name an object of that \
             type — either a with-block binding, or __new__/__old__ inside a trigger handler"
        ))
    }

    /// Compile `notify(Channel, payload)` → `pg_notify('<wire_name>', (<payload>)::text)`.
    /// The payload's required shape depends on the Channel's declared kind:
    /// - `Type(qname)`: payload must be the bare `__new__`/`__old__` trigger
    ///   anchor for that exact type — sends its `.id`, not the whole row (see
    ///   this function's own restriction: a general object-typed expression
    ///   isn't supported yet, only the trigger-anchor case).
    /// - `Scalar(pg_type)`: payload is any expression, best-effort type-checked.
    /// - `Object(fields)`: payload must be a free object literal (`{ a := .., b := .. }`)
    ///   whose field names exactly match the declared shape.
    fn compile_notify(
        &mut self,
        fc: &ast::FunctionCall,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        use crate::parse::ast::{Expr, Path, PathStep};

        if fc.args.len() != 2 {
            return Err(self.type_err("notify() takes exactly 2 arguments: (Channel, payload)"));
        }

        let (channel_module, channel_name): (Option<&str>, &str) = match &fc.args[0] {
            Expr::Path(Path { steps, partial: false }) => match steps.as_slice() {
                [PathStep::Name(s)] => {
                    if let Some((m, n)) = s.split_once("::") {
                        (Some(m), n)
                    } else {
                        (None, s.as_str())
                    }
                }
                _ => {
                    return Err(self.type_err(
                        "notify(): first argument must be a Channel name (e.g. OrderEvents or orders::OrderEvents)",
                    ));
                }
            },
            _ => {
                return Err(self.type_err(
                    "notify(): first argument must be a Channel name (e.g. OrderEvents or orders::OrderEvents)",
                ));
            }
        };
        let full_channel_name = match channel_module {
            Some(m) => format!("{m}::{channel_name}"),
            None => channel_name.to_string(),
        };
        let channel = self
            .resolve_channel(&full_channel_name)
            .ok_or_else(|| self.type_err(&format!("notify(): '{channel_name}' is not a known Channel")))?;
        let wire_name = channel.wire_name.clone();
        let payload_arg = &fc.args[1];

        // A bare `select notify(...)` trigger handler has no type at its
        // root, so the top-level statement compiles as a *free* select
        // (ctx=None) even though `special_anchors` is populated — `__new__`/
        // `__old__` only resolve through `compile_path`, which is only ever
        // reached when ctx is `Some(..)` (see `Expr::Path`'s arm above).
        // Fall back to any bound anchor's (td, alias) as a stand-in ctx so a
        // Scalar/Object payload like `__new__.name` or `{ a := __new__.x }`
        // still resolves — `compile_path`'s own `__new__`/`__old__` branch
        // ignores whatever td/alias ctx carries for those two names anyway,
        // it only matters for a real property access on some other root.
        // Cloned out of `special_anchors` (rather than borrowed) so it
        // doesn't hold an immutable borrow of `self` across the `&mut self`
        // `compile_expr_ctx` calls below.
        let anchor_fallback: Option<(&'a TypeDescriptor, String)> = self.special_anchors.values().next().cloned();
        let ctx = ctx.or_else(|| anchor_fallback.as_ref().map(|(td, alias)| (*td, alias.as_str())));

        let payload_ir = match &channel.payload {
            crate::schema::ChannelPayload::Type(qname) => {
                // The payload for an object channel is the object's `id`, in
                // either of the two places one can be named: the `__new__`/
                // `__old__` anchor a trigger handler runs against, or a
                // with-block binding in an ordinary query — which is what
                // lets a notify compose with the mutation that caused it:
                //
                //   with updated := (update User filter ... set { ... }),
                //   select (notify(UserUpdates, updated), updated)
                let Expr::Path(Path { steps, partial: false }) = payload_arg else {
                    return Err(self.notify_type_payload_err(&full_channel_name, qname));
                };
                let [PathStep::Name(name)] = steps.as_slice() else {
                    return Err(self.notify_type_payload_err(&full_channel_name, qname));
                };

                if name == "__new__" || name == "__old__" {
                    let (anchor_td, alias) = self.special_anchors.get(name.as_str()).cloned().ok_or_else(|| {
                        self.type_err(&format!(
                            "notify(): '{name}' cannot be used here — it's only bound inside a trigger handler"
                        ))
                    })?;
                    let anchor_qname = format!("{}::{}", anchor_td.module, anchor_td.name);
                    if &anchor_qname != qname {
                        return Err(self.type_err(&format!(
                            "notify(): Channel '{full_channel_name}' expects a payload of type '{qname}', got '{anchor_qname}'"
                        )));
                    }
                    IrExpr::ColumnRef {
                        alias,
                        column: "id".to_string(),
                        pg_type: "uuid".to_string(),
                    }
                } else if let Some(cte_type) = self.cte_types.get(name.as_str()).cloned() {
                    if &cte_type != qname {
                        return Err(self.type_err(&format!(
                            "notify(): Channel '{full_channel_name}' expects a payload of type '{qname}', got '{cte_type}'"
                        )));
                    }
                    // `CteRef { scalar: false }` emits `(SELECT "id" FROM
                    // "<cte>")` — the same id the trigger path sends.
                    IrExpr::CteRef {
                        name: name.clone(),
                        scalar: false,
                        pg_type: None,
                    }
                } else {
                    return Err(self.notify_type_payload_err(&full_channel_name, qname));
                }
            }
            crate::schema::ChannelPayload::Scalar(pg_type) => {
                let ir = self.compile_expr_ctx(payload_arg, ctx)?;
                if let Some(actual) = infer_ir_type(&ir)
                    && !types_compatible(actual, pg_type)
                {
                    return Err(self.type_err(&format!(
                            "notify(): Channel '{full_channel_name}' expects a payload of type '{expected}', got '{actual_pyql}'",
                            expected = pg_type_to_pyql(pg_type),
                            actual_pyql = pg_type_to_pyql(actual),
                        )));
                }
                ir
            }
            crate::schema::ChannelPayload::Object(declared_fields) => {
                let Expr::Shape(sh) = payload_arg else {
                    return Err(self.type_err(&format!(
                        "notify(): payload for Channel '{full_channel_name}' (an Object channel) must be a free \
                         object literal, e.g. {{ {} }}",
                        declared_fields
                            .iter()
                            .map(|(n, _)| format!("{n} := .."))
                            .collect::<Vec<_>>()
                            .join(", ")
                    )));
                };
                if sh.expr.is_some() {
                    return Err(self.type_err(&format!(
                        "notify(): payload for Channel '{full_channel_name}' (an Object channel) must be a free \
                         object literal, not a shape over a type"
                    )));
                }
                let ir = self.compile_expr_ctx(payload_arg, ctx)?;
                let IrExpr::NamedTuple {
                    fields,
                    is_free_object: true,
                } = &ir
                else {
                    return Err(self.type_err(&format!(
                        "notify(): payload for Channel '{full_channel_name}' (an Object channel) must be a free object literal"
                    )));
                };
                let declared_names: std::collections::HashSet<&str> =
                    declared_fields.iter().map(|(n, _)| n.as_str()).collect();
                let actual_names: std::collections::HashSet<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
                if declared_names != actual_names {
                    let mut expected: Vec<&str> = declared_names.iter().copied().collect();
                    expected.sort();
                    let mut actual: Vec<&str> = actual_names.iter().copied().collect();
                    actual.sort();
                    return Err(self.type_err(&format!(
                        "notify(): payload fields for Channel '{full_channel_name}' don't match — expected {{{}}}, got {{{}}}",
                        expected.join(", "), actual.join(", ")
                    )));
                }
                for (name, expr) in fields {
                    let Some((_, declared_pg_type)) = declared_fields.iter().find(|(n, _)| n == name) else {
                        continue;
                    };
                    if let Some(actual) = infer_ir_type(expr)
                        && !types_compatible(actual, declared_pg_type)
                    {
                        return Err(self.type_err(&format!(
                                "notify(): field '{name}' of Channel '{full_channel_name}' expects type '{expected}', got '{actual_pyql}'",
                                expected = pg_type_to_pyql(declared_pg_type),
                                actual_pyql = pg_type_to_pyql(actual),
                            )));
                    }
                }
                ir
            }
        };

        let floor = static_min_payload_bytes(payload_arg);
        if floor >= Self::NOTIFY_PAYLOAD_MAX_BYTES {
            return Err(self.type_err(&format!(
                "notify(): this payload is at least {floor} bytes, which is at or over PostgreSQL's {}-byte NOTIFY \
                 payload limit — the notification would fail at runtime, aborting the transaction that sent it",
                Self::NOTIFY_PAYLOAD_MAX_BYTES
            )));
        }

        let sql = format!("pg_notify('{}', ($1)::text)", wire_name.replace('\'', "''"));
        Ok(IrExpr::FunctionCall(super::IrFunctionCall {
            return_pg_type: None,
            schema: None,
            name: "pg_notify".to_string(),
            args: vec![payload_ir],
            sql_template: Some(sql),
        }))
    }

    /// Compile `notify_raw(channel_name, payload)` → `pg_notify($1, $2)` — the
    /// escape hatch that bypasses Channel resolution and payload-shape
    /// checking entirely: both arguments are arbitrary text expressions.
    fn compile_notify_raw(
        &mut self,
        fc: &ast::FunctionCall,
        ctx: Option<(&TypeDescriptor, &str)>,
    ) -> Result<IrExpr, PyQLError> {
        if fc.args.len() != 2 {
            return Err(self.type_err("notify_raw() takes exactly 2 arguments: (channel_name, payload)"));
        }
        let channel_ir = self.compile_expr_ctx(&fc.args[0], ctx)?;
        let payload_ir = self.compile_expr_ctx(&fc.args[1], ctx)?;

        let floor = static_min_payload_bytes(&fc.args[1]);
        if floor >= Self::NOTIFY_PAYLOAD_MAX_BYTES {
            return Err(self.type_err(&format!(
                "notify_raw(): this payload is at least {floor} bytes, which is at or over PostgreSQL's {}-byte \
                 NOTIFY payload limit",
                Self::NOTIFY_PAYLOAD_MAX_BYTES
            )));
        }

        Ok(IrExpr::FunctionCall(super::IrFunctionCall {
            return_pg_type: None,
            schema: None,
            name: "pg_notify".to_string(),
            args: vec![channel_ir, payload_ir],
            sql_template: None,
        }))
    }

    /// The `GLOBALS_ARG` value to pass when calling `qualified`, or `None` if
    /// that function does not take one.
    ///
    /// Inside a function body the caller's own argument is forwarded verbatim;
    /// at the top level every session global is packed, rather than just the
    /// ones the callee happens to read. Packing the whole set costs one small
    /// jsonb per call and keeps the caller from having to know anything about
    /// the callee's body.
    fn globals_arg_for_call(&mut self, qualified: &str) -> Result<Option<IrExpr>, PyQLError> {
        if self.fns_needing_globals.is_none() {
            self.fns_needing_globals = Some(functions_needing_globals(self.schema).clone());
        }
        if !self.fns_needing_globals.as_ref().is_some_and(|s| s.contains(qualified)) {
            return Ok(None);
        }
        if self.in_fn_body {
            self.used_globals_arg = true;
            return Ok(Some(IrExpr::RawSql(GLOBALS_ARG.to_string())));
        }
        let session_globals: Vec<String> = self
            .schema
            .globals
            .iter()
            .filter(|g| g.computed_expr.is_none())
            .map(|g| format!("{}::{}", g.module, g.name))
            .collect();
        let mut args = Vec::with_capacity(session_globals.len() * 2);
        for name in session_globals {
            let value = self.compile_global(&name)?;
            args.push(IrExpr::Literal(IrLiteral::Str(name)));
            args.push(value);
        }
        Ok(Some(IrExpr::FunctionCall(super::IrFunctionCall {
            return_pg_type: None,
            schema: None,
            name: "jsonb_build_object".to_string(),
            args,
            sql_template: None,
        })))
    }

    // ── User-defined function helpers ─────────────────────────────────────────────

    /// Try to compile `fn(args) { shape }` as a `FunctionSelect` for an object-returning
    /// user function.  Returns `None` if no matching user function exists (so the caller
    /// can fall through to other dispatch paths).
    fn try_compile_fn_object_select(
        &mut self,
        fc: &ast::FunctionCall,
        elements: &[ast::ShapeElement],
        s: &ast::SelectStmt,
        distinct: bool,
    ) -> Result<Option<IrFunctionSelect>, PyQLError> {
        use crate::schema::FunctionDescriptor;

        let fd: Option<&FunctionDescriptor> = self.schema.functions.iter().find(|f| {
            let module_matches = fc.module.as_deref().map(|m| m == f.module.as_str()).unwrap_or(true);
            module_matches && f.name == fc.name && f.return_is_object
        });
        let fd = match fd {
            Some(f) => f,
            None => return Ok(None),
        };
        if fd.params.len() != fc.args.len() {
            return Err(self.type_err(&format!(
                "function '{}::{}' expects {} argument(s), got {}",
                fd.module,
                fd.name,
                fd.params.len(),
                fc.args.len()
            )));
        }

        let fn_module = fd.module.clone();
        let fn_name = fd.name.clone();
        let return_type_name = fd.return_pg_type.clone(); // qualified type name for object returns
        let polymorphic = fd.return_is_polymorphic;

        let mut fn_args = fc
            .args
            .iter()
            .map(|a| self.compile_free_expr(a))
            .collect::<Result<Vec<_>, _>>()?;
        let qualified = format!("{}::{}", fn_module, fn_name);
        if let Some(globals) = self.globals_arg_for_call(&qualified)? {
            fn_args.insert(0, globals);
        }

        let alias = self.fresh_alias();

        // Resolve the return type to build the shape.
        let td = self.resolve_type(&return_type_name)?;
        let td = td.clone();

        let (poly_implementors, poly_columns) = if polymorphic {
            self.collect_poly_info(&return_type_name)
        } else {
            (vec![], vec![])
        };

        let td_module = td.module.clone();
        // Build shape against the return type (treat alias as the source alias).
        let shape = self.compile_shape(elements, &td, &alias, &td_module)?;
        // The shape's own computeds are in scope for the select's clauses,
        // the same as over a type -- added only now, so one pointer still
        // cannot read another.
        let outer_declared = self.active_declared_pointers.clone();
        self.active_declared_pointers
            .extend(elements.iter().filter(|el| el.compexpr.is_some()).cloned());
        let modifiers = self.compile_path_modifiers(s, &td, &alias);
        self.active_declared_pointers = outer_declared;
        let (filter, order_by, offset, limit) = modifiers?;

        Ok(Some(IrFunctionSelect {
            fn_module,
            fn_name,
            fn_args,
            alias,
            type_name: return_type_name,
            polymorphic,
            poly_implementors,
            poly_columns,
            shape,
            filter,
            order_by,
            offset,
            limit,
            distinct,
        }))
    }

    /// The interface's own physical columns (properties + `{link}_id`) — the
    /// subset every concrete implementor table is guaranteed to share, safe
    /// to RETURNING/SELECT uniformly across a poly_implementors fan-out.
    /// Shared by compile_select (read path) and the IrUpdate/IrDelete
    /// builders (write path) so a DML-as-CTE fan-out (sql/mod.rs) can expose
    /// the same columns a polymorphic select would.
    /// Point a shape's single-link sub-selects at the nested-DML CTE that
    /// supplied their foreign key.
    ///
    /// `insert Account { credentials := (insert Credentials { … }) } { ** }`
    /// runs the nested insert as a data-modifying CTE, and Postgres does not
    /// show one statement's CTE writes to the rest of that statement: reading
    /// `access."Credentials"` back finds nothing, so the link hydrated as
    /// `None` even though the row was there on the next statement (confirmed
    /// live). The CTE itself is in scope, and `RETURNING *` gives it every
    /// column the shape asks for, so the sub-select reads that instead.
    fn read_nested_links_from_their_ctes(dml: &IrStmt, dml_cte: Option<&str>, shape: &mut [IrShapePointer]) {
        let (assignments, nested_ctes, appends) = match dml {
            IrStmt::Insert(ins) => (&ins.assignments, &ins.nested_ctes, &ins.multi_link_appends),
            IrStmt::Update(upd) => (&upd.assignments, &upd.nested_ctes, &upd.multi_link_appends),
            _ => return,
        };
        // A multi-link's junction rows are written by this statement too, in
        // a CTE the emitter names after the DML's own — see
        // `emit_insert_multilink_ctes`. The targets themselves come from the
        // append's value source, which for a nested insert is one of
        // `nested_ctes`.
        if let Some(dml_cte) = dml_cte {
            for pointer in shape.iter_mut() {
                let IrShapePointer::MultiLink(link) = pointer else {
                    continue;
                };
                let IrMultiLinkJoin::Standard { junction_table, .. } = &mut link.join else {
                    continue;
                };
                let Some(index) = appends.iter().position(|a| a.junction_table == *junction_table) else {
                    continue;
                };
                *junction_table = format!("@cte:{dml_cte}__ml_add_{index}");
                if let IrMultiLinkValueSource::CteRef(target_cte) = &appends[index].values.source {
                    for row in &mut link.subquery.rows {
                        if let IrRowSource::Bound { source, .. } = row {
                            source.table = format!("@cte:{target_cte}");
                            source.poly = None;
                        }
                    }
                }
            }
        }
        if nested_ctes.is_empty() {
            return;
        }
        let from_cte: HashMap<&str, &str> = assignments
            .iter()
            .filter_map(|(column, expr)| match expr {
                IrExpr::ColumnRef { alias, column: c, .. }
                    if c == "id" && nested_ctes.iter().any(|cte| cte.name == *alias) =>
                {
                    Some((column.as_str(), alias.as_str()))
                }
                _ => None,
            })
            .collect();
        if from_cte.is_empty() {
            return;
        }
        for pointer in shape {
            let IrShapePointer::SingleLink(link) = pointer else {
                continue;
            };
            let IrSingleLinkCorrelation::Fk { fk_column, .. } = &link.correlation else {
                continue;
            };
            let Some(cte_name) = from_cte.get(fk_column.as_str()) else {
                continue;
            };
            for row in &mut link.subquery.rows {
                if let IrRowSource::Bound { source, .. } = row {
                    source.table = format!("@cte:{cte_name}");
                    source.poly = None;
                }
            }
        }
    }

    fn poly_dml_columns(td: &TypeDescriptor) -> Vec<String> {
        td.properties
            .iter()
            .map(|p| p.name.clone())
            .chain(
                td.links
                    .iter()
                    .filter(|l| !l.is_junction_backed())
                    .map(|l| format!("{}_id", l.name)),
            )
            .collect()
    }

    /// A nested SELECT over a link's target, expanded inline over the
    /// interface's implementors when the target is one.
    ///
    /// An interface is materialised as a view that carries only the
    /// interface's own columns -- no discriminator -- so reading a link
    /// through it tags every row as the interface itself and hydrates the
    /// interface class rather than the concrete one. Expanding the
    /// implementors inline is what the root of a query already does, and each
    /// branch supplies its own `__type__`.
    fn link_target_select(
        &self,
        target_td: &TypeDescriptor,
        mut source: IrSource,
        shape: Vec<IrShapePointer>,
    ) -> IrSelect {
        source.poly = self.link_target_fanout(target_td);
        IrSelect::schema_bound(source, shape, None)
    }

    /// The fan-out a link's target needs, for the builders that assemble their
    /// own source rather than going through `link_target_select`.
    fn link_target_fanout(&self, target_td: &TypeDescriptor) -> Option<IrPolyFanout> {
        self.poly_fanout_for(&format!("{}::{}", target_td.module, target_td.name))
    }

    /// Give every interface-typed join target its fan-out, so a traversal that
    /// lands on one reads the implementors and carries the real type rather
    /// than the interface's view, which has no discriminator to carry.
    ///
    /// The root is left alone: a path select fans its own root out through
    /// `poly_implementors` already, and doing it twice would nest the union.
    fn resolve_join_fanouts(&self, path_select: &mut IrPathSelect) {
        for join in &mut path_select.joins {
            let target = match join {
                IrPathJoin::Single { target, .. }
                | IrPathJoin::Multi { target, .. }
                | IrPathJoin::BacklinkSingle { target, .. }
                | IrPathJoin::BacklinkMulti { target, .. }
                | IrPathJoin::Function { target, .. }
                | IrPathJoin::Lateral { target, .. } => target,
            };
            if target.poly.is_none() && !target.table.starts_with("@cte:") {
                target.poly = self.poly_fanout_for(&target.type_name.clone());
            }
        }
    }

    /// The fan-out a source of `type_name` needs, or `None` when it is not an
    /// interface and so reads from a table of its own. See `IrSource::poly`.
    fn poly_fanout_for(&self, type_name: &str) -> Option<IrPolyFanout> {
        let td = self
            .schema
            .types
            .iter()
            .find(|t| format!("{}::{}", t.module, t.name) == type_name)?;
        // A materialised interface has a view to read; a plain abstract has no
        // relation at all, so reading its table name finds nothing. Both are
        // answered by the union of the types that carry the columns.
        if !td.abstract_ && !self.has_subtypes(td) {
            return None;
        }
        let (implementors, columns) = self.collect_poly_info(type_name);
        Some(IrPolyFanout { implementors, columns })
    }

    /// Collect poly_implementors and poly_columns for a polymorphic return type.
    fn collect_poly_info(&self, type_name: &str) -> (Vec<IrPolyImplementor>, Vec<String>) {
        let implementors = self.find_poly_implementors(type_name);
        let columns = if let Some(td) = self
            .schema
            .types
            .iter()
            .find(|t| format!("{}::{}", t.module, t.name) == type_name)
        {
            // The same set the DML path fans out (`poly_dml_columns`): the
            // interface's single-link FKs belong in it too, or reading
            // `.profile` off an interface-typed source finds no
            // `profile_id` column in the union it was fanned out into.
            Self::poly_dml_columns(td)
        } else {
            vec![]
        };
        (implementors, columns)
    }

    // ── vector::search ────────────────────────────────────────────────────────────

    /// Try to compile `vector::search` from a function-call AST node.
    ///
    /// Two overloads are supported:
    /// - `vector::search(TypeName, $vec [, index_name := '…'])` — pre-computed vector
    /// - `vector::search(TypeName, query := $text [, index_name := '…'])` — text overload;
    ///   the Python layer embeds the text and injects `__deferred_vec__` before execution.
    ///
    /// Returns `None` if the call is not `vector::search`.
    fn try_compile_vector_search(
        &mut self,
        fc: &ast::FunctionCall,
        elements: &[ast::ShapeElement],
        s: &ast::SelectStmt,
    ) -> Result<Option<IrVectorSearch>, PyQLError> {
        if fc.module.as_deref() != Some("vector") || fc.name != "search" {
            return Ok(None);
        }

        // Detect text overload: `query :=` kwarg present (no positional second arg needed).
        let text_query_arg = fc.kwargs.iter().find(|(k, _)| k == "query").map(|(_, v)| v);
        let is_text_overload = text_query_arg.is_some();

        if !is_text_overload && fc.args.len() < 2 {
            return Err(
                self.type_err("vector::search requires either a positional vector argument or `query := $text`")
            );
        }

        // First argument: a type name or a filtered subquery narrowing the candidate set.
        //   - Bare name:     `Product` or `default::Product`
        //   - Subquery:      `(select Product filter .price < 100)`
        //
        // For the subquery form we store the raw inner filter AST and compile it below,
        // after the source alias is generated, so property column refs use the right alias.
        let (type_qname, inner_filter_ast): (String, Option<ast::Expr>) = match &fc.args[0] {
            ast::Expr::Path(p) if !p.partial => {
                let name = p.steps.iter()
                    .filter_map(|s| if let ast::PathStep::Name(n) = s { Some(n.as_str()) } else { None })
                    .collect::<Vec<_>>().join("::");
                let td = self.resolve_type(&name)
                    .map_err(|_| self.type_err(&format!("vector::search: '{}' is not a known type", name)))?;
                (format!("{}::{}", td.module, td.name), None)
            }
            ast::Expr::SubQuery(stmt) => {
                if let ast::Stmt::Select(inner_sel) = stmt.as_ref() {
                    let inner_type_name = match &inner_sel.result {
                        ast::Expr::Path(p) if !p.partial => {
                            p.steps.iter()
                                .filter_map(|s| if let ast::PathStep::Name(n) = s { Some(n.as_str()) } else { None })
                                .collect::<Vec<_>>().join("::")
                        }
                        _ => return Err(self.type_err(
                            "vector::search: subquery first argument must select a single type (e.g. select Product filter …)"
                        )),
                    };
                    let td = self.resolve_type(&inner_type_name)
                        .map_err(|_| self.type_err(&format!("vector::search: '{}' is not a known type", inner_type_name)))?;
                    let qname = format!("{}::{}", td.module, td.name);
                    (qname, inner_sel.filter.clone())
                } else {
                    return Err(self.type_err("vector::search: subquery first argument must be a SELECT"));
                }
            }
            _ => return Err(self.type_err(
                "vector::search: first argument must be a type name or a filtered subquery (e.g. select Product filter …)"
            )),
        };

        // Optional named argument: index_name := '…'
        let index_name: Option<String> = fc.kwargs.iter().find(|(k, _)| k == "index_name").and_then(|(_, v)| {
            if let ast::Expr::Literal(ast::Literal::Str(s)) = v {
                Some(s.clone())
            } else {
                None
            }
        });

        // Resolve the type and find the VectorIndex.
        let td = self.resolve_type(&type_qname)?.clone();
        let vi = td
            .vector_indexes
            .iter()
            .find(|vi| vi.index_name.as_deref() == index_name.as_deref())
            .ok_or_else(|| {
                let key = index_name.as_deref().unwrap_or("<default>");
                self.type_err(&format!("type '{}' has no vector index '{}'", type_qname, key))
            })?;

        let vector_col = vi.column_name();
        let distance_op = match vi.metric.as_str() {
            "euclidean" => "<->",
            "inner_product" => "<#>",
            _ => "<=>", // cosine (default)
        };

        // Build query expression and inference fields.
        let (
            query_expr,
            inference_query_param_name,
            inference_query_literal,
            inference_model,
            inference_type_name,
            inference_index_name,
        );

        if is_text_overload {
            // Text overload: register __deferred_vec__ as the SQL param; Python injects
            // the embedding result into it before executing the query.
            let vec_idx = self.param_index("__deferred_vec__");
            let vec_param = IrExpr::Param { index: vec_idx };
            // Cast float8[] → vector so a Python list[float] encodes natively.
            let inner_cast = IrExpr::TypeCast(Box::new(IrTypeCast {
                expr: vec_param,
                pg_type: "float8[]".to_string(),
                tuple_shape: None,
            }));
            query_expr = IrExpr::TypeCast(Box::new(IrTypeCast {
                expr: inner_cast,
                pg_type: "vector".to_string(),
                tuple_shape: None,
            }));
            let query_arg = text_query_arg.unwrap();
            inference_query_param_name = Some(match query_arg {
                ast::Expr::Parameter(name) => name.clone(),
                _ => String::new(),
            });
            inference_query_literal = match query_arg {
                ast::Expr::Literal(ast::Literal::Str(s)) => Some(s.clone()),
                _ => None,
            };
            inference_model = Some(vi.model.clone());
            inference_type_name = Some(type_qname.clone());
            inference_index_name = Some(index_name.clone());
        } else {
            // Vector overload: second positional arg is the pre-computed vector.
            let raw_query_expr = self.compile_free_expr(&fc.args[1])?;
            query_expr = IrExpr::TypeCast(Box::new(IrTypeCast {
                expr: raw_query_expr,
                pg_type: "vector".to_string(),
                tuple_shape: None,
            }));
            inference_query_param_name = None;
            inference_query_literal = None;
            inference_model = None;
            inference_type_name = None;
            inference_index_name = None;
        }

        let alias = self.fresh_alias();
        let source = IrSource {
            poly: None,
            type_name: type_qname.clone(),
            table: td.table.clone(),
            alias: alias.clone(),
        };

        // Compile inner_filter_ast (from subquery first arg) now that we have the alias,
        // so property column refs (e.g. `.price`) use the correct table alias.
        let pre_filter: Option<IrExpr> = match inner_filter_ast {
            Some(ref f) => Some(self.as_condition(|c| c.compile_expr(f, &td, &alias))?),
            None => None,
        };

        // Compile the object shape from `object { … }` inside the shape elements.
        // `elements` is the outer shape (`{ object { … }, distance }`).
        // We find the `object` element and take its sub-shape; everything else is ignored
        // at compile time (distance is always emitted; unknown pointers are an error).
        let mut object_shape: Vec<IrShapePointer> = vec![];
        for el in elements {
            if el.splat.is_some() {
                continue;
            } // ignore splat in outer shape
            let pointer_name = match el.path.steps.first() {
                Some(ast::PathStep::Name(n)) => n.as_str(),
                _ => continue,
            };
            match pointer_name {
                "distance" => { /* always emitted; no sub-shape */ }
                "object" => {
                    let sub_els = el.nested.as_deref().unwrap_or(&[]);
                    object_shape = self.compile_shape(sub_els, &td, &alias, &td.module)?;
                }
                other => {
                    return Err(self.type_err(&format!(
                        "vector::search result has no pointer '{}'; valid pointers are 'object' and 'distance'",
                        other
                    )));
                }
            }
        }

        let (outer_filter, order_by_distance, offset, limit) = self.compile_vs_modifiers(s)?;

        // Merge pre_filter (from subquery first arg) with any outer filter via AND.
        let filter = match (pre_filter, outer_filter) {
            (Some(a), Some(b)) => Some(IrExpr::BinOp(Box::new(IrBinOp {
                left: a,
                op: ast::BinOpKind::And,
                right: b,
            }))),
            (Some(f), None) | (None, Some(f)) => Some(f),
            (None, None) => None,
        };

        Ok(Some(IrVectorSearch {
            source,
            vector_col,
            distance_op,
            query_expr,
            object_shape,
            filter,
            order_by_distance,
            offset,
            limit,
            inference_query_param_name,
            inference_query_literal,
            inference_model,
            inference_type_name,
            inference_index_name,
        }))
    }

    /// Compile `order by`, `filter`, `offset`, `limit` for a VectorSearch source.
    /// Recognises `.distance` (relative path) as the distance expression.
    fn compile_vs_modifiers(&mut self, s: &ast::SelectStmt) -> Result<SearchModifiers, PyQLError> {
        let mut order_by_distance: Option<IrSortDir> = None;
        for sort in &s.order_by {
            let is_distance = matches!(&sort.expr,
                ast::Expr::Path(p) if p.partial && p.steps.len() == 1
                    && matches!(&p.steps[0], ast::PathStep::Name(n) if n == "distance")
            );
            if is_distance {
                let dir = match sort.direction {
                    ast::SortDirection::Desc => IrSortDir::Desc,
                    ast::SortDirection::Asc => IrSortDir::Asc,
                };
                order_by_distance = Some(dir);
            } else {
                return Err(self.type_err("vector::search: only 'order by .distance' is supported as a sort key"));
            }
        }

        let filter = match &s.filter {
            Some(f) => Some(self.compile_free_expr(f)?),
            None => None,
        };
        let offset = match &s.offset {
            Some(o) => Some(self.compile_free_expr(o)?),
            None => None,
        };
        let limit = match &s.limit {
            Some(l) => Some(self.compile_free_expr(l)?),
            None => None,
        };

        Ok((filter, order_by_distance, offset, limit))
    }

    // ── fts::search ──────────────────────────────────────────────────────────────

    /// Try to compile `fts::search(TypeName, $query [, index_name := '…'] [, mode := '…'])`.
    /// Returns `None` if the call is not `fts::search`.
    fn try_compile_fts_search(
        &mut self,
        fc: &ast::FunctionCall,
        elements: &[ast::ShapeElement],
        s: &ast::SelectStmt,
    ) -> Result<Option<IrFtsSearch>, PyQLError> {
        if fc.module.as_deref() != Some("fts") || fc.name != "search" {
            return Ok(None);
        }
        if fc.args.len() < 2 {
            return Err(self.type_err("fts::search requires at least 2 arguments: (TypeName, $query)"));
        }

        // First argument: a bare type name reference.
        let type_qname = match &fc.args[0] {
            ast::Expr::Path(p) if !p.partial && p.steps.len() == 1 => {
                if let ast::PathStep::Name(n) = &p.steps[0] {
                    let td = self
                        .resolve_type(n)
                        .map_err(|_| self.type_err(&format!("fts::search: '{}' is not a known type", n)))?;
                    format!("{}::{}", td.module, td.name)
                } else {
                    return Err(self.type_err("fts::search: first argument must be a type name"));
                }
            }
            _ => return Err(self.type_err("fts::search: first argument must be a bare type name")),
        };

        // Optional named arguments.
        let index_name: Option<String> = fc.kwargs.iter().find(|(k, _)| k == "index_name").and_then(|(_, v)| {
            if let ast::Expr::Literal(ast::Literal::Str(s)) = v {
                Some(s.clone())
            } else {
                None
            }
        });

        let mode_str = fc
            .kwargs
            .iter()
            .find(|(k, _)| k == "mode")
            .and_then(|(_, v)| {
                if let ast::Expr::Literal(ast::Literal::Str(s)) = v {
                    Some(s.as_str())
                } else {
                    None
                }
            })
            .unwrap_or("BestFields");

        let tsquery_fn: &'static str = match mode_str {
            "Phrase" => "phraseto_tsquery",
            _ => "websearch_to_tsquery", // BestFields and PhrasePrefix both use websearch
        };

        // Resolve the type and find the SearchIndex.
        let td = self.resolve_type(&type_qname)?.clone();
        let si = td
            .search_indexes
            .iter()
            .find(|si| si.index_name.as_deref() == index_name.as_deref())
            .ok_or_else(|| {
                let key = index_name.as_deref().unwrap_or("<default>");
                self.type_err(&format!("type '{}' has no search index '{}'", type_qname, key))
            })?;

        let backend = si.backend.clone();
        let search_col = si.column_name();
        let is_deferred = backend != SearchBackend::Postgres;
        let deferred_index_name = if is_deferred {
            Some(si.deferred_index_name(&td.module, &td.name))
        } else {
            None
        };

        // Second argument: the query text expression.
        // For deferred backends, IDs/scores are the only SQL params ($1/$2). The query
        // text is consumed by the Python layer before SQL execution, so we extract its
        // name/literal directly from the AST without registering a SQL param for it.
        let query_expr;
        let deferred_query_param_name;
        let deferred_query_literal;
        let deferred_ids_param;
        let deferred_scores_param;

        if is_deferred {
            let ids_idx = self.param_index("__deferred_ids__");
            let scores_idx = self.param_index("__deferred_scores__");
            deferred_ids_param = Some(ids_idx);
            deferred_scores_param = Some(scores_idx);
            deferred_query_param_name = match &fc.args[1] {
                ast::Expr::Parameter(name) => Some(name.clone()),
                _ => None,
            };
            deferred_query_literal = match &fc.args[1] {
                ast::Expr::Literal(ast::Literal::Str(s)) => Some(s.clone()),
                _ => None,
            };
            // Placeholder — not used in SQL for the deferred backend.
            query_expr = IrExpr::Literal(crate::ir::IrLiteral::Str(String::new()));
        } else {
            query_expr = self.compile_free_expr(&fc.args[1])?;
            deferred_query_param_name = None;
            deferred_query_literal = None;
            deferred_ids_param = None;
            deferred_scores_param = None;
        }

        let alias = self.fresh_alias();
        let source = IrSource {
            poly: None,
            type_name: type_qname.clone(),
            table: td.table.clone(),
            alias: alias.clone(),
        };

        // Compile the object shape from `object { … }` in the outer shape.
        let mut object_shape: Vec<IrShapePointer> = vec![];
        for el in elements {
            if el.splat.is_some() {
                continue;
            }
            let pointer_name = match el.path.steps.first() {
                Some(ast::PathStep::Name(n)) => n.as_str(),
                _ => continue,
            };
            match pointer_name {
                "score" => { /* always emitted */ }
                "object" => {
                    let sub_els = el.nested.as_deref().unwrap_or(&[]);
                    object_shape = self.compile_shape(sub_els, &td, &alias, &td.module)?;
                }
                other => {
                    return Err(self.type_err(&format!(
                        "fts::search result has no pointer '{}'; valid pointers are 'object' and 'score'",
                        other
                    )));
                }
            }
        }

        let (filter, order_by_rank, offset, limit) = self.compile_fts_modifiers(s)?;

        Ok(Some(IrFtsSearch {
            source,
            backend,
            search_col,
            tsquery_fn,
            query_expr,
            object_shape,
            filter,
            order_by_rank,
            offset,
            limit,
            deferred_index_name,
            deferred_query_param_name,
            deferred_query_literal,
            deferred_ids_param,
            deferred_scores_param,
        }))
    }

    /// Compile `order by`, `filter`, `offset`, `limit` for a FtsSearch source.
    /// Recognises `.score` (relative path) as the score expression.
    fn compile_fts_modifiers(&mut self, s: &ast::SelectStmt) -> Result<SearchModifiers, PyQLError> {
        let mut order_by_rank: Option<IrSortDir> = None;
        for sort in &s.order_by {
            let is_rank = matches!(&sort.expr,
                ast::Expr::Path(p) if p.partial && p.steps.len() == 1
                    && matches!(&p.steps[0], ast::PathStep::Name(n) if n == "score")
            );
            if is_rank {
                let dir = match sort.direction {
                    ast::SortDirection::Desc => IrSortDir::Desc,
                    ast::SortDirection::Asc => IrSortDir::Asc,
                };
                order_by_rank = Some(dir);
            } else {
                return Err(self.type_err("fts::search: only 'order by .score' is supported as a sort key"));
            }
        }

        let filter = match &s.filter {
            Some(f) => Some(self.compile_free_expr(f)?),
            None => None,
        };
        let offset = match &s.offset {
            Some(o) => Some(self.compile_free_expr(o)?),
            None => None,
        };
        let limit = match &s.limit {
            Some(l) => Some(self.compile_free_expr(l)?),
            None => None,
        };

        Ok((filter, order_by_rank, offset, limit))
    }

    // ── Error helpers ─────────────────────────────────────────────────────────────

    fn type_err(&self, msg: &str) -> PyQLError {
        PyQLError::Type(PyQLTypeError {
            message: msg.to_string(),
            position: Position { line: 0, col: 0 },
        })
    }

    fn field_err(&self, field: &str, type_name: &str) -> PyQLError {
        if std::env::var("PYLON_DBG_FIELD_ERR").is_ok() {
            eprintln!(
                "DBG field_err {field} on {type_name}
{}",
                std::backtrace::Backtrace::force_capture()
            );
        }
        let suggestion = self
            .schema
            .types
            .iter()
            .find(|t| format!("{}::{}", t.module, t.name) == type_name)
            .and_then(|td| Self::suggest_pointer_name(td, field));
        let message = match suggestion {
            Some(s) => format!("object type '{type_name}' has no link or property '{field}'. Did you mean '{s}'?"),
            None => format!("object type '{type_name}' has no link or property '{field}'"),
        };
        PyQLError::Resolution(PyQLResolutionError::UnknownField(PyQLUnknownFieldError {
            message,
            position: Position { line: 0, col: 0 },
        }))
    }

    /// A ` — did you mean …?` fragment for an unresolvable function name, or
    /// an empty string.
    ///
    /// Mirrors `pylon.stdlib.unknown_function_message`, which has always
    /// offered this for the `std.foo(...)` attribute form; a name written as
    /// PyQL text got nothing, which is how a schema converted from a system
    /// that spelled it `uuid_generate_v7j` stayed broken instead of being
    /// pointed one character back at `uuid_generate_v7`.
    ///
    /// The wrong-namespace check comes first and is worth its own wording:
    /// the namespaces overlap unevenly — `sqrt`/`abs`/`ceil` are in both
    /// `std` and `math`, while `pi`/`ln`/`exp` are only in `math` — so
    /// guessing the wrong one is routine, and naming where the function
    /// actually lives recovers from it in a way a fuzzy match over the
    /// namespace that lacks it cannot.
    fn suggest_function_name(&self, ns: &str, name: &str) -> String {
        const MIN_SIMILARITY: f64 = 0.7;
        if let Some(other) = ["std", "math", "cal", "sys"]
            .into_iter()
            .find(|o| *o != ns && !crate::stdlib::lookup(o, name).is_empty())
        {
            return format!(" — it lives in {other}, use {other}::{name}()");
        }
        crate::stdlib::registry()
            .iter()
            .filter(|d| d.namespace == ns)
            .map(|d| (format!("{ns}::{}", d.name), d.name))
            .chain(
                self.schema
                    .functions
                    .iter()
                    .map(|f| (format!("{}::{}", f.module, f.name), f.name.as_str())),
            )
            .map(|(qualified, candidate)| (qualified, strsim::jaro_winkler(name, candidate)))
            .filter(|(_, score)| *score >= MIN_SIMILARITY)
            .max_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
            .map(|(qualified, _)| format!(" — did you mean {qualified}()?"))
            .unwrap_or_default()
    }

    /// Fuzzy-matches `name` against every pointer (property/link/multilink/
    /// computed — Pylon's term for a type's own attributes; "field" is a
    /// Postgres-level term that doesn't apply here) on `td`, returning the
    /// closest candidate when it's plausibly a typo — powers a
    /// "Did you mean X?" suggestion for an unknown property/link.
    /// Jaro-Winkler (favors a shared prefix, which is where most real typos
    /// preserve the most characters, e.g. `nam` -> `name`) with a
    /// conservative similarity floor, so an unrelated pointer never gets
    /// suggested just because it happens to be the "closest" among an
    /// otherwise-dissimilar set of candidates.
    fn suggest_pointer_name(td: &TypeDescriptor, name: &str) -> Option<String> {
        const MIN_SIMILARITY: f64 = 0.7;
        td.properties
            .iter()
            .map(|p| p.name.as_str())
            .chain(td.links.iter().map(|l| l.name.as_str()))
            .chain(td.multilinks.iter().map(|m| m.name.as_str()))
            .chain(td.computed.iter().map(|c| c.name.as_str()))
            .map(|candidate| (candidate, strsim::jaro_winkler(name, candidate)))
            .filter(|(_, score)| *score >= MIN_SIMILARITY)
            .max_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
            .map(|(name, _)| name.to_string())
    }

    // ── Default returning (pk only) ────────────────────────────────────────────

    /// For bare DML (not wrapped in SELECT) return only primary-key properties:
    /// `INSERT … ` returns `{ id }`, same for UPDATE/DELETE.
    fn pk_returning(td: &TypeDescriptor) -> Vec<IrShapePointer> {
        td.properties
            .iter()
            .filter(|p| p.is_pk)
            .map(|p| {
                IrShapePointer::Scalar(IrScalarPointer {
                    implicit_id: false,
                    marker_offset: None,
                    alias: p.name.clone(),
                    column: p.name.clone(),
                    pg_type: p.pg_type.clone(),
                    tuple_shape: None,
                })
            })
            .collect()
    }
}

// ── Helpers ─────────────────────────────────────────────────────────────────────

/// True for `<json>` / `<std::json>` — the one cast target that turns its
/// operand into output text rather than another value.
fn casts_to_json(ty: &ast::TypeExpr) -> bool {
    matches!(ty.as_named(), Some((module, "json")) if module.is_none_or(|m| m == "std"))
}

/// True if any node in a multilink value tree (including both sides of any
/// nested `union`) carries a `@prop := value` link-property assignment.
fn has_any_link_props(vals: &IrMultiLinkValues) -> bool {
    if !vals.link_props.is_empty() {
        return true;
    }
    match &vals.source {
        IrMultiLinkValueSource::Union(a, b) => has_any_link_props(a) || has_any_link_props(b),
        _ => false,
    }
}

/// True for a bare `{}` or a `<AnyType>{}` cast of one — the empty-set
/// literal a caller uses to clear an optional pointer, in either form. A
/// frontend generating PyQL typically emits the cast form (e.g.
/// `<Company>{}`, matching `compile_expr`'s own `Expr::TypeCast` handling of
/// this exact case), while hand-written PyQL more often uses the bare form.
fn is_empty_set_expr(expr: &Expr) -> bool {
    match expr {
        Expr::Set(elems) => elems.is_empty(),
        Expr::TypeCast(tc) => matches!(&tc.expr, Expr::Set(elems) if elems.is_empty()),
        _ => false,
    }
}

/// Extract the single pointer name from a relative path used in a shape element.
fn path_leaf(p: &ast::Path) -> Result<&str, PyQLError> {
    match p.steps.as_slice() {
        [ast::PathStep::Name(n)] => Ok(n.as_str()),
        _ => Err(PyQLError::Type(PyQLTypeError {
            message: "expected a simple pointer name in shape element".into(),
            position: Position { line: 0, col: 0 },
        })),
    }
}

/// Map a PyQL type expression to a PostgreSQL type string.
fn type_expr_to_pg(ty: &ast::TypeExpr) -> Result<String, PyQLError> {
    let Some((module, bare_name)) = ty.as_named() else {
        // Callers resolve a structural tuple/array directly before ever
        // reaching this function (see `resolve_cast_pg_type`) — reaching here
        // with one would be an internal bug, not a user-facing scenario.
        return Err(PyQLError::Type(PyQLTypeError {
            message: "internal error: structural tuple/array type reached type_expr_to_pg".into(),
            position: Position { line: 0, col: 0 },
        }));
    };

    // pgvector:: types map directly to PostgreSQL types.
    if module == Some("pgvector") {
        return match bare_name {
            "vector" => Ok("vector".to_string()),
            other => Err(PyQLError::Type(PyQLTypeError {
                message: format!("unknown pgvector type '{other}'; valid types are: vector"),
                position: Position { line: 0, col: 0 },
            })),
        };
    }

    // postgis:: types map directly to PostgreSQL types.
    if module == Some("postgis") {
        return match bare_name {
            "geometry" => Ok("geometry".to_string()),
            "geography" => Ok("geography".to_string()),
            "box2d" => Ok("box2d".to_string()),
            "box3d" => Ok("box3d".to_string()),
            other => Err(PyQLError::Type(PyQLTypeError {
                message: format!("unknown postgis type '{other}'; valid types are: geometry, geography, box2d, box3d"),
                position: Position { line: 0, col: 0 },
            })),
        };
    }

    // cal:: types map directly to PostgreSQL types.
    if module == Some("cal") {
        let pg = match bare_name {
            "local_datetime" => "timestamp",
            "local_date" => "date",
            "local_time" => "time",
            "relative_duration" | "date_duration" => "interval",
            other => {
                return Err(PyQLError::Type(PyQLTypeError {
                    message: format!(
                        "unknown cal type '{other}'; \
                     valid types are: local_datetime, local_date, local_time, \
                     relative_duration, date_duration"
                    ),
                    position: Position { line: 0, col: 0 },
                }));
            }
        };
        return Ok(pg.to_string());
    }

    let name = match module {
        Some("std") | None => bare_name,
        Some(m) => {
            return Err(PyQLError::Type(PyQLTypeError {
                message: format!("unknown type '{}::{}'", m, bare_name),
                position: Position { line: 0, col: 0 },
            }));
        }
    };
    Ok(match name {
        "str" => "text",
        "int16" => "int2",
        "int32" => "int4",
        "int64" => "int8",
        "float32" => "float4",
        "float64" => "float8",
        "bool" => "boolean",
        "uuid" => "uuid",
        "bytes" => "bytea",
        "json" => "jsonb",
        "decimal" => "numeric",
        // bigint and decimal are both PostgreSQL `numeric` — the distinction
        // is a Pylon-level scale/precision convention, not a separate PG type.
        "bigint" => "numeric",
        "datetime" => "timestamptz",
        "date" => "date",
        "time" => "time",
        "duration" => "interval",
        other => {
            return Err(PyQLError::Type(PyQLTypeError {
                message: format!("unknown type '{other}'"),
                position: Position { line: 0, col: 0 },
            }));
        }
    }
    .to_string())
}

/// Check whether a compiled expression is compatible with a PylonType parameter.
/// Used for overload selection when multiple overloads share the same name.
/// Emit `($1 IS NOT NULL)` for a given IR expression.
fn ir_is_not_null(expr: IrExpr) -> IrExpr {
    IrExpr::FunctionCall(IrFunctionCall {
        return_pg_type: None,
        schema: None,
        name: String::new(),
        args: vec![expr],
        sql_template: Some("($1 IS NOT NULL)".to_string()),
    })
}

/// "1 argument(s)" / "2 or 3 argument(s)" / "at least 1 argument(s)" — the
/// arities an overload set accepts, worded as `pylon.stdlib._arity_error`
/// words the same rejection on the Python side.
fn describe_arities(overloads: &[&crate::stdlib::FnDescriptor]) -> String {
    // Positions only: a named-only parameter is not one of the arguments the
    // count is about, so counting it reported `range(…)` as taking four.
    let mut arities: Vec<usize> = overloads
        .iter()
        .map(|d| d.params.iter().filter(|p| p.named_only.is_none()).count())
        .collect();
    arities.sort_unstable();
    arities.dedup();
    if overloads.iter().any(|d| d.is_variadic()) {
        return format!("at least {} argument(s)", arities[0].saturating_sub(1));
    }
    let list = arities.iter().map(usize::to_string).collect::<Vec<_>>().join(" or ");
    format!("{list} argument(s)")
}

/// The argument types as far as they could be inferred, for an error that
/// has to show the caller what it actually passed.
fn describe_args(args: &[IrExpr]) -> String {
    args.iter()
        .map(|a| infer_ir_type(a).map_or("?", literal_sentinel_to_pg))
        .collect::<Vec<_>>()
        .join(", ")
}

/// The parameter lists of the overloads that did match on arity, in PyQL
/// spelling — what the caller should have passed.
fn describe_signatures(overloads: &[&crate::stdlib::FnDescriptor]) -> String {
    overloads
        .iter()
        .map(|d| {
            let params = d
                .params
                .iter()
                .map(|p| match p.named_only {
                    // Spelled the way the call has to pass it, so a rejected
                    // call isn't told to write a named parameter by position.
                    Some(_) => format!("{} := {}", p.keyword(), p.ty.pyql_name()),
                    None => p.ty.pyql_name(),
                })
                .collect::<Vec<_>>()
                .join(", ");
            format!("({params})")
        })
        .collect::<Vec<_>>()
        .join(" or ")
}

/// The value of a boolean literal argument, for the call shapes that can be
/// resolved at compile time rather than left to a runtime `CASE`.
fn bool_literal(expr: &IrExpr) -> Option<bool> {
    match expr {
        IrExpr::Literal(IrLiteral::Bool(b)) => Some(*b),
        _ => None,
    }
}

/// Gather the arguments a variadic parameter absorbed into one array, for the
/// overloads that declare named-only parameters after it.
///
/// PostgreSQL requires `VARIADIC` to be the last parameter, so an overload
/// with anything after it declares a plain array instead (see
/// `ddl::pg_params`) and is handed the elements already gathered. An overload
/// whose variadic really is last keeps passing them one by one, which is what
/// `VARIADIC path text[]` expects.
fn pack_variadic_args(d: &crate::stdlib::FnDescriptor, args: Vec<IrExpr>) -> Vec<IrExpr> {
    let named = d.named_count();
    let Some(variadic_at) = d.variadic_index().filter(|v| v + 1 < d.params.len()) else {
        return args;
    };
    let Some(absorbed) = args.len().checked_sub(variadic_at + named) else {
        return args;
    };
    let mut packed: Vec<IrExpr> = Vec::with_capacity(variadic_at + 1 + named);
    let mut rest = args.into_iter();
    packed.extend(rest.by_ref().take(variadic_at));
    packed.push(IrExpr::Array(rest.by_ref().take(absorbed).collect()));
    packed.extend(rest);
    packed
}

/// The parameter each of `argc` arguments is checked against.
///
/// One per declared parameter, except that a variadic one stands in for every
/// argument past the fixed ones — `json_get(j, 'a', 'b')` checks both path
/// elements against the single variadic `str` parameter rather than leaving
/// the third argument unchecked, which a plain `params.iter()` zipped against
/// the arguments would do.
///
/// The named-only parameters keep their own positions at the tail:
/// `compile_named_call_args` has already appended one argument per named-only
/// parameter, in declaration order, so the arguments a variadic absorbs are
/// only the ones between the fixed parameters and that tail.
fn params_for_args(d: &crate::stdlib::FnDescriptor, argc: usize) -> impl Iterator<Item = &crate::stdlib::Param> {
    let named = d.named_count();
    let variadic_at = d.is_variadic().then(|| d.variadic_index()).flatten();
    let absorbed = variadic_at.map_or(0, |v| argc.saturating_sub(v + named));
    (0..argc).filter_map(move |i| match variadic_at {
        Some(v) if i >= v && i < v + absorbed => d.params.get(v),
        Some(v) if i >= v => d.params.get(i + 1 - absorbed),
        _ => d.params.get(i),
    })
}

fn pylon_type_matches(expr: &IrExpr, ty: &crate::stdlib::PylonType) -> bool {
    use crate::stdlib::PylonType as PT;
    match ty {
        // Wildcard params always match.
        PT::Any | PT::AnyOrderable | PT::AnyPoint => true,
        PT::Array(_) => is_array_expr(expr),
        // Matched on the concrete PostgreSQL type name, which for a
        // multirange is `int8multirange`/`tstzmultirange`/… — it carries the
        // element family as a prefix, so "is a multirange" is a `contains`,
        // not a `starts_with`, and "is a plain range" has to exclude it.
        PT::Range(_) => matches!(infer_ir_type(expr), Some(t) if t.ends_with("range") && !t.contains("multirange")),
        PT::Multirange(_) => matches!(infer_ir_type(expr), Some(t) if t.contains("multirange")),
        // Every parameter type that names a concrete PostgreSQL scalar is
        // judged by `types_compatible` — the one implicit-cast graph the
        // rest of the compiler already resolves operators against — rather
        // than by an exact type-name match. Exactness rejected an integer
        // literal reaching a `float64` parameter, which is how
        // `cal::to_relative_duration(seconds := 3)` and every other
        // int-for-float argument reads.
        //
        // An argument whose type cannot be inferred does *not* match a
        // parameter that names one: an overload is chosen only on evidence,
        // and `resolve_fn_call` reports the call rather than guessing.
        // For a parameter type with no scalar spelling (`optional<…>` and
        // friends) there is nothing to judge, so allow.
        _ => match (ty.scalar_pg_type(), infer_ir_type(expr)) {
            (Some(declared), Some(known)) => types_compatible(known, declared),
            (Some(_), None) => false,
            (None, _) => true,
        },
    }
}

/// True for a call like `array_unpack` that yields a set rather than one value.
fn expr_returns_set(expr: &Expr) -> bool {
    let Expr::FunctionCall(call) = expr else {
        return false;
    };
    crate::stdlib::lookup(call.module.as_deref().unwrap_or("std"), &call.name)
        .iter()
        .any(|d| d.returns_set())
}

fn literal_sentinel_to_pg(t: &str) -> &str {
    match t {
        "__int_literal" => "int8",
        "__float_literal" => "float8",
        other => other,
    }
}

fn is_array_expr(expr: &IrExpr) -> bool {
    match through_coalesce(expr) {
        IrExpr::Array(_) | IrExpr::ArrayFromSelect(_) => true,
        // `str_split(…)[-1]` — a stdlib call declared to return an array,
        // which `infer_ir_type` cannot spell because it only names scalars.
        IrExpr::FunctionCall(f) if f.schema.is_none() => {
            let mut overloads = crate::stdlib::registry().iter().filter(|d| d.name == f.name).peekable();
            overloads.peek().is_some() && overloads.all(|d| matches!(d.return_type, crate::stdlib::PylonType::Array(_)))
        }
        // Everything else an array can arrive as — a column, a cast, a
        // global, a `with` binding, a concatenation of any of those — is
        // known by the type it carries.
        other => matches!(infer_ir_type(other), Some(t) if t.ends_with("[]")),
    }
}

/// A lower bound, computable without running the query, on how many bytes a
/// `notify()` payload will serialize to.
///
/// Only the parts that are already known contribute: string literals count
/// their own length, a concatenation sums its sides, a free object counts the
/// JSON envelope it will always emit (`{}`, the quoted field names, and the
/// `:`/`,` separators) plus whatever its field expressions themselves floor
/// at. Anything runtime-valued — a column, a parameter, a function call —
/// contributes 0, so this never over-estimates and never rejects a payload
/// that could actually have fit.
///
/// Exists because Postgres's 8000-byte NOTIFY cap is enforced at *runtime*,
/// and blowing it aborts the transaction that sent the notification — which,
/// for the composed `with update ... select (notify(...), updated)` shape, is
/// the write itself.
fn static_min_payload_bytes(expr: &ast::Expr) -> usize {
    use crate::parse::ast::{BinOpKind, Expr, Literal};
    match expr {
        Expr::Literal(Literal::Str(s)) => s.len(),
        Expr::BinOp(op) if matches!(op.op, BinOpKind::Concat) => {
            static_min_payload_bytes(&op.left) + static_min_payload_bytes(&op.right)
        }
        Expr::Shape(sh) if sh.expr.is_none() => {
            // `{"a":,"b":}` — braces, one quoted name and colon per field,
            // and a comma between them. Every one of those bytes is emitted
            // regardless of what the values turn out to be.
            let mut total = 2;
            for (i, el) in sh.elements.iter().enumerate() {
                if i > 0 {
                    total += 1;
                }
                let name_len = match el.path.steps.last() {
                    Some(crate::parse::ast::PathStep::Name(n)) => n.len(),
                    _ => 0,
                };
                total += name_len + 3;
                if let Some(value) = &el.compexpr {
                    total += static_min_payload_bytes(value);
                }
            }
            total
        }
        _ => 0,
    }
}

fn expr_to_std_type(expr: &ast::Expr) -> &'static str {
    match expr {
        ast::Expr::Literal(ast::Literal::Str(_)) => "std::str",
        ast::Expr::Literal(ast::Literal::Int(_)) => "std::int64",
        ast::Expr::Literal(ast::Literal::Float(_)) => "std::float64",
        ast::Expr::Literal(ast::Literal::Bool(_)) => "std::bool",
        _ => "anytype",
    }
}

fn named_tuple_type_str(fields: &[(String, ast::Expr)]) -> String {
    let inner = fields
        .iter()
        .map(|(k, v)| format!("{}: {}", k, expr_to_std_type(v)))
        .collect::<Vec<_>>()
        .join(", ");
    format!("tuple<{}>", inner)
}

fn positional_tuple_type_str(elems: &[ast::Expr]) -> String {
    let inner = elems.iter().map(expr_to_std_type).collect::<Vec<_>>().join(", ");
    format!("tuple<{}>", inner)
}

pub(crate) fn infer_ir_type(expr: &IrExpr) -> Option<&str> {
    match expr {
        IrExpr::ColumnRef { pg_type, .. } => Some(pg_type.as_str()),
        IrExpr::TypeCast(tc) => Some(tc.pg_type.as_str()),
        IrExpr::FnParam { pg_type, .. } => Some(pg_type.as_str()),
        IrExpr::Literal(lit) => Some(match lit {
            IrLiteral::Str(_) => "text",
            IrLiteral::Int(_) => "__int_literal",
            IrLiteral::Float(_) => "__float_literal",
            IrLiteral::Bool(_) => "boolean",
        }),
        IrExpr::EnumLiteral { pg_type, .. } => Some(pg_type.as_str()),
        IrExpr::NamedTuple { .. } => Some("jsonb"),
        IrExpr::JsonbField { .. } | IrExpr::JsonbIndex { .. } => Some("jsonb"),
        IrExpr::GlobalParam { pg_type, .. } => Some(pg_type.as_str()),
        // A `with`-bound scalar is typed by what it binds, so a call over one
        // resolves to the same overload the bare value would.
        IrExpr::CteRef { pg_type, .. } => pg_type.as_deref(),
        // A correlated path subquery is typed by whatever it projects — the
        // scalar column at the end of the path. An object-valued one yields
        // an id, which no operator should silently compare against.
        IrExpr::PathSubquery(ps) => match &ps.result {
            IrPathResult::Scalar(e, _) => infer_ir_type(e),
            IrPathResult::Object { .. } => None,
        },
        // `a ++ b` and `distinct a` both yield whatever they were given, so
        // an array stays recognisable as one through either.
        IrExpr::BinOp(b) if b.op == crate::parse::ast::BinOpKind::Concat => {
            infer_ir_type(&b.left).or_else(|| infer_ir_type(&b.right))
        }
        IrExpr::UnaryOp(u) if u.op == crate::parse::ast::UnaryOpKind::Distinct => infer_ir_type(&u.operand),
        // `-x` is a number of x's own type; `not x` and `exists x` are always
        // boolean.
        IrExpr::UnaryOp(u) if u.op == crate::parse::ast::UnaryOpKind::Minus => infer_ir_type(&u.operand),
        IrExpr::UnaryOp(u)
            if matches!(
                u.op,
                crate::parse::ast::UnaryOpKind::Not | crate::parse::ast::UnaryOpKind::Exists
            ) =>
        {
            Some("boolean")
        }
        // `a ?? b` and `a if c else b` yield a value of their branches' own
        // type, so a call over either resolves the overload the bare value
        // would. Whichever side carries a type decides: the other is routinely
        // the untypeable one — an empty set, or a path known only to be
        // optional.
        IrExpr::BinOp(b) if b.op == crate::parse::ast::BinOpKind::Coalesce => {
            infer_ir_type(&b.left).or_else(|| infer_ir_type(&b.right))
        }
        IrExpr::IfElse(ie) => infer_ir_type(&ie.if_).or_else(|| infer_ir_type(&ie.else_)),
        // A slice is the same type as the thing sliced — `substr` of text is
        // text, of bytea is bytea, and an array slice is still that array.
        // Without this a `to_bytes(x)[12:16]` reaching a `bytes` parameter
        // reads as untyped, which is the difference between resolving the
        // bytes overload and resolving nothing at all.
        IrExpr::Slice { expr, .. } => infer_ir_type(expr),
        // `xs[0]` is one element of what `xs` holds — the array type with its
        // `[]` taken off. A string or bytes subscript stays the type it
        // indexes, the way the `substr` it emits does.
        IrExpr::CteFieldRef { pg_type, .. } | IrExpr::ForVar { pg_type, .. } => pg_type.as_deref(),
        IrExpr::Subscript { expr, is_array, .. } => {
            // `str_split(s, '::')[0]`: the array a stdlib call returns is not a
            // type `infer_ir_type` can name (it only names scalars), so the
            // element type comes from the overload's own declared return type.
            let Some(base) = infer_ir_type(expr) else {
                return stdlib_array_element_type(expr);
            };
            if *is_array { base.strip_suffix("[]") } else { Some(base) }
        }
        IrExpr::BinOp(b) => arithmetic_result_type(&b.op, infer_ir_type(&b.left)?, infer_ir_type(&b.right)?),
        // The `coalesce` the compiler itself builds — around an aggregate that
        // ran over nothing, or a `??` whose sides name rows — carries no
        // recorded return type, so it is typed from its arguments like the
        // operator it stands in for.
        IrExpr::FunctionCall(f) if f.schema.is_none() && f.name == "coalesce" => f.args.iter().find_map(infer_ir_type),
        IrExpr::FunctionCall(f) if f.schema.is_none() && matches!(f.name.as_str(), "max" | "min" | "sum") => {
            aggregate_result_type(&f.name, infer_ir_type(f.args.first()?)?)
        }
        IrExpr::AggOverSet {
            fn_name, schema: None, ..
        } if fn_name == "count" => Some("int8"),
        IrExpr::AggOverSet {
            fn_name,
            schema: None,
            elems,
        } => aggregate_result_type(fn_name, infer_ir_type(elems.first()?)?),
        // Any call whose resolution recorded a scalar return type — a stdlib
        // overload (`enc::base64_decode(…)` is bytea) or a user-defined
        // function, which is how a computed pointer's declared type gets
        // checked against the function it calls at all.
        IrExpr::FunctionCall(f) => f.return_pg_type.as_deref(),
        _ => None,
    }
}

/// The element type of an array a stdlib call returns, for an expression whose
/// own type `infer_ir_type` cannot name. `None` unless every overload of the
/// name returns an array of the same scalar — the call would be ambiguous
/// otherwise, and guessing is what overload resolution exists to avoid.
fn stdlib_array_element_type(expr: &IrExpr) -> Option<&'static str> {
    let IrExpr::FunctionCall(f) = expr else {
        return None;
    };
    if f.schema.is_some() {
        return None;
    }
    let mut element: Option<&'static str> = None;
    for descriptor in crate::stdlib::registry().iter().filter(|d| d.name == f.name) {
        let crate::stdlib::PylonType::Array(inner) = &descriptor.return_type else {
            return None;
        };
        let scalar = inner.scalar_pg_type()?;
        if element.is_some_and(|seen| seen != scalar) {
            return None;
        }
        element = Some(scalar);
    }
    element
}

/// What `+` and `-` yield over instants and durations — a datetime minus a
/// datetime is a duration, a datetime shifted by one is a datetime.
/// `duration_to_seconds(datetime_of_transaction() - .started_at)` is the shape
/// this exists for, and it resolves no overload while the subtraction reads as
/// untyped.
fn temporal_result_type(op: &ast::BinOpKind, left: &str, right: &str) -> Option<&'static str> {
    use ast::BinOpKind::*;
    let instant = |t: &str| matches!(t, "timestamptz" | "timestamp" | "date" | "time");
    match (op, left, right) {
        (Sub, l, r) if instant(l) && instant(r) => Some("interval"),
        (Sub | Add, l, "interval") if instant(l) => Some(match l {
            "timestamptz" => "timestamptz",
            "timestamp" => "timestamp",
            "date" => "date",
            _ => "time",
        }),
        (Add, "interval", r) if instant(r) => Some(match r {
            "timestamptz" => "timestamptz",
            "timestamp" => "timestamp",
            "date" => "date",
            _ => "time",
        }),
        (Add | Sub, "interval", "interval") => Some("interval"),
        _ => None,
    }
}

/// The type an arithmetic operator's result carries, from its operands'.
/// `None` for anything but a pair of numbers.
fn arithmetic_result_type(op: &ast::BinOpKind, left: &str, right: &str) -> Option<&'static str> {
    use ast::BinOpKind::*;
    if !matches!(op, Add | Sub | Mul | Div | FloorDiv | Mod | Pow) {
        return None;
    }
    let (left, right) = (literal_sentinel_to_pg(left), literal_sentinel_to_pg(right));
    if let Some(temporal) = temporal_result_type(op, left, right) {
        return Some(temporal);
    }
    let int = |t: &str| INT_TYPES.contains(&t);
    let float = |t: &str| FLOAT_TYPES.contains(&t);
    let numeric = |t: &str| NUMERIC_TYPES.contains(&t);
    if int(left) && int(right) {
        return Some(if matches!(op, Div | Pow) {
            "float8"
        } else if left == "int8" || right == "int8" {
            "int8"
        } else if left == "int4" || right == "int4" {
            "int4"
        } else {
            "int2"
        });
    }
    if (float(left) || int(left)) && (float(right) || int(right)) {
        return Some(if left == "float4" && right == "float4" {
            "float4"
        } else {
            "float8"
        });
    }
    if (numeric(left) || int(left)) && (numeric(right) || int(right)) {
        return Some("numeric");
    }
    None
}

/// What `max`, `min` and `sum` over values of `element` yield.
fn aggregate_result_type<'a>(name: &str, element: &'a str) -> Option<&'a str> {
    let element = literal_sentinel_to_pg(element);
    match name {
        "max" | "min" => Some(element),
        "sum" if INT_TYPES.contains(&element) => Some("int8"),
        "sum" if FLOAT_TYPES.contains(&element) || NUMERIC_TYPES.contains(&element) => Some(element),
        _ => None,
    }
}

/// The left operand of `left op right`, cast to `float8` when `op` divides
/// two integers: PyQL's `/` yields a float64 there, Postgres's truncates.
fn true_division_operand(op: &ast::BinOpKind, left: IrExpr, right: &IrExpr) -> IrExpr {
    let integer = |expr: &IrExpr| infer_ir_type(expr).is_some_and(|t| INT_TYPES.contains(&literal_sentinel_to_pg(t)));
    if *op != ast::BinOpKind::Div || !integer(&left) || !integer(right) {
        return left;
    }
    IrExpr::TypeCast(Box::new(IrTypeCast {
        expr: left,
        pg_type: "float8".to_string(),
        tuple_shape: None,
    }))
}

/// Maps a resolved element `pg_type` (as `infer_ir_type` reports it) to the
/// PostgreSQL native range constructor over that type. PG has no float4/
/// float8/int2/int4-native range type — only int8range, numrange, tsrange,
/// tstzrange, and daterange exist — so untyped int/float literals default
/// to the widest native family (int8/numeric) rather than erroring, matching
/// how those literals already default elsewhere in Pylon.
fn range_ctor_for_pg_type(pg_type: &str) -> Option<&'static str> {
    match pg_type {
        "int2" | "int4" | "int8" | "__int_literal" => Some("int8range"),
        "numeric" | "__float_literal" => Some("numrange"),
        "timestamp" => Some("tsrange"),
        "timestamptz" => Some("tstzrange"),
        "date" => Some("daterange"),
        _ => None,
    }
}

/// The multirange counterpart of a range constructor name resolved by
/// `range_ctor_for_pg_type`.
fn multirange_ctor_for_range_ctor(range_ctor: &str) -> Option<&'static str> {
    match range_ctor {
        "int8range" => Some("int8multirange"),
        "numrange" => Some("nummultirange"),
        "tsrange" => Some("tsmultirange"),
        "tstzrange" => Some("tstzmultirange"),
        "daterange" => Some("datemultirange"),
        _ => None,
    }
}

const INT_TYPES: &[&str] = &["int2", "int4", "int8", "__int_literal"];
const FLOAT_TYPES: &[&str] = &["float4", "float8", "__float_literal"];
/// Postgres `numeric` backs both Pylon's `bigint` and `decimal` (see
/// `pg_type_for_scalar_name`) — Pylon doesn't distinguish them at the
/// pg_type level, so this bucket covers both.
const NUMERIC_TYPES: &[&str] = &["numeric"];

/// Pylon's implicit-cast graph for numeric operands:
/// `int16 → int32 → int64 → float32 → float64` on one branch and
/// `int64 → bigint → decimal` on another — every int width casts to every
/// float width and to numeric/decimal, but float and numeric/decimal don't
/// cast to each other (they're separate branches past `int64`). Postgres's
/// own operator resolution handles the actual mixed-type arithmetic once
/// the compile-time gate lets it through (e.g. `int2 + float4` is a native
/// Postgres operator) — this only needs to match which operand-type
/// combinations are meant to be allowed.
pub(crate) fn types_compatible(a: &str, b: &str) -> bool {
    if a == b {
        return true;
    }
    let a_int = INT_TYPES.contains(&a);
    let b_int = INT_TYPES.contains(&b);
    if a_int && b_int {
        return true;
    }
    let a_float = FLOAT_TYPES.contains(&a);
    let b_float = FLOAT_TYPES.contains(&b);
    if a_float && b_float {
        return true;
    }
    let a_numeric = NUMERIC_TYPES.contains(&a);
    let b_numeric = NUMERIC_TYPES.contains(&b);
    if a_numeric && b_numeric {
        return true;
    }
    (a_int && b_float) || (a_float && b_int) || (a_int && b_numeric) || (a_numeric && b_int)
}

/// Datetime/duration `+`/`-` pairs PostgreSQL supports natively (e.g.
/// `timestamptz + interval`) that `types_compatible`'s bucket-matching
/// (same type, or both-int, or both-float) doesn't cover. Deliberately a
/// separate, narrower check from `types_compatible` (also used for UNION-branch
/// compatibility, where "a datetime and a duration are interchangeable"
/// would be nonsensical) rather than folded into it, so this can't leak
/// into a context where "arithmetic-compatible" isn't the same relation as
/// "interchangeable." Postgres's own operator resolution is the final
/// authority on any (op, operand-order) combination that doesn't actually
/// exist (e.g. `interval - timestamptz`) — this only needs to widen the
/// compile-time gate far enough to let the legitimate combinations through.
fn datetime_arithmetic_compatible(op: &ast::BinOpKind, a: &str, b: &str) -> bool {
    if !matches!(op, ast::BinOpKind::Add | ast::BinOpKind::Sub) {
        return false;
    }
    matches!(
        (a, b),
        ("timestamptz", "interval")
            | ("interval", "timestamptz")
            | ("timestamp", "interval")
            | ("interval", "timestamp")
            | ("date", "interval")
            | ("interval", "date")
            | ("time", "interval")
            | ("interval", "time")
    )
}

/// Collect `SearchEnqueueInfo` for every OpenSearch- or Meilisearch-backed
/// search index on a type — `Postgres`-backed indexes are excluded since
/// they're maintained synchronously by a trigger-updated tsvector column,
/// not an async outbox worker.
fn collect_search_enqueue(td: &TypeDescriptor, type_name: &str, operation: &'static str) -> Vec<SearchEnqueueInfo> {
    td.search_indexes
        .iter()
        .filter(|si| si.backend == SearchBackend::OpenSearch || si.backend == SearchBackend::Meilisearch)
        .map(|si| SearchEnqueueInfo {
            type_name: type_name.to_string(),
            index_name: si.index_name.clone(),
            operation,
            backend: si.backend.clone(),
        })
        .collect()
}

/// Reverse of `type_expr_to_pg`'s plain-scalar branch — renders a base
/// Postgres type back to its canonical PyQL display name. `pub` (not just
/// crate-local): reused by `pylon-server`'s `/api/schema` port
/// (`_scalar_type_name`'s equivalent) so that display-name logic isn't
/// duplicated across crates.
///
/// `"interval"`/`"date"`/`"time"`/`"timestamp"` are inherently ambiguous
/// from the bare pg_type alone: `interval` backs both `std::duration` and
/// `cal::relative_duration` (defaults to the former — the more common
/// case), while `date`/`time`/`timestamp` (no tz) are unambiguous (only
/// `cal::local_date`/`cal::local_time`/`cal::local_datetime` use them, as
/// opposed to `timestamptz` for `std::datetime`).
pub fn pg_type_to_pyql(pg: &str) -> &str {
    match pg {
        "text" | "varchar" => "std::str",
        "uuid" => "std::uuid",
        "int2" => "std::int16",
        "int4" => "std::int32",
        "int8" => "std::int64",
        "float4" => "std::float32",
        "float8" => "std::float64",
        "boolean" => "std::bool",
        "numeric" => "std::decimal",
        "timestamptz" => "std::datetime",
        "timestamp" => "cal::local_datetime",
        "date" => "cal::local_date",
        "time" => "cal::local_time",
        "interval" => "std::duration",
        "bytea" => "std::bytes",
        "jsonb" => "std::json",
        "__int_literal" => "std::int64",
        "__float_literal" => "std::float64",
        other => other,
    }
}