"""Protocol surface for the safety_state component (Phase 3, SAFE-01..06).

Phase 1: stub only — the SafetyAnchorStateMachine becomes the
authoritative source_label owner per SAFE-01 in Phase 3.
"""
from __future__ import annotations

from enum import Enum
from typing import Protocol, runtime_checkable

from gps_denied.hot_types.position_estimate import PositionEstimate
from gps_denied.hot_types.satellite_anchor import SatelliteAnchor


class SourceLabel(str, Enum):
    """Authoritative label for the provenance of a PositionEstimate (SAFE-01)."""

    SATELLITE_ANCHORED = "satellite_anchored"
    VO_EXTRAPOLATED = "vo_extrapolated"
    DEAD_RECKONED = "dead_reckoned"


@runtime_checkable
class SafetyAnchorStateMachine(Protocol):
    """Authoritative source_label owner per SAFE-01. Filled in Phase 3."""

    @property
    def source_label(self) -> SourceLabel: ...

    @property
    def anchor_age_ms(self) -> float: ...

    @property
    def can_persist_tile(self) -> bool: ...

    def on_anchor_accepted(self, anchor: SatelliteAnchor) -> None: ...

    def on_anchor_rejected(self, reason: str) -> None: ...

    def on_vo_update(self, timestamp: float) -> None: ...

    def on_visual_blackout(self) -> None: ...

    def annotate(self, estimate: PositionEstimate) -> PositionEstimate: ...
