regorus/.github/copilot-instructions.md

Regorus — Copilot Instructions

If these instructions conflict with the actual codebase, the code is the source of truth. Flag any discrepancy you notice.

Identity

Regorus is a multi-policy-language evaluation engine written in Rust. Its primary language is Rego (Open Policy Agent), with extensible support for additional policy languages via src/languages/. It is used in production at scale where correctness is security-critical — a bug in policy evaluation can mean allow when the answer should be deny.

Key properties:

• 9 language bindings: C, C (no_std), C++, C#, Go, Java, Python, Ruby, WASM (via bindings/ffi/)
• Core crate: #![no_std] + extern crate alloc; #![forbid(unsafe_code)] (default Cargo features include std — the crate is no_std-capable, not no_std-only)
• Two execution paths: tree-walking interpreter and RVM (bytecode VM)
• ~53 deny lints in src/lib.rs — restricts panics, unchecked indexing, and unchecked arithmetic (some modules like value.rs locally #![allow(...)] specific lints for performance)

Strategic direction (aspirational — not all implemented yet):

• RVM is the preferred execution path — new optimization work focuses there; interpreter remains fully supported and is the default today
• Error migration — anyhow → thiserror strongly typed errors (RVM leads)
• Formal verification — Miri (active CI), Z3 and Verus (planned)
• Multi-policy-language — extensible via src/languages/

Key Invariants

These are the most important rules that are not obvious from the code alone:

• Undefined ≠ false — Rego uses three-valued logic. Undefined propagates silently; forgetting this causes wrong allow/deny decisions.
• Panics in FFI = permanent poisoning — the engine uses with_unwind_guard() and a process-global poisoned flag. Any panic across FFI makes all engine instances in the process permanently unusable.
• Dual execution paths — interpreter (tree-walking) and RVM (bytecode VM) must produce identical results for all inputs. Both must be tested. (Exception: some language extensions like Azure RBAC are interpreter-only.)
• Resource limits — enforce_limit() must be called in accumulation loops to bound memory/CPU from adversarial policies.
• Error migration — new modules use thiserror enums; existing modules use anyhow. Don't mix within a module.
• Feature gating — new public modules need #[cfg(feature = "...")] gates. Verify builds with --all-features and --no-default-features.

Essential Coding Rules

No panics — ever (deny lints enforce this):

// Use typed errors for new code
let v = map.get("key").ok_or(MyError::MissingKey("key"))?;
// Or anyhow in existing modules
let v = map.get("key").ok_or_else(|| anyhow!("missing key"))?;

Prefer safe indexing — use .get() + ? or iterate where possible. clippy::indexing_slicing is denied crate-wide but locally allowed in some performance-critical modules (e.g., value.rs).

No unchecked arithmetic — use checked_add(), saturating_add(), etc.

no_std discipline (applies to src/ core crate) — use core:: and alloc:: by default. Only std:: behind #[cfg(feature = "std")].

Unsafe forbidden — #![forbid(unsafe_code)] in the core crate. Only FFI binding crates may use unsafe.

Error handling — new modules: thiserror enums (see src/rvm/vm/errors.rs). Existing modules: anyhow is acceptable for consistency within the module.

Feature gating — gate modules, registrations, and public API. Add docsrs annotation. Verify non-default combinations compile.

Build & Test

cargo xtask ci-debug          # Full debug CI suite
cargo xtask ci-release        # Full release CI suite (superset)
cargo xtask test-all-bindings # All 9 language binding smoke tests
cargo xtask test-no-std       # Verify no_std builds (thumbv7m-none-eabi)
cargo xtask fmt               # Format workspace + bindings
cargo xtask clippy            # Lint workspace + bindings
cargo test --test opa --features opa-testutil  # OPA conformance

Git hooks auto-installed by build.rs: pre-commit (build+format+clippy), pre-push (+ doc tests + no_std + OPA conformance).

Repository Layout

src/                    Core library (no_std, forbid(unsafe_code))
  rvm/                  Rego Virtual Machine ← strategic focus
  languages/            Policy language extensions
  builtins/             Builtin functions (~23 modules)
  value.rs              Value type (Null, Bool, Number, String, Array, Set, Object, Undefined)
  interpreter.rs        Tree-walking interpreter
  engine.rs             Engine API (public surface also includes lib.rs re-exports)
bindings/               9 language bindings + ffi layer (c/, c-nostd/, cpp/, csharp/, go/, java/, python/, ruby/, wasm/)
tests/                  Integration, conformance, domain-specific tests
docs/                   Grammar, builtins, RVM docs
xtask/                  Development automation CLI
benches/                Criterion benchmarks

Supply Chain Security

• dependency-audit.yml — cargo-audit + cargo-deny across all Cargo.lock files
• Dependabot — weekly updates for Cargo, Actions, Maven, NuGet, pip, bundler, Go
• New GitHub Actions references use pinned commit SHAs where possible
• cargo fetch --locked in CI for reproducible builds

When Making Changes

1. Consider all 9 binding targets — API changes affect every language
2. Both execution paths — features must work in interpreter AND RVM
3. Test Undefined propagation — Undefined ≠ false, test both paths
4. Run cargo xtask ci-debug before submitting
5. Update docs — docs/builtins.md, docs/rvm/ as needed