"""Command and result protocol types for the simulation backend.

Frozen dataclasses for commands sent to and results received from the
SimulationBackend, supporting queue-based communication across thread boundaries.
"""

from __future__ import annotations

from dataclasses import dataclass, field

from asm.ir import IRGraph
from emu.events import SimEvent
from monitor.snapshot import StateSnapshot
from tokens import Token


@dataclass(frozen=True)
class LoadCmd:
    """Load a dfasm program into a fresh simulation environment.

    Attributes:
        source: dfasm source code as a string
    """

    source: str


@dataclass(frozen=True)
class StepTickCmd:
    """Step the simulation by one tick (all events at current simulation time).

    Empty dataclass; no parameters needed.
    """

    pass


@dataclass(frozen=True)
class StepEventCmd:
    """Step the simulation by exactly one event.

    Empty dataclass; no parameters needed.
    """

    pass


@dataclass(frozen=True)
class RunUntilCmd:
    """Run the simulation continuously until reaching a target simulation time.

    Attributes:
        until: Target simulation time (float); events are batched per tick
    """

    until: float


@dataclass(frozen=True)
class InjectCmd:
    """Inject a token into the simulation without respecting FIFO backpressure.

    Attributes:
        token: Token to inject into the appropriate element's input store
    """

    token: Token


@dataclass(frozen=True)
class SendCmd:
    """Send a token into the simulation via SimPy store.put() (respects backpressure).

    Attributes:
        token: Token to send to the appropriate element's input store
    """

    token: Token


@dataclass(frozen=True)
class ResetCmd:
    """Reset the simulation (tear down current topology).

    Attributes:
        reload: If True, reload the last program after reset; otherwise leave backend ready for new LoadCmd
    """

    reload: bool = False


@dataclass(frozen=True)
class StopCmd:
    """Stop the backend thread gracefully.

    Empty dataclass; no parameters needed.
    """

    pass


# Union type for all command types
SimCommand = LoadCmd | StepTickCmd | StepEventCmd | RunUntilCmd | InjectCmd | SendCmd | ResetCmd | StopCmd


@dataclass(frozen=True)
class StepResult:
    """Result of a step or run command.

    Attributes:
        events: Tuple of SimEvent objects that occurred during the step
        snapshot: StateSnapshot of the system after the step (None if not available)
        sim_time: Current simulation time
        finished: True if simulation has reached terminal state (env.peek() == inf)
    """

    events: tuple[SimEvent, ...] = ()
    snapshot: StateSnapshot | None = None
    sim_time: float = 0.0
    finished: bool = False


@dataclass(frozen=True)
class GraphLoaded:
    """Result of successfully loading a dfasm program.

    Attributes:
        ir_graph: The loaded and processed IRGraph (for graph rendering, etc.)
        snapshot: Initial StateSnapshot after seed token injection
    """

    ir_graph: IRGraph
    snapshot: StateSnapshot


@dataclass(frozen=True)
class ErrorResult:
    """Result indicating an error during command processing.

    Attributes:
        message: Human-readable error message
        errors: Optional list of structured error messages from assembly
    """

    message: str
    errors: list[str] = field(default_factory=list)