domainforge 0.13.0

package/docs/specs/PRD-001-sea-projection-framework.md

@@ -0,0 +1,155 @@
+# PRD-001: SEA Projection Framework
+
+**Product:** SEA Projection Framework  
+**Primary Feature:** Protobuf Projection Engine  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Draft
+
+---
+
+## 1. Goals
+
+- Enable SEA-DSL users to declare projection intent explicitly.
+- Generate Protobuf schemas from semantic meaning, not implementation details.
+- Support agentic systems, governance pipelines, and services.
+- Enforce compatibility and stability guarantees automatically.
+
+---
+
+## 2. Non-Goals
+
+- SEA-DSL is **not** a schema language.
+- Protobuf is **not** an authoring format.
+- Projection engines do **not** infer business meaning.
+- No hand-authored `.proto` files as authoritative sources.
+
+---
+
+## 3. User Stories
+
+### 3.1 As a Domain Architect
+
+> I want to declare that a namespace should be exposed to agents as Protobuf so that AI systems can consume enterprise meaning safely.
+
+**Acceptance Criteria:**
+
+- Can define a `Projection` in SEA-DSL targeting a namespace
+- Generated `.proto` files contain all entities/resources in that namespace
+- Projection metadata is embedded in generated files
+
+### 3.2 As a Platform Engineer
+
+> I want Protobuf schemas to evolve backward-compatibly so agents don't break when semantics evolve.
+
+**Acceptance Criteria:**
+
+- Compatibility level is enforced during generation
+- Removed fields become `reserved` automatically
+- Build fails if compatibility rules are violated
+
+### 3.3 As a Governance Lead
+
+> I want to trace every runtime message back to a semantic definition and projection declaration.
+
+**Acceptance Criteria:**
+
+- Generated files include source projection name
+- Generated files include semantic version
+- Comments link back to source namespace
+
+---
+
+## 4. Functional Requirements
+
+### FR-1: Projection Declaration
+
+- DSL supports a `Projection` construct.
+- Projection supports:
+  - Source namespace(s)
+  - Filters (kinds, tags, profiles)
+  - Target format
+  - Metadata (stability, compatibility, audience)
+
+### FR-2: Semantic Graph Filtering
+
+- Projection engine can select graph nodes by:
+  - Namespace
+  - Kind (`Entity`, `Resource`, `Flow`, etc.)
+  - Tags
+  - Profiles
+
+### FR-3: Protobuf Generation
+
+- Generate `.proto` files containing:
+  - `message` definitions for Entities and Resources
+  - `enum` definitions
+  - Governance/event messages
+- Deterministic field numbering.
+- Namespaces map to Protobuf packages.
+
+### FR-4: Compatibility Enforcement
+
+- Enforce additive/backward/breaking rules.
+- Prevent illegal field reuse.
+- Emit `reserved` fields when needed.
+
+### FR-5: Traceability
+
+- Generated files include metadata:
+  - Projection name
+  - Semantic version
+  - Source namespace
+
+---
+
+## 5. Quality Attributes
+
+| Attribute         | Description                         |
+| ----------------- | ----------------------------------- |
+| **Deterministic** | Same input → same output            |
+| **Auditable**     | Traceable to DSL and projection     |
+| **Safe**          | Backward compatibility enforced     |
+| **Extensible**    | New projection targets can be added |
+
+---
+
+## 6. Success Metrics
+
+| Metric                          | Target                            |
+| ------------------------------- | --------------------------------- |
+| Projection coverage             | 100% of declared namespaces       |
+| Compatibility violations caught | 100% at build time                |
+| Generation time                 | < 1s for typical domain model     |
+| Traceability                    | Every message traceable to source |
+
+---
+
+## 7. Dependencies
+
+- SEA-DSL Parser (existing)
+- Semantic Graph Builder (existing)
+- Projection Resolver (new)
+- Protobuf Projection Engine (new)
+
+---
+
+## 8. Milestones
+
+| Phase | Deliverable               | Status  |
+| ----- | ------------------------- | ------- |
+| 1     | Projection DSL syntax     | Planned |
+| 2     | Projection Resolver       | Planned |
+| 3     | Basic Protobuf generation | Planned |
+| 4     | Compatibility enforcement | Planned |
+| 5     | Traceability metadata     | Planned |
+
+---
+
+## 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)
+- [SDS-001: Protobuf Projection Engine](./SDS-001-protobuf-projection-engine.md)

