# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-handle-states-that-are-undecidable-from-observation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-handle-states-that-are-undecidable-from-observation.warrant.json
# Markdown SHA-256:   d82462763e464fd19c740f066fb0620707f08d8c2e05b62253f17ece22382f03
# Code AST SHA-256:   ee127b0a7c1b279e68c95140ac2fe4d4932125a87219e0bd910613ca5cfff24a
# Verified Classes:   UndecidableVerdict, SystemState, ActionProposal, UndecidablePolicy, UndecidableManifest, UndecidableStateGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class UndecidableVerdict(Enum):
    STATE_DECIDABLE = auto()
    FALLBACK_ACTION_ADVISABLE = auto()
    FALLBACK_ACTION_UNADVISABLE = auto()
    DEFER_INDEFINITELY_WARNING = auto()

@dataclass(frozen=True)
class SystemState:
    state_id: str
    is_decidable: bool
    undecidability_basis: str | None
    available_observations: frozenset[str]
    supports_conclusions: frozenset[str]

@dataclass(frozen=True)
class ActionProposal:
    action_id: str
    is_idempotent: bool
    is_reversible: bool
    fallback_strategy: str | None

@dataclass(frozen=True)
class UndecidablePolicy:
    require_fallback_for_irreversible: bool

@dataclass(frozen=True)
class UndecidableManifest:
    verdict: UndecidableVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_action(
        cls, state: SystemState, action: ActionProposal, policy: UndecidablePolicy
    ) -> UndecidableManifest:
        
        # Gate 1: Decidable
        if state.is_decidable:
            digest = cls._hash(json.dumps({
                "state": state.state_id,
                "action": action.action_id,
                "decidable": "TRUE"
            }, sort_keys=True))
            return UndecidableManifest(
                verdict=UndecidableVerdict.STATE_DECIDABLE,
                directive=f"PROCEED: State {state.state_id} decidable, standard action.",
                manifest_digest=digest
            )

        # Gate 2: Irreversible action requires fallback
        if policy.require_fallback_for_irreversible and not action.is_reversible:
            if not action.fallback_strategy:
                return UndecidableManifest(
                    verdict=UndecidableVerdict.FALLBACK_ACTION_UNADVISABLE,
                    directive=f"HALT: Irreversible action {action.action_id} on undecidable state without fallback.",
                    manifest_digest=cls._hash(f"NO_FALLBACK:{action.action_id}")
                )

        # Gate 3: Idempotent + reversible is safe
        if action.is_idempotent and action.is_reversible:
            digest = cls._hash(json.dumps({
                "state": state.state_id,
                "action": action.action_id,
                "basis": state.undecidability_basis,
                "idempotent": "TRUE",
                "reversible": "TRUE"
            }, sort_keys=True))
            return UndecidableManifest(
                verdict=UndecidableVerdict.FALLBACK_ACTION_ADVISABLE,
                directive=f"PROCEED: Action {action.action_id} is idempotent and reversible on undecidable state.",
                manifest_digest=digest
            )

        # Gate 4: Fallback strategy check
        if action.fallback_strategy:
            digest = cls._hash(json.dumps({
                "state": state.state_id,
                "action": action.action_id,
                "fallback": action.fallback_strategy,
                "basis": state.undecidability_basis
            }, sort_keys=True))
            return UndecidableManifest(
                verdict=UndecidableVerdict.FALLBACK_ACTION_ADVISABLE,
                directive=f"PROCEED: Execute action with fallback {action.fallback_strategy}.",
                manifest_digest=digest
            )

        # Gate 5: Defer warning
        return UndecidableManifest(
            verdict=UndecidableVerdict.DEFER_INDEFINITELY_WARNING,
            directive=f"HALT: Defer action {action.action_id} but state may never become decidable.",
            manifest_digest=cls._hash(f"DEFER:{action.action_id}")
        )