docs(bat-037): draft — slots RPC available_slots capacity hint (REQ-073 CHG-20260612-01)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-12 10:26:04 +09:00
parent 31c18bf8d2
commit 8135dffb90
6 changed files with 137 additions and 0 deletions
@@ -0,0 +1,35 @@
 # BAT-037 Design
 - Status: confirmed
 - Batch: BAT-037
 ## Architecture Summary
 - `make_slots_rpc_handler` 에 `max_active_slots: Optional[int] = None` 파라미터를 추가하고, 응답 생성 시 `available_slots` 를 계산해 포함한다.
 - `daemon.py` 의 핸들러 wiring 에 `max_active_slots=self.config.max_active_slots` 를 전달한다.
 - 계산: `max_active_slots` 가 None 이면 `null`, 설정 시 `max(0, M − slot_repo.count_active(instance_key))`.
 - `SlotService.compute_slot_capacity` 는 SlotService 인스턴스가 필요하고 slots 핸들러에는 repo 만 주입되어 있으므로, `count_active` 를 직접 호출하는 인라인 계산을 사용한다.
 ## Changed Areas
 - Modules:
  - `trex_core/application/messaging_handlers.py` — `make_slots_rpc_handler` 시그니처 + 응답 구성
  - `trex_core/runtime/daemon.py` — `_slots_rpc_loop` 핸들러 wiring
 - Tests:
  - `tests/application/test_slots_handler.py` — AC-3 키 집합, AC-6 값 검증
 - Docs: `docs/interface-contract.md` 는 REQ-075 소관이므로 이번 배치에서 갱신하지 않음
 ## Key Decisions
 1. `SlotService` 대신 `slot_repo.count_active` 직접 호출 — slots 핸들러에 SlotService 가 주입되지 않으며, count_active 는 repo 레벨에서 단일 쿼리로 처리 가능. 의존성을 늘리지 않는다.
 2. `available_slots = null` when `max_active_slots is None` — "제한 없음"을 명시적으로 표현. 소비 측(orb-v1)은 null 을 "제한 없음"으로 처리.
 3. `available_slots = max(0, M − count_active)` — active count 가 M 을 초과하는 경우(수동 DB 조작 등)는 0 으로 클램프.
 ## Edge Cases
 - `max_active_slots` 미설정(None): `available_slots = null` 반환.
 - active > max_active_slots: `available_slots = 0` (클램프).
 - `count_active` 쿼리 실패: 예외를 상위로 전파 — 응답 자체가 실패하므로 hint 만 null 로 fallback 하지 않는다(일관성 유지).
 ## Architecture Impact
 - none (runtime-flows 흐름 변경 없음, 응답 필드 추가만)
 ## Reference Doc Update Plan
 - project-structure.md: none
 - runtime-flows.md: none
@@ -0,0 +1,23 @@
 # BAT-037 Implementation
 - Status: draft
 - Batch: BAT-037
 ## Plan Summary
 - `make_slots_rpc_handler` 에 `max_active_slots` 파라미터 추가 및 응답에 `available_slots` 포함
 - `daemon.py` wiring 에 `max_active_slots` 전달
 - `test_slots_handler.py` AC-3/AC-6 갱신
 ## Changed Files
 - `trex_core/application/messaging_handlers.py`
 - `trex_core/runtime/daemon.py`
 - `tests/application/test_slots_handler.py`
 ## Execution Log
 1. 구현 예정
 ## Validation
 - 구현 후 기록
 ## Remaining Risks
 - 없음
@@ -0,0 +1,25 @@
 # BAT-037: slots RPC 응답에 available_slots capacity hint 추가 (CHG-20260612-01)
 - Status: draft
 - Profile: standard
 - Source Discovery: dcy-025 (REQ-073 change-req)
 - Included REQ: REQ-073 (CHG-20260612-01)
 - Excluded REQ: 없음
 ## Summary
 - `trex.slots.req` 응답 payload 에 `available_slots: int|null` 필드를 추가한다. orb-v1 이 매 cycle `{filter: "inactive"}` 로 슬롯을 요청할 때 M 캡이 찬 상황에서도 intent 를 쏴야만 `capacity_full` 을 알 수 있는 불필요한 왕복을 제거하기 위한 capacity hint 다.
 ## Scope
 - In: `trex_core/application/messaging_handlers.py` — `make_slots_rpc_handler` 응답에 `available_slots` 추가 (`compute_slot_capacity` 활용), 관련 테스트 갱신 (AC-3 키 집합 반전·AC-6 값 검증)
 - Out: admission gate(`capacity_full`) 로직 변경 없음, 슬롯 도메인 모델/DB 스키마 변경 없음, 다른 RPC 표면 변경 없음
 ## Documents
 - Planning: [planning.md](./planning.md)
 - Design: [design.md](./design.md)
 - Implementation: [implementation.md](./implementation.md)
 - Verification: [verification.md](./verification.md)
 ## Notes
 - 인터페이스 변경(응답 스키마)이므로 standard profile 선택. 구현 자체는 경량(`compute_slot_capacity` 재활용).
 - `available_slots` 는 hint — admission gate 를 대체하지 않으며 orb-v1 의 skip 최적화용.
 - REQ-073 AC-3 이 반전됨(available_slots 제외→포함). BAT-035 AC-3 evidence 무효.
