trex-core/docs/srs/Interface/req-028_snapshot-read-message-contract-and-envelope.md

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

• Status: Implemented
• 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, 하위호환).

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[]), 응답 스키마(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 수용 잔여.