ChilliCream.Regorus 1.0.0-p.7

ChilliCream.Regorus

ChilliCream.Regorus is a ChilliCream-maintained, unofficial .NET distribution of Microsoft Regorus. It packages the upstream C# API and native Rust policy engine from commit 839510df56abb32219f18d192e80cf6e2f07c5c6, plus a repository-owned high-performance UTF-8 interop path.

This package is not produced, endorsed, or supported by Microsoft. The NuGet package ID and public namespace are ChilliCream.Regorus, and the managed assembly is ChilliCream.Regorus.dll. The public type and member shapes come from the pinned upstream binding, with additional UTF-8 span overloads maintained here.

This repository distributes the Regorus engine only. It has no Hot Chocolate, Fusion, or GraphQL authorization semantics. Its only additional public surface is UTF-8 span overloads for the upstream API's scalar JSON, Rego, condition, rule, and registry-name inputs.

Install and evaluate a policy

By the end of this quick start, you will evaluate one allowed input and one denied input through the packaged native engine.

You need the .NET SDK and one of the supported runtime identifiers. Package consumers do not need Rust.

1. Create a console application and install the latest stable package:

   dotnet new console --framework net8.0 --name RegorusQuickstart
   cd RegorusQuickstart
   dotnet add package ChilliCream.Regorus
   

2. Replace Program.cs with this program:

   using ChilliCream.Regorus;
   
   const string policySource = """
       package example
       import rego.v1
   
       default allow := false
   
       allow if input.user == "admin"
       """;
   
   var modules = new[]
   {
       new PolicyModule("example.rego", policySource),
   };
   
   using var policy = Compiler.CompilePolicyWithEntrypoint(
       dataJson: "{}"u8,
       modules: modules,
       entryPointRule: "data.example.allow");
   
   var allowed = policy.EvalWithInput("""{"user":"admin"}"""u8);
   var denied = policy.EvalWithInput("""{"user":"guest"}"""u8);
   
   Console.WriteLine($"admin: {allowed}");
   Console.WriteLine($"guest: {denied}");
   

3. Run the application:

   dotnet run
   

   Expected output:

   admin: true
   guest: false
   

CompiledPolicy.EvalWithInput returns serialized JSON text. In this example, allowed and denied are the strings "true" and "false", not managed Boolean values. Other APIs can use different return types; for example, RbacEngine.EvaluateCondition returns bool.

The ReadOnlySpan<byte> overloads accept already encoded UTF-8 JSON. They pin the caller's span for the native call and pass its pointer and length to the repository-owned Rust shim. Rust validates the borrowed bytes and parses them directly as &str; it does not require a null terminator or create an intermediate input String. The original managed string overloads remain available for compatibility. Evaluation output is still returned as a managed JSON string.

The UTF-8 overloads cover these scalar text inputs:

Use ReadOnlySpan<byte>, not mutable Span<byte>, because native code only reads the caller-owned bytes and never retains their pointer after the call. Methods whose strings are filesystem paths remain string-based. PolicyModule and entry-point collections also retain their upstream string shapes: spans are stack-only ref structs and cannot be stored in ordinary managed collections. APIs that retain text, such as Engine.AddPolicy, still create an owned Rust value internally; their span overloads remove the managed UTF-16 and marshalling allocations but cannot eliminate the engine's required ownership.

CompilePolicyWithEntrypoint creates an immutable native policy snapshot. It does not emit .NET IL or Regorus VM bytecode: the snapshot contains Rust-owned parsed modules, resolved rules, schedules, functions, static data, and compilation metadata. Updating the Rego modules or dataJson requires compiling a new policy, routing new evaluations to it, and disposing the previous CompiledPolicy after its callers drain.

Supported runtimes

The package contains managed assemblies for exactly these target framework monikers (TFMs):

• lib/netstandard2.0/ChilliCream.Regorus.dll
• lib/netstandard2.1/ChilliCream.Regorus.dll

Native evaluation is supported only on these runtime identifiers (RIDs):

The windows-11-arm and ubuntu-24.04-arm CI images are GitHub-hosted public preview runners. Their availability and installed software can change while the preview evolves; their native-build and smoke jobs assert the host architecture before continuing.

