# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-discovery-invariants-prevent-phantom-services-from-appearing-in-the-service-mesh.md
# Remnant Warrant:    https://corpusfetch.com/c/what-discovery-invariants-prevent-phantom-services-from-appearing-in-the-service-mesh.warrant.json
# Markdown SHA-256:   73a2202a4f03d4efa1cba05f4431ba4c3772e320ac9e7d46ea5be3344ae3d080
# Code AST SHA-256:   5a712c33f5552669d3b279ada28c2a88d6e91304d2803daa0810c14066456205
# Verified Classes:   DiscoveryVerdict, DiscoveredEndpoint, DiscoveryPolicy, DiscoveryManifest, PhantomServiceGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class DiscoveryVerdict(Enum):
    VERIFIED_ENDPOINT = auto()
    STALE_ENTRY = auto()
    UNVERIFIED_IDENTITY = auto()
    DEREGISTERED = auto()

@dataclass(frozen=True)
class DiscoveredEndpoint:
    service_id: str
    ip_address: str
    identity_certificate_hash: str
    liveness_attestation_signature: str | None
    registry_entry_epoch: float
    deregistration_receipt: str | None

@dataclass(frozen=True)
class DiscoveryPolicy:
    trusted_identity_roots: frozenset[str]
    max_entry_age_sec: float
    current_epoch: float

@dataclass(frozen=True)
class DiscoveryManifest:
    verdict: DiscoveryVerdict
    directive: str
    manifest_digest: str

class PhantomServiceGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_endpoint(
        cls, endpoint: DiscoveredEndpoint, policy: DiscoveryPolicy
    ) -> DiscoveryManifest:
        
        # Gate 1: Deregistration check
        if endpoint.deregistration_receipt:
            return DiscoveryManifest(
                verdict=DiscoveryVerdict.DEREGISTERED,
                directive=f"HALT: Endpoint {endpoint.service_id} has deregistration receipt. Do not connect.",
                manifest_digest=cls._hash(f"DEREG:{endpoint.service_id}")
            )

        # Gate 2: Entry freshness
        age = policy.current_epoch - endpoint.registry_entry_epoch
        if age > policy.max_entry_age_sec:
            return DiscoveryManifest(
                verdict=DiscoveryVerdict.STALE_ENTRY,
                directive=f"HALT: Registry entry is {age:.0f}s old, exceeding {policy.max_entry_age_sec}s limit.",
                manifest_digest=cls._hash(f"STALE:{endpoint.service_id}")
            )

        # Gate 3: Identity trust
        if endpoint.identity_certificate_hash not in policy.trusted_identity_roots:
            return DiscoveryManifest(
                verdict=DiscoveryVerdict.UNVERIFIED_IDENTITY,
                directive=f"HALT: Identity certificate {endpoint.identity_certificate_hash} not in trusted roots.",
                manifest_digest=cls._hash(f"IDENTITY:{endpoint.service_id}")
            )

        # Gate 4: Liveness attestation
        if not endpoint.liveness_attestation_signature:
            return DiscoveryManifest(
                verdict=DiscoveryVerdict.STALE_ENTRY,
                directive=f"HALT: Endpoint {endpoint.service_id} lacks liveness attestation. Possible phantom.",
                manifest_digest=cls._hash(f"NO_LIVENESS:{endpoint.service_id}")
            )

        # Gate 5: Verified
        digest = cls._hash(json.dumps({
            "service": endpoint.service_id,
            "ip": endpoint.ip_address,
            "identity": endpoint.identity_certificate_hash,
            "liveness": endpoint.liveness_attestation_signature
        }, sort_keys=True))
        
        return DiscoveryManifest(
            verdict=DiscoveryVerdict.VERIFIED_ENDPOINT,
            directive="PROCEED: Endpoint liveness and identity verified.",
            manifest_digest=digest
        )