aetherdialect 0.1.0__py3-none-any.whl

text2sql/intent_expr.py

@@ -0,0 +1,1759 @@
+"""Expression parsing, algebraic structure, and intent response parsing.
+
+Parses SQL-like expression strings such as SUM(t.col) or t.a + t.b into NormalizedExpr and MulGroup trees via parse_expr_string. Tags expressions as numeric or non-numeric, assigns structural param keys such as s1 and s2, and ensures scalar function defaults. Parses LLM JSON responses into RuntimeIntent via parse_intent_response and handles BETWEEN decomposition, IN-list normalization, and CTE output column and metadata derivation.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+import jsonschema
+
+from .config import (
+    CTE_DEFAULT_AGGS,
+    CTE_FULL_AGGS,
+    CTE_HAVING_COMPARE_OPS,
+    CTE_NUMERIC_FILTER_OPS,
+    DATE_UNIT_KEYWORDS,
+    IN_OPS,
+    IN_STRING_SEPARATORS,
+    INTEGER_SCALARS,
+    INTENT_SCHEMA,
+    NUMERIC_RESULT_AGGS,
+    NUMERIC_RESULT_SCALARS,
+    SCALAR_FUNC_DEFAULTS,
+    SCALAR_FUNCTIONS_LEADING_ARG,
+    STRUCTURAL_IDENTITY_VALUES,
+    VALID_AGG_FUNCS,
+    VALID_DATE_DIFF_UNITS,
+    VALID_DATE_WINDOW_UNITS,
+)
+from .contracts_base import CteOutputColumnMeta, SchemaGraph
+from .contracts_core import (
+    ExprValue,
+    FilterParam,
+    HavingParam,
+    MulGroup,
+    NormalizedExpr,
+    OrderByCol,
+    RuntimeCteStep,
+    RuntimeIntent,
+    SelectCol,
+    Template,
+)
+from .core_utils import debug, normalize_op, safe_json_loads
+
+
+def _peel_function(s: str) -> tuple[str | None, int | float | str | None, str]:
+    """Strip the outermost FUNC(...) wrapper from an expression string.
+
+    Args:
+
+        s: SQL expression string that may be wrapped in a function call.
+
+    Returns:
+
+        Tuple of (func_name, trailing_arg, inner_body). func_name is None when no function wrapper is found; trailing_arg is the extracted numeric or string secondary argument if present; inner_body is the unwrapped content.
+    """
+    s = s.strip()
+    m = re.match(r"^([A-Za-z_]\w*)\s*\(", s)
+    if not m:
+        return None, None, s
+    func_name = m.group(1)
+    open_pos = m.end() - 1
+    depth = 0
+    for i in range(open_pos, len(s)):
+        if s[i] == "(":
+            depth += 1
+        elif s[i] == ")":
+            depth -= 1
+        if depth == 0:
+            if i != len(s) - 1:
+                return None, None, s
+            inner = s[open_pos + 1 : i]
+            if func_name.lower() == "extract" and re.search(r"\bfrom\b", inner, re.IGNORECASE):
+                from_parts = re.split(r"\s+from\s+", inner, maxsplit=1, flags=re.IGNORECASE)
+                if len(from_parts) == 2:
+                    return (
+                        func_name,
+                        from_parts[0].strip().strip("'\"").lower(),
+                        from_parts[1].strip(),
+                    )
+            parts: list[str] = []
+            d = 0
+            start = 0
+            for j, c in enumerate(inner):
+                if c == "(":
+                    d += 1
+                elif c == ")":
+                    d -= 1
+                elif c == "," and d == 0:
+                    parts.append(inner[start:j])
+                    start = j + 1
+            parts.append(inner[start:])
+            if len(parts) > 1:
+                first = parts[0].strip()
+                if (first.startswith("'") and first.endswith("'")) or (first.startswith('"') and first.endswith('"')):
+                    body = ",".join(parts[1:]).strip()
+                    return func_name, first.strip("'\""), body
+                last = parts[-1].strip()
+                try:
+                    num = float(last)
+                    arg: int | float = int(num) if num == int(num) else num
+                    body = ",".join(parts[:-1]).strip()
+                    return func_name, arg, body
+                except ValueError:
+                    pass
+                if (last.startswith("'") and last.endswith("'")) or (last.startswith('"') and last.endswith('"')):
+                    body = ",".join(parts[:-1]).strip()
+                    return func_name, last.strip("'\""), body
+            return func_name, None, inner.strip()
+    return None, None, s
+
+
+_TABLE_COLUMN_PATTERN = re.compile(r"\w+\.\w+")
+
+
+def _split_arithmetic_term_into_column_refs(term: str) -> list[str]:
+    """Return table.column refs from a term that may contain arithmetic.
+
+    If the term contains top-level " - " or " + ", extracts all
+    table.column substrings. Otherwise returns [term] when term
+    looks like table.column.
+    """
+    stripped = term.strip()
+    if not stripped or stripped == "*":
+        return []
+    if " - " in stripped or " + " in stripped:
+        return _TABLE_COLUMN_PATTERN.findall(stripped)
+    if _TABLE_COLUMN_PATTERN.fullmatch(stripped):
+        return [stripped]
+    return [stripped]
+
+
+_DATE_INTERVAL_PATTERNS = (
+    "current_date",
+    "current_timestamp",
+    "now()",
+    "sysdate",
+    "interval",
+    "localtimestamp",
+    "localtime",
+    "utc_timestamp",
+)
+
+
+def _is_date_or_interval_expr(s: str) -> bool:
+    """Return True if the string is a date or interval expression that should be kept as right_expr."""
+    if not s or not isinstance(s, str):
+        return False
+    lower = s.strip().lower()
+    return any(p in lower for p in _DATE_INTERVAL_PATTERNS)
+
+
+def extract_columns_from_expr(expr: NormalizedExpr) -> list[str]:
+    """Extract all column references from a NormalizedExpr, stripping function wrappers.
+
+    Traverses multiply and divide operands in every MulGroup, strips
+    parenthetical wrappers, and splits arithmetic terms into
+    table.column refs so schema validation accepts expression columns.
+
+    Args:
+
+        expr: NormalizedExpr to traverse.
+
+    Returns:
+
+        List of column reference strings, possibly qualified as table.column.
+    """
+    cols: list[str] = []
+    for group in expr.add_groups + expr.sub_groups:
+        for term in group.multiply + group.divide:
+            inner = term
+            while "(" in inner:
+                start = inner.index("(")
+                end = inner.rindex(")")
+                inner = inner[start + 1 : end]
+            for ref in _split_arithmetic_term_into_column_refs(inner):
+                if ref and ref not in cols:
+                    cols.append(ref)
+    return cols
+
+
+def replace_refs_in_expr(expr: NormalizedExpr, replacer: Callable[[str], str]) -> NormalizedExpr:
+    """Apply a string replacer to all column reference terms in a NormalizedExpr.
+
+    Args:
+
+        expr: NormalizedExpr whose MulGroup terms should be transformed.
+
+        replacer: Function that takes a term string and returns the replacement.
+
+    Returns:
+
+        New NormalizedExpr with all multiply and divide terms transformed.
+    """
+
+    def _replace_in_group(g: MulGroup) -> MulGroup:
+        return MulGroup(
+            coefficient=g.coefficient,
+            multiply=[replacer(m) for m in g.multiply],
+            divide=[replacer(d) for d in g.divide],
+            agg_func=g.agg_func,
+            scalar_func=g.scalar_func,
+            inner_scalar_func=g.inner_scalar_func,
+            scalar_func_args=list(g.scalar_func_args),
+            inner_scalar_func_args=list(g.inner_scalar_func_args),
+        )
+
+    return NormalizedExpr(
+        add_groups=[_replace_in_group(g) for g in expr.add_groups],
+        sub_groups=[_replace_in_group(g) for g in expr.sub_groups],
+        add_values=expr.add_values,
+        sub_values=expr.sub_values,
+        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 _split_additive(s: str) -> list[tuple[str, str]]:
+    """Split an expression string by top-level + and - operators.
+
+    Respects parenthesis nesting so operators inside function calls are ignored.
+
+    Args:
+
+        s: SQL expression string to split.
+
+    Returns:
+
+        List of (sign, term) tuples where sign is '+' or '-'.
+    """
+    s = s.strip()
+    if not s:
+        return [("+", "")]
+    result: list[tuple[str, str]] = []
+    depth = 0
+    sign = "+"
+    start = 0
+    i = 0
+    if s[0] in ("+", "-"):
+        sign = s[0]
+        start = 1
+        i = 1
+    while i < len(s):
+        c = s[i]
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+        elif depth == 0 and c in ("+", "-"):
+            term = s[start:i].strip()
+            if term:
+                result.append((sign, term))
+            sign = c
+            start = i + 1
+        i += 1
+    term = s[start:].strip()
+    if term:
+        result.append((sign, term))
+    return result or [("+", s)]
+
+
+def _split_multiplicative(s: str) -> tuple[list[str], list[str]]:
+    """Split an expression string by top-level * and / operators.
+
+    Respects parenthesis nesting so operators inside function calls are ignored.
+
+    Args:
+
+        s: SQL expression string to split.
+
+    Returns:
+
+        Tuple of (multiply_parts, divide_parts) where each element is a list of operand strings on either side of the respective operator.
+    """
+    s = s.strip()
+    if not s:
+        return ([""], [])
+    multiply: list[str] = []
+    divide: list[str] = []
+    depth = 0
+    op = "*"
+    start = 0
+    for i, c in enumerate(s):
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+        elif depth == 0 and c in ("*", "/"):
+            part = s[start:i].strip()
+            if part:
+                (multiply if op == "*" else divide).append(part)
+            op = c
+            start = i + 1
+    part = s[start:].strip()
+    if part:
+        (multiply if op == "*" else divide).append(part)
+    return multiply, divide
+
+
+def _parse_term(term_str: str) -> MulGroup | ExprValue:
+    """Parse a single additive term into a MulGroup or a literal ExprValue.
+
+    Args:
+
+        term_str: A single additive term string with no top-level plus or minus operator.
+
+    Returns:
+
+        ExprValue if the term is a plain numeric literal, otherwise a MulGroup describing the function layers, multiplicative operands, and coefficient.
+    """
+    term_str = term_str.strip()
+    try:
+        val = float(term_str)
+        return ExprValue(value=val)
+    except ValueError:
+        pass
+    layers: list[tuple[str, int | float | None]] = []
+    current = term_str
+    while True:
+        name, args, body = _peel_function(current)
+        if not name:
+            break
+        layers.append((name.lower(), args))
+        current = body
+    agg_func = ""
+    scalar_func = ""
+    scalar_func_args: list | None = None
+    inner_scalar_func = ""
+    inner_scalar_func_args: list | None = None
+    for name, args in layers:
+        if name in VALID_AGG_FUNCS:
+            agg_func = name
+        elif not scalar_func and not agg_func:
+            scalar_func = name
+            scalar_func_args = [args] if args is not None else []
+        else:
+            inner_scalar_func = name
+            inner_scalar_func_args = [args] if args is not None else []
+    mul_parts, div_parts = _split_multiplicative(current)
+    multiply: list[str] = []
+    divide: list[str] = []
+    coefficient = 1.0
+    for p in mul_parts:
+        try:
+            coefficient *= float(p)
+        except ValueError:
+            multiply.append(p)
+    for p in div_parts:
+        try:
+            coefficient /= float(p)
+        except ValueError:
+            divide.append(p)
+    return MulGroup(
+        multiply=multiply or ["*"],
+        divide=divide,
+        coefficient=coefficient,
+        agg_func=agg_func,
+        scalar_func=scalar_func,
+        inner_scalar_func=inner_scalar_func,
+        scalar_func_args=scalar_func_args or [],
+        inner_scalar_func_args=inner_scalar_func_args or [],
+    )
+
+
+def _is_trivial_zero(term: str) -> bool:
+    """Return True if the term string is a numeric literal equal to zero.
+
+    Args:
+
+        term: Additive term string.
+
+    Returns:
+
+        True when float(term) is 0.0 and False for non-numeric or non-zero strings.
+    """
+    try:
+        return float(term.strip()) == 0.0
+    except ValueError:
+        return False
+
+
+def parse_expr_string(expr_str: str | dict) -> NormalizedExpr:
+    """Parse an SQL expression string into a structured NormalizedExpr.
+
+    Handles nested function wrappers, additive and multiplicative decomposition, numeric coefficients, and aggregation or scalar function classification.
+
+    Args:
+
+        expr_str: SQL expression string as returned by the LLM, or a dict with an "expr" key.
+
+    Returns:
+
+        NormalizedExpr representing the expression tree.
+    """
+    if isinstance(expr_str, dict):
+        expr_str = expr_str.get("expr", "")
+    if not isinstance(expr_str, str):
+        expr_str = str(expr_str) if expr_str else ""
+    expr_str = expr_str.strip()
+    if not expr_str:
+        return NormalizedExpr()
+    outer_layers: list[tuple[str, int | float | str | None]] = []
+    inner = expr_str
+    while True:
+        name, args, body = _peel_function(inner)
+        if not name:
+            break
+        outer_layers.append((name.lower(), args))
+        inner = body
+    additive = _split_additive(inner)
+    additive = [(s, t) for s, t in additive if not _is_trivial_zero(t)]
+    if not additive:
+        additive = [("+", "0")]
+    if len(additive) == 1:
+        sign, t = additive[0]
+        parsed = _parse_term(t)
+        if isinstance(parsed, ExprValue):
+            if sign == "-":
+                return NormalizedExpr(sub_values=[ExprValue(value=abs(parsed.value))])
+            return NormalizedExpr(add_values=[parsed])
+        group = parsed
+        for name, args in outer_layers:
+            if name in VALID_AGG_FUNCS:
+                group.agg_func = name
+            elif not group.scalar_func and not group.agg_func:
+                group.scalar_func = name
+                group.scalar_func_args = [args] if args is not None else []
+            elif not group.scalar_func and group.agg_func:
+                group.scalar_func = name
+                group.scalar_func_args = [args] if args is not None else []
+            else:
+                group.inner_scalar_func = name
+                group.inner_scalar_func_args = [args] if args is not None else []
+        if sign == "-":
+            return NormalizedExpr(sub_groups=[group])
+        return NormalizedExpr(add_groups=[group])
+    add_groups: list[MulGroup] = []
+    sub_groups: list[MulGroup] = []
+    add_values: list[ExprValue] = []
+    sub_values: list[ExprValue] = []
+    for sign, t in additive:
+        parsed = _parse_term(t)
+        if isinstance(parsed, ExprValue):
+            (add_values if sign == "+" else sub_values).append(parsed)
+        else:
+            (add_groups if sign == "+" else sub_groups).append(parsed)
+    expr_agg = ""
+    expr_scalar = ""
+    expr_scalar_args: list | None = None
+    expr_inner = ""
+    expr_inner_args: list | None = None
+    for name, args in outer_layers:
+        if name in VALID_AGG_FUNCS:
+            expr_agg = name
+        elif not expr_scalar and not expr_agg:
+            expr_scalar = name
+            expr_scalar_args = [args] if args is not None else []
+        elif not expr_scalar and expr_agg:
+            expr_scalar = name
+            expr_scalar_args = [args] if args is not None else []
+        else:
+            expr_inner = name
+            expr_inner_args = [args] if args is not None else []
+    return NormalizedExpr(
+        add_groups=add_groups,
+        sub_groups=sub_groups,
+        add_values=add_values,
+        sub_values=sub_values,
+        agg_func=expr_agg,
+        scalar_func=expr_scalar,
+        inner_scalar_func=expr_inner,
+        scalar_func_args=expr_scalar_args or [],
+        inner_scalar_func_args=expr_inner_args or [],
+    )
+
+
+def _is_expr_numeric(expr: NormalizedExpr, schema: SchemaGraph) -> bool:
+    """Determine whether an expression produces a numeric result.
+
+    Checks aggregation functions known to return numbers, scalar functions that return numeric types, and the value_type of the underlying column in the schema.
+
+    Args:
+
+        expr: NormalizedExpr to classify.
+        schema: SchemaGraph used to look up column value_type metadata.
+
+    Returns:
+
+        True when the expression is expected to yield a numeric value.
+    """
+    if expr.agg_func and expr.agg_func in NUMERIC_RESULT_AGGS:
+        return True
+    if expr.scalar_func and expr.scalar_func in NUMERIC_RESULT_SCALARS:
+        return True
+    if expr.inner_scalar_func and expr.inner_scalar_func in NUMERIC_RESULT_SCALARS:
+        return True
+    for g in expr.add_groups + expr.sub_groups:
+        if g.agg_func and g.agg_func in NUMERIC_RESULT_AGGS:
+            return True
+        if g.scalar_func and g.scalar_func in NUMERIC_RESULT_SCALARS:
+            return True
+        if g.inner_scalar_func and g.inner_scalar_func in NUMERIC_RESULT_SCALARS:
+            return True
+    col = expr.primary_column
+    if col and "." in col:
+        table, col_name = col.rsplit(".", 1)
+        if table in schema.tables:
+            meta = schema.tables[table].columns.get(col_name) or schema.tables[table].columns.get(col_name.lower())
+            if meta and meta.value_type:
+                return meta.value_type in ("integer", "number")
+    return len(expr.add_groups) + len(expr.sub_groups) > 1
+
+
+def _tag_single_expr(expr: NormalizedExpr, schema: SchemaGraph, skip_value_injection: bool = False) -> NormalizedExpr:
+    """Set is_numeric, inject offset for numeric expressions, and sanitize non-numeric ones.
+
+    For numeric expressions that have groups but no offset value, injects an ExprValue(0.0) to anchor the signature unless skip_value_injection is True. For non-numeric expressions, strips any coefficient or coeff_param_key and removes add_values and sub_values.
+
+    Args:
+
+        expr: NormalizedExpr to tag.
+        schema: SchemaGraph used to determine numeric classification.
+        skip_value_injection: When True, numeric expressions are tagged but no ExprValue(0.0) offset is injected and this is used for filter and having left_expr where values are handled via param_key instead.
+
+    Returns:
+
+        Updated NormalizedExpr with is_numeric set and appropriate sanitization applied.
+    """
+    numeric = _is_expr_numeric(expr, schema)
+    if numeric:
+        if skip_value_injection:
+            return replace(expr, is_numeric=True)
+        need_offset = expr.add_groups and not expr.add_values
+        return replace(
+            expr,
+            is_numeric=True,
+            add_values=[ExprValue(value=0.0)] if need_offset else expr.add_values,
+        )
+    sanitized_groups = [
+        (replace(g, coefficient=1.0, coeff_param_key="") if g.coefficient != 1.0 or g.coeff_param_key else g)
+        for g in expr.add_groups
+    ]
+    sanitized_sub_groups = [
+        (replace(g, coefficient=1.0, coeff_param_key="") if g.coefficient != 1.0 or g.coeff_param_key else g)
+        for g in expr.sub_groups
+    ]
+    return replace(
+        expr,
+        is_numeric=False,
+        add_groups=sanitized_groups,
+        sub_groups=sanitized_sub_groups,
+        add_values=[],
+        sub_values=[],
+    )
+
+
+def tag_expr_numeric(intent: RuntimeIntent, schema: SchemaGraph) -> RuntimeIntent:
+    """Apply is_numeric tagging and offset injection to all expressions in a RuntimeIntent.
+
+    Args:
+
+        intent: RuntimeIntent whose select, order_by, group_by, filter, having, and CTE expressions should be tagged.
+        schema: SchemaGraph used for column type lookups.
+
+    Returns:
+
+        New RuntimeIntent with all NormalizedExprs tagged and sanitized.
+    """
+    select_cols = [replace(sc, expr=_tag_single_expr(sc.expr, schema)) for sc in (intent.select_cols or [])]
+    order_by_cols = [replace(obc, expr=_tag_single_expr(obc.expr, schema)) for obc in (intent.order_by_cols or [])]
+    group_by_cols = [_tag_single_expr(g, schema) for g in (intent.group_by_cols or [])]
+    filters_param = []
+    for fp in intent.filters_param or []:
+        left = _tag_single_expr(fp.left_expr, schema, skip_value_injection=True)
+        right = _tag_single_expr(fp.right_expr, schema) if fp.right_expr else None
+        filters_param.append(replace(fp, left_expr=left, right_expr=right))
+    having_param = []
+    for hp in intent.having_param or []:
+        left = _tag_single_expr(hp.left_expr, schema, skip_value_injection=True)
+        right = _tag_single_expr(hp.right_expr, schema) if hp.right_expr else None
+        having_param.append(replace(hp, left_expr=left, right_expr=right))
+    cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_sc = [replace(sc, expr=_tag_single_expr(sc.expr, schema)) for sc in (cte.select_cols or [])]
+        cte_obc = [replace(obc, expr=_tag_single_expr(obc.expr, schema)) for obc in (cte.order_by_cols or [])]
+        cte_gb = [_tag_single_expr(g, schema) for g in (cte.group_by_cols or [])]
+        cte_fp = []
+        for fp in cte.filters_param or []:
+            left = _tag_single_expr(fp.left_expr, schema, skip_value_injection=True)
+            right = _tag_single_expr(fp.right_expr, schema) if fp.right_expr else None
+            cte_fp.append(replace(fp, left_expr=left, right_expr=right))
+        cte_hp = []
+        for hp in cte.having_param or []:
+            left = _tag_single_expr(hp.left_expr, schema, skip_value_injection=True)
+            right = _tag_single_expr(hp.right_expr, schema) if hp.right_expr else None
+            cte_hp.append(replace(hp, left_expr=left, right_expr=right))
+        cte_steps.append(
+            replace(
+                cte,
+                select_cols=cte_sc,
+                order_by_cols=cte_obc,
+                group_by_cols=cte_gb,
+                filters_param=cte_fp,
+                having_param=cte_hp,
+            )
+        )
+    return replace(
+        intent,
+        select_cols=select_cols,
+        order_by_cols=order_by_cols,
+        group_by_cols=group_by_cols,
+        filters_param=filters_param,
+        having_param=having_param,
+        cte_steps=cte_steps,
+    )
+
+
+def _classify_cte_expr(expr: NormalizedExpr) -> str:
+    """Classify a CTE select expression by its structural type.
+
+    Args:
+
+        expr: NormalizedExpr from a CTE SelectCol.
+
+    Returns:
+
+        One of 'passthrough', 'aggregation', 'scalar', or 'computed'.
+    """
+    agg = expr.agg_func or (expr.add_groups[0].agg_func if expr.add_groups else "")
+    has_arithmetic = (
+        len(expr.add_groups) + len(expr.sub_groups) > 1
+        or expr.add_values
+        or expr.sub_values
+        or any(g.divide or len(g.multiply) > 1 or g.coefficient != 1.0 for g in expr.add_groups)
+    )
+    if agg:
+        return "aggregation"
+    if has_arithmetic:
+        return "computed"
+    scalar = expr.scalar_func or (expr.add_groups[0].scalar_func if expr.add_groups else "")
+    if scalar:
+        return "scalar"
+    return "passthrough"
+
+
+def derive_cte_output_columns(select_cols: list[SelectCol]) -> list[str]:
+    """Derive deterministic CTE output column aliases from parsed select expressions.
+
+    Generates names like sum_amount, count_star, or expr1 based on the expression type and base column name and deduplicates by appending a numeric suffix.
+
+    Args:
+
+        select_cols: List of SelectCol objects from a CTE step.
+
+    Returns:
+
+        List of lowercase alias strings, one per SelectCol.
+    """
+    derived: list[str] = []
+    seen: dict[str, int] = {}
+    expr_counter = 0
+    for sc in select_cols:
+        expr = sc.expr
+        kind = _classify_cte_expr(expr)
+        agg = expr.agg_func or (expr.add_groups[0].agg_func if expr.add_groups else "")
+        scalar = expr.scalar_func or (expr.add_groups[0].scalar_func if expr.add_groups else "")
+        base = expr.primary_column
+        if kind == "aggregation":
+            if base == "*":
+                name = "row_count" if agg == "count" else f"{agg}_star"
+            elif "." in base:
+                bare = base.split(".", 1)[1]
+                name = f"{agg}_{bare}"
+            else:
+                name = f"{agg}_{base}"
+        elif kind == "scalar":
+            if "." in base:
+                bare = base.split(".", 1)[1]
+                name = f"{scalar}_{bare}"
+            else:
+                name = f"{scalar}_{base}"
+        elif kind == "computed":
+            expr_counter += 1
+            name = f"expr{expr_counter}"
+        else:
+            if "." in base:
+                name = base.split(".", 1)[1]
+            else:
+                name = base
+        name = name.lower()
+        if name in seen:
+            seen[name] += 1
+            name = f"{name}_{seen[name]}"
+        else:
+            seen[name] = 1
+        derived.append(name)
+    return derived
+
+
+def build_cte_output_metadata(
+    select_cols: list[SelectCol], output_columns: list[str], schema: SchemaGraph
+) -> dict[str, CteOutputColumnMeta]:
+    """Build CteOutputColumnMeta for each CTE output column.
+
+    Infers column role, data type, and allowed operations from the expression kind (passthrough, aggregation, scalar, or computed) and the source column schema metadata.
+
+    Args:
+
+        select_cols: CTE select expressions.
+        output_columns: Derived alias names aligned with select_cols.
+        schema: SchemaGraph for source column lookups.
+
+    Returns:
+
+        Dictionary mapping output column alias to its CteOutputColumnMeta.
+    """
+    result: dict[str, CteOutputColumnMeta] = {}
+    for i, sc in enumerate(select_cols):
+        if i >= len(output_columns):
+            break
+        out_col = output_columns[i]
+        expr = sc.expr
+        kind = _classify_cte_expr(expr)
+        agg = expr.agg_func or (expr.add_groups[0].agg_func if expr.add_groups else "")
+        scalar = expr.scalar_func or (expr.add_groups[0].scalar_func if expr.add_groups else "")
+        base_col = expr.primary_column
+        src_meta = None
+        base_type = "unknown"
+        if "." in base_col and base_col != "*":
+            tbl, col = base_col.split(".", 1)
+            if tbl in schema.tables:
+                src_meta = schema.tables[tbl].columns.get(col) or schema.tables[tbl].columns.get(col.lower())
+                if src_meta and src_meta.data_type:
+                    base_type = src_meta.data_type.lower().split("(")[0].strip()
+        if kind == "passthrough":
+            role = src_meta.role if src_meta else None
+            data_type = base_type
+            filterable = src_meta.is_filterable if src_meta else True
+            aggregatable = src_meta.is_aggregatable if src_meta else False
+            groupable = src_meta.is_groupable if src_meta else True
+            vf_ops = list(src_meta.get_valid_filter_ops()) if src_meta else list(CTE_NUMERIC_FILTER_OPS)
+            v_aggs = sorted(src_meta.get_valid_aggregations()) if src_meta else list(CTE_DEFAULT_AGGS)
+            vh_ops = list(src_meta.get_valid_having_ops()) if src_meta else list(CTE_HAVING_COMPARE_OPS)
+        elif kind == "aggregation":
+            role = "numeric_measure"
+            if agg == "count":
+                data_type = "integer"
+            elif agg == "avg":
+                data_type = "numeric"
+            elif agg in ("sum", "min", "max") and base_type != "unknown":
+                data_type = base_type
+            else:
+                data_type = "integer" if agg == "count" else "numeric"
+            filterable = True
+            aggregatable = True
+            groupable = False
+            vf_ops = list(CTE_NUMERIC_FILTER_OPS)
+            v_aggs = list(CTE_FULL_AGGS)
+            vh_ops = list(CTE_HAVING_COMPARE_OPS)
+        elif kind == "scalar":
+            if scalar in NUMERIC_RESULT_SCALARS:
+                role = "numeric_measure"
+                data_type = "integer" if scalar in INTEGER_SCALARS else "numeric"
+                aggregatable = True
+                groupable = False
+                vf_ops = list(CTE_NUMERIC_FILTER_OPS)
+                v_aggs = list(CTE_FULL_AGGS)
+                vh_ops = list(CTE_HAVING_COMPARE_OPS)
+            else:
+                role = src_meta.role if src_meta else None
+                data_type = base_type
+                aggregatable = src_meta.is_aggregatable if src_meta else False
+                groupable = src_meta.is_groupable if src_meta else True
+                vf_ops = list(src_meta.get_valid_filter_ops()) if src_meta else list(CTE_NUMERIC_FILTER_OPS)
+                v_aggs = sorted(src_meta.get_valid_aggregations()) if src_meta else list(CTE_DEFAULT_AGGS)
+                vh_ops = list(src_meta.get_valid_having_ops()) if src_meta else list(CTE_HAVING_COMPARE_OPS)
+            filterable = True
+        else:
+            role = "numeric_measure"
+            data_type = "numeric"
+            filterable = True
+            aggregatable = True
+            groupable = False
+            vf_ops = list(CTE_NUMERIC_FILTER_OPS)
+            v_aggs = list(CTE_FULL_AGGS)
+            vh_ops = list(CTE_HAVING_COMPARE_OPS)
+        result[out_col] = CteOutputColumnMeta(
+            source=kind,
+            base_column=base_col,
+            agg_func=agg,
+            role=role,
+            filterable=filterable,
+            aggregatable=aggregatable,
+            data_type=data_type,
+            groupable=groupable,
+            valid_filter_ops=vf_ops,
+            valid_aggregations=v_aggs,
+            valid_having_ops=vh_ops,
+        )
+    return result
+
+
+def _strip_angle_brackets(obj: Any) -> Any:
+    """Recursively strip angle-bracket placeholders from all string values in a parsed LLM output.
+
+    Args:
+
+        obj: Parsed JSON value such as a dict, list, string, or other type.
+
+    Returns:
+
+        The same structure with <word> placeholders replaced by word.
+    """
+    if isinstance(obj, str):
+        return re.sub(r"<(\w+)>", r"\1", obj)
+    if isinstance(obj, list):
+        return [_strip_angle_brackets(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: _strip_angle_brackets(v) for k, v in obj.items()}
+    return obj
+
+
+def _normalize_order_direction(direction: str) -> str:
+    """Return "asc" or "desc" from a direction string."""
+    if not isinstance(direction, str):
+        return "asc"
+    d = direction.strip().lower()
+    return "desc" if "desc" in d else "asc"
+
+
+def _strip_order_direction(expr_str: str) -> tuple[str, str]:
+    """Strip trailing ASC/DESC from an order-by expression and return direction.
+
+    Returns (expr_without_direction, "asc" or "desc"). Default direction is asc.
+    """
+    s = expr_str.strip()
+    if not s:
+        return ("", "asc")
+    upper = s.upper()
+    if upper.endswith(" DESC"):
+        return (s[: -5].strip(), "desc")
+    if upper.endswith(" ASC"):
+        return (s[: -4].strip(), "asc")
+    return (s, "asc")
+
+
+def _validate_intent_schema(parsed: dict[str, Any]) -> bool:
+    """Validate parsed intent dict against INTENT_SCHEMA.
+
+    Args:
+
+        parsed: Parsed JSON dict from an LLM response.
+
+    Returns:
+
+        True if the structure is valid for the schema and False otherwise.
+    """
+    try:
+        jsonschema.validate(instance=parsed, schema=INTENT_SCHEMA)
+        return True
+    except jsonschema.ValidationError:
+        return False
+
+
+def parse_intent_response(raw: str, question: str) -> RuntimeIntent | None:
+    """Parse a raw LLM JSON response into a RuntimeIntent.
+
+    Validates structure against INTENT_SCHEMA before parsing and returns None if the JSON is unparseable or fails schema validation.
+
+    Args:
+
+        raw: Raw LLM response string expected to contain intent JSON.
+        question: Original question used as fallback for natural_language.
+
+    Returns:
+
+        RuntimeIntent on success, or None if the response is unparseable or invalid.
+    """
+    parsed = safe_json_loads(raw)
+    if not parsed or not isinstance(parsed, dict):
+        return None
+    parsed = _strip_angle_brackets(parsed)
+    if not _validate_intent_schema(parsed):
+        debug("[intent_expr.parse_intent_response] schema validation failed")
+        return None
+
+    tables = parsed.get("tables", [])
+    if isinstance(tables, str):
+        tables = [tables]
+
+    select_cols_raw = parsed.get("select_cols", [])
+    select_cols = []
+    for sc in select_cols_raw:
+        if isinstance(sc, str):
+            select_cols.append(SelectCol(expr=parse_expr_string(sc)))
+        elif isinstance(sc, dict):
+            expr_str = sc.get("expr", "")
+            select_cols.append(
+                SelectCol(
+                    expr=parse_expr_string(expr_str),
+                )
+            )
+
+    group_by_cols_raw = parsed.get("group_by_cols", [])
+    if isinstance(group_by_cols_raw, str):
+        group_by_cols_raw = [group_by_cols_raw]
+    group_by_cols = [parse_expr_string(g) for g in group_by_cols_raw]
+
+    order_by_cols_raw = parsed.get("order_by_cols", [])
+    order_by_cols = []
+    for obc in order_by_cols_raw:
+        if isinstance(obc, str):
+            expr_clean, direction = _strip_order_direction(obc)
+            order_by_cols.append(OrderByCol(expr=parse_expr_string(expr_clean), direction=direction))
+        elif isinstance(obc, dict):
+            expr_str = obc.get("expr", "")
+            expr_clean, dir_from_expr = _strip_order_direction(expr_str)
+            direction = obc.get("direction") or dir_from_expr or "asc"
+            direction = _normalize_order_direction(direction)
+            order_by_cols.append(OrderByCol(expr=parse_expr_string(expr_clean), direction=direction))
+
+    filters_param_raw = parsed.get("filters_param", [])
+    filters_param = []
+    for fp in filters_param_raw:
+        if isinstance(fp, dict):
+            left_str = fp.get("left_expr") or fp.get("left_col") or ""
+            if not left_str:
+                continue
+            right_str = fp.get("right_expr") or fp.get("right_col") or ""
+            if right_str and "." not in right_str and not _is_date_or_interval_expr(right_str):
+                right_str = ""
+            fg_raw = fp.get("filter_group")
+            filters_param.append(
+                FilterParam(
+                    left_expr=parse_expr_string(left_str),
+                    op=normalize_op(fp.get("op", "=")),
+                    right_expr=parse_expr_string(right_str) if right_str else None,
+                    value_type=fp.get("value_type", "string"),
+                    param_key="",
+                    raw_value=fp.get("value"),
+                    bool_op=fp.get("bool_op", "AND"),
+                    filter_group=int(fg_raw) if fg_raw is not None else None,
+                )
+            )
+
+    having_param_raw = parsed.get("having_param", [])
+    having_param = []
+    for hp in having_param_raw:
+        if isinstance(hp, dict):
+            left_str = hp.get("left_expr") or hp.get("left_agg") or ""
+            if not left_str:
+                continue
+            right_str = hp.get("right_expr") or hp.get("right_agg") or ""
+            if right_str and "." not in right_str and not _is_date_or_interval_expr(right_str):
+                right_str = ""
+            fg_raw = hp.get("filter_group")
+            having_param.append(
+                HavingParam(
+                    left_expr=parse_expr_string(left_str),
+                    op=normalize_op(hp.get("op", ">")),
+                    right_expr=parse_expr_string(right_str) if right_str else None,
+                    value_type=hp.get("value_type", "integer"),
+                    param_key="",
+                    raw_value=hp.get("value"),
+                    bool_op=hp.get("bool_op", "AND"),
+                    filter_group=int(fg_raw) if fg_raw is not None else None,
+                )
+            )
+
+    cte_steps_raw = parsed.get("cte_steps", [])
+    cte_steps = []
+    for cte in cte_steps_raw:
+        if isinstance(cte, dict):
+            cte_select_cols = []
+            explicit_aliases: list[str | None] = []
+            for sc in cte.get("select_cols", []):
+                if isinstance(sc, str):
+                    cte_select_cols.append(SelectCol(expr=parse_expr_string(sc)))
+                    explicit_aliases.append(None)
+                elif isinstance(sc, dict):
+                    expr_str = sc.get("expr", "")
+                    cte_select_cols.append(SelectCol(expr=parse_expr_string(expr_str)))
+                    explicit_aliases.append(sc.get("alias") or None)
+
+            cte_order_by = []
+            for obc in cte.get("order_by_cols", []):
+                if isinstance(obc, str):
+                    expr_clean, direction = _strip_order_direction(obc)
+                    cte_order_by.append(OrderByCol(expr=parse_expr_string(expr_clean), direction=direction))
+                elif isinstance(obc, dict):
+                    expr_str = obc.get("expr", "")
+                    expr_clean, dir_from_expr = _strip_order_direction(expr_str)
+                    direction = _normalize_order_direction(obc.get("direction") or dir_from_expr or "asc")
+                    cte_order_by.append(OrderByCol(expr=parse_expr_string(expr_clean), direction=direction))
+
+            cte_filters = []
+            for fp in cte.get("filters_param", []):
+                if isinstance(fp, dict):
+                    left_str = fp.get("left_expr") or fp.get("left_col") or ""
+                    if not left_str:
+                        continue
+                    right_str = fp.get("right_expr") or fp.get("right_col") or ""
+                    if right_str and "." not in right_str and not _is_date_or_interval_expr(right_str):
+                        right_str = ""
+                    fg_raw = fp.get("filter_group")
+                    cte_filters.append(
+                        FilterParam(
+                            left_expr=parse_expr_string(left_str),
+                            op=normalize_op(fp.get("op", "=")),
+                            right_expr=(parse_expr_string(right_str) if right_str else None),
+                            value_type=fp.get("value_type", "string"),
+                            param_key="",
+                            raw_value=fp.get("value"),
+                            bool_op=fp.get("bool_op", "AND"),
+                            filter_group=int(fg_raw) if fg_raw is not None else None,
+                        )
+                    )
+
+            cte_having = []
+            for hp in cte.get("having_param", []):
+                if isinstance(hp, dict):
+                    left_str = hp.get("left_expr") or hp.get("left_agg") or ""
+                    if not left_str:
+                        continue
+                    right_str = hp.get("right_expr") or hp.get("right_agg") or ""
+                    if right_str and "." not in right_str and not _is_date_or_interval_expr(right_str):
+                        right_str = ""
+                    fg_raw = hp.get("filter_group")
+                    cte_having.append(
+                        HavingParam(
+                            left_expr=parse_expr_string(left_str),
+                            op=normalize_op(hp.get("op", ">")),
+                            right_expr=(parse_expr_string(right_str) if right_str else None),
+                            value_type=hp.get("value_type", "integer"),
+                            param_key="",
+                            raw_value=hp.get("value"),
+                            bool_op=hp.get("bool_op", "AND"),
+                            filter_group=int(fg_raw) if fg_raw is not None else None,
+                        )
+                    )
+
+            cte_output_columns_raw = cte.get("output_columns", [])
+            if isinstance(cte_output_columns_raw, str):
+                cte_output_columns_raw = [cte_output_columns_raw]
+            cte_output_columns = []
+            for i, sc in enumerate(cte_select_cols):
+                if i < len(explicit_aliases) and explicit_aliases[i]:
+                    cte_output_columns.append(str(explicit_aliases[i]).strip())
+                elif i < len(cte_output_columns_raw) and cte_output_columns_raw[i]:
+                    cte_output_columns.append(str(cte_output_columns_raw[i]).strip())
+                else:
+                    derived = derive_cte_output_columns([sc])
+                    cte_output_columns.append(derived[0] if derived else f"col_{i}")
+
+            cte_group_by_raw = cte.get("group_by_cols", [])
+            cte_group_by = [parse_expr_string(g) for g in cte_group_by_raw]
+
+            cte_steps.append(
+                RuntimeCteStep(
+                    cte_name=cte.get("cte_name", ""),
+                    description=cte.get("description"),
+                    tables=cte.get("tables", []),
+                    select_cols=cte_select_cols,
+                    group_by_cols=cte_group_by,
+                    order_by_cols=cte_order_by,
+                    filters_param=cte_filters,
+                    having_param=cte_having,
+                    param_values={},
+                    output_columns=cte_output_columns,
+                    grain=cte.get("grain") or "row_level",
+                    limit=cte.get("limit"),
+                )
+            )
+
+    limit = parsed.get("limit")
+    if isinstance(limit, str):
+        try:
+            limit = int(limit)
+        except ValueError:
+            limit = None
+
+    natural_language = parsed.get("natural_language", "").strip() or question
+    debug(f"[intent_parse.full_intent_parse] extracted natural_language='{natural_language}'")
+
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    if group_by_cols:
+        grain = "grouped"
+    elif has_agg:
+        grain = "scalar"
+    else:
+        grain = "row_level"
+
+    schema_invalid = (parsed.get("intent_status") or "").strip().lower() == "schema_invalid"
+    return RuntimeIntent(
+        tables=tables,
+        grain=grain,
+        select_cols=select_cols,
+        group_by_cols=group_by_cols,
+        order_by_cols=order_by_cols,
+        filters_param=filters_param,
+        having_param=having_param,
+        param_values={},
+        cte_steps=cte_steps,
+        natural_language=natural_language,
+        limit=limit,
+        schema_invalid=schema_invalid,
+    )
+
+
+def _is_nontrivial_group(g: MulGroup) -> bool:
+    """Return True if a MulGroup warrants coefficient parameterization.
+
+    Args:
+
+        g: MulGroup to test.
+
+    Returns:
+
+        True when the group has an aggregation, a scalar function, division operands, or a non-unit coefficient.
+    """
+    return bool(g.agg_func or g.scalar_func or g.inner_scalar_func or g.divide or g.coefficient != 1.0)
+
+
+def _assign_structural_group(g: MulGroup, idx: int, pv: dict[str, Any], is_numeric: bool = True) -> int:
+    """Assign structural param keys to a single MulGroup and collect values.
+
+    Args:
+
+        g: The MulGroup to assign param keys to.
+        idx: The current structural param index counter.
+        pv: The param_values dict to populate with key and value pairs.
+        is_numeric: If False, skip coefficient parameterization entirely.
+
+    Returns:
+
+        The updated index after all assignments.
+    """
+    if is_numeric and _is_nontrivial_group(g):
+        key = f"s{idx}"
+        g.coeff_param_key = key
+        pv[key] = g.coefficient
+        idx += 1
+    for i, v in enumerate(g.scalar_func_args or []):
+        key = f"s{idx}"
+        if len(g.sarg_param_keys) <= i:
+            g.sarg_param_keys.append(key)
+        else:
+            g.sarg_param_keys[i] = key
+        pv[key] = v
+        idx += 1
+    for i, v in enumerate(g.inner_scalar_func_args or []):
+        key = f"s{idx}"
+        if len(g.isarg_param_keys) <= i:
+            g.isarg_param_keys.append(key)
+        else:
+            g.isarg_param_keys[i] = key
+        pv[key] = v
+        idx += 1
+    return idx
+
+
+def _assign_structural_expr(expr: NormalizedExpr, idx: int, pv: dict[str, Any]) -> int:
+    """Assign structural param keys to a single NormalizedExpr including ExprValue offsets and collect values.
+
+    Args:
+
+        expr: The NormalizedExpr to assign param keys to.
+        idx: The current structural param index counter.
+        pv: The param_values dict to populate with key and value pairs.
+
+    Returns:
+
+        The updated index after all assignments.
+    """
+    for g in expr.add_groups:
+        idx = _assign_structural_group(g, idx, pv, is_numeric=expr.is_numeric)
+    for g in expr.sub_groups:
+        idx = _assign_structural_group(g, idx, pv, is_numeric=expr.is_numeric)
+    for i, v in enumerate(expr.scalar_func_args or []):
+        key = f"s{idx}"
+        if len(expr.sarg_param_keys) <= i:
+            expr.sarg_param_keys.append(key)
+        else:
+            expr.sarg_param_keys[i] = key
+        pv[key] = v
+        idx += 1
+    for i, v in enumerate(expr.inner_scalar_func_args or []):
+        key = f"s{idx}"
+        if len(expr.isarg_param_keys) <= i:
+            expr.isarg_param_keys.append(key)
+        else:
+            expr.isarg_param_keys[i] = key
+        pv[key] = v
+        idx += 1
+    if expr.is_numeric:
+        for ev in expr.add_values:
+            key = f"s{idx}"
+            ev.param_key = key
+            pv[key] = ev.value
+            idx += 1
+        for ev in expr.sub_values:
+            key = f"s{idx}"
+            ev.param_key = key
+            pv[key] = ev.value
+            idx += 1
+    return idx
+
+
+def _infer_date_unit(column: str) -> str:
+    """Infer a temporal unit keyword from a column name for date function default arguments.
+
+    Args:
+
+        column: Fully qualified or bare column name string.
+
+    Returns:
+
+        One of 'month', 'day', 'week', 'quarter', or 'year', defaulting to 'month' when no date keyword is found in the column name.
+    """
+    col_lower = column.lower()
+    for keyword, unit in DATE_UNIT_KEYWORDS:
+        if keyword in col_lower:
+            return unit
+    return "month"
+
+
+def _fill_group_defaults(g: MulGroup) -> None:
+    """Fill default scalar_func_args and inner_scalar_func_args on a MulGroup if they are missing.
+
+    Args:
+
+        g: MulGroup to mutate in-place.
+    """
+    if g.scalar_func and not g.scalar_func_args:
+        func = g.scalar_func.lower()
+        if func in SCALAR_FUNCTIONS_LEADING_ARG:
+            col = g.multiply[0] if g.multiply and g.multiply[0] != "*" else ""
+            g.scalar_func_args = [_infer_date_unit(col)]
+        else:
+            defaults = SCALAR_FUNC_DEFAULTS.get(func)
+            if defaults is not None:
+                g.scalar_func_args = list(defaults)
+    if g.inner_scalar_func and not g.inner_scalar_func_args:
+        func = g.inner_scalar_func.lower()
+        if func in SCALAR_FUNCTIONS_LEADING_ARG:
+            col = g.multiply[0] if g.multiply and g.multiply[0] != "*" else ""
+            g.inner_scalar_func_args = [_infer_date_unit(col)]
+        else:
+            defaults = SCALAR_FUNC_DEFAULTS.get(func)
+            if defaults is not None:
+                g.inner_scalar_func_args = list(defaults)
+
+
+def _fill_expr_defaults(expr: NormalizedExpr) -> None:
+    """Fill default scalar_func_args on a NormalizedExpr and all of its MulGroups if they are missing.
+
+    Args:
+
+        expr: NormalizedExpr to mutate in-place.
+    """
+    if expr.scalar_func and not expr.scalar_func_args:
+        func = expr.scalar_func.lower()
+        if func in SCALAR_FUNCTIONS_LEADING_ARG:
+            col = expr.primary_column
+            expr.scalar_func_args = [_infer_date_unit(col)]
+        else:
+            defaults = SCALAR_FUNC_DEFAULTS.get(func)
+            if defaults is not None:
+                expr.scalar_func_args = list(defaults)
+    if expr.inner_scalar_func and not expr.inner_scalar_func_args:
+        func = expr.inner_scalar_func.lower()
+        if func in SCALAR_FUNCTIONS_LEADING_ARG:
+            col = expr.primary_column
+            expr.inner_scalar_func_args = [_infer_date_unit(col)]
+        else:
+            defaults = SCALAR_FUNC_DEFAULTS.get(func)
+            if defaults is not None:
+                expr.inner_scalar_func_args = list(defaults)
+    for g in expr.add_groups + expr.sub_groups:
+        _fill_group_defaults(g)
+
+
+def ensure_scalar_func_defaults(intent: RuntimeIntent) -> RuntimeIntent:
+    """Ensure all scalar functions in a RuntimeIntent carry their default argument lists.
+
+    Fills in missing scalar_func_args and inner_scalar_func_args on every expression across the main query and all CTE steps so template signatures stay consistent.
+
+    Args:
+
+        intent: RuntimeIntent to process.
+
+    Returns:
+
+        The same RuntimeIntent object, mutated in-place via _fill_expr_defaults.
+    """
+    for cte in intent.cte_steps or []:
+        for sc in cte.select_cols or []:
+            _fill_expr_defaults(sc.expr)
+        for g in cte.group_by_cols or []:
+            _fill_expr_defaults(g)
+        for obc in cte.order_by_cols or []:
+            _fill_expr_defaults(obc.expr)
+        for fp in cte.filters_param or []:
+            _fill_expr_defaults(fp.left_expr)
+            if fp.right_expr:
+                _fill_expr_defaults(fp.right_expr)
+        for hp in cte.having_param or []:
+            _fill_expr_defaults(hp.left_expr)
+            if hp.right_expr:
+                _fill_expr_defaults(hp.right_expr)
+    for sc in intent.select_cols or []:
+        _fill_expr_defaults(sc.expr)
+    for g in intent.group_by_cols or []:
+        _fill_expr_defaults(g)
+    for obc in intent.order_by_cols or []:
+        _fill_expr_defaults(obc.expr)
+    for fp in intent.filters_param or []:
+        _fill_expr_defaults(fp.left_expr)
+        if fp.right_expr:
+            _fill_expr_defaults(fp.right_expr)
+    for hp in intent.having_param or []:
+        _fill_expr_defaults(hp.left_expr)
+        if hp.right_expr:
+            _fill_expr_defaults(hp.right_expr)
+    return intent
+
+
+def extract_structural_params(intent: RuntimeIntent) -> RuntimeIntent:
+    """Assign structural param keys such as s1 and s2 to limit values, coefficients, and function arguments.
+
+    Processes CTE steps first and then the main query, populates param_values with the concrete values for each key, and sets limit_param_key on the intent.
+
+    Args:
+
+        intent: RuntimeIntent with fully tagged NormalizedExprs.
+
+    Returns:
+
+        New RuntimeIntent with param_values and limit_param_key populated.
+    """
+    pv: dict[str, Any] = dict(intent.param_values or {})
+    idx = 1
+    for cte in intent.cte_steps or []:
+        if cte.limit is not None:
+            key = f"s{idx}"
+            pv[key] = cte.limit
+            cte.limit_param_key = key
+            idx += 1
+        for sc in cte.select_cols or []:
+            idx = _assign_structural_expr(sc.expr, idx, pv)
+        for g in cte.group_by_cols or []:
+            idx = _assign_structural_expr(g, idx, pv)
+        for obc in cte.order_by_cols or []:
+            idx = _assign_structural_expr(obc.expr, idx, pv)
+        for fp in cte.filters_param or []:
+            idx = _assign_structural_expr(fp.left_expr, idx, pv)
+            if fp.right_expr:
+                idx = _assign_structural_expr(fp.right_expr, idx, pv)
+        for hp in cte.having_param or []:
+            idx = _assign_structural_expr(hp.left_expr, idx, pv)
+            if hp.right_expr:
+                idx = _assign_structural_expr(hp.right_expr, idx, pv)
+    limit_param_key = ""
+    if intent.limit is not None:
+        key = f"s{idx}"
+        pv[key] = intent.limit
+        limit_param_key = key
+        idx += 1
+    for sc in intent.select_cols or []:
+        idx = _assign_structural_expr(sc.expr, idx, pv)
+    for g in intent.group_by_cols or []:
+        idx = _assign_structural_expr(g, idx, pv)
+    for obc in intent.order_by_cols or []:
+        idx = _assign_structural_expr(obc.expr, idx, pv)
+    for fp in intent.filters_param or []:
+        idx = _assign_structural_expr(fp.left_expr, idx, pv)
+        if fp.right_expr:
+            idx = _assign_structural_expr(fp.right_expr, idx, pv)
+    for hp in intent.having_param or []:
+        idx = _assign_structural_expr(hp.left_expr, idx, pv)
+        if hp.right_expr:
+            idx = _assign_structural_expr(hp.right_expr, idx, pv)
+    debug(f"[intent_process.extract_structural_params] assigned {idx - 1} structural params")
+    return replace(intent, param_values=pv, limit_param_key=limit_param_key)
+
+
+def has_non_default_structural(template: Template) -> bool:
+    """Return True if a template has any structural params with non-identity default values.
+
+    Identity values are 0, 0.0, 1, and 1.0 and templates with only identity structural defaults are treated the same as templates with no structural params.
+
+    Args:
+
+        template: Template to inspect.
+
+    Returns:
+
+        True when at least one structural_default value is outside the identity set.
+    """
+    if not template.structural_defaults:
+        return False
+    return any(v not in STRUCTURAL_IDENTITY_VALUES for v in template.structural_defaults.values())
+
+
+def collect_raw_param_values(intent: RuntimeIntent) -> dict[str, Any]:
+    """Collect raw_value from all keyed filter and having params and clear raw_value after.
+
+    Iterates CTE steps first and then the main query and clears raw_value in-place to avoid double-counting after collection.
+
+    Args:
+
+        intent: RuntimeIntent whose params will be harvested.
+
+    Returns:
+
+        Dictionary mapping param_key to its raw extracted value.
+    """
+    pv: dict[str, Any] = {}
+    for cte in intent.cte_steps or []:
+        for fp in cte.filters_param or []:
+            if fp.param_key and fp.raw_value is not None:
+                pv[fp.param_key] = fp.raw_value
+                fp.raw_value = None
+        for hp in cte.having_param or []:
+            if hp.param_key and hp.raw_value is not None:
+                pv[hp.param_key] = hp.raw_value
+                hp.raw_value = None
+    for fp in intent.filters_param or []:
+        if fp.param_key and fp.raw_value is not None:
+            pv[fp.param_key] = fp.raw_value
+            fp.raw_value = None
+    for hp in intent.having_param or []:
+        if hp.param_key and hp.raw_value is not None:
+            pv[hp.param_key] = hp.raw_value
+            hp.raw_value = None
+    return pv
+
+
+def assign_param_keys(
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    cte_steps: list[RuntimeCteStep] | None = None,
+) -> tuple[list[FilterParam], list[HavingParam], list[RuntimeCteStep], int]:
+    """Assign sequential param_key values such as p1 and p2 to all filter and having parameters.
+
+    CTE steps are processed before the main query and parameters with operators 'is null', 'is not null', or value_type 'date_window' are passed through without keys.
+
+    Args:
+
+        filters_param: Main query filter parameters to key.
+        having_param: Main query having parameters to key.
+        cte_steps: Optional list of CTE steps whose filters and having are keyed first.
+
+    Returns:
+
+        Tuple of (updated_filters_param, updated_having_param, updated_cte_steps, next_idx).
+    """
+    idx = 1
+    updated_cte_steps: list[RuntimeCteStep] = []
+    for cte in cte_steps or []:
+        cte_fp = []
+        for fp in cte.filters_param or []:
+            if fp.op in ("is null", "is not null") or fp.value_type in ("date_window", "date_diff") or fp.right_expr is not None:
+                cte_fp.append(fp)
+            else:
+                cte_fp.append(replace(fp, param_key=f"p{idx}"))
+                idx += 1
+        cte_hp = []
+        for hp in cte.having_param or []:
+            if hp.right_expr is not None:
+                cte_hp.append(hp)
+            else:
+                cte_hp.append(replace(hp, param_key=f"p{idx}"))
+                idx += 1
+        updated_cte_steps.append(replace(cte, filters_param=cte_fp, having_param=cte_hp))
+    new_filters_param = []
+    for fp in filters_param:
+        if fp.op in ("is null", "is not null") or fp.value_type in ("date_window", "date_diff") or fp.right_expr is not None:
+            new_filters_param.append(fp)
+        else:
+            new_filters_param.append(replace(fp, param_key=f"p{idx}"))
+            idx += 1
+    new_having_param = []
+    for hp in having_param:
+        if hp.right_expr is not None:
+            new_having_param.append(hp)
+        else:
+            new_having_param.append(replace(hp, param_key=f"p{idx}"))
+            idx += 1
+    return new_filters_param, new_having_param, updated_cte_steps, idx
+
+
+def _parse_between_raw_value(raw_value: Any) -> tuple[Any, Any] | None:
+    """Try to extract two boundary values from a BETWEEN raw_value.
+
+    Handles list-of-two and string representations separated by common delimiters such as ' AND ', ' and ', ',', or ' - '.
+
+    Args:
+
+        raw_value: The raw_value from a FilterParam or HavingParam with op equal to 'between'.
+
+    Returns:
+
+        Tuple of (low, high) on success, or None when the value cannot be split.
+    """
+    if isinstance(raw_value, list) and len(raw_value) == 2:
+        return raw_value[0], raw_value[1]
+    if isinstance(raw_value, str):
+        for sep in (" AND ", " and ", ",", " - "):
+            parts = raw_value.split(sep, 1)
+            if len(parts) == 2:
+                lo = parts[0].strip()
+                hi = parts[1].strip()
+                if lo and hi:
+                    return lo, hi
+    return None
+
+
+def _decompose_between_param_list(
+    params: list[FilterParam] | list[HavingParam],
+) -> list[FilterParam] | list[HavingParam]:
+    """Decompose BETWEEN operators in a list of filter or having params.
+
+    Each BETWEEN param is replaced by a >= and <= pair and when the raw_value can be parsed into two boundaries the pair uses separate values; otherwise the original raw_value is kept on both sides as a best-effort fallback.
+
+    Args:
+
+        params: List of FilterParam or HavingParam objects.
+
+    Returns:
+
+        New list with BETWEEN params replaced by >= and <= pairs.
+    """
+    result: list = []
+    for p in params:
+        if p.op.lower() != "between":
+            result.append(p)
+            continue
+        bounds = _parse_between_raw_value(p.raw_value)
+        if bounds is not None:
+            result.append(replace(p, op=">=", raw_value=bounds[0]))
+            result.append(replace(p, op="<=", raw_value=bounds[1]))
+        else:
+            result.append(replace(p, op=">="))
+            result.append(replace(p, op="<="))
+    return result
+
+
+def decompose_between_params(intent: RuntimeIntent) -> RuntimeIntent:
+    """Decompose BETWEEN filter and having operators into paired >= and <= conditions.
+
+    Applies to filters_param, having_param, and their counterparts in CTE steps.
+
+    Args:
+
+        intent: RuntimeIntent containing filters_param, having_param, and cte_steps to process.
+
+    Returns:
+
+        New RuntimeIntent with all BETWEEN operators replaced by >= and <= pairs.
+    """
+    new_fp = _decompose_between_param_list(intent.filters_param or [])
+    new_hp = _decompose_between_param_list(intent.having_param or [])
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_fp = _decompose_between_param_list(cte.filters_param or [])
+        cte_hp = _decompose_between_param_list(cte.having_param or [])
+        new_cte_steps.append(replace(cte, filters_param=cte_fp, having_param=cte_hp))
+    return replace(intent, filters_param=new_fp, having_param=new_hp, cte_steps=new_cte_steps)
+
+
+def _parse_in_string_to_list(raw_value: str) -> list[str]:
+    """Parse a string-encoded IN-list into a list of stripped string elements.
+
+    Handles formats such as "R, PG-13", "'R','PG-13'", and "1, 2, 3" and strips leading and trailing quotes on each element.
+
+    Args:
+
+        raw_value: String representation of an IN-list value.
+
+    Returns:
+
+        List of individual value strings with surrounding quotes removed.
+    """
+    parts = IN_STRING_SEPARATORS.split(raw_value)
+    return [p.strip().strip("'\"") for p in parts if p.strip().strip("'\"")]
+
+
+def _normalize_in_param_list(
+    params: list[FilterParam] | list[HavingParam],
+) -> list[FilterParam] | list[HavingParam]:
+    """Convert string raw_values to lists for IN / NOT IN operators.
+
+    Args:
+
+        params: Filter or having params to normalise.
+
+    Returns:
+
+        New list with string IN-values parsed into Python lists.
+    """
+    result: list = []
+    for p in params:
+        if p.op.lower() not in IN_OPS or not isinstance(p.raw_value, str):
+            result.append(p)
+            continue
+        parsed = _parse_in_string_to_list(p.raw_value)
+        if len(parsed) > 1:
+            result.append(replace(p, raw_value=parsed))
+        else:
+            result.append(p)
+    return result
+
+
+def normalize_in_raw_values(intent: RuntimeIntent) -> RuntimeIntent:
+    """Normalise IN and NOT IN raw_values from strings to lists across the intent.
+
+    When the LLM emits IN values as a flat string this function parses them into proper Python lists so that downstream processing can iterate over individual elements.
+
+    Args:
+
+        intent: RuntimeIntent whose filters and havings may contain string IN-values.
+
+    Returns:
+
+        Updated RuntimeIntent with string IN-values converted to lists.
+    """
+    new_fp = _normalize_in_param_list(intent.filters_param or [])
+    new_hp = _normalize_in_param_list(intent.having_param or [])
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_fp = _normalize_in_param_list(cte.filters_param or [])
+        cte_hp = _normalize_in_param_list(cte.having_param or [])
+        new_cte_steps.append(replace(cte, filters_param=cte_fp, having_param=cte_hp))
+    return replace(intent, filters_param=new_fp, having_param=new_hp, cte_steps=new_cte_steps)
+
+
+_PLURAL_TO_SINGULAR_UNIT = {
+    "days": "day",
+    "weeks": "week",
+    "months": "month",
+    "years": "year",
+    "hours": "hour",
+    "minutes": "minute",
+    "seconds": "second",
+}
+
+
+def _normalize_date_unit_in_raw_value(raw_value: Any) -> Any:
+    """Normalise unit in date_window/date_diff raw_value dict to singular form."""
+    if not isinstance(raw_value, dict):
+        return raw_value
+    unit = raw_value.get("unit")
+    if isinstance(unit, str):
+        unit_lower = unit.lower().strip()
+        singular = _PLURAL_TO_SINGULAR_UNIT.get(unit_lower)
+        if singular:
+            return {**raw_value, "unit": singular}
+        if unit_lower in VALID_DATE_WINDOW_UNITS | VALID_DATE_DIFF_UNITS:
+            return raw_value
+    return raw_value
+
+
+def normalize_date_diff_raw_values(intent: RuntimeIntent) -> RuntimeIntent:
+    """Normalise date_window and date_diff raw_value units to singular form.
+
+    Converts 'days' -> 'day', 'weeks' -> 'week', etc. so downstream
+    rendering uses consistent unit names.
+    """
+    def _process(params: list) -> list:
+        out = []
+        for p in params or []:
+            if p.value_type in ("date_window", "date_diff") and p.raw_value is not None:
+                out.append(replace(p, raw_value=_normalize_date_unit_in_raw_value(p.raw_value)))
+            else:
+                out.append(p)
+        return out
+
+    new_fp = _process(intent.filters_param or [])
+    new_hp = _process(intent.having_param or [])
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_fp = _process(cte.filters_param or [])
+        cte_hp = _process(cte.having_param or [])
+        new_cte_steps.append(replace(cte, filters_param=cte_fp, having_param=cte_hp))
+    return replace(intent, filters_param=new_fp, having_param=new_hp, cte_steps=new_cte_steps)
+
+
+def _is_plain_column_expr(expr: NormalizedExpr) -> bool:
+    """Return True when the expression is a bare column reference.
+
+    A plain column has exactly one add_group with one term, no
+    sub_groups, no add_values, and no arithmetic operators,
+    indicating it is not a computed date-subtraction expression.
+    """
+    if expr.sub_groups:
+        return False
+    if expr.add_values:
+        return False
+    if len(expr.add_groups) != 1:
+        return False
+    group = expr.add_groups[0]
+    if len(group.multiply) != 1:
+        return False
+    term = group.multiply[0]
+    return not any(ch in term for ch in "+-*/")
+
+
+def _reclassify_date_diff_param(
+    fp: FilterParam,
+) -> FilterParam:
+    """Convert a misclassified date_diff filter to date_window.
+
+    When the LLM returns value_type ``date_diff`` with a plain date
+    column as left_expr (instead of a date subtraction expression),
+    it actually means a relative time window such as "last 90 days".
+    Reclassify as ``date_window`` with the ``amount`` mapped to
+    ``offset``.
+    """
+    if fp.value_type != "date_diff":
+        return fp
+    if not isinstance(fp.raw_value, dict):
+        return fp
+    if not _is_plain_column_expr(fp.left_expr):
+        return fp
+    rv = fp.raw_value
+    amount = rv.get("amount")
+    if amount is None:
+        return fp
+    new_rv = {"unit": rv.get("unit", "day"), "offset": int(amount)}
+    return replace(fp, value_type="date_window", raw_value=new_rv)
+
+
+def repair_misclassified_date_diff(
+    intent: RuntimeIntent,
+) -> RuntimeIntent:
+    """Reclassify date_diff filters that target a plain column.
+
+    When a date_diff filter has a simple column reference as its
+    left_expr rather than a date-subtraction expression, it
+    represents a relative time window and is converted to
+    date_window with the amount mapped to offset.
+    """
+    def _process(params: list[FilterParam]) -> list[FilterParam]:
+        return [_reclassify_date_diff_param(fp) for fp in params]
+
+    new_fp = _process(intent.filters_param or [])
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte_fp = _process(cte.filters_param or [])
+        new_cte_steps.append(replace(cte, filters_param=cte_fp))
+    return replace(intent, filters_param=new_fp, cte_steps=new_cte_steps)