feat(forecast): feature-aware forecasting foundation — shared feature-frame contract

[w7-mgfcode]

Implements PRPs/PRP-29-feature-aware-forecasting-foundation.md — the first PRP of the Advanced ML Model Zoo sequence (MLZOO-A). Closes #238.

What

Consolidation + contracts + tests + docs only — no new model, no new dependency, no migration, no API/schema/WebSocket change. User-visible behaviour is identical.

• New app/shared/feature_frames/ package — the single source of truth for the regression feature-frame contract: pinned constants (EXOGENOUS_LAGS, HISTORY_TAIL_DAYS), the canonical column set + order, the FutureFeatureFrame carrier, the leakage-safe pure builders (build_calendar_columns, build_long_lag_columns), and the FeatureSafety taxonomy. Leaf-level — imports nothing from app/features/** (enforced by an AST-walk test).
• Eliminates the duplicated contract — _REGRESSION_FEATURE_COLUMNS (forecasting) and canonical_feature_columns() (scenarios) were physically duplicated and kept in sync only by an integration-test side-effect. Both slices now import the one shared definition; a column-order mismatch is structurally impossible.
• BaseForecaster.requires_features: ClassVar[bool] — False for the baselines, True for RegressionForecaster. ForecastingService.train_model/predict branch on this flag instead of a model_type string check.
• scenarios/feature_frame.py imports + re-exports the shared contract (via __all__); keeps only the assumption-driven, DB-touching parts.
• forecasting/service.py — pure _assemble_regression_rows helper extracted so the historical-frame leakage spec needs no DB.
• Load-bearing leakage specs — app/shared/feature_frames/tests/test_leakage.py (shared builders) + app/features/forecasting/tests/test_regression_features_leakage.py (historical builder); backtesting loud-fail guard test pins that feature-aware backtesting raises until PRP-MLZOO-B.
• Docs — new examples/models/feature_frame_contract.md; additive model_interface.md update.

Validation

• ✅ ruff check + format clean
• ✅ mypy --strict + pyright --strict — 0 errors (268 files)
• ✅ pytest -m "not integration" — 1306 passed
• ✅ pytest -m integration app/features/scenarios/ app/features/forecasting/ — 28/28 (incl. the empty-assumption model_exogenous zero-delta drift detector)
• ✅ grep _REGRESSION_FEATURE_COLUMNS app/ — empty (single source of truth)
• ✅ Baseline-forecaster tests + test_regression_forecaster.py pass with no edits
• ✅ no new dependency · no Alembic migration · no route/schema/WS change

Notes

The MLZOO-B/C/D sequence (LightGBM/sklearn first model, XGBoost/Prophet, frontend/registry/explainability) is gated on this PR merging — see PRPs/INITIAL/INITIAL-MLZOO-index.md.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 25affc8f-cd44-44b7-98f4-06215bd65a09

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/feature-aware-forecasting-foundation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery