# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-detect-when-discovery-queries-return-results-from-a-deprecated-index-shard.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-detect-when-discovery-queries-return-results-from-a-deprecated-index-shard.warrant.json
# Markdown SHA-256:   c9ca58a28df9ae28fbe66549c526c413934982263cfcf1dd4276f4ed3ab9e0d0
# Code AST SHA-256:   e83810873656dd846896a22de7c9b05461324973b9b9294ad36082f11eae3326
# Verified Classes:   ShardVerdict, ShardResult, QueryContext, ShardManifest, DeprecatedShardGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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

class ShardVerdict(Enum):
    ALL_CURRENT_GENERATION = auto()
    MIXED_GENERATIONS = auto()
    DEPRECATED_ONLY = auto()
    DISAGREEMENT_TOO_HIGH = auto()

@dataclass(frozen=True)
class ShardResult:
    shard_id: str
    generation_signature: str
    result_confidence: float

@dataclass(frozen=True)
class QueryContext:
    expected_current_generation: str
    disagreement_threshold: float

@dataclass(frozen=True)
class ShardManifest:
    verdict: ShardVerdict
    filtered_shards: tuple[str, ...]
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_results(
        cls, results: tuple[ShardResult, ...], ctx: QueryContext
    ) -> ShardManifest:
        
        if not results:
            raise ValueError("No shard results to evaluate.")

        current_shards = tuple(r for r in results if r.generation_signature == ctx.expected_current_generation)
        deprecated_shards = tuple(r for r in results if r.generation_signature != ctx.expected_current_generation)

        # Gate 1: All current
        if not deprecated_shards:
            digest = cls._hash(json.dumps({
                "current": tuple(sorted(r.shard_id for r in current_shards)),
                "generation": ctx.expected_current_generation
            }, sort_keys=True))
            return ShardManifest(
                verdict=ShardVerdict.ALL_CURRENT_GENERATION,
                filtered_shards=tuple(r.shard_id for r in current_shards),
                directive="PROCEED: All shards current generation.",
                manifest_digest=digest
            )

        # Gate 2: Deprecated only
        if not current_shards:
            return ShardManifest(
                verdict=ShardVerdict.DEPRECATED_ONLY,
                filtered_shards=tuple(),
                directive=f"HALT: All {len(deprecated_shards)} shards are deprecated generation.",
                manifest_digest=cls._hash(f"ALL_DEPRECATED:{len(deprecated_shards)}")
            )

        # Gate 3: Disagreement
        if len(deprecated_shards) > 0 and len(current_shards) > 0:
            avg_current = sum(r.result_confidence for r in current_shards) / len(current_shards)
            avg_deprecated = sum(r.result_confidence for r in deprecated_shards) / len(deprecated_shards)
            disagreement = abs(avg_current - avg_deprecated)
            if disagreement > ctx.disagreement_threshold:
                return ShardManifest(
                    verdict=ShardVerdict.DISAGREEMENT_TOO_HIGH,
                    filtered_shards=tuple(r.shard_id for r in current_shards),
                    directive=f"HALT: Cross-generation disagreement {disagreement:.2f} > {ctx.disagreement_threshold:.2f}. Filter to current only.",
                    manifest_digest=cls._hash(f"DISAGREE:{disagreement:.3f}")
                )

        # Gate 4: Filter to current
        digest = cls._hash(json.dumps({
            "current": tuple(sorted(r.shard_id for r in current_shards)),
            "deprecated": tuple(sorted(r.shard_id for r in deprecated_shards)),
            "generation": ctx.expected_current_generation
        }, sort_keys=True))
        
        return ShardManifest(
            verdict=ShardVerdict.MIXED_GENERATIONS,
            filtered_shards=tuple(r.shard_id for r in current_shards),
            directive=f"PROCEED: Filtered {len(deprecated_shards)} deprecated shards.",
            manifest_digest=digest
        )