trex-core/docs/srs/Interface/req-043_control-channel-action-dispatch.md

req-043: trex.control.req 제어 채널 + action dispatch

• Status: Implemented
• Type: Interface
• Priority: High
• Owner: project maintainers

Intent

기존 trex.pause.req 단일 목적 큐를 trex.control.req 제어 채널로 개념 확장하고, payload action 필드 기반 dispatch로 운영자 제어 명령을 단일 채널에서 처리한다. 기능마다 큐/consumer 스레드를 늘리지 않기 위한 단일 제어 채널 + action discriminator 패턴(dcy-008 OQ-1 Answered). 기존 pause/resume/list 동작을 보존하면서 kill-switch(REQ-045)와 resume_kill_switch(REQ-046) 라우팅 진입점을 추가한다.

Requirement

• 데몬은 단일 제어 큐 trex.control.req 를 소비하고 메시지 payload 의 action 필드로 핸들러를 분기한다.
• 기존 제어 action(pause/resume/list, REQ-032)의 동작·응답 계약을 그대로 유지한다.
• 신규 action 라우팅을 추가한다: kill_switch(REQ-045), resume_kill_switch(REQ-046). 본 REQ는 라우팅·메시지 계약 골격만 정의하고 실제 청산/해제 동작은 각 REQ에서 정의한다.
• 알 수 없는 action 은 {status: "error", reason: "unknown_action:<action>"} 으로 응답한다.
• 기존 trex.pause.req consumer 스레드를 control consumer(trex.control.req)로 교체한다. 데몬 워커 스레드 총수는 불변(7개 유지).
• 하위호환: trex.pause.req 를 사용하던 기존 클라이언트 호환 방식(별칭 큐 유지 vs trex.control.req 단일화)은 배포 영향이 있으므로 Notes 에 결정 필요로 남긴다.

Acceptance Criteria

1. Given trex.control.req 에 {action: "pause", portfolio_id} 발행, When 처리되면, Then 기존 REQ-032 pause 동작과 동일하게 snapshot_pause 에 반영되고 {status: "ok", paused[], action} 응답을 반환한다.
2. Given {action: "resume", portfolio_id} / {action: "list"}, When 처리되면, Then 각각 기존 resume/list 동작과 동일한 응답을 반환한다.
3. Given {action: "kill_switch", ...}, When 처리되면, Then kill-switch 핸들러(REQ-045)로 라우팅된다.
4. Given {action: "resume_kill_switch", ...}, When 처리되면, Then resume 핸들러(REQ-046)로 라우팅된다.
5. Given {action: "bogus"}, When 처리되면, Then {status: "error", reason: "unknown_action:bogus"} 를 반환한다.
6. Given 데몬 기동, When 워커 스레드를 확인하면, Then pause consumer 가 control consumer 로 교체되어 총 워커 스레드 수가 7로 불변이다.

Impacted Area

• Docs:
  • docs/interface-contract.md — 제어 채널 계약(trex.control.req + action 목록) (REQ-047 처리)
• Modules:
  • trex_core/adapters/messaging/topology.py — CONTROL_REQ_QUEUE = "trex.control.req" 추가(또는 PAUSE_REQ_QUEUE 대체)
  • trex_core/application/messaging_handlers.py — make_control_rpc_handler(action dispatch) 신설 또는 make_pause_rpc_handler 확장
  • trex_core/runtime/daemon.py — pause consumer → control consumer 교체
• Tests:
  • control dispatch 단위 테스트(pause/resume/list 회귀 + kill_switch/resume_kill_switch 라우팅 + unknown action)

Notes

• dcy-008 OQ-1 Answered: 단일 제어 채널 + action discriminator. 새 큐 추가 없음.
• 하위호환 결정 필요(배포): 기존 trex.pause.req 토픽 이름을 유지(별칭)할지, trex.control.req 로 단일화하고 전략/운영 클라이언트를 함께 갱신할지 — batch planning/release 단계에서 확정. 현재 CLI pause/resume 는 store 직접 호출이라 영향 없음(RPC 경로만 대상).
• kill_switch/resume_kill_switch 의 payload 상세(scope/portfolio_id)는 REQ-045/046 에서 정의.

Change Log

CHG-20260607-01

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• dcy-008(confirmed) → REQ-043 초안 생성.

Intent

• kill-switch 트리거 표면(OQ-1 Answered)을 단일 제어 채널 Interface REQ 로 정규화.

Acceptance Criteria Delta

• Added: AC-1~6 전체

Impacted Area Delta

• Docs: interface-contract.md (REQ-047)
• Modules: topology.py, messaging_handlers.py, daemon.py
• Tests: control dispatch 단위

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 로 승인.

CHG-20260607-02

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• Proposed → Approved (confirm-req).

Intent

• 승인 게이트 통과: 필수 필드·구체 AC·Impacted Area·Change Log 완비. dcy-008(confirmed) 범위·결정(OQ-1/2/4 Answered, OQ-3 Deferred)과 모순 없음. 하위호환(큐 rename)은 batch/release 단계 비핵심 운영 결정으로 승인 blocker 아님.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs / draft-batch 로 delivery 편성.

CHG-20260607-03

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-012 release-candidate).

Intent

• BAT-012 verification 의 AC↔evidence(control dispatch 9 단위: pause/resume/list 회귀 + kill_switch/resume_kill_switch 라우팅 + unknown action + 워커 스레드 불변 + e2e control RPC)로 AC-1~6 충족.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

• Batches: BAT-012 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Implemented)
• Follow-up Action: draft-release 로 BAT-012 배포 편성. 제어 큐 하위호환은 release rollout 결정.