This commit is contained in:
ao gong
@@ -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`，不要在核心层直接写数据库。
|
||||
@@ -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` 持久化和展示；核心层继续保持无数据库写入。
|
||||
@@ -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。
|
||||
Reference in New Issue
Block a user