clm-kernel 0.0.24

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
#![allow(unused_imports)]
use crate::layer0::vocabulary::{HASH_PREFIX_BLAKE3};
use super::*;

#[allow(dead_code)]
pub fn augment(clm_file: &str, aug_source: &str, clm_root: &str) -> Result<String, String> {
    let path = Path::new(clm_file);
    if !path.exists() {
        return Err(format!("File not found: {}", clm_file));
    }
    let yaml_content = fs::read_to_string(path)
        .map_err(|e| format!("Failed to read CLM file: {}", e))?;
    let mut clm_val: Value = serde_yaml::from_str(&yaml_content)
        .map_err(|e| format!("Failed to parse CLM YAML: {}", e))?;
    
    let clm = clm_val.get_mut("clm")
        .ok_or_else(|| "Not a valid CLM file (missing 'clm:' root)".to_string())?;

    let aug_content = if Path::new(aug_source).exists() {
        fs::read_to_string(aug_source)
            .map_err(|e| format!("Failed to read augmentation file: {}", e))?
    } else {
        aug_source.to_string()
    };

    let aug_val: Value = serde_yaml::from_str(&aug_content)
        .map_err(|e| format!("Failed to parse augmentation YAML: {}", e))?;

    let update_inv = |clm: &mut Value, key: &str, val: &Value| {
        if let Some(concrete) = clm.get_mut("concrete_impl").and_then(|c| c.as_object_mut()) {
            concrete.insert(key.to_string(), val.clone());
        }
        if let Some(obj) = clm.get_mut("abstract_spec").and_then(|a| a.as_object_mut()) {
            let inv = obj.entry("invariants".to_string()).or_insert_with(|| serde_json::json!({
                "preconditions": Vec::<String>::new(), "postconditions": Vec::<String>::new()
            }));
            if let Some(arr) = inv.as_object_mut().and_then(|io| io.entry(format!("{}s", key)).or_insert_with(|| Value::Array(Vec::new())).as_array_mut()) {
                if let Some(new_arr) = val.as_array() { arr.extend(new_arr.clone()); }
                else if !arr.contains(val) { arr.push(val.clone()); }
            }
        }
    };
    let append_arr = |target: Option<&mut Value>, field: &str, item: &Value| {
        if let Some(arr) = target.and_then(|t| t.as_object_mut()).and_then(|obj| obj.entry(field.to_string()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut()) {
            if let Some(new_arr) = item.as_array() { arr.extend(new_arr.clone()); } else { arr.push(item.clone()); }
        }
    };

    if let Some(pre) = aug_val.get("precondition").or_else(|| aug_val.get("vcard_pre")) {
        update_inv(clm, "precondition", pre);
    } else if let Some(post) = aug_val.get("postcondition").or_else(|| aug_val.get("vcard_post")) {
        update_inv(clm, "postcondition", post);
    } else if let Some(pending) = aug_val.get("pending_cases") {
        append_arr(clm.get_mut("balanced_exp"), "pending_cases", pending);
    } else if let Some(criteria) = aug_val.get("success_criteria") {
        append_arr(clm.get_mut("abstract_spec"), "success_criteria", criteria);
    } else if let Some(obj) = clm.as_object_mut() && let Some(aug_obj) = aug_val.as_object() {
        for (k, v) in aug_obj { obj.insert(k.clone(), v.clone()); }
    }

    let aug_hash = sha256_hash_string(&aug_content);
    let output_dir = crate::fs_utils::get_data_dir(clm_root, crate::layer0::vocabulary_env::PILLAR_CONTENT_MEMORY);
    let _ = fs::create_dir_all(&output_dir);
    let aug_file = output_dir.join(format!("augmented_{}.yaml", &aug_hash[..12]));

    let new_yaml = serde_yaml::to_string(&clm_val)
        .map_err(|e| format!("Failed to serialize augmented CLM: {}", e))?;
    fs::write(&aug_file, &new_yaml)
        .map_err(|e| format!("Failed to write augmented file: {}", e))?;

    // Register CLM handles in Database
    let root_content = format!(
        "{{\"@type\":\"CLM_Root\",\"clm_name\":\"augmented_{}\",\"clm_root_hash\":\"{}\",\"a_hash\":\"none\",\"c_hash\":\"none\",\"b_hash\":\"none\"}}",
        &aug_hash[..12], prefixed(&aug_hash)
    );
    let stored_root_hash = sha256_hash_string(&root_content);
    db::handle_register_batch(crate::layer0::vocabulary_env::PILLAR_CONTENT_MEMORY, clm_root, &format!("clm:augmented_{}", &aug_hash[..12]), &stored_root_hash, &root_content).map_err(|e| e.to_string())?;

    Ok(aug_file.to_string_lossy().to_string())
}

// ── Sprint 167: Dynamic Baldwin Modularity & Fiber HMR ──────────────────────

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
pub struct SubsumptionReport {
    pub fiber_id: String,
    pub old_hash: String,
    pub new_hash: String,
    pub pre_subsumed: bool,
    pub post_subsumed: bool,
    pub subsumption_valid: bool,
    pub witness: String,
}

/// Helper to extract invariant sets from CLM AST
pub fn extract_invariants(val: &Value, field: &str) -> std::collections::HashSet<String> {
    let mut set = std::collections::HashSet::new();
    let root = if let Some(clm) = val.get("clm") { clm } else { val };

    if let Some(arr) = root.get("abstract_spec")
        .and_then(|a| a.get("invariants"))
        .and_then(|inv| inv.get(field))
        .and_then(|f| f.as_array())
    {
        for item in arr {
            if let Some(s) = item.as_str() {
                set.insert(s.to_string());
            }
        }
    }
    if let Some(arr) = root.get("invariants")
        .and_then(|inv| inv.get(field))
        .and_then(|f| f.as_array())
    {
        for item in arr {
            if let Some(s) = item.as_str() {
                set.insert(s.to_string());
            }
        }
    }
    set
}

/// Verifies the Type Lattice Subsumption Criterion:
/// Subsumes(F_new, F_old) <=> (V_pre^new <= V_pre^old) AND (V_post^new >= V_post^old)
pub fn verify_subsumption(old_ast: &Value, new_ast: &Value) -> Result<SubsumptionReport, String> {
    let old_pre = extract_invariants(old_ast, "preconditions");
    let new_pre = extract_invariants(new_ast, "preconditions");
    let old_post = extract_invariants(old_ast, "postconditions");
    let new_post = extract_invariants(new_ast, "postconditions");

    // Precondition Contravariance: V_pre^new <= V_pre^old
    // new_pre must be a subset of old_pre (new cannot require MORE than old).
    let pre_subsumed = new_pre.is_subset(&old_pre);

    // Postcondition Covariance: V_post^new >= V_post^old
    // old_post must be a subset of new_post (new must guarantee AT LEAST what old guaranteed).
    let post_subsumed = old_post.is_subset(&new_post);

    let subsumption_valid = pre_subsumed && post_subsumed;

    let witness = format!(
        "Pre-subsumption: {} (old_pre={:?}, new_pre={:?}); Post-subsumption: {} (old_post={:?}, new_post={:?})",
        pre_subsumed, old_pre, new_pre, post_subsumed, old_post, new_post
    );

    let report = SubsumptionReport {
        fiber_id: String::new(),
        old_hash: String::new(),
        new_hash: String::new(),
        pre_subsumed,
        post_subsumed,
        subsumption_valid,
        witness,
    };

    if subsumption_valid {
        Ok(report)
    } else {
        Err(format!("Subsumption check failed: {}", report.witness))
    }
}

/// Dynamic Baldwin Operator: Substitute (=) via Hot Module Replacement (HMR)
/// Replaces an active PCard fiber with a new implementation without dropping tokens.
pub fn substitute_fiber(
    ctx: &crate::fiber::Context,
    fiber_id: &str,
    new_clm_file: &str,
    clm_root: &str,
) -> Result<SubsumptionReport, String> {
    // 1. Locate existing fiber in active context
    let old_fiber = ctx.get_fiber(fiber_id)
        .ok_or_else(|| format!("Fiber '{}' not found in active context", fiber_id))?;

    // 2. Read new implementation file
    let path = Path::new(new_clm_file);
    let resolved_path = if path.is_absolute() {
        path.to_path_buf()
    } else {
        Path::new(clm_root).join(new_clm_file)
    };
    if !resolved_path.exists() {
        return Err(format!("New CLM file not found: {}", resolved_path.display()));
    }
    let yaml_content = fs::read_to_string(&resolved_path)
        .map_err(|e| format!("Failed to read new CLM file: {}", e))?;

    let new_ast: Value = serde_yaml::from_str(&yaml_content)
        .map_err(|e| format!("Failed to parse new CLM YAML: {}", e))?;
    let new_json_str = serde_json::to_string(&new_ast).unwrap_or_default();
    let new_hash = sha256_hash_string(&new_json_str);

    // 3. Verify Type Lattice Subsumption against old fiber's AST
    let old_ast = old_fiber.get_ast().unwrap_or(Value::Null);
    let old_json_str = serde_json::to_string(&old_ast).unwrap_or_default();
    let old_hash = sha256_hash_string(&old_json_str);

    let mut report = verify_subsumption(&old_ast, &new_ast)?;
    report.fiber_id = fiber_id.to_string();
    report.old_hash = old_hash;
    report.new_hash = new_hash;

    // 4. Homotopy Lifting Property: pause old fiber & unwind disposables
    old_fiber.pause()?;
    let _ = old_fiber.unwind_disposables();

    // 5. Mount replacement fiber in Active state
    ctx.remove_fiber(fiber_id);
    let new_fiber = ctx.create_fiber(fiber_id, vec![])?;
    new_fiber.set_ast(new_ast);
    new_fiber.activate()?;

    Ok(report)
}

/// Dynamic Baldwin Operator: Split (//)
/// Splits an active fiber into an isolated sub-context sandbox.
pub fn split_fiber(
    ctx: &crate::fiber::Context,
    fiber_id: &str,
    allowed_coeffects: &[&str],
) -> Result<std::sync::Arc<crate::fiber::Fiber>, String> {
    let child_ctx = ctx.isolate(allowed_coeffects);
    let child_id = format!("{}_split", fiber_id);
    let child_fiber = child_ctx.create_fiber(&child_id, vec![])?;
    child_fiber.activate()?;
    Ok(child_fiber)
}

/// Dynamic Baldwin Operator: Augment (+)
/// Injects a new coeffect capability to satisfy pending fiber requirements.
pub fn augment_fiber(
    ctx: &crate::fiber::Context,
    fiber_id: &str,
    coeffect: &str,
) -> Result<(), String> {
    let fiber = ctx.get_fiber(fiber_id)
        .ok_or_else(|| format!("Fiber '{}' not found in active context", fiber_id))?;
    ctx.provide(coeffect, format!("CoeffectInstance:{}", coeffect));
    fiber.satisfy_coeffect(coeffect);
    Ok(())
}

/// Dynamic Baldwin Operator: Exclude (-)
/// Quarantines and cleanly disposes an active fiber, releasing all its resources.
pub fn exclude_fiber(
    ctx: &crate::fiber::Context,
    fiber_id: &str,
) -> Result<(), String> {
    let fiber = ctx.get_fiber(fiber_id)
        .ok_or_else(|| format!("Fiber '{}' not found in active context", fiber_id))?;
    let disposed = fiber.dispose();
    ctx.remove_fiber(fiber_id);
    disposed.map_err(|errors| format!("Fiber '{}' disposal failed: {}", fiber_id, errors.join("; ")))
}

// ── Sprint 522: Versioned BaldwinOperation/v1 Private Vector Adapter ──────

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct BaldwinCoeffectsSpec {
    #[serde(rename = "requiredServices", default)]
    pub required_services: Vec<String>,
    #[serde(default)]
    pub pure: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct BaldwinVectorNode {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    #[serde(rename = "pcardId", default, skip_serializing_if = "Option::is_none")]
    pub pcard_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    #[serde(rename = "pcardType")]
    pub pcard_type: String,
    pub signature: String,
    #[serde(rename = "sourceUri")]
    pub source_uri: String,
    pub coeffects: BaldwinCoeffectsSpec,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BaldwinVectorOutcomeOk {
    pub operator: String,
    pub target: String,
    pub after: Vec<BaldwinVectorNode>,
    pub after_canonical_json: String,
    pub after_hash: String,
    pub witness_canonical_json: String,
    pub witness_hash: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BaldwinVectorOutcomeErr {
    pub code: &'static str,
    pub message: String,
}

fn baldwin_err(code: &'static str, msg: impl Into<String>) -> BaldwinVectorOutcomeErr {
    BaldwinVectorOutcomeErr { code, message: msg.into() }
}

fn canonical_json_value(val: &Value) -> String {
    // Sprint 529: single canonicalizer (parity pinned by canonical_parity_tests).
    crate::layer0::codec::canonical_json(val).unwrap_or_default()
}

fn normalize_vector_node(node: &BaldwinVectorNode) -> Result<(String, BaldwinVectorNode), BaldwinVectorOutcomeErr> {
    let candidates: Vec<String> = [&node.id, &node.pcard_id, &node.name]
        .into_iter().flatten().map(|s| s.trim().to_string()).filter(|s| !s.is_empty()).collect();
    if candidates.is_empty() { return Err(baldwin_err("AMBIGUOUS_IDENTIFIER", "Missing node identifier")); }
    let unique: std::collections::BTreeSet<String> = candidates.iter().cloned().collect();
    if unique.len() > 1 { return Err(baldwin_err("AMBIGUOUS_IDENTIFIER", "Conflicting identifier aliases")); }
    let cid = candidates[0].clone();
    Ok((cid.clone(), BaldwinVectorNode {
        id: Some(cid), pcard_id: None, name: None,
        pcard_type: node.pcard_type.clone(), signature: node.signature.clone(),
        source_uri: node.source_uri.clone(), coeffects: node.coeffects.clone(),
    }))
}

/// Evaluate a versioned `BaldwinOperation/v1` JSON vector without mutating input state.
/// `BTreeMap` lookup is O(log N); state materialization is O(N).
pub fn evaluate_baldwin_vector(spec: &Value) -> Result<BaldwinVectorOutcomeOk, BaldwinVectorOutcomeErr> {
    let op = spec.get("operator").and_then(|v| v.as_str()).unwrap_or("");
    if !matches!(op, "split" | "substitute" | "augment" | "exclude" | "invert" | "port") {
        return Err(baldwin_err("UNKNOWN_OPERATOR", format!("Unknown operator: {}", op)));
    }
    let target = spec.get("target").and_then(|v| v.as_str()).unwrap_or("").to_string();
    let initial_arr = spec.get("initial_state").and_then(|v| v.as_array()).cloned().unwrap_or_default();
    let mut index_by_id: std::collections::BTreeMap<String, usize> = std::collections::BTreeMap::new();
    let mut current: Vec<BaldwinVectorNode> = Vec::with_capacity(initial_arr.len());
    for (idx, raw_val) in initial_arr.iter().enumerate() {
        let parsed: BaldwinVectorNode = serde_json::from_value(raw_val.clone())
            .map_err(|e| baldwin_err("AMBIGUOUS_IDENTIFIER", e.to_string()))?;
        let (cid, norm) = normalize_vector_node(&parsed)?;
        index_by_id.insert(cid, idx);
        current.push(norm);
    }

    let parse_operand = || -> Result<(String, BaldwinVectorNode), BaldwinVectorOutcomeErr> {
        let op_val = spec.get("operand").ok_or_else(|| baldwin_err("MISSING_SUBJECT", "Missing operand"))?;
        let parsed: BaldwinVectorNode = serde_json::from_value(op_val.clone())
            .map_err(|e| baldwin_err("AMBIGUOUS_IDENTIFIER", e.to_string()))?;
        normalize_vector_node(&parsed)
    };

    let after: Vec<BaldwinVectorNode> = match op {
        "split" => {
            let (matched, mut rest): (Vec<_>, Vec<_>) = current
                .iter().cloned()
                .partition(|n| n.id.as_deref() == Some(target.as_str()) || target == "*");
            if matched.is_empty() { current.clone() } else { rest.extend(matched); rest }
        }
        "substitute" => {
            let &idx = index_by_id.get(&target).ok_or_else(|| baldwin_err("MISSING_SUBJECT", "Target not found"))?;
            let (_, norm_op) = parse_operand()?;
            let orig = &current[idx];
            if orig.pcard_type == "dynamic" && norm_op.pcard_type == "dynamic" && orig.signature != norm_op.signature {
                return Err(baldwin_err("COVARIANCE_VIOLATION", "Signature mismatch"));
            }
            let mut next = current.clone();
            next[idx] = norm_op;
            next
        }
        "augment" => {
            let (op_id, norm_op) = parse_operand()?;
            if index_by_id.contains_key(&op_id) {
                return Err(baldwin_err("DUPLICATE_SUBJECT", "PCard already exists"));
            }
            let mut next = current.clone();
            next.push(norm_op);
            next
        }
        "exclude" => {
            if !index_by_id.contains_key(&target) {
                return Err(baldwin_err("MISSING_SUBJECT", "Target not found"));
            }
            current.iter().filter(|n| n.id.as_deref() != Some(target.as_str())).cloned().collect()
        }
        "invert" => {
            let &idx = index_by_id.get(&target).ok_or_else(|| baldwin_err("MISSING_SUBJECT", "Target not found"))?;
            let svc = spec.get("operand").and_then(|v| v.as_str()).unwrap_or("");
            let mut inverted = current[idx].clone();
            inverted.coeffects.required_services.retain(|s| s.as_str() != svc);
            let mut next = current.clone();
            next[idx] = inverted;
            next
        }
        _ => {
            let &idx = index_by_id.get(&target).ok_or_else(|| baldwin_err("MISSING_SUBJECT", "Target not found"))?;
            let dest = spec.get("operand").and_then(|v| v.as_str()).unwrap_or("").trim();
            let orig = &current[idx];
            if dest.is_empty() || orig.source_uri.starts_with(&format!("{}/", dest)) {
                return Err(baldwin_err("CYCLIC_PORT", "Invalid or cyclic destination layer"));
            }
            let mut ported = orig.clone();
            if ported.pcard_type == "dynamic" {
                ported.source_uri = format!("{}/{}", dest, orig.source_uri);
            }
            let mut next = current.clone();
            next.push(ported);
            next
        }
    };

    let author = spec.get("author").and_then(|v| v.as_str()).unwrap_or(crate::layer0::vocabulary_identities::DID_CLM_AGENT_BALDWIN);
    let timestamp = spec.get("timestamp").and_then(|v| v.as_i64()).unwrap_or(1_700_000_000_000);
    let after_canonical_json = canonical_json_value(&serde_json::to_value(&after).unwrap_or_default());
    let after_hash = format!("{HASH_PREFIX_BLAKE3}{}", crate::layer0::hash::compute_blake3(after_canonical_json.as_bytes()));
    let witness_val = serde_json::json!({
        "afterCount": after.len(), "author": author, "beforeCount": current.len(),
        "operator": op, "target": target, "timestamp": timestamp, "type": "baldwin_witness",
    });
    let witness_canonical_json = canonical_json_value(&witness_val);
    let witness_hash = format!("{HASH_PREFIX_BLAKE3}{}", crate::layer0::hash::compute_blake3(witness_canonical_json.as_bytes()));

    Ok(BaldwinVectorOutcomeOk {
        operator: op.to_string(), target, after, after_canonical_json, after_hash,
        witness_canonical_json, witness_hash,
    })
}

#[cfg(test)]
mod canonical_parity_tests {
    use super::canonical_json_value;
    use crate::layer0::codec::{canonical_json, canonical_parity_corpus};

    #[test]
    fn baldwin_matches_layer0() {
        for value in canonical_parity_corpus() {
            assert_eq!(canonical_json_value(&value), canonical_json(&value).unwrap(), "divergence at {value}");
        }
    }
}