Multi-line do and prompt, braced like doc_block

`do { "a" "b" "c" }` and `prompt({ "a" "b" })`, with the bare single-string form
unchanged. The shape is `doc_block`'s, which RIDDL already uses for prose, so this adds
no new spelling to the language -- and the bare form deliberately takes EXACTLY ONE
string rather than admitting juxtaposition, since `do "a" "b"` parses unambiguously
(nothing else starts with a quote) but leaves nothing except the next keyword to mark
where the statement ends.

`what` and `prompt` become Seq[LiteralString], with `text` deriving the \n-separated
prose riddlg reads. One representation, so there is no second field to disagree with
it, and a single-line `do` is a Seq of one rather than a special case.

Additive at every layer, which is the load-bearing property: a one-line `do` prettifies
byte-identically to before, and serializes to a bare JSON string rather than an array,
so none of the corpus's 190 models move for a feature they do not use. Several lines get
one per line inside braces -- the layout every other block uses. Squashing them onto one
line would have been the narrow second copy of a block dispatch that InvariantBlock was
already caught being.

All four reflectivity surfaces move together: parser, EBNF (a new literal_string_block
rule, verified by TatSu accepting the new fixture), prettify with a convergence test, and
BAST plus JSON with their own round-trip suites. FORMAT_REVISION 22 -> 23, because both
now write a SEQUENCE where they wrote a bare string, so a revision-22 file's string is
read as a COUNT and everything after it derails -- a misalignment rather than a clean
failure, which is the whole reason the gate exists. The JSON reader accepts either a
string or an array, so nothing already written stops loading.

Three suites pin the revision number so it cannot be silently reused; they reddened on
the bump exactly as intended and now read 23. NotImplemented.bast is regenerated per the
recipe in BACKLOG 0.3 -- from its own directory, 93 bytes, differing at byte 12 and
nowhere else.

Prettify cases were canary-tested: AbstractValidatingTest is a fixture spec, and a
`(td: TestData)` lambda on a plain spec constructs a Function1 without ever running the
body, so a green suite there proves nothing until you have watched it fail.

The 38 corpus round-trip failures are the inherited single-state morph cost, unchanged.

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

Author: reid-spencer

language/input/import/NotImplemented.bast

@@ -0,0 +1,24 @@
+domain MultilineDo is {
+  context Ordering is {
+    command PlaceOrder is { ??? }
+    entity Order is {
+      handler Orders is {
+        on command PlaceOrder is {
+          do "a single line stays exactly as it was"
+          do {
+            "first line of a longer instruction"
+            "second line, which a generator joins with a newline"
+            "third line"
+          }
+        }
+      }
+    }
+    function Score is {
+      requires { amount: Real }
+      returns { score: Real }
+      let one = prompt("a single-line hole")
+      let many = prompt({ "a hole whose prose" "runs to several lines" }) as Real
+      return many
+    }
+  }
+}

language/input/multiline-do.riddl

@@ -362,7 +362,7 @@ statement_start = ( "set" | "tell" | "send" | "forward" | "yield" | "reply" | "m
                   | "do" | "prompt" | "let" | "call" | "foreach" | "when" | "match" | "error"
                   | "require" | "put" | "return" | "terminate" | "code" | "focus" | "stop"
                   | "read" | "write" | "ask" | "initiate" | "if" | "else" ) ;
-prompt_value = "prompt" "(" literal_string ")" [ "as" type_expression ] ;
+prompt_value = "prompt" "(" literal_string_block ")" [ "as" type_expression ] ;
 (* Numeric literals - integers and reals, written directly. No digit separators and no radix     *)
 (* prefixes: declined deliberately, and pure additions later if wanted.                           *)
 (*                                                                                                 *)
@@ -468,7 +468,7 @@ return_statement = "return" value ;
 terminate_statement = "terminate" value [ "with" "(" [constructor_arg {"," constructor_arg}] ")" ] ;
 
 (* General statements. A54: `do` is canonical; the `prompt` statement is a deprecated synonym. *)
-prompt_statement = ("do" | "prompt") literal_string ;
+prompt_statement = ("do" | "prompt") literal_string_block ;
 code_statement = "```" ("scala" | "java" | "python" | "mojo") code_contents "```" ;
 code_contents = {any_char_except_triple_backtick} ;
 error_statement = "error" literal_string ;
@@ -662,5 +662,9 @@ doc_block = "{" {markdown_lines | literal_strings | undefined} "}" | literal_str
 markdown_lines = {markdown_line}+ ;
 markdown_line = "|" /[^\n]*\n?/ ;
 literal_strings = {literal_string}+ ;
+(* One string bare, or several inside braces -- the same shape doc_block uses for prose. The bare
+   form takes EXACTLY ONE string: admitting juxtaposition would leave nothing but the next keyword
+   to mark where the statement ends. *)
+literal_string_block = "{" literal_strings "}" | literal_string ;
 shown_by = "shown" "by" "{" {http_url} "}" ;
 mime_type = ("application" | "audio" | "example" | "font" | "image" | "model" | "text" | "video") "/" /[a-z.*-]*/ ;

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

