# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-preserve-environmental-coupling-that-cannot-be-undone.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-preserve-environmental-coupling-that-cannot-be-undone.warrant.json
# Markdown SHA-256:   16a0fe56f4cb46103b1de455901cfdb599929698b3ebc2d09de792bc0539aed7
# Code AST SHA-256:   a7b430aa5a8685571fda0978e47769c58d829ca57f6290a6d4244874f86f6bd8
# Verified Classes:   EnvironmentalVerdict, EnvironmentalAction, EnvironmentalPolicy, EnvironmentalManifest, IrreversibleCouplingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class EnvironmentalVerdict(Enum):
    ISOLATED_ACTION = auto()
    REVERSIBLE_MODIFICATION = auto()
    IRREVERSIBLE_COMMITMENT_TRACKED = auto()
    UNTRACKED_IRREVERSIBLE = auto()

@dataclass(frozen=True)
class EnvironmentalAction:
    action_id: str
    modifies_environment: bool
    is_reversible: bool
    forecloses_branches: tuple[str, ...]
    branch_commitment_documented: bool
    post_action_state_hash: str | None

@dataclass(frozen=True)
class EnvironmentalPolicy:
    require_commitment_for_branch_foreclosure: bool

@dataclass(frozen=True)
class EnvironmentalManifest:
    verdict: EnvironmentalVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_action(
        cls, action: EnvironmentalAction, policy: EnvironmentalPolicy
    ) -> EnvironmentalManifest:
        
        # Gate 1: Isolated
        if not action.modifies_environment:
            digest = cls._hash(json.dumps({
                "action": action.action_id,
                "type": "ISOLATED"
            }, sort_keys=True))
            return EnvironmentalManifest(
                verdict=EnvironmentalVerdict.ISOLATED_ACTION,
                directive=f"PROCEED: Action {action.action_id} does not modify environment.",
                manifest_digest=digest
            )

        # Gate 2: Reversible
        if action.is_reversible:
            digest = cls._hash(json.dumps({
                "action": action.action_id,
                "type": "REVERSIBLE"
            }, sort_keys=True))
            return EnvironmentalManifest(
                verdict=EnvironmentalVerdict.REVERSIBLE_MODIFICATION,
                directive=f"PROCEED: Action {action.action_id} modifies environment reversibly.",
                manifest_digest=digest
            )

        # Gate 3: Branch commitment documentation
        if action.forecloses_branches:
            if policy.require_commitment_for_branch_foreclosure and not action.branch_commitment_documented:
                return EnvironmentalManifest(
                    verdict=EnvironmentalVerdict.UNTRACKED_IRREVERSIBLE,
                    directive=f"HALT: Action {action.action_id} forecloses branches {action.forecloses_branches} without documentation.",
                    manifest_digest=cls._hash(f"UNTRACKED:{action.action_id}")
                )

        # Gate 4: Tracked
        digest = cls._hash(json.dumps({
            "action": action.action_id,
            "foreclosed": action.forecloses_branches,
            "post_state": action.post_action_state_hash,
            "documented": str(action.branch_commitment_documented)
        }, sort_keys=True))
        
        return EnvironmentalManifest(
            verdict=EnvironmentalVerdict.IRREVERSIBLE_COMMITMENT_TRACKED,
            directive=f"PROCEED: Irreversible action {action.action_id} tracked, {len(action.forecloses_branches)} branches foreclosed.",
            manifest_digest=digest
        )