# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-cost-ceiling-invariants-must-survive-when-an-agents-spend-approaches-its-budget-limit.md
# Remnant Warrant:    https://corpusfetch.com/c/what-cost-ceiling-invariants-must-survive-when-an-agents-spend-approaches-its-budget-limit.warrant.json
# Markdown SHA-256:   5a9dc7d179f796b3e3852ce248d1a6eb493f39013779551df90b71f0ca168120
# Code AST SHA-256:   c6aabc66fdee7eb5332b9ec4812a29c3edd364ad08fc3ea7c093687369a03d8d
# Verified Classes:   BudgetVerdict, BudgetState, BudgetPolicy, BudgetManifest, CostCeilingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class BudgetVerdict(Enum):
    WITHIN_BUDGET = auto()
    RESERVATION_REQUIRED = auto()
    RESERVATION_EXCEEDS_CEILING = auto()
    CEILING_REACHED = auto()

@dataclass(frozen=True)
class BudgetState:
    budget_ceiling: float
    reserved_amount: float
    spent_amount: float
    in_flight_cost_estimate: float
    has_reservation: bool

@dataclass(frozen=True)
class BudgetPolicy:
    overage_allowance_pct: float
    require_reservation: bool

@dataclass(frozen=True)
class BudgetManifest:
    verdict: BudgetVerdict
    remaining_budget: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_spend(
        cls, state: BudgetState, policy: BudgetPolicy
    ) -> BudgetManifest:
        
        effective_ceiling = state.budget_ceiling * (1 + policy.overage_allowance_pct)
        total_committed = state.reserved_amount + state.spent_amount + state.in_flight_cost_estimate
        remaining = effective_ceiling - total_committed

        # Gate 1: Ceiling reached
        if remaining <= 0:
            return BudgetManifest(
                verdict=BudgetVerdict.CEILING_REACHED,
                remaining_budget=remaining,
                directive=f"HALT: Budget exhausted. Committed {total_committed:.2f} >= {effective_ceiling:.2f}.",
                manifest_digest=cls._hash(f"EXHAUSTED:{total_committed:.2f}")
            )

        # Gate 2: Reservation requirement
        if policy.require_reservation and not state.has_reservation:
            return BudgetManifest(
                verdict=BudgetVerdict.RESERVATION_REQUIRED,
                remaining_budget=remaining,
                directive=f"ACTION: Reserve budget before executing. Remaining {remaining:.2f}.",
                manifest_digest=cls._hash(f"NO_RESERVATION:{remaining:.2f}")
            )

        # Gate 3: In-flight cost vs remaining
        if state.in_flight_cost_estimate > remaining:
            return BudgetManifest(
                verdict=BudgetVerdict.RESERVATION_EXCEEDS_CEILING,
                remaining_budget=remaining,
                directive=f"HALT: In-flight cost {state.in_flight_cost_estimate:.2f} > remaining {remaining:.2f}.",
                manifest_digest=cls._hash(f"IN_FLIGHT_OVER:{state.in_flight_cost_estimate:.2f}")
            )

        # Gate 4: Within budget
        digest = cls._hash(json.dumps({
            "ceiling": f"{effective_ceiling:.2f}",
            "reserved": f"{state.reserved_amount:.2f}",
            "spent": f"{state.spent_amount:.2f}",
            "in_flight": f"{state.in_flight_cost_estimate:.2f}",
            "remaining": f"{remaining:.2f}"
        }, sort_keys=True))
        
        return BudgetManifest(
            verdict=BudgetVerdict.WITHIN_BUDGET,
            remaining_budget=remaining,
            directive=f"PROCEED: {remaining:.2f} remaining after {total_committed:.2f} committed.",
            manifest_digest=digest
        )