feat(ledger): dcy-018 option D cash/position write-back + 추정 현금 (BAT-023)

ledger write 응답의 portfolio-hub 권위 cash/quantity 를 스냅샷에 write-back 해
매수/매도 직후 "수량 live·현금 stale" 비대칭 제거(option D 활성화). portfolio-hub#8
(*_after 응답) 동작 중 확인으로 그간 deferred 됐던 REQ-030 을 닫음.

거버넌스: 전부 change-req (신규 REQ 없음, dcy-018 OQ-3 a).
- REQ-017: record_trade → LedgerWriteOutcome{result, cash_balance_after,
  asset_quantity_after}. 어댑터가 응답 root flat *_after 파싱(new+duplicate, 누락 None)
- REQ-019: LedgerWriter 에 SnapshotStore 주입 → new+duplicate write-back
  (best-effort, *_after 절대값이라 멱등). LedgerOutbox.pending_cash_delta()
- REQ-029: 추정 현금 오버레이(_apply_cash_estimate, cash_estimated 라벨, OQ-4 i)
  + 슬롯 오버레이 유지(OQ-1 B). 미정산 outbox delta 기반, write-back 수렴
- REQ-030: option D 활성화 → Approved→Implemented

best-effort 격리(NFR-1): write-back/추정 실패가 ledger 멱등·청산 무차단.
배치 번호: 동시 커밋된 BAT-022(slot-state, dcy-016)와 충돌해 BAT-023 으로 배정.

검증: 단위 350 passed/35 skipped, 인프라 게이트(PG+RabbitMQ) 385 passed, ruff clean.
신규 test_ledger_option_d + adapter/PG 테스트. BAT-023 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-08 21:50:56 +09:00
co-authored by Claude Opus 4.8
parent 63da87c9b3
commit 2bfecd59a8
26 changed files with 969 additions and 34 deletions
@@ -173,3 +173,43 @@
#### Validation Plan
- 문서 전용 변경. 기존 AC-1~5 테스트 그대로 유효하며 재실행 불필요.
### CHG-20260608-01
- Date: 2026-06-08
- Author: Justin Ko
#### Change Summary
- (change-req, dcy-018) 수량/현금 source 정합: 슬롯 오버레이(REQ-029)는 **유지**(lifecycle 중 슬롯 = 코어 권위 즉시값, 불변식 A). 스냅샷 응답에 미정산 ledger 가 있는 자산은 `cash_balance += pending delta` + `cash_estimated:true` 라벨로 **추정 현금 오버레이**(OQ-4 (i))를 노출하고, option D write-back 도착 시 권위값 수렴. BAT-023 재구현·재검증 완료 → Implemented 유지.
#### Intent
- "수량 live·현금 stale" 비대칭 제거 — 수량은 슬롯 오버레이(정확), 현금은 추정 오버레이(라벨)로 즉시성 확보 후 권위값 수렴.
#### Acceptance Criteria Delta
- Added:
- 스냅샷 자산에 추정 현금 오버레이(`cash_estimated` 플래그) — 미정산 outbox delta 기반. 슬롯 오버레이는 그대로 유지(변경 없음).
#### Impacted Area Delta
- Modules: `trex_core/application/messaging_handlers.py`(`_apply_cash_estimate`)
- Docs: `docs/interface-contract.md`(envelope `cash_estimated`)
- Tests: tests/application/test_ledger_option_d.py(estimate overlay)
#### Delivery Trace Delta
- Batches: BAT-023
- Releases: none
#### Revalidation Impact
- Reverification Needed: yes (BAT-023 에서 완료)
- Existing Implementation Invalidated: no (오버레이 유지 + 추정 additive)
- Status Recommendation: Implemented (change-req → BAT-023 재검증)
- Follow-up Action: confirm-req-implemented(BAT-023).
#### Validation Plan
- BAT-023: 미정산 자산 cash_estimated + 추정 cash 단위, write-back 후 수렴.