feat: temporal distribution stats across resolution windows (stddev, median, percentile)

[atheurer]

Summary

When using --resolution X with an aggregation method (e.g., avg, sum), CDM divides the query time domain into X windows and returns one value per window. Currently there is no way to characterize the distribution of those window values — only to retrieve them individually.

This feature request adds a second aggregation pass over the per-window results, producing distribution statistics: min, max, median, mean, stddev, and percentiles.

Motivation

A single aggregate (e.g., "avg throughput = 20 Gbps") does not tell you whether the workload was stable or highly variable. For example:

• A uperf run reporting 20 Gbps avg could mean a rock-steady 20 Gbps throughout, or wild swings between 5 Gbps and 35 Gbps that happen to average 20 Gbps.
• Coefficient of variation (stddev / mean) is a useful signal for deciding whether a benchmark result is trustworthy.
• Agentic consumers of CDM data need this to assess result quality without downloading all raw samples.

Proposed behavior

For a query with --resolution N and aggregation method M:

1. (existing) Divide the time domain into N windows; compute aggregate M within each window → N values.
2. (new) Over those N values, compute and return: min, max, mean, median, stddev, and optionally pNN (e.g., p95, p99).

This is most meaningful for avg and sum aggregations (where the window values are commensurable), but could be offered for min/max as well.

Example use case

cdm query --metric network_throughput \
          --resolution 10 \
          --aggregation avg \
          --temporal-stats stddev,p95,min,max

Returns: per-window avg values plus stddev=X, p95=Y, min=Z, max=W across those 10 windows.

Alternatives considered

• Returning all raw per-window values and letting the caller compute stats — works but wastes bandwidth and shifts complexity to every consumer.
• A separate --distribution query type — possible but adds API surface unnecessarily if it's just a flag on existing resolution queries.

[k-rister]

Looked into implementation feasibility — the resolution-windowing code already produces exactly the per-window value arrays this needs (getMetricDataFromIdsSets/calcAvg in cdm.js), and there's a precedent (calcIterMetrics) for mean/min/max/stddev, so this looks like a reasonably small, well-scoped addition. Before starting, a few design decisions would benefit from stakeholder input:

1. Percentile interpolation method. Nothing in this codebase has picked a percentile method before — the only prior mention (workflows/result-calculation.md:194) is an unimplemented TODO, not a resolved decision. Common choices: nearest-rank (simplest, matches "the Nth value in sorted order") vs. linear interpolation between ranks (matches numpy's default, smoother for small N). Given --resolution windows are often single-digit-to-low-double-digit counts, the choice materially affects reported values at small N. Leaning toward linear interpolation as the more standard default unless there's a reason to prefer nearest-rank.

2. Degenerate small-N behavior. stddev of a single window, or a percentile request against 2-3 windows, are real cases (e.g. --resolution 2). Options: return the stat anyway (stddev=0 for N=1), omit the field, or reject the request with a validation error when N is below some threshold for the requested stat. Needs an explicit answer rather than "whatever the math produces."

3. Which aggregation methods get temporal stats. The proposal notes this is "most meaningful for avg/sum" but leaves the door open for min/max. Should --temporal-stats be restricted to avg/sum aggregations only, or allowed (with a defined semantics) for min/max windows too?

4. Requested-stats list vs. always-compute-all. The example (--temporal-stats stddev,p95,min,max) implies an explicit opt-in list per request. Confirming that's preferred over always returning the full stat set (mean/min/max/median/stddev) whenever --resolution is used — the opt-in list avoids bloating responses that don't need it, but adds parsing/validation surface (e.g. extracting N from arbitrary pNN tokens).

One implementation note: there's no existing test suite for the query layer (queries/cdmq/) to extend — verification would be manual against a live OpenSearch instance, consistent with how the rest of this layer is currently validated.

Happy to proceed once there's alignment on 1-3 above.