Bootstrap StagePilot baseline for slot domain migration

Initialize baseline seed, four baseline docs (project-structure,
runtime-flows, interface-contract, data-model), and the active
discovery/srs/batches/releases indexes. Content derived from the
trex-orbit slot pure-domain migration plan (trex-core as a new base,
pure domain only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/interface-contract.md

@@ -0,0 +1,113 @@
+# Trex Core Interface Contract
+
+- Baseline Mode: mixed
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: draft
+- Owner: project maintainers
+- Last Updated (KST): 2026-06-03
+- Source Discovery / Batch: bootstrap-baseline (pre-Discovery)
+- Primary Runtime: library
+
+## Project Summary
+- trex 제품군의 공용 베이스로, 첫 도메인으로 trex-orbit 의 일일 거래 슬롯 생명주기(slot) 순수 도메인을 storage-agnostic 하게 이식한 코어다.
+
+## Primary Domain
+- 자동매매 일일 거래 슬롯 생명주기 도메인 (equity trading slot lifecycle)
+
+## Purpose
+- This document captures the approved external and cross-boundary interface contracts for the project.
+- It is a cross-cutting reference for REQ drafting, batch design, implementation, verification, and handoff.
+
+## Scope
+- Covers in-process domain-service APIs and the persistence boundary Protocol (library 형태라 외부 HTTP/CLI 표면은 아직 없음).
+- Does not duplicate full business requirements already owned by REQ documents.
+- Does not replace low-level code references or generated API artifacts.
+
+## Interface Summary
+
+- SlotService :: 슬롯 생명주기 도메인 서비스(전이/사전할당/가용성/재진입 카운트)
+- SlotRepository (Protocol) :: 도메인 ↔ 저장소 경계 계약
+
+## Interface: `SlotService`
+
+- Type: internal-service
+- Consumers / Producers: 상위 애플리케이션(예: trex-orbit 류 매매 데몬)의 매수/매도/주문 결정 경로 및 운영자 도구
+- Purpose: 슬롯 상태 전이를 레이스-프리하게 수행하고 일일 슬롯 가용성/재진입 카운트를 계산한다.
+- Stability: internal
+
+### Inputs
+
+- preallocate_daily_slots(trading_date, count) :: 거래일 idle 슬롯 멱등 사전 할당 (count > 0)
+- transit_slot(slot_id, from_state, to_state, reason, actor, **fields) :: advisory lock 하 원자 상태 전이
+- get_today_entry_count(trading_date, symbol) :: 재진입 정책 입력 조회
+- compute_slot_capacity(trading_date, total_slots) :: 가용성 스냅샷 계산 (total_slots > 0)
+
+### Outputs
+
+- Slot :: 전이 후 슬롯 행 스냅샷
+- SlotCapacity :: idle/holding/pending 카운트 + scarcity_ratio
+- int :: 사전 할당 수 / 재진입 카운트
+- slot_transition_log append :: 모든 전이의 append-only 감사 기록(부수 효과)
+
+### Error Contract
+
+- SlotTransitionError :: 허용되지 않은 (from_state, to_state) 전이
+- SlotStateMismatchError :: read-write 사이 상태 변동(레이스 감지)
+- SlotNotFoundError :: 존재하지 않는 slot_id
+- ValueError :: count <= 0 또는 total_slots <= 0
+
+### Compatibility Rules
+
+- 6 상태 / 8 전이 패밀리 계약을 깨는 변경은 breaking 으로 취급한다.
+- 상태 변경 API 는 transactional_advisory_lock 안에서만 수행하고 lock 보유 중 외부 I/O 를 금지한다.
+
+## Interface: `SlotRepository (Protocol)`
+
+- Type: internal-service
+- Consumers / Producers: SlotService(소비) ↔ 저장소 구현체(InMemorySlotRepository / 향후 PostgreSQLSlotRepository)
+- Purpose: 도메인을 특정 저장소 기술에서 분리하는 영속화 경계 계약.
+- Stability: internal
+
+### Inputs
+
+- transactional_advisory_lock(lock_id) :: 단일 트랜잭션 + advisory lock 컨텍스트 매니저
+- pre_allocate_slots / fetch_slot / find_idle_slot / update_slot :: daily_slot CRUD
+- append_transition_log :: append-only 전이 로그
+- increment_symbol_entry / get_symbol_entry_count :: 재진입 카운터
+- count_slots_by_status :: 상태별 집계
+
+### Outputs
+
+- Slot / SlotTransitionRecord :: 도메인 모델
+- dict[SlotState, int] :: 상태별 카운트
+- int :: 재진입 카운트 / 사전 할당 수
+
+### Error Contract
+
+- SlotNotFoundError :: update 대상 row 부재
+
+### Compatibility Rules
+
+- 구현체는 advisory lock 직렬화와 append-only 전이 로그 의미를 반드시 보장한다.
+- 구현체는 lock 보유 중 외부 I/O 를 수행하지 않는다.
+
+## Shared Constraints
+
+- 도메인은 외부 의존(브로커, DB 드라이버 등)을 직접 호출하지 않는다(순수 도메인 경계).
+- 모든 상태 변경은 단일 advisory lock(SLOT_ADVISORY_LOCK_ID)으로 직렬화한다.
+
+## Current Gaps / Planned Changes
+
+- 영속화 구현체(PostgreSQL)와 그에 딸린 SQL 스키마/마이그레이션은 이번 이관 범위 밖이며 향후 도입 예정.
+- 외부 HTTP API / CLI 표면 없음(trex-orbit 의 `trex slot` CLI 미이식).
+- 패키지 네임스페이스 결정(plan.md OQ-1)에 따라 import 경로 계약이 확정된다.
+
+## Update Triggers
+
+- Update this document when an externally visible API, event, CLI, or file contract changes.
+- Update this document when a batch changes compatibility, validation, or error behavior.
+- Update this document when a new external consumer or producer is introduced.
+
+## Change Log
+
+- 2026-06-03 :: bootstrap-baseline 으로 초기 인터페이스 계약 baseline 생성(SlotService + SlotRepository Protocol).