docs(data_plane): Step C design doc — recursive L4Node plan-executor

[zzylol]

Summary

Design doc for Step C of the plan-shaped-serving migration (Step A: #407, Step B: #408) — planning doc, not an implementation, same spirit as data_plane/docs/sketchindex-sid-unification-plan.md.

Grounds the design in what ASAPQueryEngine::execute() actually does today (read, not assumed): a flat Vec<ASAPTierCandidate> loop that overwrites rather than folds multiple candidates, real cross-sid merge only for ExactAgg (plus a global-only HLL special case — every other grouped sketch case silently produces duplicate un-merged output series today), and two raw-AST fallbacks (try_topk_over_rate_fallback, try_rate_over_frequency_fallback) that exist because today's flat Capability vocabulary can't express those compositions.

Proposes replacing the flat loop with a real recursive walk over asap_sketch::L4Node — already built control-plane-side since Step A/B (implement_promql_for_asap_tier/implement_tree_in_with), never consumed by data_plane today — and flags four open questions that need a decision before/while implementing:

1. Where the tree comes from (data_plane depends on asap_plan/asap_sketch directly, or calls through a control_plane seam)
2. SummaryMerge's exact-param-match requirement for sketch families — Capability matching is family-level only (SketchKindHandle, no SummaryParams), so it can't see whether two candidate sids actually share the same k/width/depth
3. Where rank-and-slice post-processing (topk ranking by a non-count_over_time measure) lives — turns out the reason it doesn't tree-ify today is narrower than an earlier draft claimed (AggIntent::TopK can compose with an inner aggregate, just only for the RankingMeasure::Frequency case; the NonAdditive case lowers to Sort{Limit{Aggregate}}, which implement_tree_in_with just doesn't decompose yet)
4. Rollout shape (parallel-path env-var gate vs. hard cutover)

Test plan

N/A — docs only, no code changes.

🤖 Generated with Claude Code

[zzylol]

While starting the SummaryExecutor implementation for this design: filed ASAPController#159 — asap_sketch::exec::execute() has no grouping model (SummaryAgg's by field is passed to find_candidates but never used structurally; fold_states merges everything find_candidates returns into one State). For a grouped query (quantile by (zone) (...), the normal case here, not an edge case), calling execute() naively once per query would silently merge across groups instead of producing one series per group.

Doesn't block this doc (still correctly describes the target shape), but the "proposed executor" section's find_candidates table entry should note that data_plane's implementation needs a per-group enumeration loop outside execute() (calling it once per distinct group value, with find_candidates scoped to that group via whatever per-call context data_plane's Self closes over) until/unless ASAPController#159 lands a first-class answer. Same applies to time-range: the trait carries no t0_ms/t1_ms, so data_plane needs a fresh per-query context struct (not shared mutable state on ASAPQueryEngine, which is called concurrently) rather than implementing the trait directly on the engine.

🤖 Noted with Claude Code.

[zzylol]

Rebased onto current main (this branch was 27 commits behind, predating #416/#417/#418) and updated the doc's content:

• Status note + gap list brought up to date: SummaryExecutor now covers the Frequency family and ExactAgg(Sum/Increase) candidate matching + coverage tracking (landed since this doc was last synced), not just quantile/cardinality. Merge-only-existed-for-ExactAgg and no-param-agreement-check are both resolved on the new path now.
• New "Architecture reference" section citing ASAPController docs/design.md's "Serving-time execution" section directly, to anchor this doc's planning-vs-serving split in the upstream framing.
• "Rollout" section replaces "still open" (question docs: design for SimpleMapStore persistence (mem limit + disk flush) #4) with an actual plan — and corrects a real error from the original version: it named implement_promql_for_asap_tier as "the seam" for tree construction, but that function uses the naive DefaultCostModel and has its own documented, tracked gap where it can't realize the Frequency intent at all. The correct seam is sketch_algebra::lower::bind_query_expr (ControlPlaneCostModel, what main.rs's real production pipeline actually uses). Also documents why rate()/topk-over-rate/outer-agg-fold must be excluded from the shadow comparison entirely, and why shadow mode (not a cutover) is the actual scope of the next phase.

🤖 Generated with Claude Code

[zzylol]

Rewrote this doc entirely as a pure design/interface doc, dropping the implementation-status-tracking framing ("Status (date)", PR references, "resolved on the new path" narration). It now describes: the SummaryExecutor trait contract, how data_plane's data model realizes it (Handle/State/Value/GroupKey/Error), the grouping/readout/coverage/ExactAgg designs, the nested-query topology questions, and the shadow-mode rollout design — with a clean "Open design questions" list at the end instead of scattered inline status notes.

Added one new, substantive open question found while working on the shadow-mode rollout (#419): grouping semantics for an empty by are ambiguous between "no PromQL grouping syntax exists for this shape at all" (a bare per-series range function like quantile_over_time) and "an explicit aggregation operator asked to reduce everything" (count(), sum() with no by()) — both produce the identical SummaryAgg{by: []} tree (confirmed by inspecting both directly). This affects every sketch family, not just HLL/cardinality, so it's written up as a design question needing either an upstream IR signal or a caller-supplied one — not a per-metric special case to hack around locally.

🤖 Generated with Claude Code

[zzylol]

Superseded by #425, which grounds this same territory (planning-time vs. serving-time, the SummaryExecutor rollout) in ASAPController's now-merged official ## Interface docs (ASAPController#169) rather than this doc's own proposals/open questions from before those interfaces were nailed down.

In particular, open question 2 here ("SummaryMerge's exact-param-match requirement... Capability matching is family-level only") and the broader grouping-ambiguity problem this doc's later revisions documented are addressed by #169's Reduction::{Reduce(GroupKeys), PerEntity} type — a real upstream IR signal, not something this deployment needs to solve unilaterally.

This PR's own analysis (the flat-loop/no-generic-merge/two-fallback critique of ASAPQueryEngine::execute()) is still accurate and not restated in #425 — worth keeping in mind during the actual SummaryExecutor cutover, just not carried forward as a live design doc.