# req-028: 종목 스냅샷 read 메시지 계약 + envelope + degraded 신호

- Status: Deprecated
- Deprecated-By: REQ-073, REQ-074 (BAT-035, dcy-025, 2026-06-11)
- Type: Interface
- Priority: High
- Owner: project maintainers

## Intent
- 전략 모듈이 dcy-006 snapshot RPC 로 종목 스냅샷을 받는 요청/응답 계약(transport-무관 logical)을 정의한다. 빈 응답과 가용성 degrade 의 시맨틱을 모호하지 않게 한다.

## Requirement
- 스냅샷 read 는 dcy-006 의 `trex.snapshot.req` request-reply RPC 위에서 동작한다. 요청 payload 는 선택적 `strategy_key`·`view` 를 가진다.
- 응답은 **envelope** 다: `assets` 는 항상 배열(비면 `[]`, null 금지)이고, meta 로 `view`(에코), `available_slots`, `degraded`, `reason` 을 포함한다.
- 각 자산 항목은 symbol, asset_id, cash_balance, asset_quantity, active_strategy_id, 전략파라미터(opaque)를 담고 가격은 제외한다.
- (CHG-20260608-01) envelope 은 universe `assets[]` 와 **별도로** read-only `slots[]` 배열을 운반한다 — 데몬 슬롯 테이블의 per-slot 상태(`slot_id`·`status`(idle/holding/pending_buy/pending_sell)·`symbol`·`qty`·`limit_price`·`avg_price`·`portfolio_id`). 슬롯이 없어도 `[]`(null 금지). strategy 소비자는 무시 가능(additive). 운영자 CLI(`trex-core slots`)는 이 `slots[]` 를 표시한다.
- portfolio-hub 가 불가해 권위 cash/position 을 유지할 수 없으면(write `*_after` 갱신 불가 또는 일일 fetch 실패) 응답에 `degraded=true` + machine-readable reason code(예: `portfolio_hub_unavailable`/`snapshot_fetch_failed`/`cash_position_stale`) + sanitize 된 message 를 실어 전략의 신규 매매 보류를 신호한다(빈 리스트/silent stale 금지).

