domainforge 0.13.0

package/domainforge-core/src/policy/three_valued.rs

@@ -0,0 +1,140 @@
+//! Three-valued boolean logic (SQL-like UNKNOWN) for SEA policy evaluation.
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum ThreeValuedBool {
+    True,
+    False,
+    Null,
+}
+
+impl ThreeValuedBool {
+    pub fn and(self, other: Self) -> Self {
+        use ThreeValuedBool::*;
+        match (self, other) {
+            (False, _) | (_, False) => False,
+            (True, True) => True,
+            (True, Null) | (Null, True) | (Null, Null) => Null,
+        }
+    }
+
+    pub fn or(self, other: Self) -> Self {
+        use ThreeValuedBool::*;
+        match (self, other) {
+            (True, _) | (_, True) => True,
+            (False, False) => False,
+            _ => Null,
+        }
+    }
+
+    #[allow(clippy::should_implement_trait)]
+    pub fn not(self) -> Self {
+        !self
+    }
+
+    pub fn implies(self, other: Self) -> Self {
+        // A -> B == (not A) or B
+        (!self).or(other)
+    }
+
+    pub fn from_option_bool(v: Option<bool>) -> Self {
+        match v {
+            Some(true) => ThreeValuedBool::True,
+            Some(false) => ThreeValuedBool::False,
+            None => ThreeValuedBool::Null,
+        }
+    }
+
+    pub fn into_option(self) -> Option<bool> {
+        match self {
+            ThreeValuedBool::True => Some(true),
+            ThreeValuedBool::False => Some(false),
+            ThreeValuedBool::Null => None,
+        }
+    }
+
+    pub fn fold_and<I: IntoIterator<Item = Self>>(iter: I) -> Self {
+        let mut seen_null = false;
+        for v in iter {
+            match v {
+                ThreeValuedBool::False => return ThreeValuedBool::False,
+                ThreeValuedBool::Null => seen_null = true,
+                ThreeValuedBool::True => {}
+            }
+        }
+        if seen_null {
+            ThreeValuedBool::Null
+        } else {
+            ThreeValuedBool::True
+        }
+    }
+
+    pub fn fold_or<I: IntoIterator<Item = Self>>(iter: I) -> Self {
+        let mut seen_null = false;
+        for v in iter {
+            match v {
+                ThreeValuedBool::True => return ThreeValuedBool::True,
+                ThreeValuedBool::Null => seen_null = true,
+                ThreeValuedBool::False => {}
+            }
+        }
+        if seen_null {
+            ThreeValuedBool::Null
+        } else {
+            ThreeValuedBool::False
+        }
+    }
+}
+
+impl std::ops::Not for ThreeValuedBool {
+    type Output = Self;
+
+    fn not(self) -> Self::Output {
+        use ThreeValuedBool::*;
+        match self {
+            True => False,
+            False => True,
+            Null => Null,
+        }
+    }
+}
+
+pub mod aggregators {
+    #![allow(dead_code)]
+    use rust_decimal::Decimal;
+
+    /// Sum that returns None (Null) if any element is missing.
+    pub fn sum_nullable(items: &[Option<Decimal>]) -> Option<Decimal> {
+        let mut total = Decimal::ZERO;
+        let mut any_null = false;
+        for item in items {
+            match item {
+                Some(v) => total += *v,
+                None => any_null = true,
+            }
+        }
+        if any_null {
+            None
+        } else {
+            Some(total)
+        }
+    }
+
+    /// Sum that ignores NULLs.
+    pub fn sum_nonnull(items: &[Option<Decimal>]) -> Decimal {
+        let mut total = Decimal::ZERO;
+        for v in items.iter().flatten() {
+            total += *v;
+        }
+        total
+    }
+
+    /// Count all items, including nulls.
+    pub fn count_all<T>(items: &[Option<T>]) -> usize {
+        items.len()
+    }
+
+    /// Count only non-null items.
+    pub fn count_nonnull<T>(items: &[Option<T>]) -> usize {
+        items.iter().filter(|x| x.is_some()).count()
+    }
+}

