Add require statement to the RIDDL language

Adds require "condition" syntax as a precondition statement that
generates an error if the boolean expression is false. Updated
parser, EBNF grammar, AST, BAST serialization, validation, and
prettify support.

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

Author: reid-spencer

language/shared/src/main/resources/riddl/grammar/ebnf-grammar.ebnf

@@ -191,7 +191,7 @@ message_origins = inlet_ref | processor_ref | user_ref | epic_ref ;
 (* 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 | morph_statement | become_statement | comment ;
+    error_statement | require_statement | morph_statement | become_statement | comment ;
 
 (* Control flow *)
 when_statement = "when" literal_string "then" pseudo_code_block ["else" pseudo_code_block] "end" ;
@@ -203,14 +203,15 @@ send_statement = "send" message_ref "to" (outlet_ref | inlet_ref) ;
 tell_statement = "tell" message_ref "to" processor_ref ;
 
 (* Variable operations *)
-the_set_statement = "set" field_ref "to" literal_string ;
+the_set_statement = "set" (field_ref | state_ref) "to" literal_string ;
 let_statement = "let" identifier [":" type_ref] "=" literal_string ;
 
 (* General statements *)
 prompt_statement = ("prompt" | "do") literal_string ;
 code_statement = "```" ("scala" | "java" | "python" | "mojo") code_contents "```" ;
 code_contents = {any_char_except_triple_backtick} ;
 error_statement = "error" literal_string ;
+require_statement = "require" literal_string ;
 
 (* Entity state transitions *)
 morph_statement = "morph" entity_ref "to" state_ref "with" message_ref ;

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

@@ -2342,6 +2342,23 @@ object AST:
     def format: String = s"error ${message.format}"
   }
 
+  /** A statement that requires a boolean condition to be true for execution
+    * to continue. If the condition is false, an error is generated.
+    *
+    * @param loc
+    *   The location where the statement occurs in the source
+    * @param condition
+    *   The boolean expression (as a string) that must be true
+    */
+  @JSExportTopLevel("RequireStatement")
+  case class RequireStatement(
+    loc: At,
+    condition: LiteralString
+  ) extends Statement {
+    override def kind: String = "Require Statement"
+    def format: String = s"require ${condition.format}"
+  }
+
   /** A statement that sets a value of a field
     *
     * @param loc
@@ -2354,7 +2371,7 @@ object AST:
   @JSExportTopLevel("SetStatement")
   case class SetStatement(
     loc: At,
-    field: FieldRef,
+    field: FieldRef | StateRef,
     value: LiteralString
   ) extends Statement {
     override def kind: String = "Set Statement"

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

@@ -784,8 +784,10 @@ class BASTReader(bytes: Array[Byte])(using pc: PlatformContext) {
         val message = readLiteralString()
         ErrorStatement(loc, message)
 
-      case 3 => // Set
-        val field = readFieldRef()
+      case 3 => // Set (field ref or state ref)
+        val field: FieldRef | StateRef = reader.peekU8() match
+          case tag if tag == NODE_FIELD_REF => readFieldRef()
+          case tag if tag == NODE_STATE_REF => readStateRef()
         val value = readLiteralString()
         SetStatement(loc, field, value)
 
@@ -871,6 +873,10 @@ class BASTReader(bytes: Array[Byte])(using pc: PlatformContext) {
         val body = readString()
         CodeStatement(loc, language, body)
 
+      case 14 => // Require
+        val condition = readLiteralString()
+        RequireStatement(loc, condition)
+
       case _ =>
         PromptStatement(loc, LiteralString(loc, s"<unknown statement $stmtType>"))
     }

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

@@ -235,9 +235,10 @@ class BASTWriter(val writer: ByteBufferWriter, val stringTable: StringTable) {
       case input: Input => writeInput(input)
       case output: Output => writeOutput(output)
 
-      // Statements (10 declarative statements per riddlsim spec)
+      // Statements (11 declarative statements)
       case s: PromptStatement => writePromptStatement(s)
       case s: ErrorStatement => writeErrorStatement(s)
+      case s: RequireStatement => writeRequireStatement(s)
       case s: SetStatement => writeSetStatement(s)
       case s: SendStatement => writeSendStatement(s)
       case s: MorphStatement => writeMorphStatement(s)
@@ -864,11 +865,21 @@ class BASTWriter(val writer: ByteBufferWriter, val stringTable: StringTable) {
     writeLiteralString(s.message)
   }
 
+  def writeRequireStatement(s: RequireStatement): Unit = {
+    writer.writeU8(NODE_STATEMENT)
+    writer.writeU8(14) // Require statement
+    writeLocation(s.loc)
+    writeLiteralString(s.condition)
+  }
+
   def writeSetStatement(s: SetStatement): Unit = {
     writer.writeU8(NODE_STATEMENT)
     writer.writeU8(3) // Set statement
     writeLocation(s.loc)
-    writeFieldRef(s.field)
+    s.field match {
+      case fr: FieldRef => writeFieldRef(fr)
+      case sr: StateRef => writeStateRef(sr)
+    }
     writeLiteralString(s.value)
   }
 

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

@@ -58,7 +58,7 @@ package object bast {
     * with revision 0 (pre-check era) will be rejected with a
     * clear message.
     */
