Update RIDDL language reference for January 2026

Reconciled EBNF grammar and language guide with current parser code.

Key changes:
- Removed statements: if, foreach, call, stop, focus, reply, return, read, write
- Added statements: when, match, let, prompt
- Added BAST import syntax
- Updated all examples to use new statement syntax
- Added documentation for new keywords: default, let, match, prompt

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: reidspencer

docs/riddl/references/ebnf-grammar.md

@@ -1,10 +1,10 @@
 # Formal EBNF Grammar
 
-Below is the formal Extended Backus-Naur Form (EBNF) grammar for RIDDL. 
-This grammar provides a precise definition of RIDDL syntax and can be used as a 
-reference when constructing valid RIDDL expressions. This grammar was 
-automaticaly extracted from the reference grammar written in Scala/fastparse 
-form at March 1, 2025. The maintainers will keep it up to date.  
+Below is the formal Extended Backus-Naur Form (EBNF) grammar for RIDDL.
+This grammar provides a precise definition of RIDDL syntax and can be used as a
+reference when constructing valid RIDDL expressions. This grammar was
+automatically extracted from the reference grammar written in Scala/fastparse
+form and last updated January 17, 2026. The maintainers will keep it up to date.
 
 ```ebnf
 (* RIDDL Grammar in EBNF *)
@@ -29,9 +29,10 @@ end_of_line_comment = "//" {any_char_except_newline} newline ;
 
 (* Main Structure *)
 root = {root_content}+ ;
-root_content = module_content | module | root_include ;
+root_content = bast_import | module_content | module | root_include ;
 module_content = domain | author | comment ;
 root_include = "include" literal_string ;
+bast_import = "import" literal_string ;  (* path must end with .bast *)
 
 (* Module *)
 module = "module" identifier "is" "{" {module_content | module_include}+ "}" [with_metadata] ;
@@ -41,7 +42,7 @@ module_include = "include" literal_string ;
 domain = "domain" identifier "is" "{" domain_body "}" [with_metadata] ;
 domain_body = domain_definitions | "???" ;
 domain_definitions = {domain_content}+ ;
-domain_content = vital_definition_contents | author | context | domain | user | epic | saga | import_def | domain_include | comment ;
+domain_content = vital_definition_contents | author | context | domain | user | epic | saga | import_def | bast_import | domain_include | comment ;
 import_def = "import" "domain" identifier "from" literal_string ;
 domain_include = "include" literal_string ;
 
@@ -73,13 +74,13 @@ aggregate_use_case = "type" | "command" | "query" | "event" | "result" | "record
 (* Type Expressions *)
 type_expression = cardinality(
     predefined_types | pattern_type | unique_id_type | enumeration | sequence_type | mapping_from_to | a_set_type |
-    graph_type | table_type | replica_type | range_type | decimal_type | alternation | entity_reference_type | 
+    graph_type | table_type | replica_type | range_type | decimal_type | alternation | entity_reference_type |
     aggregation | aggregate_use_case_type_expression | aliased_type_expression
 ) ;
 
 cardinality = ["many"] ["optional"] type_expression_base ["?" | "*" | "+"] ;
 type_expression_base = predefined_types | pattern_type | unique_id_type | enumeration | sequence_type | mapping_from_to | a_set_type |
-    graph_type | table_type | replica_type | range_type | decimal_type | alternation | entity_reference_type | 
+    graph_type | table_type | replica_type | range_type | decimal_type | alternation | entity_reference_type |
     aggregation | aggregate_use_case_type_expression | aliased_type_expression ;
 
 (* Predefined Types *)
@@ -181,28 +182,36 @@ on_message_clause = "on" message_ref ["from" [identifier ":"] message_origins] "
 message_origins = inlet_ref | processor_ref | user_ref | epic_ref ;
 
 (* Statements *)
-statement = send_statement | arbitrary_statement | error_statement | the_set_statement | tell_statement | call_statement |
-    stop_statement | if_then_else_statement | for_each_statement | code_statement | comment | reply_statement |
-    focus_statement | morph_statement | become_statement | return_statement | read_statement | write_statement ;
+(* Core statements available in all contexts *)
+statement = when_statement | match_statement | send_statement | tell_statement |
+    the_set_statement | let_statement | prompt_statement | code_statement |
+    error_statement | comment ;
 
+(* Entity-specific statements *)
+entity_statement = statement | morph_statement | become_statement ;
+
+(* Control flow *)
+when_statement = "when" literal_string "then" pseudo_code_block "end" ;
+match_statement = "match" literal_string "{" {match_case}+ ["default" "{" {statement} "}"] "}" ;
+match_case = "case" literal_string "{" {statement} "}" ;
+
+(* Message operations *)
 send_statement = "send" message_ref "to" (outlet_ref | inlet_ref) ;
-arbitrary_statement = literal_string ;
-error_statement = "error" literal_string ;
-the_set_statement = "set" field_ref "to" literal_string ;
 tell_statement = "tell" message_ref "to" processor_ref ;
-call_statement = "call" function_ref ;
-stop_statement = "stop" ;
-if_then_else_statement = "if" literal_string "then" pseudo_code_block ["else" pseudo_code_block "end"] ;
-for_each_statement = "foreach" (field_ref | inlet_ref | outlet_ref) "do" pseudo_code_block "end" ;
+
+(* Variable operations *)
+the_set_statement = "set" field_ref "to" literal_string ;
+let_statement = "let" identifier "=" literal_string ;
+
+(* General statements *)
+prompt_statement = "prompt" literal_string ;
 code_statement = "```" ("scala" | "java" | "python" | "mojo") code_contents "```" ;
 code_contents = {any_char_except_triple_backtick} ;
-reply_statement = "reply" ["with"] message_ref ;
-focus_statement = "focus" "on" group_ref ;
+error_statement = "error" literal_string ;
+
+(* Entity state transitions *)
 morph_statement = "morph" entity_ref "to" state_ref "with" message_ref ;
 become_statement = "become" entity_ref "to" handler_ref ;
-return_statement = "return" literal_string ;
-read_statement = ("read" | "get" | "query" | "find" | "select") literal_string "from" type_ref "where" literal_string ;
-write_statement = ("write" | "put" | "create" | "update" | "delete" | "remove" | "append" | "insert" | "modify") literal_string "to" type_ref ;
 
 (* Pseudo Code Block *)
 pseudo_code_block = "???" | {statement} | "{" {statement} "}" ;
@@ -290,7 +299,7 @@ interaction = parallel_interactions | optional_interactions | sequential_interac
 parallel_interactions = "parallel" "{" interactions "}" ;
 optional_interactions = "optional" "{" interactions "}" ;
 sequential_interactions = "sequence" "{" interactions "}" ;
-step_interactions = "step" (focus_on_group_step | direct_user_to_url | select_input_step | take_input_step | 
+step_interactions = "step" (focus_on_group_step | direct_user_to_url | select_input_step | take_input_step |
                             show_output_step | self_processing_step | send_message_step | arbitrary_step | vague_step) ;
 focus_on_group_step = "focus" user_ref "on" group_ref [with_metadata] ;
 direct_user_to_url = "direct" user_ref "to" http_url [with_metadata] ;
@@ -306,7 +315,7 @@ vague_step = "is" literal_string literal_string literal_string [with_metadata] ;
 user = "user" identifier "is" literal_string [with_metadata] ;
 
 (* Author-related *)
-author = "author" identifier "is" "{" [("???" | ("name" "is" literal_string "email" "is" literal_string 
+author = "author" identifier "is" "{" [("???" | ("name" "is" literal_string "email" "is" literal_string
         ["organization" "is" literal_string] ["title" "is" literal_string] ["url" "is" http_url]))] "}" [with_metadata] ;
 
 (* URLs *)
@@ -334,4 +343,4 @@ mime_type = ("application" | "audio" | "example" | "font" | "image" | "model" |
 mime_type_chars = lower_letter | "." | "-" | "*" ;
 ```
 
