Add when/else/end syntax with identifier conditions

Extends WhenStatement to support:
- Identifier conditions (from let bindings) in addition to literal strings
- Negated identifiers using ! prefix (e.g., when !valid then)
- Optional else block for handling false conditions

Parser changes:
- Added 'else' to Punctuation.scala
- StatementParser now handles WhenCondition union type
- Supports when <cond> then <stmts> [else <stmts>] end

BAST serialization:
- BASTWriter/Reader updated for new WhenStatement structure
- Handles union type (LiteralString | Identifier) for condition
- Supports negation flag and optional elseStatements

Documentation:
- Updated conditional.md with comprehensive examples
- Removed Reply and Stop from statement.md (not valid RIDDL)

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

Author: reidspencer

doc/src/main/hugo/content/concepts/conditional.md

@@ -9,36 +9,79 @@ RIDDL provides two conditional constructs: `when` for simple conditions and
 
 ## When Statement
 
-The `when` statement executes a block of statements when a condition is true:
+The `when` statement executes a block of statements when a condition is true.
+Conditions can be literal strings or identifier references (from `let` bindings).
+An optional `else` block handles the false case:
 
 ```riddl
 handler MyHandler is {
   on command DoSomething {
     let authorized = "user has permission"
     when authorized then
       send event ActionCompleted to outlet Events
-    end
-    when !authorized then
+    else
       error "User not authorized"
     end
   }
 }
 ```
 
-### Using Let with When
+### Condition Types
+
+The `when` statement accepts three forms of conditions:
+
+1. **Literal string**: A quoted condition description
+   ```riddl
+   when "user is authenticated" then
+     // actions
+   end
+   ```
+
+2. **Identifier reference**: Reference a condition bound with `let`
+   ```riddl
+   let valid = "input passes validation"
+   when valid then
+     // actions
+   end
+   ```
+
+3. **Negated identifier**: Use `!` to negate an identifier
+   ```riddl
+   when !valid then
+     error "Validation failed"
+   end
+   ```
+
+### Using Else Blocks
+
+The `else` block is optional and executes when the condition is false:
+
+```riddl
+let condition = "some boolean expression"
+when condition then
+  // executed when true
+else
+  // executed when false
+end
+```
+
+### Alternative: Multiple When Statements
 
-The `let` statement binds a condition to a name for reuse:
+You can also use separate `when` statements with negation:
 
 ```riddl
 let condition = "some boolean expression"
 when condition then
   // executed when true
 end
 when !condition then
-  // executed when false (note the ! negation)
+  // executed when false
 end
 ```
 
+Both approaches are valid. Use `else` when the two blocks are closely related,
+and separate `when` statements when they represent distinct scenarios.
+
 ## Match Statement
 
 The `match` statement handles multiple cases with pattern matching:

doc/src/main/hugo/content/concepts/statement.md

@@ -18,13 +18,11 @@ kinds of statements, described in the table below.
 |    Match     | `match "scenario" { case "cond1" { } default { } }`          | Select from multiple conditions/cases                        |
 |    Morph     | `morph entity E to state S with record R`                    | Morph the state of an entity to a new state                  |
 |   Prompt     | `prompt "description of action"`                             | A textually described action to be implemented               |
-|    Reply     | `reply result R` or `reply record R`                         | Provide the reply to a query                                 |
 |    Return    | `return value`                                               | Return a value from a function                               |
 |    Send      | `send event E to outlet O`                                   | Send a message to an outlet (asynchronous)                   |
 |     Set      | `set field S.f to "value"`                                   | Set a field value                                            |
-|    Stop      | `stop`                                                       | Stop processing further statements                           |
 |    Tell      | `tell command C to entity E`                                 | Send a message to an entity directly                         |
-|    When      | `when condition then ... end`                                | Execute statements when a condition is true                  |
+|    When      | `when cond then ... [else ...] end`                          | Execute statements conditionally with optional else          |
 
 ## Level of Detail
 

language/shared/src/main/scala/com/ossuminc/riddl/language/AST.scala

@@ -2453,23 +2453,39 @@ object AST:
     def format: String = s"tell ${msg.format} to ${processorRef.format}"
   }
 
