perf(regex): preserve live literal programs on eviction

Replace whole-map overflow clears with one-entry eviction, and keep
content-cache entries pinned while a recorded literal site refers to them.
Only dynamic or displaced-site entries can leave the bounded table.

Add a sabotage test that crosses both cache bounds, collects dead nursery
headers, and proves the recorded literal does not rebuild.

Author: Ralph Küpper

changelog.d/9918-regex-cache-eviction.md

@@ -0,0 +1 @@
+Keep compiled programs for recorded regular-expression literal sites across bounded cache eviction, and replace whole-cache overflow clears with one-entry eviction.

crates/perry-runtime/src/hot_diag.rs

@@ -126,6 +126,9 @@ pub struct RegexDiag {
     pub compiles_std: u64,
     pub compiles_fancy: u64,
     pub compiles_repeat: u64,
+    /// One-entry evictions after a regex cache reaches its bound. The former
+    /// wholesale-clear counter remains as a zeroed regression control.
+    pub cache_evictions: u64,
     pub cache_clears: u64,
     /// `lazy::build_and_install_programs` runs (one per header that is
     /// executed at least once).
@@ -190,6 +193,10 @@ pub struct RegexDiag {
     /// CONTENT-keyed cache; a site hit never reaches it, so the two are
     /// disjoint and `site_key_hit + site_hit <= new`.
     pub new_site_key_hit: u64,
+    #[cfg(test)]
+    test_program_builds: u64,
+    #[cfg(test)]
+    test_cache_evictions: u64,
     per_pattern: HashMap<usize, PatStat>,
 }
 
@@ -252,6 +259,33 @@ pub fn regex_with(f: impl FnOnce(&mut RegexDiag)) {
     });
 }
 
