docs: record dated dividend cash-flow ledger session (2026-08-27)

docs/HANDOFF.md

@@ -193,6 +193,31 @@ Implement dated dividend events and a provenance-validated PIT score provider be
 
 ---
 
+## Session 2026-08-27 — Dated dividend cash-flow ledger (verified + pushed)
+
+**Branch:** main · **HEAD:** 5b8b6d1 (pushed `068dff2` + `5b8b6d1`; backend `068dff2`, frontend `5b8b6d1`)
+
+### Completed this session (verified + pushed)
+- **Dated dividend ledger** `backend/app/dividend_ledger.py`: per-symbol dated store with `ex_date` / `record_date` / `pay_date` / `per_share` / `source` / `estimate` flag, validation and persistence. `credit_dividends` credits `per_share × qty` once a payment is due (on/after ex-date and pay date); no ledger entry → no credit (fail closed). `build_dps_ledger` builds per-share estimate rows from the siamchart `ratios.DPS` (price-independent, a step up from the yield % × market-value proxy).
+- **Backtest integration** `backend/app/backtest.py`: `run_backtest` accepts `dividend_ledger`; `dividend_income` comes from the ledger when set and `dividend_method` reports `dated_ledger` (real rows) | `dps_annual_proxy` (estimate) | `final_holdings_yield_proxy` (legacy, kept when no ledger). `BacktestResult` gained a `dividend_method` field surfaced in `to_dict`.
+- **API** `backend/app/__init__.py`: `POST /api/v1/backtest` accepts `use_ledger`, wiring the DPS-built ledger (works independently and alongside `use_pit`).
+- **Frontend** `frontend/src/App.vue`: maps `dividend_method` to an honest Thai label (ปันผล (ตามวันจริง) / ประมาณการปันผล/หุ้น (DPS) / ประมาณการปันผล (Proxy)) and shows a **Proxy** badge whenever the dividend is an estimate, on both the result card and saved-run history rows.
+
+### Verified
+- Backend full suite **266 passed** (was 255); new: ledger store/credit (9) + backtest ledger integration (2).
+- compileall, `git diff --check`, static secret/dangerous scan clean.
+- Live route probe: `use_ledger:true` → `dividend_method=dps_annual_proxy`, `dividend_income=4151.0` (per-share) vs default proxy `5041.96` (yield×value); price P&L unchanged (5802.89).
+- Frontend build passes (bundle `index-DDD-F_cZ.js`).
+
+### Honest scope / known limitations
+- `build_dps_ledger` rows are **estimates** (no ex-date history in the snapshot) — `dividend_method=dps_annual_proxy`, flagged Proxy in UI. A symbol only reports `dated_ledger` once real ex-date/per-share history is collected for it.
+- Ledger credit is end-of-run on final holdings for this milestone (not mid-window on holdings-at-ex-date); a future pass can accrue per rebalance window as ex-date history arrives.
+
+### Exact next action
+Add a real per-stock **dividend-history collector** (siamchart `/stock-info/<SYMBOL>/`) that appends dated payments into the ledger so symbols can upgrade from `dps_annual_proxy` to `dated_ledger`. In parallel, add the **siamchart vintage chain** to un-partial the fundamental dimension. Do not reset or stage unrelated pre-existing working-tree changes.
+
+---
+
 ## Session 2026-08-27 — PIT factor store + partial PIT score provider (verified + pushed)
 
 **Branch:** main · **HEAD:** 1f630be (pushed `1b971ac..1f630be`)

docs/engineering-log.md

@@ -99,3 +99,4 @@
 - Follow-up (A+B): theme surprises now weight-normalized by total |weight| so cross-theme magnitudes are comparable (retail 0.189->0.145). Added append-only `FactorHistory` store (`data/factor_history/<key>.jsonl`) that records every FACTORS value each scheduler run, wired into `refresh_all` (non-fatal), plus `/api/v1/learning/factors` readiness endpoint. Macro/demographic factors start at n=1 and become learnable (P4) as history accumulates. 233 tests pass.
 - Backtest accounting remediation (2026-08-27): deterministic flat-price tests exposed that ending holdings value was reported as `price_pnl` and the dividend proxy was excluded from final value/net return. The corrected identity is `final_value = capital + price_pnl + dividend_income`; API now emits `dividend_method=final_holdings_yield_proxy`, and both result/history UI paths label the proxy and warn when `leakage_guard=false`. RED failures reproduced `price_pnl=20,000/49,000`; GREEN verification: 239 backend tests, compileall, Vite build, npm audit 0 high-severity vulnerabilities, served-bundle disclosure check, static scan and diff check passed. Fresh final independent review `deleg_10918fed` passed with empty blocker arrays. Evidence: `docs/engineering-log/2026-08-27-backtest-accounting-remediation.md` and `docs/test-evidence/2026-08-27-backtest-accounting-remediation.md`. The dividend model remains a proxy and the default public backtest remains descriptive non-PIT.
 - PIT factor store + partial score provider (2026-08-27, commit `1f630be`): added `factor_vintages.py` (append-only PIT factor store: observed/released/retrieved_at + SHA-256 hash chain; `value_at(as_of)` anti-look-ahead, fail-closed when nothing released by as_of) and `pit_scorer.py` (`PitScoreProvider.score_board(as_of)` + `make_pit_score_fn`). `backtest._resolve_scores` now sets `leakage_guard=True` only when the supplied score_fn asserts `pit_meta.pit=True` (closes "any callable ⇒ PIT"); `/api/v1/backtest` accepts `use_pit`. Empty factor store fail-closes (live probe `leakage_guard=false`). Full backend **255 passed** (was 239). Honest scope: theme dimension PIT from this store forward; no factor history before 2026-08-27 so pre-today backtests stay non-PIT; siamchart fundamental partial (EPS 5-yr series PIT-grade, ratios current → `partial_pit`). Next: dated dividend cash-flow ledger.
+- Dated dividend cash-flow ledger (2026-08-27, commits `068dff2` + `5b8b6d1`): added `dividend_ledger.py` (per-symbol dated store: ex_date/record_date/pay_date/per_share/source/estimate flag; `credit_dividends` credits per_share×qty when payment due, fail-closed with no entry; `build_dps_ledger` builds per-share estimate rows from siamchart ratios.DPS). `run_backtest` accepts `dividend_ledger` and reports `dividend_method` = `dated_ledger` (real rows) | `dps_annual_proxy` (estimate) | `final_holdings_yield_proxy` (legacy). `/api/v1/backtest` accepts `use_ledger`. Frontend maps method to an honest Thai label + Proxy badge on result card and history rows. Full backend **266 passed** (was 255). Honest scope: DPS rows are estimates (no ex-date history in snapshot yet); real dated cash flows require collecting per-stock dividend history, which upgrades a symbol to `dated_ledger`.