trex-core/docs/batches/bat-058_20260716_cost-basis-safe-sync-seed/planning.md

BAT-058 Planning

• Status: in-progress
• Batch: BAT-058
• Profile: standard

Included REQ

• REQ-123 (Approved): cost-basis canonical 우선 파싱 + safe sync seeding

Delivery Plan

1. trex_core.adapters.portfolio.hub_read에서 cost-basis 응답 파싱 순서 정립
   • 우선순위: cost_basis_per_unit(canonical) -> avg_cost -> wac -> cost_basis
   • canonical가 present이면 legacy fallback를 금지하고 이유를 기록
   • 유효성 검사(형변환/양수) 실패 시 source/reason 분리
2. sync_slot_to_broker에 WAC 사용 경로를 cost-basis 진단 결과와 함께 통합
   • INACTIVE + broker_qty>0 + 가격 미확보 시 dry-run은 preview만
   • live에서는 no-write fail-closed + exit fail
3. tests/adapters/portfolio/test_hub_read.py와 tests/application/test_sync.py를 AC-기반으로 확장
   • canonical 우선 규칙, invalid canonical non-fallback, unavailable reason 보존
   • inactive onboarding no-write dry-run / live fail-closed
4. docs/interface-contract.md, docs/runtime-flows.md, docs/operations.md baseline 동기화
5. docs/batches/bat-058... 산출물(implementation + verification) 작성 후 리드 검토 제출

Dependencies

• modules: trex_core/adapters/portfolio/hub_read.py, trex_core/application/reconciliation.py, trex_core/runtime/cli.py
• tests: tests/adapters/portfolio/test_hub_read.py, tests/application/test_sync.py
• docs: docs/interface-contract.md, docs/runtime-flows.md, docs/operations.md

Design Gate

• Design Required Before Implementation: yes
• Reason: 계약 precedence 및 fail-closed semantics이 배포 안전성에 직결되어, 미리 수용 기준(재기록/no-write/오류 로그)을 고정해야 함.

Milestones

1. planning 확정 (현재)
2. design 작성
3. implementation 완료
4. draft-batch-verification 작성 및 테스트 실행
5. QC handoff

Risks

• R1 High: canonical 값 parse 실패 시 legacy fallback를 허용하면 REQ-123 위반 가능성(의도치 않은 source 사용)
• R2 High: inactive onboarding에서 가격 미확보일 때 live write가 진행될 경우 거래원장·slot 상태 오염
• R3 Medium: 비용/시간 과다로 기존 cost_basis 회귀 테스트 간과 시 interface contract drift