FFI and C# bindings for RVM host-await builtins

Expose registered host-await builtins, Program compilation, and RVM
accessors through the FFI layer and C# bindings.

FFI (bindings/ffi/src/rvm.rs):
- compile_from_modules with host-await builtin registration
- set/get host-await responses, argument, identifier
- RegorusHostAwaitBuiltin C struct

C# (bindings/csharp/Regorus/):
- Program.CompileFromModules overloads with HostAwaitBuiltin[]
- Rvm.SetHostAwaitResponses, GetHostAwaitArgument, GetHostAwaitIdentifier
- HostAwaitBuiltin readonly struct, ExecutionMode enum
- ModuleMarshalling: PinnedUtf8Strings, PinnedHostAwaitBuiltins

Rust (src/rvm/vm/machine.rs):
- get_host_await_argument() and get_host_await_identifier() accessors

Docs: README examples, API.md reference, vm-runtime.md accessors
Tests: suspendable + run-to-completion C# scenarios

Author: Mark Birger

bindings/csharp/API.md

@@ -343,6 +343,106 @@ var tasks = Enumerable.Range(0, 100).Select(i =>
 var results = await Task.WhenAll(tasks);
 ```
 
+## RVM Classes
+
+### Program
+
+`Program` represents a compiled RVM bytecode artifact. It can be created from
+modules+entrypoints or from an `Engine`, serialized to binary, and loaded into
+an `Rvm` for execution.
+
+```csharp
+public sealed class Program : IDisposable
+{
+    // Compile from modules with entry points
+    public static Program CompileFromModules(
+        string dataJson,
+        IReadOnlyList<PolicyModule> modules,
+        IReadOnlyList<string> entryPoints);
+
+    // Compile with registered host-await builtins
+    public static Program CompileFromModules(
+        string dataJson,
+        IReadOnlyList<PolicyModule> modules,
+        IReadOnlyList<string> entryPoints,
+        IReadOnlyList<HostAwaitBuiltin> hostAwaitBuiltins);
+
+    // Compile from an Engine instance
+    public static Program CompileFromEngine(Engine engine, IReadOnlyList<string> entryPoints);
+
+    // Serialize/deserialize
+    public byte[] SerializeBinary();
+    public static Program DeserializeBinary(byte[] data, out bool isPartial);
+
+    // Debug listing
+    public string GenerateListing();
+
+    public void Dispose();
+}
+```
+
+### Rvm
+
+`Rvm` is the virtual machine that executes a loaded `Program`.
+
+```csharp
+public sealed class Rvm : IDisposable
+{
+    // Load a compiled program
+    public void LoadProgram(Program program);
+
+    // Set data and input documents
+    public void SetDataJson(string dataJson);
+    public void SetInputJson(string inputJson);
+
+    // Configure execution
+    public void SetExecutionMode(ExecutionMode mode);
+
+    // Run
+    public string? Execute();
+    public string? ExecuteEntryPoint(string entryPoint);
+
+    // Suspendable-mode host-await interaction
+    public string? Resume(string valueJson);
+    public string? GetExecutionState();
+    public string? GetHostAwaitIdentifier();
+    public string? GetHostAwaitArgument();
+
+    // Run-to-completion-mode host-await pre-loading
+    public void SetHostAwaitResponses(string identifier, string[] valuesJson);
+
+    public void Dispose();
+}
+```
+
+### HostAwaitBuiltin
+
+Declares a function name that the compiler should treat as a host-await call.
+When the VM encounters a call to this function, it suspends (suspendable mode)
+or consumes a pre-loaded response (run-to-completion mode).
+
+```csharp
+public readonly struct HostAwaitBuiltin
+{
+    public string Name { get; }
+    public int ArgCount { get; }
+
+    public HostAwaitBuiltin(string name, int argCount);
+}
+```
+
+### ExecutionMode
+
+Controls how the VM handles host-await instructions.
+
+```csharp
+public enum ExecutionMode
+{
+    RunToCompletion = 0,
+    Suspendable = 1,
+}
+```
+
 ## Performance Considerations
 
 ### Compilation Overhead

bindings/csharp/README.md

@@ -105,6 +105,84 @@ var result = vm.Execute();
 Console.WriteLine($"allow: {result}");
 ```
 
+## RVM with Registered Host-Await Builtins
+
+Host-await builtins let you register custom function names at compile time.
+When the VM encounters a call to one of these functions, it suspends execution
+so the host can resolve the call externally and resume with a value.
+
+### Suspendable mode (resolve one call at a time)
+
+```csharp
+using Regorus;
+
+const string Policy = """
+package demo
+import rego.v1
+
+default allow := false
+
+allow if {
+  account := get_account({"id": input.account_id})
+  account.status == "active"
+}
+""";
+
+var modules = new[] { new PolicyModule("demo.rego", Policy) };
+var entryPoints = new[] { "data.demo.allow" };
+var builtins = new[] { new HostAwaitBuiltin("get_account", 1) };
+
+using var program = Program.CompileFromModules("{}", modules, entryPoints, builtins);
+using var vm = new Rvm();
+vm.SetExecutionMode(ExecutionMode.Suspendable);
+vm.LoadProgram(program);
+vm.SetInputJson("""{"account_id": "acct-42"}""");
+
+// First Execute suspends when get_account() is called
+vm.Execute();
+
+// Inspect which builtin suspended and what argument was passed
+var identifier = vm.GetHostAwaitIdentifier();  // "get_account"
+var argument = vm.GetHostAwaitArgument();       // {"id":"acct-42"}
+
+// Resolve externally, then resume
+var result = vm.Resume("""{"status": "active", "name": "Alice"}""");
+Console.WriteLine($"allow: {result}");  // true
+```
+
+### Run-to-completion mode (pre-load responses)
+
+```csharp
+using Regorus;
+
+const string Policy = """
+package demo
+import rego.v1
+
+default greeting := "unknown"
+
+greeting := msg if {
+  msg := translate(input.lang)
+}
+""";
+
+var modules = new[] { new PolicyModule("demo.rego", Policy) };
+var entryPoints = new[] { "data.demo.greeting" };
+var builtins = new[] { new HostAwaitBuiltin("translate", 1) };
+
+using var program = Program.CompileFromModules("{}", modules, entryPoints, builtins);
+using var vm = new Rvm();
+vm.SetExecutionMode(ExecutionMode.RunToCompletion);
+vm.LoadProgram(program);
+vm.SetInputJson("""{"lang": "es"}""");
+
+// Queue responses before execution
+vm.SetHostAwaitResponses("translate", new[] { "\"hola\"" });
+
+var result = vm.Execute();
+Console.WriteLine($"greeting: {result}");  // "hola"
+```
+
 ## Azure RBAC Condition Evaluation
 
 Evaluate Azure RBAC condition expressions directly with a JSON evaluation context:

bindings/csharp/Regorus.Tests/RvmProgramTests.cs

@@ -116,4 +116,78 @@ public void Program_host_await_suspend_and_resume_succeeds()
         var resumed = vm.Resume("{\"tier\":\"gold\"}");
         Assert.AreEqual("true", resumed, "expected allow=true after resume");
     }
