refine FFI/C# host-await bindings per review

- HostAwaitBuiltin: single-arg (name) ctor; arg_count fixed to 1
- SetHostAwaitResponses: multi-identifier dictionary API
- always route CompileFromModules through host-await FFI
- dead-check/IIFE cleanup, pub(crate), expanded tests + docs

Author: Mark Birger

bindings/csharp/API.md

@@ -408,8 +408,11 @@ public sealed class Rvm : IDisposable
     public string? GetHostAwaitIdentifier();
     public string? GetHostAwaitArgument();
 
-    // Run-to-completion-mode host-await pre-loading
-    public void SetHostAwaitResponses(string identifier, string[] valuesJson);
+    // Run-to-completion-mode host-await pre-loading. Atomically replaces all
+    // previously configured responses for every identifier; pass every
+    // identifier the policy may invoke in a single call.
+    public void SetHostAwaitResponses(
+        IReadOnlyDictionary<string, IReadOnlyList<string>> responsesByIdentifier);
 
     public void Dispose();
 }
@@ -421,13 +424,16 @@ 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).
 
+Registered builtins are restricted to exactly one argument at the compiler
+level (use object packing to pass multiple values), so the C# struct does not
+expose an `argCount` parameter.
+
 ```csharp
 public readonly struct HostAwaitBuiltin
 {
     public string Name { get; }
-    public int ArgCount { get; }
 
-    public HostAwaitBuiltin(string name, int argCount);
+    public HostAwaitBuiltin(string name);
 }
 ```
 

bindings/csharp/README.md

@@ -130,7 +130,7 @@ allow if {
 
 var modules = new[] { new PolicyModule("demo.rego", Policy) };
 var entryPoints = new[] { "data.demo.allow" };
-var builtins = new[] { new HostAwaitBuiltin("get_account", 1) };
+var builtins = new[] { new HostAwaitBuiltin("get_account") };
 
 using var program = Program.CompileFromModules("{}", modules, entryPoints, builtins);
 using var vm = new Rvm();
@@ -168,16 +168,21 @@ greeting := msg if {
 
 var modules = new[] { new PolicyModule("demo.rego", Policy) };
 var entryPoints = new[] { "data.demo.greeting" };
-var builtins = new[] { new HostAwaitBuiltin("translate", 1) };
+var builtins = new[] { new HostAwaitBuiltin("translate") };
 
 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\"" });
+// Queue responses before execution. SetHostAwaitResponses atomically replaces
+// ALL prior responses for every identifier — pass every identifier the policy
+// may invoke in a single call.
+vm.SetHostAwaitResponses(new Dictionary<string, IReadOnlyList<string>>
+{
+    ["translate"] = new[] { "\"hola\"" },
+});
 
 var result = vm.Execute();
 Console.WriteLine($"greeting: {result}");  // "hola"

bindings/csharp/Regorus.Tests/RvmProgramTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System;
+using System.Collections.Generic;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 namespace Regorus.Tests;
@@ -134,7 +135,7 @@ 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) };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("get_account") };
 
         using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
         using var vm = new Rvm();
@@ -145,7 +146,9 @@ public void RegisteredHostAwait_Suspendable_SuspendAndResume()
         // Execute — should suspend on get_account()
         vm.Execute();
 
-        // Verify we're suspended due to HostAwait with identifier "get_account"
+        // Verify we're suspended due to HostAwait with identifier "get_account".
+        // GetHostAwaitIdentifier returns the JSON-encoded Value, so the identifier
+        // string itself includes the surrounding JSON quotes.
         var identifier = vm.GetHostAwaitIdentifier();
         Assert.AreEqual("\"get_account\"", identifier, "expected identifier to be get_account");
 
@@ -174,7 +177,7 @@ 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) };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("translate") };
 
         using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
         using var vm = new Rvm();
