rusty_racer 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03be69f3c1409a64a73622db3063447bbea7813f393227d508739f0c636c6859
-  data.tar.gz: 7a7ecb5203032be6f8b27133444ce8c3663eb7d9d49aa86726be8c28acf19425
+  metadata.gz: bc72e8a18f16fc78197991e4e29ff01ba94afb83ae26d3ea162903654f485dae
+  data.tar.gz: 06a00da38cb052af3a29fa772f93fa14f3e8f267f8a7c88723aad827f908a3d7
 SHA512:
-  metadata.gz: 57fb55d034906210851ea93be3ad933ee366dfccd1419d4f7f712ed5407082565ccda4ed0e0abadde12ec9af1b958ffab908cbdfb40ef5efa188ed8d2f47154e
-  data.tar.gz: 56983cedc5a48dc0a9cf1570da7a7241a6be6a3a8c80ca7114204e6764bc377a0d72814147e318c64974093b625148e8260d8e75168a76e1fa22711a94e5ed69
+  metadata.gz: 3e86f16c51dbe2b1096a7710ea105da2f95f68b640f9a3265f63b85ffcd6f630fb9642305a3afd88da1a559ce50f1238b4b1ff8c8e573d1c8ab20bfd684e03f0
+  data.tar.gz: aa1020630d83aa95c83837c8d1aa14bd3e56a207d955de314892f1c8e247a3519ad7101f9b6d6f1a9dab8f3f535c92bb59ab11cd342245be8f777bbdb21a60d3

data/README.md

@@ -217,7 +217,8 @@ warm isolate — a per-visit reset that avoids rebuilding the VM. Its contract:
   (or to an empty realm, with no snapshot).
 - **Runtime mutations are dropped.** Anything set on the realm at runtime is gone.
 - **Host fns are dropped.** Functions `attach`/`attach_many`'d into the realm are
-  released (their GC roots freed); re-attach them after a reset.
+  released — the isolate stops holding them, so whatever they captured becomes
+  collectable; re-attach them after a reset.
 - **Modules and classic scripts are dropped.** Handles compiled in the realm die
   with the old context.
 - **The realm id and the shared same-origin token are preserved** — the id keeps
@@ -337,11 +338,37 @@ What happens next depends on what the stranded operation's Fiber does:
   The isolate cannot be disposed after that; it is leaked, with a warning saying
   why. If you still hold the Fiber, **`Fiber#kill` recovers it**: it resumes the
   Fiber to unwind it, so the stranded operation finishes in order and the isolate
-  goes back to normal. (The one thing that defeats that is a script which catches
-  the error the killed callback throws and carries on — the kill only lands once
-  that operation ends, just as it would wait out any Ruby call in progress, and
-  until then the script can call further host functions, which run on the
-  already-killed Fiber.)
+  goes back to normal. The operation itself fails on the way out — see below for
+  why a kill reaches it as an ordinary error.
+
+### Killing a thread or Fiber inside a host function
+
+**A `Thread#kill` or `Fiber#kill` that lands while a host function's Ruby is
+running does not kill it.** It surfaces as `RustyRacer::RuntimeError: Error:
+Fatal` from the `eval`/`call` that was in flight, and the thread keeps going —
+and CRuby has already marked that thread as killed, so **a second `Thread#kill`
+is a no-op**. `Thread#raise` still works, and is the way out if you have to
+reach in from outside.
+
+A kill inside a **module resolver** is quieter still: the specifier it was
+resolving simply fails to link, so the error names the import
+(`failed to resolve module specifier "./dep.js" imported from /app.js`) with no
+mention of a kill at all.
+
+This is not a choice, it is the boundary. Ruby unwinds a kill with `TAG_FATAL`,
+which arrives while V8's C++ frames are on the stack — and a `longjmp` through
+those is not survivable, so the callback has to catch it like any other error.
+Nor can it be put back afterwards: `rb_jump_tag` does not carry the unwind with
+it, it re-enters whatever the VM still holds in `$!`, and anything protected
+that ran in between (one more host function raising is enough) has cleared it.
+Jumping into that is a segfault in the interpreter rather than a late kill. 0.2.2
+shipped an attempt at this and had to be withdrawn in 0.2.3.
+
+So: if you need to stop work that calls into an isolate, **stop it at a Ruby
+boundary you control** — a flag the host function checks, a `Queue` it reads —
+rather than by killing the thread from outside. `Isolate#terminate` stops the
+*JavaScript* (at V8's next interrupt check, see above), which is the other half
+of the same job.
 
 ## Installation
 

data/ext/rusty_racer/Cargo.toml

@@ -5,12 +5,16 @@
 # links and loads with no custom archive.
 [package]
 name = "rusty_racer"
-version = "0.2.2"
+version = "0.2.4"
 edition = "2024"
 publish = false
 
+# cdylib: the standalone gem extension (.so Ruby loads directly).
+# lib (rlib): lets an embedder link rusty_racer as a Rust library and build its
+# own cdylib — capybara-simulated links rusty_racer + a native DOM into one
+# extension and calls rusty_racer::install_classes from its own magnus init.
 [lib]
-crate-type = ["cdylib"]
+crate-type = ["lib", "cdylib"]
 
 [dependencies]
 # rb-sys: exposes magnus::rb_sys (protect — catch a Ruby raise from a host

data/ext/rusty_racer/src/lib.rs

@@ -31,10 +31,29 @@
 // OUTERMOST op cancels a stale terminate so it can't poison the next op, while a
 // nested op's cancel never erases a termination aimed at the suspended outer JS.
 //
-// Attached procs and the dynamic-import resolver are GC-rooted via
-// rb_gc_register_address (see RootedProc): marked, so the extension may hold the
-// only reference, and pinned, so GC.compact cannot move them behind the
-// extension's back.
+// Attached procs and the dynamic-import resolver are kept alive by the ISOLATE'S
+// OWN ROOTS ARRAY (Core.roots), which every wrapper marks — never by a GC root.
+// A root would be a leak: a host fn closes over its embedder's world, and that
+// world reaches back to this isolate's wrappers, so rooting the proc roots the
+// whole cycle and mark-and-sweep can never break it (the wrapper's free would
+// then never run, and the procs would never be released — one un-disposable
+// isolate per embedder session). Marked from the wrappers instead, the cycle is
+// ordinary Ruby garbage. `mark` PINS each entry (GC.compact must not move them:
+// the copies living in Rust are invisible to the compactor and would go stale),
+// which an RArray's own movable marking would not do.
+//
+// Two things stay OUTSIDE that array, deliberately:
+//   - the owner Thread (_owner_root) keeps its rb_gc_register_address, because the
+//     guarantee it buys has to outlive the last wrapper: Core::drop compares the
+//     raw owner VALUE when no wrapper is left to mark anything, and a freed Thread
+//     slot reused by a live thread would be a false owner match (see RootedThread).
+//     It is not the cycle above — a Thread reaches back to an isolate only if the
+//     embedder parks its world in that thread's thread-local storage.
+//   - an isolate whose last wrapper is collected on a thread OTHER than its owner
+//     still cannot be disposed (V8 forbids it) and is counted leaked, as it always
+//     was — see Core::drop. Collection now happens where it never used to, so that
+//     counter reports cases it used to miss entirely; disposing explicitly on the
+//     owner thread is still the only way to free a foreign-owned isolate promptly.
 
 use std::cell::RefCell;
 use std::collections::HashMap;
@@ -44,9 +63,10 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, Once, Weak};
 
 use magnus::block::Proc;
