# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-fallback-triggers-must-be-logged-after-an-upstream-service-degrades-gracefully.md
# Remnant Warrant:    https://corpusfetch.com/c/what-fallback-triggers-must-be-logged-after-an-upstream-service-degrades-gracefully.warrant.json
# Markdown SHA-256:   94ffaf7318a054539cfedbb8b9f51d497d7e088477047ccff5d7b9c1e70eab4d
# Code AST SHA-256:   262d926c9be60aafc1135b53d504b65b3286609d54308db19b79405d56e33eb4
# Verified Classes:   FallbackTrigger, DegradedState, DegradationEvent, DegradationManifest, CurrentTimeContext, GracefulDegradationLogger
# Defensive Guards:   3 fail-closed invariants (zero external deps)

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


class FallbackTrigger(Enum):
    LATENCY_THRESHOLD = auto()
    ERROR_RATE_THRESHOLD = auto()
    CIRCUIT_BREAKER_TRIPPED = auto()


class DegradedState(Enum):
    STALE_CACHE = auto()
    PARTIAL_PAYLOAD = auto()
    DEFAULT_VALUE_INJECTED = auto()


@dataclass(frozen=True)
class DegradationEvent:
    upstream_service_id: str
    trigger: FallbackTrigger
    degraded_state: DegradedState
    circuit_breaker_cooldown_epoch: float
    primary_path_health_predicate: str


@dataclass(frozen=True)
class DegradationManifest:
    event: DegradationEvent
    manifest_digest: str


@dataclass(frozen=True)
class CurrentTimeContext:
    current_epoch: float


class GracefulDegradationLogger:
    """
    Evaluates and seals fallback triggers after upstream degradation, ensuring
    successors do not mistake degraded state for primary health.
    """

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

    @classmethod
    def seal_manifest(cls, event: DegradationEvent) -> DegradationManifest:
        if not event.upstream_service_id.strip():
            raise ValueError("Upstream service ID is required to log a fallback trigger.")
            
        if not event.primary_path_health_predicate.strip():
            raise ValueError(
                "A health predicate is mandatory; successors must be able to "
                "confirm primary-path recovery."
            )
            
        if event.circuit_breaker_cooldown_epoch <= 0:
            raise ValueError("Circuit breaker cooldown epoch must be a positive timestamp.")

        digest_payload = {
            "service": event.upstream_service_id,
            "trigger": event.trigger.name,
            "state": event.degraded_state.name,
            "cooldown": str(event.circuit_breaker_cooldown_epoch),
            "predicate": event.primary_path_health_predicate,
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return DegradationManifest(
            event=event,
            manifest_digest=digest,
        )

    @classmethod
    def verify_primary_path_readiness(
        cls, manifest: DegradationManifest, context: CurrentTimeContext
    ) -> tuple[bool, str]:
        """
        Fetching-time check: confirms whether the circuit breaker cooldown has
        expired, allowing the successor to probe the primary path.
        """
        if context.current_epoch < manifest.event.circuit_breaker_cooldown_epoch:
            remaining = manifest.event.circuit_breaker_cooldown_epoch - context.current_epoch
            return False, f"COOLDOWN_ACTIVE: {remaining:.1f}s remaining before primary-path probe is admissible."
            
        return True, f"COOLDOWN_EXPIRED: Execute primary_path_health_predicate: {manifest.event.primary_path_health_predicate}"