From dc67f0e9829a9fc580a6aa0f9baa04cc4069894c Mon Sep 17 00:00:00 2001
From: ao gong <41768719+ageorge156@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:41:21 +0800
Subject: [PATCH] docs: record reproducible risk artifact contract

---
 README.md                                      | 11 +++++++++++
 docs/OPEN_SOURCE_REFERENCES.md                 |  6 ++++++
 .../2026-08-21-research-artifact-contract.md   | 18 +++++++++++++-----
 3 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4e8049e..5d652d7 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,16 @@ print(factor_backtest.benchmark_stats(benchmark_returns))
 
 # 下游稳定交付：显式提供代码版本、数据快照和时区，不在核心层写数据库。
 from quant_engine.artifact import build_research_run_artifact
+from quant_engine.risk import CovarianceSnapshot
+
+risk_date = factor_backtest.position_weights.index[-1].date()
+risk_snapshot = CovarianceSnapshot(
+    snapshot_id="<covariance-snapshot-id>",
+    as_of_date=risk_date,
+    covariance=daily_return_covariance,
+    return_frequency="1d",
+    periods_per_year=252,
+)
 
 artifact = build_research_run_artifact(
     factor_backtest,
@@ -156,6 +166,7 @@ artifact = build_research_run_artifact(
     parameters={"top_k": 20, "lag_sessions": 1},
     benchmark_id="000300.SH",
     benchmark_returns=benchmark_returns,
+    risk_snapshots={risk_date: risk_snapshot},
 )
 print(artifact.manifest())
 
diff --git a/docs/OPEN_SOURCE_REFERENCES.md b/docs/OPEN_SOURCE_REFERENCES.md
index a282955..e4d66c4 100644
--- a/docs/OPEN_SOURCE_REFERENCES.md
+++ b/docs/OPEN_SOURCE_REFERENCES.md
@@ -27,6 +27,12 @@
 因此 `ResearchRunArtifact` 使用显式 `schema_version`、`config_hash`、代码版本和数据
 快照身份，并提供确定性 JSON / SHA-256 manifest；核心层仍不写数据库或 artifact store。
 
+schema `1.1.0` 将 Qlib 的独立 risk-analysis artifact 思路与 Riskfolio-Lib 的 Euler
+component-risk 语义结合，但只保留本项目需要的轻量合同：协方差快照必须声明
+`snapshot_id`、`as_of_date`、收益频率和年化期数；风险从成交后的实际日末持仓计算，
+component risk 闭合到年化组合波动，percentage contribution 闭合到 1。未来日期、资产
+标签不完整和零方差组合都直接失败，不以默认值伪造结果。
+
 ## hikyuu 的定位
 
 [hikyuu](https://github.com/fasiondog/hikyuu) 的 SG / MM / CN / PG 部件化思想、
diff --git a/docs/handoff/2026-08-21-research-artifact-contract.md b/docs/handoff/2026-08-21-research-artifact-contract.md
index f982f99..c3d9582 100644
--- a/docs/handoff/2026-08-21-research-artifact-contract.md
+++ b/docs/handoff/2026-08-21-research-artifact-contract.md
@@ -11,7 +11,7 @@
 - trades / realized positions / cash；
 - asset and daily return attribution；
 - performance including Sortino / TE / IR / alpha / beta；
-- reserved risk snapshot table；
+- reproducible covariance snapshots and annualized Euler component-risk facts；
 - canonical JSON / SHA-256 manifest。
 
 ## Branch stack
@@ -24,14 +24,22 @@
 
 ## Verification
 
-- `pytest -q --cov=src --cov-report=term-missing`: 520 passed，9 个既有 SciPy warning；
-- total coverage 91%，`artifact.py` 91%；
+- `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
 
-在 `research_results` 新建独立分支，实现只接受 `ResearchRunArtifact.table_frames()` 的
-ClickHouse / artifact-store adapter；先以 mock writer 做契约测试，不接触真实数据库。
+保持 Draft PR #5，不绕过堆叠顺序合并；下游 `research_results` / `research_platform`
+已在各自 Draft 分支兼容 1.0.0 / 1.1.0，下一阶段以真实数据适配器提供可复现协方差快照。