domainforge 0.13.0

package/docs/specs/ADR-004-projection-compatibility-semantics.md

@@ -0,0 +1,57 @@
+# ADR-004: Enforce Projection Compatibility Semantics
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+Protobuf and other schema formats require strong backward-compatibility guarantees to avoid breaking agents and services.
+
+## Decision
+
+Each `Projection` SHALL declare a compatibility level:
+
+| Level      | Description                                                          |
+| ---------- | -------------------------------------------------------------------- |
+| `additive` | Only new fields may be added. No removals or modifications.          |
+| `backward` | Backward-compatible changes allowed. Removed fields become reserved. |
+| `breaking` | Structural changes allowed with explicit version bump.               |
+
+Projection engines SHALL enforce these rules when generating artifacts.
+
+### Enforcement Rules
+
+1. **Additive Mode**
+
+   - New fields: ✅ Allowed
+   - Field removal: ❌ Rejected
+   - Field modification: ❌ Rejected
+
+2. **Backward Mode**
+
+   - New fields: ✅ Allowed
+   - Field removal: ✅ Allowed (becomes `reserved`)
+   - Field type changes: ❌ Rejected
+
+3. **Breaking Mode**
+   - All changes: ✅ Allowed
+   - Requires: Major version increment
+
+## Consequences
+
+### Positive
+
+- Safe evolution of runtime contracts.
+- Breaking changes are explicit and auditable.
+- Field numbering and reservations are handled deterministically.
+
+### Negative
+
+- Requires tracking schema history for diff operations.
+- May slow down iteration during early development phases.
+
+## Related
+
+- [ADR-002: Introduce Projection as a First-Class DSL Construct](./ADR-002-projection-first-class-construct.md)
+- [ADR-003: Add Protobuf as a Projection Target](./ADR-003-protobuf-projection-target.md)

package/docs/specs/ADR-005-multi-language-support-strategy.md

@@ -0,0 +1,112 @@
+# ADR-005: Multi-Language Support Strategy
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+DomainForge needs to support multiple runtime environments to maximize adoption:
+
+- **Python**: Data scientists, ML engineers, enterprise automation
+- **TypeScript/JavaScript**: Web applications, serverless functions, Node.js backends
+- **WebAssembly (WASM)**: Browser-based tools, edge computing, sandboxed execution
+- **Rust**: High-performance systems, CLI tools, core library consumers
+
+Maintaining separate implementations for each language would lead to:
+
+- Feature drift between implementations
+- Multiplicative testing burden
+- Inconsistent behavior across platforms
+
+## Decision
+
+Implement a **single Rust core** (`domainforge-core`) that exposes bindings to other languages via FFI:
+
+| Target             | Binding Technology | Feature Flag |
+| ------------------ | ------------------ | ------------ |
+| Python             | PyO3 + Maturin     | `python`     |
+| TypeScript/Node.js | NAPI-RS            | `typescript` |
+| WebAssembly        | wasm-bindgen       | `wasm`       |
+| Rust               | Native crate       | (default)    |
+
+### Binding Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    domainforge-core (Rust)                  │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
+│  │ Parser  │ │  Graph  │ │ Policy  │ │Projection│  │
+│  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
+└─────────────────────────────────────────────────────┘
+         │              │              │
+    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+    │  PyO3   │    │ NAPI-RS │    │  WASM   │
+    │ Binding │    │ Binding │    │ Binding │
+    └────┬────┘    └────┬────┘    └────┬────┘
+         │              │              │
+    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+    │ Python  │    │  Node   │    │ Browser │
+    │  domainforge│    │  @sea   │    │  @sea   │
+    └─────────┘    └─────────┘    └─────────┘
+```
+
+### Binding Wrapper Pattern
+
+Each binding module wraps core Rust types with language-idiomatic APIs:
+
+```rust
+// Python binding example (domainforge-core/src/python/primitives.rs)
+#[pyclass]
+pub struct Entity {
+    inner: crate::primitives::Entity,
+}
+
+#[pymethods]
+impl Entity {
+    #[new]
+    fn new(name: String, namespace: String) -> Self { /* ... */ }
+
+    #[getter]
+    fn name(&self) -> &str { self.inner.name() }
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Single source of truth**: All semantics defined once in Rust.
+- **Consistent behavior**: All platforms use identical parsing, validation, and projection logic.
+- **Performance**: Core operations run at native speed; only boundary crossing has overhead.
+- **Reduced maintenance**: Bug fixes and features automatically propagate to all bindings.
+
+### Negative
+
+- **Rust expertise required**: Contributors must understand Rust for core changes.
+- **FFI complexity**: Each binding layer introduces serialization/deserialization overhead.
+- **Build complexity**: CI must build and test all target platforms.
+
+## Implementation Notes
+
+### Feature Flags
+
+Bindings are conditionally compiled via Cargo features:
+
+```toml
+[features]
+python = ["pyo3", "pythonize"]
+typescript = ["napi", "napi-derive"]
+wasm = ["wasm-bindgen", "serde-wasm-bindgen"]
+```
+
+### Data Serialization
+
+- Python: `pythonize` for automatic serde ↔ Python dict conversion
+- TypeScript: `napi` with serde for JSON-like object passing
+- WASM: `serde-wasm-bindgen` for efficient JS object bridging
+
+## Related
+
+- [ADR-006: Error Handling Strategy](./ADR-006-error-handling-strategy.md)
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)

