feat: Add causality reporting and partial evaluation (based on anakrish/causality)

.github/workflows/codeql.yml

@@ -182,6 +182,8 @@ jobs:
         # Restore NuGet packages and build .NET assemblies in release mode
         dotnet restore Regorus/Regorus.csproj
         dotnet build Regorus/Regorus.csproj --no-restore /p:Configuration=Release /p:IgnoreMissingArtifacts=true
+        dotnet restore Regorus.Experimental/Regorus.Experimental.csproj
+        dotnet build Regorus.Experimental/Regorus.Experimental.csproj --no-restore /p:Configuration=Release /p:IgnoreMissingArtifacts=true
 
     - name: Build WASM bindings via xtask
       if: matrix.language == 'javascript-typescript'

.github/workflows/test-csharp.yml

@@ -29,14 +29,18 @@ jobs:
             libpath: |
               **/release/regorus_ffi.dll
               **/release/regorus_ffi.pdb
+              **/release/regorus_experimental_ffi.dll
+              **/release/regorus_experimental_ffi.pdb
           - os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
             libpath: |
               **/release/libregorus_ffi.so
+              **/release/libregorus_experimental_ffi.so
           - os: macos-latest
             target: aarch64-apple-darwin
             libpath: |
               **/release/libregorus_ffi.dylib
+              **/release/libregorus_experimental_ffi.dylib
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -57,6 +61,19 @@ jobs:
 
       - name: Build Regorus FFI via xtask
         run: cargo xtask build-ffi --release --target ${{ matrix.runtime.target }}
+
+      - name: Build experimental Regorus FFI via xtask
+        run: cargo xtask build-ffi --release --experimental --target ${{ matrix.runtime.target }}
+
+      - name: Verify standard and experimental Linux exports
+        if: matrix.runtime.target == 'x86_64-unknown-linux-gnu'
+        shell: bash
+        run: |
+          if nm -D bindings/ffi/target/${{ matrix.runtime.target }}/release/libregorus_ffi.so | grep -q regorus_rvm_take_causality_report; then
+            echo "Standard FFI unexpectedly exports explanation APIs."
+            exit 1
+          fi
+          nm -D bindings/ffi/target-experimental/${{ matrix.runtime.target }}/release/libregorus_experimental_ffi.so | grep -q regorus_rvm_take_causality_report
 
       - name: Upload regorus ffi shared library
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -104,6 +121,9 @@ jobs:
       - name: Build Regorus nuget via xtask
         run: cargo xtask build-csharp --release --clean --artifacts-dir ./bindings/csharp/Regorus/tmp/bindings/ffi/target --enforce-artifacts --repository-commit ${{ github.sha }} --include-symbols
 
+      - name: Build experimental Regorus nuget via xtask
+        run: cargo xtask build-csharp --release --clean --experimental --artifacts-dir ./bindings/csharp/Regorus/tmp/bindings/ffi/target-experimental --enforce-artifacts --repository-commit ${{ github.sha }} --include-symbols
+
       - name: Upload Regorus nuget
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -114,6 +134,16 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+      - name: Upload experimental Regorus nuget
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: regorus-experimental-nuget
+          path: |
+            bindings/csharp/Regorus.Experimental/bin/Release/Microsoft.Regorus.Experimental*.nupkg
+            bindings/csharp/Regorus.Experimental/bin/Release/Microsoft.Regorus.Experimental*.snupkg
+          if-no-files-found: error
+          retention-days: 1
+
   test-nuget:
     name: 'Test Regorus Nuget: (${{ matrix.runtime.target }})'
     needs: build-csharp
@@ -157,10 +187,35 @@ jobs:
           name: regorus-nuget
           path: ./bindings/csharp/Regorus/bin/Release
 