package/domainforge-core/src/policy/three_valued_microbench.rs

@@ -0,0 +1,104 @@
+use super::three_valued::aggregators::sum_nullable;
+/// Simple micro-benchmark using std::time::Instant
+/// Run with: cargo test --release -- --nocapture --ignored bench_microbench
+use rust_decimal::Decimal;
+
+#[cfg(test)]
+mod microbench {
+    use super::*;
+    use std::time::Instant;
+
+    #[test]
+    #[ignore] // Run explicitly with --ignored
+    fn bench_microbench_sum_comparison() {
+        const ITERATIONS: usize = 10_000;
+        const DATA_SIZE: usize = 1_000;
+        const WARMUP_ITERS: usize = 100;
+
+        // Baseline: strict sum with manual loop (more comparable to nullable version)
+        let data_strict: Vec<Decimal> = (0..DATA_SIZE).map(|i| Decimal::new(i as i64, 0)).collect();
+
+        let expected_strict_sum: Decimal = data_strict.iter().copied().sum();
+
+        for _ in 0..WARMUP_ITERS {
+            let mut total = Decimal::ZERO;
+            for item in &data_strict {
+                total += *item;
+            }
+            std::hint::black_box(total);
+        }
+
+        let start = Instant::now();
+        let mut last_strict_total = Decimal::ZERO;
+        for _ in 0..ITERATIONS {
+            let mut total = Decimal::ZERO;
+            for item in &data_strict {
+                total += *item;
+            }
+            std::hint::black_box(total);
+            last_strict_total = total;
+        }
+        let baseline_duration = start.elapsed();
+        assert_eq!(
+            last_strict_total, expected_strict_sum,
+            "strict sum should equal the arithmetic series of {} elements",
+            DATA_SIZE
+        );
+
+        // Nullable sum with 10% nulls
+        let data_nullable: Vec<Option<Decimal>> = (0..DATA_SIZE)
+            .map(|i| {
+                if i % 10 == 0 {
+                    None
+                } else {
+                    Some(Decimal::new(i as i64, 0))
+                }
+            })
+            .collect();
+
+        let expected_nullable_sum = sum_nullable(&data_nullable);
+
+        for _ in 0..WARMUP_ITERS {
+            let result = sum_nullable(&data_nullable);
+            std::hint::black_box(result);
+        }
+
+        let start = Instant::now();
+        let mut last_nullable_result = None;
+        for _ in 0..ITERATIONS {
+            let result = sum_nullable(&data_nullable);
+            std::hint::black_box(result);
+            last_nullable_result = result;
+        }
+        let nullable_duration = start.elapsed();
+        assert_eq!(
+            last_nullable_result, expected_nullable_sum,
+            "nullable sum result should match expectation for data with 10% nulls"
+        );
+
+        // Calculate overhead
+        let baseline_nanos = baseline_duration.as_nanos();
+        let denom = baseline_nanos.max(1);
+        let nullable_nanos = nullable_duration.as_nanos();
+        let overhead_pct = ((nullable_nanos as f64 / denom as f64) - 1.0) * 100.0;
+
+        println!("\n=== Micro-Benchmark Results ===");
+        println!("Iterations: {}", ITERATIONS);
+        println!("Data size: {}", DATA_SIZE);
+        println!("Baseline (strict):  {:?}", baseline_duration);
+        println!("Nullable (10% null): {:?}", nullable_duration);
+        println!("Overhead: {:.2}%", overhead_pct);
+        println!("================================\n");
+        println!("Note: Microbenchmarks show higher variance than Criterion.");
+        println!("Criterion benchmarks show ~7-10% overhead for this scenario.");
+
+        // Assert overhead is within acceptable range
+        // Note: Microbenchmarks typically show higher overhead than Criterion
+        // due to less sophisticated measurement techniques
+        assert!(
+            overhead_pct < 35.0,
+            "Overhead {:.2}% exceeds 35% threshold (microbench variance)",
+            overhead_pct
+        );
+    }
+}

