feat(reconcile): safely seed canonical cost basis

docs/interface-contract.md

@@ -620,3 +620,17 @@ trex-core가 `source="trex-core"`, `severity="critical"`로 발행하는 초기
 - 2026-06-10 :: BAT-031 (dcy-021 포지션 사이징) — 매수 intent 가 **holding 슬롯 대상이면 증액**(qty+price 추가 매수; M 캡 미적용); 매도 intent 에 **`qty`(부분 매도, 선택)** 추가 — 지정 시 `min(qty, 브로커잔고)` 부분 매도(잔량 holding), 미지정 시 전량(→inactive). 상태머신 13 전이(holding→pending_buy). avg_price 증액 가중평균·부분 매도 cost basis 유지. (REQ-066/057/061/062)
 - 2026-07-04 :: BAT-055 (dcy-001/002 v3 FR-8, REQ-116) — `trex.slots.req` additive 확장: 요청에 선택적 `strategy: str` 필터 추가(exact-match, `filter` AND 조합, `available_slots` 불변 — REQ-073 AC-6); 응답 슬롯 행에 `strategy_name`(null)/`strategy_params`({})/`markets`([]) 3필드 추가(PortfolioItem/hub 정본, safe default). 기존 소비자(orb·tsl) backward compatible(unknown 필드 무시). REQ-074 AC-5 additive 재도입(dcy-025 OQ-4 후속 확정). PortfolioItem에 `strategy_name`/`markets` 필드 추가 + hub_read.py 파싱 확장.
 - 2026-07-06 :: BAT-056 (dcy-002 FR-6, REQ-117/118) — `OrderRequest.venue: str = "KRX"` additive 추가(기존 위치 인수 순서 불변 — AMQP wire 계약 영향 없음, 브로커 어댑터 계층 DTO까지만). KIS 어댑터: submit_order/cancel_order body에 `EXCG_ID_DVSN_CD` 항상 명시 전송(기존 미전송 → KRX 명시화 견고성 향상), cancel_order/get_current_price 시그니처 venue/market 파라미터 추가(기본값 KRX/"J" — 기존 호출자 무영향). poll_fill TR 유지(NXT 체결 포함 여부 미확인 open item). paper broker 시그니처 정합(venue/market 무시). 실측 근거: 2026-07-06 NXT 주문/취소 rt_cd=0 확인.
+
+
+## REQ-123 Contract Addendum: cost-basis canonical parsing & sync diagnostics
+
+`trex-core` REQ-123 적용 시, portfolio-hub cost-basis contract는 다음을 준수한다.
+
+- `GET /v1/portfolios/{portfolio_id}/holdings/cost-basis` 응답의 `cost_basis_per_unit`(canonical)을 먼저 확인한다.
+- canonical 값이 유효한 양수 수치면 이를 `avg_price` seed 후보로 사용한다.
+- canonical key가 존재하지만 null / non-numeric / non-positive / 범위 외이면 legacy fallback(`avg_cost` → `wac` → `cost_basis`)은 시도하지 않는다.
+- canonical이 부재한 경우에만 approved legacy 순서로 fallback을 검증한다.
+- canonical/legacy parsing 실패는 실패 원인을 reason 코드(`cost_basis_reason`)로 분리해 운영 진단으로 노출한다.
+- `sync`/`sync --dry-run` 결과에는 `seeded_avg_price`(bool), `cost_basis_source`(`canonical`/`legacy`/`none`), `cost_basis_reason` 필드가 들어간다. `cost_basis_reason`의 공개 값은 `missing`, `invalid`, `http_status_<3-digit>`, `transport`, `invalid_json`, `invalid_payload`, `not_configured`, `diagnostic_exception`, `diagnostic_source_invalid` 또는 유효한 값이 seed되었을 때의 `null`로 한정한다.
+- `http_status_<3-digit>`만 동적 형식이다. provider field name, parser detail, 임의 오류 텍스트는 공개 `cost_basis_reason` 계약 값이 아니다.
+- 비밀(credential/token/계좌정보)은 로그/출력에 노출하지 않는다.