54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# 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`: 529 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`；无正组合方差时拒绝产物。
|
||
- `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。
|
||
- shrinkage 适配器本轮不实现：scikit-learn 尚非声明依赖，未来只允许薄适配
|
||
`LedoitWolf` / `OAS`，不复制公式、不依赖环境偶然安装状态。
|
||
|
||
## Next action
|
||
|
||
保持 Draft PR #5，不绕过堆叠顺序合并；下游 `research_results` / `research_platform`
|
||
继续在现有 Draft 分支消费同一数据 lineage。下一阶段优先把 ingestion snapshot ID 从
|
||
真实 ELT 元数据接入调用方，再在依赖治理通过后单独交付可选 shrinkage adapter。
|