Musl Linux and macOS x64 are not included in v1. A project targeting a compatible .NET TFM can compile on another runtime, but its first native Regorus call will fail because the package has no native asset for that RID.

Native MSVC regorus_ffi.pdb files are intentionally excluded from the NuGet packages because NuGet.org accepts only managed Portable PDBs in .snupkg files. The repository pack command requires a separate .snupkg containing only the managed Portable ChilliCream.Regorus.pdb for both target frameworks.

Work with the upstream API

The distribution preserves the public type and member shapes from Microsoft Regorus instead of wrapping them, relocates the managed API into the ChilliCream.Regorus namespace to avoid collisions, and adds the UTF-8 overloads listed above. The pinned C# binding documentation and pinned C# source describe the broader API, including the interpreter, compiled policies, RVM, Azure Policy, RBAC, registries, limits, and caches. Replace upstream examples' using Regorus; with using ChilliCream.Regorus;.

Keep these ownership and concurrency rules in mind:

• Engine is mutable and is not thread-safe. Configure one engine with policies and data, then call Clone() to create an engine per concurrent worker.
• CompiledPolicy supports concurrent evaluation. Compile once and reuse it when many callers evaluate the same policy and static data.
• Engine, CompiledPolicy, Program, Rvm, AliasRegistryBuilder, and AliasRegistry own native handles. Dispose them with using or using var.
• Process-wide registries, cache settings, and memory limits are shared mutable state. Configure them during startup and restore changed settings during test cleanup.

Regorus defaults to Rego v1. For a legacy Rego v0 policy, migrate its syntax or call Engine.SetRegoV0(true) before loading it.

Regorus is not a complete implementation of every Open Policy Agent builtin. Review the conformance notes for the pinned engine, and test policies that depend on specialized builtins. Cryptographic builtins are unsupported by design in this upstream release.

Troubleshooting

DllNotFoundException: Unable to load shared library 'regorus_ffi'

Cause: the application is running on an unsupported OS/architecture, or the selected native package asset did not reach the application output.

Solution: inspect RuntimeInformation.RuntimeIdentifier, confirm it is win-x64, win-arm64, glibc linux-x64, glibc linux-arm64, or osx-arm64, and inspect the restored package's runtimes/<rid>/native/ directory. Restore and publish for that RID. Installing Rust does not repair a missing consumer asset.

A Rego v0 policy fails to parse

Cause: Regorus uses Rego v1 by default.

Solution: migrate the policy to Rego v1. If you must run a v0 policy, call engine.SetRegoV0(true) before AddPolicy or AddPolicyFromFile.

Concurrent evaluations race or return inconsistent state

Cause: multiple callers are mutating or evaluating the same Engine, which is not thread-safe.

Solution: load policy and data into one engine and create a clone per worker, or use a shared CompiledPolicy for concurrent evaluation. Continue to coordinate disposal with the callers that use each instance.

A builtin is unavailable

Cause: the pinned Regorus release does not implement every OPA builtin, and cryptographic builtins are excluded by design.

Solution: check the pinned OPA conformance section, validate the policy against this engine, and revise policies that depend on unsupported builtins.

Build and test the repository

Repository contributors need Git and the .NET SDK selected by global.json, currently .NET SDK 8.0.412 with latest-feature roll-forward. You need Rust 1.92.0 to build a native engine. Managed preparation, build, and repository contract tests do not compile Rust.

The repository owns an audited snapshot of the upstream C# binding under src/ChilliCream.Regorus/Upstream/, the additional managed interop code under src/ChilliCream.Regorus/Shim/, and the length-delimited Rust exports in src/native/chillicream_utf8.rs. It does not vendor the Regorus engine itself. Build commands clone the exact tag in eng/regorus-version.txt into the ignored artifacts/ directory, verify that the owned C# snapshot still matches that tag, and overlay the owned Rust module before compiling the native library.

How to prepare and test managed projects

From the repository root, run:

dotnet run --project scripts/Regorus.Build -- validate-pin
dotnet run --project scripts/Regorus.Build -- prepare-upstream
dotnet build ChilliCream.Regorus.sln -c Release
dotnet test ChilliCream.Regorus.sln -c Release --no-build

