domainforge 0.13.0

package/docs/specs/SDS-006-calm-integration.md

@@ -0,0 +1,367 @@
+# SDS-006: CALM Integration
+
+**System:** DomainForge  
+**Component:** FINOS CALM Import/Export  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. Overview
+
+The CALM (Common Architecture Language Model) integration enables DomainForge to:
+
+- Export SEA models to FINOS CALM JSON format
+- Import FINOS CALM architecture models into SEA
+- Support enterprise architecture governance workflows
+- Enable architecture-as-code practices
+
+---
+
+## 2. FINOS CALM Background
+
+CALM is a standardized format for describing enterprise architectures:
+
+```json
+{
+  "$schema": "https://calm.finos.org/draft/2024-03/meta/core.json",
+  "nodes": [...],
+  "relationships": [...]
+}
+```
+
+Key CALM concepts:
+
+- **Nodes**: Architectural components (services, systems, actors)
+- **Relationships**: Connections between nodes
+- **Interfaces**: API contracts and interactions
+
+---
+
+## 3. Architecture
+
+```
+┌────────────────────────────────────────────────────┐
+│                 calm/ Module                        │
+├────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐               │
+│  │  CalmModel   │  │  CalmNode    │               │
+│  └──────────────┘  └──────────────┘               │
+│  ┌──────────────────────────────────┐             │
+│  │       CalmRelationship           │             │
+│  └──────────────────────────────────┘             │
+├────────────────────────────────────────────────────┤
+│  export.rs         │  import.rs                    │
+│  - export()        │  - import()                   │
+│  - graph_to_calm() │  - calm_to_graph()            │
+├────────────────────────────────────────────────────┤
+│  sbvr_import.rs                                    │
+│  - import_sbvr_xmi()                               │
+└────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Core Types
+
+### 4.1 CalmModel
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CalmModel {
+    #[serde(rename = "$schema")]
+    pub schema: String,
+    pub nodes: Vec<CalmNode>,
+    pub relationships: Vec<CalmRelationship>,
+}
+
+impl CalmModel {
+    pub fn new() -> Self {
+        Self {
+            schema: "https://calm.finos.org/draft/2024-03/meta/core.json".to_string(),
+            nodes: Vec::new(),
+            relationships: Vec::new(),
+        }
+    }
+}
+```
+
+### 4.2 CalmNode
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CalmNode {
+    #[serde(rename = "unique-id")]
+    pub unique_id: String,
+
+    pub name: String,
+
+    #[serde(rename = "node-type")]
+    pub node_type: String,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub interfaces: Option<Vec<CalmInterface>>,
+
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+```
+
+### 4.3 CalmRelationship
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CalmRelationship {
+    #[serde(rename = "unique-id")]
+    pub unique_id: String,
+
+    #[serde(rename = "relationship-type")]
+    pub relationship_type: RelationshipType,
+
+    pub parties: Parties,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Parties {
+    pub source: String,
+    pub destination: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum RelationshipType {
+    Connects,
+    Interacts,
+    Deployed,
+    Composed,
+}
+```
+
+---
+
+## 5. Mapping Rules
+
+### 5.1 SEA → CALM Mappings
+
+| SEA Concept | CALM Mapping                                            |
+| ----------- | ------------------------------------------------------- |
+| Entity      | `CalmNode` with `node-type: "system"` or `"actor"`      |
+| Resource    | `CalmNode` with `node-type: "data-asset"`               |
+| Flow        | `CalmRelationship` with `relationship-type: "connects"` |
+| Role        | `CalmNode` with `node-type: "actor"`                    |
+| Relation    | `CalmRelationship` with appropriate type                |
+
+### 5.2 Node Type Inference
+
+```rust
+fn infer_node_type(entity: &Entity) -> String {
+    // Use entity attributes or naming conventions
+    if entity.name().ends_with("Service") {
+        "service".to_string()
+    } else if entity.name().ends_with("Database") || entity.name().ends_with("Store") {
+        "database".to_string()
+    } else if entity.has_role("Actor") {
+        "actor".to_string()
+    } else {
+        "system".to_string()
+    }
+}
+```
+
+---
+
+## 6. Export Process
+
+### 6.1 Graph to CALM
+
+```rust
+pub fn export(graph: &Graph) -> Result<CalmModel, CalmError> {
+    let mut model = CalmModel::new();
+
+    // Export entities as nodes
+    for entity in graph.all_entities() {
+        model.nodes.push(CalmNode {
+            unique_id: entity.id().to_string(),
+            name: entity.name().to_string(),
+            node_type: infer_node_type(entity),
+            description: entity.get_attribute("description")
+                .and_then(|v| v.as_str().map(String::from)),
+            interfaces: None,
+            extra: HashMap::new(),
+        });
+    }
+
+    // Export resources as data assets
+    for resource in graph.all_resources() {
+        model.nodes.push(CalmNode {
+            unique_id: resource.id().to_string(),
+            name: resource.name().to_string(),
+            node_type: "data-asset".to_string(),
+            description: None,
+            interfaces: None,
+            extra: HashMap::new(),
+        });
+    }
+
+    // Export flows as relationships
+    for flow in graph.all_flows() {
+        model.relationships.push(CalmRelationship {
+            unique_id: flow.id().to_string(),
+            relationship_type: RelationshipType::Connects,
+            parties: Parties {
+                source: flow.from_id().to_string(),
+                destination: flow.to_id().to_string(),
+            },
+            description: Some(format!(
+                "{} (quantity: {})",
+                graph.get_resource(flow.resource_id())
+                    .map(|r| r.name())
+                    .unwrap_or("unknown"),
+                flow.quantity()
+            )),
+        });
+    }
+
+    Ok(model)
+}
+```
+
+### 6.2 JSON Serialization
+
+```rust
+impl CalmModel {
+    pub fn to_json(&self) -> Result<String, CalmError> {
+        serde_json::to_string_pretty(self)
+            .map_err(|e| CalmError::Serialization(e.to_string()))
+    }
+
+    pub fn to_json_compact(&self) -> Result<String, CalmError> {
+        serde_json::to_string(self)
+            .map_err(|e| CalmError::Serialization(e.to_string()))
+    }
+}
+```
+
+---
+
+## 7. Import Process
+
+### 7.1 CALM to Graph
+
+```rust
+pub fn import(json: &str) -> Result<Graph, CalmError> {
+    let model: CalmModel = serde_json::from_str(json)
+        .map_err(|e| CalmError::Parse(e.to_string()))?;
+
+    let mut graph = Graph::new();
+
+    // Import nodes
+    for node in model.nodes {
+        match node.node_type.as_str() {
+            "actor" | "system" | "service" => {
+                let entity = Entity::new_with_namespace(
+                    node.name.clone(),
+                    "calm".to_string(),
+                );
+                graph.add_entity(entity)?;
+            }
+            "data-asset" => {
+                let resource = Resource::new_with_namespace(
+                    node.name.clone(),
+                    Unit::count(),
+                    "calm".to_string(),
+                );
+                graph.add_resource(resource)?;
+            }
+            _ => {
+                // Unknown node types become entities
+                let entity = Entity::new_with_namespace(
+                    node.name.clone(),
+                    "calm".to_string(),
+                );
+                graph.add_entity(entity)?;
+            }
+        }
+    }
+
+    // Import relationships as flows (where applicable)
+    for rel in model.relationships {
+        if rel.relationship_type == RelationshipType::Connects {
+            // Create a synthetic resource for the flow
+            let resource_name = format!("{}→{}", rel.parties.source, rel.parties.destination);
+            // ...
+        }
+    }
+
+    Ok(graph)
+}
+```
+
+---
+
+## 8. CLI Integration
+
+```bash
+# Export to CALM
+domainforge project --format calm model.sea > architecture.json
+
+# Import from CALM
+domainforge import --from calm architecture.json > model.sea
+```
+
+---
+
+## 9. Validation
+
+### 9.1 CALM Schema Validation
+
+```rust
+pub fn validate_calm_schema(json: &str) -> Result<(), CalmError> {
+    let model: CalmModel = serde_json::from_str(json)?;
+
+    // Check required fields
+    for node in &model.nodes {
+        if node.unique_id.is_empty() {
+            return Err(CalmError::Validation("Node missing unique-id".to_string()));
+        }
+        if node.name.is_empty() {
+            return Err(CalmError::Validation("Node missing name".to_string()));
+        }
+    }
+
+    // Check relationship references
+    let node_ids: HashSet<_> = model.nodes.iter()
+        .map(|n| n.unique_id.as_str())
+        .collect();
+
+    for rel in &model.relationships {
+        if !node_ids.contains(rel.parties.source.as_str()) {
+            return Err(CalmError::Validation(
+                format!("Relationship references unknown source: {}", rel.parties.source)
+            ));
+        }
+        if !node_ids.contains(rel.parties.destination.as_str()) {
+            return Err(CalmError::Validation(
+                format!("Relationship references unknown destination: {}", rel.parties.destination)
+            ));
+        }
+    }
+
+    Ok(())
+}
+```
+
+---
+
+## Related Documents
+
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)
+- [PRD-002: SEA CLI Tooling](./PRD-002-sea-cli-tooling.md)

