clm-kernel 0.0.21

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 0: Strongly-typed AST grammar for Cubical Logic Model specifications.
//! Canonical Path: kernel/clm_rust_core/src/layer0/ast.rs
//!
//! Provides serde-serializable AST structures for chapters, abstract specifications,
//! concrete implementations, balanced expectations, and full CLM manifests.

use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::HashMap;

/// Chapter metadata block in a CLM specification.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct ClmChapter {
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub number: Option<u32>,
    #[serde(default)]
    pub id: Option<u32>,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub mvp_card: Option<String>,
    #[serde(default)]
    pub pkc_task: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub narrative: Option<String>,
}

/// Abstract component specification (A-MCard domain concept).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct AbstractComponent {
    #[serde(default)]
    pub concept: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub signature: Option<Value>,
    #[serde(default)]
    pub invariants: Option<Value>,
    #[serde(flatten)]
    pub extra: HashMap<String, Value>,
}

/// Concrete component manifestation (C-MCard runtime implementation).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct ConcreteComponent {
    #[serde(default)]
    pub manifestation: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub runtime: Option<String>,
    #[serde(default)]
    pub operation: Option<String>,
    #[serde(default)]
    pub code: Option<String>,
    #[serde(default)]
    pub input_type: Option<String>,
    #[serde(default)]
    pub output_type: Option<String>,
    #[serde(default)]
    pub process_type: Option<String>,
    #[serde(flatten)]
    pub extra: HashMap<String, Value>,
}

/// Balanced component expectation (V-MCard validation & test cases).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct BalancedComponent {
    #[serde(default)]
    pub expectation: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub expected_results: Option<Value>,
    #[serde(default)]
    pub test_cases: Option<Vec<Value>>,
    #[serde(flatten)]
    pub extra: HashMap<String, Value>,
}

/// Fully parsed canonical CLM AST representing a chapter or component specification.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct ParsedClmAst {
    #[serde(default)]
    pub version: Option<String>,
    #[serde(default)]
    pub chapter: Option<ClmChapter>,
    pub abstract_spec: AbstractComponent,
    pub concrete_spec: ConcreteComponent,
    pub balanced_spec: BalancedComponent,
    #[serde(default)]
    pub preconditions: Vec<String>,
    #[serde(default)]
    pub postconditions: Vec<String>,
    #[serde(default)]
    pub content_hash: Option<String>,
    #[serde(default)]
    pub raw: Value,
}

impl ParsedClmAst {
    /// Returns the chapter title or name if available.
    pub fn display_name(&self) -> String {
        if let Some(ref ch) = self.chapter {
            if let Some(ref title) = ch.title {
                return title.clone();
            }
            if let Some(ref name) = ch.name {
                return name.clone();
            }
        }
        if let Some(ref concept) = self.abstract_spec.concept {
            return concept.clone();
        }
        "Unnamed CLM Component".to_string()
    }
}