# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-physical-action-provenance-must-accompany-an-actuator-log-to-prove-the-action-actually-occurred.md
# Remnant Warrant:    https://corpusfetch.com/c/what-physical-action-provenance-must-accompany-an-actuator-log-to-prove-the-action-actually-occurred.warrant.json
# Markdown SHA-256:   91a7c3f5cf921d3211892072f237e8e2ed91f6e63637f53703fb03d4075549c9
# Code AST SHA-256:   b07f2ba5cf9dba193c6006a1b56cbcdbd7be5b67e035863857a44330d1f36134
# Verified Classes:   ActuationVerdict, ActuatorLog, VerificationContext, ActuationManifest, PhysicalActionProvenanceGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ActuationVerdict(Enum):
    PHYSICALLY_CONFIRMED = auto()
    COMMAND_ONLY = auto()
    OVERRIDE_DETECTED = auto()
    SIMULATION_NOT_PHYSICAL = auto()

@dataclass(frozen=True)
class ActuatorLog:
    command_hash: str
    sensor_confirmation_hash: str | None
    override_signature: str | None
    is_simulation: bool

@dataclass(frozen=True)
class VerificationContext:
    require_sensor_confirmation: bool
    allow_simulation: bool

@dataclass(frozen=True)
class ActuationManifest:
    verdict: ActuationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_actuation(
        cls, log: ActuatorLog, ctx: VerificationContext
    ) -> ActuationManifest:
        
        # Gate 1: Simulation check
        if log.is_simulation:
            if not ctx.allow_simulation:
                return ActuationManifest(
                    verdict=ActuationVerdict.SIMULATION_NOT_PHYSICAL,
                    directive="HALT: Simulated actuation is not a real physical event. Reject.",
                    manifest_digest=cls._hash(f"SIM:{log.command_hash}")
                )
            return ActuationManifest(
                verdict=ActuationVerdict.SIMULATION_NOT_PHYSICAL,
                directive="PROCEED: Simulation acknowledged. Do not treat as physical state.",
                manifest_digest=cls._hash(f"SIM_OK:{log.command_hash}")
            )

        # Gate 2: Override detection
        if log.override_signature:
            return ActuationManifest(
                verdict=ActuationVerdict.OVERRIDE_DETECTED,
                directive=f"HALT: Override detected. Physical state determined by override, not command.",
                manifest_digest=cls._hash(f"OVERRIDE:{log.command_hash}")
            )

        # Gate 3: Sensor confirmation
        if ctx.require_sensor_confirmation and not log.sensor_confirmation_hash:
            return ActuationManifest(
                verdict=ActuationVerdict.COMMAND_ONLY,
                directive="HALT: Command dispatched but no physical sensor confirmation. Treat state as UNVERIFIED.",
                manifest_digest=cls._hash(f"NO_SENSOR:{log.command_hash}")
            )

        # Gate 4: Confirmed
        digest = cls._hash(json.dumps({
            "command": log.command_hash,
            "sensor": log.sensor_confirmation_hash or "NONE",
            "override": "NONE"
        }, sort_keys=True))
        
        return ActuationManifest(
            verdict=ActuationVerdict.PHYSICALLY_CONFIRMED,
            directive="PROCEED: Physical action confirmed by independent sensor.",
            manifest_digest=digest
        )