package/domainforge-core/src/policy/type_inference.rs

@@ -0,0 +1,67 @@
+use crate::units::Dimension;
+use thiserror::Error;
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum ExprType {
+    Quantity { dimension: Dimension },
+    Numeric,
+    String,
+    Boolean,
+    Time,
+    Interval,
+    Collection(Box<ExprType>),
+}
+
+#[derive(Error, Debug, PartialEq)]
+pub enum TypeError {
+    #[error("Unit mismatch: expected {expected}, found {found}. Hint: {hint}")]
+    UnitMismatch {
+        expected: Dimension,
+        found: Dimension,
+        hint: String,
+    },
+    #[error("Mixed quantity and numeric types. Hint: {hint}")]
+    MixedQuantityNumeric { hint: String },
+    #[error("Type mismatch: expected {expected}, found {found}")]
+    TypeMismatch { expected: String, found: String },
+}
+
+pub fn check_comparison(left: &ExprType, right: &ExprType) -> Result<(), TypeError> {
+    match (left, right) {
+        (ExprType::Quantity { dimension: d1 }, ExprType::Quantity { dimension: d2 }) => {
+            if d1 != d2 {
+                return Err(TypeError::UnitMismatch {
+                    expected: d1.clone(),
+                    found: d2.clone(),
+                    hint: format!("Convert using 'as \"{}\"'", d1), // Simplified hint
+                });
+            }
+        }
+        (ExprType::Quantity { .. }, ExprType::Numeric) => {
+            return Err(TypeError::MixedQuantityNumeric {
+                hint: "Quantities require explicit units. Did you mean 'value as \"unit\"'?"
+                    .to_string(),
+            });
+        }
+        (ExprType::Numeric, ExprType::Quantity { .. }) => {
+            return Err(TypeError::MixedQuantityNumeric {
+                hint: "Quantities require explicit units. Did you mean 'value as \"unit\"'?"
+                    .to_string(),
+            });
+        }
+        (ExprType::Numeric, ExprType::Numeric) => {}
+        (ExprType::String, ExprType::String) => {}
+        (ExprType::Boolean, ExprType::Boolean) => {}
+        (ExprType::Time, ExprType::Time) => {} // Time before/after Time
+        (ExprType::Time, ExprType::Interval) => {} // Time during Interval
+        (ExprType::Interval, ExprType::Time) => {} // Interval contains Time (reverse)
+        (ExprType::Interval, ExprType::Interval) => {} // Interval comparisons
+        (t1, t2) => {
+            return Err(TypeError::TypeMismatch {
+                expected: format!("{:?}", t1),
+                found: format!("{:?}", t2),
+            });
+        }
+    }
+    Ok(())
+}

package/domainforge-core/src/policy/violation.rs

