Deliver BAT-001: bootstrap trex-core + port slot pure domain

Implement REQ-001~004 (dcy-001): scaffold the trex-core package
(pyproject, trex_core/, tests/), port the slot pure domain into
trex_core.domain.slot with import rewrites, add the EXPECTED_SLOT_FIELDS
contract guard (test_contract), and port the state/service unit tests.

Verification: 56 passed, ruff clean, import sweep shows zero external
deps, public __all__ exposes no infra symbols, contract negative case
reproduced. Align project-structure/runtime-flows baselines to the real
tree. Sync SDLC tracking: REQ-001~004 → Implemented, BAT-001 →
release-candidate.

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

tests/domain/slot/test_contract.py

@@ -0,0 +1,36 @@
+"""Column-contract guard for `Slot` (dcy-001 OQ-2 / REQ-003 FR-5).
+
+Asserts the `Slot` dataclass field set matches the declared `EXPECTED_SLOT_FIELDS`
+so any field add/remove fails loudly. Names/presence only — type mapping lives in
+dcy-001 부록 A / docs/data-model.md, not here.
+
+DB-side (information_schema) drift checking is out of scope for this iteration and
+is deferred to the persistence REQ (dcy-001 OQ-2).
+"""
+from __future__ import annotations
+
+import dataclasses
+
+from trex_core.domain.slot import EXPECTED_SLOT_FIELDS, Slot
+
+
+def test_slot_fields_match_expected_contract():
+    """AC-2: dataclass field set == declared contract."""
+    actual = {f.name for f in dataclasses.fields(Slot)}
+    assert actual == set(EXPECTED_SLOT_FIELDS)
+
+
+def test_contract_detects_added_field():
+    """AC-3 negative case: an extra field on a Slot-like dataclass must be caught.
+
+    Recreates the guard against a mutated copy so the test proves the assertion
+    fails when fields drift, without mutating the real Slot.
+    """
+    mutated_fields = {f.name for f in dataclasses.fields(Slot)} | {"unexpected_new_field"}
+    assert mutated_fields != set(EXPECTED_SLOT_FIELDS)
+
+
+def test_contract_detects_removed_field():
+    """AC-3 negative case: a removed field must be caught."""
+    reduced_fields = {f.name for f in dataclasses.fields(Slot)} - {"forced_close_at"}
+    assert reduced_fields != set(EXPECTED_SLOT_FIELDS)

tests/domain/slot/test_service.py

