Skip to main content

qualia_client_core/
model_lifecycle.rs

1//! Catalog LLM download → GGUF shard map → WAL → lifecycle (in-process).
2
3use std::path::{Path, PathBuf};
4use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
5use std::sync::{Arc, OnceLock};
6
7use qualia_core_db::{
8    gguf_sharder::GGufSharder,
9    llm_agent::{AgentBackend, LocalLlmAgent},
10    orchestrator::{ModelLifecycle, NullThermalGovernor, TaskOrchestrator},
11    q_hash,
12    resource_catalog::{LLMResource, ResourceCatalog},
13    wal::WriteAheadLog,
14};
15use serde::{Deserialize, Serialize};
16use sha2::{Digest, Sha256};
17
18#[derive(Debug)]
19pub enum ModelError {
20    NotFound(String),
21    NoDownloadUrl(String),
22    Download(String),
23    Shard(String),
24    Wal(String),
25    Activate(String),
26    Io(std::io::Error),
27    Json(serde_json::Error),
28}
29
30impl std::fmt::Display for ModelError {
31    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
32        match self {
33            ModelError::NotFound(id) => write!(f, "LLM not found in catalog: {id}"),
34            ModelError::NoDownloadUrl(id) => write!(f, "No download URL for: {id}"),
35            ModelError::Download(e) => write!(f, "Download failed: {e}"),
36            ModelError::Shard(e) => write!(f, "GGUF shard map failed: {e}"),
37            ModelError::Wal(e) => write!(f, "WAL write failed: {e}"),
38            ModelError::Activate(e) => write!(f, "Model activation failed: {e}"),
39            ModelError::Io(e) => write!(f, "IO error: {e}"),
40            ModelError::Json(e) => write!(f, "JSON error: {e}"),
41        }
42    }
43}
44
45impl From<std::io::Error> for ModelError {
46    fn from(e: std::io::Error) -> Self {
47        ModelError::Io(e)
48    }
49}
50
51impl From<serde_json::Error> for ModelError {
52    fn from(e: serde_json::Error) -> Self {
53        ModelError::Json(e)
54    }
55}
56
57#[derive(Debug, Clone, Serialize, Deserialize)]
58pub struct ActiveModelRecord {
59    pub model_id: String,
60    pub gguf_path: String,
61    pub profile_id: u64,
62    pub quantization: String,
63    pub lifecycle_state: String,
64    #[serde(default)]
65    pub modality: String,
66    #[serde(default)]
67    pub architecture: Option<String>,
68    #[serde(default)]
69    pub mmproj_path: Option<String>,
70    #[serde(default)]
71    pub context_window: u32,
72}
73
74#[derive(Debug, Clone, Serialize)]
75pub struct ModelInstallResult {
76    pub model_id: String,
77    pub gguf_path: String,
78    pub profile_id: u64,
79    pub pointer_quin_count: usize,
80    pub vision_pointer_quin_count: usize,
81    pub lifecycle_state: String,
82    pub wal_path: String,
83    pub modality: String,
84    pub mmproj_path: Option<String>,
85}
86
87#[derive(Debug, Clone, Serialize)]
88pub struct ModelStatus {
89    pub active: Option<ActiveModelRecord>,
90    pub lifecycle_state: String,
91    pub profile_id: Option<u64>,
92}
93
94#[derive(Debug, Clone, Serialize, Deserialize)]
95pub struct InstallManifest {
96    pub model_id: String,
97    pub gguf_path: String,
98    pub profile_id: u64,
99    pub quantization: String,
100    pub pointer_quin_count: usize,
101    pub vision_pointer_quin_count: usize,
102    pub installed_at: u64,
103    pub wal_path: String,
104    pub modality: String,
105    pub architecture: Option<String>,
106    pub mmproj_path: Option<String>,
107    pub context_window: u32,
108}
109
110fn orchestrator() -> Arc<TaskOrchestrator> {
111    task_orchestrator()
112}
113
114/// Shared orchestrator for chat inference and model lifecycle transitions.
115pub fn task_orchestrator() -> Arc<TaskOrchestrator> {
116    static ORCH: OnceLock<Arc<TaskOrchestrator>> = OnceLock::new();
117    ORCH.get_or_init(|| Arc::new(TaskOrchestrator::new(Box::new(NullThermalGovernor))))
118        .clone()
119}
120
121/// UI RAM ceiling for LLM arena pressure (matches 0.0.12 Flutter plan).
122pub const MEMORY_FLOOR_MB: u32 = 512;
123
124static LLM_MEMORY_BYTES: AtomicU64 = AtomicU64::new(0);
125static KV_CACHE_USED_MB: AtomicU32 = AtomicU32::new(0);
126/// Last completed chat/decode throughput × 1000 (tok/s), or 0 if never measured.
127static LAST_DECODE_TOK_S_MILLI: AtomicU32 = AtomicU32::new(0);
128/// Unix-ish stamp (secs since process start not required — wall via duration store is enough).
129static LAST_DECODE_TOK_S_AT_SECS: AtomicU64 = AtomicU64::new(0);
130
131/// Records LLM memory bytes.
132pub fn record_llm_memory_bytes(bytes: u64) {
133    LLM_MEMORY_BYTES.store(bytes, Ordering::Relaxed);
134}
135
136/// Records an LLM memory sample.
137pub fn record_llm_memory_sample(bytes: u64) {
138    if bytes == 0 {
139        return;
140    }
141    let mut current = LLM_MEMORY_BYTES.load(Ordering::Relaxed);
142    while bytes > current {
143        match LLM_MEMORY_BYTES.compare_exchange(
144            current,
145            bytes,
146            Ordering::Relaxed,
147            Ordering::Relaxed,
148        ) {
149            Ok(_) => return,
150            Err(observed) => current = observed,
151        }
152    }
153}
154
155/// Gets llm-memory-bytes.
156pub fn get_llm_memory_bytes() -> u64 {
157    LLM_MEMORY_BYTES.load(Ordering::Relaxed)
158}
159
160/// Records KV-cache usage.
161pub fn record_kv_cache_used_mb(megabytes: u32) {
162    KV_CACHE_USED_MB.store(megabytes, Ordering::Relaxed);
163}
164
165/// Gets kv-cache-used-mb.
166pub fn get_kv_cache_used_mb() -> u32 {
167    KV_CACHE_USED_MB.load(Ordering::Relaxed)
168}
169
170/// Record measured decode/chat throughput from a completed generation turn.
171///
172/// Call only with real token counts and wall time — never synthetic marketing numbers.
173pub fn record_last_decode_tok_s(tokens: u32, duration_ms: u64) {
174    if tokens == 0 || duration_ms == 0 {
175        return;
176    }
177    let tok_s = (tokens as f64) / (duration_ms as f64 / 1000.0);
178    if !tok_s.is_finite() || tok_s <= 0.0 {
179        return;
180    }
181    let milli = (tok_s * 1000.0).round().clamp(0.0, u32::MAX as f64) as u32;
182    LAST_DECODE_TOK_S_MILLI.store(milli, Ordering::Relaxed);
183    let now = std::time::SystemTime::now()
184        .duration_since(std::time::UNIX_EPOCH)
185        .map(|d| d.as_secs())
186        .unwrap_or(0);
187    LAST_DECODE_TOK_S_AT_SECS.store(now, Ordering::Relaxed);
188}
189
190/// Last measured tok/s from a completed turn, or `None` if never measured this process.
191pub fn get_last_decode_tok_s() -> Option<f64> {
192    let milli = LAST_DECODE_TOK_S_MILLI.load(Ordering::Relaxed);
193    if milli == 0 {
194        None
195    } else {
196        Some(milli as f64 / 1000.0)
197    }
198}
199
200/// Gets last-decode-tok-s-at-unix.
201pub fn get_last_decode_tok_s_at_unix() -> u64 {
202    LAST_DECODE_TOK_S_AT_SECS.load(Ordering::Relaxed)
203}
204
205/// Gets thermal-state-label.
206pub fn get_thermal_state_label() -> &'static str {
207    orchestrator().thermal_state_label()
208}
209
210/// Models directory.
211pub fn models_dir(storage_root: &Path) -> PathBuf {
212    storage_root.join("Models")
213}
214
215/// `lifecycle` label.
216pub fn lifecycle_label(state: ModelLifecycle) -> &'static str {
217    match state {
218        ModelLifecycle::Discovered => "Discovered",
219        ModelLifecycle::MappedToDisk => "MappedToDisk",
220        ModelLifecycle::StreamingVRAM => "StreamingVRAM",
221        ModelLifecycle::Active => "Active",
222        ModelLifecycle::Scrubbing => "Scrubbing",
223    }
224}
225
226fn probe_and_activate_model(
227    agent: &LocalLlmAgent,
228    profile_id: u64,
229    model_label: &str,
230    gguf_path: &str,
231) -> Result<(), ModelError> {
232    let orch = orchestrator();
233    if let Some(resident) = orch.resident_model_id() {
234        if resident != profile_id {
235            log::info!(
236                "LLM_LOAD|unload-start|0.01|Evicting resident model 0x{resident:016x} before loading {}",
237                model_label
238            );
239            orch.evict_model(resident);
240            let wait_started = std::time::Instant::now();
241            while orch.scrubbing_lock.load(Ordering::Acquire) {
242                if wait_started.elapsed() > std::time::Duration::from_secs(5) {
243                    log::error!("LLM_LOAD|failed|1.00|Timed out waiting for prior model eviction");
244                    return Err(ModelError::Activate(
245                        "Timed out waiting for prior model eviction".to_string(),
246                    ));
247                }
248                std::thread::sleep(std::time::Duration::from_millis(5));
249            }
250            record_llm_memory_bytes(0);
251            record_kv_cache_used_mb(0);
252            log::info!("LLM_LOAD|unload-done|0.03|Previous resident model scrubbed from memory");
253        }
254    }
255    let mut sys = sysinfo::System::new_all();
256    sys.refresh_memory();
257    let ram_total_gib = sys.total_memory() as f64 / 1024.0 / 1024.0 / 1024.0;
258    let ram_used_gib = sys.used_memory() as f64 / 1024.0 / 1024.0 / 1024.0;
259    let ram_free_gib = (ram_total_gib - ram_used_gib).max(0.0);
260    {
261        let mut state = orch.current_model_state.lock().unwrap();
262        *state = ModelLifecycle::MappedToDisk;
263        *state = ModelLifecycle::StreamingVRAM;
264    }
265    log::info!("LLM_LOAD|prepare|0.02|Preparing model {}", model_label);
266    log::info!(
267        "LLM_LOAD|ram-check|0.04|System RAM {:.1}/{:.1} GiB used; {:.1} GiB available",
268        ram_used_gib,
269        ram_total_gib,
270        ram_free_gib
271    );
272    match qualia_core_db::resident_model::mount_resident_gguf(
273        profile_id,
274        gguf_path,
275        orch.mlock_enabled
276            .load(std::sync::atomic::Ordering::Relaxed),
277    ) {
278        Ok(report) => {
279            let kv_cache_mb = (report.kv_cache_bytes / (1024 * 1024)).min(u32::MAX as u64) as u32;
280            record_llm_memory_bytes(report.mapped_bytes);
281            record_kv_cache_used_mb(kv_cache_mb);
282            if let Err(err) = orch.load_model(agent, profile_id) {
283                log::error!("LLM_LOAD|failed|1.00|Activation failed: {}", err);
284                return Err(ModelError::Activate(err.to_string()));
285            }
286            orch.register_resident_model(profile_id, report.mapped_bytes + report.kv_cache_bytes);
287            log::info!(
288                "LLM_LOAD|placement|0.96|Model mapped in system RAM ({:.2} GiB) and KV cache reserved in VRAM/system memory ({} MiB)",
289                report.mapped_bytes as f64 / (1024.0 * 1024.0 * 1024.0),
290                kv_cache_mb
291            );
292            log::info!(
293                "LLM_LOAD|active|1.00|Model ready (mapped {:.2} GiB, kv {} MiB, backend {})",
294                report.mapped_bytes as f64 / (1024.0 * 1024.0 * 1024.0),
295                kv_cache_mb,
296                if report.directml_enabled {
297                    "DirectML+wgpu"
298                } else {
299                    "wgpu"
300                }
301            );
302        }
303        Err(err) => {
304            record_llm_memory_bytes(0);
305            record_kv_cache_used_mb(0);
306            let mut state = orch.current_model_state.lock().unwrap();
307            *state = ModelLifecycle::MappedToDisk;
308            log::error!("LLM_LOAD|failed|1.00|Activation failed: {}", err);
309            return Err(ModelError::Activate(err));
310        }
311    }
312    Ok(())
313}
314
315/// Unloads the active model.
316pub fn unload_active_model(profile_id: Option<u64>) {
317    let orch = orchestrator();
318    let resident = profile_id.or_else(|| orch.resident_model_id());
319    if let Some(model_id) = resident {
320        log::info!("LLM_LOAD|unload-start|0.00|Unloading resident model 0x{model_id:016x}");
321        orch.evict_model(model_id);
322        let wait_started = std::time::Instant::now();
323        while orch.scrubbing_lock.load(Ordering::Acquire) {
324            if wait_started.elapsed() > std::time::Duration::from_secs(5) {
325                log::warn!("LLM_LOAD|failed|1.00|Timed out waiting for model scrub");
326                break;
327            }
328            std::thread::sleep(std::time::Duration::from_millis(5));
329        }
330        log::info!("LLM_LOAD|unload-done|1.00|Model memory scrub complete");
331    }
332    record_llm_memory_bytes(0);
333    record_kv_cache_used_mb(0);
334}
335
336fn unix_now() -> u64 {
337    std::time::SystemTime::now()
338        .duration_since(std::time::UNIX_EPOCH)
339        .unwrap_or_default()
340        .as_secs()
341}
342
343fn llm_filename(model: &LLMResource) -> String {
344    model
345        .download
346        .local_filename()
347        .unwrap_or_else(|| format!("{}.gguf", model.id))
348}
349
350fn install_manifest_path(models_dir: &Path, model_id: &str) -> PathBuf {
351    models_dir.join(format!("{model_id}.install.json"))
352}
353
354fn projector_filename(model: &LLMResource) -> Option<String> {
355    model.vision_projector.as_ref().and_then(|d| {
356        d.local_filename().or_else(|| {
357            d.resolved_url()
358                .and_then(|u| u.rsplit('/').next().map(|s| s.to_string()))
359        })
360    })
361}
362
363fn write_install_manifest(
364    models_dir: &Path,
365    model: &LLMResource,
366    gguf_path: &Path,
367    mmproj_path: Option<&Path>,
368    profile_id: u64,
369    pointer_quin_count: usize,
370    vision_pointer_quin_count: usize,
371    wal_path: &Path,
372) -> Result<(), ModelError> {
373    let modality = if model.is_multimodal() {
374        "multimodal".to_string()
375    } else {
376        "text".to_string()
377    };
378    let manifest = InstallManifest {
379        model_id: model.id.clone(),
380        gguf_path: gguf_path.to_string_lossy().into_owned(),
381        profile_id,
382        quantization: model
383            .quantization
384            .clone()
385            .unwrap_or_else(|| "Q4_K_M".to_string()),
386        pointer_quin_count,
387        vision_pointer_quin_count,
388        installed_at: unix_now(),
389        wal_path: wal_path.to_string_lossy().into_owned(),
390        modality: modality.clone(),
391        architecture: model.architecture.clone(),
392        mmproj_path: mmproj_path.map(|p| p.to_string_lossy().into_owned()),
393        context_window: model.effective_context_window(),
394    };
395    let json = serde_json::to_string_pretty(&manifest)?;
396    std::fs::write(install_manifest_path(models_dir, &model.id), json)?;
397    Ok(())
398}
399
400/// Finalizes an LLM install.
401pub fn finalize_llm_install(
402    model: &LLMResource,
403    gguf_path: &Path,
404    mmproj_path: Option<&Path>,
405    storage_root: &Path,
406) -> Result<ModelInstallResult, ModelError> {
407    let models = models_dir(storage_root);
408    std::fs::create_dir_all(&models)?;
409
410    if !gguf_path.is_file() {
411        return Err(ModelError::Io(std::io::Error::new(
412            std::io::ErrorKind::NotFound,
413            format!("GGUF not found: {}", gguf_path.display()),
414        )));
415    }
416
417    if model.is_multimodal() && mmproj_path.is_none() {
418        return Err(ModelError::Shard(
419            "Multimodal model requires vision projector (mmproj) GGUF".to_string(),
420        ));
421    }
422
423    let path_str = gguf_path.to_string_lossy().into_owned();
424    let sharder = GGufSharder::new(path_str.clone());
425    let mut pointer_quins = sharder.generate_bidx_pointer_map();
426    let mut vision_pointer_quin_count = 0usize;
427
428    if let Some(mmproj) = mmproj_path {
429        if !mmproj.is_file() {
430            return Err(ModelError::Io(std::io::Error::new(
431                std::io::ErrorKind::NotFound,
432                format!("mmproj not found: {}", mmproj.display()),
433            )));
434        }
435        let mmproj_str = mmproj.to_string_lossy().into_owned();
436        let vision_sharder = GGufSharder::new(mmproj_str);
437        let vision_quins = vision_sharder.generate_bidx_pointer_map();
438        vision_pointer_quin_count = vision_quins.len();
439        pointer_quins.extend(vision_quins);
440    }
441
442    let wal_path = models.join("models.wal");
443    let mut wal = WriteAheadLog::open(&wal_path)
444        .map_err(|e| ModelError::Wal(format!("Cannot open {}: {}", wal_path.display(), e)))?;
445
446    let timestamp = unix_now();
447    let prov = model.provenance_quin(timestamp, &path_str);
448    wal.append_mutation(&prov)
449        .map_err(|e| ModelError::Wal(e.to_string()))?;
450
451    if let Some(src_quin) = model.source_url_quin() {
452        wal.append_mutation(&src_quin)
453            .map_err(|e| ModelError::Wal(e.to_string()))?;
454    }
455
456    for q in &pointer_quins {
457        wal.append_mutation(q)
458            .map_err(|e| ModelError::Wal(e.to_string()))?;
459    }
460
461    for q in &model.to_quins() {
462        wal.append_mutation(q)
463            .map_err(|e| ModelError::Wal(e.to_string()))?;
464    }
465
466    let mmproj_str = mmproj_path.map(|p| p.to_string_lossy().into_owned());
467    let profile = model.to_capability_profile_with_projector(&path_str, mmproj_str.as_deref());
468    write_install_manifest(
469        &models,
470        model,
471        gguf_path,
472        mmproj_path,
473        profile.profile_id,
474        pointer_quins
475            .len()
476            .saturating_sub(vision_pointer_quin_count),
477        vision_pointer_quin_count,
478        &wal_path,
479    )?;
480
481    {
482        let orch = orchestrator();
483        let mut state = orch.current_model_state.lock().unwrap();
484        *state = ModelLifecycle::MappedToDisk;
485    }
486
487    let modality = if model.is_multimodal() {
488        "multimodal".to_string()
489    } else {
490        "text".to_string()
491    };
492
493    Ok(ModelInstallResult {
494        model_id: model.id.clone(),
495        gguf_path: path_str,
496        profile_id: profile.profile_id,
497        pointer_quin_count: pointer_quins
498            .len()
499            .saturating_sub(vision_pointer_quin_count),
500        vision_pointer_quin_count,
501        lifecycle_state: lifecycle_label(ModelLifecycle::MappedToDisk).to_string(),
502        wal_path: wal_path.to_string_lossy().into_owned(),
503        modality,
504        mmproj_path: mmproj_str,
505    })
506}
507
508/// Installs a catalog LLM.
509pub async fn install_catalog_llm(
510    catalog: &ResourceCatalog,
511    id: &str,
512    storage_root: &Path,
513) -> Result<ModelInstallResult, ModelError> {
514    let model = catalog
515        .find_llm(id)
516        .ok_or_else(|| ModelError::NotFound(id.to_string()))?;
517
518    let url = model
519        .download
520        .resolved_url()
521        .ok_or_else(|| ModelError::NoDownloadUrl(id.to_string()))?;
522
523    let models = models_dir(storage_root);
524    std::fs::create_dir_all(&models)?;
525
526    let filename = llm_filename(model);
527    let local_path = models.join(&filename);
528
529    crate::resource_import::stream_download(&url, &local_path)
530        .await
531        .map_err(ModelError::Download)?;
532
533    let mmproj_path = if let (Some(ref vp), Some(vp_url)) = (
534        model.vision_projector.as_ref(),
535        model
536            .vision_projector
537            .as_ref()
538            .and_then(|d| d.resolved_url()),
539    ) {
540        let vp_name = projector_filename(model).unwrap_or_else(|| "mmproj.gguf".to_string());
541        let vp_path = models.join(&vp_name);
542        crate::resource_import::stream_download(&vp_url, &vp_path)
543            .await
544            .map_err(ModelError::Download)?;
545        let _ = vp;
546        Some(vp_path)
547    } else {
548        None
549    };
550
551    finalize_llm_install(model, &local_path, mmproj_path.as_deref(), storage_root)
552}
553
554/// Loads install-manifest.
555pub fn load_install_manifest(storage_root: &Path, model_id: &str) -> Option<InstallManifest> {
556    let path = install_manifest_path(&models_dir(storage_root), model_id);
557    let text = std::fs::read_to_string(path).ok()?;
558    serde_json::from_str(&text).ok()
559}
560
561fn sanitize_local_model_id(stem: &str) -> String {
562    let cleaned: String = stem
563        .chars()
564        .map(|c| {
565            if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
566                c
567            } else {
568                '_'
569            }
570        })
571        .collect();
572    if cleaned.is_empty() {
573        "local-model".to_string()
574    } else {
575        cleaned
576    }
577}
578
579/// Discovered weight container in a vault directory (CLI / lifecycle tooling).
580///
581/// Name retained for API stability; entries may be `.gguf` **or** preferred `.p64`.
582#[derive(Debug, Clone, Serialize)]
583pub struct VaultGgufEntry {
584    pub name: String,
585    pub path: String,
586    pub profile_id: u64,
587    pub size_bytes: u64,
588    /// `p64` | `gguf` — engine prefers `p64` when both exist for the same stem.
589    pub container: String,
590}
591
592/// Exact duplicate GGUF files, grouped by content rather than filename.
593///
594/// The audit is deliberately read-only: lifecycle code may report redundant files,
595/// but never copies, moves, or deletes a model behind the operator's back.
596#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
597pub struct VaultDuplicateGroup {
598    pub sha256: String,
599    pub size_bytes: u64,
600    pub canonical_path: String,
601    pub duplicate_paths: Vec<String>,
602}
603
604impl VaultDuplicateGroup {
605    /// Reclaimable byte count.
606    pub fn reclaimable_bytes(&self) -> u64 {
607        self.size_bytes
608            .saturating_mul(self.duplicate_paths.len() as u64)
609    }
610}
611
612/// Recursively scan `vault_dir` for `.p64` and `.gguf` weight containers.
613///
614/// When both exist for the same stem (e.g. `foo.p64` + `foo.gguf`), **only the
615/// `.p64` is listed** — GGUF is import-only once converted. `.f16.p64` keeps a
616/// distinct stem and is listed separately.
617pub fn scan_vault_gguf(vault_dir: &Path) -> Result<Vec<VaultGgufEntry>, std::io::Error> {
618    if !vault_dir.is_dir() {
619        return Err(std::io::Error::new(
620            std::io::ErrorKind::NotFound,
621            format!("Vault directory not found: {}", vault_dir.display()),
622        ));
623    }
624    let mut raw = Vec::new();
625    collect_vault_models(vault_dir, &mut raw)?;
626    // Prefer p64: drop gguf when a p64 with the same base stem exists.
627    let p64_stems: std::collections::HashSet<String> = raw
628        .iter()
629        .filter(|e| e.container == "p64")
630        .map(|e| vault_stem_key(&e.path))
631        .collect();
632    let mut out: Vec<VaultGgufEntry> = raw
633        .into_iter()
634        .filter(|e| e.container == "p64" || !p64_stems.contains(&vault_stem_key(&e.path)))
635        .collect();
636    out.sort_by(|a, b| a.name.cmp(&b.name));
637    Ok(out)
638}
639
640/// Stem key for prefer-p64 dedup: `foo.gguf` / `foo.p64` → `foo`; `foo.f16.p64` → `foo.f16`.
641fn vault_stem_key(path: &str) -> String {
642    Path::new(path)
643        .file_stem()
644        .and_then(|s| s.to_str())
645        .unwrap_or("")
646        .to_string()
647}
648
649/// Hash only same-sized GGUF candidates and report byte-identical duplicates.
650///
651/// Size bucketing avoids reading every multi-gigabyte model during a routine audit.
652/// Within each exact-content group the shortest, then lexicographically first, path
653/// is suggested as the canonical keeper. No filesystem mutation is performed.
654pub fn audit_vault_duplicates(
655    vault_dir: &Path,
656) -> Result<Vec<VaultDuplicateGroup>, std::io::Error> {
657    use std::collections::BTreeMap;
658    use std::io::Read;
659
660    let entries = scan_vault_gguf(vault_dir)?;
661    let mut by_size: BTreeMap<u64, Vec<&VaultGgufEntry>> = BTreeMap::new();
662    for entry in &entries {
663        by_size.entry(entry.size_bytes).or_default().push(entry);
664    }
665
666    let mut groups = Vec::new();
667    for (size_bytes, candidates) in by_size {
668        if candidates.len() < 2 {
669            continue;
670        }
671        let mut by_digest: BTreeMap<String, Vec<String>> = BTreeMap::new();
672        for candidate in candidates {
673            let mut file = std::fs::File::open(&candidate.path)?;
674            let mut hasher = Sha256::new();
675            // Keep the cold-path hash buffer modest enough for Windows' default
676            // main-thread stack while still reading in efficient chunks.
677            let mut buffer = [0u8; 64 * 1024];
678            loop {
679                let read = file.read(&mut buffer)?;
680                if read == 0 {
681                    break;
682                }
683                hasher.update(&buffer[..read]);
684            }
685            let digest = hasher.finalize();
686            let mut digest_hex = String::with_capacity(digest.len() * 2);
687            for byte in digest {
688                use std::fmt::Write;
689                let _ = write!(digest_hex, "{byte:02x}");
690            }
691            by_digest
692                .entry(digest_hex)
693                .or_default()
694                .push(candidate.path.clone());
695        }
696
697        for (sha256, mut paths) in by_digest {
698            if paths.len() < 2 {
699                continue;
700            }
701            paths.sort_by(|a, b| {
702                let a_depth = Path::new(a).components().count();
703                let b_depth = Path::new(b).components().count();
704                a_depth.cmp(&b_depth).then_with(|| a.cmp(b))
705            });
706            let canonical_path = paths.remove(0);
707            groups.push(VaultDuplicateGroup {
708                sha256,
709                size_bytes,
710                canonical_path,
711                duplicate_paths: paths,
712            });
713        }
714    }
715    groups.sort_by(|a, b| a.canonical_path.cmp(&b.canonical_path));
716    Ok(groups)
717}
718
719fn collect_vault_models(dir: &Path, out: &mut Vec<VaultGgufEntry>) -> Result<(), std::io::Error> {
720    for entry in std::fs::read_dir(dir)? {
721        let entry = entry?;
722        let path = entry.path();
723        if path.is_dir() {
724            collect_vault_models(&path, out)?;
725            continue;
726        }
727        let ext = path
728            .extension()
729            .and_then(|e| e.to_str())
730            .unwrap_or("")
731            .to_ascii_lowercase();
732        let container = match ext.as_str() {
733            "p64" => "p64",
734            "gguf" => "gguf",
735            _ => continue,
736        };
737        let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("model");
738        let model_id = sanitize_local_model_id(stem);
739        let size_bytes = entry.metadata()?.len();
740        out.push(VaultGgufEntry {
741            name: path
742                .file_name()
743                .map(|n| n.to_string_lossy().into_owned())
744                .unwrap_or_else(|| model_id.clone()),
745            path: path.to_string_lossy().into_owned(),
746            profile_id: q_hash(&format!("profile:local:{model_id}")),
747            size_bytes,
748            container: container.into(),
749        });
750    }
751    Ok(())
752}
753
754/// Resolve a model reference (filename, stem, or path) inside `vault_dir`.
755///
756/// Preference order: exact path → `.p64` → `.gguf` → vault scan (p64 preferred).
757pub fn resolve_vault_model(vault_dir: &Path, model_ref: &str) -> Result<PathBuf, ModelError> {
758    let direct = PathBuf::from(model_ref);
759    if direct.is_file() {
760        // If operator points at a GGUF that has a converted sibling .p64, prefer p64.
761        if let Some(p64) = prefer_p64_sibling(&direct) {
762            return Ok(p64);
763        }
764        return Ok(direct);
765    }
766    let in_vault = vault_dir.join(model_ref);
767    if in_vault.is_file() {
768        if let Some(p64) = prefer_p64_sibling(&in_vault) {
769            return Ok(p64);
770        }
771        return Ok(in_vault);
772    }
773    // Prefer p64 extension first (designed runtime format).
774    if !model_ref.ends_with(".p64") && !model_ref.ends_with(".gguf") {
775        let with_p64 = vault_dir.join(format!("{model_ref}.p64"));
776        if with_p64.is_file() {
777            return Ok(with_p64);
778        }
779        let with_gguf = vault_dir.join(format!("{model_ref}.gguf"));
780        if with_gguf.is_file() {
781            if let Some(p64) = prefer_p64_sibling(&with_gguf) {
782                return Ok(p64);
783            }
784            return Ok(with_gguf);
785        }
786    }
787    for entry in scan_vault_gguf(vault_dir).map_err(ModelError::Io)? {
788        let stem = PathBuf::from(&entry.path)
789            .file_stem()
790            .and_then(|s| s.to_str())
791            .unwrap_or("")
792            .to_string();
793        if entry.name == model_ref
794            || stem == model_ref
795            || format!("0x{:016x}", entry.profile_id) == model_ref.to_lowercase()
796        {
797            return Ok(PathBuf::from(entry.path));
798        }
799    }
800    Err(ModelError::NotFound(format!(
801        "No p64/GGUF matching `{model_ref}` under {}",
802        vault_dir.display()
803    )))
804}
805
806/// If `path` is a `.gguf` and `{stem}.p64` exists beside it, return the p64.
807fn prefer_p64_sibling(path: &Path) -> Option<PathBuf> {
808    let is_gguf = path
809        .extension()
810        .and_then(|e| e.to_str())
811        .map(|e| e.eq_ignore_ascii_case("gguf"))
812        .unwrap_or(false);
813    if !is_gguf {
814        return None;
815    }
816    let p64 = path.with_extension("p64");
817    if p64.is_file() {
818        Some(p64)
819    } else {
820        None
821    }
822}
823
824/// Map and activate a vault weight file (`.p64` preferred, or `.gguf`) without catalog install.
825pub async fn activate_vault_gguf(gguf_path: &Path) -> Result<ActiveModelRecord, ModelError> {
826    let path = prefer_p64_sibling(gguf_path).unwrap_or_else(|| gguf_path.to_path_buf());
827    if !path.is_file() {
828        return Err(ModelError::Io(std::io::Error::new(
829            std::io::ErrorKind::NotFound,
830            format!("Model not found: {}", path.display()),
831        )));
832    }
833    let stem = path
834        .file_stem()
835        .and_then(|s| s.to_str())
836        .unwrap_or("local-model");
837    let model_id = sanitize_local_model_id(stem);
838    let path_str = path.to_string_lossy().into_owned();
839    let profile_id = q_hash(&format!("profile:local:{model_id}"));
840    let quant = if path
841        .extension()
842        .and_then(|e| e.to_str())
843        .map(|e| e.eq_ignore_ascii_case("p64"))
844        .unwrap_or(false)
845    {
846        "p64"
847    } else {
848        "vault"
849    };
850
851    let agent = LocalLlmAgent::with_local_backend(
852        format!("did:qualia:cli-vault:{profile_id}"),
853        AgentBackend::Local {
854            model_path: path_str.clone(),
855            context_window: 4096,
856            quantization: quant.to_string(),
857            vision_projector_path: None,
858            modality: "text".to_string(),
859            architecture: None,
860        },
861    );
862    probe_and_activate_model(&agent, profile_id, &model_id, &path_str)?;
863
864    let lifecycle = *orchestrator().current_model_state.lock().unwrap();
865    Ok(ActiveModelRecord {
866        model_id,
867        gguf_path: path_str,
868        profile_id,
869        quantization: quant.to_string(),
870        lifecycle_state: lifecycle_label(lifecycle).to_string(),
871        modality: "text".to_string(),
872        architecture: None,
873        mmproj_path: None,
874        context_window: 4096,
875    })
876}
877
878/// Block until eviction scrub completes or `timeout` elapses.
879pub fn wait_for_eviction_scrub(timeout: std::time::Duration) -> bool {
880    let orch = orchestrator();
881    let started = std::time::Instant::now();
882    while orch.scrubbing_lock.load(Ordering::Acquire) {
883        if started.elapsed() > timeout {
884            return false;
885        }
886        std::thread::sleep(std::time::Duration::from_millis(5));
887    }
888    true
889}
890
891/// Register and activate a user-selected `.gguf` file at an arbitrary path.
892///
893/// Writes `{model_id}.install.json` under `{storage_root}/Models/` (path is not copied),
894/// maps GGUF tensor pointers into the WAL, and transitions lifecycle → `Active`.
895pub fn finalize_local_gguf(
896    gguf_path: &Path,
897    storage_root: &Path,
898) -> Result<ActiveModelRecord, ModelError> {
899    if !gguf_path.is_file() {
900        return Err(ModelError::Io(std::io::Error::new(
901            std::io::ErrorKind::NotFound,
902            format!("GGUF not found: {}", gguf_path.display()),
903        )));
904    }
905
906    let models = models_dir(storage_root);
907    std::fs::create_dir_all(&models)?;
908
909    let stem = gguf_path
910        .file_stem()
911        .and_then(|s| s.to_str())
912        .unwrap_or("local-model");
913    let model_id = sanitize_local_model_id(stem);
914    let path_str = gguf_path.to_string_lossy().into_owned();
915    let profile_id = q_hash(&format!("profile:local:{model_id}"));
916
917    let sharder = GGufSharder::new(path_str.clone());
918    let pointer_quins = sharder.generate_bidx_pointer_map();
919    let pointer_quin_count = pointer_quins.len();
920
921    let wal_path = models.join("models.wal");
922    let mut wal = WriteAheadLog::open(&wal_path)
923        .map_err(|e| ModelError::Wal(format!("Cannot open {}: {}", wal_path.display(), e)))?;
924
925    let subject = q_hash(&format!("local-gguf:{model_id}"));
926    let predicate = q_hash("prov:wasDerivedFrom");
927    let object = q_hash(&path_str);
928    let context = q_hash("ctx:local-gguf");
929    let prov = qualia_core_db::NQuin {
930        subject,
931        predicate,
932        object,
933        context,
934        metadata: unix_now(),
935        parity: subject ^ predicate ^ object ^ context,
936    };
937    wal.append_mutation(&prov)
938        .map_err(|e| ModelError::Wal(e.to_string()))?;
939
940    for quin in pointer_quins {
941        wal.append_mutation(&quin)
942            .map_err(|e| ModelError::Wal(e.to_string()))?;
943    }
944
945    let manifest = InstallManifest {
946        model_id: model_id.clone(),
947        gguf_path: path_str.clone(),
948        profile_id,
949        quantization: "local".to_string(),
950        pointer_quin_count,
951        vision_pointer_quin_count: 0,
952        installed_at: unix_now(),
953        wal_path: wal_path.to_string_lossy().into_owned(),
954        modality: "text".to_string(),
955        architecture: None,
956        mmproj_path: None,
957        context_window: 4096,
958    };
959    let json = serde_json::to_string_pretty(&manifest)?;
960    std::fs::write(install_manifest_path(&models, &model_id), json)?;
961
962    let agent = LocalLlmAgent::with_local_backend(
963        format!("did:qualia:local-gguf:{profile_id}"),
964        AgentBackend::Local {
965            model_path: path_str.clone(),
966            context_window: 4096,
967            quantization: "local".to_string(),
968            vision_projector_path: None,
969            modality: "text".to_string(),
970            architecture: None,
971        },
972    );
973    probe_and_activate_model(&agent, profile_id, &model_id, &path_str)?;
974
975    let lifecycle = *orchestrator().current_model_state.lock().unwrap();
976    Ok(ActiveModelRecord {
977        model_id,
978        gguf_path: path_str,
979        profile_id,
980        quantization: "local".to_string(),
981        lifecycle_state: lifecycle_label(lifecycle).to_string(),
982        modality: "text".to_string(),
983        architecture: None,
984        mmproj_path: None,
985        context_window: 4096,
986    })
987}
988
989/// Activates a model by ID.
990pub fn activate_model_for_id(
991    model_id: &str,
992    storage_root: &Path,
993) -> Result<ActiveModelRecord, ModelError> {
994    let manifest = load_install_manifest(storage_root, model_id).ok_or_else(|| {
995        ModelError::Activate(format!(
996            "No install manifest for `{model_id}` — download the model in LLM Hub first"
997        ))
998    })?;
999
1000    if !Path::new(&manifest.gguf_path).is_file() {
1001        return Err(ModelError::Activate(format!(
1002            "GGUF missing at {}",
1003            manifest.gguf_path
1004        )));
1005    }
1006
1007    if manifest.modality == "multimodal" {
1008        let mmproj = manifest.mmproj_path.as_deref().ok_or_else(|| {
1009            ModelError::Activate("Multimodal manifest missing mmproj_path".to_string())
1010        })?;
1011        if !Path::new(mmproj).is_file() {
1012            return Err(ModelError::Activate(format!(
1013                "Vision projector missing at {mmproj}"
1014            )));
1015        }
1016    }
1017
1018    let agent = LocalLlmAgent::with_local_backend(
1019        format!("did:qualia:profile:{}", manifest.profile_id),
1020        AgentBackend::Local {
1021            model_path: manifest.gguf_path.clone(),
1022            context_window: manifest.context_window,
1023            quantization: manifest.quantization.clone(),
1024            vision_projector_path: manifest.mmproj_path.clone(),
1025            modality: manifest.modality.clone(),
1026            architecture: manifest.architecture.clone(),
1027        },
1028    );
1029    probe_and_activate_model(
1030        &agent,
1031        manifest.profile_id,
1032        &manifest.model_id,
1033        &manifest.gguf_path,
1034    )?;
1035
1036    let lifecycle = *orchestrator().current_model_state.lock().unwrap();
1037    let record = ActiveModelRecord {
1038        model_id: manifest.model_id,
1039        gguf_path: manifest.gguf_path,
1040        profile_id: manifest.profile_id,
1041        quantization: manifest.quantization,
1042        lifecycle_state: lifecycle_label(lifecycle).to_string(),
1043        modality: manifest.modality,
1044        architecture: manifest.architecture,
1045        mmproj_path: manifest.mmproj_path,
1046        context_window: manifest.context_window,
1047    };
1048
1049    Ok(record)
1050}
1051
1052/// Activates a model.
1053pub fn activate_model(
1054    profile_id: u64,
1055    storage_root: &Path,
1056) -> Result<ActiveModelRecord, ModelError> {
1057    let models = models_dir(storage_root);
1058    let entries = std::fs::read_dir(&models).map_err(ModelError::Io)?;
1059    for entry in entries.filter_map(Result::ok) {
1060        let path = entry.path();
1061        if path.extension().and_then(|e| e.to_str()) != Some("json") {
1062            continue;
1063        }
1064        if !path
1065            .file_name()
1066            .map(|n| n.to_string_lossy().contains(".install.json"))
1067            .unwrap_or(false)
1068        {
1069            continue;
1070        }
1071        if let Ok(text) = std::fs::read_to_string(&path) {
1072            if let Ok(manifest) = serde_json::from_str::<InstallManifest>(&text) {
1073                if manifest.profile_id == profile_id {
1074                    return activate_model_for_id(&manifest.model_id, storage_root);
1075                }
1076            }
1077        }
1078    }
1079    Err(ModelError::Activate(format!(
1080        "No installed model with profile_id 0x{profile_id:016x}"
1081    )))
1082}
1083
1084/// Gets model-lifecycle-state.
1085pub fn get_model_lifecycle_state() -> ModelLifecycle {
1086    *orchestrator().current_model_state.lock().unwrap()
1087}
1088
1089/// Gets model-status.
1090pub fn get_model_status(active: Option<ActiveModelRecord>) -> ModelStatus {
1091    let lifecycle = get_model_lifecycle_state();
1092    ModelStatus {
1093        profile_id: active.as_ref().map(|r| r.profile_id),
1094        active,
1095        lifecycle_state: lifecycle_label(lifecycle).to_string(),
1096    }
1097}
1098
1099#[cfg(test)]
1100mod tests {
1101    use super::*;
1102
1103    #[test]
1104    fn duplicate_audit_groups_only_identical_gguf_files() {
1105        let root = std::env::temp_dir().join(format!(
1106            "qualia-gguf-audit-{}-{}",
1107            std::process::id(),
1108            unix_now()
1109        ));
1110        let nested = root.join("nested");
1111        std::fs::create_dir_all(&nested).unwrap();
1112        std::fs::write(root.join("keeper.gguf"), b"same model bytes").unwrap();
1113        std::fs::write(nested.join("copy.gguf"), b"same model bytes").unwrap();
1114        std::fs::write(root.join("same-size-not-copy.gguf"), b"other model byte").unwrap();
1115
1116        let groups = audit_vault_duplicates(&root).unwrap();
1117        assert_eq!(groups.len(), 1);
1118        assert_eq!(groups[0].size_bytes, 16);
1119        assert!(groups[0].canonical_path.ends_with("keeper.gguf"));
1120        assert_eq!(groups[0].duplicate_paths.len(), 1);
1121        assert!(groups[0].duplicate_paths[0].ends_with("copy.gguf"));
1122        assert_eq!(groups[0].reclaimable_bytes(), 16);
1123
1124        std::fs::remove_dir_all(root).unwrap();
1125    }
1126
1127    #[test]
1128    fn vault_scan_prefers_p64_over_gguf_same_stem() {
1129        let root = std::env::temp_dir().join(format!(
1130            "qualia-vault-p64-{}-{}",
1131            std::process::id(),
1132            unix_now()
1133        ));
1134        std::fs::create_dir_all(&root).unwrap();
1135        std::fs::write(root.join("smollm.gguf"), b"gguf-bytes").unwrap();
1136        std::fs::write(root.join("smollm.p64"), b"p64\0bytes").unwrap();
1137        std::fs::write(root.join("other.gguf"), b"only-gguf").unwrap();
1138
1139        let entries = scan_vault_gguf(&root).unwrap();
1140        let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();
1141        assert!(
1142            names.iter().any(|n| *n == "smollm.p64"),
1143            "p64 should be listed: {names:?}"
1144        );
1145        assert!(
1146            !names.iter().any(|n| *n == "smollm.gguf"),
1147            "gguf should be hidden when p64 exists: {names:?}"
1148        );
1149        assert!(names.iter().any(|n| *n == "other.gguf"));
1150
1151        let resolved = resolve_vault_model(&root, "smollm").unwrap();
1152        assert!(
1153            resolved.extension().and_then(|e| e.to_str()) == Some("p64"),
1154            "resolve stem should pick p64: {}",
1155            resolved.display()
1156        );
1157        let via_gguf = resolve_vault_model(&root, "smollm.gguf").unwrap();
1158        assert!(
1159            via_gguf.extension().and_then(|e| e.to_str()) == Some("p64"),
1160            "resolve gguf name should still prefer sibling p64: {}",
1161            via_gguf.display()
1162        );
1163
1164        std::fs::remove_dir_all(root).unwrap();
1165    }
1166}