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.
When both content ways are pinned, let the bounded site entry own the
program bundle until that site is displaced.

Add a sabotage test that crosses the 512-entry boundary, 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

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

@@ -126,6 +126,29 @@ fn entry_matches(entry: &Entry, fp: u64, pattern: &str, flags: &str) -> bool {
     entry.fp == fp && &*entry.flags == flags && &*entry.pattern == pattern
 }
 
+/// Pick one of this fingerprint's two ways without displacing a recorded
+/// literal site. If both are literal-owned, the caller leaves the new dynamic
+/// entry uncached; a new literal pins its bundle in the bounded site table.
+fn replacement_slot(cache: &[Option<Entry>], slot: usize, fp: u64) -> Option<usize> {
+    if cache[slot].is_none() {
+        return Some(slot);
+    }
+    if cache[slot ^ 1].is_none() {
+        return Some(slot ^ 1);
+    }
+    let preferred = slot ^ ((fp >> 11) as usize & 1);
+    [preferred, preferred ^ 1].into_iter().find(|&candidate| {
+        let entry = cache[candidate].as_ref().expect("both ways are occupied");
+        !super::site_key::references_content(&entry.pattern, &entry.flags)
+    })
+}
+
+fn note_eviction() {
+    if crate::hot_diag::regex_on() {
+        crate::hot_diag::regex_counters(|d| d.cache_evictions += 1);
+    }
+}
+
 /// Find the verified entry for `(pattern, canonical flags)`.
 pub(super) fn lookup(pattern: &str, flags: &str) -> Option<Hit> {
     if !enabled() {
@@ -184,21 +207,19 @@ pub(super) fn insert(pattern: &str, flags: &str) -> (Arc<str>, Arc<str>) {
                 }
             }
         }
-        let victim = if cache[slot].is_none() {
-            slot
-        } else if cache[slot ^ 1].is_none() {
-            slot ^ 1
-        } else {
-            slot ^ ((fp >> 11) as usize & 1)
-        };
         let pattern: Arc<str> = Arc::from(pattern);
         let flags: Arc<str> = Arc::from(flags);
-        cache[victim] = Some(Entry {
-            fp,
-            pattern: pattern.clone(),
-            flags: flags.clone(),
-            programs: None,
-        });
+        if let Some(victim) = replacement_slot(&cache, slot, fp) {
+            if cache[victim].is_some() {
+                note_eviction();
+            }
+            cache[victim] = Some(Entry {
+                fp,
+                pattern: pattern.clone(),
+                flags: flags.clone(),
+                programs: None,
+            });
+        }
         (pattern, flags)
     })
 }
@@ -212,7 +233,7 @@ pub(super) fn install_programs(pattern: &str, flags: &str, programs: Arc<Program
     }
     let fp = fingerprint(pattern.as_bytes(), flags.as_bytes());
     let slot = slot_of(fp);
-    SITE_CACHE.with(|cache| {
+    let content_owned = SITE_CACHE.with(|cache| {
         let mut cache = cache.borrow_mut();
         if cache.is_empty() {
             cache.resize_with(SLOTS, || None);
@@ -221,26 +242,27 @@ pub(super) fn install_programs(pattern: &str, flags: &str, programs: Arc<Program
             if let Some(entry) = &mut cache[s] {
                 if entry_matches(entry, fp, pattern, flags) {
                     if entry.programs.is_none() {
-                        entry.programs = Some(programs);
+                        entry.programs = Some(programs.clone());
                     }
-                    return;
+                    return true;
                 }
             }
         }
-        let victim = if cache[slot].is_none() {
-            slot
-        } else if cache[slot ^ 1].is_none() {
-            slot ^ 1
-        } else {
-            slot ^ ((fp >> 11) as usize & 1)
+        let Some(victim) = replacement_slot(&cache, slot, fp) else {
+            return false;
         };
+        if cache[victim].is_some() {
+            note_eviction();
+        }
         cache[victim] = Some(Entry {
             fp,
             pattern: Arc::from(pattern),
             flags: Arc::from(flags),
-            programs: Some(programs),
+            programs: Some(programs.clone()),
         });
+        true
     });
+    super::site_key::install_programs_for_content(pattern, flags, &programs, content_owned);
 }
 
 #[cfg(test)]
@@ -267,3 +289,9 @@ pub(super) fn test_has_programs(pattern: &str, flags: &str) -> Option<bool> {
         None
     })
 }
+
+#[cfg(test)]
+pub(super) fn test_slot_and_victim_way(pattern: &str, flags: &str) -> (usize, usize) {
+    let fp = fingerprint(pattern.as_bytes(), flags.as_bytes());
+    (slot_of(fp), (fp >> 11) as usize & 1)
+}