rust_rule_engine/rete/
propagation.rs

1//! Incremental Propagation Engine (P3 Feature - Advanced)
2//!
3//! This module implements incremental updates similar to Drools:
4//! - Only propagate changed facts through the network
5//! - Track affected rules and activations
6//! - Efficient re-evaluation after updates
7
8use std::collections::{HashMap, HashSet};
9use std::sync::Arc;
10use super::working_memory::{WorkingMemory, FactHandle};
11use super::network::{ReteUlNode, TypedReteUlRule};
12use super::facts::{TypedFacts, FactValue};
13use super::agenda::{AdvancedAgenda, Activation};
14use super::template::TemplateRegistry;
15use super::globals::GlobalsRegistry;
16use super::deffacts::DeffactsRegistry;
17use crate::errors::{Result, RuleEngineError};
18
19/// Track which rules are affected by which fact types
20#[derive(Debug)]
21pub struct RuleDependencyGraph {
22    /// Map: fact_type -> set of rule indices that depend on it
23    fact_type_to_rules: HashMap<String, HashSet<usize>>,
24    /// Map: rule index -> set of fact types it depends on
25    rule_to_fact_types: HashMap<usize, HashSet<String>>,
26}
27
28impl RuleDependencyGraph {
29    /// Create new dependency graph
30    pub fn new() -> Self {
31        Self {
32            fact_type_to_rules: HashMap::new(),
33            rule_to_fact_types: HashMap::new(),
34        }
35    }
36
37    /// Add dependency: rule depends on fact type
38    pub fn add_dependency(&mut self, rule_idx: usize, fact_type: String) {
39        self.fact_type_to_rules
40            .entry(fact_type.clone())
41            .or_insert_with(HashSet::new)
42            .insert(rule_idx);
43
44        self.rule_to_fact_types
45            .entry(rule_idx)
46            .or_insert_with(HashSet::new)
47            .insert(fact_type);
48    }
49
50    /// Get rules affected by a fact type change
51    pub fn get_affected_rules(&self, fact_type: &str) -> HashSet<usize> {
52        self.fact_type_to_rules
53            .get(fact_type)
54            .cloned()
55            .unwrap_or_else(HashSet::new)
56    }
57
58    /// Get fact types that a rule depends on
59    pub fn get_rule_dependencies(&self, rule_idx: usize) -> HashSet<String> {
60        self.rule_to_fact_types
61            .get(&rule_idx)
62            .cloned()
63            .unwrap_or_else(HashSet::new)
64    }
65}
66
67impl Default for RuleDependencyGraph {
68    fn default() -> Self {
69        Self::new()
70    }
71}
72
73/// Type alias for custom test functions in RETE engine
74/// Functions take a slice of FactValues and return a FactValue (typically Boolean)
75pub type ReteCustomFunction = Arc<dyn Fn(&[FactValue], &TypedFacts) -> Result<FactValue> + Send + Sync>;
76
77/// Incremental Propagation Engine
78/// Only re-evaluates rules affected by changed facts
79pub struct IncrementalEngine {
80    /// Working memory
81    working_memory: WorkingMemory,
82    /// Rules
83    rules: Vec<TypedReteUlRule>,
84    /// Dependency graph
85    dependencies: RuleDependencyGraph,
86    /// Advanced agenda
87    agenda: AdvancedAgenda,
88    /// Track which facts each rule last matched
89    rule_matched_facts: HashMap<usize, HashSet<FactHandle>>,
90    /// Template registry for type-safe facts
91    templates: TemplateRegistry,
92    /// Global variables registry
93    globals: GlobalsRegistry,
94    /// Deffacts registry for initial facts
95    deffacts: DeffactsRegistry,
96    /// Custom functions for Test CE support
97    custom_functions: HashMap<String, ReteCustomFunction>,
98}
99
100impl IncrementalEngine {
101    /// Create new incremental engine
102    pub fn new() -> Self {
103        Self {
104            working_memory: WorkingMemory::new(),
105            rules: Vec::new(),
106            dependencies: RuleDependencyGraph::new(),
107            agenda: AdvancedAgenda::new(),
108            rule_matched_facts: HashMap::new(),
109            custom_functions: HashMap::new(),
110            templates: TemplateRegistry::new(),
111            globals: GlobalsRegistry::new(),
112            deffacts: DeffactsRegistry::new(),
113        }
114    }
115
116    /// Add rule and register its dependencies
117    pub fn add_rule(&mut self, rule: TypedReteUlRule, depends_on: Vec<String>) {
118        let rule_idx = self.rules.len();
119
120        // Register dependencies
121        for fact_type in depends_on {
122            self.dependencies.add_dependency(rule_idx, fact_type);
123        }
124
125        self.rules.push(rule);
126    }
127
128    /// Insert fact into working memory
129    pub fn insert(&mut self, fact_type: String, data: TypedFacts) -> FactHandle {
130        let handle = self.working_memory.insert(fact_type.clone(), data);
131
132        // Trigger incremental propagation for this fact type
133        self.propagate_changes_for_type(&fact_type);
134
135        handle
136    }
137
138    /// Update fact in working memory
139    pub fn update(&mut self, handle: FactHandle, data: TypedFacts) -> Result<()> {
140        // Get fact type before update
141        let fact_type = self.working_memory
142            .get(&handle)
143            .map(|f| f.fact_type.clone())
144            .ok_or_else(|| RuleEngineError::FieldNotFound {
145                field: format!("FactHandle {} not found", handle),
146            })?;
147
148        self.working_memory.update(handle, data).map_err(|e| RuleEngineError::EvaluationError {
149            message: e,
150        })?;
151
152        // Trigger incremental propagation for this fact type
153        self.propagate_changes_for_type(&fact_type);
154
155        Ok(())
156    }
157
158    /// Retract fact from working memory
159    pub fn retract(&mut self, handle: FactHandle) -> Result<()> {
160        // Get fact type before retract
161        let fact_type = self.working_memory
162            .get(&handle)
163            .map(|f| f.fact_type.clone())
164            .ok_or_else(|| RuleEngineError::FieldNotFound {
165                field: format!("FactHandle {} not found", handle),
166            })?;
167
168        self.working_memory.retract(handle).map_err(|e| RuleEngineError::EvaluationError {
169            message: e,
170        })?;
171
172        // Trigger incremental propagation for this fact type
173        self.propagate_changes_for_type(&fact_type);
174
175        Ok(())
176    }
177
178    /// Propagate changes for a specific fact type (incremental!)
179    fn propagate_changes_for_type(&mut self, fact_type: &str) {
180        // Get affected rules
181        let affected_rules = self.dependencies.get_affected_rules(fact_type);
182
183        if affected_rules.is_empty() {
184            return; // No rules depend on this fact type
185        }
186
187        // Flatten working memory to TypedFacts for evaluation
188        let facts = self.working_memory.to_typed_facts();
189
190        // Re-evaluate only affected rules
191        for &rule_idx in &affected_rules {
192            let rule = &self.rules[rule_idx];
193
194            // Evaluate rule condition
195            let matches = super::network::evaluate_rete_ul_node_typed(&rule.node, &facts);
196
197            if matches {
198                // Create activation
199                let activation = Activation::new(rule.name.clone(), rule.priority)
200                    .with_no_loop(rule.no_loop);
201
202                self.agenda.add_activation(activation);
203            }
204        }
205    }
206
207    /// Fire all pending activations
208    pub fn fire_all(&mut self) -> Vec<String> {
209        let mut fired_rules = Vec::new();
210
211        while let Some(activation) = self.agenda.get_next_activation() {
212            // Find rule
213            if let Some((idx, rule)) = self.rules
214                .iter_mut()
215                .enumerate()
216                .find(|(_, r)| r.name == activation.rule_name)
217            {
218                // Execute action
219                let mut facts = self.working_memory.to_typed_facts();
220                (rule.action)(&mut facts);
221
222                // Track fired rule
223                fired_rules.push(activation.rule_name.clone());
224                self.agenda.mark_rule_fired(&activation);
225
226                // TODO: Update working memory with changed facts
227                // This is complex and would require tracking what changed
228            }
229        }
230
231        fired_rules
232    }
233
234    /// Get working memory
235    pub fn working_memory(&self) -> &WorkingMemory {
236        &self.working_memory
237    }
238
239    /// Get mutable working memory
240    pub fn working_memory_mut(&mut self) -> &mut WorkingMemory {
241        &mut self.working_memory
242    }
243
244    /// Get agenda
245    pub fn agenda(&self) -> &AdvancedAgenda {
246        &self.agenda
247    }
248
249    /// Get mutable agenda
250    pub fn agenda_mut(&mut self) -> &mut AdvancedAgenda {
251        &mut self.agenda
252    }
253
254    /// Get statistics
255    pub fn stats(&self) -> IncrementalEngineStats {
256        IncrementalEngineStats {
257            rules: self.rules.len(),
258            working_memory: self.working_memory.stats(),
259            agenda: self.agenda.stats(),
260            dependencies: self.dependencies.fact_type_to_rules.len(),
261        }
262    }
263
264    /// Clear fired flags and reset agenda
265    pub fn reset(&mut self) {
266        self.agenda.reset_fired_flags();
267    }
268
269    /// Get template registry
270    pub fn templates(&self) -> &TemplateRegistry {
271        &self.templates
272    }
273
274    /// Get mutable template registry
275    pub fn templates_mut(&mut self) -> &mut TemplateRegistry {
276        &mut self.templates
277    }
278
279    /// Register a custom function for Test CE support
280    ///
281    /// # Example
282    /// ```
283    /// use rust_rule_engine::rete::{IncrementalEngine, FactValue};
284    ///
285    /// let mut engine = IncrementalEngine::new();
286    /// engine.register_function(
287    ///     "is_valid_email",
288    ///     |args, _facts| {
289    ///         if let Some(FactValue::String(email)) = args.first() {
290    ///             Ok(FactValue::Boolean(email.contains('@')))
291    ///         } else {
292    ///             Ok(FactValue::Boolean(false))
293    ///         }
294    ///     }
295    /// );
296    /// ```
297    pub fn register_function<F>(&mut self, name: &str, func: F)
298    where
299        F: Fn(&[FactValue], &TypedFacts) -> Result<FactValue> + Send + Sync + 'static,
300    {
301        self.custom_functions.insert(name.to_string(), Arc::new(func));
302    }
303
304    /// Get a custom function by name (for Test CE evaluation)
305    pub fn get_function(&self, name: &str) -> Option<&ReteCustomFunction> {
306        self.custom_functions.get(name)
307    }
308
309    /// Get global variables registry
310    pub fn globals(&self) -> &GlobalsRegistry {
311        &self.globals
312    }
313
314    /// Get mutable global variables registry
315    pub fn globals_mut(&mut self) -> &mut GlobalsRegistry {
316        &mut self.globals
317    }
318
319    /// Get deffacts registry
320    pub fn deffacts(&self) -> &DeffactsRegistry {
321        &self.deffacts
322    }
323
324    /// Get mutable deffacts registry
325    pub fn deffacts_mut(&mut self) -> &mut DeffactsRegistry {
326        &mut self.deffacts
327    }
328
329    /// Load all registered deffacts into working memory
330    /// Returns handles of all inserted facts
331    pub fn load_deffacts(&mut self) -> Vec<FactHandle> {
332        let mut handles = Vec::new();
333
334        // Get all facts from all registered deffacts
335        let all_facts = self.deffacts.get_all_facts();
336
337        for (_deffacts_name, fact_instance) in all_facts {
338            // Check if template exists for this fact type
339            let handle = if self.templates.get(&fact_instance.fact_type).is_some() {
340                // Use template validation
341                match self.insert_with_template(&fact_instance.fact_type, fact_instance.data) {
342                    Ok(h) => h,
343                    Err(_) => continue, // Skip invalid facts
344                }
345            } else {
346                // Insert without template validation
347                self.insert(fact_instance.fact_type, fact_instance.data)
348            };
349
350            handles.push(handle);
351        }
352
353        handles
354    }
355
356    /// Load a specific deffacts set by name
357    /// Returns handles of inserted facts or error if deffacts not found
358    pub fn load_deffacts_by_name(&mut self, name: &str) -> crate::errors::Result<Vec<FactHandle>> {
359        // Clone the facts to avoid borrow checker issues
360        let facts_to_insert = {
361            let deffacts = self.deffacts.get(name).ok_or_else(|| {
362                crate::errors::RuleEngineError::EvaluationError {
363                    message: format!("Deffacts '{}' not found", name),
364                }
365            })?;
366            deffacts.facts.clone()
367        };
368
369        let mut handles = Vec::new();
370
371        for fact_instance in facts_to_insert {
372            // Check if template exists for this fact type
373            let handle = if self.templates.get(&fact_instance.fact_type).is_some() {
374                // Use template validation
375                self.insert_with_template(&fact_instance.fact_type, fact_instance.data)?
376            } else {
377                // Insert without template validation
378                self.insert(fact_instance.fact_type, fact_instance.data)
379            };
380
381            handles.push(handle);
382        }
383
384        Ok(handles)
385    }
386
387    /// Reset engine and reload all deffacts (similar to CLIPS reset)
388    /// Clears working memory and agenda, then loads all deffacts
389    pub fn reset_with_deffacts(&mut self) -> Vec<FactHandle> {
390        // Clear working memory and agenda
391        self.working_memory = WorkingMemory::new();
392        self.agenda.clear();
393        self.rule_matched_facts.clear();
394
395        // Reload all deffacts
396        self.load_deffacts()
397    }
398
399    /// Insert a typed fact with template validation
400    pub fn insert_with_template(
401        &mut self,
402        template_name: &str,
403        data: TypedFacts,
404    ) -> crate::errors::Result<FactHandle> {
405        // Validate against template
406        self.templates.validate(template_name, &data)?;
407
408        // Insert into working memory
409        Ok(self.insert(template_name.to_string(), data))
410    }
411}
412
413impl Default for IncrementalEngine {
414    fn default() -> Self {
415        Self::new()
416    }
417}
418
419/// Engine statistics
420#[derive(Debug)]
421pub struct IncrementalEngineStats {
422    pub rules: usize,
423    pub working_memory: super::working_memory::WorkingMemoryStats,
424    pub agenda: super::agenda::AgendaStats,
425    pub dependencies: usize,
426}
427
428impl std::fmt::Display for IncrementalEngineStats {
429    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
430        write!(
431            f,
432            "Engine Stats: {} rules, {} fact types tracked\nWM: {}\nAgenda: {}",
433            self.rules,
434            self.dependencies,
435            self.working_memory,
436            self.agenda
437        )
438    }
439}
440
441#[cfg(test)]
442mod tests {
443    use super::*;
444    use crate::rete::network::ReteUlNode;
445    use crate::rete::alpha::AlphaNode;
446
447    #[test]
448    fn test_dependency_graph() {
449        let mut graph = RuleDependencyGraph::new();
450
451        graph.add_dependency(0, "Person".to_string());
452        graph.add_dependency(1, "Person".to_string());
453        graph.add_dependency(1, "Order".to_string());
454
455        let affected = graph.get_affected_rules("Person");
456        assert_eq!(affected.len(), 2);
457        assert!(affected.contains(&0));
458        assert!(affected.contains(&1));
459
460        let deps = graph.get_rule_dependencies(1);
461        assert_eq!(deps.len(), 2);
462        assert!(deps.contains("Person"));
463        assert!(deps.contains("Order"));
464    }
465
466    #[test]
467    fn test_incremental_propagation() {
468        let mut engine = IncrementalEngine::new();
469
470        // Add rule that depends on "Person" type
471        let node = ReteUlNode::UlAlpha(AlphaNode {
472            field: "Person.age".to_string(),
473            operator: ">".to_string(),
474            value: "18".to_string(),
475        });
476
477        let rule = TypedReteUlRule {
478            name: "IsAdult".to_string(),
479            node,
480            priority: 0,
481            no_loop: true,
482            action: Box::new(|_| {}),
483        };
484
485        engine.add_rule(rule, vec!["Person".to_string()]);
486
487        // Insert Person fact
488        let mut person = TypedFacts::new();
489        person.set("age", 25i64);
490        let handle = engine.insert("Person".to_string(), person);
491
492        // Check that rule was activated
493        let stats = engine.stats();
494        assert!(stats.agenda.total_activations > 0);
495
496        // Update person
497        let mut updated = TypedFacts::new();
498        updated.set("age", 15i64); // Now under 18
499        engine.update(handle, updated).unwrap();
500
501        // Rule should be re-evaluated (incrementally)
502    }
503}
rust_rule_engine/rete/propagation.rs

rust_rule_engine/rete/
propagation.rs
