# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-must-session-termination-capture-the-exact-memory-ceiling-that-triggered-throttling.md
# Remnant Warrant:    https://corpusfetch.com/c/why-must-session-termination-capture-the-exact-memory-ceiling-that-triggered-throttling.warrant.json
# Markdown SHA-256:   37571f190abd419e2642565e79fa88a2048b0e8e9adf536de735901b116e63f9
# Code AST SHA-256:   3895330de706ab27a1ea1278a99c0cda2eaf430ada67a9cb01f1c74e572f359d
# Verified Classes:   MemoryPressureState, ThrottlingEvent, ThrottlingManifest, SuccessorAllocationRequest, ThrottlingBoundaryRecorder
# Defensive Guards:   3 fail-closed invariants (zero external deps)

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


class MemoryPressureState(Enum):
    NOMINAL = auto()
    CGROUP_THROTTLED = auto()
    SWAP_THRASHING = auto()


@dataclass(frozen=True)
class ThrottlingEvent:
    soft_limit_bytes: int
    hard_limit_bytes: int
    peak_rss_bytes: int
    psi_stall_duration_ms: int
    swap_consumed_bytes: int


@dataclass(frozen=True)
class ThrottlingManifest:
    pressure_state: MemoryPressureState
    event: ThrottlingEvent
    manifest_digest: str


@dataclass(frozen=True)
class SuccessorAllocationRequest:
    requested_rss_bytes: int
    requested_parallel_workers: int


class ThrottlingBoundaryRecorder:
    """
    Evaluates memory pressure events to seal the exact soft/hard cgroup limits,
    ensuring successors do not re-trigger OOM kills or severe stalls.
    """

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

    @classmethod
    def seal_throttling_event(
        cls, pressure_state: MemoryPressureState, event: ThrottlingEvent
    ) -> ThrottlingManifest:
        
        if event.peak_rss_bytes < event.soft_limit_bytes:
            raise ValueError(
                "Peak RSS is below the soft limit; this does not qualify as a throttling event."
            )
            
        if event.soft_limit_bytes >= event.hard_limit_bytes:
            raise ValueError(
                "Soft limit must be strictly less than the hard limit."
            )
            
        if pressure_state is MemoryPressureState.CGROUP_THROTTLED and event.psi_stall_duration_ms <= 0:
            raise ValueError(
                "Cgroup throttling must have a PSI stall duration > 0."
            )

        digest_payload = {
            "state": pressure_state.name,
            "soft": str(event.soft_limit_bytes),
            "hard": str(event.hard_limit_bytes),
            "rss": str(event.peak_rss_bytes),
            "psi_ms": str(event.psi_stall_duration_ms),
            "swap": str(event.swap_consumed_bytes),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return ThrottlingManifest(
            pressure_state=pressure_state,
            event=event,
            manifest_digest=digest,
        )

    @classmethod
    def verify_successor_capacity(
        cls, manifest: ThrottlingManifest, request: SuccessorAllocationRequest
    ) -> tuple[bool, str]:
        """
        Fetching-time check: ensures the successor's requested allocation
        will not breach the observed hard limit or re-trigger throttling.
        """
        # Gate 1: Hard limit check (instant OOM risk)
        if request.requested_rss_bytes >= manifest.event.hard_limit_bytes:
            return False, (
                f"OOM_RISK: Requested {request.requested_rss_bytes} bytes exceeds "
                f"hard limit of {manifest.event.hard_limit_bytes} bytes."
            )
            
        # Gate 2: Soft limit check (throttling/latency risk)
        if request.requested_rss_bytes >= manifest.event.soft_limit_bytes:
            if request.requested_parallel_workers > 1:
                return False, (
                    f"THROTTLE_RISK: Requested memory ({request.requested_rss_bytes}) "
                    f"exceeds soft limit ({manifest.event.soft_limit_bytes}) with "
                    f"parallel workers > 1. Serialize or reduce memory."
                )

        return True, "CAPACITY_ADMISSIBLE: Allocation is within safe bounds."