Module governor 

Available on crate feature governor only.

Unified self-regulation governor.

The pressure seam for the data-plane self-regulation governor. It combines a set of PressureSources into a single normalised level and a hysteretic should_hold latch that downstream stages consult to decide whether to pause inbound work.

The pieces: UnifiedPressure (the latch over the sources), InboundGate (turns the latch into pause/resume EDGES on the inbound source – never the sink), ByteBudgetController (the AIMD lever sizing the streaming sub-block budget), SelfRegulationConfig (the cascade self_regulation section, default-ON), and SelfRegulationGovernor (the built bundle the runtime threads into transports + driver).

Self-regulation is ON by default (opt-out self_regulation.enabled = false). See the docs for the full picture: docs/SELF-REGULATION.md (the three brains – memory is the HARD source of truth, CPU deliberately dropped), docs/BACKPRESSURE.md (gate the source, never the sink), and docs/KAFKA-PATH.md (the three batch sizes + the rho ~ 0.7 loop).

Design invariants

• HARD signals are never masked. A HARD source (e.g. the memory guard) contributes its raw reading to the combined level with no weight applied. A saturated SOFT signal can never lower the level below what the HARD signal demands, and the absence of a HARD signal can never be hidden by a busy SOFT one. This is the never-OOM guarantee: the memory signal always gets through.
• SOFT signals are weighted. Each SOFT source’s reading is scaled by its weight (a sensitivity knob) before it competes for the level. A low-weight SOFT source at full saturation cannot force a hold the HARD signal would not.
• Hysteresis prevents flapping. The latch arms at pause_above and releases at resume_below; between the two it holds its current state. This stops a reading that oscillates around a single threshold from rapidly toggling pause/resume.

The seam is feature-gated (the governor feature) and default-ON when compiled in: the runtime builds the governor and threads it into the transports + driver unless self_regulation.enabled = false. New source kinds (e.g. a future CPU source) plug in via UnifiedPressure::add_source with zero change to the gate API.

Structs

ByteBudgetConfig

Configuration for the ByteBudgetController.

ByteBudgetController

AIMD byte-budget lever with a memory HARD override.

Hysteresis

Hysteresis band for the pause/resume latch.

InboundGate

Edge-detecting inbound gate over a UnifiedPressure latch.

MemoryPressureSource

HARD pressure source backed by the MemoryGuard.

NoopActuator

A no-op actuator for tests and send-only pipelines.

ObservingActuator

An observability decorator over a GateActuator.

Pressure

A normalised pressure reading, clamped to [0.0, 1.0] on construction.

SelfRegulationConfig

Cascade-overridable settings for the self-regulation governor.

SelfRegulationGovernor

The constructed self-regulation governor: shared pressure + byte budget.

UnifiedPressure

Combines pressure sources into one level under a hysteretic latch.

UnifiedPressureSnapshot

Point-in-time breakdown of the governor for diagnostics / metrics.

Enums

Admit

The gate’s admission decision for the next unit of inbound work.

SelfRegulationProfile

Sizing profile for the self-regulation byte budget.

Traits

GateActuator

Drives the inbound source on pause/resume edges.

PressureSource

A source of normalised pressure feeding the unified governor.