package/docs/specs/ADR-006-error-handling-strategy.md

@@ -0,0 +1,115 @@
+# ADR-006: Error Handling Strategy
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+SEA-DSL operations can fail in multiple ways:
+
+- **Parse errors**: Invalid syntax in `.sea` files
+- **Validation errors**: Semantic violations (e.g., referencing undefined entities)
+- **Policy violations**: Business rule failures during evaluation
+- **Runtime errors**: I/O failures, module resolution issues
+
+Errors must:
+
+1. Provide actionable diagnostics (file, line, column, suggestions)
+2. Cross FFI boundaries cleanly (Rust → Python/TypeScript/WASM)
+3. Support multiple output formats (human-readable, JSON, LSP)
+
+## Decision
+
+### Error Type Hierarchy
+
+```rust
+// Core validation error with rich diagnostics
+pub struct ValidationError {
+    pub code: ErrorCode,
+    pub message: String,
+    pub range: Option<SourceRange>,
+    pub severity: Severity,
+    pub suggestions: Vec<String>,
+}
+
+// Structured error codes for programmatic handling
+pub enum ErrorCode {
+    // Syntax errors (1xxx)
+    SyntaxError = 1000,
+    UnexpectedToken = 1001,
+
+    // Semantic errors (2xxx)
+    UndefinedEntity = 2000,
+    DuplicateDeclaration = 2001,
+    TypeMismatch = 2002,
+
+    // Policy errors (3xxx)
+    PolicyViolation = 3000,
+    ConstraintFailed = 3001,
+
+    // Module errors (4xxx)
+    ModuleNotFound = 4000,
+    CircularImport = 4001,
+}
+```
+
+### Diagnostic Formatters
+
+Multiple output formats via the `DiagnosticFormatter` trait:
+
+| Formatter        | Use Case           | Output                       |
+| ---------------- | ------------------ | ---------------------------- |
+| `HumanFormatter` | CLI output         | Colored, contextual snippets |
+| `JsonFormatter`  | CI/automation      | Structured JSON array        |
+| `LspFormatter`   | Editor integration | LSP Diagnostic objects       |
+
+### FFI Error Propagation
+
+Errors are converted to native exceptions at language boundaries:
+
+```rust
+// Python: Convert to Python exception
+#[pyfunction]
+fn parse(source: &str) -> PyResult<Graph> {
+    crate::parse_to_graph(source)
+        .map_err(|e| PyValueError::new_err(e.to_string()))
+}
+
+// TypeScript: Return Result-like object or throw
+#[napi]
+fn parse(source: String) -> napi::Result<Graph> {
+    crate::parse_to_graph(&source)
+        .map_err(|e| napi::Error::from_reason(e.to_string()))
+}
+```
+
+### "Did You Mean?" Suggestions
+
+The `fuzzy` module provides Levenshtein-distance-based suggestions:
+
+```rust
+// When entity "Wharehouse" not found, suggest "Warehouse"
+if let Some(suggestion) = fuzzy::did_you_mean("Wharehouse", known_entities) {
+    error.suggestions.push(format!("Did you mean '{}'?", suggestion));
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Actionable errors**: Users get file locations and fix suggestions.
+- **Programmatic handling**: Error codes enable automated error categorization.
+- **IDE integration**: LSP formatter enables real-time editor diagnostics.
+- **Cross-platform consistency**: Same error structure across all bindings.
+
+### Negative
+
+- **Complexity**: Multiple formatter implementations to maintain.
+- **FFI overhead**: Error details may be lost when converting to simple strings.
+
+## Related
+
+- [ADR-005: Multi-Language Support Strategy](./ADR-005-multi-language-support-strategy.md)
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)

package/docs/specs/ADR-007-policy-evaluation-engine.md

@@ -0,0 +1,95 @@
+# ADR-007: Policy Evaluation Engine
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+SEA-DSL policies express business rules as logical expressions over the semantic graph. These policies must:
+
+1. Evaluate efficiently over large graphs (10,000+ entities)
+2. Support quantified expressions (`forall`, `exists`)
+3. Handle missing/null data gracefully
+4. Provide actionable violation reports
+
+Traditional two-valued boolean logic (true/false) fails when data is incomplete, leading to false positives or missed violations.
+
+## Decision
+
+### Three-Valued Logic
+
+Implement a **three-valued logic** system based on Kleene's strong logic:
+
+| Expression        | Result  |
+| ----------------- | ------- |
+| true AND unknown  | unknown |
+| false AND unknown | false   |
+| true OR unknown   | true    |
+| false OR unknown  | unknown |
+| NOT unknown       | unknown |
+
+```rust
+pub enum TruthValue {
+    True,
+    False,
+    Unknown,  // NULL propagation
+}
+
+impl TruthValue {
+    pub fn and(self, other: TruthValue) -> TruthValue {
+        match (self, other) {
+            (TruthValue::False, _) | (_, TruthValue::False) => TruthValue::False,
+            (TruthValue::Unknown, _) | (_, TruthValue::Unknown) => TruthValue::Unknown,
+            _ => TruthValue::True,
+        }
+    }
+}
+```
+
+### Quantifier Evaluation
+
+Support universal and existential quantifiers over graph collections:
+
+```sea
+// Universal: must hold for ALL matching entities
+Policy all_flows_positive as:
+    forall f in Flow: f.quantity > 0
+
+// Existential: must hold for AT LEAST ONE entity
+Policy has_active_warehouse as:
+    exists e in Entity where e.type = "Warehouse": e.active = true
+```
+
+### Expression Evaluation
+
+Expressions are parsed into an AST and evaluated against the graph:
+
+```rust
+pub enum Expression {
+    Literal(Value),
+    FieldAccess { object: Box<Expression>, field: String },
+    BinaryOp { left: Box<Expression>, op: BinaryOperator, right: Box<Expression> },
+    UnaryOp { op: UnaryOperator, operand: Box<Expression> },
+    Quantifier { kind: QuantifierKind, variable: String, domain: String, filter: Option<Box<Expression>>, body: Box<Expression> },
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Null-safe**: Missing data doesn't cause false violations
+- **Expressive**: Quantifiers enable complex business rules
+- **Efficient**: Lazy evaluation and short-circuit logic
+- **Debuggable**: Clear violation messages with context
+
+### Negative
+
+- **Complexity**: Three-valued logic less intuitive than boolean
+- **Performance**: Quantifier evaluation is O(n) per policy
+
+## Related
+
+- [SDS-004: Policy Engine Design](./SDS-004-policy-engine-design.md)
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)

