# 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](https://www.openpolicyagent.org/docs/latest/policy-language/) (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 targets: Rust, C, C (no_std), C++, C#, Go, Java, Python, Ruby, WASM - `#![no_std]` by default (`extern crate alloc`), `#![forbid(unsafe_code)]` - Two execution paths: tree-walking interpreter and **RVM** (bytecode VM) - 80+ deny lints in `src/lib.rs` — no panics, no unchecked indexing, no unchecked arithmetic **Strategic direction:** - **RVM is the strategic execution path** — new optimization work focuses there - **Isolated / daemon execution** — long-lived process, clean resource lifecycle - **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/`, don't disclose specifics ## Deep Knowledge For complex subsystems, read the knowledge files in `docs/knowledge/` before making changes. These capture invariants, edge cases, and institutional knowledge that isn't obvious from the code alone: | File | Covers | |------|--------| | `value-semantics.md` | Value type, Undefined propagation, three-valued logic | | `rvm-architecture.md` | VM execution modes, frame stack, serialization, register pooling | | `builtin-system.md` | Builtin registration, feature gating, OPA conformance | | `ffi-boundary.md` | Safety across 9 bindings, handles, panic containment, poisoning | | `feature-composition.md` | Feature flag interactions, no_std boundary, testing matrix | | `error-handling-migration.md` | anyhow → thiserror migration strategy, VmError pattern | | `policy-evaluation-security.md` | DoS protection, resource limits, input validation | | `rego-semantics.md` | Evaluation model, undefined propagation, backtracking, `with` | | `interpreter-architecture.md` | Context stack, scope management, rule lifecycle | | `compilation-pipeline.md` | Scheduler, loop hoisting, destructuring planner | | `azure-policy-language.md` | Azure Policy evaluation model, effects, alias normalization | | `azure-rbac-language.md` | RBAC condition interpreter, ABAC builtins, context model | | `engine-api.md` | Public API surface, add_policy → compile → eval flow | | `time-builtins-compat.md` | Go time.Parse compatibility, timezone handling | | `language-extension-guide.md` | Adding new policy languages, LSP/tooling vision | | `tooling-architecture.md` | Language server, linter, analyzer design patterns | | `causality-and-partial-eval.md` | Causality tracking and partial evaluation design | | `rego-compiler.md` | Worklist algorithm, expression codegen, register allocation | | `azure-policy-aliases.md` | Alias registry, ARM normalization/denormalization pipeline | | `telemetry-and-diagnostics.md` | Error traceability, structured diagnostics, cloud-scale telemetry | Also see `docs/rvm/architecture.md`, `docs/rvm/instruction-set.md`, `docs/rvm/vm-runtime.md` for RVM internals. ## Essential Coding Rules **No panics — ever** (deny lints enforce this): ```rust // 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"))?; ``` **No unchecked indexing** — use `.get()` + `?` or iterate. **No unchecked arithmetic** — use `checked_add()`, `saturating_add()`, etc. **no_std discipline** — `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 ```bash 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 # OPA conformance (needs opa-testutil feature) ``` 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 (~19 modules) value.rs Value type (Null, Bool, Number, String, Array, Set, Object, Undefined) interpreter.rs Tree-walking interpreter (legacy path) engine.rs Public API bindings/ 9 language targets (ffi/, c/, cpp/, csharp/, go/, java/, python/, ruby/, wasm/) tests/ Integration, conformance, domain-specific tests docs/ Grammar, builtins, RVM docs, knowledge base 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, npm, bundler, Go - All GitHub Actions references use pinned commit SHAs, not mutable tags - `cargo fetch --locked` / `--frozen` in CI for reproducible builds ## When Making Changes 1. **Read relevant knowledge files** in `docs/knowledge/` first 2. **Consider all 9 binding targets** — API changes affect every language 3. **Both execution paths** — features must work in interpreter AND RVM 4. **Test Undefined propagation** — `Undefined ≠ false`, test both paths 5. **Run `cargo xtask ci-debug`** before submitting 6. **Update docs** — `docs/builtins.md`, `docs/rvm/`, knowledge files as needed