# Research artifact contract handoff

## Goal

把完整可信研究链固化成存储中立、版本化、确定性的 `ResearchRunArtifact`，供
`research_results` 持久化和 `research_platform` 查询：

- run identity / schema version / config hash / code revision / data snapshot；
- signal scores / decision weights / signal-to-execution mapping；
- NAV / returns / benchmark / costs；
- trades / realized positions / cash；
- asset and daily return attribution；
- performance including Sortino / TE / IR / alpha / beta；
- reproducible covariance snapshots and annualized Euler component-risk facts；
- canonical JSON / SHA-256 manifest。

## Branch stack

- 当前：`codex/research-artifact-contract-20260821`
- 基线：`codex/ledger-attribution-20260821`（Draft PR #4）
- 下层：Draft PR #3 → Ready PR #2 → `main`

不得绕过堆叠顺序直接合并到 `main`。

## Verification

- `pytest -q`: 526 passed，9 个既有 SciPy warning；
- risk/artifact focused coverage 87.85%；
- `mypy --strict src/`: 16 source files passed；
- changed-scope Ruff: passed；
- no runtime dependency added；
- no database, network, broker or filesystem write side effect in artifact builder。

## Current risk contract

- artifact schema：`1.1.0`；
- `CovarianceSnapshot` 对输入矩阵深拷贝并显式记录截至日、频率和年化期数；
- `risk_snapshots` 按研究交易日映射，可只生成需要的风险观察日；
- 使用成交后实际持仓，不包含现金风险资产；协方差资产标签必须与研究资产全集一致；
- `covariance_as_of_date` 不得晚于 `trade_date`；无正组合方差时拒绝产物。

## Next action

保持 Draft PR #5，不绕过堆叠顺序合并；下游 `research_results` / `research_platform`
已在各自 Draft 分支兼容 1.0.0 / 1.1.0，下一阶段以真实数据适配器提供可复现协方差快照。