aetherdialect 0.1.0__py3-none-any.whl

text2sql/intent_process.py

@@ -0,0 +1,2133 @@
+"""Intent parsing pipeline orchestration and template matching."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .config import VALID_ARITH_OPS, PolicyConfig
+from .contracts_base import IntentIssue, SchemaGraph
+from .contracts_core import (
+    ConcreteIntent,
+    FilterParam,
+    HavingParam,
+    NormalizedExpr,
+    OrderByCol,
+    RuntimeCteStep,
+    RuntimeIntent,
+    SelectCol,
+    SimulatorIntent,
+    Template,
+)
+from .core_utils import debug, llm_chat, safe_json_loads, stable_json
+from .intent_expr import (
+    assign_param_keys,
+    build_cte_output_metadata,
+    collect_raw_param_values,
+    decompose_between_params,
+    derive_cte_output_columns,
+    normalize_date_diff_raw_values,
+    ensure_scalar_func_defaults,
+    extract_structural_params,
+    normalize_in_raw_values,
+    parse_intent_response,
+    repair_misclassified_date_diff,
+    tag_expr_numeric,
+)
+from .intent_repair import (
+    dedup_contradictory_filters,
+    expand_fk_select_to_descriptive,
+    normalize_boolean_filter_values,
+    normalize_in_filter_types,
+    normalize_null_filter_values,
+    normalize_pk_distinct,
+    prune_unreferenced_tables,
+    qualify_cte_output_columns,
+    repair_fk_filter_type_mismatch,
+    repair_null_equality_filters,
+    requalify_redundant_pk_references,
+    resolve_filter_value_case,
+    sanitize_table_names,
+    strip_impossible_having,
+    strip_join_conditions,
+    strip_spurious_group_by,
+)
+from .intent_expr import extract_columns_from_expr, replace_refs_in_expr
+from .intent_resolve import (
+    enforce_cte_grain_consistency,
+    enforce_grain_consistency,
+    enforce_schema,
+    force_main_grain_when_using_grouped_cte,
+    normalize_count_star,
+    normalize_cte_names,
+    normalize_filters_havings,
+    rewrite_cte_output_refs_to_aliases,
+    resolve_column_map,
+    resolve_cte_column_maps,
+    simplify_exprs,
+    sort_order_by_cols,
+    sort_select_cols,
+)
+from .utils import exact_question_match
+from .validation_execute import validate_semantics
+from .validation_semantic import auto_repair_filter_having
+
+REPAIR_INSTRUCTIONS: dict[str, str] = {
+    "extract_epoch": (
+        "Do not use EXTRACT(EPOCH FROM ...). Use date column subtraction "
+        "(e.g. <table>.<date_col> - <table>.<date_col>) or other supported "
+        "date functions for time differences."
+    ),
+    "grain_validity": "Use one of the allowed grain values: 'scalar', 'grouped', or 'row_level'.",
+    "grain_consistency": "Ensure grain matches the query structure. 'grouped' requires group_by_cols and aggregation in select_cols. 'row_level' means no GROUP BY and no aggregation. 'scalar' means a single aggregated value with no GROUP BY.",
+    "schema_validation": "One or more tables or columns do not exist in the schema. Check allowed_tables and use only exact column names from each table.",
+    "unknown_table": "The table does not exist in the schema. Remove it from tables and rewrite any references to use only tables that appear in allowed_tables.",
+    "unknown_column": "The column does not exist in its table. Check the schema for available columns with a similar name or meaning and replace the reference.",
+    "semantic_contradiction": "The intent contains contradictory operations. Keep only the aggregation or pattern that matches the question.",
+    "expression_type": "Arithmetic expressions require numeric columns. Ensure all operands in arithmetic and all comparison sides have compatible types.",
+    "filter_aggregation": "Conditions with aggregation functions (COUNT, SUM, AVG, MIN, MAX) belong in having_param, not filters_param. Move the condition.",
+    "having_aggregation": "HAVING conditions must have an aggregation function in left_expr. Conditions without aggregation belong in filters_param.",
+    "filter_semantic": "Fix the filter comparison: remove self-comparisons and ensure type compatibility between left and right expressions.",
+    "having_semantic": "Fix the HAVING comparison: remove self-comparisons and ensure type compatibility between aggregated expressions.",
+    "nested_aggregation": "Nested aggregation (e.g. SUM(COUNT(...))) is not allowed. Use a CTE: compute the inner aggregation in a CTE step, then aggregate the CTE output in the main query.",
+    "mixed_aggregation": "An expression cannot mix aggregated and bare column terms. Either wrap all terms in an aggregation function or add bare columns to group_by_cols.",
+    "group_by_membership": "Every non-aggregated column in select_cols must appear in group_by_cols when grain is 'grouped'. Add the missing column to group_by_cols or wrap it in an aggregation.",
+    "order_by_aggregation": "ORDER BY cannot contain aggregation when grain is 'row_level'. Change grain to 'grouped' or remove the aggregation from order_by_cols.",
+    "aggregation_hint": "The question contains a quantity-comparison phrase that typically requires COUNT or SUM aggregation with GROUP BY and HAVING. Add aggregation in select_cols, group_by_cols on the entity, having_param with the threshold, and set grain to 'grouped'.",
+    "column_schema": "A referenced column does not exist in its table. Check the schema for the correct column name.",
+    "table_schema": "A referenced table does not exist in the schema. Use only tables from allowed_tables.",
+    "filter_type_ops": "The filter operator is not compatible with the column data type. Use an appropriate operator for the column type.",
+    "null_filter": "NULL checks must use 'is null' or 'is not null' operator with no value or value_type field.",
+    "between_filter": "BETWEEN is not supported. Decompose into two separate filters: one with op '>=' and one with op '<='.",
+    "date_window": (
+        "For relative time filters (e.g. 'last 90 days', 'past 6 months'), "
+        "use value_type 'date_window' with the date column in left_expr, "
+        "op '>=' and value as {\"unit\": \"day\"|\"week\"|\"month\"|\"year\", \"offset\": N}. "
+        "Use singular unit names."
+    ),
+    "date_diff": (
+        "For date-difference filters comparing two date columns "
+        "(e.g. 'return_date - rental_date > 7 days'), use value_type 'date_diff' with "
+        "left_expr as the date subtraction (<table>.<end_date> - <table>.<start_date>), "
+        "op as the comparison operator, and value as "
+        "{\"unit\": \"day\"|\"week\"|\"month\"|\"year\", \"amount\": N}. "
+        "Use singular unit names. Do NOT use date_diff for relative-to-now filters; "
+        "use date_window instead."
+    ),
+    "agg_role": "SUM and AVG should only be applied to numeric measure columns. Use COUNT for non-measure columns, or select a numeric column.",
+    "agg_type": "SUM and AVG require a numeric column. The referenced column is not numeric. Use COUNT instead or choose a numeric column.",
+    "for_each_grouping": "The question contains a 'for each', 'per', or 'by' phrase implying a GROUP BY on the referenced entity. Add the entity's identifying column to group_by_cols, include it as a non-aggregated entry in select_cols, and set grain to 'grouped'.",
+    "scalar_func_type": "The scalar function is applied to an incompatible column type. Ensure the column type matches what the function expects (e.g. YEAR needs a date column, UPPER needs a text column).",
+    "threshold_missing_having": "The question contains a threshold phrase (e.g. 'more than', 'at least') and the intent already has aggregation, but no HAVING condition is defined. Add a HAVING clause that compares the aggregated column to the numeric threshold in the question.",
+    "cte_structure": "CTE steps require a cte_name string, an output_columns list of alias strings, and valid tables.",
+    "cte_grain_consistency": "CTE grain must match its structure: same rules as the main query regarding grain, group_by_cols, and aggregation.",
+    "cte_table_reference": "A CTE references an unknown table. A CTE can only reference schema tables or previously defined CTEs.",
+    "cte_grain_compatibility": "A row_level query or CTE depends on an aggregated CTE. Ensure the grain is compatible with upstream CTE grains.",
+    "cte_aggregation": "A CTE has HAVING conditions but no aggregation in its select_cols. Add aggregation or remove the HAVING.",
+    "missing_scoping_table": "The question explicitly mentions a schema table that is missing from the intent. Add the table to 'tables', join it via its foreign-key relationship, and include relevant columns in select_cols or filters as appropriate.",
+    "pk_fk_filter": "Do not filter on a primary-key or foreign-key integer column. Replace the identifier filter with a filter on the descriptive column of the referenced table, join that table if it is not already present, and use the human-readable value from the question.",
+    "agg_keyword_missing": "The question asks for an aggregation (total, count, average, sum, etc.) but the intent has no aggregated column and no HAVING condition. Add the appropriate aggregation function to select_cols, include all tables needed to compute the aggregated value, and set grain to 'grouped' with the correct group_by_cols.",
+}
+"""Map from IntentIssue.category to a targeted fix instruction for the LLM semantic-repair prompt."""
+
+
+def _resolve_repair_instruction(issue: IntentIssue) -> str:
+    """Return a targeted fix instruction for a semantic issue."""
+    return REPAIR_INSTRUCTIONS.get(issue.category, issue.message)
+
+
+def _classify_schema_error(error_message: str) -> str:
+    """Classify a schema enforcement error into a specific category.
+
+    Args:
+
+
+        error_message: Error string produced by enforce_schema.
+
+    Returns:
+
+
+        One of 'unknown_table', 'unknown_column', or 'schema_validation' as a fallback.
+    """
+    lower = error_message.lower()
+    if "unknown table" in lower:
+        return "unknown_table"
+    if "unknown" in lower and "column" in lower:
+        return "unknown_column"
+    return "schema_validation"
+
+
+def _build_intent_semantic_repair_prompt(
+    question: str,
+    current_intent_json: str,
+    errors: list[IntentIssue],
+    warnings: list[IntentIssue],
+    schema_literal_text: str,
+) -> str:
+    """Build a user-prompt for the LLM to repair semantic issues in a parsed intent.
+
+    Errors are presented as errors_to_fix with targeted fix instructions sourced from REPAIR_INSTRUCTIONS and warnings are presented as non-binding suggestions.
+
+    Args:
+
+
+        question: Original natural language question.
+        current_intent_json: JSON string of the current flawed parsed intent.
+        errors: IntentIssue objects with severity equal to "error".
+        warnings: IntentIssue objects with severity equal to "warning".
+        schema_literal_text: Human-readable schema text for the LLM context.
+
+    Returns:
+
+
+        JSON-formatted prompt string ready to send as the user message.
+    """
+    errors_to_fix: list[dict[str, str]] = []
+    for err in errors:
+        errors_to_fix.append(
+            {
+                "category": err.category,
+                "issue": err.message,
+                "fix": _resolve_repair_instruction(err),
+            }
+        )
+
+    suggestions: list[str] = [w.message for w in warnings]
+
+    prompt = stable_json(
+        {
+            "task": (
+                "Fix every error listed in errors_to_fix. Follow each "
+                "fix instruction exactly. Suggestions are optional "
+                "improvements. Output corrected intent JSON only."
+            ),
+            "critical_rules": [
+                "Do not use EXTRACT(EPOCH FROM ...). Use date column "
+                "subtraction or other supported date functions for time "
+                "differences.",
+                "Use only tables and columns that exist in schema_info.",
+                "Every non-aggregated column in select_cols must appear "
+                "in group_by_cols when grain is 'grouped'.",
+                "HAVING conditions require an aggregation function in "
+                "left_expr.",
+                "Filters without aggregation go in filters_param; filters "
+                "with aggregation go in having_param.",
+                "SUM and AVG apply only to numeric measure columns; use "
+                "COUNT for non-measure columns.",
+                "Nested aggregation like SUM(COUNT(...)) is forbidden; "
+                "use a CTE instead.",
+                "BETWEEN is not supported; decompose into >= and <= "
+                "filters.",
+                "NULL checks must use 'is null' or 'is not null' with "
+                "no value field.",
+                "For relative time windows ('last N days') use value_type "
+                "'date_window' with value {\"unit\": \"day\", \"offset\": N}. "
+                "For date-difference between two columns use value_type "
+                "'date_diff' with value {\"unit\": \"day\", \"amount\": N}.",
+            ],
+            "errors_to_fix": errors_to_fix,
+            "suggestions": suggestions,
+            "field_specifications": {
+                "tables": (
+                    "Tables from schema needed for query. Sorted "
+                    "alphabetically."
+                ),
+                "select_cols": (
+                    "Array of {expr}. expr is a SQL expression string "
+                    "built from fully-qualified columns such as "
+                    "<table_1>.<column_1>. Use DISTINCT inside expr when "
+                    "needed, for example "
+                    "'COUNT(DISTINCT <table_1>.<column_1>)'."
+                ),
+                "group_by_cols": (
+                    "GROUP BY columns in <table_1>.<column_1> format. "
+                    "Required when select_cols has both aggregated and "
+                    "non-aggregated columns."
+                ),
+                "order_by_cols": (
+                    "Array of {expr, direction}. expr is a SQL "
+                    "expression; direction is 'asc' or 'desc'."
+                ),
+                "filters_param": (
+                    "Array of {left_expr, op, value_type, value} for "
+                    "expr-vs-value or {left_expr, op, right_expr} for "
+                    "expr-vs-expr. Optional: bool_op ('AND'|'OR', "
+                    "default 'AND'), filter_group (integer)."
+                ),
+                "having_param": (
+                    "Array of {left_expr, op, value_type, value} for "
+                    "agg-vs-value or {left_expr, op, right_expr} for "
+                    "agg-vs-agg. Optional: bool_op ('AND'|'OR', default "
+                    "'AND'), filter_group (integer)."
+                ),
+                "limit": "Integer limit or null.",
+            },
+            "current_intent": current_intent_json,
+            "question": question,
+            "schema_info": schema_literal_text,
+            "output_format": {
+                "tables": ["<table_1>"],
+                "select_cols": [
+                    {"expr": "COUNT(<table_1>.<column_1>)"},
+                ],
+                "group_by_cols": [],
+                "order_by_cols": [],
+                "filters_param": [],
+                "having_param": [],
+                "limit": None,
+                "cte_steps": [],
+                "natural_language": (
+                    "<short direct-answer description of what this query "
+                    "returns>"
+                ),
+            },
+        }
+    )
+    return prompt
+
+
+def _build_intent_format_repair_prompt(question: str, raw_response: str, parse_error: str) -> str:
+    """Build a user-prompt for the LLM to fix JSON format errors in a prior response.
+
+    Args:
+
+
+        question: Original natural language question.
+        raw_response: The malformed LLM response that failed to parse.
+        parse_error: Short description of why the response failed to parse.
+
+    Returns:
+
+
+        JSON-formatted prompt string ready to send as the user message.
+    """
+    prompt = stable_json(
+        {
+            "task": "The previous response was not valid JSON. Fix the formatting errors and return ONLY valid JSON.",
+            "question": question,
+            "invalid_response": raw_response,
+            "parse_error": parse_error,
+            "field_specifications": {
+                "tables": "Array of string table names. REQUIRED.",
+                "select_cols": (
+                    "Array of objects with {expr}. expr is a SQL "
+                    "expression string that uses fully-qualified "
+                    "columns such as <table_1>.<column_1>. Use DISTINCT "
+                    "inside expr when needed. REQUIRED, non-empty."
+                ),
+                "group_by_cols": (
+                    "Array of string column names in "
+                    "<table_1>.<column_1> format. REQUIRED "
+                    "(can be empty [])."
+                ),
+                "order_by_cols": (
+                    "Array of objects with {expr, direction}. expr is a "
+                    "SQL expression string; direction is 'asc' or "
+                    "'desc'. REQUIRED (can be empty [])."
+                ),
+                "filters_param": (
+                    "Array of objects with {left_expr, op, value_type, "
+                    "value} for expr-vs-value or {left_expr, op, "
+                    "right_expr} for expr-vs-expr. Optional: bool_op "
+                    "(string, default 'AND'), filter_group "
+                    "(integer|null). REQUIRED (can be empty [])."
+                ),
+                "having_param": (
+                    "Array of objects with {left_expr, op, value_type, "
+                    "value} for agg-vs-value or {left_expr, op, "
+                    "right_expr} for agg-vs-agg. Optional: bool_op "
+                    "(string, default 'AND'), filter_group "
+                    "(integer|null). REQUIRED (can be empty [])."
+                ),
+                "limit": "Integer or null. REQUIRED.",
+                "cte_steps": (
+                    "Array of CTE step objects. REQUIRED (can be "
+                    "empty [])."
+                ),
+            },
+            "issue_action_mapping": {
+                "missing_field": "Add the missing field with appropriate default: [] for arrays, null for scalars, false for boolean.",
+                "invalid_json": "Fix syntax: ensure matching braces/brackets, proper commas, quoted strings.",
+                "null_array": "Replace null with empty array [].",
+                "invalid_type": "Convert to correct type: strings in quotes, numbers without quotes, boolean as true/false.",
+                "extra_text": "Remove any text before/after the JSON object.",
+                "truncated": "Complete the JSON structure with appropriate closing braces/brackets.",
+            },
+            "type_conversions": {
+                "tables": "string[]",
+                "select_cols": "object[] with {expr: string}",
+                "group_by_cols": "string[]",
+                "order_by_cols": "object[] with {expr: string, direction: string}",
+                "filters_param": "object[] with {left_expr: string, op: string, value_type: string, bool_op?: string, filter_group?: integer} or {left_expr: string, op: string, right_expr: string, bool_op?: string, filter_group?: integer}",
+                "having_param": "object[] with {left_expr: string, op: string, value_type: string, bool_op?: string, filter_group?: integer} or {left_expr: string, op: string, right_expr: string, bool_op?: string, filter_group?: integer}",
+                "limit": "integer|null",
+                "cte_steps": "object[]",
+            },
+            "instructions": [
+                "Return ONLY valid JSON - no explanation, no markdown.",
+                "Preserve the intent and all meaningful content.",
+                "Fix any syntax errors (missing commas, brackets, quotes).",
+                "Use empty arrays [] for list fields, not null.",
+                "Use null for optional scalar fields.",
+                "Ensure all required fields are present.",
+                "Remove any trailing commas before closing braces/brackets.",
+            ],
+            "output_format": {
+                "tables": ["<table_name>"],
+                "select_cols": [{"expr": "<table_name>.<column_name>"}],
+                "group_by_cols": [],
+                "order_by_cols": [],
+                "filters_param": [],
+                "having_param": [],
+                "limit": None,
+                "cte_steps": [],
+            },
+        }
+    )
+    return prompt
+
+
+def _build_intent_parse_prompt(
+    question: str,
+    schema_literal_text: str,
+    table_list: list[str],
+) -> tuple[str, str]:
+    """Build system and user messages for the intent parsing call."""
+    system = (
+        "You are a deterministic intent parser for text-to-SQL. "
+        "Output ONLY valid JSON that matches the required format. "
+        "Identical inputs must produce identical outputs. The "
+        "natural_language field is a short direct description of what "
+        "the query returns, without boilerplate phrases."
+    )
+
+    user_payload: dict[str, object] = {
+        "task": (
+            "Parse the question into a schema-aware intent JSON. "
+            "Do not write SQL. Extract all literals needed for "
+            "filters, HAVING, limits, and parameters."
+        ),
+        "question": question,
+        "schema_summary": schema_literal_text,
+        "allowed_tables": table_list,
+        "naming_conventions": {
+            "table_placeholder": "<table_1>",
+            "column_placeholder": "<column_1>",
+            "date_column_placeholder": "<date_column_1>",
+            "value_placeholder": "<value_from_question>",
+        },
+        "field_specifications": {
+            "tables": (
+                "All base tables and CTE names whose columns appear in "
+                "select_cols, group_by_cols, order_by_cols, "
+                "filters_param, or having_param. Do not reason about "
+                "joins here; include every table that owns a referenced "
+                "column. Sort alphabetically."
+            ),
+            "select_cols": (
+                "Array of objects {expr}. expr is a SQL expression "
+                "string that uses fully-qualified columns "
+                "<table_n>.<column_m>. Use DISTINCT inside expr when "
+                "the question asks for distinct values. The array "
+                "must be non-empty."
+            ),
+            "group_by_cols": (
+                "Array of SQL expressions in <table_n>.<column_m> "
+                "format. Required when select_cols mixes aggregated "
+                "and non-aggregated expressions."
+            ),
+            "order_by_cols": (
+                "Array of objects {expr, direction}. expr is the SQL "
+                "expression only (no ASC/DESC in expr). direction is "
+                "the only place for sort direction: 'asc' or 'desc'. "
+                "Include only when the question implies ordering."
+            ),
+            "filters_param": (
+                "Array of all row-level filter conditions implied by "
+                "the question. Use either "
+                "{left_expr, op, value_type, value} for expr-vs-value "
+                "or {left_expr, op, right_expr} for expr-vs-expr. "
+                "For relative time windows (e.g. 'last 90 days', 'past 6 months'), "
+                "use value_type 'date_window' with the date column in left_expr, "
+                "op '>=' and value as {\"unit\": \"day\", \"offset\": 90}. "
+                "For date-difference comparisons between two columns "
+                "(e.g. 'return_date - rental_date > 7 days'), "
+                "use value_type 'date_diff' with left_expr as the subtraction "
+                "and value as {\"unit\": \"day\", \"amount\": 7}. "
+                "Use singular unit names (day, week, month, year). "
+                "Use bool_op ('AND'|'OR', default 'AND') to connect "
+                "to the next filter. Use filter_group (integer) to "
+                "group filters that share parentheses."
+            ),
+            "having_param": (
+                "Array of all aggregate-level filter conditions. Use "
+                "{left_expr, op, value_type, value} for agg-vs-value "
+                "or {left_expr, op, right_expr} for agg-vs-agg. "
+                "left_expr and right_expr must contain aggregation."
+            ),
+            "limit": (
+                "Integer limit or null. Use a limit for 'top N', "
+                "'first N', or similar phrases. Do not reuse the "
+                "same number as both limit and filter value."
+            ),
+            "natural_language": (
+                "Short direct description of what the query returns. "
+                "For example: 'total <column_1> per <column_2>' or "
+                "'rows from <table_1> where <column_1> equals "
+                "<value_from_question>'. No filler words."
+            ),
+            "cte_steps": (
+                "Use CTEs only when the question explicitly describes "
+                "multiple steps or when an intermediate aggregation is "
+                "reused. Each CTE has: cte_name, description, tables, "
+                "select_cols, group_by_cols, order_by_cols, "
+                "filters_param, having_param, output_columns, limit. "
+                "For every CTE select_cols[i], you must provide "
+                "output_columns[i] as a simple alias (e.g. <measure_1>, "
+                "<count_rows>) and use only these aliases in any main "
+                "query expressions that reference CTE outputs."
+            ),
+        },
+        "expression_format": {
+            "description": (
+                "expr is a SQL expression built from fully-qualified "
+                "columns, arithmetic, aggregation, and scalar "
+                "functions. Use the same structure that the SQL "
+                "generator should ultimately implement."
+            ),
+            "rules": [
+                "Always qualify columns as <table_n>.<column_m>.",
+                "Bare column: <table_1>.<column_1>.",
+                "Aggregation: AGG(<table_1>.<column_1>) where "
+                "AGG is COUNT, SUM, AVG, MIN, or MAX.",
+                "Arithmetic: <table_1>.<column_1> * "
+                "<table_1>.<column_2>, "
+                "<table_1>.<column_1> + <table_1>.<column_2>, "
+                "<table_1>.<column_1> / <table_1>.<column_2>. "
+                "Date difference: <table_1>.<date_col> - <table_1>.<date_col>.",
+                "Do not use EXTRACT(EPOCH FROM ...) for time differences; "
+                "use date column subtraction or other supported date functions.",
+                "Aggregation over arithmetic: "
+                "SUM(<table_1>.<column_1> * <table_1>.<column_2>).",
+                "Scalar over aggregation: "
+                "ROUND(SUM(<table_1>.<column_1>), 2).",
+                "COUNT all rows: COUNT(*).",
+                "Distinct count: COUNT(DISTINCT <table_1>.<column_1>).",
+            ],
+        },
+        "rules": [
+            "All fields in output_format are required. Use [] for "
+            "arrays and null for optional scalars when empty.",
+            "Always qualify columns with their table. Never output "
+            "bare column names.",
+            "Do not invent tables, columns, filters, or HAVING "
+            "conditions that are not supported by schema_summary "
+            "or implied by the question.",
+            "Never include join conditions in filters_param or "
+            "having_param. Joins are handled separately.",
+            "Grain: 'row_level' when there is no aggregation, "
+            "'grouped' when there is aggregation and grouping, "
+            "'scalar' for a single aggregated value with no GROUP BY.",
+            "If the question cannot be answered using only the given "
+            "tables and columns, set intent_status to schema_invalid "
+            "and leave all other fields empty or null. Do not invent "
+            "tables or columns.",
+        ],
+        "intent_status": (
+            "Set to 'ok' (default) when the question is answerable "
+            "with the schema. Set to 'schema_invalid' when the "
+            "question cannot be answered using only the given tables "
+            "and columns."
+        ),
+        "answer_style_guidance": [
+            "First decide whether the question expects a single scalar "
+            "answer, a grouped summary, or a list of rows.",
+            "Scalar answers: when the question asks for a single total, "
+            "count, average, minimum, or maximum without grouping.",
+            "Grouped summaries: when the question uses phrases like "
+            "'per <entity>', 'by <entity>', or 'for each <entity>'.",
+            "Row-level lists: when the question asks to list or show "
+            "individual records satisfying conditions.",
+            "Avoid tables which are not semantically related to the "
+            "question and would provide bad or irrelevant context.",
+            "For grouped or row-level results, include at least one "
+            "identifying or descriptive column that lets the user "
+            "distinguish rows (for example, a primary key or name "
+            "column) unless the question clearly asks for only a "
+            "scalar.",
+            "Start from the minimal set of columns needed to answer the "
+            "question and uniquely identify each row. Add extra "
+            "descriptive columns only when the question explicitly "
+            "refers to them (e.g. names, titles) or when schema "
+            "descriptions indicate they are essential for context.",
+            "Questions that compare to an average (e.g. more X than "
+            "average, above average) often need a multi-step structure: "
+            "use cte_steps to compute the average or aggregate first, "
+            "then compare in the main query.",
+        ],
+        "output_format": {
+            "intent_status": "ok",
+            "tables": ["<table_1>", "<table_2>"],
+            "select_cols": [
+                {"expr": "<table_1>.<column_1>"},
+                {"expr": "COUNT(<table_1>.<column_2>)"},
+            ],
+            "group_by_cols": ["<table_1>.<column_1>"],
+            "order_by_cols": [
+                {"expr": "<table_1>.<column_1>", "direction": "asc"},
+            ],
+            "filters_param": [
+                {
+                    "left_expr": "<table_1>.<column_3>",
+                    "op": "=",
+                    "value_type": "string",
+                    "value": "<value_from_question>",
+                }
+            ],
+            "having_param": [],
+            "limit": None,
+            "natural_language": (
+                "<short direct description of the query>"
+            ),
+            "cte_steps": [],
+        },
+        "operator_reference": {
+            "filter_ops": [
+                "=",
+                "!=",
+                "<",
+                "<=",
+                ">",
+                ">=",
+                "like",
+                "not like",
+                "in",
+                "not in",
+                "is null",
+                "is not null",
+            ],
+            "having_ops": ["=", "!=", "<", "<=", ">", ">="],
+        },
+        "value_type_reference": {
+            "filter": [
+                "string",
+                "integer",
+                "number",
+                "date",
+                "boolean",
+                "null",
+                "date_window",
+                "date_diff",
+            ],
+            "having": ["integer", "number"],
+        },
+    }
+
+    user = stable_json(user_payload)
+    return system, user
+
+
+def _format_repair_loop(system: str, raw: str, question: str, max_retries: int = 3) -> tuple[RuntimeIntent | None, int]:
+    """Attempt to parse a raw LLM response into a RuntimeIntent, retrying with format repair.
+
+    Args:
+
+
+        system: System prompt for the LLM.
+        raw: Raw LLM response string to parse.
+        question: Original natural language question.
+        max_retries: Maximum number of format-repair LLM attempts on JSON parse failure.
+
+    Returns:
+
+
+        Tuple of (parsed RuntimeIntent or None, number of LLM calls made during format repair).
+    """
+    intent = parse_intent_response(raw, question)
+    if intent:
+        return intent, 0
+    llm_calls = 0
+    for _ in range(max_retries):
+        repair_prompt = _build_intent_format_repair_prompt(question, raw, "JSON parse failed")
+        raw = llm_chat(system, repair_prompt, task="intent")
+        llm_calls += 1
+        intent = parse_intent_response(raw, question)
+        if intent:
+            return intent, llm_calls
+    return None, llm_calls
+
+
+def _compute_error_signature_issues(issues: list[IntentIssue]) -> frozenset[str]:
+    """Compute a hashable signature from a list of IntentIssue objects.
+
+    Args:
+
+
+        issues: List of IntentIssue instances, typically errors.
+
+    Returns:
+
+
+        Frozenset of (category, message) pairs for set comparison.
+    """
+    return frozenset((iss.category, iss.message) for iss in issues)
+
+
+def _compute_error_signature_strings(errors: list[str]) -> frozenset[str]:
+    """Compute a hashable signature from a list of error strings.
+
+    Args:
+
+
+        errors: List of raw error message strings.
+
+    Returns:
+
+
+        Frozenset of the error strings for set comparison.
+    """
+    return frozenset(errors)
+
+
+def _detect_oscillation(history: list[frozenset[str]]) -> bool:
+    """Detect AA or ABAB oscillation patterns in error signature history.
+
+    AA means the same error set appeared consecutively and ABAB means the error set alternates between two states.
+
+    Args:
+
+
+        history: Ordered list of error signatures from successive rounds.
+
+    Returns:
+
+
+        True if oscillation is detected and repair should terminate.
+    """
+    if len(history) >= 2 and history[-1] == history[-2]:
+        return True
+    if len(history) >= 4 and history[-1] == history[-3] and history[-2] == history[-4]:
+        return True
+    return False
+
+
+def _normalize_cte_output_aliases(
+    intent: RuntimeIntent,
+    schema_graph: SchemaGraph,
+) -> RuntimeIntent:
+    """Replace LLM-provided CTE output column aliases with deterministic aliases derived from ``select_cols``.
+
+    Builds a mapping from LLM alias to deterministic alias for each CTE and rewrites all downstream references in the main query and later CTE steps so the entire intent is consistent with the canonical names.
+    This must run before qualify_cte_output_columns to avoid stale alias lookups.
+
+    Args:
+
+        intent: RuntimeIntent whose CTE aliases should be normalized.
+        schema_graph: SchemaGraph providing table and column metadata.
+
+    Returns:
+
+        RuntimeIntent with updated CTE output aliases and remapped references.
+    """
+    cte_steps = intent.cte_steps or []
+    if not cte_steps:
+        return intent
+
+    alias_map: dict[str, str] = {}
+    refreshed_cte_steps = []
+    for cte in cte_steps:
+        old_oc = list(cte.output_columns or [])
+        new_oc = derive_cte_output_columns(cte.select_cols or [])
+        ocm = build_cte_output_metadata(
+            cte.select_cols or [], new_oc, schema_graph,
+        )
+        for old_col, new_col in zip(old_oc, new_oc, strict=False):
+            if old_col != new_col:
+                alias_map[f"{cte.cte_name}.{old_col}"] = (
+                    f"{cte.cte_name}.{new_col}"
+                )
+        refreshed_cte_steps.append(
+            replace(
+                cte,
+                output_columns=new_oc,
+                output_column_metadata=ocm,
+            )
+        )
+    intent = replace(intent, cte_steps=refreshed_cte_steps)
+
+    if not alias_map:
+        return intent
+
+    debug(f"[_normalize_cte_output_aliases] remap: {alias_map}")
+
+    def _remap_alias(s: str) -> str:
+        return alias_map.get(s, s)
+
+    def _remap_expr(expr: NormalizedExpr) -> NormalizedExpr:
+        return replace_refs_in_expr(expr, _remap_alias)
+
+    def _remap_cte_step(cte: RuntimeCteStep) -> RuntimeCteStep:
+        return replace(
+            cte,
+            select_cols=[
+                replace(sc, expr=_remap_expr(sc.expr))
+                for sc in (cte.select_cols or [])
+            ],
+            order_by_cols=[
+                replace(obc, expr=_remap_expr(obc.expr))
+                for obc in (cte.order_by_cols or [])
+            ],
+            group_by_cols=[_remap_expr(g) for g in (cte.group_by_cols or [])],
+            filters_param=[
+                replace(
+                    fp,
+                    left_expr=_remap_expr(fp.left_expr),
+                    right_expr=(
+                        _remap_expr(fp.right_expr) if fp.right_expr else None
+                    ),
+                )
+                for fp in (cte.filters_param or [])
+            ],
+            having_param=[
+                replace(
+                    hp,
+                    left_expr=_remap_expr(hp.left_expr),
+                    right_expr=(
+                        _remap_expr(hp.right_expr) if hp.right_expr else None
+                    ),
+                )
+                for hp in (cte.having_param or [])
+            ],
+        )
+
+    refreshed_cte_steps = [_remap_cte_step(cte) for cte in intent.cte_steps]
+
+    intent = replace(
+        intent,
+        cte_steps=refreshed_cte_steps,
+        select_cols=[
+            replace(sc, expr=_remap_expr(sc.expr))
+            for sc in (intent.select_cols or [])
+        ],
+        order_by_cols=[
+            replace(obc, expr=_remap_expr(obc.expr))
+            for obc in (intent.order_by_cols or [])
+        ],
+        group_by_cols=[
+            _remap_expr(g) for g in (intent.group_by_cols or [])
+        ],
+        filters_param=[
+            replace(
+                fp,
+                left_expr=_remap_expr(fp.left_expr),
+                right_expr=(
+                    _remap_expr(fp.right_expr) if fp.right_expr else None
+                ),
+            )
+            for fp in (intent.filters_param or [])
+        ],
+        having_param=[
+            replace(
+                hp,
+                left_expr=_remap_expr(hp.left_expr),
+                right_expr=(
+                    _remap_expr(hp.right_expr) if hp.right_expr else None
+                ),
+            )
+            for hp in (intent.having_param or [])
+        ],
+    )
+
+    return intent
+
+
+def _apply_deterministic_repairs(
+    intent: RuntimeIntent,
+    schema_graph: SchemaGraph,
+    natural_language: str = "",
+) -> RuntimeIntent:
+    """Apply the full deterministic normalization and repair chain to a RuntimeIntent.
+
+    Runs normalizations such as count-star and CTE names, grain enforcement, filter and having normalization, join condition stripping, CTE processing, sorting, simplification, BETWEEN decomposition, and auto filter and having repair.
+
+    Args:
+
+        intent: RuntimeIntent to repair.
+        schema_graph: SchemaGraph providing table and column metadata.
+        natural_language: Original user question, reserved for future use.
+
+    Returns:
+
+        Repaired RuntimeIntent.
+    """
+    intent = normalize_count_star(intent)
+    intent = normalize_cte_names(intent)
+    intent = _normalize_cte_output_aliases(intent, schema_graph)
+    intent = qualify_cte_output_columns(intent)
+    intent = sanitize_table_names(intent, schema_graph)
+    intent = force_main_grain_when_using_grouped_cte(intent)
+    intent = enforce_grain_consistency(intent, schema_graph)
+    intent = strip_spurious_group_by(intent)
+    intent = normalize_filters_havings(intent)
+    intent = repair_null_equality_filters(intent)
+    intent = strip_join_conditions(intent, schema_graph)
+
+    new_cte_steps = []
+    for cte in intent.cte_steps or []:
+        cte = enforce_cte_grain_consistency(cte)
+        cte = replace(cte, select_cols=sort_select_cols(cte.select_cols or []))
+        cte = replace(cte, order_by_cols=sort_order_by_cols(cte.order_by_cols or []))
+        new_cte_steps.append(cte)
+    intent = replace(intent, cte_steps=new_cte_steps)
+
+    intent = replace(intent, select_cols=sort_select_cols(intent.select_cols or []))
+    intent = replace(intent, order_by_cols=sort_order_by_cols(intent.order_by_cols or []))
+
+    intent = simplify_exprs(intent)
+
+    intent = normalize_in_raw_values(intent)
+
+    intent = repair_misclassified_date_diff(intent)
+
+    intent = normalize_date_diff_raw_values(intent)
+
+    intent = decompose_between_params(intent)
+
+    main_cte_names = {c.cte_name for c in intent.cte_steps or []}
+
+    def process(
+        fp: list[FilterParam],
+        hp: list[HavingParam],
+        cte_names: set[str] | None = None,
+    ) -> tuple[list[FilterParam], list[HavingParam]]:
+        return auto_repair_filter_having(fp, hp, cte_names=cte_names)
+
+    repaired_fp, repaired_hp = process(
+        intent.filters_param or [], intent.having_param or [], cte_names=main_cte_names
+    )
+    intent = replace(intent, filters_param=repaired_fp, having_param=repaired_hp)
+    if intent.cte_steps:
+        new_cte_steps = []
+        preceding: set[str] = set()
+        for cte in intent.cte_steps:
+            fp, hp = process(
+                cte.filters_param or [],
+                cte.having_param or [],
+                cte_names=preceding,
+            )
+            new_cte_steps.append(replace(cte, filters_param=fp, having_param=hp))
+            preceding.add(cte.cte_name)
+        intent = replace(intent, cte_steps=new_cte_steps)
+
+    intent = strip_impossible_having(intent)
+    intent = repair_fk_filter_type_mismatch(intent, schema_graph)
+    intent = resolve_filter_value_case(intent, schema_graph, natural_language)
+    intent = normalize_in_filter_types(intent, schema_graph)
+    intent = normalize_boolean_filter_values(intent, schema_graph)
+    intent = normalize_null_filter_values(intent)
+    intent = expand_fk_select_to_descriptive(intent, schema_graph)
+    intent = dedup_contradictory_filters(intent)
+    intent = requalify_redundant_pk_references(intent, schema_graph)
+
+    return intent
+
+
+def _validate_cte_fk_connectivity(
+    intent: RuntimeIntent, schema: SchemaGraph,
+) -> RuntimeIntent:
+    """Ensure CTE steps with multiple tables form connected FK subgraphs.
+
+    For each CTE step referencing two or more tables, verifies that
+    every pair of tables has at least one FK join path in the schema.
+    Disconnected tables are removed from the CTE step and logged.
+
+    Args:
+        intent: The runtime intent with CTE steps to validate.
+        schema: The schema graph with ``join_paths_multi``.
+
+    Returns:
+        Updated intent with CTE table lists pruned of unreachable
+        tables.
+    """
+    cte_steps = intent.cte_steps or []
+    if not cte_steps:
+        return intent
+
+    updated_steps = []
+    changed = False
+    for cte in cte_steps:
+        tables = cte.tables or []
+        if len(tables) < 2:
+            updated_steps.append(cte)
+            continue
+        connected = _fk_connected_tables(tables, schema)
+        if connected == set(tables):
+            updated_steps.append(cte)
+            continue
+        pruned = sorted(connected)
+        debug(
+            f"[intent_process._validate_cte_fk_connectivity] CTE '{cte.cte_name}': "
+            f"pruned {set(tables) - connected} (no FK path)"
+        )
+        updated_steps.append(replace(cte, tables=pruned))
+        changed = True
+
+    if changed:
+        intent = replace(intent, cte_steps=updated_steps)
+    return intent
+
+
+def _fk_connected_tables(
+    tables: list[str], schema: SchemaGraph,
+) -> set[str]:
+    """Find the largest FK-connected subset starting from the first table.
+
+    Uses the schema's ``join_paths_multi`` to determine which tables
+    are reachable from the first table through FK edges.
+
+    Args:
+        tables: Table names to check connectivity for.
+        schema: The schema graph.
+
+    Returns:
+        Set of table names reachable from ``tables[0]`` via FK paths.
+    """
+    if not tables:
+        return set()
+    visited: set[str] = {tables[0]}
+    queue = [tables[0]]
+    target_set = set(tables)
+    while queue:
+        current = queue.pop(0)
+        for other in target_set - visited:
+            paths = schema.join_paths_multi.get(current, {}).get(other, [])
+            reverse_paths = schema.join_paths_multi.get(other, {}).get(current, [])
+            if paths or reverse_paths:
+                visited.add(other)
+                queue.append(other)
+    return visited
+
+
+def _apply_post_processing(intent: RuntimeIntent, schema_graph: SchemaGraph, question: str) -> RuntimeIntent | None:
+    """Apply post-semantic-loop processing including column resolution, CTE wiring, foreign key repairs, and parameter extraction.
+
+    Runs column map resolution, CTE output column derivation, alias remapping, foreign key filter and select repair, parameter key assignment, table pruning, primary key distinct normalization, numeric tagging, parameter value collection, scalar function defaults, and structural parameter extraction and returns None on structural failures such as missing parameter values.
+
+    Args:
+
+        intent: RuntimeIntent after the semantic loop.
+        schema_graph: SchemaGraph providing table and column metadata.
+        question: Original natural language question.
+
+    Returns:
+
+        Processed RuntimeIntent, or None on structural failure.
+    """
+    all_cols = []
+    for sc in intent.select_cols or []:
+        all_cols.extend(extract_columns_from_expr(sc.expr))
+    for obc in intent.order_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(obc.expr))
+    for g in intent.group_by_cols or []:
+        all_cols.extend(extract_columns_from_expr(g))
+    for fp in intent.filters_param or []:
+        all_cols.extend(extract_columns_from_expr(fp.left_expr))
+        if fp.right_expr:
+            all_cols.extend(extract_columns_from_expr(fp.right_expr))
+
+    column_map = resolve_column_map(all_cols, schema_graph, intent.tables or [])
+    intent = replace(intent, column_map=column_map)
+
+    if intent.cte_steps:
+        intent = replace(intent, cte_steps=resolve_cte_column_maps(intent.cte_steps))
+
+    if intent.cte_steps:
+        debug(f"[_apply_post_processing] CTE chain: {[c.cte_name for c in intent.cte_steps]}")
+        alias_map: dict[str, str] = {}
+        refreshed_cte_steps = []
+        for cte in intent.cte_steps:
+            old_oc = list(cte.output_columns or [])
+            new_oc = derive_cte_output_columns(cte.select_cols or [])
+            ocm = build_cte_output_metadata(cte.select_cols or [], new_oc, schema_graph)
+            debug(
+                f"[_apply_post_processing] CTE '{cte.cte_name}' "
+                f"tables={cte.tables} grain={cte.grain} "
+                f"old_oc={old_oc} new_oc={new_oc}"
+            )
+            for old_col, new_col in zip(old_oc, new_oc, strict=False):
+                if old_col != new_col:
+                    alias_map[f"{cte.cte_name}.{old_col}"] = f"{cte.cte_name}.{new_col}"
+            refreshed_cte_steps.append(replace(cte, output_columns=new_oc, output_column_metadata=ocm))
+        intent = replace(intent, cte_steps=refreshed_cte_steps)
+        if alias_map:
+            debug(f"[_apply_post_processing] CTE alias remap: {alias_map}")
+
+            def _remap_alias(s: str) -> str:
+                return alias_map.get(s, s)
+
+            def _remap_expr(expr: NormalizedExpr) -> NormalizedExpr:
+                return replace_refs_in_expr(expr, _remap_alias)
+
+            intent = replace(
+                intent,
+                select_cols=[replace(sc, expr=_remap_expr(sc.expr)) for sc in (intent.select_cols or [])],
+                order_by_cols=[replace(obc, expr=_remap_expr(obc.expr)) for obc in (intent.order_by_cols or [])],
+                group_by_cols=[_remap_expr(g) for g in (intent.group_by_cols or [])],
+                filters_param=[
+                    replace(
+                        fp,
+                        left_expr=_remap_expr(fp.left_expr),
+                        right_expr=(_remap_expr(fp.right_expr) if fp.right_expr else None),
+                    )
+                    for fp in (intent.filters_param or [])
+                ],
+                having_param=[
+                    replace(
+                        hp,
+                        left_expr=_remap_expr(hp.left_expr),
+                        right_expr=(_remap_expr(hp.right_expr) if hp.right_expr else None),
+                    )
+                    for hp in (intent.having_param or [])
+                ],
+            )
+
+    if intent.cte_steps:
+        intent = qualify_cte_output_columns(intent)
+
+    intent = rewrite_cte_output_refs_to_aliases(intent)
+
+    filters_param, having_param, cte_steps, _ = assign_param_keys(
+        intent.filters_param or [],
+        intent.having_param or [],
+        intent.cte_steps,
+    )
+    intent = replace(
+        intent,
+        filters_param=filters_param,
+        having_param=having_param,
+        cte_steps=cte_steps,
+    )
+
+    intent = prune_unreferenced_tables(intent, schema_graph=schema_graph)
+    intent = sanitize_table_names(intent, schema_graph)
+    intent = _validate_cte_fk_connectivity(intent, schema_graph)
+    intent = normalize_pk_distinct(intent, schema_graph)
+
+    intent = tag_expr_numeric(intent, schema_graph)
+
+    all_pv = collect_raw_param_values(intent)
+
+    expected_keys: list[str] = []
+    for cte in intent.cte_steps or []:
+        for fp in cte.filters_param or []:
+            if fp.param_key and fp.op not in ("is null", "is not null") and not fp.right_expr:
+                expected_keys.append(fp.param_key)
+        for hp in cte.having_param or []:
+            if hp.param_key and not hp.right_expr:
+                expected_keys.append(hp.param_key)
+    for fp in intent.filters_param or []:
+        if fp.param_key and fp.op not in ("is null", "is not null") and not fp.right_expr:
+            expected_keys.append(fp.param_key)
+    for hp in intent.having_param or []:
+        if hp.param_key and not hp.right_expr:
+            expected_keys.append(hp.param_key)
+    missing_keys = [k for k in expected_keys if k not in all_pv]
+    if missing_keys:
+        debug(f"[intent_process.apply_post_processing] missing_param_values — auto-terminating: {missing_keys}")
+        return None
+
+    intent = replace(intent, param_values=all_pv)
+
+    if intent.cte_steps:
+        new_cte_steps = []
+        for cte in intent.cte_steps:
+            cte_pks: set[str] = set()
+            for fp in cte.filters_param or []:
+                if fp.param_key:
+                    cte_pks.add(fp.param_key)
+            for hp in cte.having_param or []:
+                if hp.param_key:
+                    cte_pks.add(hp.param_key)
+            cte_pv = {k: v for k, v in all_pv.items() if k in cte_pks}
+            new_cte_steps.append(replace(cte, param_values=cte_pv))
+        intent = replace(intent, cte_steps=new_cte_steps)
+
+    intent = ensure_scalar_func_defaults(intent)
+    intent = extract_structural_params(intent)
+
+    return intent
+
+
+def _attempt_fresh_restart(
+    question: str,
+    system: str,
+    schema_literal_text: str,
+    table_list: list[str],
+    failure_hints: list[str],
+    max_retries: int,
+    schema_graph: SchemaGraph,
+    llm_calls: int,
+) -> tuple[RuntimeIntent | None, list[str], int]:
+    """Make one fresh LLM call with accumulated failure hints.
+
+    Called when the normal repair loops have been exhausted or oscillation was detected and builds an enriched prompt that includes the previous failure messages so the LLM can avoid repeating the same mistakes.
+
+    Args:
+
+        question: Original natural language question.
+        system: System prompt for the LLM.
+        schema_literal_text: Human-readable schema text.
+        table_list: List of table names from the schema.
+        failure_hints: Accumulated error messages from previous rounds.
+        max_retries: Maximum number of format-repair retries.
+        schema_graph: SchemaGraph for deterministic repairs and post-processing.
+        llm_calls: Running count of LLM calls made so far.
+
+    Returns:
+
+        Tuple of (RuntimeIntent or None, semantic_warnings, total_llm_calls).
+    """
+    if not failure_hints:
+        return None, [], llm_calls
+
+    debug(f"[intent_process._attempt_fresh_restart] attempting fresh restart with {len(failure_hints)} failure hints")
+
+    deduped_hints = list(dict.fromkeys(failure_hints))[:10]
+
+    _, fresh_user = _build_intent_parse_prompt(question, schema_literal_text, table_list)
+    hint_block = "\n".join(f"- {h}" for h in deduped_hints)
+    augmented_user = fresh_user + "\n\nPrevious attempts failed with these issues — avoid them:\n" + hint_block
+
+    raw = llm_chat(system, augmented_user, task="intent")
+    llm_calls += 1
+    intent, fmt_calls = _format_repair_loop(system, raw, question, max_retries)
+    llm_calls += fmt_calls
+
+    if not intent:
+        debug("[intent_process._attempt_fresh_restart] fresh restart format repair failed")
+        return None, [], llm_calls
+
+    intent = _apply_deterministic_repairs(intent, schema_graph, question)
+    intent, schema_errors = enforce_schema(intent, schema_graph)
+    if schema_errors:
+        debug(
+            f"[intent_process._attempt_fresh_restart] fresh restart has {len(schema_errors)} schema errors — giving up"
+        )
+        return None, [], llm_calls
+
+    validation_result = validate_semantics(intent, schema_graph)
+    errors = [iss for iss in validation_result.issues if iss.severity == "error"]
+    warnings = [iss for iss in validation_result.issues if iss.severity == "warning"]
+
+    if errors:
+        debug(f"[intent_process._attempt_fresh_restart] fresh restart has {len(errors)} semantic errors — giving up")
+        return None, [], llm_calls
+
+    result = _apply_post_processing(intent, schema_graph, question)
+    if result is None:
+        return None, [], llm_calls
+
+    semantic_warnings = [w.message for w in warnings]
+    debug(
+        f"[intent_process._attempt_fresh_restart] fresh restart succeeded "
+        f"with {len(result.tables or [])} tables, {llm_calls} total LLM calls"
+    )
+    return result, semantic_warnings, llm_calls
+
+
+def full_intent_parse(
+    question: str, schema_graph: SchemaGraph, max_retries: int = 3
+) -> tuple[RuntimeIntent | None, list[str], int]:
+    """Parse a natural language question into a RuntimeIntent.
+
+    Runs the LLM intent-parse prompt and then applies interleaved format and semantic repair loops.
+    Schema errors are handled in a nested sub-loop that does not consume semantic repair rounds and oscillation detection terminates repair early when the same error set repeats or alternates.
+    When all repair rounds are exhausted or oscillation is detected, a single fresh-restart LLM call is attempted with accumulated failure hints before giving up.
+
+    Args:
+
+        question: Natural language question to parse.
+        schema_graph: SchemaGraph providing table and column metadata and schema text.
+        max_retries: Maximum number of format-repair LLM attempts on JSON parse failure.
+
+    Returns:
+
+        Tuple of (RuntimeIntent, semantic_warnings, llm_call_count) where semantic_warnings is a list of non-fatal warning strings and llm_call_count is the total number of LLM API calls made; RuntimeIntent is None when parsing fails.
+    """
+    max_schema_sub_rounds = 3
+    table_list = list(schema_graph.tables.keys())
+    schema_literal_text = schema_graph.schema_literal_text
+    llm_calls = 0
+
+    system, user = _build_intent_parse_prompt(question, schema_literal_text, table_list)
+
+    raw = llm_chat(system, user, task="intent")
+    llm_calls += 1
+    debug(f"[intent_process.full_intent_parse] raw_llm_response: {raw}")
+    intent, fmt_calls = _format_repair_loop(system, raw, question, max_retries)
+    llm_calls += fmt_calls
+
+    if not intent:
+        debug("[intent_process.full_intent_parse] format repair exhausted on initial parse — terminating")
+        return None, [], llm_calls
+
+    debug(
+        f"[intent_process.full_intent_parse] normalized intent after initial parse:\n"
+        f"{stable_json(intent.to_dict())}"
+    )
+
+    semantic_warnings: list[str] = []
+    seen_warning_ids: set[str] = set()
+    semantic_error_history: list[frozenset[str]] = []
+    accumulated_failure_hints: list[str] = []
+
+    for sem_round in range(PolicyConfig.MAX_REPAIR_LOOPS):
+        debug(f"[intent_process.full_intent_parse] semantic round {sem_round + 1}/{PolicyConfig.MAX_REPAIR_LOOPS}")
+
+        intent = _apply_deterministic_repairs(intent, schema_graph, question)
+        debug(
+            f"[intent_process.full_intent_parse] full intent after deterministic repairs:\n"
+            f"{stable_json(intent.to_dict())}"
+        )
+
+        schema_error_history: list[frozenset[str]] = []
+        schema_resolved = False
+        for schema_sub in range(max_schema_sub_rounds):
+            intent, schema_errors = enforce_schema(intent, schema_graph)
+            if not schema_errors:
+                schema_resolved = True
+                break
+            debug(
+                f"[intent_process.full_intent_parse] schema sub-round {schema_sub + 1}/{max_schema_sub_rounds}: "
+                f"{len(schema_errors)} errors"
+            )
+            sig = _compute_error_signature_strings(schema_errors)
+            schema_error_history.append(sig)
+            if _detect_oscillation(schema_error_history):
+                debug("[intent_process.full_intent_parse] schema oscillation detected — breaking sub-loop")
+                accumulated_failure_hints.extend(schema_errors)
+                break
+            if schema_sub >= max_schema_sub_rounds - 1:
+                accumulated_failure_hints.extend(schema_errors)
+                break
+            schema_issues = [
+                IntentIssue(
+                    issue_id=f"schema_error_{idx}",
+                    category=_classify_schema_error(err),
+                    severity="error",
+                    message=err,
+                )
+                for idx, err in enumerate(schema_errors)
+            ]
+            for iss in schema_issues:
+                debug(f"[intent_process.full_intent_parse]   issue_id={iss.issue_id} message={iss.message}")
+            intent_json = stable_json(intent.to_dict())
+            debug(
+                f"[intent_process.full_intent_parse] intent being sent to schema repair LLM:\n{intent_json}"
+            )
+            debug(
+                f"[intent_process.full_intent_parse] schema errors_to_fix: "
+                f"{[(iss.category, iss.message) for iss in schema_issues]}"
+            )
+            repair_prompt = _build_intent_semantic_repair_prompt(
+                question, intent_json, schema_issues, [], schema_literal_text
+            )
+            repaired_raw = llm_chat(system, repair_prompt, task="intent")
+            llm_calls += 1
+            repaired, fmt_calls = _format_repair_loop(system, repaired_raw, question, max_retries)
+            llm_calls += fmt_calls
+            if not repaired:
+                debug("[intent_process.full_intent_parse] format repair exhausted after schema repair — terminating")
+                return _attempt_fresh_restart(
+                    question,
+                    system,
+                    schema_literal_text,
+                    table_list,
+                    accumulated_failure_hints,
+                    max_retries,
+                    schema_graph,
+                    llm_calls,
+                )
+            intent = repaired
+            debug(
+                f"[intent_process.full_intent_parse] normalized intent after schema repair:\n"
+                f"{stable_json(intent.to_dict())}"
+            )
+            intent = _apply_deterministic_repairs(intent, schema_graph, question)
+
+        if not schema_resolved:
+            debug("[intent_process.full_intent_parse] schema errors persist after sub-loop — terminating")
+            return _attempt_fresh_restart(
+                question,
+                system,
+                schema_literal_text,
+                table_list,
+                accumulated_failure_hints,
+                max_retries,
+                schema_graph,
+                llm_calls,
+            )
+
+        validation_result = validate_semantics(intent, schema_graph)
+
+        errors = [iss for iss in validation_result.issues if iss.severity == "error"]
+        warnings = [iss for iss in validation_result.issues if iss.severity == "warning"]
+
+        for iss in validation_result.issues:
+            debug(f"[intent_process.full_intent_parse]   issue_id={iss.issue_id} message={iss.message}")
+        for w in warnings:
+            if w.issue_id not in seen_warning_ids:
+                seen_warning_ids.add(w.issue_id)
+                semantic_warnings.append(w.message)
+
+        if not errors:
+            debug(f"[intent_process.full_intent_parse] no semantic errors in round {sem_round + 1}")
+            break
+
+        debug(
+            f"[intent_process.full_intent_parse] {len(errors)} errors, {len(warnings)} warnings in round {sem_round + 1}"
+        )
+        accumulated_failure_hints.extend(iss.message for iss in errors)
+
+        sig = _compute_error_signature_issues(errors)
+        semantic_error_history.append(sig)
+        if _detect_oscillation(semantic_error_history):
+            debug("[intent_process.full_intent_parse] semantic oscillation detected — trying fresh restart")
+            return _attempt_fresh_restart(
+                question,
+                system,
+                schema_literal_text,
+                table_list,
+                accumulated_failure_hints,
+                max_retries,
+                schema_graph,
+                llm_calls,
+            )
+
+        if sem_round >= PolicyConfig.MAX_REPAIR_LOOPS - 1:
+            debug("[intent_process.full_intent_parse] semantic errors persist after max rounds — trying fresh restart")
+            return _attempt_fresh_restart(
+                question,
+                system,
+                schema_literal_text,
+                table_list,
+                accumulated_failure_hints,
+                max_retries,
+                schema_graph,
+                llm_calls,
+            )
+
+        intent_json = stable_json(intent.to_dict())
+        debug(
+            f"[intent_process.full_intent_parse] intent being sent to semantic repair LLM:\n{intent_json}"
+        )
+        debug(
+            f"[intent_process.full_intent_parse] errors_to_fix: "
+            f"{[(e.category, e.message) for e in errors]}"
+        )
+        repair_prompt = _build_intent_semantic_repair_prompt(
+            question, intent_json, errors, warnings, schema_literal_text
+        )
+        repaired_raw = llm_chat(system, repair_prompt, task="intent")
+        llm_calls += 1
+        repaired, fmt_calls = _format_repair_loop(system, repaired_raw, question, max_retries)
+        llm_calls += fmt_calls
+
+        if not repaired:
+            debug(
+                "[intent_process.full_intent_parse] format repair exhausted after semantic repair — trying fresh restart"
+            )
+            return _attempt_fresh_restart(
+                question,
+                system,
+                schema_literal_text,
+                table_list,
+                accumulated_failure_hints,
+                max_retries,
+                schema_graph,
+                llm_calls,
+            )
+
+        intent = repaired
+        debug(
+            f"[intent_process.full_intent_parse] normalized intent after semantic repair:\n"
+            f"{stable_json(intent.to_dict())}"
+        )
+
+    result = _apply_post_processing(intent, schema_graph, question)
+    if result is None:
+        return None, [], llm_calls
+
+    debug(
+        f"[intent_process.full_intent_parse] parsed intent with {len(result.tables or [])} tables, "
+        f"{len(result.filters_param or [])} filters, {llm_calls} LLM calls"
+    )
+
+    return result, semantic_warnings, llm_calls
+
+
+def _compute_filters_similarity(filters1: list[FilterParam], filters2: list[FilterParam]) -> float:
+    """Compute Jaccard similarity between two filter parameter lists.
+
+    Args:
+
+
+        filters1: First list of FilterParam objects.
+        filters2: Second list of FilterParam objects.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0] with 1.0 when both lists are empty or identical.
+    """
+    if not filters1 and not filters2:
+        return 1.0
+    if not filters1 or not filters2:
+        return 0.0
+    keys1 = {fp.signature_key for fp in filters1}
+    keys2 = {fp.signature_key for fp in filters2}
+    score = _jaccard(keys1, keys2)
+    if score > 0:
+        bops1 = sorted(fp.bool_op for fp in filters1)
+        bops2 = sorted(fp.bool_op for fp in filters2)
+        if bops1 != bops2:
+            score *= 0.9
+    return score
+
+
+def _compute_having_similarity(having1: list[HavingParam], having2: list[HavingParam]) -> float:
+    """Compute Jaccard similarity between two having parameter lists.
+
+    Args:
+
+
+        having1: First list of HavingParam objects.
+        having2: Second list of HavingParam objects.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0] with 1.0 when both lists are empty or identical.
+    """
+    if not having1 and not having2:
+        return 1.0
+    if not having1 or not having2:
+        return 0.0
+    keys1 = {hp.signature_key for hp in having1}
+    keys2 = {hp.signature_key for hp in having2}
+    score = _jaccard(keys1, keys2)
+    if score > 0:
+        bops1 = sorted(hp.bool_op for hp in having1)
+        bops2 = sorted(hp.bool_op for hp in having2)
+        if bops1 != bops2:
+            score *= 0.9
+    return score
+
+
+def _compute_select_cols_similarity(cols1: list[SelectCol], cols2: list[SelectCol]) -> float:
+    """Compute Jaccard similarity between two select column lists.
+
+    Args:
+
+
+        cols1: First list of SelectCol objects.
+        cols2: Second list of SelectCol objects.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0] with 1.0 when both lists are empty or identical.
+    """
+    if not cols1 and not cols2:
+        return 1.0
+    if not cols1 or not cols2:
+        return 0.0
+    keys1 = {sc.signature_key for sc in cols1}
+    keys2 = {sc.signature_key for sc in cols2}
+    return _jaccard(keys1, keys2)
+
+
+def _compute_order_by_cols_similarity(cols1: list[OrderByCol], cols2: list[OrderByCol]) -> float:
+    """Compute Jaccard similarity between two order-by column lists.
+
+    Args:
+
+
+        cols1: First list of OrderByCol objects.
+        cols2: Second list of OrderByCol objects.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0] with 1.0 when both lists are empty or identical.
+    """
+    if not cols1 and not cols2:
+        return 1.0
+    if not cols1 or not cols2:
+        return 0.0
+    keys1 = {obc.signature_key for obc in cols1}
+    keys2 = {obc.signature_key for obc in cols2}
+    return _jaccard(keys1, keys2)
+
+
+def _base_similarity(
+    tables1: list[str],
+    tables2: list[str],
+    select1: list[SelectCol],
+    select2: list[SelectCol],
+    group1: list[NormalizedExpr],
+    group2: list[NormalizedExpr],
+    order1: list[OrderByCol],
+    order2: list[OrderByCol],
+    filters1: list[FilterParam],
+    filters2: list[FilterParam],
+    having1: list[HavingParam],
+    having2: list[HavingParam],
+) -> float:
+    """Compute a uniformly weighted similarity score across all structural intent fields.
+
+    Each of the six dimensions (tables, select, group_by, order_by, filters, and having) contributes an equal one sixth weight.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0].
+    """
+    tables_sim = _jaccard(set(tables1), set(tables2))
+    select_sim = _compute_select_cols_similarity(select1, select2)
+    group_sim = _jaccard({g.signature_key for g in group1}, {g.signature_key for g in group2})
+    order_sim = _compute_order_by_cols_similarity(order1, order2)
+    filter_sim = _compute_filters_similarity(filters1, filters2)
+    having_sim = _compute_having_similarity(having1, having2)
+    return (
+        1 / 6 * tables_sim
+        + 1 / 6 * select_sim
+        + 1 / 6 * group_sim
+        + 1 / 6 * order_sim
+        + 1 / 6 * filter_sim
+        + 1 / 6 * having_sim
+    )
+
+
+def _cte_step_similarity(cte1: RuntimeCteStep, cte2: RuntimeCteStep) -> float:
+    """Compute similarity score between two CTE steps.
+
+    Args:
+
+
+        cte1: First CTE step.
+        cte2: Second CTE step.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0].
+    """
+    return _base_similarity(
+        cte1.tables or [],
+        cte2.tables or [],
+        cte1.select_cols or [],
+        cte2.select_cols or [],
+        cte1.group_by_cols or [],
+        cte2.group_by_cols or [],
+        cte1.order_by_cols or [],
+        cte2.order_by_cols or [],
+        cte1.filters_param or [],
+        cte2.filters_param or [],
+        cte1.having_param or [],
+        cte2.having_param or [],
+    )
+
+
+def intent_similarity(intent1: RuntimeIntent | ConcreteIntent, intent2: RuntimeIntent | ConcreteIntent) -> float:
+    """Compute overall similarity score between two intents with dynamic CTE weighting.
+
+    The main-query similarity is down-weighted when CTEs are present and the remaining weight is split equally across matched CTE step pairs.
+
+    Args:
+
+
+        intent1: First intent, either a RuntimeIntent or a ConcreteIntent.
+        intent2: Second intent.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0].
+    """
+    base_sim = _base_similarity(
+        intent1.tables or [],
+        intent2.tables or [],
+        intent1.select_cols or [],
+        intent2.select_cols or [],
+        intent1.group_by_cols or [],
+        intent2.group_by_cols or [],
+        intent1.order_by_cols or [],
+        intent2.order_by_cols or [],
+        intent1.filters_param or [],
+        intent2.filters_param or [],
+        intent1.having_param or [],
+        intent2.having_param or [],
+    )
+    ctes1 = intent1.cte_steps or []
+    ctes2 = intent2.cte_steps or []
+    n_cte = max(len(ctes1), len(ctes2))
+    if n_cte == 0:
+        return base_sim
+    intent_weight = {1: 0.7, 2: 0.6}.get(n_cte, 0.4)
+    cte_total_weight = 1.0 - intent_weight
+    cte_per_weight = cte_total_weight / n_cte
+    cte_score = 0.0
+    for i in range(n_cte):
+        if i < len(ctes1) and i < len(ctes2):
+            cte_score += cte_per_weight * _cte_step_similarity(ctes1[i], ctes2[i])
+    return intent_weight * base_sim + cte_score
+
+
+def _jaccard(set1: set[str], set2: set[str]) -> float:
+    """Compute Jaccard similarity between two string sets.
+
+    Args:
+
+
+        set1: First set of strings.
+        set2: Second set of strings.
+
+    Returns:
+
+
+        Float in the range [0.0, 1.0] with 1.0 when both sets are empty.
+    """
+    if not set1 and not set2:
+        return 1.0
+    if not set1 or not set2:
+        return 0.0
+    intersection = set1 & set2
+    union = set1 | set2
+    return len(intersection) / len(union) if union else 1.0
+
+
+def intent_approval(intent: SimulatorIntent, runtime_intent: RuntimeIntent) -> tuple[float, list[str]]:
+    """Check how closely a SimulatorIntent matches its RuntimeIntent conversion.
+
+    Compares tables, select columns, group_by, order_by, filters, having, and CTE step counts and then computes an overall similarity score.
+
+    Args:
+
+
+        intent: SimulatorIntent to evaluate.
+        runtime_intent: RuntimeIntent to compare against.
+
+    Returns:
+
+
+        Tuple of (score, diffs) where score is a float in [0.0, 1.0] and diffs is a list of human-readable difference descriptions.
+    """
+    diffs: list[str] = []
+    if sorted(intent.tables or []) != sorted(runtime_intent.tables or []):
+        diffs.append(f"tables: {sorted(intent.tables or [])} vs {sorted(runtime_intent.tables or [])}")
+    if len(intent.select_cols or []) != len(runtime_intent.select_cols or []):
+        diffs.append(f"select_cols_count: {len(intent.select_cols or [])} vs {len(runtime_intent.select_cols or [])}")
+    else:
+        src_sigs = sorted(s.signature_key for s in (intent.select_cols or []))
+        tgt_sigs = sorted(s.signature_key for s in (runtime_intent.select_cols or []))
+        if src_sigs != tgt_sigs:
+            diffs.append(f"select_cols_sigs: {src_sigs} vs {tgt_sigs}")
+    src_gb = sorted(g.signature_key for g in (intent.group_by_cols or []))
+    tgt_gb = sorted(g.signature_key for g in (runtime_intent.group_by_cols or []))
+    if src_gb != tgt_gb:
+        diffs.append(f"group_by_cols: {src_gb} vs {tgt_gb}")
+    if len(intent.order_by_cols or []) != len(runtime_intent.order_by_cols or []):
+        diffs.append(
+            f"order_by_cols_count: {len(intent.order_by_cols or [])} vs {len(runtime_intent.order_by_cols or [])}"
+        )
+    else:
+        src_obc = sorted(o.signature_key for o in (intent.order_by_cols or []))
+        tgt_obc = sorted(o.signature_key for o in (runtime_intent.order_by_cols or []))
+        if src_obc != tgt_obc:
+            diffs.append(f"order_by_cols_sigs: {src_obc} vs {tgt_obc}")
+    if len(intent.filters_param or []) != len(runtime_intent.filters_param or []):
+        diffs.append(f"filters_count: {len(intent.filters_param or [])} vs {len(runtime_intent.filters_param or [])}")
+    else:
+        src_fp = sorted(fp.signature_key for fp in (intent.filters_param or []))
+        tgt_fp = sorted(fp.signature_key for fp in (runtime_intent.filters_param or []))
+        if src_fp != tgt_fp:
+            diffs.append(f"filters_sigs: {src_fp} vs {tgt_fp}")
+        else:
+            src_fp_bo = sorted((fp.signature_key, fp.bool_op, fp.filter_group) for fp in (intent.filters_param or []))
+            tgt_fp_bo = sorted(
+                (fp.signature_key, fp.bool_op, fp.filter_group) for fp in (runtime_intent.filters_param or [])
+            )
+            if src_fp_bo != tgt_fp_bo:
+                diffs.append(f"filters_bool_op: {src_fp_bo} vs {tgt_fp_bo}")
+    if len(intent.having_param or []) != len(runtime_intent.having_param or []):
+        diffs.append(f"having_count: {len(intent.having_param or [])} vs {len(runtime_intent.having_param or [])}")
+    else:
+        src_hp = sorted(hp.signature_key for hp in (intent.having_param or []))
+        tgt_hp = sorted(hp.signature_key for hp in (runtime_intent.having_param or []))
+        if src_hp != tgt_hp:
+            diffs.append(f"having_sigs: {src_hp} vs {tgt_hp}")
+        else:
+            src_hp_bo = sorted((hp.signature_key, hp.bool_op, hp.filter_group) for hp in (intent.having_param or []))
+            tgt_hp_bo = sorted(
+                (hp.signature_key, hp.bool_op, hp.filter_group) for hp in (runtime_intent.having_param or [])
+            )
+            if src_hp_bo != tgt_hp_bo:
+                diffs.append(f"having_bool_op: {src_hp_bo} vs {tgt_hp_bo}")
+    src_cte_count = len(intent.cte_steps or [])
+    tgt_cte_count = len(runtime_intent.cte_steps or [])
+    if src_cte_count != tgt_cte_count:
+        diffs.append(f"cte_steps_count: {src_cte_count} vs {tgt_cte_count}")
+    converted = intent.to_runtime_intent()
+    score = intent_similarity(converted, runtime_intent)
+    return score, diffs
+
+
+def find_trusted_template_match(question: str, templates: list[Template]) -> tuple[RuntimeIntent, Template] | None:
+    """Check whether the LLM intent parse can be skipped via a trusted template match.
+
+    Only templates with trust_level equal to 2 are considered and an exact fuzzy match against any historical question in the template triggers the skip path.
+
+    Args:
+
+
+        question: Normalized question to look up.
+        templates: List of Template objects to search.
+
+    Returns:
+
+
+        Tuple of (None, matching_template) when a match is found, or None when no match is found and the LLM must be called.
+    """
+    if not templates:
+        return None
+
+    for tpl in templates:
+        if tpl.trust_level != 2:
+            debug(f"[intent_process.find_trusted_template_match] {tpl.id} skipped (trust={tpl.trust_level})")
+            continue
+
+        for hist_q in tpl.value_history.questions:
+            if exact_question_match(question, hist_q or "", label=tpl.id):
+                debug(f"[intent_process.find_trusted_template_match] fuzzy match with template {tpl.id}")
+                return None, tpl
+
+    return None
+
+
+def llm_ux_explain(intent: RuntimeIntent, question: str) -> str:
+    """Generate a short user-friendly explanation of an intent for disambiguation.
+
+    Args:
+
+
+        intent: Parsed RuntimeIntent to summarize.
+        question: Original question, unused in the LLM prompt but available for context.
+
+    Returns:
+
+
+        Plain English phrase under 10 words describing what the query does.
+    """
+    system = "You are a helpful assistant that explains SQL queries in plain English. Output JSON with a single 'summary' key."
+
+    tables = ", ".join(intent.tables or [])
+
+    cols_desc = []
+    for sc in intent.select_cols or []:
+        term = sc.expr.primary_term
+        cols_desc.append(term if term else "*")
+    cols_str = ", ".join(cols_desc) if cols_desc else "*"
+
+    filters_desc = []
+    all_filters = intent.filters_param or []
+    for i, fp in enumerate(all_filters):
+        left = fp.left_expr.primary_column or fp.left_expr.primary_term
+        if fp.right_expr:
+            right = fp.right_expr.primary_column or fp.right_expr.primary_term
+            filters_desc.append(f"{left} {fp.op} {right}")
+        else:
+            filters_desc.append(f"{left} {fp.op} ?")
+        if i < len(all_filters) - 1:
+            filters_desc.append(fp.bool_op)
+    filters_str = " ".join(filters_desc) if filters_desc else "none"
+
+    user = stable_json(
+        {
+            "task": "Summarize what this query does in one short phrase (under 10 words). Do not mention specific filter values or literals. Return JSON: {\"summary\": \"<phrase>\"}.",
+            "tables": tables,
+            "columns": cols_str,
+            "filters": filters_str,
+            "group_by": ", ".join(g.primary_column for g in (intent.group_by_cols or [])) or "none",
+        }
+    )
+
+    raw = llm_chat(system, user, task="intent")
+    parsed = safe_json_loads(raw)
+    if isinstance(parsed, dict) and isinstance(parsed.get("summary"), str):
+        return parsed["summary"].strip()
+    return raw.strip()
+
+
+MAX_NON_AGG_COL_DIFF = 2
+
+
+def _cte_structural_signature(steps: list) -> list[tuple[str, str]]:
+    """Build sorted structural fingerprints for CTE steps.
+
+    Each CTE step produces a ``(cte_name, body_signature)`` tuple where the
+    body signature covers filters, group-by, order-by, having, and grain but
+    deliberately excludes select columns so that column-only deltas are
+    handled by the union matching logic.
+
+    Args:
+        steps: CTE step objects (``RuntimeCteStep`` or ``ConcreteCteStep``).
+
+    Returns:
+        Sorted list of ``(cte_name, body_signature)`` tuples.
+    """
+    sigs: list[tuple[str, str]] = []
+    for cte in steps:
+        parts: list[str] = [
+            cte.grain or "row_level",
+            ",".join(sorted(f.signature_key for f in (cte.filters_param or []))),
+            ",".join(sorted(g.signature_key for g in (cte.group_by_cols or []))),
+            ",".join(sorted(o.signature_key for o in (cte.order_by_cols or []))),
+            ",".join(sorted(h.signature_key for h in (cte.having_param or []))),
+        ]
+        sigs.append((cte.cte_name, "|".join(parts)))
+    return sorted(sigs, key=lambda t: t[0])
+
+
+def _structural_body_matches(
+    intent: RuntimeIntent,
+    concrete: ConcreteIntent,
+) -> bool:
+    """Check whether every non-select structural element matches exactly.
+
+    Compares grain, limit, filters, group-by, order-by, having, and CTE body
+    signatures between the incoming runtime intent and a stored concrete
+    intent.  Select columns and tables are deliberately excluded because they
+    are handled by the union diff logic.
+
+    Args:
+        intent: The newly parsed runtime intent.
+        concrete: The stored concrete intent from an existing template.
+
+    Returns:
+        ``True`` when all structural clauses match.
+    """
+    if (intent.grain or "row_level") != (concrete.grain or "row_level"):
+        return False
+    if intent.limit != concrete.limit:
+        return False
+
+    i_filters = sorted(f.signature_key for f in (intent.filters_param or []))
+    c_filters = sorted(f.signature_key for f in (concrete.filters_param or []))
+    if i_filters != c_filters:
+        return False
+
+    i_gb = sorted(g.signature_key for g in (intent.group_by_cols or []))
+    c_gb = sorted(g.signature_key for g in (concrete.group_by_cols or []))
+    if i_gb != c_gb:
+        return False
+
+    i_ob = sorted(o.signature_key for o in (intent.order_by_cols or []))
+    c_ob = sorted(o.signature_key for o in (concrete.order_by_cols or []))
+    if i_ob != c_ob:
+        return False
+
+    i_hav = sorted(h.signature_key for h in (intent.having_param or []))
+    c_hav = sorted(h.signature_key for h in (concrete.having_param or []))
+    if i_hav != c_hav:
+        return False
+
+    if _cte_structural_signature(intent.cte_steps or []) != _cte_structural_signature(
+        concrete.cte_steps or []
+    ):
+        return False
+
+    return True
+
+
+def _select_col_diff(
+    intent_cols: list[SelectCol],
+    concrete_cols: list[SelectCol],
+) -> tuple[bool, int]:
+    """Compute the select-column delta between two intents.
+
+    Aggregated columns must match exactly; non-aggregated columns may differ
+    by up to ``MAX_NON_AGG_COL_DIFF``.
+
+    Args:
+        intent_cols: Select columns from the runtime intent.
+        concrete_cols: Select columns from the stored concrete intent.
+
+    Returns:
+        ``(agg_match, non_agg_diff)`` — whether aggregate columns are
+        identical and the count of non-aggregate column key differences.
+    """
+    i_agg = sorted(s.signature_key for s in intent_cols if s.is_aggregated)
+    c_agg = sorted(s.signature_key for s in concrete_cols if s.is_aggregated)
+    agg_match = i_agg == c_agg
+
+    i_non = set(s.signature_key for s in intent_cols if not s.is_aggregated)
+    c_non = set(s.signature_key for s in concrete_cols if not s.is_aggregated)
+    non_agg_diff = len(i_non.symmetric_difference(c_non))
+
+    return agg_match, non_agg_diff
+
+
+def _diff_cols_span_disjoint_tables(
+    intent_cols: list[SelectCol],
+    concrete_cols: list[SelectCol],
+    intent_tables: list[str],
+    concrete_tables: list[str],
+) -> bool:
+    """Return True when any differing non-agg column references a
+    table outside the intersection of both table lists.
+
+    Prevents a union match from absorbing columns that would
+    introduce joins the template cannot satisfy, or from inheriting
+    stale template columns that reference tables the intent does not
+    need.
+
+    Args:
+        intent_cols: Select columns from the runtime intent.
+        concrete_cols: Select columns from the stored concrete intent.
+        intent_tables: Table list from the runtime intent.
+        concrete_tables: Table list from the stored concrete intent.
+
+    Returns:
+        ``True`` if any diff column belongs to a table not shared by
+        both intents.
+    """
+    shared_tables = set(intent_tables or []) & set(concrete_tables or [])
+    i_non = {s.signature_key for s in intent_cols if not s.is_aggregated}
+    c_non = {s.signature_key for s in concrete_cols if not s.is_aggregated}
+    diff_keys = i_non.symmetric_difference(c_non)
+    if not diff_keys:
+        return False
+    all_cols = list(intent_cols) + list(concrete_cols)
+    for sc in all_cols:
+        if sc.is_aggregated or sc.signature_key not in diff_keys:
+            continue
+        term = sc.expr.primary_term
+        tbl = term.split(".")[0] if "." in term else ""
+        if tbl and tbl not in shared_tables:
+            return True
+    return False
+
+
+def match_template_for_union(
+    intent: RuntimeIntent,
+    templates: dict[str, Template],
+) -> tuple[Template, list[SelectCol], bool] | None:
+    """Find the best template whose structure can absorb the new intent
+    via column-only union.
+
+    Iterates all templates with ``trust_level >= 1`` and checks for an
+    exact structural body match (filters, group-by, order-by, having,
+    CTE skeleton, grain, limit).  Select columns may differ by up to
+    ``MAX_NON_AGG_COL_DIFF`` non-aggregate columns, and aggregate
+    columns must match exactly.
+
+    A match is rejected when any differing non-aggregate column
+    references a table outside the intersection of the intent and
+    template table lists.  This prevents union merges from inheriting
+    stale context columns that would introduce foreign joins.
+
+    When a match is found the function delegates to
+    ``compute_intent_union`` to produce merged select columns.  Among
+    all valid candidates the template with the smallest column diff
+    is preferred.
+
+    Args:
+        intent: The newly parsed and validated runtime intent.
+        templates: All stored templates keyed by template id.
+
+    Returns:
+        ``(matched_template, union_select_cols, cols_changed)`` for the
+        best match, or ``None`` when no template qualifies.
+    """
+    best: tuple[Template, list[SelectCol], bool, int] | None = None
+
+    for tmpl in templates.values():
+        if tmpl.trust_level < 1:
+            continue
+
+        concrete = tmpl.intent_signature
+        if not _structural_body_matches(intent, concrete):
+            continue
+
+        agg_match, non_agg_diff = _select_col_diff(
+            intent.select_cols or [], concrete.select_cols or [],
+        )
+        if not agg_match:
+            continue
+        if non_agg_diff > MAX_NON_AGG_COL_DIFF:
+            continue
+
+        if _diff_cols_span_disjoint_tables(
+            intent.select_cols or [],
+            concrete.select_cols or [],
+            intent.tables or [],
+            concrete.tables or [],
+        ):
+            continue
+
+        union_cols, cols_changed = compute_intent_union(intent, concrete)
+
+        if best is None or non_agg_diff < best[3]:
+            best = (tmpl, union_cols, cols_changed, non_agg_diff)
+
+    if best is None:
+        return None
+
+    debug(
+        f"[intent_process.match_template_for_union] matched template={best[0].id} "
+        f"non_agg_diff={best[3]} union_cols={len(best[1])}"
+    )
+    return best[0], best[1], best[2]
+
+
+def compute_intent_union(
+    intent: RuntimeIntent,
+    concrete: ConcreteIntent,
+) -> tuple[list[SelectCol], bool]:
+    """Compute the column-only union between two intents.
+
+    Deduplicates select columns by ``signature_key`` preserving the
+    order from the concrete intent first, then appending any new
+    columns from the runtime intent.
+
+    Args:
+        intent: The newly parsed runtime intent.
+        concrete: The stored concrete intent from the matched template.
+
+    Returns:
+        ``(union_select_cols, cols_changed)`` where ``cols_changed``
+        indicates whether the union differs from the concrete intent's
+        original column set.
+    """
+    seen_keys: set[str] = set()
+    union_cols: list[SelectCol] = []
+    for sc in concrete.select_cols or []:
+        key = sc.signature_key
+        if key not in seen_keys:
+            seen_keys.add(key)
+            union_cols.append(sc)
+    for sc in intent.select_cols or []:
+        key = sc.signature_key
+        if key not in seen_keys:
+            seen_keys.add(key)
+            union_cols.append(sc)
+
+    cols_changed = sorted(seen_keys) != sorted(
+        s.signature_key for s in (concrete.select_cols or [])
+    )
+
+    debug(
+        f"[intent_process.compute_intent_union] "
+        f"union_cols={len(union_cols)} cols_changed={cols_changed}"
+    )
+    return union_cols, cols_changed