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；
• reserved risk snapshot table；
• 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 --cov=src --cov-report=term-missing: 520 passed，9 个既有 SciPy warning；
• total coverage 91%，artifact.py 91%；
• 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。

Next action

在 research_results 新建独立分支，实现只接受 ResearchRunArtifact.table_frames() 的 ClickHouse / artifact-store adapter；先以 mock writer 做契约测试，不接触真实数据库。