-use magnus::value::{BoxValue, ReprValue};
+use magnus::value::{BoxValue, Opaque, ReprValue};
 use magnus::{
-    Error, Exception, ExceptionClass, RHash, Ruby, TryConvert, Value, function, method, prelude::*,
+    DataTypeFunctions, Error, Exception, ExceptionClass, RArray, RHash, Ruby, TryConvert,
+    TypedData, Value, function, gc, method, prelude::*,
 };
 
 mod marshal;
@@ -62,10 +82,14 @@ use watchdog::{
 
 // A Ruby Proc rooted for as long as the Core holds it. BoxValue registers a
 // stable heap address with rb_gc_register_address, which both MARKS the proc
-// (the extension may hold the only reference — e.g. attach("f", -> {...}))
 // and PINS it (GC.compact must not move it: the copies living in Rust are
 // invisible to the compactor and would go stale).
 //
+// Only for a proc the isolate holds TRANSIENTLY — today just the instantiate
+// resolver, parked in the slot for the length of one InstantiateModule op and
+// restored after it. Anything held for the isolate's LIFE goes in the roots
+// array instead (see the module header): a lasting root is a lasting leak.
+//
 // SAFETY of the manual Send: the !Send contents (and BoxValue's drop, which
 // calls rb_gc_unregister_address) only run under the GVL. Two conventions
 // keep that true — breaking either is silent UB, so don't:
@@ -122,13 +146,14 @@ macro_rules! istate {
 pub(crate) use istate;
 
 // One attach()'d host fn: the realm it was attached into — so resetting or
-// disposing that realm can release the GC root — the rooted proc itself (None
-// once released; the slot index stays valid as a host_fn_id), and the name it
-// was attached under, kept only so a diagnostic can say which host function is
-// involved (one String per attach, never per call).
+// disposing that realm can release it — whether it is still attached (the slot
+// index stays valid as a host_fn_id either way), and the name it was attached
+// under, kept only so a diagnostic can say which host function is involved (one
+// String per attach, never per call). The PROC itself lives in the roots array
+// at `proc_root_index(id)`, where the GC can see it without taking this lock.
 struct ProcSlot {
     context_id: i32,
-    proc: Option<RootedProc>,
+    live: bool,
     name: String,
 }
 
@@ -157,18 +182,33 @@ impl ProcTable {
     }
 
     // Release every live proc attached into |context_id| (its realm is gone),
-    // returning each slot to the free list. Idempotent: an already-released slot
-    // has proc == None and is skipped, so it can't be double-freed.
-    fn release(&mut self, context_id: i32) {
+    // returning their ids so the caller can clear their roots-array entries (a Ruby
+    // write, which this table never does: it is locked on paths a GC must not have to
+    // wait behind) and only THEN put them on the free list. Idempotent: an
+    // already-released slot is skipped, so it can't be double-freed.
+    fn release(&mut self, context_id: i32) -> Vec<usize> {
+        let mut released = Vec::new();
         for (id, slot) in self.slots.iter_mut().enumerate() {
-            if slot.context_id == context_id && slot.proc.is_some() {
-                slot.proc = None;
-                self.free.push(id);
+            if slot.context_id == context_id && slot.live {
+                slot.live = false;
+                released.push(id);
             }
         }
+        released
     }
 }
 
+// The isolate's ROOTS ARRAY: every Ruby object the isolate must keep alive for as
+// long as a wrapper of it is reachable, in one place the GC can be shown without
+// taking any Rust lock (a mark that had to lock `procs` could deadlock against
+// the thread whose allocation triggered the GC while holding it). Slot 0 is the
+// dynamic-import resolver; the attached host fns follow, one per host_fn_id.
+const ROOT_IMPORT_RESOLVER: isize = 0;
+const ROOT_FIRST_PROC: isize = 1;
+fn proc_root_index(host_fn_id: usize) -> isize {
+    ROOT_FIRST_PROC + host_fn_id as isize
+}
+
 // Look up a RustyRacer::<name> exception class at raise time. The classes are
 // defined in lib/rusty_racer.rb (loaded after this extension), so they exist
 // by the time any eval can raise. Falls back to Ruby's RuntimeError.
@@ -301,9 +341,9 @@ enum RubyCall<'a> {
 impl RubyCall<'_> {
     fn describe(&self, core: &Core) -> String {
         match self {
-            // try_lock, not lock: nothing holds this across a callback (call_proc
-            // takes the proc out under the lock and releases it before calling),
-            // but blocking here would turn a diagnostic into a hang.
+            // try_lock, not lock: nothing holds this across a callback (the procs
+            // themselves are read from the roots array, without this lock), but
+            // blocking here would turn a diagnostic into a hang.
             Self::HostFn(id) => match core
                 .procs
                 .try_lock()
@@ -472,19 +512,6 @@ fn current_ruby_thread() -> usize {
     unsafe { rb_sys::rb_thread_current() as usize }
 }
 
-// Identity of the calling FIBER, as its object_id — monotonic and never reused,
-// unlike the VALUE, which is a heap address a collected Fiber hands back (and a
-// Fiber stranded with a pending kill DOES get collected). Ids are a Fixnum on
-// every platform this gem ships for, so the usize compared is an immediate, not
-// a pointer that could alias in its turn. Assigning one can allocate, and this
-// runs with V8 frames live and outside any rb_protect of ours, so it takes its
-// own: 0 on failure, which reads as "no Fiber" at both ends and so drops a kill
-// rather than misdelivers one. MUST be called with the GVL held.
-fn current_fiber_id() -> usize {
-    magnus::rb_sys::protect(|| unsafe { rb_sys::rb_obj_id(rb_sys::rb_fiber_current()) })
-        .map_or(0, |id| id as usize)
-}
-
 // Reduce a magnus Error to a single Exception INSTANCE so it can be GC-rooted and
 // re-raised later WITH ITS ORIGINAL CLASS. A Ruby proc's raise is already an
 // instance; an Error::new(class, msg) from our own code becomes an instance of
@@ -560,7 +587,7 @@ fn host_fn_callback(
             ruby.qnil().as_raw()
         }) {
             Ok(_) => out.unwrap_or_else(|| Err("host function did not complete".into())),
-            Err(e) => Err(core.swallow(e)),
+            Err(e) => Err(format!("{e}")),
         }
     });
     match result {
@@ -1117,10 +1144,8 @@ fn resolve_imported<'s>(
             // calls into Ruby (so it can allocate, so it can GC) and BoxValue::new
             // registers a GC root — neither is safe with the GVL released.
             match with_gvl(core, RubyCall::Resolver(&spec), || {
-                resolve_module_via_ruby(core, resolve, &spec, &ref_url, None).map_err(|e| {
-                    core.note_fatal(&e);
-                    error_to_exception(&e).map(BoxValue::new)
-                })
+                resolve_module_via_ruby(core, resolve, &spec, &ref_url, None)
+                    .map_err(|e| error_to_exception(&e).map(BoxValue::new))
             }) {
                 Ok(id) => id,
                 // Stash the resolver's own raised exception (GC-rooted) so the
@@ -1133,18 +1158,12 @@ fn resolve_imported<'s>(
             }
         }
         None => {
-            let resolver = core
-                .dynamic_import_resolver
-                .lock()
-                .unwrap()
-                .as_ref()
-                .map(|r| r.get());
-            match resolver {
+            match core.dynamic_import_resolver() {
                 Some(p) => match with_gvl(core, RubyCall::Resolver(&spec), || {
                     resolve_module_via_ruby(core, p, &spec, &ref_url, Some(here.unwrap_or(0)))
                         // Rendering the message reads the Ruby exception, so it too
                         // stays inside with_gvl.
-                        .map_err(|e| core.swallow(e))
+                        .map_err(|e| e.to_string())
                 }) {
                     Ok(id) => id,
                     // Unlike the static branch there is no Ruby frame waiting to
@@ -1250,25 +1269,13 @@ fn dynamic_import_cb<'s>(
         return Some(promise);
     }
     let core = unsafe { &*core_ptr };
-    let resolver_proc = core
-        .dynamic_import_resolver
-        .lock()
-        .unwrap()
-        .as_ref()
-        .map(|r| r.get());
-    let id = match resolver_proc {
+    let id = match core.dynamic_import_resolver() {
         // A raising resolver only fails the import() (it rejects generically);
-        // it must NOT abort the surrounding eval, so swallow the Err here — but
-        // note_fatal first, since this is the one with_gvl site that throws its
-        // Err away and a Thread#kill would go with it.
+        // it must NOT abort the surrounding eval, so swallow the Err here.
         Some(p) => with_gvl(core, RubyCall::Resolver(&spec), || {
-            resolve_module_via_ruby(core, p, &spec, &referrer, Some(initiating)).unwrap_or_else(
-                |e| {
-                    core.note_fatal(&e);
-                    None
-                },
-            )
-        }),
+            resolve_module_via_ruby(core, p, &spec, &referrer, Some(initiating))
+        })
+        .unwrap_or(None),
         None => None,
     };
     match id {
@@ -1515,27 +1522,22 @@ struct Core {
     // op. Owner-thread only, like the isolate itself; AtomicUsize for shared
     // &Core access.
     installed_stack_limit: std::sync::atomic::AtomicUsize,
-    // Set when a callback's Ruby code unwound with TAG_FATAL — a Thread#kill —
-    // which magnus catches like any other error because a longjmp through V8's
-    // C++ frames is not survivable. Holds the object_id of the
-    // Fiber that must finish the kill (never a raw VALUE: a stranded Fiber
-    // holding a pending kill does get collected, and its address can then be
-    // handed to a new one, whereas an object_id is monotonic and never reused);
-    // 0 = nothing pending.
-    // See Core::note_fatal / Core::resume_pending_fatal. Atomic for the same
-    // reason as the rest: &Core is shared, though only the owner thread ever
-    // touches this.
-    pending_fatal: std::sync::atomic::AtomicUsize,
     // Re-entry depth for THIS isolate, readable without a scope (the runner needs
     // it to choose the scope kind before any scope exists): 0 = top-level op
     // (open a fresh HandleScope from iso_ptr); >0 = a host callback is on the V8
     // stack (bootstrap via callback_scope! onto the ambient scope). Bumped around
     // each `run`.
     depth: std::sync::atomic::AtomicU32,
-    // host_fn_id indexes ProcTable.slots. Mutex (uncontended — single owner
-    // thread) so host_fn_callback can reach it through Core (via the slot's
-    // core_ptr) while a &Core method also holds it. Each proc is GC-rooted while
-    // live — see RootedProc/ProcSlot; reset/dispose releases roots, recycles slots.
+    // Everything this isolate keeps alive on the Ruby side — the attached host fns
+    // and the dynamic-import resolver — in one Array the wrappers MARK (and pin).
+    // See the module header for why these must not be GC roots; ROOT_* for the
+    // layout. Read on the V8 side without the GVL (the import hooks), which is
+    // sound because the entries are pinned and nothing here allocates or raises.
+    roots: Opaque<RArray>,
+    // host_fn_id indexes ProcTable.slots — bookkeeping only (the proc itself is in
+    // `roots`). Mutex (uncontended — single owner thread) so host_fn_callback can
+    // reach it through Core (via the slot's core_ptr) while a &Core method also
+    // holds it. reset/dispose releases the slots and recycles them.
     procs: Mutex<ProcTable>,
     // Default per-eval/call timeout (ms); 0 = none. eval(timeout_ms:)'s explicit
     // value overrides it. Guards against an in-V8 infinite loop without a watchdog.
@@ -1547,9 +1549,6 @@ struct Core {
     // the ceiling after each OOM (to this when set, else V8's captured default — see
     // oom_initial_limit). Space-axis twin of default_timeout_ms.
     memory_limit: usize,
-    // Set by Context#dynamic_import_resolver=; called for a JS import() to map
-    // (specifier, referrer) to an already-loaded Module. GC-rooted like procs.
-    dynamic_import_resolver: Mutex<Option<RootedProc>>,
     // The watchdog (armed per timed op, fires TerminateExecution via the handle)
     // and its thread's join handle, held here so dispose/Drop — which run on the
     // owner thread with no scope — can stop and join it before the isolate drops.
@@ -1560,7 +1559,8 @@ struct Core {
 // The V8 isolate (one per Isolate): lifecycle + the isolate-level ops
 // (terminate, microtask checkpoint, dynamic import). eval/call/etc. live on
 // Context, which an Isolate hands out (a v8::Context).
-#[magnus::wrap(class = "RustyRacer::Isolate")]
+#[derive(TypedData)]
+#[magnus(class = "RustyRacer::Isolate", mark)]
 struct Isolate {
     core: Arc<Core>,
 }
@@ -1569,7 +1569,8 @@ struct Isolate {
 // extra one (id >= 1, via Isolate#create_context). eval/call/attach/
 // compile_module run here. Its own `disposed` is per-context; the Core's is
 // isolate-level.
-#[magnus::wrap(class = "RustyRacer::Context")]
+#[derive(TypedData)]
+#[magnus(class = "RustyRacer::Context", mark)]
 struct Context {
     core: Arc<Core>,
     id: i32,
@@ -1584,7 +1585,8 @@ struct Snapshot {
 }
 
 // Context#compile_module result: a handle to a V8 module (by id).
-#[magnus::wrap(class = "RustyRacer::Module")]
+#[derive(TypedData)]
+#[magnus(class = "RustyRacer::Module", mark)]
 struct JsModule {
     core: Arc<Core>,
     module_id: i32,
@@ -1596,7 +1598,8 @@ struct JsModule {
 }
 
 // Context#compile result: a handle to a classic compiled script (by id).
-#[magnus::wrap(class = "RustyRacer::Script")]
+#[derive(TypedData)]
+#[magnus(class = "RustyRacer::Script", mark)]
 struct Script {
     core: Arc<Core>,
     script_id: i32,
@@ -1605,11 +1608,49 @@ struct Script {
     cache_rejected: bool,
 }
 
+// The four wrappers that hold an Arc<Core> all mark the isolate's roots, because any
+// one of them may be the last one reachable: Ruby code is free to keep only the
+// Context a `Isolate#context` handed it, or only a Module, and the host fns must
+// stay callable through it. Marking the same array four times costs nothing (the GC
+// stops at an already-marked object); missing it once would free a live proc.
+macro_rules! marks_core_roots {
+    ($t:ty) => {
+        impl DataTypeFunctions for $t {
+            fn mark(&self, marker: &gc::Marker) {
+                self.core.mark_roots(marker);
+            }
+        }
+    };
+}
+marks_core_roots!(Isolate);
+marks_core_roots!(Context);
+marks_core_roots!(JsModule);
+marks_core_roots!(Script);
+
 // Set true once V8 is initialized; Platform.set_flags! refuses after that
 // (flags must be set before V8::initialize), like mini_racer's
 // PlatformAlreadyInitialized.
 static V8_INITED: AtomicBool = AtomicBool::new(false);
 
+// The shared default platform, kept so ops can pump its foreground task queue (see
+// `platform()` / op_pump_message_loop). V8 posts FinalizationRegistry cleanup — and other
+// deferred foreground work — as platform tasks that only run when the embedder pumps the
+// message loop; without a handle to the platform we could never drive them. The platform is
+// process-global and thread-safe by V8's own contract (it is shared across every isolate on
+// every owner thread), which is what makes the SharedRef sound to park in a `static`.
+struct SharedPlatform(v8::SharedRef<v8::Platform>);
+// SAFETY: v8's default platform is explicitly designed to be shared across isolates and their
+// owner threads; PumpMessageLoop is called per-isolate on that isolate's owner thread. The
+// SharedRef is a refcounted handle to that one shared object.
+unsafe impl Send for SharedPlatform {}
+unsafe impl Sync for SharedPlatform {}
+static PLATFORM: std::sync::OnceLock<SharedPlatform> = std::sync::OnceLock::new();
+
+// The shared platform, once V8 is initialized. `None` before init (no op can run then anyway).
+pub(crate) fn platform() -> Option<&'static v8::SharedRef<v8::Platform>> {
+    PLATFORM.get().map(|p| &p.0)
+}
+
 fn init_v8() {
     static ONCE: Once = Once::new();
     ONCE.call_once(|| {
@@ -1622,6 +1663,10 @@ fn init_v8() {
             Ordering::Relaxed,
         );
         let platform = v8::new_default_platform(0, false).make_shared();
+        // Keep a handle before handing ownership to V8, so ops can pump the foreground task
+        // queue (FinalizationRegistry cleanup etc.). make_shared yields a refcounted SharedRef;
+        // clone one into the static and give the other to V8.
+        let _ = PLATFORM.set(SharedPlatform(platform.clone()));
         v8::V8::initialize_platform(platform);
         v8::V8::initialize();
         V8_INITED.store(true, Ordering::SeqCst);
@@ -1959,8 +2004,22 @@ unsafe extern "C" fn promise_reject_cb(message: v8::PromiseRejectMessage) {
 // reset and create_context so realms can't drift apart. Returns the context
 // Global AND its dedicated microtask queue; the caller owns the queue in
 // V8State alongside the context (see V8State::queues for why per-realm).
+// An embedder-supplied hook run in every realm just after the host namespace is
+// installed, with the fresh realm's scope and context. Set once (OnceLock) by an
+// embedder that links rusty_racer as a library; None for standalone gem use. A
+// plain fn pointer so it stays Send + Sync with no allocation.
+pub type RealmInitHook = fn(&mut v8::PinScope<'_, '_, ()>, &v8::Global<v8::Context>, i32);
+static REALM_INIT_HOOK: std::sync::OnceLock<RealmInitHook> = std::sync::OnceLock::new();
+
+// Register the per-realm init hook. Idempotent-ish: the first call wins (later
+// calls are ignored), which suits a single embedder wiring it once at boot.
+pub fn set_realm_init_hook(hook: RealmInitHook) {
+    let _ = REALM_INIT_HOOK.set(hook);
+}
+
 fn new_realm(
     scope: &mut v8::PinScope<'_, '_, ()>,
+    context_id: i32,
 ) -> (v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>) {
     // Explicit policy like the isolate's: rusty drives every drain by hand
     // (auto_drain / NS.drainMicrotasks), so V8 must never auto-run this queue.
@@ -2012,6 +2071,15 @@ fn new_realm(
     if let Some(name) = host_namespace {
         install_host_namespace(scope, &fresh, &name);
     }
+    // Generic, DOM-agnostic extension seam: an embedder that links rusty_racer as a
+    // library can register one hook (set_realm_init_hook) to run native setup in
+    // every realm — including frame realms the engine creates internally. This is
+    // how capybara-simulated installs its native DOM without rusty_racer knowing
+    // anything about a DOM. Extension state lives in the embedder's OWN typed
+    // isolate slot (rusty_v8 slots are keyed by TypeId), never in IsolateState.
+    if let Some(hook) = REALM_INIT_HOOK.get() {
+        hook(scope, &fresh, context_id);
+    }
     (fresh, queue)
 }
 
@@ -2225,13 +2293,13 @@ impl Isolate {
     // Core keeps its id + a stable raw ptr so `run` can open scopes on it. The
     // isolate is thread-bound from here on (every op asserts the owner thread).
     fn new(
-        _ruby: &Ruby,
+        ruby: &Ruby,
         host_namespace: Option<String>,
         snapshot: Option<magnus::typed_data::Obj<Snapshot>>,
         timeout_ms: u64,
         memory_limit: usize,
         explicit_microtasks: bool,
-    ) -> Result<Self, Error> {
+    ) -> Result<magnus::typed_data::Obj<Self>, Error> {
         init_v8();
         // A snapshot blob bakes globalThis state in: the first Context::new (in
         // new_realm below) deserializes that default context for free.
@@ -2277,7 +2345,7 @@ impl Isolate {
         // namespace from the slot (seeded above).
         {
             v8::scope!(let scope, &mut isolate);
-            let (main_context, main_queue) = new_realm(scope);
+            let (main_context, main_queue) = new_realm(scope, 0);
             istate!(scope).realms.main_context = Some(main_context);
             istate!(scope).realms.main_queue = Some(main_queue);
             // The shared graveyard for retired realms' contexts (see V8State).
@@ -2307,6 +2375,10 @@ impl Isolate {
         // owner check.
         use magnus::rb_sys::{AsRawValue, FromRawValue};
         let owner_thread = unsafe { Value::from_raw(rb_sys::rb_thread_current()) };
+        // The roots array (see ROOT_IMPORT_RESOLVER): created empty, grown by the
+        // first attach. Nothing roots it — the wrappers mark it, so it lives
+        // exactly as long as this isolate is reachable from Ruby.
+        let roots = ruby.ary_new();
         let core = Arc::new_cyclic(|me| Core {
             me: me.clone(),
             shared: Mutex::new(Shared {
@@ -2319,12 +2391,11 @@ impl Isolate {
             iso_ptr,
             scan_start_field: std::sync::atomic::AtomicUsize::new(0),
             installed_stack_limit: std::sync::atomic::AtomicUsize::new(0),
-            pending_fatal: std::sync::atomic::AtomicUsize::new(0),
             depth: std::sync::atomic::AtomicU32::new(0),
+            roots: Opaque::from(roots),
             procs: Mutex::new(ProcTable::default()),
             default_timeout_ms: timeout_ms,
             memory_limit,
-            dynamic_import_resolver: Mutex::new(None),
             watchdog,
             watchdog_join: Mutex::new(Some(watchdog_join)),
         });
@@ -2347,7 +2418,14 @@ impl Isolate {
         // enter/exit stack (an out-of-order drop aborts). Instead each op enters
         // around its run (Core::run) and teardown re-enters just before drop.
         unsafe { (*core.iso_ptr.0).exit() };
-        Ok(Isolate { core })
+        // Wrap HERE rather than returning `Self` for magnus to wrap after this frame is
+        // gone: wrapping allocates, and until the wrapper exists the roots array is
+        // referenced only from the Arc<Core>'s malloc'd block, which Ruby does not scan.
+        // `black_box` keeps the local VALUE live across that allocation — where the
+        // conservative stack scan does reach it.
+        let wrapped = ruby.obj_wrap(Isolate { core });
+        std::hint::black_box(roots);
+        Ok(wrapped)
     }
 }
 
@@ -2580,58 +2658,10 @@ impl Core {
         }
     }
 
-    // Finish a Thread#kill that a callback had to swallow (see note_fatal). This
-    // is a longjmp — the same rb_jump_tag magnus performs for an Error::Jump
-    // handed back to it — so nothing between here and Ruby runs Drop, and it may
-    // only be called where no frame in between still owns anything that matters.
-    // That rules out the end of `run`: instantiate_module parks the op's resolver
-    // across the call and restores it afterwards, and skipping THAT would leave a
-    // dead op's resolver parked for a later dynamic import to call. The end of
-    // reply_value is past every such restore, and reaching it is what every
-    // operation that can run Ruby at all does.
-    //
-    // An operation that returns Err from `run` — only a panic, which poisons the
-    // isolate — doesn't reach it, and the kill is then dropped by whichever
-    // operation gets here next (see the Fiber check). Frames above still leak
-    // whatever they hold (an argument String, say), which is why every caller with
-    // cleanup of its own runs that cleanup BEFORE calling this.
-    fn resume_pending_fatal<T>(&self, outcome: Result<T, Error>) -> Result<T, Error> {
-        let pending = self.pending_fatal.swap(0, Ordering::SeqCst);
-        // Nothing pending — the case every op takes, and one atomic load.
-        if pending == 0 {
-            return outcome;
-        }
-        // A kill belongs to the Fiber whose callback swallowed it, and finishing
-        // it anywhere else would kill an unrelated caller — the main thread, say,
-        // mid-eval, with no exception and no message. A mismatch is an ordinary
-        // outcome, not a should-not-happen: when the script CATCHES the error the
-        // killed callback threw, that operation may never end, and the next one to
-        // get here is somebody else's. Drop the kill rather than deliver it to the
-        // wrong Fiber. (CRuby's own Fiber#kill bookkeeping still terminates such a
-        // Fiber on its next resume; only its return value is lost.)
-        if pending != current_fiber_id() {
-            return outcome;
-        }
-        drop(outcome);
-        // enum ruby_tag_type's RUBY_TAG_FATAL; not in rb_sys's bindings
-        // (bindgen skips the anonymous enum), and stable since 1.9.
-        const RUBY_TAG_FATAL: std::os::raw::c_int = 8;
-        unsafe { rb_sys::rb_jump_tag(RUBY_TAG_FATAL) };
-    }
-
     // Map a terminal reply to a Ruby value (the common eval/call/run shape).
     // &self so a Terminated outcome can pick up the JS stack the watchdog snapshot
     // captured (see timeout_interrupt / take_timeout_backtrace).
     fn reply_value(&self, ruby: &Ruby, reply: VmReply) -> Result<Value, Error> {
-        let outcome = self.reply_value_deferred(ruby, reply);
-        // Every operation that can run Ruby — and so can have a Thread#kill
-        // swallowed by one of its callbacks — ends here, except the few whose own
-        // cleanup has to run first; those call the two halves in order.
-        self.resume_pending_fatal(outcome)
-    }
-
-    // reply_value without finishing a swallowed kill.
-    fn reply_value_deferred(&self, ruby: &Ruby, reply: VmReply) -> Result<Value, Error> {
         match reply {
             VmReply::Done(Ok(val)) => jsval_to_ruby(ruby, &val),
             // Clone (don't take): a nested timeout's terminate unwinds the whole op
@@ -2659,74 +2689,67 @@ impl Core {
             .clone()
     }
 
-    // A Ruby error raised under a live op cannot be allowed to longjmp — it would
-    // cross V8's C++ frames — so every callback catches it and throws it into JS
-    // as a message instead. That is right for an exception and wrong for exactly
-    // one thing: Thread#kill unwinds with TAG_FATAL, which magnus catches like
-    // anything else, and a killed thread that is merely told about it in
-    // JavaScript is not killed at all — it goes on to run whatever comes next,
-    // while the op's caller is handed a fabricated `RustyRacer::RuntimeError:
-    // Error: Fatal`. Remember it here; Core::run re-asserts it the moment the op
-    // is over and there are no V8 frames left to cross, which is what magnus
-    // would have done with the jump if it could have.
-    //
-    // Only Fatal. The other jumps (a `break` or `next` out of a host proc) have
-    // no live block to return to by the time we could resume them, so they stay
-    // what they are today: an error on the JavaScript side.
-    //
-    // The kill lands at the END of the operation, not at the callback: the
-    // callback still has to return through V8, and what it returns is an ordinary
-    // JavaScript exception, which the script may catch and carry on from — during
-    // which it can call further host functions, running Ruby on the already-killed
-    // thread.
-    //
-    // Terminating the isolate here to make that uncatchable was tried and
-    // REJECTED, for a reason worth writing down because the obvious objection is
-    // the wrong one. V8 does see it: a termination requested from inside a host
-    // callback survives the callback and is observed at the next interrupt check,
-    // which is any JavaScript function entry or a loop long enough to exhaust
-    // Ignition's interrupt budget — only a degenerate tail of host calls and
-    // literals escapes. The problem is what happens when it escapes: the request
-    // stays ARMED, and the sweep that clears a stale one runs only at an outermost
-    // request (see service_request), which is exactly what a stranded operation
-    // leaves the isolate without. It would then terminate an unrelated later
-    // operation, which is a worse failure than the one being fixed — and it does
-    // not even close the window it was for, since a script looping on host calls
-    // alone reaches no interrupt check either.
-    fn note_fatal(&self, e: &Error) {
-        if !matches!(
-            e.error_type(),
-            magnus::error::ErrorType::Jump(magnus::error::Tag::Fatal)
-        ) {
-            return;
+    // ── the roots array (see the module header + ROOT_IMPORT_RESOLVER) ──────
+    // Keep `val` alive for as long as this isolate is reachable from Ruby. On a
+    // Ruby thread with the GVL: storing can grow the Array, which allocates.
+    fn root_store<T: magnus::IntoValue>(
+        &self,
+        ruby: &Ruby,
+        index: isize,
+        val: T,
+    ) -> Result<(), Error> {
+        ruby.get_inner(self.roots).store(index, val)
+    }
+
+    // One entry, or None where nothing is stored (an unset resolver, a released
+    // host fn). Reads the Array WITHOUT the GVL — V8 calls the import hooks with it
+    // released — so it must not run one line of Ruby: `rb_ary_entry` plus
+    // `Proc::from_value` (rb_obj_is_proc) and nothing else. NOT `RArray::entry`,
+    // whose TryConvert would answer a nil slot by CALLING `nil.to_proc`, raising
+    // NoMethodError and rescuing it — Ruby code, an allocation and a longjmp, with
+    // no GVL held (measured: it corrupts the VM — "[BUG] unexpected situation" then
+    // a SEGV — under any concurrent Ruby thread). The entries are pinned by
+    // `mark_roots`, so the VALUE stays put until the caller has it under the GVL.
+    fn root_proc(&self, index: isize) -> Option<Proc> {
+        let roots = unsafe { Ruby::get_unchecked() }.get_inner(self.roots);
+        Proc::from_value(roots.entry::<Value>(index).ok()?)
+    }
+
+    // Show the GC everything this isolate holds. Called from EVERY wrapper's mark
+    // (Isolate, Context, Module, Script all keep an Arc<Core>, and any one of them
+    // may be the last reachable): a wrapper that forgot to would leave a live
+    // isolate's host fns unmarked. `mark` PINS — an Array marks its own elements
+    // MOVABLE, and the copies Rust takes out of it (call_proc, root_proc) would go
+    // stale if the compactor moved one. Takes no Rust lock, by construction.
+    fn mark_roots(&self, marker: &gc::Marker) {
+        let roots = unsafe { Ruby::get_unchecked() }.get_inner(self.roots);
+        marker.mark(roots);
+        // Entry by entry, exactly — not `mark_slice`, whose rb_gc_mark_locations is
+        // CONSERVATIVE (it tests each word for heap-likeness) and measured no faster
+        // here. The walk is O(entries) per wrapper per GC, MINOR GCs included (these
+        // wrappers are not wb_protected, so they are marked every time): measured
+        // 2026-09-13 with 600 procs, ~0.1 ms per GC at the 18 wrappers a real embedder
+        // session holds (capybara-simulated: 1 Isolate + 17 Contexts), ~3 ms at 500. If
+        // that ever bites, the fix is for the derived wrappers to mark the ISOLATE'S
+        // Ruby object and let its own mark walk the array once — which needs Core to
+        // hold that object (an Opaque<Value> nothing stores today), not just a rewrite
+        // of this loop.
+        for i in 0..roots.len() {
+            if let Ok(v) = roots.entry::<Value>(i as isize) {
+                marker.mark(v);
+            }
         }
-        // Which Fiber has to finish the kill: this one, the one the killed
-        // callback was running on. Checked again at the other end, so a pending
-        // kill can never land on an unrelated caller.
-        self.pending_fatal
-            .store(current_fiber_id(), Ordering::SeqCst);
-    }
-
-    // note_fatal + the message the callback will throw, for the map_err sites.
-    // Rendering is safe to do here, outside any rb_protect with V8 frames live:
-    // magnus formats an exception from its class name and address rather than
-    // calling #message or #inspect, so a caller whose own class raises from those
-    // (checked) cannot longjmp out of this.
-    fn swallow(&self, e: Error) -> String {
-        self.note_fatal(&e);
-        e.to_string()
     }
 
     fn call_proc(&self, ruby: &Ruby, host_fn_id: usize, args: &[JsVal]) -> Result<JsVal, String> {
-        let proc = {
-            let procs = self.procs.lock().unwrap();
-            procs
-                .slots
-                .get(host_fn_id)
-                .and_then(|slot| slot.proc.as_ref())
-                .ok_or("unknown host function")?
-                .get()
-        };
+        // Straight from the roots array — a released (or never-attached) id reads
+        // back nil, which is the same "unknown host function" the slot table would
+        // have reported, so the hot path takes no lock at all. `root_proc` and not
+        // `RArray::entry`, for the reason given there: a nil slot must answer None,
+        // never dispatch `to_proc` and raise.
+        let proc = self
+            .root_proc(proc_root_index(host_fn_id))
+            .ok_or("unknown host function")?;
         // Marshal into a Ruby Array, NOT a Vec<Value>: bare Values in a heap Vec
         // are hidden from Ruby's GC mark phase (magnus's own RArray::to_vec doc
         // spells this out). With several args, once arg N is parked in the Vec
@@ -2738,16 +2761,16 @@ impl Core {
         let ruby_args = ruby.ary_new_capa(args.len());
         for v in args {
             ruby_args
-                .push(jsval_to_ruby(ruby, v).map_err(|e| self.swallow(e))?)
-                .map_err(|e| self.swallow(e))?;
+                .push(jsval_to_ruby(ruby, v).map_err(|e| e.to_string())?)
+                .map_err(|e| e.to_string())?;
         }
         // SAFETY: ruby_args is a live local (so GC keeps it and its elements) and
         // is not mutated while the slice is borrowed — as_slice's contract. A VM
         // op the proc issues re-enters Core::run (depth > 0) directly — no nested
         // frame bookkeeping is needed any more (the call stack IS the nesting).
         let result: Result<Value, Error> = proc.call(unsafe { ruby_args.as_slice() });
-        let value = result.map_err(|e| self.swallow(e))?;
-        ruby_to_jsval(value).map_err(|e| self.swallow(e))
+        let value = result.map_err(|e| e.to_string())?;
+        ruby_to_jsval(value).map_err(|e| e.to_string())
     }
 
     // Context#call (and call_void). Resolves a dotted function path
@@ -2833,6 +2856,23 @@ impl Core {
         Ok(())
     }
 
+    // Isolate#pump_message_loop: run every pending foreground platform task, without blocking.
+    // These are the deferred tasks V8 posts to the platform's task runner rather than running
+    // inline — most importantly FinalizationRegistry cleanup callbacks (posted after a GC finds a
+    // registered target dead) and WeakRef clearing. A pure microtask checkpoint does NOT drive
+    // them; only pumping the message loop does. Returns nothing; safe to call any time (a no-op
+    // when the queue is empty).
+    fn pump_message_loop(&self, ruby: &Ruby) -> Result<(), Error> {
+        let reply = self.run(
+            ruby,
+            Request::PumpMessageLoop {
+                timeout_ms: self.default_timeout_ms,
+            },
+        )?;
+        self.reply_value(ruby, reply)?;
+        Ok(())
+    }
+
     fn eval_t(
         &self,
         ruby: &Ruby,
@@ -2862,11 +2902,16 @@ impl Core {
         name: String,
         proc: Proc,
     ) -> Result<Value, Error> {
+        // BEFORE the roots write, not just inside `run` below: storing can REALLOC the
+        // array's element storage, which the import hooks read with the GVL released —
+        // and a refused attach must not consume a slot or leave its proc rooted either.
+        self.ensure_owner_and_live(ruby)?;
         let host_fn_id = self.procs.lock().unwrap().alloc(ProcSlot {
             context_id,
-            proc: Some(RootedProc(BoxValue::new(proc))),
+            live: true,
             name: name.clone(),
         });
+        self.root_store(ruby, proc_root_index(host_fn_id), proc)?;
         let reply = self.run(
             ruby,
             Request::Attach {
@@ -2895,20 +2940,31 @@ impl Core {
         if entries.is_empty() {
             return Ok(ruby.qnil().as_value()); // nothing to install, skip the round-trip
         }
-        let named_ids: Vec<(String, usize)> = {
+        self.ensure_owner_and_live(ruby)?; // before the roots writes — see `attach`
+        let allocated: Vec<(String, usize, Proc)> = {
             let mut procs = self.procs.lock().unwrap();
             entries
                 .into_iter()
                 .map(|(name, proc)| {
                     let id = procs.alloc(ProcSlot {
                         context_id,
-                        proc: Some(RootedProc(BoxValue::new(proc))),
+                        live: true,
                         name: name.clone(),
                     });
-                    (name, id)
+                    (name, id, proc)
                 })
                 .collect()
         };
+        // Stored OUTSIDE the table's lock: storing into the array can allocate (the
+        // Array grows), and an allocation may GC — which marks through this isolate's
+        // wrappers, a path that must never wait on `procs`. The Procs parked in the
+        // Vec meanwhile are invisible to the GC (see call_proc's note), but the caller's
+        // `table: RHash` argument is live in its own frame and marks every one of them.
+        let mut named_ids: Vec<(String, usize)> = Vec::with_capacity(allocated.len());
+        for (name, id, proc) in allocated {
+            self.root_store(ruby, proc_root_index(id), proc)?;
+            named_ids.push((name, id));
+        }
         let reply = self.run(
             ruby,
             Request::AttachMany {
@@ -2920,31 +2976,29 @@ impl Core {
         self.reply_value(ruby, reply)
     }
 
-    // Release the GC roots of the procs attached into |context_id| — its
-    // realm is gone (reset or disposed), so the V8-side functions that
-    // referenced them are unreachable. Runs on a Ruby thread (a RootedProc
-    // drop unregisters its GC address). The slots stay: host_fn_ids of other
-    // realms are indices into the same Vec.
-    fn release_context_procs(&self, context_id: i32) {
-        self.procs.lock().unwrap().release(context_id);
+    // Drop the procs attached into |context_id| out of the roots array — its
+    // realm is gone (reset or disposed), so the V8-side functions that referenced
+    // them are unreachable, and holding them would keep the embedder's world alive
+    // for the rest of the isolate's life. Runs on a Ruby thread: it writes nil
+    // into the Array. The slots stay: host_fn_ids of other realms are indices into
+    // the same Vec.
+    fn release_context_procs(&self, ruby: &Ruby, context_id: i32) {
+        // Nil the entries BEFORE the ids go back on the free list, so no attach can
+        // ever be handed an id whose old proc is still in the array.
+        let released = self.procs.lock().unwrap().release(context_id);
+        for &id in &released {
+            let _ = self.root_store(ruby, proc_root_index(id), ruby.qnil());
+        }
+        self.procs.lock().unwrap().free.extend(released);
     }
 
     fn reset(&self, ruby: &Ruby, context_id: i32) -> Result<Value, Error> {
         let reply = self.run(ruby, Request::Reset { context_id })?;
-        // reply_value_deferred, not reply_value: releasing the procs has to happen
-        // before a swallowed kill is finished, or the jump skips it and this
-        // realm's procs stay GC-rooted and their slots unrecycled for the life of
-        // the isolate — a permanent leak in a process that goes on running, since
-        // a killed FIBER leaves its thread alive.
-        let out = self.reply_value_deferred(ruby, reply);
+        let out = self.reply_value(ruby, reply)?;
         // Only on success — a refused reset (unknown/suspended realm) keeps
-        // its attached fns callable. No `?`: BOTH arms have to reach
-        // resume_pending_fatal, or a kill swallowed during a reset that then
-        // fails is left for some later operation, which drops it.
-        if out.is_ok() {
-            self.release_context_procs(context_id);
-        }
-        self.resume_pending_fatal(out)
+        // its attached fns callable.
+        self.release_context_procs(ruby, context_id);
+        Ok(out)
     }
 
     // Build a new context; returns its id (replied as an Int).
@@ -2956,12 +3010,9 @@ impl Core {
 
     fn dispose_context(&self, ruby: &Ruby, context_id: i32) -> Result<(), Error> {
         let reply = self.run(ruby, Request::DisposeContext { context_id })?;
-        // Deferred, and both arms delivered, for the same reasons as reset's.
-        let out = self.reply_value_deferred(ruby, reply);
-        if out.is_ok() {
-            self.release_context_procs(context_id);
-        }
-        self.resume_pending_fatal(out.map(|_| ()))
+        self.reply_value(ruby, reply)?;
+        self.release_context_procs(ruby, context_id);
+        Ok(())
     }
 
     // Thin ESM primitives. compile_module returns the new module's id.
@@ -3038,10 +3089,7 @@ impl Core {
         // Reclaim THIS op's resolver error and restore the outer op's pair.
         let (_, resolver_err) = self.swap_instantiate(saved_resolve, saved_err);
         if let Some(exc) = resolver_err {
-            // Through resume_pending_fatal like the tail below: this return is
-            // just as much the end of the op, and skipping it would leave a
-            // swallowed kill for some later op to assert.
-            return self.resume_pending_fatal(Err(Error::from(*exc)));
+            return Err(Error::from(*exc));
         }
         self.reply_value(ruby, reply?)
     }
@@ -3140,10 +3188,18 @@ impl Core {
         code_cache_from_reply(ruby, reply)
     }
 
-    fn set_dynamic_import_resolver(&self, proc: Proc) {
-        // The old RootedProc (if any) drops here, unregistering its address —
-        // we are on a Ruby thread, so that's GVL-safe.
-        *self.dynamic_import_resolver.lock().unwrap() = Some(RootedProc(BoxValue::new(proc)));
+    // Owner-thread only, like every other writer of the roots array (`attach`,
+    // `attach_many`, `dispose`): the store can REALLOC the array's element storage, and
+    // the import hooks read that storage with the GVL released.
+    fn set_dynamic_import_resolver(&self, ruby: &Ruby, proc: Proc) -> Result<(), Error> {
+        self.ensure_owner_and_live(ruby)?;
+        self.root_store(ruby, ROOT_IMPORT_RESOLVER, proc)
+    }
+
+    // The resolver, or None if none was set. Read on the V8 side without the GVL —
+    // see root_proc.
+    fn dynamic_import_resolver(&self) -> Option<Proc> {
+        self.root_proc(ROOT_IMPORT_RESOLVER)
     }
 
     // Terminate whatever is running. IsolateHandle is Send + refcounted —
@@ -3174,12 +3230,16 @@ impl Core {
         // it entered, and OwnedIsolate's Drop asserts `self == GetCurrent()`
         // (then exits). Between ops the isolate is exited, so we must enter here.
         unsafe { (*self.iso_ptr.0).enter() };
+        // Only the Rust-side bookkeeping. Clearing the roots ARRAY here would be
+        // pointless work: teardown also runs from Core::drop, and by then the array
+        // is garbage itself — the last wrapper marking it is exactly what went away.
+        // `dispose` clears it explicitly instead, for the isolate the caller disposes
+        // but keeps a handle to.
         {
             let mut procs = self.procs.lock().unwrap();
             procs.slots.clear();
             procs.free.clear();
         }
-        *self.dynamic_import_resolver.lock().unwrap() = None;
         {
             let st = istate!(unsafe { &mut *self.iso_ptr.0 });
             st.realms = V8State::default();
@@ -3228,6 +3288,10 @@ impl Core {
             shared.disposed = true;
         }
         self.teardown();
+        // Release the host fns NOW rather than when the wrappers are collected: a
+        // disposed isolate can never call one again, and each closes over as much
+        // of the embedder's world as it happens to capture.
+        let _ = ruby.get_inner(self.roots).clear();
         Ok(())
     }
 }
@@ -3266,7 +3330,7 @@ impl Drop for Core {
                  so it cannot be disposed and is leaked.\n\
                  The usual cause is a host function that yielded out of a Fiber \
                  which was never resumed;\n\
-                 `Fiber#kill` unwinds one cleanly if you still hold it. See\n\
+                 `Fiber#kill` recovers one if you still hold it. See\n\
                  https://github.com/ursm/rusty_racer#fibers\n"
             );
             LEAKED_ISOLATES.fetch_add(1, Ordering::Relaxed);
@@ -3343,9 +3407,15 @@ impl Isolate {
     fn low_memory_notification(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
         rb_self.core.low_memory_notification(ruby)
     }
+    // Isolate#pump_message_loop: run pending foreground platform tasks (FinalizationRegistry
+    // cleanup callbacks and WeakRef clearing among them), without blocking. Pair it with a GC
+    // (low_memory_notification) or call it periodically so weak-collection callbacks actually fire.
+    fn pump_message_loop(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self.core.pump_message_loop(ruby)
+    }
     // dynamic_import_resolver = ->(specifier, referrer_url) { module } for import().
-    fn set_dynamic_import_resolver(rb_self: &Self, proc: Proc) {
-        rb_self.core.set_dynamic_import_resolver(proc);
+    fn set_dynamic_import_resolver(ruby: &Ruby, rb_self: &Self, proc: Proc) -> Result<(), Error> {
+        rb_self.core.set_dynamic_import_resolver(ruby, proc)
     }
     fn dispose(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
         rb_self.core.dispose(ruby)
@@ -3851,6 +3921,16 @@ fn resolve_module_via_ruby(
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    install_classes(ruby)
+}
+
+// Define the RustyRacer::* Ruby classes/modules. Split out of the magnus init so
+// an embedder that links rusty_racer as a LIBRARY (rather than loading its gem
+// .so) can build its own cdylib and call this from its own `#[magnus::init]` —
+// e.g. capybara-simulated, which links rusty_racer + a native DOM into one
+// extension. Standalone gem use goes through `init` above; both define the exact
+// same surface.
+pub fn install_classes(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("RustyRacer")?;
 
     // The isolate (VM) + its isolate-level ops; hands out Contexts.
@@ -3874,6 +3954,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "low_memory_notification",
         method!(Isolate::low_memory_notification, 0),
     )?;
+    isolate.define_method("pump_message_loop", method!(Isolate::pump_message_loop, 0))?;
     isolate.define_method("dispose", method!(Isolate::dispose, 0))?;
     isolate.define_method("disposed?", method!(Isolate::disposed, 0))?;
 

data/ext/rusty_racer/src/ops.rs

@@ -184,6 +184,13 @@ pub(crate) enum Request {
     // near-heap-limit callback, and tells reclaimable garbage apart from a real
     // leak (memory that survives this is genuinely retained).
     LowMemoryNotification,
+    // Run pending foreground platform tasks (Platform::PumpMessageLoop) without blocking —
+    // the deferred work V8 posts to its task runner rather than running inline, most
+    // importantly FinalizationRegistry cleanup callbacks (arbitrary JS, so time-capped by
+    // timeout_ms). Realm-independent.
+    PumpMessageLoop {
+        timeout_ms: u64,
+    },
 }
 
 // compile_module result: the module's id plus any produced bytecode cache and
@@ -439,7 +446,8 @@ fn request_realm(state: &IsolateState, request: &Request) -> Option<i32> {
         | Request::ScriptCodeCache { .. }
         | Request::ModuleCodeCache { .. }
         | Request::HeapStatistics
-        | Request::LowMemoryNotification => None,
+        | Request::LowMemoryNotification
+        | Request::PumpMessageLoop { .. } => None,
     }
 }
 
@@ -544,6 +552,7 @@ fn dispatch_one(
         Request::ModuleCodeCache { module_id } => op_module_code_cache(scope, module_id),
         Request::HeapStatistics => op_heap_statistics(scope),
         Request::LowMemoryNotification => op_low_memory_notification(scope),
+        Request::PumpMessageLoop { timeout_ms } => op_pump_message_loop(scope, timeout_ms),
     }
 }
 
@@ -571,6 +580,38 @@ fn op_low_memory_notification(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
     VmReply::Done(Ok(JsVal::Undefined))
 }
 
+// Drain the platform's foreground task queue: run every pending task, then stop (never blocks
+// waiting for work). This is what actually fires FinalizationRegistry cleanup callbacks — V8
+// posts them here after a GC finds a registered target dead, and PerformMicrotaskCheckpoint does
+// NOT run them. Runs on the isolate's owner thread, with the isolate entered (the cleanup task
+// enters the target's realm itself). A no-op when the platform is uninitialized or the queue empty.
+//
+// A cleanup callback is ARBITRARY user JS, so it gets the same bracket every other JS-running op has:
+// a watchdog time-caps a runaway (`while(true){}`) callback and makes it terminable, and the
+// `pump_message_loop(…, false)` loop stays bounded because a fired terminate blocks further JS. After
+// the tasks run, a microtask checkpoint drains any microtasks they queued (a promise reaction), so
+// cleanup-triggered continuations settle in this op — matching the binding's auto-microtask model.
+fn op_pump_message_loop(scope: &mut v8::PinScope<'_, '_, ()>, timeout_ms: u64) -> VmReply {
+    let watchdog = arm_watchdog(scope, timeout_ms);
+    if let Some(platform) = crate::platform() {
+        while v8::Platform::pump_message_loop(platform, scope, false) {}
+    }
+    if let Some(ctx) = context_for(istate!(scope), 0) {
+        let context = v8::Local::new(scope, &ctx);
+        let scope = &mut v8::ContextScope::new(scope, context);
+        checkpoint_draining(scope);
+    }
+    let fired = disarm_watchdog(scope, watchdog);
+    if fired {
+        istate!(scope).watchdog_fired = true;
+    }
+    VmReply::Done(if fired {
+        Err(VmError::Terminated)
+    } else {
+        Ok(JsVal::Undefined)
+    })
+}
+
 #[allow(clippy::too_many_arguments)]
 fn op_eval(
     scope: &mut v8::PinScope<'_, '_, ()>,
@@ -775,7 +816,7 @@ fn op_reset(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) -> VmReply {
             "cannot reset a realm while a request for it is suspended on the V8 stack".into(),
         )))
     } else {
-        let (fresh, fresh_queue) = new_realm(scope);
+        let (fresh, fresh_queue) = new_realm(scope, context_id);
         {
             let realms = &mut istate!(scope).realms;
             // Swap in the fresh realm and PARK the old context + queue in
@@ -812,7 +853,7 @@ fn op_create_context(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
         realms.next_context_id += 1;
         id
     };
-    let (fresh, fresh_queue) = new_realm(scope);
+    let (fresh, fresh_queue) = new_realm(scope, id);
     istate!(scope).realms.contexts.insert(id, fresh);
     istate!(scope).realms.queues.insert(id, fresh_queue);
     VmReply::Done(Ok(JsVal::Int(id as i64)))

data/lib/rusty_racer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RustyRacer
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

data/lib/rusty_racer.rb

@@ -14,10 +14,18 @@ require_relative "rusty_racer/version"
 # flat fallback.
 versioned = "rusty_racer/#{RUBY_VERSION[/\d+\.\d+/]}/rusty_racer"
 
-if File.exist?(File.join(__dir__, "#{versioned}.#{RbConfig::CONFIG['DLEXT']}"))
-  require_relative versioned
-else
-  require "rusty_racer/rusty_racer"
+# Skip the native load when an embedder has already defined the classes. Linking
+# rusty_racer as a library into another extension's cdylib (e.g.
+# capybara-simulated, which bundles rusty_racer + its native DOM) calls
+# install_classes from that extension's own init; loading this gem's separate .so
+# on top would put a SECOND V8 runtime in the process (unsound). This file is then
+# required only for the pure-Ruby API wrappers below.
+unless defined?(RustyRacer::Isolate)
+  if File.exist?(File.join(__dir__, "#{versioned}.#{RbConfig::CONFIG['DLEXT']}"))
+    require_relative versioned
+  else
+    require "rusty_racer/rusty_racer"
+  end
 end
 
 module RustyRacer
@@ -99,10 +107,11 @@ module RustyRacer
     # the binding's job (V8's host contract), and static imports met while linking
     # resolve through this same block (also with the realm as the 3rd arg).
     # (Module#instantiate's own resolve block keeps its 2-arg form.)
-    # Held in an ivar so the proc stays alive for the isolate's lifetime (the
-    # native side only keeps a weak handle).
+    # The native side keeps the proc alive itself (in the isolate's roots array,
+    # marked by its wrappers), so it is NOT held in an ivar here: that second
+    # reference would outlive `dispose`, which exists to drop whatever the resolver
+    # captured the moment the isolate can no longer call it.
     def dynamic_import_resolver=(resolver)
-      @dynamic_import_resolver = resolver
       _set_dynamic_import_resolver(resolver)
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Keita Urashima
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -54,7 +54,7 @@ metadata:
   source_code_uri: https://github.com/ursm/rusty_racer
   bug_tracker_uri: https://github.com/ursm/rusty_racer/issues
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Embed V8 in Ruby via rusty_v8 + Magnus (rb-sys)
 test_files: []