@@ -0,0 +1,375 @@
+"""SlotService unit tests — pre-allocation, transitions, atomic counter, capacity.
+
+Ported from trex-orbit (dcy-001 FR-3). Covers REQ-002 AC-1 ~ AC-6.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from datetime import date
+from uuid import uuid4
+
+import pytest
+
+from trex_core.domain.slot import (
+    SlotNotFoundError,
+    SlotService,
+    SlotState,
+    SlotStateMismatchError,
+    SlotTransitionError,
+)
+from trex_core.domain.slot.in_memory_repository import InMemorySlotRepository
+
+
+@pytest.fixture
+def trading_day():
+    return date(2026, 5, 24)
+
+
+@pytest.fixture
+def repo():
+    return InMemorySlotRepository()
+
+
+@pytest.fixture
+def service(repo):
+    return SlotService(repo)
+
+
+def _one_idle(repo, trading_day):
+    return repo.find_idle_slot(trading_day)
+
+
+# ----------------------------------------------------------------------------
+# preallocate
+# ----------------------------------------------------------------------------
+class TestPreallocate:
+    def test_creates_idle_slots(self, service, repo, trading_day):
+        inserted = service.preallocate_daily_slots(trading_day, 10)
+        assert inserted == 10
+        assert len(repo.list_slots(trading_day)) == 10
+        assert all(s.status is SlotState.IDLE for s in repo.list_slots(trading_day))
+
+    def test_idempotent_second_call_returns_zero(self, service, repo, trading_day):
+        """REQ-002 AC-4: same trading_date → 0 inserted on repeat."""
+        service.preallocate_daily_slots(trading_day, 5)
+        inserted = service.preallocate_daily_slots(trading_day, 5)
+        assert inserted == 0
+        assert len(repo.list_slots(trading_day)) == 5
+
+    def test_zero_or_negative_count_rejected(self, service, trading_day):
+        with pytest.raises(ValueError):
+            service.preallocate_daily_slots(trading_day, 0)
+        with pytest.raises(ValueError):
+            service.preallocate_daily_slots(trading_day, -1)
+
+
+# ----------------------------------------------------------------------------
+# transit_slot — happy paths
+# ----------------------------------------------------------------------------
+class TestTransitHappyPath:
+    def test_idle_to_pending_buy_records_fields(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        updated = service.transit_slot(
+            slot.slot_id,
+            SlotState.IDLE,
+            SlotState.PENDING_BUY,
+            reason="orb_breakout",
+            actor="buy_decision_thread",
+            symbol="005930",
+            qty=10,
+            allocated_capital=1_000_000,
+            strategy_id="orb_v1",
+        )
+        assert updated.status is SlotState.PENDING_BUY
+        assert updated.symbol == "005930"
+        assert updated.qty == 10
+        assert updated.strategy_id == "orb_v1"
+        # log appended
+        log = repo.transition_log_for(slot.slot_id)
+        assert len(log) == 1
+        assert log[0].from_state is SlotState.IDLE
+        assert log[0].to_state is SlotState.PENDING_BUY
+        assert log[0].reason == "orb_breakout"
+        assert log[0].actor == "buy_decision_thread"
+
+    def test_pending_buy_to_holding(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+            reason="orb_breakout", actor="buy", symbol="005930",
+        )
+        service.transit_slot(
+            slot.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING,
+            reason="filled", actor="order_exec",
+            avg_price=70_000, entry_price=70_000,
+        )
+        cur = repo.fetch_slot(slot.slot_id)
+        assert cur.status is SlotState.HOLDING
+        assert cur.avg_price == 70_000
+
+    def test_pending_buy_to_idle_rollback_preserves_symbol_until_recovery(
+        self, service, repo, trading_day,
+    ):
+        """pending_buy -> idle (rejection rollback) is allowed by state machine.
+
+        Note: this rollback does NOT bump daily_symbol_entries (only closed→idle does).
+        """
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+            reason="orb_breakout", actor="buy", symbol="005930",
+        )
+        service.transit_slot(
+            slot.slot_id, SlotState.PENDING_BUY, SlotState.IDLE,
+            reason="broker_reject:001", actor="order_exec",
+        )
+        assert repo.get_symbol_entry_count(trading_day, "005930") == 0
+
+
+# ----------------------------------------------------------------------------
+# transit_slot — closed → idle atomic counter (REQ-002 AC-3)
+# ----------------------------------------------------------------------------
+class TestClosedToIdleRecovery:
+    def test_closed_to_idle_resets_fields_and_bumps_counter(
+        self, service, repo, trading_day,
+    ):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        # full lifecycle: idle -> pending_buy -> holding -> pending_sell -> closed -> idle
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+            reason="orb_breakout", actor="buy", symbol="005930", qty=10,
+        )
+        service.transit_slot(
+            slot.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING,
+            reason="filled", actor="oe", avg_price=70_000, entry_price=70_000,
+        )
+        service.transit_slot(
+            slot.slot_id, SlotState.HOLDING, SlotState.PENDING_SELL,
+            reason="stop_loss", actor="sell",
+        )
+        service.transit_slot(
+            slot.slot_id, SlotState.PENDING_SELL, SlotState.CLOSED,
+            reason="filled", actor="oe",
+        )
+        # before recovery: count = 0
+        assert repo.get_symbol_entry_count(trading_day, "005930") == 0
+        result = service.transit_slot(
+            slot.slot_id, SlotState.CLOSED, SlotState.IDLE,
+            reason="recovery", actor="oe",
+        )
+        # fields cleared
+        assert result.status is SlotState.IDLE
+        assert result.symbol is None
+        assert result.qty is None
+        assert result.avg_price is None
+        assert result.allocated_capital is None
+        # counter incremented atomically (REQ-002 AC-3)
+        assert repo.get_symbol_entry_count(trading_day, "005930") == 1
+        # transition log retains symbol audit
+        log = repo.transition_log_for(slot.slot_id)
+        assert log[-1].from_state is SlotState.CLOSED
+        assert log[-1].to_state is SlotState.IDLE
+
+    def test_repeated_lifecycle_accumulates_entry_count(
+        self, service, repo, trading_day,
+    ):
+        """Two full lifecycles of same symbol → entry_count = 2."""
+        service.preallocate_daily_slots(trading_day, 2)
+        for _ in range(2):
+            slot = _one_idle(repo, trading_day)
+            service.transit_slot(
+                slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+                reason="r", actor="a", symbol="005930",
+            )
+            service.transit_slot(
+                slot.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING,
+                reason="r", actor="a",
+            )
+            service.transit_slot(
+                slot.slot_id, SlotState.HOLDING, SlotState.PENDING_SELL,
+                reason="r", actor="a",
+            )
+            service.transit_slot(
+                slot.slot_id, SlotState.PENDING_SELL, SlotState.CLOSED,
+                reason="r", actor="a",
+            )
+            service.transit_slot(
+                slot.slot_id, SlotState.CLOSED, SlotState.IDLE,
+                reason="r", actor="a",
+            )
+        assert service.get_today_entry_count(trading_day, "005930") == 2
+
+
+# ----------------------------------------------------------------------------
+# transit_slot — rejections
+# ----------------------------------------------------------------------------
+class TestTransitRejections:
+    def test_disallowed_transition_raises(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        with pytest.raises(SlotTransitionError):
+            service.transit_slot(
+                slot.slot_id, SlotState.IDLE, SlotState.HOLDING,
+                reason="x", actor="a",
+            )
+
+    def test_state_mismatch_raises_when_current_state_drifted(
+        self, service, repo, trading_day,
+    ):
+        """Race detection — if slot already advanced, transit_slot from old state fails."""
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+            reason="r", actor="a",
+        )
+        with pytest.raises(SlotStateMismatchError):
+            # caller still thinks status=idle but it's pending_buy
+            service.transit_slot(
+                slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+                reason="r", actor="a",
+            )
+
+    def test_unknown_slot_raises(self, service):
+        with pytest.raises(SlotNotFoundError):
+            service.transit_slot(
+                uuid4(), SlotState.IDLE, SlotState.PENDING_BUY,
+                reason="r", actor="a",
+            )
+
+
+# ----------------------------------------------------------------------------
+# operator error → idle/holding (REQ-004)
+# ----------------------------------------------------------------------------
+class TestOperatorResolve:
+    def test_error_to_idle_via_operator(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        # force into error
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.ERROR,
+            reason="reconcile_mismatch", actor="system",
+        )
+        result = service.transit_slot(
+            slot.slot_id, SlotState.ERROR, SlotState.IDLE,
+            reason="broker confirmed no position", actor="operator:alice",
+        )
+        assert result.status is SlotState.IDLE
+        log = repo.transition_log_for(slot.slot_id)
+        assert log[-1].actor == "operator:alice"
+        assert "broker confirmed" in log[-1].reason
+
+    def test_error_to_pending_buy_rejected(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.ERROR,
+            reason="r", actor="s",
+        )
+        with pytest.raises(SlotTransitionError):
+            service.transit_slot(
+                slot.slot_id, SlotState.ERROR, SlotState.PENDING_BUY,
+                reason="r", actor="operator:alice",
+            )
+
+
+# ----------------------------------------------------------------------------
+# compute_slot_capacity (REQ-002 AC-6)
+# ----------------------------------------------------------------------------
+class TestCapacity:
+    def test_all_idle(self, service, trading_day):
+        service.preallocate_daily_slots(trading_day, 10)
+        cap = service.compute_slot_capacity(trading_day, 10)
+        assert cap.idle_count == 10
+        assert cap.holding_count == 0
+        assert cap.pending_count == 0
+        assert cap.total_slots == 10
+        assert cap.scarcity_ratio == 0.0
+
+    def test_mixed_states(self, service, repo, trading_day):
+        service.preallocate_daily_slots(trading_day, 10)
+        # move 3 to pending_buy + 2 to holding
+        slots = repo.list_slots(trading_day)
+        for s in slots[:3]:
+            service.transit_slot(
+                s.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+                reason="r", actor="a",
+            )
+        for s in slots[3:5]:
+            service.transit_slot(
+                s.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+                reason="r", actor="a",
+            )
+            service.transit_slot(
+                s.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING,
+                reason="r", actor="a",
+            )
+        cap = service.compute_slot_capacity(trading_day, 10)
+        assert cap.idle_count == 5
+        assert cap.pending_count == 3
+        assert cap.holding_count == 2
+        assert cap.scarcity_ratio == pytest.approx(0.5)
+
+    def test_zero_total_rejected(self, service, trading_day):
+        with pytest.raises(ValueError):
+            service.compute_slot_capacity(trading_day, 0)
+
+
+# ----------------------------------------------------------------------------
+# advisory lock serialization (REQ-002 AC-5)
+# ----------------------------------------------------------------------------
+class TestAdvisoryLockSerialization:
+    def test_concurrent_transitions_are_serialized(self, service, repo, trading_day):
+        """Two threads competing for the same slot — one must observe state mismatch."""
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = _one_idle(repo, trading_day)
+
+        results: dict[str, Exception | None] = {}
+
+        def worker(name: str):
+            try:
+                service.transit_slot(
+                    slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+                    reason=f"r-{name}", actor=name,
+                )
+                results[name] = None
+            except Exception as exc:  # noqa: BLE001
+                results[name] = exc
+
+        t1 = threading.Thread(target=worker, args=("buy_thread",))
+        t2 = threading.Thread(target=worker, args=("sell_thread",))
+        t1.start()
+        t2.start()
+        t1.join()
+        t2.join()
+
+        # exactly one succeeded; the other observed state mismatch
+        successes = [k for k, v in results.items() if v is None]
+        failures = [k for k, v in results.items() if v is not None]
+        assert len(successes) == 1
+        assert len(failures) == 1
+        assert isinstance(failures[0] and results[failures[0]], SlotStateMismatchError)
+
+    def test_lock_hold_time_under_50ms(self, service, trading_day):
+        """REQ-002 AC-5 numeric: transition under the in-memory repo finishes < 50 ms."""
+        service.preallocate_daily_slots(trading_day, 1)
+        slot = list(service.compute_slot_capacity.__self__._repo.list_slots(trading_day))[0]  # type: ignore[attr-defined]
+        t0 = time.perf_counter()
+        service.transit_slot(
+            slot.slot_id, SlotState.IDLE, SlotState.PENDING_BUY,
+            reason="r", actor="a",
+        )
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        assert elapsed_ms < 50.0, f"transition took {elapsed_ms:.2f} ms"
+
+
+# ----------------------------------------------------------------------------
+# get_today_entry_count (REQ-001 + REQ-002 boundary)
+# ----------------------------------------------------------------------------
+def test_get_today_entry_count_for_unseen_symbol_is_zero(service, trading_day):
+    assert service.get_today_entry_count(trading_day, "999999") == 0

tests/domain/slot/test_state.py

@@ -0,0 +1,96 @@
+"""State machine unit tests — verify exactly the allowed transition families.
+
+Ported from trex-orbit (dcy-001 FR-3). Covers REQ-002 / REQ-003.
+"""
+from __future__ import annotations
+
+import pytest
+
+from trex_core.domain.slot.state import (
+    ALLOWED_TRANSITIONS,
+    SLOT_ADVISORY_LOCK_ID,
+    SlotState,
+    is_allowed_transition,
+)
+
+
+def test_slot_state_has_six_members():
+    """6 states per dcy-001 5.3.5.1."""
+    assert {s.value for s in SlotState} == {
+        "idle",
+        "pending_buy",
+        "holding",
+        "pending_sell",
+        "closed",
+        "error",
+    }
+
+
+def test_advisory_lock_id_is_stable_constant():
+    """SLOT_ADVISORY_LOCK_ID must not change between releases (REQ-002 NFR-1)."""
+    assert isinstance(SLOT_ADVISORY_LOCK_ID, int)
+    assert SLOT_ADVISORY_LOCK_ID == 0x5107_4D31
+
+
+@pytest.mark.parametrize(
+    "from_state,to_state",
+    [
+        # 1-7. dcy-001 FR-2 base transitions
+        (SlotState.IDLE, SlotState.PENDING_BUY),
+        (SlotState.PENDING_BUY, SlotState.HOLDING),
+        (SlotState.PENDING_BUY, SlotState.IDLE),
+        (SlotState.HOLDING, SlotState.PENDING_SELL),
+        (SlotState.PENDING_SELL, SlotState.CLOSED),
+        (SlotState.PENDING_SELL, SlotState.HOLDING),
+        (SlotState.CLOSED, SlotState.IDLE),
+        # 8. * -> error
+        (SlotState.IDLE, SlotState.ERROR),
+        (SlotState.PENDING_BUY, SlotState.ERROR),
+        (SlotState.HOLDING, SlotState.ERROR),
+        (SlotState.PENDING_SELL, SlotState.ERROR),
+        (SlotState.CLOSED, SlotState.ERROR),
+        # operator manual resolve (REQ-004)
+        (SlotState.ERROR, SlotState.IDLE),
+        (SlotState.ERROR, SlotState.HOLDING),
+    ],
+)
+def test_allowed_transition(from_state: SlotState, to_state: SlotState):
+    assert is_allowed_transition(from_state, to_state)
+
+
+@pytest.mark.parametrize(
+    "from_state,to_state",
+    [
+        # explicitly disallowed: skipping intermediate states
+        (SlotState.IDLE, SlotState.HOLDING),
+        (SlotState.IDLE, SlotState.PENDING_SELL),
+        (SlotState.IDLE, SlotState.CLOSED),
+        (SlotState.HOLDING, SlotState.IDLE),
+        (SlotState.HOLDING, SlotState.CLOSED),
+        (SlotState.PENDING_BUY, SlotState.CLOSED),
+        (SlotState.PENDING_BUY, SlotState.PENDING_SELL),
+        (SlotState.PENDING_SELL, SlotState.IDLE),
+        (SlotState.PENDING_SELL, SlotState.PENDING_BUY),
+        (SlotState.CLOSED, SlotState.HOLDING),
+        (SlotState.CLOSED, SlotState.PENDING_BUY),
+        (SlotState.CLOSED, SlotState.PENDING_SELL),
+        # error has restricted exits — only idle and holding allowed (REQ-004)
+        (SlotState.ERROR, SlotState.PENDING_BUY),
+        (SlotState.ERROR, SlotState.PENDING_SELL),
+        (SlotState.ERROR, SlotState.CLOSED),
+        (SlotState.ERROR, SlotState.ERROR),
+    ],
+)
+def test_disallowed_transition(from_state: SlotState, to_state: SlotState):
+    assert not is_allowed_transition(from_state, to_state)
+
+
+def test_self_loops_are_not_allowed():
+    """No state may transition to itself."""
+    for s in SlotState:
+        assert not is_allowed_transition(s, s)
+
+
+def test_allowed_transitions_set_size():
+    """7 base + 5 to-error + 2 operator-resolve = 14 transitions."""
+    assert len(ALLOWED_TRANSITIONS) == 14