Skip to main content

clm_rust_core/fiber/
plugin.rs

1//! Purely Functional Software Deployment (PFSD) Plugin Functors.
2//!
3//! Models a plugin as an immutable, content-addressed polynomial functor
4//! (A x C x B) in Content Addressable Storage (CAS), identified by its BLAKE3 digest.
5
6use crate::layer0::vocabulary::{HASH_PREFIX_BLAKE3};
7use super::context::{Context, Fiber};
8use serde::{Deserialize, Serialize};
9use serde_json::Value;
10use std::sync::Arc;
11
12#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
13pub struct PluginFunctor {
14    pub plugin_id: String,
15    pub name: String,
16    pub version: String,
17    pub abstract_spec_ref: String,
18    pub concrete_impl_ref: String,
19    pub balanced_exp_ref: String,
20    pub required_capabilities: Vec<String>,
21    pub optional_capabilities: Vec<String>,
22}
23
24impl PluginFunctor {
25    /// Computes the canonical BLAKE3 content digest for a plugin definition.
26    pub fn compute_plugin_id(
27        name: &str,
28        version: &str,
29        abstract_ref: &str,
30        concrete_ref: &str,
31        balanced_ref: &str,
32        required_caps: &[String],
33    ) -> String {
34        let mut hasher = blake3::Hasher::new();
35        hasher.update(name.as_bytes());
36        hasher.update(b"|");
37        hasher.update(version.as_bytes());
38        hasher.update(b"|");
39        hasher.update(abstract_ref.as_bytes());
40        hasher.update(b"|");
41        hasher.update(concrete_ref.as_bytes());
42        hasher.update(b"|");
43        hasher.update(balanced_ref.as_bytes());
44        for cap in required_caps {
45            hasher.update(b"|");
46            hasher.update(cap.as_bytes());
47        }
48        format!("{HASH_PREFIX_BLAKE3}{}", hasher.finalize().to_hex())
49    }
50
51    /// Parses and validates a PFSD plugin YAML definition.
52    pub fn from_yaml(yaml_content: &str) -> Result<Self, String> {
53        let val: Value = serde_yaml::from_str(yaml_content)
54            .map_err(|e| format!("Failed to parse plugin functor YAML: {}", e))?;
55
56        let root = val.get("clm").unwrap_or(&val);
57        let schema = root.get("concrete_impl")
58            .and_then(|c| c.get("schema"))
59            .unwrap_or(root);
60
61        let name = root.get("metadata")
62            .and_then(|m| m.get("name"))
63            .and_then(|v| v.as_str())
64            .unwrap_or("plugin-functor")
65            .to_string();
66
67        let version = root.get("metadata")
68            .and_then(|m| m.get("version"))
69            .and_then(|v| v.as_str())
70            .unwrap_or(crate::layer0::vocabulary_identities::VERSION_N_1_0_0)
71            .to_string();
72
73        let iface = schema.get("interface");
74        let a_ref = iface.and_then(|i| i.get("abstract_spec")).and_then(|v| v.as_str()).unwrap_or(crate::layer0::vocabulary::HANDLE_MCARD_NONE).to_string();
75        let c_ref = iface.and_then(|i| i.get("concrete_impl")).and_then(|v| v.as_str()).unwrap_or(crate::layer0::vocabulary::HANDLE_PCARD_NONE).to_string();
76        let b_ref = iface.and_then(|i| i.get("balanced_exp")).and_then(|v| v.as_str()).unwrap_or(crate::layer0::vocabulary::HANDLE_VCARD_NONE).to_string();
77
78        let mut required_caps = Vec::new();
79        if let Some(arr) = schema.get("capabilities").and_then(|c| c.get("required")).and_then(|r| r.as_array()) {
80            for item in arr {
81                if let Some(s) = item.as_str() {
82                    required_caps.push(s.to_string());
83                }
84            }
85        }
86
87        let mut optional_caps = Vec::new();
88        if let Some(arr) = schema.get("capabilities").and_then(|c| c.get("optional")).and_then(|r| r.as_array()) {
89            for item in arr {
90                if let Some(s) = item.as_str() {
91                    optional_caps.push(s.to_string());
92                }
93            }
94        }
95
96        let computed_id = Self::compute_plugin_id(
97            &name,
98            &version,
99            &a_ref,
100            &c_ref,
101            &b_ref,
102            &required_caps,
103        );
104
105        let declared_id = schema.get("plugin_id")
106            .and_then(|v| v.as_str())
107            .unwrap_or(&computed_id);
108
109        if declared_id != computed_id && !declared_id.is_empty() && declared_id != crate::layer0::vocabulary::HANDLE_BLAKE3_DIGEST {
110            return Err(format!(
111                "Content-Address Integrity Violation: Declared '{}' does not match computed '{}'",
112                declared_id, computed_id
113            ));
114        }
115
116        Ok(Self {
117            plugin_id: computed_id,
118            name,
119            version,
120            abstract_spec_ref: a_ref,
121            concrete_impl_ref: c_ref,
122            balanced_exp_ref: b_ref,
123            required_capabilities: required_caps,
124            optional_capabilities: optional_caps,
125        })
126    }
127
128    /// Verifies that all required capabilities exist in the context's dependency lattice.
129    pub fn verify_dependency_lattice(&self, ctx: &Context) -> Result<bool, String> {
130        let mut missing = Vec::new();
131        for cap in &self.required_capabilities {
132            if !ctx.require(cap) {
133                missing.push(cap.clone());
134            }
135        }
136        if missing.is_empty() {
137            Ok(true)
138        } else {
139            Err(format!("Dependency lattice unsatisfied; missing capabilities: {:?}", missing))
140        }
141    }
142
143    /// Mounts the plugin as a Fiber in the provided context scope.
144    pub fn mount(&self, ctx: &Context) -> Result<Arc<Fiber>, String> {
145        self.verify_dependency_lattice(ctx)?;
146        let fiber = ctx.create_fiber(&self.plugin_id, self.required_capabilities.clone())?;
147        fiber.activate()?;
148        Ok(fiber)
149    }
150}
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155
156    #[test]
157    fn test_plugin_functor_from_yaml_and_blake3_integrity() {
158        let yaml = r#"
159clm:
160  metadata:
161    name: "kv-storage-plugin"
162    version: "2.1.0"
163  concrete_impl:
164    schema:
165      interface:
166        abstract_spec: "mcard:sha256:abc"
167        concrete_impl: "pcard:sha256:def"
168        balanced_exp: "vcard:sha256:ghi"
169      capabilities:
170        required: ["clm.tridb.read", "clm.crypto.sign"]
171        optional: ["clm.net.broadcast"]
172"#;
173
174        let plugin = PluginFunctor::from_yaml(yaml).unwrap();
175        assert!(plugin.plugin_id.starts_with("blake3:"));
176        assert_eq!(plugin.name, "kv-storage-plugin");
177        assert_eq!(plugin.version, "2.1.0");
178        assert_eq!(plugin.required_capabilities.len(), 2);
179    }
180
181    #[test]
182    fn test_plugin_dependency_lattice_and_mounting() {
183        let yaml = r#"
184clm:
185  metadata:
186    name: "auth-plugin"
187    version: "1.0.0"
188  concrete_impl:
189    schema:
190      capabilities:
191        required: ["clm.crypto.sign"]
192"#;
193
194        let plugin = PluginFunctor::from_yaml(yaml).unwrap();
195        let ctx = Context::root();
196
197        // Mounting before capability provided should fail lattice check
198        assert!(plugin.mount(&ctx).is_err());
199
200        // Provide capability and retry mount
201        ctx.provide("clm.crypto.sign", "mock_key".to_string());
202        assert!(plugin.verify_dependency_lattice(&ctx).is_ok());
203
204        let fiber = plugin.mount(&ctx).unwrap();
205        assert_eq!(fiber.get_state(), crate::fiber::FiberState::Active);
206    }
207}