Add BAST import syntax parsing (Phase 4 foundation)

- Add BASTImport AST node with path, namespace, and contents fields
- Add BASTImport to RootContents type
- Add import syntax parser: `import "file.bast" as namespace`
- Add doBASTImport() stub in ParsingContext (loading happens later)
- Add NODE_BAST_IMPORT tag and serialization in BASTWriter/Reader
- Add BASTImport cases to ValidationPass, ResolutionPass, SymbolsPass
- Use readability 'as' (not keyword) to avoid conflict with 'described as'

Contents loading will be implemented in BASTLoadingPass.

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

Author: reidspencer

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

@@ -143,6 +143,7 @@ class BASTReader(bytes: Array[Byte])(using pc: PlatformContext) {
       case NODE_ENTITY => readEntityNode()
       case NODE_MODULE => readModuleNode()
       case NODE_INCLUDE => readIncludeNode()
+      case NODE_BAST_IMPORT => readBASTImportNode()
 
       // Types
       case NODE_TYPE => readTypeNode()
@@ -265,6 +266,15 @@ class BASTReader(bytes: Array[Byte])(using pc: PlatformContext) {
     Include[RiddlValue](loc, origin, contents)
   }
 
+  private def readBASTImportNode(): BASTImport = {
+    val loc = readLocation()
+    val path = readLiteralString()
+    val namespace = readIdentifier()
+    // Contents are not stored in BAST - they're loaded dynamically
+    // during BASTLoadingPass when this import is encountered
+    BASTImport(loc, path, namespace)
+  }
+
   // ========== Type Definitions ==========
 
   private def readTypeNode(): Type = {

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

@@ -70,6 +70,7 @@ case class BASTWriter(input: PassInput, outputs: PassesOutput)(using pc: Platfor
       case n: Nebula => writeNebula(n)
       case r: Root => writeRoot(r)
       case i: Include[?] => writeInclude(i)
+      case bi: BASTImport => writeBASTImport(bi)
 
       // Vital definitions
       case d: Domain => writeDomain(d)
@@ -449,6 +450,15 @@ case class BASTWriter(input: PassInput, outputs: PassesOutput)(using pc: Platfor
     writeContents(i.contents)
   }
 
+  private def writeBASTImport(bi: BASTImport): Unit = {
+    writer.writeU8(NODE_BAST_IMPORT)
+    writeLocation(bi.loc)
+    writeLiteralString(bi.path)
+    writeIdentifier(bi.namespace)
+    // Contents are not serialized - they're loaded dynamically
+    // during BASTLoadingPass when this import is encountered
+  }
+
   // ========== Definition Serialization ==========
 
   private def writeDomain(d: Domain): Unit = {

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

@@ -87,6 +87,7 @@ package object bast {
   val NODE_INCLUDE: Byte = 33
   val NODE_SAGA_STEP: Byte = 34
   val NODE_SCHEMA: Byte = 35
+  val NODE_BAST_IMPORT: Byte = 36
 
   // Metadata nodes
   val NODE_DESCRIPTION: Byte = 40

language/input/import/bast-import.riddl

@@ -0,0 +1,9 @@
+// Test file for BAST import syntax
+import "utils/common-types.bast" as utils
+import "models/shared-domain.bast" as shared
+
+domain MyApp is {
+  // This domain would use imported types like:
+  // type UserId is utils.UUID
+  briefly "Application domain using imported BAST modules"
+}

language/jvm-native/src/test/scala/com/ossuminc/riddl/language/parsing/ParserTest.scala

@@ -46,7 +46,7 @@ class ParserTest extends ParsingTest with org.scalatest.Inside {
         case Left(errors) =>
           errors must not be empty
           errors.head.message must include(
-            "Expected one of (\"/*\" | \"//\" | \"author\" | \"include\" | \"module\""
+            "Expected one of (\"/*\" | \"//\" | \"author\" | \"import\" | \"include\" | \"module\""
           )
         case Right(_) => fail("'domainfoois' should not be recognized")
       }

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

@@ -798,8 +798,8 @@ object AST:
   /** Type of definitions that can occur in a [[Module]] */
   type ModuleContents = OccursInModule | Include[OccursInModule]
 
-  /** The root is a module that can have other modules */
-  type RootContents = ModuleContents | Module
+  /** The root is a module that can have other modules and BAST imports */
+  type RootContents = ModuleContents | Module | BASTImport
 
   /** Things that can occur in the "With" section of a leaf definition */
   type MetaData =
@@ -1058,6 +1058,36 @@ object AST:
     override def toString: String = format
   end Include
 
+  /** A top-level import of a BAST (Binary AST) file with a namespace alias.
+    *
+    * Imports bring in pre-compiled definitions from .bast files at the top level of a RIDDL file.
+    * The imported definitions are accessible via the namespace prefix.
+    *
+    * Syntax: `import "path/to/file.bast" as namespace`
+    *
+    * @param loc
+    *   The location of the import statement in the source
+    * @param path
+    *   The path to the .bast file to import
+    * @param namespace
+    *   The namespace alias for accessing imported definitions
+    * @param contents
+    *   The loaded Nebula contents from the BAST file (populated during parsing)
+    */
+  case class BASTImport(
+    loc: At = At.empty,
+    path: LiteralString,
+    namespace: Identifier,
+    contents: Contents[NebulaContents] = Contents.empty[NebulaContents]()
+  ) extends Container[NebulaContents]:
+    type ContentType = NebulaContents
+
+    override def isRootContainer: Boolean = false
+
+    def format: String = s"""import "${path.s}" as ${namespace.value}"""
+    override def toString: String = format
+  end BASTImport
+
   /** Base trait of a reference to definitions that can accept a message directly via a reference
     *
     * @tparam T

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

@@ -88,6 +88,30 @@ trait ParsingContext(using pc: PlatformContext) extends ParsingErrors {
     // importDomain(url)
   }
 
+  /** Parse a BAST import statement.
+    *
+    * This creates a BASTImport node with the path and namespace. The actual BAST
+    * file loading happens later during a loading pass, avoiding circular dependencies
+    * between language and bast modules.
+    *
+    * @param loc The location of the import statement
+    * @param path The path to the .bast file
+    * @param namespace The namespace alias for accessing imported definitions
+    * @return A BASTImport node (contents populated later by BASTLoadingPass)
+    */
+  def doBASTImport(
+    loc: At,
+    path: LiteralString,
+    namespace: Identifier
+  )(implicit ctx: P[?]): BASTImport = {
+    // Validate the path ends with .bast
+    if !path.s.endsWith(".bast") then
+      warning(loc, s"Import path '${path.s}' should end with .bast extension")
+    end if
+    // Create the BASTImport node - actual loading happens in BASTLoadingPass
+    BASTImport(loc, path, namespace)
+  }
+
   def doIncludeParsing[CT <: RiddlValue](loc: At, path: String, rule: P[?] => P[Seq[CT]])(implicit
     ctx: P[?]
   ): Include[CT] = {

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

@@ -20,8 +20,16 @@ trait RootParser { this: ModuleParser & CommonParser & ParsingContext =>
     include[u, RootContents](rootContents(_))
   }
 
+  /** Parse a BAST import statement: `import "path/to/file.bast" as namespace` */
+  private def bastImport[u: P]: P[BASTImport] = {
+    P(Index ~ Keywords.import_ ~ literalString ~ as ~ identifier ~ Index).map {
+      case (start, path, namespace, end) =>
+        doBASTImport(at(start, end), path, namespace)
+    }
+  }
+
   private def rootContent[u: P]: P[RootContents] = {
-    P(moduleContent | module | rootInclude[u]).asInstanceOf[P[RootContents]]
+    P(bastImport | moduleContent | module | rootInclude[u]).asInstanceOf[P[RootContents]]
   }
 
   private def rootContents[u: P]: P[Seq[RootContents]] =

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

@@ -153,6 +153,7 @@ case class ResolutionPass(input: PassInput, outputs: PassesOutput)(using io: Pla
         }
       case cg: ContainedGroup =>
         associateUsage(cg, resolveARef[Group](cg.group, parents))
+      case _: BASTImport                 => () // BAST imports are resolved in BASTLoadingPass
       case _: NonReferencableDefinitions => () // These can't be referenced
       case _: NonDefinitionValues        => () // Neither can these values
       case _: Definition                 => () // abstract definition, can't be referenced

passes/shared/src/main/scala/com/ossuminc/riddl/passes/symbols/SymbolsPass.scala

@@ -55,6 +55,7 @@ case class SymbolsPass(input: PassInput, outputs: PassesOutput)(using pc: Platfo
   def process(definition: RiddlValue, parents: ParentStack): Unit = {
     definition match {
       case _: Root                          => // Root doesn't have a name
+      case _: BASTImport                    => // BAST imports don't go in symbol table
       case _: NonDefinitionValues           => // none of these can have names
       case nv: Definition if nv.isAnonymous => // Nameless things, like includes, aren't stored
       case nv: Definition if nv.id.isEmpty  => // Empty names are not stored