+      - name: Download experimental regorus nuget
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: regorus-experimental-nuget
+          path: ./bindings/csharp/Regorus/bin/Release
+
       - name: Display regorus nuget
         run: ls -R ./bindings/csharp/Regorus/bin/Release
 
       - name: Run C# tests via xtask
         run: cargo xtask test-csharp --release --clean --nuget-dir bindings/csharp/Regorus/bin/Release
 
+      - name: Run experimental C# tests from package
+        run: cargo xtask test-csharp --release --clean --experimental --nuget-dir bindings/csharp/Regorus/bin/Release --skip-apps
+
+      - name: Run standard and experimental package coexistence smoke test
+        shell: bash
+        run: |
+          rm -rf bindings/csharp/local-packages
+          mkdir -p bindings/csharp/local-packages
+          cp bindings/csharp/Regorus/bin/Release/*.nupkg bindings/csharp/local-packages/
+          dotnet restore bindings/csharp/ExperimentalCoexistenceApp/ExperimentalCoexistenceApp.csproj \
+            --configfile bindings/csharp/nuget.config \
+            -p:UsePackageReference=true \
+            -p:RestorePackagesPath=bindings/csharp/.nuget/packages
+          dotnet run --project bindings/csharp/ExperimentalCoexistenceApp/ExperimentalCoexistenceApp.csproj \
+            --no-restore \
+            --configuration Release \
+            -p:UsePackageReference=true \
+            -p:RestorePackagesPath=bindings/csharp/.nuget/packages
+
 

.github/workflows/test-wasm.yml

@@ -42,3 +42,6 @@ jobs:
 
       - name: Test wasm binding via xtask
         run: cargo xtask test-wasm --release --frozen --node node
+
+      - name: Test experimental wasm binding via xtask
+        run: cargo xtask test-wasm --release --frozen --experimental --node node

.gitignore

@@ -22,8 +22,11 @@ worktrees/
 # Generated C, C++ headers
 bindings/ffi/regorus.h
 bindings/ffi/regorus.ffi.hpp
+bindings/ffi/regorus.experimental.h
+bindings/ffi/regorus.experimental.ffi.hpp
 
 bindings/*/target
