ADR-004: Semantic Core Formalization with SEA™ DSL

Status: Accepted Version: 1.0 Date: 2025-10-01 Supersedes: N/A Related ADRs: N/A Related PRDs: PRD-001, PRD-003

Context

To establish a single source of truth for business semantics and enable machine-readable business rules.

Decision

The Semantic Core will be formalized using the SEA™ DSL (Semantic Enterprise Architecture DSL). This DSL serves as the canonical definition for all business policies, domain entities, and rules.

SBVR (Semantics of Business Vocabulary and Business Rules) is supported exclusively as a projection target for interoperability and stakeholder review. It is NOT the runtime execution engine. No runtime component shall depend on SBVR parsers or engines; all policy evaluation must occur via the SEA™ DSL Policy Evaluator.

Rationale

SEA™ DSL provides a concise, business-oriented language for defining concepts that maps directly to the system’s execution capabilities (Deontic + 3-Valued Logic). Treating SBVR as a projection target rather than a runtime dependency allows for:

1. Deterministic Execution: SEA™ DSL aligns directly with the Rust-based Policy Evaluator.
2. Performance: Eliminates overhead of parsing natural-language-like SBVR at runtime.
3. Simplicity: Decouples core logic from complex OMG standards compliance.

Compatibility Profile: SEA™ DSL ↔ SBVR

SEA™ DSL ↔ SBVR Mapping

• SEA™ DSL Policy → SBVR Rule: Maps 1:1 for standard Deontic modalities (Obligation, Prohibition, Permission).
• SEA™ DSL Entity → SBVR Noun Concept: Direct mapping.
• SEA™ DSL Flow → SBVR Verb Concept/Fact Type: Mapped to fact types connecting noun concepts.

Lossy vs. Lossless Aspects

• Semantic Logic: Lossless. The logical truth conditions are preserved.
• Type System: Lossy. SEA™ DSL’s strict Rust-backed types (e.g., Decimal, u64) are projected to generic SBVR representations.
• Annotations: Lossy. Internal SEA™ DSL annotations (@metrics, @generator_hints) may not have standard SBVR equivalents and are excluded or serialized as comments.

Unsupported SBVR Constructs

The following standard SBVR constructs are NOT supported in the SEA-Forge™ profile:

• Complex localized vocabulary variants (SEA™ DSL enforces a single ubiquitous language per namespace).
• Dynamic runtime synonym definitions (Synonyms must be resolved at compile time).

Round-Trip Guarantees

• Logic: Guaranteed. $P_{sea} \equiv Parse(Project_{sbvr}(P_{sea}))$.
• Formatting/Layout: Not guaranteed. Re-importing SBVR will apply standard SEA™ DSL formatting.
• Comments: Not guaranteed.

Alternatives Considered

Natural Language Descriptions

Rejected - Inherent ambiguity and difficulty in automated processing.

Traditional Data Modeling (UML, ERD)

Rejected - Often lack the expressiveness for complex business rules and direct semantic grounding.

Constraints

• MUST use SEA™ DSL as the canonical source of truth for all business policies
• MUST NOT use SBVR as a runtime execution engine
• MUST project SBVR only as an interoperability target
• MUST resolve all synonyms at compile time

Quality Attributes

• Unambiguous business rules
• Improved communication between business and IT
• Foundation for AI-driven automation
• Enhanced data quality

Bounded Contexts Impacted

• Semantic Core
• Policy Evaluator
• Knowledge Layer

Consequences

Positive

• Unambiguous business rules
• Improved communication between business and IT
• Foundation for AI-driven automation
• Enhanced data quality

Negative

• Requires specialized skills in DSL design and SBVR
• Initial investment in tooling and training

Additional Notes

✅ MVP