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 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):

// 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

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