# req-073: 전략 read 표면 — `trex.slots.req` RPC 계약 (filter/spy, snapshot.req 즉시 교체)

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

## Intent
- 자산 중심 영구 슬롯 모델(dcy-020)에서 전략 read 표면을 슬롯 단일 테이블 RPC 로 재설계한다. `trex.snapshot.req`(view/assets[]/available_slots/watchdog[] 구조)를 폐기하고 `trex.slots.req` 하나로 교체해, 전략·운영자가 슬롯 테이블 하나로 universe·포지션·워치독을 읽게 한다. (dcy-025 FR-1/2/4/5/6)

## Requirement
- per-instance 큐 `trex.slots.req`(기존 큐명 규칙 — default 는 literal, 그 외 `.{instance_key}` 접미)를 신설하고 `trex.snapshot.req` 파이프라인(큐 선언·핸들러·legacy stub 경로)을 **같은 배포에서 제거**한다(즉시 교체, 과도기 없음 — 전략 모듈 lockstep cutover, dcy-025 OQ-1).
- 요청 payload: `{filter?: str, spy?: bool}`.
  - `filter` 는 **status 단일 값**(상호배타) `{all, inactive, pending, holding, error}`. 미지정 시 `all`. `pending` = `pending_buy ∪ pending_sell`. `inactive` 판정 키는 슬롯 **status**(hub `asset_quantity` 아님). 파생 view(ALL/BUYABLE/HELD)와 `View` enum 은 폐기한다 — 매수 가능 목록 = `filter=inactive`.
  - `spy=true` 면 워치독을 갱신하지 않는다(생존 신호 미발생 — 기존 `actor="operator"`/`touch_watchdog=false` 의 일반화, REQ-034 정합). 기본 `false`(holding 슬롯 워치독 터치).
- 응답 payload: `{slots: [...], available_slots: int|null, degraded: bool, reason, message}`. `assets[]`·`watchdog[]` 는 응답에 포함하지 않는다(워치독은 슬롯 행에 흡수 — REQ-074). `available_slots` 는 capacity hint — `max_active_slots` 미설정 시 `null`, 설정 시 `max(0, M − count_active)`. admission gate(`capacity_full`)는 별도로 유지되며 `available_slots` 가 이를 대체하지 않는다.
- `strategy_id`/`strategy_key`/`strategy_params`/`active_strategy_id` 는 본 표면에서 제외한다(요청 필터·응답 필드 모두 없음). 인스턴스=다중 전략이나 전략↔자산 할당 모델은 portfolio-hub 주도 후속 discovery — 확정 시 strategy 필드를 additive 로 재도입한다(dcy-025 OQ-4).

## Acceptance Criteria
1. Given 기동된 데몬, When 토폴로지 선언, Then `trex.slots.req`(per-instance) 큐가 존재하고 `trex.snapshot.req` 큐·핸들러·legacy stub 경로는 존재하지 않는다.
2. Given `{filter: "inactive"}` 요청, When 처리, Then status 가 `inactive` 인 슬롯 행만 반환된다(매수 가능 목록). `{filter: "pending"}` 은 `pending_buy ∪ pending_sell`, 미지정은 전체. 잘못된 filter 값은 `all` 또는 명시 거부로 일관 처리된다.
3. Given 응답 payload, When 키 집합 검사, Then `slots`/`available_slots`/`degraded`/`reason`/`message` 가 있고 `assets`·`watchdog`·strategy 계열 키는 없다.
4. Given `spy=true` 요청, When holding 슬롯 포함 조회, Then 워치독 `last_seen_at` 이 갱신되지 않는다. Given 기본(`spy` 미지정/false) 요청, Then holding 슬롯 워치독이 갱신된다(REQ-034 시맨틱 보존).
5. Given degraded 상태(universe fetch 실패 등), When 조회, Then `degraded=true` + `reason` 이 기존 REQ-028 신호 의미대로 운반된다.
6. Given `max_active_slots` 미설정 인스턴스, When 조회, Then `available_slots = null`. Given `max_active_slots = M` 설정 인스턴스 + 현재 active N, When 조회, Then `available_slots = max(0, M − N)`. `available_slots` 는 hint 이며 admission gate 를 대체하지 않는다.

