wip: hand off research artifact contract

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

@@ -0,0 +1,37 @@
+# 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 做契约测试，不接触真实数据库。