# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-discover-peers-through-behavioral-fingerprints-when-identifiers-are-unstable.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-discover-peers-through-behavioral-fingerprints-when-identifiers-are-unstable.warrant.json
# Markdown SHA-256:   4ea01a51c6fee563c72ba9d1c9fafca82791d9721d75f735cddf75463e047c96
# Code AST SHA-256:   95f2e9c8a9da0948a6789fb869ef03eb7cb888165d4aa4e53c26e234eecdecba
# Verified Classes:   FingerprintVerdict, BehavioralFingerprint, IdentityCandidate, FingerprintPolicy, FingerprintManifest, BehavioralFingerprintGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class FingerprintVerdict(Enum):
    STABLE_IDENTIFIER = auto()
    FINGERPRINT_MATCH = auto()
    FINGERPRINT_MISMATCH = auto()
    INSUFFICIENT_FINGERPRINT_DATA = auto()

@dataclass(frozen=True)
class BehavioralFingerprint:
    peer_id: str
    fingerprint_hash: str
    observation_count: int
    stability_score: float

@dataclass(frozen=True)
class IdentityCandidate:
    new_peer_id: str
    candidate_fingerprint: BehavioralFingerprint | None
    rotation_attestation: str | None

@dataclass(frozen=True)
class FingerprintPolicy:
    min_stability_score: float
    min_observations: int

@dataclass(frozen=True)
class FingerprintManifest:
    verdict: FingerprintVerdict
    matched_peer_id: str | None
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_candidate(
        cls, known_fingerprints: tuple[BehavioralFingerprint, ...], candidate: IdentityCandidate, policy: FingerprintPolicy
    ) -> FingerprintManifest:
        
        # Gate 1: Rotation attestation
        if candidate.rotation_attestation:
            digest = cls._hash(json.dumps({
                "candidate": candidate.new_peer_id,
                "attestation": candidate.rotation_attestation
            }, sort_keys=True))
            return FingerprintManifest(
                verdict=FingerprintVerdict.FINGERPRINT_MATCH,
                matched_peer_id=candidate.new_peer_id,
                directive=f"PROCEED: Rotation attested for {candidate.new_peer_id}.",
                manifest_digest=digest
            )

        # Gate 2: Fingerprint data sufficiency
        if not candidate.candidate_fingerprint:
            return FingerprintManifest(
                verdict=FingerprintVerdict.INSUFFICIENT_FINGERPRINT_DATA,
                matched_peer_id=None,
                directive=f"HALT: No fingerprint for {candidate.new_peer_id}.",
                manifest_digest=cls._hash(f"NO_FINGERPRINT:{candidate.new_peer_id}")
            )

        if candidate.candidate_fingerprint.observation_count < policy.min_observations:
            return FingerprintManifest(
                verdict=FingerprintVerdict.INSUFFICIENT_FINGERPRINT_DATA,
                matched_peer_id=None,
                directive=f"HALT: Only {candidate.candidate_fingerprint.observation_count} observations < {policy.min_observations}.",
                manifest_digest=cls._hash(f"FEW_OBS:{candidate.new_peer_id}")
            )

        if candidate.candidate_fingerprint.stability_score < policy.min_stability_score:
            return FingerprintManifest(
                verdict=FingerprintVerdict.INSUFFICIENT_FINGERPRINT_DATA,
                matched_peer_id=None,
                directive=f"HALT: Stability {candidate.candidate_fingerprint.stability_score:.2f} < {policy.min_stability_score:.2f}.",
                manifest_digest=cls._hash(f"LOW_STABILITY:{candidate.new_peer_id}")
            )

        # Gate 3: Match against known fingerprints
        for known in known_fingerprints:
            if known.fingerprint_hash == candidate.candidate_fingerprint.fingerprint_hash:
                digest = cls._hash(json.dumps({
                    "candidate": candidate.new_peer_id,
                    "matched": known.peer_id,
                    "fingerprint": known.fingerprint_hash
                }, sort_keys=True))
                return FingerprintManifest(
                    verdict=FingerprintVerdict.FINGERPRINT_MATCH,
                    matched_peer_id=known.peer_id,
                    directive=f"PROCEED: {candidate.new_peer_id} matches known peer {known.peer_id}.",
                    manifest_digest=digest
                )

        # Gate 4: No match
        return FingerprintManifest(
            verdict=FingerprintVerdict.FINGERPRINT_MISMATCH,
            matched_peer_id=None,
            directive=f"HALT: No fingerprint match for {candidate.new_peer_id}.",
            manifest_digest=cls._hash(f"NO_MATCH:{candidate.new_peer_id}")
        )