package/docs/specs/SDS-007-sbvr-import.md

@@ -0,0 +1,347 @@
+# SDS-007: SBVR Import
+
+**System:** DomainForge  
+**Component:** SBVR XMI Import  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. Overview
+
+The SBVR (Semantics of Business Vocabulary and Rules) import module enables DomainForge to:
+
+- Import OMG SBVR XMI files into SEA graphs
+- Convert SBVR fact types to SEA relations
+- Transform SBVR rules to SEA policies
+- Preserve business vocabulary semantics
+
+---
+
+## 2. SBVR Background
+
+SBVR is an OMG standard for expressing business vocabularies and rules in natural language with formal semantics. Key concepts:
+
+- **Noun Concepts**: Business terms (e.g., "Customer", "Order")
+- **Verb Concepts**: Relationships between terms (e.g., "places", "contains")
+- **Fact Types**: Structured propositions (e.g., "Customer places Order")
+- **Business Rules**: Constraints and derivation rules
+
+---
+
+## 3. Architecture
+
+```
+┌────────────────────────────────────────────────────┐
+│                 sbvr.rs Module                      │
+├────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐               │
+│  │  SbvrModel   │  │ NounConcept  │               │
+│  └──────────────┘  └──────────────┘               │
+│  ┌──────────────┐  ┌──────────────┐               │
+│  │  VerbConcept │  │  FactType    │               │
+│  └──────────────┘  └──────────────┘               │
+│  ┌──────────────┐  ┌──────────────┐               │
+│  │BusinessRule  │  │ Definition   │               │
+│  └──────────────┘  └──────────────┘               │
+├────────────────────────────────────────────────────┤
+│  Parsing Methods                                   │
+│  - from_xmi()                                      │
+│  - to_graph()                                      │
+└────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Core Types
+
+### 4.1 SbvrModel
+
+```rust
+pub struct SbvrModel {
+    pub name: String,
+    pub noun_concepts: Vec<NounConcept>,
+    pub verb_concepts: Vec<VerbConcept>,
+    pub fact_types: Vec<FactType>,
+    pub business_rules: Vec<BusinessRule>,
+    pub definitions: Vec<Definition>,
+}
+```
+
+### 4.2 NounConcept
+
+```rust
+pub struct NounConcept {
+    pub id: String,
+    pub name: String,
+    pub definition: Option<String>,
+    pub synonyms: Vec<String>,
+    pub general_concept: Option<String>,  // Parent concept
+}
+```
+
+### 4.3 VerbConcept
+
+```rust
+pub struct VerbConcept {
+    pub id: String,
+    pub name: String,      // e.g., "places"
+    pub roles: Vec<Role>,  // Subject and object roles
+}
+
+pub struct Role {
+    pub name: String,
+    pub noun_concept_id: String,
+    pub cardinality: Cardinality,
+}
+
+pub enum Cardinality {
+    One,
+    ZeroOrOne,
+    OneOrMore,
+    ZeroOrMore,
+}
+```
+
+### 4.4 FactType
+
+```rust
+pub struct FactType {
+    pub id: String,
+    pub reading: String,           // e.g., "Customer places Order"
+    pub verb_concept_id: String,
+    pub role_bindings: Vec<(String, String)>,  // (role_id, concept_id)
+}
+```
+
+### 4.5 BusinessRule
+
+```rust
+pub struct BusinessRule {
+    pub id: String,
+    pub name: String,
+    pub statement: String,         // Natural language
+    pub rule_type: RuleType,
+    pub fact_type_refs: Vec<String>,
+}
+
+pub enum RuleType {
+    StructuralRule,     // Cardinality, uniqueness
+    DerivationRule,     // Computed facts
+    OperativeRule,      // Business constraints
+}
+```
+
+---
+
+## 5. XMI Parsing
+
+### 5.1 Parser Implementation
+
+```rust
+impl SbvrModel {
+    pub fn from_xmi(xmi: &str) -> Result<Self, SbvrError> {
+        let doc = roxmltree::Document::parse(xmi)
+            .map_err(|e| SbvrError::Parse(e.to_string()))?;
+
+        let mut model = SbvrModel::default();
+
+        // Parse noun concepts
+        for node in doc.descendants().filter(|n| n.has_tag_name("nounConcept")) {
+            model.noun_concepts.push(NounConcept {
+                id: node.attribute("xmi:id").unwrap_or_default().to_string(),
+                name: node.attribute("name").unwrap_or_default().to_string(),
+                definition: node.children()
+                    .find(|n| n.has_tag_name("definition"))
+                    .and_then(|n| n.text().map(String::from)),
+                synonyms: Vec::new(),
+                general_concept: node.attribute("generalConcept").map(String::from),
+            });
+        }
+
+        // Parse verb concepts
+        for node in doc.descendants().filter(|n| n.has_tag_name("verbConcept")) {
+            // ...
+        }
+
+        // Parse fact types
+        for node in doc.descendants().filter(|n| n.has_tag_name("factType")) {
+            // ...
+        }
+
+        // Parse business rules
+        for node in doc.descendants().filter(|n| n.has_tag_name("businessRule")) {
+            // ...
+        }
+
+        Ok(model)
+    }
+}
+```
+
+---
+
+## 6. Conversion to SEA Graph
+
+### 6.1 Mapping Strategy
+
+| SBVR Concept               | SEA Mapping                  |
+| -------------------------- | ---------------------------- |
+| Noun Concept               | Entity                       |
+| Verb Concept               | Relation (predicate)         |
+| Fact Type                  | Role-based Relation          |
+| Business Rule (structural) | Policy                       |
+| Business Rule (operative)  | Policy                       |
+| Definition                 | Entity description attribute |
+
+### 6.2 Conversion Implementation
+
+```rust
+impl SbvrModel {
+    pub fn to_graph(&self) -> Result<Graph, SbvrError> {
+        let mut graph = Graph::new();
+
+        // Convert noun concepts to entities
+        for noun in &self.noun_concepts {
+            let mut entity = Entity::new_with_namespace(
+                noun.name.clone(),
+                "sbvr".to_string(),
+            );
+
+            if let Some(def) = &noun.definition {
+                entity.set_attribute("description", serde_json::json!(def));
+            }
+
+            graph.add_entity(entity)?;
+        }
+
+        // Convert verb concepts to roles
+        for verb in &self.verb_concepts {
+            for role in &verb.roles {
+                let sea_role = Role::new_with_namespace(
+                    role.name.clone(),
+                    "sbvr".to_string(),
+                );
+                graph.add_role(sea_role)?;
+            }
+        }
+
+        // Convert fact types to relations
+        for fact in &self.fact_types {
+            if let Some(verb) = self.verb_concepts.iter().find(|v| v.id == fact.verb_concept_id) {
+                if verb.roles.len() >= 2 {
+                    let subject_role_id = graph.find_role_by_name(&verb.roles[0].name)
+                        .ok_or(SbvrError::Conversion("Role not found".to_string()))?;
+                    let object_role_id = graph.find_role_by_name(&verb.roles[1].name)
+                        .ok_or(SbvrError::Conversion("Role not found".to_string()))?;
+
+                    let relation = RelationType::new(
+                        verb.name.clone(),
+                        subject_role_id,
+                        object_role_id,
+                        verb.name.clone(),  // predicate
+                    );
+                    graph.add_relation_type(relation)?;
+                }
+            }
+        }
+
+        // Convert business rules to policies
+        for rule in &self.business_rules {
+            let policy = self.convert_rule_to_policy(rule)?;
+            graph.add_policy(policy)?;
+        }
+
+        Ok(graph)
+    }
+
+    fn convert_rule_to_policy(&self, rule: &BusinessRule) -> Result<Policy, SbvrError> {
+        // Convert SBVR statement to SEA expression
+        // This is a simplified mapping; full SBVR requires more complex parsing
+        let expression = self.parse_sbvr_statement(&rule.statement)?;
+
+        Ok(Policy {
+            id: ConceptId::new("sbvr", &rule.name),
+            name: rule.name.clone(),
+            expression,
+            severity: match rule.rule_type {
+                RuleType::StructuralRule => Severity::Error,
+                RuleType::OperativeRule => Severity::Warning,
+                RuleType::DerivationRule => Severity::Info,
+            },
+            description: Some(rule.statement.clone()),
+        })
+    }
+}
+```
+
+---
+
+## 7. SBVR Statement Parsing
+
+### 7.1 Supported Patterns
+
+| SBVR Pattern               | SEA Expression             |
+| -------------------------- | -------------------------- |
+| "Each X must Y"            | `forall x in X: Y(x)`      |
+| "At most one X per Y"      | Cardinality check          |
+| "It is necessary that..."  | Policy with error severity |
+| "It is permitted that..."  | No policy (allowed)        |
+| "It is obligatory that..." | Policy with error severity |
+
+### 7.2 Expression Conversion
+
+```rust
+fn parse_sbvr_statement(&self, statement: &str) -> Result<Expression, SbvrError> {
+    let normalized = statement.to_lowercase();
+
+    // Pattern: "Each X must have at least one Y"
+    if normalized.contains("each") && normalized.contains("must have") {
+        // Extract subject and object
+        // Build forall expression
+        // ...
+    }
+
+    // Pattern: "It is necessary that..."
+    if normalized.starts_with("it is necessary that") {
+        // Extract constraint
+        // Build expression
+        // ...
+    }
+
+    // Default: store as raw statement for manual review
+    Ok(Expression::Literal(Value::String(statement.to_string())))
+}
+```
+
+---
+
+## 8. CLI Integration
+
+```bash
+# Import SBVR XMI file
+domainforge import --from sbvr vocabulary.xmi > model.sea
+
+# Import with namespace override
+domainforge import --from sbvr --namespace my-domain vocabulary.xmi
+```
+
+---
+
+## 9. Limitations
+
+| Limitation           | Workaround                        |
+| -------------------- | --------------------------------- |
+| Complex quantifiers  | Manual policy authoring           |
+| Computed derivations | Not supported (logged as warning) |
+| Temporal rules       | Limited support via ConceptChange |
+| Modal logic          | Mapped to severity levels         |
+
+---
+
+## Related Documents
+
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)
+- [SDS-004: Policy Engine Design](./SDS-004-policy-engine-design.md)
+- [PRD-003: DSL Core Capabilities](./PRD-003-dsl-core-capabilities.md)