Module backpressure_tracker 

BackpressureTracker - per-peer receiver-side state for the typed-overload-signal protocol per docs/internal/superpowers/specs/2026-06-23-backpressure-runtime.md.

The framework owns this primitive; the engine consults it at Phase 1 of the poll cycle when ingress depth crosses the high-water mark or when RttTracker::scan_phi flips a sender to Suspect. Each consultation either yields a Decision::EmitNotice (the receiver will emit a typed BackoffNotice envelope back to the sender) or a Decision::Suppress (duplicate-suppression window still open, silent-drop mode active, or another reason the receiver should not act).

Composition

Per peer_state.rs, the tracker joins the existing per-peer state cluster (gate, governor, backoff) as a sibling field. Component authors and engine sites reach it through ctx.peers.backpressure / framework.peer_state.backpressure, matching the existing access pattern.

The tracker is receiver-side state. The matching sender-side state lives in the existing BackoffTable - on receipt of a BackoffNotice, the sender updates backoff so the existing BackoffGateTx consultation already gates the next outbound send. No new sender-side primitive is required.

K-then-silent semantics

Each emitted notice bumps notices_sent for the peer. The per-peer counter resets when the sender’s RttTracker::scan_phi flips back to Live (matching the existing recovery surface). Once notices_sent exceeds notice_threshold_k without recovery, Decision::EmitNotice is no longer returned; Decision::SilentDrop is returned instead. The engine’s Phase 1 envelope router drops envelopes from a silent-drop peer without further notice emission. The first silent-drop transition surfaces as InfraEvent::SilentDropActive on the bus; subsequent envelopes from the same peer surface no further event until the peer recovers.

Structs

BackpressureEntry

Per-peer back-pressure bookkeeping.

BackpressureTracker

Per-peer receiver-side back-pressure state.

Enums

BackoffCause

Why the receiver is requesting a back-off.

Decision

Decision returned by BackpressureTracker::observe_overload.

Constants

DEFAULT_HIGH_WATER_PCT

Default high-water mark percentage. Matches the spec default in §6: ingress queue depth >= 75% of capacity triggers a BackoffCause::QueueFull notice.

DEFAULT_K_BEFORE_SILENT

Default K (notices-without-slowdown before silent-drop). Matches RttEma::is_warm’s “evidence sufficient to act” threshold of 3 samples per bb-runtime/src/framework/rtt_tracker.rs:126-128.

DEFAULT_MIN_NOTICE_INTERVAL_NS

Default minimum interval between successive notices to the same peer (1 second). Acts as a hard lower bound on the duplicate-suppression window so a flood of inbound envelopes from one peer produces at most one notice per second even when the receiver lacks a tighter per-cause min_backoff_ns hint.