trex-core/docs/srs/Interface/req-080_strategy-state-set-rpc.md

req-080: trex.slots.strategy_state.set write RPC 계약 — occupancy_seq·version CAS

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

Intent

• 전략 데몬이 슬롯의 opaque strategy-state 를 write 하는 신규 RPC 계약을 정의한다. read 는 기존 trex.slots.req(REQ-073) 에 piggyback 하고(추가 왕복 없음), write 만 별도 RPC 로 분리해 evaluate() 순수성과 재시도 격리를 보존한다. (dcy-028 FR-2/OQ-2, issue #26 C-2)

Requirement

• 신규 RPC trex.slots.strategy_state.set 를 기존 계약 패턴(direct reply-to + JSON + per-instance queue_name({base}.{instance_key}))으로 신설한다.
• 요청 payload: {slot_id, strategy_id, expected_version:int, expected_occupancy_seq:int, data:str}. correlation_id = "{slot_id}:{strategy_id}:{expected_version}"(멱등 키), delivery persistent.
• 성공 응답: {ok:true, slot_id, strategy_id, version:<new>}.
• 실패 응답 reason 전체 집합 = {occupancy_changed, version_conflict, slot_inactive, state_too_large, bad_request}:
  • occupancy_changed: 슬롯 현재 occupancy_seq ≠ expected_occupancy_seq → {ok:false, reason, occupancy_seq:<cur>} (저장 안 함; 데몬 re-read 후 fresh restart).
  • version_conflict: stored version ≠ expected_version → {ok:false, reason, version:<cur>}.
  • slot_inactive: 슬롯 inactive/미존재 → {ok:false, reason} (저장 안 함).
  • state_too_large: data 가 size cap(REQ-079/NFR) 초과 → {ok:false, reason} (저장 안 함).
  • bad_request:<detail>: malformed payload(기존 intent 핸들러 패턴) → {ok:false, reason}.
• 핸들러는 REQ-079 StrategyStateStore 의 CAS 로 위임한다(저장 의미는 REQ-079 소유). data 는 opaque 로 전달하고 핸들러는 해석하지 않는다.
• 동일 correlation_id 재전송은 부작용 없음(멱등). 미인식 reason 에 대해 소비자 fail-closed 를 계약에 명시한다.

Acceptance Criteria

1. Given 기동된 데몬, When 토폴로지 선언, Then trex.slots.strategy_state.set(per-instance) 큐가 존재하고 direct reply-to 로 응답한다.
2. Given 유효 요청(occupancy_seq·version 일치), When set, Then {ok:true, version:<+1>} 를 반환하고 저장된다.
3. Given occupancy_seq 불일치, Then {ok:false, reason:"occupancy_changed", occupancy_seq:<cur>}. Given version 불일치, Then {ok:false, reason:"version_conflict", version:<cur>}. 둘 다 저장되지 않는다.
4. Given inactive 슬롯, Then {ok:false, reason:"slot_inactive"}. Given size cap 초과, Then {ok:false, reason:"state_too_large"}. Given malformed payload, Then {ok:false, reason:"bad_request:<detail>"}.
5. Given 동일 correlation_id 재전송, When 처리, Then 부작용 없이 동일 결과가 반환된다.
6. Given 응답 reason, When 집합 검사, Then {occupancy_changed, version_conflict, slot_inactive, state_too_large, bad_request} 외 값이 없다.

Impacted Area

• Docs: docs/interface-contract.md(strategy_state.set 계약 — REQ-082), docs/runtime-flows.md(write 흐름 — REQ-082)
• Modules: trex_core/adapters/messaging/topology.py(큐명), trex_core/application/messaging_handlers.py(신규 set 핸들러 — REQ-079 store 위임), trex_core/runtime/daemon.py(핸들러 와이어링)
• Tests: tests/application/(set 핸들러 6 reason 케이스 + 멱등), tests/adapters/messaging/(토폴로지)

Notes

• 저장·CAS 의미는 REQ-079 가 소유한다 — 본 REQ 는 RPC 계약(요청/응답 shape, reason 운반, 멱등, 큐). 핸들러는 store 로 위임만 한다.
• read piggyback(REQ-073/074)과의 비대칭(read 무료/write 분리)은 dcy-028 OQ-2 의도. 사이클당 다중 슬롯 write 시 N개 set RPC — optional batch 변형은 v1 범위 밖 후속.
• 출처: dcy-028 FR-2(C-2), OQ-2(별도 RPC), reject reason 집합(trex-tsl #4705990067 답변 정합).

Change Log

CHG-20260615-03

• Date: 2026-06-15
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-042 verification — trex.slots.strategy_state.set 큐(topology/rabbitmq declare) + make_strategy_state_set_handler(store 위임) + daemon consumer 스레드. AC-1~6 evidence: tests/application/test_strategy_state_set_handler.py(성공+5 reason+bad_request 2종+멱등+reason 집합). 479 passed, ruff clean. Blocking Issues 없음.

CHG-20260615-02

• Date: 2026-06-15
• Author: Justin Ko
• Type: status
• Summary: Proposed → Approved (confirm-req). 필수 필드·구체 AC(6개) 충족, source dcy-028(OQ-2 정합) 일치, reject reason 집합 trex-tsl #4705990067 답변과 정합. blocker 없음.

CHG-20260615-01

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

Change Summary

• dcy-028 FR-2/OQ-2 로부터 최초 생성(Proposed). strategy_state.set write RPC 계약 + occupancy_seq·version CAS + reject reason 전체 집합.

Intent

• write 를 별도 RPC 로 분리해 evaluate 순수성·재시도 격리 보존, read 는 slots.req piggyback.

Acceptance Criteria Delta

• Added: 큐/성공/occupancy·version reject/inactive·size·bad_request/멱등/reason 집합 6개 기준
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Docs: interface-contract.md, runtime-flows.md(REQ-082)
• Modules: topology.py, messaging_handlers.py, daemon.py
• Tests: set 핸들러 reason 케이스, 토폴로지

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/081/082 + REQ-073/074 CHG 동일 batch)

Validation Plan

• set 핸들러 단위 테스트(6 reason 케이스 + 멱등) + 토폴로지 선언 테스트로 RPC 계약 검증.