# How must an instance convert advisory backpressure into an enforced bound?

**Date of Record:** 2026 November 2

**Scope:** Applies to producer-consumer channels where the consumer signals backpressure (slow-down, high-watermark, nack-with-retry-hint) and the producer may continue sending because the signal is advisory rather than enforced. Does not apply to channels with enforced flow control (credit-based, window-based with window decrement).

## Core Distinction

Backpressure is either **advisory** (the consumer asks the producer to slow down, and the producer may ignore) or **enforced** (the consumer stops accepting, and the producer blocks or drops). Advisory backpressure depends on producer cooperation; enforced backpressure does not. An instance that treats advisory backpressure as protection is assuming cooperation from the party that is sending.

**Invariant.** Backpressure protects the consumer if and only if `queue_high_watermark + producer_inflight_max <= queue_capacity`, OR the producer's send is blocked when the consumer's queue is full (enforced).

**Violation.** The **Advisory Overflow**. The consumer signals `retry-after` and continues accepting. The producer's sending rate exceeds the rate at which the consumer can drain. The queue fills; new messages are dropped, or memory exhausts. The signal was sent; the producer did not comply; the consumer has no enforced limit to fall back on.

**Asymmetry.** The signal is sent and acknowledged. The producer's rate is under the producer's control. The consumer's overflow is a consequence of the producer's non-compliance, which is a valid producer behavior under an advisory protocol.

**Recorded elements.** The `backpressure-signal-receipt` (advisory or enforced), the `producer-compliance-signature` (observed rate versus requested rate), and the `enforced-bound-receipt` (credit, window, or hard-drop limit) together make the protection checkable.

## What Was Observed

**Signature.** Queue overflow on the consumer while the producer reports sending at normal rate. The consumer's backpressure signal is logged and normal. Producer has received it and has not changed behavior (either because it does not honor advisory signals or because it is a legacy producer that predates the signal).

**Trace.** Consumer queue 10,000 messages. High-watermark signal at 7,000. Producer sends 5,000/s, consumer drains 3,000/s. Queue exceeds 10,000 in about 3 seconds; overflow drops messages. Producer continues sending at 5,000/s and reports healthy.

**Why monitoring stays green.** Signal sent (consumer's job done). Producer sending (its job). Queue overflow logged as a queue-management event, which is expected under load.

## Condition of Validity

The instance must ensure at least one holds before it treats backpressure as protective:

1. **Must enforce a hard bound.** The consumer stops accepting when the queue reaches capacity, either by blocking the producer (credit) or by rejecting with a hard error that the producer cannot ignore.
2. **Must have headroom for in-flight.** `queue_capacity >= queue_high_watermark + producer_max_inflight` — the signal must fire early enough that in-flight messages do not overflow the queue before the producer can respond.
3. **Must verify producer compliance.** Where the producer may ignore advisory signals, the consumer measures producer rate against the requested rate and surfaces non-compliance as an alert, not merely a metric.

## Decision Boundary

- Enforced flow control (credit/window): protective.
- Advisory with verified cooperative producer: protective in steady state; assumes cooperation.
- Advisory with unverified producer: protective only if queue headroom covers max producer in-flight.
- Advisory without headroom: overflow is guaranteed under sustained overload.

## Operational Effect

The invariant converts an advisory signal into a bounded guarantee. The instance's correct posture is to add a hard cap behind the advisory signal, and to size the queue to absorb in-flight messages.

**Trap.** Increase the queue. A larger queue postpones overflow without changing the rate mismatch; it also increases memory pressure and, if the queue is durable, increases replay time on consumer restart. The fix is an enforced bound, not a larger buffer.

```python
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"
```