Compiler Architecture

Overview

Weltenwanderer is a compiler, not a framework. A .ddd file describes a domain in the language of domain experts. The compiler:

1. Parses the DSL into an AST (Langium)
2. Validates internal consistency (exhaustiveness, guard consistency, totality)
3. Generates executable code for target platforms
4. Produces living documentation from a single source of truth

Package Dependencies

graph TD
    language["language"]
    cli["cli"]
    gen["generator-emmett"]
    syntax["syntax-highlighting"]
    website["website"]

    cli --> language
    gen --> language
    website --> cli
    website --> syntax

Parser (Phase 2)

Built with Langium 4.x. The grammar (packages/language/src/weltenwanderer.langium) defines 28 AST types in 191 lines. Key constructs:

• Context — bounded context container
• Command — intent to change state (with validate constraints)
• Event — fact that happened
• Decider — the core aggregate with decide, evolve, and terminal clauses
• Expression — operator-precedence grammar for guards, postconditions, and bindings

Validation Pipeline (Phase 3)

All validation rules register in packages/language/src/validation/weltenwanderer-validator.ts and run on Decider or Context nodes.

Check	Source	What It Detects
Exhaustiveness	exhaustiveness.ts	Missing decide clause for (Command, State) pair
Evolve Totality	totality.ts	Missing evolve clause for (State, Event) pair
Guard Consistency	guard-consistency.ts	Contradictory require guards (via abstract interpretation)
Dead Code	dead-code.ts	Commands/events declared but never used
Terminal States	terminal-states.ts	decide targeting terminal state; all states terminal

Guard consistency uses an abstract domain (abstract-domain.ts) for three-valued satisfiability checking: satisfiable | unsatisfiable | unknown. See ADR-015.

Four Constraint Layers

Layer	Keyword	Scope	On Failure
Type	: TypeName	Compile-time	Compile error
Value	validate	Command construction	Err(ValidationError[])
Business Rule	require	decide invocation	Err(RejectionError)
Postcondition	ensure	After evolve	Compile error (static)

See ADR-003 for the rationale.

Code Generation (Phase 4)

Generates per decider: decider class, smart constructors, event/state unions, and platform wiring. First target: Emmett/TypeScript.

Two-Level Verification

Level 1 (Domain): Exhaustiveness, totality, guard consistency, postcondition derivability, dead code, terminal states. Platform-independent, runs at compile time.

Level 2 (Generator): Property-based testing (fast-check) on generated code. Verifies that generated code preserves the semantics specified in .ddd.