Module governor 

Available on crate feature governor only.

Unified self-regulation governor.

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. Feature-gated (governor) and ON by default (opt-out self_regulation.enabled = false).

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), and SelfRegulationGovernor (the built bundle the runtime threads into transports + driver).

Full picture in the docs: 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 level with no weight applied. A saturated SOFT signal can never lower the level below what the HARD signal demands, nor can a missing HARD signal 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 before competing 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, so a reading oscillating around a single threshold cannot rapidly toggle pause/resume.

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.