# req-032: 런타임 pause/resume 제어

- Status: Implemented
- Type: Interface
- Priority: Medium
- Owner: project maintainers

## Intent
- 운영자가 특정 자산을 런타임에 매매에서 제외(pause)하거나 다시 포함(resume)할 수 있게 한다. 프로그램 이상·이벤트 시 안전 통제를 위한 수동 overlay 다.

## Requirement
- pause/resume 단위는 `portfolio_id`(= asset_id)다.
- 제어는 **CLI** 와 **dcy-006 RPC 제어 메시지** 둘 다로 가능하며, 둘은 동일한 pause 상태를 변경한다. config 리로드 방식은 채택하지 않는다.
- pause 상태는 **Postgres 에 영속**(portfolio_id 키)하며 daemon 재시작 후에도, 일일 스냅샷 refresh 후에도 유지된다(refresh 는 universe/포지션만 갱신, pause overlay 불변).
- 적용 범위는 **전역** — pause 된 자산은 모든 view/전략 요청에서 마스킹된다.
- pause 는 request-time mask 이므로 resume 시 다음 요청부터 즉시 응답에 복귀한다.

## Acceptance Criteria
1. Given 운영자가 `portfolio_id` 를 pause, When 임의 `view`/`strategy_key` 로 스냅샷을 요청, Then 그 자산은 응답에서 마스킹된다.
2. Given pause 상태에서 daemon 재시작 또는 일일 refresh 발생, When 이후 요청, Then pause 가 유지된다.
3. Given 운영자가 resume, When 다음 요청, Then 그 자산이 응답에 다시 포함된다.
4. Given CLI 로 pause 후 RPC 제어로 조회(또는 그 반대), Then 동일한 pause 상태가 보인다.

## Impacted Area
- Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md
- Modules: pause 상태 store(Postgres), CLI 제어, dcy-006 RPC 제어 메시지 핸들러, 응답 산출 시 pause 마스킹
- Tests: pause→호출→resume→호출 시퀀스, 재시작/refresh 후 영속

## Notes
- pause(수동·영속) vs warning(자동·일시, REQ-031)은 독립 overlay 이며 OR 합성(둘 중 하나라도면 마스킹).
- OQ-10 반영.

## Change Log

### CHG-20260606-01
- Date: 2026-06-06
- Author: project maintainers

#### Change Summary
- dcy-005 FR-9 + OQ-10 분해로 최초 생성(Proposed).

#### Intent
- 런타임 pause/resume 제어(단위·제어 표면·영속·범위) 정의.

#### Acceptance Criteria Delta
- Added:
  - AC-1~4 신규
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - dcy-005
- Modules:
  - pause store, CLI, RPC 제어, 마스킹
- Tests:
  - pause/resume 시퀀스, 영속

#### 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

#### Validation Plan
- pause→호출→resume→호출 + 재시작 영속 테스트로 AC 검증.

### CHG-20260606-02
- Date: 2026-06-06
- Author: project maintainers

#### Change Summary
- 승인 게이트 통과 → Proposed → Approved.

#### Acceptance Criteria Delta
- Added: none
- Updated: none
- Removed: none

#### 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

#### Validation Plan
- 승인 기록. 구현 전 재검증 불필요.

### CHG-20260606-03
- Date: 2026-06-06
- Author: Justin Ko

#### Change Summary
- Status 변경: Approved → Implemented. BAT-008 release-candidate verification evidence 기반.

#### Intent
- pause/resume CLI + RPC 제어 + Postgres 영속 구현 완료 상태로 동기화.

#### Acceptance Criteria Delta
- Added/Updated/Removed: 없음

#### Impacted Area Delta
- Docs/Modules/Tests: 없음

#### Delivery Trace Delta
- Batches:
  - BAT-008 (release-candidate)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: release 단계는 별도 진행

#### Validation Plan
- AC-1: tests/application/test_pause_handler.py::test_pause_then_list + test_snapshot_selection.py::test_pause_overlay_masks_asset.
- AC-2: tests/adapters/portfolio/test_postgresql_pause_store.py::test_durability_simulated_via_fresh_store_instance.
- AC-3: tests/application/test_pause_handler.py::test_resume_clears_pause.
- AC-4: tests/application/test_pause_handler.py::test_cli_pause_visible_to_rpc_list_via_shared_store + 실 daemon RPC 운영 검증.

### CHG-20260608-01

- Date: 2026-06-08
- Author: Justin Ko

#### Change Summary

- (change-req, dcy-016) 운영자 CLI 확장: `universe`/`slots`/`enter`/`exit` 서브커맨드 추가(전부 데몬 RabbitMQ RPC). 인스턴스 라우팅(`--config` canonical/`--instance` 단축/default), enter/exit 안전장치(확인 프롬프트 기본 ON + `--yes`(paper)/`--yes --live`(live 이중 ack)/`--dry-run`), 전 명령 `--json`. pause/resume/paused 는 기존 direct-DB 유지(OQ-3). BAT-020 재구현·재검증 완료 → Implemented 유지.

#### Intent

- 운영자가 조회·매수(enter)·매도(exit)·일시정지를 CLI 로 수행하되, 매매는 데몬 admission(단일 writer)을 거쳐 불변식·portfolio_id 검증을 보존(DB 직접 쓰기 없음, NFR-1).

#### Acceptance Criteria Delta

- Added:
  - universe/slots(snapshot RPC)·enter(buy intent RPC)·exit(sell intent RPC) CLI + 인스턴스 라우팅 + enter/exit 안전장치 + `--json`.

#### Impacted Area Delta

- Modules: `trex_core/runtime/cli.py`(서브커맨드/가드/라우팅/RPC 클라이언트)
- Docs: `docs/interface-contract.md`, `docs/runtime-flows.md`
- Tests: tests/runtime/test_cli_operator.py

