# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-bidding-invariants-prevent-multi-agent-auction-price-collapse.md
# Remnant Warrant:    https://corpusfetch.com/c/what-bidding-invariants-prevent-multi-agent-auction-price-collapse.warrant.json
# Markdown SHA-256:   d34327088b2f4431b6dfb343eb39d3af5616ec048a891cf7e5f62a62d41cce7c
# Code AST SHA-256:   3ec5fa4625953080bb551e4bde91ac8d9b60d030b26b46b8892710259978b46a
# Verified Classes:   AuctionVerdict, Bid, AuctionState, AuctionPolicy, AuctionManifest, AuctionViabilityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class AuctionVerdict(Enum):
    VIABLE_CLEARING = auto()
    AUCTION_COLLAPSE_RISK = auto()
    COLLUSION_SUSPECTED = auto()
    NO_SALE_REQUIRED = auto()

@dataclass(frozen=True)
class Bid:
    bidder_id: str
    bid_amount: float

@dataclass(frozen=True)
class AuctionState:
    bids: tuple[Bid, ...]
    seller_willingness: float
    reserve_price: float
    min_distinct_bidders: int
    min_viable_bid_ratio: float

@dataclass(frozen=True)
class AuctionPolicy:
    collusion_variance_threshold: float

@dataclass(frozen=True)
class AuctionManifest:
    verdict: AuctionVerdict
    clearing_price: float | None
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_auction(
        cls, state: AuctionState, policy: AuctionPolicy
    ) -> AuctionManifest:
        
        # Gate 1: No bids
        if not state.bids:
            return AuctionManifest(
                verdict=AuctionVerdict.NO_SALE_REQUIRED,
                clearing_price=None,
                directive="HALT: No bids. Auction failed.",
                manifest_digest=cls._hash("NO_BIDS")
            )

        # Gate 2: Bidder count
        distinct_bidders = len({b.bidder_id for b in state.bids})
        if distinct_bidders < state.min_distinct_bidders:
            return AuctionManifest(
                verdict=AuctionVerdict.AUCTION_COLLAPSE_RISK,
                clearing_price=None,
                directive=f"HALT: Only {distinct_bidders} bidders < {state.min_distinct_bidders}. Requeue.",
                manifest_digest=cls._hash(f"FEW_BIDDERS:{distinct_bidders}")
            )

        # Gate 3: Viability threshold
        sorted_bids = sorted((b.bid_amount for b in state.bids), reverse=True)
        top_bid = sorted_bids[0]
        viable_threshold = state.seller_willingness * state.min_viable_bid_ratio

        if top_bid < viable_threshold:
            return AuctionManifest(
                verdict=AuctionVerdict.AUCTION_COLLAPSE_RISK,
                clearing_price=None,
                directive=f"HALT: Top bid {top_bid:.2f} < viable {viable_threshold:.2f}. Requeue with different parameters.",
                manifest_digest=cls._hash(f"BELOW_VIABLE:{top_bid:.2f}")
            )

        # Gate 4: Collusion detection
        if len(sorted_bids) > 2:
            variance = statistics.variance(sorted_bids)
            if variance < policy.collusion_variance_threshold:
                return AuctionManifest(
                    verdict=AuctionVerdict.COLLUSION_SUSPECTED,
                    clearing_price=None,
                    directive=f"HALT: Bid variance {variance:.4f} < {policy.collusion_variance_threshold:.4f}. Possible collusion.",
                    manifest_digest=cls._hash(f"COLLUSION:{variance:.4f}")
                )

        # Gate 5: Viable clearing
        clearing = top_bid
        digest = cls._hash(json.dumps({
            "bidders": str(distinct_bidders),
            "top_bid": f"{top_bid:.2f}",
            "viable_threshold": f"{viable_threshold:.2f}",
            "reserve": f"{state.reserve_price:.2f}"
        }, sort_keys=True))
        
        return AuctionManifest(
            verdict=AuctionVerdict.VIABLE_CLEARING,
            clearing_price=clearing,
            directive=f"PROCEED: Clearing at {clearing:.2f} with {distinct_bidders} bidders.",
            manifest_digest=digest
        )