package/docs/specs/ADR-008-knowledge-graph-integration.md

@@ -0,0 +1,90 @@
+# ADR-008: Knowledge Graph Integration
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+Enterprise systems often maintain knowledge in RDF/OWL knowledge graphs. SEA needs to:
+
+1. Export semantic models to standard RDF formats (Turtle, RDF-XML)
+2. Import existing knowledge graphs into SEA models
+3. Validate graph constraints using SHACL shapes
+4. Enable interoperability with semantic web tooling
+
+## Decision
+
+### RDF Export
+
+SEA graphs export to RDF using a canonical vocabulary:
+
+| SEA Concept | RDF Mapping                                             |
+| ----------- | ------------------------------------------------------- |
+| Entity      | `sea:Entity` instance with `rdfs:label`                 |
+| Resource    | `sea:Resource` instance with `sea:unit`                 |
+| Flow        | `sea:Flow` with `sea:from`, `sea:to`, `sea:hasResource` |
+| Relation    | `sea:Relation` with subject/object roles                |
+
+### Turtle Format
+
+```turtle
+@prefix sea: <http://domainforge.ai/sea#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+sea:Warehouse a sea:Entity ;
+    rdfs:label "Warehouse" ;
+    sea:namespace "logistics" .
+
+sea:Camera a sea:Resource ;
+    rdfs:label "Camera" ;
+    sea:unit "units" .
+```
+
+### SHACL Validation
+
+Generate SHACL shapes from SEA policies and validate imported graphs:
+
+```rust
+pub struct ShaclShape {
+    pub target_class: String,
+    pub properties: Vec<ShaclProperty>,
+}
+
+pub struct ShaclProperty {
+    pub path: String,
+    pub datatype: Option<String>,
+    pub min_count: Option<u32>,
+    pub max_count: Option<u32>,
+    pub min_exclusive: Option<String>,
+}
+```
+
+### Bidirectional Round-Trip
+
+```
+SEA Graph
+    ↓ to_turtle()
+Turtle/RDF
+    ↓ from_turtle()
+SEA Graph (restored)
+```
+
+## Consequences
+
+### Positive
+
+- **Interoperability**: Standard formats enable tool integration
+- **Semantic web**: Leverage existing RDF infrastructure
+- **Validation**: SHACL provides schema-level constraint checking
+- **Portability**: Export models for external consumption
+
+### Negative
+
+- **Lossy conversion**: Some SEA semantics may not map perfectly to RDF
+- **Complexity**: RDF parsing adds dependency weight
+
+## Related
+
+- [SDS-005: Knowledge Graph Module](./SDS-005-knowledge-graph-module.md)
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)

