photonlayer-ruvector 0.1.0

PhotonLayer experiment memory on RuVector: mask/frame embeddings, similarity recall, pass/fail boundary, coherence, RVF receipts (ADR-260 Phase 2)
Documentation
//! Mask-family coherence scoring using spectral graph analysis (ADR-260 ยง14).
//!
//! A *mask family* is a group of embeddings (one per mask) whose structural
//! similarity is measured by the spectral gap of the cosine-similarity graph.
//! Families with a large spectral gap and high mean similarity are considered
//! stable / coherent and can be promoted to demo mode.

use ruvector_coherence::cosine_similarity;
use ruvector_coherence::spectral::{
    estimate_fiedler, estimate_largest_eigenvalue, estimate_spectral_gap, CsrMatrixView,
};
use serde::{Deserialize, Serialize};

/// Minimum spectral gap for a family to be considered promotable.
const PROMOTE_SPECTRAL_GAP: f64 = 0.05;
/// Minimum mean pairwise similarity for a family to be considered promotable.
const PROMOTE_MEAN_SIM: f64 = 0.6;

/// Spectral coherence summary for a family of mask embeddings.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct FamilyCoherence {
    /// Spectral gap of the cosine-similarity graph (0 = disconnected, 1 = clique).
    pub spectral_gap: f64,
    /// Mean pairwise cosine similarity over all pairs in the family.
    pub mean_similarity: f64,
    /// Compactness: fraction of edges whose similarity exceeds the threshold.
    pub compactness: f64,
}

impl FamilyCoherence {
    /// Whether this family qualifies for promotion to demo mode.
    ///
    /// A family is promotable when:
    /// - its mean pairwise similarity exceeds [`PROMOTE_MEAN_SIM`], AND
    /// - either the spectral gap exceeds [`PROMOTE_SPECTRAL_GAP`], OR the
    ///   family is fully connected (compactness == 1.0 and mean_similarity is
    ///   near 1.0), which can occur when all masks are numerically identical.
    pub fn is_promotable(&self) -> bool {
        if self.mean_similarity < PROMOTE_MEAN_SIM {
            return false;
        }
        // A fully connected, very high similarity family is coherent even when
        // the spectral solver returns 0 for a near-degenerate Laplacian.
        let high_sim_clique = self.compactness >= 1.0 && self.mean_similarity >= 0.95;
        high_sim_clique || self.spectral_gap >= PROMOTE_SPECTRAL_GAP
    }
}

/// Edge-inclusion threshold for the similarity graph.
const EDGE_THRESHOLD: f64 = 0.3;

