# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-bound-compounding-clock-drift-across-multi-hop-coordination.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-bound-compounding-clock-drift-across-multi-hop-coordination.warrant.json
# Markdown SHA-256:   836f47252e98808fded8cc6e29a7f90b65f6c0ac77b08b177ab9251b43ea7867
# Code AST SHA-256:   4a0fdf35c156608661d2179dddd65ac0a23e5165441b6faf601c58abcd3928f2
# Verified Classes:   DriftVerdict, ClockHop, CoordinationChain, DriftPolicy, DriftManifest, CompoundingClockDriftGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class DriftVerdict(Enum):
    SINGLE_HOP = auto()
    COMPOUNDED_DRIFT_BOUNDED = auto()
    COMPOUNDED_DRIFT_EXCEEDS = auto()
    RESYNC_REQUIRED = auto()

@dataclass(frozen=True)
class ClockHop:
    hop_id: str
    drift_from_previous_sec: float
    last_sync_epoch: float

@dataclass(frozen=True)
class CoordinationChain:
    chain_id: str
    hops: tuple[ClockHop, ...]
    max_acceptable_drift_sec: float
    current_epoch: float
    uses_logical_clocks: bool

@dataclass(frozen=True)
class DriftPolicy:
    require_resync_when_exceeded: bool

@dataclass(frozen=True)
class DriftManifest:
    verdict: DriftVerdict
    cumulative_drift_sec: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_chain(
        cls, chain: CoordinationChain, policy: DriftPolicy
    ) -> DriftManifest:
        
        # Gate 1: Single hop or logical clocks
        if len(chain.hops) <= 1 or chain.uses_logical_clocks:
            digest = cls._hash(json.dumps({
                "chain": chain.chain_id,
                "type": "LOGICAL" if chain.uses_logical_clocks else "SINGLE"
            }, sort_keys=True))
            return DriftManifest(
                verdict=DriftVerdict.SINGLE_HOP,
                cumulative_drift_sec=0.0,
                directive=f"PROCEED: Chain {chain.chain_id} uses logical clocks or single hop.",
                manifest_digest=digest
            )

        # Gate 2: Compute cumulative drift
        cumulative = sum(abs(h.drift_from_previous_sec) for h in chain.hops)

        # Gate 3: Exceeds threshold
        if cumulative > chain.max_acceptable_drift_sec:
            if policy.require_resync_when_exceeded:
                return DriftManifest(
                    verdict=DriftVerdict.RESYNC_REQUIRED,
                    cumulative_drift_sec=cumulative,
                    directive=f"HALT: Cumulative drift {cumulative:.3f}s > {chain.max_acceptable_drift_sec:.3f}s, resync required.",
                    manifest_digest=cls._hash(f"RESYNC:{chain.chain_id}")
                )
            return DriftManifest(
                verdict=DriftVerdict.COMPOUNDED_DRIFT_EXCEEDS,
                cumulative_drift_sec=cumulative,
                directive=f"WARN: Cumulative drift {cumulative:.3f}s exceeds tolerance.",
                manifest_digest=cls._hash(f"EXCEEDS:{chain.chain_id}")
            )

        # Gate 4: Bounded
        digest = cls._hash(json.dumps({
            "chain": chain.chain_id,
            "hops": str(len(chain.hops)),
            "cumulative": f"{cumulative:.3f}",
            "threshold": f"{chain.max_acceptable_drift_sec:.3f}"
        }, sort_keys=True))
        
        return DriftManifest(
            verdict=DriftVerdict.COMPOUNDED_DRIFT_BOUNDED,
            cumulative_drift_sec=cumulative,
            directive=f"PROCEED: Chain {chain.chain_id} drift {cumulative:.3f}s within tolerance.",
            manifest_digest=digest
        )