-  val FORMAT_REVISION: Short = 4
+  val FORMAT_REVISION: Short = 5
 
   /** Magic bytes for BAST file identification: "BAST" */
   val MAGIC_BYTES: Array[Byte] = Array('B'.toByte, 'A'.toByte, 'S'.toByte, 'T'.toByte)

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

@@ -258,6 +258,8 @@ object Keywords {
 
   def repository[u: P]: P[Unit] = keyword(Keyword.repository)
 
+  def require[u: P]: P[Unit] = keyword(Keyword.require_)
+
   def requires[u: P]: P[Unit] = keyword(Keyword.requires)
 
   def required[u: P]: P[Unit] = keyword(Keyword.required)
@@ -434,6 +436,7 @@ object Keywords {
           Keyword.replica,
           Keyword.reply,
           Keyword.repository,
+          Keyword.require_,
           Keyword.requires,
           Keyword.required,
           Keyword.record,
@@ -583,6 +586,7 @@ object Keyword {
   final val replica = "replica"
   final val reply = "reply"
   final val repository = "repository"
+  final val require_ = "require"
   final val requires = "requires"
   final val required = "required"
   final val record = "record"

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

@@ -30,10 +30,19 @@ private[parsing] trait StatementParser {
     )./.map { case (start, str, end) => ErrorStatement(at(start, end), str) }
   }
 
+  private def requireStatement[u: P]: P[RequireStatement] = {
+    P(
+      Index ~ Keywords.require ~ literalString ~/ Index
+    )./.map { case (start, str, end) => RequireStatement(at(start, end), str) }
+  }
+
   private def theSetStatement[u: P]: P[SetStatement] = {
     P(
-      Index ~ Keywords.set ~/ fieldRef ~ to ~/ literalString ~/ Index
-    )./.map { (start, ref, str, end) => SetStatement(at(start, end), ref, str) }
+      Index ~ Keywords.set ~/ (fieldRef|stateRef) ~ to ~/ literalString ~/ Index
+    )./.map {
+      case (start, ref: FieldRef, str, end) => SetStatement(at(start, end), ref, str)
+      case (start, ref: StateRef, str, end) => SetStatement(at(start,end), ref, str)  
+    }
   }
 
   private def sendStatement[u: P]: P[SendStatement] = {
@@ -121,11 +130,11 @@ private[parsing] trait StatementParser {
     }
   }
 
-  private def backTickElipsis[u: P]: P[Unit] = { P("```") }
+  private def backTickEllipsis[u: P]: P[Unit] = { P("```") }
 
   private def codeStatement[u: P]: P[CodeStatement] = {
     P(
-      Index ~ backTickElipsis ~ Index ~ StringIn("scala", "java", "python", "mojo").! ~ Index ~
+      Index ~ backTickEllipsis ~ Index ~ StringIn("scala", "java", "python", "mojo").! ~ Index ~
         until3('`', '`', '`') ~ Index
     ).map { case (at1, at2, lang, at3, contents, at4) =>
       CodeStatement(at(at1, at4), LiteralString(at(at2, at3), lang), contents)
@@ -142,8 +151,8 @@ private[parsing] trait StatementParser {
       theSetStatement | letStatement |
       // GROUP 4: General statements
       promptStatement | codeStatement |
-      // GROUP 5: Error handling
-      errorStatement | comment
+      // GROUP 5: Error handling and preconditions
+      errorStatement | requireStatement | comment
     ).asInstanceOf[P[Statements]]
   }
 

language/shared/src/test/scala/com/ossuminc/riddl/language/parsing/HandlerTest.scala

@@ -6,7 +6,8 @@
 
 package com.ossuminc.riddl.language.parsing
 
-import com.ossuminc.riddl.language.AST.{Context, Entity}
+import com.ossuminc.riddl.language.AST.{Context, Entity, RequireStatement}
+import com.ossuminc.riddl.language.Finder
 import com.ossuminc.riddl.language.parsing.AbstractParsingTest
 import com.ossuminc.riddl.utils.PlatformContext
 import org.scalatest.TestData
@@ -225,5 +226,44 @@ abstract class HandlerTest(using PlatformContext) extends AbstractParsingTest {
         case Right(_) => succeed
       }
     }
+    "accept require statements" in { (td: TestData) =>
+      val input = RiddlParserInput(
+        """entity Account is {
+          |  type AccountState is { balance: Number }
+          |  state Active of Account.AccountState
+          |  handler Transactions is {
+          |    on command Withdraw {
+          |      require "balance >= amount"
+          |      set field Account.balance to "balance - amount"
+          |    }
+          |    on command Transfer {
+          |      require "balance >= amount"
+          |      require "recipient != sender"
+          |      prompt "execute transfer"
+          |    }
+          |  }
+          |}
+          |""".stripMargin,
+        td
+      )
+      parseDefinition[Entity](input) match {
+        case Left(errors) =>
+          val msg = errors.map(_.format).mkString("\n")
+          fail(msg)
+        case Right((entity, _)) =>
+          val handler = entity.handlers.head
+          val clause = handler.clauses.head
+          val finder = Finder(clause.contents)
+          val requires = finder.findByType[RequireStatement]
+          requires.size must be(1)
+          requires.head.condition.s must be("balance >= amount")
+          // Second clause has two requires
+          val clause2 = handler.clauses(1)
+          val finder2 = Finder(clause2.contents)
+          val requires2 = finder2.findByType[RequireStatement]
+          requires2.size must be(2)
+          succeed
+      }
+    }
   }
 }

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

