+-------------------------------------------------------------------+
|                 CRV-Sense Pipeline (6 Stages)                      |
+-------------------------------------------------------------------+
|                                                                     |
|  Raw CSI frames from ESP32 mesh (ADR-029)                          |
|       |                                                             |
|       v                                                             |
|  +----------------------------------------------------------+     |
|  | Stage I: CSI Gestalt Classification                       |     |
|  |   CsiGestaltClassifier                                    |     |
|  |   Input: raw CSI frame (amplitude envelope + phase slope) |     |
|  |   Output: GestaltType (Manmade/Natural/Movement/Energy)   |     |
|  |   Encoder: StageIEncoder (Poincare ball embedding)        |     |
|  |   Module: ruvsense/multiband.rs                           |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Stage II: CSI Sensory Feature Extraction                  |     |
|  |   CsiSensoryEncoder                                       |     |
|  |   Input: per-subcarrier CSI                               |     |
|  |   Output: amplitude textures, phase patterns, freq colors |     |
|  |   Encoder: StageIIEncoder (multi-head attention vectors)  |     |
|  |   Module: ruvsense/phase_align.rs                         |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Stage III: AP Mesh Spatial Topology                       |     |
|  |   MeshTopologyEncoder                                     |     |
|  |   Input: node positions, link SNR, baseline distances     |     |
|  |   Output: GNN graph embedding of mesh geometry            |     |
|  |   Encoder: StageIIIEncoder (GNN topology)                 |     |
|  |   Module: ruvsense/multistatic.rs                         |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Stage IV: Coherence Gating (AOL Detection)                |     |
|  |   CoherenceAolDetector                                    |     |
|  |   Input: phase coherence scores, gate decisions           |     |
|  |   Output: AOL-flagged frames removed, clean signal kept   |     |
|  |   Encoder: StageIVEncoder (SNN temporal encoding)         |     |
|  |   Module: ruvsense/coherence_gate.rs                      |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Stage V: Pose Interrogation                               |     |
|  |   PoseInterrogator                                        |     |
|  |   Input: pose hypothesis + accumulated CSI features       |     |
|  |   Output: soft attention over CSI history, top candidates |     |
|  |   Engine: StageVEngine (differentiable search)            |     |
|  |   Module: ruvsense/field_model.rs                         |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Stage VI: Multi-Person Partitioning                       |     |
|  |   PersonPartitioner                                       |     |
|  |   Input: all person embedding clusters                    |     |
|  |   Output: MinCut-separated person partitions + centroids  |     |
|  |   Modeler: StageVIModeler (MinCut partitioning)           |     |
|  |   Module: training pipeline (ruvector-mincut)             |     |
|  +----------------------------+-----------------------------+     |
|                               |                                     |
|                               v                                     |
|  +----------------------------------------------------------+     |
|  | Cross-Session: Multi-Room Convergence                     |     |
|  |   MultiViewerConvergence                                  |     |
|  |   Input: per-room embedding trails for candidate persons  |     |
|  |   Output: cross-room identity matches + confidence        |     |
|  |   Engine: CrvSessionManager::find_convergence()           |     |
|  |   Module: ruvsense/cross_room.rs                          |     |
|  +----------------------------------------------------------+     |
+-------------------------------------------------------------------+

/// CSI-domain gestalt types mapped from CRV GestaltType.
///
/// The CRV taxonomy maps to RF phenomenology:
/// - Manmade: structured multipath (walls, furniture, metallic reflectors)
/// - Natural: diffuse scattering (vegetation, irregular surfaces)
/// - Movement: Doppler-shifted components (human motion, fan, pet)
/// - Energy: high-amplitude transients (microwave, motor, interference)
/// - Water: slow fading envelope (humidity change, condensation)
/// - Land: static baseline (empty room, no perturbation)
pub struct CsiGestaltClassifier {
    encoder: StageIEncoder,
    config: CrvConfig,
}

impl CsiGestaltClassifier {
    /// Classify a raw CSI frame into a gestalt type.
    ///
    /// Extracts three features from the CSI frame:
    /// 1. Amplitude envelope shape (ideogram stroke analog)
    /// 2. Phase slope direction (spontaneous descriptor analog)
    /// 3. Subcarrier correlation structure (classification signal)
    ///
    /// Returns a Poincare ball embedding (384-d by default) encoding
    /// the hierarchical gestalt taxonomy with exponentially less
    /// distortion than Euclidean space.
    pub fn classify(&self, csi_frame: &CsiFrame) -> CrvResult<(GestaltType, Vec<f32>)>;
}

