Skip to main content

qualia_core_db/inference/runtime/prepared/
generation.rs

1//! Model residency identity and generation tracking.
2//!
3//! Binds model execution plans and caches to a unique generation and content identity,
4//! ensuring that model replacement or LoRA adapter changes invalidate stale plans.
5
6use std::sync::atomic::{AtomicU64, Ordering};
7
8/// Generation identity tracker for process-wide or engine-local model residency.
9#[derive(Debug)]
10pub struct ResidencyGenerationTracker {
11    current_generation: AtomicU64,
12}
13
14impl ResidencyGenerationTracker {
15    /// Creates a default `ResidencyGenerationTracker`.
16    pub const fn new(initial_generation: u64) -> Self {
17        Self {
18            current_generation: AtomicU64::new(initial_generation),
19        }
20    }
21
22    /// Read the current residency generation number.
23    pub fn generation(&self) -> u64 {
24        self.current_generation.load(Ordering::Acquire)
25    }
26
27    /// Bump generation, invalidating any previously compiled plans or cached states.
28    pub fn advance_generation(&self) -> u64 {
29        self.current_generation.fetch_add(1, Ordering::Release) + 1
30    }
31}
32
33/// Content-bound model residency identity.
34#[derive(Clone, Debug, PartialEq, Eq, Hash)]
35pub struct ModelResidencyIdentity {
36    /// Canonical model path or DID.
37    pub model_path: String,
38    /// Content hash of the model weights/header (e.g. FNV-1a or SHA-256 of magic + metadata).
39    pub content_hash: u64,
40    /// Residency generation number assigned upon mounting/loading.
41    pub generation: u64,
42    /// Hash of currently attached LoRA adapter configurations (0 if none).
43    pub adapter_hash: u64,
44}
45
46impl ModelResidencyIdentity {
47    /// Creates `ModelResidencyIdentity` with the given state.
48    pub fn new(
49        model_path: impl Into<String>,
50        content_hash: u64,
51        generation: u64,
52        adapter_hash: u64,
53    ) -> Self {
54        Self {
55            model_path: model_path.into(),
56            content_hash,
57            generation,
58            adapter_hash,
59        }
60    }
61
62    /// Returns true if `other` matches the exact generation, content, and adapter state.
63    pub fn is_compatible_with(&self, other: &Self) -> bool {
64        self.generation == other.generation
65            && self.content_hash == other.content_hash
66            && self.adapter_hash == other.adapter_hash
67            && self.model_path == other.model_path
68    }
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74
75    #[test]
76    fn test_generation_tracker_advances() {
77        let tracker = ResidencyGenerationTracker::new(1);
78        assert_eq!(tracker.generation(), 1);
79        let g2 = tracker.advance_generation();
80        assert_eq!(g2, 2);
81        assert_eq!(tracker.generation(), 2);
82    }
83
84    #[test]
85    fn test_residency_identity_compatibility() {
86        let id1 = ModelResidencyIdentity::new("models/qwen.gguf", 0x1234, 1, 0);
87        let id1_clone = ModelResidencyIdentity::new("models/qwen.gguf", 0x1234, 1, 0);
88        assert!(id1.is_compatible_with(&id1_clone));
89
90        // Different generation (e.g. reload or swap) -> incompatible
91        let id2 = ModelResidencyIdentity::new("models/qwen.gguf", 0x1234, 2, 0);
92        assert!(!id1.is_compatible_with(&id2));
93
94        // Different adapter -> incompatible
95        let id3 = ModelResidencyIdentity::new("models/qwen.gguf", 0x1234, 1, 0xABCD);
96        assert!(!id1.is_compatible_with(&id3));
97    }
98}