# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-spatial-safety-boundaries-must-be-transmitted-during-multi-robot-handoffs.md
# Remnant Warrant:    https://corpusfetch.com/c/what-spatial-safety-boundaries-must-be-transmitted-during-multi-robot-handoffs.warrant.json
# Markdown SHA-256:   29aba96225819a00f5f85788866e9335f01372dcff8ab79a48c0e5fe879fb293
# Code AST SHA-256:   baeccb993b0d08447585f0eaebcd6dc3df2e10aeecc437c7808111226e2a8900
# Verified Classes:   SpatialVerdict, SpatialHandoffContext, SuccessorState, SpatialManifest, SpatialHandoffGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class SpatialVerdict(Enum):
    SAFE_TO_PROCEED = auto()
    STALE_OBSTACLE_MAP = auto()
    KINEMATIC_VIOLATION = auto()
    FRAME_MISMATCH = auto()

@dataclass(frozen=True)
class SpatialHandoffContext:
    coordinate_frame_id: str
    obstacle_map_hash: str
    obstacle_map_age_sec: float
    geofence_polygon: tuple[tuple[float, float], ...]
    predecessor_max_velocity: float

@dataclass(frozen=True)
class SuccessorState:
    required_frame_id: str
    successor_max_velocity: float
    max_obstacle_map_age_sec: float

@dataclass(frozen=True)
class SpatialManifest:
    verdict: SpatialVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def verify_handoff(
        cls, ctx: SpatialHandoffContext, successor: SuccessorState
    ) -> SpatialManifest:
        
        # Gate 1: Frame of reference check
        if ctx.coordinate_frame_id != successor.required_frame_id:
            return SpatialManifest(
                verdict=SpatialVerdict.FRAME_MISMATCH,
                directive=f"HALT: Frame {ctx.coordinate_frame_id} != required {successor.required_frame_id}. Transform coordinates.",
                manifest_digest=cls._hash("FRAME_MISMATCH")
            )

        # Gate 2: Obstacle map freshness
        if ctx.obstacle_map_age_sec > successor.max_obstacle_map_age_sec:
            return SpatialManifest(
                verdict=SpatialVerdict.STALE_OBSTACLE_MAP,
                directive=f"HALT: Obstacle map is {ctx.obstacle_map_age_sec}s old. Max allowed is {successor.max_obstacle_map_age_sec}s. Sweep sensors.",
                manifest_digest=cls._hash("STALE_MAP")
            )

        # Gate 3: Kinematic envelope check (Successor must not be faster than predecessor)
        if successor.successor_max_velocity > ctx.predecessor_max_velocity:
            return SpatialManifest(
                verdict=SpatialVerdict.KINEMATIC_VIOLATION,
                directive=f"HALT: Successor max velocity {successor.successor_max_velocity} exceeds predecessor envelope {ctx.predecessor_max_velocity}.",
                manifest_digest=cls._hash("KINEMATIC_VIOLATION")
            )

        # Gate 4: Safe
        digest = cls._hash(json.dumps({
            "frame": ctx.coordinate_frame_id,
            "obstacle_hash": ctx.obstacle_map_hash,
            "geofence_vertices": str(len(ctx.geofence_polygon))
        }, sort_keys=True))
        
        return SpatialManifest(
            verdict=SpatialVerdict.SAFE_TO_PROCEED,
            directive="PROCEED: Spatial boundaries verified. Resume motion.",
            manifest_digest=digest
        )