"""Protocol surface for the flight_recorder component (Phase 4, FDR-01..06).

Phase 1: stub only — Phase 4 lands the in-memory + disk implementations
behind this Protocol.
"""
from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Any, Protocol, runtime_checkable


class RecorderHealth(str, Enum):
    """Health tier of the flight-data recorder (FDR-04)."""

    OK = "ok"
    DEGRADED = "degraded"  # >= 90% storage
    CRITICAL = "critical"  # storage limit reached


@dataclass(slots=True, frozen=True)
class FdrExportResult:
    """Outcome of :meth:`FlightRecorder.export`."""

    flight_id: str
    segment_count: int
    total_bytes: int
    path: str | None = None  # set for DiskFlightRecorder, None for in-memory


@runtime_checkable
class FlightRecorder(Protocol):
    """Append-only flight-data recorder per FDR-01. Filled in Phase 4."""

    def append_event(self, event: dict[str, Any]) -> None: ...

    def export(self) -> FdrExportResult: ...

    @property
    def health(self) -> RecorderHealth: ...