-  /** A guard clause statement for conditional early exit with validation
+  /** A conditional statement for branching logic
     *
     * @param loc
     *   The location of the statement in the model
     * @param condition
-    *   The boolean expression to evaluate (as a string, evaluated at runtime)
+    *   The boolean expression to evaluate - either a literal string description
+    *   or an identifier referencing a let binding
     * @param thenStatements
     *   The statements to execute if the condition is true
+    * @param elseStatements
+    *   The statements to execute if the condition is false (optional)
     */
   @JSExportTopLevel("WhenStatement")
   case class WhenStatement(
     loc: At,
-    condition: LiteralString,
-    thenStatements: Contents[Statements]
+    condition: LiteralString | Identifier,
+    thenStatements: Contents[Statements],
+    elseStatements: Contents[Statements] = Contents.empty[Statements](0),
+    negated: Boolean = false
   ) extends Statement {
     override def kind: String = "When Statement"
-    def format: String = s"when ${condition.format} then\n${thenStatements.toSeq.map(_.format).mkString("\n  ")}\n  end"
+    def format: String = {
+      val condStr = condition match {
+        case ls: LiteralString => ls.format
+        case id: Identifier    => if negated then s"!${id.format}" else id.format
+      }
+      val thenStr = if thenStatements.isEmpty then "" else thenStatements.toSeq.map(_.format).mkString("\n  ")
+      if elseStatements.isEmpty then s"when $condStr then\n$thenStr\n  end"
+      else {
+        val elseStr = if elseStatements.isEmpty then "" else elseStatements.toSeq.map(_.format).mkString("\n  ")
+        s"when $condStr then\n$thenStr\nelse\n$elseStr\n  end"
+      }
+    }
   }
 
   /** A case clause within a match statement */

language/shared/src/main/scala/com/ossuminc/riddl/language/Finder.scala