## Impacted Area
- Docs: docs/interface-contract.md(snapshot→slots 계약 — REQ-075), docs/runtime-flows.md
- Modules: trex_core/adapters/messaging/topology.py(큐명), trex_core/application/messaging_handlers.py(slots 핸들러·snapshot 핸들러 제거; (CHG-20260612-02) status 필터 repo 위임 + watchdog 조회 재사용), trex_core/application/portfolio.py(`View` enum 폐기)
- Tests: tests/application/(slots 핸들러 filter/spy/응답 키 집합), tests/adapters/messaging/(토폴로지)

## Notes
- 즉시 교체(과도기 없음)이므로 전략 모듈(trex-orb-v1) 소비 측을 같은 전환점에 lockstep 변경해야 한다(dcy-025 R-1/NFR-3) — 배포 전 orb-v1 의 `trex.slots.req` 대응 준비 확인. dcy-020 cutover 선례와 동일하게 단일 전환점 관리.
- 행 스키마(자산·워치독·overlay 흡수, 정본 라벨)는 REQ-074 가 소유한다.
- 운영자 CLI 의 새 표면 사용은 REQ-063 change-req(CHG-20260611-01).
- 출처: dcy-025 FR-1/2/4/5/6, NFR-1(워치독 일관성)·NFR-3(cutover 안전)은 본 REQ AC/Notes 에 흡수.

## Change Log

### CHG-20260615-02

- Date: 2026-06-15
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented, BAT-042). 신규 AC-7(strategy_state 맵+occupancy_seq additive, batched 조립) 구현·검증 완료 — `tests/application/test_slots_handler_strategy_state.py` + 기존 `test_slots_handler.py` 회귀 green. 기존 AC-1~6 불변. 479 passed, ruff clean. Implemented 복귀.

### CHG-20260615-01

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

#### Change Summary

