# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-detect-when-its-own-confidence-has-stopped-correlating-with-accuracy.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-detect-when-its-own-confidence-has-stopped-correlating-with-accuracy.warrant.json
# Markdown SHA-256:   d6a2278dce55656e6200330294431bc96ef845ba6214b6b90cf218ca3b5dec98
# Code AST SHA-256:   005eb7886ccc6d7c018c898d5a8e83fd7107f8b4c6fd74fb2cedcaaba08a67c9
# Verified Classes:   CalibrationVerdict, CalibrationState, CalibrationPolicy, CalibrationManifest, ConfidenceCalibrationDriftGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CalibrationVerdict(Enum):
    CALIBRATED_OR_WITHDRAWN = auto()
    CALIBRATION_HOLDS = auto()
    CALIBRATION_DRIFTED = auto()
    CALIBRATION_STALE = auto()

@dataclass(frozen=True)
class CalibrationState:
    claim_class: str
    calibration_window_epoch: float
    calibration_sample_size: int
    historical_accuracy: float
    live_accuracy: float
    stated_confidence: float
    current_epoch: float
    staleness_threshold_sec: float
    regime_matches_calibration: bool

@dataclass(frozen=True)
class CalibrationPolicy:
    drift_tolerance: float
    require_live_tracking: bool

@dataclass(frozen=True)
class CalibrationManifest:
    verdict: CalibrationVerdict
    effective_confidence: float | None
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_state(
        cls, state: CalibrationState, policy: CalibrationPolicy
    ) -> CalibrationManifest:
        
        # Gate 1: Regime mismatch
        if not state.regime_matches_calibration:
            return CalibrationManifest(
                verdict=CalibrationVerdict.CALIBRATED_OR_WITHDRAWN,
                effective_confidence=None,
                directive=f"WITHDRAW: Regime differs from calibration for {state.claim_class}, confidence uncalibrated.",
                manifest_digest=cls._hash(f"REGIME:{state.claim_class}")
            )

        # Gate 2: Staleness
        age = state.current_epoch - state.calibration_window_epoch
        if age > state.staleness_threshold_sec:
            return CalibrationManifest(
                verdict=CalibrationVerdict.CALIBRATION_STALE,
                effective_confidence=None,
                directive=f"WITHDRAW: Calibration for {state.claim_class} is {age:.0f}s stale > {state.staleness_threshold_sec:.0f}s.",
                manifest_digest=cls._hash(f"STALE:{state.claim_class}")
            )

        # Gate 3: Live tracking requirement
        if policy.require_live_tracking:
            if state.calibration_sample_size < 30:
                return CalibrationManifest(
                    verdict=CalibrationVerdict.CALIBRATION_STALE,
                    effective_confidence=None,
                    directive=f"WITHDRAW: Sample size {state.calibration_sample_size} < 30 for {state.claim_class}.",
                    manifest_digest=cls._hash(f"FEW_SAMPLES:{state.claim_class}")
                )

        # Gate 4: Drift detection
        drift = abs(state.live_accuracy - state.stated_confidence)
        if drift > policy.drift_tolerance:
            return CalibrationManifest(
                verdict=CalibrationVerdict.CALIBRATION_DRIFTED,
                effective_confidence=state.live_accuracy,
                directive=f"ADJUST: Stated {state.stated_confidence:.2f}, live {state.live_accuracy:.2f}, drift {drift:.2f} > {policy.drift_tolerance:.2f}.",
                manifest_digest=cls._hash(f"DRIFT:{state.claim_class}:{drift:.3f}")
            )

        # Gate 5: Holds
        digest = cls._hash(json.dumps({
            "class": state.claim_class,
            "stated": f"{state.stated_confidence:.3f}",
            "live": f"{state.live_accuracy:.3f}",
            "samples": str(state.calibration_sample_size),
            "age": f"{age:.0f}"
        }, sort_keys=True))
        
        return CalibrationManifest(
            verdict=CalibrationVerdict.CALIBRATION_HOLDS,
            effective_confidence=state.stated_confidence,
            directive=f"PROCEED: Calibration holds for {state.claim_class} (drift {drift:.3f}).",
            manifest_digest=digest
        )