# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.warrant.json
# Markdown SHA-256:   cb393fe385f231f68fc3cbe3e9478d44e5548129b6a1261b4c978853fd7508d5
# Code AST SHA-256:   3cc5ad9bb1c835a78fdc494cdc5db6217f5ab50a7b5ba149f33e24325f17cba5
# Verified Classes:   StaleConclusionRefusalError, VolatilityTier, StoredConclusionRecord, StalenessDecision, IntrinsicStalenessArbiter
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import math
from dataclasses import dataclass
from enum import Enum
from typing import Final


class StaleConclusionRefusalError(RuntimeError):
    '''Raised when a stored conclusion has decayed past its intrinsic volatility bound without a fresh probe.'''
    pass


class VolatilityTier(Enum):
    MATHEMATICAL_INVARIANT = float("inf")   # Never decays by time alone
    PROTOCOL_OR_OS_SPEC = 365.0 * 86400.0   # 365 days in seconds
    EXTERNAL_API_OR_PACKAGE = 30.0 * 86400.0  # 30 days in seconds
    EPHEMERAL_RUNTIME_STATE = 900.0         # 15 minutes in seconds


@dataclass(frozen=True)
class StoredConclusionRecord:
    record_id: str
    recorded_at_epoch_sec: float
    initial_confidence: float
    tier: VolatilityTier
    recorded_env_fingerprint: str


@dataclass(frozen=True)
class StalenessDecision:
    record_id: str
    decayed_confidence: float
    is_stale: bool
    reason: str


class IntrinsicStalenessArbiter:
    '''
    Determines whether a stored conclusion has gone stale without requiring a new
    empirical observation:
    1. Applies exponential half-life decay based on the domain's VolatilityTier.
    2. Checks environmental fingerprint parity.
    3. Refuses binding when decayed confidence drops below `MIN_BINDING_CONFIDENCE`.
    '''

    MIN_BINDING_CONFIDENCE: Final[float] = 0.70

    @classmethod
    def evaluate_conclusion(
        cls,
        record: StoredConclusionRecord,
        *,
        current_epoch_sec: float,
        active_env_fingerprint: str,
    ) -> StalenessDecision:
        if current_epoch_sec < record.recorded_at_epoch_sec:
            raise StaleConclusionRefusalError("Clock skew detected: current_epoch_sec precedes recorded timestamp.")

        # Gate 3: Environmental Epoch Drift Check
        if record.recorded_env_fingerprint != active_env_fingerprint:
            return StalenessDecision(
                record_id=record.record_id,
                decayed_confidence=0.0,
                is_stale=True,
                reason="ENV_FINGERPRINT_DRIFT",
            )

        # Gate 1 & Gate 2: Volatility Half-Life Confidence Decay
        half_life = record.tier.value
        if math.isinf(half_life):
            decayed = record.initial_confidence
        else:
            elapsed = current_epoch_sec - record.recorded_at_epoch_sec
            decayed = record.initial_confidence * math.pow(0.5, elapsed / half_life)

        if decayed < cls.MIN_BINDING_CONFIDENCE:
            return StalenessDecision(
                record_id=record.record_id,
                decayed_confidence=round(decayed, 4),
                is_stale=True,
                reason=f"HALF_LIFE_EXPIRED (confidence={decayed:.3f} < {cls.MIN_BINDING_CONFIDENCE})",
            )

        return StalenessDecision(
            record_id=record.record_id,
            decayed_confidence=round(decayed, 4),
            is_stale=False,
            reason="FRESH_WITHIN_VOLATILITY_BOUND",
        )

    @classmethod
    def assert_not_stale(
        cls,
        record: StoredConclusionRecord,
        *,
        current_epoch_sec: float,
        active_env_fingerprint: str,
    ) -> StalenessDecision:
        decision = cls.evaluate_conclusion(
            record,
            current_epoch_sec=current_epoch_sec,
            active_env_fingerprint=active_env_fingerprint,
        )
        if decision.is_stale:
            raise StaleConclusionRefusalError(
                f"Refusing to bind stale conclusion '{record.record_id}': {decision.reason}. "
                "Execute a read-only verification probe before proceeding."
            )
        return decision