SEA DSL Handbook Epic

User Journey

The SEA DSL bounded context provides a declarative semantic modeling language that serves as the source-of-truth for validation and code projection in SEA™ Forge. It enables spec-first development through declarative Entity, Resource, Flow, and Policy declarations that compile to CALM, Knowledge Graph (RDF), SBVR, and executable code. SEA™ Forge is the platform that hosts the DSL toolchain; DomainForge is the bounded context inside SEA™ Forge that loads DSL models into the Knowledge Graph and projection pipeline.

Glossary

• SEA™ Forge: The SEA platform and toolchain that owns spec-first modeling, compilation, and code projection.
• DomainForge Context: The SEA™ Forge bounded context responsible for DSL validation, projection generation, and Knowledge Graph loading.

Jobs to be Done & EARS Requirements

Job: Author SEA DSL Domain Model

User Story: As a domain architect, I want to define business concepts using SEA™ DSL declarations, so that I have a machine-readable source-of-truth for my domain.

EARS Requirement:

• While authoring domain models, when a .sea file is created or modified, the SEA DSL context shall:
  1. Accept file-level annotations: @namespace (required, format: “com.example.domain”) and @version (semver format)
  2. Parse Entity declarations with name, bounded context, and optional properties
  3. Parse Resource declarations with name, unit, dimension, and bounded context
  4. Parse Flow declarations with name, source, target, quantity, and unit
  5. Parse Policy declarations with name, type (Constraint/Obligation/Permission), priority, and expression
  6. Enforce case-insensitive grammar keywords
  7. Validate declaration uniqueness within the @namespace scope:
     • Names must be globally unique across declaration kinds (Entity, Resource, Flow, Policy, Type)
     • Example (allowed): Entity Order, Flow PlaceOrder, Policy OrderPolicy
     • Example (disallowed): Entity Order and Resource Order in the same namespace
  8. Support single-line and multi-line comments

Job: Validate SEA DSL Syntax and Semantics

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

EARS Requirement:

• While developing SEA™ DSL models, when validation is executed via just sea-validate <file.sea>, the SEA DSL context shall:
  1. Syntax Validation:
     • Parse file using tree-sitter-sea grammar
     • Report syntax errors with line/column position
     • Return clear error messages for malformed declarations
  2. Annotation Validation:
     • Ensure @namespace is present and valid (format: “com.example.domain”)
     • Ensure @version follows semver format (X.Y.Z)
     • Ensure annotations use nested JSON keys (no dotted keys)
     • Validate all Flow declarations have @cqrs annotation with kind (“command”/”query”/”event”)
     • Validate @tx format: { "transactional": true | false }
     • Validate @outbox format: { "mode": "required" | "optional" }
     • Validate @idempotency format: { "enabled": true | false, "key": "<idempotency key source>" }
     • Validate @rationale format: { "text": "<string up to 500 chars>" }
     • Validate @deprecated format: { "enabled": true | false, "message": "<optional string>" }
  3. Type Consistency:
     • Verify all referenced entities/resources are declared
     • Check Flow source/target reference valid entities
     • Validate resource units match dimensions
     • Ensure policy expressions reference declared symbols
  4. Unit Compatibility:
     • Check Flow quantity units are compatible with resource units
     • Support unit conversion via as "unit" syntax
     • Report dimension mismatches with specific error location
  5. Policy Validation:
     • Validate policy expression syntax
     • Check policy references are in scope
     • Verify policy types (Constraint/Obligation/Permission) have required attributes
  6. Return validation result with:
     • Success/failure status
     • List of errors with file path, line, column, and message
     • List of warnings for non-critical issues

Job: Parse SEA DSL to AST

User Story: As a tool developer, I want to parse SEA™ DSL files to Abstract Syntax Trees, so that I can build tooling on top of the language.

EARS Requirement:

• While processing SEA™ DSL files, when just sea-parse <file.sea> is executed, the SEA DSL context shall:
  1. Parse the SEA™ DSL file using tree-sitter-sea grammar
  2. Generate JSON AST representation with complete node hierarchy
  3. Include node types (Entity, Resource, Flow, Policy, Annotation)
  4. Capture node properties (name, namespace, version, expressions)
  5. Preserve source location information (line, column) for each node
  6. Return deterministic AST (same input produces identical output)
  7. Handle parse errors gracefully with partial AST + error report

Job: Compile SEA DSL to Projections

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

EARS Requirement:

• While compiling SEA™ DSL models, when projection is requested, the SEA DSL context shall:
  1. Parse and Validate:
     • Read input .sea file
     • Validate syntax and semantics
     • Report errors and abort if invalid
  2. Generate Projections:
     • CALM (--calm): Generate JSON architecture definition with bounded contexts, layers, dependencies
     • Knowledge Graph (--kg): Generate RDF triples in Turtle format with SHACL shapes
     • SBVR (--sbvr): Generate business rules markdown in Structured English
     • Code (--code): Generate TypeScript/Python type definitions and interfaces
  3. Write Output Files:
     • Create generated/ directory if not exists
     • Write each projection to separate file with appropriate extension
     • Include source reference in file headers
  4. Verify Output:
     • Validate generated CALM JSON schema
     • Validate RDF triple syntax
     • Return list of generated files with paths