@@ -352,6 +352,8 @@ case class RiddlFileEmitter(url: URL)(using PlatformContext) extends FileBuilder
         addLine(s"tell ${msg.format} to ${to.format}")
       case CodeStatement(_, lang, body) =>
         addIndent(s"```${lang.s}").add(body).nl.addIndent("```")
+      case RequireStatement(_, condition) =>
+        addLine(s"require ${condition.format}")
       case statement: Statement => addLine(statement.format)
       case comment: Comment     => emitComment(comment)
     end match

passes/shared/src/main/scala/com/ossuminc/riddl/passes/resolve/ResolutionPass.scala

@@ -234,7 +234,9 @@ case class ResolutionPass(input: PassInput, outputs: PassesOutput)(using io: Pla
   private def resolveStatement(statement: Statement, parents: Parents): Unit = {
     statement match {
       case SetStatement(_, field, _) =>
-        associateUsage[Field](parents.head, resolveARef[Field](field, parents))
+        field match
+          case fr: FieldRef => associateUsage[Field](parents.head, resolveARef[Field](fr, parents))
+          case sr: StateRef => associateUsage[State](parents.head, resolveARef[State](sr, parents))
       case BecomeStatement(_, entity, handler) =>
         associateUsage[Entity](parents.head, resolveARef[Entity](entity, parents))
         associateUsage[Handler](parents.head, resolveARef[Handler](handler, parents))
@@ -248,8 +250,9 @@ case class ResolutionPass(input: PassInput, outputs: PassesOutput)(using io: Pla
       case TellStatement(_, msg, processorRef) =>
         associateUsage[Type](parents.head, resolveARef[Type](msg, parents))
         associateUsage(parents.head, resolveARef[Processor[?]](processorRef, parents))
-      case _: PromptStatement => () // no references
-      case _: ErrorStatement  => () // no references
+      case _: PromptStatement  => () // no references
+      case _: ErrorStatement   => () // no references
+      case _: RequireStatement => () // no references
       case _: WhenStatement   => () // no references (condition is a literal string)
       case _: MatchStatement  => () // no references (expression/patterns are literal strings)
       case ls: LetStatement =>