# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-agents-communicate-intent-when-their-physical-actuators-have-asymmetric-latency.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-agents-communicate-intent-when-their-physical-actuators-have-asymmetric-latency.warrant.json
# Markdown SHA-256:   14516dab71bc5bf2ca0cfc542e4adeccc284130d22a410e57e84164a911d6013
# Code AST SHA-256:   81065db9fcafddace5b563fa13c662208d7635124c222a944e88694cc145335d
# Verified Classes:   ActuationSkewVerdict, ActuatorProfile, SpatialIntent, SkewPolicy, SkewManifest, IntentSkewGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ActuationSkewVerdict(Enum):
    SYMMETRIC_LATENCY_SAFE = auto()
    TRANSIT_RESERVATION_REQUIRED = auto()
    PROGRESS_STALLED = auto()
    ABORT_REQUIRED = auto()

@dataclass(frozen=True)
class ActuatorProfile:
    actuator_id: str
    mean_latency_ms: float
    max_latency_ms: float

@dataclass(frozen=True)
class SpatialIntent:
    intent_id: str
    current_position: str
    intended_position: str
    progress_ratio: float
    reserved_grid_hash: str

@dataclass(frozen=True)
class SkewPolicy:
    latency_threshold_ms: float

@dataclass(frozen=True)
class SkewManifest:
    verdict: ActuationSkewVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_intent(
        cls, actuator: ActuatorProfile, intent: SpatialIntent, policy: SkewPolicy
    ) -> SkewManifest:
        
        # Gate 1: Latency negligible
        if actuator.max_latency_ms < policy.latency_threshold_ms:
            digest = cls._hash(json.dumps({
                "actuator": actuator.actuator_id,
                "intent": intent.intent_id,
                "latency": f"{actuator.max_latency_ms:.0f}"
            }, sort_keys=True))
            return SkewManifest(
                verdict=ActuationSkewVerdict.SYMMETRIC_LATENCY_SAFE,
                directive=f"PROCEED: Latency {actuator.max_latency_ms:.0f}ms is negligible. Intent broadcast sufficient.",
                manifest_digest=digest
            )

        # Gate 2: Transit reservation required
        if not intent.reserved_grid_hash:
            return SkewManifest(
                verdict=ActuationSkewVerdict.TRANSIT_RESERVATION_REQUIRED,
                directive=f"HALT: Asymmetric latency ({actuator.max_latency_ms:.0f}ms). Must reserve full trajectory grid.",
                manifest_digest=cls._hash(f"NO_GRID:{intent.intent_id}")
            )

        # Gate 3: Progress stalled
        if intent.progress_ratio < 1.0:
            # In transit, still needs reservation, but check for abort
            if intent.progress_ratio == 0.0:
                return SkewManifest(
                    verdict=ActuationSkewVerdict.PROGRESS_STALLED,
                    directive=f"WARN: Intent {intent.intent_id} has zero progress. May be blocked.",
                    manifest_digest=cls._hash(f"STALLED:{intent.intent_id}")
                )

        # Gate 4: Abort check
        if intent.progress_ratio < 0.5 and actuator.max_latency_ms > 5 * policy.latency_threshold_ms:
            return SkewManifest(
                verdict=ActuationSkewVerdict.ABORT_REQUIRED,
                directive=f"HALT: Latency {actuator.max_latency_ms:.0f}ms and progress {intent.progress_ratio:.2f} < 0.5. Abort to prevent collision.",
                manifest_digest=cls._hash(f"ABORT:{intent.intent_id}")
            )

        # Gate 5: Proceed with reservation
        digest = cls._hash(json.dumps({
            "actuator": actuator.actuator_id,
            "intent": intent.intent_id,
            "progress": f"{intent.progress_ratio:.2f}",
            "grid": intent.reserved_grid_hash
        }, sort_keys=True))
        
        return SkewManifest(
            verdict=ActuationSkewVerdict.TRANSIT_RESERVATION_REQUIRED,
            directive=f"PROCEED: Reservation active. Progress {intent.progress_ratio:.2f}.",
            manifest_digest=digest
        )