Upgrade RIDDL to 1.20.0 and document all language changes since 1.15.0

New statements: reply, require (with invariant refs), do (prompt alias).
Extended set (state refs) and let (type annotations). New options:
auto-id (entity), external (context). New aggregate use cases: graph,
table. Added validation notes throughout language reference and cheat
sheet covering the new CompletenessWarning system (1.19.0) and all
1.20.0 validation checks. Re-extracted EBNF grammar.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: reid-spencer

build.sbt

@@ -18,7 +18,7 @@ lazy val root = Root(
   devs = developers
 ).configure(
   With.Scala3.configure(version = Some("3.7.4")),
-  With.Riddl.library(version = "1.15.0", nonJVMDependency = false)
+  With.Riddl.library(version = "1.20.0", nonJVMDependency = false)
 ).settings(
   resolvers += "GitHub Package Registry" at "https://maven.pkg.github.com/ossuminc/riddl",
 

docs/riddl/references/cheat-sheet.md

@@ -34,6 +34,8 @@ the [Language Reference](language-reference.md).
 | Define a request, response, or notification | [Message](#message) |
 | React to incoming messages | [Handler](#handler) / [On Clause](#on-clause) |
 | Create a reusable computation | [Function](#function) |
+| Assert a precondition in a handler | [`require` statement](#concrete-statements) |
+| Reply to a query | [`reply` statement](#concrete-statements) |
 | Split a model across files | [Include](#include) |
 
 ---
@@ -148,7 +150,7 @@ Include.
 - Maps to a DDD Bounded Context
 - Context-level handlers act as the context's external API
 - Adding Groups makes the context an Application (UI model)
-- Options: `service`, `gateway`, `package`
+- Options: `service`, `gateway`, `package`, `external`
 
 > *[For more details →](../concepts/context.md)*
 
@@ -169,7 +171,8 @@ in the `with { }` metadata block, not in the body.)*
 
 - Entities have one or more named States, each backed by a record type
 - Supports `morph` (change state) and `become` (change handler)
-- Options: `event-sourced`, `aggregate`, `transient`, `available`
+- Options: `event-sourced`, `aggregate`, `transient`, `available`,
+  `auto-id` (auto-assign ULID at instantiation)
 - The primary unit of consistency in a reactive system
 
 > *[For more details →](../concepts/entity.md)*
@@ -309,6 +312,7 @@ messages, states, and parameters in RIDDL.
 - **Aggregation** (record): `type X is { field1: T1, field2: T2 }`
 - **Alternation** (union): `type X is one of { T1, T2, T3 }`
 - **Enumeration**: `type X is any of { A, B, C }`
+- **Aggregate use cases**: `graph`, `table`
 - **Collection**: `many T`, `set of T`, `mapping from K to V`, `T?`
 - **Simple predefined types** — use the name alone, no parameters:
   `Abstract`, `Nothing`, `Boolean`, `Current`, `Date`, `DateTime`,
@@ -448,7 +452,7 @@ type.
 |---|---|
 | `on command X` | A specific command message |
 | `on event X` | A specific event message |
-| `on query X` | A specific query message |
+| `on query X` | A specific query message (use `reply` to send result) |
 | `on init` | Processor initialization |
 | `on term` | Processor termination |
 | `on other` | Any unmatched message (catch-all) |
@@ -495,19 +499,27 @@ interactions between definitions, not full implementations.
 |---|---|---|
 | `send` | `send event X to outlet Y` | Route a message through an outlet or inlet (pub/sub, streaming). |
 | `tell` | `tell command X to entity Y` | Send a message directly to a specific processor (point-to-point). |
+| `reply` | `reply result ProductInfo` | Send a result back to a query sender without knowing their identity. Use in query handlers. |
 
 #### Data
 
 | Statement | Syntax | Description |
 |---|---|---|
-| `set` | `set field status to "Active"` | Assign a value to a state field. |
-| `let` | `let total = "price * qty"` | Create a local variable binding. |
+| `set` | `set field status to "Active"` | Assign a value to a state field. Also accepts a state ref: `set state X to "value"`. |
+| `let` | `let total = "price * qty"` | Create a local variable binding. Optional type annotation: `let total: Decimal = "price * qty"`. |
+
+#### Preconditions
+
+| Statement | Syntax | Description |
+|---|---|---|
+| `require` | `require "amount > 0"` | Assert a precondition as a literal string. |
+| `require` | `require invariant BalanceNonNegative` | Assert a precondition by referencing a named invariant. |
 
 #### Description / Implementation
 
 | Statement | Syntax | Description |
 |---|---|---|
-| `prompt` | `prompt "Calculate the total"` | Natural-language action description for implementation. |
+| `prompt` / `do` | `prompt "Calculate the total"` | Natural-language action description for implementation. `do` is an alias: `do "Calculate the total"`. |
 | `error` | `error "Invalid state"` | Produce a named error. |
 | `code` | `` ```scala ... ``` `` | Embed implementation code (scala, java, python, mojo). |
 
@@ -522,10 +534,10 @@ interactions between definitions, not full implementations.
 
 | Context | Available Statements |
 |---|---|
-| All handlers | when, match, send, tell, set, let, prompt, error, code |
+| All handlers | when, match, send, tell, reply, require, set, let, prompt/do, error, code |
 | Entity handlers | All above + morph, become |
-| Functions | when, match, set, let, prompt, error, code |
-| Saga steps | send, tell, prompt, error |
+| Functions | when, match, require, set, let, prompt/do, error, code |
+| Saga steps | send, tell, prompt/do, error |
 
 > *[For more details →](../concepts/statement.md)*
 
@@ -747,8 +759,8 @@ behavioral flags, or classification metadata.
 - `option is kind("core")` — classification
 - Boolean if no arguments: `option is event-sourced`
 - Entity options: `event-sourced`, `aggregate`, `transient`,
-  `available`
-- Context options: `service`, `gateway`, `package`
+  `available`, `auto-id`
+- Context options: `service`, `gateway`, `package`, `external`
 
 > *[For more details →](../concepts/option.md)*
 
@@ -823,6 +835,25 @@ cannot be expressed in Markdown descriptions.
 
 ---
 
+## Validation Severity Levels
+
+| Severity | Kind | Meaning |
+|:---:|---|---|
+| 0 | Info | Informational note |
+| 1 | StyleWarning | Naming/style convention issue |
+| 2 | MissingWarning | Missing optional content |
+| 3 | UsageWarning | Unused or unreferenced definition |
+| 4 | **CompletenessWarning** | Valid but incomplete for implementation |
+| 5 | Warning | Likely mistake or problematic pattern |
+| 6 | Error | Invalid — prevents compilation |
+| 7 | SevereError | Fatal — halts processing |
+
+Severity ≥ 4 is **actionable**. CompletenessWarnings (new in 1.19.0)
+flag models that validate but lack detail for code generation.
+Toggle with `-c` / `--show-completeness-warnings`.
+
+---
+
 ## Abstract / Meta Concepts
 
 These concepts appear in the documentation hierarchy but are not

docs/riddl/references/language-reference.md

@@ -114,6 +114,10 @@ RIDDL has a rich type system supporting both simple and complex data structures:
 - **Alternation**: `one of { TypeA, TypeB, TypeC }` - Union/sum types
 - **Enumeration**: `any of { Value1, Value2, Value3 }` - Enumerated values
 
+**Aggregate Use Cases:**
+- **Graph**: `graph` — models graph-structured data
+- **Table**: `table` — models tabular data
+
 **Collection Types:**
 - **Sequence**: `sequence of Type` or `many Type`
 - **Set**: `set of Type`
@@ -261,6 +265,24 @@ metadata and cannot contain other RIDDL definitions.
   items is many Item
   ```
 
+!!! warning "Type Validation"
+    **Errors:**
+
+    - Defining a type whose name exactly matches a predefined type name
+      (e.g., `type Currency is Decimal(10,2)`) — this shadows the built-in
+      type and is not allowed
+
+    **Style Warnings:**
+
+    - Defining a type whose name is a case-variant of a predefined type
+      (e.g., `type timestamp is TimeStamp`)
+
+    **Completeness Warnings:**
+
+    - Command types with no fields (excluding `???` placeholders)
+    - Event types not produced by any handler
+    - Query types without corresponding result types (and vice versa)
+
 ## Entities and States
 
 Entities are stateful objects with explicit states. Each state
@@ -320,6 +342,36 @@ type ProductRecord is {
 }
 ```
 
+!!! warning "Entity Validation"
+    The following conditions produce validation messages:
+
+    **Errors:**
+
+    - Defining a type whose name exactly matches a predefined type
+      (e.g., `type Currency is Decimal(10,2)`) — shadows the built-in
+
+    **Warnings:**
+
+    - Entity Id type defined inside entity body instead of containing
+      context (move it to the context level)
+    - Entity Id type defined at domain level or beyond (scope too broad)
+    - Entity Id type not defined at all
+
+    **Completeness Warnings:**
+
+    - States without an `on init` clause
+    - `on init` without a `set` statement
+    - Command handlers that don't `send` an event
+    - Query handlers that don't `reply` or `send` a result
+    - Entities without any `on query` clause
+    - Entities without an outlet streamlet for publishing events
+    - Entities with no handlers at all
+    - FSM entities (2+ states) without `morph` or `become` statements
+    - Empty handlers (no statements or only `???`)
+    - Handlers with only `prompt` statements (no `tell`, `send`,
+      `morph`, `set`, etc.)
+    - Empty `on other` clauses (silently discards messages)
+
 When an entity has multiple states with their own handlers,
 it models a finite state machine—each state responds to
 messages differently, and the `morph` statement transitions
@@ -442,7 +494,7 @@ handler ProductCommandHandler is {
   }
 
   on query GetProduct {
-    reply result ProductInfo with { product: @fields.data }
+    reply result ProductInfo
   }
 } with {
   briefly as "Processes commands for product management"
@@ -495,15 +547,17 @@ tell command ProcessPayment to entity PaymentService
 ```
 
 ### Set Statement
-Assigns values to fields:
+Assigns values to fields or transitions to a named state:
 ```
 set field status to "Active"
+set state ActiveOrder to "initial values"
 ```
 
 ### Let Statement
-Creates a local variable binding:
+Creates a local variable binding, with an optional type annotation:
 ```
 let totalPrice = "subtotal + tax + shipping"
+let discount: Decimal = "totalPrice * 0.1"
 ```
 
 ### When Statement
@@ -558,12 +612,46 @@ match "orderStatus" {
 }
 ```
 
-### Prompt Statement
+### Reply Statement
+Sends a result back in response to a query, without the handler
+needing to know the sender's identity:
+```
+reply result ProductInfo
+```
+
+Use `reply` in query handlers. It satisfies the completeness check
+that query handlers must send a result.
+
+!!! warning "Validation"
+    Query handlers that do not contain a `reply` or `send` of a result
+    will produce a **CompletenessWarning**.
+
+### Require Statement
+Asserts a precondition that must hold before proceeding:
+```
+require "amount > 0"
+```
+
+You can also reference a named invariant:
+```
+require invariant BalanceNonNegative
+```
+
+!!! warning "Validation"
+    Invariants defined in an entity but never referenced by any
+    `require invariant` statement produce a **UsageWarning**.
+
+### Prompt Statement (alias: `do`)
 Describes an action in natural language for implementation:
 ```
 prompt "Calculate the total price including all applicable taxes and discounts"
 ```
 
+The `do` keyword is an alias for `prompt`:
+```
+do "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.
 
@@ -636,6 +724,11 @@ saga CheckoutProcess is {
 }
 ```
 
+!!! warning "Saga Validation"
+    **Completeness Warnings:**
+
+    - Saga step do-statements must contain `tell command`
+
 ## Repositories
 
 Repositories define persistence:
@@ -763,6 +856,13 @@ context ReportingContext is {
 }
 ```
 
+!!! warning "Projector Validation"
+    **Completeness Warnings:**
+
+    - Projectors not referencing any repository
+    - Projector handlers not `tell`ing to a repository
+    - Declared repository references never used in `tell`
+
 ## Streamlets
 
 Streamlets process streaming data. They define components for building
@@ -822,6 +922,22 @@ context DataPipeline is {
 }
 ```
 
+!!! warning "Streamlet Validation"
+    **Completeness Warnings:**
+
+    - Isolated streamlets not connected to any connector
+    - Sources without a downstream path to a sink
+    - Sinks without an upstream path from a source
+    - Unattached inlets and outlets
+    - Flow/Split/Router handlers that don't send to outlets
+    - Source streamlets without `on init` or `on other`
+    - Streamlet handlers that receive but don't `tell` to entities
+
+!!! warning "Context Validation"
+    **Completeness Warnings:**
+
+    - Contexts with entities but no Sink streamlet for incoming messages
+
 ## Connectors
 
 Connectors link outlets to inlets, defining how data flows between streamlets
@@ -999,6 +1115,32 @@ entity Product is {
 }
 ```
 
+## Validation Message Severity
+
+RIDDL's validator produces messages at the following severity levels
+(from lowest to highest):
+
+| Severity | Kind | Description |
+|:---:|---|---|
+| 0 | Info | Informational notes |
+| 1 | StyleWarning | Naming and style conventions |
+| 2 | MissingWarning | Missing optional content |
+| 3 | UsageWarning | Unused definitions or unreferenced declarations |
+| 4 | **CompletenessWarning** | Model is valid but incomplete for implementation |
+| 5 | Warning | Likely mistakes or problematic patterns |
+| 6 | Error | Invalid constructs that prevent compilation |
+| 7 | SevereError | Fatal errors that halt processing |
+
+**CompletenessWarning** (severity 4) was introduced in RIDDL 1.19.0. These
+warnings identify models that parse and validate correctly but are missing
+details needed for a complete, implementable specification. They can be
+toggled with the `-c` / `--show-completeness-warnings` CLI flag (default:
+`true`).
+
+Messages at severity 4 (CompletenessWarning) and above are considered
+**actionable** — they should be addressed before considering a model ready
+for translation or code generation.
+
 ## Best Practices
 
 1. **Include Metadata**: Add descriptions to all definitions with `with` clauses after their closing braces
@@ -1114,6 +1256,7 @@ From the formal grammar analysis, several important syntax points deserve specia
    - `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`
+   - `if`, `foreach`, `call`, `stop`, `focus`, `return`, `read`, `write`
    - Use `when` for conditionals, `match` for pattern matching, and `prompt` for implementation descriptions
+   - Note: `reply` was restored in 1.20.0 with new semantics (see Statement Syntax)