waxsql 1.0.0__py3-none-any.whl

waxsql/gen/setop.py

@@ -0,0 +1,259 @@
+"""Set-operation generator (UNION / INTERSECT / EXCEPT).
+
+Role: combines N SELECTs into one statement. The hard constraint
+that gives the file its shape: both (all) sides of a set-op must
+produce the SAME column types in the SAME order. PG enforces this
+positionally — column #i of every arm must implicitly-cast to a
+common type with column #i of every other arm. The generator
+sidesteps the cross-arm cast negotiation entirely by FIXING arm 1's
+exact target types and reusing them as the spec for arms 2..N (see
+`target_types` below). Arms 2..N don't get gen_select's full freedom;
+they call _gen_arm_select with a pinned type list.
+
+One public entry point: `gen_setop(ctx)` builds a SetOp wrapping
+N Selects with matching column counts and types.
+
+Two phases:
+
+  1. **Arm 1**: a full `gen_select(arm1_ctx)` in its own child scope.
+     Could be aggregate, could have any target shape. We extract its
+     target types after generation, then strip its with_ctes /
+     order_by / limit / offset (those belong to the SetOp wrapper,
+     not the arm).
+
+  2. **Arms 2+**: simpler Selects that match arm 1's target types
+     position-by-position. Built via `_gen_arm_select` which produces
+     a non-aggregate SELECT with FROM, optional WHERE, and one
+     SelectTarget per requested type (generated via gen_expr against
+     the arm's local scope).
+
+Each arm gets its own scope via `descend_subquery(correlated=False)`
+so arm-local FROM aliases don't collide with the surrounding query
+or with other arms. The shared `alias_counter` (and `cte_counter`)
+ensures unique naming across the whole query.
+
+After all arms are generated, the SetOp wrapper optionally gets
+its own ORDER BY (positional reference: `ORDER BY 1`) and LIMIT —
+both PG-valid only at the combined-statement level for milestone 7
+(per-arm ORDER BY/LIMIT requires explicit parens).
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Optional
+
+from ..ast import (
+    Expr, Literal, OrderByItem, Select, SelectTarget, SetOp,
+)
+from ..config import (
+    FEATURE_LIMIT, FEATURE_ORDER_BY, FEATURE_WHERE,
+)
+from ..context import GenContext
+from ..types import BOOL, INT4, PgType
+from .expr import gen_expr
+
+
+_LIMIT_VALUES: tuple[int, ...] = (1, 5, 10, 25, 50, 100)
+
+
+def gen_setop(ctx: GenContext) -> SetOp:
+    """Generate a SetOp combining N arms with the chosen operator.
+
+    Arm 1 is a full gen_select; subsequent arms match arm 1's
+    target types via _gen_arm_select OR (with probability
+    `cfg.p_nested_set_op_arm`) by recursively generating another
+    SetOp whose own first arm matches the parent's target types.
+
+    Each arm has its own child scope; the shared alias_counter
+    prevents cross-arm alias collision. Nested SetOps consume
+    `subquery_depth_remaining` via the per-arm descend_subquery,
+    so unbounded nesting is impossible.
+
+    The SetOp wrapper's ORDER BY/LIMIT (if generated) reference
+    output columns positionally (`ORDER BY 1`) — the only form
+    that works without naming the unified output columns
+    explicitly.
+    """
+    # Lazy import — gen_select / _gen_arm_select live in gen/select.py,
+    # which currently doesn't import gen/setop.py but might in future.
+    from .select import gen_select
+
+    cfg = ctx.config
+    rng = ctx.rng
+
+    n_arms = rng.randint(2, cfg.max_set_op_arms)
+    op = rng.choice(("UNION", "INTERSECT", "EXCEPT"))
+    all_ = rng.random() < cfg.p_set_op_all
+
+    # Arm 1: full SELECT in its own child scope. MUST be generated
+    # before arms 2+ — its target types drive everything downstream
+    # (positional set-op compatibility means every later arm's
+    # targets are typed-matched to arm 1's, not the other way).
+    arm1_ctx = ctx.descend_subquery(correlated=False)
+    arm1 = _strip_arm_clauses(gen_select(arm1_ctx))
+    # `target_types` is the positional type signature every later arm
+    # must match. We extract it from arm 1 AFTER stripping the
+    # combined-statement clauses but BEFORE iterating arms 2..N —
+    # gen_select's own type choices become the canonical spec for
+    # the whole set-op.
+    target_types: list[PgType] = [t.expr.pg_type for t in arm1.targets]
+
+    # `arms` may hold either Selects or nested SetOps (Track B #5).
+    # The explicit union annotation keeps mypy honest about the
+    # mixed-element list — without it, the inferred type from the
+    # initial `[arm1]` (Select-only) would reject the SetOp append.
+    arms: list[Select | SetOp] = [arm1]
+    for _ in range(n_arms - 1):
+        arm_ctx = ctx.descend_subquery(correlated=False)
+        # Nested-SetOp candidate gating:
+        #   * Need budget — descending into a nested SetOp consumes
+        #     another subquery_depth in turn for its own arms.
+        #   * Probability gate. Kept moderate-low; deeply nested
+        #     setops aren't realistic SQL and produce huge outputs.
+        arm: Select | SetOp
+        if (not arm_ctx.at_subquery_leaf()
+                and rng.random() < cfg.p_nested_set_op_arm):
+            arm = _gen_nested_setop_arm(arm_ctx, target_types)
+        else:
+            arm = _gen_arm_select(arm_ctx, target_types)
+        arms.append(arm)
+
+    # SetOp-level ORDER BY (positional) and LIMIT.
+    order_by: tuple[OrderByItem, ...] = ()
+    if (FEATURE_ORDER_BY in cfg.feature_flags
+            and rng.random() < cfg.p_order_by):
+        # Positional reference: `ORDER BY <n> ASC|DESC`. PG interprets
+        # bare integer literals in ORDER BY as 1-based output-column
+        # references — works regardless of what the unified output
+        # columns are named.
+        pos = rng.randint(1, len(target_types))
+        direction = rng.choice(("ASC", "DESC"))
+        order_by = (OrderByItem(
+            expr=Literal(INT4, pos),
+            direction=direction,
+        ),)
+
+    limit: Optional[Expr] = None
+    if (FEATURE_LIMIT in cfg.feature_flags
+            and rng.random() < cfg.p_limit):
+        limit = Literal(INT4, rng.choice(_LIMIT_VALUES))
+
+    return SetOp(
+        op=op,
+        all=all_,
+        arms=tuple(arms),
+        order_by=order_by,
+        limit=limit,
+    )
+
+
+# ===========================================================================
+# Internals
+# ===========================================================================
+
+def _gen_nested_setop_arm(
+    ctx: GenContext,
+    target_types: list[PgType],
+) -> SetOp:
+    """Generate a nested SetOp suitable for use as an arm of an
+    outer SetOp.
+
+    All arms of the nested SetOp must produce the same target_types
+    as the outer's arm 1 (set-op type compatibility is positional).
+    The nested SetOp also doesn't get its own ORDER BY/LIMIT —
+    those would be ambiguous with the outer's, and PG requires
+    explicit per-arm parens for them anyway. The wrapping parens
+    happen in the printer based on AST structure.
+
+    Currently always 2-armed (no further nesting). Could recurse to
+    arbitrary depth via subquery_depth_remaining, but two-deep
+    nesting (`A UNION (B INTERSECT C)`) is the realistic case;
+    deeper chains produce mostly-unreadable output.
+    """
+    rng = ctx.rng
+    op = rng.choice(("UNION", "INTERSECT", "EXCEPT"))
+    all_ = rng.random() < ctx.config.p_set_op_all
+
+    # All arms of the nested SetOp use _gen_arm_select with the
+    # given target types, ensuring positional type alignment with
+    # the OUTER setop's arm 1.
+    n_arms = 2
+    inner_arms: list[Select] = []
+    for _ in range(n_arms):
+        sub_ctx = ctx.descend_subquery(correlated=False)
+        inner_arms.append(_gen_arm_select(sub_ctx, target_types))
+
+    # No order_by / limit / offset — those belong only to the
+    # outermost SetOp wrapper.
+    return SetOp(op=op, all=all_, arms=tuple(inner_arms))
+
+
+def _strip_arm_clauses(s: Select) -> Select:
+    """Remove clauses that belong to the SetOp wrapper, not individual
+    arms — with_ctes, order_by, limit, offset.
+
+    PG's grammar requires per-arm ORDER BY/LIMIT/OFFSET to be wrapped
+    in parens. Stripping is simpler than parenthesizing, and the
+    SetOp wrapper carries equivalents at the combined-statement level."""
+    return replace(
+        s,
+        with_ctes=(),
+        order_by=(),
+        limit=None,
+        offset=None,
+    )
+
+
+# CONTRACT: every Select returned here has exactly len(target_types)
+# targets, in order, with each target's pg_type implicitly-castable
+# from target_types[i]. This is what the outer SetOp wrapper relies
+# on for cross-arm compatibility. Violating it produces a PG error
+# like "each UNION query must have the same number of columns" or
+# "UNION types int and text cannot be matched".
+def _gen_arm_select(
+    ctx: GenContext,
+    target_types: list[PgType],
+) -> Select:
+    """Build a Select for an arms-2+ SetOp arm: FROM clause, target
+    list of pre-determined types, optional WHERE.
+
+    Bypasses gen_select's aggregate-vs-non-aggregate dispatch: arm
+    Selects in milestone 7 are always non-aggregate (matching aggregate
+    target types from arm 1 across arms is handled by the type
+    machinery, not the GROUP BY logic). Aggregate-style arms can come
+    in a follow-up.
+    """
+    # Lazy imports for the same cycle-breaking reason as gen/cte.py
+    # — gen/select.py imports from gen/setop.py at the top level, so
+    # importing _gen_from_clause at module top would close the loop.
+    from .select import _gen_from_clause
+
+    cfg = ctx.config
+    rng = ctx.rng
+    flags = cfg.feature_flags
+
+    # FROM clause — populates arm-local scope.
+    from_ = _gen_from_clause(ctx)
+
+    # Target list: one SelectTarget per requested type, generated
+    # against the arm's scope. allow_aggregates=False because this
+    # path is non-aggregate.
+    expr_ctx = replace(ctx, allow_aggregates=False)
+    targets = tuple(
+        SelectTarget(expr=gen_expr(expr_ctx, t))
+        for t in target_types
+    )
+
+    # Optional WHERE.
+    where: Optional[Expr] = None
+    if FEATURE_WHERE in flags and rng.random() < cfg.p_where:
+        where = gen_expr(expr_ctx, BOOL)
+
+    return Select(
+        targets=targets,
+        from_=from_,
+        where=where,
+    )
+
+
+__all__ = ["gen_setop"]

waxsql/gen/subquery.py

@@ -0,0 +1,397 @@
+"""Subquery generators.
+
+Role: covers the four SQL surfaces where a SELECT appears as a value
+or table source inside another query. Each public entry point hands
+back an AST node that gen_expr or gen_select can splice directly into
+the surrounding tree.
+
+SCOPE HANDLING is the subtle bit. Correlated subqueries need the
+outer scope visible while the inner is being built (so inner
+expressions can pick outer columns); derived tables produce a fresh
+scope whose *outer* names are projected back as `alias.cN` and whose
+*internals* are NOT visible to siblings. `descend_subquery` on the
+context is the chokepoint that decides which: passing
+correlated=True keeps the outer chain reachable from the child scope;
+correlated=False severs it.
+
+Four public entry points. The first three return a complete `Expr`
+for use in `gen/expr.py`'s candidate dispatch; the fourth returns a
+FromItem for `gen/select.py`'s FROM-clause builder:
+
+  * `gen_scalar_subquery(ctx, target_type, *, correlated)` — returns
+    a `Subquery(target_type, inner)`. Inner has a single target of
+    `target_type` and `LIMIT 1` for runtime safety.
+
+  * `gen_exists_subquery(ctx, *, correlated)` — returns
+    `Exists(BOOL, inner, negated)`. Inner has the canonical
+    `SELECT 1 FROM ...` shape.
+
+  * `gen_in_subquery(ctx, *, correlated)` — returns
+    `InSubquery(BOOL, lhs, inner, negated)`. The LHS is generated
+    BEFORE descending (so it references the outer scope, not the
+    inner FROM tables); the inner produces a single column of the
+    LHS's type.
+
+  * `gen_derived_table(ctx, alias, *, lateral)` — returns a
+    `DerivedTable` FromItem (`[LATERAL ](SELECT ...) AS alias`).
+    Inner has 1..N targets aliased c1..cN; with `lateral=True`,
+    the same forced-correlation predicate gets injected so LATERAL
+    actually exercises its capability.
+
+All four share `_build_subquery_select`, which handles the recurring
+pattern: descend, build FROM, build target(s), optionally WHERE,
+force correlation if requested.
+
+The "force correlation" path is what gives the `correlated=True`
+flag teeth — without it, the inner WHERE might happen to pick an
+outer column or might not, and the test suite's
+"correlated-references-outer" invariant would be flaky. With it,
+every correlated subquery has at least one outer-column reference
+in its WHERE.
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Optional
+
+from ..ast import (
+    BinaryOp, ColumnRef, DerivedTable, Exists, Expr, InSubquery, Literal,
+    Select, SelectTarget, Subquery,
+)
+from ..config import FEATURE_WHERE
+from ..context import GenContext
+from ..scope import Scope
+from ..types import BOOL, INT4, INT8, NUMERIC, PgType, TEXT, TIMESTAMPTZ
+from .expr import gen_expr, gen_literal
+
+
+# Probability of negating an EXISTS / IN subquery. Kept low: most
+# real SQL uses the affirmative form; NOT EXISTS / NOT IN appear
+# as anti-joins or set differences but less commonly.
+_P_NEGATE_EXISTS = 0.3
+_P_NEGATE_IN = 0.3
+
+# Type pool for the IN subquery's comparison. Chosen from types where
+# `=` is in the catalog so the inner SELECT's column type aligns with
+# what the outer LHS expression can produce. Excludes JSONB / arrays
+# since the catalog has no `=` op for those.
+_IN_COMPARISON_TYPES: tuple[PgType, ...] = (
+    INT4, INT8, NUMERIC, TEXT, TIMESTAMPTZ,
+)
+
+
+# ===========================================================================
+# Public entry points
+# ===========================================================================
+
+def gen_scalar_subquery(
+    ctx: GenContext,
+    target_type: PgType,
+    *,
+    correlated: bool,
+) -> Subquery:
+    """Generate a scalar subquery `(SELECT col FROM ...)` of
+    `target_type`. The inner SELECT has exactly one target, and
+    `LIMIT 1` to be runtime-safe even though we don't actually run
+    the queries (PG accepts multi-row scalar subqueries at parse
+    time but errors at runtime if more than one row comes back)."""
+    inner = _build_subquery_select(
+        ctx,
+        correlated=correlated,
+        target_type=target_type,
+        with_limit_1=True,
+    )
+    return Subquery(target_type, inner)
+
+
+def gen_exists_subquery(
+    ctx: GenContext,
+    *,
+    correlated: bool,
+) -> Exists:
+    """Generate `[NOT ]EXISTS (SELECT 1 FROM ...)`. The constant `1`
+    is the canonical EXISTS body — PG ignores the SELECT list at
+    runtime, so we don't waste generator effort building elaborate
+    expressions there."""
+    inner = _build_subquery_select(
+        ctx,
+        correlated=correlated,
+        target_expr=Literal(INT4, 1),
+        with_limit_1=False,
+    )
+    negated = ctx.rng.random() < _P_NEGATE_EXISTS
+    return Exists(BOOL, inner, negated=negated)
+
+
+def gen_derived_table(
+    ctx: GenContext,
+    alias: str,
+    *,
+    lateral: bool,
+) -> DerivedTable:
+    """Generate a derived-table FromItem `[LATERAL ](SELECT ...) AS alias`.
+
+    The inner SELECT has 1..N targets, each with explicit `cN` alias
+    so the outer query can reference `<alias>.cN` deterministically
+    regardless of what expressions the targets carry. Column count
+    drawn from the config knob `max_derived_table_columns` (capped
+    by determinism — same draw on same RNG state always picks the
+    same count). The single-column case remains the most common
+    output by virtue of the small max.
+
+    With `lateral=True`, the inner SELECT can reference the outer
+    scope's preceding-sibling aliases. The forced-correlation
+    predicate inside `_build_subquery_select` (already used by
+    correlated scalar/EXISTS/IN subqueries in milestone 3) guarantees
+    at least one outer-column reference appears in the inner WHERE
+    — turning "LATERAL capability" into "LATERAL actually exercises
+    the capability."
+
+    No LIMIT 1: derived tables are virtual TABLES (multi-row by
+    nature), unlike scalar subqueries that need LIMIT 1 for PG's
+    single-row runtime constraint.
+    """
+    rng = ctx.rng
+    cfg = ctx.config
+    n_cols = rng.randint(1, cfg.max_derived_table_columns)
+    target_types = tuple(
+        rng.choice(_IN_COMPARISON_TYPES) for _ in range(n_cols)
+    )
+    inner = _build_subquery_select(
+        ctx,
+        correlated=lateral,
+        target_types=target_types,
+        with_limit_1=False,
+    )
+    # Re-wrap each target with an explicit `cN` alias for stable
+    # outer-side column resolution.
+    inner_aliased = replace(
+        inner,
+        targets=tuple(
+            SelectTarget(expr=t.expr, alias=f"c{i + 1}")
+            for i, t in enumerate(inner.targets)
+        ),
+    )
+    return DerivedTable(inner_aliased, alias, lateral=lateral)
+
+
+def gen_in_subquery(
+    ctx: GenContext,
+    *,
+    correlated: bool,
+) -> InSubquery:
+    """Generate `<lhs> [NOT ]IN (SELECT col FROM ...)`. The LHS is
+    generated against the OUTER context so it references outer
+    columns, not the inner FROM tables. The inner produces a single
+    column whose type matches the LHS."""
+    # The InSubquery node returns BOOL to the caller, but the LHS and
+    # inner column share a different type — the equality-comparable
+    # type chosen here. Caller's "target_type=BOOL" gate (in expr.py)
+    # is what makes this candidate visible; this local `target_type`
+    # is the comparison-element type, not the outer-expression type.
+    target_type = ctx.rng.choice(_IN_COMPARISON_TYPES)
+    # CRITICAL: build LHS before descending. After descend_subquery
+    # the ctx.scope is the inner scope, and LHS column refs would
+    # come from inner tables — semantically wrong (LHS is part of
+    # the outer query's expression, not the inner subquery).
+    # ORDERING DEPENDENCY: this line MUST stay above the
+    # _build_subquery_select call below; reordering would silently
+    # produce SQL that parses but means something different.
+    lhs = gen_expr(ctx, target_type)
+    inner = _build_subquery_select(
+        ctx,
+        correlated=correlated,
+        target_type=target_type,
+        with_limit_1=False,
+    )
+    negated = ctx.rng.random() < _P_NEGATE_IN
+    return InSubquery(BOOL, lhs, inner, negated=negated)
+
+
+# ===========================================================================
+# Shared subquery body builder
+# ===========================================================================
+
+def _build_subquery_select(
+    ctx: GenContext,
+    *,
+    correlated: bool,
+    target_type: Optional[PgType] = None,
+    target_types: Optional[tuple[PgType, ...]] = None,
+    target_expr: Optional[Expr] = None,
+    with_limit_1: bool = False,
+) -> Select:
+    """Construct a SELECT for use as a subquery body.
+
+    Caller provides EXACTLY ONE target spec:
+      * `target_type` (singular) — generate a single target of that
+        type; convenience for the common single-column case.
+      * `target_types` (tuple) — generate len(target_types) targets,
+        one of each type. Used by multi-column derived tables / CTEs.
+      * `target_expr` — a pre-built single target expression
+        (used by EXISTS's constant `SELECT 1`).
+
+    The descent flow:
+      1. Capture outer scope (needed by the correlation forcer).
+      2. Descend via ctx.descend_subquery — fresh expression depth,
+         fresh aggregate flags, child scope (correlated or not).
+      3. Build FROM clause; the child scope acquires the inner tables.
+      4. Build the target list (generated or supplied).
+      5. Optionally generate WHERE (with allow_aggregates=False —
+         WHERE forbids aggregates, just like in the outer query).
+      6. If correlated, AND-inject an outer-referencing predicate
+         into WHERE.
+      7. Add LIMIT 1 if requested.
+    """
+    # Lazy import to break the cycle: gen/expr.py imports the public
+    # entry points above; importing _gen_from_clause at module top
+    # would close the import loop. Lazy import is the standard Python
+    # answer and incurs only a sys.modules dict lookup after first call.
+    from .select import _gen_from_clause
+
+    # Capture outer scope BEFORE descending — `descend_subquery`
+    # replaces ctx.scope with the child scope, so this is the last
+    # chance to keep a handle on the outer bindings. The correlation
+    # forcer below needs that handle to pick an outer column for the
+    # left-hand side of its injected predicate.
+    outer_scope = ctx.scope
+    child_ctx = ctx.descend_subquery(correlated=correlated)
+    cfg = child_ctx.config
+    rng = child_ctx.rng
+
+    from_clause = _gen_from_clause(child_ctx)
+
+    # Resolve the three input forms into a single `target_exprs`
+    # tuple. Exactly one of (target_expr, target_type, target_types)
+    # must be set; combinations would be ambiguous.
+    set_count = sum(
+        1 for x in (target_expr, target_type, target_types) if x is not None
+    )
+    if set_count != 1:
+        raise ValueError(
+            "_build_subquery_select needs exactly one of target_expr, "
+            f"target_type, target_types (got {set_count})"
+        )
+
+    if target_expr is not None:
+        target_exprs: tuple[Expr, ...] = (target_expr,)
+    else:
+        # Subquery targets generated with allow_aggregates=False to
+        # prevent the "mixed aggregate + non-aggregate-column-ref in
+        # the same target expression" bug class. Without GROUP BY,
+        # `col - max(other)` triggers implicit-grouping inference;
+        # the un-grouped col then errors at PARSE time (42803).
+        # Pure-aggregate subqueries lose direct generability here in
+        # exchange for PARSE-correctness; can be added back via a
+        # dedicated path if needed.
+        target_ctx = replace(child_ctx, allow_aggregates=False)
+        if target_types is not None:
+            types_tuple: tuple[PgType, ...] = target_types
+        else:
+            # Validated above: exactly-one-of (expr, type, types).
+            # When we reach this branch, target_expr is None and
+            # target_types is None, so target_type MUST be non-None.
+            assert target_type is not None
+            types_tuple = (target_type,)
+        target_exprs = tuple(gen_expr(target_ctx, t) for t in types_tuple)
+
+    where: Optional[Expr] = None
+    if FEATURE_WHERE in cfg.feature_flags and rng.random() < cfg.p_where:
+        where_ctx = replace(child_ctx, allow_aggregates=False)
+        where = gen_expr(where_ctx, BOOL)
+
+    if correlated:
+        where = _force_correlation_predicate(child_ctx, outer_scope, where)
+
+    return Select(
+        targets=tuple(SelectTarget(expr=e) for e in target_exprs),
+        from_=from_clause,
+        where=where,
+        limit=Literal(INT4, 1) if with_limit_1 else None,
+    )
+
+
+# ===========================================================================
+# Correlation enforcement
+# ===========================================================================
+
+def _force_correlation_predicate(
+    child_ctx: GenContext,
+    outer_scope: Scope,
+    existing_where: Optional[Expr],
+) -> Optional[Expr]:
+    """Inject `outer_col = X` into the inner WHERE, AND-combined with
+    any existing WHERE. Guarantees the subquery references the outer
+    scope at least once — the test suite's "correlated subqueries
+    actually correlate" invariant relies on this.
+
+    Picks an outer column whose type has a usable `=` operator (filters
+    out JSONB / arrays etc. that don't have catalog-registered equality).
+    The right-hand side is preferentially another column of the same
+    type from the inner scope; failing that, a literal of that type
+    (still satisfies "references outer" because the outer column is
+    on the left).
+    """
+    rng = child_ctx.rng
+
+    # Outer bindings whose types have a usable `=` in our catalog.
+    bool_ops = child_ctx.catalog.binary_ops_returning(BOOL)
+    # Set is fine for membership tests; we never iterate it.
+    eq_types = {
+        o.left for o in bool_ops
+        if o.symbol == "=" and o.left == o.right
+    }
+    outer_candidates = [
+        b for b in outer_scope.visible_columns()
+        if b.type in eq_types
+    ]
+    if not outer_candidates:
+        # Pathological — outer has no comparable columns. Skip
+        # correlation rather than emit invalid SQL.
+        return existing_where
+
+    outer = rng.choice(outer_candidates)
+
+    # RHS: prefer an inner column of the same type; fall back to a
+    # literal. Either way, the outer column reference on the LEFT is
+    # what makes this a correlated subquery.
+    #
+    # Why filter by `inner_aliases` rather than just calling
+    # visible_columns()? In a correlated child scope, visible_columns()
+    # returns BOTH inner bindings AND outer bindings (correlation lets
+    # outer columns leak in). If we picked an OUTER column for the RHS,
+    # the predicate would compare two outer columns — semantically a
+    # constant from the inner subquery's POV, which PG might pull out
+    # of the subquery as a constant filter, defeating correlation.
+    # Restricting to inner aliases keeps the LEFT/RIGHT asymmetry that
+    # makes this a real correlated reference.
+    inner_aliases = {a for a, _ in child_ctx.scope.aliased_tables()}
+    inner_candidates = [
+        b for b in child_ctx.scope.visible_columns()
+        if b.table_alias in inner_aliases and b.type == outer.type
+    ]
+    if inner_candidates:
+        inner = rng.choice(inner_candidates)
+        rhs: Expr = ColumnRef(inner.type, inner.table_alias, inner.column)
+    else:
+        rhs = gen_literal(rng, outer.type)
+
+    correlation = BinaryOp(
+        BOOL, "=",
+        ColumnRef(outer.type, outer.table_alias, outer.column),
+        rhs,
+    )
+
+    if existing_where is None:
+        return correlation
+    # AND-combine: outer-correlation predicate first, existing where
+    # second. Order is just for readability — both are evaluated.
+    return BinaryOp(BOOL, "AND", correlation, existing_where)
+
+
+__all__ = [
+    "gen_scalar_subquery",
+    "gen_exists_subquery",
+    "gen_in_subquery",
+    "gen_derived_table",
+]