refactor: consolidate Capability into sketch_algebra; warm_tier_analysis becomes facade (Step 2a)

[zzylol]

Summary

Step 2a of the controller architectural cleanup per docs/design.md §5. Consolidates the four overlapping sketch-capability tables into a single source of truth at controller/src/sketch_algebra/capability.rs, and shrinks warm_tier_analysis.rs (PR #128) into a thin facade that uses the controller's existing intent_algebra::lower pipeline instead of matching directly on PromQL function-name strings.

Before: 4 overlapping capability tables + invented function names

	Source	Contents
1	controller/sketch_capabilities.yml	YAML runtime override (per-sketch supported_intents, perf knobs)
2	controller/src/algebra/optimizer.rs::sketch_capability()	Compiled-in defaults — duplicate of (1)
3	controller/src/sketch_algebra/params.rs::SketchKind	Family enum
4	controller/src/warm_tier_analysis.rs::{Capability, SketchKindHandle}	Query-side duplicate from PR #128

Plus the analyzer matched directly on PromQL function-name strings — count_distinct_over_time, cardinality_estimate, count_distinct — that exist in neither PromQL nor MetricsQL.

After: one definition, no invented names

MetricsQL/PromQL
    │
    ▼  query_parser::parse_query
ParsedQuery
    │
    ▼  intent_algebra::lower::lower_parsed_query
QueryExpr (Aggregate { intent: AggIntent::Quantile{q, accuracy} ... })
    │
    ▼  sketch_algebra::capability_for(&agg.intent)    ← THE missing function
Option<Capability>
    │
    ▼  SketchIndex.classify(sid) → {Hit, Ghost, Unknown}
    ▼  sketch_reducer dispatch keyed on Capability variant
WarmTierResult

What landed

New: controller/src/sketch_algebra/capability.rs (~680 lines, 22 tests)

• Capability enum (was duplicated in 2 places)
• SketchKindHandle enum (incl. CmsWithHeap + Any wildcard)
• SketchCapability struct + SupportedIntent enum (moved from algebra/optimizer.rs)
• capability_for(&AggIntent) -> Option<Capability> — the new comprehensive function
• default_capability_table() (moved from algebra/optimizer.rs::sketch_capability)
• load_capability_overrides(path) (moved from algebra/optimizer.rs::load_sketch_capabilities)
• Capability::is_satisfied_by(&Capability) with SketchKindHandle::Any wildcard

AggIntent → Capability mapping:

AggIntent	Returns
Quantile{accuracy: Epsilon/EpsilonDelta}	Some(QuantileApprox(Any))
Cardinality / Count {accuracy: Epsilon/EpsilonDelta}	Some(CardinalityApprox)
TopK / Frequency {accuracy: Epsilon/EpsilonDelta}	Some(FrequencyTopk(CmsWithHeap))
*{accuracy: Exact}	None
Sum, Min, Max, Avg, Rate, Increase	None

warm_tier_analysis.rs (1015 → 607 lines)

Pure facade. No direct function-name matching. Uses query_parser + intent_algebra::lower + sketch_algebra::capability_for. Capability + SketchKindHandle re-exported from sketch_algebra.

algebra/optimizer.rs (−199 lines)

Imports from sketch_algebra; duplicate definitions deleted.

asap-query-engine/

• stores/sketch_db/sketch_index.rs: local Capability / SketchKindHandle enums dropped → pub use controller::sketch_algebra::{...}. PR feat: unify extract_promql_call with controller — single PromQL → Capability owner #128's From<> adapters deleted.
• engines/warm_tier/sketch_reducer.rs: kept legacy function-name aliases for back-compat with PR feat: unify extract_promql_call with controller — single PromQL → Capability owner #128 reducer tests + recording-rule emission in config/precompute.rs. They no longer drive analysis-side dispatch.
• drivers/ingest/otel.rs + engines/simple/engine.rs: import-path adjustments.

Build + test

• cargo build --release -p controller: clean
• cargo build --release -p query_engine_rust: clean
• cargo test -p controller --lib -- sketch_algebra::capability: 22/22 pass (new)
• cargo test -p controller --lib -- warm_tier_analysis: 19/19 pass (PR feat: unify extract_promql_call with controller — single PromQL → Capability owner #128 had 24; 5 invented-name tests dropped + replaced with real PromQL idioms)
• cargo test -p controller --lib: 633/633 pass
• cargo test -p query_engine_rust --lib -- engines::warm_tier: 13/13 pass

Diff stat

asap-query-engine/src/drivers/ingest/otel.rs              |    9 +
asap-query-engine/src/engines/simple/engine.rs            |    8 +-
asap-query-engine/src/engines/warm_tier/sketch_reducer.rs |   40 +-
asap-query-engine/src/stores/sketch_db/sketch_index.rs    |  131 +--
controller/src/algebra/optimizer.rs                       |  199 +---
controller/src/sketch_algebra/capability.rs               |  680 + (new)
controller/src/sketch_algebra/mod.rs                      |    5 +
controller/src/warm_tier_analysis.rs                      | 1015 +/-
8 files changed, 1387 insertions(+), 1163 deletions(-)

Follow-ups (out of scope for 2a)

1. Quantile accuracy-target awareness in capability_for is coarse. Epsilon(0.0001) and Epsilon(0.05) both return QuantileApprox(Any). The L4 binder picks DDSketch vs KLL based on ε budget — that's the proper home for this granularity.
2. topk aggregate gap: the intent_algebra lowerer doesn't emit AggIntent::TopK for the topk query-expr wrapper today. capability_for sees the inner count_over_time as Cardinality instead. PR feat: unify extract_promql_call with controller — single PromQL → Capability owner #128's FrequencyTopk(CmsWithHeap) test loosened to just-assert-a-candidate. Proper fix: extend the lowerer.
3. Legacy aliases count_distinct_over_time / cardinality_estimate remain accepted in sketch_reducer.rs::function_to_family + config/precompute.rs recording-rule emission for back-compat. Step 2c can revisit.

Up next in this refactor chain

• 2g: Prometheus → VictoriaMetrics on the demo (compose + YAML edits — small)
• 2b/c/d/e (bundled): retire algebra/ legacy module; create physical/, optimizer/, emit/ modules per design.md §5; absorb query_language/ into query_parser/
• 2f: update docs/design.md "Today's locations" column to match the new layout

🤖 Generated with Claude Code