# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-reason-about-its-own-impact-on-systems-too-large-to-observe.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-reason-about-its-own-impact-on-systems-too-large-to-observe.warrant.json
# Markdown SHA-256:   700133dc37d036b17ef596e79aa15563586e434507a60e9172673556f6363c38
# Code AST SHA-256:   edad817bfa6572aedbd266c29545cb91a3f950e1bc8bfc4ffd606268f69d6daa
# Verified Classes:   SystemicVerdict, SystemicAction, SystemicPolicy, SystemicManifest, SystemicImpactGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class SystemicVerdict(Enum):
    FULLY_OBSERVABLE_SYSTEM = auto()
    WITHIN_SYSTEMIC_CAPACITY = auto()
    CONGESTION_EXTERNALITY = auto()
    CONCENTRATION_RISK = auto()

@dataclass(frozen=True)
class SystemicAction:
    action_id: str
    action_class: str
    is_observable_impact_positive: bool
    estimated_systemic_contribution: float  # 0-1, fraction of capacity
    known_externality_class: str | None
    collective_capacity_ratio: float  # session's estimated share of system capacity
    is_scale_negligible: bool

@dataclass(frozen=True)
class SystemicPolicy:
    max_systemic_contribution: float
    require_negligibility_proof: bool

@dataclass(frozen=True)
class SystemicManifest:
    verdict: SystemicVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_action(
        cls, action: SystemicAction, policy: SystemicPolicy
    ) -> SystemicManifest:
        
        # Gate 1: Negligible scale
        if action.is_scale_negligible:
            digest = cls._hash(json.dumps({
                "action": action.action_id,
                "scale": "NEGLIGIBLE"
            }, sort_keys=True))
            return SystemicManifest(
                verdict=SystemicVerdict.FULLY_OBSERVABLE_SYSTEM,
                directive=f"PROCEED: Action {action.action_id} scale negligible.",
                manifest_digest=digest
            )

        # Gate 2: System capacity
        if action.estimated_systemic_contribution > policy.max_systemic_contribution:
            if action.known_externality_class == "CONGESTION":
                return SystemicManifest(
                    verdict=SystemicVerdict.CONGESTION_EXTERNALITY,
                    directive=f"HALT: Action {action.action_id} contributes {action.estimated_systemic_contribution:.2%} to congestion.",
                    manifest_digest=cls._hash(f"CONGESTION:{action.action_id}")
                )
            if action.known_externality_class == "CONCENTRATION":
                return SystemicManifest(
                    verdict=SystemicVerdict.CONCENTRATION_RISK,
                    directive=f"HALT: Action {action.action_id} contributes to concentration.",
                    manifest_digest=cls._hash(f"CONCENTRATION:{action.action_id}")
                )
            return SystemicManifest(
                verdict=SystemicVerdict.CONGESTION_EXTERNALITY,
                directive=f"HALT: Action {action.action_id} systemic contribution {action.estimated_systemic_contribution:.2%} > {policy.max_systemic_contribution:.2%}.",
                manifest_digest=cls._hash(f"OVER_CAPACITY:{action.action_id}")
            )

        # Gate 3: Within capacity
        digest = cls._hash(json.dumps({
            "action": action.action_id,
            "class": action.action_class,
            "contribution": f"{action.estimated_systemic_contribution:.3f}",
            "capacity_share": f"{action.collective_capacity_ratio:.3f}",
            "externality": action.known_externality_class
        }, sort_keys=True))
        
        return SystemicManifest(
            verdict=SystemicVerdict.WITHIN_SYSTEMIC_CAPACITY,
            directive=f"PROCEED: Action {action.action_id} within systemic capacity ({action.estimated_systemic_contribution:.2%}).",
            manifest_digest=digest
        )