feat: 5-layer architecture — AggIntent, WindowSpec, WindowedAgg (#115)

[zzylol]

Closes #115.

Summary

Refactors the controller into a clean 5-layer architecture, separating the sketch logical plan (what to compute) from physical implementation (how to compute it).

The 5 Layers

Query workloads
  │  Layer 1 — Query Language (PromQL, SQL, DataFusion, ElasticDSL, ...)
  ▼
Language-specific AST
  │  Layer 2 — Language Logical Plan
  ▼
Language Logical Plan
  │  Layer 3 — Sketch Logical Plan (Sketch Algebra)
  ▼
Sketch Logical Plan (QueryExpr with AggIntent)
  │  Layer 4 — Sketch Optimizer (rewrite rules)
  ▼
Optimised Sketch Logical Plan
  │  Layer 5 — Physical Execution Plan
  ▼
Physical Plan (OTel processors, PromSketch, DB queries, on-device)

Key changes

SketchAggOp → AggIntent (implementation-independent)

Before (physical names)	After (logical intent)
DDSketch { quantiles, epsilon }	Quantile { quantiles, accuracy }
HLL { registers }	Cardinality { accuracy }
CountMin { width, depth } / CountSketch { width, depth }	Frequency { accuracy }
ExactMinMax { min, max }	Extrema { min, max }
Hydra { inner, partition_keys }	PerPartition { inner, keys }

The logical plan now says "I need a quantile at φ=0.99 with ≤1% error" — not "use DDSketch". The physical planner (Layer 5) decides the implementation.

WindowSpec + WindowKind — unified window model

WindowKind	Semantics	Origins
Tumbling { size }	Fixed-size, non-overlapping	SQL TUMBLE, Elastic fixed_interval
Sliding { size, slide }	Fixed-size, overlapping	PromQL [5m] range vector, SQL HOP
Unbounded	All samples	SQL GROUP BY without time
Landmark	Epoch to now	Running aggregates
Session { gap }	Gap-based	Elastic session windows

WindowedAgg — bundled window + sketch aggregation

In sketch systems the window defines the sketch lifecycle (when to flush/reset). WindowedAgg { agg, window, col, input } bundles them so the physical planner can select the best implementation:

• OTel tumbling flush (time.NewTicker)
• PromSketch ExponentialHistogram (supports tumbling + sliding natively)
• DB GROUP BY time_bucket()

Updated doc

controller/docs/query-to-sketch-translation.md rewritten with the 5-layer architecture, AggIntent semantics, and WindowSpec design.

Files changed (9 files, +454 −300)

• algebra/expr.rs — AggIntent, WindowSpec, WindowKind, WindowedAgg, backward-compat alias
• algebra/directory.rs — updated to work with AggIntent; memory estimates from accuracy
• algebra/allocator.rs — WindowedAgg arm, AggIntent dispatch
• algebra/optimizer.rs — rules match on logical intents (Cardinality, Quantile, etc.)
• planner/stage_split.rs — WindowedAgg handling, AggIntent dispatch
• query_parser/promql.rs — emits AggIntent (Quantile, Cardinality, Frequency)
• query_parser/mod.rs — QeCollector handles WindowedAgg + AggIntent
• algebra/mod.rs — re-exports AggIntent, WindowSpec, WindowKind
• docs/query-to-sketch-translation.md — 5-layer architecture doc

Test plan

• All 279 tests pass
• cargo build clean
• pub type SketchAggOp = AggIntent provides backward compatibility

🤖 Generated with Claude Code