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