trex-core/docs/discovery/dcy-019_20260609_slot-entry-count-and-closed-reallocation.md

0. 문서 상태

이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

• 상태: confirmed
• 문서 ID: dcy-019_20260609_slot-entry-count-and-closed-reallocation
• 이슈명: slot entry_count 추가 및 closed 슬롯 재할당 정책 (issue #18)
• 작성 시각(KST): 2026-06-09 13:13 KST
• 마지막 갱신 시각(KST): 2026-06-09 13:34 KST
• 대체됨: 없음
• 후속 Discovery 참조: 없음
• 생성된 REQ 참조: 신규 REQ 없음(거버넌스 전부 change-req). 변경 REQ: REQ-002/003/006/007/009 (각 CHG-20260609-01). Delivery: BAT-025 (release-candidate).

1. 계획 상태 요약

현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

• 연계 문서 현황:
  • 관련 점수 파일: 미생성
  • 관련 TODO/메모: GitHub issue #18(slot entry_count 추가 + closed 슬롯 재할당 정책). 기존 dcy-001/002(슬롯 도메인·preallocation), dcy-014(일자 경계 preallocation) 참조.
• 해석:
  • buy admission 은 현재 find_idle_slot(idle 1개 임의 선택)만 사용해 closed 슬롯을 재할당 후보로 보지 않으며, 슬롯별 진입 횟수를 기록하는 필드도 없다. issue #18 은 (1) slot-scoped entry_count 필드, (2) idle+closed 후보 중 entry_count 최소 우선 선택(+tie-break), (3) closed 직접 재할당, (4) 할당 전이 시 entry_count 증가를 요구한다.
  • 핵심 OQ(1~3) 전부 결정됨 — 데이터 모델(마이그레이션 008)·admission 흐름·슬롯 계약(+closed→pending_buy 신규 전이) 변경을 동반하는 신규 주기다. OQ-1: 신규 entry_count 는 daily_slot row 단독(기존 symbol-scoped daily_symbol_entries 와 무관·분리). OQ-2: 선택은 entry_count 오름차순 → updated_at 오름차순 → slot_id. OQ-3: closed 를 admission 후보에 직접 포함(closed→pending_buy 직접 전이), entry_count 는 →pending_buy 시 +1, 동시성은 SKIP LOCKED 보존.

2. 요구사항 판정 결과

이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

• 판정: 신규
• 근거
  • 슬롯 선택 정책(현재 idle-only find_idle_slot)과 슬롯 데이터 계약(EXPECTED_SLOT_FIELDS)에 entry_count 가 없어, 신규 영속 필드 + 마이그레이션 + admission 흐름 변경을 요구한다. 기존 REQ 문구 미세 조정으로 흡수되지 않는다.
  • 기존 daily_symbol_entries(symbol-scoped 재진입 카운터, REQ-002 AC-3)와 목적·키가 다른 slot-scoped 카운터를 도입하고, closed 슬롯 재할당이라는 새 도메인 정책을 정의하므로 독립 주기로 추적하는 것이 명확하다.

3. 문제점의 요약

문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

• 현재 상태
  • slot 진입 횟수 필드 없음: Slot 모델(trex_core/domain/slot/models.py)에 진입 횟수 필드가 없고, EXPECTED_SLOT_FIELDS(test_contract.py 로 강제되는 엄격 컬럼 계약)에도 없다. daily_slot 스키마(sql/001_create_slot_core_tables.sql)도 slot row 에 진입 카운터를 두지 않는다.
  • admission 은 idle-only 임의 선택: buy admission(trex_core/application/intents.py:_admit_buy)은 repo.find_idle_slot(postgresql.py:108, WHERE status='idle' LIMIT 1)으로 idle 슬롯 1개를 순서 규칙 없이 잡는다. closed 슬롯은 admission 후보가 아니며, 우선순위(진입 횟수) 개념이 없다.
  • closed 재사용은 별도 복구 전이: 상태 머신(domain/slot/state.py)에 closed→idle 복구 전이(#7)가 있고(service.py:130), 이때만 슬롯이 다시 idle 후보가 된다. admission 이 closed 를 직접 후보로 보지는 않는다.
  • 별개의 symbol-scoped 카운터(본 주기 범위 밖): daily_symbol_entries 테이블(sql/001, trading_date+symbol → entry_count, last_entry_at)이 closed→idle 복구 시 +1 증가한다(postgresql.py:160, REQ-002 AC-3). 이름은 같은 "entry_count" 이나 키(symbol)·목적(심볼 재진입 결정 입력)이 slot-scoped 할당 정렬과 전혀 다르다. 게다가 현재 production 소비자가 없다(get_today_entry_count 읽기는 테스트뿐 — 재진입 제한 게이트 미배선, trex-orbit 계보 보존 불변식 REQ-002 NFR-2). 따라서 신규 slot entry_count 와 개념적으로 무관하며, 본 Discovery 는 이 테이블을 변경하지 않는다(분리). 제거는 별도 트랙(아래 Out of Scope 참고).
  • baseline 문서(docs/project-structure.md, docs/runtime-flows.md, docs/data-model.md)는 존재하며 최신이다. 슬롯 할당·상태 전이는 기존 runtime flow 에 속한다.
• 기대 상태
  • daily_slot(슬롯 row)에 slot-scoped 진입 횟수가 영속되고, buy admission 이 idle+closed 후보 중 진입 횟수가 가장 적은 슬롯을 결정적 규칙(tie-break 포함)으로 선택한다.
  • closed 슬롯이 재할당 후보로 명시적으로 취급되어 슬롯 자원이 효율적으로 재사용된다.
  • 진입 횟수 증가 시점(할당 전이)이 명확히 정의되고, 신규 slot entry_count 는 daily_slot row 단독 source of truth 로 daily_symbol_entries 와 분리되어 이중 소스 모호성이 없다.
• 이해관계자
  • 문서 작성자(AI agent) — Discovery/REQ/Batch 산출물 작성
  • 리뷰어/승인자 — 데이터 모델·admission 정책·카운터 정합 결정 승인
  • 운영 담당자 — 슬롯 재사용·진입 이력 관측
  • 전략 모듈(간접) — admission 결과(어느 슬롯이 잡히는지)에 의존하나 계약상 슬롯 선택은 core 책임
• 제약사항
  • daily_slot 스키마 변경은 멱등 마이그레이션(008)으로 추가하고, EXPECTED_SLOT_FIELDS 계약·persistence flat slot 매핑·data-model.md 를 같은 변경 묶음으로 정합해야 한다(change-req Common Pitfall 1).
  • admission 의 동시성(마지막 슬롯 경합) 보존 — 현재 FOR UPDATE SKIP LOCKED/재시도 규약(intents.py)을 깨지 않아야 한다.
  • 상태 머신 불변식 변경: 현재 "6 상태 / 8 허용 전이"(state.py ALLOWED_TRANSITIONS, REQ-001/002 NFR-2, dcy-001 FR-2)에 closed→pending_buy 가 없다. 본 주기는 이 전이를 추가(8→9 전이)하므로 REQ-001/002 의 전이 집합 계약·전이 카운트 서술을 change-req 로 함께 정합해야 한다.
  • 신규 slot-scoped entry_count 와 기존 daily_symbol_entries(symbol-scoped, REQ-002 AC-3)는 본 주기에서 분리 유지(후자 미변경) — 회귀를 깨지 않는다.

주요 사용자 시나리오

사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

• 하루 중 일부 슬롯이 진입·청산(closed)을 반복한 뒤, 새 buy 가 들어오면 admission 이 idle 뿐 아니라 closed 슬롯도 후보로 보고 진입 횟수가 가장 적은 슬롯을 골라 슬롯 사용을 고르게 분산한다.
• idle 슬롯이 모두 소진됐지만 closed 슬롯이 남아 있을 때, 현재는 no_idle_slot 으로 거부되던 buy 가 closed 재할당으로 admit 된다.
• 운영자가 슬롯별 누적 진입 횟수를 조회해 그날 슬롯 회전·집중도를 파악한다(분석 기반).

4. 이번에 정의할 변경

이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

• daily_slot/Slot 모델에 slot-scoped entry_count(기본 0) 필드 추가 + 마이그레이션 008 + EXPECTED_SLOT_FIELDS 계약·persistence 매핑·data-model.md 정합.
• buy admission 슬롯 선택 정책 변경: 후보 = idle ∪ closed, 정렬 = entry_count 오름차순 → updated_at 오름차순(가장 오래 안 쓴 슬롯) → slot_id(OQ-2), 동시성(SKIP LOCKED/재시도) 보존. find_idle_slot → 후보 확장 selector 로 일반화.
• closed 슬롯 재할당 경로 정의(OQ-3): admission 이 closed 를 직접 후보로 잡아 closed→pending_buy 신규 전이(state.py 전이 추가)로 점유 필드 초기화·설정. entry_count 는 할당 전이(→pending_buy) 시 +1.
• baseline 문서(docs/runtime-flows.md admission/슬롯 선택 흐름, docs/data-model.md daily_slot 필드) 갱신. (신규 entry_count 가 daily_slot 단독임을 명시하고, 기존 daily_symbol_entries(심볼 재진입 카운터)와 역할이 다름을 data-model 에 구분 기록.)

영향 범위

변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

• 코드 영향:
  • trex_core/domain/slot/models.py — Slot.entry_count + EXPECTED_SLOT_FIELDS
  • trex_core/adapters/persistence/sql/008_*.sql — daily_slot entry_count 컬럼 추가(멱등)
  • trex_core/adapters/persistence/postgresql.py — flat slot 매핑, 후보 selector(idle∪closed, ORDER BY entry_count, SKIP LOCKED), 증가 로직
  • trex_core/domain/slot/repository.py / in_memory_repository.py — selector 포트 + 인메모리 동등 구현
  • trex_core/application/intents.py — _admit_buy 후보 selector 사용 + closed 재할당 처리
  • trex_core/domain/slot/service.py / state.py — closed→pending_buy 신규 전이 추가(허용 전이 집합), 할당 전이(→pending_buy) 시 entry_count +1, closed 직접 할당 시 점유 초기화·설정
• 문서 영향:
  • docs/data-model.md — daily_slot entry_count 필드
  • docs/runtime-flows.md — buy admission 슬롯 선택(idle∪closed, entry_count 정렬) 흐름
• 운영 영향:
  • 마이그레이션 008 적용(additive 컬럼, 기본 0) — 배포 시 1회. 슬롯 선택 동작이 바뀌므로 회귀 관측 필요.

5. 요구사항 목록

실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

기능 요구사항

• FR-1: daily_slot/Slot 에 slot-scoped entry_count 정수 필드(기본 0)를 추가하고 멱등 마이그레이션 008 + EXPECTED_SLOT_FIELDS 계약 + persistence flat 매핑 + data-model.md 를 정합한다.
• FR-2: buy admission 은 후보를 idle ∪ closed 로 확장하고, entry_count 오름차순 → updated_at 오름차순(가장 오래 안 쓴 슬롯) → slot_id(OQ-2) 순으로 결정적 선택한다. 마지막 슬롯 경합 동시성(FOR UPDATE SKIP LOCKED + 재시도)을 보존한다.
• FR-3: closed 슬롯은 admission 후보에 직접 포함되며, 선택 시 별도 closed→idle 왕복 없이 closed→pending_buy 직접 전이한다(OQ-3 — 신규 전이). 이때 점유 필드(symbol/qty/avg_price/limit_price/...)를 새 진입 값으로 초기화·설정한다(기존 closed→idle 리셋 의미 재사용).
• FR-4: slot entry_count 는 할당 전이(idle/closed → pending_buy) 시 +1 증가한다(OQ-3). 단일 트랜잭션 내에서 슬롯 claim·상태 전이·entry_count 증가를 함께 수행해 동시 buy 경합에서도 중복 카운트가 없다. 신규 entry_count 는 daily_slot row 단독이며 daily_symbol_entries(심볼 재진입 카운터, REQ-002 AC-3)와 무관·독립이다 — 본 주기에서 후자를 읽거나 변경하지 않는다.
• FR-5: docs/runtime-flows.md(admission 슬롯 선택)·docs/data-model.md(daily_slot) baseline 문서를 갱신한다.

비기능 요구사항

성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

• NFR-1: 동시성 안전 — 슬롯 선택·entry_count 증가는 advisory lock/SKIP LOCKED/단일 트랜잭션으로 경합·중복 카운트 없이 처리한다.
• NFR-2: 결정성 — 동일 후보 집합·동일 entry_count 분포에서 tie-break 규칙으로 선택 결과가 결정적이고 재현 가능하다.
• NFR-3: 하위호환 — 마이그레이션은 additive(기본 0), 기존 idle-only 동작은 closed 후보가 없을 때 결과적으로 보존(회귀 안전).

범위 경계

이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

• In Scope
  • slot-scoped entry_count 필드 + 마이그레이션 008 + 계약/매핑/data-model 정합
  • admission 후보 확장(idle∪closed) + entry_count 정렬 + tie-break + closed 재할당 + 증가 시점
  • 기존 daily_symbol_entries 와의 관계 확정 + runtime-flows/data-model 갱신
• Out of Scope
  • 슬롯별 수익률/PnL 집계(이슈 고려사항대로 ledger/log 기반이 적절 — 본 주기 제외)
  • 전략 모듈에 슬롯 선택 정책을 노출하는 계약 변경(슬롯 선택은 core 책임 유지)
  • preallocation 총량/스케줄 정책 변경(dcy-014 범위 — 불변)
  • daily_symbol_entries(심볼 재진입 카운터) 제거/변경 — 본 주기 제외. production 소비자 없음이 확인됐고 심볼 재진입 제한 미사용으로 결정됐으나, 보존 불변식(REQ-002 NFR-2)이라 캐주얼 삭제 불가 → 별도 REQ-002 change-req 트랙으로 처리(후속).
  • 운영자 CLI/스냅샷에 slot entry_count 노출 — 본 주기 제외(이슈가 분석/노출을 후순위로 명시). 필요 시 후속 change-req 후보.

6. 리스크/가정 목록

불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

리스크

• R-1 (Low): 신규 slot entry_count 와 기존 daily_symbol_entries.entry_count 가 같은 이름이라 코드/문서에서 혼동될 수 있다. (OQ-1 결정으로 이중 소스 자체는 해소 — 둘은 분리·무관, 후자는 본 주기 미변경.)
  • 완화 방안: data-model 에 두 카운터의 키·목적·증가 시점을 명확히 구분 기록. 신규 필드는 daily_slot 컬럼으로 테이블이 달라 물리적 충돌 없음. REQ-002 AC-3 회귀 보존(후자 미변경).
• R-2 (Medium): admission 후보에 closed 를 포함하면서 동시성(마지막 슬롯 경합)·점유 리셋이 어긋나면 잘못된 슬롯 재사용/상태 오염이 발생할 수 있다.
  • 완화 방안: FOR UPDATE SKIP LOCKED + 단일 트랜잭션 내 상태/점유/카운트 갱신, closed 직접 할당 시 기존 closed→idle 리셋 로직 재사용, 경합 회귀 테스트.
• R-3 (Medium): daily_slot 컬럼 추가가 EXPECTED_SLOT_FIELDS 계약·flat 슬롯 read/write 순서를 깨면 광범위 회귀가 난다.
  • 완화 방안: 모델·계약·persistence 매핑·data-model 을 같은 변경 묶음으로 갱신하고 test_contract.py green 확인.

가정

아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

• A-1: entry_count 는 trading_date 범위 내 slot row 기준(일 단위 preallocation 과 정합). 일자 경계에서 새 슬롯은 0 으로 시작한다.
• A-2: closed 슬롯은 같은 trading_date 안에서 재할당 후보다(전일 슬롯을 끌어오지 않는다 — dcy-014 trading_date 경계 유지).
• A-3: 슬롯 선택은 core admission 단독 책임이며 전략 모듈 계약에 영향을 주지 않는다.

오픈 질문

답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

• OQ-1: slot-scoped entry_count 의 source of truth 를 어떻게 둘 것인가 — (a) daily_slot row 단독, (b) 기존 daily_symbol_entries 병행 유지, (c) daily_symbol_entries 를 slot-scoped 로 대체/재정의.
  • 상태: Answered (2026-06-09, 사용자 결정)
  • 결정: (a) daily_slot row 단독. 신규 entry_count 는 daily_symbol_entries(심볼 재진입 카운터)와 개념·키·목적이 무관 → 본 주기에서 완전 분리(후자 미변경). 심볼 재진입 제한은 사용하지 않기로 했고 daily_symbol_entries 는 현재 production 소비자가 없어, 그 제거는 별도 REQ-002 change-req 트랙으로 후속 처리(본 주기 Out of Scope). 반영: §3 현재 상태/기대 상태, §4, FR-4, R-1.
• OQ-2: 동률(entry_count 동일) 시 tie-break 규칙은 무엇인가.
  • 상태: Answered (2026-06-09, 사용자 결정)
  • 결정: entry_count 오름차순 → updated_at 오름차순(가장 오래 안 쓴 슬롯) → slot_id. 결정적(NFR-2) + 직관적. 반영: FR-2, §4.
• OQ-3: closed 재할당 경로와 entry_count 증가 시점.
  • 상태: Answered (2026-06-09, 사용자 결정)
  • 결정: closed 를 admission 후보에 직접 포함하고 별도 closed→idle 왕복 없이 closed→pending_buy 직접 전이(state.py 신규 전이). entry_count 는 할당 전이(→pending_buy) 시 +1. 동시성은 기존 FOR UPDATE SKIP LOCKED 로 보존. 반영: FR-3/FR-4, §4.

7. 초기 성공 기준

이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

• S-1: idle 이 없고 closed 가 있는 상태에서 buy 가 closed 슬롯으로 admit 된다(이전엔 no_idle_slot 거부).
• S-2: 여러 후보가 있을 때 entry_count 최소 슬롯이 선택되고, 동률 시 tie-break 규칙대로 결정적으로 선택된다.
• S-3: 할당 전이 시 해당 slot 의 entry_count 가 정확히 1 증가하며, 동시 buy 경합에서도 중복 카운트가 없다. 기존 daily_symbol_entries(REQ-002 AC-3) 회귀가 green.

측정 방식 및 데이터 출처

각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

• S-1 측정 방식: idle=0, closed≥1 픽스처에서 admission 단위/통합 테스트 / 데이터 출처: daily_slot 상태 + admission 결과
• S-2 측정 방식: 다중 후보(상이/동일 entry_count) 픽스처에서 선택 결과 단언 / 데이터 출처: daily_slot entry_count + 선택된 slot_id
• S-3 측정 방식: 단일/동시 admission 후 entry_count 증분 단언 + daily_symbol_entries 회귀 테스트 / 데이터 출처: daily_slot.entry_count, daily_symbol_entries.entry_count

8. REQ로 넘기기 전 확인 체크

REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

• 범위(In Scope/Out of Scope) 확정
  • 기준: 운영자 노출은 본 주기 제외로 확정. In/Out 경계 명확.
• 성공 지표의 측정 방식/데이터 출처 확정
  • 기준: S-1~3 측정 픽스처/데이터 출처(daily_slot.entry_count/상태)가 테스트 가능한 형태로 정의됨
• High 영향 리스크 우선순위 및 해소 책임자 지정
  • 기준: R-1(이중 소스)은 OQ-1 결정(daily_slot 단독·분리)으로 Low 로 해소됨. 잔여 High 리스크 없음.
• 모든 오픈 질문(OQ) Open 상태 없음 확인
  • 기준: OQ-1/2/3 전부 Answered (2026-06-09 사용자 결정)
• Freeze 확정 담당자(CONFIRMED_BY) 지정
  • 기준: 승인자 Justin confirm-discovery 수행

9. 파일 처리 결과

이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

• 처리 결과: 생성
• 생성 경로: docs/discovery/dcy-019_20260609_slot-entry-count-and-closed-reallocation.md
• 참조 문서:
  • docs/discovery/dcy-001_20260603_slot-pure-domain-migration.md (슬롯 도메인·daily_symbol_entries 기원, REQ-002)
  • docs/discovery/dcy-014_20260608_trading-date-configurable-timezone-kst.md (일자 경계 preallocation)
  • docs/data-model.md, docs/runtime-flows.md (baseline — 갱신 대상)

10. 사용자 결정 필요 항목 요약

사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

DECIDE

• 없음 (OQ-1/2/3 사용자 결정 완료 — §6 참조. 운영자 노출은 본 주기 제외로 확정 — §5)

CONFIRM

• 없음 (이슈 #18 재구성 ①entry_count 필드 ②idle/closed 중 entry_count 최소 우선 ③closed 재할당 후보 ④할당 전이 시 증가 — 사용자가 OQ-1/2/3 결정으로 확인함)

DATA

• 없음 (외부 데이터 의존 없음 — 전부 내부 도메인/스키마 결정)

11. Discovery Freeze

REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

• 범위: # 5. 요구사항 목록 > 범위 경계
• 리스크/오픈 질문: # 6. 리스크/가정 목록
• 성공 기준: # 7. 초기 성공 기준
• 인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
• 사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

• Handoff Decision: 승인
• Handoff Rationale: OQ-1/2/3 전부 Answered(사용자 결정 반영), C형 플레이스홀더 0, 저장소 사실 재확인 일치(slot entry_count 부재·idle-only admission·closed→pending_buy 미존재 검증). REQ Drafting 인계 가능.
• Ready for REQ Drafting: true
• Confirmed By: Justin
• Confirmed At (KST): 2026-06-09 13:34 KST