aetherdialect 0.1.0__py3-none-any.whl

text2sql/intent_repair.py

@@ -0,0 +1,1733 @@
+"""Structural intent repairs and value normalization.
+
+Repairs foreign key filter type mismatches where an integer column is compared to a string value by rewriting filters to use descriptive columns and expands foreign key selects to descriptive columns.
+
+Strips spurious GROUP BY clauses, impossible HAVING conditions such as COUNT < 0, and hallucinated SQL keywords in table names.
+
+Strips foreign key equi-join conditions from filters, prunes unreferenced tables, and normalizes boolean filter values, IN-list types, and filter value casing against schema statistics and question text.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+from .config import (
+    BOOLEAN_FALSY_VALUES,
+    BOOLEAN_TRUTHY_VALUES,
+    DISTINCT_RE,
+    IMPOSSIBLE_HAVING_RE,
+    NUMERIC_DATA_TYPES,
+    NUMERIC_LITERAL_RE,
+    RANGE_OPS,
+    SQL_KEYWORDS,
+    TOP_N_RE,
+    PolicyConfig,
+)
+from .contracts_base import ColumnMetadata, SchemaGraph, TableMetadata
+from .contracts_core import (
+    FilterParam,
+    HavingParam,
+    MulGroup,
+    NormalizedExpr,
+    RuntimeCteStep,
+    RuntimeIntent,
+    SelectCol,
+)
+from .core_utils import debug
+from .intent_expr import extract_columns_from_expr, replace_refs_in_expr
+
+
+def _english_plurals(word: str) -> list[str]:
+    """Return *word* together with its common English plural forms.
+
+    Covers consonant-y to -ies, sibilant endings to -es, and the default -s suffix and always returns the original word as the first element so callers can iterate a single list.
+    """
+    forms = [word]
+    w = word.lower()
+    if w.endswith("y") and len(w) > 2 and w[-2] not in "aeiou":
+        forms.append(w[:-1] + "ies")
+    elif w.endswith(("s", "sh", "ch", "x", "z")):
+        forms.append(w + "es")
+    else:
+        forms.append(w + "s")
+    return forms
+
+
+def _apply_filters_to_main_and_ctes(
+    intent: RuntimeIntent,
+    process_fn: Callable[[list[FilterParam]], tuple[list[FilterParam], bool]],
+) -> RuntimeIntent:
+    """Apply a filter processor to the main intent and each CTE, merging results."""
+    new_fp, main_changed = process_fn(intent.filters_param or [])
+    if not intent.cte_steps:
+        return replace(intent, filters_param=new_fp) if main_changed else intent
+    new_cte_steps = []
+    cte_changed = False
+    for cte in intent.cte_steps:
+        cte_fp, c = process_fn(cte.filters_param or [])
+        if c:
+            cte_changed = True
+        new_cte_steps.append(replace(cte, filters_param=cte_fp))
+    if not main_changed and not cte_changed:
+        return intent
+    result = replace(intent, filters_param=new_fp)
+    if cte_changed:
+        result = replace(result, cte_steps=new_cte_steps)
+    return result
+
+
+def _dedup_contradictory_filters_list(
+    filters: list[FilterParam],
+) -> tuple[list[FilterParam], bool]:
+    """Remove range operators when equality exists on the same column.
+
+    When a column has both an '=' filter and a range operator such as '>', '<', '>=', or '<=', the range filter contradicts or is redundant with the equality and the range filter is dropped.
+    """
+    eq_columns: set[str] = set()
+    for fp in filters:
+        col = fp.left_expr.primary_column or ""
+        if fp.op == "=" and col:
+            eq_columns.add(col)
+
+    if not eq_columns:
+        return filters, False
+
+    kept: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        col = fp.left_expr.primary_column or ""
+        if col in eq_columns and fp.op in RANGE_OPS:
+            debug(f"[intent_repair.dedup_contradictory_filters] dropping {fp.op} on '{col}' that contradicts =")
+            changed = True
+            continue
+        kept.append(fp)
+    return kept, changed
+
+
+def dedup_contradictory_filters(intent: RuntimeIntent) -> RuntimeIntent:
+    """Remove contradictory range filters from main query and CTEs."""
+    return _apply_filters_to_main_and_ctes(intent, _dedup_contradictory_filters_list)
+
+
+def _is_null_value(raw_value: Any) -> bool:
+    """Return True if the raw filter value represents NULL."""
+    if raw_value is None:
+        return True
+    if isinstance(raw_value, str) and raw_value.strip().lower() == "null":
+        return True
+    return False
+
+
+def repair_null_equality_filters(intent: RuntimeIntent) -> RuntimeIntent:
+    """Rewrite equality filters against null values into proper IS NULL or IS NOT NULL conditions.
+
+    When the LLM produces a filter with op '=' and a null value, the SQL column = NULL is rewritten to column IS NULL and similarly '!=' or '<>' against null becomes IS NOT NULL and the change applies to both the main query and all CTE steps.
+
+    Args:
+
+        intent: RuntimeIntent to inspect.
+
+    Returns:
+
+        Updated RuntimeIntent with corrected null operators.
+    """
+
+    return _apply_filters_to_main_and_ctes(intent, _repair_null_equality_list)
+
+
+def _repair_null_equality_list(
+    filters: list[FilterParam],
+) -> tuple[list[FilterParam], bool]:
+    repaired: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        if fp.op == "=" and _is_null_value(fp.raw_value):
+            repaired.append(
+                replace(
+                    fp,
+                    op="is null",
+                    raw_value=None,
+                    value_type="null",
+                )
+            )
+            changed = True
+        elif fp.op in ("!=", "<>") and _is_null_value(fp.raw_value):
+            repaired.append(
+                replace(
+                    fp,
+                    op="is not null",
+                    raw_value=None,
+                    value_type="null",
+                )
+            )
+            changed = True
+        else:
+            repaired.append(fp)
+    return repaired, changed
+
+
+def _infer_cte_output_columns(cte: Any) -> list[str]:
+    """Derive output column names from a CTE's select_cols.
+
+    When the LLM omits output_columns this falls back to extracting the trailing column identifier from each select expression and prepends the aggregation function name for aggregated columns to avoid ambiguity.
+
+    Args:
+
+        cte: A RuntimeCteStep with populated select_cols.
+
+    Returns:
+
+        List of bare column-name strings suitable for use as CTE output aliases.
+    """
+    names: list[str] = []
+    for sc in cte.select_cols or []:
+        col = sc.expr.primary_column if sc.expr else ""
+        if not col:
+            continue
+        bare = col.split(".")[-1].strip().lower()
+        if sc.is_aggregated and sc.expr.agg_func:
+            bare = f"{sc.expr.agg_func.lower()}_{bare}"
+        if bare and bare not in names:
+            names.append(bare)
+    return names
+
+
+def _qualify_term(term: str, output_to_cte: dict[str, str]) -> str:
+    """Prefix an unqualified column reference with its CTE source name.
+
+    If term, which is a single MulGroup.multiply or MulGroup.divide entry, contains an unqualified column name that matches a CTE output column, the column portion is rewritten to cte_name.column while already qualified terms containing a dot are returned unchanged, and function-wrapped columns such as SUM(total_amount) are handled by replacing the innermost identifier.
+
+    Args:
+
+        term: Raw expression term.
+
+        output_to_cte: Mapping of lowered bare output column name to the owning CTE name.
+
+    Returns:
+
+        The possibly rewritten term string.
+    """
+    for col_lower, cte_name in output_to_cte.items():
+        pat = re.compile(
+            r"(?<!\.)(?<![A-Za-z0-9_])" + re.escape(col_lower) + r"(?![A-Za-z0-9_])",
+            re.IGNORECASE,
+        )
+        if pat.search(term):
+            term = pat.sub(f"{cte_name}.{col_lower}", term)
+    return term
+
+
+def _qualify_expr(expr: NormalizedExpr, output_to_cte: dict[str, str]) -> NormalizedExpr:
+    """Apply CTE qualification to every term in a NormalizedExpr by rebuilding each MulGroup with qualified multiply and divide terms."""
+
+    def _fix_group(g: MulGroup) -> MulGroup:
+        return replace(
+            g,
+            multiply=[_qualify_term(m, output_to_cte) for m in g.multiply],
+            divide=[_qualify_term(d, output_to_cte) for d in g.divide],
+        )
+
+    return replace(
+        expr,
+        add_groups=[_fix_group(g) for g in expr.add_groups],
+        sub_groups=[_fix_group(g) for g in expr.sub_groups],
+    )
+
+
+def qualify_cte_output_columns(intent: RuntimeIntent) -> RuntimeIntent:
+    """Qualify unqualified column references in the main query that match CTE output columns.
+
+    When the LLM produces a main-query expression referencing a CTE output column without the CTE-name prefix this repair detects the match and prepends the correct CTE name and only the main query's select_cols, group_by_cols, and order_by_cols are touched because CTE steps reference their own tables rather than other CTE outputs.
+
+    Args:
+
+        intent: RuntimeIntent with CTE steps whose output_columns may be referenced without qualification in the main query.
+
+    Returns:
+
+        Updated RuntimeIntent with qualified main-query expressions or the original intent if nothing changed.
+    """
+    cte_steps = intent.cte_steps or []
+    if not cte_steps:
+        return intent
+
+    output_to_cte: dict[str, str] = {}
+    for cte in cte_steps:
+        explicit_outputs = cte.output_columns or []
+        if not explicit_outputs:
+            explicit_outputs = _infer_cte_output_columns(cte)
+        for oc in explicit_outputs:
+            bare = oc.split(".")[-1].strip().lower()
+            if bare:
+                output_to_cte[bare] = cte.cte_name
+    if not output_to_cte:
+        return intent
+
+    main_tables = set(intent.tables or [])
+
+    def _should_skip(term: str) -> bool:
+        """Return True if the term is already qualified with a real
+        table."""
+        if "." in term:
+            prefix = term.split(".")[0].lower()
+            return prefix in {t.lower() for t in main_tables}
+        return False
+
+    def _safe_qualify(term: str) -> str:
+        if _should_skip(term):
+            return term
+        return _qualify_term(term, output_to_cte)
+
+    new_select_cols = [
+        (replace(sc, expr=_qualify_expr(sc.expr, output_to_cte)) if not _should_skip(sc.expr.primary_column) else sc)
+        for sc in (intent.select_cols or [])
+    ]
+    new_group_by = [
+        _qualify_expr(g, output_to_cte) if not _should_skip(g.primary_column) else g
+        for g in (intent.group_by_cols or [])
+    ]
+    new_order_by = [
+        (
+            replace(obc, expr=_qualify_expr(obc.expr, output_to_cte))
+            if not _should_skip(obc.expr.primary_column)
+            else obc
+        )
+        for obc in (intent.order_by_cols or [])
+    ]
+
+    if (
+        new_select_cols == intent.select_cols
+        and new_group_by == intent.group_by_cols
+        and new_order_by == intent.order_by_cols
+    ):
+        return intent
+
+    debug("[qualify_cte_output_columns] qualified unqualified CTE output references in main query")
+    return replace(
+        intent,
+        select_cols=new_select_cols,
+        group_by_cols=new_group_by,
+        order_by_cols=new_order_by,
+    )
+
+
+DESCRIPTIVE_ALLOWED_VALUE_TYPES = frozenset({"string", "integer"})
+DESCRIPTIVE_EXCLUDED_VALUE_TYPES = frozenset({"date", "boolean", "number"})
+
+
+def _descriptive_column_score(col_name: str, col_meta: ColumnMetadata) -> tuple[int, int]:
+    """Score a column for use as a descriptive column; higher is better.
+
+    Prefers name-like columns (name, title, first_name, last_name) and
+    higher distinct_count. No maximum cardinality cap.
+    """
+    name_lower = col_name.lower()
+    name_score = 0
+    if "name" in name_lower or "title" in name_lower:
+        name_score = 2
+    elif "first_name" in name_lower or "last_name" in name_lower:
+        name_score = 3
+    dc = col_meta.distinct_count or 0
+    return (name_score, dc)
+
+
+def best_descriptive_columns(
+    table: str,
+    schema_graph: SchemaGraph,
+    exclude: set[str],
+    max_count: int = 2,
+) -> list[str]:
+    """Return up to *max_count* best descriptive columns for the table.
+
+    Excludes PK/FK columns and non-string/integer types.  Requires
+    high individual uniqueness (``distinct_ratio >= 0.95``).  When
+    *max_count* >= 2 and two name-like candidates exist whose
+    composite distinct ratio (profiled during schema loading) exceeds
+    the best single-column ratio, both columns are returned.
+    """
+    tbl_meta = schema_graph.tables.get(table)
+    if not tbl_meta:
+        return []
+    candidates: list[tuple[str, ColumnMetadata]] = []
+    for col_name, col_meta in tbl_meta.columns.items():
+        if col_meta.is_primary_key or col_meta.is_foreign_key:
+            continue
+        if f"{table}.{col_name}" in exclude:
+            continue
+        vt = (col_meta.value_type or "").lower()
+        if vt in DESCRIPTIVE_EXCLUDED_VALUE_TYPES:
+            continue
+        if vt not in DESCRIPTIVE_ALLOWED_VALUE_TYPES:
+            continue
+        ratio = col_meta.distinct_ratio
+        if ratio is not None and ratio < 0.95:
+            continue
+        candidates.append((col_name, col_meta))
+    if not candidates:
+        return []
+    candidates.sort(
+        key=lambda p: _descriptive_column_score(p[0], p[1]),
+        reverse=True,
+    )
+    if max_count >= 2 and len(candidates) >= 2:
+        pair = _best_composite_name_pair(tbl_meta, candidates)
+        if pair is not None:
+            return list(pair)
+    return [col_name for col_name, _ in candidates[:max_count]]
+
+
+def _best_composite_name_pair(
+    tbl_meta: TableMetadata,
+    candidates: list[tuple[str, ColumnMetadata]],
+) -> tuple[str, str] | None:
+    """Return a name-like column pair if its composite ratio beats singles.
+
+    Checks whether any two name-scored candidates have a profiled
+    composite distinct ratio that exceeds the best individual
+    distinct_ratio among the candidates.  Returns ``None`` when no
+    such pair is found.
+    """
+    name_candidates = [
+        (name, meta)
+        for name, meta in candidates
+        if _descriptive_column_score(name, meta)[0] >= 2
+    ]
+    if len(name_candidates) < 2:
+        return None
+    best_single_ratio = max(
+        (m.distinct_ratio or 0.0) for _, m in candidates
+    )
+    ratios = tbl_meta.composite_descriptive_ratios
+    for i in range(len(name_candidates)):
+        for j in range(i + 1, len(name_candidates)):
+            c1 = name_candidates[i][0]
+            c2 = name_candidates[j][0]
+            composite = ratios.get((c1, c2)) or ratios.get((c2, c1))
+            if composite is not None and composite > best_single_ratio:
+                return (c1, c2)
+    return None
+
+
+def best_descriptive_column(table: str, schema_graph: SchemaGraph, exclude: set[str]) -> str | None:
+    """Return the best non-PK non-FK descriptive column for the table.
+
+    Uses best_descriptive_columns with max_count=1. Allows string and integer
+    types; excludes PK/FK and decimals, dates, booleans.
+    """
+    cols = best_descriptive_columns(table, schema_graph, exclude, max_count=1)
+    return cols[0] if cols else None
+
+
+def _repair_fk_filters(
+    filters: list[FilterParam],
+    select_cols: list,
+    tables: list[str],
+    schema_graph: SchemaGraph,
+    label: str = "",
+) -> tuple[list[FilterParam], list[str], bool]:
+    """Detect foreign-key filters that should use descriptive columns.
+
+    Leaves filters unchanged but reports whether any filter targets a
+    foreign-key integer column with a string-like value, which should be
+    surfaced as a semantic issue for repair rather than rewritten
+    deterministically.
+    """
+    new_filters: list[FilterParam] = []
+    tables = list(tables)
+    changed = False
+    existing_terms = {sc.expr.primary_term for sc in select_cols or []}
+    for fp in filters:
+        if fp.value_type not in {"string", "enum"} or fp.raw_value is None:
+            new_filters.append(fp)
+            continue
+        col = fp.left_expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            new_filters.append(fp)
+            continue
+        col_meta = schema_graph.get_column(parts[0], parts[1])
+        if not col_meta or not col_meta.is_foreign_key or col_meta.value_type not in {"integer", "number"}:
+            new_filters.append(fp)
+            continue
+        fk_target = col_meta.fk_target
+        if not fk_target:
+            new_filters.append(fp)
+            continue
+        target_table, _ = fk_target
+        desc = best_descriptive_column(target_table, schema_graph, existing_terms)
+        new_filters.append(fp)
+        if desc:
+            changed = True
+            debug(f"[intent_resolve.repair_fk_filter_type_mismatch{label}] detected fk filter {col} needing descriptive column")
+    return new_filters, tables, changed
+
+
+def repair_fk_filter_type_mismatch(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    main_filters, _, main_changed = _repair_fk_filters(
+        intent.filters_param or [],
+        intent.select_cols or [],
+        list(intent.tables or []),
+        schema_graph,
+    )
+    cte_changed = False
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_filters, _, c = _repair_fk_filters(
+            cte.filters_param or [],
+            cte.select_cols or [],
+            list(cte.tables or []),
+            schema_graph,
+            label=f" CTE '{cte.cte_name}'",
+        )
+        if c:
+            new_cte_steps.append(replace(cte, filters_param=cte_filters))
+            cte_changed = True
+        else:
+            new_cte_steps.append(cte)
+    if not main_changed and not cte_changed:
+        return intent
+    result = intent
+    if main_changed:
+        result = replace(result, filters_param=main_filters)
+    if cte_changed:
+        result = replace(result, cte_steps=new_cte_steps)
+    return result
+
+
+def expand_fk_select_to_descriptive(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Replace foreign-key integer columns in select_cols with the target table's descriptive column.
+
+    When a SelectCol references a foreign-key column this rewrites it to the foreign-key target table's best descriptive column and adds the target table to intent.tables so join enumeration discovers the path, mirroring repair_fk_filter_type_mismatch but operating on SELECT columns instead of filter conditions and only rewriting bare non-aggregated foreign-key columns.
+
+    Args:
+
+        intent: RuntimeIntent whose select_cols may reference foreign-key integer columns.
+        schema_graph: SchemaGraph for foreign-key relationship and descriptive column lookups.
+
+    Returns:
+
+        Updated RuntimeIntent with foreign-key select_cols expanded to descriptive columns.
+    """
+    tables = list(intent.tables or [])
+    new_select: list[SelectCol] = []
+    changed = False
+    existing_terms = {sc.expr.primary_term for sc in intent.select_cols or []}
+    for sc in intent.select_cols or []:
+        if sc.is_aggregated:
+            new_select.append(sc)
+            continue
+        col = sc.expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            new_select.append(sc)
+            continue
+        col_meta = schema_graph.get_column(parts[0], parts[1])
+        if not col_meta or not col_meta.is_foreign_key or col_meta.value_type not in {"integer", "number"}:
+            new_select.append(sc)
+            continue
+        fk_target = col_meta.fk_target
+        if not fk_target:
+            new_select.append(sc)
+            continue
+        target_table, _ = fk_target
+        descs = best_descriptive_columns(
+            target_table, schema_graph, existing_terms, max_count=2,
+        )
+        if not descs:
+            new_select.append(sc)
+            continue
+        for desc in descs:
+            fq = f"{target_table}.{desc}"
+            new_expr = NormalizedExpr.from_column(fq)
+            new_select.append(SelectCol(expr=new_expr))
+            existing_terms.add(fq)
+        if target_table not in tables:
+            tables.append(target_table)
+        changed = True
+        debug(
+            f"[intent_resolve.expand_fk_select_to_descriptive] "
+            f"rewired select {col} -> {[f'{target_table}.{d}' for d in descs]}"
+        )
+    if not changed:
+        return intent
+    return replace(intent, select_cols=new_select, tables=sorted(tables))
+
+
+def strip_spurious_group_by(intent: RuntimeIntent) -> RuntimeIntent:
+    """Remove group_by_cols when no aggregation exists in select or having.
+
+    Guards against LLM hallucinations that produce GROUP BY without any aggregate function in select_cols or having_param, and when group_by_cols are present but neither select nor having contains an aggregate the GROUP BY is stripped and the grain is downgraded to 'row_level' if it was 'grouped' with the same logic applied to each CTE step independently.
+
+    Args:
+
+        intent: RuntimeIntent to inspect.
+
+    Returns:
+
+        Updated RuntimeIntent with group_by_cols cleared when spurious, or the original intent unchanged.
+    """
+    main_changed = False
+    new_grain = intent.grain
+    new_gb = intent.group_by_cols or []
+    if intent.group_by_cols:
+        has_agg = any(sc.is_aggregated for sc in (intent.select_cols or []))
+        has_agg = has_agg or any(hp.left_expr.has_aggregation for hp in (intent.having_param or []))
+        if not has_agg:
+            debug(
+                f"[intent_resolve.strip_spurious_group_by] group_by_cols present without aggregation — stripping {[g.primary_term for g in intent.group_by_cols]}"
+            )
+            new_grain = "row_level" if intent.grain == "grouped" else intent.grain
+            new_gb = []
+            main_changed = True
+
+    new_cte_steps = []
+    cte_changed = False
+    for cte in intent.cte_steps or []:
+        if not (cte.group_by_cols or []):
+            new_cte_steps.append(cte)
+            continue
+        cte_has_agg = any(sc.is_aggregated for sc in (cte.select_cols or []))
+        cte_has_agg = cte_has_agg or any(hp.left_expr.has_aggregation for hp in (cte.having_param or []))
+        if cte_has_agg:
+            new_cte_steps.append(cte)
+            continue
+        debug(
+            f"[intent_resolve.strip_spurious_group_by] CTE '{cte.cte_name}' group_by_cols present without aggregation — stripping {[g.primary_term for g in cte.group_by_cols]}"
+        )
+        cte_grain = "row_level" if cte.grain == "grouped" else cte.grain
+        new_cte_steps.append(replace(cte, group_by_cols=[], grain=cte_grain))
+        cte_changed = True
+
+    if not main_changed and not cte_changed:
+        return intent
+    return replace(
+        intent,
+        group_by_cols=new_gb,
+        grain=new_grain,
+        cte_steps=new_cte_steps if cte_changed else (intent.cte_steps or []),
+    )
+
+
+def _is_impossible_having(hp: HavingParam) -> bool:
+    """Return True when a HAVING condition is logically impossible.
+
+    Detects patterns such as ``COUNT(...) < 0`` or ``COUNT(...) <= -1``
+    which can never be satisfied.  Only applies to COUNT since SUM can
+    legitimately produce negative values.  Handles both raw-string forms
+    (``primary_term`` starting with ``COUNT``) and structured forms
+    where ``agg_func`` is stored on the ``MulGroup``.
+
+    Args:     hp: A single HavingParam to inspect.
+
+    Returns:     True if the condition can never be true.
+    """
+    left_expr = hp.left_expr
+    if not left_expr:
+        return False
+    primary = left_expr.primary_term
+    agg_func = ""
+    if left_expr.add_groups and left_expr.add_groups[0].agg_func:
+        agg_func = left_expr.add_groups[0].agg_func.upper()
+    is_count = bool(IMPOSSIBLE_HAVING_RE.match(primary)) or agg_func == "COUNT"
+    if not is_count:
+        return False
+    op = (hp.op or "").strip().lower()
+    val = hp.raw_value
+    if val is None:
+        return False
+    try:
+        numeric_val = float(val) if not isinstance(val, (int, float)) else val
+    except (ValueError, TypeError):
+        return False
+    if op in ("<", "<=") and numeric_val <= 0:
+        return True
+    if op == "=" and numeric_val < 0:
+        return True
+    return False
+
+
+def strip_impossible_having(intent: RuntimeIntent) -> RuntimeIntent:
+    """Remove HAVING conditions that are logically impossible.
+
+    Filters out conditions like ``COUNT(...) < 0`` which can never be
+    satisfied.  When all HAVING params are removed and the intent was
+    ``"grouped"`` with no remaining aggregation need, the grain is
+    downgraded.
+
+    Applies the same logic to each CTE step independently.
+
+    Args:     intent: RuntimeIntent to inspect.
+
+    Returns:     Updated RuntimeIntent with impossible HAVING params
+    removed,     or the original intent unchanged.
+    """
+    main_having = intent.having_param or []
+    kept_main = [hp for hp in main_having if not _is_impossible_having(hp)]
+    main_changed = len(kept_main) != len(main_having)
+    if main_changed:
+        removed = len(main_having) - len(kept_main)
+        debug(f"[strip_impossible_having] removed {removed} impossible HAVING condition(s)")
+
+    new_cte_steps = []
+    cte_changed = False
+    for cte in intent.cte_steps or []:
+        cte_having = cte.having_param or []
+        kept_cte = [hp for hp in cte_having if not _is_impossible_having(hp)]
+        if len(kept_cte) != len(cte_having):
+            cte_changed = True
+            new_cte_steps.append(replace(cte, having_param=kept_cte))
+        else:
+            new_cte_steps.append(cte)
+
+    if not main_changed and not cte_changed:
+        return intent
+    return replace(
+        intent,
+        having_param=kept_main,
+        cte_steps=new_cte_steps if cte_changed else (intent.cte_steps or []),
+    )
+
+
+def sanitize_table_names(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Strip SQL keywords accidentally prepended to table names.
+
+    LLMs sometimes hallucinate table references like ``"FROM orders"``
+    or ``"JOIN products"`` instead of bare ``"orders"`` /
+    ``"products"``. This function strips leading tokens that match SQL
+    keywords, keeping only the trailing word if it matches a known
+    schema table.
+
+    Args:     intent: RuntimeIntent whose ``tables`` list may contain
+    polluted names.     schema_graph: SchemaGraph providing the set of
+    valid table names.
+
+    Returns:     Updated RuntimeIntent with sanitized table names, or
+    the     original intent when no changes are needed.
+    """
+    valid_tables = {t.lower(): t for t in schema_graph.tables}
+    new_tables: list[str] = []
+    changed = False
+    for tbl in intent.tables or []:
+        if tbl.lower() in valid_tables:
+            new_tables.append(tbl)
+            continue
+        parts = tbl.split()
+        candidate = parts[-1].lower() if parts else ""
+        if candidate in valid_tables and any(p.lower() in SQL_KEYWORDS for p in parts[:-1]):
+            debug(f"[sanitize_table_names] corrected '{tbl}' → '{valid_tables[candidate]}'")
+            new_tables.append(valid_tables[candidate])
+            changed = True
+        else:
+            new_tables.append(tbl)
+
+    if not changed:
+        return intent
+    return replace(intent, tables=new_tables)
+
+
+def _strip_join_condition_filters(filters: list[FilterParam], schema_graph: SchemaGraph) -> list[FilterParam]:
+    """Remove FilterParam entries that are FK equi-join conditions.
+
+    An equi-join condition is an equality filter (op '=') between two
+    fully-qualified columns that match a known FK edge in the schema (in
+    either direction).
+
+    Args:     filters: List of FilterParam objects to process.
+    schema_graph: SchemaGraph providing FK edge definitions.
+
+    Returns:     Filtered list with FK join conditions removed.
+    """
+    fk_pairs: set[tuple[str, str]] = set()
+    for tbl in schema_graph.tables.values():
+        for fk in tbl.foreign_keys:
+            if len(fk.src_cols) == 1 and len(fk.dst_cols) == 1:
+                left = f"{fk.src_table}.{fk.src_cols[0]}"
+                right = f"{fk.dst_table}.{fk.dst_cols[0]}"
+                fk_pairs.add((left, right))
+                fk_pairs.add((right, left))
+    result: list[FilterParam] = []
+    for fp in filters:
+        if fp.right_expr is None or fp.op != "=":
+            result.append(fp)
+            continue
+        left_term = fp.left_expr.primary_term
+        right_term = fp.right_expr.primary_term
+        if (left_term, right_term) in fk_pairs:
+            debug(f"[intent_resolve.strip_join_condition_filters] dropping FK join filter: {left_term} = {right_term}")
+            continue
+        result.append(fp)
+    return result
+
+
+def strip_join_conditions(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Remove FK equi-join filters from the main query and all CTE
+    steps.
+
+    Args:     intent: RuntimeIntent whose filter lists should be
+    stripped.     schema_graph: SchemaGraph providing FK edge
+    definitions.
+
+    Returns:     New RuntimeIntent with FK join conditions removed.
+    """
+    new_filters = _strip_join_condition_filters(intent.filters_param or [], schema_graph)
+    new_cte_steps = [
+        replace(
+            cte,
+            filters_param=_strip_join_condition_filters(cte.filters_param or [], schema_graph),
+        )
+        for cte in (intent.cte_steps or [])
+    ]
+    return replace(intent, filters_param=new_filters, cte_steps=new_cte_steps)
+
+
+def _is_pk_column(col_ref: str, schema_graph: SchemaGraph) -> bool:
+    """Check whether a fully-qualified column reference points to a
+    primary key.
+
+    Args:     col_ref: Column reference string in 'table.column' format.
+    schema_graph: SchemaGraph for metadata lookups.
+
+    Returns:     True when the referenced column is marked as a primary
+    key.
+    """
+    if "." not in col_ref:
+        return False
+    tbl, col = col_ref.split(".", 1)
+    tbl_meta = schema_graph.tables.get(tbl)
+    if not tbl_meta:
+        return False
+    col_meta = tbl_meta.columns.get(col)
+    return col_meta.is_primary_key if col_meta else False
+
+
+def _strip_distinct_prefix(term: str) -> str:
+    """Remove a DISTINCT prefix that leaked into an expression term.
+
+    Args:     term: Expression term string that may start with 'DISTINCT
+    '.
+
+    Returns:     Term string with the prefix removed, or the original
+    string if absent.
+    """
+    if term.upper().startswith("DISTINCT "):
+        return term[9:].strip()
+    return term
+
+
+def _normalize_sc_pk_distinct(sc: SelectCol, schema_graph: SchemaGraph) -> SelectCol:
+    """Strip redundant DISTINCT from a single SelectCol if aggregated
+    column is a PK."""
+    e = sc.expr
+    agg = e.agg_func or (e.add_groups[0].agg_func if e.add_groups and e.add_groups[0].agg_func else None)
+    if agg != "count":
+        return sc
+    term = e.primary_term
+    clean_term = _strip_distinct_prefix(term)
+    if not _is_pk_column(clean_term, schema_graph):
+        return sc
+    needs_term_fix = clean_term != term
+    if not needs_term_fix:
+        return sc
+    new_groups = list(e.add_groups)
+    if new_groups and needs_term_fix:
+        g = new_groups[0]
+        new_mul = [clean_term if _strip_distinct_prefix(m) == clean_term else m for m in g.multiply]
+        new_groups[0] = replace(g, multiply=new_mul)
+    new_expr = replace(e, add_groups=new_groups)
+    debug(f"[normalize_pk_distinct] stripped DISTINCT prefix from PK term: {term} → {clean_term}")
+    return replace(sc, expr=new_expr)
+
+
+def normalize_pk_distinct(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Strip redundant DISTINCT from COUNT expressions on primary key
+    columns.
+
+    COUNT(DISTINCT pk) is semantically equivalent to COUNT(pk) for
+    primary keys. Removes the DISTINCT prefix from affected select
+    columns.
+
+    Args:     intent: RuntimeIntent to normalize.     schema_graph:
+    SchemaGraph for PK lookups.
+
+    Returns:     New RuntimeIntent with redundant DISTINCT removed.
+    """
+    new_select = [_normalize_sc_pk_distinct(sc, schema_graph) for sc in (intent.select_cols or [])]
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_select = [_normalize_sc_pk_distinct(sc, schema_graph) for sc in (cte.select_cols or [])]
+        new_cte_steps.append(replace(cte, select_cols=cte_select))
+    return replace(intent, select_cols=new_select, cte_steps=new_cte_steps)
+
+
+def _tables_from_columns(cols: list[str]) -> set[str]:
+    """Extract unique table names from a list of fully-qualified column
+    references.
+
+    Args:     cols: List of column reference strings in 'table.column'
+    format.
+
+    Returns:     Set of table name strings found before the '.'
+    separator.
+    """
+    tables: set[str] = set()
+    for col in cols:
+        if "." in col:
+            tables.add(col.split(".")[0])
+    return tables
+
+
+def _collect_referenced_tables(
+    select_cols: list,
+    order_by_cols: list,
+    group_by_cols: list,
+    filters_param: list,
+    having_param: list,
+) -> set[str]:
+    """Collect all table names referenced in expressions across the
+    given clause lists.
+
+    Args:     select_cols: SelectCol list.     order_by_cols: OrderByCol
+    list.     group_by_cols: NormalizedExpr list.     filters_param:
+    FilterParam list.     having_param: HavingParam list.
+
+    Returns:     Set of table names extracted from fully-qualified
+    column references.
+    """
+    all_cols: list[str] = []
+    for sc in select_cols or []:
+        all_cols.extend(extract_columns_from_expr(sc.expr))
+    for obc in order_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(obc.expr))
+    for g in group_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(g))
+    for fp in filters_param or []:
+        all_cols.extend(extract_columns_from_expr(fp.left_expr))
+        if fp.right_expr:
+            all_cols.extend(extract_columns_from_expr(fp.right_expr))
+    for hp in having_param or []:
+        all_cols.extend(extract_columns_from_expr(hp.left_expr))
+        if hp.right_expr:
+            all_cols.extend(extract_columns_from_expr(hp.right_expr))
+    return _tables_from_columns(all_cols)
+
+
+def _collect_essential_tables(
+    order_by_cols: list,
+    group_by_cols: list,
+    filters_param: list,
+    having_param: list,
+) -> set[str]:
+    """Collect tables referenced in non-select clauses.
+
+    These tables are essential for query semantics (filtering, grouping,
+    ordering, having) and must never be pruned.
+    """
+    all_cols: list[str] = []
+    for obc in order_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(obc.expr))
+    for g in group_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(g))
+    for fp in filters_param or []:
+        all_cols.extend(extract_columns_from_expr(fp.left_expr))
+        if fp.right_expr:
+            all_cols.extend(extract_columns_from_expr(fp.right_expr))
+    for hp in having_param or []:
+        all_cols.extend(extract_columns_from_expr(hp.left_expr))
+        if hp.right_expr:
+            all_cols.extend(extract_columns_from_expr(hp.right_expr))
+    return _tables_from_columns(all_cols)
+
+
+def _find_fk_column_for_pk(
+    parent_table: str,
+    pk_column: str,
+    candidate_tables: set[str],
+    schema_graph: SchemaGraph,
+) -> str | None:
+    """Find an FK column on a *candidate_table* that references
+    *parent_table*.*pk_column*.
+
+    Returns the fully qualified FK column  or ``None`` when no candidate
+    holds a matching foreign key.
+    """
+    target_key = (parent_table.lower(), pk_column.lower())
+    for tbl in candidate_tables:
+        tbl_meta = schema_graph.tables.get(tbl)
+        if not tbl_meta:
+            continue
+        for col_name, col_meta in tbl_meta.columns.items():
+            if not col_meta.is_foreign_key or not col_meta.fk_target:
+                continue
+            fk_tgt = (col_meta.fk_target[0].lower(), col_meta.fk_target[1].lower())
+            if fk_tgt == target_key:
+                return f"{tbl}.{col_name}"
+    return None
+
+
+def _rewrite_redundant_pk_aggregations(
+    select_cols: list[SelectCol],
+    select_only_tables: set[str],
+    essential_tables: set[str],
+    schema_graph: SchemaGraph,
+    all_intent_tables: set[str] | None = None,
+) -> tuple[list[SelectCol], set[str]]:
+    """Rewrite aggregations on a parent PK to the child FK column,
+    eliminating the need for the parent table.
+
+    When a select-only table contributes only aggregated columns on its
+    primary key, and another intent table has an FK pointing to that PK,
+    the aggregation is rewritten to use the FK column.  If another
+    aggregation on a different table already exists, the redundant
+    column is dropped instead of rewritten.
+
+    *all_intent_tables*, when provided, is used as the candidate set for
+    FK lookup so that bridge tables not yet referenced by any expression
+    are still discoverable.
+
+    Returns the updated select_cols and a set of tables whose references
+    were fully eliminated by rewriting.
+    """
+    eliminated: set[str] = set()
+    new_select: list[SelectCol] = list(select_cols)
+
+    for tbl in list(select_only_tables):
+        tbl_meta = schema_graph.tables.get(tbl)
+        if not tbl_meta:
+            continue
+
+        pk_col: str | None = None
+        for col_name, col_meta in tbl_meta.columns.items():
+            if col_meta.is_primary_key:
+                pk_col = col_name
+                break
+        if not pk_col:
+            continue
+
+        prefix = f"{tbl}.".lower()
+        tbl_indices: list[int] = []
+        all_agg_pk = True
+        for idx, sc in enumerate(new_select):
+            cols = extract_columns_from_expr(sc.expr)
+            refs_tbl = any(c.lower().startswith(prefix) for c in cols)
+            if not refs_tbl:
+                continue
+            tbl_indices.append(idx)
+            col_ref = sc.expr.primary_column.lower()
+            if not sc.is_aggregated or col_ref != f"{tbl}.{pk_col}".lower():
+                all_agg_pk = False
+                break
+
+        if not tbl_indices or not all_agg_pk:
+            continue
+
+        candidate_pool = (all_intent_tables or set()) | essential_tables | select_only_tables
+        other_tables = candidate_pool - {tbl}
+        fk_col = _find_fk_column_for_pk(tbl, pk_col, other_tables, schema_graph)
+        if not fk_col:
+            continue
+
+        other_has_agg = any(sc.is_aggregated for idx, sc in enumerate(new_select) if idx not in tbl_indices)
+
+        rewritten: list[SelectCol] = []
+        for idx, sc in enumerate(new_select):
+            if idx not in tbl_indices:
+                rewritten.append(sc)
+                continue
+            if other_has_agg:
+                debug(f"[prune_unreferenced_tables] dropping redundant agg {sc.expr.primary_term} (other agg exists)")
+                continue
+            agg_func = sc.expr.agg_func or (sc.expr.add_groups[0].agg_func if sc.expr.add_groups else "")
+            rewritten.append(SelectCol(expr=NormalizedExpr.from_agg(agg_func, fk_col)))
+            debug(f"[prune_unreferenced_tables] rewrote {sc.expr.primary_term} → {agg_func}({fk_col})")
+
+        new_select = rewritten
+        eliminated.add(tbl)
+
+    return new_select, eliminated
+
+
+def requalify_redundant_pk_references(
+    intent: RuntimeIntent,
+    schema_graph: SchemaGraph,
+) -> RuntimeIntent:
+    """Rewrite target-table PK references to source-table FK
+    equivalents when the PK table contributes no other columns.
+
+    When the LLM places ``target.pk_col`` in ``group_by_cols`` or
+    non-aggregated ``select_cols`` and another intent table holds an
+    FK pointing to that PK, the reference is rewritten to
+    ``source.fk_col``.  This eliminates an unnecessary join to the
+    target table.
+
+    Aggregated expressions and ``having_param`` are never touched
+    because PK/FK usage inside aggregation functions (e.g.
+    ``COUNT(table.pk)``) is intentional.
+    """
+    if not schema_graph:
+        return intent
+
+    all_cols: list[str] = []
+    for sc in intent.select_cols or []:
+        all_cols.extend(extract_columns_from_expr(sc.expr))
+    for obc in intent.order_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(obc.expr))
+    for g in intent.group_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(g))
+    for fp in intent.filters_param or []:
+        all_cols.extend(extract_columns_from_expr(fp.left_expr))
+        if fp.right_expr:
+            all_cols.extend(extract_columns_from_expr(fp.right_expr))
+    for hp in intent.having_param or []:
+        all_cols.extend(extract_columns_from_expr(hp.left_expr))
+        if hp.right_expr:
+            all_cols.extend(extract_columns_from_expr(hp.right_expr))
+
+    col_counts: dict[str, int] = {}
+    for col_ref in all_cols:
+        tbl = col_ref.split(".")[0] if "." in col_ref else ""
+        if tbl:
+            col_counts[tbl] = col_counts.get(tbl, 0) + 1
+
+    intent_tables = set(intent.tables or [])
+    fk_lookup: dict[str, tuple[str, str]] = {}
+    for src_table_name in intent_tables:
+        src_table = schema_graph.tables.get(src_table_name)
+        if not src_table:
+            continue
+        for fk in src_table.foreign_keys:
+            dst_table = fk.dst_table
+            if dst_table not in intent_tables:
+                continue
+            for src_col, dst_col in zip(fk.src_cols, fk.dst_cols, strict=False):
+                pk_ref = f"{dst_table}.{dst_col}"
+                fk_ref = f"{src_table_name}.{src_col}"
+                if pk_ref not in fk_lookup:
+                    fk_lookup[pk_ref] = (fk_ref, dst_table)
+
+    rewrite_map: dict[str, str] = {}
+    for pk_ref, (fk_ref, pk_table) in fk_lookup.items():
+        if col_counts.get(pk_table, 0) <= 1:
+            rewrite_map[pk_ref] = fk_ref
+
+    if not rewrite_map:
+        return intent
+
+    debug(f"[requalify_redundant_pk_references] rewrite_map: {rewrite_map}")
+
+    def _rewrite_col(col_ref: str) -> str:
+        return rewrite_map.get(col_ref, col_ref)
+
+    def _rewrite_expr(expr: NormalizedExpr) -> NormalizedExpr:
+        return replace_refs_in_expr(expr, _rewrite_col)
+
+    new_group_by = [
+        _rewrite_expr(g) for g in (intent.group_by_cols or [])
+    ]
+
+    new_select_cols = []
+    for sc in intent.select_cols or []:
+        if sc.is_aggregated:
+            new_select_cols.append(sc)
+        else:
+            new_select_cols.append(replace(sc, expr=_rewrite_expr(sc.expr)))
+
+    return replace(
+        intent,
+        select_cols=new_select_cols,
+        group_by_cols=new_group_by,
+    )
+
+
+def prune_unreferenced_tables(
+    intent: RuntimeIntent,
+    schema_graph: SchemaGraph | None = None,
+) -> RuntimeIntent:
+    """Synchronize the tables list with tables actually referenced in
+    expressions.
+
+    Any table referenced in any clause (select, filter, group_by,
+    having, order_by) is kept.  Tables present in the intent but not
+    referenced anywhere are removed.  Missing referenced tables are
+    added.
+
+    Redundant PK aggregation columns are rewritten to their FK
+    equivalents when possible, which may eliminate a table reference
+    and thus the table itself.
+
+    The same synchronization is applied to each CTE step
+    independently.
+    """
+    cte_names = {cte.cte_name for cte in (intent.cte_steps or [])}
+    select_cols = list(intent.select_cols or [])
+    referenced = (
+        _collect_referenced_tables(
+            select_cols,
+            intent.order_by_cols,
+            intent.group_by_cols,
+            intent.filters_param,
+            intent.having_param,
+        )
+        | cte_names
+    )
+    essential = (
+        _collect_essential_tables(
+            intent.order_by_cols,
+            intent.group_by_cols,
+            intent.filters_param,
+            intent.having_param,
+        )
+        | cte_names
+    )
+
+    select_only = referenced - essential
+
+    if schema_graph and select_only:
+        all_intent = set(intent.tables or [])
+        select_cols, eliminated = _rewrite_redundant_pk_aggregations(
+            select_cols,
+            select_only,
+            essential,
+            schema_graph,
+            all_intent_tables=all_intent,
+        )
+        if eliminated:
+            referenced = (
+                _collect_referenced_tables(
+                    select_cols,
+                    intent.order_by_cols,
+                    intent.group_by_cols,
+                    intent.filters_param,
+                    intent.having_param,
+                )
+                | cte_names
+            )
+            select_only = referenced - essential
+
+    kept_tables = referenced
+    new_select_cols = select_cols
+
+    original = set(intent.tables or [])
+    added = (kept_tables - original) - cte_names
+    removed = original - kept_tables
+    main_tables = sorted(kept_tables)
+    if added:
+        debug(f"[prune_unreferenced_tables] added {sorted(added)} to tables")
+    if removed:
+        debug(f"[prune_unreferenced_tables] removed {sorted(removed)} from tables")
+    if added or removed:
+        debug(f"[prune_unreferenced_tables] final tables: {main_tables}")
+
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_referenced = (
+            _collect_referenced_tables(
+                cte.select_cols,
+                cte.order_by_cols,
+                cte.group_by_cols,
+                cte.filters_param,
+                cte.having_param,
+            )
+            | cte_names
+        )
+        cte_original = set(cte.tables or [])
+        cte_added = (cte_referenced - cte_original) - cte_names
+        cte_removed = cte_original - cte_referenced
+        cte_tables = sorted(cte_referenced)
+        if cte_added:
+            debug(f"[prune_unreferenced_tables] CTE '{cte.cte_name}' added {sorted(cte_added)} to tables")
+        if cte_removed:
+            debug(f"[prune_unreferenced_tables] CTE '{cte.cte_name}' removed {sorted(cte_removed)} from tables")
+        new_cte_steps.append(replace(cte, tables=cte_tables))
+
+    return replace(
+        intent,
+        tables=main_tables,
+        select_cols=new_select_cols,
+        cte_steps=new_cte_steps,
+    )
+
+
+def _correct_value_case(raw_value: str, top_k: list[str]) -> str | None:
+    """Return the case-corrected version of a filter value using
+    profiled sample values.
+
+    Performs a case-insensitive comparison of ``raw_value`` against each
+    entry in ``top_k``.  When a match is found whose casing differs from
+    the original, the sample value is returned so the filter uses the
+    casing that actually appears in the database.
+
+    Args:     raw_value: The filter value string extracted from the user
+    question.     top_k: Profiled sample values
+    (``ColumnMetadata.top_k_values``) for the         column being
+    filtered.
+
+    Returns:     The matching sample string with correct casing, or
+    ``None`` when no     case-insensitive match is found or the casing
+    already matches.
+    """
+    if not raw_value or not top_k:
+        return None
+    lower_val = raw_value.lower()
+    for sample in top_k:
+        if sample.lower() == lower_val and sample != raw_value:
+            return sample
+    return None
+
+
+def _match_enum_value(raw_value: str, col_meta: ColumnMetadata, schema_graph: SchemaGraph) -> str | None:
+    """Case-insensitive match of *raw_value* against the column's enum
+    type values.
+
+    Looks up ``col_meta.data_type`` in ``schema_graph.enum_values``.
+    When the column belongs to a defined enum type, returns the enum
+    member whose casing matches the database definition.
+
+    Args:     raw_value: Filter value string extracted from the user
+    question.     col_meta: Column metadata for the filter target
+    column.     schema_graph: Schema graph holding ``enum_values``.
+
+    Returns:     The correctly-cased enum member, or ``None`` when no
+    match is found or     the column is not an enum type.
+    """
+    if not schema_graph.enum_values:
+        return None
+    dtype_lower = (col_meta.data_type or "").lower()
+    enum_vals = schema_graph.enum_values.get(dtype_lower)
+    if not enum_vals:
+        return None
+    raw_lower = raw_value.lower()
+    for ev in enum_vals:
+        if ev.lower() == raw_lower:
+            return ev
+    return None
+
+
+def _extract_question_casing(raw_value: str, question: str) -> str | None:
+    """Extract the user's original casing for a filter value from the
+    question text.
+
+    Searches *question* for *raw_value* (case-insensitive).  When a
+    match is found and the matched substring contains at least one
+    uppercase letter, returns it so the filter preserves the user's
+    intended casing.  When the matched substring is entirely lowercase
+    the result is ``None`` so that downstream tiers (e.g. ILIKE
+    fallback) can still apply.
+
+    Args:     raw_value: Filter value string to locate.     question:
+    Original natural-language question.
+
+    Returns:     The matched substring from *question* with its original
+    casing, or ``None``     when no match is found, the match is all-
+    lowercase, or the casing already     equals *raw_value*.
+    """
+    if not raw_value or not question:
+        return None
+    q_lower = question.lower()
+    val_lower = raw_value.lower()
+    idx = q_lower.find(val_lower)
+    if idx < 0:
+        return None
+    matched = question[idx : idx + len(val_lower)]
+    if matched == matched.lower():
+        return None
+    if matched == raw_value:
+        return None
+    return matched
+
+
+def _resolve_filter_list_cascade(
+    filters: list[FilterParam],
+    schema_graph: SchemaGraph,
+    question: str,
+) -> tuple[list[FilterParam], bool]:
+    """Resolve string filter values to database-safe casing.
+
+    For each eligible string/enum filter the function first checks for
+    an enum-type match (tier 1) which preserves the exact database
+    casing. When no enum match exists, the raw_value is lowercased so
+    the SQL prompt can pair it with a ``LOWER(column)`` wrapper for
+    case-insensitive comparison.
+
+    Args:     filters: List of ``FilterParam`` objects to inspect and
+    correct.     schema_graph: Schema graph with enum and profiled
+    column data.     question: Original natural-language question.
+
+    Returns:     Tuple of ``(resolved_filters, changed)`` where
+    *changed* is ``True``     when at least one filter was modified.
+    """
+    new_filters: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        if fp.raw_value is None or fp.value_type not in {"string", "enum"}:
+            new_filters.append(fp)
+            continue
+        col = fp.left_expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            new_filters.append(fp)
+            continue
+        col_meta = schema_graph.get_column(parts[0], parts[1])
+        if not col_meta:
+            new_filters.append(fp)
+            continue
+
+        if isinstance(fp.raw_value, list):
+            new_vals: list = []
+            list_changed = False
+            for v in fp.raw_value:
+                if not isinstance(v, str):
+                    new_vals.append(v)
+                    continue
+                enum_match = _match_enum_value(v, col_meta, schema_graph)
+                if enum_match is not None:
+                    if enum_match != v:
+                        list_changed = True
+                    new_vals.append(enum_match)
+                else:
+                    lowered = v.lower()
+                    if lowered != v:
+                        list_changed = True
+                    new_vals.append(lowered)
+            if list_changed:
+                new_filters.append(replace(fp, raw_value=new_vals))
+                changed = True
+                debug(f"[intent_repair.resolve_filter_list_cascade] resolved list values on {col}")
+            else:
+                new_filters.append(fp)
+            continue
+
+        if not isinstance(fp.raw_value, str):
+            new_filters.append(fp)
+            continue
+
+        enum_match = _match_enum_value(fp.raw_value, col_meta, schema_graph)
+        if enum_match is not None:
+            if enum_match != fp.raw_value:
+                new_filters.append(replace(fp, raw_value=enum_match))
+                changed = True
+                debug(f"[intent_repair.resolve_filter_list_cascade] enum {col}: '{fp.raw_value}' -> '{enum_match}'")
+            else:
+                new_filters.append(fp)
+            continue
+
+        lowered = fp.raw_value.lower()
+        if lowered != fp.raw_value:
+            new_filters.append(replace(fp, raw_value=lowered))
+            changed = True
+            debug(f"[intent_repair.resolve_filter_list_cascade] lower {col}: '{fp.raw_value}' -> '{lowered}'")
+        else:
+            new_filters.append(fp)
+    return new_filters, changed
+
+
+def resolve_filter_value_case(intent: RuntimeIntent, schema_graph: SchemaGraph, question: str) -> RuntimeIntent:
+    """Resolve string filter values across the main query and CTE steps.
+
+    Tier 1 — enum match via ``schema_graph.enum_values`` preserves exact
+    database casing.  All other string filters have their raw_value
+    lowercased so the SQL generator can pair them with ``LOWER(column)``
+    for case-insensitive comparison.
+
+    Args:     intent: ``RuntimeIntent`` whose filter values may have
+    incorrect casing.     schema_graph: Schema graph with enum and
+    profiled column data.     question: Original natural-language
+    question.
+
+    Returns:     Updated ``RuntimeIntent`` with resolved filter value
+    casing, or the     original intent unchanged when no corrections are
+    needed.
+    """
+
+    def process(filters: list[FilterParam]) -> tuple[list[FilterParam], bool]:
+        return _resolve_filter_list_cascade(filters, schema_graph, question)
+
+    return _apply_filters_to_main_and_ctes(intent, process)
+
+
+def _coerce_element(val: Any, data_type: str) -> Any:
+    """Coerce a single IN-list element to match the column's data type.
+
+    When the column is numeric, strings that look like numbers are cast
+    to ``int`` or ``float``.  Non-castable values are returned
+    unchanged.
+
+    Args:     val: Single element from an IN-list raw_value.
+    data_type: Lowercased column data_type string.
+
+    Returns:     Coerced value, or the original value if coercion is not
+    applicable.
+    """
+    if data_type not in NUMERIC_DATA_TYPES:
+        return val
+    if isinstance(val, (int, float)):
+        return val
+    if not isinstance(val, str):
+        return val
+    stripped = val.strip()
+    try:
+        if "." in stripped:
+            return float(stripped)
+        return int(stripped)
+    except (ValueError, OverflowError):
+        return val
+
+
+def _consolidate_in_list(vals: list, data_type: str) -> str:
+    """Convert a list of IN-values into a formatted SQL-ready string.
+
+    String elements are wrapped in single quotes (``'R', 'PG-13'``),
+    while numeric elements are joined as-is (``1, 2, 3``).
+
+    Args:     vals: List of IN-list elements (already type-coerced).
+    data_type: Lowercased column data_type for formatting decisions.
+
+    Returns:     Comma-separated string suitable for direct SQL
+    substitution.
+    """
+    if all(isinstance(v, (int, float)) for v in vals):
+        return ", ".join(str(v) for v in vals)
+    parts: list[str] = []
+    for v in vals:
+        if isinstance(v, str):
+            parts.append(f"'{v}'")
+        else:
+            parts.append(str(v))
+    return ", ".join(parts)
+
+
+def _normalize_in_types_for_list(
+    filters: list[FilterParam],
+    schema_graph: SchemaGraph,
+) -> tuple[list[FilterParam], bool]:
+    """Coerce IN / NOT IN list elements to match their column types and
+    consolidate to strings.
+
+    For each filter with ``op`` in (``in``, ``not in``) and a list
+    ``raw_value``, each element is coerced to the column's native type.
+    The list is then consolidated into a formatted SQL string so
+    ``substitute_params`` can perform direct substitution.
+
+    Args:     filters: Filter params to inspect and coerce.
+    schema_graph: Schema graph for column type lookup.
+
+    Returns:     Tuple of ``(coerced_filters, changed)``.
+    """
+    new_filters: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        if fp.op.lower() not in {"in", "not in"} or not isinstance(fp.raw_value, list):
+            new_filters.append(fp)
+            continue
+        col = fp.left_expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            new_filters.append(fp)
+            continue
+        col_meta = schema_graph.get_column(parts[0], parts[1])
+        dtype = (col_meta.data_type or "").lower() if col_meta else ""
+        coerced = [_coerce_element(v, dtype) for v in fp.raw_value]
+        consolidated = _consolidate_in_list(coerced, dtype)
+        if consolidated != fp.raw_value:
+            new_filters.append(replace(fp, raw_value=consolidated))
+            changed = True
+            debug(f"[intent_resolve_normalize_in_types_for_list] {col}: {fp.raw_value!r} -> {consolidated!r}")
+        else:
+            new_filters.append(fp)
+    return new_filters, changed
+
+
+def normalize_in_filter_types(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Coerce IN / NOT IN list elements and consolidate across main
+    query and CTE steps.
+
+    Args:     intent: RuntimeIntent whose IN-list filter values may need
+    type coercion.     schema_graph: Schema graph for column type
+    lookup.
+
+    Returns:     Updated RuntimeIntent with coerced and consolidated IN-
+    list values.
+    """
+
+    def process(filters: list[FilterParam]) -> tuple[list[FilterParam], bool]:
+        return _normalize_in_types_for_list(filters, schema_graph)
+
+    intent = _apply_filters_to_main_and_ctes(intent, process)
+    return decompose_in_not_in_filters(intent)
+
+
+def _decompose_in_list(
+    filters: list[FilterParam],
+    max_list_size: int = 10,
+) -> list[FilterParam]:
+    """Expand small IN / NOT IN lists into primitive comparisons.
+
+    For ``IN`` with a short raw_value list, creates one ``=`` filter per
+    element combined with ``OR``. For ``NOT IN`` with a short list,
+    creates ``!=`` filters combined with ``AND``. Large lists are left
+    unchanged.
+    """
+    new_filters: list[FilterParam] = []
+    for fp in filters:
+        raw = fp.raw_value
+        op_lower = (fp.op or "").lower()
+        if not isinstance(raw, list) or op_lower not in {"in", "not in"} or len(raw) == 0 or len(raw) > max_list_size:
+            new_filters.append(fp)
+            continue
+        elems = list(raw)
+        bool_op = "OR" if op_lower == "in" else "AND"
+        new_group = []
+        for idx, val in enumerate(elems):
+            new_fp = replace(
+                fp,
+                op="=" if op_lower == "in" else "!=",
+                raw_value=val,
+                bool_op=bool_op if idx > 0 else (fp.bool_op or "AND"),
+            )
+            new_group.append(new_fp)
+        new_filters.extend(new_group)
+    return new_filters
+
+
+def decompose_in_not_in_filters(intent: RuntimeIntent) -> RuntimeIntent:
+    """Decompose small IN / NOT IN lists across main query and CTE steps."""
+    main_filters = _decompose_in_list(intent.filters_param or [])
+    new_ctes: list[RuntimeCteStep] = []
+    for cte in intent.cte_steps or []:
+        decomposed = _decompose_in_list(cte.filters_param or [])
+        new_ctes.append(replace(cte, filters_param=decomposed))
+    return replace(intent, filters_param=main_filters, cte_steps=new_ctes or intent.cte_steps)
+
+
+def _resolve_boolean_value(raw_value: Any, col_meta: ColumnMetadata) -> tuple[Any, str] | None:
+    """Resolve a filter raw_value to a Python ``bool`` for a native
+    boolean column.
+
+    Only applies to columns whose ``data_type`` contains ``"bool"``.
+    Converts common truthy/falsy representations (integers, strings,
+    Python bools) to ``True``/``False`` and sets the value_type to
+    ``"boolean"`` so that ``substitute_params`` emits the SQL literal
+    ``TRUE`` or ``FALSE``.
+
+    Args:     raw_value: The current filter value (int, str, bool, or
+    other).     col_meta: Column metadata for the filter target column.
+
+    Returns:     Tuple of ``(resolved_value, "boolean")`` when
+    conversion succeeds,     or ``None`` when the column is not a native
+    boolean or the value     cannot be mapped.
+    """
+    dtype_lower = (col_meta.data_type or "").lower()
+    if "bool" not in dtype_lower:
+        return None
+    if isinstance(raw_value, bool):
+        return raw_value, "boolean"
+    val_str = str(raw_value).lower().strip()
+    if val_str in BOOLEAN_TRUTHY_VALUES:
+        return True, "boolean"
+    if val_str in BOOLEAN_FALSY_VALUES:
+        return False, "boolean"
+    return None
+
+
+def _normalize_boolean_filter_list(
+    filters: list[FilterParam], schema_graph: SchemaGraph
+) -> tuple[list[FilterParam], bool]:
+    """Normalise boolean filter values in a list of ``FilterParam``
+    objects.
+
+    For each filter targeting a native boolean column whose
+    ``raw_value`` is not already a Python ``bool``, converts the value
+    and sets ``value_type`` to ``"boolean"``.
+
+    Args:     filters: List of ``FilterParam`` objects to inspect and
+    correct.     schema_graph: ``SchemaGraph`` providing column
+    metadata.
+
+    Returns:     Tuple of ``(normalised_filters, changed)`` where
+    *changed* is ``True``     when at least one filter was rewritten.
+    """
+    new_filters: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        if fp.raw_value is None:
+            new_filters.append(fp)
+            continue
+        col = fp.left_expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            new_filters.append(fp)
+            continue
+        col_meta = schema_graph.get_column(parts[0], parts[1])
+        if not col_meta:
+            new_filters.append(fp)
+            continue
+        resolved = _resolve_boolean_value(fp.raw_value, col_meta)
+        if resolved is None:
+            new_filters.append(fp)
+            continue
+        bool_val, vtype = resolved
+        new_filters.append(replace(fp, raw_value=bool_val, value_type=vtype))
+        changed = True
+        debug(
+            f"[intent_resolve_normalize_boolean_filter_list] {col}: "
+            f"{fp.raw_value!r} ({fp.value_type}) → {bool_val!r} ({vtype})"
+        )
+    return new_filters, changed
+
+
+def normalize_boolean_filter_values(intent: RuntimeIntent, schema_graph: SchemaGraph) -> RuntimeIntent:
+    """Normalise boolean filter values across the main query and CTE
+    steps.
+
+    LLM-extracted intents frequently represent boolean filters as
+    integers.  For native boolean columns these must become Python
+    ``True``/``False`` with ``value_type="boolean"`` so that
+    ``substitute_params`` emits the SQL literal ``TRUE`` or ``FALSE``
+    rather than an integer or quoted string.
+
+    Args:     intent: ``RuntimeIntent`` whose filter values may need
+    boolean         normalisation.     schema_graph: ``SchemaGraph``
+    providing column data-type metadata.
+
+    Returns:     Updated ``RuntimeIntent`` with normalised boolean
+    filter values, or     the original intent unchanged when no
+    corrections are needed.
+    """
+
+    def process(filters: list[FilterParam]) -> tuple[list[FilterParam], bool]:
+        return _normalize_boolean_filter_list(filters, schema_graph)
+
+    return _apply_filters_to_main_and_ctes(intent, process)
+
+
+def _normalize_null_filter_list(
+    filters: list[FilterParam],
+) -> tuple[list[FilterParam], bool]:
+    """Normalise IS NULL / IS NOT NULL filters to canonical form.
+
+    Ensures ``value_type`` is ``"null"`` and ``raw_value`` is ``None``
+    for any filter whose operator is ``"is null"`` or ``"is not null"``.
+    """
+    result: list[FilterParam] = []
+    changed = False
+    for fp in filters:
+        if fp.op in ("is null", "is not null"):
+            needs_fix = fp.value_type != "null" or fp.raw_value is not None
+            if needs_fix:
+                result.append(replace(fp, value_type="null", raw_value=None))
+                changed = True
+                continue
+        result.append(fp)
+    return result, changed
+
+
+def normalize_null_filter_values(intent: RuntimeIntent) -> RuntimeIntent:
+    """Normalise null-operator filters across main query and CTE steps.
+
+    Ensures every ``IS NULL`` / ``IS NOT NULL`` filter carries
+    ``value_type="null"`` and ``raw_value=None`` so downstream
+    validation does not flag a spurious type mismatch.
+    """
+    return _apply_filters_to_main_and_ctes(intent, _normalize_null_filter_list)