feat(planner): declare counter metrics so CMS+heap can prove non-negative weights

[zzylol]

Rebased on main d4869a7 (DF 54).

Wave 1 chain: #594 → #593 → #592 → #591 → #595 → #596 → #597 → #598 → #599 (on #589)

Part of #509 (Example 1), decision X1 from #580's planning: a metric-type declaration plus a non-negativity proof, so Count-Min + heap is valid over raw counter samples.

Why

Example 1's Q2 is topk by (job) (10, sum_over_time(http_requests_total[1m])). Every Count-Min + heap candidate for it, including #589's whole-expression heap over raw samples, was rejected by Stage 3 and by the runtime, because nothing proved the update weights (raw sample values, or their sums) non-negative. Neither the workload nor the catalog carried a metric type, and the _total suffix is only a naming convention.

What

• Declaration: DataWorkload.metric_types: BTreeMap<String, MetricType> with MetricType::{Counter, Gauge} (Prometheus # TYPE). It defaults to empty.
  • It goes in DataWorkload because that struct already holds the facts about the queried data, the PromQL frontend already reads its ingestion interval, and plan_stages already receives it, so Stage 1 can read it without a new input layer.
  • HistogramCatalog was not used: it is histogram-specific and lowering-only, and the IR has no place to carry the declaration on to Stage 1.
• Proof: a new NonNegativeWeightProof::CounterSamples variant.
• Stage 3 and runtime: unchanged. Both already accept Count-Min for any WeightDomain::NonNegative proof, so they apply the same rule.

How

• plan_stages passes &data.metric_types to stage1_logical_candidates, which passes it to enumerate_local_logical_candidates. This is a plain parameter.
• Pass 1 records counter_input on each target. It is true when the target's input is samples of a metric declared a counter, reached only through TimeRange and plain Sum aggregates (sum_over_time, sum by).
• A keyed summary update weighted by SampleValue over such an input gets CounterSamples. This covers both the heap over per-series sums and the whole-expression heap over raw samples.
• Arithmetic, any other operator, a gauge, or an undeclared metric (whatever its name) gets no proof.
• Example 1's workload declares http_requests_total a counter in the stage_pipeline devtool and in the acceptance test. The fixture and acceptance doc are regenerated, and the workflow doc lists the field. The integration commit updates Stage 3 per-second cost model, memory pricing and calibration #594's per-second ranking test and the Stage 3 cost model's worked example to P60.

Before / After (Example 1, built-in models, no cost tuning)

Costs are per second (#594): per-evaluation CPU-ms × 0.1 evaluations/s.

	Before (#594)	After
Count-Min + heap candidates	24 invalid ("not proven non-negative")	24 valid, all compile in the runtime
Selected	P58 (all exact, shared input), 5.220/s (52.201 per evaluation)	P60 (Q1 exact, Rate and Sum acc; Q2 Count-Min + heap over the exact sum_over_time accumulator; shared input), 4.620/s (46.201 per evaluation)
Q2 cost in the winner, per evaluation	19.001 (Sum acc 5.0 + sort and limit 14.001)	13.001 (Sum acc 5.0 + CMS 1M sums × depth 8 = 8.0 + estimate 0.001)
P58 rank	1st	8th. Ranks 1–7 are shared-input Count-Min + heap plans over per-series sums, 4.620–5.220/s; P51 ties P58
Whole-expression Count-Min + heap	invalid	ranks 17th–20th; P63 is cheapest at 6.520/s (per evaluation, 4M raw samples × depth 8 = 32.0)
Whole-expression CountSketch + heap	P64, 53.720/s	unchanged

Without the declaration, or with http_requests_total declared a gauge, the 24 Count-Min + heap candidates stay invalid and the runtime still rejects them. This is today's behavior, and a test covers it.

Tests

• Pass 1: a declared counter gives CounterSamples on all 6 heap updates. An undeclared m_total, a gauge, or a different declared counter gives none. counter_samples stops at arithmetic (- 100, unary minus).
• Stage 3: Count-Min over declared counter samples is priced, not rejected.
• Acceptance: with the declaration, all 64 candidates are valid and compile. With no declaration or a gauge, 24 are invalid and the runtime rejects the same ones.

Gate

• cargo fmt --all --check: passes.
• cargo clippy --workspace --all-targets --all-features -- -D warnings: passes.
• cargo test --workspace: 1,522 passed / 10 ignored (feat(planner): whole-expression top-k heap sketch over raw samples #589: 1,517 / 10).
• Viewer tests: 29 run, OK (6 skipped).

Refs #509, #580.

🤖 Generated with Claude Code