@@ -71,8 +71,9 @@ case class Finder[CV <: RiddlValue](root: Container[CV]) {
         child match
           case c: Container[?] =>
             c.contents.foldLeft(list) { case (next, child) => consider(next, child) }
-          case WhenStatement(_, _, thenStatements) =>
-            thenStatements.foldLeft(list) { case (next, child) => consider(next, child) }
+          case WhenStatement(_, _, thenStatements, elseStatements, _) =>
+            val r1 = thenStatements.foldLeft(list) { case (next, child) => consider(next, child) }
+            elseStatements.foldLeft(r1) { case (next, child) => consider(next, child) }
           case MatchStatement(_, _, cases, default) =>
             val r1 = cases.foldLeft(list) { case (next, mc) =>
               mc.statements.foldLeft(next) { case (next2, child) => consider(next2, child) }

language/shared/src/main/scala/com/ossuminc/riddl/language/bast/BASTReader.scala

@@ -718,9 +718,16 @@ class BASTReader(bytes: Array[Byte])(using pc: PlatformContext) {
         TellStatement(loc, msg, processorRef)
 
       case 10 => // When
-        val condition = readLiteralString()
+        val conditionType = reader.readU8()
+        val condition: LiteralString | Identifier = conditionType match {
+          case 0 => readLiteralString()
+          case 1 => readIdentifierInline()
+          case _ => throw new RuntimeException(s"Invalid when condition type: $conditionType")
+        }
+        val negated = reader.readU8() != 0
         val thenStatements = readContentsDeferred[Statements]()
-        WhenStatement(loc, condition, thenStatements)
+        val elseStatements = readContentsDeferred[Statements]()
+        WhenStatement(loc, condition, thenStatements, elseStatements, negated)
 
       case 11 => // Match
         val expression = readLiteralString()

language/shared/src/main/scala/com/ossuminc/riddl/language/bast/BASTWriter.scala

@@ -874,8 +874,18 @@ class BASTWriter(val writer: ByteBufferWriter, val stringTable: StringTable) {
     writer.writeU8(NODE_STATEMENT)
     writer.writeU8(10) // When statement
     writeLocation(s.loc)
-    writeLiteralString(s.condition)
-    // NOTE: thenStatements count/items are written by the Pass's traverse() override
+    // Write condition with type flag (0=LiteralString, 1=Identifier)
+    s.condition match {
+      case ls: LiteralString =>
+        writer.writeU8(0)
+        writeLiteralString(ls)
+      case id: Identifier =>
+        writer.writeU8(1)
+        writeIdentifierInline(id)
+    }
+    // Write negated flag (0=not negated, 1=negated)
+    writer.writeU8(if s.negated then 1 else 0)
+    // NOTE: thenStatements and elseStatements counts/items are written by the Pass's traverse() override
   }
 
   def writeMatchStatement(s: MatchStatement): Unit = {

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/Punctuation.scala

@@ -17,6 +17,7 @@ object Punctuation {
   final val curlyClose = "}"
   final val dot = "."
   final val equalsSign = "="
+  final val exclamation = "!"
   final val plus = "+"
   final val question = "?"
   final val quote = "\""

language/shared/src/main/scala/com/ossuminc/riddl/language/parsing/StatementParser.scala

@@ -71,11 +71,23 @@ private[parsing] trait StatementParser {
     )./.map { case (start, eRef, hRef, end) => BecomeStatement(at(start, end), eRef, hRef) }
   }
 
+  private def whenCondition[u: P]: P[(LiteralString | Identifier, Boolean)] = {
+    P(
+      literalString.map(ls => (ls, false)) |
+      (Punctuation.exclamation ~ identifier).map { case id => (id, true) } |
+      identifier.map(id => (id, false))
+    )
+  }
+
   private def whenStatement[u: P](set: StatementsSet): P[WhenStatement] = {
     P(
-      Index ~ Keywords.when ~/ literalString ~ Keywords.`then` ~/ pseudoCodeBlock(set) ~/ Keywords.end_ ~/ Index
-    )./.map { case (start, cond, statements, end) =>
-      WhenStatement(at(start, end), cond, statements.toContents)
+      Index ~ Keywords.when ~/ whenCondition ~ Keywords.`then` ~/
+        pseudoCodeBlock(set) ~/
+        (Keywords.else_ ~/ pseudoCodeBlock(set)).? ~/
+        Keywords.end_ ~/ Index
+    )./.map { case (start, (cond, negated), thenStmts, elseStmtsOpt, end) =>
+      val elseStmts = elseStmtsOpt.getOrElse(Seq.empty[Statements])
+      WhenStatement(at(start, end), cond, thenStmts.toContents, elseStmts.toContents, negated)
     }
   }
 

passes/shared/src/main/scala/com/ossuminc/riddl/passes/BASTWriterPass.scala

@@ -87,11 +87,13 @@ case class BASTWriterPass(input: PassInput, outputs: PassesOutput)(using pc: Pla
         // Phase 7: Only write metadata if non-empty (flag was set)
         if ss.metadata.nonEmpty then bastWriter.writeMetadataCount(ss.metadata)
 
-      // WhenStatement has a thenStatements Contents field that must be traversed
+      // WhenStatement has thenStatements and elseStatements Contents fields that must be traversed
       case ws: WhenStatement =>
         process(ws, parents)
         bastWriter.writeContents(ws.thenStatements)
         ws.thenStatements.toSeq.foreach { value => traverse(value, parents) }
+        bastWriter.writeContents(ws.elseStatements)
+        ws.elseStatements.toSeq.foreach { value => traverse(value, parents) }
         // WhenStatement is a Statement, no metadata
 
       // MatchStatement has cases and default Contents that must be traversed

passes/shared/src/main/scala/com/ossuminc/riddl/passes/prettify/RiddlFileEmitter.scala

@@ -297,9 +297,17 @@ case class RiddlFileEmitter(url: URL) extends FileBuilder {
 
   def emitStatement(statement: Statements): Unit =
     statement match
-      case WhenStatement(_, cond, thenStatements) =>
-        addIndent(s"when ${cond.format} then").nl.incr
+      case WhenStatement(_, cond, thenStatements, elseStatements, negated) =>
+        val condStr = cond match {
+          case ls: LiteralString => ls.format
+          case id: Identifier    => if negated then s"!${id.format}" else id.format
+        }
+        addIndent(s"when $condStr then").nl.incr
         if thenStatements.isEmpty then addLine("???") else thenStatements.toSeq.foreach(emitStatement)
+        if elseStatements.nonEmpty then
+          decr.addLine("else").incr
+          elseStatements.toSeq.foreach(emitStatement)
+        end if
         decr.addLine("end")
       case MatchStatement(_, expr, cases, default) =>
         addIndent(s"match ${expr.format} {").nl.incr