+#[cfg(test)]
+pub(crate) fn test_reset_regex_builds_and_evictions() {
+    REGEX_DIAG.with(|diag| {
+        let mut diag = diag.borrow_mut();
+        diag.test_program_builds = 0;
+        diag.test_cache_evictions = 0;
+    });
+}
+
+#[cfg(test)]
+pub(crate) fn test_note_regex_program_build() {
+    REGEX_DIAG.with(|diag| diag.borrow_mut().test_program_builds += 1);
+}
+
+#[cfg(test)]
+pub(crate) fn test_note_regex_cache_eviction() {
+    REGEX_DIAG.with(|diag| diag.borrow_mut().test_cache_evictions += 1);
+}
+
+#[cfg(test)]
+pub(crate) fn test_regex_builds_and_evictions() -> (u64, u64) {
+    REGEX_DIAG.with(|diag| {
+        let diag = diag.borrow();
+        (diag.test_program_builds, diag.test_cache_evictions)
+    })
+}
+
 impl RegexDiag {
     fn pat(&mut self, pattern_addr: usize, pattern: &[u8], flags: &str) -> &mut PatStat {
         let entry = self.per_pattern.entry(pattern_addr).or_default();
@@ -331,7 +365,7 @@ impl RegexDiag {
         let _ = writeln!(
             out,
             "[regex-diag] t={secs:.1}s new={} validated_hit={} site_hit={} pattern_bytes={} \
-             compiles std={} fancy={} repeat={} cache_clears={} lazy_builds={} lazy_cache_hits={} \
+             compiles std={} fancy={} repeat={} cache_clears={} evictions={} lazy_builds={} lazy_cache_hits={} \
              exec={} exec_matched={} capture_slots={} capture_bytes={} test={} test_global={} \
              match={} replace={} replace_matches={} split={} flags_alloc={} \
              desc_regexp_probes={} desc_regexp_meta_negative={} \
@@ -346,6 +380,7 @@ impl RegexDiag {
             self.compiles_fancy,
             self.compiles_repeat,
             self.cache_clears,
+            self.cache_evictions,
             self.lazy_builds,
             self.lazy_cache_hits,
             self.exec_calls,

crates/perry-runtime/src/regex.rs

@@ -481,9 +481,9 @@ crate::perry_thread_local! {
     /// validation. Validity is a pure function of the pair, so the answer is
     /// worth remembering; `js_regexp_new` used to get this from a
     /// `REGEX_CACHE` hit, which stopped being a proxy once the compiled
-    /// program became lazy (see `regex::lazy`). Same cap and
-    /// clear-on-overflow policy as the program caches — the cost of a clear
-    /// is a repeated parse, never a wrong verdict. The unit value keeps
+    /// program became lazy (see `regex::lazy`). Same cap and one-entry
+    /// eviction policy as the program caches — eviction can repeat one parse,
+    /// never change a verdict. The unit value keeps
     /// `evict_regex_cache_if_full` shared with the three program caches.
     static VALIDATED_PATTERNS: RefCell<HashMap<(String, String), ()>> = RefCell::new(HashMap::new());
 }
@@ -569,26 +569,25 @@ pub(crate) fn build_fancy_regex(pattern: &str) -> Result<fancy_regex::Regex, fan
         .build()
 }
 
-/// Entry cap for the compiled-regex caches (2026-07-09 GC audit: one entry
-/// per distinct `(pattern, flags)` ever compiled, no cap of any kind, entries
-/// up to [`REGEX_SIZE_LIMIT`] — `new RegExp(userInput)` was an attacker-driven
-/// OOM). When an insert would exceed the cap the whole map is cleared — the
-/// `PARSE_KEY_CACHE` precedent: cheap, no LRU bookkeeping, recompilation is
-/// the fallback. Live `RegExpHeader`s are unaffected: each header OWNS a raw
-/// `Arc` reference to its compiled program(s), released by its GC finalizer,
-/// so dropping the cache's references cannot free a program still in use.
+/// Entry cap for the content-keyed compiled-regex caches. An insertion at the
+/// cap evicts one entry rather than clearing the entire working set. Literal
+/// programs remain owned by `site_cache` while their literal site is recorded;
+/// only dynamic programs can lose their last cache reference.
 #[cfg(feature = "regex-engine")]
 const REGEX_CACHE_MAX_ENTRIES: usize = 512;
 
-/// Clear-on-overflow guard shared by the compiled-program caches and the
-/// validated-pattern set: make room for one more entry, wiping the map when it
-/// is at capacity.
+/// Make room for one entry without invalidating the other 511 cached answers.
 #[cfg(feature = "regex-engine")]
-fn evict_regex_cache_if_full<K, V>(cache: &mut HashMap<K, V>) {
+fn evict_regex_cache_if_full<K: Clone + Eq + std::hash::Hash, V>(cache: &mut HashMap<K, V>) {
     if cache.len() >= REGEX_CACHE_MAX_ENTRIES {
-        cache.clear();
+        let victim = cache.keys().next().cloned();
+        if let Some(victim) = victim {
+            cache.remove(&victim);
+        }
+        #[cfg(test)]
+        tests_cache::note_cache_eviction();
         if crate::hot_diag::regex_on() {
-            crate::hot_diag::regex_with(|d| d.cache_clears += 1);
+            crate::hot_diag::regex_counters(|d| d.cache_evictions += 1);
         }
     }
 }
@@ -1996,4 +1995,6 @@ pub(crate) fn test_last_exec_groups() -> usize {
 #[cfg(all(test, feature = "regex-engine"))]
 mod tests;
 #[cfg(all(test, feature = "regex-engine"))]
+mod tests_cache;
+#[cfg(all(test, feature = "regex-engine"))]
 mod tests_header;

crates/perry-runtime/src/regex/lazy.rs

@@ -217,6 +217,8 @@ fn build_and_install_programs(re: *const RegExpHeader) {
     if !is_valid_regex_ptr(re) {
         return;
     }
+    #[cfg(test)]
+    crate::hot_diag::test_note_regex_program_build();
     let (pattern, flags) = source_and_flags(re);
     if crate::hot_diag::regex_on() {
         let cache_hit = super::REGEX_CACHE.with(|cache| {
@@ -248,7 +250,7 @@ fn build_and_install_programs(re: *const RegExpHeader) {
     // here becomes the answer for every later construction of the same
     // literal. It therefore has to be complete, and the probes above cannot
     // guarantee that on their own: the three caches are capped independently
-    // and each `clear()`s wholesale, while
+    // and each can evict a different entry, while
     // `compile_and_cache_regex_checked` returns early whenever `REGEX_CACHE`
     // already holds the pattern — so it never re-runs the fancy or
     // repeat-matcher build for a pattern whose `REGEX_CACHE` entry survived a
@@ -306,6 +308,16 @@ fn build_and_install_programs(re: *const RegExpHeader) {
     }
 }
 
+#[cfg(test)]
+pub(super) fn test_reset_program_builds() {
+    crate::hot_diag::test_reset_regex_builds_and_evictions();
+}
+
+#[cfg(test)]
+pub(super) fn test_program_builds() -> u64 {
+    crate::hot_diag::test_regex_builds_and_evictions().0
+}
+
 /// The header's standard-engine program, building it on first use.
 ///
 /// Every standard-program borrow in the tree goes through here — the field is