trex-core/docs/srs/Interface/req-073_slots-req-rpc-contract.md

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

• Status: Approved
• 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 핸들러 제거), 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-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 신호 회귀.