Skip to main content

clm_rust_core/layer1/
action.rs

1//! Layer 1: Declarative Action Manifest Engine & Baldwin Modularity Manipulators
2//! Canonical Path: kernel/clm_rust_core/src/layer1/action.rs
3
4use std::collections::{BTreeMap, HashMap};
5use std::path::Path;
6use serde::{Deserialize, Serialize};
7use serde_json::{json, Value};
8
9/// Format of data processed by an Action
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "lowercase")]
12pub enum ActionFormat {
13    Csv,
14    Json,
15    Yaml,
16    Markdown,
17    Text,
18    Binary,
19    Media,
20}
21
22/// Baldwin modularity operators (Baldwin & Clark, 2000)
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "lowercase")]
25pub enum BaldwinOperator {
26    Split,
27    Substitute,
28    Augment,
29    Exclude,
30    Invert,
31    Port,
32    Custom,
33}
34
35impl std::fmt::Display for BaldwinOperator {
36    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
37        match self {
38            BaldwinOperator::Split => write!(f, "split"),
39            BaldwinOperator::Substitute => write!(f, "substitute"),
40            BaldwinOperator::Augment => write!(f, "augment"),
41            BaldwinOperator::Exclude => write!(f, "exclude"),
42            BaldwinOperator::Invert => write!(f, "invert"),
43            BaldwinOperator::Port => write!(f, "port"),
44            BaldwinOperator::Custom => write!(f, "custom"),
45        }
46    }
47}
48
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct ActionMetadata {
51    #[serde(default = "default_action_type")]
52    pub r#type: String,
53    pub name: String,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub description: Option<String>,
56    #[serde(default = "default_face")]
57    pub face: String,
58    pub operator: BaldwinOperator,
59    #[serde(default = "default_author")]
60    pub author: String,
61}
62
63fn default_action_type() -> String { "action".to_string() }
64fn default_face() -> String { "C".to_string() }
65fn default_author() -> String { crate::layer0::vocabulary_identities::DID_CLM_SYSTEM.to_string() }
66
67#[derive(Debug, Clone, Serialize, Deserialize)]
68pub struct ActionInput {
69    pub name: String,
70    #[serde(skip_serializing_if = "Option::is_none")]
71    pub uri: Option<String>,
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub format: Option<String>,
74    #[serde(default = "default_true")]
75    pub required: bool,
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub description: Option<String>,
78}
79
80fn default_true() -> bool { true }
81
82#[derive(Debug, Clone, Serialize, Deserialize)]
83pub struct ActionPrecondition {
84    pub invariant: String,
85    pub rule: String,
86    #[serde(skip_serializing_if = "Option::is_none")]
87    pub schema_ref: Option<String>,
88    #[serde(skip_serializing_if = "Option::is_none")]
89    pub description: Option<String>,
90}
91
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct ActionOperation {
94    pub operator: BaldwinOperator,
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub strategy: Option<String>,
97    #[serde(default)]
98    pub parameters: HashMap<String, Value>,
99    #[serde(default = "default_runtime")]
100    pub runtime: String,
101}
102
103fn default_runtime() -> String { "builtin".to_string() }
104
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct ActionPostcondition {
107    pub invariant: String,
108    pub rule: String,
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub schema_ref: Option<String>,
111    #[serde(skip_serializing_if = "Option::is_none")]
112    pub description: Option<String>,
113}
114
115#[derive(Debug, Clone, Serialize, Deserialize)]
116pub struct ActionOutput {
117    pub name: String,
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub handle: Option<String>,
120    #[serde(skip_serializing_if = "Option::is_none")]
121    pub format: Option<String>,
122    #[serde(skip_serializing_if = "Option::is_none")]
123    pub description: Option<String>,
124}
125
126#[derive(Debug, Clone, Serialize, Deserialize)]
127pub struct ActionManifest {
128    #[serde(default = "default_version")]
129    pub version: String,
130    pub clm: ActionMetadata,
131    pub inputs: Vec<ActionInput>,
132    #[serde(default)]
133    pub preconditions: Vec<ActionPrecondition>,
134    pub operation: ActionOperation,
135    #[serde(default)]
136    pub postconditions: Vec<ActionPostcondition>,
137    pub outputs: Vec<ActionOutput>,
138}
139
140fn default_version() -> String { "1.0".to_string() }
141
142impl ActionManifest {
143    pub fn from_yaml_str(yaml_str: &str) -> Result<Self, String> {
144        let manifest: ActionManifest = serde_yaml::from_str(yaml_str)
145            .map_err(|e| format!("Failed to parse YAML ActionManifest: {}", e))?;
146        if manifest.clm.operator != manifest.operation.operator {
147            return Err(format!(
148                "Operator mismatch: clm.operator='{}' != operation.operator='{}'",
149                manifest.clm.operator, manifest.operation.operator
150            ));
151        }
152        Ok(manifest)
153    }
154
155    pub fn from_yaml_file<P: AsRef<Path>>(path: P) -> Result<Self, String> {
156        let content = std::fs::read_to_string(path.as_ref())
157            .map_err(|e| format!("Cannot read file {}: {}", path.as_ref().display(), e))?;
158        Self::from_yaml_str(&content)
159    }
160
161    pub fn to_canonical_json_value(&self) -> Value {
162        serde_json::to_value(self).unwrap_or(Value::Null)
163    }
164}
165
166// ── Canonical Hashing Helpers ────────────────────────────────────────────────
167
168pub fn sort_json_value(v: &Value) -> Value {
169    match v {
170        Value::Object(map) => {
171            let mut sorted = BTreeMap::new();
172            for (k, val) in map {
173                sorted.insert(k.clone(), sort_json_value(val));
174            }
175            serde_json::to_value(sorted).unwrap()
176        }
177        Value::Array(arr) => {
178            Value::Array(arr.iter().map(sort_json_value).collect())
179        }
180        other => other.clone(),
181    }
182}
183
184pub fn compute_canonical_serialized(val: &Value) -> String {
185    let sorted = sort_json_value(val);
186    serde_json::to_string(&sorted).unwrap_or_default()
187}
188
189pub fn compute_canonical_hash(val: &Value) -> String {
190    let s = compute_canonical_serialized(val);
191    blake3::hash(s.as_bytes()).to_hex().to_string()
192}
193
194pub fn clm_hash_string(s: &str) -> String {
195    blake3::hash(s.as_bytes()).to_hex().to_string()
196}
197
198// ── Modality Manipulators ───────────────────────────────────────────────────
199
200pub struct TabularManipulator;
201
202impl TabularManipulator {
203    pub fn parse_csv(text: &str) -> (Vec<String>, Vec<Vec<String>>) {
204        let mut lines = text.lines().filter(|l| !l.trim().is_empty());
205        let header_line = match lines.next() {
206            Some(h) => h,
207            None => return (vec![], vec![]),
208        };
209        let headers: Vec<String> = header_line.split(',').map(|s| s.trim().to_string()).collect();
210        let mut rows = Vec::new();
211        for line in lines {
212            let row: Vec<String> = line.split(',').map(|s| s.trim().to_string()).collect();
213            rows.push(row);
214        }
215        (headers, rows)
216    }
217
218    pub fn render_csv(headers: &[String], rows: &[Vec<String>]) -> String {
219        let mut out = String::new();
220        if !headers.is_empty() {
221            out.push_str(&headers.join(","));
222            out.push('\n');
223        }
224        for r in rows {
225            out.push_str(&r.join(","));
226            out.push('\n');
227        }
228        out
229    }
230
231    pub fn split(data: &str, params: &HashMap<String, Value>) -> Result<HashMap<String, String>, String> {
232        let (headers, rows) = Self::parse_csv(data);
233        if rows.is_empty() {
234            let mut res = HashMap::new();
235            res.insert("part_1".to_string(), Self::render_csv(&headers, &[]));
236            res.insert("part_2".to_string(), Self::render_csv(&headers, &[]));
237            return Ok(res);
238        }
239
240        if let Some(Value::Object(ratios)) = params.get("ratios") {
241            let total = rows.len();
242            let mut partitions = HashMap::new();
243            let mut current_idx = 0;
244            let ratio_list: Vec<(&String, f64)> = ratios
245                .iter()
246                .map(|(k, v)| (k, v.as_f64().unwrap_or(0.0)))
247                .collect();
248
249            for (i, (name, ratio)) in ratio_list.iter().enumerate() {
250                let part_rows = if i == ratio_list.len() - 1 {
251                    &rows[current_idx..]
252                } else {
253                    let count = (total as f64 * ratio).round() as usize;
254                    let end = (current_idx + count).min(total);
255                    let slice = &rows[current_idx..end];
256                    current_idx = end;
257                    slice
258                };
259                partitions.insert((*name).clone(), Self::render_csv(&headers, part_rows));
260            }
261            return Ok(partitions);
262        }
263
264        let mid = rows.len() / 2;
265        let mut partitions = HashMap::new();
266        partitions.insert("part_1".to_string(), Self::render_csv(&headers, &rows[..mid]));
267        partitions.insert("part_2".to_string(), Self::render_csv(&headers, &rows[mid..]));
268        Ok(partitions)
269    }
270
271    pub fn substitute(data: &str, params: &HashMap<String, Value>) -> Result<String, String> {
272        let (mut headers, rows) = Self::parse_csv(data);
273        if let (Some(target), Some(replacement)) = (
274            params.get("target_column").and_then(|v| v.as_str()),
275            params.get("replacement_column").and_then(|v| v.as_str()),
276        ) {
277            for h in &mut headers {
278                if h == target {
279                    *h = replacement.to_string();
280                }
281            }
282        } else if let Some(Value::Object(rename)) = params.get("rename_columns") {
283            for h in &mut headers {
284                if let Some(new_name) = rename.get(h).and_then(|v| v.as_str()) {
285                    *h = new_name.to_string();
286                }
287            }
288        }
289        Ok(Self::render_csv(&headers, &rows))
290    }
291
292    pub fn augment(data: &str, params: &HashMap<String, Value>) -> Result<String, String> {
293        let (mut headers, rows) = Self::parse_csv(data);
294        let col_name = params.get("column_name")
295            .or_else(|| params.get("target_column"))
296            .and_then(|v| v.as_str())
297            .unwrap_or("augmented_col");
298        let default_val = params.get("default_value")
299            .or_else(|| params.get("constant_value"))
300            .map(|v| match v {
301                Value::String(s) => s.clone(),
302                other => other.to_string(),
303            })
304            .unwrap_or_else(|| "active".to_string());
305
306        headers.push(col_name.to_string());
307        let mut new_rows = Vec::new();
308        for r in rows {
309            let mut nr = r;
310            nr.push(default_val.clone());
311            new_rows.push(nr);
312        }
313        Ok(Self::render_csv(&headers, &new_rows))
314    }
315
316    pub fn exclude(data: &str, params: &HashMap<String, Value>) -> Result<String, String> {
317        let (headers, rows) = Self::parse_csv(data);
318        let mut drop_cols = Vec::new();
319        if let Some(Value::Array(cols)) = params.get("columns").or_else(|| params.get("target_columns")) {
320            for c in cols {
321                if let Some(s) = c.as_str() {
322                    drop_cols.push(s.to_string());
323                }
324            }
325        }
326
327        let keep_indices: Vec<usize> = headers
328            .iter()
329            .enumerate()
330            .filter(|(_, h)| !drop_cols.contains(h))
331            .map(|(i, _)| i)
332            .collect();
333
334        let new_headers: Vec<String> = keep_indices.iter().map(|&i| headers[i].clone()).collect();
335        let mut new_rows = Vec::new();
336        for r in rows {
337            let nr: Vec<String> = keep_indices.iter().filter(|&&i| i < r.len()).map(|&i| r[i].clone()).collect();
338            new_rows.push(nr);
339        }
340        Ok(Self::render_csv(&new_headers, &new_rows))
341    }
342
343    pub fn invert(data: &str, params: &HashMap<String, Value>) -> Result<String, String> {
344        let (headers, mut rows) = Self::parse_csv(data);
345        let strategy = params.get("strategy").and_then(|v| v.as_str()).unwrap_or("reverse_rows");
346        if strategy == "transpose" && !headers.is_empty() {
347            let mut matrix = vec![headers];
348            matrix.extend(rows);
349            let cols = matrix[0].len();
350            let mut transposed = Vec::new();
351            for c in 0..cols {
352                let mut row = Vec::new();
353                for r in 0..matrix.len() {
354                    if c < matrix[r].len() {
355                        row.push(matrix[r][c].clone());
356                    }
357                }
358                transposed.push(row);
359            }
360            let new_headers = transposed.first().cloned().unwrap_or_default();
361            let new_rows = if transposed.len() > 1 { transposed[1..].to_vec() } else { vec![] };
362            return Ok(Self::render_csv(&new_headers, &new_rows));
363        }
364        rows.reverse();
365        Ok(Self::render_csv(&headers, &rows))
366    }
367
368    pub fn port(data: &str, params: &HashMap<String, Value>) -> Result<String, String> {
369        let (headers, rows) = Self::parse_csv(data);
370        let target_format = params.get("target_format").and_then(|v| v.as_str()).unwrap_or("json").to_lowercase();
371        if target_format == "json" {
372            let mut records = Vec::new();
373            for r in rows {
374                let mut obj = serde_json::Map::new();
375                for (i, h) in headers.iter().enumerate() {
376                    let val = if i < r.len() { r[i].clone() } else { String::new() };
377                    obj.insert(h.clone(), Value::String(val));
378                }
379                records.push(Value::Object(obj));
380            }
381            return serde_json::to_string_pretty(&records).map_err(|e| e.to_string());
382        }
383        Ok(Self::render_csv(&headers, &rows))
384    }
385}
386
387
388#[path = "action_manipulators.rs"]
389mod action_manipulators;
390#[allow(unused_imports)]
391pub use action_manipulators::*;
392#[path = "action_rules.rs"]
393mod action_rules;
394#[allow(unused_imports)]
395pub use action_rules::*;
396#[path = "action_sandwich.rs"]
397mod action_sandwich;
398#[allow(unused_imports)]
399pub use action_sandwich::*;