1#![forbid(unsafe_code)]
2
3use web_time::{Duration, Instant};
41
42#[cfg(feature = "tracing")]
43use tracing::{trace, warn};
44
45#[derive(Debug, Clone, PartialEq)]
87pub struct PidGains {
88 pub kp: f64,
90 pub ki: f64,
92 pub kd: f64,
94 pub integral_max: f64,
96}
97
98impl Default for PidGains {
99 fn default() -> Self {
100 Self {
101 kp: 0.5,
102 ki: 0.05,
103 kd: 0.2,
104 integral_max: 5.0,
105 }
106 }
107}
108
109#[derive(Debug, Clone)]
113struct PidState {
114 integral: f64,
116 prev_error: f64,
118 last_p: f64,
120 last_i: f64,
122 last_d: f64,
124}
125
126impl Default for PidState {
127 fn default() -> Self {
128 Self {
129 integral: 0.0,
130 prev_error: 0.0,
131 last_p: 0.0,
132 last_i: 0.0,
133 last_d: 0.0,
134 }
135 }
136}
137
138impl PidState {
139 fn update(&mut self, error: f64, gains: &PidGains) -> f64 {
143 if error.is_nan() {
144 return 0.0;
145 }
146 self.integral = (self.integral + error).clamp(-gains.integral_max, gains.integral_max);
148
149 let derivative = error - self.prev_error;
151 self.prev_error = error;
152
153 self.last_p = gains.kp * error;
155 self.last_i = gains.ki * self.integral;
156 self.last_d = gains.kd * derivative;
157
158 self.last_p + self.last_i + self.last_d
160 }
161
162 fn reset(&mut self) {
164 *self = Self::default();
165 }
166}
167
168#[derive(Debug, Clone, PartialEq)]
213pub struct EProcessConfig {
214 pub lambda: f64,
218 pub adaptive_lambda: bool,
222 pub grapa_eta: f64,
225 pub lambda_min: f64,
228 pub lambda_max: f64,
231 pub alpha: f64,
234 pub beta: f64,
237 pub sigma_ema_decay: f64,
240 pub sigma_floor_ms: f64,
243 pub warmup_frames: u32,
253}
254
255impl Default for EProcessConfig {
256 fn default() -> Self {
257 Self {
258 lambda: 0.5,
259 adaptive_lambda: true,
260 grapa_eta: 0.1,
261 lambda_min: 0.05,
262 lambda_max: 2.0,
263 alpha: 0.05,
264 beta: 0.5,
265 sigma_ema_decay: 0.9,
266 sigma_floor_ms: 1.0,
267 warmup_frames: 10,
268 }
269 }
270}
271
272#[derive(Debug, Clone)]
274struct EProcessState {
275 e_value: f64,
277 lambda: f64,
283 sigma_ema: f64,
285 mean_ema: f64,
287 frames_observed: u32,
289}
290
291impl Default for EProcessState {
292 fn default() -> Self {
293 Self {
294 e_value: 1.0,
295 lambda: EProcessConfig::default().lambda,
296 sigma_ema: 0.0,
297 mean_ema: 0.0,
298 frames_observed: 0,
299 }
300 }
301}
302
303impl EProcessState {
304 fn new(config: &EProcessConfig) -> Self {
305 Self {
306 lambda: config.lambda,
307 ..Self::default()
308 }
309 }
310
311 fn update(&mut self, frame_time_ms: f64, target_ms: f64, config: &EProcessConfig) -> f64 {
326 self.frames_observed = self.frames_observed.saturating_add(1);
327
328 if self.frames_observed == 1 {
330 self.mean_ema = frame_time_ms;
331 self.sigma_ema = config.sigma_floor_ms;
332 self.lambda = config.lambda;
333 } else {
334 let decay = config.sigma_ema_decay;
335 self.mean_ema = decay * self.mean_ema + (1.0 - decay) * frame_time_ms;
336 let deviation = (frame_time_ms - self.mean_ema).abs();
338 self.sigma_ema = decay * self.sigma_ema + (1.0 - decay) * deviation;
339 }
340
341 if !config.adaptive_lambda {
342 self.lambda = config.lambda;
343 }
344
345 let sigma = self.sigma_ema.max(config.sigma_floor_ms);
347
348 let residual = (frame_time_ms - target_ms) / sigma;
350
351 let lambda = self.lambda;
356 let log_factor = lambda * residual - lambda * lambda / 2.0;
357 if !log_factor.is_nan() {
358 self.e_value *= log_factor.exp();
359 self.e_value = self.e_value.clamp(1e-10, 1e10);
362 }
363
364 if config.adaptive_lambda
368 && self.frames_observed >= config.warmup_frames
369 && !residual.is_nan()
370 {
371 let lo = config.lambda_min.min(config.lambda_max);
372 let hi = config.lambda_max.max(config.lambda_min);
373 let effective_min = if self.e_value > 1.0 && residual < 0.0 {
374 config.lambda.clamp(lo, hi)
375 } else {
376 lo
377 };
378 self.lambda = (self.lambda + config.grapa_eta * (residual - self.lambda))
379 .clamp(effective_min, hi);
380 }
381
382 #[cfg(feature = "tracing")]
383 trace!(
384 target: ftui_core::TARGET_EPROCESS,
385 lambda = self.lambda,
386 e_value = self.e_value,
387 residual,
388 "e-process update"
389 );
390
391 self.e_value
392 }
393
394 fn should_degrade(&self, config: &EProcessConfig) -> bool {
396 if self.frames_observed < config.warmup_frames {
397 return false; }
399 self.e_value > 1.0 / config.alpha
400 }
401
402 fn should_upgrade(&self, config: &EProcessConfig) -> bool {
404 if self.frames_observed < config.warmup_frames {
405 return true; }
407 self.e_value < config.beta
408 }
409
410 fn reset(&mut self, config: &EProcessConfig) {
412 *self = Self::new(config);
413 }
414}
415
416#[derive(Debug, Clone, PartialEq)]
418pub struct BudgetControllerConfig {
419 pub pid: PidGains,
421 pub eprocess: EProcessConfig,
423 pub target: Duration,
425 pub degrade_threshold: f64,
437 pub upgrade_threshold: f64,
440 pub cooldown_frames: u32,
446 pub degradation_floor: DegradationLevel,
454}
455
456impl Default for BudgetControllerConfig {
457 fn default() -> Self {
458 Self {
459 pid: PidGains::default(),
460 eprocess: EProcessConfig::default(),
461 target: Duration::from_millis(16),
462 degrade_threshold: 0.3,
463 upgrade_threshold: 0.2,
464 cooldown_frames: 3,
465 degradation_floor: DegradationLevel::SimpleBorders,
466 }
467 }
468}
469
470#[derive(Debug, Clone)]
504pub struct BudgetController {
505 config: BudgetControllerConfig,
506 pid: PidState,
507 eprocess: EProcessState,
508 current_level: DegradationLevel,
509 frames_since_change: u32,
510 last_pid_output: f64,
511 last_decision: BudgetDecision,
512 last_decision_reason: BudgetDecisionReason,
513 last_frame_ms: f64,
514 transition_seq: u64,
515 last_transition_correlation_id: u64,
516 last_pid_gate_threshold: f64,
517 last_pid_gate_margin: f64,
518 last_evidence_threshold: f64,
519 last_evidence_margin: f64,
520 recovery_streak: u32,
521 total_degrades: u64,
522 total_recoveries: u64,
523}
524
525#[derive(Debug, Clone, Copy, PartialEq, Eq)]
527pub enum BudgetDecision {
528 Hold,
530 Degrade,
532 Upgrade,
534}
535
536impl BudgetDecision {
537 #[inline]
539 pub fn as_str(self) -> &'static str {
540 match self {
541 Self::Hold => "stay",
542 Self::Degrade => "degrade",
543 Self::Upgrade => "upgrade",
544 }
545 }
546}
547
548pub const BUDGET_TELEMETRY_SCHEMA_VERSION: u16 = 1;
550
551#[derive(Debug, Clone, Copy, PartialEq, Eq)]
553pub enum BudgetDecisionReason {
554 CooldownActive,
556 OverloadEvidencePassed,
558 UnderloadEvidencePassed,
560 AtMaxDegradation,
562 AtDegradationFloor,
564 AtFullQuality,
566 OverloadEvidenceInsufficient,
568 UnderloadEvidenceInsufficient,
570 WithinThresholdBand,
572}
573
574impl BudgetDecisionReason {
575 #[inline]
577 pub fn as_str(self) -> &'static str {
578 match self {
579 Self::CooldownActive => "cooldown_active",
580 Self::OverloadEvidencePassed => "overload_evidence_passed",
581 Self::UnderloadEvidencePassed => "underload_evidence_passed",
582 Self::AtMaxDegradation => "at_max_degradation",
583 Self::AtDegradationFloor => "at_degradation_floor",
584 Self::AtFullQuality => "at_full_quality",
585 Self::OverloadEvidenceInsufficient => "overload_evidence_insufficient",
586 Self::UnderloadEvidenceInsufficient => "underload_evidence_insufficient",
587 Self::WithinThresholdBand => "within_threshold_band",
588 }
589 }
590}
591
592impl BudgetController {
593 pub fn new(config: BudgetControllerConfig) -> Self {
595 let eprocess = EProcessState::new(&config.eprocess);
596 Self {
597 config,
598 pid: PidState::default(),
599 eprocess,
600 current_level: DegradationLevel::Full,
601 frames_since_change: 0,
602 last_pid_output: 0.0,
603 last_decision: BudgetDecision::Hold,
604 last_decision_reason: BudgetDecisionReason::WithinThresholdBand,
605 last_frame_ms: 0.0,
606 transition_seq: 0,
607 last_transition_correlation_id: 0,
608 last_pid_gate_threshold: 0.0,
609 last_pid_gate_margin: 0.0,
610 last_evidence_threshold: 0.0,
611 last_evidence_margin: 0.0,
612 recovery_streak: 0,
613 total_degrades: 0,
614 total_recoveries: 0,
615 }
616 }
617
618 pub fn update(&mut self, frame_time: Duration) -> BudgetDecision {
622 let target_ms = self.config.target.as_secs_f64() * 1000.0;
623 let frame_ms = frame_time.as_secs_f64() * 1000.0;
624
625 let error = (frame_ms - target_ms) / target_ms;
627
628 let u = self.pid.update(error, &self.config.pid);
630 self.last_pid_output = u;
631 self.last_frame_ms = frame_ms;
632
633 self.eprocess
635 .update(frame_ms, target_ms, &self.config.eprocess);
636
637 if u < -self.config.upgrade_threshold {
639 self.recovery_streak = self.recovery_streak.saturating_add(1);
640 } else {
641 self.recovery_streak = 0;
642 }
643
644 self.frames_since_change = self.frames_since_change.saturating_add(1);
646
647 let mut decision = BudgetDecision::Hold;
648 let mut reason = BudgetDecisionReason::WithinThresholdBand;
649 let mut pid_gate_threshold = 0.0;
650 let mut pid_gate_margin = 0.0;
651 let mut evidence_threshold = 0.0;
652 let mut evidence_margin = 0.0;
653
654 if self.frames_since_change < self.config.cooldown_frames {
656 reason = BudgetDecisionReason::CooldownActive;
657 } else if u > self.config.degrade_threshold {
658 pid_gate_threshold = self.config.degrade_threshold;
659 pid_gate_margin = u - pid_gate_threshold;
660 evidence_threshold = 1.0 / self.config.eprocess.alpha;
661 evidence_margin = self.eprocess.e_value - evidence_threshold;
662
663 if self.current_level.is_max() {
664 reason = BudgetDecisionReason::AtMaxDegradation;
665 } else if self.current_level >= self.config.degradation_floor {
666 reason = BudgetDecisionReason::AtDegradationFloor;
667 } else if self.eprocess.should_degrade(&self.config.eprocess) {
668 decision = BudgetDecision::Degrade;
669 reason = BudgetDecisionReason::OverloadEvidencePassed;
670 } else {
671 reason = BudgetDecisionReason::OverloadEvidenceInsufficient;
672 }
673 } else if u < -self.config.upgrade_threshold {
674 pid_gate_threshold = -self.config.upgrade_threshold;
675 pid_gate_margin = (-u) - self.config.upgrade_threshold;
676 evidence_threshold = self.config.eprocess.beta;
677 evidence_margin = evidence_threshold - self.eprocess.e_value;
678
679 if self.current_level.is_full() {
680 reason = BudgetDecisionReason::AtFullQuality;
681 } else if self.eprocess.should_upgrade(&self.config.eprocess) {
682 decision = BudgetDecision::Upgrade;
683 reason = BudgetDecisionReason::UnderloadEvidencePassed;
684 } else {
685 reason = BudgetDecisionReason::UnderloadEvidenceInsufficient;
686 }
687 }
688
689 self.last_decision = decision;
691 self.last_decision_reason = reason;
692 self.last_pid_gate_threshold = pid_gate_threshold;
693 self.last_pid_gate_margin = pid_gate_margin;
694 self.last_evidence_threshold = evidence_threshold;
695 self.last_evidence_margin = evidence_margin;
696
697 match decision {
699 BudgetDecision::Degrade => {
700 self.transition_seq = self.transition_seq.saturating_add(1);
701 self.last_transition_correlation_id =
702 (self.transition_seq << 32) ^ u64::from(self.eprocess.frames_observed);
703 let next = self.current_level.next();
704 self.current_level = if next > self.config.degradation_floor {
706 self.config.degradation_floor
707 } else {
708 next
709 };
710 self.frames_since_change = 0;
711 self.recovery_streak = 0;
712 self.total_degrades = self.total_degrades.saturating_add(1);
713
714 #[cfg(feature = "tracing")]
715 warn!(
716 level = self.current_level.as_str(),
717 pid_output = u,
718 e_value = self.eprocess.e_value,
719 "budget controller: degrade"
720 );
721 }
722 BudgetDecision::Upgrade => {
723 self.transition_seq = self.transition_seq.saturating_add(1);
724 self.last_transition_correlation_id =
725 (self.transition_seq << 32) ^ u64::from(self.eprocess.frames_observed);
726 self.current_level = self.current_level.prev();
727 self.frames_since_change = 0;
728 self.total_recoveries = self.total_recoveries.saturating_add(1);
729
730 #[cfg(feature = "tracing")]
731 trace!(
732 level = self.current_level.as_str(),
733 pid_output = u,
734 e_value = self.eprocess.e_value,
735 "budget controller: upgrade"
736 );
737 }
738 BudgetDecision::Hold => {}
739 }
740
741 decision
742 }
743
744 #[inline]
746 pub fn level(&self) -> DegradationLevel {
747 self.current_level
748 }
749
750 pub fn sync_level(&mut self, level: DegradationLevel) {
761 if self.current_level != level {
762 if level > self.current_level {
763 self.recovery_streak = 0;
764 }
765 self.current_level = level;
766 self.frames_since_change = 0;
767 }
768 }
769
770 #[inline]
772 pub fn recovery_streak(&self) -> u32 {
773 self.recovery_streak
774 }
775
776 #[inline]
778 pub fn total_degrades(&self) -> u64 {
779 self.total_degrades
780 }
781
782 #[inline]
784 pub fn total_recoveries(&self) -> u64 {
785 self.total_recoveries
786 }
787
788 #[inline]
790 pub fn e_value(&self) -> f64 {
791 self.eprocess.e_value
792 }
793
794 #[inline]
796 pub fn eprocess_lambda(&self) -> f64 {
797 self.eprocess.lambda
798 }
799
800 #[inline]
802 pub fn eprocess_sigma_ms(&self) -> f64 {
803 self.eprocess
804 .sigma_ema
805 .max(self.config.eprocess.sigma_floor_ms)
806 }
807
808 #[inline]
810 pub fn pid_integral(&self) -> f64 {
811 self.pid.integral
812 }
813
814 #[inline]
816 pub fn frames_observed(&self) -> u32 {
817 self.eprocess.frames_observed
818 }
819
820 #[inline]
825 pub fn telemetry(&self) -> BudgetTelemetry {
826 BudgetTelemetry {
827 schema_version: BUDGET_TELEMETRY_SCHEMA_VERSION,
828 level: self.current_level,
829 pid_output: self.last_pid_output,
830 pid_p: self.pid.last_p,
831 pid_i: self.pid.last_i,
832 pid_d: self.pid.last_d,
833 e_value: self.eprocess.e_value,
834 eprocess_lambda: self.eprocess.lambda,
835 frames_observed: self.eprocess.frames_observed,
836 frames_since_change: self.frames_since_change,
837 last_decision: self.last_decision,
838 decision_reason: self.last_decision_reason,
839 transition_seq: self.transition_seq,
840 transition_correlation_id: self.last_transition_correlation_id,
841 frame_time_ms: self.last_frame_ms,
842 target_ms: self.config.target.as_secs_f64() * 1000.0,
843 pid_gate_threshold: self.last_pid_gate_threshold,
844 pid_gate_margin: self.last_pid_gate_margin,
845 evidence_threshold: self.last_evidence_threshold,
846 evidence_margin: self.last_evidence_margin,
847 in_warmup: self.eprocess.frames_observed < self.config.eprocess.warmup_frames,
848 recovery_streak: self.recovery_streak,
849 total_degrades: self.total_degrades,
850 total_recoveries: self.total_recoveries,
851 }
852 }
853
854 pub fn reset(&mut self) {
856 self.pid.reset();
857 self.eprocess.reset(&self.config.eprocess);
858 self.current_level = DegradationLevel::Full;
859 self.frames_since_change = 0;
860 self.last_pid_output = 0.0;
861 self.last_decision = BudgetDecision::Hold;
862 self.last_decision_reason = BudgetDecisionReason::WithinThresholdBand;
863 self.last_frame_ms = 0.0;
864 self.transition_seq = 0;
865 self.last_transition_correlation_id = 0;
866 self.last_pid_gate_threshold = 0.0;
867 self.last_pid_gate_margin = 0.0;
868 self.last_evidence_threshold = 0.0;
869 self.last_evidence_margin = 0.0;
870 self.recovery_streak = 0;
871 self.total_degrades = 0;
872 self.total_recoveries = 0;
873 }
874
875 #[inline]
877 #[must_use]
878 pub fn config(&self) -> &BudgetControllerConfig {
879 &self.config
880 }
881}
882
883#[derive(Debug, Clone, Copy, PartialEq)]
888pub struct BudgetTelemetry {
889 pub schema_version: u16,
891 pub level: DegradationLevel,
893 pub pid_output: f64,
895 pub pid_p: f64,
897 pub pid_i: f64,
899 pub pid_d: f64,
901 pub e_value: f64,
903 pub eprocess_lambda: f64,
905 pub frames_observed: u32,
907 pub frames_since_change: u32,
909 pub last_decision: BudgetDecision,
911 pub decision_reason: BudgetDecisionReason,
913 pub transition_seq: u64,
915 pub transition_correlation_id: u64,
917 pub frame_time_ms: f64,
919 pub target_ms: f64,
921 pub pid_gate_threshold: f64,
923 pub pid_gate_margin: f64,
925 pub evidence_threshold: f64,
927 pub evidence_margin: f64,
929 pub in_warmup: bool,
931 pub recovery_streak: u32,
933 pub total_degrades: u64,
935 pub total_recoveries: u64,
937}
938
939#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
944#[repr(u8)]
945pub enum DegradationLevel {
946 #[default]
948 Full = 0,
949 SimpleBorders = 1,
951 NoStyling = 2,
953 EssentialOnly = 3,
955 Skeleton = 4,
957 SkipFrame = 5,
959}
960
961impl DegradationLevel {
962 #[inline]
966 #[must_use]
967 pub fn next(self) -> Self {
968 match self {
969 Self::Full => Self::SimpleBorders,
970 Self::SimpleBorders => Self::NoStyling,
971 Self::NoStyling => Self::EssentialOnly,
972 Self::EssentialOnly => Self::Skeleton,
973 Self::Skeleton | Self::SkipFrame => Self::SkipFrame,
974 }
975 }
976
977 #[inline]
981 #[must_use]
982 pub fn prev(self) -> Self {
983 match self {
984 Self::SkipFrame => Self::Skeleton,
985 Self::Skeleton => Self::EssentialOnly,
986 Self::EssentialOnly => Self::NoStyling,
987 Self::NoStyling => Self::SimpleBorders,
988 Self::SimpleBorders | Self::Full => Self::Full,
989 }
990 }
991
992 #[inline]
994 pub fn is_max(self) -> bool {
995 self == Self::SkipFrame
996 }
997
998 #[inline]
1000 pub fn is_full(self) -> bool {
1001 self == Self::Full
1002 }
1003
1004 #[inline]
1006 pub fn as_str(self) -> &'static str {
1007 match self {
1008 Self::Full => "Full",
1009 Self::SimpleBorders => "SimpleBorders",
1010 Self::NoStyling => "NoStyling",
1011 Self::EssentialOnly => "EssentialOnly",
1012 Self::Skeleton => "Skeleton",
1013 Self::SkipFrame => "SkipFrame",
1014 }
1015 }
1016
1017 #[inline]
1019 pub fn level(self) -> u8 {
1020 self as u8
1021 }
1022
1023 #[inline]
1029 pub fn use_unicode_borders(self) -> bool {
1030 self < Self::SimpleBorders
1031 }
1032
1033 #[inline]
1037 pub fn apply_styling(self) -> bool {
1038 self < Self::NoStyling
1039 }
1040
1041 #[inline]
1046 pub fn render_decorative(self) -> bool {
1047 self < Self::EssentialOnly
1048 }
1049
1050 #[inline]
1054 pub fn render_content(self) -> bool {
1055 self < Self::Skeleton
1056 }
1057
1058 #[inline]
1064 #[must_use]
1065 pub fn allows_widget(self, essential: bool) -> bool {
1066 match self {
1067 Self::Full | Self::SimpleBorders | Self::NoStyling => true,
1068 Self::EssentialOnly | Self::Skeleton => essential,
1069 Self::SkipFrame => false,
1070 }
1071 }
1072}
1073
1074#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1076pub struct PhaseBudgets {
1077 pub diff: Duration,
1079 pub present: Duration,
1081 pub render: Duration,
1083}
1084
1085impl Default for PhaseBudgets {
1086 fn default() -> Self {
1087 Self {
1088 diff: Duration::from_millis(2),
1089 present: Duration::from_millis(4),
1090 render: Duration::from_millis(8),
1091 }
1092 }
1093}
1094
1095#[derive(Debug, Clone, PartialEq)]
1097pub struct FrameBudgetConfig {
1098 pub total: Duration,
1100 pub phase_budgets: PhaseBudgets,
1102 pub allow_frame_skip: bool,
1106 pub degradation_cooldown: u32,
1108 pub upgrade_threshold: f32,
1111}
1112
1113impl Default for FrameBudgetConfig {
1114 fn default() -> Self {
1115 Self {
1116 total: Duration::from_millis(16), phase_budgets: PhaseBudgets::default(),
1118 allow_frame_skip: true,
1119 degradation_cooldown: 3,
1120 upgrade_threshold: 0.5,
1121 }
1122 }
1123}
1124
1125impl FrameBudgetConfig {
1126 pub fn with_total(total: Duration) -> Self {
1128 Self {
1129 total,
1130 ..Default::default()
1131 }
1132 }
1133
1134 pub fn strict(total: Duration) -> Self {
1139 Self {
1140 total,
1141 allow_frame_skip: false,
1142 ..Default::default()
1143 }
1144 }
1145
1146 pub fn relaxed() -> Self {
1148 Self {
1149 total: Duration::from_millis(33), degradation_cooldown: 5,
1151 ..Default::default()
1152 }
1153 }
1154}
1155
1156#[derive(Debug, Clone)]
1161pub struct RenderBudget {
1162 total: Duration,
1164 start: Instant,
1166 last_frame_time: Option<Duration>,
1168 degradation: DegradationLevel,
1170 phase_budgets: PhaseBudgets,
1172 allow_frame_skip: bool,
1174 upgrade_threshold: f32,
1176 frames_since_change: u32,
1178 cooldown: u32,
1180 controller: Option<BudgetController>,
1183}
1184
1185impl RenderBudget {
1186 pub fn new(total: Duration) -> Self {
1188 Self {
1189 total,
1190 start: Instant::now(),
1191 last_frame_time: None,
1192 degradation: DegradationLevel::Full,
1193 phase_budgets: PhaseBudgets::default(),
1194 allow_frame_skip: true,
1195 upgrade_threshold: 0.5,
1196 frames_since_change: 0,
1197 cooldown: 3,
1198 controller: None,
1199 }
1200 }
1201
1202 pub fn from_config(config: &FrameBudgetConfig) -> Self {
1204 Self {
1205 total: config.total,
1206 start: Instant::now(),
1207 last_frame_time: None,
1208 degradation: DegradationLevel::Full,
1209 phase_budgets: config.phase_budgets,
1210 allow_frame_skip: config.allow_frame_skip,
1211 upgrade_threshold: config.upgrade_threshold,
1212 frames_since_change: 0,
1213 cooldown: config.degradation_cooldown,
1214 controller: None,
1215 }
1216 }
1217
1218 #[must_use]
1234 pub fn with_controller(mut self, config: BudgetControllerConfig) -> Self {
1235 self.controller = Some(BudgetController::new(config));
1236 self
1237 }
1238
1239 #[inline]
1241 pub fn total(&self) -> Duration {
1242 self.total
1243 }
1244
1245 #[inline]
1247 pub fn elapsed(&self) -> Duration {
1248 self.start.elapsed()
1249 }
1250
1251 #[inline]
1253 pub fn remaining(&self) -> Duration {
1254 self.total.saturating_sub(self.start.elapsed())
1255 }
1256
1257 #[inline]
1259 pub fn remaining_fraction(&self) -> f32 {
1260 if self.total.is_zero() {
1261 return 0.0;
1262 }
1263 let remaining = self.remaining().as_secs_f32();
1264 let total = self.total.as_secs_f32();
1265 (remaining / total).clamp(0.0, 1.0)
1266 }
1267
1268 #[inline]
1272 pub fn should_degrade(&self, estimated_cost: Duration) -> bool {
1273 self.remaining() < estimated_cost
1274 }
1275
1276 pub fn degrade(&mut self) {
1286 let from = self.degradation;
1287 self.degradation = self.degradation.next();
1288 self.frames_since_change = 0;
1289 self.sync_controller_level();
1290
1291 #[cfg(feature = "tracing")]
1292 if from != self.degradation {
1293 warn!(
1294 from = from.as_str(),
1295 to = self.degradation.as_str(),
1296 remaining_ms = self.remaining().as_millis() as u32,
1297 "render budget degradation"
1298 );
1299 }
1300 let _ = from; }
1302
1303 #[inline]
1306 pub fn degradation_floor(&self) -> DegradationLevel {
1307 self.controller
1308 .as_ref()
1309 .map_or(DegradationLevel::SkipFrame, |ctrl| {
1310 ctrl.config().degradation_floor
1311 })
1312 }
1313
1314 pub fn degrade_respecting_floor(&mut self) -> bool {
1319 let floor = self.degradation_floor();
1320 if self.degradation >= floor {
1321 return false;
1322 }
1323 let from = self.degradation;
1324 self.degrade();
1325 self.degradation > from
1326 }
1327
1328 #[inline]
1330 fn sync_controller_level(&mut self) {
1331 if let Some(controller) = self.controller.as_mut() {
1332 controller.sync_level(self.degradation);
1333 }
1334 }
1335
1336 #[inline]
1338 pub fn degradation(&self) -> DegradationLevel {
1339 self.degradation
1340 }
1341
1342 pub fn set_degradation(&mut self, level: DegradationLevel) {
1348 if self.degradation != level {
1349 self.degradation = level;
1350 self.frames_since_change = 0;
1351 self.sync_controller_level();
1352 }
1353 }
1354
1355 #[inline]
1362 pub fn exhausted(&self) -> bool {
1363 self.remaining().is_zero() || self.should_skip_frame()
1364 }
1365
1366 #[inline]
1374 pub fn should_skip_frame(&self) -> bool {
1375 self.degradation == DegradationLevel::SkipFrame && self.allow_frame_skip
1376 }
1377
1378 pub fn should_upgrade(&self) -> bool {
1383 !self.degradation.is_full()
1384 && self.remaining_fraction() > self.upgrade_threshold
1385 && self.frames_since_change >= self.cooldown
1386 }
1387
1388 fn should_upgrade_with_elapsed(&self, elapsed: Duration) -> bool {
1390 if self.degradation.is_full() || self.frames_since_change < self.cooldown {
1391 return false;
1392 }
1393 self.remaining_fraction_for_elapsed(elapsed) > self.upgrade_threshold
1394 }
1395
1396 fn remaining_fraction_for_elapsed(&self, elapsed: Duration) -> f32 {
1398 if self.total.is_zero() {
1399 return 0.0;
1400 }
1401 let remaining = self.total.saturating_sub(elapsed);
1402 let remaining = remaining.as_secs_f32();
1403 let total = self.total.as_secs_f32();
1404 (remaining / total).clamp(0.0, 1.0)
1405 }
1406
1407 pub fn upgrade(&mut self) {
1411 let from = self.degradation;
1412 self.degradation = self.degradation.prev();
1413 self.frames_since_change = 0;
1414 self.sync_controller_level();
1415
1416 #[cfg(feature = "tracing")]
1417 if from != self.degradation {
1418 trace!(
1419 from = from.as_str(),
1420 to = self.degradation.as_str(),
1421 remaining_fraction = self.remaining_fraction(),
1422 "render budget upgrade"
1423 );
1424 }
1425 let _ = from; }
1427
1428 pub fn reset(&mut self) {
1432 self.start = Instant::now();
1433 self.frames_since_change = self.frames_since_change.saturating_add(1);
1434 }
1435
1436 pub fn next_frame(&mut self) {
1445 let frame_time = self
1452 .last_frame_time
1453 .take()
1454 .unwrap_or_else(|| self.start.elapsed());
1455
1456 if self.controller.is_some() {
1457 let decision = self
1462 .controller
1463 .as_mut()
1464 .expect("controller guaranteed by is_some guard")
1465 .update(frame_time);
1466
1467 match decision {
1468 BudgetDecision::Degrade => self.degrade(),
1469 BudgetDecision::Upgrade => self.upgrade(),
1470 BudgetDecision::Hold => {}
1471 }
1472 } else {
1473 if self.should_upgrade_with_elapsed(frame_time) {
1475 self.upgrade();
1476 }
1477 }
1478 self.reset();
1479 }
1480
1481 pub fn record_frame_time(&mut self, elapsed: Duration) {
1483 self.last_frame_time = Some(elapsed);
1484 }
1485
1486 #[inline]
1491 pub fn telemetry(&self) -> Option<BudgetTelemetry> {
1492 self.controller.as_ref().map(BudgetController::telemetry)
1493 }
1494
1495 #[inline]
1497 pub fn controller(&self) -> Option<&BudgetController> {
1498 self.controller.as_ref()
1499 }
1500
1501 #[inline]
1503 #[must_use]
1504 pub fn phase_budgets(&self) -> &PhaseBudgets {
1505 &self.phase_budgets
1506 }
1507
1508 pub fn phase_has_budget(&self, phase: Phase) -> bool {
1510 let phase_budget = match phase {
1511 Phase::Diff => self.phase_budgets.diff,
1512 Phase::Present => self.phase_budgets.present,
1513 Phase::Render => self.phase_budgets.render,
1514 };
1515 self.remaining() >= phase_budget
1516 }
1517
1518 #[must_use]
1527 pub fn phase_budget(&self, phase: Phase) -> Self {
1528 let phase_total = match phase {
1529 Phase::Diff => self.phase_budgets.diff,
1530 Phase::Present => self.phase_budgets.present,
1531 Phase::Render => self.phase_budgets.render,
1532 };
1533 Self {
1534 total: phase_total.min(self.remaining()),
1535 start: Instant::now(),
1536 last_frame_time: self.last_frame_time,
1537 degradation: self.degradation,
1538 phase_budgets: self.phase_budgets,
1539 allow_frame_skip: self.allow_frame_skip,
1540 upgrade_threshold: self.upgrade_threshold,
1541 frames_since_change: self.frames_since_change,
1542 cooldown: self.cooldown,
1543 controller: None, }
1545 }
1546}
1547
1548#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
1550pub enum Phase {
1551 Diff,
1553 Present,
1555 Render,
1557}
1558
1559impl Phase {
1560 pub fn as_str(self) -> &'static str {
1562 match self {
1563 Self::Diff => "diff",
1564 Self::Present => "present",
1565 Self::Render => "render",
1566 }
1567 }
1568}
1569
1570#[cfg(test)]
1571mod tests {
1572 use super::*;
1573 use std::thread;
1574
1575 #[test]
1576 fn degradation_level_ordering() {
1577 assert!(DegradationLevel::Full < DegradationLevel::SimpleBorders);
1578 assert!(DegradationLevel::SimpleBorders < DegradationLevel::NoStyling);
1579 assert!(DegradationLevel::NoStyling < DegradationLevel::EssentialOnly);
1580 assert!(DegradationLevel::EssentialOnly < DegradationLevel::Skeleton);
1581 assert!(DegradationLevel::Skeleton < DegradationLevel::SkipFrame);
1582 }
1583
1584 #[test]
1585 fn degradation_level_next() {
1586 assert_eq!(
1587 DegradationLevel::Full.next(),
1588 DegradationLevel::SimpleBorders
1589 );
1590 assert_eq!(
1591 DegradationLevel::SimpleBorders.next(),
1592 DegradationLevel::NoStyling
1593 );
1594 assert_eq!(
1595 DegradationLevel::NoStyling.next(),
1596 DegradationLevel::EssentialOnly
1597 );
1598 assert_eq!(
1599 DegradationLevel::EssentialOnly.next(),
1600 DegradationLevel::Skeleton
1601 );
1602 assert_eq!(
1603 DegradationLevel::Skeleton.next(),
1604 DegradationLevel::SkipFrame
1605 );
1606 assert_eq!(
1607 DegradationLevel::SkipFrame.next(),
1608 DegradationLevel::SkipFrame
1609 );
1610 }
1611
1612 #[test]
1613 fn degradation_level_prev() {
1614 assert_eq!(
1615 DegradationLevel::SkipFrame.prev(),
1616 DegradationLevel::Skeleton
1617 );
1618 assert_eq!(
1619 DegradationLevel::Skeleton.prev(),
1620 DegradationLevel::EssentialOnly
1621 );
1622 assert_eq!(
1623 DegradationLevel::EssentialOnly.prev(),
1624 DegradationLevel::NoStyling
1625 );
1626 assert_eq!(
1627 DegradationLevel::NoStyling.prev(),
1628 DegradationLevel::SimpleBorders
1629 );
1630 assert_eq!(
1631 DegradationLevel::SimpleBorders.prev(),
1632 DegradationLevel::Full
1633 );
1634 assert_eq!(DegradationLevel::Full.prev(), DegradationLevel::Full);
1635 }
1636
1637 #[test]
1638 fn degradation_level_is_max() {
1639 assert!(!DegradationLevel::Full.is_max());
1640 assert!(!DegradationLevel::Skeleton.is_max());
1641 assert!(DegradationLevel::SkipFrame.is_max());
1642 }
1643
1644 #[test]
1645 fn degradation_level_is_full() {
1646 assert!(DegradationLevel::Full.is_full());
1647 assert!(!DegradationLevel::SimpleBorders.is_full());
1648 assert!(!DegradationLevel::SkipFrame.is_full());
1649 }
1650
1651 #[test]
1652 fn degradation_level_as_str() {
1653 assert_eq!(DegradationLevel::Full.as_str(), "Full");
1654 assert_eq!(DegradationLevel::SimpleBorders.as_str(), "SimpleBorders");
1655 assert_eq!(DegradationLevel::NoStyling.as_str(), "NoStyling");
1656 assert_eq!(DegradationLevel::EssentialOnly.as_str(), "EssentialOnly");
1657 assert_eq!(DegradationLevel::Skeleton.as_str(), "Skeleton");
1658 assert_eq!(DegradationLevel::SkipFrame.as_str(), "SkipFrame");
1659 }
1660
1661 #[test]
1662 fn degradation_level_values() {
1663 assert_eq!(DegradationLevel::Full.level(), 0);
1664 assert_eq!(DegradationLevel::SimpleBorders.level(), 1);
1665 assert_eq!(DegradationLevel::NoStyling.level(), 2);
1666 assert_eq!(DegradationLevel::EssentialOnly.level(), 3);
1667 assert_eq!(DegradationLevel::Skeleton.level(), 4);
1668 assert_eq!(DegradationLevel::SkipFrame.level(), 5);
1669 }
1670
1671 #[test]
1672 fn degradation_level_allows_widget_matrix() {
1673 assert!(DegradationLevel::Full.allows_widget(true));
1675 assert!(DegradationLevel::Full.allows_widget(false));
1676 assert!(DegradationLevel::SimpleBorders.allows_widget(true));
1677 assert!(DegradationLevel::SimpleBorders.allows_widget(false));
1678 assert!(DegradationLevel::NoStyling.allows_widget(true));
1679 assert!(DegradationLevel::NoStyling.allows_widget(false));
1680
1681 assert!(DegradationLevel::EssentialOnly.allows_widget(true));
1683 assert!(!DegradationLevel::EssentialOnly.allows_widget(false));
1684
1685 assert!(DegradationLevel::Skeleton.allows_widget(true));
1687 assert!(!DegradationLevel::Skeleton.allows_widget(false));
1688
1689 assert!(!DegradationLevel::SkipFrame.allows_widget(true));
1691 assert!(!DegradationLevel::SkipFrame.allows_widget(false));
1692 }
1693
1694 #[test]
1695 fn budget_remaining_decreases() {
1696 let budget = RenderBudget::new(Duration::from_millis(100));
1697 let initial = budget.remaining();
1698
1699 thread::sleep(Duration::from_millis(10));
1700
1701 let later = budget.remaining();
1702 assert!(later < initial);
1703 }
1704
1705 #[test]
1706 fn budget_remaining_fraction() {
1707 let mut budget = RenderBudget::new(Duration::from_millis(100));
1708
1709 let initial = budget.remaining_fraction();
1711 assert!(initial > 0.9);
1712
1713 budget.start = Instant::now() - Duration::from_millis(50);
1718
1719 let later = budget.remaining_fraction();
1721 assert!(
1722 later < 0.6,
1723 "expected remaining_fraction < 0.6, got {later}"
1724 );
1725 assert!(
1726 later > 0.3,
1727 "expected remaining_fraction > 0.3, got {later}"
1728 );
1729 }
1730
1731 #[test]
1732 fn should_degrade_when_cost_exceeds_remaining() {
1733 let mut budget = RenderBudget::new(Duration::from_millis(100));
1736 budget.start = Instant::now() - Duration::from_millis(50);
1737
1738 assert!(budget.should_degrade(Duration::from_millis(80)));
1740 assert!(!budget.should_degrade(Duration::from_millis(10)));
1742 }
1743
1744 #[test]
1745 fn degrade_advances_level() {
1746 let mut budget = RenderBudget::new(Duration::from_millis(16));
1747
1748 assert_eq!(budget.degradation(), DegradationLevel::Full);
1749
1750 budget.degrade();
1751 assert_eq!(budget.degradation(), DegradationLevel::SimpleBorders);
1752
1753 budget.degrade();
1754 assert_eq!(budget.degradation(), DegradationLevel::NoStyling);
1755 }
1756
1757 #[test]
1758 fn exhausted_when_no_time_left() {
1759 let budget = RenderBudget::new(Duration::from_millis(5));
1760
1761 assert!(!budget.exhausted());
1762
1763 thread::sleep(Duration::from_millis(10));
1764
1765 assert!(budget.exhausted());
1766 }
1767
1768 #[test]
1769 fn exhausted_at_skip_frame() {
1770 let mut budget = RenderBudget::new(Duration::from_millis(1000));
1771
1772 budget.set_degradation(DegradationLevel::SkipFrame);
1774
1775 assert!(budget.exhausted());
1777 }
1778
1779 #[test]
1780 fn should_skip_frame_only_at_skip_frame_when_allowed() {
1781 let mut budget = RenderBudget::new(Duration::from_millis(1000));
1782 for level in [
1783 DegradationLevel::Full,
1784 DegradationLevel::SimpleBorders,
1785 DegradationLevel::NoStyling,
1786 DegradationLevel::EssentialOnly,
1787 DegradationLevel::Skeleton,
1788 ] {
1789 budget.set_degradation(level);
1790 assert!(!budget.should_skip_frame(), "{level:?} must not skip");
1791 }
1792 budget.set_degradation(DegradationLevel::SkipFrame);
1793 assert!(budget.should_skip_frame());
1794
1795 budget.allow_frame_skip = false;
1796 assert!(
1797 !budget.should_skip_frame(),
1798 "SkipFrame must not skip when frame skips are disallowed"
1799 );
1800 }
1801
1802 #[test]
1803 fn running_out_of_time_does_not_request_a_frame_skip() {
1804 let budget = RenderBudget::new(Duration::ZERO);
1807 assert!(budget.exhausted(), "no time remains");
1808 assert!(!budget.should_skip_frame());
1809 }
1810
1811 #[test]
1812 fn strict_config_never_requests_a_frame_skip() {
1813 let mut budget =
1814 RenderBudget::from_config(&FrameBudgetConfig::strict(Duration::from_millis(16)));
1815 budget.set_degradation(DegradationLevel::SkipFrame);
1816 assert!(
1817 !budget.should_skip_frame(),
1818 "strict() is documented to never skip frames"
1819 );
1820 }
1821
1822 #[test]
1823 fn should_upgrade_with_remaining_budget() {
1824 let mut budget = RenderBudget::new(Duration::from_millis(1000));
1825
1826 assert!(!budget.should_upgrade());
1828
1829 budget.degrade();
1831 budget.frames_since_change = 5;
1832
1833 assert!(budget.should_upgrade());
1835 }
1836
1837 #[test]
1838 fn upgrade_improves_level() {
1839 let mut budget = RenderBudget::new(Duration::from_millis(16));
1840
1841 budget.set_degradation(DegradationLevel::Skeleton);
1842 assert_eq!(budget.degradation(), DegradationLevel::Skeleton);
1843
1844 budget.upgrade();
1845 assert_eq!(budget.degradation(), DegradationLevel::EssentialOnly);
1846
1847 budget.upgrade();
1848 assert_eq!(budget.degradation(), DegradationLevel::NoStyling);
1849 }
1850
1851 #[test]
1852 fn upgrade_downgrade_symmetric() {
1853 let mut budget = RenderBudget::new(Duration::from_millis(16));
1854
1855 while !budget.degradation().is_max() {
1857 budget.degrade();
1858 }
1859 assert_eq!(budget.degradation(), DegradationLevel::SkipFrame);
1860
1861 while !budget.degradation().is_full() {
1863 budget.upgrade();
1864 }
1865 assert_eq!(budget.degradation(), DegradationLevel::Full);
1866 }
1867
1868 #[test]
1869 fn reset_preserves_degradation() {
1870 let mut budget = RenderBudget::new(Duration::from_millis(16));
1871
1872 budget.degrade();
1873 budget.degrade();
1874 let level = budget.degradation();
1875
1876 budget.reset();
1877
1878 assert_eq!(budget.degradation(), level);
1879 assert!(budget.remaining_fraction() > 0.9);
1881 }
1882
1883 #[test]
1884 fn next_frame_upgrades_when_possible() {
1885 let mut budget = RenderBudget::new(Duration::from_millis(1000));
1886
1887 budget.degrade();
1889 for _ in 0..5 {
1890 budget.reset();
1891 }
1892
1893 let before = budget.degradation();
1894 budget.next_frame();
1895
1896 assert!(budget.degradation() < before);
1898 }
1899
1900 #[test]
1901 fn next_frame_prefers_recorded_frame_time_for_upgrade() {
1902 let mut budget = RenderBudget::new(Duration::from_millis(16));
1903
1904 budget.degrade();
1905 for _ in 0..5 {
1906 budget.reset();
1907 }
1908
1909 budget.record_frame_time(Duration::from_millis(1));
1912 std::thread::sleep(Duration::from_millis(25));
1913
1914 let before = budget.degradation();
1915 budget.next_frame();
1916
1917 assert!(budget.degradation() < before);
1918 }
1919
1920 #[test]
1921 fn config_defaults() {
1922 let config = FrameBudgetConfig::default();
1923
1924 assert_eq!(config.total, Duration::from_millis(16));
1925 assert!(config.allow_frame_skip);
1926 assert_eq!(config.degradation_cooldown, 3);
1927 assert!((config.upgrade_threshold - 0.5).abs() < f32::EPSILON);
1928 }
1929
1930 #[test]
1931 fn config_with_total() {
1932 let config = FrameBudgetConfig::with_total(Duration::from_millis(33));
1933
1934 assert_eq!(config.total, Duration::from_millis(33));
1935 assert!(config.allow_frame_skip);
1937 }
1938
1939 #[test]
1940 fn config_strict() {
1941 let config = FrameBudgetConfig::strict(Duration::from_millis(16));
1942
1943 assert!(!config.allow_frame_skip);
1944 }
1945
1946 #[test]
1947 fn config_relaxed() {
1948 let config = FrameBudgetConfig::relaxed();
1949
1950 assert_eq!(config.total, Duration::from_millis(33));
1951 assert_eq!(config.degradation_cooldown, 5);
1952 }
1953
1954 #[test]
1955 fn from_config() {
1956 let config = FrameBudgetConfig {
1957 total: Duration::from_millis(20),
1958 allow_frame_skip: false,
1959 ..Default::default()
1960 };
1961
1962 let budget = RenderBudget::from_config(&config);
1963
1964 assert_eq!(budget.total(), Duration::from_millis(20));
1965 assert!(!budget.exhausted()); let mut budget = RenderBudget::from_config(&config);
1969 budget.set_degradation(DegradationLevel::SkipFrame);
1970 assert!(!budget.exhausted());
1971 }
1972
1973 #[test]
1974 fn phase_budgets_default() {
1975 let budgets = PhaseBudgets::default();
1976
1977 assert_eq!(budgets.diff, Duration::from_millis(2));
1978 assert_eq!(budgets.present, Duration::from_millis(4));
1979 assert_eq!(budgets.render, Duration::from_millis(8));
1980 }
1981
1982 #[test]
1983 fn phase_has_budget() {
1984 let budget = RenderBudget::new(Duration::from_millis(100));
1985
1986 assert!(budget.phase_has_budget(Phase::Diff));
1987 assert!(budget.phase_has_budget(Phase::Present));
1988 assert!(budget.phase_has_budget(Phase::Render));
1989 }
1990
1991 #[test]
1992 fn phase_budget_respects_remaining() {
1993 let budget = RenderBudget::new(Duration::from_millis(100));
1994
1995 let diff_budget = budget.phase_budget(Phase::Diff);
1996 assert_eq!(diff_budget.total(), Duration::from_millis(2));
1997
1998 let present_budget = budget.phase_budget(Phase::Present);
1999 assert_eq!(present_budget.total(), Duration::from_millis(4));
2000 }
2001
2002 #[test]
2003 fn phase_as_str() {
2004 assert_eq!(Phase::Diff.as_str(), "diff");
2005 assert_eq!(Phase::Present.as_str(), "present");
2006 assert_eq!(Phase::Render.as_str(), "render");
2007 }
2008
2009 #[test]
2010 fn zero_budget_is_immediately_exhausted() {
2011 let budget = RenderBudget::new(Duration::ZERO);
2012 assert!(budget.exhausted());
2013 assert_eq!(budget.remaining_fraction(), 0.0);
2014 }
2015
2016 #[test]
2017 fn degradation_level_never_exceeds_skip_frame() {
2018 let mut level = DegradationLevel::Full;
2019
2020 for _ in 0..100 {
2021 level = level.next();
2022 }
2023
2024 assert_eq!(level, DegradationLevel::SkipFrame);
2025 }
2026
2027 #[test]
2028 fn budget_remaining_never_negative() {
2029 let budget = RenderBudget::new(Duration::from_millis(1));
2030
2031 thread::sleep(Duration::from_millis(10));
2033
2034 assert_eq!(budget.remaining(), Duration::ZERO);
2036 assert_eq!(budget.remaining_fraction(), 0.0);
2037 }
2038
2039 #[test]
2040 fn infinite_budget_stays_at_full() {
2041 let mut budget = RenderBudget::new(Duration::from_secs(1000));
2042
2043 assert!(!budget.should_degrade(Duration::from_millis(100)));
2045 assert_eq!(budget.degradation(), DegradationLevel::Full);
2046
2047 budget.next_frame();
2049 assert_eq!(budget.degradation(), DegradationLevel::Full);
2050 }
2051
2052 #[test]
2053 fn cooldown_prevents_immediate_upgrade() {
2054 let mut budget = RenderBudget::new(Duration::from_millis(1000));
2055 budget.cooldown = 3;
2056
2057 budget.degrade();
2059 assert_eq!(budget.frames_since_change, 0);
2060
2061 assert!(!budget.should_upgrade());
2063
2064 budget.frames_since_change = 3;
2066
2067 assert!(budget.should_upgrade());
2069 }
2070
2071 #[test]
2072 fn set_degradation_resets_cooldown() {
2073 let mut budget = RenderBudget::new(Duration::from_millis(16));
2074 budget.frames_since_change = 10;
2075
2076 budget.set_degradation(DegradationLevel::NoStyling);
2077
2078 assert_eq!(budget.frames_since_change, 0);
2079 }
2080
2081 #[test]
2082 fn set_degradation_same_level_preserves_cooldown() {
2083 let mut budget = RenderBudget::new(Duration::from_millis(16));
2084 budget.frames_since_change = 10;
2085
2086 budget.set_degradation(DegradationLevel::Full);
2088
2089 assert_eq!(budget.frames_since_change, 10);
2091 }
2092
2093 mod controller_tests {
2098 use super::super::*;
2099
2100 fn make_controller() -> BudgetController {
2101 BudgetController::new(BudgetControllerConfig::default())
2102 }
2103
2104 fn make_controller_with_config(
2105 target_ms: u64,
2106 warmup: u32,
2107 cooldown: u32,
2108 ) -> BudgetController {
2109 BudgetController::new(BudgetControllerConfig {
2110 target: Duration::from_millis(target_ms),
2111 eprocess: EProcessConfig {
2112 warmup_frames: warmup,
2113 ..Default::default()
2114 },
2115 cooldown_frames: cooldown,
2116 ..Default::default()
2117 })
2118 }
2119
2120 #[test]
2123 fn pid_step_input_yields_nonzero_output() {
2124 let mut state = PidState::default();
2125 let gains = PidGains::default();
2126
2127 let u = state.update(1.0, &gains);
2129 assert!(
2131 (u - 0.75).abs() < 1e-10,
2132 "First PID output should be 0.75, got {}",
2133 u
2134 );
2135 }
2136
2137 #[test]
2138 fn pid_zero_error_zero_output() {
2139 let mut state = PidState::default();
2140 let gains = PidGains::default();
2141
2142 let u = state.update(0.0, &gains);
2143 assert!(
2144 u.abs() < 1e-10,
2145 "Zero error should produce zero output, got {}",
2146 u
2147 );
2148 }
2149
2150 #[test]
2151 fn pid_integral_accumulates() {
2152 let mut state = PidState::default();
2153 let gains = PidGains::default();
2154
2155 state.update(1.0, &gains);
2157 state.update(1.0, &gains);
2158 state.update(1.0, &gains);
2159
2160 assert!(
2161 state.integral > 2.5,
2162 "Integral should accumulate: {}",
2163 state.integral
2164 );
2165 }
2166
2167 #[test]
2168 fn pid_integral_anti_windup() {
2169 let mut state = PidState::default();
2170 let gains = PidGains {
2171 integral_max: 2.0,
2172 ..Default::default()
2173 };
2174
2175 for _ in 0..100 {
2177 state.update(10.0, &gains);
2178 }
2179
2180 assert!(
2181 state.integral <= 2.0 + f64::EPSILON,
2182 "Integral should be clamped to max: {}",
2183 state.integral
2184 );
2185 assert!(
2186 state.integral >= -2.0 - f64::EPSILON,
2187 "Integral should be clamped to -max: {}",
2188 state.integral
2189 );
2190 }
2191
2192 #[test]
2193 fn pid_derivative_responds_to_change() {
2194 let mut state = PidState::default();
2195 let gains = PidGains::default();
2196
2197 let u1 = state.update(0.0, &gains);
2199 let u2 = state.update(1.0, &gains);
2201
2202 assert!(
2204 u2 > u1,
2205 "Step change should produce larger output: u1={}, u2={}",
2206 u1,
2207 u2
2208 );
2209 }
2210
2211 #[test]
2212 fn pid_settling_after_step() {
2213 let mut state = PidState::default();
2214 let gains = PidGains::default();
2215
2216 state.update(1.0, &gains);
2218 state.update(1.0, &gains);
2219 state.update(1.0, &gains);
2220
2221 let mut outputs = Vec::new();
2223 for _ in 0..20 {
2224 outputs.push(state.update(0.0, &gains));
2225 }
2226
2227 let last = *outputs.last().unwrap();
2229 assert!(
2230 last.abs() < 0.5,
2231 "PID should settle toward zero: last={}",
2232 last
2233 );
2234 }
2235
2236 #[test]
2237 fn pid_reset_clears_state() {
2238 let mut state = PidState::default();
2239 let gains = PidGains::default();
2240
2241 state.update(5.0, &gains);
2242 state.update(5.0, &gains);
2243 assert!(state.integral.abs() > 0.0);
2244
2245 state.reset();
2246 assert_eq!(state.integral, 0.0);
2247 assert_eq!(state.prev_error, 0.0);
2248 }
2249
2250 #[test]
2253 fn eprocess_starts_at_one() {
2254 let state = EProcessState::default();
2255 assert!(
2256 (state.e_value - 1.0).abs() < f64::EPSILON,
2257 "E-process should start at 1.0"
2258 );
2259 }
2260
2261 #[test]
2262 fn eprocess_grows_under_overload() {
2263 let mut state = EProcessState::default();
2264 let config = EProcessConfig {
2265 warmup_frames: 0,
2266 ..Default::default()
2267 };
2268
2269 for _ in 0..20 {
2271 state.update(30.0, 16.0, &config);
2272 }
2273
2274 assert!(
2275 state.e_value > 1.0,
2276 "E-value should grow under overload: {}",
2277 state.e_value
2278 );
2279 }
2280
2281 #[test]
2282 fn eprocess_shrinks_under_underload() {
2283 let mut state = EProcessState::default();
2284 let config = EProcessConfig {
2285 warmup_frames: 0,
2286 ..Default::default()
2287 };
2288
2289 for _ in 0..20 {
2291 state.update(8.0, 16.0, &config);
2292 }
2293
2294 assert!(
2295 state.e_value < 1.0,
2296 "E-value should shrink under underload: {}",
2297 state.e_value
2298 );
2299 }
2300
2301 #[test]
2302 fn eprocess_gate_blocks_during_warmup() {
2303 let mut state = EProcessState::default();
2304 let config = EProcessConfig {
2305 warmup_frames: 10,
2306 ..Default::default()
2307 };
2308
2309 for _ in 0..5 {
2311 state.update(50.0, 16.0, &config);
2312 }
2313
2314 assert!(
2315 !state.should_degrade(&config),
2316 "E-process should not permit degradation during warmup"
2317 );
2318 }
2319
2320 #[test]
2321 fn eprocess_gate_allows_after_warmup() {
2322 let mut state = EProcessState::default();
2323 let config = EProcessConfig {
2324 warmup_frames: 5,
2325 alpha: 0.05,
2326 ..Default::default()
2327 };
2328
2329 for _ in 0..50 {
2331 state.update(80.0, 16.0, &config);
2332 }
2333
2334 assert!(
2335 state.should_degrade(&config),
2336 "E-process should permit degradation after sustained overload: E={}",
2337 state.e_value
2338 );
2339 }
2340
2341 #[test]
2342 fn eprocess_recovery_after_overload() {
2343 let mut state = EProcessState::default();
2344 let config = EProcessConfig {
2345 warmup_frames: 0,
2346 ..Default::default()
2347 };
2348
2349 for _ in 0..30 {
2351 state.update(40.0, 16.0, &config);
2352 }
2353 let peak = state.e_value;
2354
2355 for _ in 0..100 {
2357 state.update(8.0, 16.0, &config);
2358 }
2359
2360 assert!(
2361 state.e_value < peak,
2362 "E-value should decrease after recovery: peak={}, now={}",
2363 peak,
2364 state.e_value
2365 );
2366 }
2367
2368 #[test]
2369 fn eprocess_sigma_floor_prevents_instability() {
2370 let mut state = EProcessState::default();
2371 let config = EProcessConfig {
2372 sigma_floor_ms: 1.0,
2373 warmup_frames: 0,
2374 ..Default::default()
2375 };
2376
2377 for _ in 0..20 {
2379 state.update(16.0, 16.0, &config);
2380 }
2381
2382 assert!(
2384 state.sigma_ema >= 0.0,
2385 "Sigma should be non-negative: {}",
2386 state.sigma_ema
2387 );
2388 assert!(
2390 state.e_value.is_finite(),
2391 "E-value should be finite: {}",
2392 state.e_value
2393 );
2394 }
2395
2396 #[test]
2397 fn eprocess_reset_returns_to_initial() {
2398 let mut state = EProcessState::default();
2399 let config = EProcessConfig::default();
2400
2401 state.update(50.0, 16.0, &config);
2402 state.update(50.0, 16.0, &config);
2403
2404 state.reset(&config);
2405 assert!((state.e_value - 1.0).abs() < f64::EPSILON);
2406 assert_eq!(state.frames_observed, 0);
2407 }
2408
2409 #[test]
2412 fn controller_holds_under_normal_load() {
2413 let mut ctrl = make_controller_with_config(16, 0, 0);
2414
2415 for _ in 0..20 {
2417 let decision = ctrl.update(Duration::from_millis(16));
2418 assert_eq!(
2419 decision,
2420 BudgetDecision::Hold,
2421 "On-target frames should hold"
2422 );
2423 }
2424 assert_eq!(ctrl.level(), DegradationLevel::Full);
2425 }
2426
2427 #[test]
2428 fn controller_degrades_under_sustained_overload() {
2429 let mut ctrl = make_controller_with_config(16, 0, 0);
2430
2431 let mut degraded = false;
2432 for _ in 0..50 {
2434 let decision = ctrl.update(Duration::from_millis(40));
2435 if decision == BudgetDecision::Degrade {
2436 degraded = true;
2437 }
2438 }
2439
2440 assert!(
2441 degraded,
2442 "Controller should degrade under sustained overload"
2443 );
2444 assert!(
2445 ctrl.level() > DegradationLevel::Full,
2446 "Level should be degraded: {:?}",
2447 ctrl.level()
2448 );
2449 }
2450
2451 #[test]
2452 fn controller_upgrades_after_recovery() {
2453 let mut ctrl = make_controller_with_config(16, 0, 0);
2454
2455 for _ in 0..50 {
2457 ctrl.update(Duration::from_millis(40));
2458 }
2459 let degraded_level = ctrl.level();
2460 assert!(degraded_level > DegradationLevel::Full);
2461
2462 let mut upgraded = false;
2464 for _ in 0..200 {
2465 let decision = ctrl.update(Duration::from_millis(4));
2466 if decision == BudgetDecision::Upgrade {
2467 upgraded = true;
2468 }
2469 }
2470
2471 assert!(upgraded, "Controller should upgrade after recovery");
2472 assert!(
2473 ctrl.level() < degraded_level,
2474 "Level should improve: before={:?}, after={:?}",
2475 degraded_level,
2476 ctrl.level()
2477 );
2478 }
2479
2480 #[test]
2481 fn controller_cooldown_prevents_oscillation() {
2482 let mut ctrl = make_controller_with_config(16, 0, 5);
2483
2484 for _ in 0..50 {
2486 ctrl.update(Duration::from_millis(40));
2487 }
2488
2489 let mut decisions_during_cooldown = Vec::new();
2491 for _ in 0..4 {
2492 decisions_during_cooldown.push(ctrl.update(Duration::from_millis(4)));
2493 }
2494
2495 assert!(
2497 decisions_during_cooldown
2498 .iter()
2499 .all(|d| *d == BudgetDecision::Hold),
2500 "Cooldown should prevent changes: {:?}",
2501 decisions_during_cooldown
2502 );
2503 }
2504
2505 #[test]
2506 fn controller_no_oscillation_under_constant_load() {
2507 let mut ctrl = make_controller_with_config(16, 0, 3);
2508
2509 let mut transitions = 0u32;
2511 let mut prev_level = ctrl.level();
2512 for _ in 0..100 {
2513 ctrl.update(Duration::from_millis(20));
2514 if ctrl.level() != prev_level {
2515 transitions += 1;
2516 prev_level = ctrl.level();
2517 }
2518 }
2519
2520 assert!(
2523 transitions < 10,
2524 "Too many transitions under constant load: {}",
2525 transitions
2526 );
2527 }
2528
2529 #[test]
2530 fn controller_reset_restores_full_quality() {
2531 let mut ctrl = make_controller();
2532
2533 for _ in 0..50 {
2535 ctrl.update(Duration::from_millis(40));
2536 }
2537
2538 ctrl.reset();
2539
2540 assert_eq!(ctrl.level(), DegradationLevel::Full);
2541 assert!((ctrl.e_value() - 1.0).abs() < f64::EPSILON);
2542 assert_eq!(ctrl.pid_integral(), 0.0);
2543 }
2544
2545 #[test]
2546 fn controller_transient_spike_does_not_degrade() {
2547 let mut ctrl = make_controller_with_config(16, 5, 3);
2548
2549 for _ in 0..20 {
2551 ctrl.update(Duration::from_millis(16));
2552 }
2553
2554 ctrl.update(Duration::from_millis(100));
2556
2557 for _ in 0..5 {
2559 ctrl.update(Duration::from_millis(16));
2560 }
2561
2562 assert_eq!(
2564 ctrl.level(),
2565 DegradationLevel::Full,
2566 "Single spike should not cause degradation"
2567 );
2568 }
2569
2570 #[test]
2571 fn controller_never_exceeds_skip_frame() {
2572 let mut ctrl = make_controller_with_config(16, 0, 0);
2573
2574 for _ in 0..500 {
2576 ctrl.update(Duration::from_millis(200));
2577 }
2578
2579 assert!(
2580 ctrl.level() <= DegradationLevel::SkipFrame,
2581 "Level should not exceed SkipFrame: {:?}",
2582 ctrl.level()
2583 );
2584 }
2585
2586 #[test]
2587 fn controller_never_goes_below_full() {
2588 let mut ctrl = make_controller_with_config(16, 0, 0);
2589
2590 for _ in 0..200 {
2592 ctrl.update(Duration::from_millis(1));
2593 }
2594
2595 assert_eq!(
2596 ctrl.level(),
2597 DegradationLevel::Full,
2598 "Level should not go below Full"
2599 );
2600 }
2601
2602 #[test]
2605 fn pid_gains_default_valid() {
2606 let gains = PidGains::default();
2607 assert!(gains.kp > 0.0);
2608 assert!(gains.ki > 0.0);
2609 assert!(gains.kd > 0.0);
2610 assert!(gains.integral_max > 0.0);
2611 }
2612
2613 #[test]
2614 fn eprocess_config_default_valid() {
2615 let config = EProcessConfig::default();
2616 assert!(config.lambda > 0.0);
2617 assert!(config.alpha > 0.0 && config.alpha < 1.0);
2618 assert!(config.beta > 0.0 && config.beta < 1.0);
2619 assert!(config.sigma_floor_ms > 0.0);
2620 }
2621
2622 #[test]
2623 fn controller_config_default_valid() {
2624 let config = BudgetControllerConfig::default();
2625 assert!(config.degrade_threshold > 0.0);
2626 assert!(config.upgrade_threshold > 0.0);
2627 assert!(config.target > Duration::ZERO);
2628 }
2629
2630 #[test]
2631 fn budget_decision_equality() {
2632 assert_eq!(BudgetDecision::Hold, BudgetDecision::Hold);
2633 assert_ne!(BudgetDecision::Hold, BudgetDecision::Degrade);
2634 assert_ne!(BudgetDecision::Degrade, BudgetDecision::Upgrade);
2635 }
2636 }
2637
2638 mod integration_tests {
2643 use super::super::*;
2644
2645 #[test]
2646 fn render_budget_without_controller_returns_no_telemetry() {
2647 let budget = RenderBudget::new(Duration::from_millis(16));
2648 assert!(budget.telemetry().is_none());
2649 assert!(budget.controller().is_none());
2650 }
2651
2652 #[test]
2653 fn render_budget_with_controller_returns_telemetry() {
2654 let budget = RenderBudget::new(Duration::from_millis(16))
2655 .with_controller(BudgetControllerConfig::default());
2656 assert!(budget.controller().is_some());
2657
2658 let telem = budget.telemetry().unwrap();
2659 assert_eq!(telem.level, DegradationLevel::Full);
2660 assert_eq!(telem.last_decision, BudgetDecision::Hold);
2661 assert_eq!(telem.frames_observed, 0);
2662 assert!(telem.in_warmup);
2663 }
2664
2665 #[test]
2666 fn telemetry_fields_update_after_next_frame() {
2667 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
2668 BudgetControllerConfig {
2669 eprocess: EProcessConfig {
2670 warmup_frames: 0,
2671 ..Default::default()
2672 },
2673 cooldown_frames: 0,
2674 ..Default::default()
2675 },
2676 );
2677
2678 for _ in 0..5 {
2680 budget.next_frame();
2681 }
2682
2683 let telem = budget.telemetry().unwrap();
2684 assert_eq!(telem.frames_observed, 5);
2685 assert!(!telem.in_warmup);
2686 assert!(telem.pid_output.is_finite());
2689 assert!(telem.e_value.is_finite());
2690 }
2691
2692 #[test]
2693 fn controller_next_frame_degrades_under_simulated_overload() {
2694 let config = BudgetControllerConfig {
2699 target: Duration::from_millis(16),
2700 eprocess: EProcessConfig {
2701 warmup_frames: 0,
2702 ..Default::default()
2703 },
2704 cooldown_frames: 0,
2705 ..Default::default()
2706 };
2707 let mut ctrl = BudgetController::new(config);
2708
2709 for _ in 0..50 {
2711 ctrl.update(Duration::from_millis(40));
2712 }
2713
2714 assert!(
2716 ctrl.level() > DegradationLevel::Full,
2717 "Controller should degrade: {:?}",
2718 ctrl.level()
2719 );
2720
2721 let telem = ctrl.telemetry();
2723 assert!(telem.level > DegradationLevel::Full);
2724 assert!(
2725 telem.pid_output > 0.0,
2726 "PID output should be positive under overload"
2727 );
2728 assert!(telem.e_value > 1.0, "E-value should grow under overload");
2729 }
2730
2731 #[test]
2732 fn next_frame_delegates_to_controller_when_attached() {
2733 let mut budget = RenderBudget::new(Duration::from_millis(1000))
2736 .with_controller(BudgetControllerConfig::default());
2737
2738 budget.degrade();
2740 assert_eq!(budget.degradation(), DegradationLevel::SimpleBorders);
2741
2742 budget.next_frame();
2746
2747 let telem = budget.telemetry().unwrap();
2752 assert_eq!(telem.frames_observed, 1);
2753 }
2754
2755 #[test]
2756 fn telemetry_is_copy_and_no_alloc() {
2757 let budget = RenderBudget::new(Duration::from_millis(16))
2758 .with_controller(BudgetControllerConfig::default());
2759
2760 let telem = budget.telemetry().unwrap();
2761 let telem2 = telem;
2763 assert_eq!(telem.level, telem2.level);
2764 assert_eq!(telem.e_value, telem2.e_value);
2765 }
2766
2767 #[test]
2768 fn telemetry_warmup_flag_transitions() {
2769 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
2770 BudgetControllerConfig {
2771 eprocess: EProcessConfig {
2772 warmup_frames: 3,
2773 ..Default::default()
2774 },
2775 ..Default::default()
2776 },
2777 );
2778
2779 budget.next_frame();
2781 budget.next_frame();
2782 let telem = budget.telemetry().unwrap();
2783 assert!(telem.in_warmup, "Should be in warmup at frame 2");
2784
2785 budget.next_frame();
2787 let telem = budget.telemetry().unwrap();
2788 assert!(!telem.in_warmup, "Should exit warmup at frame 3");
2789 }
2790
2791 #[test]
2792 fn phase_sub_budget_does_not_carry_controller() {
2793 let budget = RenderBudget::new(Duration::from_millis(100))
2794 .with_controller(BudgetControllerConfig::default());
2795
2796 let phase = budget.phase_budget(Phase::Render);
2797 assert!(
2798 phase.controller().is_none(),
2799 "Phase sub-budgets should not carry the controller"
2800 );
2801 }
2802
2803 #[test]
2804 fn controller_telemetry_tracks_frames_since_change() {
2805 let mut ctrl = BudgetController::new(BudgetControllerConfig {
2806 eprocess: EProcessConfig {
2807 warmup_frames: 0,
2808 ..Default::default()
2809 },
2810 cooldown_frames: 0,
2811 ..Default::default()
2812 });
2813
2814 for i in 1..=5 {
2816 ctrl.update(Duration::from_millis(16));
2817 let telem = ctrl.telemetry();
2818 assert_eq!(
2819 telem.frames_since_change, i,
2820 "frames_since_change should be {} after {} frames",
2821 i, i
2822 );
2823 }
2824 }
2825
2826 #[test]
2827 fn telemetry_last_decision_reflects_controller_decision() {
2828 let mut ctrl = BudgetController::new(BudgetControllerConfig {
2829 eprocess: EProcessConfig {
2830 warmup_frames: 0,
2831 ..Default::default()
2832 },
2833 cooldown_frames: 0,
2834 ..Default::default()
2835 });
2836
2837 ctrl.update(Duration::from_millis(16));
2839 assert_eq!(ctrl.telemetry().last_decision, BudgetDecision::Hold);
2840
2841 let mut saw_degrade = false;
2843 for _ in 0..50 {
2844 let d = ctrl.update(Duration::from_millis(50));
2845 if d == BudgetDecision::Degrade {
2846 saw_degrade = true;
2847 assert_eq!(ctrl.telemetry().last_decision, BudgetDecision::Degrade);
2848 break;
2849 }
2850 }
2851 assert!(saw_degrade, "Should have seen a Degrade decision");
2852 }
2853
2854 #[test]
2855 fn perf_overhead_controller_update_is_fast() {
2856 let mut ctrl = BudgetController::new(BudgetControllerConfig::default());
2860
2861 let start = Instant::now();
2862 for _ in 0..10_000 {
2863 ctrl.update(Duration::from_millis(16));
2864 }
2865 let elapsed = start.elapsed();
2866
2867 assert!(
2871 elapsed < Duration::from_millis(50),
2872 "10k controller updates took {:?}, expected <50ms",
2873 elapsed
2874 );
2875 }
2876
2877 #[test]
2878 fn perf_overhead_telemetry_snapshot_is_fast() {
2879 let mut ctrl = BudgetController::new(BudgetControllerConfig::default());
2880 ctrl.update(Duration::from_millis(16));
2881
2882 let start = Instant::now();
2883 for _ in 0..10_000 {
2884 let _telem = ctrl.telemetry();
2885 }
2886 let elapsed = start.elapsed();
2887
2888 assert!(
2889 elapsed < Duration::from_millis(10),
2890 "10k telemetry snapshots took {:?}, expected <10ms",
2891 elapsed
2892 );
2893 }
2894 }
2895
2896 mod stability_tests {
2901 use super::super::*;
2902
2903 #[derive(Debug, Clone)]
2904 struct CampaignFrameLog {
2905 frame_idx: u64,
2906 phase: &'static str,
2907 frame_time_us: u64,
2908 telemetry: BudgetTelemetry,
2909 }
2910
2911 fn fast_controller(target_ms: u64) -> BudgetController {
2913 BudgetController::new(BudgetControllerConfig {
2914 target: Duration::from_millis(target_ms),
2915 eprocess: EProcessConfig {
2916 warmup_frames: 0,
2917 ..Default::default()
2918 },
2919 cooldown_frames: 0,
2920 ..Default::default()
2921 })
2922 }
2923
2924 fn run_trace(
2928 ctrl: &mut BudgetController,
2929 trace: &[Duration],
2930 ) -> Vec<(u64, u64, BudgetTelemetry)> {
2931 trace
2932 .iter()
2933 .enumerate()
2934 .map(|(i, &ft)| {
2935 ctrl.update(ft);
2936 let telem = ctrl.telemetry();
2937 (i as u64, ft.as_micros() as u64, telem)
2938 })
2939 .collect()
2940 }
2941
2942 fn run_campaign(
2944 ctrl: &mut BudgetController,
2945 phases: &[(&'static str, usize, Duration)],
2946 ) -> Vec<CampaignFrameLog> {
2947 let mut logs = Vec::new();
2948 let mut frame_idx: u64 = 0;
2949 for &(phase, count, frame_time) in phases {
2950 for _ in 0..count {
2951 ctrl.update(frame_time);
2952 logs.push(CampaignFrameLog {
2953 frame_idx,
2954 phase,
2955 frame_time_us: frame_time.as_micros() as u64,
2956 telemetry: ctrl.telemetry(),
2957 });
2958 frame_idx = frame_idx.saturating_add(1);
2959 }
2960 }
2961 logs
2962 }
2963
2964 fn count_transitions(log: &[(u64, u64, BudgetTelemetry)]) -> u32 {
2966 let mut transitions = 0u32;
2967 for pair in log.windows(2) {
2968 if pair[0].2.level != pair[1].2.level {
2969 transitions += 1;
2970 }
2971 }
2972 transitions
2973 }
2974
2975 #[test]
2978 fn e2e_burst_logs_no_oscillation() {
2979 let mut ctrl = fast_controller(16);
2982
2983 let mut trace = Vec::new();
2984 for _cycle in 0..5 {
2985 for _ in 0..10 {
2987 trace.push(Duration::from_millis(40));
2988 }
2989 for _ in 0..20 {
2991 trace.push(Duration::from_millis(16));
2992 }
2993 }
2994
2995 let log = run_trace(&mut ctrl, &trace);
2996
2997 let transitions = count_transitions(&log);
3002 assert!(
3003 transitions < 20,
3004 "Too many transitions under bursty load: {} (expected <20)",
3005 transitions
3006 );
3007
3008 for (frame, ft_us, telem) in &log {
3010 assert!(
3011 telem.pid_output.is_finite(),
3012 "frame {}: NaN pid_output",
3013 frame
3014 );
3015 assert!(telem.e_value.is_finite(), "frame {}: NaN e_value", frame);
3016 assert!(telem.pid_p.is_finite(), "frame {}: NaN pid_p", frame);
3017 assert!(telem.pid_i.is_finite(), "frame {}: NaN pid_i", frame);
3018 assert!(telem.pid_d.is_finite(), "frame {}: NaN pid_d", frame);
3019 assert!(*ft_us > 0, "frame {}: zero frame time", frame);
3020 }
3021 }
3022
3023 #[test]
3024 fn e2e_burst_recovers_after_moderate_overload() {
3025 let mut ctrl = BudgetController::new(BudgetControllerConfig {
3029 target: Duration::from_millis(16),
3030 eprocess: EProcessConfig {
3031 warmup_frames: 5,
3032 ..Default::default()
3033 },
3034 cooldown_frames: 3,
3035 ..Default::default()
3036 });
3037
3038 let mut trace = Vec::new();
3039 for _cycle in 0..3 {
3040 for _ in 0..15 {
3042 trace.push(Duration::from_millis(30));
3043 }
3044 for _ in 0..50 {
3046 trace.push(Duration::from_millis(10));
3047 }
3048 }
3049
3050 let log = run_trace(&mut ctrl, &trace);
3051
3052 for cycle in 0..3 {
3055 let calm_end = (cycle + 1) * 65 - 1;
3056 if calm_end < log.len() {
3057 assert!(
3058 log[calm_end].2.level < DegradationLevel::SkipFrame,
3059 "cycle {}: should recover after calm period, got {:?} at frame {}",
3060 cycle,
3061 log[calm_end].2.level,
3062 calm_end
3063 );
3064 }
3065 }
3066
3067 let final_level = log.last().unwrap().2.level;
3069 assert!(
3070 final_level < DegradationLevel::Skeleton,
3071 "Final level should recover below Skeleton: {:?}",
3072 final_level
3073 );
3074 }
3075
3076 #[test]
3079 fn e2e_idle_to_burst_recovery() {
3080 let mut ctrl = fast_controller(16);
3083
3084 let mut trace = Vec::new();
3085 for _ in 0..50 {
3087 trace.push(Duration::from_millis(8));
3088 }
3089 for _ in 0..20 {
3091 trace.push(Duration::from_millis(50));
3092 }
3093 for _ in 0..100 {
3095 trace.push(Duration::from_millis(8));
3096 }
3097
3098 let log = run_trace(&mut ctrl, &trace);
3099
3100 assert_eq!(
3102 log[49].2.level,
3103 DegradationLevel::Full,
3104 "Should be Full during idle phase"
3105 );
3106
3107 let max_during_burst = log[50..70].iter().map(|(_, _, t)| t.level).max().unwrap();
3109 assert!(
3110 max_during_burst > DegradationLevel::Full,
3111 "Should degrade during burst"
3112 );
3113
3114 let final_level = log.last().unwrap().2.level;
3116 assert!(
3117 final_level < max_during_burst,
3118 "Should recover after burst: final={:?}, max_during_burst={:?}",
3119 final_level,
3120 max_during_burst
3121 );
3122 }
3123
3124 #[test]
3125 fn e2e_idle_to_burst_no_over_degrade() {
3126 let mut ctrl = fast_controller(16);
3129
3130 for _ in 0..30 {
3132 ctrl.update(Duration::from_millis(8));
3133 }
3134
3135 for _ in 0..5 {
3137 ctrl.update(Duration::from_millis(40));
3138 }
3139
3140 let level = ctrl.level();
3142 assert!(
3143 level <= DegradationLevel::NoStyling,
3144 "Brief burst should not over-degrade: {:?}",
3145 level
3146 );
3147 }
3148
3149 #[test]
3150 fn e2e_overload_campaign_burst_sustained_recovery_with_replay_logs() {
3151 let phases: [(&str, usize, Duration); 3] = [
3158 ("burst_overload", 24, Duration::from_millis(28)),
3159 ("sustained_overload", 80, Duration::from_millis(52)),
3160 ("recovery_underload", 140, Duration::from_millis(8)),
3161 ];
3162
3163 let mut ctrl = BudgetController::new(BudgetControllerConfig {
3164 target: Duration::from_millis(16),
3165 eprocess: EProcessConfig {
3166 warmup_frames: 0,
3167 ..Default::default()
3168 },
3169 cooldown_frames: 0,
3170 degradation_floor: DegradationLevel::SkipFrame,
3171 ..Default::default()
3172 });
3173 let logs = run_campaign(&mut ctrl, &phases);
3174 assert!(!logs.is_empty(), "campaign logs must be non-empty");
3175
3176 let mut burst_degrades = 0u32;
3177 let mut sustained_degrades = 0u32;
3178 let mut sustained_degraded_frames = 0u32;
3179 let mut recovery_upgrades = 0u32;
3180 let mut max_level = DegradationLevel::Full;
3181
3182 for log in &logs {
3183 let telem = &log.telemetry;
3184 if telem.level > max_level {
3185 max_level = telem.level;
3186 }
3187 if log.phase == "burst_overload" && telem.last_decision == BudgetDecision::Degrade {
3188 burst_degrades = burst_degrades.saturating_add(1);
3189 }
3190 if log.phase == "sustained_overload"
3191 && telem.last_decision == BudgetDecision::Degrade
3192 {
3193 sustained_degrades = sustained_degrades.saturating_add(1);
3194 }
3195 if log.phase == "sustained_overload" && telem.level > DegradationLevel::Full {
3196 sustained_degraded_frames = sustained_degraded_frames.saturating_add(1);
3197 }
3198 if log.phase == "recovery_underload"
3199 && telem.last_decision == BudgetDecision::Upgrade
3200 {
3201 recovery_upgrades = recovery_upgrades.saturating_add(1);
3202 }
3203
3204 assert!(
3206 telem.level <= DegradationLevel::SkipFrame,
3207 "frame {}: invalid degradation level {:?}",
3208 log.frame_idx,
3209 telem.level
3210 );
3211 assert!(
3212 telem.e_value.is_finite() && telem.e_value > 0.0,
3213 "frame {}: invalid e_value {}",
3214 log.frame_idx,
3215 telem.e_value
3216 );
3217 assert!(
3218 telem.pid_output.is_finite(),
3219 "frame {}: invalid pid_output {}",
3220 log.frame_idx,
3221 telem.pid_output
3222 );
3223 }
3224
3225 for pair in logs.windows(2) {
3227 let prev = pair[0].telemetry.level.level();
3228 let curr = pair[1].telemetry.level.level();
3229 let delta = (curr as i16 - prev as i16).unsigned_abs();
3230 assert!(
3231 delta <= 1,
3232 "frame {}->{} level jump {}: {:?} -> {:?}",
3233 pair[0].frame_idx,
3234 pair[1].frame_idx,
3235 delta,
3236 pair[0].telemetry.level,
3237 pair[1].telemetry.level
3238 );
3239 }
3240
3241 assert!(
3242 burst_degrades > 0,
3243 "burst phase should trigger degradation decisions"
3244 );
3245 assert!(
3246 sustained_degrades > 0 || sustained_degraded_frames > 0,
3247 "sustained overload phase should maintain degraded operation"
3248 );
3249 assert!(
3250 max_level >= DegradationLevel::Skeleton,
3251 "sustained overload should reach deep degradation (got {:?})",
3252 max_level
3253 );
3254 assert!(
3255 recovery_upgrades > 0,
3256 "recovery phase should trigger upgrade decisions"
3257 );
3258
3259 let final_level = logs
3260 .last()
3261 .map(|entry| entry.telemetry.level)
3262 .unwrap_or(DegradationLevel::SkipFrame);
3263 assert!(
3264 final_level < max_level,
3265 "final level should recover below peak degradation: final={:?} peak={:?}",
3266 final_level,
3267 max_level
3268 );
3269
3270 let mut ctrl_replay = BudgetController::new(BudgetControllerConfig {
3272 target: Duration::from_millis(16),
3273 eprocess: EProcessConfig {
3274 warmup_frames: 0,
3275 ..Default::default()
3276 },
3277 cooldown_frames: 0,
3278 degradation_floor: DegradationLevel::SkipFrame,
3279 ..Default::default()
3280 });
3281 let replay_logs = run_campaign(&mut ctrl_replay, &phases);
3282 assert_eq!(
3283 logs.len(),
3284 replay_logs.len(),
3285 "log length mismatch in replay"
3286 );
3287 for (lhs, rhs) in logs.iter().zip(replay_logs.iter()) {
3288 assert_eq!(lhs.frame_idx, rhs.frame_idx);
3289 assert_eq!(lhs.phase, rhs.phase);
3290 assert_eq!(lhs.frame_time_us, rhs.frame_time_us);
3291 assert_eq!(lhs.telemetry.schema_version, rhs.telemetry.schema_version);
3292 assert_eq!(lhs.telemetry.level, rhs.telemetry.level);
3293 assert_eq!(lhs.telemetry.last_decision, rhs.telemetry.last_decision);
3294 assert_eq!(
3295 lhs.telemetry.decision_reason, rhs.telemetry.decision_reason,
3296 "decision_reason mismatch at frame {}",
3297 lhs.frame_idx
3298 );
3299 assert_eq!(
3300 lhs.telemetry.transition_seq, rhs.telemetry.transition_seq,
3301 "transition_seq mismatch at frame {}",
3302 lhs.frame_idx
3303 );
3304 assert_eq!(
3305 lhs.telemetry.transition_correlation_id,
3306 rhs.telemetry.transition_correlation_id,
3307 "transition_correlation_id mismatch at frame {}",
3308 lhs.frame_idx
3309 );
3310 assert!(
3311 (lhs.telemetry.pid_output - rhs.telemetry.pid_output).abs() < 1e-12,
3312 "pid_output mismatch at frame {}",
3313 lhs.frame_idx
3314 );
3315 assert!(
3316 (lhs.telemetry.e_value - rhs.telemetry.e_value).abs() < 1e-12,
3317 "e_value mismatch at frame {}",
3318 lhs.frame_idx
3319 );
3320 }
3321
3322 for entry in &logs {
3324 let t = &entry.telemetry;
3325 eprintln!(
3326 r#"{{"event":"control_campaign_frame","schema_version":{},"scenario":"bd-2vr05.15.4.5","frame_idx":{},"phase":"{}","frame_time_us":{},"decision":"{}","decision_reason":"{}","transition_seq":{},"transition_correlation_id":{},"level":"{}","pid_output":{:.6},"pid_p":{:.6},"pid_i":{:.6},"pid_d":{:.6},"e_value":{:.6},"frame_time_ms":{:.6},"target_ms":{:.6},"pid_gate_threshold":{:.6},"pid_gate_margin":{:.6},"evidence_threshold":{:.6},"evidence_margin":{:.6},"frames_observed":{},"frames_since_change":{}}}"#,
3327 t.schema_version,
3328 entry.frame_idx,
3329 entry.phase,
3330 entry.frame_time_us,
3331 t.last_decision.as_str(),
3332 t.decision_reason.as_str(),
3333 t.transition_seq,
3334 t.transition_correlation_id,
3335 t.level.as_str(),
3336 t.pid_output,
3337 t.pid_p,
3338 t.pid_i,
3339 t.pid_d,
3340 t.e_value,
3341 t.frame_time_ms,
3342 t.target_ms,
3343 t.pid_gate_threshold,
3344 t.pid_gate_margin,
3345 t.evidence_threshold,
3346 t.evidence_margin,
3347 t.frames_observed,
3348 t.frames_since_change
3349 );
3350 }
3351 eprintln!(
3352 r#"{{"event":"control_campaign_summary","schema_version":{},"scenario":"bd-2vr05.15.4.5","frames":{},"burst_degrades":{},"sustained_degrades":{},"recovery_upgrades":{},"peak_level":"{}","final_level":"{}"}}"#,
3353 BUDGET_TELEMETRY_SCHEMA_VERSION,
3354 logs.len(),
3355 burst_degrades,
3356 sustained_degrades,
3357 recovery_upgrades,
3358 max_level.as_str(),
3359 final_level.as_str()
3360 );
3361 }
3362
3363 #[test]
3366 fn property_random_load_hysteresis_bounds() {
3367 let mut ctrl = fast_controller(16);
3370
3371 let mut rng_state: u64 = 0xDEAD_BEEF_CAFE_BABE;
3374 let mut trace = Vec::new();
3375 for _ in 0..1000 {
3376 rng_state = rng_state
3378 .wrapping_mul(6_364_136_223_846_793_005)
3379 .wrapping_add(1_442_695_040_888_963_407);
3380 let frame_ms = 4 + ((rng_state >> 33) % 77);
3382 trace.push(Duration::from_millis(frame_ms));
3383 }
3384
3385 let log = run_trace(&mut ctrl, &trace);
3386
3387 for pair in log.windows(2) {
3389 let prev = pair[0].2.level.level();
3390 let curr = pair[1].2.level.level();
3391 let delta = (curr as i16 - prev as i16).unsigned_abs();
3392 assert!(
3393 delta <= 1,
3394 "Level jumped {} steps at frame {}: {:?} -> {:?}",
3395 delta,
3396 pair[1].0,
3397 pair[0].2.level,
3398 pair[1].2.level
3399 );
3400 }
3401
3402 for (frame, _, telem) in &log {
3404 assert!(
3405 telem.level <= DegradationLevel::SkipFrame,
3406 "frame {}: level out of range: {:?}",
3407 frame,
3408 telem.level
3409 );
3410 }
3411
3412 for (frame, _, telem) in &log {
3414 assert!(
3415 telem.pid_output.is_finite(),
3416 "frame {}: NaN pid_output",
3417 frame
3418 );
3419 assert!(telem.pid_p.is_finite(), "frame {}: NaN pid_p", frame);
3420 assert!(telem.pid_i.is_finite(), "frame {}: NaN pid_i", frame);
3421 assert!(telem.pid_d.is_finite(), "frame {}: NaN pid_d", frame);
3422 assert!(telem.e_value.is_finite(), "frame {}: NaN e_value", frame);
3423 assert!(
3424 telem.e_value > 0.0,
3425 "frame {}: e_value not positive: {}",
3426 frame,
3427 telem.e_value
3428 );
3429 }
3430 }
3431
3432 #[test]
3433 fn property_random_load_bounded_transitions() {
3434 let mut ctrl = BudgetController::new(BudgetControllerConfig {
3437 target: Duration::from_millis(16),
3438 eprocess: EProcessConfig {
3439 warmup_frames: 5,
3440 ..Default::default()
3441 },
3442 cooldown_frames: 3,
3443 ..Default::default()
3444 });
3445
3446 let mut rng_state: u64 = 0x1234_5678_9ABC_DEF0;
3448 let mut trace = Vec::new();
3449 for _ in 0..500 {
3450 rng_state = rng_state
3451 .wrapping_mul(6_364_136_223_846_793_005)
3452 .wrapping_add(1_442_695_040_888_963_407);
3453 let frame_ms = 8 + ((rng_state >> 33) % 40);
3454 trace.push(Duration::from_millis(frame_ms));
3455 }
3456
3457 let log = run_trace(&mut ctrl, &trace);
3458 let transitions = count_transitions(&log);
3459
3460 assert!(
3463 transitions < 80,
3464 "Too many transitions under random load: {} (expected <80 with cooldown=3)",
3465 transitions
3466 );
3467 }
3468
3469 #[test]
3470 fn property_deterministic_replay() {
3471 let trace: Vec<Duration> = (0..100)
3473 .map(|i| Duration::from_millis(10 + (i * 7 % 30)))
3474 .collect();
3475
3476 let mut ctrl1 = fast_controller(16);
3477 let log1 = run_trace(&mut ctrl1, &trace);
3478
3479 let mut ctrl2 = fast_controller(16);
3480 let log2 = run_trace(&mut ctrl2, &trace);
3481
3482 for (r1, r2) in log1.iter().zip(log2.iter()) {
3483 assert_eq!(r1.0, r2.0, "frame index mismatch");
3484 assert_eq!(r1.1, r2.1, "frame time mismatch");
3485 assert_eq!(r1.2.schema_version, r2.2.schema_version);
3486 assert_eq!(r1.2.level, r2.2.level, "level mismatch at frame {}", r1.0);
3487 assert_eq!(
3488 r1.2.last_decision, r2.2.last_decision,
3489 "decision mismatch at frame {}",
3490 r1.0
3491 );
3492 assert_eq!(
3493 r1.2.decision_reason, r2.2.decision_reason,
3494 "decision_reason mismatch at frame {}",
3495 r1.0
3496 );
3497 assert_eq!(
3498 r1.2.transition_seq, r2.2.transition_seq,
3499 "transition_seq mismatch at frame {}",
3500 r1.0
3501 );
3502 assert_eq!(
3503 r1.2.transition_correlation_id, r2.2.transition_correlation_id,
3504 "transition_correlation_id mismatch at frame {}",
3505 r1.0
3506 );
3507 assert!(
3508 (r1.2.pid_output - r2.2.pid_output).abs() < 1e-10,
3509 "pid_output mismatch at frame {}: {} vs {}",
3510 r1.0,
3511 r1.2.pid_output,
3512 r2.2.pid_output
3513 );
3514 assert!(
3515 (r1.2.e_value - r2.2.e_value).abs() < 1e-10,
3516 "e_value mismatch at frame {}: {} vs {}",
3517 r1.0,
3518 r1.2.e_value,
3519 r2.2.e_value
3520 );
3521 }
3522 }
3523
3524 #[test]
3527 fn telemetry_jsonl_fields_complete() {
3528 let mut ctrl = fast_controller(16);
3530 ctrl.update(Duration::from_millis(20));
3531
3532 let telem = ctrl.telemetry();
3533
3534 let _schema_version: u16 = telem.schema_version;
3536 let _degradation: &str = telem.level.as_str();
3537 let _pid_p: f64 = telem.pid_p;
3538 let _pid_i: f64 = telem.pid_i;
3539 let _pid_d: f64 = telem.pid_d;
3540 let _e_value: f64 = telem.e_value;
3541 let _decision: &str = telem.last_decision.as_str();
3542 let _reason: &str = telem.decision_reason.as_str();
3543 let _transition_seq: u64 = telem.transition_seq;
3544 let _transition_correlation_id: u64 = telem.transition_correlation_id;
3545 let _frame_time_ms: f64 = telem.frame_time_ms;
3546 let _target_ms: f64 = telem.target_ms;
3547 let _pid_gate_threshold: f64 = telem.pid_gate_threshold;
3548 let _pid_gate_margin: f64 = telem.pid_gate_margin;
3549 let _evidence_threshold: f64 = telem.evidence_threshold;
3550 let _evidence_margin: f64 = telem.evidence_margin;
3551 let _frames: u32 = telem.frames_observed;
3552
3553 assert_eq!(BudgetDecision::Hold.as_str(), "stay");
3555 assert_eq!(BudgetDecision::Degrade.as_str(), "degrade");
3556 assert_eq!(BudgetDecision::Upgrade.as_str(), "upgrade");
3557 assert_eq!(
3558 BUDGET_TELEMETRY_SCHEMA_VERSION, telem.schema_version,
3559 "schema version mismatch"
3560 );
3561 }
3562
3563 #[test]
3564 fn telemetry_transition_records_correlation_reason_and_evidence() {
3565 let mut ctrl = fast_controller(16);
3566
3567 let mut degrade_telem = None;
3569 for _ in 0..64 {
3570 ctrl.update(Duration::from_millis(48));
3571 let telem = ctrl.telemetry();
3572 if telem.last_decision == BudgetDecision::Degrade {
3573 degrade_telem = Some(telem);
3574 break;
3575 }
3576 }
3577 let degrade_telem =
3578 degrade_telem.expect("expected degrade transition with correlation metadata");
3579 assert_eq!(
3580 degrade_telem.decision_reason,
3581 BudgetDecisionReason::OverloadEvidencePassed
3582 );
3583 assert!(
3584 degrade_telem.transition_seq > 0,
3585 "transition_seq should increment on transitions"
3586 );
3587 assert!(
3588 degrade_telem.transition_correlation_id > 0,
3589 "transition correlation id should be populated on transitions"
3590 );
3591 assert!(
3592 degrade_telem.pid_gate_margin > 0.0,
3593 "degrade transition should have positive PID gate margin"
3594 );
3595 assert!(
3596 degrade_telem.evidence_margin > 0.0,
3597 "degrade transition should have positive evidence margin"
3598 );
3599
3600 let mut upgrade_telem = None;
3602 for _ in 0..160 {
3603 ctrl.update(Duration::from_millis(4));
3604 let telem = ctrl.telemetry();
3605 if telem.last_decision == BudgetDecision::Upgrade {
3606 upgrade_telem = Some(telem);
3607 break;
3608 }
3609 }
3610 let upgrade_telem =
3611 upgrade_telem.expect("expected upgrade transition with correlation metadata");
3612 assert_eq!(
3613 upgrade_telem.decision_reason,
3614 BudgetDecisionReason::UnderloadEvidencePassed
3615 );
3616 assert!(
3617 upgrade_telem.transition_seq >= degrade_telem.transition_seq,
3618 "transition sequence should be monotonic"
3619 );
3620 assert!(
3621 upgrade_telem.transition_correlation_id >= degrade_telem.transition_correlation_id,
3622 "transition correlation id should be monotonic"
3623 );
3624 assert!(
3625 upgrade_telem.pid_gate_margin > 0.0,
3626 "upgrade transition should have positive PID gate margin"
3627 );
3628 assert!(
3629 upgrade_telem.evidence_margin > 0.0,
3630 "upgrade transition should have positive evidence margin"
3631 );
3632 }
3633
3634 #[test]
3635 fn telemetry_pid_components_sum_to_output() {
3636 let mut ctrl = fast_controller(16);
3638
3639 for ms in [10u64, 16, 20, 30, 8, 50] {
3640 ctrl.update(Duration::from_millis(ms));
3641 let telem = ctrl.telemetry();
3642 let sum = telem.pid_p + telem.pid_i + telem.pid_d;
3643 assert!(
3644 (sum - telem.pid_output).abs() < 1e-10,
3645 "P+I+D != output at {}ms: {} + {} + {} = {} != {}",
3646 ms,
3647 telem.pid_p,
3648 telem.pid_i,
3649 telem.pid_d,
3650 sum,
3651 telem.pid_output
3652 );
3653 }
3654 }
3655 }
3656
3657 mod edge_case_tests {
3662 use super::super::*;
3663
3664 #[test]
3667 fn pid_negative_integral_windup() {
3668 let mut state = PidState::default();
3670 let gains = PidGains {
3671 integral_max: 3.0,
3672 ..Default::default()
3673 };
3674
3675 for _ in 0..200 {
3676 state.update(-10.0, &gains);
3677 }
3678
3679 assert!(
3680 state.integral >= -3.0 - f64::EPSILON,
3681 "Negative integral should be clamped to -max: {}",
3682 state.integral
3683 );
3684 assert!(
3685 state.integral <= -3.0 + f64::EPSILON,
3686 "Negative integral should saturate at -max: {}",
3687 state.integral
3688 );
3689 }
3690
3691 #[test]
3692 fn pid_zero_gains_zero_output() {
3693 let mut state = PidState::default();
3694 let gains = PidGains {
3695 kp: 0.0,
3696 ki: 0.0,
3697 kd: 0.0,
3698 integral_max: 5.0,
3699 };
3700
3701 let u = state.update(42.0, &gains);
3702 assert!(
3703 u.abs() < 1e-10,
3704 "Zero gains should yield zero output: {}",
3705 u
3706 );
3707 }
3708
3709 #[test]
3710 fn pid_large_error_stays_finite() {
3711 let mut state = PidState::default();
3712 let gains = PidGains::default();
3713
3714 let u = state.update(1e12, &gains);
3716 assert!(
3717 u.is_finite(),
3718 "PID output should be finite for large error: {}",
3719 u
3720 );
3721
3722 assert!(
3724 state.integral <= gains.integral_max + f64::EPSILON,
3725 "Integral should be clamped: {}",
3726 state.integral
3727 );
3728 }
3729
3730 #[test]
3731 fn pid_alternating_error_derivative_responds() {
3732 let mut state = PidState::default();
3733 let gains = PidGains::default();
3734
3735 let u1 = state.update(1.0, &gains);
3737 let u2 = state.update(-1.0, &gains);
3738
3739 assert!(
3742 u2 < u1,
3743 "Alternating error should reduce output: u1={}, u2={}",
3744 u1,
3745 u2
3746 );
3747 }
3748
3749 #[test]
3750 fn pid_telemetry_terms_match_after_update() {
3751 let mut state = PidState::default();
3752 let gains = PidGains::default();
3753
3754 state.update(2.0, &gains);
3755
3756 assert!(
3758 (state.last_p - 1.0).abs() < 1e-10,
3759 "P term: {}",
3760 state.last_p
3761 );
3762 assert!(
3764 (state.last_i - 0.1).abs() < 1e-10,
3765 "I term: {}",
3766 state.last_i
3767 );
3768 assert!(
3770 (state.last_d - 0.4).abs() < 1e-10,
3771 "D term: {}",
3772 state.last_d
3773 );
3774 }
3775
3776 #[test]
3777 fn pid_integral_clamping_symmetric() {
3778 let mut state = PidState::default();
3779 let gains = PidGains {
3780 integral_max: 1.0,
3781 ..Default::default()
3782 };
3783
3784 for _ in 0..50 {
3786 state.update(100.0, &gains);
3787 }
3788 let pos_integral = state.integral;
3789
3790 state.reset();
3791
3792 for _ in 0..50 {
3794 state.update(-100.0, &gains);
3795 }
3796 let neg_integral = state.integral;
3797
3798 assert!(
3799 (pos_integral + neg_integral).abs() < f64::EPSILON,
3800 "Clamping should be symmetric: pos={}, neg={}",
3801 pos_integral,
3802 neg_integral
3803 );
3804 }
3805
3806 #[test]
3809 fn eprocess_first_frame_initializes_mean() {
3810 let mut state = EProcessState::default();
3811 let config = EProcessConfig::default();
3812
3813 state.update(25.0, 16.0, &config);
3814
3815 assert!(
3816 (state.mean_ema - 25.0).abs() < f64::EPSILON,
3817 "First frame should set mean_ema directly: {}",
3818 state.mean_ema
3819 );
3820 assert!(
3821 (state.sigma_ema - config.sigma_floor_ms).abs() < f64::EPSILON,
3822 "First frame should set sigma_ema to floor: {}",
3823 state.sigma_ema
3824 );
3825 assert_eq!(state.frames_observed, 1);
3826 }
3827
3828 #[test]
3829 fn eprocess_e_value_clamped_at_upper_bound() {
3830 let mut state = EProcessState::default();
3831 let config = EProcessConfig {
3832 lambda: 2.0, warmup_frames: 0,
3834 sigma_floor_ms: 0.001, ..Default::default()
3836 };
3837
3838 for _ in 0..1000 {
3840 state.update(1e6, 16.0, &config);
3841 }
3842
3843 assert!(
3844 state.e_value <= 1e10,
3845 "E-value should be clamped at 1e10: {}",
3846 state.e_value
3847 );
3848 }
3849
3850 #[test]
3851 fn eprocess_e_value_clamped_at_lower_bound() {
3852 let mut state = EProcessState::default();
3853 let config = EProcessConfig {
3854 lambda: 2.0,
3855 warmup_frames: 0,
3856 sigma_floor_ms: 0.001,
3857 ..Default::default()
3858 };
3859
3860 for _ in 0..1000 {
3862 state.update(0.001, 1e6, &config);
3863 }
3864
3865 assert!(
3866 state.e_value >= 1e-10,
3867 "E-value should be clamped at 1e-10: {}",
3868 state.e_value
3869 );
3870 }
3871
3872 #[test]
3873 fn eprocess_should_upgrade_during_warmup() {
3874 let state = EProcessState::default();
3875 let config = EProcessConfig {
3876 warmup_frames: 10,
3877 ..Default::default()
3878 };
3879
3880 assert!(
3882 state.should_upgrade(&config),
3883 "should_upgrade should return true during warmup"
3884 );
3885 }
3886
3887 #[test]
3888 fn eprocess_frames_observed_saturates() {
3889 let mut state = EProcessState {
3890 frames_observed: u32::MAX,
3891 ..EProcessState::default()
3892 };
3893 let config = EProcessConfig::default();
3894
3895 state.update(16.0, 16.0, &config);
3897 assert_eq!(
3898 state.frames_observed,
3899 u32::MAX,
3900 "frames_observed should saturate at u32::MAX"
3901 );
3902 }
3903
3904 #[test]
3905 fn eprocess_sigma_ema_decay_boundary_zero() {
3906 let mut state = EProcessState::default();
3907 let config = EProcessConfig {
3908 sigma_ema_decay: 0.0,
3909 warmup_frames: 0,
3910 ..Default::default()
3911 };
3912
3913 state.update(20.0, 16.0, &config);
3915 state.update(30.0, 16.0, &config);
3916
3917 assert!(
3919 (state.mean_ema - 30.0).abs() < f64::EPSILON,
3920 "decay=0 should fully replace mean_ema: {}",
3921 state.mean_ema
3922 );
3923 }
3924
3925 #[test]
3926 fn eprocess_sigma_ema_decay_boundary_one() {
3927 let mut state = EProcessState::default();
3928 let config = EProcessConfig {
3929 sigma_ema_decay: 1.0,
3930 warmup_frames: 0,
3931 ..Default::default()
3932 };
3933
3934 state.update(20.0, 16.0, &config);
3936 let first_mean = state.mean_ema;
3937 state.update(100.0, 16.0, &config);
3938
3939 assert!(
3940 (state.mean_ema - first_mean).abs() < f64::EPSILON,
3941 "decay=1 should lock mean_ema at first value: got {}, expected {}",
3942 state.mean_ema,
3943 first_mean
3944 );
3945 }
3946
3947 #[test]
3948 fn eprocess_zero_target_no_panic() {
3949 let mut state = EProcessState::default();
3950 let config = EProcessConfig {
3951 warmup_frames: 0,
3952 ..Default::default()
3953 };
3954
3955 let e = state.update(16.0, 0.0, &config);
3957 assert!(
3958 e.is_finite(),
3959 "E-value should be finite with zero target: {}",
3960 e
3961 );
3962 }
3963
3964 #[test]
3967 fn degradation_level_default_is_full() {
3968 assert_eq!(DegradationLevel::default(), DegradationLevel::Full);
3969 }
3970
3971 #[test]
3972 fn degradation_level_hash_unique() {
3973 use std::collections::HashSet;
3974 let levels = [
3975 DegradationLevel::Full,
3976 DegradationLevel::SimpleBorders,
3977 DegradationLevel::NoStyling,
3978 DegradationLevel::EssentialOnly,
3979 DegradationLevel::Skeleton,
3980 DegradationLevel::SkipFrame,
3981 ];
3982 let set: HashSet<DegradationLevel> = levels.iter().copied().collect();
3983 assert_eq!(set.len(), 6, "All levels should hash uniquely");
3984 }
3985
3986 #[test]
3987 fn degradation_level_widget_queries_full() {
3988 let l = DegradationLevel::Full;
3989 assert!(l.use_unicode_borders());
3990 assert!(l.apply_styling());
3991 assert!(l.render_decorative());
3992 assert!(l.render_content());
3993 }
3994
3995 #[test]
3996 fn degradation_level_widget_queries_simple_borders() {
3997 let l = DegradationLevel::SimpleBorders;
3998 assert!(!l.use_unicode_borders());
3999 assert!(l.apply_styling());
4000 assert!(l.render_decorative());
4001 assert!(l.render_content());
4002 }
4003
4004 #[test]
4005 fn degradation_level_widget_queries_no_styling() {
4006 let l = DegradationLevel::NoStyling;
4007 assert!(!l.use_unicode_borders());
4008 assert!(!l.apply_styling());
4009 assert!(l.render_decorative());
4010 assert!(l.render_content());
4011 }
4012
4013 #[test]
4014 fn degradation_level_widget_queries_essential_only() {
4015 let l = DegradationLevel::EssentialOnly;
4016 assert!(!l.use_unicode_borders());
4017 assert!(!l.apply_styling());
4018 assert!(!l.render_decorative());
4019 assert!(l.render_content());
4020 }
4021
4022 #[test]
4023 fn degradation_level_widget_queries_skeleton() {
4024 let l = DegradationLevel::Skeleton;
4025 assert!(!l.use_unicode_borders());
4026 assert!(!l.apply_styling());
4027 assert!(!l.render_decorative());
4028 assert!(!l.render_content());
4029 }
4030
4031 #[test]
4032 fn degradation_level_widget_queries_skip_frame() {
4033 let l = DegradationLevel::SkipFrame;
4034 assert!(!l.use_unicode_borders());
4035 assert!(!l.apply_styling());
4036 assert!(!l.render_decorative());
4037 assert!(!l.render_content());
4038 }
4039
4040 #[test]
4041 fn degradation_level_partial_ord_consistent() {
4042 let levels = [
4044 DegradationLevel::Full,
4045 DegradationLevel::SimpleBorders,
4046 DegradationLevel::NoStyling,
4047 DegradationLevel::EssentialOnly,
4048 DegradationLevel::Skeleton,
4049 DegradationLevel::SkipFrame,
4050 ];
4051 for (i, a) in levels.iter().enumerate() {
4052 for (j, b) in levels.iter().enumerate() {
4053 let po = a.partial_cmp(b);
4054 let o = a.cmp(b);
4055 assert_eq!(po, Some(o), "PartialOrd != Ord for {:?} vs {:?}", a, b);
4056 if i < j {
4057 assert!(*a < *b, "{:?} should be < {:?}", a, b);
4058 }
4059 }
4060 }
4061 }
4062
4063 #[test]
4064 fn degradation_level_clone_eq() {
4065 let a = DegradationLevel::NoStyling;
4066 let b = a;
4067 assert_eq!(a, b);
4068 }
4069
4070 #[test]
4071 fn degradation_level_debug() {
4072 let s = format!("{:?}", DegradationLevel::EssentialOnly);
4073 assert!(s.contains("EssentialOnly"), "Debug output: {}", s);
4074 }
4075
4076 #[test]
4079 fn controller_eprocess_sigma_ms_uses_floor() {
4080 let ctrl = BudgetController::new(BudgetControllerConfig {
4081 eprocess: EProcessConfig {
4082 sigma_floor_ms: 2.5,
4083 ..Default::default()
4084 },
4085 ..Default::default()
4086 });
4087
4088 assert!(
4090 (ctrl.eprocess_sigma_ms() - 2.5).abs() < f64::EPSILON,
4091 "Should return sigma_floor_ms when sigma_ema < floor: {}",
4092 ctrl.eprocess_sigma_ms()
4093 );
4094 }
4095
4096 #[test]
4097 fn controller_config_accessor() {
4098 let config = BudgetControllerConfig {
4099 degrade_threshold: 0.42,
4100 ..Default::default()
4101 };
4102 let ctrl = BudgetController::new(config.clone());
4103
4104 assert_eq!(ctrl.config().degrade_threshold, 0.42);
4105 assert_eq!(ctrl.config().target, Duration::from_millis(16));
4106 }
4107
4108 #[test]
4109 fn controller_frames_observed_accessor() {
4110 let mut ctrl = BudgetController::new(BudgetControllerConfig::default());
4111
4112 assert_eq!(ctrl.frames_observed(), 0);
4113
4114 ctrl.update(Duration::from_millis(16));
4115 assert_eq!(ctrl.frames_observed(), 1);
4116
4117 ctrl.update(Duration::from_millis(16));
4118 assert_eq!(ctrl.frames_observed(), 2);
4119 }
4120
4121 #[test]
4124 fn render_budget_record_frame_time_used_by_next_frame() {
4125 let mut budget = RenderBudget::new(Duration::from_millis(1000));
4126 budget.degrade();
4127
4128 for _ in 0..10 {
4130 budget.reset();
4131 }
4132
4133 budget.record_frame_time(Duration::from_millis(1));
4135 std::thread::sleep(Duration::from_millis(15));
4137
4138 let before = budget.degradation();
4139 budget.next_frame();
4140
4141 assert!(
4144 budget.degradation() < before,
4145 "Recorded frame time should enable upgrade: before={:?}, after={:?}",
4146 before,
4147 budget.degradation()
4148 );
4149 }
4150
4151 #[test]
4152 fn render_budget_phase_budget_clamped_by_remaining() {
4153 let budget = RenderBudget::new(Duration::from_millis(1));
4155 std::thread::sleep(Duration::from_millis(5));
4156
4157 let phase = budget.phase_budget(Phase::Render);
4159 assert!(
4160 phase.total() <= Duration::from_millis(1),
4161 "Phase budget should be clamped by remaining: {:?}",
4162 phase.total()
4163 );
4164 }
4165
4166 #[test]
4167 fn render_budget_exhausted_skipframe_with_no_frame_skip() {
4168 let mut budget = RenderBudget::new(Duration::from_millis(1000));
4169 budget.allow_frame_skip = false;
4170 budget.set_degradation(DegradationLevel::SkipFrame);
4171
4172 assert!(
4175 !budget.exhausted(),
4176 "SkipFrame should not exhaust when frame skip disabled"
4177 );
4178 }
4179
4180 #[test]
4181 fn render_budget_remaining_fraction_zero_total() {
4182 let budget = RenderBudget::new(Duration::ZERO);
4183 assert_eq!(budget.remaining_fraction(), 0.0);
4184 }
4185
4186 #[test]
4187 fn render_budget_total_accessor() {
4188 let budget = RenderBudget::new(Duration::from_millis(42));
4189 assert_eq!(budget.total(), Duration::from_millis(42));
4190 }
4191
4192 #[test]
4193 fn render_budget_phase_budgets_accessor() {
4194 let budget = RenderBudget::new(Duration::from_millis(16));
4195 let pb = budget.phase_budgets();
4196 assert_eq!(pb.diff, Duration::from_millis(2));
4197 assert_eq!(pb.present, Duration::from_millis(4));
4198 assert_eq!(pb.render, Duration::from_millis(8));
4199 }
4200
4201 #[test]
4202 fn render_budget_set_degradation_no_op_preserves_cooldown() {
4203 let mut budget = RenderBudget::new(Duration::from_millis(16));
4204 budget.set_degradation(DegradationLevel::NoStyling);
4205 budget.frames_since_change = 7;
4206
4207 budget.set_degradation(DegradationLevel::NoStyling);
4209 assert_eq!(budget.frames_since_change, 7);
4210
4211 budget.set_degradation(DegradationLevel::Skeleton);
4213 assert_eq!(budget.frames_since_change, 0);
4214 }
4215
4216 #[test]
4217 fn render_budget_should_upgrade_false_at_full() {
4218 let budget = RenderBudget::new(Duration::from_millis(1000));
4219 assert!(!budget.should_upgrade(), "Full level should never upgrade");
4220 }
4221
4222 #[test]
4223 fn render_budget_should_upgrade_false_during_cooldown() {
4224 let mut budget = RenderBudget::new(Duration::from_millis(1000));
4225 budget.degrade();
4226 assert!(
4228 !budget.should_upgrade(),
4229 "Should not upgrade during cooldown"
4230 );
4231 }
4232
4233 #[test]
4234 fn render_budget_degrade_at_max_stays_at_max() {
4235 let mut budget = RenderBudget::new(Duration::from_millis(16));
4236 budget.set_degradation(DegradationLevel::SkipFrame);
4237 budget.degrade();
4238 assert_eq!(budget.degradation(), DegradationLevel::SkipFrame);
4239 }
4240
4241 #[test]
4242 fn render_budget_upgrade_at_full_stays_at_full() {
4243 let mut budget = RenderBudget::new(Duration::from_millis(16));
4244 budget.upgrade();
4245 assert_eq!(budget.degradation(), DegradationLevel::Full);
4246 }
4247
4248 #[test]
4251 fn frame_budget_config_partial_eq() {
4252 let a = FrameBudgetConfig::default();
4253 let b = FrameBudgetConfig::default();
4254 assert_eq!(a, b);
4255
4256 let c = FrameBudgetConfig::strict(Duration::from_millis(16));
4257 assert_ne!(a, c, "Different configs should not be equal");
4258 }
4259
4260 #[test]
4261 fn phase_budgets_eq_and_copy() {
4262 let a = PhaseBudgets::default();
4263 let b = a; assert_eq!(a, b);
4265
4266 let c = PhaseBudgets {
4267 diff: Duration::from_millis(1),
4268 ..Default::default()
4269 };
4270 assert_ne!(a, c);
4271 }
4272
4273 #[test]
4274 fn budget_controller_config_partial_eq() {
4275 let a = BudgetControllerConfig::default();
4276 let b = BudgetControllerConfig::default();
4277 assert_eq!(a, b);
4278 }
4279
4280 #[test]
4281 fn pid_gains_partial_eq() {
4282 let a = PidGains::default();
4283 let b = PidGains::default();
4284 assert_eq!(a, b);
4285 }
4286
4287 #[test]
4288 fn eprocess_config_partial_eq() {
4289 let a = EProcessConfig::default();
4290 let b = EProcessConfig::default();
4291 assert_eq!(a, b);
4292 }
4293
4294 #[test]
4297 fn budget_decision_debug_format() {
4298 assert!(format!("{:?}", BudgetDecision::Hold).contains("Hold"));
4299 assert!(format!("{:?}", BudgetDecision::Degrade).contains("Degrade"));
4300 assert!(format!("{:?}", BudgetDecision::Upgrade).contains("Upgrade"));
4301 }
4302
4303 #[test]
4304 fn budget_decision_clone_copy() {
4305 let d = BudgetDecision::Degrade;
4306 let d2 = d;
4307 assert_eq!(d, d2);
4308 }
4309
4310 #[test]
4311 fn budget_decision_as_str_coverage() {
4312 assert_eq!(BudgetDecision::Hold.as_str(), "stay");
4313 assert_eq!(BudgetDecision::Degrade.as_str(), "degrade");
4314 assert_eq!(BudgetDecision::Upgrade.as_str(), "upgrade");
4315 }
4316
4317 #[test]
4318 fn budget_decision_reason_debug_and_as_str() {
4319 assert!(
4320 format!("{:?}", BudgetDecisionReason::CooldownActive).contains("CooldownActive")
4321 );
4322 assert_eq!(
4323 BudgetDecisionReason::CooldownActive.as_str(),
4324 "cooldown_active"
4325 );
4326 assert_eq!(
4327 BudgetDecisionReason::OverloadEvidencePassed.as_str(),
4328 "overload_evidence_passed"
4329 );
4330 assert_eq!(
4331 BudgetDecisionReason::UnderloadEvidencePassed.as_str(),
4332 "underload_evidence_passed"
4333 );
4334 assert_eq!(
4335 BudgetDecisionReason::AtMaxDegradation.as_str(),
4336 "at_max_degradation"
4337 );
4338 assert_eq!(
4339 BudgetDecisionReason::AtDegradationFloor.as_str(),
4340 "at_degradation_floor"
4341 );
4342 assert_eq!(
4343 BudgetDecisionReason::AtFullQuality.as_str(),
4344 "at_full_quality"
4345 );
4346 assert_eq!(
4347 BudgetDecisionReason::WithinThresholdBand.as_str(),
4348 "within_threshold_band"
4349 );
4350 }
4351
4352 #[test]
4355 fn phase_eq_and_hash() {
4356 use std::collections::HashSet;
4357 let mut set = HashSet::new();
4358 set.insert(Phase::Diff);
4359 set.insert(Phase::Present);
4360 set.insert(Phase::Render);
4361 assert_eq!(set.len(), 3);
4362
4363 set.insert(Phase::Diff);
4365 assert_eq!(set.len(), 3);
4366 }
4367
4368 #[test]
4369 fn phase_debug() {
4370 assert!(format!("{:?}", Phase::Diff).contains("Diff"));
4371 assert!(format!("{:?}", Phase::Present).contains("Present"));
4372 assert!(format!("{:?}", Phase::Render).contains("Render"));
4373 }
4374
4375 #[test]
4376 fn phase_clone_copy() {
4377 let p = Phase::Present;
4378 let p2 = p;
4379 assert_eq!(p, p2);
4380 }
4381
4382 #[test]
4385 fn budget_telemetry_debug() {
4386 let telem = BudgetTelemetry {
4387 schema_version: BUDGET_TELEMETRY_SCHEMA_VERSION,
4388 level: DegradationLevel::Full,
4389 pid_output: 0.0,
4390 pid_p: 0.0,
4391 pid_i: 0.0,
4392 pid_d: 0.0,
4393 e_value: 1.0,
4394 eprocess_lambda: 0.5,
4395 frames_observed: 0,
4396 frames_since_change: 0,
4397 last_decision: BudgetDecision::Hold,
4398 decision_reason: BudgetDecisionReason::WithinThresholdBand,
4399 transition_seq: 0,
4400 transition_correlation_id: 0,
4401 frame_time_ms: 0.0,
4402 target_ms: 16.0,
4403 pid_gate_threshold: 0.0,
4404 pid_gate_margin: 0.0,
4405 evidence_threshold: 0.0,
4406 evidence_margin: 0.0,
4407 in_warmup: true,
4408 recovery_streak: 0,
4409 total_degrades: 0,
4410 total_recoveries: 0,
4411 };
4412 let s = format!("{:?}", telem);
4413 assert!(s.contains("BudgetTelemetry"), "Debug output: {}", s);
4414 }
4415
4416 #[test]
4417 fn budget_telemetry_partial_eq() {
4418 let a = BudgetTelemetry {
4419 schema_version: BUDGET_TELEMETRY_SCHEMA_VERSION,
4420 level: DegradationLevel::Full,
4421 pid_output: 0.5,
4422 pid_p: 0.3,
4423 pid_i: 0.1,
4424 pid_d: 0.1,
4425 e_value: 1.0,
4426 eprocess_lambda: 0.5,
4427 frames_observed: 5,
4428 frames_since_change: 2,
4429 last_decision: BudgetDecision::Hold,
4430 decision_reason: BudgetDecisionReason::WithinThresholdBand,
4431 transition_seq: 0,
4432 transition_correlation_id: 0,
4433 frame_time_ms: 16.0,
4434 target_ms: 16.0,
4435 pid_gate_threshold: 0.0,
4436 pid_gate_margin: 0.0,
4437 evidence_threshold: 0.0,
4438 evidence_margin: 0.0,
4439 in_warmup: false,
4440 recovery_streak: 0,
4441 total_degrades: 0,
4442 total_recoveries: 0,
4443 };
4444 let b = a;
4445 assert_eq!(a, b);
4446
4447 let c = BudgetTelemetry {
4448 level: DegradationLevel::SimpleBorders,
4449 ..a
4450 };
4451 assert_ne!(a, c);
4452 }
4453
4454 #[test]
4457 fn next_frame_without_recorded_time_uses_elapsed() {
4458 let mut budget = RenderBudget::new(Duration::from_millis(1000));
4459
4460 budget.next_frame();
4462
4463 assert!(budget.remaining_fraction() > 0.9);
4465 }
4466
4467 #[test]
4468 fn controller_at_max_degradation_holds() {
4469 let mut ctrl = BudgetController::new(BudgetControllerConfig {
4470 eprocess: EProcessConfig {
4471 warmup_frames: 0,
4472 ..Default::default()
4473 },
4474 cooldown_frames: 0,
4475 degradation_floor: DegradationLevel::SkipFrame,
4477 ..Default::default()
4478 });
4479
4480 for _ in 0..500 {
4482 ctrl.update(Duration::from_millis(200));
4483 }
4484 assert_eq!(ctrl.level(), DegradationLevel::SkipFrame);
4485
4486 let d = ctrl.update(Duration::from_millis(200));
4488 assert_eq!(d, BudgetDecision::Hold, "At max level, should hold");
4489 }
4490
4491 #[test]
4492 fn controller_at_configured_degradation_floor_reports_floor_reason() {
4493 let mut ctrl = BudgetController::new(BudgetControllerConfig {
4494 eprocess: EProcessConfig {
4495 warmup_frames: 0,
4496 ..Default::default()
4497 },
4498 cooldown_frames: 0,
4499 degradation_floor: DegradationLevel::SimpleBorders,
4500 ..Default::default()
4501 });
4502
4503 ctrl.current_level = DegradationLevel::SimpleBorders;
4504
4505 let decision = ctrl.update(Duration::from_millis(200));
4506 let telemetry = ctrl.telemetry();
4507
4508 assert_eq!(decision, BudgetDecision::Hold);
4509 assert_eq!(telemetry.level, DegradationLevel::SimpleBorders);
4510 assert_eq!(
4511 telemetry.decision_reason,
4512 BudgetDecisionReason::AtDegradationFloor
4513 );
4514 }
4515
4516 #[test]
4517 fn controller_at_full_level_no_upgrade() {
4518 let mut ctrl = BudgetController::new(BudgetControllerConfig {
4519 eprocess: EProcessConfig {
4520 warmup_frames: 0,
4521 ..Default::default()
4522 },
4523 cooldown_frames: 0,
4524 ..Default::default()
4525 });
4526
4527 for _ in 0..50 {
4529 let d = ctrl.update(Duration::from_millis(1));
4530 assert_ne!(
4531 d,
4532 BudgetDecision::Upgrade,
4533 "Full level should never upgrade"
4534 );
4535 }
4536 }
4537
4538 #[test]
4539 fn controller_recovers_after_external_degradation() {
4540 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
4546 BudgetControllerConfig {
4547 eprocess: EProcessConfig {
4548 warmup_frames: 0,
4549 ..Default::default()
4550 },
4551 cooldown_frames: 0,
4552 ..Default::default()
4553 },
4554 );
4555
4556 budget.set_degradation(DegradationLevel::EssentialOnly);
4558 assert_eq!(
4559 budget.controller().expect("controller attached").level(),
4560 DegradationLevel::EssentialOnly,
4561 "controller must observe the external level change"
4562 );
4563
4564 for _ in 0..300 {
4566 budget.record_frame_time(Duration::from_millis(2));
4567 budget.next_frame();
4568 }
4569 assert!(
4570 budget.degradation() < DegradationLevel::EssentialOnly,
4571 "externally degraded budget must recover under healthy load, got {:?}",
4572 budget.degradation()
4573 );
4574
4575 assert_eq!(
4577 budget.controller().expect("controller attached").level(),
4578 budget.degradation(),
4579 "controller and budget level must stay in lockstep"
4580 );
4581 }
4582
4583 #[test]
4584 fn external_conformal_style_degrade_syncs_controller() {
4585 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
4586 BudgetControllerConfig {
4587 eprocess: EProcessConfig {
4588 warmup_frames: 0,
4589 ..Default::default()
4590 },
4591 cooldown_frames: 0,
4592 ..Default::default()
4593 },
4594 );
4595
4596 budget.degrade();
4598 assert_eq!(
4599 budget.controller().expect("controller attached").level(),
4600 budget.degradation()
4601 );
4602 }
4603
4604 #[test]
4605 fn phase_budget_starts_with_full_phase_allocation() {
4606 let budget = RenderBudget::new(Duration::from_millis(1000));
4610 std::thread::sleep(Duration::from_millis(20));
4611
4612 let sub = budget.phase_budget(Phase::Diff);
4613 assert!(
4614 !sub.exhausted(),
4615 "phase budget must not be exhausted at phase start"
4616 );
4617 assert!(sub.remaining() > Duration::ZERO);
4620 assert!(sub.remaining() <= sub.total());
4621 }
4622
4623 #[test]
4624 fn next_frame_consumes_recorded_time_once() {
4625 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
4629 BudgetControllerConfig {
4630 eprocess: EProcessConfig {
4631 warmup_frames: 0,
4632 ..Default::default()
4633 },
4634 cooldown_frames: 0,
4635 ..Default::default()
4636 },
4637 );
4638
4639 budget.record_frame_time(Duration::from_millis(40));
4640 budget.next_frame();
4641 let after_first = budget
4642 .controller()
4643 .expect("controller attached")
4644 .telemetry()
4645 .frame_time_ms;
4646 assert!((after_first - 40.0).abs() < 1.0);
4647
4648 budget.next_frame();
4651 let after_second = budget
4652 .controller()
4653 .expect("controller attached")
4654 .telemetry()
4655 .frame_time_ms;
4656 assert!(
4657 after_second < 20.0,
4658 "stale frame time re-fed to controller: {after_second}ms"
4659 );
4660 }
4661
4662 #[test]
4663 fn render_budget_full_degrade_cycle_with_controller() {
4664 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
4665 BudgetControllerConfig {
4666 eprocess: EProcessConfig {
4667 warmup_frames: 0,
4668 ..Default::default()
4669 },
4670 cooldown_frames: 0,
4671 ..Default::default()
4672 },
4673 );
4674
4675 for _ in 0..100 {
4677 budget.record_frame_time(Duration::from_millis(40));
4678 budget.next_frame();
4679 }
4680 let degraded = budget.degradation();
4681 assert!(
4682 degraded > DegradationLevel::Full,
4683 "Should degrade: {:?}",
4684 degraded
4685 );
4686
4687 for _ in 0..200 {
4689 budget.record_frame_time(Duration::from_millis(4));
4690 budget.next_frame();
4691 }
4692 let recovered = budget.degradation();
4693 assert!(
4694 recovered < degraded,
4695 "Should recover: {:?} -> {:?}",
4696 degraded,
4697 recovered
4698 );
4699 }
4700
4701 #[test]
4702 fn render_budget_phase_has_budget_exhausted() {
4703 let budget = RenderBudget::new(Duration::from_millis(1));
4704 std::thread::sleep(Duration::from_millis(10));
4705
4706 assert!(!budget.phase_has_budget(Phase::Diff));
4708 assert!(!budget.phase_has_budget(Phase::Present));
4709 assert!(!budget.phase_has_budget(Phase::Render));
4710 }
4711
4712 #[test]
4713 fn render_budget_elapsed_increases() {
4714 let budget = RenderBudget::new(Duration::from_millis(1000));
4715 let e1 = budget.elapsed();
4716 std::thread::sleep(Duration::from_millis(5));
4717 let e2 = budget.elapsed();
4718 assert!(e2 > e1, "Elapsed should increase: {:?} vs {:?}", e1, e2);
4719 }
4720
4721 #[test]
4722 fn controller_pid_integral_accessor() {
4723 let mut ctrl = BudgetController::new(BudgetControllerConfig::default());
4724
4725 assert_eq!(ctrl.pid_integral(), 0.0);
4726
4727 ctrl.update(Duration::from_millis(32)); assert!(
4730 ctrl.pid_integral() > 0.0,
4731 "Integral should grow: {}",
4732 ctrl.pid_integral()
4733 );
4734 }
4735
4736 #[test]
4737 fn controller_e_value_accessor() {
4738 let ctrl = BudgetController::new(BudgetControllerConfig::default());
4739 assert!((ctrl.e_value() - 1.0).abs() < f64::EPSILON);
4740 }
4741
4742 #[test]
4743 fn budget_controller_counts_degrades_and_recoveries() {
4744 let mut ctrl = BudgetController::new(BudgetControllerConfig {
4745 target: Duration::from_millis(16),
4746 cooldown_frames: 0,
4747 upgrade_threshold: 0.1,
4748 degrade_threshold: 0.1,
4749 ..Default::default()
4750 });
4751
4752 assert_eq!(ctrl.recovery_streak(), 0);
4753 assert_eq!(ctrl.total_degrades(), 0);
4754 assert_eq!(ctrl.total_recoveries(), 0);
4755
4756 for _ in 0..5 {
4758 ctrl.update(Duration::from_millis(4));
4759 }
4760 assert!(ctrl.recovery_streak() > 0);
4761
4762 for _ in 0..50 {
4764 ctrl.update(Duration::from_millis(50));
4765 if ctrl.total_degrades() == 1 {
4766 break;
4767 }
4768 }
4769 assert_eq!(ctrl.total_degrades(), 1);
4770 assert_eq!(
4771 ctrl.recovery_streak(),
4772 0,
4773 "recovery_streak resets on degrade"
4774 );
4775
4776 for _ in 0..200 {
4778 ctrl.update(Duration::from_millis(4));
4779 if ctrl.total_recoveries() == 1 {
4780 break;
4781 }
4782 }
4783 assert_eq!(ctrl.total_recoveries(), 1);
4784 assert!(ctrl.recovery_streak() > 0);
4785
4786 ctrl.reset();
4788 assert_eq!(ctrl.recovery_streak(), 0);
4789 assert_eq!(ctrl.total_degrades(), 0);
4790 assert_eq!(ctrl.total_recoveries(), 0);
4791 }
4792
4793 #[test]
4794 fn controller_telemetry_includes_counters() {
4795 let ctrl = BudgetController::new(BudgetControllerConfig::default());
4796 let t = ctrl.telemetry();
4797 assert_eq!(t.recovery_streak, 0);
4798 assert_eq!(t.total_degrades, 0);
4799 assert_eq!(t.total_recoveries, 0);
4800 }
4801
4802 #[test]
4803 fn degrade_respecting_floor_honors_controller_floor_and_syncs_level() {
4804 let mut budget = RenderBudget::new(Duration::from_millis(16)).with_controller(
4805 BudgetControllerConfig {
4806 degradation_floor: DegradationLevel::NoStyling,
4807 ..Default::default()
4808 },
4809 );
4810
4811 assert_eq!(budget.degradation_floor(), DegradationLevel::NoStyling);
4812 assert!(budget.degrade_respecting_floor());
4813 assert_eq!(budget.degradation(), DegradationLevel::SimpleBorders);
4814 assert_eq!(
4815 budget.controller().unwrap().level(),
4816 DegradationLevel::SimpleBorders
4817 );
4818
4819 assert!(budget.degrade_respecting_floor());
4820 assert_eq!(budget.degradation(), DegradationLevel::NoStyling);
4821 assert_eq!(
4822 budget.controller().unwrap().level(),
4823 DegradationLevel::NoStyling
4824 );
4825
4826 assert!(!budget.degrade_respecting_floor());
4828 assert_eq!(budget.degradation(), DegradationLevel::NoStyling);
4829 }
4830
4831 #[test]
4832 fn virtual_clock_overload_traverses_full_ladder_and_recovers_deterministically() {
4833 let make_budget = || {
4834 RenderBudget::new(Duration::from_millis(16)).with_controller(
4835 BudgetControllerConfig {
4836 target: Duration::from_millis(16),
4837 degradation_floor: DegradationLevel::SkipFrame,
4838 ..Default::default()
4839 },
4840 )
4841 };
4842
4843 let run_virtual_trace = |budget: &mut RenderBudget| -> Vec<DegradationLevel> {
4844 let mut observed_levels = Vec::new();
4845 for frame in 0..9 {
4847 budget.record_frame_time(Duration::from_millis(80));
4848 budget.next_frame();
4849 assert_eq!(
4850 budget.degradation(),
4851 DegradationLevel::Full,
4852 "warmup frame {frame} must not degrade"
4853 );
4854 observed_levels.push(budget.degradation());
4855 }
4856 for _ in 0..40 {
4858 budget.record_frame_time(Duration::from_millis(80));
4859 budget.next_frame();
4860 observed_levels.push(budget.degradation());
4861 }
4862 assert_eq!(budget.degradation(), DegradationLevel::SkipFrame);
4863
4864 for _ in 0..240 {
4866 budget.record_frame_time(Duration::from_millis(4));
4867 budget.next_frame();
4868 observed_levels.push(budget.degradation());
4869 }
4870 assert_eq!(budget.degradation(), DegradationLevel::Full);
4871 observed_levels
4872 };
4873
4874 let mut budget_a = make_budget();
4875 let mut budget_b = make_budget();
4876 let path_a = run_virtual_trace(&mut budget_a);
4877 let path_b = run_virtual_trace(&mut budget_b);
4878
4879 assert_eq!(path_a, path_b);
4881
4882 for expected in [
4884 DegradationLevel::Full,
4885 DegradationLevel::SimpleBorders,
4886 DegradationLevel::NoStyling,
4887 DegradationLevel::EssentialOnly,
4888 DegradationLevel::Skeleton,
4889 DegradationLevel::SkipFrame,
4890 ] {
4891 assert!(
4892 path_a.contains(&expected),
4893 "expected ladder traversal to visit {expected:?}"
4894 );
4895 }
4896 }
4897
4898 fn splitmix64_normal(state: &mut u64) -> (f64, f64) {
4899 fn next_u01(state: &mut u64) -> f64 {
4900 *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
4901 let mut z = *state;
4902 z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
4903 z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
4904 z ^= z >> 31;
4905 ((z >> 11) as f64) * (1.0 / ((1u64 << 53) as f64))
4906 }
4907 let u1 = next_u01(state).clamp(1e-12, 1.0 - 1e-12);
4908 let u2 = next_u01(state);
4909 let r = (-2.0 * u1.ln()).sqrt();
4910 let theta = 2.0 * std::f64::consts::PI * u2;
4911 (r * theta.cos(), r * theta.sin())
4912 }
4913
4914 #[test]
4915 fn budget_controller_grapa_adapts_lambda() {
4916 let target_ms = 16.0;
4917 let step_ms = target_ms * 1.8; let base_eprocess = EProcessConfig {
4919 lambda: 0.5,
4920 adaptive_lambda: true,
4921 grapa_eta: 0.1,
4922 lambda_min: 0.05,
4923 lambda_max: 2.0,
4924 alpha: 0.05,
4925 beta: 0.5,
4926 sigma_ema_decay: 0.9,
4927 sigma_floor_ms: 4.0,
4928 warmup_frames: 10,
4929 };
4930
4931 let mut adaptive = BudgetController::new(BudgetControllerConfig {
4932 target: Duration::from_millis(16),
4933 eprocess: base_eprocess.clone(),
4934 ..Default::default()
4935 });
4936 let mut fixed = BudgetController::new(BudgetControllerConfig {
4937 target: Duration::from_millis(16),
4938 eprocess: EProcessConfig {
4939 adaptive_lambda: false,
4940 ..base_eprocess.clone()
4941 },
4942 ..Default::default()
4943 });
4944
4945 for _ in 0..30 {
4947 adaptive.update(Duration::from_millis(16));
4948 fixed.update(Duration::from_millis(16));
4949 }
4950
4951 let threshold = 1.0 / base_eprocess.alpha; let step_dur = Duration::from_secs_f64(step_ms / 1000.0);
4953 let mut adaptive_cross = None;
4954 let mut fixed_cross = None;
4955
4956 for step_frame in 1..=50usize {
4957 adaptive.update(step_dur);
4958 fixed.update(step_dur);
4959 if adaptive_cross.is_none() && adaptive.e_value() > threshold {
4960 adaptive_cross = Some(step_frame);
4961 }
4962 if fixed_cross.is_none() && fixed.e_value() > threshold {
4963 fixed_cross = Some(step_frame);
4964 }
4965 if adaptive_cross.is_some() && fixed_cross.is_some() {
4966 break;
4967 }
4968 }
4969
4970 let adaptive_frames = adaptive_cross.expect("adaptive controller must cross 1/alpha");
4971 let fixed_frames = fixed_cross.expect("fixed controller must cross 1/alpha");
4972 eprintln!(
4973 "budget_controller_grapa_adapts_lambda: adaptive_frames={adaptive_frames}, fixed_frames={fixed_frames}"
4974 );
4975 assert!(
4976 adaptive_frames < fixed_frames,
4977 "Expected adaptive controller ({adaptive_frames} frames) to cross 1/alpha={threshold} in strictly fewer frames than fixed ({fixed_frames} frames)"
4978 );
4979
4980 let null_eprocess = EProcessConfig {
4982 sigma_floor_ms: 2.0,
4983 ..EProcessConfig::default()
4984 };
4985 let mut adaptive_null = BudgetController::new(BudgetControllerConfig {
4986 target: Duration::from_millis(16),
4987 eprocess: null_eprocess.clone(),
4988 ..Default::default()
4989 });
4990 let mut fixed_null = BudgetController::new(BudgetControllerConfig {
4991 target: Duration::from_millis(16),
4992 eprocess: EProcessConfig {
4993 adaptive_lambda: false,
4994 ..null_eprocess
4995 },
4996 ..Default::default()
4997 });
4998
4999 let mut rng = 0x6130_1720_2026_1016u64;
5000 for i in 0..5_000 {
5001 let (z0, z1) = splitmix64_normal(&mut rng);
5002 for (step_offset, z) in [(0usize, z0), (1usize, z1)] {
5003 let frame_idx = i * 2 + step_offset;
5004 let ms = (16.0 + z).clamp(1.0, 31.0);
5006 let dur = Duration::from_secs_f64(ms / 1000.0);
5007 adaptive_null.update(dur);
5008 fixed_null.update(dur);
5009 assert!(
5010 adaptive_null.e_value() <= threshold,
5011 "adaptive crossed threshold at null frame {frame_idx}: E={}",
5012 adaptive_null.e_value()
5013 );
5014 assert!(
5015 fixed_null.e_value() <= threshold,
5016 "fixed crossed threshold at null frame {frame_idx}: E={}",
5017 fixed_null.e_value()
5018 );
5019 }
5020 }
5021 }
5022
5023 #[test]
5024 fn lambda_is_predictable() {
5025 let cfg = BudgetControllerConfig {
5029 target: Duration::from_millis(16),
5030 eprocess: EProcessConfig {
5031 warmup_frames: 3,
5032 ..EProcessConfig::default()
5033 },
5034 ..Default::default()
5035 };
5036 let mut ctrl = BudgetController::new(cfg.clone());
5037 let mut mirror_state = EProcessState::new(&cfg.eprocess);
5038
5039 let sequence_ms = [
5040 16.0, 15.5, 16.5, 18.0, 22.0, 26.0, 30.0, 24.0, 16.0, 14.0, 12.0, 16.0, 20.0, 28.0,
5041 ];
5042
5043 let mut prev_e = ctrl.telemetry().e_value;
5044 let mut prev_lambda = ctrl.telemetry().eprocess_lambda;
5045
5046 for (idx, &ms) in sequence_ms.iter().enumerate() {
5047 mirror_state.frames_observed = mirror_state.frames_observed.saturating_add(1);
5049 if mirror_state.frames_observed == 1 {
5050 mirror_state.mean_ema = ms;
5051 mirror_state.sigma_ema = cfg.eprocess.sigma_floor_ms;
5052 } else {
5053 let decay = cfg.eprocess.sigma_ema_decay;
5054 mirror_state.mean_ema = decay * mirror_state.mean_ema + (1.0 - decay) * ms;
5055 let deviation = (ms - mirror_state.mean_ema).abs();
5056 mirror_state.sigma_ema =
5057 decay * mirror_state.sigma_ema + (1.0 - decay) * deviation;
5058 }
5059 let sigma = mirror_state.sigma_ema.max(cfg.eprocess.sigma_floor_ms);
5060 let r_t = (ms - 16.0) / sigma;
5061
5062 ctrl.update(Duration::from_secs_f64(ms / 1000.0));
5063 let telem = ctrl.telemetry();
5064
5065 let expected_e = (prev_e
5066 * (prev_lambda * r_t - prev_lambda * prev_lambda / 2.0).exp())
5067 .clamp(1e-10, 1e10);
5068 let rel_err = (telem.e_value - expected_e).abs() / expected_e.max(1.0);
5069 assert!(
5070 (telem.e_value - expected_e).abs() < 1e-9 || rel_err < 1e-9,
5071 "step {idx}: expected e_value {expected_e} from prev_e={prev_e} and prev_lambda={prev_lambda}, got {}",
5072 telem.e_value
5073 );
5074
5075 prev_e = telem.e_value;
5076 prev_lambda = telem.eprocess_lambda;
5077 }
5078 }
5079
5080 #[test]
5081 fn lambda_stays_within_bounds() {
5082 let config = EProcessConfig {
5083 warmup_frames: 0,
5084 lambda_min: 0.05,
5085 lambda_max: 2.0,
5086 ..EProcessConfig::default()
5087 };
5088 let mut state = EProcessState::new(&config);
5089
5090 for &frame_ms in &[0.0, 1e6, 0.0, 1e6, 16.0, 1e6, 1e6, 0.0, 0.0, f64::NAN, 16.0] {
5091 state.update(frame_ms, 16.0, &config);
5092 assert!(
5093 state.lambda.is_finite(),
5094 "lambda must remain finite, got {}",
5095 state.lambda
5096 );
5097 assert!(
5098 state.lambda >= config.lambda_min && state.lambda <= config.lambda_max,
5099 "lambda {} out of [{}, {}]",
5100 state.lambda,
5101 config.lambda_min,
5102 config.lambda_max
5103 );
5104 }
5105 }
5106
5107 proptest::proptest! {
5108 #![proptest_config(proptest::test_runner::Config::with_cases(32))]
5109
5110 #[test]
5111 fn proptest_e_value_is_supermartingale_under_null(seed in 1u64..1_000_000u64) {
5112 let cfg = EProcessConfig {
5113 warmup_frames: 10,
5114 sigma_floor_ms: 2.0,
5115 ..EProcessConfig::default()
5116 };
5117 let runs = 200usize;
5118 let frames = 500usize;
5119 let mut total_final_e = 0.0;
5120
5121 for run in 0..runs {
5122 let mut rng = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15).wrapping_add(run as u64);
5123 let mut state = EProcessState::new(&cfg);
5124 for _ in 0..(frames / 2) {
5125 let (z0, z1) = splitmix64_normal(&mut rng);
5126 let f0 = (16.0 + z0).clamp(1.0, 31.0);
5127 let f1 = (16.0 + z1).clamp(1.0, 31.0);
5128 state.update(f0, 16.0, &cfg);
5129 state.update(f1, 16.0, &cfg);
5130 }
5131 total_final_e += state.e_value;
5132 }
5133
5134 let mean_final_e = total_final_e / runs as f64;
5135 proptest::prop_assert!(
5136 mean_final_e < 3.0,
5137 "Expected mean final e_value < 3.0 over {runs} null runs of {frames} frames, got {mean_final_e}"
5138 );
5139 }
5140 }
5141 }
5142}