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

Ledger-backed attribution handoff

Goal

在 ExecutionSimulationResult 日频 Ledger 之上增加轻量、可审计的成交后分析层：

• 逐日隔夜 / 日内资产收益贡献；
• 佣金、印花税、滑点成本独立贡献；
• 贡献闭合到成本后日收益并显式暴露 residual；
• 严格日期对齐的 TE / IR / alpha / beta；
• 标签安全且可分组的 Euler component risk。

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: 513 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，不要在核心层直接写数据库。