# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-discovery-invariants-must-survive-a-namespace-collision-in-a-federated-package-registry.md
# Remnant Warrant:    https://corpusfetch.com/c/what-discovery-invariants-must-survive-a-namespace-collision-in-a-federated-package-registry.warrant.json
# Markdown SHA-256:   dcfd4d304e0c5917d84ef9463ac42e649dd8ea67e585b9ce7ea4fc688f73e754
# Code AST SHA-256:   1cd88904d89939e533a8b20dcdb0b3c872f56554ad87185a6724813193e24e9f
# Verified Classes:   RegistryTrust, NamespaceVerdict, PackageCandidate, NamespacePolicy, NamespaceManifest, FederatedNamespaceGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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

class RegistryTrust(Enum):
    PRIVATE_ENTERPRISE = 3
    PUBLIC_VERIFIED = 2
    PUBLIC_UNTRUSTED = 1

class NamespaceVerdict(Enum):
    VERIFIED_NAMESPACE = auto()
    TRUST_HIERARCHY_VIOLATED = auto()
    MAINTAINER_MISMATCH = auto()

@dataclass(frozen=True)
class PackageCandidate:
    registry: str
    trust_tier: RegistryTrust
    qualified_id: str
    maintainer_sig: str
    version: str

@dataclass(frozen=True)
class NamespacePolicy:
    trusted_maintainer_sigs: frozenset[str]
    min_trust_tier: RegistryTrust

@dataclass(frozen=True)
class NamespaceManifest:
    verdict: NamespaceVerdict
    selected_candidate: PackageCandidate | None
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_candidates(
        cls, candidates: tuple[PackageCandidate, ...], policy: NamespacePolicy
    ) -> NamespaceManifest:
        
        if not candidates:
            raise ValueError("No candidates provided.")

        # Gate 1: Trust tier filter
        trusted = [c for c in candidates if c.trust_tier.value >= policy.min_trust_tier.value]
        if not trusted:
            return NamespaceManifest(
                verdict=NamespaceVerdict.TRUST_HIERARCHY_VIOLATED,
                selected_candidate=None,
                directive=f"HALT: No candidates meet minimum trust tier {policy.min_trust_tier.name}.",
                manifest_digest=cls._hash("NO_TRUSTED")
            )

        # Gate 2: Maintainer verification
        verified = [c for c in trusted if c.maintainer_sig in policy.trusted_maintainer_sigs]
        if not verified:
            return NamespaceManifest(
                verdict=NamespaceVerdict.MAINTAINER_MISMATCH,
                selected_candidate=None,
                directive=f"HALT: No candidates have trusted maintainer signatures.",
                manifest_digest=cls._hash("NO_VERIFIED_MAINTAINER")
            )

        # Gate 3: Select highest trust
        selected = max(verified, key=lambda c: c.trust_tier.value)

        digest = cls._hash(json.dumps({
            "selected": selected.qualified_id,
            "registry": selected.registry,
            "trust": selected.trust_tier.name,
            "maintainer": selected.maintainer_sig,
            "version": selected.version
        }, sort_keys=True))
        
        return NamespaceManifest(
            verdict=NamespaceVerdict.VERIFIED_NAMESPACE,
            selected_candidate=selected,
            directive=f"PROCEED: Selected {selected.qualified_id} from {selected.registry} (trust: {selected.trust_tier.name}).",
            manifest_digest=digest
        )