fix(quantitative): correct CAPM monthly regression

[losterbr]

Description

• Correct CAPM calculations by:
  • Converting asset prices to month-end returns.
  • Aligning returns and Fama-French factors by calendar month.
  • Using Mkt-RF directly instead of subtracting the risk-free rate twice.
• Add named constants and documentation for Fama-French columns.
• Add validation for insufficient observations and constant market returns.
• Make the Fama-French source injectable for deterministic offline tests.
• Clarify that Mkt-RF represents the market excess return, $R_m-R_f$.
• Link issue, if applicable.
• Screenshot, not applicable.
• No new runtime dependencies are required.

Motivation

The previous CAPM implementation combined daily asset returns with monthly
Fama-French factors using exact dates. This could omit months and select
individual daily returns rather than monthly returns.

It also subtracted RF from Mkt-RF, although the Ken French dataset already
defines Mkt-RF as the market return minus the risk-free rate.

How has this been tested?

• Added deterministic tests for:
  • Calendar-month alignment.
  • Month-end price selection.
  • Correct handling of Mkt-RF.
  • Known-beta recovery with nonzero risk-free rates.
  • Insufficient observations and constant market returns.
  • Local ZIP parsing without network access.
  • CAPM router orchestration.
  • Fama-French query validation and fetcher transformation.
• Ran 25 relevant unit tests successfully.
• Ran a live smoke check against the official Ken French archive:
  • 79 monthly rows processed from January 2020 through July 2026.
• Ran all configured pre-commit hooks:
  • Black
  • Ruff
  • Pylint
  • mypy
  • pydocstyle
  • codespell
  • detect-secrets
• Python command behavior is covered by direct router tests.
• Full repository unit and integration suite will run in CI.
• API integration was not run locally.

Production coverage for the touched modules is 94%.

Checklist

• I have performed a self-review of my code.
• I have commented the month-end aggregation behavior.
• I have adhered to the GitFlow branch naming convention.
• I have followed the contributing guidelines.
• I have added tests for the modified command and provider behavior.

[CLAassistant]

All committers have signed the CLA.