pub struct CsiSensoryEncoder {
    encoder: StageIIEncoder,
}

impl CsiSensoryEncoder {
    /// Extract sensory features from per-subcarrier CSI data.
    ///
    /// Maps CSI signal characteristics to CRV sensory modalities:
    /// - Amplitude variance -> Texture
    /// - Spectral shape -> Color
    /// - Phase drift rate -> Temperature
    /// - Signal power -> Luminosity
    /// - Delay spread -> Dimension
    ///
    /// Uses multi-head attention (ruvector-attention) to produce
    /// a unified sensory embedding that captures cross-modality
    /// correlations.
    pub fn encode(&self, csi_subcarriers: &SubcarrierData) -> CrvResult<Vec<f32>>;
}

pub struct MeshTopologyEncoder {
    encoder: StageIIIEncoder,
}

impl MeshTopologyEncoder {
    /// Encode the AP mesh as a GNN graph topology.
    ///
    /// Each AP node becomes a SketchElement with its position and
    /// antenna count. Each bistatic link becomes a SpatialRelationship
    /// with strength proportional to link SNR.
    ///
    /// Uses ruvector-gnn to produce a graph embedding that captures
    /// the mesh's geometric diversity index (GDI) and effective
    /// viewpoint count.
    pub fn encode(&self, mesh: &MultistaticArray) -> CrvResult<Vec<f32>>;
}

pub struct CoherenceAolDetector {
    encoder: StageIVEncoder,
}

impl CoherenceAolDetector {
    /// Map coherence gate decisions to CRV AOL detection.
    ///
    /// The SNN temporal encoding models the spike pattern of
    /// coherence violations over time:
    /// - Burst of low-coherence frames -> high AOL anomaly score
    /// - Sustained coherence -> low anomaly score (clean signal)
    /// - Single transient -> moderate score (check and continue)
    ///
    /// Returns an embedding that encodes the temporal pattern of
    /// signal quality, enabling downstream stages to weight their
    /// attention based on signal cleanliness.
    pub fn detect(
        &self,
        coherence_history: &[GateDecision],
        timestamps: &[u64],
    ) -> CrvResult<(Vec<AOLDetection>, Vec<f32>)>;
}

pub struct PoseInterrogator {
    engine: StageVEngine,
}

impl PoseInterrogator {
    /// Cross-reference a pose hypothesis against CSI history.
    ///
    /// Uses differentiable search (soft attention with temperature
    /// scaling) to find which historical CSI frames best support
    /// or contradict the current pose estimate.
    ///
    /// Returns:
    /// - Attention weights over the CSI history buffer
    /// - Top-k supporting frames (highest attention)
    /// - Cross-references linking pose keypoints to specific
    ///   CSI subcarrier features from earlier stages
    pub fn interrogate(
        &self,
        pose_embedding: &[f32],
        csi_history: &[CrvSessionEntry],
    ) -> CrvResult<(StageVData, Vec<f32>)>;
}

pub struct PersonPartitioner {
    modeler: StageVIModeler,
}

impl PersonPartitioner {
    /// Partition accumulated embeddings into distinct persons.
    ///
    /// Uses MinCut (ruvector-mincut) to find natural cluster
    /// boundaries in the embedding space. Each partition corresponds
    /// to one person, with:
    /// - A centroid embedding (person signature)
    /// - Member frame indices (which CSI frames belong to this person)
    /// - Separation strength (how distinct this person is from others)
    ///
    /// The MinCut value between partitions serves as a confidence
    /// metric for person separation quality.
    pub fn partition(
        &self,
        person_embeddings: &[CrvSessionEntry],
    ) -> CrvResult<(StageVIData, Vec<f32>)>;
}

pub struct MultiViewerConvergence {
    session_manager: CrvSessionManager,
}

