aetherdialect 0.1.0__py3-none-any.whl

text2sql/sql_gen.py

@@ -0,0 +1,1537 @@
+"""SQL generation, join path resolution, and canonical normalization.
+
+Responsible for building the SQL prompt and repair prompt sent to the LLM, enumerating and ranking all valid FK-based join paths between a set of tables, normalising generated SQL to a canonical JOIN order and predicate form, and validating that the LLM-chosen join candidate matches the actual SQL structure. Also provides utilities for rendering intent expressions as SQL fragments used in the generation prompt and for post-hoc alias injection.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .config import SCALAR_FUNCTIONS_LEADING_ARG, EngineConfig, PolicyConfig
+from .contracts_base import SchemaGraph
+from .contracts_core import FilterParam, MulGroup, NormalizedExpr, RuntimeCteStep, RuntimeIntent, SelectCol
+from .core_utils import debug, llm_json, llm_sql_with_join, stable_json
+from .dialect import get_dialect, render_date_diff_expr, render_date_window_expr
+
+
+def cte_to_intent_for_ranking(cte: RuntimeCteStep) -> RuntimeIntent:
+    """Build a synthetic ``RuntimeIntent`` from ``RuntimeCteStep`` for CTE join ranking.
+
+    Args:
+
+        cte: The ``RuntimeCteStep`` whose tables and intent fields should be promoted.
+
+    Returns:
+
+        A ``RuntimeIntent`` with the CTE's tables, grain, select/group/order/filter/having columns, param values, column map, and limit, suitable for join scoring.
+    """
+    return RuntimeIntent(
+        tables=cte.tables,
+        grain=cte.grain,
+        select_cols=cte.select_cols,
+        group_by_cols=cte.group_by_cols,
+        order_by_cols=cte.order_by_cols,
+        filters_param=cte.filters_param,
+        having_param=cte.having_param,
+        param_values=cte.param_values,
+        column_map=cte.column_map,
+        limit=cte.limit,
+        cte_steps=[],
+    )
+
+
+SQL_REPAIR_SYSTEM_PROMPT = """You are a deterministic SQL repair assistant.
+
+Output requirements:
+- Output ONLY valid JSON that matches the specified output_schema.
+- Do NOT include markdown, explanations, or commentary.
+- Identical inputs must produce identical outputs.
+
+Repair guidelines:
+- Make minimal changes to fix the specific error.
+- Do not change query logic unless required to fix the error.
+- Preserve JOIN structure unless the error requires changing it.
+- Maintain existing filters, aggregations, and ordering when possible.
+"""
+
+
+def join_candidate_map(join_hints: dict[str, Any]) -> dict[str, list[str]]:
+    """Build map from candidate ID to join path signature.
+
+    Args:
+
+        join_hints: The join hints dict produced by ``join_hints_multi``.
+
+    Returns:
+
+        Dict mapping ``candidate_id`` to list of join path signature strings.
+    """
+    out: dict[str, list[str]] = {}
+    for c in join_hints.get("candidates", []):
+        cid = c.get("candidate_id")
+        sig = c.get("join_path_signature")
+        if isinstance(cid, str) and isinstance(sig, list):
+            out[cid] = [str(x) for x in sig]
+    return out
+
+
+def _analyze_join_topology(sig: list[str]) -> tuple[str, str, list[str]]:
+    """Analyze join signature to determine topology type, hub table, and leaf tables.
+
+    Args:
+
+        sig: List of join path signature strings.
+
+    Returns:
+
+        Tuple of ``(topology_type, anchor_table, leaf_tables)`` where ``topology_type`` is one of ``"none"``, ``"linear"``, ``"star"``, or ``"tree"``; ``anchor_table`` is the canonical root; and ``leaf_tables`` is the list of endpoint tables.
+    """
+    if not sig:
+        return ("none", "", [])
+    table_counts: dict[str, int] = {}
+    for item in sig:
+        if "->" not in item:
+            continue
+        left, right = item.split("->", 1)
+        left_table = left.split(".")[0].strip()
+        right_table = right.split(".")[0].strip()
+        table_counts[left_table] = table_counts.get(left_table, 0) + 1
+        table_counts[right_table] = table_counts.get(right_table, 0) + 1
+    if not table_counts:
+        return ("none", "", [])
+    leaves = sorted([t for t, c in table_counts.items() if c == 1])
+    hubs = sorted(
+        [t for t, c in table_counts.items() if c > 1],
+        key=lambda t: (-table_counts[t], t),
+    )
+    if len(leaves) == 2 and len(hubs) == len(table_counts) - 2:
+        return ("linear", min(leaves), leaves)
+    if len(hubs) == 1:
+        return ("star", hubs[0], leaves)
+    if hubs:
+        return ("tree", hubs[0], leaves)
+    return ("linear", min(table_counts.keys()), list(table_counts.keys()))
+
+
+def reorder_sql_joins_canonical(sql: str, join_sig: list[str]) -> str:
+    """Reorder SQL FROM clause to canonical form based on join topology.
+
+    Args:
+
+        sql: The SQL string whose FROM/JOIN clause should be reordered.
+
+        join_sig: The join path signature that defines the canonical order.
+
+    Returns:
+
+        SQL string with the FROM clause reordered; returns the original SQL unchanged if topology is ``"none"`` or the SQL cannot be parsed.
+    """
+    if not join_sig or len(join_sig) == 0:
+        return sql
+    topology_type, anchor, leaves = _analyze_join_topology(join_sig)
+    if topology_type == "none":
+        return sql
+    from_match = re.search(r"\bFROM\s+(\w+)", sql, re.IGNORECASE)
+    if not from_match:
+        return sql
+    current_first_table = from_match.group(1).lower()
+    if topology_type == "linear":
+        if current_first_table == anchor.lower():
+            return sql
+        other_endpoint = [leaf for leaf in leaves if leaf.lower() != anchor.lower()]
+        if not other_endpoint or current_first_table != other_endpoint[0].lower():
+            return sql
+        join_pattern = re.compile(
+            r"\bFROM\s+(\w+)\s+((?:(?:INNER\s+)?JOIN\s+\w+\s+ON\s+[^)]+?(?=\s+(?:INNER\s+)?JOIN|\s+WHERE|\s+GROUP|\s+ORDER|\s+LIMIT|\s+HAVING|$))+)",
+            re.IGNORECASE | re.DOTALL,
+        )
+        match = join_pattern.search(sql)
+        if not match:
+            return sql
+        first_table = match.group(1)
+        joins_block = match.group(2)
+        join_clauses = re.findall(
+            r"((?:INNER\s+)?JOIN\s+(\w+)\s+ON\s+([^)]+?)(?=\s+(?:INNER\s+)?JOIN|\s*$))",
+            joins_block,
+            re.IGNORECASE | re.DOTALL,
+        )
+        if not join_clauses:
+            return sql
+        tables_in_order = [first_table]
+        for jc in join_clauses:
+            tables_in_order.append(jc[1])
+        reversed_tables = list(reversed(tables_in_order))
+        reversed_on_clauses = []
+        for jc in reversed(join_clauses):
+            on_clause = jc[2].strip()
+            reversed_on_clauses.append(on_clause)
+        new_from = f"FROM {reversed_tables[0]}"
+        for i, tbl in enumerate(reversed_tables[1:]):
+            new_from += f" JOIN {tbl} ON {reversed_on_clauses[i]}"
+        original_from_end = match.end()
+        original_from_start = match.start()
+        new_sql = sql[:original_from_start] + new_from + sql[original_from_end:]
+        debug(f"[sql_gen.reorder_sql_joins_canonical] linear reordered: {current_first_table} -> {reversed_tables[0]}")
+        return new_sql
+    if current_first_table == anchor.lower():
+        join_pattern = re.compile(
+            r"\bFROM\s+(\w+)\s+((?:(?:INNER\s+)?JOIN\s+\w+\s+ON\s+[^)]+?(?=\s+(?:INNER\s+)?JOIN|\s+WHERE|\s+GROUP|\s+ORDER|\s+LIMIT|\s+HAVING|$))+)",
+            re.IGNORECASE | re.DOTALL,
+        )
+        match = join_pattern.search(sql)
+        if not match:
+            return sql
+        joins_block = match.group(2)
+        join_clauses = re.findall(
+            r"((?:INNER\s+)?JOIN\s+(\w+)\s+ON\s+([^)]+?)(?=\s+(?:INNER\s+)?JOIN|\s*$))",
+            joins_block,
+            re.IGNORECASE | re.DOTALL,
+        )
+        if not join_clauses:
+            return sql
+        sorted_joins = sorted(join_clauses, key=lambda jc: jc[1].lower())
+        new_from = f"FROM {anchor}"
+        for jc in sorted_joins:
+            new_from += f" JOIN {jc[1]} ON {jc[2].strip()}"
+        original_from_end = match.end()
+        original_from_start = match.start()
+        new_sql = sql[:original_from_start] + new_from + sql[original_from_end:]
+        debug("[sql_gen.reorder_sql_joins_canonical] star/tree branches sorted alphabetically")
+        return new_sql
+    debug(
+        f"[sql_gen.reorder_sql_joins_canonical] star/tree topology but FROM table {current_first_table} != anchor {anchor}"
+    )
+    return sql
+
+
+JOIN_PLACEHOLDER = "-- <JOIN: integrate from join candidates>"
+
+
+def _wrap_for_case_insensitive(expr: str, dialect_type: str) -> str:
+    """Wrap expression for case-insensitive string comparison.
+
+    On Databricks, uses LOWER(TRIM(expr)) to handle whitespace and
+    collation. On other dialects, uses LOWER(expr).
+    """
+    if dialect_type == "databricks":
+        return f"LOWER(TRIM({expr}))"
+    return f"LOWER({expr})"
+
+
+def _join_clause_from_signature(signature: list[str], from_table: str = "") -> str:
+    """Build JOIN clause text from a join path signature.
+
+    Each segment is "src_tbl.col->dst_tbl.col". Tracks tables already in
+    the chain to avoid duplicate JOINs (e.g. when two edges target the
+    same table). When the target is already present, adds the source
+    table instead.
+    """
+    if not signature:
+        return ""
+    chain: set[str] = {from_table.lower()} if from_table else set()
+    parts: list[str] = []
+    for seg in signature:
+        seg = seg.strip()
+        if "->" not in seg:
+            continue
+        left_part, right_part = seg.split("->", 1)
+        left_part = left_part.strip()
+        right_part = right_part.strip()
+        if "." not in left_part or "." not in right_part:
+            continue
+        left_tbl, left_cols = left_part.split(".", 1)
+        right_tbl, right_cols = right_part.split(".", 1)
+        left_col_list = [c.strip() for c in left_cols.split(",")]
+        right_col_list = [c.strip() for c in right_cols.split(",")]
+        on_terms = [
+            f"{left_tbl}.{lc} = {right_tbl}.{rc}"
+            for lc, rc in zip(left_col_list, right_col_list, strict=False)
+        ]
+        if not on_terms:
+            continue
+        right_tbl_lower = right_tbl.lower()
+        left_tbl_lower = left_tbl.lower()
+        if right_tbl_lower in chain:
+            join_tbl = left_tbl
+            chain.add(left_tbl_lower)
+        else:
+            join_tbl = right_tbl
+            chain.add(right_tbl_lower)
+        parts.append(f" JOIN {join_tbl} ON " + " AND ".join(on_terms))
+    return "".join(parts)
+
+
+def _orient_join_sig_for_from(
+    sig: list[str],
+    from_table: str,
+) -> list[str]:
+    """Reorient join segments so that no target duplicates the FROM table.
+
+    When the right-hand (target) table of a segment equals the current
+    FROM table, the segment is flipped so the other table becomes the
+    JOIN target instead.  This prevents ``FROM t JOIN t`` self-join
+    artefacts that occur when ``tables[0]`` in the intent happens to
+    sit on the target side of the join signature.
+    """
+    if not from_table:
+        return sig
+    oriented: list[str] = []
+    for seg in sig:
+        if "->" not in seg:
+            oriented.append(seg)
+            continue
+        left, right = seg.split("->", 1)
+        right_tbl = right.split(".")[0].strip().lower()
+        if right_tbl == from_table:
+            oriented.append(f"{right.strip()}->{left.strip()}")
+        else:
+            oriented.append(seg)
+    return oriented
+
+
+def inject_join_into_deterministic_sql(
+    det_sql: str,
+    join_sigs_ordered: list[list[str]],
+) -> str:
+    """Replace each JOIN placeholder in deterministic SQL with JOIN clause from signatures.
+
+    Placeholders are replaced in order: first occurrence with
+    ``join_sigs_ordered[0]``, etc.  Before building each JOIN clause
+    the signature is oriented so that the target table does not
+    duplicate the current FROM table.
+    """
+    if not join_sigs_ordered:
+        return det_sql
+    result = det_sql
+    for sig in join_sigs_ordered:
+        if JOIN_PLACEHOLDER not in result:
+            break
+        from_match = re.search(r"\bFROM\s+(\w+)", result, re.IGNORECASE)
+        from_tbl = from_match.group(1) if from_match else ""
+        oriented = _orient_join_sig_for_from(sig, from_tbl.lower())
+        join_clause = _join_clause_from_signature(oriented, from_tbl)
+        result = result.replace(JOIN_PLACEHOLDER, join_clause.strip(), 1)
+    result = re.sub(r"\n\s*-- <JOIN[^>]*>\s*", "\n", result)
+    return result
+
+
+def normalize_where_having_predicates(sql: str) -> str:
+    """Normalize WHERE and HAVING predicates to put column references on the left.
+
+    Swaps predicates of the form ``:param op table.column`` to ``table.column op :param`` so that column references always appear on the left-hand side of comparison operators.
+
+    Args:
+
+        sql: The SQL string to normalise.
+
+    Returns:
+
+        SQL string with swapped predicates in WHERE and HAVING clauses.
+    """
+
+    def swap_predicate(match):
+        full = match.group(0)
+        left = match.group(1).strip()
+        op = match.group(2).strip()
+        right = match.group(3).strip()
+
+        left_is_param = left.startswith(":") or left.startswith("'") or left.startswith('"') or left[0].isdigit()
+        right_is_col = "." in right and not (right.startswith(":") or right.startswith("'") or right.startswith('"'))
+
+        if left_is_param and right_is_col:
+            return f"{right} {op} {left}"
+        return full
+
+    pattern = r"([:\w.]+|'[^']*'|\"[^\"]*\")\s*(=|!=|<>|<=|>=|<|>)\s+([:\w.]+|'[^']*'|\"[^\"]*\")"
+
+    where_match = re.search(r"\bWHERE\b", sql, re.IGNORECASE)
+    if where_match:
+        where_start = where_match.end()
+        next_clause = re.search(
+            r"\b(GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT)\b",
+            sql[where_start:],
+            re.IGNORECASE,
+        )
+        where_end = where_start + next_clause.start() if next_clause else len(sql)
+        where_clause = sql[where_start:where_end]
+        normalized_where = re.sub(pattern, swap_predicate, where_clause)
+        sql = sql[:where_start] + normalized_where + sql[where_end:]
+
+    having_match = re.search(r"\bHAVING\b", sql, re.IGNORECASE)
+    if having_match:
+        having_start = having_match.end()
+        next_clause = re.search(r"\b(ORDER\s+BY|LIMIT)\b", sql[having_start:], re.IGNORECASE)
+        having_end = having_start + next_clause.start() if next_clause else len(sql)
+        having_clause = sql[having_start:having_end]
+        normalized_having = re.sub(pattern, swap_predicate, having_clause)
+        sql = sql[:having_start] + normalized_having + sql[having_end:]
+
+    return sql
+
+
+def normalize_cte_sql(sql: str, cte_join_sigs: dict[str, list[str]]) -> str:
+    """Normalize CTE bodies with join reordering and predicate normalization.
+
+    Args:
+
+        sql: The full SQL string that may contain WITH/CTE clauses.
+
+        cte_join_sigs: Dict mapping CTE name to join path signature for reordering.
+
+    Returns:
+
+        SQL string with each CTE body's FROM clause reordered and WHERE/HAVING predicates normalised.
+    """
+    dialect = get_dialect()
+    cte_bodies = dialect.extract_cte_bodies(sql)
+    if not cte_bodies:
+        return sql
+
+    for cte_name, cte_body in cte_bodies.items():
+        join_sig = cte_join_sigs.get(cte_name, [])
+        normalized_body = cte_body
+        if join_sig:
+            normalized_body = reorder_sql_joins_canonical(normalized_body, join_sig)
+        normalized_body = normalize_where_having_predicates(normalized_body)
+        if normalized_body != cte_body:
+            old_cte = f"{cte_name} AS ({cte_body})"
+            new_cte = f"{cte_name} AS ({normalized_body})"
+            sql = sql.replace(old_cte, new_cte)
+
+    debug(f"[sql_gen.normalize_cte_sql] normalized {len(cte_bodies)} CTEs")
+    return sql
+
+
+def _join_path_signature_for_path(path: list[dict[str, Any]]) -> list[str]:
+    """Generate signature strings for a join path.
+
+    Args:
+
+        path: List of edge dicts, each with ``src_table``, ``src_cols``, ``dst_table``, and ``dst_cols`` keys.
+
+    Returns:
+
+        List of strings in the form ``"src_table.col1,col2->dst_table.col3,col4"``.
+    """
+    sig = []
+    for e in path:
+        sig.append(f"{e['src_table']}.{','.join(e['src_cols'])}->{e['dst_table']}.{','.join(e['dst_cols'])}")
+    return sig
+
+
+def _candidate_join_paths_for_tables(schema: SchemaGraph, tables: list[str]) -> list[list[dict[str, Any]]]:
+    """Compute all candidate join paths for a set of tables by trying every table as root.
+
+    First attempts direct paths (no bridge tables). Falls back to bridge-table paths if no direct paths are found.
+
+    Args:
+
+        schema: The schema graph containing pre-computed join paths.
+
+        tables: List of table names that must all be reachable in each candidate.
+
+    Returns:
+
+        List of join paths, each a list of edge dicts with source and destination table and column keys. Returns ``[[]]`` for single-table queries.
+    """
+    tables = sorted(set(tables))
+    if len(tables) < 2:
+        return [[]]
+
+    def uniq_edges(edges: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        seen: set = set()
+        out: list[dict[str, Any]] = []
+        for e in edges:
+            pair = (
+                (e["src_table"], tuple(e["src_cols"])),
+                (e["dst_table"], tuple(e["dst_cols"])),
+            )
+            canonical = tuple(sorted(pair))
+            if canonical in seen:
+                continue
+            seen.add(canonical)
+            out.append(e)
+        return out
+
+    table_set = set(tables)
+
+    def _edges_cover_tables(edges: list[dict[str, Any]], root: str) -> set[str]:
+        covered = {root}
+        for e in edges:
+            covered.add(e["src_table"])
+            covered.add(e["dst_table"])
+        return covered
+
+    def _merge_paths_minimal(
+        root: str, others: list[str], allow_bridges: bool
+    ) -> list[list[dict[str, Any]]]:
+        covered: set[str] = {root}
+        merged: list[dict[str, Any]] = []
+        for target in others:
+            if target in covered:
+                continue
+            paths = schema.join_paths_multi.get(root, {}).get(target, [])
+            if not paths:
+                continue
+            best: list[dict[str, Any]] | None = None
+            for p in paths:
+                if not p:
+                    continue
+                path_tables = _edges_cover_tables(p, root)
+                if target not in path_tables:
+                    continue
+                if not allow_bridges and not path_tables <= table_set:
+                    continue
+                if best is None or len(p) < len(best):
+                    best = p
+            if best:
+                for e in best:
+                    if e not in merged:
+                        merged.append(e)
+                covered = _edges_cover_tables(merged, root)
+        return [merged] if merged else []
+
+    def _collect(allow_bridges: bool) -> dict[tuple, list[dict[str, Any]]]:
+        candidates: dict[tuple, list[dict[str, Any]]] = {}
+        for root in tables:
+            others = [t for t in tables if t != root]
+            for merged in _merge_paths_minimal(root, others, allow_bridges):
+                deduped = uniq_edges(merged)
+                edge_tables = (
+                    {root}
+                    | {e["src_table"] for e in deduped}
+                    | {e["dst_table"] for e in deduped}
+                )
+                if not table_set <= edge_tables:
+                    continue
+                if not allow_bridges and not edge_tables <= table_set:
+                    continue
+                sig = tuple(_join_path_signature_for_path(deduped))
+                if sig not in candidates:
+                    candidates[sig] = deduped
+        return candidates
+
+    all_candidates = _collect(allow_bridges=False)
+    if not all_candidates:
+        all_candidates = _collect(allow_bridges=True)
+        if all_candidates:
+            debug(
+                f"[sql_gen.candidate_join_paths_for_tables] no direct paths, found {len(all_candidates)} bridge paths"
+            )
+
+    res = list(all_candidates.values())
+    res.sort(key=lambda m: (len(m), tuple(_join_path_signature_for_path(m))))
+    return res
+
+
+def _score_join_path(edges: list[dict[str, Any]], intent: RuntimeIntent, schema: SchemaGraph) -> float:
+    """Score a join path based on FK direction, intent alignment, and path characteristics.
+
+    Higher scores indicate more semantically appropriate join paths. Points are awarded for forward FK direction, shorter paths, joins that connect to filtered or grouped columns, and FACT→DIMENSION relationships.
+
+    Args:
+
+        edges: List of join edge dicts for the candidate path.
+
+        intent: The ``RuntimeIntent`` providing filter, group-by, and aggregation context.
+
+        schema: The schema graph for table role and FK metadata.
+
+    Returns:
+
+        Float score; higher is better.
+    """
+    score = 0.0
+
+    filter_columns = set()
+    for fp in intent.filters_param or []:
+        pcol = fp.left_expr.primary_column
+        col_parts = pcol.split(".")
+        if len(col_parts) == 2:
+            filter_columns.add((col_parts[0], col_parts[1]))
+
+    groupby_columns = set()
+    for gb in intent.group_by_cols or []:
+        col_parts = gb.primary_column.split(".")
+        if len(col_parts) == 2:
+            groupby_columns.add((col_parts[0], col_parts[1]))
+
+    agg_tables = set()
+    for sc in intent.select_cols or []:
+        if sc.is_aggregated:
+            pcol = sc.expr.primary_column
+            col_parts = pcol.split(".")
+            if len(col_parts) == 2:
+                agg_tables.add(col_parts[0])
+
+    path_tables = set()
+    for edge in edges:
+        path_tables.add(edge["src_table"])
+        path_tables.add(edge["dst_table"])
+
+    score += max(20 - (len(edges) * 3), 0)
+
+    for edge in edges:
+        src_table = edge["src_table"]
+        dst_table = edge["dst_table"]
+        src_cols = edge["src_cols"]
+        dst_cols = edge["dst_cols"]
+
+        src_meta = schema.tables.get(src_table)
+        dst_meta = schema.tables.get(dst_table)
+
+        if not src_meta or not dst_meta:
+            continue
+
+        is_forward = False
+        for fk in src_meta.foreign_keys:
+            if fk.dst_table == dst_table and set(fk.src_cols) == set(src_cols) and set(fk.dst_cols) == set(dst_cols):
+                is_forward = True
+                break
+
+        if is_forward:
+            score += 10
+        else:
+            score += 5
+
+        for dst_col in dst_cols:
+            if (dst_table, dst_col) in filter_columns:
+                score += 15
+            if (dst_table, dst_col) in groupby_columns:
+                score += 10
+
+        for src_col in src_cols:
+            if (src_table, src_col) in filter_columns:
+                if is_forward and any(
+                    dst_col == src_col.replace("_id", "") or src_col.endswith(f"_{dst_table}_id")
+                    for dst_col in dst_cols
+                ):
+                    score += 12
+
+        if src_table in agg_tables:
+            score += 8
+
+        src_role = src_meta.role or ""
+        dst_role = dst_meta.role or ""
+
+        if dst_role == "DIMENSION":
+            score += 3
+        if src_role == "FACT" and dst_role == "DIMENSION":
+            score += 5
+        if src_role == "FACT" and dst_role == "FACT":
+            score -= 10
+        if dst_role == "BRIDGE":
+            score -= 5
+
+    return score
+
+
+def _format_join_candidate_semantic(
+    candidate_id: str, edges: list[dict[str, Any]], schema: SchemaGraph, score: float
+) -> str:
+    """Format join candidate with semantic labels and FK direction indicators.
+
+    Args:
+
+        candidate_id: The candidate identifier string (for example, ``"J01"``).
+
+        edges: List of join edge dicts for this candidate.
+
+        schema: The schema graph for FK direction lookup.
+
+        score: The numeric score assigned to this candidate.
+
+    Returns:
+
+        Multi-line string describing each join edge with FK direction label and overall score, suitable for inclusion in an LLM prompt.
+    """
+    if not edges:
+        return f"{candidate_id}: Single table (no joins)"
+
+    lines = [f"{candidate_id} [Score: {score:.1f}]:"]
+
+    for edge in edges:
+        src_table = edge["src_table"]
+        dst_table = edge["dst_table"]
+        src_cols = edge["src_cols"]
+        dst_cols = edge["dst_cols"]
+
+        src_meta = schema.tables.get(src_table)
+
+        fk_direction = "Reverse FK"
+        if src_meta:
+            for fk in src_meta.foreign_keys:
+                if (
+                    fk.dst_table == dst_table
+                    and set(fk.src_cols) == set(src_cols)
+                    and set(fk.dst_cols) == set(dst_cols)
+                ):
+                    fk_direction = "Forward FK"
+                    break
+
+        src_col_str = ",".join(src_cols)
+        dst_col_str = ",".join(dst_cols)
+        lines.append(f"  {src_table}.{src_col_str} -> {dst_table}.{dst_col_str} ({fk_direction})")
+
+    return "\n".join(lines)
+
+
+def _llm_rank_join_candidates(
+    candidates: list[dict[str, Any]], intent: RuntimeIntent, schema: SchemaGraph
+) -> list[int]:
+    """Use LLM to rank ambiguous join candidates when scores are tied.
+
+    Args:
+
+        candidates: List of scored candidate dicts (each with ``edges``, ``score``, and ``candidate_id`` keys).
+
+        intent: The ``RuntimeIntent`` for query context.
+
+        schema: The schema graph.
+
+    Returns:
+
+        List of integer indices into ``candidates`` in LLM-ranked order (best first). Falls back to the original order if the LLM call fails.
+    """
+    if len(candidates) <= 1:
+        return list(range(len(candidates)))
+
+    filter_desc = []
+    for fp in intent.filters_param or []:
+        filter_desc.append(f"{fp.left_expr.primary_column} {fp.op}")
+
+    agg_desc = []
+    for sc in intent.select_cols or []:
+        if sc.is_aggregated:
+            agg_desc.append(sc.expr.primary_term)
+
+    groupby_desc = ", ".join(g.primary_column for g in (intent.group_by_cols or []))
+
+    intent_summary = (
+        f"Tables: {intent.tables}\n"
+        f"Filters: {', '.join(filter_desc) if filter_desc else 'none'}\n"
+        f"Aggregations: {', '.join(agg_desc) if agg_desc else 'none'}\n"
+        f"Group By: {groupby_desc if groupby_desc else 'none'}\n"
+        f"Grain: {intent.grain}"
+    )
+
+    candidate_descriptions = []
+    for idx, cand in enumerate(candidates[:3]):
+        edges = cand.get("edges", [])
+        cand_id = cand.get("candidate_id", f"J{idx + 1:02d}")
+        score = cand.get("score", 0.0)
+        desc = _format_join_candidate_semantic(cand_id, edges, schema, score)
+        candidate_descriptions.append(desc)
+
+    system_prompt = (
+        "You are a SQL join path validator. Rank join paths by semantic correctness for the given query intent.\n\n"
+        "Output Requirements:\n"
+        "- Output ONLY valid JSON matching the specified output_schema.\n"
+        "- Do NOT include markdown code blocks, explanations, or commentary.\n"
+        "- Identical inputs must produce identical outputs.\n\n"
+        "Ranking Criteria:\n"
+        "1. FK direction: Forward FKs (natural flow) preferred over reverse FKs.\n"
+        "2. Filter alignment: Joins connecting directly to filtered columns score higher.\n"
+        "3. Semantic correctness: Does the join path match business intent?\n"
+        "4. Simplicity: Shorter, more intuitive paths preferred."
+    )
+
+    user_prompt = stable_json(
+        {
+            "task": "Rank SQL join path candidates by semantic correctness for the given query intent.",
+            "intent_summary": intent_summary,
+            "join_path_candidates": candidate_descriptions,
+            "output_schema": {
+                "ranked_ids": ["J01", "J02", "J03"],
+                "reasoning": "Brief explanation of ranking",
+            },
+            "instructions": "Rank the candidates from best to worst based on semantic fit for this query.",
+        }
+    )
+
+    result = llm_json(system_prompt, user_prompt, task="sql")
+    if not result or "ranked_ids" not in result:
+        debug("[sql_gen.llm_rank_join_candidates] LLM ranking failed, using original order")
+        return list(range(len(candidates)))
+
+    ranked_ids = result["ranked_ids"]
+    id_to_idx = {cand.get("candidate_id", f"J{i + 1:02d}"): i for i, cand in enumerate(candidates)}
+
+    ranked_indices = []
+    for cand_id in ranked_ids:
+        if cand_id in id_to_idx:
+            ranked_indices.append(id_to_idx[cand_id])
+
+    for i in range(len(candidates)):
+        if i not in ranked_indices:
+            ranked_indices.append(i)
+
+    debug(f"[sql_gen.llm_rank_join_candidates] LLM ranked: {ranked_ids}, reasoning: {result.get('reasoning', 'none')}")
+    return ranked_indices
+
+
+def _rank_join_candidates(
+    candidates: list[list[dict[str, Any]]], intent: RuntimeIntent, schema: SchemaGraph
+) -> list[list[dict[str, Any]]]:
+    """Rank join candidates deterministically by score with optional LLM tie-breaking.
+
+    Sorts candidates by ``score_join_path`` score descending. When the top two candidates are within 5 points of each other, invokes ``llm_rank_join_candidates`` on the top three for LLM tie-breaking.
+
+    Args:
+
+        candidates: List of join paths (each a list of edge dicts).
+
+        intent: The ``RuntimeIntent`` for scoring context.
+
+        schema: The schema graph.
+
+    Returns:
+
+        List of join paths sorted from most to least preferred.
+    """
+    if len(candidates) <= 1:
+        return candidates
+
+    scored = []
+    for edges in candidates:
+        score = _score_join_path(edges, intent, schema)
+        scored.append({"edges": edges, "score": score})
+
+    scored.sort(key=lambda x: x["score"], reverse=True)
+
+    if len(scored) >= 2:
+        top_score = scored[0]["score"]
+        second_score = scored[1]["score"]
+
+        if abs(top_score - second_score) <= 5.0:
+            debug(
+                f"[sql_gen.rank_join_candidates] top scores within threshold: {top_score:.1f} vs {second_score:.1f}, invoking LLM"
+            )
+
+            for idx, item in enumerate(scored[:3]):
+                item["candidate_id"] = f"J{idx + 1:02d}"
+
+            llm_ranking = _llm_rank_join_candidates(scored[:3], intent, schema)
+
+            reordered = [scored[i] for i in llm_ranking if i < len(scored)]
+            remaining = [scored[i] for i in range(len(scored)) if i not in llm_ranking[: len(reordered)]]
+            scored = reordered + remaining
+
+    ranked = [item["edges"] for item in scored]
+
+    top_score = scored[0]["score"] if scored else 0.0
+    debug(f"[sql_gen.rank_join_candidates] ranked {len(ranked)} candidates, top_score={top_score:.1f}")
+
+    return ranked
+
+
+def physical_tables_for_join_hints(
+    tables: list[str] | None,
+    schema: SchemaGraph,
+) -> list[str]:
+    """Return physical table names from ``tables`` that exist in ``schema``.
+
+    Preserves first-seen order and drops CTE aliases or unknown names so
+    join-path lookup only uses keys present in ``schema.tables``.
+
+    Args:
+
+        tables: Declared table list, possibly mixing CTE names and bases.
+
+        schema: Loaded schema graph.
+
+    Returns:
+
+        Deduped list of canonical table keys from ``schema.tables``.
+    """
+    if not tables:
+        return []
+    by_lower: dict[str, str] = {k.lower(): k for k in schema.tables}
+    out: list[str] = []
+    seen: set[str] = set()
+    for raw in tables:
+        key = by_lower.get(raw.lower()) if raw else None
+        if key is None or key in seen:
+            continue
+        out.append(key)
+        seen.add(key)
+    return out
+
+
+def join_hints_multi(schema: SchemaGraph, tables: list[str], intent: RuntimeIntent | None = None) -> dict[str, Any]:
+    """Generate join hint candidates for SQL generation with deterministic ranking.
+
+    Args:
+
+        schema: The schema graph.
+
+        tables: List of table names to join.
+
+        intent: Optional ``RuntimeIntent`` used for score-based ranking.
+
+    Returns:
+
+        Dict with a ``"candidates"`` list, each entry containing ``candidate_id``, ``join_path_signature``, and ``edge_count``.
+    """
+    candidates = _candidate_join_paths_for_tables(schema, tables)
+    debug(f"[sql_gen.join_hints_multi] tables={tables}, raw_candidates={len(candidates)}")
+
+    if len(tables) <= 1:
+        debug("[sql_gen.join_hints_multi] single table, returning J00")
+        return {
+            "candidates": [
+                {
+                    "candidate_id": "J00",
+                    "join_path_signature": [],
+                    "edge_count": 0,
+                }
+            ]
+        }
+
+    if intent:
+        debug(f"[sql_gen.join_hints_multi] ranking {len(candidates)} candidates with intent context")
+        ranked_candidates = _rank_join_candidates(candidates, intent, schema)
+    else:
+        debug("[sql_gen.join_hints_multi] no intent provided, using original order")
+        ranked_candidates = candidates
+
+    out = []
+    for idx, edges in enumerate(ranked_candidates):
+        out.append(
+            {
+                "candidate_id": f"J{idx + 1:02d}",
+                "join_path_signature": _join_path_signature_for_path(edges),
+                "edge_count": len(edges),
+            }
+        )
+    debug(f"[sql_gen.join_hints_multi] generated {len(out)} candidates")
+    return {"candidates": out}
+
+
+def _format_sql_arg(k: str, v: Any) -> str:
+    """Format a scalar function argument for SQL expression guide.
+
+    Args:
+
+        k: Parameter key (used as ``:k`` placeholder); empty string means use literal.
+
+        v: Argument value used when ``k`` is empty.
+
+    Returns:
+
+        Parameter placeholder string (for example, ``:key``) or a quoted or numeric literal.
+    """
+    if k:
+        return f":{k}"
+    if isinstance(v, str):
+        return f"'{v}'"
+    return str(v)
+
+
+def _render_group_sql(g: MulGroup) -> str:
+    """Render a MulGroup as a SQL fragment for expression guide.
+
+    Args:
+
+        g: The ``MulGroup`` containing multiply or divide columns, aggregation function, coefficient, and optional scalar or inner-scalar function wrappers.
+
+    Returns:
+
+        SQL fragment string representing the group, for example ``"ROUND(SUM(:coeff * table.col), 2)"``.
+    """
+    if not g.multiply:
+        return "1"
+    base = " * ".join(g.multiply)
+    if g.divide:
+        base = f"({base}) / ({' * '.join(g.divide)})"
+    if g.coeff_param_key:
+        base = f":{g.coeff_param_key} * {base}"
+    elif g.coefficient != 1.0:
+        base = f"{g.coefficient} * {base}"
+    if g.inner_scalar_func:
+        iargs = [
+            _format_sql_arg(k, v)
+            for k, v in zip(g.isarg_param_keys or [], g.inner_scalar_func_args or [], strict=False)
+        ]
+        iargs += [_format_sql_arg("", v) for v in (g.inner_scalar_func_args or [])[len(g.isarg_param_keys or []) :]]
+        args_str = ", ".join(iargs)
+        if g.inner_scalar_func.lower() in SCALAR_FUNCTIONS_LEADING_ARG and args_str:
+            inner = f"{g.inner_scalar_func.upper()}({args_str}, {base})"
+        else:
+            inner = f"{g.inner_scalar_func.upper()}({base}{', ' + args_str if args_str else ''})"
+    else:
+        inner = base
+    if g.agg_func:
+        mid = f"{g.agg_func.upper()}({inner})"
+    else:
+        mid = inner
+    if g.scalar_func:
+        sargs = [_format_sql_arg(k, v) for k, v in zip(g.sarg_param_keys or [], g.scalar_func_args or [], strict=False)]
+        sargs += [_format_sql_arg("", v) for v in (g.scalar_func_args or [])[len(g.sarg_param_keys or []) :]]
+        args_str = ", ".join(sargs)
+        if g.scalar_func.lower() == "extract" and args_str:
+            return f"EXTRACT({args_str} FROM {mid})"
+        if g.scalar_func.lower() in SCALAR_FUNCTIONS_LEADING_ARG and args_str:
+            return f"{g.scalar_func.upper()}({args_str}, {mid})"
+        return f"{g.scalar_func.upper()}({mid}{', ' + args_str if args_str else ''})"
+    return mid
+
+
+def _render_expr_sql(expr: NormalizedExpr) -> str:
+    """Render a NormalizedExpr as a SQL fragment for expression guide.
+
+    Args:
+
+        expr: The ``NormalizedExpr`` to render, potentially containing multiple additive or subtractive groups and optional outer scalar wrapping.
+
+    Returns:
+
+        SQL fragment string that the LLM should produce for this expression.
+    """
+    parts: list[str] = []
+    for g in expr.add_groups:
+        parts.append(_render_group_sql(g))
+    for v in expr.add_values:
+        parts.append(f":{v.param_key}" if v.param_key else str(v.value))
+    sub_parts: list[str] = []
+    for g in expr.sub_groups:
+        sub_parts.append(_render_group_sql(g))
+    for v in expr.sub_values:
+        sub_parts.append(f":{v.param_key}" if v.param_key else str(v.value))
+    result = " + ".join(parts) if parts else "0"
+    if sub_parts:
+        result = f"{result} - {' - '.join(sub_parts)}"
+    if expr.inner_scalar_func and not any(g.inner_scalar_func for g in expr.add_groups):
+        iargs = [
+            _format_sql_arg(k, v)
+            for k, v in zip(
+                expr.isarg_param_keys or [],
+                expr.inner_scalar_func_args or [],
+                strict=False,
+            )
+        ]
+        iargs += [
+            _format_sql_arg("", v) for v in (expr.inner_scalar_func_args or [])[len(expr.isarg_param_keys or []) :]
+        ]
+        args_str = ", ".join(iargs)
+        if expr.inner_scalar_func.lower() in SCALAR_FUNCTIONS_LEADING_ARG and args_str:
+            result = f"{expr.inner_scalar_func.upper()}({args_str}, {result})"
+        else:
+            result = f"{expr.inner_scalar_func.upper()}({result}{', ' + args_str if args_str else ''})"
+    if expr.agg_func and not any(g.agg_func for g in expr.add_groups):
+        result = f"{expr.agg_func.upper()}({result})"
+    if expr.scalar_func and not any(g.scalar_func for g in expr.add_groups):
+        sargs = [
+            _format_sql_arg(k, v) for k, v in zip(expr.sarg_param_keys or [], expr.scalar_func_args or [], strict=False)
+        ]
+        sargs += [_format_sql_arg("", v) for v in (expr.scalar_func_args or [])[len(expr.sarg_param_keys or []) :]]
+        args_str = ", ".join(sargs)
+        if expr.scalar_func.lower() == "extract" and args_str:
+            result = f"EXTRACT({args_str} FROM {result})"
+        elif expr.scalar_func.lower() in SCALAR_FUNCTIONS_LEADING_ARG and args_str:
+            result = f"{expr.scalar_func.upper()}({args_str}, {result})"
+        else:
+            result = f"{expr.scalar_func.upper()}({result}{', ' + args_str if args_str else ''})"
+    return result
+
+
+def build_deterministic_sql(
+    intent: RuntimeIntent,
+    cte_join_hints: dict[str, dict[str, Any]] | None = None,
+) -> str:
+    """Build a rough deterministic SQL from a RuntimeIntent.
+
+    The output is structurally correct but may lack JOIN clauses and dialect-specific syntax. It serves as a constrained template for the SQL LLM and as a reference for post-generation validation.
+
+    Each SELECT expression is rendered via ``_render_expr_sql``. CTE steps are emitted as ``WITH`` clauses with deterministic output column aliases. A ``-- <JOIN>`` placeholder marks where the LLM should insert the chosen join predicates.
+    """
+    parts: list[str] = []
+
+    cte_steps = intent.cte_steps or []
+    if cte_steps:
+        cte_clauses: list[str] = []
+        for cte in cte_steps:
+            cte_sql = _build_deterministic_select_block(
+                cte.select_cols or [],
+                cte.tables or [],
+                cte.group_by_cols or [],
+                cte.order_by_cols or [],
+                cte.filters_param or [],
+                cte.having_param or [],
+                cte.limit,
+                cte.grain or "row_level",
+                cte.output_columns or [],
+            )
+            cte_clauses.append(f"{cte.cte_name} AS (\n{cte_sql}\n)")
+        parts.append("WITH " + ",\n".join(cte_clauses))
+
+    main_sql = _build_deterministic_select_block(
+        intent.select_cols or [],
+        intent.tables or [],
+        intent.group_by_cols or [],
+        intent.order_by_cols or [],
+        intent.filters_param or [],
+        intent.having_param or [],
+        intent.limit,
+        intent.grain or "row_level",
+    )
+    parts.append(main_sql)
+
+    return "\n".join(parts)
+
+
+def _join_clause_parts_with_bool_op(
+    parts: list[tuple[str, str]],
+) -> str:
+    """Chain SQL clause fragments using their positional boolean operators.
+
+    Each element's ``bool_op`` is the connector between that element and
+    the next.  The last element's ``bool_op`` is unused.  Fragments are
+    joined sequentially to preserve the canonical ordering established
+    by ``_canonicalize_condition_order``.
+
+    When any ``OR`` connector is present the entire expression is wrapped
+    in parentheses to maintain correct SQL precedence in outer contexts.
+
+    Args:
+        parts: List of ``(sql_fragment, bool_op)`` tuples where
+            ``bool_op`` is ``"AND"`` or ``"OR"``.
+
+    Returns:
+        Combined SQL predicate string.
+    """
+    if not parts:
+        return ""
+
+    result = parts[0][0]
+    for i in range(1, len(parts)):
+        connector = parts[i - 1][1]
+        result = f"{result} {connector} {parts[i][0]}"
+
+    has_or = any(op == "OR" for _, op in parts[:-1])
+    if has_or and len(parts) > 1:
+        result = f"({result})"
+
+    return result
+
+
+def _build_deterministic_select_block(
+    select_cols: list[SelectCol],
+    tables: list[str],
+    group_by_cols: list[NormalizedExpr],
+    order_by_cols: list,
+    filters_param: list,
+    having_param: list,
+    limit: int | None,
+    grain: str,
+    output_aliases: list[str] | None = None,
+) -> str:
+    """Build a single SELECT block from structured intent clauses.
+
+    Renders SELECT, FROM (with ``-- <JOIN>`` placeholder), WHERE, GROUP BY, HAVING, ORDER BY, and LIMIT clauses.
+    """
+    lines: list[str] = []
+
+    select_exprs: list[str] = []
+    for idx, sc in enumerate(select_cols):
+        rendered = _render_expr_sql(sc.expr)
+        if output_aliases and idx < len(output_aliases):
+            rendered = f"{rendered} AS {output_aliases[idx]}"
+        select_exprs.append(rendered)
+
+    lines.append("SELECT " + ", ".join(select_exprs))
+
+    if tables:
+        lines.append(f"FROM {tables[0]}")
+        if len(tables) > 1:
+            lines.append("-- <JOIN: integrate from join candidates>")
+
+    where_parts: list[tuple[str, str]] = []
+    dialect_type = EngineConfig.TYPE or "postgresql"
+    for fp in filters_param:
+        left = _render_expr_sql(fp.left_expr)
+        op = fp.op or "="
+        case_insensitive = fp.value_type == "string" and op.lower() not in (
+            "is null", "is not null", "ilike", "not ilike",
+        )
+        if case_insensitive:
+            left = _wrap_for_case_insensitive(left, dialect_type)
+        bool_op = getattr(fp, "bool_op", "AND") or "AND"
+        if op.lower() in ("is null", "is not null"):
+            where_parts.append((f"{left} {op.upper()}", bool_op))
+        elif fp.value_type == "date_window" and isinstance(fp.raw_value, dict):
+            for dw_frag in _render_date_window_where(fp, left, dialect_type):
+                where_parts.append((dw_frag, "AND"))
+        elif fp.value_type == "date_diff" and isinstance(fp.raw_value, dict):
+            rv = fp.raw_value
+            unit = rv.get("unit", "day")
+            amount = int(rv.get("amount", 0)) if rv.get("amount") is not None else 0
+            op = fp.op or ">"
+            frag = render_date_diff_expr(dialect_type, left, op, unit, amount)
+            where_parts.append((frag, "AND"))
+        elif fp.right_expr:
+            right = _render_expr_sql(fp.right_expr)
+            if case_insensitive:
+                right = _wrap_for_case_insensitive(right, dialect_type)
+            where_parts.append((f"{left} {op} {right}", bool_op))
+        elif fp.param_key:
+            val_needs_lower = case_insensitive and op.lower() in ("like", "not like")
+            val_ref = f"LOWER(:{fp.param_key})" if val_needs_lower else f":{fp.param_key}"
+            where_parts.append((f"{left} {op} {val_ref}", bool_op))
+        elif fp.raw_value is not None:
+            pkey = fp.param_key or "p?"
+            val_needs_lower = case_insensitive and op.lower() in ("like", "not like")
+            val_ref = f"LOWER(:{pkey})" if val_needs_lower else f":{pkey}"
+            where_parts.append((f"{left} {op} {val_ref}", bool_op))
+    if where_parts:
+        lines.append("WHERE " + _join_clause_parts_with_bool_op(where_parts))
+
+    if group_by_cols:
+        gb_exprs = [_render_expr_sql(g) for g in group_by_cols]
+        lines.append("GROUP BY " + ", ".join(gb_exprs))
+
+    having_parts: list[tuple[str, str]] = []
+    for hp in having_param:
+        left = _render_expr_sql(hp.left_expr)
+        op = hp.op or ">"
+        bool_op = getattr(hp, "bool_op", "AND") or "AND"
+        if hp.right_expr:
+            right = _render_expr_sql(hp.right_expr)
+            having_parts.append((f"{left} {op} {right}", bool_op))
+        elif hp.param_key:
+            having_parts.append((f"{left} {op} :{hp.param_key}", bool_op))
+        else:
+            having_parts.append((f"{left} {op} ?", bool_op))
+    if having_parts:
+        lines.append("HAVING " + _join_clause_parts_with_bool_op(having_parts))
+
+    if order_by_cols:
+        ob_exprs = []
+        for obc in order_by_cols:
+            rendered = _render_expr_sql(obc.expr)
+            direction = obc.direction.upper() if obc.direction else "ASC"
+            ob_exprs.append(f"{rendered} {direction}")
+        lines.append("ORDER BY " + ", ".join(ob_exprs))
+
+    if limit:
+        lines.append(f"LIMIT {limit}")
+
+    return "\n".join(lines)
+
+
+def _generate_col_alias(sc: SelectCol) -> str:
+    """Build a deterministic display alias from a SelectCol's expression metadata.
+
+    Rules:
+        * Plain column ``table.col`` → ``col``.
+        * Aggregate ``COUNT(table.col)`` → ``count_col``.
+        * Distinct aggregate ``COUNT(DISTINCT table.col)`` → ``count_distinct_col``.
+        * Scalar wrapper ``ROUND(SUM(table.col), 2)`` → ``round_sum_col``.
+        * Arithmetic ``table.a * table.b`` → ``a_times_b``.
+        * Fallback: ``col_<idx>`` assigned by the caller.
+
+    Args:
+        sc: The ``SelectCol`` to derive an alias for.
+
+    Returns:
+        A lowercase alias string safe for SQL ``AS`` usage.
+    """
+    expr = sc.expr
+    col = expr.primary_column
+    if col:
+        col_clean = col.rsplit(".", 1)[-1].lower()
+    else:
+        col_clean = ""
+
+    groups = expr.add_groups or []
+    if len(groups) >= 2 and not expr.agg_func and not expr.scalar_func:
+        parts = [g.multiply[0].rsplit(".", 1)[-1].lower() if g.multiply else "x" for g in groups]
+        alias = "_times_".join(parts)
+    elif expr.sub_groups and groups:
+        plus_part = groups[0].multiply[0].rsplit(".", 1)[-1].lower() if groups[0].multiply else "x"
+        minus_part = (
+            expr.sub_groups[0].multiply[0].rsplit(".", 1)[-1].lower()
+            if expr.sub_groups[0].multiply
+            else "y"
+        )
+        alias = f"{plus_part}_minus_{minus_part}"
+    elif col_clean:
+        alias = col_clean
+    else:
+        return ""
+
+    distinct_prefix = ""
+    if groups and groups[0].multiply:
+        term = groups[0].multiply[0].upper()
+        if "DISTINCT " in term:
+            distinct_prefix = "distinct_"
+
+    if expr.agg_func:
+        alias = f"{expr.agg_func}_{distinct_prefix}{alias}"
+    if expr.inner_scalar_func:
+        alias = f"{expr.inner_scalar_func}_{alias}"
+    if expr.scalar_func:
+        alias = f"{expr.scalar_func}_{alias}"
+
+    return alias.lower()
+
+
+def deterministic_alias_sql(sql_param: str, intent: RuntimeIntent) -> str:
+    """Add deterministic display aliases to each SELECT expression.
+
+    Parses the ``SELECT ... FROM`` portion of the parameterized SQL,
+    matches each comma-separated expression positionally with the
+    intent's ``select_cols``, and appends an ``AS alias`` clause derived
+    from column metadata.
+
+    Args:
+        sql_param: Parameterized SQL string produced by ``build_deterministic_sql``.
+        intent: The ``RuntimeIntent`` whose ``select_cols`` drive aliasing.
+
+    Returns:
+        SQL string with ``AS`` aliases on every SELECT expression.  Returns
+        the original SQL unchanged when the SELECT clause cannot be parsed
+        or the column count does not match.
+    """
+    import re
+
+    match = re.search(r"(?i)\bSELECT\s+", sql_param)
+    if not match:
+        return sql_param
+
+    select_start = match.end()
+    from_match = re.search(r"(?i)\bFROM\b", sql_param[select_start:])
+    if not from_match:
+        return sql_param
+
+    select_body = sql_param[select_start : select_start + from_match.start()].strip()
+    rest = sql_param[select_start + from_match.start() :]
+
+    depth = 0
+    parts: list[str] = []
+    current: list[str] = []
+    for ch in select_body:
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append("".join(current).strip())
+            current = []
+        else:
+            current.append(ch)
+    if current:
+        parts.append("".join(current).strip())
+
+    cols = intent.select_cols or []
+    if len(parts) != len(cols):
+        return sql_param
+
+    aliased: list[str] = []
+    seen_aliases: set[str] = set()
+    for idx, (expr_str, sc) in enumerate(zip(parts, cols, strict=False)):
+        alias = _generate_col_alias(sc)
+        if not alias:
+            alias = f"col_{idx + 1}"
+        base = alias
+        counter = 2
+        while alias in seen_aliases:
+            alias = f"{base}_{counter}"
+            counter += 1
+        seen_aliases.add(alias)
+        aliased.append(f"{expr_str} AS {alias}")
+
+    prefix = sql_param[: match.start()] + match.group()
+    return prefix + ", ".join(aliased) + " " + rest
+
+
+def _render_date_window_where(
+    fp: FilterParam, left_rendered: str, dialect_type: str
+) -> list[str]:
+    """Render WHERE clause part(s) for a date_window filter.
+
+    For raw_value with start/end keys emits two predicates (>= start AND <= end).
+    For unit/offset uses render_date_window_expr. Returns a list of one or two
+    fragments to AND together.
+    """
+    rv = fp.raw_value if isinstance(fp.raw_value, dict) else {}
+    if "start" in rv and "end" in rv:
+        start_val = rv["start"]
+        end_val = rv["end"]
+        if isinstance(start_val, str) and isinstance(end_val, str):
+            return [
+                f"{left_rendered} >= '{start_val}'",
+                f"{left_rendered} <= '{end_val}'",
+            ]
+    unit = rv.get("unit", "day")
+    offset = int(rv.get("offset", 0)) if rv.get("offset") is not None else 0
+    op = fp.op or ">="
+    return [render_date_window_expr(dialect_type, left_rendered, op, unit, offset)]
+
+
+def build_join_choice_prompt(
+    q_norm: str,
+    deterministic_sql: str,
+    join_candidates: dict[str, Any],
+    cte_join_hints: dict[str, dict[str, Any]] | None = None,
+) -> tuple[str, str]:
+    """Build minimal prompt for LLM to return only join candidate IDs.
+
+    Returns (system_prompt, user_prompt). Response must be JSON with
+    chosen_join_candidate_id and optionally chosen_cte_join_candidate_ids.
+    """
+    system = (
+        "You are a join selector for text-to-SQL. Output ONLY valid JSON. "
+        "Return chosen_join_candidate_id and, if the query has CTEs that need joins, "
+        "chosen_cte_join_candidate_ids mapping each CTE name to its candidate_id."
+    )
+    candidates = join_candidates.get("candidates", [])
+    cte_names = list(cte_join_hints.keys()) if cte_join_hints else []
+    cte_payload = None
+    if cte_names and cte_join_hints:
+        cte_payload = {}
+        for cte, h in cte_join_hints.items():
+            cands = h.get("candidates", []) or []
+            cte_payload[cte] = [
+                {"candidate_id": c.get("candidate_id"), "join_path_signature": c.get("join_path_signature")}
+                for c in cands
+            ]
+    user = stable_json(
+        {
+            "task": (
+                "Given the question and the deterministic SQL template, choose the join candidate "
+                "that correctly connects the tables. Return only the IDs; do not modify the SQL."
+            ),
+            "question": q_norm,
+            "deterministic_sql": deterministic_sql,
+            "join_candidates": [
+                {"candidate_id": c.get("candidate_id"), "join_path_signature": c.get("join_path_signature")}
+                for c in candidates
+            ],
+            "cte_join_candidates": cte_payload,
+            "output_format": {
+                "chosen_join_candidate_id": "J00 or J01, J02, ...",
+                "chosen_cte_join_candidate_ids": "Optional dict: cte_name -> candidate_id",
+            },
+        }
+    )
+    return system, user
+
+
+def get_join_choice_from_llm(
+    q_norm: str,
+    deterministic_sql: str,
+    join_candidates: dict[str, Any],
+    cte_join_hints: dict[str, dict[str, Any]] | None,
+) -> tuple[str, dict[str, str]]:
+    """Call LLM to get only chosen join candidate ID and per-CTE IDs.
+
+    Returns (chosen_join_candidate_id, chosen_cte_join_candidate_ids).
+    Defaults to J00 and empty dict on parse failure.
+    """
+    system, user = build_join_choice_prompt(
+        q_norm, deterministic_sql, join_candidates, cte_join_hints
+    )
+    parsed = llm_json(system, user, retries=1, task="sql")
+    if not isinstance(parsed, dict):
+        return "J00", {}
+    chosen = parsed.get("chosen_join_candidate_id")
+    if not isinstance(chosen, str):
+        chosen = "J00"
+    cte_ids = parsed.get("chosen_cte_join_candidate_ids")
+    if not isinstance(cte_ids, dict):
+        cte_ids = {}
+    return chosen, {k: v for k, v in cte_ids.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def build_repair_prompt(
+    schema: SchemaGraph,
+    q_norm: str,
+    prev_sql: str,
+    db_error: str,
+    nl_error: str,
+    join_hints: dict[str, Any],
+    cte_join_hints: dict[str, dict[str, Any]] | None = None,
+) -> tuple[str, str]:
+    """Build system and user prompts for SQL repair.
+
+    Args:
+
+        schema: The schema graph.
+
+        q_norm: The normalised user question string.
+
+        prev_sql: The previously generated SQL that failed.
+
+        db_error: The raw database error message.
+
+        nl_error: The human-readable explanation of the error.
+
+        join_hints: Join hint candidates from ``join_hints_multi``.
+
+        cte_join_hints: Optional dict mapping CTE name to join hints for CTE steps.
+
+    Returns:
+
+        Tuple of ``(system_prompt, user_prompt)`` strings ready for the LLM.
+    """
+    dialect_type = EngineConfig.TYPE
+    if dialect_type == "databricks":
+        dialect_name = "Spark"
+    elif dialect_type == "postgresql":
+        dialect_name = "PostgreSQL"
+    else:
+        dialect_name = "SQL"
+
+    hard_constraints = [
+        f"Dialect: {dialect_name}. Use {dialect_name} syntax ONLY.",
+        "Output ONLY valid JSON. No markdown. No explanations.",
+        "SYNTAX-ONLY REPAIR: fix syntax errors, column qualification, keyword casing, operator typos, parameter placeholder format.",
+        "Do NOT add, remove, or reorder tables in FROM/JOIN clauses.",
+        "Do NOT change SELECT columns, aggregation functions, or expressions.",
+        "Do NOT alter GROUP BY, ORDER BY, or HAVING structure.",
+        "Do NOT change join conditions, join types, or join order.",
+        "Do NOT add or remove WHERE/HAVING predicates.",
+        "ALWAYS qualify column names with table name (for example, <table_1>.<column_1>).",
+        "Do not alias SELECT expressions. No AS clauses on SELECT columns or aggregates.",
+        "HAVING clause: Use full aggregation expression, NOT an alias.",
+        "Use :p1, :p2 parameter placeholders for filter/having values, NOT literal values.",
+        "WHERE/HAVING predicates: column reference on LEFT side of comparison.",
+        "ORDER BY must include explicit ASC or DESC direction.",
+        "chosen_join_candidate_id must match the SAME candidate as the original SQL.",
+    ]
+
+    if cte_join_hints:
+        cte_names = list(cte_join_hints.keys())
+        hard_constraints.append(
+            f"CTE join predicates MUST exactly match chosen CTE join candidate for: {', '.join(cte_names)}"
+        )
+        hard_constraints.append(
+            "chosen_cte_join_candidate_ids must specify join candidate for each CTE with multi-table joins."
+        )
+
+    output_format: dict[str, Any] = {"sql": "...", "chosen_join_candidate_id": "J01"}
+    if cte_join_hints:
+        output_format["chosen_cte_join_candidate_ids"] = {"cte_name": "J01"}
+
+    prompt_data: dict[str, Any] = {
+        "task": "Fix ONLY syntax errors in the SQL query. Do not change query structure, tables, joins, or logic.",
+        "error_info": {
+            "db_error": db_error,
+            "explanation": nl_error,
+        },
+        "hard_constraints": hard_constraints,
+        "output_schema": output_format,
+        "schema": schema.schema_literal_text,
+        "join_candidates": join_hints,
+        "question": q_norm,
+        "previous_sql": prev_sql,
+        "db_error": db_error,
+        "error_explanation": nl_error,
+    }
+
+    if cte_join_hints:
+        prompt_data["cte_join_candidates"] = cte_join_hints
+
+    return (SQL_REPAIR_SYSTEM_PROMPT, stable_json(prompt_data))