# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-negotiate-clock-skew-boundaries-during-a-distributed-state-handoff.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-negotiate-clock-skew-boundaries-during-a-distributed-state-handoff.warrant.json
# Markdown SHA-256:   88fbcfdb19a7a7a287fb7e478c7bad4d85e70d500783cffa9e7c22f800d75998
# Code AST SHA-256:   444e3f407f49139db205d943a9aafc154c261f8886610fcaa90b4859a4950462
# Verified Classes:   ClockVerdict, ClockState, HandoffContext, ClockManifest, ClockSkewGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ClockVerdict(Enum):
    SYNCHRONIZED = auto()
    DRIFT_WITHIN_TOLERANCE = auto()
    DRIFT_EXCEEDS_TOLERANCE = auto()

@dataclass(frozen=True)
class ClockState:
    predecessor_epoch: float
    successor_epoch: float
    measured_drift_ms: float

@dataclass(frozen=True)
class HandoffContext:
    tolerance_ms: float
    contains_time_sensitive_state: bool

@dataclass(frozen=True)
class ClockManifest:
    verdict: ClockVerdict
    effective_adjustment_ms: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_handoff(
        cls, state: ClockState, ctx: HandoffContext
    ) -> ClockManifest:
        
        # Gate 1: No time-sensitive state
        if not ctx.contains_time_sensitive_state:
            return ClockManifest(
                verdict=ClockVerdict.SYNCHRONIZED,
                effective_adjustment_ms=0.0,
                directive="PROCEED: Handoff has no time-sensitive state. Clock drift irrelevant.",
                manifest_digest=cls._hash("NO_TIME_STATE")
            )

        # Gate 2: Drift within tolerance
        if abs(state.measured_drift_ms) <= ctx.tolerance_ms:
            return ClockManifest(
                verdict=ClockVerdict.DRIFT_WITHIN_TOLERANCE,
                effective_adjustment_ms=state.measured_drift_ms,
                directive=f"PROCEED: Drift {state.measured_drift_ms}ms is within tolerance {ctx.tolerance_ms}ms.",
                manifest_digest=cls._hash(f"WITHIN_TOL:{state.measured_drift_ms}")
            )

        # Gate 3: Drift exceeds tolerance
        return ClockManifest(
            verdict=ClockVerdict.DRIFT_EXCEEDS_TOLERANCE,
            effective_adjustment_ms=state.measured_drift_ms,
            directive=f"HALT: Drift {state.measured_drift_ms}ms exceeds tolerance {ctx.tolerance_ms}ms. Correct timestamps by adjustment delta or re-sync clocks.",
            manifest_digest=cls._hash(f"EXCEEDS:{state.measured_drift_ms}")
        )

    @classmethod
    def adjust_timestamp(
        cls, raw_timestamp: float, manifest: ClockManifest
    ) -> float:
        """
        Fetching-time utility: adjusts a raw timestamp by the measured drift
        to produce an effective, synchronized timestamp.
        """
        return raw_timestamp + (manifest.effective_adjustment_ms / 1000.0)