@@ -183,11 +186,161 @@ public void RegisteredHostAwait_RunToCompletion_WithPreloadedResponses()
         vm.SetInputJson("{\"lang\": \"es\"}");
 
         // Pre-load a response for translate
-        vm.SetHostAwaitResponses("translate", new[] { "\"hola\"" });
+        vm.SetHostAwaitResponses(new Dictionary<string, IReadOnlyList<string>>
+        {
+            ["translate"] = new[] { "\"hola\"" },
+        });
 
         // Execute — translate returns "hola"
         var result = vm.Execute();
         Assert.AreEqual("\"hola\"", result, "expected greeting=hola");
     }
 
+    [TestMethod]
+    public void RegisteredHostAwait_CompileRejectsEmptyOrWhitespaceName()
+    {
+        var modules = new[] { new PolicyModule("noop.rego", "package demo\nallow := true\n") };
+        var entryPoints = new[] { "data.demo.allow" };
+
+        foreach (var badName in new[] { "", "   ", "\t" })
+        {
+            var builtins = new[] { new HostAwaitBuiltin(badName) };
+            Assert.ThrowsException<InvalidOperationException>(
+                () => Program.CompileFromModules("{}", modules, entryPoints, builtins),
+                $"expected compilation to reject empty/whitespace name '{badName}'");
+        }
+    }
+
+    [TestMethod]
+    public void RegisteredHostAwait_CompileRejectsDuplicateRegistration()
+    {
+        var modules = new[] { new PolicyModule("noop.rego", "package demo\nallow := true\n") };
+        var entryPoints = new[] { "data.demo.allow" };
+        var builtins = new[]
+        {
+            new HostAwaitBuiltin("translate"),
+            new HostAwaitBuiltin("translate"),
+        };
+
+        Assert.ThrowsException<InvalidOperationException>(
+            () => Program.CompileFromModules("{}", modules, entryPoints, builtins),
+            "expected compilation to reject duplicate registration");
+    }
+
+    [TestMethod]
+    public void RegisteredHostAwait_CompileRejectsReservedName()
+    {
+        var modules = new[] { new PolicyModule("noop.rego", "package demo\nallow := true\n") };
+        var entryPoints = new[] { "data.demo.allow" };
+        var builtins = new[] { new HostAwaitBuiltin("__builtin_host_await") };
+
+        Assert.ThrowsException<InvalidOperationException>(
+            () => Program.CompileFromModules("{}", modules, entryPoints, builtins),
+            "expected compilation to reject reserved __builtin_host_await identifier");
+    }
+
+    [TestMethod]
+    public void RegisteredHostAwait_GetAccessorsReturnNullWhenVmIsNotSuspended()
+    {
+        var modules = new[] { new PolicyModule("translate.rego", TranslatePolicy) };
+        var entryPoints = new[] { "data.demo.greeting" };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("translate") };
+
+        using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
+        using var vm = new Rvm();
+        vm.SetExecutionMode(ExecutionMode.RunToCompletion);
+        vm.LoadProgram(program);
+        vm.SetInputJson("{\"lang\": \"es\"}");
+        vm.SetHostAwaitResponses(new Dictionary<string, IReadOnlyList<string>>
+        {
+            ["translate"] = new[] { "\"hola\"" },
+        });
+        vm.Execute();
+
+        // After run-to-completion completes successfully, the VM is no longer suspended.
+        Assert.IsNull(vm.GetHostAwaitArgument(), "expected null argument when VM is not suspended");
+        Assert.IsNull(vm.GetHostAwaitIdentifier(), "expected null identifier when VM is not suspended");
+    }
+
+    private const string TranslateNoDefaultPolicy = """
+package demo
+import rego.v1
+
+# No default — if translate() can't produce a value, the entry point
+# evaluation propagates the error to the caller.
+result := translate(input.lang)
+""";
+
+    [TestMethod]
+    public void RegisteredHostAwait_RunToCompletion_FailsWhenResponseQueueExhausted()
+    {
+        var modules = new[] { new PolicyModule("translate.rego", TranslateNoDefaultPolicy) };
+        var entryPoints = new[] { "data.demo.result" };
+        var hostAwaitBuiltins = new[] { new HostAwaitBuiltin("translate") };
+
+        using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
+        using var vm = new Rvm();
+        vm.SetExecutionMode(ExecutionMode.RunToCompletion);
+        vm.LoadProgram(program);
+        vm.SetInputJson("{\"lang\": \"es\"}");
+
+        // No responses pre-loaded — translate has nothing to return.
+        // Document the actual behavior: in run-to-completion mode the
+        // missing-response error fails the rule body silently rather than
+        // surfacing as an exception, so Execute() returns the literal
+        // string `"<undefined>"` for an entry point that produced no value.
+        // Asserting the exact return value locks this contract so any
+        // future change (e.g. propagating an exception) shows up as a
+        // test failure that has to be explicitly re-acknowledged.
+        var actual = vm.Execute();
+        Assert.AreEqual(
+            "\"<undefined>\"",
+            actual,
+            "expected `\"<undefined>\"` when the response queue is exhausted");
+    }
+
+    private const string MultiAwaitPolicy = """
+package demo
+import rego.v1
+
+default greeting := "unknown"
+
+greeting := combined if {
+  hello := translate(input.lang)
+  user := lookup_user({"id": input.user_id})
+  combined := sprintf("%s %s", [hello, user.name])
+}
+""";
+
+    [TestMethod]
+    public void RegisteredHostAwait_RunToCompletion_MultipleIdentifiersInSingleCall()
+    {
+        var modules = new[] { new PolicyModule("multi.rego", MultiAwaitPolicy) };
+        var entryPoints = new[] { "data.demo.greeting" };
+        var hostAwaitBuiltins = new[]
+        {
+            new HostAwaitBuiltin("translate"),
+            new HostAwaitBuiltin("lookup_user"),
+        };
+
+        using var program = Program.CompileFromModules("{}", modules, entryPoints, hostAwaitBuiltins);
+        using var vm = new Rvm();
+        vm.SetExecutionMode(ExecutionMode.RunToCompletion);
+        vm.LoadProgram(program);
+        vm.SetInputJson("{\"lang\": \"es\", \"user_id\": \"u1\"}");
+
+        // Pre-load responses for BOTH identifiers in a single call.
+        // The new IReadOnlyDictionary API atomically replaces ALL prior
+        // responses, so this single call must carry every identifier the
+        // policy may invoke during this run.
+        vm.SetHostAwaitResponses(new Dictionary<string, IReadOnlyList<string>>
+        {
+            ["translate"] = new[] { "\"hola\"" },
+            ["lookup_user"] = new[] { "{\"name\": \"Alice\"}" },
+        });
+
+        var result = vm.Execute();
+        Assert.AreEqual("\"hola Alice\"", result, "expected combined greeting from both responses");
+    }
+
 }

bindings/csharp/Regorus/Compiler.cs

@@ -42,30 +42,28 @@ public PolicyModule(string id, string content)
     /// 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.
+    /// Registered builtins are restricted to exactly one argument at the compiler
+    /// level (use object packing to pass multiple values). The argument count is
+    /// therefore not exposed here.
+    ///
+    /// Host-await builtins are not yet supported via the <c>CompileFromEngine</c>
+    /// path; only <c>CompileFromModules</c> accepts them today.
     /// </remarks>
     public readonly struct HostAwaitBuiltin
     {
         /// <summary>
-        /// Gets the function name.
+        /// Gets the function name to register as host-awaitable.
         /// </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)
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> is null.</exception>
+        public HostAwaitBuiltin(string name)
         {
-            Name = name;
-            ArgCount = argCount;
+            Name = name ?? throw new ArgumentNullException(nameof(name));
         }
     }