+
+    private const string GetAccountPolicy = """
+package demo
+import rego.v1
+
+default allow := false
+
+allow if {
+  account := get_account({"id": input.account_id})
+  account.status == "active"
+}
+""";
+
+    [TestMethod]
+    public void RegisteredHostAwait_Suspendable_SuspendAndResume()
+    {
+        var modules = new[] { new PolicyModule("account.rego", GetAccountPolicy) };
+        var entryPoints = new[] { "data.demo.allow" };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("get_account", 1) };
+
+        using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
+        using var vm = new Rvm();
+        vm.SetExecutionMode(ExecutionMode.Suspendable);
+        vm.LoadProgram(program);
+        vm.SetInputJson("{\"account_id\": \"acct-42\"}");
+
+        // Execute — should suspend on get_account()
+        vm.Execute();
+
+        // Verify we're suspended due to HostAwait with identifier "get_account"
+        var identifier = vm.GetHostAwaitIdentifier();
+        Assert.AreEqual("\"get_account\"", identifier, "expected identifier to be get_account");
+
+        var argument = vm.GetHostAwaitArgument();
+        Assert.IsNotNull(argument, "expected non-null argument");
+        StringAssert.Contains(argument!, "acct-42", "expected account_id in argument");
+
+        // Resume with an account response
+        var result = vm.Resume("{\"status\": \"active\", \"name\": \"Alice\"}");
+        Assert.AreEqual("true", result, "expected allow=true after resume");
+    }
+
+    private const string TranslatePolicy = """
+package demo
+import rego.v1
+
+default greeting := "unknown"
+
+greeting := msg if {
+  msg := translate(input.lang)
+}
+""";
+
+    [TestMethod]
+    public void RegisteredHostAwait_RunToCompletion_WithPreloadedResponses()
+    {
+        var modules = new[] { new PolicyModule("translate.rego", TranslatePolicy) };
+        var entryPoints = new[] { "data.demo.greeting" };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("translate", 1) };
+
+        using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
+        using var vm = new Rvm();
+        vm.SetExecutionMode(ExecutionMode.RunToCompletion);
+        vm.LoadProgram(program);
+        vm.SetInputJson("{\"lang\": \"es\"}");
+
+        // Pre-load a response for translate
+        vm.SetHostAwaitResponses("translate", new[] { "\"hola\"" });
+
+        // Execute — translate returns "hola"
+        var result = vm.Execute();
+        Assert.AreEqual("\"hola\"", result, "expected greeting=hola");
+    }
+
 }

bindings/csharp/Regorus/Compiler.cs

@@ -36,6 +36,39 @@ public PolicyModule(string id, string content)
         }
     }
 
+    /// <summary>
+    /// Represents a host-awaitable builtin registration for RVM compilation.
+    /// When registered, calls to the named function compile to HostAwait instructions
+    /// rather than regular function calls.
+    /// </summary>
+    /// <remarks>
+    /// Host-await builtins are only supported via the <c>CompileFromModules</c> path.
+    /// The <c>CompileFromEngine</c> path does not support host-await registration.
+    /// </remarks>
+    public readonly struct HostAwaitBuiltin
+    {
+        /// <summary>
+        /// Gets the function name.
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// Gets the expected argument count.
+        /// </summary>
+        public int ArgCount { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the HostAwaitBuiltin struct.
+        /// </summary>
+        /// <param name="name">The function name to register as host-awaitable.</param>
+        /// <param name="argCount">The expected number of arguments.</param>
+        public HostAwaitBuiltin(string name, int argCount)
+        {
+            Name = name;
+            ArgCount = argCount;
+        }
+    }
+
     /// <summary>
     /// Provides static methods for compiling policies into efficient compiled representations.
     /// These are convenience methods that create an engine internally and perform compilation.