rustyclaw_core/protocols/
freshness.rs

1//! Freshness Protocol — Data Volatility Awareness
2//!
3//! LLMs confidently produce outdated information: model IDs, pricing, deprecated APIs,
4//! old package versions. This protocol categorizes data by volatility and indicates
5//! when verification is needed.
6//!
7//! # Volatility Tiers
8//!
9//! - **Critical**: Changes in days/weeks (model IDs, pricing, CVEs) — MUST verify
10//! - **High**: Changes in weeks/months (package versions, framework APIs) — verify when writing config
11//! - **Medium**: Changes in months/quarters (browser APIs, compliance) — verify if uncertain
12//! - **Stable**: Changes over years (language syntax, protocols) — trust training data
13
14use serde::{Deserialize, Serialize};
15
16/// Volatility tier indicating how frequently data changes
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(rename_all = "lowercase")]
19pub enum VolatilityTier {
20    /// Changes in days to weeks — MUST verify before using
21    /// Examples: LLM model IDs, API pricing, CVEs, SDK breaking changes
22    Critical,
23    
24    /// Changes in weeks to months — verify when writing config/deps
25    /// Examples: package versions, framework APIs, Docker tags, cloud services
26    High,
27    
28    /// Changes in months to quarters — verify if uncertain
29    /// Examples: browser APIs, crypto recommendations, compliance frameworks
30    Medium,
31    
32    /// Changes over years — trust training data
33    /// Examples: language syntax, protocols, algorithms, design patterns
34    Stable,
35}
36
37impl VolatilityTier {
38    /// Whether this tier requires verification before use
39    pub fn requires_verification(&self) -> bool {
40        matches!(self, VolatilityTier::Critical | VolatilityTier::High)
41    }
42    
43    /// Human-readable recommendation for this tier
44    pub fn recommendation(&self) -> &'static str {
45        match self {
46            VolatilityTier::Critical => "MUST verify via web search before implementing",
47            VolatilityTier::High => "Verify when writing config, versions, or integration code",
48            VolatilityTier::Medium => "Verify if uncertain or version-specific",
49            VolatilityTier::Stable => "Trust training data — rarely changes",
50        }
51    }
52}
53
54/// Categories of data with their volatility tiers
55#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "snake_case")]
57pub enum DataCategory {
58    // Critical tier
59    LlmModelIds,
60    ApiPricing,
61    SecurityAdvisories,
62    SdkBreakingChanges,
63    DeprecatedFeatures,
64    
65    // High tier
66    PackageVersions,
67    FrameworkApis,
68    DockerBaseTags,
69    CloudServices,
70    TerraformSchemas,
71    CiCdSyntax,
72    OAuthFlows,
73    CliFlags,
74    
75    // Medium tier
76    BrowserApis,
77    CryptoAlgorithms,
78    ComplianceFrameworks,
79    InfraBestPractices,
80    
81    // Stable tier
82    LanguageFundamentals,
83    Protocols,
84    SqlFundamentals,
85    Algorithms,
86    DesignPatterns,
87    GitOperations,
88}
89
90impl DataCategory {
91    /// Get the volatility tier for this category
92    pub fn tier(&self) -> VolatilityTier {
93        match self {
94            // Critical
95            DataCategory::LlmModelIds
96            | DataCategory::ApiPricing
97            | DataCategory::SecurityAdvisories
98            | DataCategory::SdkBreakingChanges
99            | DataCategory::DeprecatedFeatures => VolatilityTier::Critical,
100            
101            // High
102            DataCategory::PackageVersions
103            | DataCategory::FrameworkApis
104            | DataCategory::DockerBaseTags
105            | DataCategory::CloudServices
106            | DataCategory::TerraformSchemas
107            | DataCategory::CiCdSyntax
108            | DataCategory::OAuthFlows
109            | DataCategory::CliFlags => VolatilityTier::High,
110            
111            // Medium
112            DataCategory::BrowserApis
113            | DataCategory::CryptoAlgorithms
114            | DataCategory::ComplianceFrameworks
115            | DataCategory::InfraBestPractices => VolatilityTier::Medium,
116            
117            // Stable
118            DataCategory::LanguageFundamentals
119            | DataCategory::Protocols
120            | DataCategory::SqlFundamentals
121            | DataCategory::Algorithms
122            | DataCategory::DesignPatterns
123            | DataCategory::GitOperations => VolatilityTier::Stable,
124        }
125    }
126    
127    /// Description of what this category covers
128    pub fn description(&self) -> &'static str {
129        match self {
130            DataCategory::LlmModelIds => "LLM/AI model names, context windows, capabilities",
131            DataCategory::ApiPricing => "Cloud service, SaaS, or API pricing",
132            DataCategory::SecurityAdvisories => "Active CVEs, vulnerability disclosures",
133            DataCategory::SdkBreakingChanges => "Major SDK/library version breaking changes",
134            DataCategory::DeprecatedFeatures => "APIs, services, or flags marked for removal",
135            DataCategory::PackageVersions => "Latest stable versions of libraries/frameworks",
136            DataCategory::FrameworkApis => "Next.js, React, FastAPI, etc. API surfaces",
137            DataCategory::DockerBaseTags => "Current LTS/stable Docker image tags",
138            DataCategory::CloudServices => "AWS/GCP/Azure service names and features",
139            DataCategory::TerraformSchemas => "Terraform/Pulumi resource schemas",
140            DataCategory::CiCdSyntax => "GitHub Actions, GitLab CI workflow syntax",
141            DataCategory::OAuthFlows => "Provider-specific OAuth endpoints and scopes",
142            DataCategory::CliFlags => "CLI tool flags and subcommands",
143            DataCategory::BrowserApis => "Web APIs, CSS features, browser support",
144            DataCategory::CryptoAlgorithms => "Current best practices for hashing/encryption",
145            DataCategory::ComplianceFrameworks => "SOC2, HIPAA, GDPR requirements",
146            DataCategory::InfraBestPractices => "Instance types, scaling patterns",
147            DataCategory::LanguageFundamentals => "Language syntax, type systems, stdlib",
148            DataCategory::Protocols => "HTTP, TCP/IP, WebSocket, gRPC",
149            DataCategory::SqlFundamentals => "SQL and database fundamentals",
150            DataCategory::Algorithms => "Algorithms and data structures",
151            DataCategory::DesignPatterns => "Design patterns and architecture principles",
152            DataCategory::GitOperations => "Git operations and workflows",
153        }
154    }
155}
156
157/// Freshness protocol for tracking data volatility
158pub struct FreshnessProtocol;
159
160impl FreshnessProtocol {
161    /// Check if a piece of data needs verification
162    pub fn needs_verification(category: DataCategory) -> bool {
163        category.tier().requires_verification()
164    }
165    
166    /// Get verification guidance for a category
167    pub fn guidance(category: DataCategory) -> String {
168        format!(
169            "{}: {} — {}",
170            category.description(),
171            format!("{:?}", category.tier()).to_uppercase(),
172            category.tier().recommendation()
173        )
174    }
175    
176    /// Classify text to detect potential volatile data
177    /// Returns categories that might need verification
178    pub fn classify_text(text: &str) -> Vec<DataCategory> {
179        let mut categories = Vec::new();
180        let lower = text.to_lowercase();
181        
182        // Model IDs
183        if lower.contains("gpt-4") || lower.contains("claude") || lower.contains("gemini")
184            || lower.contains("model") && (lower.contains("id") || lower.contains("name"))
185        {
186            categories.push(DataCategory::LlmModelIds);
187        }
188        
189        // Pricing
190        if lower.contains("price") || lower.contains("pricing") || lower.contains("cost")
191            || lower.contains("$/") || lower.contains("per token")
192        {
193            categories.push(DataCategory::ApiPricing);
194        }
195        
196        // Security
197        if lower.contains("cve-") || lower.contains("vulnerability") || lower.contains("advisory")
198        {
199            categories.push(DataCategory::SecurityAdvisories);
200        }
201        
202        // Package versions
203        if lower.contains("version") || lower.contains("@") || lower.contains("^")
204            || lower.contains("~") || lower.contains("latest")
205        {
206            categories.push(DataCategory::PackageVersions);
207        }
208        
209        // Docker
210        if lower.contains("docker") || lower.contains("from ") || lower.contains(":alpine")
211            || lower.contains(":slim")
212        {
213            categories.push(DataCategory::DockerBaseTags);
214        }
215        
216        categories
217    }
218    
219    /// Format a verification citation
220    pub fn format_citation(what: &str, source: &str, date: &str) -> String {
221        format!("✓ Verified: {} ({}, {})", what, source, date)
222    }
223}
224
225#[cfg(test)]
226mod tests {
227    use super::*;
228    
229    #[test]
230    fn test_volatility_tiers() {
231        assert!(VolatilityTier::Critical.requires_verification());
232        assert!(VolatilityTier::High.requires_verification());
233        assert!(!VolatilityTier::Medium.requires_verification());
234        assert!(!VolatilityTier::Stable.requires_verification());
235    }
236    
237    #[test]
238    fn test_category_tiers() {
239        assert_eq!(DataCategory::LlmModelIds.tier(), VolatilityTier::Critical);
240        assert_eq!(DataCategory::PackageVersions.tier(), VolatilityTier::High);
241        assert_eq!(DataCategory::BrowserApis.tier(), VolatilityTier::Medium);
242        assert_eq!(DataCategory::Algorithms.tier(), VolatilityTier::Stable);
243    }
244    
245    #[test]
246    fn test_text_classification() {
247        let categories = FreshnessProtocol::classify_text("Use gpt-4o model");
248        assert!(categories.contains(&DataCategory::LlmModelIds));
249        
250        let categories = FreshnessProtocol::classify_text("FROM node:22-alpine");
251        assert!(categories.contains(&DataCategory::DockerBaseTags));
252        
253        let categories = FreshnessProtocol::classify_text("CVE-2026-1234 vulnerability");
254        assert!(categories.contains(&DataCategory::SecurityAdvisories));
255    }
256}
rustyclaw_core/protocols/freshness.rs

rustyclaw_core/protocols/
freshness.rs
