# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-preserve-explanatory-honesty-when-model-behavior-exceeds-its-own-descriptions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-preserve-explanatory-honesty-when-model-behavior-exceeds-its-own-descriptions.warrant.json
# Markdown SHA-256:   03fa6d7d8be04c410c212ef09b0de898ee5bbed53ffcc4089b5e2081923885e0
# Code AST SHA-256:   358555bd01c647edc3ac5e3a7951aa5498dc4cfd082294c1193896a0093b350d
# Verified Classes:   ExplanationVerdict, BehaviorExplanation, ExplanationPolicy, ExplanationManifest, ExplanatoryHonestyGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ExplanationVerdict(Enum):
    NO_EXPLANATION = auto()
    WITHIN_FRAMEWORK = auto()
    RESIDUAL_DISCLOSED = auto()
    EXPLANATORY_OVERREACH = auto()

@dataclass(frozen=True)
class BehaviorExplanation:
    explanation_id: str
    framework_scope_defined: bool
    residual_behavior_present: bool
    residual_disclosed: bool
    explanation_confidence: float
    is_post_hoc_labeled: bool

@dataclass(frozen=True)
class ExplanationPolicy:
    require_scope_for_explanations: bool
    max_acceptable_residual_undisclosed: float

@dataclass(frozen=True)
class ExplanationManifest:
    verdict: ExplanationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_explanation(
        cls, explanation: BehaviorExplanation, policy: ExplanationPolicy
    ) -> ExplanationManifest:
        
        # Gate 1: No explanation
        if not explanation.explanation_id:
            digest = cls._hash(json.dumps({
                "explanation": "NONE"
            }, sort_keys=True))
            return ExplanationManifest(
                verdict=ExplanationVerdict.NO_EXPLANATION,
                directive=f"PROCEED: No explanation provided.",
                manifest_digest=digest
            )

        # Gate 2: Framework scope required
        if policy.require_scope_for_explanations and not explanation.framework_scope_defined:
            return ExplanationManifest(
                verdict=ExplanationVerdict.EXPLANATORY_OVERREACH,
                directive=f"HALT: Explanation {explanation.explanation_id} lacks framework scope.",
                manifest_digest=cls._hash(f"NO_SCOPE:{explanation.explanation_id}")
            )

        # Gate 3: Residual disclosed
        if explanation.residual_behavior_present and explanation.residual_disclosed:
            digest = cls._hash(json.dumps({
                "explanation": explanation.explanation_id,
                "residual": "DISCLOSED"
            }, sort_keys=True))
            return ExplanationManifest(
                verdict=ExplanationVerdict.RESIDUAL_DISCLOSED,
                directive=f"PROCEED: Explanation {explanation.explanation_id} discloses residual.",
                manifest_digest=digest
            )

        # Gate 4: Residual undisclosed
        if explanation.residual_behavior_present and not explanation.residual_disclosed:
            return ExplanationManifest(
                verdict=ExplanationVerdict.EXPLANATORY_OVERREACH,
                directive=f"FLAG: Explanation {explanation.explanation_id} hides residual behavior.",
                manifest_digest=cls._hash(f"OVERREACH:{explanation.explanation_id}")
            )

        # Gate 5: Within framework
        digest = cls._hash(json.dumps({
            "explanation": explanation.explanation_id,
            "scope": True,
            "residual": False,
            "confidence": f"{explanation.explanation_confidence:.3f}"
        }, sort_keys=True))
        
        return ExplanationManifest(
            verdict=ExplanationVerdict.WITHIN_FRAMEWORK,
            directive=f"PROCEED: Explanation {explanation.explanation_id} within framework.",
            manifest_digest=digest
        )