@@ -186,6 +186,17 @@ object AST:
 
     /** Definition of the empty LiteralString */
     val empty: LiteralString = LiteralString(At.empty, "")
+
+    /** One string bare, several braced -- the shape `doc_block` already uses for prose.
+      *
+      * Single-line renders EXACTLY as it did before multi-line existed, which is what keeps the
+      * feature additive: no existing model's output moves. This is the ONE-LINE form, for messages
+      * and `.format`; the prettifier lays a multi-line block out one string per line, as it does
+      * for every other block, and owns that layout rather than deriving it from here.
+      */
+    def blockFormat(lines: Seq[LiteralString]): String =
+      if lines.sizeIs == 1 then lines.head.format
+      else lines.map(_.format).mkString("{ ", " ", " }")
   end LiteralString
 
   /** A RiddlValue that is a parsed identifier, typically the name of a definition.
@@ -3417,13 +3428,17 @@ object AST:
 
   case class PromptValue(
     loc: At,
-    prompt: LiteralString,
+    prompt: Seq[LiteralString],
     typeEx: Option[TypeExpression] = None
   ) extends RiddlValue:
     override def kind: String = "Prompt Value"
+
+    /** The prose as a generator wants it. See [[DoStatement.text]]. */
+    def text: String = prompt.map(_.s).mkString("\n")
+
     def format: String =
       val ascription = typeEx.map(t => s" as ${PromptValue.ascriptionFormat(t)}").getOrElse("")
-      s"prompt(${prompt.format})$ascription"
+      s"prompt(${LiteralString.blockFormat(prompt)})$ascription"
   end PromptValue
 
   object PromptValue:
@@ -3688,10 +3703,19 @@ object AST:
   @JSExportTopLevel("DoStatement")
   case class DoStatement(
     loc: At,
-    what: LiteralString
+    what: Seq[LiteralString]
   ) extends Statement {
     override def kind: String = "Do Statement"
-    def format: String = what.format
+
+    /** The prose as a generator wants it: the lines joined by newlines, without quotes.
+      *
+      * riddlg reads this. It is derived rather than stored, so there is no second representation to
+      * disagree with `what` -- the same reason a single-line `do` is a Seq of one instead of a
+      * special case.
+      */
+    def text: String = what.map(_.s).mkString("\n")
+
+    def format: String = LiteralString.blockFormat(what)
   }
 
   /** A statement that is intended to generate a runtime error in the application or otherwise

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

@@ -95,7 +95,7 @@ case class Finder[CV <: RiddlValue](root: Container[CV]) {
     // audit consistency (review round 1, fix 2). A LiteralString is a leaf so these add no
     // actual reachability, but a table claiming to be exhaustive should not have unexplained
     // gaps next to a sibling it does cover.
-    case ps: DoStatement  => Seq(ps.what)
+    case ps: DoStatement  => ps.what
     case es: ErrorStatement   => Seq(es.message)
     case cs: CodeStatement    => Seq(cs.language)
     case fe: ForeachStatement => fe.doStatements.toSeq
@@ -140,7 +140,7 @@ case class Finder[CV <: RiddlValue](root: Container[CV]) {
     // ascription's `TypeExpression` is surfaced here too (an `AliasedTypeExpression` — a NAMED
     // type ascription — recurses one further level into its `PathIdentifier`, so `prompt("…") as
     // SomeType` makes both the ascription node AND the path it names reachable).
-    case pv: PromptValue            => Seq(pv.prompt) ++ pv.typeEx.toSeq
+    case pv: PromptValue            => pv.prompt ++ pv.typeEx.toSeq
     case ate: AliasedTypeExpression => Seq(ate.pathId)
 
     case _ => Seq.empty

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

@@ -992,8 +992,11 @@ class BASTReader(
 
   private def readStatement(loc: At, stmtType: Int): Statement = {
     stmtType match {
-      case 0 => // Prompt
-        val what = readLiteralString()
+      case 0 => // Do (spelled `prompt` before 2.0)
+        // FORMAT_REVISION 23: a SEQUENCE. A revision-22 file wrote a bare string here, so an older
+        // file misaligns rather than failing cleanly -- which is exactly what the revision gate is
+        // for.
+        val what = readSeq(() => readLiteralString())
         DoStatement(loc, what)
 
       case 1 => // Error
@@ -2584,7 +2587,8 @@ class BASTReader(
         LiteralString(loc, s)
       case 4 => // PromptValue
         val loc = readLocation()
-        val what = readLiteralString()
+        // FORMAT_REVISION 23: a SEQUENCE, as for DoStatement.
+        val what = readSeq(() => readLiteralString())
         val typeEx = readOption(readTypeExpression()) // A20: optional `as <type>` ascription
         PromptValue(loc, what, typeEx)
       case 12 => // EmptyValue -- `empty` / `empty <type>` (FORMAT_REVISION 21)

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

@@ -1116,7 +1116,8 @@ class BASTWriter(val writer: ByteBufferWriter, val stringTable: StringTable) {
     writer.writeU8(NODE_STATEMENT)
     writer.writeU8(0) // Prompt statement type
     writeLocation(s.loc)
-    writeLiteralString(s.what)
+    // FORMAT_REVISION 23: a SEQUENCE of strings, where revision 22 wrote exactly one.
+    writeSeq(s.what)(writeLiteralString)
   }
 
   def writeErrorStatement(s: ErrorStatement): Unit = {
@@ -1434,7 +1435,8 @@ class BASTWriter(val writer: ByteBufferWriter, val stringTable: StringTable) {
       case pv: PromptValue =>
         writer.writeU8(4)
         writeLocation(pv.loc)
-        writeLiteralString(pv.prompt)
+        // FORMAT_REVISION 23: a SEQUENCE, as for DoStatement.
+        writeSeq(pv.prompt)(writeLiteralString)
         writeOption(pv.typeEx)(writeTypeExpression) // A20: optional `as <type>` ascription
       case c: Constructor =>
         writer.writeU8(1)

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

@@ -147,7 +147,11 @@ package object bast {
     // reader has no arm for sub-kind 21 at all, so it THROWS rather than misreading -- which is the
     // good failure, and the reason the reader's default arm was made to throw instead of
     // fabricating a DoStatement. Bumped rather than ridden because 18 SHIPPED in 2.0.0-rc.15.
-    22 // `system` value: tag 13 in readValue/writeValue. A revision-21 reader hitting tag 13 throws
+    // 23 makes `do` and `prompt(...)` hold a SEQUENCE of literal strings rather than one, so a
+    // revision-22 file's bare string is read as a COUNT and everything after it derails. Not a
+    // clean failure -- which is the whole reason this gate exists.
+    23 // multi-line `do` / `prompt`
+    // 22 was: `system` value: tag 13 in readValue/writeValue. A revision-21 reader hitting tag 13 throws
     // rather than misreading, which is what the revision gate is for.
     // 21 // `empty` value: tag 12 in readValue/writeValue. A revision-20 reader hitting tag 12 throws
     // rather than misreading, but the gate is what makes that a clean failure.

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

@@ -190,6 +190,17 @@ private[parsing] trait CommonParser(using pc: PlatformContext)
 
   def literalStrings[u: P]: P[Seq[LiteralString]] = { P(literalString.rep(1)) }
 
+  /** One string bare, or several inside braces -- the same shape `docBlock` uses for prose.
+    *
+    * The bare form takes EXACTLY ONE string, deliberately. Making it `literalStrings` would admit
+    * `do "a" "b"` by juxtaposition, and while that parses unambiguously (no statement begins with a
+    * quote), nothing would mark where the statement ends except the next keyword. The braces make
+    * the extent explicit, and this is the spelling RIDDL already uses for multi-line prose.
+    */
+  def literalStringBlock[u: P]: P[Seq[LiteralString]] = {
+    P((open ~ literalStrings ~ close) | literalString.map(Seq(_)))
+  }
+
   def markdownLines[u: P]: P[Seq[LiteralString]] = {
     P(markdownLine.rep(1))
   }

