Upgrade RIDDL to 1.15.0 and update State documentation

States are now branches that can contain handlers and comments,
enabling proper state machine modeling where each state defines
its own message-handling behavior.

Co-Authored-By: Claude Opus 4.6 <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.13.1", nonJVMDependency = false)
+  With.Riddl.library(version = "1.15.0", nonJVMDependency = false)
 ).settings(
   resolvers += "GitHub Package Registry" at "https://maven.pkg.github.com/ossuminc/riddl",
 

docs/riddl/concepts/handler.md

@@ -64,9 +64,23 @@ state accordingly. Projector handlers also respond to queries that read from
 the projected data.
 
 ## State Handler
-State handlers process messages while an entity is in that specific 
-state, presumably with the intent of updating that state by generating 
-events from commands.
+State handlers process messages while an entity is in that
+specific state. They are defined inside a state's body,
+enabling each state to respond to messages differently—the
+foundation for modeling state machines in RIDDL. When an
+entity transitions to a new state via a `morph` statement,
+the new state's handlers become active.
+
+```riddl
+state ActiveOrder of ActiveOrderData is {
+  handler ActiveOrderHandler is {
+    on command ShipOrder {
+      morph entity Order to state Order.ShippedOrder
+        with command ShipOrder
+    }
+  }
+}
+```
 
 ## Occurs In
 * [Adaptors](adaptor.md)

docs/riddl/concepts/state.md

@@ -3,22 +3,46 @@ title: "States"
 draft: false
 ---
 
-A State defines the state of an [entity](entity.md). It is 
-defined as a set of [fields](field.md) with a 
-[handler](handler.md) that defines 
-how messages cause changes to the value of those fields. 
+A State defines a named state of an [entity](entity.md). It
+references a [type](type.md) that defines the data structure
+for the state, and optionally contains
+[handlers](handler.md) that define how messages are processed
+while the entity is in that state.
 
-An [entity](entity.md) can have multiple state definitions with
-the implication that this entity would be considered a 
-[Finite State Machine](https://en.wikipedia.org/wiki/Finite-state_machine). 
-However, it would only be such if the entity used the 
-[finite state machine](entity.md#finite-state-machine) 
-[option](option.md).
+An [entity](entity.md) can have multiple state definitions.
+When an entity has multiple states with their own handlers,
+it naturally models a
+[Finite State Machine](https://en.wikipedia.org/wiki/Finite-state_machine)
+—each state responds to messages differently. Use the
+[finite state machine](entity.md#finite-state-machine)
+[option](option.md) to make this intent explicit.
 
+States are branches in the AST, meaning they can contain
+their own definitions. The `morph` statement transitions an
+entity from one state to another, changing which handlers
+are active.
+
+### Syntax
+
+```riddl
+state ActiveOrder of ActiveOrderData is {
+  handler ActiveOrderHandler is {
+    on command CancelOrder { ??? }
+    on command ShipOrder { ??? }
+  }
+}
+```
+
+The state body (with handlers) is optional—a state can also
+be defined simply as:
+
+```riddl
+state ActiveOrder of ActiveOrderData
+```
 
 ## Occurs In
 * [Entities](entity.md)
 
 ## Contains
-* [Fields](field.md)
-* [Handler](handler.md)
+* [Handlers](handler.md)
+* [Comments](comment.md)

docs/riddl/guides/authors/index.md

@@ -452,35 +452,45 @@ Entities can morph between states to model lifecycles:
 
 ```riddl
 entity Order is {
-  state Pending is {
+  record PendingData is { orderId is OrderId }
+  record PaidData is { orderId is OrderId, paidAt is TimeStamp }
+  record ShippedData is { orderId is OrderId, shippedAt is TimeStamp }
+  record CancelledData is { orderId is OrderId }
+
+  state Pending of PendingData is {
     handler PendingHandler is {
       on command ConfirmPayment {
         morph entity Order to state Paid
+          with command ConfirmPayment
         send event PaymentConfirmed to outlet Events
       }
       on command Cancel {
         morph entity Order to state Cancelled
+          with command Cancel
         send event OrderCancelled to outlet Events
       }
     }
   }
 
-  state Paid is {
+  state Paid of PaidData is {
     handler PaidHandler is {
       on command Ship {
         morph entity Order to state Shipped
+          with command Ship
         send event OrderShipped to outlet Events
       }
     }
   }
 
-  state Shipped is {
+  state Shipped of ShippedData is {
     // Final state - no transitions out
   }
 
-  state Cancelled is {
+  state Cancelled of CancelledData is {
     // Final state - no transitions out
   }
+} with {
+  option is finite state machine
 }
 ```
 

docs/riddl/references/language-reference.md

@@ -263,19 +263,27 @@ metadata and cannot contain other RIDDL definitions.
 
 ## Entities and States
 
-Entities are stateful objects with explicit states:
+Entities are stateful objects with explicit states. Each state
+references a type that defines its data structure, and can
+optionally contain handlers that define behavior while the
+entity is in that state:
 
 ```
 entity Product is {
-  state ProductData of ProductRecord with {
-    briefly as "Product state containing all product information"
-    described by {
-      | Contains the complete product information including identification,
-      | pricing, and inventory information.
+  state ProductData of ProductRecord is {
+    handler ProductHandler is {
+      on command UpdatePrice {
+        set field ProductRecord.price to "field price of
+          command UpdatePrice"
+        send event PriceUpdated to
+          outlet ProductEvents.Products
+      }
     }
+  } with {
+    briefly as "Product state with update handling"
   }
-  
-  // Commands, events, handlers
+
+  // Commands, events, types
 } with {
   briefly as "Represents a purchasable item"
   described by {
@@ -285,6 +293,16 @@ entity Product is {
 }
 ```
 
+States can also be defined without a body when handlers are
+defined at the entity level instead:
+
+```
+entity SimpleProduct is {
+  state ProductData of ProductRecord
+  handler ProductHandler is { ??? }
+}
+```
+
 States reference record types that define the data structure:
 
 ```
@@ -296,8 +314,47 @@ type ProductRecord is {
 } with {
   briefly as "Record type containing product data"
   described by {
-    | Defines the structure of product data including identification and pricing.
+    | Defines the structure of product data including
+    | identification and pricing.
+  }
+}
+```
+
+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
+between states:
+
+```
+entity Order is {
+  state PendingOrder of PendingOrderData is {
+    handler PendingHandler is {
+      on command ConfirmOrder {
+        morph entity Order to state Order.ActiveOrder
+          with command ConfirmOrder
+      }
+    }
   }
+  state ActiveOrder of ActiveOrderData is {
+    handler ActiveHandler is {
+      on command ShipOrder {
+        morph entity Order to state Order.ShippedOrder
+          with command ShipOrder
+      }
+      on command CancelOrder {
+        morph entity Order to state Order.CancelledOrder
+          with command CancelOrder
+      }
+    }
+  }
+  state ShippedOrder of ShippedOrderData is {
+    handler ShippedHandler is { ??? }
+  }
+  state CancelledOrder of CancelledOrderData is {
+    handler CancelledHandler is { ??? }
+  }
+} with {
+  option is finite state machine
 }
 ```
 

docs/riddl/references/riddl-grammar.ebnf

@@ -64,7 +64,9 @@ entity = "entity" identifier is "{" entity_body "}" [with_metadata] ;
 entity_body = entity_definitions | "???" ;
 entity_definitions = {entity_content}+ ;
 entity_content = processor_definition_contents | state | entity_include ;
-state = "state" identifier ("of" | is) type_ref [with_metadata] ;
+state = "state" identifier ("of" | is) type_ref [state_body] [with_metadata] ;
+state_body = is "{" (state_content+ | "???") "}" ;
+state_content = handler | comment ;
 entity_include = "include" literal_string ;
 
 (* Processor Definition Contents *)