aetherdialect 0.1.0__py3-none-any.whl

text2sql/validation_schema.py

@@ -0,0 +1,1847 @@
+"""Schema-level validation for intent fields against the database schema.
+
+Validates ``select_cols``, ``order_by_cols``, ``group_by_cols``, ``filters_param``, and ``having_param`` for column existence, table qualification, valid operators, aggregation appropriateness, and scalar function type compatibility. Supports CTE output column tracking for cross-CTE validation. All validators return lists of ``IntentIssue`` objects and are called from both the main query and CTE chain validators.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .config import (
+    AGGREGATION_ALLOWED_COLUMN_TYPES,
+    ARITHMETIC_ROLES,
+    DISALLOWED_EXTRACT_UNITS,
+    VALID_AGG_FUNCS,
+    VALID_AGGREGATION_FUNCTIONS,
+    VALID_DATE_DIFF_UNITS,
+    VALID_DATE_WINDOW_UNITS,
+    VALID_FILTER_OPS,
+    VALID_HAVING_OPS,
+    VALID_SCALAR_FUNCTIONS,
+    VALID_VALUE_TYPES,
+)
+from .contracts_base import (
+    ColumnMetadata,
+    CteOutputColumnMeta,
+    IntentIssue,
+    SchemaGraph,
+)
+from .contracts_core import (
+    FilterParam,
+    HavingParam,
+    NormalizedExpr,
+    OrderByCol,
+    RuntimeCteStep,
+    SelectCol,
+)
+from .core_utils import debug
+
+
+def _strip_distinct_prefix(col: str) -> str:
+    """Remove a leading ``DISTINCT`` keyword from a column reference.
+
+    For example, ``"DISTINCT orders.order_id"`` returns ``"orders.order_id"``.
+
+    Args:
+
+        col: A column expression string that may have a ``DISTINCT`` prefix.
+
+    Returns:
+
+        The column expression with any leading ``DISTINCT`` keyword removed.
+    """
+    if col and col.upper().startswith("DISTINCT "):
+        return col[9:].strip()
+    return col
+
+
+def extract_col_from_scalar_wrapper(col_expr: str) -> str:
+    """Strip a scalar function wrapper and any leading ``DISTINCT`` keyword, returning the inner column expression.
+
+    For example, ``"ABS(table.col)"`` returns ``"table.col"`` and ``"DISTINCT table.col"`` returns ``"table.col"``.
+
+    Args:
+
+        col_expr: A column expression string, possibly wrapped in a scalar function and/or prefixed with ``DISTINCT``.
+
+    Returns:
+
+        The inner column expression string, or the original string if no recognised scalar wrapper is present.
+    """
+    if not col_expr:
+        return col_expr
+    match = re.match(r"^\s*(\w+)\s*\(\s*(.+)\s*\)\s*$", col_expr, re.IGNORECASE)
+    if match:
+        func_name = match.group(1).lower()
+        if func_name in VALID_SCALAR_FUNCTIONS:
+            return _strip_distinct_prefix(match.group(2).strip())
+    return _strip_distinct_prefix(col_expr)
+
+
+def _validate_scalar_func_valid(scalar_func: str | None, context: str, location: str) -> list[IntentIssue]:
+    """Validate that a scalar function name is in the allowed set.
+
+    Args:
+
+        scalar_func: The scalar function name to validate, or ``None``.
+        context: A short label for the field being validated (for example ``"select_0"``).
+        location: Human-readable location string used in error messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects (empty if valid or if ``scalar_func`` is ``None``).
+    """
+    issues = []
+    if not scalar_func:
+        return issues
+    func_lower = scalar_func.lower()
+    if func_lower not in VALID_SCALAR_FUNCTIONS:
+        issues.append(
+            IntentIssue(
+                issue_id=f"invalid_scalar_func_{context}_{scalar_func}",
+                category="scalar_validity",
+                severity="error",
+                message=f"Invalid scalar function '{scalar_func}' in {location}. Allowed: {', '.join(sorted(VALID_SCALAR_FUNCTIONS))}",
+                context={
+                    "function": scalar_func,
+                    "location": location,
+                    "allowed": list(VALID_SCALAR_FUNCTIONS),
+                },
+            )
+        )
+        debug(f"[validation_schema.validate_scalar_func_valid] invalid scalar '{scalar_func}' in {location}")
+    return issues
+
+
+def _first_arg_lower(args: list[Any]) -> str:
+    """Return the first scalar arg lowercased, or empty string if none."""
+    if not args:
+        return ""
+    return str(args[0]).strip().lower()
+
+
+def _is_extract_epoch(func: str | None, args: list[Any]) -> bool:
+    """Return True if func is extract and first arg is a disallowed unit (e.g. epoch)."""
+    if not func or func.lower() != "extract":
+        return False
+    unit = _first_arg_lower(args)
+    return unit in DISALLOWED_EXTRACT_UNITS
+
+
+def validate_expr_no_extract_epoch(
+    expr: NormalizedExpr,
+    context: str,
+    location: str,
+) -> list[IntentIssue]:
+    """Flag EXTRACT(EPOCH FROM ...) in expressions; EPOCH is not supported.
+
+    Walks expr and its add_groups/sub_groups and returns one error per
+    occurrence of extract with a disallowed unit.
+    """
+    issues: list[IntentIssue] = []
+    if _is_extract_epoch(expr.scalar_func, expr.scalar_func_args or []):
+        issues.append(
+            IntentIssue(
+                issue_id=f"extract_epoch_{context}",
+                category="extract_epoch",
+                severity="error",
+                message=(
+                    "EXTRACT(EPOCH FROM ...) is not supported. Use date column "
+                    "subtraction or other supported date functions."
+                ),
+                context={"location": location},
+            )
+        )
+    if _is_extract_epoch(expr.inner_scalar_func, expr.inner_scalar_func_args or []):
+        issues.append(
+            IntentIssue(
+                issue_id=f"extract_epoch_inner_{context}",
+                category="extract_epoch",
+                severity="error",
+                message=(
+                    "EXTRACT(EPOCH FROM ...) is not supported. Use date column "
+                    "subtraction or other supported date functions."
+                ),
+                context={"location": location},
+            )
+        )
+    for group in expr.add_groups + expr.sub_groups:
+        if _is_extract_epoch(group.scalar_func, group.scalar_func_args or []):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"extract_epoch_group_{context}",
+                    category="extract_epoch",
+                    severity="error",
+                    message=(
+                        "EXTRACT(EPOCH FROM ...) is not supported. Use date column "
+                        "subtraction or other supported date functions."
+                    ),
+                    context={"location": location},
+                )
+            )
+        if _is_extract_epoch(group.inner_scalar_func, group.inner_scalar_func_args or []):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"extract_epoch_inner_group_{context}",
+                    category="extract_epoch",
+                    severity="error",
+                    message=(
+                        "EXTRACT(EPOCH FROM ...) is not supported. Use date column "
+                        "subtraction or other supported date functions."
+                    ),
+                    context={"location": location},
+                )
+            )
+    return issues
+
+
+def _validate_agg_func_valid(agg_func: str | None, context: str, location: str) -> list[IntentIssue]:
+    """Validate that an aggregation function name is in the allowed set.
+
+    Args:
+
+        agg_func: The aggregation function name to validate, or ``None``.
+        context: A short label for the field being validated.
+        location: Human-readable location string used in error messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects (empty if valid or if ``agg_func`` is ``None``).
+    """
+    issues = []
+    if not agg_func:
+        return issues
+    func_lower = agg_func.lower()
+    if func_lower not in VALID_AGGREGATION_FUNCTIONS:
+        issues.append(
+            IntentIssue(
+                issue_id=f"invalid_agg_func_{context}_{agg_func}",
+                category="aggregation_validity",
+                severity="error",
+                message=f"Invalid aggregation function '{agg_func}' in {location}. Allowed: {', '.join(sorted(VALID_AGGREGATION_FUNCTIONS))}",
+                context={
+                    "function": agg_func,
+                    "location": location,
+                    "allowed": list(VALID_AGGREGATION_FUNCTIONS),
+                },
+            )
+        )
+        debug(f"[validation_schema.validate_agg_func_valid] invalid agg '{agg_func}' in {location}")
+    return issues
+
+
+def validate_select_cols_schema(
+    select_cols: list[SelectCol],
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``SelectCol`` entries against the schema for column existence and qualification.
+
+    Args:
+
+        select_cols: List of ``SelectCol`` instances to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this query context.
+        cte_outputs: Dict of CTE name to output column metadata for cross-CTE lookup.
+        context: Label used in issue IDs and messages (for example ``"main"`` or ``"CTE cte1"``).
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not select_cols:
+        issues.append(
+            IntentIssue(
+                issue_id=f"select_cols_empty_{context}",
+                category="select_validity",
+                severity="error",
+                message=f"select_cols cannot be empty in {context}",
+                context={"location": context},
+            )
+        )
+        return issues
+    cte_outputs = cte_outputs or {}
+    for idx, sc in enumerate(select_cols):
+        col_expr = sc.expr.primary_column
+        if not col_expr:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"select_col_empty_{context}_{idx}",
+                    category="select_validity",
+                    severity="error",
+                    message=f"SelectCol at index {idx} has empty col in {context}",
+                    context={"index": idx, "location": context},
+                )
+            )
+            continue
+        actual_col = extract_col_from_scalar_wrapper(col_expr)
+        if "." not in actual_col:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"select_unqualified_{context}_{actual_col}",
+                    category="select_validity",
+                    severity="error",
+                    message=f"select_cols must be qualified as table.column, got '{actual_col}' in {context}",
+                    context={"column": actual_col, "location": context},
+                )
+            )
+            continue
+        table_name, col_name = actual_col.rsplit(".", 1)
+        if table_name in cte_outputs:
+            if col_name.lower() not in [c.lower() for c in cte_outputs[table_name]]:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"select_cte_col_not_found_{context}_{table_name}_{col_name}",
+                        category="select_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in CTE '{table_name}' outputs for select in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+            continue
+        if table_name not in allowed_tables:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"select_table_not_allowed_{context}_{table_name}",
+                    category="select_validity",
+                    severity="error",
+                    message=f"Table '{table_name}' not in allowed tables for select in {context}",
+                    context={"table": table_name, "location": context},
+                )
+            )
+            continue
+        if table_name in schema.tables:
+            table_meta = schema.tables[table_name]
+            col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+            if not col_meta:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"select_col_not_found_{context}_{table_name}_{col_name}",
+                        category="select_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in table '{table_name}' for select in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+        sc_scalar, sc_agg = extract_functions_from_term(sc.expr.primary_term)
+        issues.extend(_validate_agg_func_valid(sc_agg, f"select_{idx}", context))
+        issues.extend(_validate_scalar_func_valid(sc_scalar, f"select_{idx}", context))
+        issues.extend(
+            validate_expr_no_extract_epoch(sc.expr, f"select_{idx}", context)
+        )
+    debug(f"[validation_schema.validate_select_cols_schema] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_order_by_cols_schema(
+    order_by_cols: list[OrderByCol],
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``OrderByCol`` entries against the schema for column existence and direction.
+
+    Args:
+
+        order_by_cols: List of ``OrderByCol`` instances to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this query context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not order_by_cols:
+        return []
+    cte_outputs = cte_outputs or {}
+    for idx, obc in enumerate(order_by_cols):
+        col_expr = obc.expr.primary_column
+        if not col_expr:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"order_by_col_empty_{context}_{idx}",
+                    category="order_by_validity",
+                    severity="error",
+                    message=f"OrderByCol at index {idx} has empty col in {context}",
+                    context={"index": idx, "location": context},
+                )
+            )
+            continue
+        actual_col = extract_col_from_scalar_wrapper(col_expr)
+        if "." not in actual_col:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"order_by_unqualified_{context}_{actual_col}",
+                    category="order_by_validity",
+                    severity="error",
+                    message=f"order_by_cols must be qualified as table.column, got '{actual_col}' in {context}",
+                    context={"column": actual_col, "location": context},
+                )
+            )
+            continue
+        table_name, col_name = actual_col.rsplit(".", 1)
+        if table_name in cte_outputs:
+            if col_name.lower() not in [c.lower() for c in cte_outputs[table_name]]:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"order_by_cte_col_not_found_{context}_{table_name}_{col_name}",
+                        category="order_by_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in CTE '{table_name}' outputs for order_by in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+            continue
+        if table_name not in allowed_tables:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"order_by_table_not_allowed_{context}_{table_name}",
+                    category="order_by_validity",
+                    severity="error",
+                    message=f"Table '{table_name}' not in allowed tables for order_by in {context}",
+                    context={"table": table_name, "location": context},
+                )
+            )
+            continue
+        if table_name in schema.tables:
+            table_meta = schema.tables[table_name]
+            col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+            if not col_meta:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"order_by_col_not_found_{context}_{table_name}_{col_name}",
+                        category="order_by_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in table '{table_name}' for order_by in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+        if obc.direction not in ("ASC", "DESC"):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"order_by_invalid_direction_{context}_{idx}",
+                    category="order_by_validity",
+                    severity="error",
+                    message=f"OrderByCol direction must be 'ASC' or 'DESC', got '{obc.direction}' in {context}",
+                    context={"direction": obc.direction, "location": context},
+                )
+            )
+        obc_scalar, obc_agg = extract_functions_from_term(obc.expr.primary_term)
+        issues.extend(_validate_agg_func_valid(obc_agg, f"order_by_{idx}", context))
+        issues.extend(_validate_scalar_func_valid(obc_scalar, f"order_by_{idx}", context))
+        issues.extend(
+            validate_expr_no_extract_epoch(obc.expr, f"order_by_{idx}", context)
+        )
+    debug(f"[validation_schema.validate_order_by_cols_schema] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_group_by_cols_schema(
+    group_by_cols: list[NormalizedExpr],
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``group_by_cols`` against the schema and column groupability.
+
+    Args:
+
+        group_by_cols: List of ``NormalizedExpr`` instances to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this query context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not group_by_cols:
+        return []
+    cte_outputs = cte_outputs or {}
+    for g in group_by_cols:
+        col = g.primary_column
+        if "." not in col:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"group_by_unqualified_{context}_{col}",
+                    category="group_by_validity",
+                    severity="error",
+                    message=f"group_by_cols must be qualified as table.column, got '{col}' in {context}",
+                    context={"column": col, "location": context},
+                )
+            )
+            continue
+        table_name, col_name = col.rsplit(".", 1)
+        if table_name in cte_outputs:
+            cte_cols = cte_outputs[table_name]
+            matched_key = next((c for c in cte_cols if c.lower() == col_name.lower()), None)
+            if not matched_key:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"group_by_cte_col_not_found_{context}_{table_name}_{col_name}",
+                        category="group_by_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in CTE '{table_name}' outputs for group_by in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+            elif not cte_cols[matched_key].groupable:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"group_by_cte_col_not_groupable_{context}_{table_name}_{col_name}",
+                        category="group_by_validity",
+                        severity="warning",
+                        message=f"CTE column '{table_name}.{col_name}' (role={cte_cols[matched_key].role}) is not recommended for GROUP BY in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "role": cte_cols[matched_key].role,
+                            "location": context,
+                        },
+                    )
+                )
+            continue
+        if table_name not in allowed_tables:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"group_by_table_not_allowed_{context}_{table_name}",
+                    category="group_by_validity",
+                    severity="error",
+                    message=f"Table '{table_name}' not in allowed tables for group_by in {context}",
+                    context={"table": table_name, "location": context},
+                )
+            )
+            continue
+        if table_name in schema.tables:
+            table_meta = schema.tables[table_name]
+            col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+            if not col_meta:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"group_by_col_not_found_{context}_{table_name}_{col_name}",
+                        category="group_by_validity",
+                        severity="error",
+                        message=f"Column '{col_name}' not in table '{table_name}' for group_by in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "location": context,
+                        },
+                    )
+                )
+            elif not col_meta.is_groupable:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"group_by_col_not_groupable_{context}_{table_name}_{col_name}",
+                        category="group_by_validity",
+                        severity="warning",
+                        message=f"Column '{col_name}' (role={col_meta.role}) is not recommended for grouping in {context}",
+                        context={
+                            "table": table_name,
+                            "column": col_name,
+                            "role": col_meta.role,
+                            "location": context,
+                        },
+                    )
+                )
+    debug(f"[validation_schema.validate_group_by_cols_schema] {len(issues)} issues in {context}")
+    return issues
+
+
+def _validate_filter_col(
+    col_expr: str,
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+    context: str,
+    side: str,
+    param_key: str,
+) -> list[IntentIssue]:
+    """Validate a single filter column reference (left or right side of a ``FilterParam``).
+
+    Args:
+
+        col_expr: The column expression string to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+        side: ``"left_col"`` or ``"right_col"``.
+        param_key: The ``param_key`` of the ``FilterParam`` (for issue IDs).
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not col_expr:
+        return issues
+    actual_col = extract_col_from_scalar_wrapper(col_expr)
+    if "." not in actual_col:
+        issues.append(
+            IntentIssue(
+                issue_id=f"filter_{side}_unqualified_{context}_{actual_col}",
+                category="filter_validity",
+                severity="error",
+                message=f"Filter {side} must be qualified as table.column, got '{actual_col}' in {context}",
+                context={
+                    "column": actual_col,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    table_name, col_name = actual_col.rsplit(".", 1)
+    if table_name in cte_outputs:
+        if col_name.lower() not in [c.lower() for c in cte_outputs[table_name]]:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_{side}_cte_col_not_found_{context}_{table_name}_{col_name}",
+                    category="filter_validity",
+                    severity="error",
+                    message=f"Column '{col_name}' not in CTE '{table_name}' outputs for filter {side} in {context}",
+                    context={
+                        "table": table_name,
+                        "column": col_name,
+                        "side": side,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        return issues
+    if table_name not in allowed_tables:
+        issues.append(
+            IntentIssue(
+                issue_id=f"filter_{side}_table_not_allowed_{context}_{table_name}",
+                category="filter_validity",
+                severity="error",
+                message=f"Table '{table_name}' not in allowed tables for filter {side} in {context}",
+                context={
+                    "table": table_name,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    if table_name not in schema.tables:
+        issues.append(
+            IntentIssue(
+                issue_id=f"filter_{side}_table_not_in_schema_{context}_{table_name}",
+                category="filter_validity",
+                severity="error",
+                message=f"Table '{table_name}' not in schema for filter {side} in {context}",
+                context={
+                    "table": table_name,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    table_meta = schema.tables[table_name]
+    col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+    if not col_meta:
+        issues.append(
+            IntentIssue(
+                issue_id=f"filter_{side}_col_not_found_{context}_{table_name}_{col_name}",
+                category="filter_validity",
+                severity="error",
+                message=f"Column '{col_name}' not in table '{table_name}' for filter {side} in {context}",
+                context={
+                    "table": table_name,
+                    "column": col_name,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+    return issues
+
+
+def validate_filters_schema(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``FilterParam`` entries against the schema.
+
+    Checks left and right column references, operator validity, and value-type validity, and also validates scalar functions on both sides.
+
+    Args:
+
+        filters_param: List of ``FilterParam`` instances to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not filters_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    for fp in filters_param:
+        param_key = fp.param_key or "unknown"
+        issues.extend(
+            _validate_filter_col(
+                fp.left_expr.primary_column,
+                schema,
+                allowed_tables,
+                cte_outputs,
+                context,
+                "left_col",
+                param_key,
+            )
+        )
+        if fp.right_expr:
+            issues.extend(
+                _validate_filter_col(
+                    fp.right_expr.primary_column,
+                    schema,
+                    allowed_tables,
+                    cte_outputs,
+                    context,
+                    "right_col",
+                    param_key,
+                )
+            )
+        if fp.op not in VALID_FILTER_OPS:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_invalid_op_{context}_{fp.op}",
+                    category="filter_validity",
+                    severity="error",
+                    message=f"Invalid filter operator '{fp.op}' in {context}",
+                    context={
+                        "operator": fp.op,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        if not fp.right_expr and fp.op not in ("is null", "is not null"):
+            if fp.value_type not in VALID_VALUE_TYPES:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"filter_invalid_value_type_{context}_{fp.value_type}",
+                        category="filter_validity",
+                        severity="error",
+                        message=f"Invalid filter value_type '{fp.value_type}' in {context}",
+                        context={
+                            "value_type": fp.value_type,
+                            "param_key": param_key,
+                            "location": context,
+                        },
+                    )
+                )
+        fp_left_scalar, _ = extract_functions_from_term(fp.left_expr.primary_term)
+        fp_right_scalar, _ = extract_functions_from_term(fp.right_expr.primary_term) if fp.right_expr else (None, None)
+        issues.extend(_validate_scalar_func_valid(fp_left_scalar, f"filter_{param_key}_left", context))
+        issues.extend(_validate_scalar_func_valid(fp_right_scalar, f"filter_{param_key}_right", context))
+        issues.extend(
+            validate_expr_no_extract_epoch(
+                fp.left_expr, f"filter_{param_key}_left", context
+            )
+        )
+        if fp.right_expr:
+            issues.extend(
+                validate_expr_no_extract_epoch(
+                    fp.right_expr, f"filter_{param_key}_right", context
+                )
+            )
+        if fp.bool_op not in ("AND", "OR"):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_invalid_bool_op_{context}_{fp.bool_op}",
+                    category="filter_validity",
+                    severity="error",
+                    message=f"Invalid filter bool_op '{fp.bool_op}' in {context}. Must be 'AND' or 'OR'.",
+                    context={
+                        "bool_op": fp.bool_op,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+    debug(f"[validation_schema.validate_filters_schema] {len(issues)} issues in {context}")
+    return issues
+
+
+def extract_agg_col(agg_expr: str) -> tuple:
+    """Extract ``(func, target, has_distinct)`` from an aggregation expression.
+
+    For example, ``"COUNT(DISTINCT table.col)"`` returns ``("count", "table.col", True)``.
+
+    Args:
+
+        agg_expr: The aggregation expression string.
+
+    Returns:
+
+        Tuple of ``(func, target, has_distinct)`` or ``(None, None, False)`` if the expression does not match the expected ``FUNC(...)`` pattern.
+    """
+    if not agg_expr:
+        return (None, None, False)
+    match = re.match(r"^\s*(\w+)\s*\(\s*(.*)\s*\)\s*$", agg_expr, re.IGNORECASE)
+    if not match:
+        return (None, None, False)
+    func = match.group(1).lower()
+    inner = match.group(2).strip()
+    has_distinct = False
+    actual_target = inner
+    if inner.upper().startswith("DISTINCT "):
+        has_distinct = True
+        actual_target = inner[9:].strip()
+    actual_target = extract_col_from_scalar_wrapper(actual_target)
+    return (func, actual_target, has_distinct)
+
+
+def extract_functions_from_term(term: str) -> tuple[str | None, str | None]:
+    """Extract the outer scalar and inner aggregation function names from a term string.
+
+    Handles patterns like ``"ROUND(SUM(table.col))"`` returning ``("round", "sum")`` and plain ``"SUM(table.col)"`` returning ``(None, "sum")``.
+
+    Args:
+
+        term: The expression term string.
+
+    Returns:
+
+        Tuple of ``(scalar_func, agg_func)`` where each is a lowercase function name string or ``None`` if not present.
+    """
+    result = extract_agg_col(term)
+    if len(result) != 3 or not result[0]:
+        return None, None
+    outer = result[0]
+    if outer in VALID_AGG_FUNCS:
+        return None, outer
+    inner_result = extract_agg_col(result[1]) if result[1] else (None, None, False)
+    if len(inner_result) == 3 and inner_result[0] and inner_result[0] in VALID_AGG_FUNCS:
+        return outer, inner_result[0]
+    return outer, None
+
+
+def _validate_having_agg(
+    agg_expr: str,
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+    context: str,
+    side: str,
+    param_key: str,
+) -> list[IntentIssue]:
+    """Validate a single HAVING aggregation expression (left or right side).
+
+    Args:
+
+        agg_expr: The aggregation expression string (for example ``"COUNT(table.col)"``).
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+        side: ``"left_agg"`` or ``"right_agg"``.
+        param_key: The ``param_key`` of the ``HavingParam`` (for issue IDs).
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not agg_expr:
+        return issues
+    cte_col_match = re.match(r"^\s*(\w+)\s*\.\s*(\w+)\s*$", agg_expr.strip())
+    if cte_col_match:
+        cte_name, col_name = cte_col_match.group(1), cte_col_match.group(2)
+        cte_cols = cte_outputs.get(cte_name, {})
+        col_meta = next(
+            (v for k, v in cte_cols.items() if k.lower() == col_name.lower()),
+            None,
+        )
+        if col_meta and (
+            col_meta.source == "aggregation" or (col_meta.agg_func or "").strip()
+        ):
+            return issues
+    result = extract_agg_col(agg_expr)
+    if len(result) != 3:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_invalid_format_{context}",
+                category="having_validity",
+                severity="error",
+                message=f"Invalid aggregation format in HAVING {side}: '{agg_expr}' in {context}",
+                context={
+                    "aggregation": agg_expr,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    func, actual_target, has_distinct = result
+    if not func:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_invalid_format_{context}_{agg_expr}",
+                category="having_validity",
+                severity="error",
+                message=f"Invalid aggregation format in HAVING {side}: '{agg_expr}' in {context}",
+                context={
+                    "aggregation": agg_expr,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    if func not in VALID_AGGREGATION_FUNCTIONS:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_invalid_func_{context}_{func}",
+                category="having_validity",
+                severity="error",
+                message=f"Invalid aggregation function '{func}' in HAVING {side} for {context}",
+                context={
+                    "function": func,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    if has_distinct and func != "count":
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_distinct_not_count_{context}_{func}",
+                category="having_validity",
+                severity="error",
+                message=f"DISTINCT only allowed with COUNT in HAVING, not {func.upper()} in {context}",
+                context={
+                    "function": func,
+                    "aggregation": agg_expr,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    if actual_target == "*":
+        if func != "count":
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_{side}_star_not_count_{context}_{func}",
+                    category="having_validity",
+                    severity="error",
+                    message=f"'*' only allowed with COUNT in HAVING, not {func.upper()} in {context}",
+                    context={
+                        "function": func,
+                        "side": side,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        return issues
+    if "." not in actual_target:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_unqualified_{context}_{actual_target}",
+                category="having_validity",
+                severity="error",
+                message=f"HAVING aggregation target must be qualified as table.column, got '{actual_target}' in {context}",
+                context={
+                    "target": actual_target,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    table_name, col_name = actual_target.rsplit(".", 1)
+    if table_name in cte_outputs:
+        if col_name.lower() not in [c.lower() for c in cte_outputs[table_name]]:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_{side}_cte_col_not_found_{context}_{table_name}_{col_name}",
+                    category="having_validity",
+                    severity="error",
+                    message=f"Column '{col_name}' not in CTE '{table_name}' outputs for HAVING {side} in {context}",
+                    context={
+                        "table": table_name,
+                        "column": col_name,
+                        "side": side,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        return issues
+    if table_name not in allowed_tables:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_{side}_table_not_allowed_{context}_{table_name}",
+                category="having_validity",
+                severity="error",
+                message=f"Table '{table_name}' not in allowed tables for HAVING {side} in {context}",
+                context={
+                    "table": table_name,
+                    "side": side,
+                    "param_key": param_key,
+                    "location": context,
+                },
+            )
+        )
+        return issues
+    if table_name in schema.tables:
+        table_meta = schema.tables[table_name]
+        col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+        if not col_meta:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_{side}_col_not_found_{context}_{table_name}_{col_name}",
+                    category="having_validity",
+                    severity="error",
+                    message=f"Column '{col_name}' not in table '{table_name}' for HAVING {side} in {context}",
+                    context={
+                        "table": table_name,
+                        "column": col_name,
+                        "side": side,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        elif func != "count":
+            value_type = col_meta.value_type or "string"
+            allowed_types = AGGREGATION_ALLOWED_COLUMN_TYPES.get(func, [])
+            if value_type not in allowed_types:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"having_{side}_type_mismatch_{context}_{func}_{col_name}",
+                        category="having_validity",
+                        severity="error",
+                        message=f"Cannot use {func.upper()} on column '{actual_target}' of type '{col_meta.data_type}' in HAVING {side} for {context}",
+                        context={
+                            "function": func,
+                            "column": actual_target,
+                            "column_type": col_meta.data_type,
+                            "side": side,
+                            "param_key": param_key,
+                            "location": context,
+                        },
+                    )
+                )
+    return issues
+
+
+def _reconstruct_agg_expr(expr: NormalizedExpr) -> str:
+    """Reconstruct an aggregation expression string from a ``NormalizedExpr``.
+
+    The ``NormalizedExpr`` decomposition strips the wrapping aggregation function, storing it on the ``MulGroup`` or expression level; this helper reassembles the canonical ``FUNC(column)`` string that ``_validate_having_agg`` expects.
+
+    Args:
+
+        expr: The ``NormalizedExpr`` from a ``HavingParam`` side.
+
+    Returns:
+
+        Reassembled expression such as ``"COUNT(orders.order_id)"``, or the bare ``primary_term`` when no aggregation is present.
+    """
+    agg_func = expr.agg_func
+    if not agg_func and expr.add_groups:
+        agg_func = expr.add_groups[0].agg_func
+    column = expr.primary_term
+    if not agg_func:
+        return column
+    return f"{agg_func.upper()}({column})"
+
+
+def validate_having_schema(
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    allowed_tables: set[str],
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``HavingParam`` entries against the schema.
+
+    Checks left and right aggregation expressions, operator validity, value-type validity, and scalar functions on both sides.
+
+    Args:
+
+        having_param: List of ``HavingParam`` instances to validate.
+        schema: The ``SchemaGraph``.
+        allowed_tables: Set of table names permitted in this context.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not having_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    for hp in having_param:
+        param_key = hp.param_key or "unknown"
+        issues.extend(
+            _validate_having_agg(
+                _reconstruct_agg_expr(hp.left_expr),
+                schema,
+                allowed_tables,
+                cte_outputs,
+                context,
+                "left_agg",
+                param_key,
+            )
+        )
+        if hp.right_expr:
+            issues.extend(
+                _validate_having_agg(
+                    _reconstruct_agg_expr(hp.right_expr),
+                    schema,
+                    allowed_tables,
+                    cte_outputs,
+                    context,
+                    "right_agg",
+                    param_key,
+                )
+            )
+        if hp.op not in VALID_HAVING_OPS:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_invalid_op_{context}_{hp.op}",
+                    category="having_validity",
+                    severity="error",
+                    message=f"Invalid HAVING operator '{hp.op}' in {context}",
+                    context={
+                        "operator": hp.op,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+        if not hp.right_expr:
+            if hp.value_type not in VALID_VALUE_TYPES:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"having_invalid_value_type_{context}_{hp.value_type}",
+                        category="having_validity",
+                        severity="error",
+                        message=f"Invalid HAVING value_type '{hp.value_type}' in {context}",
+                        context={
+                            "value_type": hp.value_type,
+                            "param_key": param_key,
+                            "location": context,
+                        },
+                    )
+                )
+            if hp.op not in ("is null", "is not null") and hp.raw_value is None:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"having_missing_value_{context}_{param_key}",
+                        category="having_validity",
+                        severity="error",
+                        message=(
+                            f"HAVING parameter '{param_key}' has no comparison value in {context}. "
+                            "Provide a numeric or string raw_value."
+                        ),
+                        context={
+                            "param_key": param_key,
+                            "op": hp.op,
+                            "location": context,
+                        },
+                    )
+                )
+        hp_left_scalar, _ = extract_functions_from_term(hp.left_expr.primary_term)
+        hp_right_scalar, _ = extract_functions_from_term(hp.right_expr.primary_term) if hp.right_expr else (None, None)
+        issues.extend(_validate_scalar_func_valid(hp_left_scalar, f"having_{param_key}_left", context))
+        issues.extend(_validate_scalar_func_valid(hp_right_scalar, f"having_{param_key}_right", context))
+        issues.extend(
+            validate_expr_no_extract_epoch(
+                hp.left_expr, f"having_{param_key}_left", context
+            )
+        )
+        if hp.right_expr:
+            issues.extend(
+                validate_expr_no_extract_epoch(
+                    hp.right_expr, f"having_{param_key}_right", context
+                )
+            )
+        if hp.bool_op not in ("AND", "OR"):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_invalid_bool_op_{context}_{hp.bool_op}",
+                    category="having_validity",
+                    severity="error",
+                    message=f"Invalid HAVING bool_op '{hp.bool_op}' in {context}. Must be 'AND' or 'OR'.",
+                    context={
+                        "bool_op": hp.bool_op,
+                        "param_key": param_key,
+                        "location": context,
+                    },
+                )
+            )
+    debug(f"[validation_schema.validate_having_schema] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_filter_ops_per_column(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that filter operators are valid for each column's data type and role.
+
+    Args:
+
+        filters_param: List of ``FilterParam`` instances to validate.
+        schema: The ``SchemaGraph``.
+        cte_outputs: Dict of CTE name to output column metadata.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects.
+    """
+    issues = []
+    if not filters_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    for fp in filters_param:
+        col_expr = fp.left_expr.primary_column
+        if not col_expr:
+            continue
+        actual_col = extract_col_from_scalar_wrapper(col_expr)
+        if "." not in actual_col:
+            continue
+        table_name, col_name = actual_col.rsplit(".", 1)
+        if table_name in cte_outputs:
+            cte_cols = cte_outputs[table_name]
+            matched_key = next((c for c in cte_cols if c.lower() == col_name.lower()), None)
+            if matched_key:
+                cte_meta = cte_cols[matched_key]
+                valid_ops = cte_meta.get_valid_filter_ops()
+                if valid_ops and fp.op not in valid_ops:
+                    issues.append(
+                        IntentIssue(
+                            issue_id=f"filter_op_invalid_for_cte_{context}_{actual_col}_{fp.op}",
+                            category="filter_validity",
+                            severity="error",
+                            message=f"Operator '{fp.op}' not valid for CTE column '{actual_col}' (role={cte_meta.role}, type={cte_meta.data_type}) in {context}. Valid: {valid_ops}",
+                            context={
+                                "column": actual_col,
+                                "operator": fp.op,
+                                "role": cte_meta.role,
+                                "data_type": cte_meta.data_type,
+                                "valid_ops": valid_ops,
+                                "location": context,
+                            },
+                        )
+                    )
+                if not cte_meta.filterable and fp.op not in ("is null", "is not null"):
+                    issues.append(
+                        IntentIssue(
+                            issue_id=f"filter_cte_col_not_filterable_{context}_{actual_col}",
+                            category="filter_validity",
+                            severity="warning",
+                            message=f"CTE column '{actual_col}' (role={cte_meta.role}) is not recommended for filtering in {context}",
+                            context={
+                                "column": actual_col,
+                                "role": cte_meta.role,
+                                "location": context,
+                            },
+                        )
+                    )
+            continue
+        if table_name not in schema.tables:
+            continue
+        table_meta = schema.tables[table_name]
+        col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+        if not col_meta:
+            continue
+        valid_ops = col_meta.get_valid_filter_ops()
+        if fp.op not in valid_ops:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_op_invalid_for_type_{context}_{actual_col}_{fp.op}",
+                    category="filter_validity",
+                    severity="error",
+                    message=f"Operator '{fp.op}' not valid for column '{actual_col}' (role={col_meta.role}, type={col_meta.data_type}) in {context}. Valid: {valid_ops}",
+                    context={
+                        "column": actual_col,
+                        "operator": fp.op,
+                        "role": col_meta.role,
+                        "data_type": col_meta.data_type,
+                        "valid_ops": valid_ops,
+                        "location": context,
+                    },
+                )
+            )
+        if not col_meta.is_filterable and fp.op not in ("is null", "is not null"):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_col_not_filterable_{context}_{actual_col}",
+                    category="filter_validity",
+                    severity="warning",
+                    message=f"Column '{actual_col}' (role={col_meta.role}) is not recommended for filtering in {context}",
+                    context={
+                        "column": actual_col,
+                        "role": col_meta.role,
+                        "location": context,
+                    },
+                )
+            )
+    debug(f"[validation_schema.validate_filter_ops_per_column] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_having_ops_per_column(
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that HAVING operators are valid for each column's type and role."""
+    issues: list[IntentIssue] = []
+    if not having_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    for hp in having_param:
+
+        def _check_expr(term: str, _hp: Any = hp) -> None:
+            result = extract_agg_col(term)
+            if len(result) == 3 and result[0] and result[1] and "." in result[1]:
+                _, actual_target, _ = result
+                table_name, col_name = actual_target.rsplit(".", 1)
+            else:
+                col = extract_col_from_scalar_wrapper(term)
+                if "." not in col:
+                    return
+                table_name, col_name = col.rsplit(".", 1)
+            if table_name in cte_outputs:
+                cte_cols = cte_outputs[table_name]
+                cte_meta = cte_cols.get(col_name) or cte_cols.get(col_name.lower())
+                if cte_meta:
+                    valid_ops = cte_meta.get_valid_having_ops()
+                    if valid_ops and _hp.op not in valid_ops:
+                        actual_col = f"{table_name}.{col_name}"
+                        issues.append(
+                            IntentIssue(
+                                issue_id=f"having_op_invalid_for_cte_{context}_{actual_col}_{_hp.op}",
+                                category="having_validity",
+                                severity="error",
+                                message=f"Operator '{_hp.op}' not valid for CTE column '{actual_col}' (role={cte_meta.role}, type={cte_meta.data_type}) in {context}. Valid: {valid_ops}",
+                                context={
+                                    "column": actual_col,
+                                    "operator": _hp.op,
+                                    "role": cte_meta.role,
+                                    "data_type": cte_meta.data_type,
+                                    "valid_ops": valid_ops,
+                                    "location": context,
+                                },
+                            )
+                        )
+            elif table_name in schema.tables:
+                tbl = schema.tables[table_name]
+                col_meta = tbl.columns.get(col_name) or tbl.columns.get(col_name.lower())
+                if col_meta:
+                    valid_ops = col_meta.get_valid_having_ops()
+                    if valid_ops and _hp.op not in valid_ops:
+                        actual_col = f"{table_name}.{col_name}"
+                        issues.append(
+                            IntentIssue(
+                                issue_id=f"having_op_invalid_for_column_{context}_{actual_col}_{_hp.op}",
+                                category="having_validity",
+                                severity="error",
+                                message=f"Operator '{_hp.op}' not valid for column '{actual_col}' (role={col_meta.role}, type={col_meta.data_type}) in {context}. Valid: {valid_ops}",
+                                context={
+                                    "column": actual_col,
+                                    "operator": _hp.op,
+                                    "role": col_meta.role,
+                                    "data_type": col_meta.data_type,
+                                    "valid_ops": valid_ops,
+                                    "location": context,
+                                },
+                            )
+                        )
+
+        _check_expr(hp.left_expr.primary_term)
+        if hp.right_expr:
+            _check_expr(hp.right_expr.primary_term)
+    if issues:
+        debug(f"[validation_schema.validate_having_ops_per_column] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_date_window_units(
+    filters_param: list[FilterParam],
+    cte_steps: list[RuntimeCteStep] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that ``date_window`` filters have a valid unit.
+
+    Args:
+
+        filters_param: List of ``FilterParam`` instances for the main query.
+        cte_steps: Optional list of CTE steps whose filters are also checked.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects for invalid ``date_window`` units.
+    """
+    issues: list[IntentIssue] = []
+    cte_steps = cte_steps or []
+
+    def check(fp: FilterParam, loc: str) -> None:
+        if fp.value_type != "date_window":
+            return
+        if not isinstance(fp.raw_value, dict):
+            return
+        unit = fp.raw_value.get("unit")
+        if unit is None:
+            return
+        if unit not in VALID_DATE_WINDOW_UNITS:
+            col = fp.left_expr.primary_column
+            issues.append(
+                IntentIssue(
+                    issue_id=f"date_window_invalid_unit_{context}_{col}",
+                    category="filter_validity",
+                    severity="error",
+                    message=f"{loc}: date_window filter on '{col}' has invalid unit '{unit}'. Valid: {sorted(VALID_DATE_WINDOW_UNITS)}",
+                    context={
+                        "column": col,
+                        "unit": unit,
+                        "valid_units": sorted(VALID_DATE_WINDOW_UNITS),
+                        "location": context,
+                    },
+                )
+            )
+
+    for fp in filters_param:
+        check(fp, f"{context} filter")
+    for cte in cte_steps:
+        for fp in cte.filters_param or []:
+            check(fp, f"CTE '{cte.cte_name}' filter")
+
+    if issues:
+        debug(f"[validation_schema.validate_date_window_units] {len(issues)} invalid units")
+    return issues
+
+
+def validate_date_diff_units(
+    filters_param: list[FilterParam],
+    cte_steps: list[RuntimeCteStep] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that ``date_diff`` filters have a valid unit and amount.
+
+    Args:
+
+        filters_param: List of ``FilterParam`` instances for the main query.
+        cte_steps: Optional list of CTE steps whose filters are also checked.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects for invalid ``date_diff`` config.
+    """
+    issues: list[IntentIssue] = []
+    cte_steps = cte_steps or []
+
+    def check(fp: FilterParam, loc: str) -> None:
+        if fp.value_type != "date_diff":
+            return
+        if not isinstance(fp.raw_value, dict):
+            return
+        unit = fp.raw_value.get("unit")
+        amount = fp.raw_value.get("amount")
+        if unit is not None and unit not in VALID_DATE_DIFF_UNITS:
+            col = fp.left_expr.primary_column or fp.left_expr.primary_term or fp.param_key or "expr"
+            issues.append(
+                IntentIssue(
+                    issue_id=f"date_diff_invalid_unit_{context}_{col}",
+                    category="date_diff",
+                    severity="error",
+                    message=f"{loc}: date_diff filter has invalid unit '{unit}'. Valid: {sorted(VALID_DATE_DIFF_UNITS)}",
+                    context={
+                        "column": col,
+                        "unit": unit,
+                        "valid_units": sorted(VALID_DATE_DIFF_UNITS),
+                        "location": context,
+                    },
+                )
+            )
+        if amount is not None and not isinstance(amount, (int, float)):
+            try:
+                int(amount)
+            except (TypeError, ValueError):
+                col = fp.left_expr.primary_column or fp.left_expr.primary_term or fp.param_key or "expr"
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"date_diff_invalid_amount_{context}_{col}",
+                        category="date_diff",
+                        severity="error",
+                        message=f"{loc}: date_diff filter has non-numeric amount '{amount}'",
+                        context={"column": col, "amount": amount, "location": context},
+                    )
+                )
+
+    for fp in filters_param:
+        check(fp, f"{context} filter")
+    for cte in cte_steps:
+        for fp in cte.filters_param or []:
+            check(fp, f"CTE '{cte.cte_name}' filter")
+
+    if issues:
+        debug(f"[validation_schema.validate_date_diff_units] {len(issues)} invalid configs")
+    return issues
+
+
+def validate_null_filters(
+    filters_param: list[FilterParam],
+    cte_steps: list[RuntimeCteStep] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that ``IS NULL`` / ``IS NOT NULL`` filters have the correct ``value_type``.
+
+    Args:
+
+        filters_param: List of ``FilterParam`` instances for the main query.
+        cte_steps: Optional list of CTE steps whose filters are also checked.
+        context: Label used in issue IDs and messages.
+
+    Returns:
+
+        List of ``IntentIssue`` objects for any NULL filter with incorrect ``value_type``.
+    """
+    issues = []
+    cte_steps = cte_steps or []
+
+    def check_filter(fp: FilterParam, loc: str) -> IntentIssue | None:
+        if fp.op in ("is null", "is not null"):
+            if fp.value_type and fp.value_type != "null":
+                col = fp.left_expr.primary_column
+                return IntentIssue(
+                    issue_id=f"null_filter_wrong_value_type_{col}",
+                    category="filter_structure",
+                    severity="error",
+                    message=f"{loc}: IS NULL filter on '{col}' should have value_type='null' or empty, got '{fp.value_type}'",
+                    context={
+                        "column": col,
+                        "op": fp.op,
+                        "expected_value_type": "null",
+                        "actual_value_type": fp.value_type,
+                    },
+                )
+        return None
+
+    for fp in filters_param:
+        issue = check_filter(fp, f"{context} filter")
+        if issue:
+            issues.append(issue)
+
+    for cte in cte_steps:
+        for fp in cte.filters_param or []:
+            issue = check_filter(fp, f"CTE '{cte.cte_name}' filter")
+            if issue:
+                issues.append(issue)
+
+    if issues:
+        debug(f"[validation_schema.validate_null_filters] FAILED with {len(issues)} issues")
+    else:
+        debug("[validation_schema.validate_null_filters] PASSED")
+    return issues
+
+
+def validate_filter_value_type_alignment(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    context: str = "main",
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+) -> list[IntentIssue]:
+    issues: list[IntentIssue] = []
+    cte_outputs = cte_outputs or {}
+    for fp in filters_param:
+        if fp.value_type not in {"string", "enum"}:
+            continue
+        if fp.raw_value is None:
+            continue
+        col = fp.left_expr.primary_column
+        parts = col.split(".", 1) if "." in col else None
+        if not parts:
+            continue
+        table_name, col_name = parts
+        col_meta = schema.get_column(table_name, col_name)
+        if col_meta:
+            if col_meta.is_foreign_key and col_meta.value_type in {"integer", "number"}:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"filter_string_on_fk_int_{table_name}_{col_name}_{context}",
+                        category="type_alignment",
+                        severity="warning",
+                        message=f"Filter on {col} uses string value '{fp.raw_value}' but column is a numeric FK in {context}. Filter should target the FK target table's descriptive column.",
+                        context={
+                            "column": col,
+                            "value": str(fp.raw_value),
+                            "value_type": fp.value_type,
+                            "column_type": col_meta.value_type,
+                            "location": context,
+                        },
+                    )
+                )
+                debug(f"[validation_schema.validate_filter_value_type_alignment] string value on FK int column {col}")
+            continue
+        if table_name in cte_outputs:
+            cte_cols = cte_outputs[table_name]
+            cte_meta = cte_cols.get(col_name) or cte_cols.get(col_name.lower())
+            if cte_meta and cte_meta.value_type in {"integer", "number"}:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"filter_string_on_cte_numeric_{table_name}_{col_name}_{context}",
+                        category="type_alignment",
+                        severity="warning",
+                        message=f"Filter on {col} uses string value '{fp.raw_value}' but CTE column is numeric ({cte_meta.value_type}) in {context}.",
+                        context={
+                            "column": col,
+                            "value": str(fp.raw_value),
+                            "value_type": fp.value_type,
+                            "column_type": cte_meta.value_type,
+                            "location": context,
+                        },
+                    )
+                )
+    return issues
+
+
+def validate_no_between_ops(
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    context: str = "main query",
+) -> list[IntentIssue]:
+    """Flag any remaining BETWEEN operators that were not decomposed.
+
+    After ``decompose_between_params`` all BETWEEN ops should be
+    replaced by >= / <= pairs.  This validator catches any that survived
+    as errors so the semantic repair loop can instruct the LLM to
+    rewrite them.
+
+    Args:     filters_param: Filter conditions to inspect.
+    having_param: Having conditions to inspect.     context: Description
+    of the query scope for issue messages.
+
+    Returns:     List of ``IntentIssue`` objects, one per surviving
+    BETWEEN op.
+    """
+    issues: list[IntentIssue] = []
+    for fp in filters_param:
+        if fp.op.lower() == "between":
+            col = fp.left_expr.primary_column
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_between_not_decomposed_{col}_{context}",
+                    category="operator",
+                    severity="error",
+                    message=(
+                        f"Filter on {col} still uses BETWEEN in {context}. "
+                        "Decompose into separate >= and <= conditions."
+                    ),
+                    context={"column": col, "op": fp.op, "location": context},
+                )
+            )
+    for hp in having_param:
+        if hp.op.lower() == "between":
+            col = hp.left_expr.primary_column
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_between_not_decomposed_{col}_{context}",
+                    category="operator",
+                    severity="error",
+                    message=(
+                        f"Having on {col} still uses BETWEEN in {context}. "
+                        "Decompose into separate >= and <= conditions."
+                    ),
+                    context={"column": col, "op": hp.op, "location": context},
+                )
+            )
+    if issues:
+        debug(f"[validation_schema.validate_no_between_ops] FAILED with {len(issues)} issues in {context}")
+    return issues
+
+
+def get_col_type(
+    col_expr: str,
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+) -> str | None:
+    """Get column ``value_type`` from schema or CTE output metadata.
+
+    Args:
+
+        col_expr: Column reference, optionally wrapped in scalar function calls.
+        schema: Schema graph containing table and column metadata.
+        cte_outputs: Map of CTE name to column output metadata.
+
+    Returns:
+
+        The ``value_type`` string for the resolved column, or ``None`` if it cannot be resolved.
+    """
+    actual_col = extract_col_from_scalar_wrapper(col_expr)
+    if "." not in actual_col:
+        return None
+    table_name, col_name = actual_col.rsplit(".", 1)
+    if table_name in cte_outputs:
+        meta = cte_outputs[table_name].get(col_name) or cte_outputs[table_name].get(col_name.lower())
+        return meta.value_type if meta else None
+    if table_name not in schema.tables:
+        return None
+    table_meta = schema.tables[table_name]
+    col_meta = table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+    if not col_meta:
+        return None
+    return col_meta.value_type
+
+
+def get_col_meta(
+    col_expr: str,
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+) -> Any | None:
+    """Get column metadata from the schema graph or synthesise it from CTE output metadata.
+
+    Args:
+
+        col_expr: Column reference, optionally wrapped in scalar function calls.
+        schema: Schema graph containing table and column metadata.
+        cte_outputs: Map of CTE name to column output metadata.
+
+    Returns:
+
+        A ``ColumnMetadata`` instance (real or synthetic) for the resolved column, or ``None`` if the column cannot be resolved.
+    """
+    actual_col = extract_col_from_scalar_wrapper(col_expr)
+    if "." not in actual_col:
+        return None
+    table_name, col_name = actual_col.rsplit(".", 1)
+    if table_name in cte_outputs:
+        cte_meta = cte_outputs[table_name].get(col_name) or cte_outputs[table_name].get(col_name.lower())
+        if not cte_meta:
+            return None
+        return ColumnMetadata(
+            name=col_name,
+            data_type=cte_meta.data_type or "unknown",
+            role=cte_meta.role,
+            is_filterable_override=cte_meta.filterable,
+            is_aggregatable_override=cte_meta.aggregatable,
+            is_groupable_override=cte_meta.groupable,
+            valid_filter_ops=list(cte_meta.valid_filter_ops or []),
+            valid_aggregations=list(cte_meta.valid_aggregations or []),
+            valid_having_ops=list(cte_meta.valid_having_ops or []),
+        )
+    if table_name not in schema.tables:
+        return None
+    table_meta = schema.tables[table_name]
+    return table_meta.columns.get(col_name) or table_meta.columns.get(col_name.lower())
+
+
+def is_col_numeric(
+    col_ref: str,
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+) -> bool | None:
+    """Return whether a column's value type is numeric.
+
+    Args:
+
+        col_ref: Fully-qualified column reference (``table.column``).
+        schema: Schema graph containing column type information.
+        cte_outputs: Map of CTE name to column output metadata.
+
+    Returns:
+
+        ``True`` if the column type is numeric, ``False`` if it is not, or ``None`` if the column cannot be resolved.
+    """
+    col_type = get_col_type(col_ref, schema, cte_outputs)
+    if col_type is None:
+        return None
+    return col_type in ("integer", "number")
+
+
+def is_col_arithmetic_role(
+    col_ref: str,
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+) -> bool | None:
+    """Return whether a column's role permits its use in arithmetic expressions.
+
+    Args:
+
+        col_ref: Fully-qualified column reference (``table.column``).
+        schema: Schema graph containing column role information.
+        cte_outputs: Map of CTE name to column output metadata.
+
+    Returns:
+
+        ``True`` if the column role is ``NUMERIC_MEASURE`` or ``NUMERIC_CATEGORICAL``; ``None`` if the column cannot be resolved.
+    """
+    meta = get_col_meta(col_ref, schema, cte_outputs)
+    if meta and meta.role:
+        return meta.role in ARITHMETIC_ROLES
+    actual_col = extract_col_from_scalar_wrapper(col_ref)
+    if "." in actual_col:
+        table_name, col_name = actual_col.rsplit(".", 1)
+        if table_name in cte_outputs:
+            cte_meta = cte_outputs[table_name].get(col_name) or cte_outputs[table_name].get(col_name.lower())
+            if cte_meta and cte_meta.role:
+                return cte_meta.role in ARITHMETIC_ROLES
+    return None