package/docs/specs/ADR-009-module-resolution-strategy.md

@@ -0,0 +1,115 @@
+# ADR-009: Module Resolution Strategy
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+Large SEA models need to be split across multiple files for maintainability. This requires:
+
+1. Import syntax for referencing external SEA files
+2. Namespace resolution for qualified references
+3. Standard library of reusable types
+4. Circular dependency detection
+
+## Decision
+
+### Import Syntax
+
+```sea
+// Relative file import
+import "common/types.sea"
+
+// Namespace binding
+import namespace core from "std/core.sea"
+
+// Selective import
+import { Customer, Order } from "domain/entities.sea"
+```
+
+### Namespace Registry
+
+A `.sea-registry.toml` file at the project root maps namespace prefixes to file paths:
+
+```toml
+[namespaces]
+core = "domainforge-core/std/core.sea"
+http = "domainforge-core/std/http.sea"
+aws = "domainforge-core/std/aws.sea"
+domain = "src/domain/index.sea"
+```
+
+### Resolution Algorithm
+
+1. Check if namespace is in registry
+2. Resolve relative to entry file if not found
+3. Search standard library paths
+4. Fail with helpful error message
+
+```rust
+pub struct ModuleResolver {
+    registry: NamespaceRegistry,
+    loaded: HashMap<PathBuf, Ast>,
+}
+
+impl ModuleResolver {
+    pub fn resolve(&mut self, import: &ImportSpec, from: &Path) -> Result<Ast, ParseError> {
+        // 1. Try registry lookup
+        if let Some(path) = self.registry.resolve(&import.namespace) {
+            return self.load(path);
+        }
+
+        // 2. Try relative resolution
+        let relative = from.parent().unwrap().join(&import.path);
+        if relative.exists() {
+            return self.load(&relative);
+        }
+
+        // 3. Fail with suggestion
+        Err(ParseError::ModuleNotFound { /* ... */ })
+    }
+}
+```
+
+### Circular Dependency Detection
+
+Track loading state to detect cycles:
+
+```rust
+enum LoadState {
+    Loading,    // Currently being parsed
+    Loaded(Ast), // Successfully loaded
+}
+
+// If we encounter Loading while resolving, it's circular
+```
+
+### Standard Library
+
+Built-in types available via `std:` prefix:
+
+| Module     | Contents                       |
+| ---------- | ------------------------------ |
+| `std:core` | Basic types (UUID, Email, URL) |
+| `std:http` | HTTP request/response patterns |
+| `std:aws`  | AWS resource types             |
+
+## Consequences
+
+### Positive
+
+- **Modularity**: Large models split into maintainable files
+- **Reusability**: Standard library provides common patterns
+- **Clarity**: Explicit namespace bindings reduce ambiguity
+- **Safety**: Circular dependencies caught at parse time
+
+### Negative
+
+- **Configuration**: Requires `.sea-registry.toml` setup
+- **Complexity**: Resolution logic adds parsing overhead
+
+## Related
+
+- [SDS-003: Parser and Semantic Graph](./SDS-003-parser-semantic-graph.md)
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)

