mur_common/skill/
gene.rs

1//! Skill gene model (M7b).
2//!
3//! A `SkillGene` is a pure field-level projection of a `SkillManifest`. It is
4//! not persisted — derived on demand. Two genes can be diffed and recombined
5//! to produce a third manifest.
6//!
7//! Scope (M7b): procedure-mode skills only. Context-only or command-only
8//! skills are not eligible — `from_manifest` returns `Err` for them.
9
10use crate::skill::manifest::{Procedure, ProcedureStep, Requirement, SkillManifest, Trigger};
11use crate::skill::mcp::{McpRequirement, SkillCapability};
12use crate::skill::types::TriggerKind;
13use serde::{Deserialize, Serialize};
14use std::collections::{BTreeMap, BTreeSet};
15
16#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
17pub struct TriggerGene {
18    pub kind: TriggerKind,
19    pub pattern: Option<String>,
20}
21
22#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
23pub struct McpGene {
24    pub tool_pattern: String,
25    pub capability: SkillCapability,
26}
27
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29pub struct StepGene {
30    /// `None` means the step is not matchable by intent in Intersection.
31    pub intent: Option<String>,
32    pub description: String,
33    pub tool: Option<String>,
34}
35
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37pub struct SkillGene {
38    pub triggers: BTreeSet<TriggerGene>,
39    pub steps: Vec<StepGene>,
40    /// requirement name -> semver constraint string (as written in the
41    /// manifest; parsed lazily by the Union semver merger).
42    pub requires: BTreeMap<String, String>,
43    pub mcp: BTreeSet<McpGene>,
44}
45
46#[derive(Debug, thiserror::Error)]
47pub enum GeneError {
48    #[error("skill is not procedure-mode (recombine requires procedure-mode skills)")]
49    NotProcedure,
50}
51
52impl SkillGene {
53    pub fn from_manifest(m: &SkillManifest) -> Result<Self, GeneError> {
54        let proc = m
55            .content
56            .procedure
57            .as_ref()
58            .ok_or(GeneError::NotProcedure)?;
59
60        let triggers = m
61            .triggers
62            .iter()
63            .map(|t| TriggerGene {
64                kind: t.kind,
65                pattern: t.pattern.clone(),
66            })
67            .collect();
68
69        let steps = proc
70            .steps
71            .iter()
72            .map(|s| StepGene {
73                intent: s.intent.clone(),
74                description: s.description.clone(),
75                tool: s.tool.clone(),
76            })
77            .collect();
78
79        let requires = m
80            .requires
81            .iter()
82            .map(|r| (r.name.clone(), r.version.clone()))
83            .collect();
84
85        let mcp = m
86            .mcp_requirements
87            .iter()
88            .map(|r| McpGene {
89                tool_pattern: r.tool_pattern.clone(),
90                capability: r.capability,
91            })
92            .collect();
93
94        Ok(SkillGene {
95            triggers,
96            steps,
97            requires,
98            mcp,
99        })
100    }
101
102    /// Rebuild a `Procedure` from the steps in this gene (preserves order,
103    /// no variables — Variables are copied from the keeper manifest by the
104    /// orchestrator, not the gene layer).
105    pub fn to_procedure(&self) -> Procedure {
106        Procedure {
107            variables: Vec::new(),
108            steps: self
109                .steps
110                .iter()
111                .map(|s| ProcedureStep {
112                    description: s.description.clone(),
113                    tool: s.tool.clone(),
114                    intent: s.intent.clone(),
115                    tool_hint: None,
116                    ..Default::default()
117                })
118                .collect(),
119        }
120    }
121
122    pub fn to_triggers(&self) -> Vec<Trigger> {
123        self.triggers
124            .iter()
125            .map(|t| Trigger {
126                kind: t.kind,
127                pattern: t.pattern.clone(),
128            })
129            .collect()
130    }
131
132    pub fn to_requirements(&self) -> Vec<Requirement> {
133        self.requires
134            .iter()
135            .map(|(name, version)| Requirement {
136                name: name.clone(),
137                version: version.clone(),
138            })
139            .collect()
140    }
141
142    pub fn to_mcp_requirements(&self) -> Vec<McpRequirement> {
143        self.mcp
144            .iter()
145            .map(|g| McpRequirement {
146                tool_pattern: g.tool_pattern.clone(),
147                capability: g.capability,
148                fallback: String::new(),
149            })
150            .collect()
151    }
152}
153
154#[derive(Debug, Clone, Default, Serialize)]
155pub struct GeneDiff {
156    pub triggers_added: Vec<TriggerGene>,
157    pub triggers_removed: Vec<TriggerGene>,
158    pub steps_added: Vec<StepGene>,
159    pub steps_removed: Vec<StepGene>,
160    /// Same intent, different description or tool. (old, new).
161    pub steps_changed: Vec<(StepGene, StepGene)>,
162    /// (name, old_version, new_version).
163    pub requires_changed: Vec<(String, String, String)>,
164    pub requires_added: Vec<(String, String)>,
165    pub requires_removed: Vec<(String, String)>,
166    pub mcp_added: Vec<McpGene>,
167    pub mcp_removed: Vec<McpGene>,
168}
169
170impl GeneDiff {
171    pub fn between(a: &SkillGene, b: &SkillGene) -> Self {
172        let mut d = GeneDiff {
173            triggers_added: b.triggers.difference(&a.triggers).cloned().collect(),
174            triggers_removed: a.triggers.difference(&b.triggers).cloned().collect(),
175            mcp_added: b.mcp.difference(&a.mcp).cloned().collect(),
176            mcp_removed: a.mcp.difference(&b.mcp).cloned().collect(),
177            ..Default::default()
178        };
179
180        // Requires — key-wise
181        for (name, a_ver) in &a.requires {
182            match b.requires.get(name) {
183                None => d.requires_removed.push((name.clone(), a_ver.clone())),
184                Some(b_ver) if b_ver != a_ver => {
185                    d.requires_changed
186                        .push((name.clone(), a_ver.clone(), b_ver.clone()));
187                }
188                _ => {}
189            }
190        }
191        for (name, b_ver) in &b.requires {
192            if !a.requires.contains_key(name) {
193                d.requires_added.push((name.clone(), b_ver.clone()));
194            }
195        }
196
197        // Steps — match by intent (when both have Some(intent) and they match)
198        let a_by_intent: BTreeMap<&str, &StepGene> = a
199            .steps
200            .iter()
201            .filter_map(|s| s.intent.as_deref().map(|i| (i, s)))
202            .collect();
203        let b_by_intent: BTreeMap<&str, &StepGene> = b
204            .steps
205            .iter()
206            .filter_map(|s| s.intent.as_deref().map(|i| (i, s)))
207            .collect();
208
209        for (intent, a_step) in &a_by_intent {
210            match b_by_intent.get(intent) {
211                None => d.steps_removed.push((*a_step).clone()),
212                Some(b_step) if a_step != b_step => {
213                    d.steps_changed.push(((*a_step).clone(), (*b_step).clone()));
214                }
215                _ => {}
216            }
217        }
218        for (intent, b_step) in &b_by_intent {
219            if !a_by_intent.contains_key(intent) {
220                d.steps_added.push((*b_step).clone());
221            }
222        }
223
224        // Steps without intent in either side are appended to added/removed
225        // wholesale (they cannot be matched).
226        for s in a.steps.iter().filter(|s| s.intent.is_none()) {
227            d.steps_removed.push(s.clone());
228        }
229        for s in b.steps.iter().filter(|s| s.intent.is_none()) {
230            d.steps_added.push(s.clone());
231        }
232
233        d
234    }
235}
236
237#[cfg(test)]
238mod tests {
239    use super::*;
240    use crate::skill::manifest::{Content, Procedure, ProcedureStep, Trigger};
241    use crate::skill::types::{Category, TriggerKind};
242
243    fn manifest_with_steps(steps: Vec<ProcedureStep>, triggers: Vec<Trigger>) -> SkillManifest {
244        SkillManifest {
245            name: "x".into(),
246            version: "0.1.0".into(),
247            publisher: "human:test".into(),
248            description: "t".into(),
249            category: Category::Workflow,
250            scope: Default::default(),
251            fleet: None,
252            team: None,
253            governance: None,
254            project: None,
255            hosts: vec![],
256            content: Content {
257                r#abstract: "a".into(),
258                context: None,
259                procedure: Some(Procedure {
260                    variables: vec![],
261                    steps,
262                }),
263                command: None,
264                note: None,
265            },
266            requires: vec![],
267            tags: vec![],
268            triggers,
269            priority: Default::default(),
270            evolution_log: vec![],
271            transfer_chain: vec![],
272            mcp_requirements: vec![],
273            provenance: Default::default(),
274            updated_at: chrono::Utc::now(),
275        }
276    }
277
278    #[test]
279    fn from_manifest_extracts_gene_fields() {
280        let m = manifest_with_steps(
281            vec![ProcedureStep {
282                description: "navigate".into(),
283                tool: Some("browser.go".into()),
284                intent: Some("open_page".into()),
285                tool_hint: None,
286                ..Default::default()
287            }],
288            vec![Trigger {
289                kind: TriggerKind::Command,
290                pattern: Some("/x".into()),
291            }],
292        );
293        let g = SkillGene::from_manifest(&m).unwrap();
294        assert_eq!(g.steps.len(), 1);
295        assert_eq!(g.steps[0].intent.as_deref(), Some("open_page"));
296        assert_eq!(g.triggers.len(), 1);
297    }
298
299    #[test]
300    fn from_manifest_rejects_non_procedure() {
301        let mut m = manifest_with_steps(vec![], vec![]);
302        m.content.procedure = None;
303        m.content.context = Some("ctx".into());
304        assert!(matches!(
305            SkillGene::from_manifest(&m),
306            Err(GeneError::NotProcedure)
307        ));
308    }
309
310    #[test]
311    fn diff_detects_added_and_changed_steps() {
312        let a = manifest_with_steps(
313            vec![ProcedureStep {
314                description: "old".into(),
315                tool: None,
316                intent: Some("i1".into()),
317                tool_hint: None,
318                ..Default::default()
319            }],
320            vec![],
321        );
322        let b = manifest_with_steps(
323            vec![
324                ProcedureStep {
325                    description: "new desc".into(),
326                    tool: None,
327                    intent: Some("i1".into()),
328                    tool_hint: None,
329                    ..Default::default()
330                },
331                ProcedureStep {
332                    description: "added".into(),
333                    tool: None,
334                    intent: Some("i2".into()),
335                    tool_hint: None,
336                    ..Default::default()
337                },
338            ],
339            vec![],
340        );
341        let ga = SkillGene::from_manifest(&a).unwrap();
342        let gb = SkillGene::from_manifest(&b).unwrap();
343        let d = GeneDiff::between(&ga, &gb);
344        assert_eq!(d.steps_changed.len(), 1);
345        assert_eq!(d.steps_added.len(), 1);
346        assert_eq!(d.steps_removed.len(), 0);
347    }
348
349    #[test]
350    fn diff_treats_intentless_steps_as_unmatched() {
351        let a = manifest_with_steps(
352            vec![ProcedureStep {
353                description: "no-intent".into(),
354                tool: None,
355                intent: None,
356                tool_hint: None,
357                ..Default::default()
358            }],
359            vec![],
360        );
361        let b = manifest_with_steps(vec![], vec![]);
362        let ga = SkillGene::from_manifest(&a).unwrap();
363        let gb = SkillGene::from_manifest(&b).unwrap();
364        let d = GeneDiff::between(&ga, &gb);
365        assert_eq!(d.steps_removed.len(), 1);
366    }
367
368    #[test]
369    fn round_trip_to_procedure_preserves_intent_and_tool() {
370        let g = SkillGene {
371            triggers: BTreeSet::new(),
372            steps: vec![StepGene {
373                intent: Some("i".into()),
374                description: "d".into(),
375                tool: Some("t".into()),
376            }],
377            requires: BTreeMap::new(),
378            mcp: BTreeSet::new(),
379        };
380        let p = g.to_procedure();
381        assert_eq!(p.steps.len(), 1);
382        assert_eq!(p.steps[0].intent.as_deref(), Some("i"));
383        assert_eq!(p.steps[0].tool.as_deref(), Some("t"));
384        assert!(p.steps[0].tool_hint.is_none());
385    }
386}
mur_common/skill/gene.rs

mur_common/skill/
gene.rs