@@ -0,0 +1,30 @@
 # BAT-037 Planning
 - Status: confirmed
 - Batch: BAT-037
 - Profile: standard
 ## Included REQ
 - REQ-073 (CHG-20260612-01): 응답에 `available_slots: int|null` 추가, AC-3 반전, AC-6 신규
 ## Delivery Plan
 1. `messaging_handlers.py` — `make_slots_rpc_handler` 에서 `compute_slot_capacity` 호출 후 `available_slots` 를 응답에 포함
 2. `tests/application/test_slots_handler.py` — AC-3 키 집합 검사 갱신(available_slots 포함), AC-6 값 검증 케이스 추가
 ## Dependencies
 - Internal:
  - `trex_core/domain/slot/service.py` — `SlotService.compute_slot_capacity(max_active_slots)` 이미 존재, 재활용
  - `make_slots_rpc_handler` 에 `max_active_slots: Optional[int]` 파라미터가 이미 있는지 확인 필요
 - External: 없음
 ## Design Gate
 - Design Required Before Implementation: yes
 - Reason: 응답 스키마 변경(인터페이스 계약) — AC-3 반전 근거와 `available_slots` 계산 경로를 design 에서 명확히 한 뒤 구현한다.
 ## Milestones
 1. Design confirmed — 계산 경로 확정
 2. Implementation — 핸들러 수정 + 테스트 갱신
 3. Verification — AC 전체 매핑 확인
 ## Risks
 - `make_slots_rpc_handler` 에 `max_active_slots` 가 전달되지 않는 경로가 있으면 `null` fallback 처리 필요 — design 에서 확인.
@@ -0,0 +1,23 @@
 # BAT-037 Verification
 - Status: draft
 - Batch: BAT-037
 ## Acceptance Mapping
 - REQ-073 AC-3: 응답 키 집합에 `available_slots` 포함, `assets`/`watchdog`/strategy 계열 제외
  - Evidence: 구현 후 기록
 - REQ-073 AC-6: `max_active_slots` 미설정 → `null`, 설정 시 `max(0, M − count_active)`
  - Evidence: 구현 후 기록
 - REQ-073 AC-1/2/4/5: 회귀 없음
  - Evidence: 구현 후 기록
 ## Evidence
 - Test:
  - 구현 후 기록
 - Manual:
  - 구현 후 기록
 ## Result
 - Ready for Release: false
 - Blocking Issues:
  - 구현 전
@@ -44,3 +44,4 @@
 | BAT-034 | standard | release-candidate | REQ-002 (CHG-20260610-02), REQ-006 (CHG-20260610-02), REQ-007 (CHG-20260610-02), REQ-028 (CHG-20260610-01), REQ-032 (CHG-20260610-07) | dcy-023 (issue #22) | [bat-034](./bat-034_20260610_drop-allocated-capital/) |
 | BAT-035 | standard | confirmed | REQ-073, REQ-074, REQ-075, REQ-021 (CHG-20260611-01), REQ-034 (CHG-20260611-01), REQ-063 (CHG-20260611-01) | dcy-025 | [bat-035](./bat-035_20260611_strategy-read-surface-slots-req/) |
 | BAT-036 | standard | confirmed | REQ-048 (CHG-20260611-01), REQ-005 (CHG-20260611-01) | dcy-024 | [bat-036](./bat-036_20260611_safety-sell-disable-mode/) |
 | BAT-037 | standard | draft | REQ-073 (CHG-20260612-01) | dcy-025 (REQ-073 change-req) | [bat-037](./bat-037_20260612_slots-rpc-available-slots/) |