feat(controller): Phase E — stage_split L5 (StageAllocator + ThreeStageEmitter)

[zzylol]

Summary

Lands the typed L5 framework per controller/docs/design.md §6 core::physical:
takes a Phase-C-bound SketchExpr DAG and colors each node by StageId, then
emits one structured StageConfig per stage for the DC three-stage topology
(edge → gateway → backend).

• controller/src/stage_split/ — new module: stage_id.rs (StageId + Topology),
  colored_dag.rs (ColoredDag IR with cut-edge analysis), allocator.rs
  (StageAllocator::allocate), emitter.rs (Emitter trait +
  ThreeStageEmitter), tests.rs (module-level integration tests).
• Coloring rules per design.md §6 batched-queries example:
  Logical(Scan/Window/Aggregate{exact}) + SketchAgg → Edge;
  SketchMerge → Gateway; SketchEstimate → Backend; LetBinding/Ref
  resolve to their bound expression's stage.
• StageConfig carries the structural facts each downstream consumer needs
  (sketch processor names — kllprocessor, ddsketchprocessor, etc. — plus
  aggregation ids threaded edge → gateway → backend, plus OTLP exporter
  targets). Phase G+ wires the actual OpAMP push and StreamingConfig POST.
• controller/src/planner/stage_split.rs gets an additive typed call path
  (split_typed_three_stage) gated by USE_TYPED_STAGE_SPLIT=1, mirroring
  Phase C's USE_TYPED_SKETCH_ALGEBRA pattern. Existing untyped callers run
  unchanged.
• controller/docs/design.md adds an Implementation-status subsection in §6
  describing what Phase E lands and what's deferred to Phase G+.

Test plan

• cargo build --release -p controller — clean
• cargo test --release -p controller stage_split — 38 passed, 0 failed
• cargo clippy --release -p controller --all-targets -- -D warnings —
  same 186 errors as origin/main (all pre-existing; Phase E introduces
  zero new clippy warnings)
• No docker activity; no submodule pointer drift; touched only the
  allowed files (controller/src/stage_split/, controller/src/main.rs,
  controller/src/planner/stage_split.rs, controller/docs/design.md).

Tests added (12)

stage_split::tests:

• allocator_three_stage_basic
• allocator_sketch_agg_under_scan_pinned_edge
• allocator_sketch_estimate_pinned_backend
• allocator_let_binding_color_propagates
• allocator_ref_resolves_to_binding_stage
• allocator_sketch_merge_lands_gateway
• emitter_three_stage_emits_three_configs
• emitter_edge_config_has_correct_processor_kll
• emitter_edge_config_has_correct_processor_ddsketch
• emitter_backend_config_routes_aggregation_id
• emitter_unsupported_topology_errors_cleanly
• end_to_end_quantile_workload

planner::stage_split::tests:

• typed_three_stage_path_returns_three_configs

Plus per-module unit tests in stage_id.rs, colored_dag.rs, allocator.rs
(9 more).

Open question / doc tightening

design.md §6's L5 placement table (line ~1380) puts Aggregate{Max} on Edge in
one column and "root of q3" on Backend in another. The natural reading is that
the same Aggregate{Max} node maintains per-window state at the edge AND
re-aggregates the merged stream at the backend — which Phase E's SketchExpr
IR cannot directly express today (there's no Logical(Merge) SketchExpr
variant for the gateway hop over exact streams). Phase E colours the
Logical(Aggregate) reachable in L4 as Edge unconditionally and notes the
deferral in allocator.rs + the Implementation-status doc note. Phase G+ that
adds the explicit Logical(Merge) / SketchExpr-level exact-merge variant is
the natural place to revisit the backend re-aggregation rule.

🤖 Generated with Claude Code