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: 540 passed，9 个既有 SciPy warning；
data-adapter focused coverage 77%（包含未连接真实 ClickHouse 的 I/O 便捷函数）；
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。
三仓隔离 ClickHouse 黄金链路通过：市场价格 → return snapshot → covariance → artifact → publisher → reader；使用随机 localhost 端口、tmpfs 和自动容器清理。

Current risk contract

artifact schema：1.1.0；
CovarianceSnapshot 对输入矩阵深拷贝并显式记录截至日、频率和年化期数；
risk_snapshots 按研究交易日映射，可只生成需要的风险观察日；
使用成交后实际持仓，不包含现金风险资产；协方差资产标签必须与研究资产全集一致；
covariance_as_of_date 不得晚于 trade_date；无正组合方差时拒绝产物。
estimate_covariance_snapshot 从显式数据快照的日收益生成无前视、complete-case、 SHA-256 可复现的 per-period sample covariance；不包含 I/O 或未来行。
prepare_asset_return_snapshot 从规范化长表行情生成不前向填充的 simple daily returns；显式 ingestion snapshot ID、源/字段/复权口径、价格值和缺失掩码共同形成 asset-returns-v1:<sha256>，并把同一 ID 传给 covariance 与 run artifact。
artifact builder fail closed：每个 CovarianceSnapshot.data_snapshot_id 必须与 run 级 data_snapshot_id 完全一致，禁止把其他行情快照的风险分解静默发布到当前研究运行。
shrinkage 适配器本轮不实现：scikit-learn 尚非声明依赖，未来只允许薄适配 LedoitWolf / OAS，不复制公式、不依赖环境偶然安装状态。

Next action

保持 Draft PR #5，不绕过堆叠顺序合并；下游 research_results / research_platform 继续在现有 Draft 分支消费同一数据 lineage。下一阶段优先把 ingestion snapshot ID 从真实 ELT 元数据接入调用方，再在依赖治理通过后单独交付可选 shrinkage adapter。

3.0 KiB Raw Permalink Blame History Unescape Escape