docs: record covariance estimator decision

README.md

@@ -139,15 +139,15 @@ print(factor_backtest.benchmark_stats(benchmark_returns))
 
 # 下游稳定交付：显式提供代码版本、数据快照和时区，不在核心层写数据库。
 from quant_engine.artifact import build_research_run_artifact
-from quant_engine.risk import CovarianceSnapshot
+from quant_engine.risk import estimate_covariance_snapshot
 
 risk_date = factor_backtest.position_weights.index[-1].date()
-risk_snapshot = CovarianceSnapshot(
+risk_snapshot = estimate_covariance_snapshot(
-    snapshot_id="<covariance-snapshot-id>",
+    daily_asset_returns,
     as_of_date=risk_date,
-    covariance=daily_return_covariance,
+    lookback_sessions=252,
-    return_frequency="1d",
+    min_observations=120,
-    periods_per_year=252,
+    data_snapshot_id="<risk-return-data-snapshot-id>",
 )
 
 artifact = build_research_run_artifact(

docs/OPEN_SOURCE_REFERENCES.md

@@ -33,6 +33,19 @@ component-risk 语义结合，但只保留本项目需要的轻量合同：协
 component risk 闭合到年化组合波动，percentage contribution 闭合到 1。未来日期、资产
 标签不完整和零方差组合都直接失败，不以默认值伪造结果。
 
+## 2026-08-21：协方差快照估计
+
+| 项目 | 借鉴内容 | 当前决策 |
+|---|---|---|
+| [PyPortfolioOpt risk models](https://github.com/PyPortfolio/PyPortfolioOpt/blob/main/pypfopt/risk_models.py) | 将收益输入、协方差估计器和组合优化解耦；sample / EWM / shrinkage 使用统一标签输出 | 借鉴可替换估计器边界，不引入完整包 |
+| [scikit-learn covariance](https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/covariance/_shrunk_covariance.py) | 维护成熟的 Ledoit–Wolf / OAS shrinkage 实现 | 未来作为可选 adapter；不复制统计公式 |
+| [Qlib structured risk model](https://github.com/microsoft/qlib/blob/main/qlib/model/riskmodel/structured.py) | PCA/FA 结构化协方差和固定随机状态 | 留作因子风险模型阶段，不进入当前 baseline |
+
+当前 `estimate_covariance_snapshot` 只编排 pandas 的 sample covariance：先按 `as_of_date`
+截断，再取固定 session 窗口，使用 complete-case 行并拒绝历史不足；禁止 pandas 默认的
+pairwise 样本集合产生含义不一致的矩阵。snapshot ID 对窗口数据、缺失掩码、上游数据
+快照身份和估计参数做 SHA-256，追加未来数据不会改变历史快照。
+
 ## hikyuu 的定位
 
 [hikyuu](https://github.com/fasiondog/hikyuu) 的 SG / MM / CN / PG 部件化思想、

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

@@ -24,7 +24,7 @@
 
 ## Verification
 
-- `pytest -q`: 526 passed，9 个既有 SciPy warning；
+- `pytest -q`: 529 passed，9 个既有 SciPy warning；
 - risk/artifact focused coverage 87.85%；
 - `mypy --strict src/`: 16 source files passed；
 - changed-scope Ruff: passed；
@@ -38,8 +38,11 @@
 - `risk_snapshots` 按研究交易日映射，可只生成需要的风险观察日；
 - 使用成交后实际持仓，不包含现金风险资产；协方差资产标签必须与研究资产全集一致；
 - `covariance_as_of_date` 不得晚于 `trade_date`；无正组合方差时拒绝产物。
+- `estimate_covariance_snapshot` 从显式数据快照的日收益生成无前视、complete-case、
+  SHA-256 可复现的 per-period sample covariance；不包含 I/O 或未来行。
 
 ## Next action
 
 保持 Draft PR #5，不绕过堆叠顺序合并；下游 `research_results` / `research_platform`
-已在各自 Draft 分支兼容 1.0.0 / 1.1.0，下一阶段以真实数据适配器提供可复现协方差快照。
+已在各自 Draft 分支兼容 1.0.0 / 1.1.0，下一阶段让市场数据适配器提供带稳定
+`data_snapshot_id` 的资产日收益，再评估可选 scikit-learn shrinkage adapter。