feat(rvm): extend program metadata and bump serialization to v6 (microsoft#654)

Add typed metadata support to RVM programs so that language frontends
can store language identity and arbitrary annotations alongside the
compiled bytecode.

Program metadata:
- Add `language` field to identify the source language (e.g. "rego",
  "azure_policy") so the VM can adjust semantics at runtime
- Add `annotations` map (BTreeMap<String, MetadataValue>) for
  frontend-specific key-value metadata
- Add MetadataValue enum with String, Bool, Integer, Float, Array,
  and Object variants, plus full serde support
- Add to_value() conversion for runtime access from VM instructions
- Add has_host_await flag with recompute_host_await_presence()

Serialization:
- Bump binary format version from 5 to 6
- Add JSON serialization for the new metadata fields

Assembly listing:
- Display language and annotations in the program header

Compiler:
- Track has_host_await during Rego compilation

Author: anakrish

src/languages/rego/compiler/core.rs

@@ -259,6 +259,9 @@ impl<'a> Compiler<'a> {
     }
 
     pub fn emit_instruction(&mut self, instruction: Instruction, span: &Span) {
+        if matches!(instruction, Instruction::HostAwait { .. }) {
+            self.program.has_host_await = true;
+        }
         self.program.instructions.push(instruction);
 
         let source_path = span.source.get_path().to_string();

src/languages/rego/compiler/mod.rs

@@ -23,8 +23,8 @@ pub use error::{CompilerError, Result, SpannedCompilerError};
 use crate::ast::ExprRef;
 use crate::lexer::Span;
 use crate::rvm::program::{Program, RuleType, SpanInfo};
-use crate::value::Value;
 use crate::CompiledPolicy;
+use crate::Value;
 use alloc::collections::{BTreeMap, BTreeSet};
 use alloc::string::String;
 use alloc::vec;

src/rvm/program/core.rs

@@ -8,7 +8,8 @@ use anyhow::Result as AnyResult;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
-use super::types::{BuiltinInfo, ProgramMetadata, RuleInfo, SourceFile, SpanInfo};
+use super::metadata::ProgramMetadata;
+use super::types::{BuiltinInfo, RuleInfo, SourceFile, SpanInfo};
 use crate::builtins::BuiltinFcn;
 use crate::rvm::instructions::InstructionData;
 use crate::rvm::Instruction;
@@ -70,6 +71,11 @@ pub struct Program {
     /// Flag indicating that VirtualDataDocumentLookup instruction was used and runtime recursion checking is needed
     pub needs_runtime_recursion_check: bool,
 
+    /// Flag indicating whether this program contains any HostAwait instruction.
+    /// Clients can use this to decide whether suspendable execution mode is required.
+    #[serde(default)]
+    pub has_host_await: bool,
+
     /// Flag indicating that recompilation is needed due to partial deserialization failure
     /// This is set to true when the artifact section was successfully read but the extensible
     /// section failed to deserialize (e.g., due to version incompatibility)
@@ -85,7 +91,7 @@ pub struct Program {
 
 impl Program {
     /// Current serialization format version
-    pub const SERIALIZATION_VERSION: u32 = 5;
+    pub const SERIALIZATION_VERSION: u32 = 6;
     /// Magic bytes to identify Regorus program files
     pub const MAGIC: [u8; 4] = *b"REGO";
     /// Maximum instructions supported (matches u16 jump targets)
@@ -122,10 +128,13 @@ impl Program {
                 compiled_at: "unknown".to_string(),
                 source_info: "unknown".to_string(),
                 optimization_level: 0,
+                language: String::new(),
+                annotations: alloc::collections::BTreeMap::new(),
             },
             rule_tree: Value::new_object(),
             resolved_builtins: Vec::new(),
             needs_runtime_recursion_check: false,
+            has_host_await: false,
             needs_recompilation: false,
             rego_v0: false, // Default to Rego v1
         }
@@ -330,10 +339,21 @@ impl Program {
 
     /// Add instruction with optional span
     pub fn add_instruction(&mut self, instruction: Instruction, span: Option<SpanInfo>) {
+        if matches!(instruction, Instruction::HostAwait { .. }) {
+            self.has_host_await = true;
+        }
         self.instructions.push(instruction);
         self.instruction_spans.push(span);
     }
 
+    /// Recompute whether HostAwait is present by scanning instructions.
+    pub fn recompute_host_await_presence(&mut self) {
+        self.has_host_await = self
+            .instructions
+            .iter()
+            .any(|instruction| matches!(instruction, Instruction::HostAwait { .. }));
+    }
+
     /// Add literal value and return its index
     pub fn add_literal(&mut self, value: Value) -> usize {
         for (i, existing) in self.literals.iter().enumerate() {
@@ -408,6 +428,11 @@ impl Program {
     pub const fn is_fully_functional(&self) -> bool {
         !self.needs_recompilation
     }
+
+    /// Check whether HostAwait instructions are present in this program.
+    pub const fn has_host_await(&self) -> bool {
+        self.has_host_await
+    }
 }
 
 impl Default for Program {

src/rvm/program/listing.rs

@@ -133,6 +133,19 @@ pub fn generate_assembly_listing(program: &Program, config: &AssemblyListingConf
                 program.metadata.optimization_level
             ),
         );
+        if !program.metadata.language.is_empty() {
+            push_line(
+                &mut output,
+                format_args!(";   language: {}", program.metadata.language),
+            );
+        }
+        if !program.metadata.annotations.is_empty() {
+            push_line(&mut output, format_args!(";   annotations:"));
+            for (key, value) in &program.metadata.annotations {
+                let json = serde_json::to_string(value).unwrap_or_else(|_| "<invalid>".to_string());
+                push_line(&mut output, format_args!(";     {}: {}", key, json));
+            }
+        }
     }
 
     push_line(&mut output, format_args!(";"));