trex-core/docs/srs/Interface/req-029_asset-selection-slot-overlay-view-and-strategy-key.md

req-029: 자산 선별(slot overlay) + view 모드 + strategy_key 필터

• Status: Implemented
• Type: Interface
• Priority: High
• Owner: project maintainers

Intent

• 스냅샷 응답에 담을 자산 집합을 core 의 권위 슬롯 상태로 선별한다. 보유(holding)는 포함하되 일시·불안전 상태는 마스킹하고, 전략 타입별 view 와 전략별 필터를 제공한다.

Requirement

• 응답 base 집합은 요청 view(all 기본 | buyable | held)로 선택한다: all = universe 전체(portfolio-hub 보유 + holding 슬롯), buyable = universe − 슬롯 점유, held = holding 슬롯 자산만.
• 마스킹(pending·warning·pause)은 전 모드에 균일 적용한다. pending 은 모든 모드에서 마스킹되므로 held 는 holding 만 포함한다. 포함/마스킹 판정은 core 권위 슬롯 상태 + 정합 결과 + pause 상태를 portfolio-hub 보유 여부보다 우선한다(slot overlay, 불변식 A).
• 선택적 strategy_key(요청 시) 는 자산의 단일 active_strategy_id 와 대소문자 구분 정확 일치로 직교 필터링한다. strategy_key 는 사람이 읽는 안정 유일 slug(예: target-value-v1)다.
• 최종 합성: assets = base(view) − mask(pending·warning·pause) − (strategy_key 필터, 주어진 경우). buyable 은 available_slots=0 이면 [] 다.

Acceptance Criteria

1. Given 같은 종목이 holding 슬롯·pending 슬롯에 각각 있을 때, When view=all, Then holding 자산은 포함되고 pending 자산은 마스킹된다.
2. Given available_slots=0, When view=buyable, Then [] 를 반환한다.
3. Given view=held, Then holding 슬롯 자산만 반환하고 pending 은 제외한다.
4. Given strategy_key 제공, Then active_strategy_id 가 일치하는 자산만 반환하고, 생략 시 (마스킹 후) 전체 자산을 반환한다.
5. Given warning 또는 pause 자산, When 임의 view, Then 해당 자산은 마스킹된다.

Impacted Area

• Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md
• Modules: trex_core/application 스냅샷 선별/slot overlay 로직(slot repository 재사용), strategy_key 필터
• Tests: view 모드별·마스킹·strategy_key 필터 합성 테스트

Notes

• core 권위 슬롯 상태(불변식 A)가 portfolio-hub 보유 여부보다 우선한다.
• OQ-4(in-flight 합성)·OQ-9(strategy_key)·OQ-11/OQ-12(view 모드) 반영.
• holding 자산의 보유 수량 표기를 core 슬롯 vs 스냅샷 중 무엇 기준으로 할지(holding→ledger flush 갭)는 설계 시 확정(dcy-005 OQ-4 잔여).
• (orb-v1 소비 참고, CHG-04) 첫 전략 orb-v1 은 strategy_key 없이 view=buyable 로 조회한다. 즉 전략 설정과 무관하게 universe 전체를 대상으로 하고, slot 점유(holding·pending)·warning(정합 불일치)·pause(사용자) 만 제외하면 된다 — 이는 view=buyable + strategy_key 생략의 기존 동작과 정확히 일치한다. pending(in-flight) 제외는 중복 주문 방지, warning 제외는 틀린 baseline 매매 차단(REQ-031) 목적으로 orb-v1 의도에 부합한다(사용자 확인). 따라서 단일 전략 단계에서는 /v1/portfolios PortfolioItem 의 전략 필드(active_strategy_id/strategy_params) 부재가 orb-v1 동작에 무해하다. (2번째 전략부터는 strategy_key 라우팅이 필요해져 전략 필드 부재 해소가 재대두된다.)

Change Log

CHG-20260606-01

• Date: 2026-06-06
• Author: project maintainers

Change Summary

• dcy-005 FR-2/FR-8 + OQ-4/9/11/12 분해로 최초 생성(Proposed).

Intent

• 응답 자산 선별(slot overlay·view·strategy_key) 규칙 정의.

Acceptance Criteria Delta

• Added:
  • AC-1~5 신규
• Updated:
  • none
• Removed:
  • none

Impacted Area Delta

• Docs:
  • dcy-005
• Modules:
  • 스냅샷 선별/slot overlay, strategy_key 필터
• Tests:
  • view/마스킹/필터 테스트

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req

Validation Plan

• 슬롯 상태 주입 후 view/마스킹/strategy_key 합성 테스트로 AC 검증.

CHG-20260606-02

• Date: 2026-06-06
• Author: project maintainers

Change Summary

• 승인 게이트 통과 → Proposed → Approved.

Acceptance Criteria Delta

• Added: none
• Updated: none
• Removed: none

Impacted Area Delta

• 변경 없음

Delivery Trace Delta

• Batches: none
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs / draft-batch

Validation Plan

• 승인 기록. 구현 전 재검증 불필요.

CHG-20260606-03

• Date: 2026-06-06
• Author: Justin Ko

Change Summary

• Status 변경: Approved → Implemented. BAT-008 release-candidate verification evidence 기반.

Intent

• build_snapshot_envelope 의 base(view) 산출 + masking OR 합성 + strategy_key 직교 필터 구현 완료 상태로 동기화.

Acceptance Criteria Delta

• Added/Updated/Removed: 없음

Impacted Area Delta

• Docs/Modules/Tests: 없음

Delivery Trace Delta

• Batches:
  • BAT-008 (release-candidate)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: Implemented
• Follow-up Action: release 단계는 별도 진행

Validation Plan

• AC-1: tests/application/test_snapshot_selection.py::test_view_all_includes_holding_excludes_pending_for_same_symbol.
• AC-2: ::test_view_buyable_with_zero_available_slots_returns_empty.
• AC-3: ::test_view_held_returns_only_holding_slot_assets.
• AC-4: ::test_strategy_key_orthogonal_filter + ::test_strategy_key_missing_includes_everything_unmasked.
• AC-5: ::test_warning_overlay_masks_asset_uniformly_across_views + ::test_pause_overlay_masks_asset.

CHG-20260606-04

• Date: 2026-06-06
• Author: Justin Ko

Change Summary

• 첫 전략 orb-v1 의 스냅샷 소비 패턴을 Notes 참고 사항으로 추가(본문 비변경). AC/요구사항/계약 변경 없음.

Intent

• orb-v1 은 전략 설정(active_strategy_id/strategy_params)과 무관하게 모든 자산을 대상으로 하며 strategy_key 없이 view=buyable 로 조회한다는 소비 계약을 명시해, /v1/portfolios PortfolioItem 의 전략 필드 부재가 orb-v1 에 무해함을 기록한다.

Acceptance Criteria Delta

• Added: none
• Updated: none
• Removed: none

Impacted Area Delta

• Docs:
  • 본 REQ Notes 에 orb-v1 소비 참고 사항 1건 추가
• Modules: 없음
• Tests: 없음

Delivery Trace Delta

• Batches:
  • BAT-008 (release-candidate) — 영향 없음(기존 구현/검증 그대로 유효)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Implemented 유지)
• Follow-up Action: orb-v1 Discovery 착수 시 본 참고 사항을 입력으로 사용. 2번째 전략 도입 시 strategy_key/strategy_params 필요 → PortfolioItem 전략 필드 부재 해소(detail strategy_set 보강 또는 별도 change-req) 재검토.

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 후 수렴.