Add normalized correction metrics to the inference aggregators

[jpdunc23]

Corrector-equipped runs currently write their per-step correction deltas to autoregressive_step_diagnostics.nc but log no metrics about them, so there is no at-a-glance answer to "how much does this model lean on its corrector?". This PR adds normalized-space correction metrics to both inference aggregators, computed from the StepDiagnostics attached to prediction data: an area-weighted global mean of the time-mean |normalized correction| per corrected variable (plus an opt-in signed time-mean map image) under the existing time_mean_norm group, and per-forecast-step area-weighted magnitude/std series under mean_norm. The normalized correction is normalize(delta, apply_mean=False) — i.e. delta / std, using the apply_mean option from #1353, since mean-centering a difference quantity would wrongly subtract the per-variable mean offset; all reductions go through the mask-aware GriddedOperations, so NaN off-mask cells drop out of the scalars. Metrics are uniform over all corrected variables and silent when no corrector ran (or in coupled inference, which does not attach step diagnostics). Inline training keeps the time-mean metrics but drops the per-step series, matching the existing time-series behavior.

The wiring mirrors the StepDiagnostics container rather than its current contents: each host aggregator carries a single optional StepDiagnosticsAggregator — a concrete wrapper owning a dict of per-concern sub-aggregators (one entry today — the correction-delta aggregator) and fanning record/log/flush out over it — so future StepDiagnostics fields get sibling entries inside the wrapper instead of more host surgery. Granular sub-aggregators for specific container fields (just delta, for now) live another level down and are equally invisible to the hosts.

Changes:

• fme.ace.aggregator.inference.step_diagnostics (new): the StepDiagnosticsAggregator wrapper, the StepDiagnosticsSubAggregator protocol, StepDiagnosticsMetricConfig, the CorrectionDeltaAggregator, and its granular CorrectionDeltaTimeMeanAggregator / CorrectionDeltaMeanAggregator sub-aggregators

• InferenceEvaluatorAggregatorConfig.step_diagnostics and InferenceAggregatorConfig.step_diagnostics: new StepDiagnosticsMetricConfig fields controlling metric granularity — correction_scalars (default on) and correction_maps (default off)

• Both inference aggregators gain step_diagnostics_aggregator: StepDiagnosticsAggregator | None = None and delegate record/log/flush to it

• InferenceAggregatorConfig.build gains an optional normalize argument (default None); the no-target inference entrypoint now passes stepper.normalizer.normalize. With no normalizer, a default step_diagnostics config silently skips the correction metrics (preserving current behavior for callers that omit normalize, e.g. the coupled builder), while an explicitly non-default config raises rather than silently dropping an opt-in

• reduced.py's series-assembly dataclass is public (SeriesData), and CorrectionDeltaTimeMeanAggregator raises if a batch changes the sample count or variable set mid-accumulation instead of silently biasing the time-means

• Tests added

• If dependencies changed, "deps only" image rebuilt and "latest_deps_only_image.txt" file updated

[jpdunc23]

Pre-review agent: I ran a pre-review audit of this PR ahead of human review, in a clean session separate from the one that built the change. All 19 new tests pass locally and ruff/mypy are clean. Three observations for the reviewer, none blocking:

1. Silent skip when no normalizer is supplied. StepDiagnosticsMetricConfig.build returns None whenever normalize is None, including when the user explicitly enabled correction_scalars/correction_maps. Both in-repo entrypoints now pass a normalizer, and the behavior is documented in the config docstring, but an explicit opt-in being silently dropped (rather than raising) is a deliberate trade-off the reviewer may want to sign off on.
2. Unguarded accumulation invariants in CorrectionDeltaTimeMeanAggregator. record_batch overwrites self._n_samples on every call and divides each variable's accumulated sum by the global timestep count, which assumes a constant sample count and a constant variable set across windows. The current inference loop guarantees both, but nothing asserts them — a future caller violating either would get silently biased time-means rather than an error.
3. Multi-window accumulation is untested. No test records two batches into the time-mean aggregator, so the accumulation arithmetic in (2) is exercised only for the single-window case. A two-call test with a hand-computed expected mean would lock it down.

Minor: step_diagnostics.py imports the private _SeriesData from reduced.py — the only cross-module use of that private name; consider making it public.

— 🤖 Drafted by Claude (Fable 5) via Claude Code, posted on @jpdunc23's behalf.

[jpdunc23]

1. Silent skip when no normalizer is supplied. StepDiagnosticsMetricConfig.build returns None whenever normalize is None, including when the user explicitly enabled correction_scalars/correction_maps. Both in-repo entrypoints now pass a normalizer, and the behavior is documented in the config docstring, but an explicit opt-in being silently dropped (rather than raising) is a deliberate trade-off the reviewer may want to sign off on.

I think we already have precedents of raising errors in the aggregators when user config and build-time data availability are mismatched. Should we do the same here?

2. Unguarded accumulation invariants in CorrectionDeltaTimeMeanAggregator. record_batch overwrites self._n_samples on every call and divides each variable's accumulated sum by the global timestep count, which assumes a constant sample count and a constant variable set across windows. The current inference loop guarantees both, but nothing asserts them — a future caller violating either would get silently biased time-means rather than an error.

Is this a preexisting issue in other time mean aggregators? If not, we should follow their prior art. If so, do we just need to provide some better documentation of the record_batch assumptions?

3. Multi-window accumulation is untested. No test records two batches into the time-mean aggregator, so the accumulation arithmetic in (2) is exercised only for the single-window case. A two-call test with a hand-computed expected mean would lock it down.

Let's add this test.

Minor: step_diagnostics.py imports the private _SeriesData from reduced.py — the only cross-module use of that private name; consider making it public.

Let's make it public.

[jpdunc23]

All four addressed in cd6dd05:

1. Followed the existing precedent, with one nuance: StepDiagnosticsMetricConfig.build now raises ValueError when the configuration was explicitly changed from the defaults but no normalizer is supplied. The default configuration (scalars on) keeps the silent skip — raising unconditionally would break the coupled inference aggregator builder, which constructs the per-component InferenceAggregatorConfig with defaults and no normalizer.
2. Partially preexisting: TimeMeanAggregator sets its sample count once rather than overwriting it, and a changed variable set there fails with a KeyError rather than biasing. I brought the correction time-mean aggregator up to (slightly beyond) that bar: record_batch documents its contiguous-windows assumptions and raises ValueError if a batch changes the sample count or the variable set mid-accumulation.
3. Added a two-window accumulation test with a hand-computed expected mean over unequal window lengths, plus tests for the two new invariant errors and the build-time error.
4. Renamed to public SeriesData.

— 🤖 Drafted by Claude (Fable 5) via Claude Code, posted on @jpdunc23's behalf.

[mcgibbon]

LGTM, only optional comments.

[mcgibbon]

Suggestion (optional): Use StepDiagnosticsSubAggregator = CorrectionDeltaAggregator (or whatever the correct form is for type variable assignment, and update this to equal the union of types when we have more than one such example. Or I don't mind you leaving it as-is, especially if this is replicating an existing pattern.

Optional: If you want a stronger guarantee that new implementations have the API, you could use an ABC instead of protocol.