# ADR-07: Aggregation reducers in the contract

**Status**: accepted (2026-05-28)
**Blocks**: workstream B (canonical reducer set), workstream E (bridge controller manifest).

## Context

nirs4all aggregates predictions per sample (mean / median / vote / robust_mean / exclude_outliers) when the dataset has repeated measurements. Roadmap v1 considered approximating in the adapter; Codex pushed back: **canonical reducers belong in the contract**, not only in the adapter, otherwise the conformance pack is incomplete.

## Decision

Six canonical reducers live in the contract:

| Reducer | Semantics | NaN policy |
|---|---|---|
| `mean` | arithmetic mean of valid values | `skipna=true` |
| `weighted_mean` | mean weighted by per-row `weight` column (provider-supplied) | `skipna=true` |
| `median` | sample median | `skipna=true` |
| `vote` | majority vote (classification only); ties broken by sorted class id | undefined classes refused |
| `robust_mean` | trimmed mean: drop the top/bottom `trim_fraction` (default `0.1`) before averaging | `skipna=true` |
| `exclude_outliers` | drop rows where the per-row prediction is outside `Hotelling T²` confidence boundary at `threshold` (default `0.95`), then `mean` | `skipna=true` |

Each reducer is declared in `dag-ml-data-core::aggregation.rs` and the conformance pack (`docs/contracts/conformance_pack.v1.json`) — same enum surface in Rust, C ABI, and JSON. Bindings expose them by name; custom reducers go through a host-controller path with an explicit `custom_reducer_id` field so the bundle can still replay deterministically.

### Implementation notes

- Tolerance vs. legacy: `robust_mean` and `exclude_outliers` use the **same numerical implementation** as nirs4all's current implementation; the bridge ports the code, doesn't re-derive.
- `vote` works on classification predictions; the reducer is refused on regression with `IncompatibleReducer` (the bridge surfaces this at compile time).
- Per-sample aggregation respects the augmentation-origin invariant (ADR-04): augmented rows aggregate up to their origin sample, never to a different sample.

## Consequences

- `dag-ml-data`'s `AggregationPolicy` accepts the six canonical reducer names; anything else falls through to a host-controller call.
- `nirs4all`'s `RunResult.top(n)` ranking respects the configured reducer (e.g. classification with `vote` ranks by accuracy, not RMSE).
- The parity oracle's `aggregation_rep_*` cases pin the exact reducer behavior; the parity manifest records expected aggregated values.

## Risk

- `Hotelling T²` requires per-sample inverse covariance; numerically unstable on small samples. The reducer falls back to `robust_mean` with a logged warning when the covariance condition number exceeds `1e10`.