aetherdialect 0.1.0__py3-none-any.whl

text2sql/intent_resolve.py

@@ -0,0 +1,1292 @@
+"""Column resolution, normalization, and grain enforcement for intent post-processing.
+
+Resolves bare column names to source tables or CTE steps via resolve_column_map and resolve_cte_column_maps, normalizes filter and having operators to canonical forms, deduplicates conditions, and sorts select, order, filter, and having clauses by structural keys.
+
+Enforces grain consistency between scalar, grouped, and row_level settings versus aggregation and GROUP BY, validates tables and columns against the schema, applies algebraic simplification such as constant folding and like-term combining to all expressions, and normalizes CTE names and COUNT(1) to COUNT(*).
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import replace
+
+from .config import REVERSE_OP_MAP, normalize_value_type
+from .contracts_base import SchemaGraph
+from .contracts_core import (
+    ExprValue,
+    FilterParam,
+    HavingParam,
+    MulGroup,
+    NormalizedExpr,
+    OrderByCol,
+    RuntimeCteStep,
+    RuntimeIntent,
+    SelectCol,
+)
+from .core_utils import debug, normalize_op
+from .intent_expr import extract_columns_from_expr, replace_refs_in_expr
+from .intent_repair import best_descriptive_column
+from .sql_gen import _render_expr_sql
+
+
+def normalize_count_star(intent: RuntimeIntent) -> RuntimeIntent:
+    """Convert COUNT(1) references to COUNT(*) throughout an intent for consistency.
+
+    Args:
+
+        intent: RuntimeIntent to normalize.
+
+    Returns:
+
+        New RuntimeIntent with COUNT(1) replaced by COUNT(*) in all expressions.
+    """
+
+    def _fix_count(term: str) -> str:
+        if term.upper() == "COUNT(1)":
+            return "COUNT(*)"
+        return term
+
+    def _fix_filter_list(params):
+        return [
+            replace(
+                fp,
+                left_expr=replace_refs_in_expr(fp.left_expr, _fix_count),
+                right_expr=(replace_refs_in_expr(fp.right_expr, _fix_count) if fp.right_expr else None),
+            )
+            for fp in params
+        ]
+
+    new_select_cols = [replace(sc, expr=replace_refs_in_expr(sc.expr, _fix_count)) for sc in (intent.select_cols or [])]
+    new_order_by_cols = [
+        replace(obc, expr=replace_refs_in_expr(obc.expr, _fix_count)) for obc in (intent.order_by_cols or [])
+    ]
+    new_filters = _fix_filter_list(intent.filters_param or [])
+    new_having = _fix_filter_list(intent.having_param or [])
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_sc = [replace(sc, expr=replace_refs_in_expr(sc.expr, _fix_count)) for sc in (cte.select_cols or [])]
+        cte_obc = [replace(obc, expr=replace_refs_in_expr(obc.expr, _fix_count)) for obc in (cte.order_by_cols or [])]
+        cte_fp = _fix_filter_list(cte.filters_param or [])
+        cte_hp = _fix_filter_list(cte.having_param or [])
+        new_cte_steps.append(
+            replace(
+                cte,
+                select_cols=cte_sc,
+                order_by_cols=cte_obc,
+                filters_param=cte_fp,
+                having_param=cte_hp,
+            )
+        )
+    return replace(
+        intent,
+        select_cols=new_select_cols,
+        order_by_cols=new_order_by_cols,
+        filters_param=new_filters,
+        having_param=new_having,
+        cte_steps=new_cte_steps,
+    )
+
+
+def sort_select_cols(cols: list[SelectCol]) -> list[SelectCol]:
+    """Sort select columns so non-aggregated expressions come before aggregated ones and ties are broken by expression signature.
+
+    Args:
+
+        cols: List of SelectCol objects to sort.
+
+    Returns:
+
+        Sorted list of SelectCol objects.
+    """
+
+    def key_fn(sc: SelectCol) -> tuple[int, str]:
+        return (1 if sc.is_aggregated else 0, sc.signature_key)
+
+    return sorted(cols, key=key_fn)
+
+
+def sort_order_by_cols(cols: list[OrderByCol]) -> list[OrderByCol]:
+    """Sort order-by columns so non-aggregated expressions come before aggregated ones and ties are broken by expression signature.
+
+    Args:
+
+        cols: List of OrderByCol objects to sort.
+
+    Returns:
+
+        Sorted list of OrderByCol objects.
+    """
+
+    def key_fn(obc: OrderByCol) -> tuple[int, str]:
+        return (1 if obc.is_aggregated else 0, obc.signature_key)
+
+    return sorted(cols, key=key_fn)
+
+
+def _filter_structural_key(fp: FilterParam) -> tuple[str, str, str, str]:
+    """Return the structural sort key for a single FilterParam.
+
+    Args:
+
+        fp: FilterParam to compute the key for.
+
+    Returns:
+
+        Tuple of (left_sig, op, right_sig, value_type) with all components lowercased.
+    """
+    left = fp.left_expr.signature_key if fp.left_expr else ""
+    right = fp.right_expr.signature_key if fp.right_expr else ""
+    return (left, fp.op.lower(), right, fp.value_type.lower())
+
+
+def _having_structural_key(hp: HavingParam) -> tuple[str, str, str, str]:
+    """Return the structural sort key for a single HavingParam.
+
+    Args:
+
+        hp: HavingParam to compute the key for.
+
+    Returns:
+
+        Tuple of (left_sig, op, right_sig, value_type) with all components lowercased.
+    """
+    left = hp.left_expr.signature_key if hp.left_expr else ""
+    right = hp.right_expr.signature_key if hp.right_expr else ""
+    return (left, hp.op.lower(), right, hp.value_type.lower())
+
+
+def _canonicalize_condition_order(
+    items: list,
+    structural_key_fn: Callable,
+) -> list:
+    """Canonicalize a flat condition list by parsing the positional bool_op operators into a precedence tree (AND binds tighter than OR), sorting at each level using the commutativity of AND/OR, and re-serializing with adjusted bool_ops.
+
+    The last element's bool_op is treated as the inter-group connector and is preserved on whichever element ends up last after sorting.
+
+    Works for both FilterParam and HavingParam since they share the same bool_op / filter_group field layout.
+
+    Args:
+
+        items: List of FilterParam or HavingParam objects.
+
+        structural_key_fn: Callable that returns a sortable tuple for one item.
+
+    Returns:
+
+        New list with the same elements in canonical order and bool_ops reassigned.
+    """
+    if len(items) <= 1:
+        return list(items)
+    inter_connector = items[-1].bool_op
+    ops: list[str] = [it.bool_op for it in items[:-1]]
+    chunks: list[list] = []
+    current_chunk: list = [items[0]]
+    for i, op in enumerate(ops):
+        if op == "OR":
+            chunks.append(current_chunk)
+            current_chunk = [items[i + 1]]
+        else:
+            current_chunk.append(items[i + 1])
+    chunks.append(current_chunk)
+    sorted_chunks: list[list] = []
+    for chunk in chunks:
+        sorted_chunks.append(sorted(chunk, key=structural_key_fn))
+    sorted_chunks.sort(key=lambda ch: structural_key_fn(ch[0]))
+    result: list = []
+    for ci, chunk in enumerate(sorted_chunks):
+        for fi, item in enumerate(chunk):
+            is_last_in_chunk = fi == len(chunk) - 1
+            is_last_chunk = ci == len(sorted_chunks) - 1
+            if is_last_chunk and is_last_in_chunk:
+                new_bool_op = inter_connector
+            elif is_last_in_chunk:
+                new_bool_op = "OR"
+            else:
+                new_bool_op = "AND"
+            result.append(replace(item, bool_op=new_bool_op))
+    return result
+
+
+def sort_filters(filters: list[FilterParam]) -> list[FilterParam]:
+    """Sort filter parameters using precedence-aware group canonicalization.
+
+    Partitions filters by filter_group, canonicalizes order within each group using the precedence tree algorithm (AND binds tighter than OR, both are commutative), then sorts the groups themselves at the inter-group level using the same algorithm on group-representative elements.
+
+    Args:
+
+        filters: List of FilterParam objects to sort.
+
+    Returns:
+
+        Sorted list of FilterParam objects with bool_ops adjusted to reflect the new canonical positions.
+    """
+    if not filters:
+        return []
+    buckets: dict[int | None, list[FilterParam]] = defaultdict(list)
+    for fp in filters:
+        buckets[fp.filter_group].append(fp)
+    canonicalized_groups: list[tuple[int | None, list[FilterParam]]] = []
+    for gid, group in buckets.items():
+        canonicalized_groups.append((gid, _canonicalize_condition_order(group, _filter_structural_key)))
+    if len(canonicalized_groups) == 1:
+        return canonicalized_groups[0][1]
+    representatives: list[FilterParam] = []
+    group_map: dict[int, tuple[int | None, list[FilterParam]]] = {}
+    for idx, (gid, group) in enumerate(canonicalized_groups):
+        rep = group[-1]
+        representatives.append(replace(rep, filter_group=idx))
+        group_map[idx] = (gid, group)
+    sorted_reps = _canonicalize_condition_order(representatives, _filter_structural_key)
+    result: list[FilterParam] = []
+    for _ri, rep in enumerate(sorted_reps):
+        proxy_id = rep.filter_group
+        assert isinstance(proxy_id, int)
+        real_gid, group = group_map[proxy_id]
+        inter_connector = rep.bool_op
+        for fi, fp in enumerate(group):
+            if fi == len(group) - 1:
+                result.append(replace(fp, bool_op=inter_connector, filter_group=real_gid))
+            else:
+                result.append(replace(fp, filter_group=real_gid))
+    return result
+
+
+def sort_having(having: list[HavingParam]) -> list[HavingParam]:
+    """Sort having parameters using precedence-aware group canonicalization.
+
+    Partitions having conditions by filter_group, canonicalizes order within each group using the precedence tree algorithm, then sorts the groups at the inter-group level using the same algorithm.
+
+    Args:
+
+        having: List of HavingParam objects to sort.
+
+    Returns:
+
+        Sorted list of HavingParam objects with bool_ops adjusted to reflect the new canonical positions.
+    """
+    if not having:
+        return []
+    buckets: dict[int | None, list[HavingParam]] = defaultdict(list)
+    for hp in having:
+        buckets[hp.filter_group].append(hp)
+    canonicalized_groups: list[tuple[int | None, list[HavingParam]]] = []
+    for gid, group in buckets.items():
+        canonicalized_groups.append((gid, _canonicalize_condition_order(group, _having_structural_key)))
+    if len(canonicalized_groups) == 1:
+        return canonicalized_groups[0][1]
+    representatives: list[HavingParam] = []
+    group_map: dict[int, tuple[int | None, list[HavingParam]]] = {}
+    for idx, (gid, group) in enumerate(canonicalized_groups):
+        rep = group[-1]
+        representatives.append(replace(rep, filter_group=idx))
+        group_map[idx] = (gid, group)
+    sorted_reps = _canonicalize_condition_order(representatives, _having_structural_key)
+    result: list[HavingParam] = []
+    for _ri, rep in enumerate(sorted_reps):
+        proxy_id = rep.filter_group
+        assert isinstance(proxy_id, int)
+        real_gid, group = group_map[proxy_id]
+        inter_connector = rep.bool_op
+        for fi, hp in enumerate(group):
+            if fi == len(group) - 1:
+                result.append(replace(hp, bool_op=inter_connector, filter_group=real_gid))
+            else:
+                result.append(replace(hp, filter_group=real_gid))
+    return result
+
+
+def _is_cte_output_groupable(term: str, cte_steps: list[RuntimeCteStep]) -> bool:
+    """Return True if term references a CTE output column."""
+    if "." not in term:
+        return False
+    table_part, col_part = term.split(".", 1)
+    table_lower = table_part.strip().lower()
+    col_lower = col_part.strip().lower()
+    for cte in cte_steps or []:
+        if cte.cte_name.lower() == table_lower:
+            out_cols = cte.output_columns or []
+            return any(c.strip().lower() == col_lower for c in out_cols)
+    return False
+
+
+def enforce_grain_consistency(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Ensure GROUP BY grain matches select columns and augment with descriptive columns.
+
+    When group_by_cols is empty but select has mixed aggregated/non-aggregated columns, infers the group-by from groupable non-aggregated columns and for PK group-by columns auto-adds the best descriptive column to both select and group_by for readability.
+
+    Args:
+
+        intent: RuntimeIntent to enforce grain on.
+
+        schema_graph: SchemaGraph for column role lookups.
+
+    Returns:
+
+        Updated RuntimeIntent with grain set to 'grouped' when grouping is present.
+    """
+    group_by = list(intent.group_by_cols or [])
+    select_cols = list(intent.select_cols or [])
+    cte_steps = intent.cte_steps or []
+    if not group_by:
+        has_agg = any(sc.is_aggregated for sc in select_cols)
+        non_agg = [sc for sc in select_cols if not sc.is_aggregated]
+        if not (has_agg and non_agg):
+            return intent
+        groupable: list[NormalizedExpr] = []
+        for sc in non_agg:
+            term = sc.expr.primary_term
+            parts = term.split(".", 1) if "." in term else None
+            if not parts:
+                groupable.append(sc.expr)
+                continue
+            if _is_cte_output_groupable(term, cte_steps):
+                groupable.append(sc.expr)
+                continue
+            tbl_meta = schema_graph.tables.get(parts[0])
+            col_meta = tbl_meta.columns.get(parts[1]) if tbl_meta else None
+            if not col_meta or col_meta.is_groupable:
+                groupable.append(sc.expr)
+        group_by = sorted(groupable, key=lambda g: g.signature_key)
+        debug(
+            f"[intent_resolve.enforce_grain_consistency] inferred group_by from groupable non-agg cols: {[g.primary_term for g in group_by]}"
+        )
+    existing_terms = {sc.expr.primary_term for sc in select_cols}
+    gb_terms = {g.primary_term for g in group_by}
+    has_agg_check = any(sc.is_aggregated for sc in select_cols)
+    if has_agg_check and gb_terms:
+        for sc in select_cols:
+            if sc.is_aggregated:
+                continue
+            term = sc.expr.primary_term
+            if term in gb_terms:
+                continue
+            parts = term.split(".", 1) if "." in term else None
+            if not parts:
+                group_by.append(sc.expr)
+                gb_terms.add(term)
+                debug(f"[intent_resolve.enforce_grain_consistency] auto-added non-agg select col to group_by: {term}")
+                continue
+            if _is_cte_output_groupable(term, cte_steps):
+                group_by.append(sc.expr)
+                gb_terms.add(term)
+                debug(f"[intent_resolve.enforce_grain_consistency] auto-added CTE output col to group_by: {term}")
+                continue
+            tbl_meta = schema_graph.tables.get(parts[0])
+            col_meta = tbl_meta.columns.get(parts[1]) if tbl_meta else None
+            if not col_meta or col_meta.is_groupable:
+                group_by.append(sc.expr)
+                gb_terms.add(term)
+                debug(f"[intent_resolve.enforce_grain_consistency] auto-added non-agg select col to group_by: {term}")
+    intent_tables = set(intent.tables or [])
+    for gb_expr in list(group_by):
+        gb_col = gb_expr.primary_term
+        parts = gb_col.split(".", 1) if "." in gb_col else None
+        if not parts:
+            continue
+        tbl_meta = schema_graph.tables.get(parts[0])
+        col_meta = tbl_meta.columns.get(parts[1]) if tbl_meta else None
+        if not col_meta:
+            continue
+        if col_meta.is_primary_key:
+            desc = best_descriptive_column(parts[0], schema_graph, existing_terms | gb_terms)
+            if desc:
+                fq = f"{parts[0]}.{desc}"
+                group_by.append(NormalizedExpr.from_column(fq))
+                select_cols.append(SelectCol(expr=NormalizedExpr.from_column(fq)))
+                existing_terms.add(fq)
+                gb_terms.add(fq)
+                debug(f"[intent_resolve.enforce_grain_consistency] auto-added descriptive column {fq}")
+            continue
+        if col_meta.is_foreign_key:
+            for fk in tbl_meta.foreign_keys or []:
+                if parts[1] not in fk.src_cols:
+                    continue
+                if fk.dst_table not in intent_tables:
+                    continue
+                desc = best_descriptive_column(fk.dst_table, schema_graph, existing_terms | gb_terms)
+                if not desc:
+                    continue
+                fq = f"{fk.dst_table}.{desc}"
+                group_by.append(NormalizedExpr.from_column(fq))
+                select_cols.append(SelectCol(expr=NormalizedExpr.from_column(fq)))
+                existing_terms.add(fq)
+                gb_terms.add(fq)
+                debug(
+                    f"[intent_resolve.enforce_grain_consistency] auto-added FK descriptive column {fq} via {parts[0]}.{parts[1]}->{fk.dst_table}"
+                )
+    return replace(
+        intent,
+        group_by_cols=sorted(group_by, key=lambda g: g.signature_key),
+        select_cols=select_cols,
+        grain="grouped",
+    )
+
+
+def _cte_is_aggregated(cte: RuntimeCteStep) -> bool:
+    """Return True if the CTE is grouped or scalar by structure."""
+    has_agg = any(sc.is_aggregated for sc in (cte.select_cols or []))
+    if cte.group_by_cols:
+        return True
+    if has_agg:
+        return True
+    return False
+
+
+def force_main_grain_when_using_grouped_cte(intent: RuntimeIntent) -> RuntimeIntent:
+    """Promote main grain to grouped when it aggregates over a grouped CTE.
+
+    Only promotes when the main query itself contains aggregated
+    select columns, preventing false promotion when the main query
+    simply selects pre-aggregated CTE output without further
+    aggregation.
+
+    Args:
+
+        intent: RuntimeIntent with optional cte_steps and main tables.
+
+    Returns:
+
+        Updated RuntimeIntent with grain "grouped" when applicable.
+    """
+    if intent.grain != "row_level":
+        return intent
+    cte_steps = intent.cte_steps or []
+    if not cte_steps:
+        return intent
+    has_main_agg = any(
+        sc.is_aggregated for sc in (intent.select_cols or [])
+    )
+    if not has_main_agg:
+        return intent
+    main_tables = set(intent.tables or [])
+    aggregated_cte_names = {
+        cte.cte_name for cte in cte_steps if _cte_is_aggregated(cte)
+    }
+    if not main_tables.intersection(aggregated_cte_names):
+        return intent
+    return replace(intent, grain="grouped")
+
+
+def enforce_cte_grain_consistency(cte: RuntimeCteStep) -> RuntimeCteStep:
+    """Set grain on a CTE step based on its structural properties.
+
+    Sets grain to ``"grouped"`` when ``group_by_cols`` are present, or
+    ``"scalar"`` when the CTE contains aggregation in select columns
+    but no GROUP BY clause, indicating a single-row aggregate result.
+    Sorts group_by_cols by signature_key for consistency with main
+    intent.
+    """
+    has_agg = any(sc.is_aggregated for sc in (cte.select_cols or []))
+    if not cte.group_by_cols:
+        if has_agg and cte.grain != "scalar":
+            return replace(cte, grain="scalar")
+        return cte
+    sorted_gb = sorted(cte.group_by_cols, key=lambda g: g.signature_key)
+    return replace(cte, grain="grouped", group_by_cols=sorted_gb)
+
+
+def resolve_column_map(columns: list[str], schema_graph: SchemaGraph, tables: list[str]) -> dict[str, str]:
+    """Map bare or qualified column references to their source table names.
+
+    For qualified references (table.col), validates the table against the allowed list and for bare references resolves by scanning the column lists of all candidate tables while logging a debug message when a column is ambiguous across multiple tables.
+
+    Args:
+
+        columns: List of column reference strings (bare or table-qualified).
+
+        schema_graph: SchemaGraph containing table/column metadata.
+
+        tables: Allowed table names to resolve against.
+
+    Returns:
+
+        Dictionary mapping bare column name to its source table name.
+    """
+    column_map: dict[str, str] = {}
+    table_col_index: dict[str, set[str]] = {}
+    for tbl in tables:
+        if tbl not in schema_graph.tables:
+            continue
+        table_col_index[tbl] = {c.lower() for c in schema_graph.tables[tbl].columns}
+    for col in columns:
+        col_stripped = col.strip()
+        if "." in col_stripped:
+            tbl_ref, col_ref = col_stripped.split(".", 1)
+            col_ref_lower = col_ref.strip().lower()
+            tbl_ref_lower = tbl_ref.strip().lower()
+            for tbl in tables:
+                if (
+                    tbl.lower() == tbl_ref_lower or tbl.split(".")[-1].lower() == tbl_ref_lower
+                ) and col_ref_lower in table_col_index.get(tbl, set()):
+                    column_map[col_ref.strip()] = tbl
+                    break
+            continue
+        col_lower = col_stripped.lower()
+        candidates = [tbl for tbl in tables if col_lower in table_col_index.get(tbl, set())]
+        if len(candidates) == 1:
+            column_map[col_stripped] = candidates[0]
+        elif len(candidates) > 1:
+            column_map[col_stripped] = candidates[0]
+            debug(f"[intent_resolve.resolve_column_map] ambiguous column '{col}': {candidates}, using {candidates[0]}")
+    return column_map
+
+
+def resolve_cte_column_maps(cte_steps: list[RuntimeCteStep]) -> list[RuntimeCteStep]:
+    """Build a column_map for each CTE step, mapping bare column names to source CTE names.
+
+    Processes CTE steps in order so each step can reference output columns from prior steps and bare column names found in earlier CTE output lists are mapped to that CTE's name.
+
+    Args:
+
+        cte_steps: Ordered list of RuntimeCteStep objects.
+
+    Returns:
+
+        New list of RuntimeCteStep objects with column_map populated.
+    """
+    cte_output_cols: dict[str, set[str]] = {}
+    result = []
+    for cte in cte_steps:
+        cte_name = cte.cte_name
+        out_cols = set(cte.output_columns or [])
+        for sc in cte.select_cols or []:
+            col = sc.expr.primary_column
+            if col:
+                out_cols.add(col.split(".")[-1])
+        cte_output_cols[cte_name] = out_cols
+        available_sources: dict[str, str] = {}
+        for prev_cte_name, prev_cols in cte_output_cols.items():
+            if prev_cte_name == cte_name:
+                continue
+            for c in prev_cols:
+                available_sources[c.lower()] = prev_cte_name
+        cols_to_resolve: list[str] = []
+        for sc in cte.select_cols or []:
+            cols_to_resolve.extend(extract_columns_from_expr(sc.expr))
+        for obc in cte.order_by_cols or []:
+            cols_to_resolve.extend(extract_columns_from_expr(obc.expr))
+        for fp in cte.filters_param or []:
+            cols_to_resolve.extend(extract_columns_from_expr(fp.left_expr))
+            if fp.right_expr:
+                cols_to_resolve.extend(extract_columns_from_expr(fp.right_expr))
+        for hp in cte.having_param or []:
+            cols_to_resolve.extend(extract_columns_from_expr(hp.left_expr))
+            if hp.right_expr:
+                cols_to_resolve.extend(extract_columns_from_expr(hp.right_expr))
+        column_map: dict[str, str] = {}
+        for col in cols_to_resolve:
+            col_stripped = col.strip()
+            if "." in col_stripped:
+                bare = col_stripped.split(".", 1)[1].strip()
+                source = col_stripped.split(".", 1)[0].strip()
+                column_map[bare] = source
+            elif col_stripped.lower() in available_sources:
+                column_map[col_stripped] = available_sources[col_stripped.lower()]
+        updated_cte = replace(cte, column_map=column_map)
+        result.append(updated_cte)
+    return result
+
+
+def normalize_cte_names(intent: RuntimeIntent) -> RuntimeIntent:
+    """Rename all CTE steps to canonical names (cte1, cte2, ...) and update all references.
+
+    Replaces old CTE name occurrences in tables lists, expression terms, column maps, and output column names throughout both CTE steps and the main query.
+
+    Args:
+
+        intent: RuntimeIntent with CTE steps to normalize.
+
+    Returns:
+
+        New RuntimeIntent with CTE names and all cross-references updated.
+    """
+    cte_steps = intent.cte_steps or []
+    if not cte_steps:
+        return intent
+    old_to_new: dict[str, str] = {}
+    for i, cte in enumerate(cte_steps, start=1):
+        new_name = f"cte{i}"
+        old_to_new[cte.cte_name] = new_name
+
+    def replace_cte_refs(s: str) -> str:
+        for old, new in old_to_new.items():
+            pattern = re.compile(rf"\b{re.escape(old)}\b", re.IGNORECASE)
+            s = pattern.sub(new, s)
+        return s
+
+    def _update_expr(expr: NormalizedExpr) -> NormalizedExpr:
+        return replace_refs_in_expr(expr, replace_cte_refs)
+
+    new_cte_steps = []
+    for cte in cte_steps:
+        new_name = old_to_new[cte.cte_name]
+        new_tables = [replace_cte_refs(t) for t in (cte.tables or [])]
+        new_select_cols = [replace(sc, expr=_update_expr(sc.expr)) for sc in (cte.select_cols or [])]
+        new_group_by = [_update_expr(g) for g in (cte.group_by_cols or [])]
+        new_order_by = [replace(obc, expr=_update_expr(obc.expr)) for obc in (cte.order_by_cols or [])]
+        new_filters = []
+        for fp in cte.filters_param or []:
+            new_fp = replace(
+                fp,
+                left_expr=_update_expr(fp.left_expr),
+                right_expr=_update_expr(fp.right_expr) if fp.right_expr else None,
+            )
+            new_filters.append(new_fp)
+        new_having = []
+        for hp in cte.having_param or []:
+            new_hp = replace(
+                hp,
+                left_expr=_update_expr(hp.left_expr),
+                right_expr=_update_expr(hp.right_expr) if hp.right_expr else None,
+            )
+            new_having.append(new_hp)
+        new_column_map = {}
+        for k, v in (cte.column_map or {}).items():
+            new_column_map[replace_cte_refs(k)] = replace_cte_refs(v)
+        new_output_columns = [replace_cte_refs(oc) for oc in (cte.output_columns or [])]
+        new_ocm = {replace_cte_refs(k): v for k, v in (cte.output_column_metadata or {}).items()}
+        new_cte = replace(
+            cte,
+            cte_name=new_name,
+            tables=new_tables,
+            select_cols=new_select_cols,
+            group_by_cols=new_group_by,
+            order_by_cols=new_order_by,
+            filters_param=new_filters,
+            having_param=new_having,
+            column_map=new_column_map,
+            output_columns=new_output_columns,
+            output_column_metadata=new_ocm,
+        )
+        new_cte_steps.append(new_cte)
+
+    new_main_tables = [replace_cte_refs(t) for t in (intent.tables or [])]
+    new_main_select = [replace(sc, expr=_update_expr(sc.expr)) for sc in (intent.select_cols or [])]
+    new_main_group_by = [_update_expr(g) for g in (intent.group_by_cols or [])]
+    new_main_order_by = [replace(obc, expr=_update_expr(obc.expr)) for obc in (intent.order_by_cols or [])]
+    new_main_filters = []
+    for fp in intent.filters_param or []:
+        new_fp = replace(
+            fp,
+            left_expr=_update_expr(fp.left_expr),
+            right_expr=_update_expr(fp.right_expr) if fp.right_expr else None,
+        )
+        new_main_filters.append(new_fp)
+    new_main_having = []
+    for hp in intent.having_param or []:
+        new_hp = replace(
+            hp,
+            left_expr=_update_expr(hp.left_expr),
+            right_expr=_update_expr(hp.right_expr) if hp.right_expr else None,
+        )
+        new_main_having.append(new_hp)
+    new_main_column_map = {}
+    for k, v in (intent.column_map or {}).items():
+        new_main_column_map[replace_cte_refs(k)] = replace_cte_refs(v)
+    return replace(
+        intent,
+        tables=new_main_tables,
+        select_cols=new_main_select,
+        group_by_cols=new_main_group_by,
+        order_by_cols=new_main_order_by,
+        filters_param=new_main_filters,
+        having_param=new_main_having,
+        column_map=new_main_column_map,
+        cte_steps=new_cte_steps,
+    )
+
+
+def _normalize_expr_ref_for_alias(rendered: str) -> str:
+    """Normalize a rendered expression for alias-map matching.
+
+    Strips spaces inside comparison/operator tokens and normalizes
+    aggregation function casing so small formatting differences still match.
+    """
+    s = rendered.strip()
+    for op in (" >= ", " <= ", " != ", " = ", " > ", " < ", " + ", " - ", " * ", " / "):
+        s = s.replace(op, op.replace(" ", ""))
+    s = re.sub(r"\b(count|sum|avg|min|max)\s*\(", r"\1(", s, flags=re.IGNORECASE)
+    return s
+
+
+def _cte_output_alias_map(intent: RuntimeIntent) -> dict[str, str]:
+    """Build a map from CTE-qualified expression form to CTE-qualified output column name.
+
+    For each CTE step, each select expression is rendered; the key is cte_name.rendered_expr
+    and the value is cte_name.output_columns[i]. Also adds a stripped/normalized key so
+    small formatting changes (spaces in operators, function casing) still match.
+    """
+    alias_map: dict[str, str] = {}
+    for cte in intent.cte_steps or []:
+        output_cols = cte.output_columns or []
+        for i, sc in enumerate(cte.select_cols or []):
+            if i >= len(output_cols):
+                continue
+            rendered = _render_expr_sql(sc.expr)
+            from_ref = f"{cte.cte_name}.{rendered}"
+            to_ref = f"{cte.cte_name}.{output_cols[i]}"
+            if from_ref != to_ref:
+                alias_map[from_ref] = to_ref
+                stripped = _normalize_expr_ref_for_alias(rendered)
+                if stripped != rendered:
+                    alias_map[f"{cte.cte_name}.{stripped}"] = to_ref
+    return alias_map
+
+
+def rewrite_cte_output_refs_to_aliases(intent: RuntimeIntent) -> RuntimeIntent:
+    """Rewrite references to CTE outputs from expression form to output column alias.
+
+    After CTE names are normalized to cte1, cte2, references in the main query (e.g. cte1.COUNT(table_1.column_1))
+    are replaced with the deterministic output column name (e.g. cte1.count_column_1) so validation and SQL
+    generation see consistent column names.
+    """
+    alias_map = _cte_output_alias_map(intent)
+    if not alias_map:
+        return intent
+
+    def replacer(s: str) -> str:
+        return alias_map.get(s, s)
+
+    def _update_expr(expr: NormalizedExpr) -> NormalizedExpr:
+        return replace_refs_in_expr(expr, replacer)
+
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        new_select = [replace(sc, expr=_update_expr(sc.expr)) for sc in (cte.select_cols or [])]
+        new_group_by = [_update_expr(g) for g in (cte.group_by_cols or [])]
+        new_order_by = [replace(obc, expr=_update_expr(obc.expr)) for obc in (cte.order_by_cols or [])]
+        new_filters = [
+            replace(fp, left_expr=_update_expr(fp.left_expr), right_expr=_update_expr(fp.right_expr) if fp.right_expr else None)
+            for fp in (cte.filters_param or [])
+        ]
+        new_having = [
+            replace(hp, left_expr=_update_expr(hp.left_expr), right_expr=_update_expr(hp.right_expr) if hp.right_expr else None)
+            for hp in (cte.having_param or [])
+        ]
+        new_cte_steps.append(
+            replace(
+                cte,
+                select_cols=new_select,
+                group_by_cols=new_group_by,
+                order_by_cols=new_order_by,
+                filters_param=new_filters,
+                having_param=new_having,
+            )
+        )
+
+    new_main_select = [replace(sc, expr=_update_expr(sc.expr)) for sc in (intent.select_cols or [])]
+    new_main_group_by = [_update_expr(g) for g in (intent.group_by_cols or [])]
+    new_main_order_by = [replace(obc, expr=_update_expr(obc.expr)) for obc in (intent.order_by_cols or [])]
+    new_main_filters = [
+        replace(fp, left_expr=_update_expr(fp.left_expr), right_expr=_update_expr(fp.right_expr) if fp.right_expr else None)
+        for fp in (intent.filters_param or [])
+    ]
+    new_main_having = [
+        replace(hp, left_expr=_update_expr(hp.left_expr), right_expr=_update_expr(hp.right_expr) if hp.right_expr else None)
+        for hp in (intent.having_param or [])
+    ]
+    return replace(
+        intent,
+        select_cols=new_main_select,
+        group_by_cols=new_main_group_by,
+        order_by_cols=new_main_order_by,
+        filters_param=new_main_filters,
+        having_param=new_main_having,
+        cte_steps=new_cte_steps,
+    )
+
+
+def enforce_schema(intent: RuntimeIntent, schema_graph: SchemaGraph) -> tuple[RuntimeIntent, list[str]]:
+    """Validate intent table and column references against the schema graph.
+
+    Checks that every table referenced in the intent exists in the schema or is a CTE name and that every qualified column reference points to a known column.
+
+    Args:
+
+        intent: RuntimeIntent to validate.
+
+        schema_graph: SchemaGraph providing the authoritative table/column set.
+
+    Returns:
+
+        Tuple of (intent, errors) where errors is a list of human-readable violation strings and the intent is returned unchanged.
+    """
+    errors: list[str] = []
+    valid_tables = set(schema_graph.tables.keys())
+    cte_names = {cte.cte_name for cte in (intent.cte_steps or [])}
+    for tbl in intent.tables or []:
+        if tbl not in valid_tables and tbl not in cte_names:
+            errors.append(f"Unknown table: {tbl}")
+
+    def _check_expr_cols(exprs: list, label: str) -> None:
+        for item in exprs:
+            expr = item.expr if hasattr(item, "expr") else item
+            for col in extract_columns_from_expr(expr):
+                if "." in col:
+                    tbl_ref, col_ref = col.split(".", 1)
+                    if tbl_ref in valid_tables:
+                        tbl_meta = schema_graph.tables[tbl_ref]
+                        if col_ref not in tbl_meta.columns:
+                            errors.append(f"Unknown {label} column: {col}")
+
+    def _check_filter_cols(params: list, label: str) -> None:
+        for fp in params:
+            for col in extract_columns_from_expr(fp.left_expr):
+                if "." in col:
+                    tbl_ref, col_ref = col.split(".", 1)
+                    if tbl_ref in valid_tables:
+                        tbl_meta = schema_graph.tables[tbl_ref]
+                        if col_ref not in tbl_meta.columns:
+                            errors.append(f"Unknown {label} column: {col}")
+            if fp.right_expr:
+                for col in extract_columns_from_expr(fp.right_expr):
+                    if "." in col:
+                        tbl_ref, col_ref = col.split(".", 1)
+                        if tbl_ref in valid_tables:
+                            tbl_meta = schema_graph.tables[tbl_ref]
+                            if col_ref not in tbl_meta.columns:
+                                errors.append(f"Unknown {label} column: {col}")
+
+    def _check_bare_cols(cols: list, label: str) -> None:
+        for g in cols:
+            col = g.primary_term if hasattr(g, "primary_term") else str(g)
+            if "." in col:
+                tbl_ref, col_ref = col.split(".", 1)
+                if tbl_ref in valid_tables:
+                    tbl_meta = schema_graph.tables[tbl_ref]
+                    if col_ref not in tbl_meta.columns:
+                        errors.append(f"Unknown {label} column: {col}")
+
+    _check_expr_cols(intent.select_cols or [], "select")
+    _check_expr_cols(intent.order_by_cols or [], "order_by")
+    _check_filter_cols(intent.filters_param or [], "filter")
+    _check_filter_cols(intent.having_param or [], "having")
+    _check_bare_cols(intent.group_by_cols or [], "group_by")
+    for cte in intent.cte_steps or []:
+        ctx = f"CTE '{cte.cte_name}'"
+        for tbl in cte.tables or []:
+            if tbl not in valid_tables and tbl not in cte_names:
+                errors.append(f"{ctx} unknown table: {tbl}")
+        _check_expr_cols(cte.select_cols or [], f"{ctx} select")
+        _check_expr_cols(cte.order_by_cols or [], f"{ctx} order_by")
+        _check_filter_cols(cte.filters_param or [], f"{ctx} filter")
+        _check_filter_cols(cte.having_param or [], f"{ctx} having")
+        _check_bare_cols(cte.group_by_cols or [], f"{ctx} group_by")
+    if errors:
+        debug(f"[intent_resolve.enforce_schema] validation errors: {errors}")
+    return intent, errors
+
+
+def _simplify_expr(expr: NormalizedExpr) -> NormalizedExpr:
+    """Apply algebraic simplifications to a NormalizedExpr.
+
+    Performs constant folding that accumulates numeric literal terms, like-term combining that merges groups with identical structural keys, zero-coefficient elimination, negative coefficient normalization that moves negative-coeff add_groups to sub_groups, and coefficient-to-value collapse where groups with no operands become ExprValue offsets.
+
+    Args:
+
+        expr: NormalizedExpr to simplify.
+
+    Returns:
+
+        New NormalizedExpr in simplified canonical form.
+    """
+    add_groups: list[MulGroup] = []
+    sub_groups: list[MulGroup] = []
+    add_vals: list[ExprValue] = []
+    sub_vals: list[ExprValue] = []
+    parameterized_add: list[ExprValue] = []
+    parameterized_sub: list[ExprValue] = []
+    for v in expr.add_values:
+        (parameterized_add if v.param_key else add_vals).append(v)
+    for v in expr.sub_values:
+        (parameterized_sub if v.param_key else sub_vals).append(v)
+    net_const = sum(v.value for v in add_vals) - sum(v.value for v in sub_vals)
+    for g in expr.add_groups:
+        if not g.multiply and not g.divide and not g.agg_func and not g.scalar_func and not g.inner_scalar_func:
+            net_const += g.coefficient
+        else:
+            add_groups.append(g)
+    for g in expr.sub_groups:
+        if not g.multiply and not g.divide and not g.agg_func and not g.scalar_func and not g.inner_scalar_func:
+            net_const -= g.coefficient
+        else:
+            sub_groups.append(g)
+    bucket: dict[str, float] = {}
+    group_map: dict[str, MulGroup] = {}
+    for g in add_groups:
+        key = g.structural_key
+        bucket[key] = bucket.get(key, 0.0) + g.coefficient
+        if key not in group_map:
+            group_map[key] = g
+    for g in sub_groups:
+        key = g.structural_key
+        bucket[key] = bucket.get(key, 0.0) - g.coefficient
+        if key not in group_map:
+            group_map[key] = g
+    final_add: list[MulGroup] = []
+    final_sub: list[MulGroup] = []
+    for key, coeff in bucket.items():
+        if coeff == 0.0:
+            continue
+        ref = group_map[key]
+        if coeff > 0:
+            final_add.append(
+                MulGroup(
+                    coefficient=coeff,
+                    multiply=list(ref.multiply),
+                    divide=list(ref.divide),
+                    agg_func=ref.agg_func,
+                    scalar_func=ref.scalar_func,
+                    inner_scalar_func=ref.inner_scalar_func,
+                    scalar_func_args=list(ref.scalar_func_args),
+                    inner_scalar_func_args=list(ref.inner_scalar_func_args),
+                )
+            )
+        else:
+            final_sub.append(
+                MulGroup(
+                    coefficient=abs(coeff),
+                    multiply=list(ref.multiply),
+                    divide=list(ref.divide),
+                    agg_func=ref.agg_func,
+                    scalar_func=ref.scalar_func,
+                    inner_scalar_func=ref.inner_scalar_func,
+                    scalar_func_args=list(ref.scalar_func_args),
+                    inner_scalar_func_args=list(ref.inner_scalar_func_args),
+                )
+            )
+    final_add_vals: list[ExprValue] = list(parameterized_add)
+    final_sub_vals: list[ExprValue] = list(parameterized_sub)
+    if net_const > 0:
+        final_add_vals.append(ExprValue(value=net_const))
+    elif net_const < 0:
+        final_sub_vals.append(ExprValue(value=abs(net_const)))
+    return NormalizedExpr(
+        add_groups=final_add,
+        sub_groups=final_sub,
+        add_values=final_add_vals,
+        sub_values=final_sub_vals,
+        agg_func=expr.agg_func,
+        scalar_func=expr.scalar_func,
+        inner_scalar_func=expr.inner_scalar_func,
+        scalar_func_args=list(expr.scalar_func_args),
+        inner_scalar_func_args=list(expr.inner_scalar_func_args),
+    )
+
+
+def _simplify_filter(fp: FilterParam) -> FilterParam:
+    """Apply simplify_expr to both sides of a FilterParam.
+
+    Args:
+
+        fp: FilterParam to simplify.
+
+    Returns:
+
+        New FilterParam with simplified left_expr and right_expr.
+    """
+    new_left = _simplify_expr(fp.left_expr)
+    new_right = _simplify_expr(fp.right_expr) if fp.right_expr else None
+    return replace(fp, left_expr=new_left, right_expr=new_right)
+
+
+def _simplify_having(hp: HavingParam) -> HavingParam:
+    """Apply simplify_expr to both sides of a HavingParam.
+
+    Args:
+
+        hp: HavingParam to simplify.
+
+    Returns:
+
+        New HavingParam with simplified left_expr and right_expr.
+    """
+    new_left = _simplify_expr(hp.left_expr)
+    new_right = _simplify_expr(hp.right_expr) if hp.right_expr else None
+    return replace(hp, left_expr=new_left, right_expr=new_right)
+
+
+def simplify_exprs(intent: RuntimeIntent) -> RuntimeIntent:
+    """Apply algebraic simplification to every NormalizedExpr across all intent clauses.
+
+    Args:
+
+        intent: RuntimeIntent whose expressions should be simplified.
+
+    Returns:
+
+        New RuntimeIntent with all expressions in simplified form.
+    """
+    debug("[intent_resolve.simplify_exprs] simplifying all expressions")
+    new_select = [replace(sc, expr=_simplify_expr(sc.expr)) for sc in (intent.select_cols or [])]
+    new_order = [replace(obc, expr=_simplify_expr(obc.expr)) for obc in (intent.order_by_cols or [])]
+    new_filters = [_simplify_filter(fp) for fp in (intent.filters_param or [])]
+    new_having = [_simplify_having(hp) for hp in (intent.having_param or [])]
+    new_cte_steps: list[RuntimeCteStep] = []
+    for cte in intent.cte_steps or []:
+        cte_select = [replace(sc, expr=_simplify_expr(sc.expr)) for sc in (cte.select_cols or [])]
+        cte_order = [replace(obc, expr=_simplify_expr(obc.expr)) for obc in (cte.order_by_cols or [])]
+        cte_filters = [_simplify_filter(fp) for fp in (cte.filters_param or [])]
+        cte_having = [_simplify_having(hp) for hp in (cte.having_param or [])]
+        new_cte_steps.append(
+            replace(
+                cte,
+                select_cols=cte_select,
+                order_by_cols=cte_order,
+                filters_param=cte_filters,
+                having_param=cte_having,
+            )
+        )
+    return replace(
+        intent,
+        select_cols=new_select,
+        order_by_cols=new_order,
+        filters_param=new_filters,
+        having_param=new_having,
+        cte_steps=new_cte_steps,
+    )
+
+
+def _normalize_filter_scalar_on_left(fp: FilterParam) -> FilterParam:
+    """Swap sides when left is scalar and right is column, flipping the operator.
+
+    Ensures column or table.column expressions are on the left for validation and SQL generation.
+
+    Args:
+
+        fp: FilterParam to normalize.
+
+    Returns:
+
+        FilterParam with column on the left when applicable.
+    """
+    if not fp.right_expr:
+        return fp
+    left_cols = [c for c in extract_columns_from_expr(fp.left_expr) if "." in c]
+    right_cols = [c for c in extract_columns_from_expr(fp.right_expr) if "." in c]
+    if left_cols or not right_cols:
+        return fp
+    new_op = REVERSE_OP_MAP.get(fp.op, fp.op)
+    return FilterParam(
+        left_expr=fp.right_expr,
+        op=new_op,
+        right_expr=fp.left_expr,
+        value_type=fp.value_type,
+        param_key=fp.param_key,
+        raw_value=fp.raw_value,
+        bool_op=fp.bool_op,
+        filter_group=fp.filter_group,
+    )
+
+
+def _normalize_filter_canonical(fp: FilterParam) -> FilterParam:
+    """Normalize a filter to canonical form with a non-empty expression on the left.
+
+    When the left_expr is empty but right_expr is not, swaps the sides and reverses the comparison operator.
+
+    Args:
+
+        fp: FilterParam to normalize.
+
+    Returns:
+
+        FilterParam with the heavier side on the left.
+    """
+    if not fp.left_expr.add_groups and not fp.left_expr.add_values and fp.right_expr:
+        new_op = REVERSE_OP_MAP.get(fp.op, fp.op)
+        return FilterParam(
+            left_expr=fp.right_expr,
+            op=new_op,
+            right_expr=fp.left_expr,
+            value_type=fp.value_type,
+            param_key=fp.param_key,
+        )
+    return fp
+
+
+def _normalize_having_canonical(hp: HavingParam) -> HavingParam:
+    """Normalize a having condition to canonical form with a non-empty expression on the left.
+
+    Args:
+
+        hp: HavingParam to normalize.
+
+    Returns:
+
+        HavingParam with the heavier side on the left.
+    """
+    if not hp.left_expr.add_groups and not hp.left_expr.add_values and hp.right_expr:
+        new_op = REVERSE_OP_MAP.get(hp.op, hp.op)
+        return HavingParam(
+            left_expr=hp.right_expr,
+            op=new_op,
+            right_expr=hp.left_expr,
+            value_type=hp.value_type,
+            param_key=hp.param_key,
+        )
+    return hp
+
+
+def _normalize_col_to_col_filter(fp: FilterParam) -> FilterParam:
+    """Normalize an expr-vs-expr filter so the lexicographically smaller signature is on the left.
+
+    Args:
+
+        fp: FilterParam with a right_expr (col-vs-col filter).
+
+    Returns:
+
+        FilterParam with sides swapped and operator reversed if needed.
+    """
+    if fp.right_expr and not fp.param_key:
+        left_sig = fp.left_expr.signature_key
+        right_sig = fp.right_expr.signature_key
+        if left_sig > right_sig:
+            new_op = REVERSE_OP_MAP.get(fp.op, fp.op)
+            return FilterParam(
+                left_expr=fp.right_expr,
+                op=new_op,
+                right_expr=fp.left_expr,
+                value_type=fp.value_type,
+                param_key=fp.param_key,
+            )
+    return fp
+
+
+def _normalize_agg_to_agg_having(hp: HavingParam) -> HavingParam:
+    """Normalize an expr-vs-expr having condition so the lexicographically smaller signature is on the left.
+
+    Args:
+
+        hp: HavingParam with a right_expr (agg-vs-agg having).
+
+    Returns:
+
+        HavingParam with sides swapped and operator reversed if needed.
+    """
+    if hp.right_expr and not hp.param_key:
+        left_sig = hp.left_expr.signature_key
+        right_sig = hp.right_expr.signature_key
+        if left_sig > right_sig:
+            new_op = REVERSE_OP_MAP.get(hp.op, hp.op)
+            return HavingParam(
+                left_expr=hp.right_expr,
+                op=new_op,
+                right_expr=hp.left_expr,
+                value_type=hp.value_type,
+                param_key=hp.param_key,
+            )
+    return hp
+
+
+def _normalize_filter(fp: FilterParam) -> FilterParam:
+    """Apply all normalization steps to a single filter.
+
+    Runs scalar-on-left swap, canonical form, col-vs-col ordering, operator normalization, and value type normalization in sequence.
+
+    Args:
+
+        fp: FilterParam to normalize.
+
+    Returns:
+
+        Fully normalized FilterParam.
+    """
+    fp = _normalize_filter_scalar_on_left(fp)
+    fp = _normalize_filter_canonical(fp)
+    fp = _normalize_col_to_col_filter(fp)
+    return replace(fp, op=normalize_op(fp.op), value_type=normalize_value_type(fp.value_type))
+
+
+def _normalize_having(hp: HavingParam) -> HavingParam:
+    """Apply all normalization steps to a single having condition.
+
+    Runs canonical form, agg-vs-agg ordering, operator normalization, and value type normalization in sequence.
+
+    Args:
+
+        hp: HavingParam to normalize.
+
+    Returns:
+
+        Fully normalized HavingParam.
+    """
+    hp = _normalize_having_canonical(hp)
+    hp = _normalize_agg_to_agg_having(hp)
+    return replace(hp, op=normalize_op(hp.op), value_type=normalize_value_type(hp.value_type))
+
+
+def _dedup_filters(filters: list[FilterParam]) -> list[FilterParam]:
+    """Remove duplicate filters that share an identical structural signature, bool_op, and filter_group.
+
+    Args:
+
+        filters: List of FilterParam objects to deduplicate.
+
+    Returns:
+
+        List with the first occurrence of each unique (signature_key, bool_op, filter_group) retained.
+    """
+    seen: set[tuple[str, str, int | None]] = set()
+    result: list[FilterParam] = []
+    for fp in filters:
+        key = (fp.signature_key, fp.bool_op, fp.filter_group)
+        if key in seen:
+            debug(f"[intent_resolve.dedup_filters] dropping duplicate filter: {key}")
+            continue
+        seen.add(key)
+        result.append(fp)
+    return result
+
+
+def _dedup_having(having: list[HavingParam]) -> list[HavingParam]:
+    """Remove duplicate having conditions that share an identical structural signature, bool_op, and filter_group.
+
+    Args:
+
+        having: List of HavingParam objects to deduplicate.
+
+    Returns:
+
+        List with the first occurrence of each unique (signature_key, bool_op, filter_group) retained.
+    """
+    seen: set[tuple[str, str, int | None]] = set()
+    result: list[HavingParam] = []
+    for hp in having:
+        key = (hp.signature_key, hp.bool_op, hp.filter_group)
+        if key in seen:
+            debug(f"[intent_resolve.dedup_having] dropping duplicate having: {key}")
+            continue
+        seen.add(key)
+        result.append(hp)
+    return result
+
+
+def normalize_filters_havings(intent: RuntimeIntent) -> RuntimeIntent:
+    """Apply all normalization, deduplication, and sorting rules to filters and having conditions.
+
+    Args:
+
+        intent: RuntimeIntent whose filters and having lists should be normalized.
+
+    Returns:
+
+        New RuntimeIntent with all filters and having conditions normalized, deduplicated, and sorted.
+    """
+    new_filters = [_normalize_filter(fp) for fp in (intent.filters_param or [])]
+    new_having = [_normalize_having(hp) for hp in (intent.having_param or [])]
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_filters = _dedup_filters(sort_filters([_normalize_filter(fp) for fp in (cte.filters_param or [])]))
+        cte_having = _dedup_having(sort_having([_normalize_having(hp) for hp in (cte.having_param or [])]))
+        new_cte_steps.append(replace(cte, filters_param=cte_filters, having_param=cte_having))
+    new_filters = _dedup_filters(sort_filters(new_filters))
+    new_having = _dedup_having(sort_having(new_having))
+    return replace(
+        intent,
+        filters_param=new_filters,
+        having_param=new_having,
+        cte_steps=new_cte_steps,
+    )