# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-convert-advisory-backpressure-into-an-enforced-bound.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-convert-advisory-backpressure-into-an-enforced-bound.warrant.json
# Markdown SHA-256:   fd53af03153f9ca349addc343fb7e699864ad2425be965e9fee81312303d17d4
# Code AST SHA-256:   2aba7758637dce51a4253d9631eba9d218efb1f8334be87024a46f9d4a97aed5
# Verified Classes:   AdvisoryOverflowError, BackpressureGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class AdvisoryOverflowError(RuntimeError):
    """Raised when advisory backpressure has no enforced bound and the queue cannot absorb in-flight."""


@dataclass(frozen=True)
class BackpressureGate:
    enforced: bool
    queue_capacity: int
    high_watermark: int
    producer_max_inflight: int
    producer_compliance_verified: bool = False

    def verify(self) -> bool:
        if self.enforced:
            return True
        if self.producer_compliance_verified:
            return True
        required = self.high_watermark + self.producer_max_inflight
        if self.queue_capacity < required:
            raise AdvisoryOverflowError(
                f"queue capacity {self.queue_capacity} < required {required} "
                f"(watermark {self.high_watermark} + inflight {self.producer_max_inflight}): "
                "advisory signal cannot prevent overflow"
            )
        return True


def dispatch_backpressure_mode(gate: BackpressureGate) -> str:
    try:
        gate.verify()
    except AdvisoryOverflowError:
        return "add-enforced-credit"
    return "backpressure-protective"