diff --git a/docs/batches/bat-037_20260612_slots-rpc-available-slots/design.md b/docs/batches/bat-037_20260612_slots-rpc-available-slots/design.md new file mode 100644 index 0000000..746a9fc --- /dev/null +++ b/docs/batches/bat-037_20260612_slots-rpc-available-slots/design.md @@ -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 diff --git a/docs/batches/bat-037_20260612_slots-rpc-available-slots/implementation.md b/docs/batches/bat-037_20260612_slots-rpc-available-slots/implementation.md new file mode 100644 index 0000000..94d396f --- /dev/null +++ b/docs/batches/bat-037_20260612_slots-rpc-available-slots/implementation.md @@ -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 +- 없음 diff --git a/docs/batches/bat-037_20260612_slots-rpc-available-slots/index.md b/docs/batches/bat-037_20260612_slots-rpc-available-slots/index.md new file mode 100644 index 0000000..e39eab6 --- /dev/null +++ b/docs/batches/bat-037_20260612_slots-rpc-available-slots/index.md @@ -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 무효. diff --git a/docs/batches/bat-037_20260612_slots-rpc-available-slots/planning.md b/docs/batches/bat-037_20260612_slots-rpc-available-slots/planning.md new file mode 100644 index 0000000..376aa78 --- /dev/null +++ b/docs/batches/bat-037_20260612_slots-rpc-available-slots/planning.md @@ -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 에서 확인. diff --git a/docs/batches/bat-037_20260612_slots-rpc-available-slots/verification.md b/docs/batches/bat-037_20260612_slots-rpc-available-slots/verification.md new file mode 100644 index 0000000..6d81e07 --- /dev/null +++ b/docs/batches/bat-037_20260612_slots-rpc-available-slots/verification.md @@ -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: + - 구현 전 diff --git a/docs/batches/index.md b/docs/batches/index.md index 518fb20..d208926 100644 --- a/docs/batches/index.md +++ b/docs/batches/index.md @@ -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/) |