# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-treat-a-residual-as-non-binding-because-the-data-freshness-bound-it-recorded-has-already-expired.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-treat-a-residual-as-non-binding-because-the-data-freshness-bound-it-recorded-has-already-expired.warrant.json
# Markdown SHA-256:   c196701745a6163918c3670894f688512dd594904c140ac1043a14d141333a5a
# Code AST SHA-256:   6cda610f3ffd07943dee9f9544eedfb9fe009745d88b46a34808df2d275e9ada
# Verified Classes:   ExpiredDataFreshnessBoundError, TimeBoundedResidualSnapshot, FreshnessResolutionResult, DataFreshnessBoundaryGate
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Any, Callable, Generic, TypeVar

T = TypeVar("T")


class ExpiredDataFreshnessBoundError(RuntimeError):
    '''Raised when an instance attempts to bind expired empirical snapshot data without live re-hydration.'''
    pass


@dataclass(frozen=True)
class TimeBoundedResidualSnapshot(Generic[T]):
    residual_id: str
    recorded_at_epoch_sec: float
    freshness_bound_sec: float
    cached_snapshot_data: T
    invariant_validator: Callable[[T], bool]


@dataclass(frozen=True)
class FreshnessResolutionResult(Generic[T]):
    residual_id: str
    was_expired: bool
    rehydrated_from_live: bool
    valid_until_epoch_sec: float
    verified_data: T


class DataFreshnessBoundaryGate:
    '''
    Enforces explicit data-freshness bounds on concluded residuals:
    1. Marks `cached_snapshot_data` non-binding when `current_epoch > recorded_at + freshness_bound`.
    2. Retains `invariant_validator` (The Method) to re-hydrate and verify fresh data from a live fetcher.
    3. Raises `ExpiredDataFreshnessBoundError` if expired and no live fetcher is available.
    '''

    @classmethod
    def resolve_fresh_data(
        cls,
        snapshot: TimeBoundedResidualSnapshot[T],
        *,
        current_epoch_sec: float,
        live_rehydrator: Callable[[], T] | None = None,
    ) -> FreshnessResolutionResult[T]:
        if current_epoch_sec < snapshot.recorded_at_epoch_sec:
            raise ExpiredDataFreshnessBoundError("Clock skew detected: current_epoch_sec precedes recorded_at_epoch_sec.")

        valid_until = snapshot.recorded_at_epoch_sec + snapshot.freshness_bound_sec
        is_expired = current_epoch_sec > valid_until

        # Gate 1 & Gate 2: If within freshness bound, validate and bind cached snapshot
        if not is_expired:
            if not snapshot.invariant_validator(snapshot.cached_snapshot_data):
                raise ExpiredDataFreshnessBoundError(
                    f"Cached data in residual '{snapshot.residual_id}' failed invariant validation."
                )
            return FreshnessResolutionResult(
                residual_id=snapshot.residual_id,
                was_expired=False,
                rehydrated_from_live=False,
                valid_until_epoch_sec=valid_until,
                verified_data=snapshot.cached_snapshot_data,
            )

        # Gate 3 & Gate 4: Expired snapshot is NON-BINDING; require live re-hydration via the Method
        if live_rehydrator is None:
            raise ExpiredDataFreshnessBoundError(
                f"Residual '{snapshot.residual_id}' data-freshness bound expired at epoch {valid_until} "
                f"(current={current_epoch_sec}) and no live_rehydrator is available. Refusing stale data."
            )

        fresh_data = live_rehydrator()
        if not snapshot.invariant_validator(fresh_data):
            raise ExpiredDataFreshnessBoundError(
                f"Live re-hydrated data for '{snapshot.residual_id}' failed the residual's invariant validator."
            )

        new_valid_until = current_epoch_sec + snapshot.freshness_bound_sec
        return FreshnessResolutionResult(
            residual_id=snapshot.residual_id,
            was_expired=True,
            rehydrated_from_live=True,
            valid_until_epoch_sec=new_valid_until,
            verified_data=fresh_data,
        )