Skip to main content

qualia_core_db/lora/
adapter_manager.rs

1//! LoRA adapter loading, caching, and application.
2//!
3//! # File format (`*.lora`)
4//!
5//! ```text
6//! Offset  Size  Field
7//! 0       4     magic `LORA`
8//! 4       4     format version (u32 le) — currently 1
9//! 8       1     adapter_id (0–255)
10//! 9       3     _pad
11//! 12      4     rank (u32 le)
12//! 16      4     alpha (f32 le)
13//! 20      4     n_in — lora_a cols, lora_b rows (u32 le)
14//! 24      4     n_out — lora_b rows, lora_a rows (u32 le)
15//! 28      4     _pad
16//! 32      32    sha256 checksum of payload (lora_a ++ lora_b, raw f32 le)
17//! 64      …     lora_a data: rank × n_in f32 le, row-major
18//!               lora_b data: n_out × rank f32 le, row-major
19//! ```
20//!
21//! Both matrices are stored as raw `f32` little-endian.
22//! `scaling = alpha / rank`; the caller multiplies by this before adding the delta.
23//!
24//! # Invariants
25//!
26//! - `lora_a.rows == rank`, `lora_a.cols == n_in` (down-projection)
27//! - `lora_b.rows == n_out`, `lora_b.cols == rank` (up-projection)
28//! - `lora_a` is initialised with Kaiming uniform; `lora_b` is zeroed (standard LoRA init)
29//! - The checksum covers `lora_a_data ++ lora_b_data` only, not the header
30
31use std::collections::HashMap;
32use std::path::PathBuf;
33
34use super::context_detector::ContextType;
35
36// ─── Errors ──────────────────────────────────────────────────────────────────
37
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub enum LoRAError {
40    Io(String),
41    InvalidHeader,
42    InvalidMagic,
43    ChecksumMismatch,
44    DimensionMismatch {
45        expected: (usize, usize),
46        got: (usize, usize),
47    },
48    AdapterNotFound(ContextType),
49    InferenceDimMismatch {
50        input_len: usize,
51        lora_n_in: usize,
52    },
53}
54
55impl std::fmt::Display for LoRAError {
56    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57        match self {
58            LoRAError::Io(e) => write!(f, "LoRA I/O error: {e}"),
59            LoRAError::InvalidHeader => write!(f, "LoRA header too short"),
60            LoRAError::InvalidMagic => write!(f, "LoRA bad magic (expected LORA)"),
61            LoRAError::ChecksumMismatch => write!(f, "LoRA checksum mismatch"),
62            LoRAError::DimensionMismatch { expected, got } => write!(
63                f,
64                "LoRA dimension mismatch: expected {expected:?}, got {got:?}"
65            ),
66            LoRAError::AdapterNotFound(ctx) => write!(f, "LoRA adapter not found for {ctx}"),
67            LoRAError::InferenceDimMismatch {
68                input_len,
69                lora_n_in,
70            } => write!(
71                f,
72                "LoRA inference: input len {input_len} ≠ lora n_in {lora_n_in}"
73            ),
74        }
75    }
76}
77
78impl std::error::Error for LoRAError {}
79
80// ─── LoRATensor ───────────────────────────────────────────────────────────────
81
82/// Dense f32 matrix stored in row-major order.
83///
84/// Using `Box<[f32]>` (not `Vec`) signals fixed-size after construction.
85#[derive(Clone)]
86pub struct LoRATensor {
87    pub data: Box<[f32]>,
88    pub rows: usize,
89    pub cols: usize,
90}
91
92impl LoRATensor {
93    /// Creates a default `LoRATensor`.
94    pub fn new(data: Box<[f32]>, rows: usize, cols: usize) -> Self {
95        assert_eq!(data.len(), rows * cols, "LoRATensor data length mismatch");
96        Self { data, rows, cols }
97    }
98
99    /// Multiply `self` (rows × cols) by `x` (cols,) → output `(rows,)`.
100    /// Accumulates into `out` (must already be the right length and may be pre-filled).
101    #[inline]
102    pub fn matvec_add(&self, x: &[f32], out: &mut [f32]) {
103        debug_assert_eq!(x.len(), self.cols);
104        debug_assert_eq!(out.len(), self.rows);
105        for i in 0..self.rows {
106            let row = &self.data[i * self.cols..(i + 1) * self.cols];
107            let mut acc = 0f32;
108            for (a, b) in row.iter().zip(x.iter()) {
109                acc += a * b;
110            }
111            out[i] += acc;
112        }
113    }
114}
115
116impl std::fmt::Debug for LoRATensor {
117    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
118        write!(f, "LoRATensor({}×{})", self.rows, self.cols)
119    }
120}
121
122// ─── LoRAMetadata ─────────────────────────────────────────────────────────────
123
124#[derive(Debug, Clone)]
125pub struct LoRAMetadata {
126    pub name: String,
127    pub version: String,
128    pub adapter_id: u8,
129    pub rank: u32,
130    pub alpha: f32,
131    pub n_in: usize,
132    pub n_out: usize,
133    pub checksum: [u8; 32],
134    pub file_size: usize,
135}
136
137impl LoRAMetadata {
138    /// `scaling = alpha / rank` — the factor applied when adding the LoRA delta.
139    #[inline]
140    pub fn scaling(&self) -> f32 {
141        self.alpha / self.rank.max(1) as f32
142    }
143}
144
145// ─── LoRAAdapter ─────────────────────────────────────────────────────────────
146
147/// A loaded LoRA adapter ready for CPU or GPU application.
148#[derive(Debug, Clone)]
149pub struct LoRAAdapter {
150    pub context_type: ContextType,
151    pub meta: LoRAMetadata,
152    /// Down-projection: `[rank × n_in]`
153    pub lora_a: LoRATensor,
154    /// Up-projection: `[n_out × rank]`
155    pub lora_b: LoRATensor,
156}
157
158impl LoRAAdapter {
159    /// Apply the LoRA delta **additively** to `output`.
160    ///
161    /// Implements `output += lora_b @ (lora_a @ input) * scaling` using caller-provided scratch.
162    ///
163    /// - `input` must have length `meta.n_in`
164    /// - `output` must have length `meta.n_out` (values are preserved and incremented)
165    /// - `rank_scratch` must have length >= `meta.rank`
166    pub fn apply_cpu_buffered(
167        &self,
168        input: &[f32],
169        output: &mut [f32],
170        rank_scratch: &mut [f32],
171    ) -> Result<(), LoRAError> {
172        let n_in = self.meta.n_in;
173        let n_out = self.meta.n_out;
174        let rank = self.meta.rank as usize;
175
176        if input.len() != n_in {
177            return Err(LoRAError::InferenceDimMismatch {
178                input_len: input.len(),
179                lora_n_in: n_in,
180            });
181        }
182        if rank_scratch.len() < rank {
183            return Err(LoRAError::InferenceDimMismatch {
184                input_len: rank_scratch.len(),
185                lora_n_in: rank,
186            });
187        }
188
189        // Phase 1 — down-projection: z[rank] = A @ input
190        rank_scratch[..rank].fill(0f32);
191        self.lora_a.matvec_add(input, &mut rank_scratch[..rank]);
192
193        // Phase 2 — up-projection + scaling: output += B @ z * scaling
194        let scaling = self.meta.scaling();
195        for i in 0..n_out {
196            let row = &self.lora_b.data[i * rank..(i + 1) * rank];
197            let mut acc = 0f32;
198            for (bval, zval) in row.iter().zip(rank_scratch[..rank].iter()) {
199                acc += bval * zval;
200            }
201            output[i] += acc * scaling;
202        }
203
204        Ok(())
205    }
206
207    /// Implements `output += lora_b @ (lora_a @ input) * scaling`.
208    ///
209    /// - `input`  must have length `meta.n_in`
210    /// - `output` must have length `meta.n_out` (values are preserved and incremented)
211    pub fn apply_cpu(&self, input: &[f32], output: &mut [f32]) -> Result<(), LoRAError> {
212        let rank = self.meta.rank as usize;
213        let mut z = vec![0f32; rank];
214        self.apply_cpu_buffered(input, output, &mut z)
215    }
216
217    /// Compute the LoRA delta vector without applying it.
218    /// Returns `delta` of length `meta.n_out`.
219    pub fn compute_delta(&self, input: &[f32]) -> Result<Vec<f32>, LoRAError> {
220        let mut delta = vec![0f32; self.meta.n_out];
221        let mut output_ref = vec![0f32; self.meta.n_out];
222        self.apply_cpu(input, &mut output_ref)?;
223        delta.copy_from_slice(&output_ref);
224        Ok(delta)
225    }
226}
227
228// ─── Binary header (64 bytes) ────────────────────────────────────────────────
229
230const HEADER_SIZE: usize = 64;
231const MAGIC: [u8; 4] = *b"LORA";
232
233#[repr(C, packed)]
234struct RawHeader {
235    magic: [u8; 4],
236    version: u32,
237    adapter_id: u8,
238    _pad0: [u8; 3],
239    rank: u32,
240    alpha_bits: u32, // f32 as raw bits (avoids packed f32 UB)
241    n_in: u32,
242    n_out: u32,
243    _pad1: u32,
244    checksum: [u8; 32],
245}
246
247const _: () = assert!(std::mem::size_of::<RawHeader>() == HEADER_SIZE);
248
249// ─── Parser ──────────────────────────────────────────────────────────────────
250
251fn parse_adapter(data: &[u8], context_type: ContextType) -> Result<LoRAAdapter, LoRAError> {
252    if data.len() < HEADER_SIZE {
253        return Err(LoRAError::InvalidHeader);
254    }
255
256    // Safety: data is at least HEADER_SIZE bytes; RawHeader is repr(C, packed).
257    let hdr: RawHeader = unsafe { std::ptr::read_unaligned(data.as_ptr() as *const RawHeader) };
258
259    if hdr.magic != MAGIC {
260        return Err(LoRAError::InvalidMagic);
261    }
262
263    let rank = u32::from_le(hdr.rank) as usize;
264    let alpha = f32::from_bits(u32::from_le(hdr.alpha_bits));
265    let n_in = u32::from_le(hdr.n_in) as usize;
266    let n_out = u32::from_le(hdr.n_out) as usize;
267
268    let a_elems = rank * n_in;
269    let b_elems = n_out * rank;
270    let payload_bytes = (a_elems + b_elems) * 4;
271
272    if data.len() < HEADER_SIZE + payload_bytes {
273        return Err(LoRAError::DimensionMismatch {
274            expected: (a_elems + b_elems, 4),
275            got: (data.len().saturating_sub(HEADER_SIZE), 4),
276        });
277    }
278
279    let payload = &data[HEADER_SIZE..HEADER_SIZE + payload_bytes];
280
281    // Verify SHA-256 checksum over payload
282    let expected = hdr.checksum;
283    let actual = sha256(payload);
284    if actual != expected {
285        return Err(LoRAError::ChecksumMismatch);
286    }
287
288    let a_bytes = &payload[..a_elems * 4];
289    let b_bytes = &payload[a_elems * 4..a_elems * 4 + b_elems * 4];
290
291    let lora_a = LoRATensor::new(f32_slice_from_le_bytes(a_bytes), rank, n_in);
292    let lora_b = LoRATensor::new(f32_slice_from_le_bytes(b_bytes), n_out, rank);
293
294    Ok(LoRAAdapter {
295        context_type,
296        meta: LoRAMetadata {
297            name: format!("{}", context_type),
298            version: format!("{}", u32::from_le(hdr.version)),
299            adapter_id: hdr.adapter_id,
300            rank: rank as u32,
301            alpha,
302            n_in,
303            n_out,
304            checksum: expected,
305            file_size: data.len(),
306        },
307        lora_a,
308        lora_b,
309    })
310}
311
312#[inline]
313fn f32_slice_from_le_bytes(bytes: &[u8]) -> Box<[f32]> {
314    bytes
315        .chunks_exact(4)
316        .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
317        .collect::<Vec<_>>()
318        .into_boxed_slice()
319}
320
321fn sha256(data: &[u8]) -> [u8; 32] {
322    use sha2::{Digest, Sha256};
323    let mut h = Sha256::new();
324    h.update(data);
325    let result = h.finalize();
326    let mut out = [0u8; 32];
327    out.copy_from_slice(&result);
328    out
329}
330
331/// Build a minimal valid `.lora` file from raw A and B matrices.
332/// Useful for generating test adapters and offline tooling.
333pub fn encode_adapter(
334    context_type: ContextType,
335    adapter_id: u8,
336    rank: u32,
337    alpha: f32,
338    lora_a: &LoRATensor, // [rank × n_in]
339    lora_b: &LoRATensor, // [n_out × rank]
340) -> Vec<u8> {
341    let n_in = lora_a.cols;
342    let n_out = lora_b.rows;
343
344    let a_bytes: Vec<u8> = lora_a.data.iter().flat_map(|&f| f.to_le_bytes()).collect();
345    let b_bytes: Vec<u8> = lora_b.data.iter().flat_map(|&f| f.to_le_bytes()).collect();
346    let mut payload = a_bytes;
347    payload.extend_from_slice(&b_bytes);
348    let checksum = sha256(&payload);
349
350    let _ = context_type; // used for naming, not encoded in header
351    let mut hdr = [0u8; HEADER_SIZE];
352    hdr[0..4].copy_from_slice(&MAGIC);
353    hdr[4..8].copy_from_slice(&1u32.to_le_bytes()); // version
354    hdr[8] = adapter_id;
355    hdr[12..16].copy_from_slice(&(rank as u32).to_le_bytes());
356    hdr[16..20].copy_from_slice(&alpha.to_bits().to_le_bytes());
357    hdr[20..24].copy_from_slice(&(n_in as u32).to_le_bytes());
358    hdr[24..28].copy_from_slice(&(n_out as u32).to_le_bytes());
359    hdr[32..64].copy_from_slice(&checksum);
360
361    let mut out = hdr.to_vec();
362    out.extend_from_slice(&payload);
363    out
364}
365
366// ─── LruCache (no external crate) ────────────────────────────────────────────
367
368struct LruCache<K, V> {
369    cap: usize,
370    store: HashMap<K, (V, u64)>,
371    clock: u64,
372}
373
374impl<K: Eq + std::hash::Hash + Clone, V: Clone> LruCache<K, V> {
375    fn new(cap: usize) -> Self {
376        Self {
377            cap: cap.max(1),
378            store: HashMap::new(),
379            clock: 0,
380        }
381    }
382
383    fn get(&mut self, key: &K) -> Option<&V> {
384        if let Some(entry) = self.store.get_mut(key) {
385            self.clock += 1;
386            entry.1 = self.clock;
387            // Safety: we just confirmed the key exists; return a reference.
388            Some(unsafe { &*((&entry.0) as *const V) })
389        } else {
390            None
391        }
392    }
393
394    fn put(&mut self, key: K, val: V) {
395        self.clock += 1;
396        if self.store.len() >= self.cap && !self.store.contains_key(&key) {
397            // Evict LRU entry
398            let lru_key = self
399                .store
400                .iter()
401                .min_by_key(|(_, (_, ts))| ts)
402                .map(|(k, _)| k.clone());
403            if let Some(k) = lru_key {
404                self.store.remove(&k);
405            }
406        }
407        self.store.insert(key, (val, self.clock));
408    }
409
410    fn contains(&self, key: &K) -> bool {
411        self.store.contains_key(key)
412    }
413}
414
415// ─── LoRAAdapterManager ───────────────────────────────────────────────────────
416
417/// Manages LoRA adapter loading, caching, and active-adapter switching.
418///
419/// The manager maintains:
420/// - A filesystem directory for `.lora` files
421/// - An LRU cache of up to 10 loaded adapters (≈150 MB at 15 MB each)
422/// - The currently active adapter (fast path for repeated calls)
423pub struct LoRAAdapterManager {
424    adapter_dir: PathBuf,
425    cache: LruCache<ContextType, LoRAAdapter>,
426    active_adapter: Option<LoRAAdapter>,
427    pub detector: super::context_detector::ContextDetector,
428    /// Expected embedding dimension — used for dim-check at apply time.
429    pub expected_n_in: Option<usize>,
430    /// Expected hidden/output dimension — used for dim-check at apply time.
431    pub expected_n_out: Option<usize>,
432    /// Side-table: NQuin content-hash → active adapter ID.
433    /// Replaces the retired metadata bit-packing (§4.1 migration).
434    active_adapter_by_hash: std::collections::HashMap<u64, u64>,
435}
436
437impl LoRAAdapterManager {
438    /// Create a manager pointing at `adapter_dir`.
439    ///
440    /// The directory does not need to exist at construction time; adapters
441    /// are loaded lazily on first `switch_to`.
442    pub fn new(adapter_dir: impl Into<PathBuf>) -> Self {
443        Self {
444            adapter_dir: adapter_dir.into(),
445            cache: LruCache::new(10),
446            active_adapter: None,
447            detector: super::context_detector::ContextDetector::new(),
448            expected_n_in: None,
449            expected_n_out: None,
450            active_adapter_by_hash: std::collections::HashMap::new(),
451        }
452    }
453
454    /// Standard location: `~/.qualia/lora_adapters/`
455    pub fn default_path() -> PathBuf {
456        let home = std::env::var("HOME")
457            .or_else(|_| std::env::var("USERPROFILE"))
458            .unwrap_or_else(|_| ".".to_string());
459        PathBuf::from(home).join(".qualia").join("lora_adapters")
460    }
461
462    /// Hint the expected input/output dimensions so that mis-shaped adapters
463    /// are rejected early rather than causing panic in `apply_cpu`.
464    pub fn set_expected_dims(&mut self, n_in: usize, n_out: usize) {
465        self.expected_n_in = Some(n_in);
466        self.expected_n_out = Some(n_out);
467    }
468
469    // ── Context detection ────────────────────────────────────────────────────
470
471    /// Detect `ContextType` from prompt text.
472    /// LoRA context is no longer encoded in NQuin metadata bits (§4.1 migration);
473    /// use `active_adapter_for_hash()` to look up the adapter for a specific quin.
474    pub fn detect_context(&self, prompt: &str) -> (ContextType, f32) {
475        self.detector.analyze_text(prompt)
476    }
477
478    /// Look up the active adapter ID for a given NQuin content-hash.
479    /// Returns `None` if no adapter has been associated with that quin.
480    pub fn active_adapter_for_hash(&self, content_hash: u64) -> Option<u64> {
481        self.active_adapter_by_hash.get(&content_hash).copied()
482    }
483
484    /// Associate an adapter ID with a NQuin content-hash in the side-table.
485    pub fn set_adapter_for_hash(&mut self, content_hash: u64, adapter_id: u64) {
486        self.active_adapter_by_hash.insert(content_hash, adapter_id);
487    }
488
489    /// Remove all side-table associations (e.g. at end of an inference batch).
490    pub fn clear_hash_associations(&mut self) {
491        self.active_adapter_by_hash.clear();
492    }
493
494    // ── Adapter switching ────────────────────────────────────────────────────
495
496    /// Ensure the adapter for `target` is loaded and set as active.
497    ///
498    /// Returns `Ok(true)` if a switch occurred, `Ok(false)` if already active.
499    pub fn switch_to(&mut self, target: ContextType) -> Result<bool, LoRAError> {
500        // Already active — nothing to do
501        if let Some(ref a) = self.active_adapter {
502            if a.context_type == target {
503                return Ok(false);
504            }
505        }
506
507        // Promote from cache
508        if self.cache.contains(&target) {
509            let adapter = self.cache.get(&target).unwrap().clone();
510            self.active_adapter = Some(adapter);
511            return Ok(true);
512        }
513
514        // Load from disk
515        let adapter = self.load_from_disk(target)?;
516
517        // Validate dimensions if hints are available
518        if let Some(n_in) = self.expected_n_in {
519            if adapter.meta.n_in != n_in {
520                return Err(LoRAError::DimensionMismatch {
521                    expected: (n_in, adapter.meta.n_out),
522                    got: (adapter.meta.n_in, adapter.meta.n_out),
523                });
524            }
525        }
526
527        self.cache.put(target, adapter.clone());
528        self.active_adapter = Some(adapter);
529        Ok(true)
530    }
531
532    /// Detect context from `prompt` and switch adapter if confidence exceeds `threshold`.
533    ///
534    /// Returns `(context_type, confidence, switched)`.
535    pub fn auto_switch(&mut self, prompt: &str, threshold: f32) -> (ContextType, f32, bool) {
536        let (ctx, conf) = self.detect_context(prompt);
537
538        if conf < threshold {
539            return (ContextType::General, conf, false);
540        }
541
542        let switched = self.switch_to(ctx).unwrap_or(false);
543        (ctx, conf, switched)
544    }
545
546    // ── Inference integration ────────────────────────────────────────────────
547
548    /// Apply the active adapter's delta to `output` (if any adapter is loaded).
549    ///
550    /// `input` is the current hidden-state vector before the LoRA correction.
551    /// `output` is incremented in-place: `output += B @ (A @ input) * scaling`.
552    pub fn apply_active(&self, input: &[f32], output: &mut [f32]) -> Result<(), LoRAError> {
553        match &self.active_adapter {
554            Some(a) => a.apply_cpu(input, output),
555            None => Ok(()),
556        }
557    }
558
559    /// Return a reference to the active adapter, if any.
560    pub fn active(&self) -> Option<&LoRAAdapter> {
561        self.active_adapter.as_ref()
562    }
563
564    /// Clear the active adapter (revert to base model behaviour).
565    pub fn deactivate(&mut self) {
566        self.active_adapter = None;
567    }
568
569    // ── Disk I/O ─────────────────────────────────────────────────────────────
570
571    fn adapter_path(&self, ctx: ContextType) -> PathBuf {
572        self.adapter_dir.join(ctx.adapter_filename())
573    }
574
575    fn load_from_disk(&self, ctx: ContextType) -> Result<LoRAAdapter, LoRAError> {
576        let path = self.adapter_path(ctx);
577
578        // memmap2 for zero-copy loading
579        #[cfg(not(target_arch = "wasm32"))]
580        {
581            use std::fs::File;
582            let file =
583                File::open(&path).map_err(|e| LoRAError::Io(format!("{}: {e}", path.display())))?;
584            let mmap = unsafe { memmap2::MmapOptions::new().map(&file) }
585                .map_err(|e| LoRAError::Io(format!("mmap {}: {e}", path.display())))?;
586            parse_adapter(&mmap, ctx)
587        }
588
589        #[cfg(target_arch = "wasm32")]
590        {
591            let data = std::fs::read(&path)
592                .map_err(|e| LoRAError::Io(format!("{}: {e}", path.display())))?;
593            parse_adapter(&data, ctx)
594        }
595    }
596
597    /// Check which adapters exist on disk (for UI / resource catalog).
598    pub fn available_adapters(&self) -> Vec<ContextType> {
599        ContextType::all()
600            .iter()
601            .filter(|&&ctx| self.adapter_path(ctx).exists())
602            .copied()
603            .collect()
604    }
605
606    /// Persist an adapter to disk in the `.lora` binary format.
607    pub fn save_adapter(
608        &self,
609        ctx: ContextType,
610        adapter: &LoRAAdapter,
611    ) -> Result<PathBuf, LoRAError> {
612        let path = self.adapter_path(ctx);
613        if let Some(parent) = path.parent() {
614            std::fs::create_dir_all(parent).map_err(|e| LoRAError::Io(e.to_string()))?;
615        }
616        let bytes = encode_adapter(
617            ctx,
618            adapter.meta.adapter_id,
619            adapter.meta.rank,
620            adapter.meta.alpha,
621            &adapter.lora_a,
622            &adapter.lora_b,
623        );
624        std::fs::write(&path, &bytes).map_err(|e| LoRAError::Io(e.to_string()))?;
625        Ok(path)
626    }
627
628    /// Build a synthetic adapter populated with Kaiming-uniform A / zero B weights.
629    /// Used for fine-tuning initialisation and test harness.
630    pub fn build_synthetic(
631        ctx: ContextType,
632        rank: u32,
633        alpha: f32,
634        n_in: usize,
635        n_out: usize,
636        adapter_id: u8,
637    ) -> LoRAAdapter {
638        let scale = (2.0 / n_in as f32).sqrt();
639        // Kaiming uniform: U(-scale, scale)
640        let seed_a: Box<[f32]> = (0..rank as usize * n_in)
641            .map(|i| {
642                // Deterministic pseudo-random without rand dep: LCG
643                let x = (i as u64)
644                    .wrapping_mul(6364136223846793005)
645                    .wrapping_add(1442695040888963407);
646                let frac = (x >> 32) as f32 / u32::MAX as f32; // [0, 1)
647                (frac * 2.0 - 1.0) * scale
648            })
649            .collect::<Vec<_>>()
650            .into_boxed_slice();
651
652        let seed_b = vec![0f32; n_out * rank as usize].into_boxed_slice();
653
654        let lora_a = LoRATensor::new(seed_a, rank as usize, n_in);
655        let lora_b = LoRATensor::new(seed_b, n_out, rank as usize);
656
657        LoRAAdapter {
658            context_type: ctx,
659            meta: LoRAMetadata {
660                name: ctx.to_string(),
661                version: "synthetic".to_string(),
662                adapter_id,
663                rank,
664                alpha,
665                n_in,
666                n_out,
667                checksum: [0u8; 32],
668                file_size: 0,
669            },
670            lora_a,
671            lora_b,
672        }
673    }
674}
675
676// ─── Tests ───────────────────────────────────────────────────────────────────
677
678#[cfg(test)]
679mod tests {
680    use super::*;
681
682    fn make_adapter(rank: u32, n_in: usize, n_out: usize) -> LoRAAdapter {
683        LoRAAdapterManager::build_synthetic(
684            ContextType::Technical,
685            rank,
686            rank as f32,
687            n_in,
688            n_out,
689            5,
690        )
691    }
692
693    #[test]
694    fn test_apply_cpu_shape() {
695        let adapter = make_adapter(4, 16, 32);
696        let input = vec![1.0f32; 16];
697        let mut out = vec![0.0f32; 32];
698        adapter.apply_cpu(&input, &mut out).unwrap();
699        // lora_b is zeroed → delta = 0; output stays all-zero
700        assert!(out.iter().all(|&v| v == 0.0));
701    }
702
703    #[test]
704    fn test_apply_cpu_nonzero() {
705        // Build adapter with non-zero lora_b so we can check the delta path
706        let rank = 2usize;
707        let n_in = 4;
708        let n_out = 4;
709        let lora_a = LoRATensor::new(vec![1.0; rank * n_in].into_boxed_slice(), rank, n_in);
710        let lora_b = LoRATensor::new(vec![1.0; n_out * rank].into_boxed_slice(), n_out, rank);
711        let adapter = LoRAAdapter {
712            context_type: ContextType::Technical,
713            meta: LoRAMetadata {
714                name: "test".into(),
715                version: "0".into(),
716                adapter_id: 0,
717                rank: rank as u32,
718                alpha: rank as f32,
719                n_in,
720                n_out,
721                checksum: [0; 32],
722                file_size: 0,
723            },
724            lora_a,
725            lora_b,
726        };
727        let input = vec![1.0f32; n_in];
728        let mut out = vec![0.0f32; n_out];
729        adapter.apply_cpu(&input, &mut out).unwrap();
730        // With all-one A and all-one B and input=[1,1,1,1]:
731        // z[k] = sum_j(A[k,j]*x[j]) = n_in = 4  for each k
732        // delta[i] = sum_k(B[i,k]*z[k])*scaling = rank * n_in * scaling
733        // scaling = alpha/rank = 1
734        // delta[i] = 2 * 4 * 1 = 8
735        for &v in &out {
736            assert!((v - 8.0).abs() < 1e-5, "expected 8.0, got {v}");
737        }
738    }
739
740    #[test]
741    fn test_roundtrip_encode_parse() {
742        let adapter = make_adapter(4, 8, 16);
743        let bytes = encode_adapter(
744            ContextType::Technical,
745            adapter.meta.adapter_id,
746            adapter.meta.rank,
747            adapter.meta.alpha,
748            &adapter.lora_a,
749            &adapter.lora_b,
750        );
751        let parsed = parse_adapter(&bytes, ContextType::Technical).unwrap();
752        assert_eq!(parsed.meta.rank, adapter.meta.rank);
753        assert_eq!(parsed.meta.n_in, adapter.meta.n_in);
754        assert_eq!(parsed.meta.n_out, adapter.meta.n_out);
755        assert_eq!(parsed.lora_a.data.len(), adapter.lora_a.data.len());
756        for (a, b) in parsed.lora_a.data.iter().zip(adapter.lora_a.data.iter()) {
757            assert!(
758                (a - b).abs() < 1e-6,
759                "A matrix roundtrip mismatch: {a} vs {b}"
760            );
761        }
762    }
763
764    #[test]
765    fn test_bad_magic_rejected() {
766        let mut bytes = encode_adapter(
767            ContextType::Medical,
768            0,
769            4,
770            1.0,
771            &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 1, 4),
772            &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 4, 1),
773        );
774        bytes[0] = b'X'; // corrupt magic
775        assert!(matches!(
776            parse_adapter(&bytes, ContextType::Medical),
777            Err(LoRAError::InvalidMagic)
778        ));
779    }
780
781    #[test]
782    fn test_checksum_corruption_detected() {
783        // Use rank=1 so tensor dimensions are consistent with the header:
784        //   lora_a: [rank × n_in] = [1 × 4] = 4 elements
785        //   lora_b: [n_out × rank] = [4 × 1] = 4 elements
786        // The earlier test_bad_magic_rejected used rank=4 with the same small tensors
787        // (1×4 and 4×1), which makes the header declare 16 elements per matrix but only
788        // 4 are present — parse_adapter rejects that with DimensionMismatch before it
789        // ever reaches the checksum.  rank=1 makes header and payload agree so the
790        // checksum is actually verified, and the byte flip produces ChecksumMismatch.
791        let mut bytes = encode_adapter(
792            ContextType::Medical,
793            0,
794            1,
795            1.0,
796            &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 1, 4),
797            &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 4, 1),
798        );
799        // Flip a payload byte to corrupt the data without touching the stored checksum
800        *bytes.last_mut().unwrap() ^= 0xFF;
801        assert!(matches!(
802            parse_adapter(&bytes, ContextType::Medical),
803            Err(LoRAError::ChecksumMismatch)
804        ));
805    }
806
807    #[test]
808    fn test_synthetic_output_zeroed_initially() {
809        let adapter =
810            LoRAAdapterManager::build_synthetic(ContextType::Biological, 8, 8.0, 32, 64, 4);
811        // lora_b is all-zero → delta is always zero regardless of input
812        let input = vec![1.0f32; 32];
813        let mut out = vec![0.0f32; 64];
814        adapter.apply_cpu(&input, &mut out).unwrap();
815        assert!(out.iter().all(|&v| v == 0.0));
816    }
817
818    #[test]
819    fn test_lru_eviction() {
820        let mut cache: LruCache<u32, u32> = LruCache::new(3);
821        cache.put(1, 10);
822        cache.put(2, 20);
823        cache.put(3, 30);
824        let _ = cache.get(&1); // touch 1 so 2 is now LRU
825        cache.put(4, 40); // evicts 2 (LRU)
826        assert!(!cache.contains(&2));
827        assert!(cache.contains(&1));
828        assert!(cache.contains(&3));
829        assert!(cache.contains(&4));
830    }
831
832    #[test]
833    fn test_manager_auto_switch_below_threshold() {
834        let mgr = LoRAAdapterManager::new("/tmp/nonexistent_lora");
835        // analyze_text returns (ContextType, f32); "hello world" has no domain keywords
836        let (ctx, conf) = mgr.detector.analyze_text("hello world");
837        assert_eq!(ctx, ContextType::General);
838        assert!(conf < mgr.detector.confidence_threshold);
839    }
840}