# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-backpressure-invariants-must-survive-when-the-queue-itself-is-the-bottleneck.md
# Remnant Warrant:    https://corpusfetch.com/c/what-backpressure-invariants-must-survive-when-the-queue-itself-is-the-bottleneck.warrant.json
# Markdown SHA-256:   941bfbe5e97b00fed60c183d04a51f6e18babbb2f46041619af8c692442fb427
# Code AST SHA-256:   fc934a668e46221dbe9d0fd5fbcb36861ab7e94c18a0c7fce9269d6897d7043f
# Verified Classes:   QueueVerdict, QueueState, QueuePolicy, QueueManifest, QueueSaturationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class QueueVerdict(Enum):
    HEALTHY = auto()
    LAG_DETECTED = auto()
    DISK_PRESSURE = auto()
    NON_DURABLE_ACK = auto()

@dataclass(frozen=True)
class QueueState:
    current_lag_offset: int
    max_acceptable_lag: int
    disk_utilization_pct: float
    ack_is_durable: bool
    consumer_dequeue_latency_ms: float

@dataclass(frozen=True)
class QueuePolicy:
    max_disk_utilization_pct: float
    max_acceptable_dequeue_latency_ms: float
    require_durable_ack: bool

@dataclass(frozen=True)
class QueueManifest:
    verdict: QueueVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_queue(
        cls, state: QueueState, policy: QueuePolicy
    ) -> QueueManifest:
        
        # Gate 1: Disk pressure
        if state.disk_utilization_pct >= policy.max_disk_utilization_pct:
            return QueueManifest(
                verdict=QueueVerdict.DISK_PRESSURE,
                directive=f"HALT: Disk at {state.disk_utilization_pct:.1f}% >= {policy.max_disk_utilization_pct:.1f}%. Stop producing.",
                manifest_digest=cls._hash(f"DISK:{state.disk_utilization_pct:.1f}")
            )

        # Gate 2: Durability
        if policy.require_durable_ack and not state.ack_is_durable:
            return QueueManifest(
                verdict=QueueVerdict.NON_DURABLE_ACK,
                directive="HALT: ACK is not durable. Message at risk of loss.",
                manifest_digest=cls._hash("NON_DURABLE")
            )

        # Gate 3: Lag
        if state.current_lag_offset > state.max_acceptable_lag:
            return QueueManifest(
                verdict=QueueVerdict.LAG_DETECTED,
                directive=f"THROTTLE: Lag {state.current_lag_offset} > {state.max_acceptable_lag}. Reduce production.",
                manifest_digest=cls._hash(f"LAG:{state.current_lag_offset}")
            )

        # Gate 4: Dequeue latency
        if state.consumer_dequeue_latency_ms > policy.max_acceptable_dequeue_latency_ms:
            return QueueManifest(
                verdict=QueueVerdict.LAG_DETECTED,
                directive=f"THROTTLE: Dequeue latency {state.consumer_dequeue_latency_ms:.0f}ms > {policy.max_acceptable_dequeue_latency_ms:.0f}ms.",
                manifest_digest=cls._hash(f"DEQUEUE:{state.consumer_dequeue_latency_ms:.0f}")
            )

        # Gate 5: Healthy
        digest = cls._hash(json.dumps({
            "lag": str(state.current_lag_offset),
            "disk": f"{state.disk_utilization_pct:.1f}",
            "durable_ack": str(state.ack_is_durable),
            "dequeue_ms": f"{state.consumer_dequeue_latency_ms:.0f}"
        }, sort_keys=True))
        
        return QueueManifest(
            verdict=QueueVerdict.HEALTHY,
            directive="PROCEED: Queue is healthy.",
            manifest_digest=digest
        )