docs(design): controller mapping from query to edge aggregation config (scope + sparse)

[zzylol]

What

Design doc specifying the controller-side mapping from query → edge aggregation config — the follow-up flagged by ASAPCollector #471 (the Scope per-series/whole-stream field) and #472 (the hll_sparse knob). Those edge fields exist but currently default to legacy behavior because nothing on the controller sets them; this doc specifies the mapping that does.

New file: docs/query-to-edge-config-mapping.md.

Scope of the design

Three per-aggregation decisions, each grounded in code that already exists:

Edge decision	Query signal	Source
Sketch family + params	AggIntent kind + AccuracyTarget	agg_intent.rs:35, types.rs:5
Scope (per-series / whole-stream)	Aggregate.by: GroupKeys + the TimeRange per-series marker	query_expr.rs:47,278,369
Sparse HLL	Cardinality intent + expected cardinality + ε	agg_intent.rs (+ workload/catalog)

Key rules:

• Scope — global ungrouped cross-series aggregate (by.is_empty() and not per-series) ⇒ WholeStream; grouped (by non-empty) ⇒ PerSeries with AggregateBy = by; Rate/Increase or TimeRange-child ⇒ PerSeries. (Grouped ≠ whole-stream: sum by (zone) needs one sketch per zone.)
• Sparse HLL — default sparse for per-series (most series are low-cardinality; auto-promotes, zero accuracy/wire risk); dense for whole-stream (one high-cardinality instance).
• ItemLabel reconciled with whole-stream item-subject (distinct items vs value distribution).

What it identifies as the gap

The L3 intent algebra and L4 sketch-bound IR (SummaryKind/SummaryParams) exist, but the L3→L4 binding rules (optimizer/rules/) and the L4→edge emitter that produces PrecomputeConfig do not — both are future work per docs/design.md. The doc specifies them as pure, table-testable mapping functions, includes worked examples (PromQL/SQL → config), AggID stability/versioning, a build order, and open questions (expected-cardinality source, DDSketch-vs-KLL, Theta/KMV with no edge family).

Design only — no code.

🤖 Generated with Claude Code

[zzylol]

Misplaced — the query→edge-config mapping belongs in ASAPQuery-backend's control_plane (which already has intent_algebra/, optimizer/, and emit/precompute.rs), not the controller. Moving the design + implementation there.