ripple-sql 0.1.0__py3-none-any.whl

ripple/engine/column_ref.py

@@ -0,0 +1,818 @@
+"""Multi-part column reference resolution.
+
+BigQuery (and increasingly Databricks) allow `alias.struct_col.field.subfield`.
+sqlglot parses the leading identifiers into the Column node's catalog/db/table
+slots, so naively reading `col.table` turns a struct root into a phantom
+source table. This module decides, against the statement's known relations,
+which identifier is the relation and which is the column.
+
+Rules, in order:
+1. one or two parts: classic (alias, column), unchanged.
+2. leading part is a known relation alias/table: relation-anchored struct
+   access. `o.customer.name` -> relation o, column customer, field .name.
+3. the tail (everything but the last part, or just the second-to-last part)
+   is a known relation: fully qualified table.column. `ds.orders.customer`
+   -> relation orders, column customer.
+4. nothing matches: assume struct access on an unresolved relation, but say
+   so (certain=False) so the caller downgrades trust instead of fabricating
+   a confident edge.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlglot import exp
+
+from ripple.engine.preprocess import JINJA_DOT_SENTINEL, restore_jinja_dots
+
+
+def column_parts(col: exp.Column) -> list[str]:
+    """All identifier parts, leading to trailing: [o, customer, name].
+
+    Parts come back with the preprocess jinja-dot marker restored, so every
+    consumer compares and emits the as-written spelling (cycle-12, F19)."""
+    parts = []
+    for key in ("catalog", "db", "table"):
+        node = col.args.get(key)
+        if node is not None:
+            name = getattr(node, "name", None) or str(node)
+            if name:
+                parts.append(restore_jinja_dots(name))
+    parts.append(restore_jinja_dots(col.name))
+    return parts
+
+
+def table_and_column(col: exp.Column) -> tuple[str | None, str]:
+    """Relation-and-column read for filter/join dependencies, struct-aware.
+
+    `o.customer.tier` yields (o, customer): the filter depends on the struct
+    column, and the relation is the leading identifier, never the struct root.
+    """
+    parts = column_parts(col)
+    if len(parts) <= 2:
+        return (parts[0] if len(parts) == 2 else None, parts[-1])
+    return parts[0], parts[1]
+
+
+def resolve_column_ref(
+    col: exp.Column, known_relations: set[str]
+) -> tuple[str, str, str | None, bool]:
+    """Return (relation_or_alias, column, field_path, certain).
+
+    known_relations must be lowercase: query aliases, CTE names, table names
+    (bare and qualified), and array-expansion aliases.
+    """
+    parts = column_parts(col)
+    if len(parts) == 1:
+        return "", parts[0], None, True
+
+    leading = parts[0].lower()
+    if leading in known_relations:
+        if len(parts) == 2:
+            return parts[0], parts[1], None, True
+        field_path = ".".join(parts[2:]) or None
+        return parts[0], parts[1], field_path, True
+
+    if len(parts) >= 3:
+        full_qualification = ".".join(parts[:-1]).lower()
+        bare_table = parts[-2].lower()
+        if full_qualification in known_relations or bare_table in known_relations:
+            return parts[-2], parts[-1], None, True
+
+    # Unknown leading identifier: in warehouse SQL the likelier read is a
+    # struct root column (ecommerce.total_item_quantity on the sole FROM
+    # table; protopayload.auth.email inside a CTE). Return it unanchored;
+    # the caller anchors to the sole relation or downgrades trust. Never a
+    # confident phantom table.
+    field_path = ".".join(parts[1:]) or None
+    return "", parts[0], field_path, False
+
+
+def table_function_kind(table) -> str | None:
+    """Classify a Table wrapping a function call.
+
+    "srf": a set-returning function over COLUMN arguments (CROSS JOIN
+    jsonb_array_elements_text(roles) AS role) whose alias is an expansion of
+    those columns, never a relation. "relation": an opaque table function
+    over literals (read_parquet('f.parquet') rp), a real unknown-schema
+    relation that must keep blocking unique-ownership claims (review
+    of cycle 8). None: not a function table."""
+    func = table.this if isinstance(table, exp.Table) else None
+    if not isinstance(func, exp.Func):
+        return None
+    args = list(getattr(func, "expressions", None) or [])
+    if not args and isinstance(func.args.get("this"), exp.Expression):
+        args = [func.args["this"]]
+    return (
+        "srf"
+        if any(a.find(exp.Column) is not None for a in args if isinstance(a, exp.Expression))
+        else "relation"
+    )
+
+
+def table_function_relation_name(table) -> str:
+    """The written qualified name of an opaque table-function relation.
+
+    sys.fn_xe_file_target_read_file(...) is a catalog object whose output
+    columns exist independent of its arguments, so lineage cites the
+    function's own name instead of surfacing the query-local alias as a
+    relation (sqlserver_kit DarkQueries, holdout round 8). A bare function
+    like read_parquet('f.parquet') has no catalog identity (the file does);
+    '' keeps the alias-named relation for those."""
+    func = table.this if isinstance(table, exp.Table) else None
+    if not isinstance(func, exp.Anonymous) or not func.name:
+        return ""
+    qualifiers = [p for p in (table.catalog, table.db) if p and "{{" not in p]
+    if not qualifiers:
+        return ""
+    return ".".join([*qualifiers, func.name])
+
+
+def colliding_function_relations(
+    parsed, real_tables: set[str], function_relations: set[str] | None = None
+) -> dict[str, str]:
+    """Written name (lowered) -> degraded citation, for every opaque
+    table-function whose written name could bind a project relation.
+
+    PostgreSQL separates functions from relations by kind, so a function
+    analytics.events() may coexist with a relation analytics.events; a
+    citation by the shared spelling would confidently bind a relation the
+    query never reads. Such a name degrades to the query-local alias, the
+    unbindable citation these functions had before written names ('' when
+    the alias itself collides). Cycle-9 review, F2.
+
+    function_relations exempts names whose colliding relation IS the
+    function's own minted model (a CREATE FUNCTION traced by the TVF
+    path): there the call site should bind confidently, not degrade
+    (cycle-13 review, F11)."""
+    lowered = {t.lower() for t in real_tables}
+    exempt = {f.lower() for f in (function_relations or ())}
+
+    def _collides(name: str) -> bool:
+        low = name.lower()
+        return low in lowered or low.split(".")[-1] in lowered
+
+    out: dict[str, str] = {}
+    for table in parsed.find_all(exp.Table):
+        if table_function_kind(table) != "relation":
+            continue
+        written = table_function_relation_name(table)
+        if not written or written.lower() in exempt or not _collides(written):
+            continue
+        alias = table.alias or ""
+        out[written.lower()] = "" if alias and _collides(alias) else alias
+    return out
+
+
+def temp_marked_name(node) -> str:
+    """An identifier's spelling WITH its T-SQL temp marker.
+
+    sqlglot parses #stats_agg into Identifier(temporary=True) whose .name is
+    the bare "stats_agg". The prefix is namespace identity, not decoration
+    (#x and x are different tables, temps are connection-scoped): dropping it
+    let sp_Blitz's #dm_exec_query_stats mirror eclipse every repo-wide read
+    of the real sys.dm_exec_query_stats DMV (holdout round 6)."""
+    ident = node.this if isinstance(node, exp.Table) else node
+    name = node.name
+    if isinstance(ident, exp.Parameter):
+        # @tablevar: procedure-local scratch; the spelling keeps the marker
+        # so it can never eclipse (or pose as) a real relation
+        return f"@{name}" if name and not name.startswith("@") else name
+    if isinstance(ident, exp.Identifier) and name and not name.startswith("#"):
+        if ident.args.get("temporary"):
+            return f"#{name}"
+        if ident.args.get("global_"):
+            return f"##{name}"
+    return name
+
+
+def qualified_table_name(table: exp.Table) -> str:
+    """The relation's dotted name, with unrendered jinja placeholders dropped
+    from the QUALIFIER parts only.
+
+    A raw-SQL repo writing CREATE TABLE `{{reporting_db}}`.x deploys x into a
+    configured database; the placeholder is deploy config, not identity, and
+    keeping it made even the bare spelling unresolvable (patentsview, holdout
+    round 5). Partial spellings like `db_{{ env }}` are config too. The table
+    part itself is never dropped: stripping schema.`{{ params.table }}` down
+    to `schema` fabricated a relation named after the schema (review of
+    PR #28); a templated table name stays as written and stays unresolved.
+
+    When the table part ITSELF is templated, dropping qualifiers gains no
+    resolvable spelling; the whole relation round-trips as written
+    ({{params.dataset}}.blocks{{params.postfix}}, polygon_etl, round 11).
+    In-chain dots come back from the preprocess encoding here.
+
+    A qualifier that is a whole DOTTED chain ({{params.dataset_name_raw}},
+    the sentinel-encoded shape) is the round-trip convention's spelling of
+    an unrenderable relation path, not deploy config; dropping it emitted
+    bare `blocks` that resolved into the model itself and vanished
+    (bitcoin_etl, round 12). Single-name and partial placeholders keep the
+    round-5 drop."""
+    raw = [p for p in (table.catalog, table.db, temp_marked_name(table)) if p]
+    if not raw:
+        return ""
+    parts = [restore_jinja_dots(p) for p in raw]
+    if "{{" in parts[-1]:
+        return ".".join(parts)
+    qualifiers = [
+        restored
+        for encoded, restored in zip(raw[:-1], parts[:-1], strict=True)
+        if "{{" not in encoded or JINJA_DOT_SENTINEL in encoded
+    ]
+    return ".".join([*qualifiers, parts[-1]])
+
+
+def qualifier_is_quoted(node: exp.Expression) -> bool:
+    """True when the node's table qualifier was written quoted.
+
+    Postgres treats "Q" and q as different identifiers; a quoted reference
+    may only match an alias exactly, while an unquoted one folds case
+    (the cycle-6 review)."""
+    ident = node.args.get("table")
+    return bool(getattr(ident, "quoted", False))
+
+
+def alias_is_foldable(aliased: exp.Expression) -> bool:
+    """True when the node's alias can be matched case-insensitively: written
+    unquoted, or quoted but already lowercase."""
+    ident = getattr(aliased.args.get("alias"), "this", None)
+    alias = getattr(aliased, "alias", "") or ""
+    return not getattr(ident, "quoted", False) or alias == alias.lower()
+
+
+def owning_select(node: exp.Expression) -> exp.Expression | None:
+    """The nearest enclosing SELECT, or None at the statement root."""
+    parent = node.parent
+    while parent is not None and not isinstance(parent, exp.Select):
+        parent = parent.parent
+    return parent
+
+
+def nested_scope_sole_table(col: exp.Column, outer: exp.Expression) -> str | None:
+    """For a column inside a subselect below outer: the one relation its own
+    FROM names, "" when its scope has none or several, None when the column
+    belongs to outer itself (or has no FROM, i.e. is correlated to outer).
+
+    An unqualified column resolves in ITS select's scope. Anchoring
+    `(select max(payload) from source_rows s where ...)` to the outer sole
+    table claimed the outer table wrote payload (the review of PR #28)."""
+    owner = owning_select(col)
+    if owner is None or owner is outer:
+        return None
+    from_clause = owner.args.get("from_") or owner.args.get("from")
+    if from_clause is None:
+        return None
+    tables = [t for t in from_clause.find_all(exp.Table) if owning_select(t) is owner]
+    for join in owner.args.get("joins") or []:
+        if isinstance(join.this, exp.Table):
+            tables.append(join.this)
+    if len(tables) != 1:
+        return ""
+    return qualified_table_name(tables[0])
+
+
+def unwrap_select(node: exp.Expression | None) -> exp.Expression | None:
+    """Peel Subquery/Paren wrappers off a CTE or derived-table body.
+
+    dbt macros that emit '(select ...)' produce WITH c AS ((select ...)):
+    the same derivation one wrapper deeper. Every consumer that guards on
+    isinstance(body, Select) silently dropped the whole CTE for that shape
+    (make-open-data, holdout round 2)."""
+    while isinstance(node, (exp.Subquery, exp.Paren)):
+        node = node.this
+    return node
+
+
+def under_subquery_where(col: exp.Expression, root: exp.Expression) -> bool:
+    """True when col sits in a nested SELECT's WHERE, JOIN ON, or GROUP BY
+    below root.
+
+    Such a column selects, matches, or groups rows inside the subquery; it
+    never feeds the produced value, so it must not surface as a value
+    source. The exception is EXISTS: there the WHERE is the value, so it
+    stays.
+    """
+    prev: exp.Expression = col
+    node = col.parent
+    while node is not None and node is not root:
+        if isinstance(node, exp.Group) and isinstance(node.parent, exp.Select):
+            return True
+        if isinstance(node, exp.Where) and isinstance(node.parent, exp.Select):
+            outer = node.parent.parent
+            while isinstance(outer, (exp.Subquery, exp.Paren)):
+                outer = outer.parent
+            if not isinstance(outer, exp.Exists):
+                return True
+        if isinstance(node, exp.Join) and prev is node.args.get("on"):
+            return True
+        prev = node
+        node = node.parent
+    return False
+
+
+def in_window_ordering(col: exp.Expression, root: exp.Expression) -> bool:
+    """True when col sits in a window's PARTITION BY or ORDER BY below root.
+
+    `lag(mrr) over (partition by customer_id order by date_month)` produces a
+    value made of mrr alone. The other two decide which rows the frame spans
+    and in what order, which is the same C_ref role WHERE and JOIN ON play, so
+    they are collected as window keys instead of value sources. A column inside
+    the function's own arguments is untouched.
+    """
+    prev: exp.Expression = col
+    node = col.parent
+    while node is not None:
+        if isinstance(node, exp.Window):
+            if prev is node.args.get("order"):
+                return True
+            if any(prev is part for part in (node.args.get("partition_by") or [])):
+                return True
+        if node is root:
+            # root itself can be the window (`select lag(x) over (...)` with no
+            # wrapping expression), so it is tested before the walk stops
+            break
+        prev = node
+        node = node.parent
+    return False
+
+
+def in_selector_argument(col: exp.Expression, root: exp.Expression) -> bool:
+    """True when col sits in the selector argument of an arg_max/arg_min below root.
+
+    `arg_max(stage_key, stage_rank)` produces a value made of stage_key alone.
+    The selector only picks the row, the same C_ref role a window's ORDER BY
+    plays, so it is collected as a window key instead of a value source. A
+    column inside the value argument is untouched, even nested. duckdb's
+    3-arg form puts the result count in a third argument; a column there
+    also frames the result rather than feeding it.
+    """
+    prev: exp.Expression = col
+    node = col.parent
+    while node is not None:
+        if isinstance(node, (exp.ArgMax, exp.ArgMin)) and prev is not node.this:
+            return True
+        if node is root:
+            break
+        prev = node
+        node = node.parent
+    return False
+
+
+def register_subquery_from_aliases(
+    selects: list[exp.Expression], alias_map: dict[str, str]
+) -> None:
+    """Add FROM aliases of selects nested inside select items to alias_map.
+
+    The outer FROM sweep never sees a scalar subquery's own FROM, so its
+    projected column (f.title) would otherwise read as a struct root on a
+    phantom relation. Outer aliases win on collision. Qualifiers are kept in
+    the value for the same reason as scope.register_table: stripping them
+    lets a model named after the table it wraps swallow the reference.
+    """
+    for item in selects:
+        for sub in item.find_all(exp.Select):
+            sub_from = sub.args.get("from_") or sub.args.get("from")
+            if sub_from is None:
+                continue
+            for table in sub_from.find_all(exp.Table):
+                if table.name:
+                    alias_map.setdefault(table.alias or table.name, qualified_table_name(table))
+
+
+def extract_array_source(source_expr: exp.Expression) -> dict[str, Any] | None:
+    """Extract source table and column from array expansion expressions.
+
+    Handles patterns like:
+    - FLATTEN(orders.items) -> {source_table: "orders", source_column: "items"}
+    - UNNEST(arr) -> {source_table: "", source_column: "arr"}
+    - FLATTEN(input => t.data:items) -> {source_table: "t", source_column: "data", json_path: "items"}
+
+    Returns:
+        Dict with source_table, source_column, and optional json_path,
+        or None if cannot extract source.
+    """
+    if source_expr is None:
+        return None
+
+    if isinstance(source_expr, exp.Column):
+        info = {
+            "source_table": source_expr.table or "",
+            "source_column": source_expr.name or "",
+        }
+        parts = [p.name for p in source_expr.parts if getattr(p, "name", "")]
+        if len(parts) > 2:
+            # a.b.c is a struct path, not proof that b is a table: which
+            # identifier is the root column depends on what a resolves to,
+            # and only the scope knows its aliases (crux
+            # UNNEST(first_contentful_paint.histogram.bin), holdout round 4)
+            info["struct_parts"] = parts
+        return info
+
+    # data:items (snowflake) and data['items'] both parse as Bracket/Dot
+    if isinstance(source_expr, (exp.Bracket, exp.Dot)):
+        base = source_expr
+        json_path_parts = []
+        while isinstance(base, (exp.Bracket, exp.Dot)):
+            if isinstance(base, exp.Bracket) and base.expressions:
+                key = base.expressions[0]
+                if hasattr(key, "this"):
+                    json_path_parts.insert(0, str(key.this))
+            elif isinstance(base, exp.Dot) and hasattr(base, "expression"):
+                json_path_parts.insert(
+                    0,
+                    base.expression.name
+                    if hasattr(base.expression, "name")
+                    else str(base.expression),
+                )
+            base = base.this
+
+        if isinstance(base, exp.Column):
+            result = {
+                "source_table": base.table or "",
+                "source_column": base.name or "",
+            }
+            if json_path_parts:
+                result["json_path"] = ".".join(json_path_parts)
+            return result
+
+    if isinstance(source_expr, exp.JSONExtract):
+        base_col = source_expr.this
+        if isinstance(base_col, exp.Column):
+            result = {
+                "source_table": base_col.table or "",
+                "source_column": base_col.name or "",
+            }
+            if source_expr.expression:
+                path_expr = source_expr.expression
+                if hasattr(path_expr, "this"):
+                    result["json_path"] = str(path_expr.this).strip("$.")
+            return result
+
+    for json_type in (exp.JSONExtract, exp.JSONExtractScalar):
+        if (
+            isinstance(source_expr, json_type)
+            and hasattr(source_expr, "this")
+            and isinstance(source_expr.this, exp.Column)
+        ):
+            col = source_expr.this
+            return {
+                "source_table": col.table or "",
+                "source_column": col.name or "",
+                "json_path": str(source_expr.expression)
+                if hasattr(source_expr, "expression")
+                else "",
+            }
+
+    # An ARRAY of named STRUCTs is a melt: each element field is built from
+    # exactly the expressions aliased AS that field, so a read of
+    # element.<field> must resolve to those and never to sibling fields
+    # (rj_smtr integracao, round 11: 55 extra sources per case). The
+    # every-column fallback below stays for whole-element reads. Nested
+    # struct fields register under their dotted path too (nested.x), and a
+    # Cast(Struct) element unwraps to its struct (cycle-12, F15/F18).
+    if isinstance(source_expr, exp.Array) and source_expr.expressions:
+        fields: dict[str, list[dict[str, str]]] = {}
+        all_structs = True
+
+        def collect_fields(prefix: str, struct: exp.Struct) -> None:
+            for item in struct.expressions:
+                if isinstance(item, exp.PropertyEQ):
+                    fname, value = item.name, item.expression
+                elif isinstance(item, exp.Alias):
+                    fname, value = item.alias, item.this
+                else:
+                    continue
+                if not fname or value is None:
+                    continue
+                while isinstance(value, exp.Cast):
+                    value = value.this
+                path = f"{prefix}{fname}".lower()
+                bucket = fields.setdefault(path, [])
+                for col in value.find_all(exp.Column):
+                    src = {"source_table": col.table or "", "source_column": col.name or ""}
+                    if src["source_column"] and src not in bucket:
+                        bucket.append(src)
+                if isinstance(value, exp.Struct):
+                    collect_fields(f"{path}.", value)
+
+        for element in source_expr.expressions:
+            while isinstance(element, exp.Cast):
+                element = element.this
+            if not isinstance(element, exp.Struct):
+                all_structs = False
+                break
+            collect_fields("", element)
+        if all_structs and fields:
+            result = _array_fallback_sources(source_expr)
+            if result is None:
+                # literal-only named structs: the alias still owns the field
+                # names, and registering nothing let element reads fabricate
+                # a struct guess on the outer relation (cycle-12, F17)
+                result = {"source_table": "", "source_column": ""}
+            result["field_sources"] = fields
+            return result
+
+    # Fallback: a computed array expression (GENERATE_DATE_ARRAY(a, b), ...)
+    # contributes every column it reads; the first is the primary, the rest
+    # ride along as extra_columns.
+    return _array_fallback_sources(source_expr)
+
+
+def _array_fallback_sources(source_expr: exp.Expression) -> dict[str, Any] | None:
+    cols = list(source_expr.find_all(exp.Column))
+    if cols:
+        result = {
+            "source_table": cols[0].table or "",
+            "source_column": cols[0].name or "",
+        }
+        seen = {(result["source_table"], result["source_column"])}
+        extras = []
+        for col in cols[1:]:
+            key = (col.table or "", col.name or "")
+            if key[1] and key not in seen:
+                seen.add(key)
+                extras.append({"source_table": key[0], "source_column": key[1]})
+        if extras:
+            result["extra_columns"] = extras
+        return result
+
+    return None
+
+
+def resolve_expansion_extras(
+    info: dict[str, Any],
+    alias_map: dict[str, str],
+    all_tables: list[str],
+) -> list[dict[str, str]]:
+    """Resolve extra_columns of a computed array expression through the
+    select's alias map, like the primary source column."""
+    extras = []
+    for extra in info.get("extra_columns", []):
+        src_table = extra.get("source_table", "")
+        resolved = alias_map.get(src_table, src_table)
+        if not resolved:
+            real = [t for t in all_tables if not t.startswith("(")]
+            if len(real) == 1:
+                resolved = real[0]
+        extras.append({"source_table": resolved, "source_column": extra.get("source_column", "")})
+    return extras
+
+
+def resolve_field_sources(
+    info: dict[str, Any],
+    alias_map: dict[str, str],
+    all_tables: list[str],
+) -> dict[str, list[dict[str, str]]] | None:
+    """The array-of-structs field map with each source resolved through the
+    select's alias map, or None when the expansion carries no field map."""
+    fields = info.get("field_sources")
+    if not fields:
+        return None
+    return {
+        fname: resolve_expansion_extras({"extra_columns": srcs}, alias_map, all_tables)
+        for fname, srcs in fields.items()
+    }
+
+
+def field_selective_reads(entry: dict[str, Any], field_name: str) -> list[dict[str, str]] | None:
+    """Sources for a read of one named STRUCT field through an
+    array-of-structs expansion. None when the entry has no field map or the
+    read is not one of the declared field names (callers fall back to the
+    every-column behavior rather than guessing)."""
+    fields = entry.get("field_sources")
+    if not fields or not field_name:
+        return None
+    return fields.get(field_name.lower())
+
+
+def expansion_field_reads(
+    entry: dict[str, Any], col: exp.Column, column: str, field_path: str | None = None
+) -> list[dict[str, str]] | None:
+    """field_selective_reads by the resolved column name, or by the Dot
+    field when qualify() rewrote the element read into alias.element.field
+    (Column(_1.im) wrapped in Dot(data_transacao)).
+
+    A remaining field path is consumed first: im.nested.x looks up
+    nested.x before falling back to the whole nested subtree (cycle-12,
+    F15)."""
+    if field_path:
+        deep = field_selective_reads(entry, f"{column}.{field_path}")
+        if deep is not None:
+            return deep
+    selective = field_selective_reads(entry, column)
+    if selective is None:
+        parent = col.parent
+        if isinstance(parent, exp.Dot) and parent.this is col:
+            field = getattr(parent.expression, "name", "")
+            if field:
+                selective = field_selective_reads(entry, field)
+    return selective
+
+
+def collect_unnest_expansions(
+    select_node: exp.Expression,
+    alias_map: dict[str, str],
+    all_tables: list[str],
+) -> dict[str, dict[str, Any]]:
+    """UNNEST element names in this select's own FROM scope -> array root.
+
+    Keys are every name a reference could use for the expanded element: the
+    table alias, alias columns (including sqlglot's synthetic _0-style names
+    that qualify() invents), or '__anonymous_unnest__'. UNNESTs belonging to
+    nested subqueries are excluded; their scope is their own select.
+    """
+    expansions: dict[str, dict[str, Any]] = {}
+    # a set-returning function in table position (CROSS JOIN
+    # jsonb_array_elements_text(roles) AS role, no LATERAL keyword) parses
+    # as Table(this=Func); its alias is an expansion of the argument, not a
+    # relation (kingfisher-summarize, holdout round 7)
+    for table in select_node.find_all(exp.Table):
+        if owning_select(table) is not select_node:
+            continue
+        if table_function_kind(table) != "srf":
+            continue
+        func = table.this
+        args = list(getattr(func, "expressions", None) or [])
+        if not args and isinstance(func.args.get("this"), exp.Expression):
+            args = [func.args["this"]]
+        if not args:
+            continue
+        info = extract_array_source(args[0])
+        if not info or not info.get("source_column"):
+            continue
+        src_table = info.get("source_table", "")
+        resolved = alias_map.get(src_table, src_table)
+        if not resolved:
+            real = [t for t in all_tables if t and not t.startswith("(")]
+            if len(real) == 1:
+                resolved = real[0]
+        entry: dict[str, Any] = {
+            "source_table": resolved,
+            "source_column": info["source_column"],
+            "expansion_type": "TABLE_FUNCTION",
+        }
+        # every argument counts: regexp_split_to_table(body, delimiter)
+        # reads both (the cycle-8 review)
+        extra_args = []
+        for arg in args[1:]:
+            extra_info = extract_array_source(arg)
+            if extra_info and extra_info.get("source_column"):
+                extra_args.append(
+                    {
+                        "source_table": extra_info.get("source_table", ""),
+                        "source_column": extra_info["source_column"],
+                    }
+                )
+        if extra_args:
+            entry["extra_columns"] = resolve_expansion_extras(
+                {"extra_columns": extra_args}, alias_map, all_tables
+            )
+        names: list[str] = []
+        table_alias = table.args.get("alias")
+        if table_alias is not None:
+            if table_alias.this is not None:
+                names.append(table_alias.this.name)
+            names.extend(c.name for c in table_alias.columns or [])
+        for name in names:
+            expansions.setdefault(name, entry)
+    # LATERAL FLATTEN/EXPLODE joined into this select (snowflake's
+    # `, lateral flatten(input => x) dep` parses as Lateral(Explode)):
+    # the statement-level scope registers it, but a CTE body's element
+    # reads went through this map only, so `dep.value` degraded to a
+    # struct guess on the sole relation and the flatten never composed
+    # with set-op branch merging (dbt_artifacts dim_dbt__lineage_edges,
+    # holdout round 8).
+    explode_types: tuple[type, ...] = (exp.Explode,)
+    for extra in ("ExplodeOuter", "Inline"):
+        if hasattr(exp, extra):
+            explode_types = (*explode_types, getattr(exp, extra))
+    for lateral in select_node.find_all(exp.Lateral):
+        if owning_select(lateral) is not select_node:
+            continue
+        inner = lateral.this
+        if not isinstance(inner, explode_types) or inner.this is None:
+            continue
+        info = extract_array_source(inner.this)
+        if not info or not info.get("source_column"):
+            continue
+        src_table = info.get("source_table", "")
+        prior = expansions.get(src_table) or (
+            expansions.get(info["source_column"]) if not src_table else None
+        )
+        if prior is not None and prior.get("source_column"):
+            # chained flatten: the input is an earlier expansion's element,
+            # so the true source is that expansion's own array root
+            # (cycle-9 review, F4)
+            path_bits = [p for p in (prior.get("json_path"), info.get("json_path")) if p]
+            entry: dict[str, Any] = {
+                "source_table": prior.get("source_table", ""),
+                "source_column": prior["source_column"],
+                "expansion_type": "FLATTEN",
+            }
+            if path_bits:
+                entry["json_path"] = ".".join(path_bits)
+            if prior.get("extra_columns"):
+                entry["extra_columns"] = [dict(e) for e in prior["extra_columns"]]
+        else:
+            resolved = alias_map.get(src_table, src_table)
+            if not resolved:
+                real = [t for t in all_tables if t and not t.startswith("(")]
+                if len(real) == 1:
+                    resolved = real[0]
+            entry = {
+                "source_table": resolved,
+                "source_column": info["source_column"],
+                "expansion_type": "FLATTEN",
+            }
+            if info.get("json_path"):
+                entry["json_path"] = info["json_path"]
+            extras = resolve_expansion_extras(info, alias_map, all_tables)
+            if extras:
+                entry["extra_columns"] = extras
+        names: list[str] = []
+        alias_node = lateral.args.get("alias")
+        if alias_node is not None:
+            if alias_node.this is not None:
+                names.append(alias_node.this.name)
+            names.extend(c.name for c in alias_node.columns or [])
+        for name in names:
+            expansions.setdefault(name, entry)
+    for unnest in select_node.find_all(exp.Unnest):
+        if owning_select(unnest) is not select_node or not unnest.expressions:
+            continue
+        info = extract_array_source(unnest.expressions[0])
+        # a literal-only named-struct array reads no outer column but still
+        # owns its aliases; dropping it fabricated struct guesses (F17)
+        if not info or not (info.get("source_column") or info.get("field_sources")):
+            continue
+        src_table = info.get("source_table", "")
+        resolved = alias_map.get(src_table, src_table)
+        if not resolved and info.get("source_column"):
+            real = [t for t in all_tables if not t.startswith("(")]
+            if len(real) == 1:
+                resolved = real[0]
+        entry: dict[str, Any] = {
+            "source_table": resolved,
+            "source_column": info["source_column"],
+            "expansion_type": "UNNEST",
+        }
+        extras = resolve_expansion_extras(info, alias_map, all_tables)
+        if extras:
+            entry["extra_columns"] = extras
+        field_map = resolve_field_sources(info, alias_map, all_tables)
+        if field_map:
+            entry["field_sources"] = field_map
+        names: list[str] = []
+        table_alias = unnest.args.get("alias")
+        if table_alias is not None:
+            if table_alias.this is not None:
+                names.append(table_alias.this.name)
+            names.extend(c.name for c in table_alias.columns or [])
+        if names:
+            for name in names:
+                expansions.setdefault(name, entry)
+        else:
+            expansions.setdefault("__anonymous_unnest__", entry)
+    return expansions
+
+
+def left_join_anchor(select_node: exp.Expression) -> str:
+    """The FROM table of a lookup-shaped scope: exactly one FROM table and
+    every join this select owns is a LEFT JOIN onto it, so unqualified reads
+    anchor to the table the joins hang off. Returns '' when the shape does
+    not hold."""
+    from_clause = select_node.args.get("from_") or select_node.args.get("from")
+    if from_clause is None or not isinstance(from_clause.this, exp.Table):
+        return ""
+    joins = [j for j in select_node.find_all(exp.Join) if owning_select(j) is select_node]
+    if joins and all(j.side == "LEFT" for j in joins):
+        return from_clause.this.name or ""
+    return ""
+
+
+def scoped_unnest_entry(
+    col: exp.Column,
+    root: exp.Expression,
+    alias_map: dict[str, str],
+    all_tables: list[str],
+) -> dict[str, Any] | None:
+    """The UNNEST owning the column's own subquery scope below root,
+    innermost first. A select-item subquery's UNNEST anchors its own
+    element reads (including qualify()'s synthetic _0 alias) but never
+    sibling items."""
+    node = col.parent
+    while node is not None and node is not root:
+        if isinstance(node, exp.Select):
+            scoped = collect_unnest_expansions(node, alias_map, all_tables)
+            if scoped:
+                lowered = {k.lower(): v for k, v in scoped.items()}
+                leading = column_parts(col)[0].lower()
+                return (
+                    lowered.get(leading)
+                    or lowered.get("__anonymous_unnest__")
+                    or next(iter(scoped.values()))
+                )
+        node = node.parent
+    return None