DomainForge Handbook Epic

User Journey

The DomainForge bounded context provides the semantic modeling stack for SEA™ Forge, enabling Knowledge Graph operations (Oxigraph), SHACL validation, and SEA™ DSL projections to CALM, RDF, and SBVR. It serves as the central repository for domain concepts, relationships, and business rules.

Jobs to be Done & EARS Requirements

Job: Start Knowledge Graph (Oxigraph)

User Story: As a platform engineer, I want to start the Oxigraph RDF store, so that I can load and query semantic models.

EARS Requirement:

• While starting Knowledge Graph, when Oxigraph is launched via docker-compose, the domain forge context shall:
  1. Start Oxigraph container with volume mount for data persistence
  2. Expose SPARQL endpoint at http://localhost:7878/
  3. Verify server responds with “Oxigraph SPARQL server”
  4. Enable write access for data loading
  5. Confirm data persistence across container restarts

Job: Write SEA DSL Domain Model

User Story: As a domain architect, I want to write a SEA™ DSL model with entities, resources, flows, and policies, so that I have a declarative definition of my domain.

EARS Requirement:

• While authoring domain models, when a .sea file is created, the domain forge context shall:
  1. Accept file with @namespace (required, format: “com.example.domain”)
  2. Parse @version annotation (semver format X.Y.Z)
  3. Parse Entity declarations with name and bounded context
  4. Parse Resource declarations with name, unit, dimension, and context
  5. Parse Flow declarations with name, source, target, quantity, and unit
  6. Parse Policy declarations with name, type, priority, and expression
  7. Support Dimensions and Units for type checking
  8. Support quantifiers (forall, exists, sum) and operators in policy expressions

Job: Validate SEA DSL Model

User Story: As a developer, I want to validate my SEA™ DSL model for syntax, types, and units, so that errors are caught before compilation.

EARS Requirement:

• While validating models, when sea validate is executed, the domain forge context shall:
  1. Syntax Validation:
     • Parse file using tree-sitter-sea grammar
     • Return errors with line/column positions
  2. Type Checking:
     • Verify all referenced entities/resources are declared
     • Check Flow source/target reference valid entities
     • Validate resource units match dimensions
  3. Unit Checking:
     • Check Flow quantity units are compatible with resource units
     • Support unit conversion via as "unit" syntax
     • Report dimension mismatches
  4. Policy Validation:
     • Validate policy expression syntax
     • Check policy references are in scope
     • Verify required attributes per policy type
  5. Return validation result with:
     • ✓ Syntax valid
     • ✓ Types consistent
     • ✓ Units compatible
     • ✓ X policies validated

Job: Generate Projections from SEA DSL

User Story: As a developer, I want to compile SEA™ DSL to target formats (CALM, KG, SBVR), so that I can use the model across the platform.

EARS Requirement:

• While compiling models, when sea project is executed, the domain forge context shall:
  1. Parse and Validate input .sea file
  2. Generate Projections:
     • CALM (--calm): JSON architecture with bounded contexts, layers, dependencies
     • Knowledge Graph (--kg): RDF triples in Turtle format
     • SBVR (--sbvr): Business rules markdown in Structured English
  3. Write Output to generated/ directory:
     • example.calm.json - CALM architecture
     • example.ttl - RDF triples (Turtle)
     • example.sbvr.md - Business rules
  4. Deterministic Projection Rules:
     • Stable sort entities, resources, flows, and policies (by id then name)
     • Lexicographic ordering of all JSON map keys
     • No timestamps or random identifiers in projection artifacts
     • Canonical JSON formatting (UTF-8, consistent indentation, no trailing whitespace)
  5. Return list of generated files with paths

Job: Load Triples into Knowledge Graph

User Story: As a knowledge engineer, I want to load RDF triples into Oxigraph, so that I can query the semantic model.

EARS Requirement:

• While loading triples, when RDF data is posted to Oxigraph, the domain forge context shall:
  1. Accept POST request to http://localhost:7878/store
  2. Parse Content-Type: text/turtle
  3. Load triples into Oxigraph store
  4. Verify load success with query count
  5. Return confirmation with triple count

Job: Query Knowledge Graph via SPARQL

User Story: As a domain analyst, I want to execute SPARQL queries on the Knowledge Graph, so that I can retrieve semantic information.

EARS Requirement:

• While querying Knowledge Graph, when SPARQL query is posted, the domain forge context shall:
  1. Accept POST request to http://localhost:7878/query
  2. Parse Content-Type: application/sparql-query
  3. Execute SPARQL query on Oxigraph store
  4. Return results in requested format (JSON, XML, TSV)
  5. Support SELECT, ASK, CONSTRUCT, DESCRIBE queries

Job: Validate Knowledge Graph with SHACL

User Story: As a knowledge steward, I want to validate the Knowledge Graph against SHACL shapes, so that I can ensure data integrity.

EARS Requirement:

• While validating graph, when SHACL validation is executed, the domain forge context shall:
  1. Load SHACL shapes from TTL file
  2. Execute SHACL validation on graph data
  3. Return validation result with:
     • Conforms: true/false
     • Validation report with violations
     • Specific constraint failures with node path
     • Severity levels (error, warning, info)

Job: Manage Graph Snapshots

User Story: As a knowledge engineer, I want to create and restore Knowledge Graph snapshots, so that I can safely experiment with graph changes.

EARS Requirement:

• While managing snapshots, when snapshot operations are executed, the domain forge context shall:
  1. Create Snapshot:
     • Export all triples to N-Triples format
     • Compress and store with timestamp
     • Return snapshot ID
  2. Restore Snapshot:
     • Clear current graph data
     • Load triples from snapshot file
     • Verify restore with triple count
     • Return confirmation
  3. List Snapshots:
     • Return all snapshots with timestamps and sizes
     • Support filtering by date range

Domain Entities Summary

Root Aggregates

• SEADocument: SEA™ DSL file with namespace, version, and declarations
• KnowledgeGraph: Oxigraph RDF store with triples, SHACL shapes, and validation state
• Projection: Generated output artifact (CALM JSON, RDF Turtle, SBVR markdown)
• ValidationResult: Model validation output with errors, warnings, and status

Value Objects

• EntityDeclaration: Domain concept with name, bounded context, and properties
• ResourceDeclaration: Flow-able thing with name, unit, and dimension
• FlowDeclaration: Movement with source, target, quantity, and unit
• PolicyDeclaration: Business rule with type, priority, and expression
• SHACLShape: Validation constraint with target class and property shapes

Policy Rules

• RequiredNamespace: Every SEA™ DSL file must have @namespace annotation
• TripleValidity: All loaded triples must be valid RDF Turtle
• SHACLCompliance: Graph must conform to loaded SHACL shapes when validation is enabled
• SnapshotIntegrity: Snapshots must be complete and restore graph to exact state

Integration Points

• tree-sitter-sea: Grammar parser for SEA™ DSL
• Oxigraph: RDF triple store with SPARQL 1.1 support
• SHACL Engine: Shape validation for Knowledge Graph constraints
• CALM Projection: Generates architecture definition from SEA™ DSL
• Semantic Core Context: Processes SEA™ DSL for validation and compilation

Success Metrics

• Parse Success Rate: >99% for valid .sea files
• Validation Speed: <2 seconds for typical domain model
• Load Performance: <5 seconds to load 10,000 triples
• Query Performance: <500ms for typical SELECT queries

Non-Functional Requirements

• NFR-001: Knowledge Graph persists data across container restarts
• NFR-002: SPARQL queries support SELECT, ASK, CONSTRUCT, DESCRIBE
• NFR-003: SHACL validation completes in <10 seconds for typical graph
• NFR-004: Projections are deterministic (same input → identical output)