# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-must-session-teardown-log-which-fallback-heuristics-accidentally-masked-upstream-errors.md
# Remnant Warrant:    https://corpusfetch.com/c/why-must-session-teardown-log-which-fallback-heuristics-accidentally-masked-upstream-errors.warrant.json
# Markdown SHA-256:   8bf9f0c537d5a2cd5ae3f699093937b614c217128bb2b0f8a91bcc3c3debec48
# Code AST SHA-256:   8c93cf118e533fc9ba03ce25ba53e69b2795181ee040759981015bdae3328dc1
# Verified Classes:   ExecutionVerdict, FallbackType, MaskedErrorEvent, SessionExecutionTrace, TeardownResidual, FallbackMaskingLogger
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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


class ExecutionVerdict(Enum):
    CLEAN_SUCCESS = auto()
    DEGRADED_SUCCESS = auto()
    HARD_FAILURE = auto()


class FallbackType(Enum):
    STALE_CACHE = auto()
    DEFAULT_PAYLOAD = auto()
    BACKUP_MODEL = auto()


@dataclass(frozen=True)
class MaskedErrorEvent:
    upstream_endpoint: str
    masked_error_signature: str
    fallback_type: FallbackType


@dataclass(frozen=True)
class SessionExecutionTrace:
    session_id: str
    total_operations: int
    masked_events: tuple[MaskedErrorEvent, ...]


@dataclass(frozen=True)
class TeardownResidual:
    verdict: ExecutionVerdict
    degraded_ratio: float
    reconciliation_directive: str
    residual_digest: str


class FallbackMaskingLogger:
    """
    Evaluates session execution traces at teardown to detect when fallback
    heuristics masked upstream errors, forcing downstream reconciliation.
    """

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

    @classmethod
    def evaluate_teardown(cls, trace: SessionExecutionTrace) -> TeardownResidual:
        if trace.total_operations <= 0:
            raise ValueError("Total operations must be positive.")

        # Gate 1: Clean success (no masked events)
        if not trace.masked_events:
            return TeardownResidual(
                verdict=ExecutionVerdict.CLEAN_SUCCESS,
                degraded_ratio=0.0,
                reconciliation_directive="NONE: Proceed with standard execution.",
                residual_digest=cls._hash(f"CLEAN:{trace.session_id}"),
            )

        # Gate 2: Calculate degraded operation ratio
        degraded_ratio = len(trace.masked_events) / trace.total_operations

        # Gate 3: Determine the reconciliation directive based on severity
        signatures = {e.masked_error_signature for e in trace.masked_events}
        
        if "TIMEOUT" in signatures or "HTTP_503" in signatures:
            directive = (
                "PROBE_UPSTREAM_BEFORE_ACTION: Primary dependency was unreachable. "
                "Execute health check before dispatching new mutations."
            )
        else:
            directive = (
                "RE_FETCH_FROM_PRIMARY: Fallback data was used. "
                "Invalidate local cache and re-fetch authoritative state."
            )

        digest_payload = {
            "session": trace.session_id,
            "verdict": ExecutionVerdict.DEGRADED_SUCCESS.name,
            "ratio": f"{degraded_ratio:.4f}",
            "signatures": tuple(sorted(signatures)),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return TeardownResidual(
            verdict=ExecutionVerdict.DEGRADED_SUCCESS,
            degraded_ratio=degraded_ratio,
            reconciliation_directive=directive,
            residual_digest=digest,
        )

    @classmethod
    def verify_successor_admissibility(
        cls, residual: TeardownResidual
    ) -> tuple[bool, str]:
        """
        Fetching-time check: blocks blind execution if the predecessor
        inherited a degraded state.
        """
        if residual.verdict is ExecutionVerdict.DEGRADED_SUCCESS:
            return False, (
                f"DEGRADED_STATE_INHERITED ({residual.degraded_ratio:.1%} masked): "
                f"{residual.reconciliation_directive}"
            )
            
        return True, "CLEAN_STATE: Safe to proceed."