- (change-req, dcy-028/issue #26 C-1) `trex.slots.req` 응답의 각 슬롯 행에 **strategy_state 맵**(`{<strategy_id>: {version,data,updated_at}}`, REQ-079/074)과 **occupancy_seq**(int, REQ-081)를 additive 로 추가한다. 핸들러는 반환 slot_id 들로 `StrategyStateStore`(REQ-079) batched 조회 후 group by 해 행별 맵으로 조립한다(추가 왕복 없음). 미보유 시 omit/`{}`. 기존 envelope 키(`slots`/`available_slots`/`degraded`/`reason`/`message`)·filter·spy·degraded 동작은 불변. AC-3 의 "strategy 계열 키 없음"은 dcy-025 가 제외한 strategy_* **reasoning** 필드(strategy_id/params/active)를 가리키며, 본 변경의 `strategy_state`(opaque 상태 맵)·`occupancy_seq`는 그와 구분되는 신규 additive 필드다.

#### Intent

- 전략 데몬이 슬롯과 함께 opaque strategy-state 를 추가 왕복 없이 read(C-1 piggyback). write 는 별도 RPC(REQ-080).

#### Acceptance Criteria Delta

- Added:
  - AC-7(신규): 행에 `strategy_state` 맵(보유 시)과 `occupancy_seq` 가 포함되고, batched 조회로 조립되어 추가 RPC 왕복이 없다. strategy_* reasoning 필드 부재는 유지(AC-3 정합).
- Updated:
  - AC-3: 응답 키 집합에서 제외되는 "strategy 계열"은 strategy_* reasoning 필드로 한정하고 `strategy_state`/`occupancy_seq` additive 필드는 허용함을 명확화.
- Removed: 없음

#### Impacted Area Delta

- Docs: docs/interface-contract.md(strategy_state·occupancy_seq 행 필드 — REQ-082)
- Modules: trex_core/application/messaging_handlers.py(slots 핸들러 strategy_state batched 조립), trex_core/application/portfolio.py(slot_to_dict)
- Tests: tests/application/(strategy_state 맵·occupancy_seq 행 조립, batched 조회)

#### Delivery Trace Delta

- Batches: BAT-035(dcy-025, 기존 Implemented 근거) 불변 — 신규 AC-7 은 dcy-028 batch 에서 구현·검증.
- Releases: REL-006(REQ-073 released) — 기존 계약 영향 없음(additive). 신규 필드는 REL-007 이후 dcy-028 batch.

#### Revalidation Impact

- Reverification Needed: yes (신규 AC-7 만)
- Existing Implementation Invalidated: no (기존 envelope/filter/spy 동작 보존)
- Status Recommendation: revert-to-approved (Implemented → Approved — 신규 additive AC 구현·검증 대기, 선례 REQ-002/006 CHG-20260612)
- Follow-up Action: confirm-req → dcy-028 batch 에서 REQ-079/080/081 과 함께 구현·검증 → confirm-req-implemented

#### Validation Plan

- slots 핸들러 테스트: 행에 strategy_state 맵(보유/미보유)·occupancy_seq 포함, batched 조회로 추가 왕복 없음, 기존 키 집합/filter/spy/degraded 회귀.

### CHG-20260612-02

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

#### Change Summary

- (change-req, issue #25) slots RPC 핸들러(`make_slots_rpc_handler`)가 status 필터링을 `SlotRepository.list_slots(instance_key, status_filter=...)`(REQ-002/006) 에 위임해 per-request full scan + Python 필터를 제거한다. 추가로 watchdog 갱신용 holding 조회를, 응답 필터가 `all`/`holding` 이라 이미 holding 을 포함한 경우 fetch 결과를 재사용해 두 번째 커넥션을 생략한다(그 외 필터는 기존대로 `list_holding_slots`). **관찰 가능한 응답 계약(AC-1~6)은 불변** — filter 결과·키 집합·spy·degraded·available_slots 동일. AC delta 없음 → **Implemented 유지**(BAT-040 재검증).

#### Intent

- issue #25 (1) DB 레벨 status 필터 + (2) 두 쿼리 통합. orb-v1 이 매 cycle `{filter:"inactive"}` 로 요청할 때 200-slot 인스턴스에서 전 행 fetch 를 반복하던 비용 제거. 동작 보존 내부 최적화.

#### Acceptance Criteria Delta

- Added/Updated/Removed: 없음 (AC-1~6 관찰 계약 불변, 핸들러 내부 위임만)

#### Impacted Area Delta

- Docs: 없음
- Modules: `trex_core/application/messaging_handlers.py`(`make_slots_rpc_handler` — `list_slots(status_filter)` 위임 + watchdog 조회 재사용)
- Tests: 기존 filter/spy/응답 키 집합 테스트 회귀 + status_filter 위임 확인

#### Delivery Trace Delta

- Batches: BAT-040 (예정, issue #25)
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (BAT-040 에서 filter/spy/degraded/available_slots 회귀)
- Existing Implementation Invalidated: no (관찰 응답 동일, 내부 위임만 — AC evidence 유효)
- Status Recommendation: **Implemented 유지**
- Follow-up Action: BAT-040 구현·검증으로 재확인(REQ-002/006 Implemented 복귀와 동일 배치)

#### Validation Plan

- BAT-040: 기존 `test_filter_*`/`test_spy_*`/`test_response_keys_*`/`test_available_slots_*` 회귀 green + status_filter 위임 경로(필터별 list_slots 인자) 확인.

### CHG-20260612-IMPL
- Date: 2026-06-12
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-037 (release-candidate) — AC-3 반전(available_slots 포함)·AC-6 신규(null/잔여/0 클램프) 16 tests passed, 423 전체 회귀 없음. Blocking Issues 없음.

### CHG-20260612-01
- Date: 2026-06-12
- Author: Justin Ko

#### Change Summary
- 응답 payload 에 `available_slots: int|null` 추가. orb-v1 이 매 cycle `{filter: "inactive"}` 로 슬롯을 요청할 때 capacity 가 차 있어도 intent 를 쏴야만 `capacity_full` 을 알 수 있던 문제 해소. `max_active_slots` 미설정 시 `null`(제한 없음), 설정 시 `max(0, M − active)` 정수.

#### Intent
- slots RPC 를 read 표면으로 유지하면서도 capacity 힌트를 제공해 불필요한 intent 왕복을 줄인다. admission gate(`capacity_full`)는 그대로 유지 — `available_slots` 는 hint 이며 orb-v1 이 skip 최적화에 사용한다.

#### Acceptance Criteria Delta
- Updated:
  - AC-3: 응답 키 집합에서 `available_slots` 제외 → **포함**으로 반전. `assets`·`watchdog`·strategy 계열은 여전히 제외.
- Added:
  - AC-6: `available_slots` 값 규칙 — `max_active_slots` 미설정 시 `null`, 설정 시 `max(0, M − count_active)`. 응답의 `available_slots` 는 hint 이며 admission gate 를 대체하지 않는다.
- Removed: 없음

#### Impacted Area Delta
- Modules:
  - `trex_core/application/messaging_handlers.py` — `make_slots_rpc_handler` 응답에 `available_slots` 추가
  - `trex_core/domain/slot/service.py` — `compute_slot_capacity` 호출 경로 확인
- Tests: `tests/application/test_slots_handler.py` — AC-3 키 집합 검사 및 AC-6 값 검증 갱신
- Docs: `docs/interface-contract.md` — 응답 스키마 반영 (REQ-075 소관)

#### Delivery Trace Delta
- Batches: BAT-035 (REQ-073 구현/확인) — AC-3 evidence 무효. 신규 batch 필요.
- Releases: REL-006 (배포 완료) — 운영 중 발견, 비파괴적 필드 추가(additive).

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: yes (AC-3 — `available_slots` 부재 검증이 반전됨)
- Status Recommendation: Implemented → **Approved** (차기 batch 구현·검증 후 복귀)
- Follow-up Action: draft-batch → implementation → verification → confirm-req-implemented

#### Validation Plan
- 응답에 `available_slots` 키 존재 확인.
- `max_active_slots` 설정 인스턴스: active N 개일 때 `available_slots = M − N`, active ≥ M 이면 `0`.
- `max_active_slots` 미설정: `available_slots = null`.
- 기존 AC-1/2/4/5 회귀 없음 확인.

### CHG-20260611-01
- Date: 2026-06-11
- Author: Justin Ko

#### Change Summary
- dcy-025 FR-1/2/4/5/6 로부터 최초 생성(Proposed). `trex.slots.req` RPC 계약(filter=status 단일/spy 워치독 무터치/응답 slots+health 만/strategy 제외/즉시 교체).

#### Intent
- 전략 read 표면을 슬롯 단일 테이블로 재설계 — assets/available_slots/watchdog 병렬 구조와 파생 view 폐기.

#### Acceptance Criteria Delta
- Added:
  - AC-1~5 신규
- Updated/Removed: none

#### Impacted Area Delta
- Docs: interface-contract/runtime-flows
- Modules: topology/messaging_handlers/portfolio(View 폐기)
- Tests: slots 핸들러/토폴로지

#### Delivery Trace Delta
- Batches: none(승인 후 draft-batch)
- Releases: none

#### Revalidation Impact
- Reverification Needed: no(신규)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current(Proposed)
- Follow-up Action: confirm-req

#### Validation Plan
- 신규 batch: 토폴로지 선언/제거 단위, filter·spy·응답 키 집합 단위, 워치독 터치/무터치, degraded 신호 회귀.