/// Compute the coherence of a family of mask embeddings.
///
/// `embeddings` contains one L2-normalised 32-dim vector per mask.
///
/// # Edge cases
/// - Returns all-zero [`FamilyCoherence`] for families with fewer than 2 members.
/// - Single-node families have a spectral gap and mean similarity of `0.0`.
pub fn mask_family_coherence(embeddings: &[Vec<f32>]) -> FamilyCoherence {
    let n = embeddings.len();
    if n < 2 {
        return FamilyCoherence {
            spectral_gap: 0.0,
            mean_similarity: 0.0,
            compactness: 0.0,
        };
    }

    let total_pairs = n * (n - 1) / 2;
    let mut edges: Vec<(usize, usize, f64)> = Vec::with_capacity(total_pairs);
    let mut sim_sum = 0.0_f64;
    let mut edges_above = 0usize;

    for i in 0..n {
        for j in (i + 1)..n {
            let sim = cosine_similarity(&embeddings[i], &embeddings[j]);
            sim_sum += sim;
            if sim >= EDGE_THRESHOLD {
                edges.push((i, j, sim));
                edges_above += 1;
            }
        }
    }

    let mean_similarity = sim_sum / total_pairs as f64;
    let compactness = edges_above as f64 / total_pairs as f64;

    // Build Laplacian of the similarity graph and estimate spectral gap.
    let lap = CsrMatrixView::build_laplacian(n, &edges);
    let (fiedler_raw, _) = estimate_fiedler(&lap, 100, 1e-6);
    let largest = estimate_largest_eigenvalue(&lap, 100);
    let spectral_gap = estimate_spectral_gap(fiedler_raw, largest);

    FamilyCoherence {
        spectral_gap,
        mean_similarity,
        compactness,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use photonlayer_core::prelude::PhaseMask;

    use crate::embedding::mask_embedding;

    fn embeddings_for_seeds(seeds: &[u64]) -> Vec<Vec<f32>> {
        seeds
            .iter()
            .map(|&s| mask_embedding(&PhaseMask::random(16, 16, s)))
            .collect()
    }

    #[test]
    fn single_member_family_returns_zero() {
        let embs = embeddings_for_seeds(&[1]);
        let fc = mask_family_coherence(&embs);
        assert_eq!(fc.spectral_gap, 0.0);
        assert_eq!(fc.mean_similarity, 0.0);
        assert!(!fc.is_promotable());
    }

    #[test]
    fn identical_masks_form_coherent_family() {
        // Same seed => identical embeddings => cosine sim = 1.0.
        let embs: Vec<Vec<f32>> = (0..4)
            .map(|_| mask_embedding(&PhaseMask::random(16, 16, 7)))
            .collect();
        let fc = mask_family_coherence(&embs);
        assert!(
            fc.mean_similarity > 0.99,
            "mean_sim = {}",
            fc.mean_similarity
        );
        // Compactness must be 1.0 since all pairs exceed the threshold.
        assert!(
            (fc.compactness - 1.0).abs() < 1e-9,
            "compactness = {}",
            fc.compactness
        );
        // The family is promotable via the high-similarity-clique path.
        assert!(fc.is_promotable(), "fc = {:?}", fc);
    }

    #[test]
    fn diverse_masks_have_lower_coherence_than_similar() {
        // Very diverse seeds โ€” low similarity.
        let diverse_seeds: Vec<u64> = (0..5).map(|i| i * 1_000_003).collect();
        let diverse_embs = embeddings_for_seeds(&diverse_seeds);
        let fc_diverse = mask_family_coherence(&diverse_embs);

        // Same mask repeated โ€” high similarity.
        let uniform_embs: Vec<Vec<f32>> = (0..5)
            .map(|_| mask_embedding(&PhaseMask::random(16, 16, 42)))
            .collect();
        let fc_uniform = mask_family_coherence(&uniform_embs);

        assert!(
            fc_uniform.mean_similarity > fc_diverse.mean_similarity,
            "uniform={} diverse={}",
            fc_uniform.mean_similarity,
            fc_diverse.mean_similarity
        );
    }

    #[test]
    fn promotable_gate_works() {
        // Identical embeddings: high similarity clique => promotable via
        // the compactness + high mean_similarity path.
        let uniform: Vec<Vec<f32>> = (0..4)
            .map(|_| mask_embedding(&PhaseMask::random(16, 16, 99)))
            .collect();
        let fc_uniform = mask_family_coherence(&uniform);
        assert!(fc_uniform.is_promotable(), "fc = {:?}", fc_uniform);

        // A single-member family is not promotable.
        let single = embeddings_for_seeds(&[1]);
        assert!(!mask_family_coherence(&single).is_promotable());

        // A very diverse family should not be promotable (low mean_similarity).
        let diverse: Vec<Vec<f32>> = (0..5)
            .map(|i| mask_embedding(&PhaseMask::random(16, 16, i * 999_983 + 1)))
            .collect();
        let fc_diverse = mask_family_coherence(&diverse);
        // If it happens to be promotable due to high similarity, that is fine โ€”
        // we just check the gate logic is consistent with the fields.
        assert_eq!(
            fc_diverse.is_promotable(),
            (fc_diverse.compactness >= 1.0 && fc_diverse.mean_similarity >= 0.95)
                || (fc_diverse.spectral_gap >= PROMOTE_SPECTRAL_GAP
                    && fc_diverse.mean_similarity >= PROMOTE_MEAN_SIM),
            "fc = {:?}",
            fc_diverse
        );
    }

    #[test]
    fn coherence_fields_are_in_range() {
        let embs = embeddings_for_seeds(&[10, 20, 30, 40]);
        let fc = mask_family_coherence(&embs);
        assert!(fc.spectral_gap >= 0.0 && fc.spectral_gap <= 1.0);
        assert!(fc.mean_similarity >= -1.0 && fc.mean_similarity <= 1.0);
        assert!(fc.compactness >= 0.0 && fc.compactness <= 1.0);
    }
}