1use anyhow::{anyhow, Result};
2use std::collections::HashMap;
3use std::time::Instant;
4use tch::Tensor;
5
6#[derive(Debug)]
8pub enum ResolveOutcome {
9 WrittenBack,
10 Evicted {
13 snapshot: HashMap<String, Tensor>,
14 muon: HashMap<String, Tensor>,
15 eff_ranks: HashMap<String, usize>,
16 },
17 StoredPending,
18 Skipped {
19 reason: String,
20 },
21}
22
23#[derive(Debug, Clone, PartialEq)]
25pub enum AdaptationStrategy {
26 AutoWriteback,
28 AutoEvict,
30 Speculative,
32 WritebackIfAbove { threshold: f32 },
34}
35
36#[derive(Debug, Clone)]
39pub struct GuardStatus {
40 pub expired: bool,
42 pub at_capacity: bool,
44 pub lora_generation: u64,
46}
47
48#[derive(Debug, Clone)]
50pub struct WritebackInfo {
51 pub steps_performed: usize,
52 pub loss_improvement: f32,
53}
54
55#[derive(Debug)]
57pub struct EvictedSnapshot {
58 pub pre_snapshot: HashMap<String, Tensor>,
59 pub pre_muon: HashMap<String, Tensor>,
60 pub pre_eff_ranks: HashMap<String, usize>,
61}
62
63#[derive(Debug)]
68#[allow(clippy::large_enum_variant)]
69pub enum DeltaAdaptationState {
70 Idle,
72 Pending {
74 pre_snapshot: HashMap<String, Tensor>,
75 pre_muon: HashMap<String, Tensor>,
76 pre_eff_ranks: HashMap<String, usize>,
77 ttt_result: super::ttt::TTTResult,
78 created_at: Instant,
79 timeout_ms: u64,
80 },
81}
82
83impl DeltaAdaptationState {
84 pub fn new() -> Self {
85 Self::Idle
86 }
87
88 pub fn is_pending(&self) -> bool {
89 matches!(self, Self::Pending { .. })
90 }
91
92 pub fn is_expired(&self) -> bool {
93 match self {
94 Self::Pending {
95 created_at,
96 timeout_ms,
97 ..
98 } => created_at.elapsed().as_millis() as u64 > *timeout_ms,
99 Self::Idle => false,
100 }
101 }
102
103 pub fn resolve(
112 &mut self,
113 strategy: AdaptationStrategy,
114 guard: &GuardStatus,
115 result: &super::ttt::TTTResult,
116 pre_snapshot: HashMap<String, Tensor>,
117 pre_muon: HashMap<String, Tensor>,
118 pre_eff_ranks: HashMap<String, usize>,
119 ) -> ResolveOutcome {
120 if guard.at_capacity && !result.skipped {
122 return ResolveOutcome::Skipped {
123 reason: "Delta at capacity. Save, export, or reset to continue.".into(),
124 };
125 }
126
127 if guard.expired && self.is_pending() {
135 *self = Self::Idle;
136 }
137
138 if result.skipped {
140 return ResolveOutcome::Skipped {
141 reason: result.skip_reason.clone().unwrap_or_default(),
142 };
143 }
144
145 let (base_snapshot, base_muon, base_eff_ranks) = if let Self::Pending {
150 pre_snapshot: old_snap,
151 pre_muon: old_muon,
152 pre_eff_ranks: old_ranks,
153 ..
154 } = std::mem::replace(self, Self::Idle)
155 {
156 (old_snap, old_muon, old_ranks)
158 } else {
159 (pre_snapshot, pre_muon, pre_eff_ranks)
160 };
161
162 match strategy {
164 AdaptationStrategy::AutoWriteback if result.recommendation => {
165 *self = Self::Idle;
166 ResolveOutcome::WrittenBack
167 }
168 AdaptationStrategy::AutoWriteback | AdaptationStrategy::AutoEvict => {
169 *self = Self::Idle;
170 ResolveOutcome::Evicted {
171 snapshot: base_snapshot,
172 muon: base_muon,
173 eff_ranks: base_eff_ranks,
174 }
175 }
176 AdaptationStrategy::Speculative => {
177 *self = Self::Pending {
178 pre_snapshot: base_snapshot,
179 pre_muon: base_muon,
180 pre_eff_ranks: base_eff_ranks,
181 ttt_result: result.clone(),
182 created_at: Instant::now(),
183 timeout_ms: 60_000,
184 };
185 ResolveOutcome::StoredPending
186 }
187 AdaptationStrategy::WritebackIfAbove { threshold } => {
188 *self = Self::Idle;
189 if result.loss_improvement > threshold {
190 ResolveOutcome::WrittenBack
191 } else {
192 ResolveOutcome::Evicted {
193 snapshot: base_snapshot,
194 muon: base_muon,
195 eff_ranks: base_eff_ranks,
196 }
197 }
198 }
199 }
200 }
201
202 pub fn writeback_stats(&mut self) -> Result<WritebackInfo> {
205 match std::mem::replace(self, Self::Idle) {
206 Self::Pending { ttt_result, .. } => Ok(WritebackInfo {
207 steps_performed: ttt_result.steps_performed,
208 loss_improvement: ttt_result.loss_improvement,
209 }),
210 Self::Idle => Err(anyhow!("No pending adaptation to write back")),
211 }
212 }
213
214 pub fn evict(&mut self) -> Result<EvictedSnapshot> {
217 match std::mem::replace(self, Self::Idle) {
218 Self::Pending {
219 pre_snapshot,
220 pre_muon,
221 pre_eff_ranks,
222 ..
223 } => Ok(EvictedSnapshot {
224 pre_snapshot,
225 pre_muon,
226 pre_eff_ranks,
227 }),
228 Self::Idle => Err(anyhow!("No pending adaptation to evict")),
229 }
230 }
231}
232
233impl Default for DeltaAdaptationState {
234 fn default() -> Self {
235 Self::new()
236 }
237}
238
239#[cfg(test)]
240#[allow(clippy::unwrap_used, clippy::expect_used)]
241mod tests {
242 use super::*;
243
244 fn make_guard(expired: bool, at_capacity: bool) -> GuardStatus {
245 GuardStatus {
246 expired,
247 at_capacity,
248 lora_generation: 0,
249 }
250 }
251
252 fn make_fake_snapshot() -> HashMap<String, Tensor> {
253 let mut m = HashMap::new();
254 m.insert(
255 "test".into(),
256 Tensor::zeros([2, 2], (tch::Kind::Float, tch::Device::Cpu)),
257 );
258 m
259 }
260
261 fn make_fake_result(
262 recommendation: bool,
263 loss_improvement: f32,
264 steps: usize,
265 ) -> super::super::ttt::TTTResult {
266 let mut r = super::super::ttt::TTTResult::skipped("test");
267 r.recommendation = recommendation;
268 r.loss_improvement = loss_improvement;
269 r.steps_performed = steps;
270 r.skipped = false;
271 r.skip_reason = None;
272 r
273 }
274
275 #[test]
276 fn test_new_state_is_idle() {
277 let state = DeltaAdaptationState::new();
278 assert!(!state.is_pending());
279 assert!(!state.is_expired());
280 }
281
282 #[test]
283 fn test_resolve_auto_writeback_positive() {
284 let mut state = DeltaAdaptationState::new();
285 let guard = make_guard(false, false);
286 let result = make_fake_result(true, 0.05, 3);
287 let outcome = state.resolve(
288 AdaptationStrategy::AutoWriteback,
289 &guard,
290 &result,
291 make_fake_snapshot(),
292 HashMap::new(),
293 HashMap::new(),
294 );
295 assert!(matches!(outcome, ResolveOutcome::WrittenBack));
296 assert!(!state.is_pending());
297 }
298
299 #[test]
300 fn test_resolve_auto_writeback_negative_evicts() {
301 let mut state = DeltaAdaptationState::new();
302 let guard = make_guard(false, false);
303 let result = make_fake_result(false, -0.01, 3);
304 let outcome = state.resolve(
305 AdaptationStrategy::AutoWriteback,
306 &guard,
307 &result,
308 make_fake_snapshot(),
309 HashMap::new(),
310 HashMap::new(),
311 );
312 assert!(matches!(outcome, ResolveOutcome::Evicted { .. }));
313 assert!(!state.is_pending());
314 }
315
316 #[test]
317 fn test_resolve_speculative_stores_pending() {
318 let mut state = DeltaAdaptationState::new();
319 let guard = make_guard(false, false);
320 let result = make_fake_result(true, 0.05, 3);
321 let outcome = state.resolve(
322 AdaptationStrategy::Speculative,
323 &guard,
324 &result,
325 make_fake_snapshot(),
326 HashMap::new(),
327 HashMap::new(),
328 );
329 assert!(matches!(outcome, ResolveOutcome::StoredPending));
330 assert!(state.is_pending());
331 }
332
333 #[test]
334 fn test_resolve_at_capacity_skips() {
335 let mut state = DeltaAdaptationState::new();
336 let guard = make_guard(false, true);
337 let result = make_fake_result(true, 0.05, 3);
338 let outcome = state.resolve(
339 AdaptationStrategy::AutoWriteback,
340 &guard,
341 &result,
342 make_fake_snapshot(),
343 HashMap::new(),
344 HashMap::new(),
345 );
346 assert!(matches!(outcome, ResolveOutcome::Skipped { .. }));
347 }
348
349 #[test]
350 fn test_resolve_expired_auto_evicts_before_new() {
351 let mut state = DeltaAdaptationState::new();
352 let guard = make_guard(false, false);
353 let result = make_fake_result(true, 0.05, 3);
354 let snap1 = make_fake_snapshot();
355 state.resolve(
356 AdaptationStrategy::Speculative,
357 &guard,
358 &result,
359 snap1,
360 HashMap::new(),
361 HashMap::new(),
362 );
363 assert!(state.is_pending());
364
365 let guard_expired = make_guard(true, false);
366 let result2 = make_fake_result(true, 0.03, 2);
367 let outcome = state.resolve(
368 AdaptationStrategy::AutoWriteback,
369 &guard_expired,
370 &result2,
371 make_fake_snapshot(),
372 HashMap::new(),
373 HashMap::new(),
374 );
375 assert!(matches!(outcome, ResolveOutcome::WrittenBack));
376 }
377
378 #[test]
379 fn test_stacked_pending_promotes_baseline() {
380 let mut state = DeltaAdaptationState::new();
381 let guard = make_guard(false, false);
382 let result = make_fake_result(true, 0.05, 3);
383
384 let snap1 = make_fake_snapshot();
385 let snap1_keys: Vec<String> = snap1.keys().cloned().collect();
386 state.resolve(
387 AdaptationStrategy::Speculative,
388 &guard,
389 &result,
390 snap1,
391 HashMap::new(),
392 HashMap::new(),
393 );
394
395 let snap2 = {
396 let mut m = HashMap::new();
397 m.insert(
398 "different_key".into(),
399 Tensor::ones([2, 2], (tch::Kind::Float, tch::Device::Cpu)),
400 );
401 m
402 };
403 let result2 = make_fake_result(true, 0.03, 2);
404 state.resolve(
405 AdaptationStrategy::Speculative,
406 &guard,
407 &result2,
408 snap2,
409 HashMap::new(),
410 HashMap::new(),
411 );
412
413 if let DeltaAdaptationState::Pending {
414 ref pre_snapshot, ..
415 } = state
416 {
417 assert!(
418 pre_snapshot.contains_key(&snap1_keys[0]),
419 "Stacked pending should promote the FIRST snapshot as baseline"
420 );
421 } else {
422 panic!("Expected Pending state");
423 }
424 }
425
426 #[test]
427 fn test_writeback_from_idle_errors() {
428 let mut state = DeltaAdaptationState::new();
429 assert!(state.writeback_stats().is_err());
430 }
431
432 #[test]
433 fn test_writeback_returns_stats() {
434 let mut state = DeltaAdaptationState::new();
435 let guard = make_guard(false, false);
436 let result = make_fake_result(true, 0.05, 3);
437 state.resolve(
438 AdaptationStrategy::Speculative,
439 &guard,
440 &result,
441 make_fake_snapshot(),
442 HashMap::new(),
443 HashMap::new(),
444 );
445 let info = state.writeback_stats().unwrap();
446 assert_eq!(info.steps_performed, 3);
447 assert!((info.loss_improvement - 0.05).abs() < 1e-6);
448 assert!(!state.is_pending());
449 }
450
451 #[test]
452 fn test_evict_from_idle_errors() {
453 let mut state = DeltaAdaptationState::new();
454 assert!(state.evict().is_err());
455 }
456
457 #[test]
458 fn test_evict_returns_snapshot() {
459 let mut state = DeltaAdaptationState::new();
460 let guard = make_guard(false, false);
461 let result = make_fake_result(true, 0.05, 3);
462 state.resolve(
463 AdaptationStrategy::Speculative,
464 &guard,
465 &result,
466 make_fake_snapshot(),
467 HashMap::new(),
468 HashMap::new(),
469 );
470 let evicted = state.evict().unwrap();
471 assert!(!evicted.pre_snapshot.is_empty());
472 assert!(!state.is_pending());
473 }
474
475 #[test]
476 fn test_auto_evict_always_evicts() {
477 let mut state = DeltaAdaptationState::new();
478 let guard = make_guard(false, false);
479 let result = make_fake_result(true, 0.05, 3);
480 let outcome = state.resolve(
481 AdaptationStrategy::AutoEvict,
482 &guard,
483 &result,
484 make_fake_snapshot(),
485 HashMap::new(),
486 HashMap::new(),
487 );
488 assert!(matches!(outcome, ResolveOutcome::Evicted { .. }));
489 }
490
491 #[test]
492 fn test_writeback_if_above_threshold() {
493 let mut state = DeltaAdaptationState::new();
494 let guard = make_guard(false, false);
495
496 let result = make_fake_result(true, 0.01, 3);
497 let outcome = state.resolve(
498 AdaptationStrategy::WritebackIfAbove { threshold: 0.02 },
499 &guard,
500 &result,
501 make_fake_snapshot(),
502 HashMap::new(),
503 HashMap::new(),
504 );
505 assert!(matches!(outcome, ResolveOutcome::Evicted { .. }));
506
507 let result2 = make_fake_result(true, 0.05, 3);
508 let outcome2 = state.resolve(
509 AdaptationStrategy::WritebackIfAbove { threshold: 0.02 },
510 &guard,
511 &result2,
512 make_fake_snapshot(),
513 HashMap::new(),
514 HashMap::new(),
515 );
516 assert!(matches!(outcome2, ResolveOutcome::WrittenBack));
517 }
518
519 #[test]
520 fn test_skipped_result_does_nothing() {
521 let mut state = DeltaAdaptationState::new();
522 let guard = make_guard(false, false);
523 let result = crate::training::ttt::TTTResult::skipped("too short");
524 let outcome = state.resolve(
525 AdaptationStrategy::AutoWriteback,
526 &guard,
527 &result,
528 make_fake_snapshot(),
529 HashMap::new(),
530 HashMap::new(),
531 );
532 assert!(matches!(outcome, ResolveOutcome::Skipped { .. }));
533 assert!(!state.is_pending());
534 }
535}