impl MultiViewerConvergence {
    /// Match person identities across rooms via CRV convergence.
    ///
    /// Each room's AP cluster is modeled as an independent CRV session.
    /// When a person moves from Room A to Room B:
    /// 1. Room A session contains the person's embedding trail (Stages I-VI)
    /// 2. Room B session begins accumulating new embeddings
    /// 3. Convergence analysis finds agreement between Room A's final
    ///    embeddings and Room B's initial embeddings
    /// 4. Agreement score above threshold establishes identity continuity
    ///
    /// Returns ConvergenceResult with:
    /// - Session pairs (room pairs) that converged
    /// - Per-pair similarity scores
    /// - Convergent stages (which CRV stages showed strongest agreement)
    /// - Consensus embedding (merged identity signature)
    pub fn match_across_rooms(
        &self,
        room_sessions: &[(RoomId, SessionId)],
        threshold: f32,
    ) -> CrvResult<ConvergenceResult>;
}

/// A WiFi-DensePose sensing session modeled as a CRV session.
///
/// Wraps CrvSessionManager with CSI-specific convenience methods.
/// Each call to process_frame() advances through all six CRV stages
/// and appends stage embeddings to the session.
pub struct WifiCrvSession {
    session_manager: CrvSessionManager,
    gestalt: CsiGestaltClassifier,
    sensory: CsiSensoryEncoder,
    topology: MeshTopologyEncoder,
    coherence: CoherenceAolDetector,
    interrogator: PoseInterrogator,
    partitioner: PersonPartitioner,
    convergence: MultiViewerConvergence,
}

impl WifiCrvSession {
    /// Create a new WiFi CRV session with the given configuration.
    pub fn new(config: WifiCrvConfig) -> Self;

    /// Process a single CSI frame through all six CRV stages.
    ///
    /// Returns the per-stage embeddings and the final person partitions.
    pub fn process_frame(
        &mut self,
        frame: &CsiFrame,
        mesh: &MultistaticArray,
        coherence_state: &GateDecision,
        pose_hypothesis: Option<&[f32]>,
    ) -> CrvResult<WifiCrvOutput>;

    /// Find convergence across room sessions for identity matching.
    pub fn find_convergence(
        &self,
        room_sessions: &[(RoomId, SessionId)],
        threshold: f32,
    ) -> CrvResult<ConvergenceResult>;
}

pub struct WifiCrvSession {
    /// Underlying CRV session manager
    session_manager: CrvSessionManager,
    /// Per-stage encoders
    stages: CrvStageEncoders,
    /// Session configuration
    config: WifiCrvConfig,
    /// Running statistics for convergence quality
    convergence_stats: ConvergenceStats,
}

/// Output of a single frame through the 6-stage pipeline.
pub struct WifiCrvOutput {
    /// Per-stage embeddings (6 vectors, one per CRV stage).
    pub stage_embeddings: [Vec<f32>; 6],
    /// Gestalt classification for this frame.
    pub gestalt: GestaltType,
    /// AOL detections (frames flagged as noise-contaminated).
    pub aol_events: Vec<AOLDetection>,
    /// Person partitions from Stage VI.
    pub partitions: Vec<TargetPartition>,
    /// Processing latency per stage in microseconds.
    pub stage_latencies_us: [u64; 6],
}

/// WiFi-specific CRV configuration extending CrvConfig.
pub struct WifiCrvConfig {
    /// Base CRV config (dimensions, curvature, thresholds).
    pub crv: CrvConfig,
    /// AETHER embedding dimension (default: 128, overrides CrvConfig.dimensions).
    pub aether_dim: usize,
    /// Coherence threshold for AOL detection (maps to aol_threshold).
    pub coherence_threshold: f32,
    /// Maximum CSI history frames for Stage V interrogation.
    pub max_history_frames: usize,
    /// Cross-room convergence threshold (default: 0.75).
    pub convergence_threshold: f32,
}

pub enum CrvSensingEvent {
    /// Stage I completed: gestalt classified
    GestaltClassified { gestalt: GestaltType, confidence: f32 },
    /// Stage IV: AOL detected (noise contamination)
    AolDetected { anomaly_score: f32, flagged: bool },
    /// Stage VI: Persons partitioned
    PersonsPartitioned { count: usize, min_separation: f32 },
    /// Cross-session: Identity matched across rooms
    IdentityConverged { room_pair: (RoomId, RoomId), score: f32 },
    /// Full pipeline completed for one frame
    FrameProcessed { latency_us: u64, stages_completed: u8 },
}