package/docs/specs/PRD-002-sea-cli-tooling.md

@@ -0,0 +1,169 @@
+# PRD-002: SEA CLI Tooling
+
+**Product:** SEA Command-Line Interface  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. Goals
+
+- Provide a unified `sea` command for all DSL operations.
+- Enable local development workflows: validate, format, project.
+- Support CI/CD integration with structured output.
+- Offer extensibility for future commands.
+
+---
+
+## 2. Non-Goals
+
+- GUI or TUI interfaces (out of scope for v1).
+- Package management or registry operations.
+- Remote execution or cloud deployment.
+
+---
+
+## 3. User Stories
+
+### 3.1 As a Domain Modeler
+
+> I want to validate my `.sea` files before committing so that I catch errors early.
+
+**Acceptance Criteria:**
+
+- `domainforge validate path/to/model.sea` reports errors with line numbers
+- Exit code is non-zero on validation failure
+
+### 3.2 As a Developer
+
+> I want to project my SEA models to JSON/DDD manifests for consumption by downstream systems.
+
+**Acceptance Criteria:**
+
+- `domainforge project --format json model.sea` outputs valid JSON
+- Multiple format options available (json, ddd, yaml)
+
+### 3.3 As a CI Pipeline
+
+> I want machine-readable validation output for automated quality gates.
+
+**Acceptance Criteria:**
+
+- `domainforge validate --format json` outputs structured error array
+- Consistent exit codes for scripting
+
+---
+
+## 4. Commands
+
+### 4.1 `domainforge validate`
+
+Validate SEA source files.
+
+```bash
+domainforge validate [OPTIONS] <FILES>...
+
+Options:
+  --format <FORMAT>    Output format [default: human] [possible: human, json, lsp]
+  --strict             Treat warnings as errors
+  --profile <PROFILE>  Enforce a specific DSL profile
+```
+
+### 4.2 `domainforge project`
+
+Export semantic graph to target formats.
+
+```bash
+domainforge project [OPTIONS] <FILE>
+
+Options:
+  --format <FORMAT>    Target format [default: json] [possible: json, ddd, yaml]
+  --output <PATH>      Output file path (default: stdout)
+```
+
+### 4.3 `domainforge format`
+
+Format SEA source files.
+
+```bash
+domainforge format [OPTIONS] <FILES>...
+
+Options:
+  --check              Check formatting without modifying files
+  --write              Write formatted output back to files
+```
+
+### 4.4 `domainforge import`
+
+Import models from external formats.
+
+```bash
+domainforge import [OPTIONS] <FILE>
+
+Options:
+  --from <FORMAT>      Source format [possible: turtle, rdfxml, sbvr]
+  --output <PATH>      Output .sea file path
+```
+
+### 4.5 `domainforge test`
+
+Run SEA test assertions.
+
+```bash
+domainforge test [OPTIONS] <FILES>...
+
+Options:
+  --filter <PATTERN>   Run only tests matching pattern
+```
+
+### 4.6 `domainforge validate-kg`
+
+Validate Knowledge Graph files (SHACL).
+
+```bash
+domainforge validate-kg [OPTIONS] <FILE>
+
+Options:
+  --shapes <PATH>      SHACL shapes file
+```
+
+---
+
+## 5. Global Options
+
+| Option             | Description                       |
+| ------------------ | --------------------------------- |
+| `--verbose`        | Increase output verbosity         |
+| `--quiet`          | Suppress non-error output         |
+| `--color <CHOICE>` | Color output: auto, always, never |
+
+---
+
+## 6. Exit Codes
+
+| Code | Meaning                     |
+| ---- | --------------------------- |
+| 0    | Success                     |
+| 1    | Validation/processing error |
+| 2    | Invalid arguments           |
+
+---
+
+## 7. Implementation Status
+
+| Command       | Status         |
+| ------------- | -------------- |
+| `validate`    | ✅ Implemented |
+| `project`     | ✅ Implemented |
+| `format`      | ✅ Implemented |
+| `import`      | ✅ Implemented |
+| `test`        | ✅ Implemented |
+| `validate-kg` | ✅ Implemented |
+
+---
+
+## Related Documents
+
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)
+- [ADR-006: Error Handling Strategy](./ADR-006-error-handling-strategy.md)

