fix(portfolios): replay corporate-action cost basis (#38)

docs/interface-contract.md

@@ -445,6 +445,14 @@
 - `GET /v1/portfolios/{id}/trades` remains restricted to BUY/SELL history.
 - `portfolio corporate-action` is the operator command; it requires an idempotency key and confirmation unless `--force` is supplied. `--resume-partial` enables only the guarded recovery mode above.
 
+### Endpoint: `GET /v1/portfolios/{portfolio_id}/holdings/cost-basis` (REQ-043, req-0008)
+
+- BUY/SELL과 `stock_consolidation` ledger를 repository가 제공한 `executed_at ASC, ledger_entry_id ASC` 순서대로 replay한다.
+- 정상 `stock_consolidation`은 감사 metadata의 양수 `quantity_after`를 replay 수량으로 적용하고 `total_cost_basis`를 authoritative 총원가로 보존한다. 응답의 `cost_basis_per_unit`는 authoritative 총원가를 현재 수량으로 나눈 값이다.
+- Persisted `average_price_after`는 감사·표시용 반올림 값이다. Endpoint는 이를 수량과 곱하여 총원가를 재구성하거나 별도 허용오차 판정에 사용하지 않는다.
+- `quantity_after`가 없거나 0 이하이거나 `total_cost_basis`가 없으면 기업행동 전 WAC로 추정하지 않는다. `cost_basis_per_unit`과 `total_cost_basis`는 모두 `null`이고 `data_completeness_warning`은 기업행동 metadata 부족을 나타낸다.
+- 기업행동이 없는 BUY/SELL-only 원가와 기존 불완전 거래 이력 warning, response field/nullability, daemon scope와 portfolio ownership 계약은 유지한다.
+
 
 ### Endpoint: `GET /v1/portfolios/{portfolio_id}/returns/summary` (REQ-056, BAT-024)