ruvector_crv/
types.rs

1//! Core types for the CRV (Coordinate Remote Viewing) protocol.
2//!
3//! Defines the data structures for the 6-stage CRV signal line methodology,
4//! session management, and analytical overlay (AOL) detection.
5
6use serde::{Deserialize, Serialize};
7use std::collections::HashMap;
8
9/// Unique identifier for a CRV session.
10pub type SessionId = String;
11
12/// Unique identifier for a target coordinate.
13pub type TargetCoordinate = String;
14
15/// Unique identifier for a stage data entry.
16pub type EntryId = String;
17
18/// Classification of gestalt primitives in Stage I.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
20pub enum GestaltType {
21    /// Human-made structures, artifacts
22    Manmade,
23    /// Organic, natural formations
24    Natural,
25    /// Dynamic, kinetic signals
26    Movement,
27    /// Thermal, electromagnetic, force
28    Energy,
29    /// Aqueous, fluid, wet
30    Water,
31    /// Solid, terrain, geological
32    Land,
33}
34
35impl GestaltType {
36    /// Returns all gestalt types for iteration.
37    pub fn all() -> &'static [GestaltType] {
38        &[
39            GestaltType::Manmade,
40            GestaltType::Natural,
41            GestaltType::Movement,
42            GestaltType::Energy,
43            GestaltType::Water,
44            GestaltType::Land,
45        ]
46    }
47
48    /// Returns the index of this gestalt type in the canonical ordering.
49    pub fn index(&self) -> usize {
50        match self {
51            GestaltType::Manmade => 0,
52            GestaltType::Natural => 1,
53            GestaltType::Movement => 2,
54            GestaltType::Energy => 3,
55            GestaltType::Water => 4,
56            GestaltType::Land => 5,
57        }
58    }
59}
60
61/// Stage I data: Ideogram traces and gestalt classifications.
62#[derive(Debug, Clone, Serialize, Deserialize)]
63pub struct StageIData {
64    /// Raw ideogram stroke trace as a sequence of (x, y) coordinates.
65    pub stroke: Vec<(f32, f32)>,
66    /// First spontaneous descriptor word.
67    pub spontaneous_descriptor: String,
68    /// Classified gestalt type.
69    pub classification: GestaltType,
70    /// Confidence in the classification (0.0 - 1.0).
71    pub confidence: f32,
72}
73
74/// Sensory modality for Stage II data.
75#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
76pub enum SensoryModality {
77    /// Surface textures (smooth, rough, grainy, etc.)
78    Texture,
79    /// Visual colors and patterns
80    Color,
81    /// Thermal impressions (hot, cold, warm)
82    Temperature,
83    /// Auditory impressions
84    Sound,
85    /// Olfactory impressions
86    Smell,
87    /// Taste impressions
88    Taste,
89    /// Size/scale impressions (large, small, vast)
90    Dimension,
91    /// Luminosity (bright, dark, glowing)
92    Luminosity,
93}
94
95/// Stage II data: Sensory impressions.
96#[derive(Debug, Clone, Serialize, Deserialize)]
97pub struct StageIIData {
98    /// Sensory impressions as modality-descriptor pairs.
99    pub impressions: Vec<(SensoryModality, String)>,
100    /// Raw sensory feature vector (encoded from descriptors).
101    pub feature_vector: Option<Vec<f32>>,
102}
103
104/// Stage III data: Dimensional and spatial relationships.
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct StageIIIData {
107    /// Spatial sketch as a set of named geometric primitives.
108    pub sketch_elements: Vec<SketchElement>,
109    /// Spatial relationships between elements.
110    pub relationships: Vec<SpatialRelationship>,
111}
112
113/// A geometric element in a Stage III sketch.
114#[derive(Debug, Clone, Serialize, Deserialize)]
115pub struct SketchElement {
116    /// Unique label for this element.
117    pub label: String,
118    /// Type of geometric primitive.
119    pub kind: GeometricKind,
120    /// Position in sketch space (x, y).
121    pub position: (f32, f32),
122    /// Optional size/scale.
123    pub scale: Option<f32>,
124}
125
126/// Types of geometric primitives.
127#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
128pub enum GeometricKind {
129    Point,
130    Line,
131    Curve,
132    Rectangle,
133    Circle,
134    Triangle,
135    Polygon,
136    Freeform,
137}
138
139/// Spatial relationship between two sketch elements.
140#[derive(Debug, Clone, Serialize, Deserialize)]
141pub struct SpatialRelationship {
142    /// Source element label.
143    pub from: String,
144    /// Target element label.
145    pub to: String,
146    /// Relationship type.
147    pub relation: SpatialRelationType,
148    /// Strength of the relationship (0.0 - 1.0).
149    pub strength: f32,
150}
151
152/// Types of spatial relationships.
153#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
154pub enum SpatialRelationType {
155    Adjacent,
156    Contains,
157    Above,
158    Below,
159    Inside,
160    Surrounding,
161    Connected,
162    Separated,
163}
164
165/// Stage IV data: Emotional, aesthetic, and intangible impressions.
166#[derive(Debug, Clone, Serialize, Deserialize)]
167pub struct StageIVData {
168    /// Emotional impact descriptors with intensity.
169    pub emotional_impact: Vec<(String, f32)>,
170    /// Tangible object impressions.
171    pub tangibles: Vec<String>,
172    /// Intangible concept impressions (purpose, function, significance).
173    pub intangibles: Vec<String>,
174    /// Analytical overlay detections with timestamps.
175    pub aol_detections: Vec<AOLDetection>,
176}
177
178/// An analytical overlay (AOL) detection event.
179///
180/// AOL occurs when the viewer's analytical mind attempts to assign
181/// a known label/concept to incoming signal line data, potentially
182/// contaminating the raw perception.
183#[derive(Debug, Clone, Serialize, Deserialize)]
184pub struct AOLDetection {
185    /// The AOL content (what the viewer's mind jumped to).
186    pub content: String,
187    /// Timestamp within the session (milliseconds from start).
188    pub timestamp_ms: u64,
189    /// Whether it was flagged and set aside ("AOL break").
190    pub flagged: bool,
191    /// Anomaly score from spike rate analysis (0.0 - 1.0).
192    /// Higher scores indicate stronger AOL contamination.
193    pub anomaly_score: f32,
194}
195
196/// Stage V data: Interrogation and cross-referencing results.
197#[derive(Debug, Clone, Serialize, Deserialize)]
198pub struct StageVData {
199    /// Probe queries and their results.
200    pub probes: Vec<SignalLineProbe>,
201    /// Cross-references to data from earlier stages.
202    pub cross_references: Vec<CrossReference>,
203}
204
205/// A signal line probe query.
206#[derive(Debug, Clone, Serialize, Deserialize)]
207pub struct SignalLineProbe {
208    /// The question or aspect being probed.
209    pub query: String,
210    /// Stage being interrogated.
211    pub target_stage: u8,
212    /// Resulting soft attention weights over candidates.
213    pub attention_weights: Vec<f32>,
214    /// Top-k candidate indices from differentiable search.
215    pub top_candidates: Vec<usize>,
216}
217
218/// A cross-reference between stage data entries.
219#[derive(Debug, Clone, Serialize, Deserialize)]
220pub struct CrossReference {
221    /// Source stage number.
222    pub from_stage: u8,
223    /// Source entry index.
224    pub from_entry: usize,
225    /// Target stage number.
226    pub to_stage: u8,
227    /// Target entry index.
228    pub to_entry: usize,
229    /// Similarity/relevance score.
230    pub score: f32,
231}
232
233/// Stage VI data: Composite 3D model from accumulated session data.
234#[derive(Debug, Clone, Serialize, Deserialize)]
235pub struct StageVIData {
236    /// Cluster partitions discovered by MinCut.
237    pub partitions: Vec<TargetPartition>,
238    /// Overall composite descriptor.
239    pub composite_description: String,
240    /// Confidence scores per partition.
241    pub partition_confidence: Vec<f32>,
242}
243
244/// A partition of the target, representing a distinct aspect or component.
245#[derive(Debug, Clone, Serialize, Deserialize)]
246pub struct TargetPartition {
247    /// Human-readable label for this partition.
248    pub label: String,
249    /// Stage data entry indices that belong to this partition.
250    pub member_entries: Vec<(u8, usize)>,
251    /// Centroid embedding of this partition.
252    pub centroid: Vec<f32>,
253    /// MinCut value separating this partition from others.
254    pub separation_strength: f32,
255}
256
257/// A complete CRV session entry stored in the database.
258#[derive(Debug, Clone, Serialize, Deserialize)]
259pub struct CrvSessionEntry {
260    /// Session identifier.
261    pub session_id: SessionId,
262    /// Target coordinate.
263    pub coordinate: TargetCoordinate,
264    /// CRV stage (1-6).
265    pub stage: u8,
266    /// Embedding vector for this entry.
267    pub embedding: Vec<f32>,
268    /// Arbitrary metadata.
269    pub metadata: HashMap<String, serde_json::Value>,
270    /// Timestamp in milliseconds.
271    pub timestamp_ms: u64,
272}
273
274/// Configuration for CRV session processing.
275#[derive(Debug, Clone, Serialize, Deserialize)]
276pub struct CrvConfig {
277    /// Embedding dimensionality.
278    pub dimensions: usize,
279    /// Curvature for Poincare ball (Stage I). Positive value.
280    pub curvature: f32,
281    /// AOL anomaly detection threshold (Stage IV).
282    pub aol_threshold: f32,
283    /// SNN refractory period in ms (Stage IV).
284    pub refractory_period_ms: f64,
285    /// SNN time step in ms (Stage IV).
286    pub snn_dt: f64,
287    /// Differentiable search temperature (Stage V).
288    pub search_temperature: f32,
289    /// Convergence threshold for cross-session matching.
290    pub convergence_threshold: f32,
291}
292
293impl Default for CrvConfig {
294    fn default() -> Self {
295        Self {
296            dimensions: 384,
297            curvature: 1.0,
298            aol_threshold: 0.7,
299            refractory_period_ms: 50.0,
300            snn_dt: 1.0,
301            search_temperature: 1.0,
302            convergence_threshold: 0.75,
303        }
304    }
305}
306
307/// Result of a convergence analysis across multiple sessions.
308#[derive(Debug, Clone, Serialize, Deserialize)]
309pub struct ConvergenceResult {
310    /// Session pairs that converged.
311    pub session_pairs: Vec<(SessionId, SessionId)>,
312    /// Convergence scores per pair.
313    pub scores: Vec<f32>,
314    /// Stages where convergence was strongest.
315    pub convergent_stages: Vec<u8>,
316    /// Merged embedding representing the consensus signal.
317    pub consensus_embedding: Option<Vec<f32>>,
318}
319
320#[cfg(test)]
321mod tests {
322    use super::*;
323
324    #[test]
325    fn test_gestalt_type_all() {
326        let all = GestaltType::all();
327        assert_eq!(all.len(), 6);
328    }
329
330    #[test]
331    fn test_gestalt_type_index() {
332        assert_eq!(GestaltType::Manmade.index(), 0);
333        assert_eq!(GestaltType::Land.index(), 5);
334    }
335
336    #[test]
337    fn test_default_config() {
338        let config = CrvConfig::default();
339        assert_eq!(config.dimensions, 384);
340        assert_eq!(config.curvature, 1.0);
341        assert_eq!(config.aol_threshold, 0.7);
342    }
343
344    #[test]
345    fn test_session_entry_serialization() {
346        let entry = CrvSessionEntry {
347            session_id: "sess-001".to_string(),
348            coordinate: "1234-5678".to_string(),
349            stage: 1,
350            embedding: vec![0.1, 0.2, 0.3],
351            metadata: HashMap::new(),
352            timestamp_ms: 1000,
353        };
354
355        let json = serde_json::to_string(&entry).unwrap();
356        let deserialized: CrvSessionEntry = serde_json::from_str(&json).unwrap();
357        assert_eq!(deserialized.session_id, "sess-001");
358        assert_eq!(deserialized.stage, 1);
359    }
360}
ruvector_crv/types.rs

ruvector_crv/
types.rs
