# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-agents-communicate-confidence-intervals-when-their-underlying-models-have-diverged-behaviorally.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-agents-communicate-confidence-intervals-when-their-underlying-models-have-diverged-behaviorally.warrant.json
# Markdown SHA-256:   6200942896f06926a3cf8a920dda23749995b905878e50e821b2842b86cda618
# Code AST SHA-256:   c4c9ecc68c125825de90dba6b27099092a3a4438dab89e579e5a7604750af784
# Verified Classes:   ConfidenceVerdict, AgentOutput, CalibrationPolicy, ConfidenceManifest, ConfidenceCalibrationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ConfidenceVerdict(Enum):
    CALIBRATED_CONFIDENCE = auto()
    UNCALIBRATED_OUTPUT = auto()
    STALE_CALIBRATION = auto()

@dataclass(frozen=True)
class AgentOutput:
    output_hash: str
    confidence_value: float
    calibration_curve_hash: str | None
    calibration_epoch: float

@dataclass(frozen=True)
class CalibrationPolicy:
    max_calibration_age_sec: float
    min_acceptable_confidence: float
    current_epoch: float

@dataclass(frozen=True)
class ConfidenceManifest:
    verdict: ConfidenceVerdict
    effective_confidence: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_output(
        cls, output: AgentOutput, policy: CalibrationPolicy
    ) -> ConfidenceManifest:
        
        # Gate 1: Calibration presence
        if not output.calibration_curve_hash:
            return ConfidenceManifest(
                verdict=ConfidenceVerdict.UNCALIBRATED_OUTPUT,
                effective_confidence=0.0,
                directive="HALT: No calibration curve. Confidence is unverifiable.",
                manifest_digest=cls._hash(f"NO_CALIBRATION:{output.output_hash}")
            )

        # Gate 2: Calibration freshness
        age = policy.current_epoch - output.calibration_epoch
        if age > policy.max_calibration_age_sec:
            return ConfidenceManifest(
                verdict=ConfidenceVerdict.STALE_CALIBRATION,
                effective_confidence=output.confidence_value * 0.5,
                directive=f"HALT: Calibration is {age:.0f}s old. Down-weighting confidence by 50%.",
                manifest_digest=cls._hash(f"STALE:{age:.0f}")
            )

        # Gate 3: Minimum confidence threshold
        if output.confidence_value < policy.min_acceptable_confidence:
            return ConfidenceManifest(
                verdict=ConfidenceVerdict.STALE_CALIBRATION,
                effective_confidence=output.confidence_value,
                directive=f"HALT: Confidence {output.confidence_value} below acceptable minimum {policy.min_acceptable_confidence}.",
                manifest_digest=cls._hash(f"LOW_CONF:{output.confidence_value}")
            )

        # Gate 4: Calibrated
        digest = cls._hash(json.dumps({
            "output": output.output_hash,
            "confidence": str(output.confidence_value),
            "calibration": output.calibration_curve_hash
        }, sort_keys=True))
        
        return ConfidenceManifest(
            verdict=ConfidenceVerdict.CALIBRATED_CONFIDENCE,
            effective_confidence=output.confidence_value,
            directive="PROCEED: Output is calibrated and confidence is trustworthy.",
            manifest_digest=digest
        )