# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-detect-peer-collusion-masquerading-as-independent-verification.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-detect-peer-collusion-masquerading-as-independent-verification.warrant.json
# Markdown SHA-256:   828dea219c27a3d59db1c6d297fa60cd079023ac93cc0ff098ace63112571a95
# Code AST SHA-256:   71ede9f4d38db1c1824a25874b80330f03572b44acdfc559fde0a34bd53b46fd
# Verified Classes:   CollusionVerdict, PeerSignal, VerificationSet, CollusionPolicy, CollusionManifest, PeerCollusionGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CollusionVerdict(Enum):
    SINGLE_PEER = auto()
    INDEPENDENT_VERIFICATION = auto()
    UPSTREAM_CONCENTRATION = auto()
    COORDINATION_SUSPECTED = auto()

@dataclass(frozen=True)
class PeerSignal:
    peer_id: str
    claim_hash: str
    upstream_sources: frozenset[str]
    timing_correlation: float
    reciprocity_with_peers: frozenset[str]

@dataclass(frozen=True)
class VerificationSet:
    verification_id: str
    signals: tuple[PeerSignal, ...]

@dataclass(frozen=True)
class CollusionPolicy:
    min_independent_sources: int
    max_acceptable_reciprocity: int

@dataclass(frozen=True)
class CollusionManifest:
    verdict: CollusionVerdict
    effective_independence: int
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_verification(
        cls, vset: VerificationSet, policy: CollusionPolicy
    ) -> CollusionManifest:
        
        # Gate 1: Single peer
        if len(vset.signals) <= 1:
            digest = cls._hash(json.dumps({
                "verification": vset.verification_id,
                "peers": str(len(vset.signals))
            }, sort_keys=True))
            return CollusionManifest(
                verdict=CollusionVerdict.SINGLE_PEER,
                effective_independence=len(vset.signals),
                directive=f"PROCEED: Single peer for {vset.verification_id}.",
                manifest_digest=digest
            )

        # Gate 2: Reciprocity
        for signal in vset.signals:
            if len(signal.reciprocity_with_peers) > policy.max_acceptable_reciprocity:
                return CollusionManifest(
                    verdict=CollusionVerdict.COORDINATION_SUSPECTED,
                    effective_independence=0,
                    directive=f"HALT: Peer {signal.peer_id} reciprocal with {len(signal.reciprocity_with_peers)} peers.",
                    manifest_digest=cls._hash(f"RECIPROCITY:{signal.peer_id}")
                )

        # Gate 3: Timing correlation
        max_correlation = max((s.timing_correlation for s in vset.signals), default=0.0)
        if max_correlation > 0.8:
            return CollusionManifest(
                verdict=CollusionVerdict.COORDINATION_SUSPECTED,
                effective_independence=0,
                directive=f"FLAG: Timing correlation {max_correlation:.2f} suggests choreography.",
                manifest_digest=cls._hash(f"TIMING:{vset.verification_id}")
            )

        # Gate 4: Upstream concentration
        all_sources: set[str] = set()
        for signal in vset.signals:
            all_sources.update(signal.upstream_sources)

        if len(all_sources) < policy.min_independent_sources:
            return CollusionManifest(
                verdict=CollusionVerdict.UPSTREAM_CONCENTRATION,
                effective_independence=len(all_sources),
                directive=f"FLAG: {len(vset.signals)} peers but only {len(all_sources)} upstream sources.",
                manifest_digest=cls._hash(f"CONCENTRATED:{vset.verification_id}")
            )

        # Gate 5: Independent
        digest = cls._hash(json.dumps({
            "verification": vset.verification_id,
            "peers": tuple(s.peer_id for s in vset.signals),
            "sources": tuple(sorted(all_sources))
        }, sort_keys=True))
        
        return CollusionManifest(
            verdict=CollusionVerdict.INDEPENDENT_VERIFICATION,
            effective_independence=len(all_sources),
            directive=f"PROCEED: {len(all_sources)} independent sources behind {len(vset.signals)} peers.",
            manifest_digest=digest
        )