package/docs/specs/ADR-010-unit-system.md

@@ -0,0 +1,106 @@
+# ADR-010: Unit System
+
+**Status:** Accepted  
+**Date:** 2025-12-14  
+**Deciders:** DomainForge Architecture Team
+
+## Context
+
+SEA Resources have associated units of measurement (e.g., "units", "kg", "USD"). The system needs to:
+
+1. Parse unit specifications from DSL source
+2. Validate unit compatibility in operations
+3. Support unit conversions where applicable
+4. Enable dimensional analysis for type safety
+
+## Decision
+
+### Unit Representation
+
+```rust
+pub struct Unit {
+    pub symbol: String,      // "kg", "USD", "units"
+    pub name: String,        // "Kilogram", "US Dollar", "Units"
+    pub dimension: Dimension, // Mass, Currency, Count
+    pub scale: f64,          // Conversion factor to base unit
+    pub base_symbol: String, // Base unit symbol
+}
+
+pub enum Dimension {
+    Mass,
+    Length,
+    Time,
+    Currency,
+    Count,
+    Temperature,
+    Custom(String),
+}
+```
+
+### Unit Parsing
+
+```rust
+pub fn unit_from_string(s: &str) -> Unit {
+    match s.to_lowercase().as_str() {
+        "units" | "unit" => Unit::count(),
+        "kg" | "kilograms" => Unit::mass_kg(),
+        "usd" | "dollars" => Unit::currency_usd(),
+        // ... more built-in units
+        custom => Unit::custom(custom),
+    }
+}
+```
+
+### Conversion Operator
+
+The DSL supports explicit unit conversion via the `as` operator:
+
+```sea
+Resource "Response Time" 1000 'ms' as 's'  // Converts to 1 second
+```
+
+### Dimensional Analysis
+
+Prevent invalid operations at parse time:
+
+```sea
+// Error: Cannot add Mass and Currency
+Policy invalid as: Weight.value + Price.value > 100
+```
+
+### Unit Registry
+
+Extensible registry for custom units:
+
+```rust
+pub struct UnitRegistry {
+    units: HashMap<String, Unit>,
+    conversions: HashMap<(String, String), f64>,
+}
+
+impl UnitRegistry {
+    pub fn convert(&self, value: f64, from: &str, to: &str) -> Option<f64> {
+        self.conversions.get(&(from.to_string(), to.to_string()))
+            .map(|factor| value * factor)
+    }
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Type safety**: Dimensional analysis catches unit errors
+- **Expressiveness**: Natural unit syntax in DSL
+- **Flexibility**: Custom units for domain-specific needs
+- **Interoperability**: Standard units map to external systems
+
+### Negative
+
+- **Complexity**: Full dimensional analysis is non-trivial
+- **Limitations**: Not all unit conversions are linear
+
+## Related
+
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)
+- [PRD-003: DSL Core Capabilities](./PRD-003-dsl-core-capabilities.md)