language/src/main/scala/com/ossuminc/riddl/language/parsing/CommonParser.scala

@@ -29,7 +29,7 @@ private[parsing] trait StatementParser {
 
   // `do "…"` is the canonical AI-action statement (A54). It builds a DoStatement.
   private def doStatement[u: P]: P[DoStatement] = {
-    P(Index ~ Keywords.do_ ~ literalString ~/ Index)./ map { case (start, str, end) =>
+    P(Index ~ Keywords.do_ ~ literalStringBlock ~/ Index)./ map { case (start, str, end) =>
       DoStatement(at(start, end), str)
     }
   }
@@ -38,7 +38,7 @@ private[parsing] trait StatementParser {
   // deprecation at the keyword (pattern mirrors replyStatement's `reply` -> `yield`). Note: the
   // parenthesized `prompt("…")` value form is handled by `promptValue`, not here.
   private def promptStatement[u: P]: P[DoStatement] = {
-    P(Index ~ Keywords.prompt ~ literalString ~/ Index)./ map { case (start, str, end) =>
+    P(Index ~ Keywords.prompt ~ literalStringBlock ~/ Index)./ map { case (start, str, end) =>
       val kwLoc = at(start, start + Keyword.prompt.length)
       deprecation(
         kwLoc,
@@ -541,7 +541,7 @@ private[parsing] trait StatementParser {
 
   private[parsing] def promptValue[u: P]: P[PromptValue] = {
     P(
-      Index ~ Keywords.prompt ~ Punctuation.roundOpen ~/ literalString ~
+      Index ~ Keywords.prompt ~ Punctuation.roundOpen ~/ literalStringBlock ~
         Punctuation.roundClose ~ (Keywords.keyword("as") ~/ typeExpression).? ~/ Index
     )./.map { case (start, str, typeEx, end) => PromptValue(at(start, end), str, typeEx) }
   }