# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-discovery-invariants-prevent-cold-start-bias-in-federated-agent-networks.md
# Remnant Warrant:    https://corpusfetch.com/c/what-discovery-invariants-prevent-cold-start-bias-in-federated-agent-networks.warrant.json
# Markdown SHA-256:   b9226ebd562b89393d99c0881eb1905d1fbd37971bc0a75e94528ddd46dfaa33
# Code AST SHA-256:   e5e64f88a347984373748955fe7b8038e875ea63eef61fb0e17cc97269330477
# Verified Classes:   ColdStartVerdict, AgentProfile, ColdStartPolicy, ColdStartManifest, ColdStartDiscoveryGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ColdStartVerdict(Enum):
    ESTABLISHED_AGENT = auto()
    COLD_START_AGENT_EXPLORE = auto()
    COLD_START_AGENT_EXCLUDED = auto()

@dataclass(frozen=True)
class AgentProfile:
    agent_id: str
    successful_transactions: int
    stake_amount: int
    uncertainty_band: float

@dataclass(frozen=True)
class ColdStartPolicy:
    graduation_threshold: int
    min_stake_for_inclusion: int
    exploration_budget_ratio: float

@dataclass(frozen=True)
class ColdStartManifest:
    verdict: ColdStartVerdict
    exploration_weight: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_agent(
        cls, agent: AgentProfile, policy: ColdStartPolicy
    ) -> ColdStartManifest:
        
        # Gate 1: Established agent
        if agent.successful_transactions >= policy.graduation_threshold:
            digest = cls._hash(json.dumps({
                "agent": agent.agent_id,
                "transactions": str(agent.successful_transactions),
                "status": "ESTABLISHED"
            }, sort_keys=True))
            return ColdStartManifest(
                verdict=ColdStartVerdict.ESTABLISHED_AGENT,
                exploration_weight=0.0,
                directive="PROCEED: Agent is established with full reputation weighting.",
                manifest_digest=digest
            )

        # Gate 2: Insufficient stake
        if agent.stake_amount < policy.min_stake_for_inclusion:
            return ColdStartManifest(
                verdict=ColdStartVerdict.COLD_START_AGENT_EXCLUDED,
                exploration_weight=0.0,
                directive=f"HALT: Cold-start agent with insufficient stake ({agent.stake_amount} < {policy.min_stake_for_inclusion}).",
                manifest_digest=cls._hash(f"INSUFFICIENT_STAKE:{agent.agent_id}")
            )

        # Gate 3: Cold-start with exploration
        digest = cls._hash(json.dumps({
            "agent": agent.agent_id,
            "transactions": str(agent.successful_transactions),
            "stake": str(agent.stake_amount),
            "uncertainty": f"{agent.uncertainty_band:.3f}"
        }, sort_keys=True))
        
        return ColdStartManifest(
            verdict=ColdStartVerdict.COLD_START_AGENT_EXPLORE,
            exploration_weight=policy.exploration_budget_ratio,
            directive=f"PROCEED: Cold-start agent included with {policy.exploration_budget_ratio:.0%} exploration weight.",
            manifest_digest=digest
        )