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