package/docs/specs/PRD-003-dsl-core-capabilities.md

@@ -0,0 +1,275 @@
+# PRD-003: DSL Core Capabilities
+
+**Product:** SEA Domain-Specific Language  
+**Version:** 1.0  
+**Date:** 2025-12-14  
+**Status:** Implemented
+
+---
+
+## 1. Goals
+
+- Define the complete vocabulary of SEA-DSL
+- Enable business-readable, machine-executable models
+- Support enterprise domain modeling patterns
+- Provide a stable foundation for all projections and bindings
+
+---
+
+## 2. Non-Goals
+
+- General-purpose programming language features
+- Runtime execution environment
+- Database or persistence layer
+- UI/visualization components
+
+---
+
+## 3. Core Primitives
+
+### 3.1 Entity
+
+**Purpose:** Represent actors, locations, or organizational units
+
+```sea
+Entity "Warehouse" in logistics {
+    id: UUID
+    name: String
+    capacity: Int
+    location: Address
+}
+```
+
+**Attributes:**
+
+- `name`: Human-readable identifier (required)
+- `namespace`: Logical grouping (optional, defaults to file namespace)
+- `attributes`: Typed fields with optional patterns
+- `relations`: Links to other entities
+
+### 3.2 Resource
+
+**Purpose:** Represent quantifiable items that flow between entities
+
+```sea
+Resource "Camera Units" units in inventory
+Resource "Payment" USD in finance
+```
+
+**Attributes:**
+
+- `name`: Resource identifier (required)
+- `unit`: Unit of measurement (required)
+- `namespace`: Logical grouping (optional)
+
+### 3.3 Flow
+
+**Purpose:** Represent movement of resources between entities
+
+```sea
+Flow "Camera Units" from "Assembly Line" to "Warehouse" quantity 100
+```
+
+**Attributes:**
+
+- `resource`: Reference to Resource (required)
+- `from`: Source Entity (required)
+- `to`: Destination Entity (required)
+- `quantity`: Numeric amount (required)
+
+### 3.4 Instance
+
+**Purpose:** Represent concrete, trackable instantiations of entities
+
+```sea
+Instance "Camera #SN12345" of "Camera" at "Warehouse A" {
+    serial_number: "SN12345"
+    manufactured_date: 2024-01-15
+    status: "available"
+}
+```
+
+**Attributes:**
+
+- `name`: Instance identifier (required)
+- `entity_type`: Reference to Entity type (required)
+- `location`: Current location Entity (optional)
+- `fields`: Concrete values for Entity attributes
+
+### 3.5 Role
+
+**Purpose:** Define capabilities that can be assigned to entities
+
+```sea
+Role "Supplier" in supply-chain {
+    provides: Resource
+}
+
+Role "Consumer" in supply-chain {
+    consumes: Resource
+}
+```
+
+### 3.6 Relation
+
+**Purpose:** Define typed relationships between entities via roles
+
+```sea
+Relation "supplies" {
+    subject: Supplier
+    object: Consumer
+    predicate: "supplies"
+    via: "Shipment"
+}
+```
+
+### 3.7 Policy
+
+**Purpose:** Express business rules and constraints
+
+```sea
+Policy production_minimum as:
+    forall f in Flow where f.resource = "Camera Units":
+        f.quantity >= 500
+
+Policy inventory_limit severity warn as:
+    forall e in Entity where e.type = "Warehouse":
+        sum(Instance.quantity where Instance.at = e) <= e.capacity
+```
+
+**Attributes:**
+
+- `name`: Policy identifier (required)
+- `expression`: Logical expression (required)
+- `severity`: error | warn | info (default: error)
+
+### 3.8 Metric
+
+**Purpose:** Define observable measurements with thresholds
+
+```sea
+Metric "Daily Throughput" on Flow where resource = "Camera Units" {
+    aggregate: sum(quantity)
+    warn_above: 1000
+    error_above: 2000
+}
+```
+
+### 3.9 Pattern
+
+**Purpose:** Define reusable validation patterns
+
+```sea
+Pattern "email" as: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
+Pattern "phone" as: /^\+?[1-9]\d{1,14}$/
+```
+
+### 3.10 ConceptChange
+
+**Purpose:** Model temporal evolution of concepts
+
+```sea
+ConceptChange "Product Rename" {
+    from: "Widget"
+    to: "Gadget"
+    effective: 2024-06-01
+    reason: "Rebranding initiative"
+}
+```
+
+---
+
+## 4. Expression Language
+
+### 4.1 Operators
+
+| Category   | Operators                       |
+| ---------- | ------------------------------- |
+| Comparison | `=`, `!=`, `<`, `>`, `<=`, `>=` |
+| Logical    | `and`, `or`, `not`              |
+| Arithmetic | `+`, `-`, `*`, `/`              |
+| Membership | `in`                            |
+
+### 4.2 Quantifiers
+
+| Quantifier                 | Meaning                                            |
+| -------------------------- | -------------------------------------------------- |
+| `forall x in Domain: expr` | Universal: true if expr holds for all x            |
+| `exists x in Domain: expr` | Existential: true if expr holds for at least one x |
+
+### 4.3 Aggregations
+
+| Function      | Description    |
+| ------------- | -------------- |
+| `sum(expr)`   | Sum of values  |
+| `count(expr)` | Count of items |
+| `min(expr)`   | Minimum value  |
+| `max(expr)`   | Maximum value  |
+| `avg(expr)`   | Average value  |
+
+---
+
+## 5. Type System
+
+### 5.1 Built-in Types
+
+| Type       | Description                       |
+| ---------- | --------------------------------- |
+| `String`   | Text value                        |
+| `Int`      | Integer                           |
+| `Float`    | Decimal number                    |
+| `Bool`     | Boolean                           |
+| `Date`     | Date (YYYY-MM-DD)                 |
+| `DateTime` | Date with time                    |
+| `UUID`     | Unique identifier                 |
+| `Email`    | Email address (pattern validated) |
+| `URL`      | Web URL                           |
+| `Money`    | Currency amount                   |
+
+### 5.2 Custom Types
+
+Defined via Entity attributes with patterns:
+
+```sea
+Entity "Customer" {
+    phone: String pattern: phone
+    email: String pattern: email
+}
+```
+
+---
+
+## 6. Profiles
+
+Restrict allowed constructs for specific use cases:
+
+```sea
+@profile "basic"
+
+// Only Entity, Resource, Flow allowed in this file
+```
+
+| Profile    | Allowed Constructs               |
+| ---------- | -------------------------------- |
+| `basic`    | Entity, Resource, Flow           |
+| `standard` | basic + Policy, Metric, Instance |
+| `full`     | All constructs                   |
+
+---
+
+## 7. Quality Attributes
+
+| Attribute         | Requirement                              |
+| ----------------- | ---------------------------------------- |
+| **Readability**   | Business analysts can understand models  |
+| **Precision**     | Unambiguous semantics for all constructs |
+| **Extensibility** | New primitives can be added              |
+| **Performance**   | 10,000 entities validated in < 100ms     |
+
+---
+
+## Related Documents
+
+- [SDS-002: SEA Core Architecture](./SDS-002-domainforge-core-architecture.md)
+- [SDS-003: Parser and Semantic Graph](./SDS-003-parser-semantic-graph.md)
+- [ADR-007: Policy Evaluation Engine](./ADR-007-policy-evaluation-engine.md)

