"""Protocol surface for the anchor_verifier component (Phase 3, VERIFY-01..05).

Phase 1: stub only — semantics filled in Phase 3. The Protocol must
exist now so the ARCH-01 directory inventory is complete at end of
Phase 1.
"""
from __future__ import annotations

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

from gps_denied.hot_types.alignment_result import AlignmentResult
from gps_denied.hot_types.satellite_anchor import SatelliteAnchor


@dataclass(slots=True, frozen=True)
class VerifierDecision:
    """Result of an :meth:`AnchorVerifier.verify` call.

    Phase 3 will refine the rejection-reason taxonomy (currently free-text:
    ``too_few_inliers`` / ``mre_above_threshold`` / ``degenerate_homography``
    / ``freshness_expired``).
    """

    accepted: bool
    anchor: SatelliteAnchor | None = None
    rejection_reason: str | None = None
    inlier_count: int = 0
    mean_reprojection_error_px: float = 0.0
    homography_condition_number: float = 0.0


@runtime_checkable
class AnchorVerifier(Protocol):
    """Geometry-gated anchor verifier. Filled in Phase 3."""

    def verify(self, candidate: AlignmentResult) -> VerifierDecision: ...
