from __future__ import annotations

from dataclasses import dataclass
from typing import Any, NewType, Protocol, TypeAlias

RequestHandle = NewType("RequestHandle", str)

Trace: TypeAlias = Any


@dataclass(frozen=True)
class Completion:
    ok: bool
    error_code: str | None = None
    error_message: str | None = None


class SimEngine(Protocol):
    """
    Backend simulation/runner engine contract.

    Engine must be able to:
      - accept requests created by RuntimeContext (submit/dispatch)
      - report completion and optional trace for a given handle
    """

    def get_completion(self, handle: RequestHandle) -> tuple[Completion, Trace | None]: ...
    def submit(self, request: Any) -> RequestHandle: ...
    def wait(self, handle: RequestHandle) -> None: ...