#### Delivery Trace Delta

- Batches: BAT-020
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (BAT-020 에서 완료)
- Existing Implementation Invalidated: no (pause/resume 불변, 명령 추가)
- Status Recommendation: Implemented (change-req → BAT-020 재검증)
- Follow-up Action: confirm-req-implemented(BAT-020).

#### Validation Plan

- BAT-020: CLI universe/slots/enter/exit RPC payload·안전장치·라우팅·--json 단위.

### CHG-20260608-02

- Date: 2026-06-08
- Author: Justin Ko

#### Change Summary

- (change-req, dcy-017) `trex-core slots` 가 snapshot 응답의 `watchdog` 필드를 읽어 `expired=true` 슬롯을 **WATCHDOG-OWNED(전략 이탈)** 로 표시(+`watchdog_owned` 카운트). dcy-016 `slots` 확장. BAT-021 재구현·재검증 완료 → Implemented 유지.

#### Intent

- 운영자가 CLI 로 워치독 소유(전략 이탈) 슬롯을 즉시 인지.

#### Acceptance Criteria Delta

- Updated:
  - `slots` 출력에 워치독 소유 표시(snapshot watchdog 필드 기반).

#### Impacted Area Delta

- Modules: `trex_core/runtime/cli.py`(_cmd_slots watchdog 표시)
- Tests: tests/runtime/test_cli_operator.py::test_slots_marks_watchdog_owned

#### Delivery Trace Delta

- Batches: BAT-021
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (BAT-021 에서 완료)
- Existing Implementation Invalidated: no (표시 추가)
- Status Recommendation: Implemented (change-req → BAT-021 재검증)
- Follow-up Action: confirm-req-implemented(BAT-021).

#### Validation Plan

- BAT-021: slots watchdog-owned 표시 단위.

### CHG-20260608-03

- Date: 2026-06-08
- Author: project maintainers

#### Change Summary

- (change-req, dcy-016 후속) `trex-core slots` 가 universe `assets[]`(portfolio: asset_id/symbol/asset_quantity)를 **슬롯 상태로 오인 표시**하던 갭 정정(운영 관측: 10개 슬롯인데 universe 1개·status 없음). snapshot envelope 의 신규 read-only `slots[]`(REQ-028 CHG-20260608-01, AC-4)를 읽어 **실제 슬롯 상태(`slot_id`·`status`(idle/holding/pending_buy/pending_sell)·`symbol`·`qty`·`limit_price`·`avg_price`)** 를 표시한다. `universe` 명령은 `assets[]`(universe) 유지로 둘을 명확히 분리. watchdog-owned 표시(CHG-20260608-02)는 `slots[]` 항목과 결합.

#### Intent

- 운영자가 `trex-core slots` 로 데몬의 실제 슬롯 상태(idle/holding/pending_*)를 관측하게 한다. `universe`(거래 대상 portfolio)와 `slots`(데몬 슬롯 할당 상태)를 표면상 명확히 구분.

#### Acceptance Criteria Delta

- Updated:
  - `slots` 출력은 universe `assets[]` 가 아니라 envelope `slots[]`(슬롯 상태, `status` 포함)를 표시한다. `--status held/holding/...` 필터는 슬롯 상태 기준으로 적용된다.
- Added: none
- Removed: none

#### Impacted Area Delta

- Modules: `trex_core/runtime/cli.py`(`_cmd_slots` → `resp["slots"]` 읽기). 전제: REQ-028 envelope `slots[]`(CHG-20260608-01).
- Tests: `slots` 가 universe 가 아닌 실제 슬롯 상태(status 포함)를 표시, universe 와 구분.

#### Delivery Trace Delta

- Batches: BAT-020 (`slots` 최초 구현 — 갭 발생). 정정은 신규 BAT-022 (REQ-028 AC-4 와 함께).
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes
- Existing Implementation Invalidated: yes (`slots` 가 universe assets 를 표시하던 부분이 슬롯 상태 의도와 불일치)
- Status Recommendation: Implemented → Approved (REQ-028 `slots[]` 의존, BAT-022 재구현/재검증)
- Follow-up Action: REQ-028 AC-4 구현 후 draft-batch(BAT-022) → 구현/검증

#### Validation Plan

- BAT-022: `trex-core slots` 가 envelope `slots[]` 의 실제 슬롯 상태(status enum 포함)를 표시하고 universe(`assets[]`)와 구분됨을 단위/통합 검증.

### CHG-20260608-04
- Date: 2026-06-08
- Author: Justin Ko

#### Change Summary
- Status 변경: Approved → Implemented. BAT-022 release-candidate verification evidence 기반(`slots` 가 envelope `slots[]` 표시, CHG-20260608-03).

#### Intent
- `trex-core slots` 가 실제 슬롯 상태(status)를 표시하는 정정 구현 완료 동기화.

#### Acceptance Criteria Delta
- Added/Updated/Removed: 없음

#### Impacted Area Delta
- Docs/Modules/Tests: 없음

#### Delivery Trace Delta
- Batches:
  - BAT-022 (release-candidate)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no (BAT-022 에서 완료)
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: release 단계 별도 진행

#### Validation Plan
- tests/runtime/test_cli_operator.py::test_slots_shows_real_slot_state_not_universe / ::test_slots_status_filters_by_slot_status / ::test_slots_marks_watchdog_owned. 운영 재현(BAT-022): 신규 코드 데몬 + 실 인프라 `trex-core slots` → slots=10 status·`--status holding`=0·universe(assets=1) 분리·비침습. pytest 인프라 게이트는 Human Approval Memo 수용 잔여.