# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-prevent-instances-from-over-committing-to-capabilities-that-may-change.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-prevent-instances-from-over-committing-to-capabilities-that-may-change.warrant.json
# Markdown SHA-256:   bc2a14da1a1ceabfbe75666bada2398fa788cb69acaea17f22200d10128cbfb0
# Code AST SHA-256:   28b3eddf62ae73618bd1ab323acb1fbea0688c916b09c3c8ae2ad92ecb28213f
# Verified Classes:   CommitmentVerdict, CapabilityRequirement, CommitmentProposal, CommitmentPolicy, CommitmentManifest, OverCommitmentGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CommitmentVerdict(Enum):
    NO_CAPABILITY_DEPENDENCY = auto()
    SAFE_COMMITMENT = auto()
    OVER_COMMITMENT_RISK = auto()
    HEDGE_REQUIRED = auto()

@dataclass(frozen=True)
class CapabilityRequirement:
    capability_id: str
    required_units: float
    available_units: float
    historical_stability: float  # 0-1, higher = more stable

@dataclass(frozen=True)
class CommitmentProposal:
    commitment_id: str
    requirements: tuple[CapabilityRequirement, ...]
    is_critical: bool
    hedge_available: bool

@dataclass(frozen=True)
class CommitmentPolicy:
    min_margin_ratio: float
    require_hedge_for_critical: bool

@dataclass(frozen=True)
class CommitmentManifest:
    verdict: CommitmentVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_commitment(
        cls, proposal: CommitmentProposal, policy: CommitmentPolicy
    ) -> CommitmentManifest:
        
        # Gate 1: No capability dependency
        if not proposal.requirements:
            digest = cls._hash(json.dumps({
                "commitment": proposal.commitment_id,
                "requirements": "NONE"
            }, sort_keys=True))
            return CommitmentManifest(
                verdict=CommitmentVerdict.NO_CAPABILITY_DEPENDENCY,
                directive=f"PROCEED: Commitment {proposal.commitment_id} has no capability dependency.",
                manifest_digest=digest
            )

        # Gate 2: Margin check per requirement
        for req in proposal.requirements:
            if req.available_units <= 0:
                return CommitmentManifest(
                    verdict=CommitmentVerdict.OVER_COMMITMENT_RISK,
                    directive=f"HALT: Capability {req.capability_id} has no available units.",
                    manifest_digest=cls._hash(f"NO_UNITS:{req.capability_id}")
                )
            
            margin_ratio = (req.available_units - req.required_units) / req.available_units
            required_margin = policy.min_margin_ratio / req.historical_stability if req.historical_stability > 0 else 1.0

            if margin_ratio < required_margin:
                return CommitmentManifest(
                    verdict=CommitmentVerdict.OVER_COMMITMENT_RISK,
                    directive=f"HALT: Capability {req.capability_id} margin {margin_ratio:.2f} < required {required_margin:.2f}.",
                    manifest_digest=cls._hash(f"LOW_MARGIN:{req.capability_id}:{margin_ratio:.2f}")
                )

        # Gate 3: Critical hedge requirement
        if proposal.is_critical and policy.require_hedge_for_critical:
            if not proposal.hedge_available:
                return CommitmentManifest(
                    verdict=CommitmentVerdict.HEDGE_REQUIRED,
                    directive=f"HALT: Critical commitment {proposal.commitment_id} requires hedge.",
                    manifest_digest=cls._hash(f"NO_HEDGE:{proposal.commitment_id}")
                )

        # Gate 4: Safe
        digest = cls._hash(json.dumps({
            "commitment": proposal.commitment_id,
            "requirements": tuple(
                {"capability": r.capability_id, "required": f"{r.required_units:.2f}", "available": f"{r.available_units:.2f}", "stability": f"{r.historical_stability:.2f}"}
                for r in proposal.requirements
            ),
            "critical": str(proposal.is_critical)
        }, sort_keys=True))
        
        return CommitmentManifest(
            verdict=CommitmentVerdict.SAFE_COMMITMENT,
            directive=f"PROCEED: Commitment {proposal.commitment_id} safe with margin.",
            manifest_digest=digest
        )