If this succeeds, the pin is exact, the repository-owned managed shim matches the audited upstream sources, the solution builds, and the repository contract tests pass.

The preparation commands print these checkpoints, followed by the normal .NET build and test summaries:

Validated upstream pin: 839510df56abb32219f18d192e80cf6e2f07c5c6
Validated repository-owned managed API shim: ChilliCream.Regorus (24 files at <checkout>/src/ChilliCream.Regorus/Upstream).
Applied repository-owned UTF-8 FFI shim: <checkout>/artifacts/upstream/regorus/bindings/ffi/src/chillicream_utf8.rs
Prepared Microsoft Regorus at 839510df56abb32219f18d192e80cf6e2f07c5c6.

How to build the native engine for your host

Run the command that matches the current native host. Cross-compilation is intentionally rejected.

The command stages the result below artifacts/native/<target>/release/ and prints the exact native-library path.

For example, the macOS command ends with:

Staged osx-arm64: <checkout>/artifacts/native/aarch64-apple-darwin/release/libregorus_ffi.dylib

How to pack and verify all RIDs

Packing requires native outputs for all five RIDs. Gather them without flattening their target directories so that artifacts/native/ has this shape:

artifacts/native/
├── x86_64-pc-windows-msvc/release/regorus_ffi.dll
├── aarch64-pc-windows-msvc/release/regorus_ffi.dll
├── x86_64-unknown-linux-gnu/release/libregorus_ffi.so
├── aarch64-unknown-linux-gnu/release/libregorus_ffi.so
└── aarch64-apple-darwin/release/libregorus_ffi.dylib

A native Windows build may stage regorus_ffi.pdb beside either DLL for CI diagnostics, but packaging intentionally excludes it. Do not stage other target directories or native libraries.

Create and inspect a local package version:

dotnet run --project scripts/Regorus.Build -- pack --version 0.0.0-local
dotnet run --project scripts/Regorus.Build -- verify-package --version 0.0.0-local

pack already invokes the verifier. The second command is useful after moving or downloading the package. Both commands require exactly one ChilliCream.Regorus.0.0.0-local.nupkg and one matching .snupkg in artifacts/packages/. Verification opens the archive and checks its internal ID and version, managed assemblies, exact RID directories and native files, symbols, license, and third-party notices.

Successful verification prints:

Verified package identity/layout: ChilliCream.Regorus 0.0.0-local
Main package: <checkout>/artifacts/packages/ChilliCream.Regorus.0.0.0-local.nupkg
Symbol package: <checkout>/artifacts/packages/ChilliCream.Regorus.0.0.0-local.snupkg

How to run the clean package-consumer smoke test

After packing, run the smoke test on a matching host:

dotnet run --project scripts/Regorus.Build -- smoke --version 0.0.0-local --rid osx-arm64

Replace osx-arm64 with win-x64, win-arm64, linux-x64, or linux-arm64 on those hosts. The command creates a fresh NuGet cache under artifacts/smoke/, maps ChilliCream.Regorus exclusively to the local package source, proves that the restored .nuspec and selected native library came from that cache, and runs a real allow/deny evaluation without an ambient native-library path.

The printed paths depend on the checkout. These result lines must appear:

restored package: ChilliCream.Regorus 0.0.0-local
allowed input: true
denied input: false

CI performs native builds and the clean consumer test on all five supported RIDs. A local run validates only the current host RID.

Contributor build failures

Cross-compilation is not supported.

Cause: build-native received a target that does not match the current operating system and architecture.

Solution: run each Windows or glibc Linux target on a host with its matching architecture, or run the macOS target on macOS arm64. The build utility rejects cross-compilation.

Missing native asset or Unsupported native target directories are staged

Cause: artifacts/native/ is incomplete, its target directories were flattened during transfer, or it contains an extra target.

Solution: restore the exact five-target tree shown in How to pack and verify all RIDs. Keep only the supported target directories and the optional Windows PDBs.

Update the upstream Regorus version

The pin is intentionally assertion-based. When you update it, treat changes to upstream source, packaging, licensing, and platform support as a compatibility review.

1. Change eng/regorus-version.txt to the new upstream commit, written as exactly 40 lowercase hexadecimal characters.

