Module input_fairness 

Input Fairness Guard (bd-1rz0.17)

Prevents resize scheduling from starving input/keyboard events by monitoring event latencies and intervening when fairness thresholds are violated.

Design Philosophy

In a responsive TUI, keyboard input must feel instantaneous. Even during rapid resize sequences (e.g., user dragging terminal corner), keystrokes should be processed without noticeable delay. This module enforces that guarantee.

Mathematical Model

Jain’s Fairness Index

We track fairness across event types using Jain’s fairness index:

F(x₁..xₙ) = (Σxᵢ)² / (n × Σxᵢ²)

When applied to processing time allocations:

• F = 1.0: Perfect fairness (equal allocation)
• F = 1/n: Maximal unfairness (all time to one type)

We maintain F ≥ fairness_threshold (default 0.5 for two event types).

Starvation Detection

Input starvation is detected when:

1. Input latency exceeds max_input_latency, OR
2. Consecutive resize-dominated cycles exceed dominance_threshold

Intervention

When starvation is detected:

1. Force resize coalescer to yield (return ApplyNow instead of ShowPlaceholder)
2. Log the intervention with evidence
3. Reset dominance counter

Invariants

1. Bounded Input Latency: Input events are processed within max_input_latency from their arrival time, guaranteed by intervention mechanism.

2. Work Conservation: The guard never blocks event processing; it only changes priority ordering between event types.

3. Monotonic Time: All timestamps use Instant (monotonic) to prevent clock drift from causing priority inversions.

Failure Modes

Condition	Behavior	Rationale
Clock drift	Use monotonic Instant	Prevent priority inversion
Resize storm	Force input processing	Bounded latency guarantee
Input flood	Yield to BatchController	Not our concern; batch handles it
Zero events	Return default (fair)	Safe default, no intervention

Structs

FairnessConfig

Configuration for input fairness.

FairnessDecision

Fairness decision returned by the guard.

FairnessLogEntry

Fairness log entry for telemetry.

FairnessStats

Statistics about fairness scheduling.

InputFairnessGuard

Guard for input fairness scheduling.

InterventionCounts

Counts of interventions by type.

Enums

EventType

Event type for fairness classification.

InterventionReason

Intervention reason for fairness.

Type Aliases

FairnessEventType

Type alias for compatibility with program.rs