Skip to main content

hyprstream_inference/runtime/
ttn_profile.rs

1//! TTN (Test-Time Naturalization) analysis pipeline for model layer profiling.
2//!
3//! Provides per-layer LoRA rank allocation. Uses a tiered approach:
4//!
5//! - **Tier 1**: Embedded profiles for known models (zero-cost const lookup) —
6//!   ranks from ablation perplexity delta (the gold standard).
7//! - **Tier 2**: Cached profiles from disk (~1ms file read).
8//! - **Tier 3**: Computed profiles — layer type detected from weight-key
9//!   geometry, every layer assigned a flat unvalidated rank (see
10//!   [`UNVALIDATED_RANK_CAP`] / [`GDN_LORA_RANK`]) that the runtime
11//!   utilization oracle narrows from. There is no per-layer spectral analysis;
12//!   a data-calibrated allocator is gated on the rank-proxy spike (#842).
13//!
14//! Ported from `tnn-transformer-1/src/entropy.py` and `attention_analysis.py`.
15
16use anyhow::Result;
17use serde::{Deserialize, Serialize};
18use std::collections::HashMap;
19use std::path::Path;
20use tch::{Kind, Tensor};
21use tracing::{info, warn};
22
23use crate::runtime::model_config::ModelConfig;
24
25// ============================================================================
26// Core types
27// ============================================================================
28
29#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
30pub enum LayerType {
31    FullAttention,
32    GatedDeltaNet,
33    StandardAttention,
34}
35
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct LayerAnalysis {
38    pub layer_idx: usize,
39    pub layer_type: LayerType,
40    /// Perplexity delta if ablation data available, else None
41    pub perplexity_delta: Option<f64>,
42    pub recommended_rank: usize,
43    pub target_modules: Vec<String>,
44}
45
46#[derive(Debug, Clone, Serialize, Deserialize)]
47pub struct LayerProfile {
48    pub model_id: String,
49    pub num_layers: usize,
50    pub hidden_size: usize,
51    pub baseline_perplexity: Option<f64>,
52    pub layers: Vec<LayerAnalysis>,
53    /// ISO timestamp; None for embedded profiles
54    pub computed_at: Option<String>,
55}
56
57// ============================================================================
58// Tier 1: Embedded profiles (known models — zero cost)
59// ============================================================================
60
61/// Embedded Tier-1 layer profile for the single ablated hybrid (full-attention
62/// + GatedDeltaNet) reference model.
63///
64/// Data from `tnn-transformer-1/results/linearization_ablation.json`.
65/// Rank assignments based on perplexity delta (the ablation gold standard).
66pub fn qwen3_5_0_8b_profile() -> LayerProfile {
67    // Full-attention layers: 3, 7, 11, 15, 19, 23
68    // GDN layers: 0-2, 4-6, 8-10, 12-14, 16-18, 20-22
69    // (layer_idx, perplexity_delta, rank). Rank comes from perplexity delta;
70    // no per-projection spectral data is carried.
71    let attn_layers = [
72        (23usize, Some(8.40f64), 32usize),
73        (3usize, Some(5.62f64), 24usize),
74        (19usize, Some(4.39f64), 16usize),
75        (15usize, Some(3.22f64), 16usize),
76        (7usize, Some(2.16f64), 8usize),
77        (11usize, Some(1.13f64), 8usize),
78    ];
79    let attn_set: std::collections::HashSet<usize> = attn_layers.iter().map(|(i, ..)| *i).collect();
80
81    let mut layers: Vec<LayerAnalysis> = Vec::with_capacity(24);
82
83    // Build full-attention entries
84    for (idx, ppl_delta, rank) in &attn_layers {
85        layers.push(LayerAnalysis {
86            layer_idx: *idx,
87            layer_type: LayerType::FullAttention,
88            perplexity_delta: *ppl_delta,
89            recommended_rank: *rank,
90            target_modules: vec![
91                "q_proj".to_owned(),
92                "v_proj".to_owned(),
93                "o_proj".to_owned(),
94            ],
95        });
96    }
97
98    // Build GDN entries (layers 0-23 not in attn_set)
99    for idx in 0..24usize {
100        if !attn_set.contains(&idx) {
101            layers.push(LayerAnalysis {
102                layer_idx: idx,
103                layer_type: LayerType::GatedDeltaNet,
104                perplexity_delta: None,
105                recommended_rank: GDN_LORA_RANK,
106                target_modules: vec!["o_proj".to_owned()],
107            });
108        }
109    }
110
111    layers.sort_by_key(|l| l.layer_idx);
112
113    LayerProfile {
114        model_id: "Qwen/Qwen3.5-0.8B".to_owned(),
115        num_layers: 24,
116        hidden_size: 1024,
117        baseline_perplexity: Some(29.54),
118        layers,
119        computed_at: None,
120    }
121}
122
123/// Registry lookup for embedded profiles. Returns `None` for unknown models.
124///
125/// A known model family with unexpected geometry (e.g. a larger variant of a
126/// profiled family) also returns `None`, but loudly: it falls through to
127/// unvalidated allocation, and silence here previously masked that.
128pub fn find_embedded_profile(
129    model_type: &str,
130    num_layers: usize,
131    hidden_size: usize,
132) -> Option<LayerProfile> {
133    let normalized = model_type.to_lowercase();
134    let normalized = normalized.as_str();
135    let known_family = matches!(normalized, "qwen3_5" | "qwen3.5" | "qwen3_5_text");
136    match (normalized, num_layers, hidden_size) {
137        ("qwen3_5" | "qwen3.5" | "qwen3_5_text", 24, 1024) => Some(qwen3_5_0_8b_profile()),
138        _ => {
139            if known_family {
140                warn!(
141                    model_type,
142                    num_layers,
143                    hidden_size,
144                    "Known model family but unexpected geometry — no embedded \
145                     rank profile matches; falling through to unvalidated \
146                     allocation"
147                );
148            }
149            None
150        }
151    }
152}
153
154// ============================================================================
155// Tier 2: Cached profiles (disk cache)
156// ============================================================================
157
158const ANALYSIS_DIR: &str = ".analysis";
159const PROFILE_FILE: &str = "layer_profile.json";
160
161/// Load cached profile from model directory.
162pub fn load_cached_profile(model_path: &Path) -> Option<LayerProfile> {
163    let path = model_path.join(ANALYSIS_DIR).join(PROFILE_FILE);
164    let content = std::fs::read_to_string(&path).ok()?;
165    serde_json::from_str(&content).ok()
166}
167
168/// Save computed profile to model directory (atomic: tmpfile + rename).
169pub fn save_cached_profile(model_path: &Path, profile: &LayerProfile) -> Result<()> {
170    let dir = model_path.join(ANALYSIS_DIR);
171    std::fs::create_dir_all(&dir)?;
172    let content = serde_json::to_string_pretty(profile)?;
173    let tmp = dir.join(format!("{PROFILE_FILE}.tmp.{}", std::process::id()));
174    std::fs::write(&tmp, &content)?;
175    std::fs::rename(&tmp, dir.join(PROFILE_FILE))?; // atomic on Linux same-FS
176    Ok(())
177}
178
179// ============================================================================
180// Tier 3: Computed profiles (weight-key geometry → flat rank)
181// ============================================================================
182
183/// Shannon entropy of a non-negative tensor treated as unnormalized probabilities.
184///
185/// Used by `delta_rank_utilization` (applied to gram eigenvalues, which are
186/// already σᵢ²) to measure how spread the learned LoRA update is across rank.
187fn entropy_of_nonneg(s: &Tensor) -> f64 {
188    let total: f64 = s.sum(Kind::Double).double_value(&[]);
189    if total < 1e-30 {
190        return 0.0;
191    }
192    let p = s / total;
193    let mask = p.gt(1e-30);
194    let p_valid = p.masked_select(&mask);
195    -(&p_valid * p_valid.log())
196        .sum(Kind::Double)
197        .double_value(&[])
198}
199
200/// Rank ceiling for any profile derived without ablation ground truth
201/// (computed Tier-3 profiles, the uniform fallback, and cached copies of
202/// them). Without a validated per-layer allocator, every unprofiled layer gets
203/// this flat value, which the runtime utilization oracle then narrows from.
204const UNVALIDATED_RANK_CAP: usize = 8;
205
206/// LoRA rank for GatedDeltaNet layers, as an explicit constant.
207///
208/// GDN capacity lives in the recurrent/conv/gating parameters; this value
209/// matches the embedded GDN rank and sits under [`UNVALIDATED_RANK_CAP`].
210/// Revisit when GDN ablation ground truth exists.
211const GDN_LORA_RANK: usize = 4;
212
213/// Detect the layer type for a given layer index.
214///
215/// Priority:
216/// 1. `config.layer_types` if non-empty
217/// 2. Weight key presence
218/// 3. Default: `StandardAttention`
219fn detect_layer_type(
220    config: &ModelConfig,
221    layer_idx: usize,
222    weights: &HashMap<String, Tensor>,
223    prefix: &str,
224) -> LayerType {
225    // Tier 1: use config.layer_types
226    if let Some(lt) = config.layer_types.get(layer_idx) {
227        return match lt.as_str() {
228            "linear_attention" => LayerType::GatedDeltaNet,
229            "full_attention" | "global" | "sliding_window" => LayerType::FullAttention,
230            _ => LayerType::StandardAttention,
231        };
232    }
233
234    // Tier 2: weight key presence
235    let gdn_key = format!("{prefix}.linear_attn.out_proj.weight");
236    if weights.contains_key(&gdn_key) {
237        return LayerType::GatedDeltaNet;
238    }
239    let attn_key = format!("{prefix}.self_attn.q_proj.weight");
240    if weights.contains_key(&attn_key) {
241        return LayerType::FullAttention;
242    }
243
244    LayerType::StandardAttention
245}
246
247/// Compute a layer profile from weight-key geometry (Tier 3).
248///
249/// Detects each layer's type from weight-key presence and assigns a flat
250/// unvalidated rank (see [`UNVALIDATED_RANK_CAP`] / [`GDN_LORA_RANK`]); there
251/// is no per-layer spectral analysis. Results are cached to
252/// `{model_path}/.analysis/layer_profile.json`.
253pub fn compute_layer_profile(
254    weights: &HashMap<String, Tensor>,
255    config: &ModelConfig,
256    model_path: &Path,
257) -> Result<LayerProfile> {
258    let _guard = tch::no_grad_guard();
259    info!(
260        "Computing TTN layer profile for {} ({} layers)...",
261        config.model_type, config.num_hidden_layers
262    );
263
264    // Detect key prefix: base models use "model.layers.*",
265    // Instruct models may use "model.language_model.layers.*"
266    let prefix_base = if weights
267        .keys()
268        .any(|k| k.starts_with("model.language_model."))
269    {
270        "model.language_model.layers"
271    } else {
272        "model.layers"
273    };
274
275    let mut layers = Vec::new();
276
277    for layer_idx in 0..config.num_hidden_layers {
278        let prefix = format!("{prefix_base}.{layer_idx}");
279
280        let layer_type = detect_layer_type(config, layer_idx, weights, &prefix);
281
282        // No validated per-layer rank signal exists for unprofiled models: the
283        // spectral-entropy → rank mapping that lived here was unvalidated (its
284        // sign inverted across attention projections on the only ablation
285        // data) and has been removed. Every layer gets a flat prior — the cap
286        // for attention/standard layers, the explicit GDN constant for GDN —
287        // and the runtime utilization oracle narrows from there. A
288        // data-calibrated allocator is gated on the rank-proxy validation
289        // spike (#842); until then a flat prior is more honest than an
290        // unvalidated guess.
291        let recommended_rank = if layer_type == LayerType::GatedDeltaNet {
292            GDN_LORA_RANK
293        } else {
294            UNVALIDATED_RANK_CAP
295        };
296
297        // Target modules: default ["q_proj", "v_proj"] for standard attention
298        let target_modules = match layer_type {
299            LayerType::FullAttention => {
300                vec![
301                    "q_proj".to_owned(),
302                    "v_proj".to_owned(),
303                    "o_proj".to_owned(),
304                ]
305            }
306            LayerType::GatedDeltaNet => vec!["o_proj".to_owned()],
307            LayerType::StandardAttention => {
308                vec!["q_proj".to_owned(), "v_proj".to_owned()]
309            }
310        };
311
312        layers.push(LayerAnalysis {
313            layer_idx,
314            layer_type,
315            perplexity_delta: None,
316            recommended_rank,
317            target_modules,
318        });
319    }
320
321    let profile = LayerProfile {
322        model_id: config.model_type.clone(),
323        num_layers: config.num_hidden_layers,
324        hidden_size: config.hidden_size,
325        baseline_perplexity: None,
326        layers,
327        computed_at: Some(chrono::Utc::now().to_rfc3339()),
328    };
329
330    // Atomic cache write (tmpfile + rename)
331    if let Err(e) = save_cached_profile(model_path, &profile) {
332        warn!("Failed to cache layer profile: {e}");
333    }
334
335    info!(
336        "TTN profile computed: {} layers analyzed",
337        profile.layers.len()
338    );
339    Ok(profile)
340}
341
342/// Fallback uniform profile when no weights are available for analysis.
343///
344/// Uses `["o_proj"]` as the sole target module because it is present in all known
345/// architectures (full-attention and GDN/SSM layers alike). Using `["q_proj", "v_proj"]`
346/// would crash delta pool creation for hybrid models whose GDN layers have no q/v projections.
347fn uniform_fallback_profile(config: &ModelConfig) -> LayerProfile {
348    let layers = (0..config.num_hidden_layers)
349        .map(|layer_idx| LayerAnalysis {
350            layer_idx,
351            layer_type: LayerType::StandardAttention,
352            perplexity_delta: None,
353            recommended_rank: UNVALIDATED_RANK_CAP, // uninformed uniform default
354            target_modules: vec!["o_proj".to_owned()],
355        })
356        .collect();
357
358    LayerProfile {
359        model_id: config.model_type.clone(),
360        num_layers: config.num_hidden_layers,
361        hidden_size: config.hidden_size,
362        baseline_perplexity: None,
363        layers,
364        computed_at: None,
365    }
366}
367
368// ============================================================================
369// Unified public API
370// ============================================================================
371
372/// Get or compute the layer profile for a model.
373///
374/// Tiered: embedded → cached → computed.
375///
376/// # Arguments
377/// * `model_path` - Path to model directory (for cache read/write)
378/// * `config` - Model configuration
379/// * `weights` - Optional loaded weights (required for Tier 3 computation)
380pub fn get_layer_profile(
381    model_path: &Path,
382    config: &ModelConfig,
383    weights: Option<&HashMap<String, Tensor>>,
384) -> Result<LayerProfile> {
385    // Tier 1: Embedded profile for known models (zero-cost)
386    if let Some(profile) = find_embedded_profile(
387        &config.model_type,
388        config.num_hidden_layers,
389        config.hidden_size,
390    ) {
391        info!(
392            "Using embedded TTN profile for {} ({} layers)",
393            config.model_type, config.num_hidden_layers
394        );
395        return Ok(profile);
396    }
397
398    // Tier 2: Cached profile from disk (~1ms)
399    if let Some(mut profile) = load_cached_profile(model_path) {
400        info!("Loaded cached TTN profile from {}", model_path.display());
401        // A cached profile for a model with no embedded ablation data is a
402        // persisted Tier-3 computation and gets the same cap. Older caches
403        // predate the cap; hand-edited ones must not bypass it either.
404        for layer in &mut profile.layers {
405            if layer.recommended_rank > UNVALIDATED_RANK_CAP {
406                warn!(
407                    layer_idx = layer.layer_idx,
408                    cached_rank = layer.recommended_rank,
409                    "Cached profile exceeds the unvalidated-rank cap; clamping"
410                );
411                layer.recommended_rank = UNVALIDATED_RANK_CAP;
412            }
413        }
414        return Ok(profile);
415    }
416
417    // Tier 3: Compute from weights (~2-5s)
418    if let Some(weights) = weights {
419        warn!(
420            model_type = %config.model_type,
421            rank_cap = UNVALIDATED_RANK_CAP,
422            "Unknown model — Tier 3 entropy-based rank allocation is unvalidated \
423             (no embedded ablation data). A conservative rank cap is applied until \
424             the mapping is validated against ablation ground truth. Consider \
425             contributing an embedded profile."
426        );
427        info!("Computing TTN profile for new model (one-time analysis)...");
428        return compute_layer_profile(weights, config, model_path);
429    }
430
431    // Fallback: uniform profile
432    warn!("No weights available for TTN analysis, using uniform profile");
433    Ok(uniform_fallback_profile(config))
434}
435
436// ============================================================================
437// Runtime observability
438// ============================================================================
439
440/// Compute delta rank utilization: how much of allocated rank is actually used.
441///
442/// Returns value in [0, 1]: 0 = rank-1 (collapsed), 1 = fully utilized.
443///
444/// Uses SVD of `B^T @ B` which is `[rank, rank]` — much cheaper than `B @ A`
445/// which is `[out, in]`. B accumulates the learned update (initialized to zeros), so its
446/// singular value distribution captures how much of the allocated rank is actually being
447/// used. When B is zero (fresh delta), returns 0.0.
448///
449/// lora_a: [rank, in_features], lora_b: [out_features, rank]
450///
451/// Called periodically during TTT (every N steps), not on every forward pass.
452pub fn delta_rank_utilization(lora_a: &Tensor, lora_b: &Tensor) -> f64 {
453    let _guard = tch::no_grad_guard();
454    let _ = lora_a; // A is kaiming-initialized and not informative for rank utilization
455                    // Gram trick: B^T @ B = [rank, rank]; eigenvalues = σᵢ² of B.
456                    // O(rank³) — much cheaper than SVD of [out, rank] directly (O(out·rank²)).
457    let gram = lora_b.tr().matmul(lora_b);
458    let (_, s, _) = gram.svd(true, false); // s = σᵢ² of B (eigenvalues of PSD gram)
459    let max_entropy = (s.size()[0] as f64).ln();
460    if max_entropy < 1e-10 {
461        return 0.0;
462    }
463    // s is already σᵢ² — pass directly to shared helper (no double-squaring)
464    entropy_of_nonneg(&s) / max_entropy
465}
466
467// ============================================================================
468// Attention analysis functions (offline / developer tooling)
469// ============================================================================
470
471/// Compute Shannon entropy of attention distributions.
472///
473/// Input: `[B, H, N, N]` attention weights → Output: `[B, H, N]` per-token entropy.
474///
475/// Ported from `tnn-transformer-1/src/attention_analysis.py:compute_attention_entropy`.
476pub fn attention_entropy(attn_weights: &Tensor) -> Tensor {
477    let _guard = tch::no_grad_guard();
478    let eps = 1e-10f64;
479    let p = attn_weights.clamp_min(eps);
480    -(&p * p.log()).sum_dim_intlist(&[-1i64][..], false, None)
481}
482
483/// Compute top-k attention mass fraction (sparsity measure).
484///
485/// Input: `[B, H, N, N]` attention weights → Output: `[B, H, N]` per-token sparsity.
486///
487/// Ported from `tnn-transformer-1/src/attention_analysis.py:compute_attention_sparsity`.
488pub fn attention_sparsity(attn_weights: &Tensor, top_k: i64) -> Tensor {
489    let _guard = tch::no_grad_guard();
490    let (top_vals, _) = attn_weights.topk(top_k, -1, true, false);
491    top_vals.sum_dim_intlist(&[-1i64][..], false, None)
492}
493
494// ============================================================================
495// Rank Utilization Tracker
496// ============================================================================
497
498/// Rolling-window rank utilization tracker.
499///
500/// Records per-key utilization values and produces adaptation signals
501/// (increase/decrease/hold) based on configurable thresholds.
502#[derive(Debug, Clone)]
503pub struct RankUtilizationTracker {
504    window_size: usize,
505    history: HashMap<String, std::collections::VecDeque<f64>>,
506}
507
508/// Signal for rank adaptation.
509#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
510pub enum RankSignal {
511    Increase,
512    Decrease,
513    Hold,
514}
515
516/// Summary statistics for a key's utilization history.
517#[derive(Debug, Clone)]
518pub struct UtilizationSummary {
519    pub mean: f64,
520    pub min: f64,
521    pub max: f64,
522    pub count: usize,
523}
524
525impl RankUtilizationTracker {
526    pub fn new(window_size: usize) -> Self {
527        Self {
528            window_size,
529            history: HashMap::new(),
530        }
531    }
532
533    pub fn record(&mut self, key: &str, utilization: f64) {
534        let entry = self.history.entry(key.to_owned()).or_default();
535        entry.push_back(utilization);
536        while entry.len() > self.window_size {
537            entry.pop_front();
538        }
539    }
540
541    pub fn summary(&self, key: &str) -> Option<UtilizationSummary> {
542        let h = self.history.get(key)?;
543        if h.is_empty() {
544            return None;
545        }
546        let count = h.len();
547        let sum: f64 = h.iter().sum();
548        let min = h.iter().copied().fold(f64::MAX, f64::min);
549        let max = h.iter().copied().fold(f64::MIN, f64::max);
550        Some(UtilizationSummary {
551            mean: sum / count as f64,
552            min,
553            max,
554            count,
555        })
556    }
557
558    pub fn rank_adaptation_signals(
559        &self,
560        low_threshold: f64,
561        high_threshold: f64,
562    ) -> HashMap<String, RankSignal> {
563        self.history
564            .keys()
565            .filter_map(|key| {
566                let s = self.summary(key)?;
567                let signal = if s.mean < low_threshold {
568                    RankSignal::Decrease
569                } else if s.mean > high_threshold {
570                    RankSignal::Increase
571                } else {
572                    RankSignal::Hold
573                };
574                Some((key.clone(), signal))
575            })
576            .collect()
577    }
578}
579
580#[cfg(test)]
581#[allow(clippy::expect_used, clippy::unwrap_used)]
582mod tests {
583    use super::*;
584
585    #[test]
586    fn test_qwen3_5_profile_structure() {
587        let profile = qwen3_5_0_8b_profile();
588        assert_eq!(profile.num_layers, 24);
589        assert_eq!(profile.layers.len(), 24);
590
591        // Check full-attention layers have correct ranks
592        let attn_23 = profile
593            .layers
594            .iter()
595            .find(|l| l.layer_idx == 23)
596            .expect("layer 23 should exist");
597        assert_eq!(attn_23.recommended_rank, 32);
598        assert_eq!(attn_23.layer_type, LayerType::FullAttention);
599        assert_eq!(attn_23.perplexity_delta, Some(8.40));
600
601        let gdn_0 = profile
602            .layers
603            .iter()
604            .find(|l| l.layer_idx == 0)
605            .expect("layer 0 should exist");
606        assert_eq!(gdn_0.recommended_rank, GDN_LORA_RANK);
607        assert_eq!(gdn_0.layer_type, LayerType::GatedDeltaNet);
608    }
609
610    #[test]
611    fn test_find_embedded_profile() {
612        assert!(find_embedded_profile("qwen3_5", 24, 1024).is_some());
613        assert!(find_embedded_profile("qwen3.5", 24, 1024).is_some());
614        assert!(find_embedded_profile("llama", 32, 4096).is_none());
615        assert!(find_embedded_profile("qwen3_5", 32, 4096).is_none()); // different dims
616    }
617
618    #[test]
619    fn test_tier3_synthetic_profile_golden() {
620        let _guard = tch::no_grad_guard();
621        tch::manual_seed(42);
622        let dir = tempfile::tempdir().expect("tempdir");
623
624        let config = ModelConfig {
625            model_type: "synthetic_test".to_owned(),
626            num_hidden_layers: 2,
627            hidden_size: 64,
628            ..Default::default()
629        };
630
631        // Layer 0: GDN (detected by weight-key presence). Layer 1: attention.
632        let mut weights: HashMap<String, Tensor> = HashMap::new();
633        weights.insert(
634            "model.layers.0.linear_attn.out_proj.weight".to_owned(),
635            Tensor::randn([64, 64], (Kind::Float, tch::Device::Cpu)),
636        );
637        for proj in ["q_proj", "k_proj", "v_proj", "o_proj"] {
638            weights.insert(
639                format!("model.layers.1.self_attn.{proj}.weight"),
640                Tensor::randn([64, 64], (Kind::Float, tch::Device::Cpu)),
641            );
642        }
643
644        let profile = compute_layer_profile(&weights, &config, dir.path()).expect("profile");
645        assert_eq!(profile.layers.len(), 2);
646
647        let gdn = &profile.layers[0];
648        assert_eq!(gdn.layer_type, LayerType::GatedDeltaNet);
649        assert_eq!(gdn.recommended_rank, GDN_LORA_RANK);
650
651        let attn = &profile.layers[1];
652        assert_eq!(attn.layer_type, LayerType::FullAttention);
653        assert_eq!(
654            attn.recommended_rank, UNVALIDATED_RANK_CAP,
655            "unprofiled attention layers get the flat unvalidated cap"
656        );
657
658        // The computation persisted itself to the Tier-2 cache.
659        assert!(load_cached_profile(dir.path()).is_some());
660    }
661
662    #[test]
663    fn test_cached_profile_rank_is_capped_on_load() {
664        let dir = tempfile::tempdir().expect("tempdir");
665        let config = ModelConfig {
666            model_type: "synthetic_test".to_owned(),
667            num_hidden_layers: 1,
668            hidden_size: 64,
669            ..Default::default()
670        };
671
672        // A pre-cap (or hand-edited) cache claiming rank 32.
673        let mut profile = uniform_fallback_profile(&config);
674        profile.layers[0].recommended_rank = 32;
675        save_cached_profile(dir.path(), &profile).expect("save");
676
677        // No embedded profile for this model → Tier 2 load must clamp.
678        let loaded = get_layer_profile(dir.path(), &config, None).expect("load");
679        assert_eq!(loaded.layers[0].recommended_rank, UNVALIDATED_RANK_CAP);
680    }
681
682    #[test]
683    fn test_delta_rank_utilization() {
684        let _guard = tch::no_grad_guard();
685        let rank = 8i64;
686        let in_f = 64i64;
687        let out_f = 64i64;
688
689        let a = Tensor::randn([rank, in_f], (Kind::Float, tch::Device::Cpu));
690        let b = Tensor::zeros([out_f, rank], (Kind::Float, tch::Device::Cpu));
691        // B = 0 → product is 0 → utilization should be 0
692        let util = delta_rank_utilization(&a, &b);
693        assert_eq!(util, 0.0);
694    }
695
696    // --- Rank Utilization Tracker Tests ---
697
698    #[test]
699    fn test_utilization_tracker_records() {
700        let mut tracker = RankUtilizationTracker::new(5);
701        tracker.record("0.q_proj", 0.3);
702        tracker.record("0.q_proj", 0.5);
703        let summary = tracker.summary("0.q_proj");
704        assert!(summary.is_some());
705        let s = summary.unwrap();
706        assert_eq!(s.count, 2);
707        assert!((s.mean - 0.4).abs() < 1e-9);
708    }
709
710    #[test]
711    fn test_utilization_tracker_window() {
712        let mut tracker = RankUtilizationTracker::new(3);
713        tracker.record("k", 0.1);
714        tracker.record("k", 0.2);
715        tracker.record("k", 0.3);
716        tracker.record("k", 0.9); // pushes out 0.1
717        let s = tracker.summary("k").unwrap();
718        assert_eq!(s.count, 3);
719        // mean of [0.2, 0.3, 0.9] = 0.4667
720        assert!((s.mean - 0.4667).abs() < 0.01);
721    }
722
723    #[test]
724    fn test_utilization_tracker_rank_signals() {
725        let mut tracker = RankUtilizationTracker::new(10);
726        for _ in 0..5 {
727            tracker.record("low", 0.15);
728        }
729        for _ in 0..5 {
730            tracker.record("high", 0.95);
731        }
732        for _ in 0..5 {
733            tracker.record("ok", 0.5);
734        }
735
736        let signals = tracker.rank_adaptation_signals(0.25, 0.85);
737        assert_eq!(signals.get("low"), Some(&RankSignal::Decrease));
738        assert_eq!(signals.get("high"), Some(&RankSignal::Increase));
739        assert_eq!(signals.get("ok"), Some(&RankSignal::Hold));
740    }
741
742    #[test]
743    fn test_utilization_tracker_empty_key() {
744        let tracker = RankUtilizationTracker::new(5);
745        assert!(tracker.summary("nonexistent").is_none());
746    }
747}