feat(slot,intent): slot strategy-state 저장소 (dcy-028) + sell retryable 플래그 (issue #27)

BAT-042 (dcy-028 / issue #26 C-1/C-2/C-2b/C-3, REQ-079~082 + REQ-073/074 CHG): - slot_strategy_state 별도 테이블 + StrategyStateStore(in-memory+PG) + occupancy_seq·version CAS + opaque UTF-8 data + 2단 size cap (REQ-079) - trex.slots.strategy_state.set write RPC — reject reason 집합, 멱등 (REQ-080) - Slot.occupancy_seq 필드 + inactive→pending_buy bump + →INACTIVE close 삭제 훅 → 점유 전환 ABA 구조적 차단 (REQ-081) - slots.req 응답 행에 strategy_state 맵(batched 조립)·occupancy_seq additive (REQ-073 AC-7/REQ-074 AC-6) - 마이그레이션 014(occupancy_seq)/015(slot_strategy_state), baseline 문서 정합 (REQ-082) BAT-043 (issue #27 / REQ-007 CHG): - rejected SellIntent 응답에 additive retryable: bool (core 소유 reason→retryable 매핑, 미인식 기본 true, bad_request* false) — 손절매 재시도 안전 경로 decoupling 검증: 487 passed, 47 skipped (신규 41: store CAS 6+ABA, occupancy bump/close 4경로, set RPC 9, slots read 5, retryable 8, PG 게이트), ruff clean. REQ-079·080·081·082·073·074·007 → Implemented. issue #27 close. PG 경로 실 DB 검증은 release 위임. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-15 19:27:57 +09:00
parent bfadd0d5c8
commit e0d4e71304
40 changed files with 1941 additions and 14 deletions
@@ -0,0 +1,77 @@
+# req-082: strategy-state baseline 문서 정합 — read/write/삭제 흐름 + occupancy_seq 가드 + 저장소 구조
+
+- Status: Implemented
+- Type: Documentation
+- Priority: Medium
+- Owner: project maintainers
+
+## Intent
+- Slot strategy-state 저장소의 구조·흐름·계약 경계를 baseline 문서에 명시해 이후 REQ/batch·전략 데몬·운영자가 참조 가능하게 한다. 특히 read piggyback / write 별도 RPC 비대칭, occupancy_seq 점유 가드, close 삭제 불변식, opaque/size cap 경계를 문서로 확정한다. (dcy-028 FR-4)
+
+## Requirement
+- `docs/runtime-flows.md` 에 strategy-state 흐름을 추가한다: 데몬 decision-cycle(`trex.slots.req` read piggyback → `evaluate()` → 변경 시 `trex.slots.strategy_state.set` write), occupancy_seq·version CAS, 점유 전환 가드(`occupancy_changed`), 슬롯 close(`→INACTIVE`) 시 strategy_state 삭제 훅.
+- `docs/project-structure.md` 에 저장소 구조를 반영한다: `slot_strategy_state` 테이블(복합 PK), `StrategyStateStore` 포트 + PG/in-memory 구현 위치, slot `occupancy_seq` 컬럼.
+- `docs/interface-contract.md` 에 `trex.slots.strategy_state.set` 계약(요청/응답 shape, reject reason 집합)과 slots.req 응답의 strategy_state 맵·occupancy_seq 필드(C-1)를 명시한다.
+- 경계 명시: trex-core 는 `data` 를 해석하지 않는다(opaque), schema 는 전략 소유, size cap(기본 1~2KB / ceiling 4KB byte), 단일 writer 전제, full 3계층 분할은 후속 Discovery.
+
+## Acceptance Criteria
+1. Given `docs/runtime-flows.md`, When strategy-state 섹션 확인, Then read piggyback/write 별도 RPC·occupancy_seq 가드·close 삭제 흐름이 현행 코드(REQ-079/080/081)와 정합하게 기술되어 있다.
+2. Given `docs/project-structure.md`, When 확인, Then `slot_strategy_state` 테이블·StrategyStateStore·occupancy_seq 컬럼 위치가 반영되어 있다.
+3. Given `docs/interface-contract.md`, When 확인, Then strategy_state.set 계약(요청/응답/reject reason 집합)과 slots.req 행의 strategy_state·occupancy_seq 필드가 명시되어 있다.
+4. Given 신규 전략 개발자, When baseline 문서만으로 strategy-state 사용 모델 파악 시도, Then opaque 경계·size cap·점유 가드·삭제 책임(core)이 모호함 없이 판단 가능하다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(strategy-state 흐름 + Change Log), docs/project-structure.md(저장소 구조), docs/interface-contract.md(계약), docs/data-model.md(스키마 참조 — REQ-079/081 과 정합)
+- Modules: 없음(문서 전용)
+- Tests: 없음(문서 diff 리뷰로 검증)
+
+## Notes
+- REQ-079/080/081 구현 결과와 같은 batch 에서 정합 — 코드 확정 후 문서화(선례: REQ-075/078 등 baseline 정합 REQ).
+- 출처: dcy-028 FR-4, S-1~S-4 의 문서 참조 가능성.
+
+## Change Log
+
+### CHG-20260615-03
+- Date: 2026-06-15
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-042 verification — `docs/runtime-flows.md`(slot strategy-state 흐름 + Change Log), `docs/project-structure.md`(strategy_state.py 책임), `docs/interface-contract.md`(strategy_state.set 계약 + slots.req additive + Change Log) 반영, 현행 코드 정합. AC-1~4 충족(흐름/구조/계약/경계 명시). Blocking Issues 없음.
+
+### CHG-20260615-02
+- Date: 2026-06-15
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → Approved (confirm-req). 필수 필드·구체 AC(4개) 충족, source dcy-028(FR-4) 정합. 코드 확정 후 문서화(REQ-079/080/081 과 동일 batch). blocker 없음.
+
+### CHG-20260615-01
+- Date: 2026-06-15
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-028 FR-4 로부터 최초 생성(Proposed). strategy-state read/write/삭제 흐름·occupancy_seq 가드·저장소 구조·계약 baseline 정합.
+
+#### Intent
+- strategy-state 모델의 구조·흐름·경계를 문서로 확정해 운영·후속 개발·전략 데몬 참조점 제공.
+
+#### Acceptance Criteria Delta
+- Added: runtime-flows/project-structure/interface-contract 정합 + 개발자 판단 가능성 4개 기준
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs: runtime-flows.md, project-structure.md, interface-contract.md, data-model.md
+- Modules: 없음
+- Tests: 없음
+
+#### 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 후 batch 편성(REQ-079/080/081 + REQ-073/074 CHG 와 동일 batch, 코드 확정 후 문서화)
+
+#### Validation Plan
+- baseline 문서 diff 리뷰 — strategy-state 흐름·구조·계약 섹션 존재 + 현행 코드 정합 확인.