@@ -0,0 +1,36 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum Severity {
+    Error,
+    Warning,
+    Info,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Violation {
+    pub policy_name: String,
+    pub message: String,
+    pub severity: Severity,
+    pub context: serde_json::Value,
+}
+
+impl Violation {
+    pub fn new(
+        policy_name: impl Into<String>,
+        message: impl Into<String>,
+        severity: Severity,
+    ) -> Self {
+        Self {
+            policy_name: policy_name.into(),
+            message: message.into(),
+            severity,
+            context: serde_json::json!({}),
+        }
+    }
+
+    pub fn with_context(mut self, context: serde_json::Value) -> Self {
+        self.context = context;
+        self
+    }
+}

package/domainforge-core/src/primitives/concept_change.rs

@@ -0,0 +1,61 @@
+use crate::ConceptId;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ConceptChange {
+    id: ConceptId,
+    name: String,
+    from_version: String,
+    to_version: String,
+    migration_policy: String,
+    breaking_change: bool,
+}
+
+impl ConceptChange {
+    pub fn new(
+        name: impl Into<String>,
+        from_version: impl Into<String>,
+        to_version: impl Into<String>,
+        migration_policy: impl Into<String>,
+        breaking_change: bool,
+    ) -> Self {
+        let name = name.into();
+        // Concept changes are usually global or tied to a namespace, but here we assume default namespace for simplicity
+        // or we could add namespace support. For now, let's assume global or default.
+        let namespace = "default";
+        let id = ConceptId::from_concept(namespace, &name);
+
+        Self {
+            id,
+            name,
+            from_version: from_version.into(),
+            to_version: to_version.into(),
+            migration_policy: migration_policy.into(),
+            breaking_change,
+        }
+    }
+
+    pub fn id(&self) -> &ConceptId {
+        &self.id
+    }
+
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    pub fn from_version(&self) -> &str {
+        &self.from_version
+    }
+
+    pub fn to_version(&self) -> &str {
+        &self.to_version
+    }
+
+    pub fn migration_policy(&self) -> &str {
+        &self.migration_policy
+    }
+
+    pub fn is_breaking_change(&self) -> bool {
+        self.breaking_change
+    }
+}

package/domainforge-core/src/primitives/entity.rs

@@ -0,0 +1,224 @@
+use crate::ConceptId;
+use crate::SemanticVersion;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+use uuid::Uuid;
+
+/// Represents a business actor, location, or organizational unit.
+///
+/// Entities are the "WHO" in enterprise models - the actors that perform
+/// actions, hold resources, or participate in flows.
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// use domainforge_core::primitives::Entity;
+///
+/// let warehouse = Entity::new_with_namespace("Main Warehouse", "default");
+/// assert_eq!(warehouse.name(), "Main Warehouse");
+/// assert_eq!(warehouse.namespace(), "default");
+/// ```
+///
+/// With namespace:
+///
+/// ```
+/// use domainforge_core::primitives::Entity;
+///
+/// let warehouse = Entity::new_with_namespace("Warehouse A", "logistics");
+/// assert_eq!(warehouse.namespace(), "logistics");
+/// ```
+///
+/// With custom attributes:
+///
+/// ```
+/// use domainforge_core::primitives::Entity;
+/// use serde_json::json;
+///
+/// let mut factory = Entity::new_with_namespace("Factory", "default");
+/// factory.set_attribute("capacity", json!(5000));
+/// factory.set_attribute("location", json!("Building 3"));
+///
+/// assert_eq!(factory.get_attribute("capacity"), Some(&json!(5000)));
+/// ```
+///
+/// Serialization:
+///
+/// ```
+/// use domainforge_core::primitives::Entity;
+///
+/// let entity = Entity::new_with_namespace("Test Entity", "default");
+/// let json = serde_json::to_string(&entity).unwrap();
+/// let deserialized: Entity = serde_json::from_str(&json).unwrap();
+/// assert_eq!(entity.name(), deserialized.name());
+/// ```
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Entity {
+    id: ConceptId,
+    name: String,
+    namespace: String,
+    version: Option<SemanticVersion>,
+    replaces: Option<String>,
+    changes: Vec<String>,
+    attributes: HashMap<String, Value>,
+}
+
+impl Entity {
+    /// Creates a new Entity with a generated UUID (deprecated - use new_with_namespace).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use domainforge_core::primitives::Entity;
+    ///
+    /// let entity = Entity::new_with_namespace("Warehouse", "default");
+    /// assert_eq!(entity.name(), "Warehouse");
+    /// ```
+    #[deprecated(note = "use new_with_namespace instead")]
+    pub fn new(name: impl Into<String>) -> Self {
+        let name = name.into();
+        let namespace = "default".to_string();
+        Self {
+            id: ConceptId::from_concept(&namespace, &name),
+            name,
+            namespace,
+            version: None,
+            replaces: None,
+            changes: Vec::new(),
+            attributes: HashMap::new(),
+        }
+    }
+
+    /// Creates a new Entity with a specific namespace.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use domainforge_core::primitives::Entity;
+    ///
+    /// let entity = Entity::new_with_namespace("Warehouse", "logistics");
+    /// assert_eq!(entity.namespace(), "logistics");
+    /// ```
+    pub fn new_with_namespace(name: impl Into<String>, namespace: impl Into<String>) -> Self {
+        let namespace = namespace.into();
+        let name = name.into();
+        let id = ConceptId::from_concept(&namespace, &name);
+
+        Self {
+            id,
+            name,
+            namespace,
+            version: None,
+            replaces: None,
+            changes: Vec::new(),
+            attributes: HashMap::new(),
+        }
+    }
+
+    /// Sets the entity version.
+    pub fn with_version(mut self, version: SemanticVersion) -> Self {
+        self.version = Some(version);
+        self
+    }
+
+    /// Sets the entity that this version replaces.
+    pub fn with_replaces(mut self, replaces: String) -> Self {
+        self.replaces = Some(replaces);
+        self
+    }
+
+    /// Sets the list of changes in this version.
+    pub fn with_changes(mut self, changes: Vec<String>) -> Self {
+        self.changes = changes;
+        self
+    }
+
+    /// Returns the entity version.
+    pub fn version(&self) -> Option<&SemanticVersion> {
+        self.version.as_ref()
+    }
+
+    /// Returns the entity that this version replaces.
+    pub fn replaces(&self) -> Option<&str> {
+        self.replaces.as_deref()
+    }
+
+    /// Returns the list of changes in this version.
+    pub fn changes(&self) -> &[String] {
+        &self.changes
+    }
+
+    /// Creates an Entity from a legacy UUID for backward compatibility.
+    pub fn from_legacy_uuid(
+        uuid: Uuid,
+        name: impl Into<String>,
+        namespace: impl Into<String>,
+    ) -> Self {
+        Self {
+            id: ConceptId::from_legacy_uuid(uuid),
+            name: name.into(),
+            namespace: namespace.into(),
+            version: None,
+            replaces: None,
+            changes: Vec::new(),
+            attributes: HashMap::new(),
+        }
+    }
+
+    /// Returns the entity's unique identifier.
+    pub fn id(&self) -> &ConceptId {
+        &self.id
+    }
+
+    /// Returns the entity's name.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Returns the entity's namespace.
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    /// Sets a custom attribute.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use domainforge_core::primitives::Entity;
+    /// use serde_json::json;
+    ///
+    /// let mut entity = Entity::new_with_namespace("Factory", "default");
+    /// entity.set_attribute("capacity", json!(5000));
+    /// assert_eq!(entity.get_attribute("capacity"), Some(&json!(5000)));
+    /// ```
+    pub fn set_attribute(&mut self, key: impl Into<String>, value: Value) {
+        self.attributes.insert(key.into(), value);
+    }
+
+    /// Gets a custom attribute.
+    ///
+    /// Returns `None` if the attribute doesn't exist.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use domainforge_core::primitives::Entity;
+    /// use serde_json::json;
+    ///
+    /// let mut entity = Entity::new_with_namespace("Factory", "default");
+    /// entity.set_attribute("capacity", json!(5000));
+    /// assert_eq!(entity.get_attribute("capacity"), Some(&json!(5000)));
+    /// assert_eq!(entity.get_attribute("missing"), None);
+    /// ```
+    pub fn get_attribute(&self, key: &str) -> Option<&Value> {
+        self.attributes.get(key)
+    }
+
+    /// Returns all attributes as a reference.
+    pub fn attributes(&self) -> &HashMap<String, Value> {
+        &self.attributes
+    }
+}