aetherdialect 0.1.0__py3-none-any.whl

text2sql/validation_semantic.py

@@ -0,0 +1,2122 @@
+"""Semantic and intent-level validation for SQL generation.
+
+Validates grain consistency (scalar/grouped/row_level vs aggregation and GROUP BY), semantic contradictions (for example MAX and MIN on the same column or scalar grain with ``expected_rows`` many), and expression-vs-expression filter/HAVING type compatibility. Validates filter/HAVING placement (no aggregation in WHERE, aggregation required in HAVING), nested and mixed aggregation rules, ORDER BY aggregation context, and SELECT/GROUP BY membership. Validates CTE grain consistency and dependency grains, orchestrates full intent validation, and provides auto-repair for misplaced filter/HAVING conditions.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .config import (
+    AGG_KEYWORDS_RE,
+    AGG_QUANTITY_RE,
+    COMPATIBLE_TYPE_PAIRS,
+    COUNT_THRESHOLD_TABLE_RE,
+    NUMERIC_ONLY_AGGREGATIONS,
+    NUMERIC_RESULT_AGGS,
+    NUMERIC_RESULT_OPS,
+    NUMERIC_RESULT_SCALARS,
+    SCALAR_FUNCTIONS_NUMERIC,
+    VALID_AGG_FUNCS,
+)
+from .contracts_base import (
+    CteOutputColumnMeta,
+    IntentIssue,
+    SchemaGraph,
+)
+from .contracts_core import (
+    FilterParam,
+    HavingParam,
+    MulGroup,
+    NormalizedExpr,
+    OrderByCol,
+    RuntimeCteStep,
+    SelectCol,
+)
+from .core_utils import debug
+from .validation_agg import (
+    expr_has_arithmetic,
+    expr_result_is_numeric,
+    strip_function_wrappers,
+    term_result_is_numeric,
+)
+from .validation_schema import (
+    extract_agg_col,
+    get_col_meta,
+    get_col_type,
+    is_col_arithmetic_role,
+    is_col_numeric,
+)
+
+
+def validate_grain_consistency(
+    grain: str,
+    select_cols: list[SelectCol],
+    group_by_cols: list[NormalizedExpr],
+    having_param: list[HavingParam],
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that the declared grain is consistent with aggregation and GROUP BY presence.
+
+    Args:
+
+        grain: Declared query grain (``"scalar"``, ``"grouped"``, or ``"row_level"``).
+        select_cols: SELECT column list to inspect for aggregation.
+        group_by_cols: GROUP BY expression list.
+        having_param: HAVING conditions to check for aggregation-free usage.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing grain inconsistencies.
+    """
+    issues = []
+    debug(
+        f"[validation_semantic.validate_grain_consistency] grain={grain}, group_by={len(group_by_cols)}, having={len(having_param)}"
+    )
+    if grain not in {"scalar", "grouped", "row_level"}:
+        issues.append(
+            IntentIssue(
+                issue_id=f"invalid_grain_{grain}",
+                category="grain_validity",
+                severity="error",
+                message=f"Invalid grain value '{grain}'. Allowed: scalar, grouped, row_level",
+                context={"grain": grain, "location": context},
+            )
+        )
+        return issues
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    has_group_by = bool(group_by_cols)
+    has_having = bool(having_param)
+    if grain == "grouped" and not has_group_by:
+        issues.append(
+            IntentIssue(
+                issue_id=f"grouped_without_group_by_{context}",
+                category="grain_consistency",
+                severity="error",
+                message=f"Grouped grain without GROUP BY columns in {context}",
+                context={"grain": grain, "location": context},
+            )
+        )
+        debug("[validation_semantic.validate_grain_consistency] grouped grain without group_by")
+    if grain in {"scalar", "row_level"} and has_group_by:
+        issues.append(
+            IntentIssue(
+                issue_id=f"group_by_with_{grain}_{context}",
+                category="grain_consistency",
+                severity="error",
+                message=f"GROUP BY columns present but grain={grain} in {context}",
+                context={
+                    "grain": grain,
+                    "group_by": [g.primary_column for g in group_by_cols],
+                    "location": context,
+                },
+            )
+        )
+        debug(f"[validation_semantic.validate_grain_consistency] group_by present but grain={grain}")
+    if has_agg and grain == "row_level":
+        agg_funcs = [sc.expr.primary_term for sc in select_cols if sc.is_aggregated]
+        issues.append(
+            IntentIssue(
+                issue_id=f"agg_with_row_level_{context}_{','.join(agg_funcs)}",
+                category="grain_consistency",
+                severity="error",
+                message=f"Aggregation functions {agg_funcs} with row_level grain in {context}",
+                context={"agg_funcs": agg_funcs, "grain": grain, "location": context},
+            )
+        )
+        debug("[validation_semantic.validate_grain_consistency] agg funcs with row_level grain")
+    if has_having and grain not in {"grouped", "scalar"}:
+        issues.append(
+            IntentIssue(
+                issue_id=f"having_without_agg_{grain}_{context}",
+                category="grain_consistency",
+                severity="error",
+                message=f"HAVING conditions without aggregation: grain={grain} but HAVING present in {context}",
+                context={
+                    "grain": grain,
+                    "having_count": len(having_param),
+                    "location": context,
+                },
+            )
+        )
+        debug(f"[validation_semantic.validate_grain_consistency] HAVING without aggregation: grain={grain}")
+    debug(f"[validation_semantic.validate_grain_consistency] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_grouped_requires_aggregation(
+    grain: str,
+    select_cols: list[SelectCol],
+    group_by_cols: list[NormalizedExpr],
+    context: str = "main",
+) -> list[IntentIssue]:
+    issues: list[IntentIssue] = []
+    if grain != "grouped":
+        return issues
+    if not group_by_cols:
+        return issues
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    if has_agg:
+        return issues
+    issues.append(
+        IntentIssue(
+            issue_id=f"grouped_without_aggregation_{context}",
+            category="grain_consistency",
+            severity="error",
+            message=f"Grouped grain with GROUP BY but no aggregation in SELECT in {context}. Use row_level with DISTINCT instead.",
+            context={
+                "grain": grain,
+                "group_by": [g.primary_column for g in group_by_cols],
+                "location": context,
+            },
+        )
+    )
+    debug(f"[validation_semantic.validate_grouped_requires_aggregation] grouped without aggregation in {context}")
+    return issues
+
+
+def validate_semantic_contradictions(
+    select_cols: list[SelectCol],
+    natural_language: str,
+    grain: str,
+    expected_rows: str,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Check for contradictory operations in the intent (for example MAX and MIN on the same column).
+
+    Args:
+
+        select_cols: SELECT column list to inspect for contradictory aggregations.
+        natural_language: Original natural-language question for pattern contradiction checks.
+        grain: Declared query grain used to assess expected-row contradictions.
+        expected_rows: Expected row count hint from the intent (for example ``"few"`` or ``"many"``).
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing semantic contradictions found.
+    """
+    issues = []
+    debug("[validation_semantic.validate_semantic_contradictions] checking for contradictions")
+    agg_funcs = {extract_agg_col(sc.expr.primary_term)[0] for sc in select_cols if sc.is_aggregated} - {None}
+    contradictory_pairs = [
+        ({"highest", "max"}, {"lowest", "min"}),
+        ({"most", "maximum"}, {"least", "minimum"}),
+        ({"first", "earliest"}, {"last", "latest"}),
+    ]
+    for set1, set2 in contradictory_pairs:
+        if agg_funcs & set1 and agg_funcs & set2:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"contradictory_ops_{','.join(sorted(set1 & agg_funcs))}_{','.join(sorted(set2 & agg_funcs))}",
+                    category="semantic_contradiction",
+                    severity="error",
+                    message=f"Intent contains contradictory operations: {set1 & agg_funcs} and {set2 & agg_funcs}",
+                    context={
+                        "ops1": list(set1 & agg_funcs),
+                        "ops2": list(set2 & agg_funcs),
+                        "location": context,
+                    },
+                )
+            )
+            debug(
+                f"[validation_semantic.validate_semantic_contradictions] CONTRADICTION: {set1 & agg_funcs} vs {set2 & agg_funcs}"
+            )
+    if grain == "scalar" and expected_rows in {"few", "many"}:
+        issues.append(
+            IntentIssue(
+                issue_id=f"grain_expected_mismatch_scalar_{expected_rows}",
+                category="semantic_contradiction",
+                severity="error",
+                message=f"Intent expects a single value (scalar) but also expects multiple rows ({expected_rows})",
+                context={
+                    "grain": grain,
+                    "expected_rows": expected_rows,
+                    "location": context,
+                },
+            )
+        )
+        debug(
+            f"[validation_semantic.validate_semantic_contradictions] CONTRADICTION: grain=scalar but expected_rows={expected_rows}"
+        )
+    nl = natural_language.lower() if natural_language else ""
+    contradiction_patterns = [
+        ("never", "total"),
+        ("no records", "count"),
+        ("zero", "greater than"),
+        ("empty", "count"),
+    ]
+    for pattern1, pattern2 in contradiction_patterns:
+        if pattern1 in nl and pattern2 in nl:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"nl_contradiction_{pattern1.replace(' ', '_')}_{pattern2.replace(' ', '_')}",
+                    category="semantic_contradiction",
+                    severity="warning",
+                    message=f"Intent may contain contradiction: mentions '{pattern1}' and '{pattern2}'",
+                    context={
+                        "pattern1": pattern1,
+                        "pattern2": pattern2,
+                        "location": context,
+                    },
+                )
+            )
+            debug(
+                f"[validation_semantic.validate_semantic_contradictions] POTENTIAL CONTRADICTION: '{pattern1}' and '{pattern2}'"
+            )
+    debug(f"[validation_semantic.validate_semantic_contradictions] {len(issues)} issues")
+    return issues
+
+
+def _validate_single_expr_types(
+    expr: NormalizedExpr,
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]],
+    location: str,
+    context: str,
+) -> list[IntentIssue]:
+    """Validate that all columns in an expression are type-appropriate for their usage.
+
+    Checks that columns appearing in arithmetic or numeric-input aggregation/scalar contexts have a numeric type and an arithmetic-compatible role.
+
+    Args:
+
+        expr: The normalised expression to validate.
+        schema: Schema graph for resolving column types and roles.
+        cte_outputs: Map of CTE name to column output metadata.
+        location: Human-readable location label for issue context (for example ``"select_cols[0]"``).
+        context: Query context label (for example ``"main query"`` or ``"CTE 'base'"``).
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing type or role violations found.
+    """
+    issues: list[IntentIssue] = []
+    has_arith = expr_has_arithmetic(expr)
+    for g in expr.add_groups + expr.sub_groups:
+        group_requires_numeric = (g.agg_func and g.agg_func in NUMERIC_ONLY_AGGREGATIONS) or (
+            g.inner_scalar_func and g.inner_scalar_func in SCALAR_FUNCTIONS_NUMERIC
+        )
+        expr_requires_numeric = (expr.agg_func and expr.agg_func in NUMERIC_ONLY_AGGREGATIONS) or (
+            expr.inner_scalar_func and expr.inner_scalar_func in SCALAR_FUNCTIONS_NUMERIC
+        )
+        needs_numeric = (
+            has_arith
+            or len(g.multiply) > 1
+            or len(g.divide) > 0
+            or g.coefficient != 1.0
+            or group_requires_numeric
+            or expr_requires_numeric
+        )
+        if not needs_numeric:
+            continue
+        if g.inner_scalar_func:
+            col_check_skippable = (
+                g.inner_scalar_func in NUMERIC_RESULT_SCALARS and g.inner_scalar_func not in SCALAR_FUNCTIONS_NUMERIC
+            )
+        elif g.agg_func:
+            col_check_skippable = g.agg_func in NUMERIC_RESULT_AGGS and g.agg_func not in NUMERIC_ONLY_AGGREGATIONS
+        elif expr.inner_scalar_func:
+            col_check_skippable = (
+                expr.inner_scalar_func in NUMERIC_RESULT_SCALARS
+                and expr.inner_scalar_func not in SCALAR_FUNCTIONS_NUMERIC
+            )
+        elif expr.agg_func:
+            col_check_skippable = (
+                expr.agg_func in NUMERIC_RESULT_AGGS and expr.agg_func not in NUMERIC_ONLY_AGGREGATIONS
+            )
+        else:
+            col_check_skippable = False
+        for term in g.multiply:
+            if col_check_skippable or term_result_is_numeric(term):
+                continue
+            ref = strip_function_wrappers(term)
+            if not ref or ref == "*" or "." not in ref:
+                continue
+            is_num = is_col_numeric(ref, schema, cte_outputs)
+            if is_num is False:
+                col_type = get_col_type(ref, schema, cte_outputs) or "unknown"
+                if has_arith and col_type in ("date", "date_window"):
+                    continue
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"expr_non_numeric_{location}_{ref}",
+                        category="expression_type",
+                        severity="error",
+                        message=f"Non-numeric column '{ref}' (type={col_type}) in arithmetic at {location} in {context}",
+                        context={
+                            "column": ref,
+                            "data_type": col_type,
+                            "location": location,
+                        },
+                    )
+                )
+            role_ok = is_col_arithmetic_role(ref, schema, cte_outputs)
+            if role_ok is False:
+                meta = get_col_meta(ref, schema, cte_outputs)
+                role = meta.role if meta else "unknown"
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"expr_invalid_role_{location}_{ref}",
+                        category="expression_type",
+                        severity="warning",
+                        message=f"Column '{ref}' (role={role}) not suited for arithmetic at {location} in {context}",
+                        context={"column": ref, "role": role, "location": location},
+                    )
+                )
+        for div_term in g.divide:
+            if col_check_skippable or term_result_is_numeric(div_term):
+                continue
+            ref = strip_function_wrappers(div_term)
+            if not ref or ref == "*" or "." not in ref:
+                continue
+            is_num = is_col_numeric(ref, schema, cte_outputs)
+            if is_num is False:
+                col_type = get_col_type(ref, schema, cte_outputs) or "unknown"
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"expr_non_numeric_div_{location}_{ref}",
+                        category="expression_type",
+                        severity="error",
+                        message=f"Non-numeric column '{ref}' (type={col_type}) in divide at {location} in {context}",
+                        context={
+                            "column": ref,
+                            "data_type": col_type,
+                            "location": location,
+                        },
+                    )
+                )
+    return issues
+
+
+def validate_expr_vs_expr_filters(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``FilterParam`` expression-vs-expression comparisons for numeric type compatibility.
+
+    Args:
+
+        filters_param: List of filter conditions to validate.
+        schema: Schema graph for resolving column types.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where a numeric expression is compared to a non-numeric expression within the same filter condition.
+    """
+    issues = []
+    if not filters_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    debug("[validation_semantic.validate_expr_vs_expr_filters] checking expr-vs-expr type compatibility")
+    for fp in filters_param:
+        if not fp.right_expr:
+            continue
+        left_col = fp.left_expr.primary_column
+        right_col = fp.right_expr.primary_column
+        if left_col == right_col:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"self_comparison_filter_{left_col}",
+                    category="filter_semantic",
+                    severity="error",
+                    message=f"Self-comparison in filter: {left_col} compared to itself",
+                    context={
+                        "column": left_col,
+                        "param_key": fp.param_key,
+                        "location": context,
+                    },
+                )
+            )
+            debug(f"[validation_semantic.validate_expr_vs_expr_filters] self-comparison: {left_col}")
+            continue
+        left_type = get_col_type(left_col, schema, cte_outputs)
+        right_type = get_col_type(right_col, schema, cte_outputs)
+        if left_type and right_type:
+            if (left_type, right_type) not in COMPATIBLE_TYPE_PAIRS and (
+                right_type,
+                left_type,
+            ) not in COMPATIBLE_TYPE_PAIRS:
+                if left_type != right_type:
+                    issues.append(
+                        IntentIssue(
+                            issue_id=f"filter_type_mismatch_{left_col}_{right_col}",
+                            category="filter_semantic",
+                            severity="error",
+                            message=f"Type mismatch in filter: {left_col} ({left_type}) vs {right_col} ({right_type})",
+                            context={
+                                "left_col": left_col,
+                                "left_type": left_type,
+                                "right_col": right_col,
+                                "right_type": right_type,
+                                "param_key": fp.param_key,
+                                "location": context,
+                            },
+                        )
+                    )
+                    debug(
+                        f"[validation_semantic.validate_expr_vs_expr_filters] type mismatch: {left_type} vs {right_type}"
+                    )
+        left_meta = get_col_meta(left_col, schema, cte_outputs)
+        right_meta = get_col_meta(right_col, schema, cte_outputs)
+        if left_meta and right_meta:
+            if left_meta.is_primary_key or right_meta.is_primary_key:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"pk_comparison_filter_{left_col}_{right_col}",
+                        category="filter_semantic",
+                        severity="warning",
+                        message=f"Comparing primary key in filter: {left_col} vs {right_col}",
+                        context={
+                            "left_col": left_col,
+                            "right_col": right_col,
+                            "param_key": fp.param_key,
+                            "location": context,
+                        },
+                    )
+                )
+                debug(f"[validation_semantic.validate_expr_vs_expr_filters] PK comparison: {left_col}")
+    debug(f"[validation_semantic.validate_expr_vs_expr_filters] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_agg_vs_agg_having(
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``HavingParam`` expression-vs-expression comparisons for numeric type compatibility.
+
+    Args:
+
+        having_param: List of HAVING conditions to validate.
+        schema: Schema graph for resolving column types.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where numeric and non-numeric aggregation results are compared within the same HAVING condition.
+    """
+    issues = []
+    if not having_param:
+        return []
+    cte_outputs = cte_outputs or {}
+    debug("[validation_semantic.validate_agg_vs_agg_having] checking agg-vs-agg type compatibility")
+    for hp in having_param:
+        if not hp.right_expr:
+            continue
+        left_term = hp.left_expr.primary_term
+        right_term = hp.right_expr.primary_term
+        left_result = extract_agg_col(left_term)
+        right_result = extract_agg_col(right_term)
+        if len(left_result) != 3 or len(right_result) != 3:
+            continue
+        left_func, left_target, _ = left_result
+        right_func, right_target, _ = right_result
+        if not left_func or not right_func:
+            continue
+        if left_target == right_target and left_func == right_func:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"self_comparison_having_{left_term}",
+                    category="having_semantic",
+                    severity="error",
+                    message=f"Self-comparison in HAVING: {left_term} compared to itself",
+                    context={
+                        "aggregation": left_term,
+                        "param_key": hp.param_key,
+                        "location": context,
+                    },
+                )
+            )
+            debug(f"[validation_semantic.validate_agg_vs_agg_having] self-comparison: {left_term}")
+            continue
+        if left_target != "*" and right_target != "*":
+            left_type = get_col_type(left_target, schema, cte_outputs)
+            right_type = get_col_type(right_target, schema, cte_outputs)
+            if left_type and right_type:
+                numeric_funcs = {"sum", "avg", "count"}
+                if left_func in numeric_funcs and right_func in numeric_funcs:
+                    pass
+                elif (left_type, right_type) not in COMPATIBLE_TYPE_PAIRS and (
+                    right_type,
+                    left_type,
+                ) not in COMPATIBLE_TYPE_PAIRS:
+                    if left_type != right_type:
+                        issues.append(
+                            IntentIssue(
+                                issue_id=f"having_type_mismatch_{left_term}_{right_term}",
+                                category="having_semantic",
+                                severity="warning",
+                                message=f"Type mismatch in HAVING: {left_term} ({left_type}) vs {right_term} ({right_type})",
+                                context={
+                                    "left_agg": left_term,
+                                    "left_type": left_type,
+                                    "right_agg": right_term,
+                                    "right_type": right_type,
+                                    "param_key": hp.param_key,
+                                    "location": context,
+                                },
+                            )
+                        )
+                        debug(
+                            f"[validation_semantic.validate_agg_vs_agg_having] type mismatch: {left_type} vs {right_type}"
+                        )
+    debug(f"[validation_semantic.validate_agg_vs_agg_having] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_select_expr_types(
+    select_cols: list[SelectCol],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that SELECT column arithmetic expressions reference numeric columns with valid roles.
+
+    Args:
+
+        select_cols: SELECT column list whose expressions are to be validated.
+        schema: Schema graph for resolving column types and roles.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing expression type violations in SELECT.
+    """
+    issues: list[IntentIssue] = []
+    cte_outputs = cte_outputs or {}
+    for idx, sc in enumerate(select_cols or []):
+        issues.extend(_validate_single_expr_types(sc.expr, schema, cte_outputs, f"select_cols[{idx}]", context))
+    if issues:
+        debug(f"[validation_semantic.validate_select_expr_types] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_order_by_expr_types(
+    order_by_cols: list[OrderByCol],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that ORDER BY column arithmetic expressions reference numeric columns with valid roles.
+
+    Args:
+
+        order_by_cols: ORDER BY column list whose expressions are to be validated.
+        schema: Schema graph for resolving column types and roles.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing expression type violations in ORDER BY.
+    """
+    issues: list[IntentIssue] = []
+    cte_outputs = cte_outputs or {}
+    for idx, obc in enumerate(order_by_cols or []):
+        issues.extend(_validate_single_expr_types(obc.expr, schema, cte_outputs, f"order_by_cols[{idx}]", context))
+    if issues:
+        debug(f"[validation_semantic.validate_order_by_expr_types] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_filter_expr_types(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``FilterParam`` expression types, cross-expression type compatibility, and operator compatibility.
+
+    Args:
+
+        filters_param: List of filter conditions to validate.
+        schema: Schema graph for resolving column types.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing type mismatches or operator incompatibilities in filter conditions.
+    """
+    issues: list[IntentIssue] = []
+    cte_outputs = cte_outputs or {}
+    for fp in filters_param or []:
+        pk = fp.param_key or "unknown"
+        issues.extend(_validate_single_expr_types(fp.left_expr, schema, cte_outputs, f"filter_{pk}_left", context))
+        if fp.right_expr:
+            issues.extend(
+                _validate_single_expr_types(fp.right_expr, schema, cte_outputs, f"filter_{pk}_right", context)
+            )
+            left_num = expr_result_is_numeric(fp.left_expr, schema, cte_outputs)
+            right_num = expr_result_is_numeric(fp.right_expr, schema, cte_outputs)
+            if left_num is not None and right_num is not None and left_num != right_num:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"filter_cross_type_mismatch_{pk}",
+                        category="expression_type",
+                        severity="error",
+                        message=f"Filter '{pk}' compares numeric expression to non-numeric expression in {context}",
+                        context={
+                            "param_key": pk,
+                            "left_numeric": left_num,
+                            "right_numeric": right_num,
+                            "location": context,
+                        },
+                    )
+                )
+        left_arith = expr_has_arithmetic(fp.left_expr)
+        right_arith = fp.right_expr and expr_has_arithmetic(fp.right_expr)
+        if (left_arith or right_arith) and fp.op not in NUMERIC_RESULT_OPS and fp.op not in ("is null", "is not null"):
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_op_on_arith_{pk}_{fp.op}",
+                    category="expression_type",
+                    severity="error",
+                    message=f"Operator '{fp.op}' invalid on arithmetic expression in filter '{pk}' in {context}. Expected: {sorted(NUMERIC_RESULT_OPS)}",
+                    context={
+                        "param_key": pk,
+                        "operator": fp.op,
+                        "valid_ops": sorted(NUMERIC_RESULT_OPS),
+                        "location": context,
+                    },
+                )
+            )
+    if issues:
+        debug(f"[validation_semantic.validate_filter_expr_types] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_having_expr_types(
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate ``HavingParam`` expression types and cross-expression numeric type compatibility.
+
+    Args:
+
+        having_param: List of HAVING conditions to validate.
+        schema: Schema graph for resolving column types.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing type mismatches in HAVING conditions.
+    """
+    issues: list[IntentIssue] = []
+    cte_outputs = cte_outputs or {}
+    for hp in having_param or []:
+        pk = hp.param_key or "unknown"
+        issues.extend(_validate_single_expr_types(hp.left_expr, schema, cte_outputs, f"having_{pk}_left", context))
+        if hp.right_expr:
+            issues.extend(
+                _validate_single_expr_types(hp.right_expr, schema, cte_outputs, f"having_{pk}_right", context)
+            )
+            left_num = expr_result_is_numeric(hp.left_expr, schema, cte_outputs)
+            right_num = expr_result_is_numeric(hp.right_expr, schema, cte_outputs)
+            if left_num is not None and right_num is not None and left_num != right_num:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"having_cross_type_mismatch_{pk}",
+                        category="expression_type",
+                        severity="error",
+                        message=f"Having '{pk}' compares numeric expression to non-numeric expression in {context}",
+                        context={
+                            "param_key": pk,
+                            "left_numeric": left_num,
+                            "right_numeric": right_num,
+                            "location": context,
+                        },
+                    )
+                )
+    if issues:
+        debug(f"[validation_semantic.validate_having_expr_types] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_arith_expression_semantics(
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    cte_outputs: dict[str, dict[str, CteOutputColumnMeta]] | None = None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that arithmetic expressions in filters and HAVING use compatible operand types.
+
+    Args:
+
+        filters_param: Filter conditions to inspect for arithmetic type violations.
+        having_param: HAVING conditions to inspect.
+        schema: Schema graph for resolving column types.
+        cte_outputs: Optional map of CTE name to column output metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing arithmetic expression semantic violations.
+    """
+    issues = []
+    cte_outputs = cte_outputs or {}
+    debug("[validation_semantic.validate_arith_expression_semantics] checking arithmetic semantics")
+    for fp in filters_param:
+        if expr_has_arithmetic(fp.left_expr):
+            issues.extend(
+                _validate_single_expr_types(
+                    fp.left_expr,
+                    schema,
+                    cte_outputs,
+                    f"filter_{fp.param_key or 'unknown'}_left",
+                    context,
+                )
+            )
+        if fp.right_expr and expr_has_arithmetic(fp.right_expr):
+            issues.extend(
+                _validate_single_expr_types(
+                    fp.right_expr,
+                    schema,
+                    cte_outputs,
+                    f"filter_{fp.param_key or 'unknown'}_right",
+                    context,
+                )
+            )
+    for hp in having_param:
+        if expr_has_arithmetic(hp.left_expr):
+            issues.extend(
+                _validate_single_expr_types(
+                    hp.left_expr,
+                    schema,
+                    cte_outputs,
+                    f"having_{hp.param_key or 'unknown'}_left",
+                    context,
+                )
+            )
+        if hp.right_expr and expr_has_arithmetic(hp.right_expr):
+            issues.extend(
+                _validate_single_expr_types(
+                    hp.right_expr,
+                    schema,
+                    cte_outputs,
+                    f"having_{hp.param_key or 'unknown'}_right",
+                    context,
+                )
+            )
+    debug(f"[validation_semantic.validate_arith_expression_semantics] {len(issues)} issues in {context}")
+    return issues
+
+
+def _term_has_aggregation(term: str) -> bool:
+    """Return whether a single multiply/divide term string contains an inline aggregation call.
+
+    Args:
+
+        term: A raw SQL term string (for example a single element from ``MulGroup.multiply``).
+
+    Returns:
+
+        ``True`` if the term begins with or contains one of the standard aggregation functions (``COUNT``, ``SUM``, ``AVG``, ``MIN``, ``MAX``); ``False`` otherwise.
+    """
+    upper = term.upper()
+    return any(upper.startswith(f"{a.upper()}(") or f" {a.upper()}(" in upper for a in VALID_AGG_FUNCS)
+
+
+def validate_filter_no_aggregation(filters_param: list[FilterParam], context: str = "main") -> list[IntentIssue]:
+    """Validate that filter (WHERE) conditions do not contain aggregation functions.
+
+    Args:
+
+        filters_param: List of filter conditions to inspect.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where a filter expression contains an aggregation function that should be in HAVING instead.
+    """
+    issues: list[IntentIssue] = []
+    debug("[validation_semantic.validate_filter_no_aggregation] checking filter aggregation ban")
+    for fp in filters_param or []:
+        pk = fp.param_key or "unknown"
+        if fp.left_expr.has_aggregation:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_has_aggregation_{pk}_left",
+                    category="filter_aggregation",
+                    severity="error",
+                    message=f"Filter '{pk}' left expression contains aggregation in {context}; use HAVING instead of WHERE",
+                    context={"param_key": pk, "side": "left", "location": context},
+                )
+            )
+        if fp.right_expr and fp.right_expr.has_aggregation:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"filter_has_aggregation_{pk}_right",
+                    category="filter_aggregation",
+                    severity="error",
+                    message=f"Filter '{pk}' right expression contains aggregation in {context}; use HAVING instead of WHERE",
+                    context={"param_key": pk, "side": "right", "location": context},
+                )
+            )
+    if issues:
+        debug(f"[validation_semantic.validate_filter_no_aggregation] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_having_requires_aggregation(having_param: list[HavingParam], context: str = "main") -> list[IntentIssue]:
+    """Validate that each HAVING condition contains at least one aggregation (left or right expression).
+
+    Args:
+
+        having_param: List of HAVING conditions to inspect.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where a HAVING condition lacks any aggregation and should be moved to WHERE instead.
+    """
+    issues: list[IntentIssue] = []
+    debug("[validation_semantic.validate_having_requires_aggregation] checking having aggregation requirement")
+    for hp in having_param or []:
+        pk = hp.param_key or "unknown"
+        has_agg = hp.left_expr.has_aggregation or (
+            hp.right_expr is not None and hp.right_expr.has_aggregation
+        )
+        if not has_agg:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"having_missing_aggregation_{pk}",
+                    category="having_aggregation",
+                    severity="error",
+                    message=f"Having '{pk}' has no aggregation in {context}; belongs in WHERE not HAVING",
+                    context={"param_key": pk, "location": context},
+                )
+            )
+    if issues:
+        debug(f"[validation_semantic.validate_having_requires_aggregation] {len(issues)} issues in {context}")
+    return issues
+
+
+def _check_nested_aggregation(expr: NormalizedExpr, location: str, context: str) -> list[IntentIssue]:
+    """Check a single ``NormalizedExpr`` for double-wrap (nested) aggregation.
+
+    Detects cases where an expression-level aggregation wraps a group-level aggregation, or either level wraps an inline aggregation term.
+
+    Args:
+
+        expr: The normalised expression to inspect.
+        location: Human-readable location label for issue context.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing nested aggregation patterns found.
+    """
+    issues: list[IntentIssue] = []
+    for g in expr.add_groups + expr.sub_groups:
+        group_inline_agg = any(_term_has_aggregation(t) for t in g.multiply + g.divide)
+        if expr.agg_func and g.agg_func:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"nested_agg_expr_group_{location}",
+                    category="nested_aggregation",
+                    severity="error",
+                    message=f"Nested aggregation {expr.agg_func.upper()}({g.agg_func.upper()}(...)) at {location} in {context}",
+                    context={
+                        "outer": expr.agg_func,
+                        "inner": g.agg_func,
+                        "location": location,
+                    },
+                )
+            )
+        if expr.agg_func and group_inline_agg:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"nested_agg_expr_inline_{location}",
+                    category="nested_aggregation",
+                    severity="error",
+                    message=f"Nested aggregation: expr-level {expr.agg_func.upper()} wraps inline aggregation at {location} in {context}",
+                    context={"outer": expr.agg_func, "location": location},
+                )
+            )
+        if g.agg_func and group_inline_agg:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"nested_agg_group_inline_{location}",
+                    category="nested_aggregation",
+                    severity="error",
+                    message=f"Nested aggregation: group-level {g.agg_func.upper()} wraps inline aggregation at {location} in {context}",
+                    context={"outer": g.agg_func, "location": location},
+                )
+            )
+    return issues
+
+
+def validate_no_nested_aggregation(
+    select_cols: list[SelectCol],
+    order_by_cols: list[OrderByCol],
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that no expression across SELECT, ORDER BY, filters, or HAVING contains nested aggregation.
+
+    Args:
+
+        select_cols: SELECT column list to inspect.
+        order_by_cols: ORDER BY column list to inspect.
+        filters_param: Filter conditions to inspect.
+        having_param: HAVING conditions to inspect.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing nested aggregation violations found.
+    """
+    issues: list[IntentIssue] = []
+    debug("[validation_semantic.validate_no_nested_aggregation] checking nested aggregation")
+    for idx, sc in enumerate(select_cols or []):
+        issues.extend(_check_nested_aggregation(sc.expr, f"select_cols[{idx}]", context))
+    for idx, obc in enumerate(order_by_cols or []):
+        issues.extend(_check_nested_aggregation(obc.expr, f"order_by_cols[{idx}]", context))
+    for fp in filters_param or []:
+        pk = fp.param_key or "unknown"
+        issues.extend(_check_nested_aggregation(fp.left_expr, f"filter_{pk}_left", context))
+        if fp.right_expr:
+            issues.extend(_check_nested_aggregation(fp.right_expr, f"filter_{pk}_right", context))
+    for hp in having_param or []:
+        pk = hp.param_key or "unknown"
+        issues.extend(_check_nested_aggregation(hp.left_expr, f"having_{pk}_left", context))
+        if hp.right_expr:
+            issues.extend(_check_nested_aggregation(hp.right_expr, f"having_{pk}_right", context))
+    if issues:
+        debug(f"[validation_semantic.validate_no_nested_aggregation] {len(issues)} issues in {context}")
+    return issues
+
+
+def _check_mixed_aggregation_in_group(group: MulGroup, location: str, context: str) -> list[IntentIssue]:
+    """Check a single ``MulGroup`` for mixed aggregated and bare column terms.
+
+    A group-level ``agg_func`` is considered to cover all terms; the check only applies to groups without an outer aggregation.
+
+    Args:
+
+        group: The ``MulGroup`` to inspect.
+        location: Human-readable location label for issue context.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where aggregated and non-aggregated bare column terms appear together in the same multiply/divide group.
+    """
+    issues: list[IntentIssue] = []
+    if group.agg_func:
+        return issues
+    all_terms = list(group.multiply) + list(group.divide)
+    if len(all_terms) < 2:
+        return issues
+    agg_terms: list[str] = []
+    bare_terms: list[str] = []
+    for term in all_terms:
+        if _term_has_aggregation(term):
+            agg_terms.append(term)
+        else:
+            ref = strip_function_wrappers(term)
+            if ref and ref != "*" and "." in ref:
+                bare_terms.append(term)
+    if agg_terms and bare_terms:
+        issues.append(
+            IntentIssue(
+                issue_id=f"mixed_agg_bare_{location}",
+                category="mixed_aggregation",
+                severity="error",
+                message=f"MulGroup at {location} in {context} mixes aggregated terms ({', '.join(agg_terms)}) with bare columns ({', '.join(bare_terms)})",
+                context={
+                    "agg_terms": agg_terms,
+                    "bare_terms": bare_terms,
+                    "location": location,
+                },
+            )
+        )
+    return issues
+
+
+def _check_mixed_aggregation_in_expr(expr: NormalizedExpr, location: str, context: str) -> list[IntentIssue]:
+    """Check all ``MulGroup`` entries in a ``NormalizedExpr`` for mixed aggregation.
+
+    Delegates per-group checking to ``_check_mixed_aggregation_in_group`` and additionally checks across add/sub groups when no outer expression-level aggregation is present.
+
+    Args:
+
+        expr: The normalised expression to inspect.
+        location: Human-readable location label for issue context.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing mixed aggregation violations found within or across ``MulGroup`` entries.
+    """
+    issues: list[IntentIssue] = []
+    for idx, g in enumerate(expr.add_groups):
+        issues.extend(_check_mixed_aggregation_in_group(g, f"{location}_add[{idx}]", context))
+    for idx, g in enumerate(expr.sub_groups):
+        issues.extend(_check_mixed_aggregation_in_group(g, f"{location}_sub[{idx}]", context))
+    all_groups = list(expr.add_groups) + list(expr.sub_groups)
+    if len(all_groups) >= 2 and not expr.agg_func:
+        agg_groups: list[str] = []
+        bare_groups: list[str] = []
+        for g in all_groups:
+            has_agg = g.agg_func or any(_term_has_aggregation(t) for t in g.multiply + g.divide)
+            sig = g.signature_key
+            if has_agg:
+                agg_groups.append(sig)
+            else:
+                has_bare = any("." in t and not _term_has_aggregation(t) for t in g.multiply + g.divide)
+                if has_bare:
+                    bare_groups.append(sig)
+        if agg_groups and bare_groups:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"mixed_agg_across_groups_{location}",
+                    category="mixed_aggregation",
+                    severity="error",
+                    message=f"Expression at {location} in {context} mixes aggregated groups ({', '.join(agg_groups)}) with bare column groups ({', '.join(bare_groups)})",
+                    context={
+                        "agg_groups": agg_groups,
+                        "bare_groups": bare_groups,
+                        "location": location,
+                    },
+                )
+            )
+    return issues
+
+
+def validate_mixed_aggregation_in_mulgroup(
+    select_cols: list[SelectCol],
+    order_by_cols: list[OrderByCol],
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that no ``MulGroup`` mixes aggregated terms with bare column references.
+
+    Args:
+
+        select_cols: SELECT column list to inspect.
+        order_by_cols: ORDER BY column list to inspect.
+        filters_param: Filter conditions to inspect.
+        having_param: HAVING conditions to inspect.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing mixed aggregation violations across all inspected clause types.
+    """
+    issues: list[IntentIssue] = []
+    debug("[validation_semantic.validate_mixed_aggregation_in_mulgroup] checking mixed aggregation")
+    for idx, sc in enumerate(select_cols or []):
+        issues.extend(_check_mixed_aggregation_in_expr(sc.expr, f"select_cols[{idx}]", context))
+    for idx, obc in enumerate(order_by_cols or []):
+        issues.extend(_check_mixed_aggregation_in_expr(obc.expr, f"order_by_cols[{idx}]", context))
+    for fp in filters_param or []:
+        pk = fp.param_key or "unknown"
+        issues.extend(_check_mixed_aggregation_in_expr(fp.left_expr, f"filter_{pk}_left", context))
+        if fp.right_expr:
+            issues.extend(_check_mixed_aggregation_in_expr(fp.right_expr, f"filter_{pk}_right", context))
+    for hp in having_param or []:
+        pk = hp.param_key or "unknown"
+        issues.extend(_check_mixed_aggregation_in_expr(hp.left_expr, f"having_{pk}_left", context))
+        if hp.right_expr:
+            issues.extend(_check_mixed_aggregation_in_expr(hp.right_expr, f"having_{pk}_right", context))
+    if issues:
+        debug(f"[validation_semantic.validate_mixed_aggregation_in_mulgroup] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_order_by_aggregation_context(
+    order_by_cols: list[OrderByCol], grain: str, context: str = "main"
+) -> list[IntentIssue]:
+    """Validate that ORDER BY aggregation expressions are compatible with the query grain.
+
+    Args:
+
+        order_by_cols: ORDER BY column list to inspect for aggregation usage.
+        grain: Declared query grain; aggregation in ORDER BY is invalid when grain is ``"row_level"``.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where ORDER BY contains aggregation incompatible with the declared grain.
+    """
+    issues: list[IntentIssue] = []
+    debug(f"[validation_semantic.validate_order_by_aggregation_context] grain={grain}")
+    if grain != "row_level":
+        return issues
+    for idx, obc in enumerate(order_by_cols or []):
+        if obc.expr.has_aggregation:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"order_by_agg_row_level_{idx}",
+                    category="order_by_aggregation",
+                    severity="error",
+                    message=f"Order-by[{idx}] contains aggregation but grain is row_level in {context}",
+                    context={"index": idx, "grain": grain, "location": context},
+                )
+            )
+    if issues:
+        debug(f"[validation_semantic.validate_order_by_aggregation_context] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_select_group_by_membership(
+    select_cols: list[SelectCol],
+    group_by_cols: list[NormalizedExpr],
+    grain: str,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Validate that every non-aggregated SELECT column appears in GROUP BY when grain is ``"grouped"``.
+
+    Args:
+
+        select_cols: SELECT column list to inspect.
+        group_by_cols: GROUP BY expression list providing the allowed column set.
+        grain: Declared query grain; check only applies when grain is ``"grouped"``.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances for non-aggregated SELECT columns absent from the GROUP BY clause.
+    """
+    issues: list[IntentIssue] = []
+    debug(f"[validation_semantic.validate_select_group_by_membership] grain={grain}, group_by={len(group_by_cols)}")
+    if grain != "grouped" or not group_by_cols:
+        return issues
+    group_by_set = frozenset(g.primary_column.lower() for g in group_by_cols)
+    for idx, sc in enumerate(select_cols or []):
+        if sc.is_aggregated:
+            continue
+        col = sc.expr.primary_column
+        if not col:
+            continue
+        if col.lower() not in group_by_set:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"select_not_in_group_by_{idx}_{col}",
+                    category="group_by_membership",
+                    severity="error",
+                    message=f"Non-aggregated select column '{col}' at index {idx} not in GROUP BY in {context}",
+                    context={
+                        "column": col,
+                        "index": idx,
+                        "group_by_cols": [g.primary_column for g in group_by_cols],
+                        "location": context,
+                    },
+                )
+            )
+    if issues:
+        debug(f"[validation_semantic.validate_select_group_by_membership] {len(issues)} issues in {context}")
+    return issues
+
+
+def validate_cte_grain_consistency(cte: RuntimeCteStep, context: str) -> list[IntentIssue]:
+    """Validate that a CTE's declared grain is consistent with its aggregation and GROUP BY.
+
+    Args:
+
+        cte: The CTE step to validate.
+        context: Query context label for issue messages (typically the CTE name).
+
+    Returns:
+
+        List of ``IntentIssue`` instances describing grain inconsistencies within the CTE, such as ``"grouped"`` without GROUP BY or aggregation with ``"row_level"``.
+    """
+    issues = []
+    grain = cte.grain
+    group_by = cte.group_by_cols or []
+    select_cols = cte.select_cols or []
+    having_param = cte.having_param or []
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    if grain == "grouped" and not group_by:
+        issues.append(
+            IntentIssue(
+                issue_id=f"cte_grouped_no_groupby_{cte.cte_name}",
+                category="cte_grain_consistency",
+                severity="error",
+                message=f"CTE '{cte.cte_name}' has grain=grouped but no group_by_cols",
+                context={"cte_name": cte.cte_name, "grain": grain},
+            )
+        )
+    if grain in {"scalar", "row_level"} and group_by:
+        issues.append(
+            IntentIssue(
+                issue_id=f"cte_groupby_with_{grain}_{cte.cte_name}",
+                category="cte_grain_consistency",
+                severity="error",
+                message=f"CTE '{cte.cte_name}' has group_by_cols but grain={grain}",
+                context={
+                    "cte_name": cte.cte_name,
+                    "grain": grain,
+                    "group_by": group_by,
+                },
+            )
+        )
+    if has_agg and grain == "row_level":
+        agg_funcs = [sc.expr.primary_term for sc in select_cols if sc.is_aggregated]
+        issues.append(
+            IntentIssue(
+                issue_id=f"cte_agg_row_level_{cte.cte_name}",
+                category="cte_grain_consistency",
+                severity="error",
+                message=f"CTE '{cte.cte_name}' has aggregation with row_level grain",
+                context={
+                    "cte_name": cte.cte_name,
+                    "agg_funcs": agg_funcs,
+                    "grain": grain,
+                },
+            )
+        )
+    if has_agg and not group_by and grain != "scalar":
+        issues.append(
+            IntentIssue(
+                issue_id=f"cte_{cte.cte_name}_agg_no_groupby",
+                category="cte_grain_consistency",
+                severity="warning",
+                message=f"CTE '{cte.cte_name}' has aggregation but no group_by_cols (expected grain=scalar or group_by)",
+                context={"cte_name": cte.cte_name, "grain": grain},
+            )
+        )
+    if having_param and not has_agg:
+        issues.append(
+            IntentIssue(
+                issue_id=f"cte_{cte.cte_name}_having_no_agg",
+                category="cte_aggregation",
+                severity="error",
+                message=f"CTE '{cte.cte_name}' has HAVING clause but no aggregation",
+                context={"cte_name": cte.cte_name, "having_count": len(having_param)},
+            )
+        )
+    debug(f"[validation_semantic.validate_cte_grain_consistency] {len(issues)} issues for CTE '{cte.cte_name}'")
+    return issues
+
+
+def validate_cte_dependency_grains(cte_steps: list[RuntimeCteStep], main_grain: str) -> list[IntentIssue]:
+    """Validate that CTE grains are compatible with their upstream dependencies and the main query grain.
+
+    Args:
+
+        cte_steps: Ordered list of CTE steps in the query plan.
+        main_grain: Declared grain of the main (outer) query.
+
+    Returns:
+
+        List of ``IntentIssue`` instances where a ``"row_level"`` CTE or the main query depends on an aggregated (``"grouped"`` or ``"scalar"``) CTE.
+    """
+    issues = []
+    cte_grains: dict[str, str] = {}
+    debug(
+        f"[validation_semantic.validate_cte_dependency_grains] validating {len(cte_steps)} CTEs against main grain '{main_grain}'"
+    )
+    for cte in cte_steps:
+        cte_grains[cte.cte_name] = cte.grain
+    for cte in cte_steps:
+        cte_name = cte.cte_name
+        cte_grain = cte.grain
+        for table in cte.tables:
+            if table in cte_grains:
+                dep_grain = cte_grains[table]
+                if cte_grain == "row_level" and dep_grain in {"grouped", "scalar"}:
+                    issues.append(
+                        IntentIssue(
+                            issue_id=f"cte_grain_incompatible_{cte_name}_{table}",
+                            category="cte_grain_compatibility",
+                            severity="warning",
+                            message=f"CTE '{cte_name}' (row_level) depends on aggregated CTE '{table}' ({dep_grain})",
+                            context={
+                                "cte_name": cte_name,
+                                "cte_grain": cte_grain,
+                                "dep_cte": table,
+                                "dep_grain": dep_grain,
+                            },
+                        )
+                    )
+    final_cte = cte_steps[-1] if cte_steps else None
+    if final_cte:
+        final_grain = final_cte.grain
+        if main_grain == "row_level" and final_grain in {"grouped", "scalar"}:
+            issues.append(
+                IntentIssue(
+                    issue_id=f"cte_main_grain_incompatible_{final_cte.cte_name}",
+                    category="cte_grain_compatibility",
+                    severity="warning",
+                    message=f"Main query (row_level) uses aggregated CTE '{final_cte.cte_name}' ({final_grain})",
+                    context={
+                        "final_cte": final_cte.cte_name,
+                        "final_grain": final_grain,
+                        "main_grain": main_grain,
+                    },
+                )
+            )
+    debug(f"[validation_semantic.validate_cte_dependency_grains] {len(issues)} grain compatibility issues")
+    return issues
+
+
+def _flip_comparison_op(op: str) -> str:
+    """Return the operator when swapping left and right sides of a comparison."""
+    from .config import OP_FLIP
+
+    return OP_FLIP.get(op, op)
+
+
+def auto_repair_filter_having(
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    cte_names: set[str] | None = None,
+) -> tuple[list[FilterParam], list[HavingParam]]:
+    """Repair misplaced filter/HAVING conditions by moving or flipping.
+
+    Moves filter conditions whose left expression contains aggregation into
+    HAVING. For HAVING: when left lacks aggregation but right has it, flip
+    to put aggregation on left and keep in HAVING; when both lack agg,
+    move to filters.
+
+    Args:
+
+        filters_param: Original list of WHERE filter conditions.
+        having_param: Original list of HAVING conditions.
+        cte_names: Set of CTE names for context when processing main query.
+
+    Returns:
+
+        A 2-tuple ``(repaired_filters, repaired_having)``.
+    """
+    repaired_filters: list[FilterParam] = []
+    repaired_having: list[HavingParam] = []
+    for fp in filters_param or []:
+        if fp.left_expr.has_aggregation:
+            repaired_having.append(
+                HavingParam(
+                    left_expr=fp.left_expr,
+                    op=fp.op,
+                    right_expr=fp.right_expr,
+                    value_type=fp.value_type,
+                    param_key=fp.param_key,
+                    raw_value=fp.raw_value,
+                )
+            )
+            debug(f"[validation_semantic.auto_repair_filter_having] filter->having: {fp.param_key}")
+        else:
+            repaired_filters.append(fp)
+    for hp in having_param or []:
+        if hp.left_expr.has_aggregation:
+            repaired_having.append(hp)
+        elif hp.right_expr and hp.right_expr.has_aggregation:
+            repaired_having.append(
+                HavingParam(
+                    left_expr=hp.right_expr,
+                    op=_flip_comparison_op(hp.op),
+                    right_expr=hp.left_expr,
+                    value_type=hp.value_type,
+                    param_key=hp.param_key,
+                    raw_value=hp.raw_value,
+                )
+            )
+            debug(f"[validation_semantic.auto_repair_filter_having] having flip (agg->left): {hp.param_key}")
+        else:
+            repaired_filters.append(
+                FilterParam(
+                    left_expr=hp.left_expr,
+                    op=hp.op,
+                    right_expr=hp.right_expr,
+                    value_type=hp.value_type,
+                    param_key=hp.param_key,
+                    raw_value=hp.raw_value,
+                )
+            )
+            debug(f"[validation_semantic.auto_repair_filter_having] having->filter: {hp.param_key}")
+    return repaired_filters, repaired_having
+
+
+def validate_question_aggregation_hint(
+    natural_language: str,
+    select_cols: list[SelectCol],
+    having_param: list[HavingParam],
+    grain: str,
+    context: str = "main",
+    filters_param: list[FilterParam] | None = None,
+    schema: SchemaGraph | None = None,
+) -> list[IntentIssue]:
+    """Detect quantity-comparison phrases that imply aggregation.
+
+    Scans the natural-language question for patterns such as ``"more than N"``, ``"at least N"``, or ``"fewer than N"`` and, when a match is found but the intent has no aggregation, no HAVING conditions, and the grain is ``"row_level"``, raises an error so the semantic repair loop can inject aggregation structure. The check is suppressed when the matched numeric value already corresponds to a row-level filter on a known numeric column, indicating that the phrase describes a simple comparison rather than an aggregation threshold.
+
+    Args:
+
+        natural_language: Original user question text.
+        select_cols: SELECT column list to check for existing aggregation.
+        having_param: HAVING condition list.
+        grain: Declared query grain from the intent.
+        context: Query context label for issue messages.
+        filters_param: Filter list to cross-check matched numeric values.
+        schema: Schema graph for column type lookups.
+
+    Returns:
+
+        List of ``IntentIssue`` instances.
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+    match = AGG_QUANTITY_RE.search(natural_language)
+    if not match:
+        return issues
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    has_having = bool(having_param)
+    if has_agg or has_having:
+        return issues
+    if grain in ("grouped", "scalar"):
+        return issues
+    if filters_param and schema:
+        matched_text = match.group()
+        numeric_tokens = [tok for tok in matched_text.split() if tok.isdigit()]
+        if numeric_tokens:
+            matched_value = int(numeric_tokens[-1])
+            for fp in filters_param:
+                if fp.raw_value is None:
+                    continue
+                try:
+                    filter_val = float(fp.raw_value)
+                except (TypeError, ValueError):
+                    continue
+                if filter_val != matched_value:
+                    continue
+                col_ref = fp.left_expr.primary_column
+                if col_ref and is_col_numeric(col_ref, schema, {}) is True:
+                    debug(
+                        f"[validation_semantic.validate_question_aggregation_hint] "
+                        f"suppressed: '{matched_text}' matches numeric filter on {col_ref}"
+                    )
+                    return issues
+    issues.append(
+        IntentIssue(
+            issue_id=f"missing_aggregation_hint_{context}",
+            category="aggregation_hint",
+            severity="warning",
+            message=(
+                f"Question contains quantity comparison '{match.group()}' which typically "
+                f"requires COUNT/SUM aggregation with GROUP BY and HAVING, but intent has "
+                f"no aggregation and grain is '{grain}'."
+            ),
+            context={"matched_phrase": match.group(), "location": context},
+        )
+    )
+    debug(
+        f"[validation_semantic.validate_question_aggregation_hint] "
+        f"detected aggregation hint '{match.group()}' but no agg in intent"
+    )
+    return issues
+
+
+def validate_question_agg_keyword_coverage(
+    natural_language: str,
+    select_cols: list[SelectCol],
+    having_param: list[HavingParam],
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag aggregation-keyword questions whose intent has no aggregation.
+
+    Fires when the question contains an aggregation keyword such as ``total``, ``count``, ``average``, or ``sum`` but the intent contains neither an aggregated ``SelectCol`` nor a HAVING condition; this catches cases where the LLM drops all aggregation structure and the ``repair_grouped_to_distinct`` pass silently converts the intent to a row-level ``DISTINCT`` query.
+    """
+    if not natural_language:
+        return []
+    if not AGG_KEYWORDS_RE.search(natural_language):
+        return []
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    if has_agg or having_param:
+        return []
+    issue = IntentIssue(
+        issue_id=f"agg_keyword_missing_{context}",
+        category="agg_keyword_missing",
+        severity="warning",
+        message=(
+            f"Question contains an aggregation keyword but the intent "
+            f"has no aggregated column and no HAVING condition in "
+            f"{context}. Add the appropriate aggregation function and "
+            f"set grain to 'grouped'."
+        ),
+        context={"location": context},
+    )
+    debug(
+        "[validation_semantic.validate_question_agg_keyword_coverage] "
+        "aggregation keyword in question but no agg in intent"
+    )
+    return [issue]
+
+
+_NUMERIC_LITERAL_RE = re.compile(r"\b\d+(?:\.\d+)?\b")
+_YEAR_IN_STRING_RE = re.compile(r"\b(19|20)\d{2}\b")
+_TOP_N_RE = re.compile(r"\b(?:top|first|bottom|last|least|most)\s+\d+\b", re.IGNORECASE)
+_DISTINCT_RE = re.compile(r"\b(?:distinct|unique)\b", re.IGNORECASE)
+
+
+def validate_question_numeric_coverage(
+    natural_language: str,
+    filters_param: list[FilterParam],
+    having_param: list[HavingParam],
+    limit: int | None,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag numeric literals in the question missing from intent conditions.
+
+    Extracts all numbers from the natural-language question and checks whether each appears as a filter value, HAVING value, or limit, excluding numbers matched by top-N phrasing since they map to ``LIMIT``.
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+
+    top_n_numbers: set[str] = set()
+    for m in _TOP_N_RE.finditer(natural_language):
+        for tok in m.group().split():
+            if tok.isdigit():
+                top_n_numbers.add(tok)
+
+    all_numbers = _NUMERIC_LITERAL_RE.findall(natural_language)
+    if not all_numbers:
+        return issues
+
+    intent_values: set[float] = set()
+    covered_number_strs: set[str] = set()
+    for fp in filters_param:
+        if fp.raw_value is not None:
+            try:
+                intent_values.add(float(fp.raw_value))
+            except (TypeError, ValueError):
+                pass
+            if isinstance(fp.raw_value, str):
+                for m in _YEAR_IN_STRING_RE.finditer(fp.raw_value):
+                    covered_number_strs.add(m.group())
+    for hp in having_param:
+        if hp.raw_value is not None:
+            try:
+                intent_values.add(float(hp.raw_value))
+            except (TypeError, ValueError):
+                pass
+            if isinstance(hp.raw_value, str):
+                for m in _YEAR_IN_STRING_RE.finditer(hp.raw_value):
+                    covered_number_strs.add(m.group())
+    if limit is not None:
+        intent_values.add(float(limit))
+
+    for num_str in all_numbers:
+        if num_str in top_n_numbers:
+            continue
+        if num_str in covered_number_strs:
+            continue
+        try:
+            val = float(num_str)
+        except ValueError:
+            continue
+        if val in intent_values:
+            continue
+        issues.append(
+            IntentIssue(
+                issue_id=f"missing_numeric_{num_str}_{context}",
+                category="missing_numeric_filter",
+                severity="warning",
+                message=(
+                    f"Question mentions number '{num_str}' which does not "
+                    f"appear in any filter, having condition, or limit in "
+                    f"{context}."
+                ),
+                context={"value": num_str, "location": context},
+            )
+        )
+        debug(
+            f"[validation_semantic.validate_question_numeric_coverage] "
+            f"number '{num_str}' not found in intent conditions"
+        )
+    return issues
+
+
+def validate_question_distinct_hint(
+    natural_language: str,
+    select_cols: list[SelectCol],
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag when the question explicitly requests distinct results but no ``DISTINCT`` keyword appears in any expression."""
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+    if not _DISTINCT_RE.search(natural_language):
+        return issues
+    for sc in select_cols:
+        raw = sc.expr if isinstance(sc.expr, str) else str(sc.expr)
+        if "DISTINCT" in raw.upper():
+            return issues
+    issues.append(
+        IntentIssue(
+            issue_id=f"missing_distinct_{context}",
+            category="missing_distinct",
+            severity="warning",
+            message=(
+                f"Question explicitly requests distinct/unique results "
+                f"but no DISTINCT keyword found in any expression in "
+                f"{context}."
+            ),
+            context={"location": context},
+        )
+    )
+    debug(
+        "[validation_semantic.validate_question_distinct_hint] "
+        "question has distinct/unique keyword but intent lacks DISTINCT"
+    )
+    return issues
+
+
+def _english_plural_forms(word: str) -> list[str]:
+    """Return a list of plausible English plural forms for *word*.
+
+    Covers the three most common patterns: consonant + ``y`` → ``-ies`` (``category`` → ``categories``), sibilant ending → ``-es`` (``class`` → ``classes``), and default → ``-s`` (``product`` → ``products``); the original word is always included so callers can iterate one list.
+    """
+    forms = [word]
+    w = word.lower()
+    if w.endswith("y") and len(w) > 2 and w[-2] not in "aeiou":
+        forms.append(w[:-1] + "ies")
+    elif w.endswith(("s", "sh", "ch", "x", "z")):
+        forms.append(w + "es")
+    else:
+        forms.append(w + "s")
+    return forms
+
+
+def _word_is_column_component(
+    word: str,
+    intent_tables: set[str],
+    schema: SchemaGraph,
+) -> bool:
+    """Return ``True`` when *word* is a component of a column name on any intent table.
+
+    Column names use underscore-separated tokens; a word matches when it equals any underscore-separated part of a column name on a table that is already present in the intent, which suppresses false positives such as matching the ``product`` table because the question contains the phrase ``"product category"`` as a reference to the ``product_category`` column on an existing intent table.
+    """
+    w = word.lower()
+    for table_name in intent_tables:
+        tbl_meta = schema.tables.get(table_name)
+        if not tbl_meta:
+            continue
+        for col_name in tbl_meta.columns:
+            parts = col_name.lower().split("_")
+            if w in parts:
+                return True
+    return False
+
+
+def validate_question_table_mentions(
+    natural_language: str,
+    intent_tables: list[str],
+    schema: SchemaGraph,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag schema tables mentioned in the question but absent from intent tables.
+
+    Tokenizes the question and checks each token against known schema table names, matching both the exact table name and its common English plural forms, and suppresses matches when the table name word is also a component of a column name on an already-included intent table to avoid mistaking column-concept language for a table reference; tables already in the intent are skipped.
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language or not schema:
+        return issues
+    intent_set = {t.lower() for t in (intent_tables or [])}
+    nl_lower = natural_language.lower()
+    for table_name in schema.tables:
+        if table_name.lower() in intent_set:
+            continue
+        forms = _english_plural_forms(table_name.lower())
+        alternatives = "|".join(re.escape(f) for f in forms)
+        pattern = rf"\b(?:{alternatives})\b"
+        if not re.search(pattern, nl_lower):
+            continue
+        if _word_is_column_component(table_name.lower(), intent_set, schema):
+            debug(
+                f"[validation_semantic.validate_question_table_mentions] "
+                f"suppressed '{table_name}' — word is a column component "
+                f"on an intent table"
+            )
+            continue
+        issues.append(
+            IntentIssue(
+                issue_id=f"missing_table_{table_name}_{context}",
+                category="missing_scoping_table",
+                severity="warning",
+                message=(
+                    f"Question mentions table '{table_name}' which "
+                    f"exists in the schema but is not included in "
+                    f"intent tables in {context}."
+                ),
+                context={"table": table_name, "location": context},
+            )
+        )
+        debug(
+            f"[validation_semantic.validate_question_table_mentions] table '{table_name}' in question but not in intent"
+        )
+    return issues
+
+
+def validate_no_pk_fk_filters(
+    filters_param: list[FilterParam],
+    schema: SchemaGraph,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag filters that operate directly on primary-key or foreign-key columns.
+
+    Primary-key filters are almost certainly hallucinations and are reported as ``"error"``. Foreign-key filters with a literal comparison value are also reported as ``"error"`` because they indicate the LLM should join the referenced table and filter on its descriptive column instead, while foreign-key filters that compare two columns (``right_expr`` present) are reported as ``"warning"`` to avoid blocking legitimate cross-column joins.
+    """
+    issues: list[IntentIssue] = []
+    for fp in filters_param:
+        # Collect column references to inspect: always left_expr; also
+        # right_expr when it is a column reference (not a literal).
+        col_refs: list[str] = []
+        left_col = fp.left_expr.primary_column
+        if left_col and "." in left_col:
+            col_refs.append(left_col)
+        if fp.right_expr is not None:
+            right_col = fp.right_expr.primary_column
+            if right_col and "." in right_col:
+                col_refs.append(right_col)
+
+        for col_ref in col_refs:
+            table, col = col_ref.split(".", 1)
+            tbl_meta = schema.tables.get(table)
+            if not tbl_meta:
+                continue
+            col_meta = tbl_meta.columns.get(col)
+            if not col_meta:
+                continue
+            if col_meta.is_primary_key:
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"pk_fk_filter_{col_ref}_{context}",
+                        category="pk_fk_filter",
+                        severity="error",
+                        message=(
+                            f"Filter on primary-key column '{col_ref}' in "
+                            f"{context}. Use a descriptive column on the "
+                            f"target table instead of filtering by "
+                            f"identifier."
+                        ),
+                        context={
+                            "column": col_ref,
+                            "kind": "primary-key",
+                            "location": context,
+                        },
+                    )
+                )
+                debug(f"[validation_semantic.validate_no_pk_fk_filters] primary-key filter on '{col_ref}'")
+            elif col_meta.is_foreign_key:
+                literal_filter = fp.raw_value is not None and fp.right_expr is None
+                severity = "error" if literal_filter else "warning"
+                issues.append(
+                    IntentIssue(
+                        issue_id=f"pk_fk_filter_{col_ref}_{context}",
+                        category="pk_fk_filter",
+                        severity=severity,
+                        message=(
+                            f"Filter on foreign-key column '{col_ref}' in "
+                            f"{context}. Consider joining the referenced "
+                            f"table and filtering on its descriptive "
+                            f"column instead."
+                        ),
+                        context={
+                            "column": col_ref,
+                            "kind": "foreign-key",
+                            "location": context,
+                        },
+                    )
+                )
+                debug(
+                    f"[validation_semantic.validate_no_pk_fk_filters] "
+                    f"foreign-key filter on '{col_ref}' severity={severity}"
+                )
+    return issues
+
+
+def validate_threshold_missing_having(
+    natural_language: str,
+    select_cols: list[SelectCol],
+    having_param: list[HavingParam],
+    grain: str,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Detect threshold phrases where aggregation exists but HAVING is absent.
+
+    Fires when the question contains phrases like ``"more than N"`` or ``"at least N"``, the intent has aggregation and is grouped, but no HAVING condition is defined, which typically indicates the LLM produced the aggregation but forgot the threshold filter.
+
+    Args:
+
+        natural_language: Original user question text.
+        select_cols: SELECT column list to check for existing aggregation.
+        having_param: HAVING condition list.
+        grain: Declared query grain from the intent.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances (at most one).
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+    if grain != "grouped":
+        return issues
+    has_agg = any(sc.is_aggregated for sc in select_cols)
+    if not has_agg:
+        return issues
+    if having_param:
+        return issues
+    match = AGG_QUANTITY_RE.search(natural_language)
+    if not match:
+        return issues
+    issues.append(
+        IntentIssue(
+            issue_id=f"threshold_missing_having_{context}",
+            category="threshold_missing_having",
+            severity="error",
+            message=(
+                f"Question contains threshold phrase '{match.group()}' and "
+                f"intent has aggregation, but no HAVING condition is defined. "
+                f"Add a HAVING clause for the threshold."
+            ),
+            context={"matched_phrase": match.group(), "location": context},
+        )
+    )
+    debug(f"[validation_semantic.validate_threshold_missing_having] threshold phrase '{match.group()}' without HAVING")
+    return issues
+
+
+def validate_count_threshold_missing_having(
+    natural_language: str,
+    tables: list[str],
+    having_param: list[HavingParam],
+    schema: SchemaGraph,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Flag count-threshold phrases that lack a HAVING clause.
+
+    Fires when the question contains an explicit count threshold such as ``"in exactly N <entity>"`` but no HAVING condition references a ``COUNT(DISTINCT ...)`` over the foreign-key column that points at the threshold entity; the issue message includes the specific FK column so the LLM repair loop can synthesise the correct HAVING clause.
+
+    Args:
+
+        natural_language: Original user question text.
+        tables: Table list from the intent.
+        having_param: Current HAVING conditions.
+        schema: ``SchemaGraph`` providing FK metadata.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances (at most one).
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+
+    match = COUNT_THRESHOLD_TABLE_RE.search(natural_language)
+    if not match:
+        return issues
+
+    threshold_count = match.group(1)
+    threshold_word = match.group(2)
+    threshold_table = _resolve_word_to_table(threshold_word, schema)
+    if not threshold_table:
+        return issues
+
+    if having_param:
+        return issues
+
+    fk_col = _find_fk_column_for_target(threshold_table, tables, schema)
+
+    hint = (
+        f"COUNT(DISTINCT {fk_col}) = {threshold_count}"
+        if fk_col
+        else f"COUNT(DISTINCT <fk_column_referencing_{threshold_table}>) = {threshold_count}"
+    )
+
+    issues.append(
+        IntentIssue(
+            issue_id=f"count_threshold_missing_having_{context}",
+            category="count_threshold_missing_having",
+            severity="error",
+            message=(
+                f"Question implies a count threshold of "
+                f"{threshold_count} for entity '{threshold_table}' "
+                f"but no HAVING clause is defined. Add a HAVING "
+                f"condition with {hint}."
+            ),
+            context={
+                "threshold_count": threshold_count,
+                "threshold_table": threshold_table,
+                "fk_column": fk_col or "",
+                "location": context,
+            },
+        )
+    )
+    debug(
+        f"[validation_semantic.validate_count_threshold_missing_having] "
+        f"count threshold {threshold_count} for '{threshold_table}' "
+        f"without HAVING"
+    )
+    return issues
+
+
+def _resolve_word_to_table(
+    word: str,
+    schema: SchemaGraph,
+) -> str | None:
+    """Resolve a natural-language word to a schema table name.
+
+    Checks the exact word and common English plural/singular forms against the schema table names.
+
+    Args:
+
+        word: Candidate word from the question.
+        schema: ``SchemaGraph`` providing table names.
+
+    Returns:
+
+        Canonical schema table name, or ``None``.
+    """
+    word_lower = word.lower()
+    lower_tables = {t.lower(): t for t in schema.tables}
+    if word_lower in lower_tables:
+        return lower_tables[word_lower]
+    for tbl_lower, tbl_canonical in lower_tables.items():
+        if word_lower in _english_plural_forms(tbl_lower):
+            return tbl_canonical
+    return None
+
+
+def _find_fk_column_for_target(
+    target_table: str,
+    candidate_tables: list[str],
+    schema: SchemaGraph,
+) -> str | None:
+    """Find an FK column on *candidate_tables* referencing *target_table*.
+
+    Args:
+
+        target_table: The table being referenced by the FK.
+        candidate_tables: Tables to search for FK columns.
+        schema: ``SchemaGraph`` providing column metadata.
+
+    Returns:
+
+        Qualified ``table.column`` string, or ``None``.
+    """
+    for tbl in candidate_tables:
+        tbl_meta = schema.tables.get(tbl)
+        if not tbl_meta:
+            continue
+        for col_name, col_meta in tbl_meta.columns.items():
+            if not col_meta.is_foreign_key or not col_meta.fk_target:
+                continue
+            if col_meta.fk_target[0] == target_table:
+                return f"{tbl}.{col_name}"
+    return None
+
+
+_FOR_EACH_RE = re.compile(
+    r"\b(?:for\s+each|per|each)\s+(\w+(?:\s+\w+)?)\b",
+    re.IGNORECASE,
+)
+
+_PER_RATE_PREFIX_RE = re.compile(
+    r"\b(?:average|avg|sum|total|count|min|max|mean|number\s+of|amount)\b",
+    re.IGNORECASE,
+)
+
+
+def validate_for_each_grouping(
+    natural_language: str,
+    group_by_cols: list[NormalizedExpr],
+    schema: SchemaGraph,
+    has_aggregation: bool,
+    context: str = "main",
+) -> list[IntentIssue]:
+    """Detect ``"for each X"`` patterns missing a corresponding GROUP BY.
+
+    Fires only when the intent already contains aggregation context (aggregated select columns or HAVING conditions); for row-level queries, ``"for each X"`` simply means per row and should not force a GROUP BY. When the question contains phrases like ``"for each entity"`` or ``"per entity"`` but no column from the matching table appears in ``group_by_cols``, an error is raised; matches table names and their common English plural forms.
+
+    Args:
+
+        natural_language: Original user question text.
+        group_by_cols: GROUP BY column list from the intent.
+        schema: ``SchemaGraph`` providing table metadata.
+        has_aggregation: Whether the intent contains any aggregated select columns or HAVING conditions.
+        context: Query context label for issue messages.
+
+    Returns:
+
+        List of ``IntentIssue`` instances with severity ``"error"``.
+    """
+    issues: list[IntentIssue] = []
+    if not natural_language:
+        return issues
+    if not has_aggregation:
+        return issues
+    nl_lower = natural_language.lower()
+
+    gb_tables: set[str] = set()
+    for g in group_by_cols:
+        col = g.primary_column if hasattr(g, "primary_column") else ""
+        if col and "." in col:
+            gb_tables.add(col.split(".", 1)[0].lower())
+
+    for match in _FOR_EACH_RE.finditer(nl_lower):
+        noun = match.group(1).strip().lower()
+        matched_table = _resolve_word_to_table(noun, schema)
+        if not matched_table:
+            words = noun.split()
+            if words:
+                matched_table = _resolve_word_to_table(words[-1], schema)
+        if not matched_table:
+            continue
+        if matched_table.lower() in gb_tables:
+            continue
+        preceding = nl_lower[: match.start()]
+        if match.group().startswith("per") and _PER_RATE_PREFIX_RE.search(preceding[-40:]):
+            debug(
+                f"[validation_semantic.validate_for_each_grouping] "
+                f"skipping '{match.group()}' — preceded by aggregation "
+                f"keyword (rate context)"
+            )
+            continue
+        issues.append(
+            IntentIssue(
+                issue_id=f"for_each_missing_group_by_{matched_table}_{context}",
+                category="for_each_grouping",
+                severity="error",
+                message=(
+                    f"Question says '{match.group()}' implying GROUP BY "
+                    f"on table '{matched_table}', but no column from "
+                    f"that table appears in group_by_cols. Add the "
+                    f"identifying column to group_by_cols and set "
+                    f"grain to 'grouped'."
+                ),
+                context={
+                    "matched_phrase": match.group(),
+                    "table": matched_table,
+                    "location": context,
+                },
+            )
+        )
+        debug(
+            f"[validation_semantic.validate_for_each_grouping] "
+            f"'{match.group()}' → table '{matched_table}' missing "
+            f"from group_by"
+        )
+    return issues