Skip to main content

hyprstream_inference/training/
adaptation_state.rs

1use anyhow::{anyhow, Result};
2use std::collections::HashMap;
3use std::time::Instant;
4use tch::Tensor;
5
6/// Outcome of resolving an adaptation through the state machine.
7#[derive(Debug)]
8pub enum ResolveOutcome {
9    WrittenBack,
10    /// The adaptation was evicted (rolled back). The baseline snapshot is returned
11    /// so the caller can restore delta weights without retaining ownership beforehand.
12    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/// Strategy for handling a completed adaptation.
24#[derive(Debug, Clone, PartialEq)]
25pub enum AdaptationStrategy {
26    /// Write back if recommendation positive, evict if negative.
27    AutoWriteback,
28    /// Always evict — eval/benchmark mode.
29    AutoEvict,
30    /// Store as pending — client calls writeback() or evict() later.
31    Speculative,
32    /// Write back if loss_improvement exceeds threshold, else evict.
33    WritebackIfAbove { threshold: f32 },
34}
35
36/// Guard status — proof that invariant checks were run before resolution.
37/// Returned by the guard middleware; required input to resolve().
38#[derive(Debug, Clone)]
39pub struct GuardStatus {
40    /// True if the pending adaptation has expired (past timeout_ms).
41    pub expired: bool,
42    /// True if accumulated_steps >= max_accumulated_steps.
43    pub at_capacity: bool,
44    /// LoRA generation counter at guard-check time.
45    pub lora_generation: u64,
46}
47
48/// Info returned after a successful writeback (for stats accounting by the caller).
49#[derive(Debug, Clone)]
50pub struct WritebackInfo {
51    pub steps_performed: usize,
52    pub loss_improvement: f32,
53}
54
55/// Snapshot returned after eviction (for restoring delta state by the caller).
56#[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/// The lifecycle state of a tenant delta's pending adaptation.
64///
65/// Stored inside TenantDelta. Replaces the external
66/// `pending_adaptations: Mutex<HashMap<Subject, PendingAdaptation>>`.
67#[derive(Debug)]
68#[allow(clippy::large_enum_variant)]
69pub enum DeltaAdaptationState {
70    /// No pending work. Delta holds its last committed state.
71    Idle,
72    /// Adaptation applied in-place. Snapshot held for potential rollback.
73    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    /// Resolve a new adaptation result according to the given strategy.
104    ///
105    /// This is the single entry point for all commit/rollback/pending decisions.
106    /// Called by both the adapt-then-generate and pure-training paths.
107    ///
108    /// For the `Evicted` outcome, the baseline snapshot (pre-first-adaptation state)
109    /// is returned inside `ResolveOutcome::Evicted` so the caller can restore weights
110    /// without needing to retain ownership of the inputs before this call.
111    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        // 1. Capacity check
121        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        // 2. Expired pending: auto-evict silently (guard detected, we clear it)
128        // NOTE: We transition the *state* to Idle but do NOT restore the delta's
129        // LoRA weights here. The expired adaptation's weight changes remain in the
130        // live delta. Weight restoration requires &mut TenantDelta, which will be
131        // threaded through resolve() in the service-layer integration (Task 3/4).
132        // Callers that receive ResolveOutcome::Evicted are responsible for calling
133        // delta.load_state_dict(&snapshot) with whatever snapshot is appropriate.
134        if guard.expired && self.is_pending() {
135            *self = Self::Idle;
136        }
137
138        // 3. Skipped result: no state change
139        if result.skipped {
140            return ResolveOutcome::Skipped {
141                reason: result.skip_reason.clone().unwrap_or_default(),
142            };
143        }
144
145        // 4. Stacked adaptation: promote old baseline.
146        // If an old Pending exists, extract its stored baseline (pre-first-adaptation
147        // state) so that rollback always unwinds to before any pending work.
148        // Otherwise use the caller's snapshot directly (moved in, no copy needed).
149        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 pending exists: promote its baseline (pre-first-adaptation state)
157            (old_snap, old_muon, old_ranks)
158        } else {
159            (pre_snapshot, pre_muon, pre_eff_ranks)
160        };
161
162        // 5. Apply strategy
163        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    /// Write back (accept) a pending adaptation. Returns stats info for the caller
203    /// to apply to the delta's counters.
204    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    /// Evict (discard) a pending adaptation. Returns the snapshot for the caller
215    /// to restore onto the delta.
216    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}