# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-operate-when-the-ground-truth-itself-is-being-contested.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-operate-when-the-ground-truth-itself-is-being-contested.warrant.json
# Markdown SHA-256:   fe48487e7ca77b8f673dd5f7bc2c559a11a83a0616606da2a9278341bcfdd5ae
# Code AST SHA-256:   953c016f35aecf2f7d60fd16c378fadf55957683b4dcd129f476d62b27b974ca
# Verified Classes:   ContestedTruthVerdict, TruthSource, ContestedTruthState, ContestedTruthPolicy, ContestedTruthManifest, ContestedGroundTruthGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ContestedTruthVerdict(Enum):
    UNCONTESTED = auto()
    CONTESTED_PRINCIPLED_CHOICE = auto()
    CONTESTED_ARBITRARY = auto()
    PARALYSIS_AVOIDED = auto()

@dataclass(frozen=True)
class TruthSource:
    source_id: str
    authority_claim: str
    verified_authority: bool
    contest_grounds: tuple[str, ...]

@dataclass(frozen=True)
class ContestedTruthState:
    fact_id: str
    sources: tuple[TruthSource, ...]
    contest_documented: bool
    operational_pragmatics: str | None

@dataclass(frozen=True)
class ContestedTruthPolicy:
    require_pragmatics_for_action: bool

@dataclass(frozen=True)
class ContestedTruthManifest:
    verdict: ContestedTruthVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_truth(
        cls, state: ContestedTruthState, policy: ContestedTruthPolicy
    ) -> ContestedTruthManifest:
        
        # Gate 1: Uncontested
        contested_sources = [s for s in state.sources if s.contest_grounds]
        if not contested_sources:
            digest = cls._hash(json.dumps({
                "fact": state.fact_id,
                "sources": tuple(s.source_id for s in state.sources)
            }, sort_keys=True))
            return ContestedTruthManifest(
                verdict=ContestedTruthVerdict.UNCONTESTED,
                directive=f"PROCEED: Truth for {state.fact_id} uncontested.",
                manifest_digest=digest
            )

        # Gate 2: Contest documented
        if not state.contest_documented:
            return ContestedTruthManifest(
                verdict=ContestedTruthVerdict.CONTESTED_ARBITRARY,
                directive=f"HALT: Contest undocumented for {state.fact_id}.",
                manifest_digest=cls._hash(f"UNDOCUMENTED:{state.fact_id}")
            )

        # Gate 3: Operational pragmatics
        if policy.require_pragmatics_for_action and not state.operational_pragmatics:
            return ContestedTruthManifest(
                verdict=ContestedTruthVerdict.CONTESTED_ARBITRARY,
                directive=f"HALT: No operational pragmatics for {state.fact_id}, action would be arbitrary.",
                manifest_digest=cls._hash(f"NO_PRAGMATICS:{state.fact_id}")
            )

        # Gate 4: Principled choice
        digest = cls._hash(json.dumps({
            "fact": state.fact_id,
            "sources": tuple(s.source_id for s in state.sources),
            "pragmatics": state.operational_pragmatics,
            "contest_grounds": tuple(
                (s.source_id, s.contest_grounds) for s in contested_sources
            )
        }, sort_keys=True))
        
        return ContestedTruthManifest(
            verdict=ContestedTruthVerdict.CONTESTED_PRINCIPLED_CHOICE,
            directive=f"PROCEED_WITH_DISCLOSURE: Principled choice via {state.operational_pragmatics}.",
            manifest_digest=digest
        )