Skip to main content

clm_rust_core/layer5/
petri_learning.rs

1//! Layer 5 Epistemic Learning Petri Net with Cordis HMR (Sprint 518, GAP-18, INV-518).
2//! Canonical Path: kernel/clm_rust_core/src/layer5/petri_learning.rs
3
4use std::collections::{BTreeMap, BTreeSet, HashMap};
5use serde::{Deserialize, Serialize};
6use serde_json::{json, Value};
7
8use crate::cpn::mcard_token::{PlaceMCard, TokenMCard, TransitionMCard};
9use crate::cpn::place_type_lattice::{PlaceRole, PlaceTypeLattice};
10use crate::cpn::token_namespace::{FiringReceiptMCard, MCardMarking, MCardTokenNamespace};
11use crate::domain::BailVerdict;
12use crate::layer1::fractal_net_harness::{register_place_specs, PlaceSpec};
13
14pub type EpistemicPlaceMCard = PlaceMCard;
15pub type LearningTransitionPCard = TransitionMCard;
16
17/// Result of firing a Layer 5 epistemic learning transition.
18#[derive(Debug, Clone, Serialize, Deserialize)]
19pub struct LearningCycleResult {
20    pub assimilated: bool,
21    pub trapped_to_falsified: bool,
22    pub delta_e: f64,
23    pub crystallized_pcard_token: TokenMCard,
24    pub marking: MCardMarking,
25    pub receipt: FiringReceiptMCard,
26    pub hmr_trace: Vec<String>,
27}
28
29/// Layer 5 Meta-Circular Loop Gamma modeled as an Epistemic Petri Net with Cordis HMR.
30pub struct Layer5EpistemicLearningNet {
31    pub namespace: MCardTokenNamespace,
32    pub lattice: PlaceTypeLattice,
33    pub active_instincts: HashMap<String, String>,
34}
35
36impl Default for Layer5EpistemicLearningNet {
37    fn default() -> Self {
38        Self::new()
39    }
40}
41
42impl Layer5EpistemicLearningNet {
43    /// Creates a new `Layer5EpistemicLearningNet` with 4 canonical epistemic places.
44    pub fn new() -> Self {
45        let mut namespace = MCardTokenNamespace::new("layer5_learning");
46
47        // Sprint 533: place table replaces four build-and-register blocks.
48        // Each binding keeps its explicit type URI, as before.
49        let specs = [
50            PlaceSpec::new("p_untrained", crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_UNTRAINED, PlaceRole::InitialBottom)
51                .with_binding_type_uri(crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_UNTRAINED),
52            PlaceSpec::new("p_candidate", crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_CANDIDATE, PlaceRole::Intermediate)
53                .with_binding_type_uri(crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_CANDIDATE),
54            PlaceSpec::new("p_assimilated", crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_ASSIMILATED, PlaceRole::TerminalTop)
55                .with_binding_type_uri(crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_ASSIMILATED),
56            PlaceSpec::new("p_falsified_exception", crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_FALSIFIED_TRAP, PlaceRole::Exception)
57                .with_binding_type_uri(crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_FALSIFIED_TRAP),
58        ];
59        let places = register_place_specs(&mut namespace, &specs).expect("valid learning places");
60
61        let mut exc_ids = BTreeSet::new();
62        exc_ids.insert("p_falsified_exception".to_string());
63        let lattice = PlaceTypeLattice::from_net(&places, &[], Some(&exc_ids));
64
65        Self {
66            namespace,
67            lattice,
68            active_instincts: HashMap::new(),
69        }
70    }
71
72    /// Deposits an observation `TokenMCard` into `p_untrained`.
73    pub fn seed_observation(
74        &mut self,
75        marking: &MCardMarking,
76        observation_payload: Value,
77    ) -> (MCardMarking, TokenMCard) {
78        let tok = TokenMCard::from_payload(
79            observation_payload,
80            crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_UNTRAINED,
81            "tok_obs",
82            Some(crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3),
83            None,
84        ).expect("observation token");
85
86        let mut next_marking = marking.clone();
87        next_marking.append("p_untrained", tok.qualified_hash());
88        self.namespace.tokens_by_ref.insert(tok.qualified_hash(), tok.clone());
89        self.namespace.records_by_ref.insert(tok.qualified_hash(), tok.card.clone());
90        self.namespace.marking = next_marking.clone();
91        (next_marking, tok)
92    }
93
94    /// Executes a `LearningTransitionPCard` gated by `delta_e > 0`.
95    pub fn run_learning_transition(
96        &mut self,
97        marking: &MCardMarking,
98        observation_token: &TokenMCard,
99        skill_handle: &str,
100        baseline_fitness: f64,
101        candidate_fitness: f64,
102        synthesized_guard: &str,
103    ) -> LearningCycleResult {
104        let delta_e = ((candidate_fitness - baseline_fitness) * 1_000_000.0).round() / 1_000_000.0;
105        let tid = format!("t_learn:{skill_handle}");
106
107        let transition = TransitionMCard::create(
108            &tid,
109            vec!["p_untrained".to_string()],
110            vec!["p_assimilated".to_string()],
111            crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_UNTRAINED,
112            crate::layer0::vocabulary_types::TYPE_URI_CLM_TYPE_EPISTEMIC_ASSIMILATED,
113            Some(BTreeMap::new()),
114            &format!("delta_e({candidate_fitness} - {baseline_fitness}) > 0"),
115            Some(crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3),
116            None,
117        ).expect("learning transition");
118
119        self.namespace.register_transition(transition);
120        self.namespace.marking = marking.clone();
121        self.namespace.tokens_by_ref.insert(observation_token.qualified_hash(), observation_token.clone());
122        self.namespace.records_by_ref.insert(observation_token.qualified_hash(), observation_token.card.clone());
123
124        let prev_ref = self.active_instincts.get(skill_handle).cloned();
125        let guard_str = synthesized_guard.to_string();
126        let handle_str = skill_handle.to_string();
127
128        let res = self.namespace.fire_in_cordis_fiber(
129            &tid,
130            None,
131            Some("p_falsified_exception"),
132            None,
133            move |_raw_inputs| {
134                if delta_e <= 0.0 {
135                    return Err(format!("Epistemic hypothesis falsified for '{handle_str}': delta_e={delta_e} <= 0"));
136                }
137                Ok(json!({
138                    "kind": "crystallized_pcard",
139                    "skill_handle": handle_str,
140                    "synthesized_guard": guard_str,
141                    "delta_e": delta_e,
142                }))
143            },
144            Some(crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3),
145        );
146
147        let (receipt, verdict) = res.expect("fiber execution");
148        if matches!(verdict, BailVerdict::Pass) {
149            let out_tokens = self.namespace.get_place_tokens("p_assimilated");
150            let out_tok = out_tokens.last().cloned().unwrap_or_else(|| observation_token.clone());
151            self.active_instincts.insert(skill_handle.to_string(), out_tok.qualified_hash());
152            LearningCycleResult {
153                assimilated: true,
154                trapped_to_falsified: false,
155                delta_e,
156                crystallized_pcard_token: out_tok,
157                marking: self.namespace.marking.clone(),
158                receipt,
159                hmr_trace: vec![
160                    "OLD_FIBER_UNLOADING".to_string(),
161                    "OLD_FIBER_DISPOSED".to_string(),
162                    "NEW_FIBER_ACTIVE".to_string(),
163                ],
164            }
165        } else {
166            if let Some(prev) = prev_ref {
167                self.active_instincts.insert(skill_handle.to_string(), prev);
168            } else {
169                self.active_instincts.remove(skill_handle);
170            }
171            let exc_tokens = self.namespace.get_place_tokens("p_falsified_exception");
172            let exc_tok = exc_tokens.last().cloned().unwrap_or_else(|| observation_token.clone());
173            LearningCycleResult {
174                assimilated: false,
175                trapped_to_falsified: true,
176                delta_e,
177                crystallized_pcard_token: exc_tok,
178                marking: self.namespace.marking.clone(),
179                receipt,
180                hmr_trace: vec![
181                    "CANDIDATE_FIBER_ABORTED".to_string(),
182                    "PREVIOUS_FIBER_PRESERVED".to_string(),
183                ],
184            }
185        }
186    }
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    #[test]
194    fn test_layer5_epistemic_learning() {
195        let mut net = Layer5EpistemicLearningNet::new();
196        let (m0, tok0) = net.seed_observation(&net.namespace.marking.clone(), json!({ "sensor_reading": 42.0 }));
197        assert_eq!(net.namespace.get_place_tokens("p_untrained").len(), 1);
198
199        let res1 = net.run_learning_transition(
200            &m0,
201            &tok0,
202            "adaptive_sort",
203            0.5,
204            0.85,
205            "len(arr) > 10 -> quicksort",
206        );
207        assert!(res1.assimilated);
208        assert!(!res1.trapped_to_falsified);
209        assert_eq!(res1.delta_e, 0.35);
210        assert_eq!(
211            res1.hmr_trace,
212            vec!["OLD_FIBER_UNLOADING", "OLD_FIBER_DISPOSED", "NEW_FIBER_ACTIVE"]
213        );
214        assert!(net.active_instincts.contains_key("adaptive_sort"));
215
216        let (m1, tok1) = net.seed_observation(&res1.marking, json!({ "sensor_reading": 99.0 }));
217        let res2 = net.run_learning_transition(
218            &m1,
219            &tok1,
220            "adaptive_sort",
221            0.9,
222            0.7,
223            "bogus_guard",
224        );
225        assert!(!res2.assimilated);
226        assert!(res2.trapped_to_falsified);
227        assert_eq!(res2.delta_e, -0.2);
228        assert_eq!(
229            res2.hmr_trace,
230            vec!["CANDIDATE_FIBER_ABORTED", "PREVIOUS_FIBER_PRESERVED"]
231        );
232        assert_eq!(
233            net.active_instincts.get("adaptive_sort"),
234            Some(&res1.crystallized_pcard_token.qualified_hash())
235        );
236    }
237}