aetherdialect 0.1.0__py3-none-any.whl

text2sql/expansion_ops.py

@@ -0,0 +1,1218 @@
+"""Fully deterministic expansion operators for synthetic intent generation.
+
+Implements A-series (attribute: filters, aggregations, GROUP BY, ORDER BY,
+HAVING), B-series (join: dimension, fact, swap, remove, bridge), C-series
+(gold inclusion), T-series (temporal: EXTRACT, DATE_TRUNC, date_window,
+date_diff), N-series (numeric: ROUND, ABS), and structural operators
+(DISTINCT, LIMIT, OR-groups, expression composition).
+
+All operators are purely deterministic — no LLM calls.  The top-level
+``expand_gold_intents`` function orchestrates multi-depth expansion with
+SHA-256 dedup across all gold intents.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import replace
+from typing import Any
+
+from .config import (
+    VALID_AGGREGATION_FUNCTIONS,
+    VALID_FILTER_OPS,
+    VALID_HAVING_OPS,
+    SimulatorConfig,
+)
+from .contracts_base import (
+    ColumnRole,
+    ExpansionMetadata,
+    SchemaGraph,
+    SchemaLimits,
+    TableRole,
+)
+from .contracts_core import (
+    FilterParam,
+    HavingParam,
+    MulGroup,
+    NormalizedExpr,
+    OrderByCol,
+    SelectCol,
+    SimulatorIntent,
+)
+from .core_utils import debug, log
+from .intent_resolve import enforce_schema
+from .utils import intent_key
+
+
+# ---------------------------------------------------------------------------
+# Schema helpers
+# ---------------------------------------------------------------------------
+
+def _get_table_role(schema: SchemaGraph, table: str) -> str | None:
+    """Return table role string from schema."""
+    tm = schema.tables.get(table)
+    return tm.role if tm else None
+
+
+def _table_from_column_ref(col_ref: str) -> str:
+    """Extract table name from ``table.column`` reference."""
+    if not col_ref or "." not in col_ref:
+        return ""
+    return col_ref.split(".", 1)[0]
+
+
+def _build_column_metadata(
+    schema: SchemaGraph,
+) -> dict[str, dict[str, dict[str, Any]]]:
+    """Build nested ``table -> column -> metadata`` dict from schema."""
+    result: dict[str, dict[str, dict[str, Any]]] = {}
+    for table_name, table_obj in schema.tables.items():
+        result[table_name] = {}
+        for col_name, col in table_obj.columns.items():
+            result[table_name][col_name] = {
+                "data_type": col.data_type,
+                "role": col.role,
+                "nullable": col.null_ratio > 0.0,
+                "cardinality": getattr(col, "cardinality", None),
+            }
+    return result
+
+
+def _build_fk_map(schema: SchemaGraph) -> dict[str, list[dict[str, str]]]:
+    """Build FK adjacency map: ``source_table -> [{source_column, target_table, target_column}]``."""
+    fk_map: dict[str, list[dict[str, str]]] = {}
+    for fk in schema.fk_edges:
+        source = fk.src_table
+        if source not in fk_map:
+            fk_map[source] = []
+        fk_map[source].append({
+            "source_column": fk.src_cols[0] if fk.src_cols else "",
+            "target_table": fk.dst_table,
+            "target_column": fk.dst_cols[0] if fk.dst_cols else "",
+        })
+    return fk_map
+
+
+def _tables_are_connected(
+    tables: list[str],
+    fk_map: dict[str, list[dict[str, str]]],
+) -> bool:
+    """Return True when all *tables* form a connected component via FKs."""
+    if len(tables) <= 1:
+        return True
+    adjacency: dict[str, set[str]] = {t: set() for t in tables}
+    for source, fks in fk_map.items():
+        if source not in adjacency:
+            continue
+        for fk in fks:
+            target = fk.get("target_table", "")
+            if target in adjacency:
+                adjacency[source].add(target)
+                adjacency[target].add(source)
+    visited: set[str] = set()
+    stack = [tables[0]]
+    while stack:
+        current = stack.pop()
+        if current in visited:
+            continue
+        visited.add(current)
+        for neighbor in adjacency.get(current, []):
+            if neighbor not in visited:
+                stack.append(neighbor)
+    return len(visited) == len(tables)
+
+
+def _get_filterable_columns(
+    schema: SchemaGraph, table_name: str,
+) -> list[str]:
+    """Return ``table.column`` refs suitable for filtering (CATEGORICAL, TEMPORAL, IDENTIFIER)."""
+    if table_name not in schema.tables:
+        return []
+    table = schema.tables[table_name]
+    return [
+        f"{table_name}.{c}"
+        for c, col in table.columns.items()
+        if col.role in (
+            ColumnRole.CATEGORICAL.value,
+            ColumnRole.TEMPORAL.value,
+            ColumnRole.IDENTIFIER.value,
+        )
+    ]
+
+
+def _get_groupable_columns(
+    schema: SchemaGraph, table_name: str,
+) -> list[str]:
+    """Return ``table.column`` refs suitable for GROUP BY."""
+    if table_name not in schema.tables:
+        return []
+    table = schema.tables[table_name]
+    return [
+        f"{table_name}.{c}"
+        for c, col in table.columns.items()
+        if col.role in (
+            ColumnRole.CATEGORICAL.value,
+            ColumnRole.TEMPORAL.value,
+        )
+    ]
+
+
+def _get_temporal_columns(
+    schema: SchemaGraph, table_name: str,
+) -> list[str]:
+    """Return ``table.column`` refs for TEMPORAL columns."""
+    if table_name not in schema.tables:
+        return []
+    table = schema.tables[table_name]
+    return [
+        f"{table_name}.{c}"
+        for c, col in table.columns.items()
+        if col.role == ColumnRole.TEMPORAL.value
+    ]
+
+
+def _get_numeric_measure_columns(
+    schema: SchemaGraph, table_name: str,
+) -> list[str]:
+    """Return ``table.column`` refs for NUMERIC_MEASURE columns."""
+    if table_name not in schema.tables:
+        return []
+    table = schema.tables[table_name]
+    return [
+        f"{table_name}.{c}"
+        for c, col in table.columns.items()
+        if col.role == ColumnRole.NUMERIC_MEASURE.value
+    ]
+
+
+def _get_dimension_tables(schema: SchemaGraph) -> list[str]:
+    """Return all dimension table names."""
+    return [
+        t for t, info in schema.tables.items()
+        if info.role == TableRole.DIMENSION.value
+    ]
+
+
+def _add_expansion_metadata(
+    intent: SimulatorIntent, operator: str,
+) -> None:
+    """Stamp *intent* in-place with expansion metadata for *operator*."""
+    if intent.expansion_metadata is None:
+        intent.expansion_metadata = ExpansionMetadata(
+            parent_intent_id="",
+            operator=operator,
+            depth=1,
+            expansion_path=[operator],
+        )
+    else:
+        intent.expansion_metadata = ExpansionMetadata(
+            parent_intent_id=(
+                intent.expansion_metadata.parent_intent_id
+                or intent.intent_id
+            ),
+            operator=operator,
+            depth=(intent.expansion_metadata.depth or 0) + 1,
+            expansion_path=(
+                (intent.expansion_metadata.expansion_path or [])
+                + [operator]
+            ),
+        )
+
+
+def _compatible_data_types(type_a: str, type_b: str) -> bool:
+    """Return True when *type_a* and *type_b* belong to the same broad category."""
+    numeric = {
+        "integer", "decimal", "float", "numeric",
+        "double", "bigint", "smallint", "real",
+    }
+    text = {"character varying", "varchar", "text", "char", "character"}
+    temporal = {
+        "date", "timestamp", "timestamp without time zone",
+        "timestamp with time zone", "time",
+    }
+    a, b = type_a.lower(), type_b.lower()
+    if a == b:
+        return True
+    for group in (numeric, text, temporal):
+        if a in group and b in group:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# A-series operators (attribute modifications)
+# ---------------------------------------------------------------------------
+
+def _a1_add_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A1: Add one value-based filter per filterable column not yet filtered."""
+    current_filter_cols = {
+        f.left_expr.primary_column for f in (intent.filters_param or [])
+    }
+    if len(current_filter_cols) >= SimulatorConfig.MAX_FILTERS:
+        return []
+
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_filterable_columns(schema, table):
+            if col in current_filter_cols:
+                continue
+            new_intent = copy.deepcopy(intent)
+            new_filter = FilterParam(
+                left_expr=NormalizedExpr.from_column(col),
+                op="=",
+                value_type="string",
+                param_key=f"f_{col.replace('.', '_')}",
+            )
+            new_intent.filters_param = list(
+                new_intent.filters_param or []
+            ) + [new_filter]
+            _add_expansion_metadata(new_intent, "A1_add_filter")
+            results.append(new_intent)
+    return results
+
+
+def _a2_add_expr_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A2: Add column-vs-column comparison for same-type column pairs."""
+    existing = set()
+    for f in intent.filters_param or []:
+        if f.right_expr:
+            existing.add((
+                f.left_expr.primary_column,
+                f.op,
+                f.right_expr.primary_column,
+            ))
+    if len(existing) >= SimulatorConfig.MAX_EXPR_COMPARISONS:
+        return []
+
+    type_groups: dict[str, list[str]] = {}
+    for table in intent.tables or []:
+        if table not in column_metadata:
+            continue
+        for col_name, col_info in column_metadata[table].items():
+            dtype = col_info.get("data_type", "unknown")
+            full_col = f"{table}.{col_name}"
+            type_groups.setdefault(dtype, []).append(full_col)
+
+    results: list[SimulatorIntent] = []
+    for cols in type_groups.values():
+        if len(cols) < 2:
+            continue
+        for i, left in enumerate(cols):
+            for right in cols[i + 1:]:
+                for op in ["=", ">", "<"]:
+                    if (left, op, right) in existing:
+                        continue
+                    new_intent = copy.deepcopy(intent)
+                    new_filter = FilterParam(
+                        left_expr=NormalizedExpr.from_column(left),
+                        op=op,
+                        right_expr=NormalizedExpr.from_column(right),
+                        value_type="column",
+                        param_key="",
+                    )
+                    new_intent.filters_param = list(
+                        new_intent.filters_param or []
+                    ) + [new_filter]
+                    _add_expansion_metadata(new_intent, "A2_add_expr_filter")
+                    results.append(new_intent)
+    return results
+
+
+def _swap_agg_func(expr: NormalizedExpr, new_agg: str) -> NormalizedExpr:
+    """Return *expr* with its aggregation function swapped to *new_agg*."""
+    if expr.agg_func:
+        return replace(expr, agg_func=new_agg)
+    if expr.add_groups and expr.add_groups[0].agg_func:
+        new_group = replace(expr.add_groups[0], agg_func=new_agg)
+        return replace(
+            expr, add_groups=[new_group] + list(expr.add_groups[1:])
+        )
+    return NormalizedExpr.from_agg(new_agg, expr.primary_column)
+
+
+def _a3_change_aggregation(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A3: Swap aggregation function on each aggregated select column."""
+    results: list[SimulatorIntent] = []
+    alt_aggs = ["count", "sum", "avg", "min", "max"]
+
+    for sc in intent.select_cols or []:
+        if not sc.is_aggregated:
+            continue
+        sc_col = sc.expr.primary_column
+        sc_term = sc.expr.primary_term
+        for new_agg in alt_aggs:
+            new_term = f"{new_agg}({sc_col})"
+            if new_term.lower() == sc_term.lower():
+                continue
+            new_intent = copy.deepcopy(intent)
+            for i, s in enumerate(new_intent.select_cols or []):
+                if (
+                    s.expr.primary_column == sc_col
+                    and s.expr.primary_term == sc_term
+                ):
+                    new_expr = _swap_agg_func(s.expr, new_agg)
+                    new_intent.select_cols[i] = SelectCol(expr=new_expr)
+                    break
+            _add_expansion_metadata(new_intent, "A3_change_aggregation")
+            results.append(new_intent)
+    return results
+
+
+def _a4_add_groupby(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A4: Add one GROUP BY column per groupable column not yet grouped."""
+    current_gb = {g.primary_column for g in (intent.group_by_cols or [])}
+    if len(current_gb) >= SimulatorConfig.MAX_GROUPBY:
+        return []
+
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_groupable_columns(schema, table):
+            if col in current_gb:
+                continue
+            new_intent = copy.deepcopy(intent)
+            new_intent.group_by_cols = sorted(
+                list(intent.group_by_cols or [])
+                + [NormalizedExpr.from_column(col)],
+                key=lambda g: g.signature_key,
+            )
+            if new_intent.grain == "row_level":
+                new_intent.grain = "grouped"
+            _add_expansion_metadata(new_intent, "A4_add_groupby")
+            results.append(new_intent)
+    return results
+
+
+def _a5_add_orderby(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A5: Add ORDER BY for each select/groupby column in ASC and DESC."""
+    current_ob = {o.expr.primary_column for o in (intent.order_by_cols or [])}
+    candidates = [g.primary_column for g in (intent.group_by_cols or [])]
+    for sc in intent.select_cols or []:
+        if sc.expr.primary_column not in candidates:
+            candidates.append(sc.expr.primary_column)
+
+    results: list[SimulatorIntent] = []
+    for col in candidates:
+        if col in current_ob:
+            continue
+        for direction in ["ASC", "DESC"]:
+            new_intent = copy.deepcopy(intent)
+            new_order = OrderByCol(
+                expr=NormalizedExpr.from_column(col),
+                direction=direction,
+            )
+            new_intent.order_by_cols = list(
+                new_intent.order_by_cols or []
+            ) + [new_order]
+            _add_expansion_metadata(new_intent, "A5_add_orderby")
+            results.append(new_intent)
+    return results
+
+
+def _a6_add_having_value(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A6: Add HAVING with value threshold for grouped intents."""
+    if intent.grain != "grouped" or not intent.group_by_cols:
+        return []
+    existing = {
+        (h.left_expr.primary_term, h.op)
+        for h in (intent.having_param or [])
+    }
+    results: list[SimulatorIntent] = []
+    for agg_func in ["count", "sum", "avg"]:
+        for op in [">", "<", ">=", "<="]:
+            left_agg = f"{agg_func}(*)"
+            if (left_agg, op) in existing:
+                continue
+            new_intent = copy.deepcopy(intent)
+            new_having = HavingParam(
+                left_expr=NormalizedExpr.from_agg(agg_func, "*"),
+                op=op,
+                value_type="number",
+                param_key=f"h_{agg_func}_{op.replace('<', 'lt').replace('>', 'gt').replace('=', 'e')}",
+            )
+            new_intent.having_param = list(
+                new_intent.having_param or []
+            ) + [new_having]
+            _add_expansion_metadata(new_intent, "A6_add_having_value")
+            results.append(new_intent)
+    return results
+
+
+def _a7_add_having_expr(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A7: Add HAVING agg-vs-agg comparison for grouped intents."""
+    if intent.grain != "grouped" or not intent.group_by_cols:
+        return []
+    existing = {
+        (h.left_expr.primary_term, h.op)
+        for h in (intent.having_param or [])
+    }
+    agg_cols = [
+        sc.expr.primary_column
+        for sc in (intent.select_cols or []) if sc.is_aggregated
+    ]
+    target_col = agg_cols[0] if agg_cols else "*"
+
+    agg_pairs = [("count", "avg"), ("sum", "count"), ("avg", "min")]
+    results: list[SimulatorIntent] = []
+    for left_agg, right_agg in agg_pairs:
+        left_term = f"{left_agg}({target_col})"
+        if (left_term, ">") in existing:
+            continue
+        new_intent = copy.deepcopy(intent)
+        new_having = HavingParam(
+            left_expr=NormalizedExpr.from_agg(left_agg, target_col),
+            op=">",
+            right_expr=NormalizedExpr.from_agg(right_agg, target_col),
+            value_type="expression",
+            param_key="",
+        )
+        new_intent.having_param = list(
+            new_intent.having_param or []
+        ) + [new_having]
+        _add_expansion_metadata(new_intent, "A7_add_having_expr")
+        results.append(new_intent)
+    return results
+
+
+def _a8_remove_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A8: Remove each filter one at a time."""
+    current = intent.filters_param or []
+    if not current:
+        return []
+    results: list[SimulatorIntent] = []
+    for i in range(len(current)):
+        new_intent = copy.deepcopy(intent)
+        new_intent.filters_param = current[:i] + current[i + 1:]
+        _add_expansion_metadata(new_intent, "A8_remove_filter")
+        results.append(new_intent)
+    return results
+
+
+def _a9_remove_groupby(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A9: Remove each GROUP BY column one at a time (skip if single)."""
+    current = list(intent.group_by_cols or [])
+    if len(current) <= 1:
+        return []
+    results: list[SimulatorIntent] = []
+    for gb in current:
+        new_intent = copy.deepcopy(intent)
+        new_intent.group_by_cols = [
+            g for g in current if g.primary_column != gb.primary_column
+        ]
+        _add_expansion_metadata(new_intent, "A9_remove_groupby")
+        results.append(new_intent)
+    return results
+
+
+def _a10_remove_having(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """A10: Remove each HAVING condition one at a time."""
+    current = intent.having_param or []
+    if not current:
+        return []
+    results: list[SimulatorIntent] = []
+    for i in range(len(current)):
+        new_intent = copy.deepcopy(intent)
+        new_intent.having_param = current[:i] + current[i + 1:]
+        _add_expansion_metadata(new_intent, "A10_remove_having")
+        results.append(new_intent)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# B-series operators (join modifications)
+# ---------------------------------------------------------------------------
+
+def _b1_add_dimension_join(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    fk_map: dict[str, list[dict[str, str]]],
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """B1: Add each FK-connected dimension table not already present."""
+    current = set(intent.tables or [])
+    if len(current) >= SimulatorConfig.MAX_TABLES:
+        return []
+    results: list[SimulatorIntent] = []
+    for table in list(current):
+        for fk in fk_map.get(table, []):
+            target = fk.get("target_table")
+            if not target or target in current:
+                continue
+            if (
+                _get_table_role(schema, target) or TableRole.FACT.value
+            ) != TableRole.DIMENSION.value:
+                continue
+            new_tables = list(current | {target})
+            if not _tables_are_connected(new_tables, fk_map):
+                continue
+            new_intent = copy.deepcopy(intent)
+            new_intent.tables = sorted(new_tables)
+            _add_expansion_metadata(new_intent, "B1_add_dimension_join")
+            results.append(new_intent)
+    return results
+
+
+def _b2_add_fact_join(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    fk_map: dict[str, list[dict[str, str]]],
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """B2: Add each FK-connected fact table not already present."""
+    current = set(intent.tables or [])
+    if len(current) >= SimulatorConfig.MAX_TABLES:
+        return []
+    results: list[SimulatorIntent] = []
+    seen_targets: set[str] = set()
+    for table in list(current):
+        for fk in fk_map.get(table, []):
+            target = fk.get("target_table")
+            if not target or target in current or target in seen_targets:
+                continue
+            if (
+                _get_table_role(schema, target) or TableRole.FACT.value
+            ) != TableRole.FACT.value:
+                continue
+            new_tables = list(current | {target})
+            if not _tables_are_connected(new_tables, fk_map):
+                continue
+            seen_targets.add(target)
+            new_intent = copy.deepcopy(intent)
+            new_intent.tables = sorted(new_tables)
+            _add_expansion_metadata(new_intent, "B2_add_fact_join")
+            results.append(new_intent)
+
+        for other_table, other_fks in fk_map.items():
+            if other_table in current or other_table in seen_targets:
+                continue
+            if (
+                _get_table_role(schema, other_table) or TableRole.FACT.value
+            ) != TableRole.FACT.value:
+                continue
+            for ofk in other_fks:
+                if ofk.get("target_table") == table:
+                    new_tables = list(current | {other_table})
+                    if not _tables_are_connected(new_tables, fk_map):
+                        continue
+                    seen_targets.add(other_table)
+                    new_intent = copy.deepcopy(intent)
+                    new_intent.tables = sorted(new_tables)
+                    _add_expansion_metadata(
+                        new_intent, "B2_add_fact_join",
+                    )
+                    results.append(new_intent)
+                    break
+    return results
+
+
+def _b3_swap_dimension(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    fk_map: dict[str, list[dict[str, str]]],
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """B3: Swap each dimension for an alternative FK-connected dimension."""
+    current = list(intent.tables or [])
+    results: list[SimulatorIntent] = []
+    for i, table in enumerate(current):
+        if (
+            _get_table_role(schema, table) or TableRole.FACT.value
+        ) != TableRole.DIMENSION.value:
+            continue
+        fact_tables = [
+            t for t in current
+            if (_get_table_role(schema, t) or TableRole.FACT.value)
+            == TableRole.FACT.value
+        ]
+        if not fact_tables:
+            continue
+        for dim in _get_dimension_tables(schema):
+            if dim == table or dim in current:
+                continue
+            can_join = any(
+                fk.get("target_table") == dim
+                for fact in fact_tables
+                for fk in fk_map.get(fact, [])
+            )
+            if not can_join:
+                continue
+            new_tables = current[:i] + [dim] + current[i + 1:]
+            new_intent = copy.deepcopy(intent)
+            new_intent.tables = sorted(new_tables)
+            _add_expansion_metadata(new_intent, "B3_swap_dimension")
+            results.append(new_intent)
+    return results
+
+
+def _b4_remove_table(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    fk_map: dict[str, list[dict[str, str]]],
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """B4: Remove each removable dimension table, pruning dependent clauses."""
+    current = list(intent.tables or [])
+    if len(current) <= 1:
+        return []
+    results: list[SimulatorIntent] = []
+    for i, table in enumerate(current):
+        if (
+            _get_table_role(schema, table) or TableRole.FACT.value
+        ) != TableRole.DIMENSION.value:
+            continue
+        new_tables = current[:i] + current[i + 1:]
+        if not new_tables:
+            continue
+        if not _tables_are_connected(new_tables, fk_map):
+            continue
+        new_intent = copy.deepcopy(intent)
+        new_intent.tables = sorted(new_tables)
+        ts = set(new_tables)
+        new_intent.filters_param = [
+            f for f in (new_intent.filters_param or [])
+            if _table_from_column_ref(f.left_expr.primary_column) in ts
+        ]
+        new_intent.group_by_cols = [
+            c for c in (new_intent.group_by_cols or [])
+            if _table_from_column_ref(c.primary_column) in ts
+        ]
+        new_intent.order_by_cols = [
+            o for o in (new_intent.order_by_cols or [])
+            if _table_from_column_ref(o.expr.primary_column) in ts
+        ]
+        new_intent.select_cols = [
+            sc for sc in (new_intent.select_cols or [])
+            if _table_from_column_ref(sc.expr.primary_column) in ts
+        ]
+        if not new_intent.select_cols:
+            continue
+        _add_expansion_metadata(new_intent, "B4_remove_table")
+        results.append(new_intent)
+    return results
+
+
+def _b5_bridge_via_intermediate(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    fk_map: dict[str, list[dict[str, str]]],
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """B5: Add bridge tables connected to 2+ current tables."""
+    current = set(intent.tables or [])
+    if len(current) >= SimulatorConfig.MAX_TABLES:
+        return []
+    results: list[SimulatorIntent] = []
+    for bridge in schema.tables:
+        if bridge in current:
+            continue
+        if (
+            _get_table_role(schema, bridge) or TableRole.FACT.value
+        ) != TableRole.BRIDGE.value:
+            continue
+        connected = {
+            fk.get("target_table")
+            for fk in fk_map.get(bridge, [])
+            if fk.get("target_table") in current
+        }
+        if len(connected) < 2:
+            continue
+        new_tables = list(current | {bridge})
+        if not _tables_are_connected(new_tables, fk_map):
+            continue
+        new_intent = copy.deepcopy(intent)
+        new_intent.tables = sorted(new_tables)
+        _add_expansion_metadata(
+            new_intent, "B5_bridge_via_intermediate",
+        )
+        results.append(new_intent)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# C-series (gold inclusion)
+# ---------------------------------------------------------------------------
+
+def _c1_include_gold(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """C1: Include the gold intent as-is with expansion metadata."""
+    gold_copy = copy.deepcopy(intent)
+    _add_expansion_metadata(gold_copy, "C1_include_gold")
+    return [gold_copy]
+
+
+# ---------------------------------------------------------------------------
+# T-series (temporal scalar expansions)
+# ---------------------------------------------------------------------------
+
+def _t1_extract_select_groupby(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """T1: Wrap temporal columns with EXTRACT(unit) in SELECT and GROUP BY."""
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_temporal_columns(schema, table):
+            for unit in SimulatorConfig.EXTRACT_EXPANSION_UNITS:
+                new_intent = copy.deepcopy(intent)
+                extract_expr = NormalizedExpr.from_column(col)
+                extract_expr = replace(
+                    extract_expr,
+                    scalar_func="extract",
+                    scalar_func_args=[unit],
+                )
+                new_intent.select_cols = list(
+                    new_intent.select_cols or []
+                ) + [SelectCol(expr=extract_expr)]
+                new_intent.group_by_cols = sorted(
+                    list(new_intent.group_by_cols or [])
+                    + [extract_expr],
+                    key=lambda g: g.signature_key,
+                )
+                if new_intent.grain == "row_level":
+                    new_intent.grain = "grouped"
+                _add_expansion_metadata(
+                    new_intent, "T1_extract_select_groupby",
+                )
+                results.append(new_intent)
+    return results
+
+
+def _t2_date_trunc_groupby(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """T2: Wrap temporal columns with DATE_TRUNC(unit) in GROUP BY and SELECT."""
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_temporal_columns(schema, table):
+            for unit in SimulatorConfig.DATE_TRUNC_EXPANSION_UNITS:
+                new_intent = copy.deepcopy(intent)
+                trunc_expr = NormalizedExpr.from_column(col)
+                trunc_expr = replace(
+                    trunc_expr,
+                    scalar_func="date_trunc",
+                    scalar_func_args=[unit],
+                )
+                new_intent.select_cols = list(
+                    new_intent.select_cols or []
+                ) + [SelectCol(expr=trunc_expr)]
+                new_intent.group_by_cols = sorted(
+                    list(new_intent.group_by_cols or [])
+                    + [trunc_expr],
+                    key=lambda g: g.signature_key,
+                )
+                if new_intent.grain == "row_level":
+                    new_intent.grain = "grouped"
+                _add_expansion_metadata(
+                    new_intent, "T2_date_trunc_groupby",
+                )
+                results.append(new_intent)
+    return results
+
+
+def _t3_date_window_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """T3: Add date_window filter on temporal columns using config presets."""
+    current_filter_cols = {
+        f.left_expr.primary_column for f in (intent.filters_param or [])
+    }
+    if len(current_filter_cols) >= SimulatorConfig.MAX_FILTERS:
+        return []
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_temporal_columns(schema, table):
+            if col in current_filter_cols:
+                continue
+            for preset in SimulatorConfig.DATE_WINDOW_EXPANSION_PRESETS:
+                new_intent = copy.deepcopy(intent)
+                new_filter = FilterParam(
+                    left_expr=NormalizedExpr.from_column(col),
+                    op=">=",
+                    value_type="date_window",
+                    param_key="",
+                    raw_value=dict(preset),
+                )
+                new_intent.filters_param = list(
+                    new_intent.filters_param or []
+                ) + [new_filter]
+                _add_expansion_metadata(
+                    new_intent, "T3_date_window_filter",
+                )
+                results.append(new_intent)
+    return results
+
+
+def _t4_date_diff_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """T4: Add date_diff filter on temporal columns using config presets."""
+    current_filter_cols = {
+        f.left_expr.primary_column for f in (intent.filters_param or [])
+    }
+    if len(current_filter_cols) >= SimulatorConfig.MAX_FILTERS:
+        return []
+    results: list[SimulatorIntent] = []
+    for table in intent.tables or []:
+        for col in _get_temporal_columns(schema, table):
+            if col in current_filter_cols:
+                continue
+            for preset in SimulatorConfig.DATE_DIFF_EXPANSION_PRESETS:
+                new_intent = copy.deepcopy(intent)
+                new_filter = FilterParam(
+                    left_expr=NormalizedExpr.from_column(col),
+                    op="<=",
+                    value_type="date_diff",
+                    param_key="",
+                    raw_value=dict(preset),
+                )
+                new_intent.filters_param = list(
+                    new_intent.filters_param or []
+                ) + [new_filter]
+                _add_expansion_metadata(
+                    new_intent, "T4_date_diff_filter",
+                )
+                results.append(new_intent)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# N-series (numeric scalar expansions)
+# ---------------------------------------------------------------------------
+
+def _n1_round_numeric(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """N1: Wrap NUMERIC_MEASURE select columns with ROUND."""
+    numeric_cols: set[str] = set()
+    for table in intent.tables or []:
+        numeric_cols.update(_get_numeric_measure_columns(schema, table))
+
+    results: list[SimulatorIntent] = []
+    for idx, sc in enumerate(intent.select_cols or []):
+        if sc.expr.primary_column not in numeric_cols:
+            continue
+        if sc.expr.scalar_func == "round":
+            continue
+        new_intent = copy.deepcopy(intent)
+        new_expr = replace(
+            new_intent.select_cols[idx].expr,
+            scalar_func="round",
+            scalar_func_args=[0],
+        )
+        new_intent.select_cols[idx] = SelectCol(expr=new_expr)
+        _add_expansion_metadata(new_intent, "N1_round_numeric")
+        results.append(new_intent)
+    return results
+
+
+def _n2_abs_filter(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """N2: Wrap numeric filter left_expr with ABS for range ops."""
+    results: list[SimulatorIntent] = []
+    for idx, f in enumerate(intent.filters_param or []):
+        if f.op not in (">", "<", ">=", "<="):
+            continue
+        if f.left_expr.scalar_func == "abs":
+            continue
+        col = f.left_expr.primary_column
+        table = _table_from_column_ref(col)
+        if not table or table not in column_metadata:
+            continue
+        bare = col.split(".", 1)[1] if "." in col else col
+        col_info = column_metadata.get(table, {}).get(bare, {})
+        if col_info.get("role") != ColumnRole.NUMERIC_MEASURE.value:
+            continue
+        new_intent = copy.deepcopy(intent)
+        new_expr = replace(
+            new_intent.filters_param[idx].left_expr,
+            scalar_func="abs",
+        )
+        new_intent.filters_param[idx] = replace(
+            new_intent.filters_param[idx], left_expr=new_expr,
+        )
+        _add_expansion_metadata(new_intent, "N2_abs_filter")
+        results.append(new_intent)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Structural operators (DISTINCT, LIMIT, OR-groups, expression composition)
+# ---------------------------------------------------------------------------
+
+def _d1_add_distinct(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """D1: Set distinct=True if not already set."""
+    if getattr(intent, "distinct", False):
+        return []
+    new_intent = copy.deepcopy(intent)
+    if hasattr(new_intent, "distinct"):
+        new_intent.distinct = True
+    _add_expansion_metadata(new_intent, "D1_add_distinct")
+    return [new_intent]
+
+
+def _l1_add_limit(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """L1: Add LIMIT with representative values from config."""
+    if intent.limit is not None:
+        return []
+    results: list[SimulatorIntent] = []
+    for val in SimulatorConfig.LIMIT_EXPANSION_VALUES:
+        new_intent = copy.deepcopy(intent)
+        new_intent.limit = val
+        _add_expansion_metadata(new_intent, "L1_add_limit")
+        results.append(new_intent)
+    return results
+
+
+def _f1_or_filter_group(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """F1: Convert pairs of existing AND filters into OR groups."""
+    filters = intent.filters_param or []
+    if len(filters) < 2:
+        return []
+    results: list[SimulatorIntent] = []
+    for i in range(len(filters)):
+        for j in range(i + 1, len(filters)):
+            fi, fj = filters[i], filters[j]
+            if fi.right_expr or fj.right_expr:
+                continue
+            if fi.value_type in ("date_window", "date_diff"):
+                continue
+            if fj.value_type in ("date_window", "date_diff"):
+                continue
+            new_intent = copy.deepcopy(intent)
+            group_id = 1
+            new_fi = replace(
+                new_intent.filters_param[i],
+                bool_op="OR",
+                filter_group=group_id,
+            )
+            new_fj = replace(
+                new_intent.filters_param[j],
+                bool_op="OR",
+                filter_group=group_id,
+            )
+            new_intent.filters_param[i] = new_fi
+            new_intent.filters_param[j] = new_fj
+            _add_expansion_metadata(new_intent, "F1_or_filter_group")
+            results.append(new_intent)
+    return results
+
+
+def _e1_expression_select(
+    intent: SimulatorIntent, schema: SchemaGraph,
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+) -> list[SimulatorIntent]:
+    """E1: Create composed expressions from numeric column pairs in SELECT."""
+    numeric_cols: list[str] = []
+    for table in intent.tables or []:
+        numeric_cols.extend(_get_numeric_measure_columns(schema, table))
+
+    if len(numeric_cols) < 2:
+        return []
+
+    results: list[SimulatorIntent] = []
+    for i, col_a in enumerate(numeric_cols):
+        for col_b in numeric_cols[i + 1:]:
+            new_intent = copy.deepcopy(intent)
+            composed = NormalizedExpr(
+                add_groups=[
+                    MulGroup(multiply=[col_a, col_b]),
+                ],
+            )
+            new_intent.select_cols = list(
+                new_intent.select_cols or []
+            ) + [SelectCol(expr=composed)]
+            _add_expansion_metadata(new_intent, "E1_expression_select")
+            results.append(new_intent)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Orchestration: single-depth expansion
+# ---------------------------------------------------------------------------
+
+_OperatorFn = Any
+
+
+def _build_operator_registry(
+    column_metadata: dict[str, dict[str, dict[str, Any]]],
+    fk_map: dict[str, list[dict[str, str]]],
+) -> dict[str, _OperatorFn]:
+    """Return the full operator map keyed by short code."""
+    return {
+        "A1": lambda i, s: _a1_add_filter(i, s, column_metadata),
+        "A2": lambda i, s: _a2_add_expr_filter(i, s, column_metadata),
+        "A3": lambda i, s: _a3_change_aggregation(i, s, column_metadata),
+        "A4": lambda i, s: _a4_add_groupby(i, s, column_metadata),
+        "A5": lambda i, s: _a5_add_orderby(i, s, column_metadata),
+        "A6": lambda i, s: _a6_add_having_value(i, s, column_metadata),
+        "A7": lambda i, s: _a7_add_having_expr(i, s, column_metadata),
+        "A8": lambda i, s: _a8_remove_filter(i, s, column_metadata),
+        "A9": lambda i, s: _a9_remove_groupby(i, s, column_metadata),
+        "A10": lambda i, s: _a10_remove_having(i, s, column_metadata),
+        "B1": lambda i, s: _b1_add_dimension_join(i, s, fk_map, column_metadata),
+        "B2": lambda i, s: _b2_add_fact_join(i, s, fk_map, column_metadata),
+        "B3": lambda i, s: _b3_swap_dimension(i, s, fk_map, column_metadata),
+        "B4": lambda i, s: _b4_remove_table(i, s, fk_map, column_metadata),
+        "B5": lambda i, s: _b5_bridge_via_intermediate(i, s, fk_map, column_metadata),
+        "C1": lambda i, s: _c1_include_gold(i, s, column_metadata),
+        "T1": lambda i, s: _t1_extract_select_groupby(i, s, column_metadata),
+        "T2": lambda i, s: _t2_date_trunc_groupby(i, s, column_metadata),
+        "T3": lambda i, s: _t3_date_window_filter(i, s, column_metadata),
+        "T4": lambda i, s: _t4_date_diff_filter(i, s, column_metadata),
+        "N1": lambda i, s: _n1_round_numeric(i, s, column_metadata),
+        "N2": lambda i, s: _n2_abs_filter(i, s, column_metadata),
+        "D1": lambda i, s: _d1_add_distinct(i, s, column_metadata),
+        "L1": lambda i, s: _l1_add_limit(i, s, column_metadata),
+        "F1": lambda i, s: _f1_or_filter_group(i, s, column_metadata),
+        "E1": lambda i, s: _e1_expression_select(i, s, column_metadata),
+    }
+
+
+def _expand_single_depth(
+    intents: list[SimulatorIntent],
+    schema: SchemaGraph,
+    operators: dict[str, _OperatorFn],
+    seen_keys: set[str],
+) -> list[SimulatorIntent]:
+    """Run all operators on each intent in *intents*, returning new unique variants.
+
+    Deduplicates via *seen_keys* (mutated in place) and enforces schema
+    consistency on each accepted variant.
+    """
+    results: list[SimulatorIntent] = []
+    for intent in intents:
+        for op_name, op_func in operators.items():
+            variants = op_func(intent, schema)
+            for var in variants:
+                var_key = intent_key(var.to_runtime_intent())
+                if var_key in seen_keys:
+                    continue
+                seen_keys.add(var_key)
+                if var.grain == "grouped" and not var.group_by_cols:
+                    continue
+                var, _ = enforce_schema(var, schema)
+                results.append(var)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def expand_gold_intents(
+    gold_intents: list[SimulatorIntent],
+    schema: SchemaGraph,
+    limits: SchemaLimits | None = None,
+    max_depth: int | None = None,
+) -> list[SimulatorIntent]:
+    """Expand all gold intents into synthetic intents via multi-depth deterministic expansion.
+
+    Runs every operator on every gold intent (depth 1), then re-expands
+    the depth-1 results (depth 2), up to *max_depth*.  Deduplicates
+    across all golds and depths via SHA-256 ``intent_key``.
+
+    CTE gold intents are now included (operators apply to the main
+    query portion).
+
+    Args:
+
+        gold_intents: Seed SimulatorIntents to expand.
+        schema: Schema graph for column/table introspection.
+        limits: Optional SchemaLimits overriding MAX_FILTERS,
+            MAX_GROUPBY, MAX_TABLES.
+        max_depth: Expansion depth; defaults to
+            ``SimulatorConfig.MAX_EXPANSION_DEPTH``.
+
+    Returns:
+
+        List of unique synthetic SimulatorIntents.
+    """
+    if limits is not None:
+        SimulatorConfig.MAX_FILTERS = limits.max_filters
+        SimulatorConfig.MAX_GROUPBY = limits.max_groupby
+        SimulatorConfig.MAX_TABLES = limits.max_tables
+        log(
+            f"expand_gold_intents: using SchemaLimits "
+            f"max_filters={limits.max_filters}, "
+            f"max_groupby={limits.max_groupby}, "
+            f"max_tables={limits.max_tables}"
+        )
+
+    if max_depth is None:
+        max_depth = SimulatorConfig.MAX_EXPANSION_DEPTH
+
+    log(
+        f"expand_gold_intents: expanding {len(gold_intents)} gold intents "
+        f"with max_depth={max_depth}"
+    )
+
+    column_metadata = _build_column_metadata(schema)
+    fk_map = _build_fk_map(schema)
+    operators = _build_operator_registry(column_metadata, fk_map)
+
+    seen_keys: set[str] = set()
+    for gold in gold_intents:
+        seen_keys.add(intent_key(gold.to_runtime_intent()))
+
+    current_layer = list(gold_intents)
+    all_synthetic: list[SimulatorIntent] = []
+
+    for depth in range(1, max_depth + 1):
+        new_variants = _expand_single_depth(
+            current_layer, schema, operators, seen_keys,
+        )
+        log(
+            f"expand_gold_intents: depth={depth} produced "
+            f"{len(new_variants)} new variants"
+        )
+        if not new_variants:
+            break
+        all_synthetic.extend(new_variants)
+        current_layer = new_variants
+
+    log(
+        f"expand_gold_intents: generated {len(all_synthetic)} "
+        f"unique synthetic intents across {max_depth} depth(s)"
+    )
+    return all_synthetic