## Acceptance Criteria
1. Given 정상 상태, When 스냅샷을 요청, Then `assets`(배열) + meta(`view`·`available_slots`·`degraded`·`reason`) envelope 를 반환하고, 자산이 없어도 `assets` 는 `[]`(null 아님)다.
2. Given portfolio-hub 불가(권위 cash/position 유지 불가), When 요청, Then `degraded=true` + reason code 가 포함되고 raw 예외/자격증명 등 민감정보는 노출되지 않는다.
3. Given 응답 항목, Then 필드는 symbol/asset_id/cash_balance/asset_quantity/active_strategy_id/strategy_params(opaque) 이고 가격 필드는 없다.
4. (CHG-20260608-01) Given 스냅샷 요청, Then envelope 에 read-only `slots[]` 배열을 포함한다 — 각 항목은 `slot_id`·`status`·`symbol`·`qty`·`limit_price`·`avg_price`·`portfolio_id` 를 담고, 슬롯이 없어도 `[]`(null 아님)다. `assets[]` 와 독립이며 strategy 소비자는 무시 가능(additive, 하위호환).
5. (CHG-20260610-01, dcy-023/issue #22) Given 스냅샷 응답, Then `slots[]` 항목에 `allocated_capital` 키가 없다 — 구현이 계약 외로 노출하던 죽은 필드를 제거해 AC-4 의 문서화된 필드 집합과 구현을 정렬한다.

## Impacted Area
- Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md, docs/discovery/dcy-016_20260608_operator-cli-rpc-commands.md, docs/interface-contract.md
- Modules: trex_core/adapters/messaging (snapshot RPC 핸들러), trex_core/application/portfolio.py (`build_snapshot_envelope` — `slots[]`, (CHG-20260610-01) allocated_capital 노출 제거), 응답 스키마(transport-무관), trex_core/runtime/cli.py (REQ-032 companion)
- Tests: envelope 스키마 검증(빈 응답 포함), degraded 주입 테스트, `slots[]` 스키마(빈 배열·status enum) + `trex-core slots` 실제 슬롯 상태 표시

## Notes
- transport 는 dcy-006(REQ-021/022) 의 snapshot RPC 를 사용하며 본 REQ 는 logical 계약만 정의한다.
- NFR-3(가용성 degrade, OQ-5) + OQ-6(빈 표현)을 본 REQ 로 흡수/반영한다.
- 정확한 reason code enum/필드 스키마는 구현 단계에서 확정한다(dcy-005 OQ-5/OQ-6 결정 범위 내).

## Change Log

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

#### Change Summary
- dcy-005 FR-1/FR-3 + OQ-5/OQ-6 분해로 최초 생성(Proposed). NFR-3 흡수.

#### Intent
- 스냅샷 read 의 요청/응답 envelope 계약 + degrade 신호 정의.

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

#### Impacted Area Delta
- Docs:
  - dcy-005, interface-contract
- Modules:
  - adapters/messaging snapshot RPC 핸들러, 응답 스키마
- Tests:
  - envelope 스키마, degraded 주입

#### 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
- envelope 스키마 검증 + portfolio-hub 불가 주입으로 degraded 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
- snapshot RPC envelope 응답 + degraded 신호 + sanitization 구현 완료 상태로 동기화.

#### 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_snapshot_handler.py::test_envelope_shape_returned + test_snapshot_selection.py::test_empty_envelope_assets_is_list_not_null.
- AC-2: tests/application/test_snapshot_handler.py::test_degraded_signal_does_not_leak_credentials + 실 daemon 운영 검증.
- AC-3: tests/application/test_snapshot_selection.py::test_envelope_shape_no_price_field.

### CHG-20260608-01
- Date: 2026-06-08
- Author: project maintainers

#### Change Summary
- dcy-016 후속 정정. `trex-core slots`(REQ-032)가 universe `assets`(portfolio: asset_id/symbol/asset_quantity)를 **슬롯 상태로 오인 표시**하던 갭 — snapshot envelope 이 슬롯 상태 목록을 운반하지 않아 발생(운영자 관측: 10개 슬롯인데 universe portfolio 1개만, status 없음). envelope 에 **read-only per-slot 상태 목록 `slots[]` 를 additive 로 추가**한다(dcy-017 의 per-slot `watchdog` 동봉 선례와 동일 방식). BAT-007 에서 HTTP 슬롯 read(REQ-008/025) 제거 후 슬롯 상태 read 표면이 부재했던 점을 함께 해소.

#### Intent
- 운영자가 데몬의 **실제 슬롯 상태(idle/holding/pending_buy/pending_sell)** 를 snapshot RPC 로 관측할 수 있게 한다. strategy-facing `assets[]`(universe) 계약은 그대로 유지하고, 슬롯 상태는 별도 `slots[]` 로 분리 노출한다.

#### Acceptance Criteria Delta
- Added:
  - AC-4: Given 스냅샷 요청, Then envelope 에 read-only `slots[]` 배열을 포함한다 — 각 항목은 `slot_id`·`status`·`symbol`·`qty`·`limit_price`·`avg_price`·`portfolio_id` 를 담고, 슬롯이 없어도 `[]`(null 아님)다. `assets[]`(universe) 와 독립이며 strategy 소비자는 무시 가능(additive, 하위호환).
- Updated:
  - none (AC-1~3 의 `assets[]`/degraded/no-price 계약 불변)
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - docs/interface-contract.md(snapshot 응답에 `slots[]` 필드 추가), dcy-005/dcy-016
- Modules:
  - trex_core/application/portfolio.py(`build_snapshot_envelope` 에 `slots[]`), trex_core/application/messaging_handlers.py(envelope), trex_core/runtime/cli.py(REQ-032 companion — `slots` 가 `slots[]` 를 읽도록, `universe` 는 `assets[]` 유지)
- Tests:
  - envelope `slots[]` 스키마(빈 배열 포함), `trex-core slots` 가 universe 가 아닌 실제 슬롯 상태(status 포함)를 표시

#### Delivery Trace Delta
- Batches:
  - BAT-008 (REQ-028 최초 구현), BAT-020 (dcy-016 — `slots` CLI 가 갭 노출). 정정 구현은 신규 BAT-022 (예정).
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: yes (신규 AC-4)
- Existing Implementation Invalidated: no (AC-1~3 assets/degraded/no-price 근거 유지)
- Status Recommendation: Implemented → Approved (신규 AC-4 미구현)
- Follow-up Action: REQ-032 companion change-req + draft-batch(BAT-022) → 구현/검증

#### Validation Plan
- AC-4: envelope `slots[]` 스키마 테스트(빈 배열·status enum 포함) + `trex-core slots` 통합 검증(universe 가 아닌 실제 슬롯 상태 N개를 status 와 함께 표시).

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

#### Change Summary
- Status 변경: Approved → Implemented. BAT-022 release-candidate verification evidence 기반(AC-4 envelope `slots[]`).

#### Intent
- envelope `slots[]`(operator-facing per-slot 상태) 구현 완료 상태로 동기화.

#### 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
- AC-4: tests/application/test_snapshot_selection.py::test_envelope_shape_no_price_field + test_snapshot_handler.py::test_envelope_shape_returned(envelope `slots` list). 운영 재현: 신규 코드 데몬 + 실 PostgreSQL/RabbitMQ 에서 `trex-core slots` → slots=10·status 표시·DB `(2026-06-08,idle,10)` 일치(BAT-022 verification). pytest 인프라 게이트는 Human Approval Memo 수용 잔여.

### CHG-20260610-01

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

#### Change Summary

- (change-req, dcy-023/issue #22) snapshot envelope `slots[]` 에서 `allocated_capital` 노출 제거 — `build_snapshot_envelope`(trex_core/application/portfolio.py) 가 계약(AC-4 필드 집합) 외로 노출하던 죽은 필드를 삭제해 문서화된 계약과 구현을 정렬. AC-5 추가, Implemented→Approved(재구현 대기).

#### Intent

- Slot 도메인에서 allocated_capital 이 제거(REQ-002 CHG-20260610-02)됨에 따라 read 표면에서도 동일 필드를 제거. strategy/operator 소비자가 죽은 필드를 참조할 여지 차단.

#### Acceptance Criteria Delta

- Added:
  - AC-5: slots[] 항목에 allocated_capital 키 부재.
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta

- Modules: trex_core/application/portfolio.py(build_snapshot_envelope slots[] 매핑)
- Tests: snapshot envelope slots[] 스키마 테스트에서 allocated_capital 부재 확인 + 기존 fixture 정리

#### Delivery Trace Delta

- Batches: (예정) dcy-023 batch
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (dcy-023 batch 에서 수행)
- Existing Implementation Invalidated: yes (slots[] 노출 필드 변경)
- Status Recommendation: Approved (Implemented→Approved 되돌림)
- Follow-up Action: dcy-023 batch 구현·검증 후 confirm-req-implemented. CLI slots detail 표시 제거는 REQ-032 CHG-20260610-07 이 소유.

#### Validation Plan

- dcy-023 batch: envelope slots[] 스키마 테스트(allocated_capital 부재) + 전체 suite green.

### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-034(release-candidate) verification — allocated_capital 전 경로 제거(도메인/intent/영속/snapshot/CLI), 마이그레이션 013 테스트 DSN 멱등 round-trip + 컬럼 부재 확인, 전체 428 passed + PG 게이트 21 passed + ruff clean, grep 전수 0건. Blocking Issues 없음.

### CHG-20260611-01

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

#### Change Summary

- (change-req, dcy-025) 본 REQ 가 소유한 snapshot read 계약(`trex.snapshot.req` 요청 view/strategy_key, 응답 envelope `assets[]`/`available_slots`/`watchdog[]`/degraded)이 **폐기 예정** — `trex.slots.req`(REQ-073) + 슬롯 단일 행 스키마(REQ-074)로 대체된다(즉시 교체, dcy-025 OQ-1). degraded/reason/message health 신호 의미는 REQ-073 으로 승계. 현재 코드는 불변이므로 Implemented 유지(keep-current, REQ-005 CHG-20260610-01 선례), dcy-025 delivery 배치에서 표면 제거와 함께 **Deprecated** 전환.

#### Intent

- snapshot→slots 표면 교체의 추적성 forward-link.

#### Acceptance Criteria Delta

- Updated: 없음(dcy-025 delivery 배치에서 본 REQ 의 envelope AC 폐기)

#### Impacted Area Delta

- Docs: dcy-025, REQ-073/074/075
- Modules: (예정) messaging_handlers.py snapshot 핸들러·portfolio.py envelope 빌더 제거/대체

#### Delivery Trace Delta

- Batches: (예정) dcy-025 delivery 배치
- Releases: none

#### Revalidation Impact

- Reverification Needed: no (현 시점 — 코드 불변)
- Existing Implementation Invalidated: no (배치 구현 시점에 무효화·Deprecated 전환)
- Status Recommendation: keep-current
- Follow-up Action: dcy-025 배치에서 표면 제거 + 본 REQ Deprecated 전환.

#### Validation Plan

- dcy-025 배치 verification 으로 대체(snapshot 표면 부재 + slots 표면 계약 검증).