-This EBNF grammar provides a formal representation of the RIDDL language syntax. It's particularly useful for understanding the exact structure of each language element and how they relate to each other.
+This EBNF grammar provides a formal representation of the RIDDL language syntax. It's particularly useful for understanding the exact structure of each language element and how they relate to each other.

docs/riddl/references/language-reference.md

@@ -242,11 +242,9 @@ Commands should always result in one or more events being emitted. This follows
 ```
 handler ProductCommandHandler is {
   on command UpdatePrice is {
-    if "newPrice > 0" then {
+    when "newPrice > 0" then {
       morph entity Product to state ProductData with command UpdatePrice
       tell event PriceUpdated to entity Product  // Emitting an event is essential
-    } else {
-      error "Price must be greater than zero"
     } end
   }
 } with {
@@ -265,10 +263,11 @@ Handlers process commands and emit events:
 ```
 handler ProductCommandHandler is {
   on command UpdatePrice is {
-    if "newPrice > 0" then {
+    when "newPrice > 0" then {
       morph entity Product to state ProductData with command UpdatePrice
       tell event PriceUpdated to entity Product
-    } else {
+    } end
+    when "newPrice <= 0" then {
       error "Price must be greater than zero"
     } end
   }
@@ -297,45 +296,56 @@ tell command ProcessPayment to entity PaymentService
 ```
 
 ### Set Statement
-Assigns values:
+Assigns values to fields:
 ```
 set field status to "Active"
 ```
 
-### If Statement
-Conditional logic:
+### Let Statement
+Creates a local variable binding:
 ```
-if "condition" then {
-  // actions
-} else if "another condition" then {
-  // actions
-} else {
+let totalPrice = "subtotal + tax + shipping"
+```
+
+### When Statement
+Conditional logic (replaces the former `if` statement):
+```
+when "condition" then {
   // actions
 } end
 ```
 
-The `end` keyword is required to terminate if statements.
+The `end` keyword is required to terminate when statements. Note: there is no
+`else` clause - use multiple `when` statements for different conditions.
 
-### Foreach Statement
-Iteration:
+### Match Statement
+Pattern matching for multiple conditions:
 ```
-foreach field Cart.items do {
-  // actions for each item
-} end
+match "orderStatus" {
+  case "pending" {
+    tell event OrderPending to entity Order
+  }
+  case "shipped" {
+    tell event OrderShipped to entity Order
+  }
+  case "delivered" {
+    tell event OrderDelivered to entity Order
+  }
+  default {
+    error "Unknown order status"
+  }
+}
 ```
 
-The `end` keyword is required to terminate foreach loops.
-
-### Arbitrary Statement
-Allows for implementation code inside functions and handler actions:
+### Prompt Statement
+Describes an action in natural language for implementation:
 ```
-"var subtotal = 0;
- for (var i = 0; i < items.length; i++) {
-   subtotal += items[i].totalPrice;
- }
- return subtotal;"
+prompt "Calculate the total price including all applicable taxes and discounts"
 ```
 
+This is useful for describing complex business logic that will be implemented
+in target code.
+
 ## Functions
 
 Functions define reusable operations:
@@ -351,9 +361,9 @@ function calculateTotal is {
   returns {
     total is Price
   }
-  
-  // Implementation using arbitrary statement
-  "return subtotal + taxes + shipping - discount;"
+
+  // Implementation using prompt statement
+  prompt "Calculate total by adding subtotal, taxes, and shipping, then subtracting discount"
 } with {
   briefly as "Calculates the final cart total"
   described by {
@@ -414,12 +424,12 @@ repository CartRepository is {
   schema CartData is relational of
     cart as Cart
     link cartItems as field Cart.items.id to field Product.id
-    
+
   handler CartRepositoryHandler is {
     on event CartCreated is {
-      write "Create new cart record" to Cart
+      prompt "Persist the new cart record to the database"
     }
-    
+
     // Other event handlers
   } with {
     briefly as "Handles persistence of cart events"
@@ -562,9 +572,9 @@ entity Product is {
 1. **Include Metadata**: Add descriptions to all definitions with `with` clauses after their closing braces
 2. **Be Explicit**: Always specify reference types (entity, command, event, etc.)
 3. **Place Functions Close to Usage**: Define functions within the entities that use them
-4. **End Control Structures**: Always terminate control structures with `end` keyword
-5. **Use Field References**: In foreach loops, use `foreach field X.items`
-6. **Provide Default Actions**: Use `"nothing"` for empty else branches
+4. **End When Statements**: Always terminate `when` statements with the `end` keyword
+5. **Use Match for Multiple Conditions**: Prefer `match` over multiple `when` statements for readability
+6. **Use Prompt for Complex Logic**: Use `prompt` to describe business logic for implementation
 7. **Model Complete Flows**: Include UI components and user interactions
 8. **Maintain Semantic Consistency**: Use the same field names for the same concepts
 9. **Emit Events from Commands**: Ensure commands emit events to follow reactive principles
@@ -574,8 +584,8 @@ entity Product is {
 
 ## Common Syntax Issues
 
-1. Don't use assignment operators (`=`); use `set field x to "value"`
-2. Don't forget `end` after if statements and foreach loops
+1. Don't use assignment operators (`=`) for fields; use `set field x to "value"` (but `let x = "value"` is valid for local bindings)
+2. Don't forget `end` after `when` statements
 3. Always include reference types before identifiers
 4. Use proper syntax for function parameters and return values
 5. Make sure all morph/tell statements have correct type references
@@ -584,6 +594,8 @@ entity Product is {
 8. Never place entity, type, or repository definitions directly within a domain - they must be in a context
 9. Never place definitions inside an author - authors only contain metadata
 10. Make sure each context contains related definitions that form a bounded context
+11. Use `when` for conditionals (not `if` which is no longer supported)
+12. Use `prompt` for describing implementation logic (not bare quoted strings)
 
 ## Incomplete Definitions
 
@@ -650,8 +662,8 @@ From the formal grammar analysis, several important syntax points deserve specia
 3. **Nested Element Validation**: Elements can only be nested within specific parent elements according to strict containment rules. For example, types must be defined within contexts, not directly within domains.
 
 4. **Termination of Statements**: Control flow statements must be properly terminated:
-   - If statements must end with the `end` keyword
-   - Foreach loops must end with the `end` keyword
+   - `when` statements must end with the `end` keyword
+   - `match` statements are terminated by the closing brace
    - Other statements are implicitly terminated
 
 5. **Handler Clauses**: Handlers must use specific clause types:
@@ -663,3 +675,13 @@ From the formal grammar analysis, several important syntax points deserve specia
 
 6. **Readability Words**: While readability words like `is`, `as`, `by`, etc. are often optional, their proper placement significantly improves model clarity. Use them consistently.
 
+7. **New Statement Types** (as of January 2026):
+   - `when` replaces the former `if-then-else` statement
+   - `match` provides pattern matching for multiple conditions
+   - `let` creates local variable bindings
+   - `prompt` replaces bare quoted strings for describing implementation logic
+
+8. **Removed Statements**: The following statements have been removed from the language:
+   - `if`, `foreach`, `call`, `stop`, `focus`, `reply`, `return`, `read`, `write`
+   - Use `when` for conditionals, `match` for pattern matching, and `prompt` for implementation descriptions
+