quant_engine/docs/handoff/2026-08-21-research-artifact-contract.md

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，下一阶段以真实数据适配器提供可复现协方差快照。