RVM compiler & runtime optimizations: caching, instruction fusion, constant hoisting, and correctness fixes (#626)

* perf!: add LRU caches for compiled regex and glob patterns

Add bounded LRU caches for compiled regex and glob patterns used by
Rego builtins, avoiding repeated recompilation of the same patterns
during policy evaluation.

New `cache` feature (included in `full-opa` and `opa-no-std`) backed by
the `lru` crate (no_std compatible) with `spin::Mutex` for thread safety.

- `src/cache.rs`: generic `LruCache<V>` wrapper, global `REGEX_CACHE`
  (default capacity 256) and `GLOB_CACHE` (default capacity 128)
- `src/builtins/regex.rs`: all regex builtins route through the cache
- `src/builtins/glob.rs`: glob.match routes through the cache
- Public API: `regorus::cache::{Config, configure, clear}`

Compilation costs avoided per cache hit:
  regex  10-55 µs  (simple to complex patterns)
  glob   10-12 µs
  LRU hit   ~10 ns

BREAKING CHANGE: new `cache` Cargo feature added to `full-opa` and
`opa-no-std` feature sets; adds `lru` as a dependency.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* perf(vm): amortize per-instruction memory and time limit checks

Deduplicate per-instruction memory_check calls by hoisting them to the
main dispatch loop, and amortize monotonic_now() syscalls in the
execution timer by checking elapsed time every N instructions instead
of on every tick.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* fix(vm): correct object membership to check values only, not keys

The Contains instruction for objects was checking both keys and values:

    object_fields.contains_key(v) || object_fields.values().any(|v| ...)

Per the Rego specification, `x in obj` tests whether x is a VALUE of
the object, not a key. The two-argument form `k, v in obj` is needed
to access keys. The interpreter already implemented this correctly
(values-only scan), but the RVM had the extra contains_key() check
which would incorrectly return true when the search value happened to
match a key name.

Remove the contains_key() branch so the behavior matches the interpreter
and the Rego spec. Add two regression tests:
- object_membership_checks_values_not_keys: "foo" in {"foo": "bar"}
  must be false (key, not a value)
- object_membership_finds_value: "bar" in {"foo": "bar"} must be true

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* perf(compiler): hoist all-constant collection literals to the literal table

When an array, set, or object literal consists entirely of compile-time
constant expressions (numbers, strings, bools, null, and nested constant
collections), the compiler now evaluates them at compile time and emits a
single Load instruction from the literal table instead of generating
per-element instructions at runtime.

Previously, a Rego expression like `x in [1, 2, 3]` would emit
ArrayCreate + three Load + three ArrayAppend instructions, allocating a
new Vec and Rc on every evaluation. With this change, the entire array
is built once during compilation and loaded as a single constant.

This optimization applies to all three collection types:
- Array literals: avoids ArrayCreate + N x (Load + ArrayAppend)
- Set literals: avoids SetCreate + N x (Load + SetAdd)
- Object literals: avoids ObjectCreate + N x (Load + Load + ObjectInsert)

The implementation adds a try_eval_const() helper that recursively
evaluates an AST expression as a constant Value, returning None if any
sub-expression is non-constant. Each compile method for collection
literals attempts the all-constant fast path first and falls through to
the existing instruction-by-instruction codegen otherwise.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* perf(compiler): fuse Eq + AssertCondition into AssertEq instruction

Add a new `AssertEq { left, right }` instruction that combines equality
comparison and condition assertion into a single operation. This replaces
the previous two-instruction pattern of `Eq { dest, left, right }` followed
by `AssertCondition { condition: dest }`, saving one instruction and one
register per equality assertion.

The fused instruction checks two registers for equality and directly calls
handle_condition with the result, avoiding the intermediate boolean
register entirely. If either operand is undefined or the values differ,
the condition fails and the rule/loop backtracks.

The optimization applies to four destructuring sites:
- EqualityCheck (assignment re-binding with `x = expr; x = expr`)
- EqualityExpr (destructuring against an expression)
- EqualityValue (destructuring against a literal value)
- assert_array_length (array length validation in destructuring)

In soft_assert_mode the compiler still emits the original Eq instruction
since the boolean result register is needed by callers.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* perf(compiler): fuse Not + AssertCondition into AssertNot instruction

Add a new `AssertNot { operand }` instruction that combines logical
negation and condition assertion into a single operation. This replaces
the previous two-instruction pattern of `Not { dest, operand }` followed
by `AssertCondition { condition: dest }`, saving one instruction and one
register allocation.

The fused instruction checks the operand register and passes the
condition if the value is false or undefined (per Rego semantics where
`not expr` succeeds when the expression has no results or is false),
and fails the condition if the value is true or any non-boolean truthy
value.

This was the only emission site for the Not+AssertCondition pair,
occurring in the compilation of `Literal::NotExpr` statements.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* perf(vm): early exit for same-value multi-definition rules

When a rule has multiple definitions that all produce the same value
(e.g. implicit true, or identical literal), set early_exit_on_first_success
on RuleInfo so the VM can stop after the first successful definition.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

* feat!: expose cache configuration API to all language bindings

Add `set_cache_config` and `clear_cache` functions to every binding
so callers can tune or reset the global regex/glob pattern caches
introduced in the cache feature.

Bindings updated:
- FFI (C): `regorus_set_cache_config`, `regorus_clear_cache`
- C++ header: free functions `regorus::set_cache_config`, `regorus::clear_cache`
- Python: module-level `set_cache_config(*, regex, glob)`, `clear_cache()`
- Java: static methods on new `CacheConfig` class
- Go: package-level `SetCacheConfig`, `ClearCache`
- Ruby: module functions `Regorus.set_cache_config`, `Regorus.clear_cache`
- WASM: free functions `setCacheConfig`, `clearCache`
- C#: static methods `Engine.SetCacheConfig`, `Engine.ClearCache`

BREAKING CHANGE: Bump SERIALIZATION_VERSION from 4 to 5 due to new
AssertEq and AssertNot instruction variants added in the instruction
fusion commits. Programs serialized with version 5 cannot be loaded
by older versions of regorus.

* fix: address PR review feedback

Cache subsystem:
- Gate REGEX_CACHE and related imports behind #[cfg(feature = "regex")]
  so that building with --features cache without regex compiles correctly.
- Gate LruCache struct behind #[cfg(any(feature = "regex", feature = "glob"))].
- Add Config::MAX_CAPACITY (2^16) hard upper bound; clamp values in
  configure() to prevent unbounded cache growth.
- Use parking_lot::Mutex for std builds and spin::Mutex for no_std to
  avoid CPU spinning under contention in tight regex/glob eval loops.
- Narrow lock scopes in regex/glob builtins: release the mutex before
  compiling a pattern, then re-acquire to insert.

Java JNI binding:
- Fix cache config overflow: negative jlong values now saturate to 0
  and positive overflow saturates to usize::MAX (then clamped by
  MAX_CAPACITY) instead of silently disabling the cache.
- Gate JNI cache config/clear functions behind #[cfg(feature = "cache")].

Compiler:
- Refactor static_value_of_expr to delegate to try_eval_const,
  gaining support for negated numbers and constant collections.
- Make try_eval_const pub(in crate::languages::rego::compiler) and
  re-export through expressions.rs.
- Handle Expr::UnaryExpr with numeric literals in try_eval_const so
  collections containing negated numbers (e.g. [-1, 2]) are hoisted.

VM correctness:
- Fix Not instruction to follow Rego semantics: not expr yields
  true when expr is undefined or false, false for any other defined
  value (including non-booleans) -- no longer errors on non-boolean
  operands.
- Add enforce_memory_check() call at execute_suspendable_entry to
  ensure memory limits are checked before the first instruction.
- Update AssertNot listing comment to "exit if any defined truthy
  value" to match actual VM behaviour.
- Add doc comment on Not instruction clarifying Rego negation
  semantics.

Bindings:
- Fix C++ header indentation for set_cache_config / clear_cache.
- Propagate Cargo.lock parking_lot addition across ffi, java, python,
  and wasm binding lockfiles.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

---------

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

bindings/c/main.c

@@ -11,6 +11,13 @@ int main() {
     if (r.status != Ok)
 	goto error;
 
+    // Configure the global pattern caches.
+    RegorusCacheConfig cache_config = { .regex = 256, .glob = 128 };
+    r = regorus_set_cache_config(cache_config);
+    if (r.status != Ok)
+	goto error;
+    regorus_result_drop(r);
+
     // Raise the default col limit to 2000
     RegorusPolicyLengthConfig len_config = { .max_col = 2000, .max_file_bytes = 1048576, .max_lines = 20000 };
     r = regorus_engine_set_policy_length_config(engine, len_config);

bindings/cpp/main.cpp

@@ -6,6 +6,10 @@ void example()
     // Create engine
     regorus::Engine engine;
 
+    // Configure the global pattern caches.
+    RegorusCacheConfig cache_config = { 256, 128 };
+    regorus::set_cache_config(cache_config);
+
     engine.set_rego_v0(true);
     engine.set_enable_coverage(true);
 

bindings/cpp/regorus.hpp

@@ -158,6 +158,14 @@ namespace regorus {
 	Engine& operator=(const Engine&) = delete;
     };
 
+    inline Result set_cache_config(RegorusCacheConfig config) {
+	    return Result(regorus_set_cache_config(config));
+    }
+
+    inline Result clear_cache() {
+	    return Result(regorus_clear_cache());
+    }
+
     class CompiledPolicy {
     public:
 	explicit CompiledPolicy(RegorusCompiledPolicy* p) : policy(p) {}

bindings/csharp/Regorus/CacheConfig.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+
+namespace Regorus
+{
+    /// <summary>
+    /// Global configuration for compiled pattern caches used by regex and glob builtins.
+    /// </summary>
+    public readonly struct CacheConfig
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CacheConfig"/> struct.
+        /// </summary>
+        /// <param name="regex">Maximum cached compiled regex patterns (default 256, 0 = disabled).</param>
+        /// <param name="glob">Maximum cached compiled glob matchers (default 128, 0 = disabled).</param>
+        public CacheConfig(nuint regex, nuint glob)
+        {
+            Regex = regex;
+            Glob = glob;
+        }
+
+        /// <summary>Maximum cached compiled regex patterns (default 256).</summary>
+        public nuint Regex { get; }
+
+        /// <summary>Maximum cached compiled glob matchers (default 128).</summary>
+        public nuint Glob { get; }
+
+        internal Regorus.Internal.RegorusCacheConfig ToNative()
+        {
+            return new Regorus.Internal.RegorusCacheConfig
+            {
+                regex = Regex,
+                glob = Glob,
+            };
+        }
+    }
+}

bindings/csharp/Regorus/Engine.cs

@@ -34,6 +34,17 @@ namespace Regorus
             CheckAndDropResult(Regorus.Internal.API.regorus_clear_fallback_execution_timer_config());
         }
 
+        public static void SetCacheConfig(CacheConfig config)
+        {
+            var nativeConfig = config.ToNative();
+            CheckAndDropResult(Regorus.Internal.API.regorus_set_cache_config(nativeConfig));
+        }
+
+        public static void ClearCache()
+        {
+            CheckAndDropResult(Regorus.Internal.API.regorus_clear_cache());
+        }
+
         private Engine(RegorusEngineHandle handle)
             : base(handle, nameof(Engine))
         {

bindings/csharp/Regorus/NativeMethods.cs

@@ -458,6 +458,22 @@ namespace Regorus.Internal
 
         #endregion
 
+        #region Cache Configuration Global Methods
+
+        /// <summary>
+        /// Configure the global pattern caches used by regex and glob builtins.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_set_cache_config", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_set_cache_config(RegorusCacheConfig config);
+
+        /// <summary>
+        /// Clear all entries from every pattern cache.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_clear_cache", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_clear_cache();
+
+        #endregion
+
         #region Compilation Methods
 
         /// <summary>
@@ -795,6 +811,16 @@ namespace Regorus.Internal
         public UIntPtr max_lines;
     }
 
+    /// <summary>
+    /// FFI representation of the cache configuration.
+    /// </summary>
+    [StructLayout(LayoutKind.Sequential)]
+    internal struct RegorusCacheConfig
+    {
+        public UIntPtr regex;
+        public UIntPtr glob;
+    }
+
     /// <summary>
     /// Byte buffer returned from FFI.
     /// </summary>

bindings/csharp/TestApp/Program.cs

@@ -18,6 +18,9 @@ var w = new Stopwatch();
 
 w.Restart();
 
+// Configure the global pattern caches.
+Regorus.Engine.SetCacheConfig(new Regorus.CacheConfig(regex: 256, glob: 128));
+
 var engine = new Regorus.Engine();
 engine.SetRegoV0(true);
 // Raise the default col limit to 2000

bindings/ffi/Cargo.lock

@@ -657,6 +657,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+
 [[package]]
 name = "memchr"
 version = "2.7.6"
@@ -985,9 +991,11 @@ dependencies = [
  "ipnet",
  "jsonschema",
  "lazy_static",
+ "lru",
  "msvc_spectre_libs",
  "num-bigint",
  "num-traits",
+ "parking_lot",
  "postcard",
  "rand",
  "regex",

bindings/ffi/Cargo.toml

@@ -35,6 +35,7 @@ default = [
 	"rbac",
 	"regorus/arc",
 	"regorus/full-opa",
+	"cache",
 	"contention_checks",
 ]
 ast = ["regorus/ast"]
@@ -45,6 +46,7 @@ allocator-memory-limits = ["regorus/allocator-memory-limits"]
 contention_checks = ["parking_lot"]
 rvm = ["regorus/rvm"]
 rbac = ["regorus/azure-rbac"]
+cache = ["regorus/cache"]
 custom_allocator = []
 
 [build-dependencies]

bindings/ffi/src/limits.rs

@@ -199,6 +199,40 @@ pub extern "C" fn regorus_clear_fallback_execution_timer_config() -> RegorusResu
     RegorusResult::ok_void()
 }
 
+// ---------------------------------------------------------------------------
+// Cache configuration (global)
+// ---------------------------------------------------------------------------
+
+/// FFI representation of [`regorus::cache::Config`].
+#[cfg(feature = "cache")]
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct RegorusCacheConfig {
+    /// Maximum compiled regex patterns (default 256, 0 = disabled).
+    pub regex: usize,
+    /// Maximum compiled glob matchers (default 128, 0 = disabled).
+    pub glob: usize,
+}
+
+/// Configure the global pattern caches used by `regex.*` and `glob.*` builtins.
+#[cfg(feature = "cache")]
+#[no_mangle]
+pub extern "C" fn regorus_set_cache_config(config: RegorusCacheConfig) -> RegorusResult {
+    regorus::cache::configure(regorus::cache::Config {
+        regex: config.regex,
+        glob: config.glob,
+    });
+    RegorusResult::ok_void()
+}
+
+/// Clear all entries from every pattern cache.
+#[cfg(feature = "cache")]
+#[no_mangle]
+pub extern "C" fn regorus_clear_cache() -> RegorusResult {
+    regorus::cache::clear();
+    RegorusResult::ok_void()
+}
+
 #[cfg(test)]
 mod tests {
     use super::{

bindings/go/main.go

@@ -17,6 +17,12 @@ func main() {
 	engine := regorus.NewEngine()
 	defer engine.Close()
 
+	// Configure the global pattern caches.
+	if err = regorus.SetCacheConfig(regorus.CacheConfig{Regex: 256, Glob: 128}); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
 	engine.SetRegoV0(true)
 	// Raise the default col limit to 2000
 	engine.SetPolicyLengthConfig(regorus.PolicyLengthConfig{MaxCol: 2000, MaxFileBytes: 1048576, MaxLines: 20000})

bindings/go/pkg/regorus/mod.go

@@ -243,3 +243,30 @@ func (e *Engine) ClearPolicyLengthConfig() error {
 	}
 	return nil
 }
+
+type CacheConfig struct {
+	Regex uint
+	Glob  uint
+}
+
+func SetCacheConfig(config CacheConfig) error {
+	c := C.RegorusCacheConfig{
+		regex: C.size_t(config.Regex),
+		glob:  C.size_t(config.Glob),
+	}
+	result := C.regorus_set_cache_config(c)
+	defer C.regorus_result_drop(result)
+	if result.status != C.Ok {
+		return fmt.Errorf("%s", C.GoString(result.error_message))
+	}
+	return nil
+}
+
+func ClearCache() error {
+	result := C.regorus_clear_cache()
+	defer C.regorus_result_drop(result)
+	if result.status != C.Ok {
+		return fmt.Errorf("%s", C.GoString(result.error_message))
+	}
+	return nil
+}

bindings/java/Cargo.lock

@@ -539,6 +539,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+
 [[package]]
 name = "memchr"
 version = "2.7.6"
@@ -860,9 +866,11 @@ dependencies = [
  "ipnet",
  "jsonschema",
  "lazy_static",
+ "lru",
  "msvc_spectre_libs",
  "num-bigint",
  "num-traits",
+ "parking_lot",
  "postcard",
  "rand",
  "regex",

bindings/java/Cargo.toml

@@ -14,9 +14,10 @@ keywords = ["interpreter", "opa", "policy-as-code", "rego"]
 crate-type = ["cdylib"]
 
 [features]
-default = ["ast", "coverage", "regorus/std", "regorus/full-opa"]
+default = ["ast", "cache", "coverage", "regorus/std", "regorus/full-opa"]
 coverage = ["regorus/coverage"]
 ast = ["regorus/ast"]
+cache = ["regorus/cache"]
 
 [dependencies]
 anyhow = "1.0"

bindings/java/Test.java

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+import com.microsoft.regorus.CacheConfig;
 import com.microsoft.regorus.Engine;
 import com.microsoft.regorus.PolicyLengthConfig;
 import com.microsoft.regorus.PolicyModule;
@@ -10,6 +11,9 @@ import com.microsoft.regorus.Rvm;
 public class Test {
 
     public static void main(String[] args) {
+        // Configure the global pattern caches.
+        CacheConfig.configure(new CacheConfig(256, 128));
+
         try (Engine engine = new Engine()) {
             String pkg = engine.addPolicy(
                     "hello.rego",

bindings/java/src/lib.rs

@@ -399,6 +399,37 @@ pub extern "system" fn Java_com_microsoft_regorus_Engine_nativeClearPolicyLength
     engine.clear_policy_length_config();
 }
 
+#[cfg(feature = "cache")]
+#[no_mangle]
+pub extern "system" fn Java_com_microsoft_regorus_CacheConfig_nativeSetCacheConfig(
+    _env: JNIEnv,
+    _class: JClass,
+    regex: jlong,
+    glob: jlong,
+) {
+    regorus::cache::configure(regorus::cache::Config {
+        regex: if regex < 0 {
+            0
+        } else {
+            usize::try_from(regex).unwrap_or(usize::MAX)
+        },
+        glob: if glob < 0 {
+            0
+        } else {
+            usize::try_from(glob).unwrap_or(usize::MAX)
+        },
+    });
+}
+
+#[cfg(feature = "cache")]
+#[no_mangle]
+pub extern "system" fn Java_com_microsoft_regorus_CacheConfig_nativeClearCache(
+    _env: JNIEnv,
+    _class: JClass,
+) {
+    regorus::cache::clear();
+}
+
 #[no_mangle]
 pub extern "system" fn Java_com_microsoft_regorus_Engine_nativeDestroyEngine(
     _env: JNIEnv,

bindings/java/src/main/java/com/microsoft/regorus/CacheConfig.java

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ **/
+
+package com.microsoft.regorus;
+
+/**
+ * Global configuration for compiled pattern caches used by regex and glob builtins.
+ *
+ * <p>Capacity of 0 disables the corresponding cache.
+ */
+public final class CacheConfig {
+
+    static {
+        System.loadLibrary("regorus_java");
+    }
+
+    private static native void nativeSetCacheConfig(long regex, long glob);
+    private static native void nativeClearCache();
+
+    /**
+     * Maximum cached compiled regex patterns (default 256).
+     */
+    public final long regex;
+
+    /**
+     * Maximum cached compiled glob matchers (default 128).
+     */
+    public final long glob;
+
+    /**
+     * Create a new cache configuration.
+     *
+     * @param regex Maximum cached compiled regex patterns (0 = disabled).
+     * @param glob Maximum cached compiled glob matchers (0 = disabled).
+     */
+    public CacheConfig(long regex, long glob) {
+        if (regex < 0) {
+            throw new IllegalArgumentException("regex must be non-negative");
+        }
+        if (glob < 0) {
+            throw new IllegalArgumentException("glob must be non-negative");
+        }
+        this.regex = regex;
+        this.glob = glob;
+    }
+
+    /**
+     * Apply this cache configuration globally.
+     */
+    public static void configure(CacheConfig config) {
+        nativeSetCacheConfig(config.regex, config.glob);
+    }
+
+    /**
+     * Clear all entries from every pattern cache.
+     */
+    public static void clear() {
+        nativeClearCache();
+    }
+}

bindings/python/Cargo.lock

@@ -510,6 +510,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+
 [[package]]
 name = "memchr"
 version = "2.7.6"
@@ -919,9 +925,11 @@ dependencies = [
  "ipnet",
  "jsonschema",
  "lazy_static",
+ "lru",
  "msvc_spectre_libs",
  "num-bigint",
  "num-traits",
+ "parking_lot",
  "postcard",
  "rand",
  "regex",

bindings/python/Cargo.toml

@@ -15,8 +15,9 @@ keywords = ["interpreter", "opa", "policy-as-code", "rego"]
 crate-type = ["cdylib"]
 
 [features]
-default = ["ast", "coverage", "regorus/std", "regorus/full-opa"]
+default = ["ast", "cache", "coverage", "regorus/std", "regorus/full-opa"]
 ast = ["regorus/ast"]
+cache = ["regorus/cache"]
 coverage = ["regorus/coverage"]
 
 [dependencies]

bindings/python/src/lib.rs

@@ -622,10 +622,33 @@ impl Rvm {
     }
 }
 
+/// Configure the global pattern caches used by `regex.*` and `glob.*` builtins.
+///
+/// * `regex`: Maximum cached compiled regex patterns (default 256, 0 = disabled).
+/// * `glob`: Maximum cached compiled glob matchers (default 128, 0 = disabled).
+#[cfg(feature = "cache")]
+#[pyfunction]
+#[pyo3(signature = (*, regex = 256, glob = 128))]
+fn set_cache_config(regex: usize, glob: usize) {
+    ::regorus::cache::configure(::regorus::cache::Config { regex, glob });
+}
+
+/// Clear all entries from every pattern cache.
+#[cfg(feature = "cache")]
+#[pyfunction]
+fn clear_cache() {
+    ::regorus::cache::clear();
+}
+
 #[pymodule]
 pub fn regorus(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<crate::Engine>()?;
     m.add_class::<crate::Program>()?;
     m.add_class::<crate::Rvm>()?;
+    #[cfg(feature = "cache")]
+    {
+        m.add_function(wrap_pyfunction!(set_cache_config, m)?)?;
+        m.add_function(wrap_pyfunction!(clear_cache, m)?)?;
+    }
     Ok(())
 }

bindings/python/test.py

@@ -6,6 +6,9 @@ import sys
 if hasattr(sys.stdout, "reconfigure"):
   sys.stdout.reconfigure(encoding="utf-8")
 
+# Configure the global pattern caches.
+regorus.set_cache_config(regex=256, glob=128)
+
 # Create engine
 engine = regorus.Engine()
 

bindings/ruby/Cargo.lock

@@ -549,6 +549,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+
 [[package]]
 name = "magnus"
 version = "0.8.2"
@@ -926,6 +932,7 @@ dependencies = [
  "ipnet",
  "jsonschema",
  "lazy_static",
+ "lru",
  "msvc_spectre_libs",
  "num-bigint",
  "num-traits",

bindings/ruby/ext/regorusrb/Cargo.toml

@@ -11,8 +11,9 @@ crate-type = ["cdylib"]
 path = "src/lib.rs"
 
 [features]
-default = ["ast", "coverage", "regorus/std", "regorus/full-opa"]
+default = ["ast", "cache", "coverage", "regorus/std", "regorus/full-opa"]
 ast = ["regorus/ast"]
+cache = ["regorus/cache"]
 coverage = ["regorus/coverage"]
 
 [dependencies]

bindings/ruby/ext/regorusrb/src/lib.rs

@@ -14,6 +14,13 @@ struct PolicyLengthSpec {
     max_lines: usize,
 }
 
+#[cfg(feature = "cache")]
+#[derive(Deserialize)]
+struct CacheConfigSpec {
+    regex: usize,
+    glob: usize,
+}
+
 #[derive(Default)]
 #[magnus::wrap(class = "Regorus::Engine")]
 pub struct Engine {
@@ -417,5 +424,35 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     // ast
     engine_class.define_method("get_ast_as_json", method!(Engine::get_ast_as_json, 0))?;
+
+    // cache configuration (module-level)
+    #[cfg(feature = "cache")]
+    {
+        regorus_module
+            .define_module_function("set_cache_config", magnus::function!(set_cache_config, 1))?;
+        regorus_module.define_module_function("clear_cache", magnus::function!(clear_cache, 0))?;
+    }
+
+    Ok(())
+}
+
+#[cfg(feature = "cache")]
+fn set_cache_config(ruby: &Ruby, hash: magnus::RHash) -> Result<(), Error> {
+    let spec: CacheConfigSpec = serde_magnus::deserialize(ruby, hash).map_err(|e| {
+        Error::new(
+            runtime_error(),
+            format!("Failed to deserialize cache config: {e}"),
+        )
+    })?;
+    regorus::cache::configure(regorus::cache::Config {
+        regex: spec.regex,
+        glob: spec.glob,
+    });
+    Ok(())
+}
+
+#[cfg(feature = "cache")]
+fn clear_cache() -> Result<(), Error> {
+    regorus::cache::clear();
     Ok(())
 }

bindings/ruby/test/test_regorus.rb

@@ -188,6 +188,11 @@ class TestRegorus < Minitest::Test
     @engine.clear_policy_length_config
   end
 
+  def test_set_cache_config
+    ::Regorus.set_cache_config({ regex: 256, glob: 128 })
+    ::Regorus.clear_cache
+  end
+
   def alice_results
     {
       result: [

bindings/wasm/Cargo.lock

@@ -558,6 +558,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+
 [[package]]
 name = "memchr"
 version = "2.7.6"
@@ -917,9 +923,11 @@ dependencies = [
  "ipnet",
  "jsonschema",
  "lazy_static",
+ "lru",
  "msvc_spectre_libs",
  "num-bigint",
  "num-traits",
+ "parking_lot",
  "postcard",
  "rand",
  "regex",

bindings/wasm/Cargo.toml

@@ -32,9 +32,11 @@ default = [
 	"regorus/time",
 	"regorus/uuid",
 	"regorus/urlquery",
-	"regorus/yaml"
+	"regorus/yaml",
+	"cache"
 ]
 ast = ["regorus/ast"]
+cache = ["regorus/cache"]
 coverage = ["regorus/coverage"]
 
 [dependencies]

bindings/wasm/src/lib.rs

@@ -35,6 +35,34 @@ struct PolicyLengthSpec {
     max_lines: usize,
 }
 
+#[cfg(feature = "cache")]
+#[derive(Deserialize)]
+struct CacheConfigSpec {
+    regex: usize,
+    glob: usize,
+}
+
+/// Configure the global pattern caches used by regex and glob builtins.
+///
+/// Accepts a JS object: `{ regex, glob }`.
+#[cfg(feature = "cache")]
+#[wasm_bindgen(js_name = "setCacheConfig")]
+pub fn set_cache_config(config: JsValue) -> Result<(), JsValue> {
+    let spec: CacheConfigSpec = serde_wasm_bindgen::from_value(config).map_err(error_to_jsvalue)?;
+    regorus::cache::configure(regorus::cache::Config {
+        regex: spec.regex,
+        glob: spec.glob,
+    });
+    Ok(())
+}
+
+/// Clear all entries from every pattern cache.
+#[cfg(feature = "cache")]
+#[wasm_bindgen(js_name = "clearCache")]
+pub fn clear_cache() {
+    regorus::cache::clear();
+}
+
 #[wasm_bindgen]
 pub struct Program {
     program: Arc<RvmProgram>,

bindings/wasm/test.js

@@ -3,6 +3,9 @@
 
 var regorus = require('./pkg/regorusjs');
 
+// Configure the global pattern caches.
+regorus.setCacheConfig({ regex: 256, glob: 128 });
+
 // Create an engine.
 var engine = new regorus.Engine();