"""Slot state machine (REQ-001, REQ-002; dcy-020/REQ-057 asset-centric).

The asset-centric permanent slot has five states. `inactive` means "no open
position" — it replaced the pool-model `idle` (never-bought) and `closed`
(sold, now flat) states, whose aliases were removed at the cutover (BAT-030);
migration 010 rewrites any remaining `idle`/`closed` rows to `inactive` and
swaps the status CHECK constraint accordingly.
"""
from __future__ import annotations

import zlib
from enum import Enum


# Shared PostgreSQL advisory lock base id. dcy-020/REQ-057 (NFR-1): in a shared
# DB the lock is scoped per instance via `slot_advisory_lock_id(instance_key)` so
# one instance's transitions never serialize against another's.
SLOT_ADVISORY_LOCK_ID: int = 0x5107_4D31  # arbitrary mnemonic constant


def slot_advisory_lock_id(instance_key: str) -> int:
    """Per-instance advisory lock id (dcy-020/REQ-057). Combines the base id with
    a stable hash of instance_key so distinct instances take distinct locks while
    the same instance always takes the same lock. Result stays in signed-32 range
    (pg advisory lock accepts bigint; this keeps it deterministic and small)."""
    h = zlib.crc32((instance_key or "default").encode("utf-8")) & 0x7FFF_FFFF
    return SLOT_ADVISORY_LOCK_ID ^ h


class SlotState(str, Enum):
    """Slot lifecycle states (dcy-020/REQ-057 asset-centric, 5 states)."""

    INACTIVE = "inactive"      # no open position (permanent slot at rest)
    PENDING_BUY = "pending_buy"
    HOLDING = "holding"
    PENDING_SELL = "pending_sell"
    ERROR = "error"


# Canonical transitions (dcy-020/REQ-057; dcy-021/REQ-057 CHG-03). There is no
# inactive self-loop and no closed->idle recovery family — a permanent slot
# simply returns to `inactive` and may activate again via inactive->pending_buy.
# dcy-021 adds holding->pending_buy for position-sizing increase (the slot stays
# a held position; the buy adds to it, returning to holding on fill).
_BASE_TRANSITIONS: frozenset[tuple[SlotState, SlotState]] = frozenset(
    {
        (SlotState.INACTIVE, SlotState.PENDING_BUY),   # 1. buy decision (activate)
        (SlotState.PENDING_BUY, SlotState.HOLDING),    # 2. buy filled
        (SlotState.PENDING_BUY, SlotState.INACTIVE),   # 3. buy rejected/rollback
        (SlotState.HOLDING, SlotState.PENDING_BUY),    # 7. position-sizing increase (dcy-021)
        (SlotState.HOLDING, SlotState.PENDING_SELL),   # 4. sell decision
        (SlotState.PENDING_SELL, SlotState.INACTIVE),  # 5. sell filled (deactivate)
        (SlotState.PENDING_SELL, SlotState.HOLDING),   # 6. sell rejected/rollback (or partial-sell remainder)
    }
)

# Any non-error state may move to error.
_TO_ERROR_TRANSITIONS: frozenset[tuple[SlotState, SlotState]] = frozenset(
    (s, SlotState.ERROR)
    for s in (SlotState.INACTIVE, SlotState.PENDING_BUY, SlotState.HOLDING,
              SlotState.PENDING_SELL)
)

# Operator manual resolve out of error (REQ-004).
_FROM_ERROR_TRANSITIONS: frozenset[tuple[SlotState, SlotState]] = frozenset(
    {
        (SlotState.ERROR, SlotState.INACTIVE),
        (SlotState.ERROR, SlotState.HOLDING),
    }
)

# dcy-034 / REQ-105 OQ-A: cold-start onboarding transition (actor=sync/reconcile only).
# A permanent slot that already has a position in the broker at daemon cold-start can
# transition INACTIVE→HOLDING so the sync command can onboard it without going through
# the normal INACTIVE→PENDING_BUY buy-flow. Wire-contract unchanged: SlotState enum
# values remain 5 (inactive/pending_buy/holding/pending_sell/error). Only the transition
# table expands. Callers MUST supply actor="sync" and reason="onboarding" (or
# "reconcile_sync") so the transition_log is auditable and distinct from the normal
# strategy entry path (INACTIVE→PENDING_BUY→HOLDING).
_SYNC_TRANSITIONS: frozenset[tuple[SlotState, SlotState]] = frozenset(
    {
        (SlotState.INACTIVE, SlotState.HOLDING),  # REQ-105 OQ-A: cold-start onboarding
    }
)


ALLOWED_TRANSITIONS: frozenset[tuple[SlotState, SlotState]] = (
    _BASE_TRANSITIONS | _TO_ERROR_TRANSITIONS | _FROM_ERROR_TRANSITIONS | _SYNC_TRANSITIONS
)


def is_allowed_transition(from_state: SlotState, to_state: SlotState) -> bool:
    """Return True iff (from_state, to_state) is an allowed transition."""
    return (from_state, to_state) in ALLOWED_TRANSITIONS