feat(deterministic): calendar-anchored deterministic climate regressors

[thomaspinder]

Summary

New public module src/impulso/deterministic.py: composable deterministic regressors with deterministic column names, built for the climate workflow the issue describes — and built around the one property that makes them safe to forecast with:

design.build(index[:T+h]).iloc[T:] equals design.extend(index[:T], h) — trends continue their count, harmonics stay in phase, dummies stay calendar-correct. Tested as a single property, parametrised ~90 ways across term types, frequencies, and horizons.

• Terms: Trend(degree≤3, scale), Fourier(period, order) (Nyquist-validated), SeasonalDummies(month|quarter|dayofweek, drop_first), BreakDummy(date, level|pulse). All calendar-anchored via period ordinals — one (origin, alias) resolved from the estimation index makes three of the four terms pure functions of the timestamp, so gaps in the index are handled correctly (a trend jumps across a gap rather than compressing it).
• DeterministicDesign (frozen): build(index) for estimation (with a single rank guard against the always-present intercept — catching drop-first violations, degenerate Nyquist sines, dummies-vs-harmonics overlap, and dead break dummies with targeted messages), extend(index, steps) for the horizon, and exog_future(fitted, steps) which reorders columns by name against fitted.data.exog_names — closing the silent-wrong-forecast path (forecast consumes exog_future positionally).
• Refuse-don't-guess frequency handling: explicit freq → index.freq → pd.infer_freq verified by regenerate-and-compare (it demonstrably lies on short irregular indices) → error. Cycle periods are always explicit. Multiplied offsets (15D, 2h) count in sampling periods, matching the documented contract; off-anchor final timestamps extend without skipping a period.
• In-scope hardening: FittedVAR.forecast now validates exog_future's shape (matching conditional_forecast's existing check) instead of failing with an opaque einsum error.
• Docs: an onboarding how-to ("Deterministic regressors for climate VARs") covering the transform-vs-model routes, the no-NaN order of operations, the column-name contract, and the ConjugateVAR boundary (rejection message quoted verbatim, with both workarounds) — its end-to-end snippet is byte-identical to the slow integration test and says so. Reference page, protocols entry, CONTEXT.md term.

Closes #135

Review

Planned with live pandas 3.0 probes (the datetime64[us] unit trap, Day-not-Tick, infer_freq false positives — all designed around). Independently reviewed: verdict approve after two P2 fixes (multiplied-frequency elapsed counting; off-anchor extension skipping a period), both probe-verified by the reviewer and fixed with exact-arithmetic solutions rather than guards.

Tests

341 tests in tests/test_deterministic.py (incl. one slow MCMC round-trip asserting the design's column names survive into posterior["B_exog"].coords), plus forecast-validation and public-API tests. Coverage on deterministic.py: 99%.

ruff / ty / fast suite: all green (875 passed, 30 deselected). Docs build (warnings-as-errors) clean. (The only local slow-test failure is the known broken-marimo-husk nutpie import in the venv — environmental, affects every slow test in the repo.)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Egjd7ToFeb9TQqFnfRQZxV

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.03150% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.3%. Comparing base (866ca8f) to head (3e747c7).

Files with missing lines	Patch %	Lines
src/impulso/fitted.py	73.3%	2 Missing and 2 partials ⚠️
src/impulso/deterministic.py	99.5%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #191     +/-   ##
=======================================
+ Coverage   95.0%   95.3%   +0.3%     
=======================================
  Files         45      46      +1     
  Lines       3099    3349    +250     
  Branches     380     427     +47     
=======================================
+ Hits        2945    3194    +249     
  Misses       111     111             
- Partials      43      44      +1     

☔ 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.