refactor phase 3c: decompose the pre-aggregation pipeline into named phases

[hussainsultan]

Phase 3c, stacked on #299 — the riskiest single refactor in the plan, executed with the safety net built for it. The 1,089-line to_untagged_with_preagg body is now a ~25-line orchestrator over ten named phase functions, with explicit data flow instead of 15 loose accumulators threading through one scope.

Shape

scope       = _build_scope(...)                # prologue + phase 1: metadata merge,
                                               #   joined table, filter application
raw_tables,
filter_owners = _resolve_filter_ownership(scope)   # 1b
filter_legs  = _split_cross_table_legs(...)        # 1c
plan         = _build_plan(scope)                  # 2
partitioned  = _partition_by_source(scope, plan)   # 3
acc          = _preaggregate_sources(...)          # 4: the 556-line per-source loop
result       = _combine_preaggregates(...)         # 5 (or _aggregate_joined_fallback)
result       = _attach_deferred_count_distincts(scope, acc, result)  # 5b
result       = _apply_calc_phase(scope, plan, acc, result)           # 6
return _project_requested(plan, result)                              # 7

Two explicit dataclasses replace the loose state: _PreaggScope (read-only after phase 1 — op, join tree info, merged fields, the filtered joined table, filter bookkeeping) and _PreaggAccumulators (what phase 4 produces — pre-agg results, decomposed means, re-agg ops, count identities, deferred count-distincts, totals sources).

Method

Every phase body moved verbatim: each function unpacks the scope fields into the original local names at the top, so the diff inside each phase is pure indentation. No logic was rewritten. Extraction went one commit per phase group (scope → 1b–3 → 4 → 5–7), each gated on the SQL-snapshot corpus, the full soundness directory, and the pre-agg stress + BI-trap suites; the final commit ran the full suite.

The follow-up this enables (not in this PR): phase 4's interior — per-table filter pushdown, measure classification, grain computation — can now be decomposed against a 556-line function with a typed contract, and the ~40 remaining broad exception handlers in the pre-agg path can be triaged per phase.

Verification

• Full suite: 1703 passed, exit 0
• SQL snapshots byte-identical across all 4 commits
• Soundness (152), pre-agg stress, BI-traps green at every step
• SCC ratchet green (graph remains a DAG); ruff + format clean

🤖 Generated with Claude Code