@feltdb/core 0.4.12 → 0.4.13

package/dist/create/server-source/crates/feltdb/src/query_performance.rs

@@ -0,0 +1,217 @@
+/// Query Performance Tracking & Latency Contracts
+///
+/// Manages query performance benchmarks and latency SLAs:
+/// - Query latency tracking (p50, p95, p99)
+/// - Latency contract enforcement
+/// - Performance degradation detection
+/// - Query optimization recommendations
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LatencyContract {
+    pub query_type: String,
+    pub p50_target_us: u64,
+    pub p95_target_us: u64,
+    pub p99_target_us: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct QueryMetric {
+    pub query_type: String,
+    pub duration_us: u64,
+    pub timestamp: u64,
+    pub index_name: String,
+    pub result_count: usize,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct QueryLatencyStats {
+    pub query_type: String,
+    pub count: u64,
+    pub p50_us: u64,
+    pub p95_us: u64,
+    pub p99_us: u64,
+    pub min_us: u64,
+    pub max_us: u64,
+    pub avg_us: u64,
+}
+
+#[derive(Debug, Clone)]
+struct QueryTimer {
+    start: Instant,
+}
+
+impl QueryTimer {
+    fn new() -> Self {
+        QueryTimer {
+            start: Instant::now(),
+        }
+    }
+
+    fn elapsed_us(&self) -> u64 {
+        self.start.elapsed().as_micros() as u64
+    }
+}
+
+pub struct QueryPerformanceTracker {
+    contracts: HashMap<String, LatencyContract>,
+    metrics: Vec<QueryMetric>,
+    violations: Vec<String>,
+}
+
+impl QueryPerformanceTracker {
+    pub fn new() -> Self {
+        QueryPerformanceTracker {
+            contracts: HashMap::new(),
+            metrics: Vec::new(),
+            violations: Vec::new(),
+        }
+    }
+
+    pub fn register_contract(&mut self, contract: LatencyContract) {
+        self.contracts.insert(contract.query_type.clone(), contract);
+    }
+
+    pub fn start_timer(&self) -> QueryTimer {
+        QueryTimer::new()
+    }
+
+    pub fn record_query(
+        &mut self,
+        query_type: String,
+        index_name: String,
+        result_count: usize,
+        duration_us: u64,
+    ) {
+        let metric = QueryMetric {
+            query_type: query_type.clone(),
+            duration_us,
+            timestamp: std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_secs(),
+            index_name,
+            result_count,
+        };
+
+        if let Some(contract) = self.contracts.get(&query_type) {
+            if duration_us > contract.p99_target_us {
+                self.violations.push(format!(
+                    "Query {} violated p99 contract: {} us > {} us",
+                    query_type, duration_us, contract.p99_target_us
+                ));
+            }
+        }
+
+        self.metrics.push(metric);
+    }
+
+    pub fn get_stats(&self, query_type: &str) -> Option<QueryLatencyStats> {
+        let relevant: Vec<&QueryMetric> = self
+            .metrics
+            .iter()
+            .filter(|m| m.query_type == query_type)
+            .collect();
+
+        if relevant.is_empty() {
+            return None;
+        }
+
+        let mut durations: Vec<u64> = relevant.iter().map(|m| m.duration_us).collect();
+        durations.sort();
+
+        let count = durations.len() as u64;
+        let sum: u64 = durations.iter().sum();
+        let avg = sum / count;
+
+        let p50_idx = (count / 2) as usize;
+        let p95_idx = ((count * 95) / 100) as usize;
+        let p99_idx = ((count * 99) / 100) as usize;
+
+        Some(QueryLatencyStats {
+            query_type: query_type.to_string(),
+            count,
+            p50_us: durations.get(p50_idx).copied().unwrap_or(0),
+            p95_us: durations.get(p95_idx).copied().unwrap_or(0),
+            p99_us: durations.get(p99_idx).copied().unwrap_or(0),
+            min_us: *durations.first().unwrap_or(&0),
+            max_us: *durations.last().unwrap_or(&0),
+            avg_us: avg,
+        })
+    }
+
+    pub fn get_violations(&self) -> Vec<String> {
+        self.violations.clone()
+    }
+
+    pub fn clear_violations(&mut self) {
+        self.violations.clear();
+    }
+
+    pub fn export_metrics_csv(&self) -> String {
+        let mut csv = String::from("timestamp,query_type,duration_us,index_name,result_count\n");
+        for metric in &self.metrics {
+            csv.push_str(&format!(
+                "{},{},{},{},{}\n",
+                metric.timestamp, metric.query_type, metric.duration_us, metric.index_name, metric.result_count
+            ));
+        }
+        csv
+    }
+}
+
+impl Default for QueryPerformanceTracker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_latency_contract() {
+        let mut tracker = QueryPerformanceTracker::new();
+        tracker.register_contract(LatencyContract {
+            query_type: "index_lookup".to_string(),
+            p50_target_us: 100,
+            p95_target_us: 500,
+            p99_target_us: 1000,
+        });
+
+        let timer = tracker.start_timer();
+        std::thread::sleep(Duration::from_micros(50));
+        let elapsed = timer.elapsed_us();
+
+        tracker.record_query(
+            "index_lookup".to_string(),
+            "idx_1".to_string(),
+            10,
+            elapsed,
+        );
+
+        let stats = tracker.get_stats("index_lookup").unwrap();
+        assert_eq!(stats.count, 1);
+        assert!(stats.p50_us < 1000);
+    }
+
+    #[test]
+    fn test_violation_detection() {
+        let mut tracker = QueryPerformanceTracker::new();
+        tracker.register_contract(LatencyContract {
+            query_type: "slow_query".to_string(),
+            p50_target_us: 100,
+            p95_target_us: 200,
+            p99_target_us: 500,
+        });
+
+        tracker.record_query("slow_query".to_string(), "idx_1".to_string(), 100, 600);
+
+        let violations = tracker.get_violations();
+        assert_eq!(violations.len(), 1);
+    }
+}

package/dist/create/server-source/crates/feltdb/src/references.rs

@@ -0,0 +1,404 @@
+/// References module for distributed content fabric
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::fmt::{Display, Formatter};
+use std::hash::{Hash, Hasher};
+
+/// A stable reference primitive for distributed FeltDB fabric
+///
+/// FlowRef separates logical identity from physical location.
+/// The same reference can be resolved on different peers.
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
+pub struct FlowRef {
+    /// Namespace containing the object (e.g., "docs", "orders", "embeddings")
+    pub namespace: String,
+    /// Object identifier within the namespace
+    pub object_id: String,
+    /// Version of the object (for content addressing)
+    pub version: Option<u64>,
+}
+
+impl FlowRef {
+    /// Create a new FlowRef with namespace and object_id
+    pub fn new(namespace: impl Into<String>, object_id: impl Into<String>) -> Self {
+        Self {
+            namespace: namespace.into(),
+            object_id: object_id.into(),
+            version: None,
+        }
+    }
+
+    /// Create a FlowRef with explicit version
+    pub fn with_version(
+        namespace: impl Into<String>,
+        object_id: impl Into<String>,
+        version: u64,
+    ) -> Self {
+        Self {
+            namespace: namespace.into(),
+            object_id: object_id.into(),
+            version: Some(version),
+        }
+    }
+
+    /// Get a canonical string representation
+    pub fn canonical(&self) -> String {
+        match self.version {
+            Some(v) => format!("flow://{}#{}@{}", self.namespace, self.object_id, v),
+            None => format!("flow://{}#{}", self.namespace, self.object_id),
+        }
+    }
+
+    /// Parse from canonical form
+    pub fn from_canonical(s: &str) -> Option<Self> {
+        if !s.starts_with("flow://") {
+            return None;
+        }
+        let s = &s[7..]; // Remove "flow://"
+
+        let (namespace, rest) = s.split_once('#')?;
+
+        if let Some((object_id, version_str)) = rest.split_once('@') {
+            let version = version_str.parse().ok()?;
+            Some(Self {
+                namespace: namespace.to_string(),
+                object_id: object_id.to_string(),
+                version: Some(version),
+            })
+        } else {
+            Some(Self {
+                namespace: namespace.to_string(),
+                object_id: rest.to_string(),
+                version: None,
+            })
+        }
+    }
+}
+
+impl Display for FlowRef {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.canonical())
+    }
+}
+
+impl Hash for FlowRef {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.namespace.hash(state);
+        self.object_id.hash(state);
+        self.version.hash(state);
+    }
+}
+
+/// Content identity based on hash
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, Hash)]
+pub struct ContentIdentity {
+    /// SHA-256 hash of the content
+    pub hash: String,
+}
+
+impl ContentIdentity {
+    /// Create a new ContentIdentity from a hash string
+    pub fn new(hash: impl Into<String>) -> Self {
+        Self { hash: hash.into() }
+    }
+
+    /// Compute content hash from serialized data
+    pub fn from_bytes(data: &[u8]) -> Self {
+        let hash = sha256(data);
+        Self { hash }
+    }
+
+    /// Get the hash as a hex string
+    pub fn as_str(&self) -> &str {
+        &self.hash
+    }
+}
+
+impl Display for ContentIdentity {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "sha256:{}", self.hash)
+    }
+}
+
+/// Compute SHA-256 hash of the data
+fn sha256(data: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(data);
+    let result = hasher.finalize();
+    format!("{:x}", result)
+}
+
+/// Peer identifier in the distributed fabric
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, Hash)]
+pub struct PeerId {
+    /// Unique identifier for a peer
+    pub id: String,
+}
+
+impl PeerId {
+    /// Create a new PeerId
+    pub fn new(id: impl Into<String>) -> Self {
+        Self { id: id.into() }
+    }
+}
+
+impl Display for PeerId {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.id)
+    }
+}
+
+/// Advertisement of what a peer provides
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PeerAdvertisement {
+    /// The peer being advertised
+    pub peer_id: PeerId,
+    /// Namespaces this peer provides
+    pub namespaces: Vec<String>,
+    /// Content ranges available (can be extended to include ranges)
+    pub content_ranges: Vec<ContentRange>,
+    /// Capabilities this peer provides (e.g., "search:docs", "vector:embeddings")
+    pub capabilities: Vec<String>,
+    /// Timestamp when this advertisement was created
+    pub advertised_at_ms: u128,
+}
+
+impl PeerAdvertisement {
+    /// Create a new peer advertisement
+    pub fn new(peer_id: PeerId) -> Self {
+        Self {
+            peer_id,
+            namespaces: Vec::new(),
+            content_ranges: Vec::new(),
+            capabilities: Vec::new(),
+            advertised_at_ms: crate::now_ms(),
+        }
+    }
+
+    /// Add a namespace this peer provides
+    pub fn with_namespace(mut self, namespace: impl Into<String>) -> Self {
+        self.namespaces.push(namespace.into());
+        self
+    }
+
+    /// Add multiple namespaces
+    pub fn with_namespaces(mut self, namespaces: Vec<String>) -> Self {
+        self.namespaces.extend(namespaces);
+        self
+    }
+
+    /// Add a capability this peer provides
+    pub fn with_capability(mut self, capability: impl Into<String>) -> Self {
+        self.capabilities.push(capability.into());
+        self
+    }
+
+    /// Add multiple capabilities
+    pub fn with_capabilities(mut self, capabilities: Vec<String>) -> Self {
+        self.capabilities.extend(capabilities);
+        self
+    }
+
+    /// Add a content range
+    pub fn with_range(mut self, range: ContentRange) -> Self {
+        self.content_ranges.push(range);
+        self
+    }
+
+    /// Check if this peer provides a specific namespace
+    pub fn provides_namespace(&self, namespace: &str) -> bool {
+        self.namespaces.iter().any(|ns| ns == namespace)
+    }
+
+    /// Check if this peer provides a specific capability
+    pub fn provides_capability(&self, capability: &str) -> bool {
+        self.capabilities.iter().any(|cap| cap == capability)
+    }
+}
+
+/// A range of content available on a peer
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
+pub struct ContentRange {
+    /// Start of the range (inclusive)
+    pub start: String,
+    /// End of the range (inclusive)
+    pub end: String,
+    /// Number of items in this range
+    pub count: u64,
+}
+
+impl ContentRange {
+    /// Create a new content range
+    pub fn new(start: impl Into<String>, end: impl Into<String>, count: u64) -> Self {
+        Self {
+            start: start.into(),
+            end: end.into(),
+            count,
+        }
+    }
+
+    /// Check if an object_id is in this range
+    pub fn contains(&self, object_id: &str) -> bool {
+        object_id >= self.start.as_str() && object_id <= self.end.as_str()
+    }
+}
+
+/// Trait for resolving FlowRefs to actual objects
+pub trait ReferenceResolver: Send + Sync {
+    /// Resolve a reference to its content
+    /// Returns the serialized content if found
+    fn resolve(&self, flow_ref: &FlowRef) -> Result<Option<Vec<u8>>, String>;
+
+    /// Check if a reference can be resolved
+    fn can_resolve(&self, flow_ref: &FlowRef) -> bool;
+
+    /// List all references in a namespace
+    fn list_namespace(&self, namespace: &str) -> Result<Vec<FlowRef>, String>;
+}
+
+/// Metadata about a resolved reference
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResolutionMetadata {
+    /// Whether the content was found locally or acquired remotely
+    pub is_local: bool,
+    /// If acquired remotely, which peer provided it
+    pub source_peer: Option<PeerId>,
+    /// Timestamp when content was resolved/acquired (ms since UNIX epoch)
+    pub resolved_at_ms: u128,
+}
+
+impl ResolutionMetadata {
+    /// Create metadata for locally resolved content
+    pub fn local() -> Self {
+        Self {
+            is_local: true,
+            source_peer: None,
+            resolved_at_ms: crate::now_ms(),
+        }
+    }
+
+    /// Create metadata for remotely acquired content
+    pub fn remote(source_peer: PeerId) -> Self {
+        Self {
+            is_local: false,
+            source_peer: Some(source_peer),
+            resolved_at_ms: crate::now_ms(),
+        }
+    }
+}
+
+/// Result of content resolution with metadata
+#[derive(Debug, Clone)]
+pub struct ResolutionResult {
+    /// The actual content
+    pub content: Vec<u8>,
+    /// Metadata about how it was resolved
+    pub metadata: ResolutionMetadata,
+}
+
+impl ResolutionResult {
+    /// Create a resolution result for local content
+    pub fn local(content: Vec<u8>) -> Self {
+        Self {
+            content,
+            metadata: ResolutionMetadata::local(),
+        }
+    }
+
+    /// Create a resolution result for remotely acquired content
+    pub fn remote(content: Vec<u8>, source_peer: PeerId) -> Self {
+        Self {
+            content,
+            metadata: ResolutionMetadata::remote(source_peer),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_flow_ref_canonical() {
+        let r = FlowRef::new("docs", "123");
+        assert_eq!(r.canonical(), "flow://docs#123");
+
+        let r = FlowRef::with_version("docs", "123", 42);
+        assert_eq!(r.canonical(), "flow://docs#123@42");
+    }
+
+    #[test]
+    fn test_flow_ref_parse() {
+        let s = "flow://docs#123";
+        let r = FlowRef::from_canonical(s).unwrap();
+        assert_eq!(r.namespace, "docs");
+        assert_eq!(r.object_id, "123");
+        assert_eq!(r.version, None);
+
+        let s = "flow://docs#123@42";
+        let r = FlowRef::from_canonical(s).unwrap();
+        assert_eq!(r.namespace, "docs");
+        assert_eq!(r.object_id, "123");
+        assert_eq!(r.version, Some(42));
+    }
+
+    #[test]
+    fn test_content_range_contains() {
+        let range = ContentRange::new("a", "z", 26);
+        assert!(range.contains("m"));
+        assert!(range.contains("a"));
+        assert!(range.contains("z"));
+        assert!(!range.contains("0"));
+    }
+
+    #[test]
+    fn test_peer_advertisement() {
+        let peer = PeerId::new("peer-a");
+        let ad = PeerAdvertisement::new(peer.clone())
+            .with_namespace("docs")
+            .with_namespace("orders")
+            .with_capability("search:docs");
+
+        assert!(ad.provides_namespace("docs"));
+        assert!(ad.provides_capability("search:docs"));
+        assert!(!ad.provides_namespace("embeddings"));
+    }
+
+    #[test]
+    fn test_resolution_metadata_local() {
+        let metadata = ResolutionMetadata::local();
+        assert!(metadata.is_local);
+        assert!(metadata.source_peer.is_none());
+        assert!(metadata.resolved_at_ms > 0);
+    }
+
+    #[test]
+    fn test_resolution_metadata_remote() {
+        let peer = PeerId::new("peer-b");
+        let metadata = ResolutionMetadata::remote(peer.clone());
+        assert!(!metadata.is_local);
+        assert_eq!(metadata.source_peer, Some(peer));
+        assert!(metadata.resolved_at_ms > 0);
+    }
+
+    #[test]
+    fn test_resolution_result_creation() {
+        let content = b"test content".to_vec();
+        let result = ResolutionResult::local(content.clone());
+
+        assert_eq!(result.content, content);
+        assert!(result.metadata.is_local);
+        assert!(result.metadata.source_peer.is_none());
+    }
+
+    #[test]
+    fn test_resolution_result_remote() {
+        let content = b"acquired content".to_vec();
+        let peer = PeerId::new("provider-peer");
+        let result = ResolutionResult::remote(content.clone(), peer.clone());
+
+        assert_eq!(result.content, content);
+        assert!(!result.metadata.is_local);
+        assert_eq!(result.metadata.source_peer, Some(peer));
+    }
+}