trex-core/docs/srs/Interface/req-002_slot-pure-domain-port.md

req-002: slot 순수 도메인 이식 및 공개 API 확정

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

Intent

• 검증된 slot 상태머신/서비스 계약을 인프라에 오염되지 않은 storage-agnostic 코어로 trex-core 에 이식해, trex-core 의 표준 도메인 작성 패턴(순수 도메인 + Protocol 저장소 경계)을 확립한다.

Requirement

• trex-orbit 의 순수 6개 모듈(state/models/errors/repository/service/in_memory_repository)과 __init__.py 를 trex_core.domain.slot 네임스페이스로 이식하고, 모듈 간 import 경로를 trex_core.domain.slot.* 로 통일하며, 공개 API 를 인프라 심볼 없이 노출한다.

Acceptance Criteria

1. Given 이식 완료, When from trex_core.domain.slot import SlotState, Slot, SlotCapacity, SlotTransitionRecord, SlotRepository, SlotService, SlotDomainError, SlotNotFoundError, SlotStateMismatchError, SlotTransitionError, is_allowed_transition, SLOT_ADVISORY_LOCK_ID, ALLOWED_TRANSITIONS 를 실행, Then 모두 import 에 성공한다.
2. Given 이식된 도메인 코드, When 정적 import 스윕, Then stdlib 와 trex_core.domain.slot 내부 참조 외 외부 의존(psycopg/네트워크/CLI/config) import 가 0이다. (NFR-1)
3. Given 공개 API, When __init__.py 의 __all__ 을 확인, Then PostgreSQLSlotRepository·check_slot_domain_schema_drift 등 인프라 심볼이 노출되지 않는다.
4. Given SlotService, When 6 상태/9 base 전이(closed→pending_buy 포함, dcy-019)/advisory-lock 직렬화/closed→idle 재진입 +1/→pending_buy 시 slot entry_count +1(dcy-019)/closed→pending_buy clean-slate 점유 초기화/lock 보유 중 외부 I/O 금지 동작을 확인, Then 보존된다. (NFR-2 — 검증은 REQ-003)
5. (CHG-20260610-02, dcy-023/issue #22) Given allocated_capital 제거 후, Then Slot 모델과 EXPECTED_SLOT_FIELDS 에 allocated_capital 필드가 없고, SlotService 의 설정/전이 경로(buy 진입·전이 시 set/clear)에서 해당 파라미터가 제거된다.
6. (CHG-20260612-01, issue #25) Given SlotRepository.list_slots(instance_key, status_filter=None), When status_filter 가 status 값 집합(예: {"inactive"}, {"pending_buy","pending_sell"})이면, Then 해당 status 슬롯만 반환하고 None(미지정)이면 기존대로 전체를 반환한다(in-memory 구현 포함). 기존 무인자 호출자는 동작이 불변이다.

Impacted Area

• Docs: docs/interface-contract.md, docs/data-model.md (계약 기준 — 큰 변경 없을 수 있음)
• Modules: trex_core/domain/slot/{init,state,models,errors,repository,service,in_memory_repository}.py, (CHG-20260610-02) models.py Slot/EXPECTED_SLOT_FIELDS + service.py allocated_capital 제거, (CHG-20260612-01) repository.py SlotRepository.list_slots 시그니처 status_filter 옵션 + in_memory_repository.py 구현
• Tests: REQ-003 에서 이식 단위테스트 + 계약 테스트로 검증

Notes

• NFR-1(순수 경계)·NFR-2(불변식 보존)를 본 REQ 의 acceptance 로 흡수. NFR-3(컬럼 계약)은 REQ-003 계약 테스트가 강제한다.
• 이식 시 유일한 코드 수정은 __init__.py docstring 정리 수준이며 로직 변경은 없다(dcy-001 A-2).
• 네임스페이스 trex_core.domain.slot 은 dcy-001 OQ-1 결정. REQ-001(부트스트랩) 선행.
• 출처: dcy-001 FR-2.

Change Log

CHG-20260603-01

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

Change Summary

• dcy-001 FR-2 로부터 최초 생성(Proposed). NFR-1·NFR-2 를 acceptance 로 흡수.

Intent

• slot 순수 도메인 이식 + 공개 API 확정 요구사항을 backlog 로 정규화.

Acceptance Criteria Delta

• Added:
  • 공개 API import, 외부 의존 0, 인프라 심볼 비노출, 도메인 불변식 보존 4개 기준
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/interface-contract.md, docs/data-model.md
• Modules:
  • trex_core/domain/slot/* (6 모듈 + init)
• Tests:
  • REQ-003 에 위임

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-001 과 동일 batch 가능)

Validation Plan

• 공개 API import 성공 + import 스윕(외부 의존 0) + REQ-003 테스트 통과로 검증.

CHG-20260603-02

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

Change Summary

• Status Proposed → Approved (confirm-req).

Intent

• 승인 게이트(필수 필드·구체 AC·blocker 없음) 충족, source dcy-001(confirmed, handoff 승인)과 모순 없음 확인.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register 상태 Approved)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • none (batch 편성 전)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs / draft-batch 로 delivery batch 편성

Validation Plan

• 승인 후 batch planning 에서 본 REQ 의 Acceptance Criteria 를 검증 기준으로 사용.

CHG-20260603-03

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

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-001 release-candidate).

Intent

• BAT-001 verification.md 의 evidence(공개 API import / import 스윕 외부 의존 0 / __all__ 인프라 심볼 0 / 도메인 불변식 테스트)로 AC1~AC4 충족 → 구현 완료 동기화.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register Implemented)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • BAT-001 (release-candidate)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: draft-release 로 release 편성

Validation Plan

• BAT-001 verification evidence 재참조로 충분.

CHG-20260608-01

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

Change Summary

• (change-req, dcy-012/issue #10) 슬롯 도메인 필드 entry_price → limit_price(side 무관 "현재 pending 주문 지정가") 내부 rename + 생애주기 정의: pending 진입 시 set, pending 이탈(→HOLDING/→CLOSED) 시 None clear. transit_slot/_apply_transition_fields 파라미터·EXPECTED_SLOT_FIELDS 반영. BAT-016 재구현·재검증 완료 → Implemented 유지.

Intent

• 매수 지정가가 매도 주문에 누수되는 구조적 원인을 도메인 모델에서 제거(clear-on-exit). 가격 필드 의미를 side 무관으로 통일.

Acceptance Criteria Delta

• Updated:
  • Slot.entry_price → limit_price; →HOLDING/→CLOSED 전이 시 limit_price clear, →PENDING_* 전이 시 set.

Impacted Area Delta

• Modules: trex_core/domain/slot/models.py(Slot/EXPECTED_SLOT_FIELDS), trex_core/domain/slot/service.py(transit_slot/_apply_transition_fields clear-on-exit)
• Tests: tests/domain/slot/test_service.py(holding clear), tests/domain/slot/test_contract.py(필드셋)

Delivery Trace Delta

• Batches: BAT-016
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-016 에서 완료)
• Existing Implementation Invalidated: yes (entry_price 필드명/유지 의미)
• Status Recommendation: Implemented (change-req → BAT-016 재검증)
• Follow-up Action: confirm-req-implemented(BAT-016).

Validation Plan

• BAT-016: 전이별 set/clear 단위 + 컬럼 계약 가드(REQ-003) 정합.

CHG-20260609-01

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

Change Summary

• (change-req, dcy-019/issue #18) 슬롯 도메인에 (1) slot-scoped Slot.entry_count(기본 0) 필드 + EXPECTED_SLOT_FIELDS 추가, (2) 상태 머신 허용 전이에 closed→pending_buy(closed 슬롯 직접 재할당) 추가(8→9 base 전이), (3) _apply_transition_fields 에 closed→pending_buy clean-slate 점유 초기화 + 모든 →pending_buy(idle→/closed→) 시 entry_count +1 로직 반영. 기존 daily_symbol_entries(symbol-scoped, AC-3)는 무관·미변경. BAT-025 재구현·재검증 완료 → Implemented 유지.

Intent

• 슬롯 자원을 고르게 재사용(최저 진입 우선)하고 idle 소진 시 closed 재할당을 허용하기 위해, 슬롯 단위 누적 진입 횟수를 도메인 정본에 영속하고 closed→pending_buy 직접 전이를 도메인 계약에 추가.

Acceptance Criteria Delta

• Updated:
  • AC-4: "6 상태/8 전이" → "6 상태/9 base 전이(closed→pending_buy 포함)". 불변식 보존 대상에 →pending_buy 시 entry_count +1, closed→pending_buy clean-slate 점유 초기화 추가.
• Added:
  • Slot.entry_count(int, 기본 0) 필드가 EXPECTED_SLOT_FIELDS 계약에 포함된다.

Impacted Area Delta

• Modules: trex_core/domain/slot/models.py(Slot.entry_count/EXPECTED_SLOT_FIELDS), trex_core/domain/slot/state.py(closed→pending_buy 전이), trex_core/domain/slot/service.py(clean-slate + entry_count +1)
• Tests: tests/domain/slot/test_state.py(전이 카운트 14→15), test_contract.py(필드셋), test_slot_entry_count.py(신규)

Delivery Trace Delta

• Batches: BAT-025
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-025 에서 완료)
• Existing Implementation Invalidated: no (additive — 기존 idle-only 동작은 closed 후보 부재 시 보존, 회귀 green)
• Status Recommendation: Implemented (change-req → BAT-025 재검증)
• Follow-up Action: confirm-req-implemented(BAT-025).

Validation Plan

• BAT-025: 전이 카운트/계약 가드 + entry_count 증분·보존 + closed→pending_buy clean-slate 단위 테스트 green; daily_symbol_entries(AC-3) 회귀 green.

CHG-20260610-01

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

Change Summary

• (change-req, dcy-020 자산 중심 슬롯 모델) 본 REQ 의 슬롯 도메인(6상태·closed→idle 복구·entry_count·익명 슬롯)이 dcy-020 으로 재정의/폐기 예정. 신규 REQ-057(상태머신 inactive↔pending_buy↔holding↔pending_sell·holding 로컬·인스턴스 스코프 lock)·REQ-056(영구 슬롯 필드·entry_count 제거)·REQ-062(qty hub 정본+미러)가 대체. 현재 코드는 불변이므로 Implemented 유지(keep-current), 실제 폐기/재정의는 dcy-020 delivery 배치(상태머신/스키마 BAT)에서 확정한다.

Intent

• 자산 1:1 영구 슬롯 모델 전환의 추적성을 본 REQ 에 forward-link.

Acceptance Criteria Delta

• Updated: 없음(본 주기 변경 없음 — dcy-020 delivery 배치에서 AC 재정의 예정)

Impacted Area Delta

• Docs: dcy-020, REQ-056/057/062
• Modules: (예정) domain/slot/state.py·models.py·service.py
• Tests: (예정) REQ-057 테스트로 대체

Delivery Trace Delta

• Batches: (예정) dcy-020 상태머신/스키마 배치
• Releases: none

Revalidation Impact

• Reverification Needed: no (현 시점)
• Existing Implementation Invalidated: no (코드 불변 — dcy-020 delivery 시 무효화·재정의)
• Status Recommendation: keep-current
• Follow-up Action: dcy-020 delivery 배치에서 Deprecated/재정의 + 그때 status 전환.

Validation Plan

• dcy-020 상태머신 배치의 verification 으로 대체.

CHG-20260610-02

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

Change Summary

• (change-req, dcy-023/issue #22) 죽은 필드 allocated_capital 을 슬롯 도메인에서 제거 — Slot 모델·EXPECTED_SLOT_FIELDS 계약·SlotService 의 설정/전이(set/clear) 경로에서 삭제. 소비처(의사결정/회계/사이징) 0건 확인(dcy-023 §3). AC-5 추가, Implemented→Approved(재구현 대기).

Intent

• 실제 소비되는 필드만 슬롯 계약에 남겨 유지 비용과 "capital 이 사이징한다"는 오해를 제거. dcy-021 사이징 계약(전략이 qty 계산, core 미관여) 확정의 귀결.

Acceptance Criteria Delta

• Added:
  • AC-5: Slot 모델·EXPECTED_SLOT_FIELDS·SlotService 경로에서 allocated_capital 부재.
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Modules: trex_core/domain/slot/models.py(Slot/EXPECTED_SLOT_FIELDS), trex_core/domain/slot/service.py(설정/전이 경로 파라미터 제거)
• Tests: tests/domain/slot/ 계약 테스트(필드셋) + allocated_capital 참조 테스트 정리

Delivery Trace Delta

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

Revalidation Impact

• Reverification Needed: yes (dcy-023 batch 에서 수행)
• Existing Implementation Invalidated: yes (필드 제거 — 기존 필드셋 계약 evidence 무효)
• Status Recommendation: Approved (Implemented→Approved 되돌림)
• Follow-up Action: dcy-023 batch 구현·검증 후 confirm-req-implemented.

Validation Plan

• dcy-023 batch: 필드셋 계약 테스트(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-20260612-01

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

Change Summary

• (change-req, issue #25) SlotRepository.list_slots 에 optional status_filter 파라미터를 추가해 status 필터링을 저장소 경계로 내린다. 시그니처 list_slots(instance_key, status_filter: Optional[set[str]] = None) — None 은 기존(전체), 값 집합이면 해당 status 만 반환. in-memory 구현도 동일 의미로 갱신. slots RPC 핸들러(REQ-073)의 per-request full scan + Python 필터를 제거하기 위한 포트 확장. 신규 AC-6 추가 구현·검증 필요 → Implemented → Approved 되돌림.

Intent

• trex.slots.req 가 매 요청마다 전 슬롯을 fetch 한 뒤 Python 에서 거르던 구조(issue #25)를 DB 레벨 필터로 바꾸기 위해, 도메인 포트(list_slots)와 in-memory 더블을 먼저 확장한다. 기존 무인자 호출자(reconcile/safety-sell 등)는 default None 으로 동작 불변.

Acceptance Criteria Delta

• Added:
  • AC-6: list_slots(instance_key, status_filter) — status 값 집합 필터 + None 전체, in-memory 포함, 기존 호출자 불변.
• Updated/Removed: 없음

Impacted Area Delta

• Docs: 없음
• Modules: trex_core/domain/slot/repository.py(Protocol 시그니처), trex_core/domain/slot/in_memory_repository.py(구현)
• Tests: in-memory list_slots(status_filter) 단위 — status 집합 필터 + None 전체 + 기존 무인자 회귀

Delivery Trace Delta

• Batches: BAT-040 (예정, issue #25)
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-040 에서 AC-6 + 기존 AC 회귀)
• Existing Implementation Invalidated: no (추가 파라미터는 default None 으로 기존 동작 보존). 단 신규 AC-6 미구현으로 Implemented 유지 불가 → Approved.
• Status Recommendation: Implemented → Approved
• Follow-up Action: confirm-req → BAT-040 구현·검증 → confirm-req-implemented

Validation Plan

• BAT-040: in-memory list_slots status 집합 필터 + None 전체 단위 테스트, 기존 무인자 호출 회귀, 전체 suite + ruff clean.

CHG-20260612-IMPL

• Date: 2026-06-12
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-040(release-candidate) verification — AC-6 list_slots(status_filter) in-memory 5종(None 전체/단일 status/pending 그룹/무매치/instance 스코프) PASSED, 무인자 호출자 default None 동작 보존(전체 439 passed), ruff clean. Blocking Issues 없음.