diff --git a/docs/srs/Interface/req-073_slots-req-rpc-contract.md b/docs/srs/Interface/req-073_slots-req-rpc-contract.md index 59053e7..afa472f 100644 --- a/docs/srs/Interface/req-073_slots-req-rpc-contract.md +++ b/docs/srs/Interface/req-073_slots-req-rpc-contract.md @@ -1,6 +1,6 @@ # req-073: 전략 read 표면 — `trex.slots.req` RPC 계약 (filter/spy, snapshot.req 즉시 교체) -- Status: Implemented +- Status: Approved - Type: Interface - Priority: High - Owner: project maintainers @@ -13,15 +13,16 @@ - 요청 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: [...], degraded: bool, reason, message}` **만**. `assets[]`·`available_slots`·`watchdog[]` 는 응답에 포함하지 않는다(워치독은 슬롯 행에 흡수 — REQ-074). capacity 사전 확인은 제공하지 않으며 admission(`capacity_full`)이 게이트다. +- 응답 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`/`degraded`/`reason`/`message` 만 있고 `assets`·`available_slots`·`watchdog`·strategy 계열 키는 없다. +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 @@ -36,6 +37,46 @@ ## 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 diff --git a/docs/srs/index.md b/docs/srs/index.md index b3a9dd4..8b2c9ed 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -153,16 +153,15 @@ | REQ-070 | slippage 보호 지정가 집행 | Integration | Implemented | High | project maintainers | [req-070](./Integration/req-070_slippage-limit-price-execution.md) | | REQ-071 | 운영자 강제 취소 백스톱 (trex-core cancel) | Interface | Implemented | Medium | project maintainers | [req-071](./Interface/req-071_operator-cancel-pending-backstop.md) | | REQ-072 | 실행 정책 baseline 문서 정합 | Documentation | Implemented | Medium | project maintainers | [req-072](./Documentation/req-072_execution-policy-baseline-alignment.md) | -| REQ-073 | 전략 read 표면 — trex.slots.req RPC 계약 (filter/spy, snapshot.req 즉시 교체) | Interface | Implemented | High | project maintainers | [req-073](./Interface/req-073_slots-req-rpc-contract.md) | +| REQ-073 | 전략 read 표면 — trex.slots.req RPC 계약 (filter/spy, snapshot.req 즉시 교체) | Interface | Approved | High | project maintainers | [req-073](./Interface/req-073_slots-req-rpc-contract.md) | | REQ-074 | 슬롯 단일 행 스키마 — 자산·워치독·overlay 흡수 + 필드별 정본 라벨 | Data | Implemented | High | project maintainers | [req-074](./Data/req-074_merged-slot-row-schema.md) | | REQ-075 | slots read 표면 baseline 문서 정합 | Documentation | Implemented | Medium | project maintainers | [req-075](./Documentation/req-075_slots-read-surface-baseline-alignment.md) | ## Recent Change Log Summary +- 2026-06-12 :: REQ-073 change-req (CHG-20260612-01): 응답 payload 에 `available_slots: int|null` 추가. AC-3 반전(available_slots 포함), AC-6 신규(hint 값 규칙). BAT-035 AC-3 evidence 무효 → Implemented → **Approved** 되돌림. 차기 batch 구현·검증 후 복귀. - 2026-06-11 :: REQ-058 change-req (CHG-20260611-01): `reconcile_universe` 슬롯 생성 시 `symbol` 누락 수정. 시그니처 `set[str]` → `dict[str, str]`(portfolio_id→symbol), INSERT에 symbol 포함, `symbol IS NULL` 기존 슬롯 backfill 추가. AC-5 신규 추가. 기존 AC 1~4 evidence 유효 → **Implemented 유지**. - 2026-06-11 :: BAT-035/036 완료 — REQ-073/074/075/021/034/063/048/005 Approved → **Implemented**, REQ-028 → **Deprecated** (trex.snapshot.req 코드 삭제·trex.slots.req 대체) - 2026-06-11 :: REQ-028 Implemented → **Deprecated** (BAT-035, dcy-025): `trex.snapshot.req` envelope (`assets[]`/`View`/`build_snapshot_envelope`) 코드 삭제 완료. 후속 표면은 REQ-073/074 (`trex.slots.req`) 로 대체. - 2026-06-11 :: REQ-073/074/075 신규 생성(Proposed) + REQ-021/034/063 change-req Implemented→**Approved** + REQ-028 폐기 예정 forward-link (draft-req, dcy-025 전략 read 표면 재설계): `trex.snapshot.req`→`trex.slots.req` 즉시 교체 RPC 계약(요청 {filter: status 단일, spy}, 응답 {slots[], degraded/reason/message}, strategy 제외)(REQ-073), 슬롯 단일 행 스키마(asset_quantity hub 정본+qty 미러+warned, cash_balance+cash_estimated, watchdog nested, paused — 필드별 정본 라벨)(REQ-074), baseline 정합(REQ-075). 토폴로지 큐 교체(REQ-021 CHG-01), 워치독 터치=slots.req 기본/spy 무터치·행 흡수(REQ-034 CHG-01), 운영자 CLI 새 표면+spy(REQ-063 CHG-01). REQ-028 은 keep-current + delivery 배치에서 Deprecated 전환(REQ-005 선례). 전략 모듈 lockstep cutover 필요. Next ID: REQ-076. - 2026-06-11 :: REQ-048/005 change-req (dcy-024 safety-sell 비활성화 모드/issue #15, CHG: 048-20260611-01·005-20260611-01): per-instance TOML `safety_sell_enabled: bool=True`(env 제외, REQ-048 AC-10) + `daemon.start()` 조건부 워커 게이팅(false 시 `trex-safety-sell` 미기동·물리 차단) + 기동 로그 `no autonomous liquidation` 경고 + runtime-flows(REQ-005 AC-5/6). `ExecutionService`·운영자 exit/cancel·kill-switch·전략 sell intent 불변. 모드는 기동 로그만 노출(스냅샷 응답 미포함, OQ-3). **신규 REQ 없음**(change-req only, dcy-024 OQ-1). 둘 다 Implemented→**Approved**, 차기 batch 구현·검증 후 복귀. -- 2026-06-11 :: REQ-068~072 + REQ-013/061(CHG) → Implemented (confirm-req-implemented, BAT-032 dcy-022 실행 정책): timeout_sec·slippage_pct intent 계약·슬롯 lifecycle(REQ-068), timeout 초과 자동 취소·cancel-fill race(REQ-069), slippage 보호 지정가 dispatch(REQ-070), 운영자 `trex-core cancel` 백스톱(REQ-071), baseline 정합(REQ-072), 집행 루프 확장(REQ-013 CHG-03)·intent 필드 추가(REQ-061 CHG-05). BAT-032 verification — 신규 71 tests, 425 passed 회귀 없음, Blocking Issues 없음. -- 2026-06-10 :: REQ-002/006/007/028/032 → Implemented (confirm-req-implemented, BAT-034 dcy-023 allocated_capital 제거): 도메인(Slot/EXPECTED_SLOT_FIELDS)·intent(BuyIntent·수신 무시)·영속(마이그레이션 013 drop + flat 매핑)·snapshot(slots[])·CLI(--capital argparse 거부) 전 경로 제거. 테스트 DSN 013 멱등 round-trip + 컬럼 부재, 428 passed + PG 21 passed + ruff clean, grep 전수 0건. BAT-034 release-candidate. release 시 사전 백업·롤백 절차 필수(비가역 drop).