2. Update the matching commit/version assertions in scripts/Regorus.Build/Program.cs, the repository contract tests, package metadata or links, and THIRD-PARTY-NOTICES.

3. Delete any existing artifacts/upstream/regorus checkout so prepare-upstream fetches the new pin, then check out the new commit and run these commands from that exact checkout:

   cargo xtask --help
   cargo xtask build-ffi --help
   cargo xtask build-csharp --help
   cargo xtask test-csharp --help
   

   Confirm the canonical command names and flags instead of relying on documentation from another revision.

4. Re-audit the upstream composite license and notices, default native dependencies, C# public API, upstream Regorus namespace, ChilliCream.Regorus namespace adaptation and assembly identity, TFMs, managed dependencies, target triples, native filenames, package paths, symbol behavior, and C# workflow.

5. Refresh and commit the audited files under src/ChilliCream.Regorus/Upstream/, applying the namespace relocation and the explicit partial extension points used by the shim. Update the build utility's assertions and mappings when an audited upstream change requires it; prepare-upstream must reject any mismatch between the pin and the owned snapshot.

6. Review the managed span shim and native length-delimited exports against the new upstream ABI, then build, pack, inspect, and smoke-test the same package on all five supported RIDs. Update the commit-pinned links in this README after verification.

Commit the reviewed managed snapshot and repository-owned shim sources. Do not commit the upstream clone or generated native/package artifacts.

CI and releases

ci.yml runs for pull requests and branch pushes. It validates the upstream pin, builds each native library on a matching native runner, aggregates one 0.0.0-ci package, verifies its layout, and runs isolated package-consumer smoke tests on all five supported RIDs. CI never authenticates with NuGet.org and never publishes its package.

release.yml triggers only for pushed tags matching the broad 1* filter. Its first job applies this exact validation expression before checkout, native build, authentication, or publication:

^1\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-p\.(0|[1-9][0-9]*))?$

For an accepted tag, the tag text becomes the NuGet version without a prefix, normalization, or recalculation. The release graph is tag validation, native builds, aggregate pack, package verification, five-RID smoke tests, then NuGet login and publication. Every downstream job requires successful tag validation. The final job verifies the package again before authentication.

NuGet.org does not allow a published version to be overwritten. The workflow uses --skip-duplicate so an exact rerun is idempotent; it cannot replace different package contents under an existing version.

Configure NuGet.org Trusted Publishing

The release workflow uses OpenID Connect through NuGet/login@v1; it does not use a long-lived NuGet API-key secret.

1. In the GitHub repository, create the repository secret NUGET_USERNAME. Set it to the nuget.org account or user associated with the ChilliCream.Regorus package owner.

2. On nuget.org, create a Trusted Publishing policy with these exact values:

   Field	Value
   GitHub owner	ChilliCream
   Repository	ChilliCream.Regorus
   Workflow filename	release.yml
   Environment	Leave unset

3. Confirm the GitHub repository name, workflow filename, and nuget.org policy match exactly. The workflow declares no GitHub environment. If you add one later, add the same environment to the workflow and the nuget.org policy.

4. Do not create a repository secret named NUGET_API_KEY. NuGet/login@v1 returns a short-lived key as ${{ steps.login.outputs.NUGET_API_KEY }} after the package has passed verification and all smoke tests.

The publish job has contents: read and id-token: write. It invokes dotnet nuget push once for the verified .nupkg, with the matching .snupkg in the same directory so the .NET CLI discovers and pushes symbols automatically. It publishes to https://api.nuget.org/v3/index.json and verifies the output mentions the symbol package.

License, attribution, and support

ChilliCream-authored repository material is available under the MIT License. The package carries the upstream composite expression MIT AND Apache-2.0 AND BSD-3-Clause, the pinned Microsoft Regorus license as UPSTREAM-LICENSE, and the required notices in THIRD-PARTY-NOTICES.

Report distribution packaging, RID, or workflow problems in the ChilliCream.Regorus issue tracker. When reporting upstream engine behavior, include the packaged Regorus commit (839510df56abb32219f18d192e80cf6e2f07c5c6) and a minimal policy/input reproduction. Microsoft does not support this ChilliCream distribution.