Job: Author CQRS Pattern in SEA DSL

User Story: As a domain architect, I want to define CQRS flows using SEA™ DSL with @cqrs annotations, so that commands and queries are explicitly separated.

EARS Requirement:

• While authoring CQRS patterns, when a Flow declaration includes @cqrs annotation, the SEA DSL context shall:
  1. Require @cqrs annotation on every Flow declaration
  2. Validate annotation value: { "kind": "command" | "query" | "event" }
  3. Enforce Flow-only CQRS tagging pattern per flow-lint rules (see docs/reference/flow-annotations.md; enforced by tools/flow_lint.py)
  4. Support @tx annotation for transactional flows: { "transactional": true | false }
  5. Support @outbox annotation for outbox pattern: { "mode": "required" | "optional" }
  6. Support @idempotency annotation: { "enabled": true | false, "key": "header:X-Idempotency-Key" }
  7. Validate annotation completeness for flows requiring transactional guarantees and outbox publishing

Job: Define and Validate Business Policies

User Story: As a business analyst, I want to define business rules as policies in SEA™ DSL, so that rules are machine-checkable and enforceable.

EARS Requirement:

• While authoring business policies, when a Policy declaration is created, the SEA DSL context shall:
  1. Accept policy types: Constraint (invariants), Obligation (requirements), Permission (authorizations)
  2. Parse policy priority levels (1-100, higher = more important)
  3. Support @rationale annotation for policy documentation
  4. Validate policy expressions using supported operators:
     • Quantifiers: forall, exists, sum, count, avg
     • Logical: and, or, not, implies
     • Comparison: =, <>, <, >, <=, >=
     • Arithmetic: +, -, *, /, %
  5. Check policy references are in scope (entities, resources, flows)
  6. Report policy validation errors with specific location and explanation

Job: Evolve SEA DSL Concepts with Versioning

User Story: As a domain steward, I want to evolve SEA™ DSL concepts over time while maintaining backward compatibility, so that existing models don’t break.

EARS Requirement:

• While evolving domain models, when concepts are versioned, the SEA DSL context shall:
  1. Support semantic versioning in @version annotation (MAJOR.MINOR.PATCH)
  2. Allow concept deprecation with @deprecated annotation
  3. Support concept aliases for renaming without breaking references
  4. Validate version compatibility across namespace imports
  5. Generate migration guidance for breaking changes
  6. Preserve concept lineage in Knowledge Graph projections

Domain Entities Summary

Root Aggregates

• SEADocument: Represents a .sea file with namespace, version, and declarations (Entity, Resource, Flow, Policy)
• ASTNode: Abstract Syntax Tree node representing parsed SEA™ DSL structure
• ValidationReport: Aggregates validation results with errors, warnings, and file references
• Projection: Generated output artifact (CALM JSON, RDF Turtle, SBVR markdown, code)

Value Objects

• EntityDeclaration: Domain concept with name, bounded context, and properties
• ResourceDeclaration: Flow-able thing with name, unit, dimension, and context
• FlowDeclaration: Movement from source to target with quantity, unit, and CQRS annotation
• PolicyDeclaration: Business rule with type, priority, rationale, and expression
• Annotation: Metadata attached to declarations (@namespace, @version, @cqrs, @tx, etc.)

Policy Rules

• RequiredNamespace: Every SEA™ DSL file must have @namespace annotation
• RequiredCQRS: Every Flow must have @cqrs annotation with valid kind
• DeclarationUniqueness: No duplicate declaration names within namespace
• ReferenceValidity: All referenced symbols must be declared in scope

Integration Points

• tree-sitter-sea Grammar: Parser for SEA™ DSL syntax
• Semantic Core Context: Processes parsed DSL for validation and projection
• DomainForge Context: Loads SEA™ DSL models into the Knowledge Graph and projection pipeline within SEA™ Forge
• Architectural Governance Context: Validates CALM projections for compliance
• Code Generation: Projects SEA™ DSL to TypeScript/Python type definitions

Success Metrics

• Parse Success Rate: >99% for valid .sea files
• Validation Accuracy: 100% of semantic errors correctly identified
• Projection Completeness: All 4 projections (CALM, KG, SBVR, Code) generated successfully
• Developer Velocity: <30 seconds from model edit to validated projection

Non-Functional Requirements

• NFR-001: SEA™ DSL is case-insensitive for keywords
• NFR-002: AST output is deterministic (same input → identical JSON)
• NFR-003: Validation completes in <5 seconds for typical domain model
• NFR-004: Generated projections are human-readable and version-controlled