feat(quant): consolidate research artifact contract (#7)

docs/OPEN_SOURCE_REFERENCES.md

@@ -0,0 +1,64 @@
+# Open-source design references
+
+本项目采用“借鉴稳定语义、保留轻量实现”的策略。引入新量化能力前先检查成熟
+开源案例；除非维护成本和许可证收益明确优于本地小型实现，否则不增加框架级依赖。
+
+## 2026-08-21：成交后归因与相对绩效
+
+| 项目 | 借鉴内容 | 当前决策 |
+|---|---|---|
+| [Qlib](https://github.com/microsoft/qlib) | 信号时间与交易时间分离、成本前后超额收益分开报告 | 借鉴语义；不引入完整框架 |
+| [Zipline](https://github.com/quantopian/zipline) | Ledger / transaction / portfolio value 状态模型 | 以现有 `ExecutionSimulationResult` 承担事实源 |
+| [empyrical](https://github.com/quantopian/empyrical) | beta 协方差口径、alpha 几何年化、年化因子 | 移植小型公式；不增加老旧运行时依赖 |
+| [Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib) | Euler component risk 与分组/因子风险贡献 | 只实现当前需要的 pandas/numpy 标签安全封装 |
+| [PyPortfolioOpt](https://github.com/PyPortfolio/PyPortfolioOpt) | 协方差估计与优化器解耦 | 留作未来风险模型适配器参考 |
+
+当前核心不新增依赖。逐日收益归因必须从实际换仓前后持仓、成交记录、执行价和
+收盘估值推导；因子分数与目标权重只是意图，不能作为成交后归因事实源。
+
+## 2026-08-21：研究运行工件
+
+- 借鉴 [Qlib Recorder / RecordTemplate](https://github.com/microsoft/qlib/blob/main/qlib/workflow/record_temp.py)
+  将 signal、portfolio analysis 和 risk analysis 分成稳定事实，但不引入 Qlib 运行时；
+- 借鉴 [MLflow Tracking](https://mlflow.org/docs/latest/tracking/) 的 run / params /
+  metrics / artifacts 分层，但 MLflow 只保留为未来可选 exporter；
+- HTML、PNG 和 tearsheet 是可再生展示物，不能替代 NAV、成交、持仓、归因和绩效事实。
+
+因此 `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。未来日期、资产
+标签不完整和零方差组合都直接失败，不以默认值伪造结果。
+
+## 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，追加未来数据不会改变历史快照。
+
+市场适配层现以 `AssetReturnSnapshot` 固化 simple-return 输入：上游 ingestion snapshot ID、
+数据源、价格字段、复权口径、规范化价格值和缺失掩码共同形成内容寻址 ID；不前向填充
+停牌/缺失价格。该 ID 同时传入协方差快照和研究运行工件，避免同一研究链出现两套数据
+身份。
+
+可选 shrinkage adapter 的评估结论是“保留边界，暂不实现”：当前运行依赖没有声明
+scikit-learn，本切片也不修改版本或锁文件。未来只有在依赖治理接受后，才以延迟导入
+直接调用 scikit-learn 的 `LedoitWolf` / `OAS`，并让估计器名称、库版本与参数进入
+snapshot identity；不复制成熟统计公式，也不让环境中偶然存在的包改变 baseline 行为。
+
+## hikyuu 的定位
+
+[hikyuu](https://github.com/fasiondog/hikyuu) 的 SG / MM / CN / PG 部件化思想、
+A 股交易约束和系统组合方式仍有借鉴价值；但其完整 C++/Python 运行时、对象模型和
+数据体系不适合作为本项目核心依赖。当前原则是按真实研究链路吸收边界设计，不复制
+其框架层级，也不为了“架构完整”预先建设尚无端到端需求的抽象。

docs/handoff/2026-08-21-ledger-attribution.md

@@ -0,0 +1,42 @@
+# Ledger-backed attribution handoff
+
+## Goal
+
+在 `ExecutionSimulationResult` 日频 Ledger 之上增加轻量、可审计的成交后分析层：
+
+- 逐日隔夜 / 日内资产收益贡献；
+- 佣金、印花税、滑点成本独立贡献；
+- 贡献闭合到成本后日收益并显式暴露 residual；
+- 严格日期对齐的 TE / IR / alpha / beta；
+- 标签安全且可分组的 Euler component risk。
+- 从 Ledger 股数和收盘估值投影的实际资产 / 现金权重。
+
+## Branch stack
+
+- 当前：`codex/ledger-attribution-20260821`
+- 基线：`codex/post-execution-ledger-20260821`
+- 再下层：`codex/core-contracts-20260821`（PR #2，尚待用户确认合并）
+
+本分支不得直接合并到 `main`。应按上述顺序逐层审阅；未经用户明确确认，不得合并
+L2 PR。
+
+## Open-source decision
+
+调研结论记录在 `docs/OPEN_SOURCE_REFERENCES.md`。Qlib、Zipline、empyrical、
+Riskfolio-Lib 和 PyPortfolioOpt 只作为时间语义、Ledger、相对指标与 Euler 风险贡献
+的设计参考；本阶段没有新增运行时依赖。
+
+## Verification
+
+- `pytest -q --cov=src --cov-report=term-missing`: 514 passed，9 个既有 SciPy warning，91% coverage；
+- `mypy --strict src/`: 15 source files passed；
+- 变更范围 `ruff check`: passed；
+- 全仓 Ruff：仅 13 个既有 `tests/governance/*` PT009；
+- workspace verify/status：passed，预期提示 quant_engine 非 main；
+- global Gitea workflow check：passed，23 个无关仓库 warning。
+
+## Next action
+
+先按堆叠顺序审阅 PR。基础 Ledger 分支完成后，再将本分支 rebase 到其最终提交，
+运行唯一一次 `ship --ready`；随后将稳定输出适配到 `research_results` 与
+`research_platform`，不要在核心层直接写数据库。

docs/handoff/2026-08-21-post-execution-ledger.md

@@ -0,0 +1,33 @@
+# Post-execution daily Ledger handoff
+
+## 状态
+
+- 分支：`codex/post-execution-ledger-20260821`
+- 基线：`codex/core-contracts-20260821`（PR #2，尚未获用户确认合并）
+- 本分支不得直接合并到 `main`；先等待 PR #2 合并，再整理基线并创建独立 PR。
+- 无账户、券商、数据库或实盘副作用。
+
+## 已完成
+
+- 新增稀疏调仓、完整交易日估值的 `simulate_daily_ledger_with_audit()`。
+- 显式分离 execution price 与 valuation price，支持下一日 open 成交、当日 close 估值。
+- 成交记录补齐 `side / quantity / price`，并提供 `trades_frame`。
+- 提供平台中立的 `ledger_frame`，不携带 `run_id`，不写数据库。
+- 新增 `run_factor_backtest_research()`：PIT 因子、下一交易日执行、日频 NAV、首日成本收益和标准绩效。
+- 研究区间从首条有效信号日开始，排除因子预热行情对绩效的稀释。
+
+## 验证
+
+- `pytest -q --cov=src --cov-report=term-missing`：500 passed，total coverage 91%。
+- `mypy --strict src/`：14 source files passed。
+- 本阶段文件 scoped Ruff：passed。
+- 全仓 Ruff：仅既有 governance tests 的 13 个 PT009 基线问题。
+- workspace verify/status：通过；仅提示功能分支不是引导基线 `main`。
+- 全局 Gitea workflow check：通过，23 个既有警告。
+
+## 继续步骤
+
+1. 获得用户对 PR #2 的明确合并确认并按 L2 流程合并。
+2. 将本分支整理到更新后的 `main`，重新运行相同全量验证。
+3. 为 Ledger 阶段创建独立 PR，执行唯一一次最终 `ship --ready`，等待用户确认合并。
+4. 后续在 `research_results` 增加业务投影适配器，再由 `research_platform` 持久化和展示；核心层继续保持无数据库写入。

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

@@ -0,0 +1,57 @@
+# 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`: 540 passed，9 个既有 SciPy warning；
+- data-adapter focused coverage 77%（包含未连接真实 ClickHouse 的 I/O 便捷函数）；
+- `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。
+- 三仓隔离 ClickHouse 黄金链路通过：市场价格 → return snapshot → covariance → artifact →
+  publisher → reader；使用随机 localhost 端口、tmpfs 和自动容器清理。
+
+## 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。
+- artifact builder fail closed：每个 `CovarianceSnapshot.data_snapshot_id` 必须与 run 级
+  `data_snapshot_id` 完全一致，禁止把其他行情快照的风险分解静默发布到当前研究运行。
+- shrinkage 适配器本轮不实现：scikit-learn 尚非声明依赖，未来只允许薄适配
+  `LedoitWolf` / `OAS`，不复制公式、不依赖环境偶然安装状态。
+
+## Next action
+
+保持 Draft PR #5，不绕过堆叠顺序合并；下游 `research_results` / `research_platform`
+继续在现有 Draft 分支消费同一数据 lineage。下一阶段优先把 ingestion snapshot ID 从
+真实 ELT 元数据接入调用方，再在依赖治理通过后单独交付可选 shrinkage adapter。