trex-core/docs/batches/bat-037_20260612_slots-rpc-available-slots/design.md

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