Skip to main content

clm_rust_core/layer1/
fractal.rs

1//! Multi-scale FractalMCard and conserved Colored Petri Net knowledge codec (INV-FRAC-01..04).
2
3use std::collections::BTreeMap;
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6
7pub const FRACTAL_ORDERS: [&str; 5] = ["token", "fiber", "collection", "unit", "program"];
8
9#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(rename_all = "camelCase")]
11pub struct KnowledgeTriadSpec {
12    pub abstract_spec: Value,
13    pub concrete_impl: Value,
14    pub balanced_exp: Value,
15}
16
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub struct FractalInterfaceSpec {
19    pub inputs: Vec<String>,
20    pub outputs: Vec<String>,
21}
22
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "camelCase")]
25pub struct FiberTapeEvent {
26    pub from: String,
27    pub to: String,
28    pub timestamp: i64,
29}
30
31#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
32#[serde(rename_all = "camelCase")]
33pub struct FiberCard {
34    pub order: String,
35    pub fiber: String,
36    pub terminal: String,
37    pub tape: Vec<FiberTapeEvent>,
38    pub effects_settled: usize,
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub children: Option<Vec<String>>,
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub triad: Option<KnowledgeTriadSpec>,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub interface: Option<FractalInterfaceSpec>,
45}
46
47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
48pub struct Compression {
49    pub handle: String,
50    pub hash: String,
51    pub content: Vec<u8>,
52    pub card: FiberCard,
53}
54
55pub type FractalMCard = Compression;
56
57#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
58#[serde(rename_all = "camelCase")]
59pub struct DecodedFractalCard {
60    pub handle: String,
61    pub hash: String,
62    pub order: String,
63    pub fiber: String,
64    pub terminal: String,
65    pub tape: Vec<FiberTapeEvent>,
66    pub effects_settled: usize,
67    pub children: Vec<String>,
68    pub triad: Option<KnowledgeTriadSpec>,
69    pub interface: Option<FractalInterfaceSpec>,
70    pub payload: Value,
71}
72
73#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
74#[serde(rename_all = "camelCase")]
75pub struct PlaceSpec {
76    pub place_id: String,
77    pub type_expr: String,
78    pub role: String,
79}
80
81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
82pub struct FractalPetriProjection {
83    pub order: String,
84    pub source_hash: String,
85    pub place_specs: Vec<PlaceSpec>,
86    pub topology: Value,
87    pub p_invariant_weights: (i64, i64, i64),
88}
89
90pub fn is_fractal_order(val: &str) -> bool {
91    FRACTAL_ORDERS.contains(&val)
92}
93
94pub fn hash_of(content: &[u8]) -> String {
95    let mut hasher = blake3::Hasher::new();
96    hasher.update(content);
97    hasher.finalize().to_hex().to_string()
98}
99
100pub fn canonicalise(card: &FiberCard) -> Result<Vec<u8>, serde_json::Error> {
101    let mut map = BTreeMap::new();
102    map.insert("order", Value::String(card.order.clone()));
103    map.insert("fiber", Value::String(card.fiber.clone()));
104    map.insert("terminal", Value::String(card.terminal.clone()));
105
106    let tape_vals: Vec<Value> = card
107        .tape
108        .iter()
109        .map(|e| {
110            let mut em = BTreeMap::new();
111            em.insert("from", Value::String(e.from.clone()));
112            em.insert("timestamp", Value::Number(serde_json::Number::from(e.timestamp)));
113            em.insert("to", Value::String(e.to.clone()));
114            Value::Object(em.into_iter().map(|(k, v)| (k.to_string(), v)).collect())
115        })
116        .collect();
117    map.insert("tape", Value::Array(tape_vals));
118    map.insert("effectsSettled", Value::Number(serde_json::Number::from(card.effects_settled)));
119
120    if let Some(ref ch) = card.children {
121        let mut sorted_ch = ch.clone();
122        sorted_ch.sort();
123        map.insert(
124            "children",
125            Value::Array(sorted_ch.into_iter().map(Value::String).collect()),
126        );
127    }
128
129    if let Some(ref tr) = card.triad {
130        let mut tm = BTreeMap::new();
131        tm.insert("abstractSpec", tr.abstract_spec.clone());
132        tm.insert("concreteImpl", tr.concrete_impl.clone());
133        tm.insert("balancedExp", tr.balanced_exp.clone());
134        map.insert("triad", Value::Object(tm.into_iter().map(|(k, v)| (k.to_string(), v)).collect()));
135    }
136
137    if let Some(ref iface) = card.interface {
138        let mut im = BTreeMap::new();
139        im.insert("inputs", Value::Array(iface.inputs.iter().cloned().map(Value::String).collect()));
140        im.insert("outputs", Value::Array(iface.outputs.iter().cloned().map(Value::String).collect()));
141        map.insert("interface", Value::Object(im.into_iter().map(|(k, v)| (k.to_string(), v)).collect()));
142    }
143
144    let json_str = serde_json::to_string(&map)?;
145    Ok(json_str.into_bytes())
146}
147
148pub fn compress_fiber(
149    fiber_id: &str,
150    terminal: &str,
151    tape: Vec<FiberTapeEvent>,
152    effects_settled: usize,
153    order: Option<&str>,
154) -> Result<Compression, String> {
155    if terminal != "disposed" {
156        return Err(format!(
157            "compress_fiber: refusing to compress a Fiber in state \"{}\" — INV-FRAC-02 requires terminal disposed",
158            terminal
159        ));
160    }
161    let ord = order.unwrap_or("fiber");
162    let card = FiberCard {
163        order: ord.to_string(),
164        fiber: fiber_id.to_string(),
165        terminal: terminal.to_string(),
166        tape,
167        effects_settled,
168        children: None,
169        triad: None,
170        interface: None,
171    };
172    let content = canonicalise(&card).map_err(|e| e.to_string())?;
173    let hash = hash_of(&content);
174    Ok(Compression {
175        handle: format!("urn:mcard:execution:{}:{}", ord, fiber_id),
176        hash,
177        content,
178        card,
179    })
180}
181
182pub fn compress_collection(
183    name: &str,
184    members: &[Compression],
185    order: Option<&str>,
186) -> Result<Compression, String> {
187    let ord = order.unwrap_or("collection");
188    let mut children: Vec<String> = members.iter().map(|m| m.hash.clone()).collect();
189    children.sort();
190
191    let mut map = BTreeMap::new();
192    map.insert("children", Value::Array(children.iter().cloned().map(Value::String).collect()));
193    map.insert("effectsSettled", Value::Number(serde_json::Number::from(members.len())));
194    map.insert("fiber", Value::String(name.to_string()));
195    map.insert("members", Value::Array(children.iter().cloned().map(Value::String).collect()));
196    map.insert("order", Value::String(ord.to_string()));
197    map.insert("tape", Value::Array(vec![]));
198    map.insert("terminal", Value::String("disposed".to_string()));
199
200    let json_str = serde_json::to_string(&map).map_err(|e| e.to_string())?;
201    let content = json_str.into_bytes();
202    let hash = hash_of(&content);
203
204    let card = FiberCard {
205        order: ord.to_string(),
206        fiber: name.to_string(),
207        terminal: "disposed".to_string(),
208        tape: vec![],
209        effects_settled: members.len(),
210        children: Some(children),
211        triad: None,
212        interface: None,
213    };
214
215    Ok(Compression {
216        handle: format!("urn:mcard:mcard:{}:{}", ord, name),
217        hash,
218        content,
219        card,
220    })
221}
222
223pub fn encode_knowledge_triad(
224    id: &str,
225    order: &str,
226    triad: KnowledgeTriadSpec,
227    interface: Option<FractalInterfaceSpec>,
228    children: Option<Vec<Compression>>,
229) -> Result<FractalMCard, String> {
230    if !is_fractal_order(order) {
231        return Err(format!("encode_knowledge_triad: unsupported FractalOrder \"{}\"", order));
232    }
233    let mut sorted_children = children
234        .map(|cs| {
235            let mut hashes: Vec<String> = cs.iter().map(|c| c.hash.clone()).collect();
236            hashes.sort();
237            hashes
238        })
239        .unwrap_or_default();
240    sorted_children.sort();
241
242    let effects_settled = sorted_children.len();
243    let card = FiberCard {
244        order: order.to_string(),
245        fiber: id.to_string(),
246        terminal: "disposed".to_string(),
247        tape: vec![],
248        effects_settled,
249        children: Some(sorted_children),
250        triad: Some(triad),
251        interface,
252    };
253    let content = canonicalise(&card).map_err(|e| e.to_string())?;
254    let hash = hash_of(&content);
255
256    Ok(Compression {
257        handle: format!("urn:mcard:knowledge:{}:{}", order, id),
258        hash,
259        content,
260        card,
261    })
262}
263
264pub fn decode_fractal_card(card: &FractalMCard) -> Result<DecodedFractalCard, String> {
265    let actual_hash = hash_of(&card.content);
266    if actual_hash != card.hash {
267        return Err(format!(
268            "decode_fractal_card: BLAKE3 content mismatch (expected {}, computed {})",
269            card.hash, actual_hash
270        ));
271    }
272    let parsed: Value = serde_json::from_slice(&card.content).map_err(|e| e.to_string())?;
273    let obj = parsed.as_object().ok_or_else(|| "decode_fractal_card: root is not object".to_string())?;
274
275    let order = obj.get("order").and_then(|v| v.as_str()).ok_or_else(|| "missing order".to_string())?;
276    if !is_fractal_order(order) {
277        return Err(format!("decode_fractal_card: invalid FractalOrder \"{}\"", order));
278    }
279    let fiber = obj.get("fiber").and_then(|v| v.as_str()).ok_or_else(|| "missing fiber".to_string())?;
280    let terminal = obj.get("terminal").and_then(|v| v.as_str()).ok_or_else(|| "missing terminal".to_string())?;
281    if terminal != "disposed" {
282        return Err("decode_fractal_card: malformed terminal FiberCard payload".to_string());
283    }
284
285    let children = if let Some(ch) = obj.get("children").and_then(|v| v.as_array()) {
286        ch.iter().filter_map(|v| v.as_str().map(String::from)).collect()
287    } else if let Some(m) = obj.get("members").and_then(|v| v.as_array()) {
288        m.iter().filter_map(|v| v.as_str().map(String::from)).collect()
289    } else {
290        vec![]
291    };
292
293    let effects_settled = obj
294        .get("effectsSettled")
295        .and_then(|v| v.as_u64())
296        .map(|v| v as usize)
297        .unwrap_or(children.len());
298
299    let triad: Option<KnowledgeTriadSpec> = obj.get("triad").and_then(|t| serde_json::from_value(t.clone()).ok());
300    let interface: Option<FractalInterfaceSpec> = obj.get("interface").and_then(|i| serde_json::from_value(i.clone()).ok());
301
302    Ok(DecodedFractalCard {
303        handle: card.handle.clone(),
304        hash: card.hash.clone(),
305        order: order.to_string(),
306        fiber: fiber.to_string(),
307        terminal: terminal.to_string(),
308        tape: vec![],
309        effects_settled,
310        children,
311        triad,
312        interface,
313        payload: parsed,
314    })
315}
316
317pub fn project_fractal_petri_net(card: &FractalMCard) -> Result<FractalPetriProjection, String> {
318    let decoded = decode_fractal_card(card)?;
319    let place_specs = vec![
320        PlaceSpec { place_id: "p_abstract".to_string(), type_expr: "structured".to_string(), role: "InitialBottom".to_string() },
321        PlaceSpec { place_id: "p_concrete".to_string(), type_expr: "structured".to_string(), role: "Intermediate".to_string() },
322        PlaceSpec { place_id: "p_verified".to_string(), type_expr: "structured".to_string(), role: "TerminalTop".to_string() },
323    ];
324
325    let topology = serde_json::json!({
326        "name": format!("fractal_{}_{}", decoded.order, decoded.fiber),
327        "places": [
328            { "id": "p_abstract", "initialTokens": 1, "initialColor": decoded.hash, "capacity": 1 },
329            { "id": "p_concrete", "initialTokens": 0, "capacity": 1 },
330            { "id": "p_verified", "initialTokens": 0, "capacity": 1 }
331        ],
332        "transitions": [
333            { "id": "t_realize", "inputs": ["p_abstract"], "outputs": ["p_concrete"] },
334            { "id": "t_verify", "inputs": ["p_concrete"], "outputs": ["p_verified"] }
335        ],
336        "arcs": [
337            { "source": "p_abstract", "target": "t_realize", "weight": 1 },
338            { "source": "t_realize", "target": "p_concrete", "weight": 1 },
339            { "source": "p_concrete", "target": "t_verify", "weight": 1 },
340            { "source": "t_verify", "target": "p_verified", "weight": 1 }
341        ],
342        "assertions": {
343            "fireCount": 2,
344            "finalMarking": { "p_abstract": 0, "p_concrete": 0, "p_verified": 1 },
345            "noetherianInvariants": {
346                "pInvariants": [
347                    {
348                        "expectedConstant": 1,
349                        "weights": { "p_abstract": 1, "p_concrete": 1, "p_verified": 1 }
350                    }
351                ]
352            }
353        }
354    });
355
356    Ok(FractalPetriProjection {
357        order: decoded.order,
358        source_hash: decoded.hash,
359        place_specs,
360        topology,
361        p_invariant_weights: (1, 1, 1),
362    })
363}