# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-bound-inferential-uncertainty-when-observation-is-costly.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-bound-inferential-uncertainty-when-observation-is-costly.warrant.json
# Markdown SHA-256:   c7c3762bd93ab02a086ce41c6f20b42fbd736ca317cb5c065607d27b69356601
# Code AST SHA-256:   b0258ea50c5286cfa056b667374d0908d94dbcbebb71fdbfb67a4f58dd3cad6d
# Verified Classes:   ObservationVerdict, BeliefState, ObservationProposal, ObservationPolicy, ObservationManifest, CostlyObservationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ObservationVerdict(Enum):
    BELIEF_SUFFICIENT = auto()
    OBSERVE_FURTHER = auto()
    BUDGET_EXHAUSTED = auto()
    DIMINISHING_RETURNS = auto()

@dataclass(frozen=True)
class BeliefState:
    belief_id: str
    current_uncertainty: float
    decision_sufficiency_threshold: float
    observation_budget_used: float
    observation_budget_total: float

@dataclass(frozen=True)
class ObservationProposal:
    observation_id: str
    expected_uncertainty_reduction: float
    cost: float

@dataclass(frozen=True)
class ObservationPolicy:
    min_marginal_value: float  # uncertainty_reduction / cost

@dataclass(frozen=True)
class ObservationManifest:
    verdict: ObservationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_observation(
        cls, belief: BeliefState, obs: ObservationProposal, policy: ObservationPolicy
    ) -> ObservationManifest:
        
        # Gate 1: Already sufficient
        if belief.current_uncertainty <= belief.decision_sufficiency_threshold:
            digest = cls._hash(json.dumps({
                "belief": belief.belief_id,
                "uncertainty": f"{belief.current_uncertainty:.3f}",
                "threshold": f"{belief.decision_sufficiency_threshold:.3f}"
            }, sort_keys=True))
            return ObservationManifest(
                verdict=ObservationVerdict.BELIEF_SUFFICIENT,
                directive=f"PROCEED: Uncertainty {belief.current_uncertainty:.3f} <= {belief.decision_sufficiency_threshold:.3f}, act.",
                manifest_digest=digest
            )

        # Gate 2: Budget check
        remaining_budget = belief.observation_budget_total - belief.observation_budget_used
        if obs.cost > remaining_budget:
            return ObservationManifest(
                verdict=ObservationVerdict.BUDGET_EXHAUSTED,
                directive=f"HALT: Observation {obs.observation_id} cost {obs.cost:.2f} > remaining {remaining_budget:.2f}.",
                manifest_digest=cls._hash(f"BUDGET:{obs.observation_id}")
            )

        # Gate 3: Marginal value
        if obs.cost <= 0:
            return ObservationManifest(
                verdict=ObservationVerdict.OBSERVE_FURTHER,
                directive=f"PROCEED: Observation {obs.observation_id} is free.",
                manifest_digest=cls._hash(f"FREE:{obs.observation_id}")
            )

        marginal_value = obs.expected_uncertainty_reduction / obs.cost
        if marginal_value < policy.min_marginal_value:
            return ObservationManifest(
                verdict=ObservationVerdict.DIMINISHING_RETURNS,
                directive=f"HALT: Marginal value {marginal_value:.4f} < {policy.min_marginal_value:.4f}, act on current beliefs.",
                manifest_digest=cls._hash(f"DIMINISHING:{marginal_value:.4f}")
            )

        # Gate 4: Observe further
        digest = cls._hash(json.dumps({
            "belief": belief.belief_id,
            "observation": obs.observation_id,
            "marginal_value": f"{marginal_value:.4f}",
            "expected_reduction": f"{obs.expected_uncertainty_reduction:.3f}",
            "cost": f"{obs.cost:.2f}"
        }, sort_keys=True))
        
        return ObservationManifest(
            verdict=ObservationVerdict.OBSERVE_FURTHER,
            directive=f"PROCEED: Observation {obs.observation_id} marginal value {marginal_value:.3f}.",
            manifest_digest=digest
        )