package/docs/specs/README.md

@@ -0,0 +1,62 @@
+# DomainForge Specifications
+
+This directory contains the architectural documentation for DomainForge and the SEA Domain-Specific Language, including core architecture, projection framework, integrations, and tooling.
+
+## Document Overview
+
+### Architecture Decision Records (ADRs)
+
+| Document                                                   | Status   | Summary                                         |
+| ---------------------------------------------------------- | -------- | ----------------------------------------------- |
+| [ADR-001](./ADR-001-sea-dsl-semantic-source-of-truth.md)   | Accepted | SEA-DSL remains the semantic source of truth    |
+| [ADR-002](./ADR-002-projection-first-class-construct.md)   | Accepted | Projection as a first-class DSL construct       |
+| [ADR-003](./ADR-003-protobuf-projection-target.md)         | Accepted | Protobuf as a projection target                 |
+| [ADR-004](./ADR-004-projection-compatibility-semantics.md) | Accepted | Compatibility enforcement semantics             |
+| [ADR-005](./ADR-005-multi-language-support-strategy.md)    | Accepted | Multi-language support via Rust core + bindings |
+| [ADR-006](./ADR-006-error-handling-strategy.md)            | Accepted | Rich error handling with FFI propagation        |
+| [ADR-007](./ADR-007-policy-evaluation-engine.md)           | Accepted | Three-valued logic and quantifier support       |
+| [ADR-008](./ADR-008-knowledge-graph-integration.md)        | Accepted | RDF/Turtle export and SHACL validation          |
+| [ADR-009](./ADR-009-module-resolution-strategy.md)         | Accepted | Import syntax and namespace registry            |
+| [ADR-010](./ADR-010-unit-system.md)                        | Accepted | Dimensional analysis and unit conversions       |
+
+### Product Requirements Documents (PRDs)
+
+| Document                                         | Status      | Summary                                     |
+| ------------------------------------------------ | ----------- | ------------------------------------------- |
+| [PRD-001](./PRD-001-sea-projection-framework.md) | Draft       | SEA Projection Framework requirements       |
+| [PRD-002](./PRD-002-sea-cli-tooling.md)          | Implemented | SEA CLI commands and options                |
+| [PRD-003](./PRD-003-dsl-core-capabilities.md)    | Implemented | Core DSL primitives and expression language |
+
+### Software Design Specifications (SDSs)
+
+| Document                                           | Status      | Summary                                   |
+| -------------------------------------------------- | ----------- | ----------------------------------------- |
+| [SDS-001](./SDS-001-protobuf-projection-engine.md) | Draft       | Protobuf Projection Engine design         |
+| [SDS-002](./SDS-002-domainforge-core-architecture.md)      | Implemented | Core library architecture and modules     |
+| [SDS-003](./SDS-003-parser-semantic-graph.md)      | Implemented | Parser pipeline and graph construction    |
+| [SDS-004](./SDS-004-policy-engine-design.md)       | Implemented | Policy evaluation with three-valued logic |
+| [SDS-005](./SDS-005-knowledge-graph-module.md)     | Implemented | RDF/Turtle export/import and SHACL        |
+| [SDS-006](./SDS-006-calm-integration.md)           | Implemented | FINOS CALM architecture-as-code           |
+| [SDS-007](./SDS-007-sbvr-import.md)                | Implemented | OMG SBVR XMI business vocabulary import   |
+
+## Key Principles
+
+1. **Semantic Primacy**: SEA-DSL remains a semantic language; all schemas are derived, never authored directly.
+
+2. **Declarative Projections**: Projection intent is declared explicitly in the DSL, enabling governance and auditing.
+
+3. **Compatibility by Default**: All projections enforce compatibility rules to prevent breaking downstream consumers.
+
+4. **Traceability**: Every generated artifact links back to its semantic source and projection declaration.
+
+5. **Single Source of Truth**: Rust core (`domainforge-core`) is the single implementation; all language bindings wrap it.
+
+6. **Standards Alignment**: Built on SBVR semantics, RDF interoperability, and FINOS CALM architecture standards.
+
+## Quick Links
+
+- [Implementation Roadmap](../plans/protobuf_plan.yml)
+- [SEA-DSL Reference](../../domainforge-core/README.md)
+- [Python README](../../README_PYTHON.md)
+- [TypeScript README](../../README_TYPESCRIPT.md)
+- [WASM README](../../README_WASM.md)