+bindings/*/target-experimental
 
 # Temporary commit message files
 .commit-msg.txt

Cargo.toml

@@ -47,6 +47,7 @@ opa-runtime = []
 regex = ["dep:regex"]
 cache = ["dep:lru"]
 rvm = ["dep:postcard", "dep:indexmap"]
+explanations = []
 semver = ["dep:semver"]
 allocator-memory-limits = ["std", "mimalloc", "mimalloc/allocator-memory-limits"]
 std = ["rand/std", "rand/std_rng", "serde_json/std", "indexmap?/std", "msvc_spectre_libs", "dep:parking_lot", "vstd/std" ]

bindings/csharp/Directory.Packages.props

@@ -3,11 +3,14 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
     <RegorusPackageVersion>0.13.0</RegorusPackageVersion>
     <RegorusPackageVersionSuffix Condition="'$(VersionSuffix)' != ''">-$(VersionSuffix)</RegorusPackageVersionSuffix>
+    <RegorusExperimentalVersion>$([System.IO.File]::ReadAllText('$(MSBuildThisFileDirectory)../experimental-version.txt').Trim())</RegorusExperimentalVersion>
+    <RegorusExperimentalPackageVersionSuffix>experimental.$(RegorusExperimentalVersion)$(RegorusPackageVersionSuffix)</RegorusExperimentalPackageVersionSuffix>
   </PropertyGroup>
 
   <ItemGroup>
     <!-- Centralize Regorus package version with optional CI suffix -->
     <PackageVersion Include="Microsoft.Regorus" Version="$(RegorusPackageVersion)$(RegorusPackageVersionSuffix)" />
+    <PackageVersion Include="Microsoft.Regorus.Experimental" Version="$(RegorusPackageVersion)-$(RegorusExperimentalPackageVersionSuffix)" />
     <PackageVersion Include="MSTest" Version="3.8.2" />
     <PackageVersion Include="System.Text.Json" Version="8.0.5" />
     <PackageVersion Include="YamlDotNet" Version="13.7.0" />

bindings/csharp/ExperimentalCoexistenceApp/ExperimentalCoexistenceApp.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <UsePackageReference Condition="'$(UsePackageReference)' == ''">false</UsePackageReference>
+  </PropertyGroup>
+
+  <ItemGroup Condition="'$(UsePackageReference)' != 'true'">
+    <ProjectReference Include="../Regorus/Regorus.csproj" />
+    <ProjectReference Include="../Regorus.Experimental/Regorus.Experimental.csproj" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(UsePackageReference)' == 'true'">
+    <PackageReference Include="Microsoft.Regorus" />
+    <PackageReference Include="Microsoft.Regorus.Experimental" />
+  </ItemGroup>
+</Project>

bindings/csharp/ExperimentalCoexistenceApp/Program.cs

@@ -0,0 +1,60 @@
+using ExperimentalEngine = Regorus.Experimental.Engine;
+using StandardEngine = Regorus.Engine;
+using System.Text.Json;
+
+const string policy = """
+package experimental
+import rego.v1
+
+allow if {
+    input.enabled == true
+}
+""";
+
+if (typeof(StandardEngine).GetMethod("SetExplanationSettings") is not null)
+{
+    throw new InvalidOperationException("Standard Regorus unexpectedly exposes explanation APIs.");
+}
+if (typeof(ExperimentalEngine).GetMethod("SetExplanationSettings") is null)
+{
+    throw new InvalidOperationException("Experimental Regorus does not expose explanation APIs.");
+}
+
+using (var standard = new StandardEngine())
+{
+    standard.AddPolicy("coexistence.rego", policy);
+    standard.SetInputJson("""{"enabled":true}""");
+    if (standard.EvalRule("data.experimental.allow") != "true")
+    {
+        throw new InvalidOperationException("Standard Regorus returned an unexpected result.");
+    }
+}
+
+using (var experimental = new ExperimentalEngine())
+{
+    experimental.AddPolicy("coexistence.rego", policy);
+    experimental.SetExplanationSettings(enabled: true);
+    experimental.SetInputJson("""{"enabled":true}""");
+    if (experimental.EvalRule("data.experimental.allow") != "true")
+    {
+        throw new InvalidOperationException("Experimental Regorus returned an unexpected result.");
+    }
+
+    var reportJson = experimental.TakeCausalityReport();
+    if (string.IsNullOrWhiteSpace(reportJson))
+    {
+        throw new InvalidOperationException("Experimental Regorus did not return a causality report.");
+    }
+    using var report = JsonDocument.Parse(reportJson);
+    if (!report.RootElement.TryGetProperty("query_result", out var queryResult) ||
+        queryResult.ValueKind != JsonValueKind.True)
+    {
+        throw new InvalidOperationException("Experimental Regorus report did not preserve the true query result.");
+    }
+    if (!report.RootElement.TryGetProperty("rules", out var rules) ||
+        rules.ValueKind != JsonValueKind.Array ||
+        rules.GetArrayLength() == 0)
+    {
+        throw new InvalidOperationException("Experimental Regorus report contained no evaluated rules.");
+    }
+}

bindings/csharp/README.md

@@ -35,6 +35,31 @@ The `cargo xtask` runner provides helpers for local builds:
 2. `cargo xtask nuget` reuses those artefacts to pack the C# library. It defaults to debug builds for the host but accepts `--target`, `--release`, `--artifacts-dir <path>` to reuse existing binaries, and `--enforce-artifacts` to require every officially supported platform.
 3. `cargo xtask test-csharp` ensures a NuGet is available (rebuilding when required or when `--force-nuget` is passed) and then runs `Regorus.Tests`, `TestApp`, and `TargetExampleApp` against it. The command accepts the same build flags as `cargo xtask nuget`.
 
+## Experimental explanations package
+
+Explanation and partial-evaluation APIs are distributed separately from the standard package:
+
+- `Microsoft.Regorus` loads `regorus_ffi` and does not expose explanation APIs.
+- `Microsoft.Regorus.Experimental` uses the `Regorus.Experimental` namespace, loads
+  `regorus_experimental_ffi`, and exposes the opt-in explanation APIs.
+
+The packages can coexist in one application. They load separate native runtimes, so process-global
+settings are also separate: configure memory limits, cache settings, and fallback execution timers
+through both namespaces when both runtimes are used. Exception types are distinct as well; code
+that handles both runtimes must catch the corresponding standard and experimental exceptions.
+
+Experimental package versions use the same base version as the standard package with an
+`-experimental.N` suffix. Experimental APIs and report formats may change before stabilization.
+
+Build the experimental native and managed artifacts with:
+
+```console
+cargo xtask build-ffi --release --experimental
+cargo xtask build-csharp --release --experimental
+```
+
+These commands create local artifacts only; publishing remains a separate release operation.
+
 ## Memory Usage Safeguards
 
 The C# bindings expose allocator-backed memory tracking utilities via the static `Regorus.MemoryLimits` helper. Typical usage:

bindings/csharp/Regorus.Experimental.Tests/Regorus.Experimental.Tests.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <Nullable>Enable</Nullable>
+    <TargetFramework>net8.0</TargetFramework>
+    <EnableMSTestRunner>true</EnableMSTestRunner>
+    <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
+    <TestingPlatformShowTestsFailure>true</TestingPlatformShowTestsFailure>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <UsePackageReference Condition="'$(UsePackageReference)' == ''">false</UsePackageReference>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="../Regorus.Tests/AssumptionTests.cs" Link="AssumptionTests.cs" />
+    <PackageReference Include="MSTest" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(UsePackageReference)' != 'true'">
+    <ProjectReference Include="../Regorus.Experimental/Regorus.Experimental.csproj" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(UsePackageReference)' == 'true'">
+    <PackageReference Include="Microsoft.Regorus.Experimental" />
+  </ItemGroup>
+</Project>

bindings/csharp/Regorus.Experimental/README.md

@@ -0,0 +1,14 @@
+# Microsoft.Regorus.Experimental
+
+`Microsoft.Regorus.Experimental` contains opt-in .NET bindings for Regorus explanations and partial
+evaluation. It can be referenced alongside the standard `Microsoft.Regorus` package.
+
+The package loads the separately named `regorus_experimental_ffi` native library. Its APIs and
+report formats are experimental and may change between prerelease versions.
+
+The standard and experimental packages load separate native runtimes. Memory limits, cache
+settings, fallback timers, and other global settings configured through `Microsoft.Regorus` do not
+apply to `Microsoft.Regorus.Experimental`; configure both when both packages are used. Their
+exception types are also distinct.
+
+Use the standard package when explanation or partial-evaluation APIs are not required.

bindings/csharp/Regorus.Experimental/Regorus.Experimental.csproj

@@ -0,0 +1,65 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Library</OutputType>
+        <PackageId>Microsoft.Regorus.Experimental</PackageId>
+        <AssemblyName>Regorus.Experimental</AssemblyName>
+        <RootNamespace>Regorus.Experimental</RootNamespace>
+        <TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
+        <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+        <LangVersion>10.0</LangVersion>
+        <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+        <DefineConstants>$(DefineConstants);REGORUS_EXPERIMENTAL</DefineConstants>
+        <PackageVersion>$(RegorusPackageVersion)-$(RegorusExperimentalPackageVersionSuffix)</PackageVersion>
+        <Version>$(RegorusPackageVersion)-$(RegorusExperimentalPackageVersionSuffix)</Version>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+        <PackageLicenseExpression>MIT AND Apache-2.0 AND BSD-3-Clause</PackageLicenseExpression>
+        <PackageProjectUrl>https://github.com/microsoft/regorus</PackageProjectUrl>
+        <RepositoryUrl>https://github.com/microsoft/regorus</RepositoryUrl>
+        <RepositoryType>git</RepositoryType>
+        <Authors>Microsoft</Authors>
+        <Company>Microsoft</Company>
+        <PackageTags>rego;policy;engine;authorization;opa;experimental</PackageTags>
+        <Description>Experimental Regorus APIs for explanations and partial evaluation. APIs and report formats may change before stabilization.</Description>
+        <Copyright>Copyright (c) Microsoft Corporation.</Copyright>
+    </PropertyGroup>
+
+    <PropertyGroup>
+        <RegorusFFIArtifactsProfile Condition="'$(RegorusFFIArtifactsProfile)' == ''">release</RegorusFFIArtifactsProfile>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <Compile Include="../Regorus/*.cs" Link="%(Filename)%(Extension)" />
+        <PackageReference Include="System.Text.Json" />
+    </ItemGroup>
+
+    <PropertyGroup Condition="'$(EnableRegorusTestHooks)' == 'true'">
+        <DefineConstants>$(DefineConstants);REGORUS_FFI_TEST_HOOKS</DefineConstants>
+    </PropertyGroup>
+
+    <Target Name="ChecksRegorusExperimentalFFIArtifactsDir" BeforeTargets="Pack" Condition="'$(IgnoreMissingArtifacts)' == ''">
+        <Error Text="RegorusFFIArtifactsDir must be supplied." Condition="'$(RegorusFFIArtifactsDir)' == ''" />
+        <Error Text="$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll missing."
+            Condition="!Exists('$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll')" />
+        <Error Text="$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb missing."
+            Condition="!Exists('$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb')" />
+        <Error Text="$(RegorusFFIArtifactsDir)/x86_64-unknown-linux-gnu/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.so missing."
+            Condition="!Exists('$(RegorusFFIArtifactsDir)/x86_64-unknown-linux-gnu/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.so')" />
+        <Error Text="$(RegorusFFIArtifactsDir)/aarch64-apple-darwin/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.dylib missing."
+            Condition="!Exists('$(RegorusFFIArtifactsDir)/aarch64-apple-darwin/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.dylib')" />
+    </Target>
+
+    <ItemGroup Condition="'$(RegorusFFIArtifactsDir)' != ''">
+        <None Include="$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll" Pack="true" PackagePath="runtimes/win-x64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll')" />
+        <None Include="$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb" Pack="true" PackagePath="runtimes/win-x64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/x86_64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb')" />
+        <None Include="$(RegorusFFIArtifactsDir)/aarch64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll" Pack="true" PackagePath="runtimes/win-arm64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/aarch64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.dll')" />
+        <None Include="$(RegorusFFIArtifactsDir)/aarch64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb" Pack="true" PackagePath="runtimes/win-arm64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/aarch64-pc-windows-msvc/$(RegorusFFIArtifactsProfile)/regorus_experimental_ffi.pdb')" />
+        <None Include="$(RegorusFFIArtifactsDir)/x86_64-unknown-linux-gnu/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.so" Pack="true" PackagePath="runtimes/linux-x64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/x86_64-unknown-linux-gnu/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.so')" />
+        <None Include="$(RegorusFFIArtifactsDir)/aarch64-apple-darwin/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.dylib" Pack="true" PackagePath="runtimes/osx-arm64/native/" Condition="Exists('$(RegorusFFIArtifactsDir)/aarch64-apple-darwin/$(RegorusFFIArtifactsProfile)/libregorus_experimental_ffi.dylib')" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <None Include="README.md" Pack="true" PackagePath="/" />
+        <None Include="../../../LICENSE" Pack="true" PackagePath="/" />
+    </ItemGroup>
+</Project>