feat(pooling): static predictive-density pooling

[thomaspinder]

Summary

New public leaf module src/impulso/pooling.py: pool_forecasts(fits, holdout, *, method, density, n_draws, seed) scores each fitted model's predictive density on an explicit held-out VARData window and returns a frozen PredictivePool with normalised weights, the full per-horizon log-score matrix, a pooled predictive sample (as a regular ForecastResult), and optimiser diagnostics. PredictivePool.combine() applies the frozen weights to new forecasts from full-sample refits.

• Two weight methods: "stacking" (default — convex SLSQP solve of the mixture log score on the simplex, log-score-restart on failure, loud RuntimeError if both starts fail) and "log_score" (max-shifted softmax of summed scores, the pseudo-BMA analogue). Both are overflow-safe by construction (per-row max shift) — strictly safer than ArviZ's unshifted exponentiation, and tested as such at ±1e4–1e5 log-score magnitudes.
• Density evaluation: moment-matched joint Gaussian per horizon fitted to each model's forecast draws (density="diagonal" escape hatch), with a min-eigenvalue degeneracy guard that rejects covariances only the jitter makes decomposable. The exact mixture score is deferred behind the same keyword (ADR-0006).
• Hard compatibility validation: ≥2 models, identical ordered variable names, one shared forecast origin, holdout postdating it, date-exact step alignment, and a shared estimation frequency across all fits (mixed monthly/quarterly candidates are rejected in any order). Every rule has an actionable error naming the offending label.
• Determinism: single-seed Generator.spawn contract across member forecasts and the mixture draw; bit-identical under a fixed seed.
• Docs: ADR-0006, docs/reference/pooling.md, a how-to whose fenced examples were executed verbatim and whose tables are real output, CONTEXT.md vocabulary (pool / held-out window / stacking vs log-score / forecast origin), plot_pool_weights.

Closes #151

Review

Planned by a dedicated planning agent (numerics empirically validated against installed arviz/scipy before coding); implementation adversarially reviewed by an independent reviewer that re-derived the stacking first-order conditions and stress-tested the degeneracy guard over 20k adversarial covariance trials. Three P2 findings (mixed-frequency validation hole, doc/number contradiction, reserved-label collision) fixed in a follow-up round; reviewer's enhancement suggestions filed as separate issues.

Conflicts note: trivially overlaps PR #160 in __init__.py, docs/reference/index.md, and CONTEXT.md (additive entries in each).

Tests

103 tests in tests/test_pooling.py plus public-API and plotting additions — all fast, no MCMC. Solvers pinned to closed-form optima (stacking interior optimum 7/9 exact from the KKT conditions; log-score 0.8/0.2), ArviZ az.compare parity for both methods via a constant-log-likelihood shim, a version-proof direct scipy re-solve, mixture membership statistics, RNG spawn-contract reconstruction, and one test per validation rule. pooling.py and plotting/_pooling.py at 100% line+branch coverage.

ruff / ty / fast suite: all green (636 passed, 29 deselected). Docs smoke build clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Egjd7ToFeb9TQqFnfRQZxV

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.5%. Comparing base (866ca8f) to head (1deb946).

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #164     +/-   ##
=======================================
+ Coverage   95.0%   95.5%   +0.4%     
=======================================
  Files         45      47      +2     
  Lines       3099    3430    +331     
  Branches     380     436     +56     
=======================================
+ Hits        2945    3276    +331     
  Misses       111     111             
  Partials      43      43             

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.