domainforge 0.13.0

package/docs/specs/SDS-001-protobuf-projection-engine.md

@@ -0,0 +1,451 @@
+# SDS-001: Protobuf Projection Engine
+
+**System:** SEA Projection Framework  
+**Component:** Protobuf Projection Engine  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. High-Level Architecture
+
+```
+SEA DSL
+  ↓
+Parser
+  ↓
+Semantic Graph
+  ↓
+Projection Resolver
+  ↓
+Projection Engine (Protobuf)
+  ↓
+.proto Files
+```
+
+### Data Flow
+
+1. **SEA DSL Source** → Parsed into AST
+2. **AST** → Built into Semantic Graph
+3. **Projection Declarations** → Resolved into `ProjectionSpec`
+4. **Semantic Graph + ProjectionSpec** → Filtered and transformed
+5. **Protobuf IR** → Written to `.proto` files
+
+---
+
+## 2. Core Modules
+
+### 2.1 Projection Resolver
+
+**Location:** `domainforge-core/src/projection/resolver.rs`
+
+**Responsibilities:**
+
+- Parse `Projection` declarations from AST
+- Resolve scopes and filters against semantic graph
+- Produce validated `ProjectionSpec`
+
+```rust
+pub struct ProjectionSpec {
+    pub name: String,
+    pub format: ProjectionFormat,
+    pub filters: ProjectionFilters,
+    pub metadata: ProjectionMetadata,
+}
+
+pub struct ProjectionFilters {
+    pub namespaces: Vec<String>,
+    pub kinds: Vec<SeaKind>,
+    pub tags: Vec<String>,
+    pub profiles: Vec<String>,
+}
+
+pub struct ProjectionMetadata {
+    pub stability: Stability,
+    pub compatibility: Compatibility,
+    pub audience: Vec<String>,
+    pub version: SemanticVersion,
+}
+
+pub enum Compatibility {
+    Additive,
+    Backward,
+    Breaking,
+}
+
+pub enum Stability {
+    Experimental,
+    Stable,
+    Deprecated,
+}
+```
+
+### 2.2 Protobuf Projection Engine
+
+**Location:** `domainforge-core/src/projection/protobuf/engine.rs`
+
+**Responsibilities:**
+
+- Walk semantic graph using `ProjectionSpec`
+- Build intermediate Protobuf IR
+- Enforce compatibility rules
+- Emit `.proto` files
+
+```rust
+pub trait ProjectionEngine {
+    fn project(&self, graph: &SemanticGraph, spec: &ProjectionSpec) -> Result<ProjectionOutput, ProjectionError>;
+}
+
+pub struct ProtobufEngine {
+    type_mapper: TypeMapper,
+    compatibility_checker: CompatibilityChecker,
+}
+
+impl ProjectionEngine for ProtobufEngine {
+    fn project(&self, graph: &SemanticGraph, spec: &ProjectionSpec) -> Result<ProjectionOutput, ProjectionError> {
+        // 1. Filter graph nodes
+        // 2. Build Protobuf IR
+        // 3. Check compatibility
+        // 4. Generate output
+    }
+}
+```
+
+---
+
+## 3. Protobuf Intermediate Representation (IR)
+
+**Location:** `domainforge-core/src/projection/protobuf/ir.rs`
+
+```rust
+pub struct ProtoFile {
+    pub package: String,
+    pub syntax: String,  // "proto3"
+    pub imports: Vec<String>,
+    pub options: ProtoOptions,
+    pub enums: Vec<ProtoEnum>,
+    pub messages: Vec<ProtoMessage>,
+    pub metadata: ProtoMetadata,
+}
+
+pub struct ProtoMessage {
+    pub name: String,
+    pub fields: Vec<ProtoField>,
+    pub nested_messages: Vec<ProtoMessage>,
+    pub nested_enums: Vec<ProtoEnum>,
+    pub reserved_fields: Vec<u32>,
+    pub reserved_names: Vec<String>,
+    pub comments: Vec<String>,
+}
+
+pub struct ProtoField {
+    pub name: String,
+    pub number: u32,
+    pub proto_type: ProtoType,
+    pub label: FieldLabel,  // optional, repeated, required
+    pub comments: Vec<String>,
+}
+
+pub struct ProtoEnum {
+    pub name: String,
+    pub values: Vec<ProtoEnumValue>,
+    pub comments: Vec<String>,
+}
+
+pub struct ProtoEnumValue {
+    pub name: String,
+    pub number: i32,
+}
+
+pub struct ProtoOptions {
+    pub java_package: Option<String>,
+    pub java_multiple_files: bool,
+    pub go_package: Option<String>,
+}
+
+pub struct ProtoMetadata {
+    pub projection_name: String,
+    pub semantic_version: String,
+    pub source_namespace: String,
+    pub generated_at: String,
+}
+```
+
+---
+
+## 4. Mapping Rules
+
+### 4.1 SEA Entities / Resources → Protobuf Messages
+
+| SEA Construct | Protobuf Construct |
+| ------------- | ------------------ |
+| `Entity`      | `message`          |
+| `Resource`    | `message`          |
+| `ValueObject` | `message`          |
+| Attributes    | Fields             |
+| Relations     | Field references   |
+
+**Field Ordering:**
+
+- Fields are ordered deterministically by name (alphabetical)
+- Field numbers are assigned sequentially starting at 1
+- Once assigned, field numbers are immutable
+
+### 4.2 SEA Types → Protobuf Types
+
+| SEA Type      | Protobuf Type               |
+| ------------- | --------------------------- |
+| `String`      | `string`                    |
+| `Int`         | `int64`                     |
+| `Float`       | `double`                    |
+| `Bool`        | `bool`                      |
+| `Date`        | `google.protobuf.Timestamp` |
+| `DateTime`    | `google.protobuf.Timestamp` |
+| `Money`       | Custom `Money` message      |
+| `UUID`        | `string`                    |
+| `List<T>`     | `repeated T`                |
+| `Optional<T>` | `optional T`                |
+| Custom Entity | Reference message           |
+
+### 4.3 SEA Enums → Protobuf Enums
+
+- First value is always `UNSPECIFIED = 0`
+- Subsequent values numbered sequentially
+- Names converted to SCREAMING_SNAKE_CASE
+
+**Example:**
+
+```sea
+enum PaymentStatus {
+  Pending
+  Completed
+  Failed
+}
+```
+
+Becomes:
+
+```proto
+enum PaymentStatus {
+  PAYMENT_STATUS_UNSPECIFIED = 0;
+  PAYMENT_STATUS_PENDING = 1;
+  PAYMENT_STATUS_COMPLETED = 2;
+  PAYMENT_STATUS_FAILED = 3;
+}
+```
+
+### 4.4 Flows / Policies / Metrics
+
+Emit standardized governance and telemetry messages:
+
+```proto
+message GovernanceEvent {
+  string event_id = 1;
+  string flow_name = 2;
+  string policy_name = 3;
+  google.protobuf.Timestamp timestamp = 4;
+  map<string, string> context = 5;
+}
+
+message MetricEvent {
+  string metric_name = 1;
+  double value = 2;
+  google.protobuf.Timestamp timestamp = 3;
+  map<string, string> dimensions = 4;
+}
+```
+
+---
+
+## 5. Compatibility Enforcement Algorithm
+
+**Location:** `domainforge-core/src/projection/protobuf/compatibility.rs`
+
+```rust
+pub struct CompatibilityChecker {
+    history_store: Box<dyn SchemaHistoryStore>,
+}
+
+impl CompatibilityChecker {
+    pub fn check(
+        &self,
+        new_schema: &ProtoFile,
+        spec: &ProjectionSpec,
+    ) -> Result<(), CompatibilityViolation> {
+        // 1. Load previous schema (if available)
+        let previous = self.history_store.load(&spec.name)?;
+
+        if let Some(prev) = previous {
+            // 2. Diff old vs new
+            let diff = self.diff(&prev, new_schema);
+
+            // 3. Apply compatibility rules
+            match spec.metadata.compatibility {
+                Compatibility::Additive => self.check_additive(&diff)?,
+                Compatibility::Backward => self.check_backward(&diff)?,
+                Compatibility::Breaking => self.check_breaking(&diff)?,
+            }
+        }
+
+        // 4. Store new schema for future checks
+        self.history_store.save(&spec.name, new_schema)?;
+
+        Ok(())
+    }
+}
+```
+
+### Compatibility Rules Matrix
+
+| Change Type         | Additive | Backward      | Breaking |
+| ------------------- | -------- | ------------- | -------- |
+| Add field           | ✅       | ✅            | ✅       |
+| Remove field        | ❌       | ✅ (reserved) | ✅       |
+| Rename field        | ❌       | ❌            | ✅       |
+| Change field type   | ❌       | ❌            | ✅       |
+| Change field number | ❌       | ❌            | ✅       |
+| Add enum value      | ✅       | ✅            | ✅       |
+| Remove enum value   | ❌       | ✅ (reserved) | ✅       |
+
+---
+
+## 6. Output Structure
+
+```
+/generated
+  /protobuf
+    /com
+      /example
+        /finance
+          payments.proto
+          risk.proto
+        /hr
+          employees.proto
+```
+
+### File Header Template
+
+```proto
+// =============================================================================
+// Generated by SEA Projection Framework
+//
+// Projection: PaymentsProto
+// Semantic Version: 1.3.0
+// Source Namespace: com.example.finance.payments
+// Generated At: 2025-12-14T15:47:05Z
+//
+// DO NOT EDIT - This file is generated from SEA-DSL source
+// =============================================================================
+
+syntax = "proto3";
+
+package com.example.finance.payments;
+
+option java_package = "com.example.finance.payments";
+option java_multiple_files = true;
+option go_package = "github.com/example/finance/payments";
+```
+
+---
+
+## 7. Extension Points
+
+### 7.1 New Projection Formats
+
+Implement the `ProjectionEngine` trait:
+
+```rust
+pub struct GraphQLEngine;
+pub struct AvroEngine;
+pub struct OpenAPIEngine;
+
+impl ProjectionEngine for GraphQLEngine { /* ... */ }
+```
+
+### 7.2 Service/RPC Projections
+
+Future support for gRPC service definitions:
+
+```rust
+pub struct ProtoService {
+    pub name: String,
+    pub methods: Vec<ProtoMethod>,
+}
+
+pub struct ProtoMethod {
+    pub name: String,
+    pub input_type: String,
+    pub output_type: String,
+    pub streaming: StreamingMode,
+}
+```
+
+### 7.3 Semantic Diff Tooling
+
+```rust
+pub trait SchemaDiffTool {
+    fn diff(&self, old: &ProtoFile, new: &ProtoFile) -> SchemaDiff;
+    fn report(&self, diff: &SchemaDiff) -> String;
+}
+```
+
+---
+
+## 8. Error Handling
+
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum ProjectionError {
+    #[error("Invalid projection: {0}")]
+    InvalidProjection(String),
+
+    #[error("Namespace not found: {0}")]
+    NamespaceNotFound(String),
+
+    #[error("Compatibility violation: {0}")]
+    CompatibilityViolation(CompatibilityViolation),
+
+    #[error("IO error: {0}")]
+    IoError(#[from] std::io::Error),
+}
+
+#[derive(Debug)]
+pub struct CompatibilityViolation {
+    pub rule: Compatibility,
+    pub message_name: String,
+    pub field_name: String,
+    pub violation_type: ViolationType,
+}
+```
+
+---
+
+## 9. Testing Strategy
+
+### Unit Tests
+
+- Type mapping correctness
+- Field numbering determinism
+- Compatibility rule enforcement
+
+### Integration Tests
+
+- End-to-end projection from SEA → Protobuf
+- Round-trip parsing of generated `.proto` files
+- Multi-namespace projections
+
+### Golden Tests
+
+- Snapshot testing of generated output
+- Ensure deterministic generation
+
+---
+
+## Related Documents
+
+- [ADR-001: SEA-DSL as Semantic Source of Truth](./ADR-001-sea-dsl-semantic-source-of-truth.md)
+- [ADR-002: Projection as First-Class Construct](./ADR-002-projection-first-class-construct.md)
+- [ADR-003: Protobuf as Projection Target](./ADR-003-protobuf-projection-target.md)
+- [ADR-004: Projection Compatibility Semantics](./ADR-004-projection-compatibility-semantics.md)
+- [PRD-001: SEA Projection Framework](./PRD-001-sea-projection-framework.md)

package/docs/specs/SDS-002-sea-core-architecture.md

@@ -0,0 +1,268 @@
+# SDS-002: SEA Core Architecture
+
+**System:** DomainForge  
+**Component:** domainforge-core  
+**Version:** 0.2.1  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. Overview
+
+`domainforge-core` is the Rust implementation of the SEA Domain-Specific Language. It provides:
+
+- **Parsing**: Convert `.sea` source text to AST and semantic graph
+- **Validation**: Enforce semantic rules and constraints
+- **Policy Evaluation**: Execute business logic policies
+- **Projection**: Export to external formats (JSON, YAML, DDD, Protobuf)
+- **Multi-language Bindings**: Python, TypeScript, WASM
+
+---
+
+## 2. High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         domainforge-core                                │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐   │
+│  │  Parser  │→ │   AST    │→ │  Graph   │→ │  Projection   │   │
+│  │  (pest)  │  │          │  │          │  │    Engine     │   │
+│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘   │
+│        ↓                          ↓                              │
+│  ┌──────────┐              ┌──────────┐                          │
+│  │  Linter  │              │  Policy  │                          │
+│  │          │              │ Evaluator│                          │
+│  └──────────┘              └──────────┘                          │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐   │
+│  │  Python  │  │   Node   │  │   WASM   │  │     CLI       │   │
+│  │ Bindings │  │ Bindings │  │ Bindings │  │    (clap)     │   │
+│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Module Structure
+
+```
+domainforge-core/src/
+├── lib.rs              # Public API and feature-gated re-exports
+├── bin/sea.rs          # CLI entry point
+│
+├── parser/             # DSL parsing
+│   ├── mod.rs          # Parser API
+│   ├── ast.rs          # AST types and construction
+│   ├── error.rs        # Parse errors
+│   ├── lint.rs         # Linting rules
+│   ├── printer.rs      # Pretty printer
+│   └── profiles.rs     # Profile enforcement
+│
+├── grammar/            # Pest grammar
+│   └── sea.pest        # SEA grammar definition
+│
+├── primitives/         # Core domain types
+│   ├── entity.rs       # Entity primitive
+│   ├── resource.rs     # Resource primitive
+│   ├── flow.rs         # Flow primitive
+│   ├── instance.rs     # Instance primitive
+│   ├── role.rs         # Role primitive
+│   ├── relation.rs     # Relation types
+│   ├── policy.rs       # Policy primitive
+│   ├── metric.rs       # Metric primitive
+│   ├── concept_change.rs  # Temporal changes
+│   ├── mapping_contract.rs
+│   └── projection_contract.rs
+│
+├── graph/              # Semantic graph
+│   ├── mod.rs          # Graph structure
+│   └── to_ast.rs       # Graph → AST conversion
+│
+├── policy/             # Policy evaluation
+│   ├── mod.rs          # Policy engine
+│   ├── expression.rs   # Expression evaluation
+│   └── three_valued.rs # Three-valued logic
+│
+├── projection/         # Output generation
+│   ├── mod.rs          # Projection API
+│   ├── contracts.rs    # Mapping/projection contracts
+│   ├── engine.rs       # Projection executor
+│   └── registry.rs     # Projection registry
+│
+├── registry/           # Namespace management
+│   └── mod.rs          # NamespaceRegistry
+│
+├── module/             # Module resolution
+│   └── resolver.rs     # Import handling
+│
+├── error/              # Error handling
+│   ├── mod.rs          # Error types
+│   ├── diagnostics.rs  # Formatters
+│   └── fuzzy.rs        # Did-you-mean suggestions
+│
+├── cli/                # CLI commands
+│   ├── mod.rs          # Command definitions
+│   ├── validate.rs
+│   ├── project.rs
+│   ├── format.rs
+│   ├── import.rs
+│   └── test.rs
+│
+├── python/             # Python bindings (feature: python)
+├── typescript/         # Node.js bindings (feature: typescript)
+└── wasm/               # WASM bindings (feature: wasm)
+```
+
+---
+
+## 4. Core Types
+
+### 4.1 Semantic Primitives
+
+| Type            | Description                                           |
+| --------------- | ----------------------------------------------------- |
+| `Entity`        | Domain concept with attributes and optional relations |
+| `Resource`      | Quantifiable items that flow between entities         |
+| `Flow`          | Movement of resources between entities                |
+| `Instance`      | Concrete instantiation of an entity with values       |
+| `Role`          | Named capability assigned to entities                 |
+| `Relation`      | Typed relationship between entities                   |
+| `Policy`        | Executable business rule with expression              |
+| `Metric`        | Observable measurement with thresholds                |
+| `ConceptChange` | Temporal evolution of a concept                       |
+
+### 4.2 Graph
+
+```rust
+pub struct Graph {
+    entities: IndexMap<ConceptId, Entity>,
+    roles: IndexMap<ConceptId, Role>,
+    resources: IndexMap<ConceptId, Resource>,
+    flows: IndexMap<ConceptId, Flow>,
+    relations: IndexMap<ConceptId, RelationType>,
+    instances: IndexMap<ConceptId, ResourceInstance>,
+    entity_instances: IndexMap<ConceptId, Instance>,
+    policies: IndexMap<ConceptId, Policy>,
+    patterns: IndexMap<ConceptId, Pattern>,
+    concept_changes: IndexMap<ConceptId, ConceptChange>,
+    metrics: IndexMap<ConceptId, Metric>,
+    mappings: IndexMap<ConceptId, MappingContract>,
+    projections: IndexMap<ConceptId, ProjectionContract>,
+    config: GraphConfig,
+}
+```
+
+### 4.3 ConceptId
+
+Stable, content-addressable identifier for all graph nodes:
+
+```rust
+pub struct ConceptId {
+    namespace: String,
+    name: String,
+    uuid: Uuid,  // v5 deterministic from namespace:name
+}
+```
+
+---
+
+## 5. Data Flow
+
+### 5.1 Parse Pipeline
+
+```
+Source Text (.sea)
+       │
+       ▼
+┌─────────────────┐
+│   pest Parser   │  ← sea.pest grammar
+└────────┬────────┘
+         │ Pairs
+         ▼
+┌─────────────────┐
+│   AST Builder   │  ← ast.rs
+└────────┬────────┘
+         │ Ast
+         ▼
+┌─────────────────┐
+│ Graph Builder   │  ← ast_to_graph()
+└────────┬────────┘
+         │ Graph
+         ▼
+┌─────────────────┐
+│   Validation    │  ← Reference checks, type checks
+└────────┬────────┘
+         │ Result<Graph>
+         ▼
+    Ready for use
+```
+
+### 5.2 Policy Evaluation
+
+```rust
+// Three-valued logic for null-safe evaluation
+enum TruthValue {
+    True,
+    False,
+    Unknown,  // NULL propagation
+}
+
+impl Graph {
+    pub fn evaluate_policies(&self) -> Vec<Violation> {
+        self.policies
+            .values()
+            .flat_map(|policy| policy.evaluate(self))
+            .collect()
+    }
+}
+```
+
+---
+
+## 6. Feature Flags
+
+| Feature              | Dependencies      | Description                  |
+| -------------------- | ----------------- | ---------------------------- |
+| `python`             | pyo3, pythonize   | Python bindings              |
+| `typescript`         | napi, napi-derive | Node.js bindings             |
+| `wasm`               | wasm-bindgen      | WebAssembly bindings         |
+| `cli`                | clap, colored     | CLI binary                   |
+| `shacl`              | oxigraph          | SHACL validation             |
+| `three_valued_logic` | (none)            | NULL-aware policy evaluation |
+
+---
+
+## 7. Serialization
+
+Graph and primitives use `serde` for serialization:
+
+```rust
+#[derive(Serialize, Deserialize)]
+pub struct Entity { /* ... */ }
+
+// JSON round-trip
+let json = serde_json::to_string(&graph)?;
+let restored: Graph = serde_json::from_str(&json)?;
+```
+
+---
+
+## 8. Extension Points
+
+| Extension        | Mechanism                            |
+| ---------------- | ------------------------------------ |
+| New primitives   | Add to `primitives/`, update `Graph` |
+| New projections  | Implement in `projection/`, register |
+| New CLI commands | Add subcommand in `cli/`             |
+| New bindings     | Feature-gate new binding module      |
+
+---
+
+## Related Documents
+
+- [ADR-005: Multi-Language Support Strategy](./ADR-005-multi-language-support-strategy.md)
+- [ADR-006: Error Handling Strategy](./ADR-006-error-handling-strategy.md)
+- [SDS-003: Parser and Semantic Graph](./SDS-003-parser-semantic-graph.md)
+- [PRD-002: SEA CLI Tooling](./PRD-002-sea-cli-tooling.md)