rusty_racer 0.2.4 → 0.2.6

data/ext/rusty_racer/src/lib.rs

@@ -59,7 +59,7 @@ use std::cell::RefCell;
 use std::collections::HashMap;
 use std::ffi::c_void;
 use std::ptr::null_mut;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex, Once, Weak};
 
 use magnus::block::Proc;
@@ -72,7 +72,7 @@ use magnus::{
 mod marshal;
 use marshal::{JsVal, js_to_jsval, jsval_to_js, jsval_to_ruby, ruby_to_jsval};
 mod ops;
-use ops::{Compiled, Request, VmReply, run_source, service_request};
+use ops::{Compiled, Completion, Request, VmReply, run_source, service_request};
 mod stack;
 use stack::{STACK_DEBUG, StackScope, current_real_isolate, discover_scan_start_field};
 mod watchdog;
@@ -93,8 +93,8 @@ use watchdog::{
 // 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:
-//   - Arc<Core> lives ONLY in the four TypedData wrappers (Isolate, Context,
-//     Module, Script). Never clone it into the V8/watchdog threads, or the
+//   - Arc<Core> lives ONLY in the five TypedData wrappers (Isolate, Context,
+//     Module, Script, Function). Never clone it into the V8/watchdog threads, or the
 //     last drop could run off a Ruby thread.
 //   - the wrappers must not set free_immediately: their dfree (and so Core's
 //     drop) has to run outside the GC sweep, where Ruby APIs are forbidden.
@@ -146,23 +146,58 @@ 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 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.
+// disposing that realm can release it — whether it is still attached, which
+// occupant of the slot it is (`HostFnKey`), 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(index)`, where the GC can see it without taking this lock.
 struct ProcSlot {
     context_id: i32,
     live: bool,
+    generation: u32,
     name: String,
 }
 
-// The isolate's host-fn registry, indexed by host_fn_id. `free` lists slots
+// What a host function's V8 External carries: its slot, and the slot's generation
+// when it was attached. A slot is reused once its realm is released, but a function
+// of that realm can outlive the release — the embedder may still hold its document
+// — so a call has to prove it is the slot's CURRENT occupant, or it would run
+// whichever proc the slot was handed to next.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub(crate) struct HostFnKey {
+    index: u32,
+    generation: u32,
+}
+
+impl HostFnKey {
+    // (…both halves in one pointer-sized word: V8 builds for 64-bit targets alone.
+    // The word is stored as is only while V8's sandbox is off — the v8 crate's
+    // opt-in `v8_enable_sandbox`, which this crate leaves off; a sandboxed External
+    // goes through a pointer table that keeps tags in the high bits.)
+    pub(crate) fn to_external(self) -> *mut c_void {
+        const { assert!(usize::BITS >= 64) };
+        (((self.generation as u64) << 32) | self.index as u64) as usize as *mut c_void
+    }
+
+    fn from_external(value: *mut c_void) -> Self {
+        let value = value as usize as u64;
+        Self {
+            index: value as u32,
+            generation: (value >> 32) as u32,
+        }
+    }
+
+    fn index(self) -> usize {
+        self.index as usize
+    }
+}
+
+// The isolate's host-fn registry, indexed by HostFnKey::index. `free` lists slots
 // emptied by release_context_procs so a later attach reuses them instead of
 // growing `slots` forever — a long-lived process that re-navigates iframe
-// realms would otherwise leak one slot per attach. Reuse is safe because a slot
-// is only freed when its realm (and the V8 functions that carried its id) is
-// gone, so no stale V8 external can still call a recycled id.
+// realms would otherwise leak one slot per attach. A reused slot's generation
+// moves on, so a function of the released realm that is still reachable calls
+// a key the table no longer answers (`current`) instead of the new occupant.
 #[derive(Default)]
 struct ProcTable {
     slots: Vec<ProcSlot>,
@@ -170,17 +205,39 @@ struct ProcTable {
 }
 
 impl ProcTable {
-    // Take a free slot if one exists, else grow. Returns the host_fn_id.
-    fn alloc(&mut self, slot: ProcSlot) -> usize {
-        if let Some(id) = self.free.pop() {
-            self.slots[id] = slot;
-            id
-        } else {
-            self.slots.push(slot);
-            self.slots.len() - 1
+    // Take a free slot if one exists, its generation the next, else grow.
+    fn alloc(&mut self, context_id: i32, name: String) -> HostFnKey {
+        let (index, generation) = match self.free.pop() {
+            Some(index) => (index, self.slots[index].generation.wrapping_add(1)),
+            None => {
+                self.slots.push(ProcSlot {
+                    context_id,
+                    live: false,
+                    generation: 0,
+                    name: String::new(),
+                });
+                (self.slots.len() - 1, 0)
+            }
+        };
+        self.slots[index] = ProcSlot {
+            context_id,
+            live: true,
+            generation,
+            name,
+        };
+        HostFnKey {
+            index: index as u32,
+            generation,
         }
     }
 
+    // Whether `key` is its slot's live occupant.
+    fn current(&self, key: HostFnKey) -> bool {
+        self.slots
+            .get(key.index())
+            .is_some_and(|slot| slot.live && slot.generation == key.generation)
+    }
+
     // Release every live proc attached into |context_id| (its realm is gone),
     // 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
@@ -202,11 +259,11 @@ impl ProcTable {
 // 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.
+// dynamic-import resolver; the attached host fns follow, one per proc slot.
 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
+fn proc_root_index(index: usize) -> isize {
+    ROOT_FIRST_PROC + index as isize
 }
 
 // Look up a RustyRacer::<name> exception class at raise time. The classes are
@@ -221,16 +278,23 @@ fn err_class(ruby: &Ruby, name: &str) -> ExceptionClass {
 
 #[derive(Debug)]
 enum VmError {
-    Parse(String),   // compile-time failure -> RustyRacer::ParseError
+    // compile-time failure -> RustyRacer::ParseError; the SyntaxError V8 made of
+    // it kept as for a JsError (`keep_thrown`)
+    Parse(String, Option<u64>),
     Runtime(String), // internal failure (no JS stack) -> RustyRacer::RuntimeError
     // A thrown JS exception: its message plus the JS stack frames, which become
-    // the Ruby exception's backtrace -> RustyRacer::RuntimeError.
+    // the Ruby exception's backtrace -> RustyRacer::RuntimeError — and the value
+    // thrown, kept (`keep_thrown`), so a host fn the error propagates out of
+    // throws it on.
     JsError {
         message: String,
         backtrace: Vec<String>,
+        thrown: Option<u64>,
     },
     Terminated,  // watchdog/stop -> RustyRacer::ScriptTerminatedError
     OutOfMemory, // memory_limit hit -> RustyRacer::V8OutOfMemoryError
+    // A handle whose realm was reset or disposed under it -> RustyRacer::DisposedError
+    Disposed(String),
 }
 
 // V8's near-heap-limit callback (registered on EVERY isolate). V8 calls this,
@@ -330,9 +394,9 @@ where
 // instead of saying "a host function". Rendered only on that path, so an
 // ordinary callback pays for a pointer and nothing else.
 enum RubyCall<'a> {
-    // An attach()'d host function, by host_fn_id — the name it was attached
+    // An attach()'d host function, by its key — the name it was attached
     // under lives in the isolate's proc table.
-    HostFn(usize),
+    HostFn(HostFnKey),
     // A module resolver (a static instantiate block, a dynamic auto-link, or
     // import()), named by the specifier it was handed.
     Resolver(&'a str),
@@ -341,15 +405,17 @@ enum RubyCall<'a> {
 impl RubyCall<'_> {
     fn describe(&self, core: &Core) -> String {
         match self {
-            // 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()
-                .ok()
-                .and_then(|procs| procs.slots.get(*id).map(|slot| slot.name.clone()))
-            {
+            // try_lock, not lock: nothing holds this across a callback (`call_proc`
+            // holds it for one comparison, before the proc runs), but blocking here
+            // would turn a diagnostic into a hang. A slot handed on since names
+            // nobody: its name is another function's.
+            Self::HostFn(id) => match core.procs.try_lock().ok().and_then(|procs| {
+                procs
+                    .slots
+                    .get(id.index())
+                    .filter(|slot| slot.generation == id.generation)
+                    .map(|slot| slot.name.clone())
+            }) {
                 Some(name) => format!("The host function `{name}`"),
                 None => "A host function".to_string(),
             },
@@ -546,8 +612,8 @@ fn host_fn_callback(
     args: v8::FunctionCallbackArguments<'_>,
     mut rv: v8::ReturnValue<'_, v8::Value>,
 ) {
-    let host_fn_id = match v8::Local::<v8::External>::try_from(args.data()) {
-        Ok(e) => e.value() as usize,
+    let host_fn = match v8::Local::<v8::External>::try_from(args.data()) {
+        Ok(e) => HostFnKey::from_external(e.value()),
         Err(_) => return,
     };
     let mut js_args = Vec::with_capacity(args.length() as usize);
@@ -574,20 +640,22 @@ fn host_fn_callback(
         return;
     }
     let core = unsafe { &*core_ptr };
-    let result: Result<JsVal, String> = with_gvl(core, RubyCall::HostFn(host_fn_id), || {
+    let result: Result<JsVal, HostFnFailure> = with_gvl(core, RubyCall::HostFn(host_fn), || {
         let ruby = Ruby::get().unwrap();
         // rb_protect so a Ruby exception raised during arg/return marshalling
         // (ary_new_capa / jsval_to_ruby / ruby_to_jsval can raise on OOM etc.)
         // is CAUGHT here instead of longjmp-ing through V8's C++ frames. The
         // proc's own raise is already a magnus Err; this covers the rest.
         use magnus::rb_sys::AsRawValue;
-        let mut out: Option<Result<JsVal, String>> = None;
+        let mut out: Option<Result<JsVal, HostFnFailure>> = None;
         match magnus::rb_sys::protect(|| {
-            out = Some(core.call_proc(&ruby, host_fn_id, &js_args));
+            out = Some(core.call_proc(&ruby, host_fn, &js_args));
             ruby.qnil().as_raw()
         }) {
-            Ok(_) => out.unwrap_or_else(|| Err("host function did not complete".into())),
-            Err(e) => Err(format!("{e}")),
+            Ok(_) => {
+                out.unwrap_or_else(|| Err("host function did not complete".to_string().into()))
+            }
+            Err(e) => Err(format!("{e}").into()),
         }
     });
     match result {
@@ -595,8 +663,30 @@ fn host_fn_callback(
             let v = jsval_to_js(scope, val);
             rv.set(v);
         }
-        // The proc raised (or marshalling failed): surface as a JS exception.
-        Err(message) => throw_js_error(scope, &message),
+        // The proc raised (or marshalling failed): surface as a JS exception —
+        // the value JS threw, where the error is one a JS throw became.
+        Err(failure) => match failure.thrown.and_then(|serial| take_thrown(scope, serial)) {
+            Some(thrown) => {
+                scope.throw_exception(thrown);
+            }
+            None => throw_js_error(scope, &failure.message),
+        },
+    }
+}
+
+// How a host fn failed: the Ruby error's text, and the serial of the JS value
+// it carries when a JS throw is what it became (`keep_thrown`).
+struct HostFnFailure {
+    message: String,
+    thrown: Option<u64>,
+}
+
+impl From<String> for HostFnFailure {
+    fn from(message: String) -> Self {
+        HostFnFailure {
+            message,
+            thrown: None,
+        }
     }
 }
 
@@ -696,12 +786,93 @@ fn capture_js_error(
     let backtrace = stack_str
         .map(|s| parse_js_stack(s.as_str()))
         .unwrap_or_default();
-    VmError::JsError { message, backtrace }
+    let thrown = keep_thrown(scope, exception);
+    VmError::JsError {
+        message,
+        backtrace,
+        thrown,
+    }
+}
+
+// A value JS failed with that no TryCatch caught — an errored module's
+// exception, a rejected promise's reason — as a JsError: its text, no stack
+// frames, and the value kept as a thrown one is.
+fn rejected_with(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<v8::Value>) -> VmError {
+    VmError::JsError {
+        message: value.to_rust_string_lossy(scope),
+        backtrace: vec![],
+        thrown: keep_thrown(scope, Some(value)),
+    }
+}
+
+// A compile failure as a ParseError: V8's message, the location it recorded
+// (always the file, the line when it has one), and the SyntaxError kept as a
+// thrown value is.
+fn parse_error(
+    scope: &mut v8::PinScope<'_, '_>,
+    exception: Option<v8::Local<v8::Value>>,
+    message: Option<v8::Local<v8::Message>>,
+    filename: &str,
+    fallback: &str,
+) -> VmError {
+    let msg = exception
+        .map(|e| e.to_rust_string_lossy(scope))
+        .unwrap_or_else(|| fallback.to_string());
+    let res = message
+        .and_then(|m| m.get_script_resource_name(scope))
+        .filter(|v| v.is_string())
+        .map(|v| v.to_rust_string_lossy(scope))
+        .unwrap_or_else(|| filename.to_string());
+    let loc = match message.and_then(|m| m.get_line_number(scope)) {
+        Some(line) => format!(" at {res}:{line}"),
+        None => format!(" at {res}"),
+    };
+    VmError::Parse(format!("{msg}{loc}"), keep_thrown(scope, exception))
+}
+
+// Keep the value JS threw, so a host fn that lets the Ruby error it became
+// propagate throws THAT value on — its identity, class and stack — rather than a
+// fresh Error made of its text: a script a host fn ran for JS fails in JS as the
+// script did. One slot per isolate, since only the latest thrown value can still
+// be on its way back out, and only until the outermost op returns (`Core::run`),
+// since only a host fn inside it can still ask — kept longer, it would pin the
+// value, and its realm, for as long as nothing else threw. The serial (carried
+// by the Ruby exception, see `carrying_thrown`) tells it from a stale one, and is
+// drawn process-wide, so an error another isolate's op raised never matches this
+// one's slot: its value cannot cross isolates. None on an isolate with no state
+// (the snapshot creator's), where no host fn can ask.
+fn keep_thrown(
+    scope: &mut v8::PinScope<'_, '_>,
+    exception: Option<v8::Local<v8::Value>>,
+) -> Option<u64> {
+    static SERIAL: AtomicU64 = AtomicU64::new(0);
+    let exception = exception?;
+    let kept = v8::Global::new(scope, exception);
+    let state = scope.get_slot_mut::<IsolateState>()?;
+    let serial = SERIAL.fetch_add(1, Ordering::Relaxed) + 1;
+    state.thrown = Some((serial, kept));
+    Some(serial)
+}
+
+// The Ruby exception's kept thrown value (`keep_thrown`), when it still is the
+// latest: taken, as it is thrown once.
+fn take_thrown<'s>(
+    scope: &mut v8::PinScope<'s, '_>,
+    serial: u64,
+) -> Option<v8::Local<'s, v8::Value>> {
+    let state = scope.get_slot_mut::<IsolateState>()?;
+    let (kept_serial, _) = state.thrown.as_ref()?;
+    if *kept_serial != serial {
+        return None;
+    }
+    let (_, kept) = state.thrown.take()?;
+    Some(v8::Local::new(scope, kept))
 }
 
 // ---------------------------------------------------------------------------
 // ES modules: V8's raw compile/instantiate/evaluate steps, with the embedder
-// owning the url->Module registry (MODULES) and the resolve policy.
+// owning the url->Module registry and the resolve policy (ModuleReg is only the
+// binding's id and url bookkeeping).
 // ---------------------------------------------------------------------------
 fn module_origin<'s>(scope: &v8::PinScope<'s, '_>, url: &str) -> v8::ScriptOrigin<'s> {
     let name = v8::String::new(scope, url).unwrap();
@@ -720,18 +891,47 @@ fn module_origin<'s>(scope: &v8::PinScope<'s, '_>, url: &str) -> v8::ScriptOrigi
     )
 }
 
-// Registry for the thin compile_module/instantiate API: each compiled module is
-// addressed by an id, with its url kept for the resolve round-trip and a
-// hash bucket to map a referrer Local<Module> back to its id.
+// Registry for the thin compile_module/instantiate API.
 #[derive(Default)]
 struct ModuleReg {
-    // id -> (module, url, owning context id). The context id is needed because
-    // a module is bound to the v8::Context it was compiled in.
-    by_id: HashMap<i32, (v8::Global<v8::Module>, String, i32)>,
-    by_hash: HashMap<i32, Vec<(v8::Global<v8::Module>, i32)>>,
+    // id -> (module, owning context id): what a Module wrapper's ops address.
+    // The context id is needed because a module is bound to the v8::Context it
+    // was compiled in. Strong, and gone once the wrapper is disposed or collected
+    // (Core.released).
+    by_id: HashMap<i32, (v8::Global<v8::Module>, i32)>,
+    // identity hash -> (module, url): a Local<Module> V8 hands a callback
+    // (import.meta, a referrer being linked) back to the url it was compiled
+    // with. WEAK, so a module V8 still keeps — a dependency linked into a live
+    // graph, a function of a disposed realm's module another realm holds —
+    // answers whether its wrapper (or its realm) is still around or not, and
+    // one V8 collected is pruned instead of pinned (`add_url`).
+    urls: HashMap<i32, Vec<(v8::Weak<v8::Module>, String)>>,
+    // `add_url`'s amortization: entries added since the last prune, and the
+    // entries that prune left.
+    added_since_prune: usize,
+    kept_at_prune: usize,
     next_id: i32,
 }
 
+impl ModuleReg {
+    // Index |module|'s url, first pruning the entries of collected modules once
+    // as many have been added since the last prune as it left — a scan
+    // amortized O(1) per compile, keeping the index within about twice the
+    // modules alive.
+    fn add_url(&mut self, hash: i32, module: v8::Weak<v8::Module>, url: String) {
+        if self.added_since_prune > self.kept_at_prune {
+            self.urls.retain(|_, bucket| {
+                bucket.retain(|(module, _)| !module.is_empty());
+                !bucket.is_empty()
+            });
+            self.kept_at_prune = self.urls.values().map(Vec::len).sum();
+            self.added_since_prune = 0;
+        }
+        self.added_since_prune += 1;
+        self.urls.entry(hash).or_default().push((module, url));
+    }
+}
+
 // Classic compiled scripts: id -> (unbound script, owning context id). An
 // UnboundScript is context-independent, but we run it in the context it was
 // compiled in (and reset/dispose of that context drops it).
@@ -741,6 +941,39 @@ struct ScriptReg {
     next_id: i32,
 }
 
+// Context#function's handles: id -> the function its path resolved to, the
+// holder it was read off (its `this`), and the realm it was resolved in. The
+// Globals live HERE, not in the Ruby wrapper, so a reset or disposed realm drops
+// them (drop_context_artifacts) whatever wrappers Ruby still holds — a handle
+// must not keep its realm's v8::Context alive — and so they are only ever
+// dropped on the owner thread with the isolate entered, which a wrapper's GC
+// free can't promise. A wrapper that is disposed or collected queues its id on
+// Core.released instead, and the next outermost request boundary removes it
+// here. Ids are never reused, so a stale id can only miss.
+//
+// A path may lead into ANOTHER realm (`frames[0].fn`): the entry belongs to the
+// realm it was resolved in, so it holds that other realm's function until this
+// one is reset or the handle is released — as any reference this realm keeps
+// to it would.
+#[derive(Default)]
+struct FunctionReg {
+    by_id: HashMap<u64, FunctionEntry>,
+    next_id: u64,
+}
+
+struct FunctionEntry {
+    function: v8::Global<v8::Function>,
+    receiver: v8::Global<v8::Value>,
+    context_id: i32,
+}
+
+// A handle whose Ruby wrapper let go of it, queued on Core.released.
+enum Released {
+    Function(u64),
+    Module(i32),
+    Script(i32),
+}
+
 // The V8 thread's realm registry: the main context (id 0, swappable by reset),
 // the extra realms from create_context, and the host-namespace name to
 // re-install on fresh realms. Thread-local (like MODULES/SCRIPTS) so
@@ -825,6 +1058,7 @@ struct IsolateState {
     realms: V8State,
     modules: ModuleReg,
     scripts: ScriptReg,
+    functions: FunctionReg,
     active_realms: Vec<i32>,
     instantiating: bool,
     watchdog_fired: bool,
@@ -864,6 +1098,8 @@ struct IsolateState {
     // the ScriptTerminatedError can name what was running. Taken (cleared) when the
     // terminated op's error is built; None for any non-timeout outcome.
     timeout_backtrace: Option<Vec<String>>,
+    // The latest value JS threw out of an op, with its serial (`keep_thrown`).
+    thrown: Option<(u64, v8::Global<v8::Value>)>,
 }
 
 impl IsolateState {
@@ -876,6 +1112,7 @@ impl IsolateState {
             },
             modules: ModuleReg::default(),
             scripts: ScriptReg::default(),
+            functions: FunctionReg::default(),
             active_realms: Vec::new(),
             instantiating: false,
             watchdog_fired: false,
@@ -888,6 +1125,7 @@ impl IsolateState {
             oom_fired: false,
             oom_initial_limit: 0,
             timeout_backtrace: None,
+            thrown: None,
         }
     }
 }
@@ -973,7 +1211,7 @@ fn transfer_registry() -> &'static Mutex<HashMap<u64, SendBackingStore>> {
 // Monotonic token source. Starts at 1 so 0 is free as the JS-side "not
 // transferable — fall back to a copy" sentinel. A token is f64-exact for ~2^53
 // transfers, which a process will never reach.
-static NEXT_TRANSFER_TOKEN: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
+static NEXT_TRANSFER_TOKEN: AtomicU64 = AtomicU64::new(1);
 
 // Drain EVERY realm's microtask queue once. Each realm has its own queue (see
 // V8State::queues), so a single scope.perform_microtask_checkpoint() — which only
@@ -1033,23 +1271,19 @@ fn auto_drain(scope: &mut v8::PinScope<'_, '_>, outermost: bool) {
     }
 }
 
-// Drop every module AND script compiled in `context_id` (its v8::Context is
-// going away — on reset or dispose — so those handles are now dead).
+// Drop every module, script and function handle of `context_id` (its
+// v8::Context is going away — on reset or dispose — so those handles are now
+// dead, and a function's Globals would otherwise keep that context alive).
 fn drop_context_artifacts(state: &mut IsolateState, context_id: i32) {
     let m = &mut state.modules;
-    let dead: Vec<i32> = m
-        .by_id
-        .iter()
-        .filter(|(_, (_, _, cid))| *cid == context_id)
-        .map(|(id, _)| *id)
-        .collect();
-    for id in dead {
-        m.by_id.remove(&id);
-        for bucket in m.by_hash.values_mut() {
-            bucket.retain(|(_, mid)| *mid != id);
-        }
-    }
+    // (Not its url index: weak, it pins nothing, and a module of this realm that
+    // another realm still reaches keeps its import.meta.url.)
+    m.by_id.retain(|_, (_, cid)| *cid != context_id);
     state.scripts.by_id.retain(|_, (_, cid)| *cid != context_id);
+    state
+        .functions
+        .by_id
+        .retain(|_, entry| entry.context_id != context_id);
     // A promise-reject recorder created in this context is unusable now.
     if state
         .realms
@@ -1073,24 +1307,21 @@ fn script_handle(
         .map(|(g, cid)| (g.clone(), *cid))
 }
 
-// A registered module's url (the filename it was compiled with), by identity
-// against MODULES — the reverse of the id lookup. Used to give a referrer its
-// url for the resolve round-trip and to fill import.meta.url.
+// A compiled module's url (the filename it was compiled with), by identity in
+// the weak url index (ModuleReg.urls) — for as long as V8 keeps the module. Used
+// to give a referrer its url for the resolve round-trip and to fill
+// import.meta.url.
 fn module_url(scope: &mut v8::PinScope<'_, '_>, module: v8::Local<v8::Module>) -> Option<String> {
     let hash = module.get_identity_hash().get();
-    // Snapshot the hash bucket (cloned globals) so the scope is free for the
-    // Local comparison below: istate! borrows the scope and v8::Local::new
-    // needs it too, so they can't overlap in one expression.
-    let bucket = istate!(scope).modules.by_hash.get(&hash)?.clone();
-    let id = bucket
-        .iter()
-        .find(|(g, _)| v8::Local::new(&*scope, g) == module)
-        .map(|(_, id)| *id)?;
-    istate!(scope)
+    // A shared borrow of the slot beside the shared one to_local takes.
+    scope
+        .get_slot::<IsolateState>()?
         .modules
-        .by_id
-        .get(&id)
-        .map(|(_, u, _)| u.clone())
+        .urls
+        .get(&hash)?
+        .iter()
+        .find(|(weak, _)| weak.to_local(scope) == Some(module))
+        .map(|(_, url)| url.clone())
 }
 
 // V8 calls this the first time a module reads import.meta. Fills in
@@ -1214,7 +1445,7 @@ fn resolve_imported<'s>(
         .modules
         .by_id
         .get(&dep_id)
-        .map(|(g, _, cid)| (g.clone(), *cid));
+        .map(|(g, cid)| (g.clone(), *cid));
     let g = match (here, found) {
         (Some(here), Some((g, cid))) if cid == here => g,
         (Some(_), Some(_)) => {
@@ -1291,8 +1522,8 @@ fn dynamic_import_cb<'s>(
                 .modules
                 .by_id
                 .get(&id)
-                .filter(|(_, _, cid)| Some(*cid) == here)
-                .map(|(g, _, _)| g.clone());
+                .filter(|(_, cid)| Some(*cid) == here)
+                .map(|(g, _)| g.clone());
             match g {
                 Some(g) => {
                     let module = v8::Local::new(scope, &g);
@@ -1473,7 +1704,7 @@ fn module_handle(state: &IsolateState, module_id: i32) -> Option<(v8::Global<v8:
         .modules
         .by_id
         .get(&module_id)
-        .map(|(g, _, cid)| (g.clone(), *cid))
+        .map(|(g, cid)| (g.clone(), *cid))
 }
 
 // ---------------------------------------------------------------------------
@@ -1534,11 +1765,19 @@ struct Core {
     // 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
+    // A HostFnKey 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>,
+    // The handles (Function, Module, Script) whose Ruby wrappers were disposed or
+    // collected, for the next outermost request boundary to remove from their
+    // registries (`forget_released_handles`). A wrapper's free may run on any
+    // Ruby thread, outside any op, so all it can do is queue its id here.
+    released: Mutex<Vec<Released>>,
+    // Set with each push there, so the request boundary looks at the lock only
+    // when there is something under it.
+    handles_released: AtomicBool,
     // 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.
     default_timeout_ms: u64,
@@ -1608,10 +1847,22 @@ struct Script {
     cache_rejected: bool,
 }
 
-// The four wrappers that hold an Arc<Core> all mark the isolate's roots, because any
+// Context#function result: a JS function resolved once, with its `this`, kept in
+// FunctionReg by id — the realm it belongs to rides along so a call enters it
+// without a lookup.
+#[derive(TypedData)]
+#[magnus(class = "RustyRacer::Function", mark)]
+struct JsFunction {
+    core: Arc<Core>,
+    context_id: i32,
+    function_id: u64,
+    disposed: AtomicBool,
+}
+
+// The five 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
+// stay callable through it. Marking the same array five 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) => {
@@ -1626,6 +1877,7 @@ marks_core_roots!(Isolate);
 marks_core_roots!(Context);
 marks_core_roots!(JsModule);
 marks_core_roots!(Script);
+marks_core_roots!(JsFunction);
 
 // Set true once V8 is initialized; Platform.set_flags! refuses after that
 // (flags must be set before V8::initialize), like mini_racer's
@@ -2152,12 +2404,12 @@ fn install_host_namespace(
     ];
     for (member, function) in members {
         if let (Some(f), Some(k)) = (function, v8::String::new(scope, member)) {
-            ns.set(scope, k.into(), f.into());
+            ns.create_data_property(scope, k.into(), f.into());
         }
     }
     if let Some(key) = v8::String::new(scope, name) {
         let global = context.global(scope);
-        global.set(scope, key.into(), ns.into());
+        global.create_data_property(scope, key.into(), ns.into());
     }
 }
 
@@ -2253,11 +2505,11 @@ fn build_snapshot(code: &str, base: Option<Vec<u8>>, warmup: bool) -> Result<Vec
                     // leaves behind); nothing reads its completion value, so
                     // don't marshal it — a bundle ending in an expression must
                     // not fail the snapshot over a value no one wants.
-                    true,
+                    Completion::Void,
                 )
             {
                 err = Some(match e {
-                    VmError::Parse(m) | VmError::Runtime(m) => m,
+                    VmError::Parse(m, _) | VmError::Runtime(m) | VmError::Disposed(m) => m,
                     VmError::JsError { message, .. } => message,
                     VmError::Terminated => "snapshot code was terminated".to_string(),
                     // Unreachable: the snapshot-creator is a separate isolate
@@ -2394,6 +2646,8 @@ impl Isolate {
             depth: std::sync::atomic::AtomicU32::new(0),
             roots: Opaque::from(roots),
             procs: Mutex::new(ProcTable::default()),
+            released: Mutex::new(Vec::new()),
+            handles_released: AtomicBool::new(false),
             default_timeout_ms: timeout_ms,
             memory_limit,
             watchdog,
@@ -2641,6 +2895,9 @@ impl Core {
             // on an op.
             if reply.is_none() {
                 self.shared.lock().unwrap().disposed = true;
+            } else if depth == 0 {
+                // No host fn is left to throw a kept value on (`keep_thrown`).
+                istate!(unsafe { &mut *iso }).thrown = None;
             }
             self.depth.fetch_sub(1, Ordering::SeqCst);
             reply
@@ -2716,7 +2973,7 @@ impl Core {
     }
 
     // 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
+    // (Isolate, Context, Module, Script, Function 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
@@ -2741,15 +2998,24 @@ impl Core {
         }
     }
 
-    fn call_proc(&self, ruby: &Ruby, host_fn_id: usize, args: &[JsVal]) -> Result<JsVal, String> {
-        // 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.
+    fn call_proc(
+        &self,
+        ruby: &Ruby,
+        host_fn: HostFnKey,
+        args: &[JsVal],
+    ) -> Result<JsVal, HostFnFailure> {
+        // A function of a released realm is refused here, before its slot's roots
+        // entry is read: that entry may by now hold another realm's proc. (The lock
+        // is uncontended and held for the comparison alone — nothing here allocates,
+        // so no GC can need it meanwhile.)
+        if !self.procs.lock().unwrap().current(host_fn) {
+            return Err("unknown host function".to_string().into());
+        }
+        // `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")?;
+            .root_proc(proc_root_index(host_fn.index()))
+            .ok_or_else(|| "unknown host function".to_string())?;
         // 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
@@ -2769,8 +3035,11 @@ impl Core {
         // 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| e.to_string())?;
-        ruby_to_jsval(value).map_err(|e| e.to_string())
+        let value = result.map_err(|e| HostFnFailure {
+            message: e.to_string(),
+            thrown: thrown_serial_of(&e),
+        })?;
+        ruby_to_jsval(value).map_err(|e| e.to_string().into())
     }
 
     // Context#call (and call_void). Resolves a dotted function path
@@ -2789,18 +3058,47 @@ impl Core {
                 "call requires a function name",
             ));
         };
-        let name = String::try_convert(*name)?;
-        let jsargs: Vec<JsVal> = call_args
-            .iter()
-            .map(|v| ruby_to_jsval(*v))
-            .collect::<Result<_, _>>()?;
-
         let reply = self.run(
             ruby,
             Request::Call {
                 context_id,
-                name,
-                args: jsargs,
+                name: String::try_convert(*name)?,
+                args: js_args(call_args)?,
+                void,
+                timeout_ms: self.default_timeout_ms,
+            },
+        )?;
+        self.reply_value(ruby, reply)
+    }
+
+    // Context#function: resolve |path| in the realm once; the handle's id.
+    fn resolve_function(&self, ruby: &Ruby, context_id: i32, path: String) -> Result<u64, Error> {
+        let reply = self.run(
+            ruby,
+            Request::ResolveFunction {
+                context_id,
+                path,
+                timeout_ms: self.default_timeout_ms,
+            },
+        )?;
+        u64::try_convert(self.reply_value(ruby, reply)?)
+    }
+
+    // Function#call (and call_void): Context#call's invocation, of a resolved handle.
+    fn call_function(
+        &self,
+        ruby: &Ruby,
+        context_id: i32,
+        function_id: u64,
+        args: &[Value],
+        void: bool,
+    ) -> Result<Value, Error> {
+        let reply = self.run(
+            ruby,
+            Request::CallFunction {
+                context_id,
+                function_id,
+                args: js_args(args)?,
                 void,
                 timeout_ms: self.default_timeout_ms,
             },
@@ -2808,6 +3106,13 @@ impl Core {
         self.reply_value(ruby, reply)
     }
 
+    // A wrapper let go of its handle (see `released`). Takes only this lock,
+    // briefly, and allocates no Ruby object — it runs from a GC free.
+    fn release(&self, handle: Released) {
+        self.released.lock().unwrap().push(handle);
+        self.handles_released.store(true, Ordering::Relaxed);
+    }
+
     fn drain_microtasks(&self, ruby: &Ruby) -> Result<Value, Error> {
         let reply = self.run(
             ruby,
@@ -2880,7 +3185,7 @@ impl Core {
         source: String,
         filename: String,
         timeout_ms: u64,
-        void: bool,
+        completion: Completion,
     ) -> Result<Value, Error> {
         let reply = self.run(
             ruby,
@@ -2889,7 +3194,7 @@ impl Core {
                 source,
                 filename,
                 timeout_ms,
-                void,
+                completion,
             },
         )?;
         self.reply_value(ruby, reply)
@@ -2906,18 +3211,14 @@ impl Core {
         // 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,
-            live: true,
-            name: name.clone(),
-        });
-        self.root_store(ruby, proc_root_index(host_fn_id), proc)?;
+        let host_fn = self.procs.lock().unwrap().alloc(context_id, name.clone());
+        self.root_store(ruby, proc_root_index(host_fn.index()), proc)?;
         let reply = self.run(
             ruby,
             Request::Attach {
                 context_id,
                 name,
-                host_fn_id,
+                host_fn,
                 timeout_ms: self.default_timeout_ms,
             },
         )?;
@@ -2926,7 +3227,7 @@ impl Core {
 
     // attach_many: install several host fns in ONE round-trip to the V8 thread
     // (a fresh realm needs ~dozens; one rendezvous instead of one per fn). Slots
-    // are allocated up front so each carries a stable host_fn_id; entries are
+    // are allocated up front so each carries a stable key; entries are
     // applied IN ORDER and a build/attach failure aborts the batch with that
     // (name-tagged) error WITHOUT rolling back earlier entries (see the
     // AttachMany arm). On that error path the unused slots are reclaimed at the
@@ -2941,18 +3242,11 @@ impl Core {
             return Ok(ruby.qnil().as_value()); // nothing to install, skip the round-trip
         }
         self.ensure_owner_and_live(ruby)?; // before the roots writes — see `attach`
-        let allocated: Vec<(String, usize, Proc)> = {
+        let allocated: Vec<(String, HostFnKey, Proc)> = {
             let mut procs = self.procs.lock().unwrap();
             entries
                 .into_iter()
-                .map(|(name, proc)| {
-                    let id = procs.alloc(ProcSlot {
-                        context_id,
-                        live: true,
-                        name: name.clone(),
-                    });
-                    (name, id, proc)
-                })
+                .map(|(name, proc)| (name.clone(), procs.alloc(context_id, name), proc))
                 .collect()
         };
         // Stored OUTSIDE the table's lock: storing into the array can allocate (the
@@ -2960,16 +3254,16 @@ impl Core {
         // 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 mut named_keys: Vec<(String, HostFnKey)> = Vec::with_capacity(allocated.len());
+        for (name, key, proc) in allocated {
+            self.root_store(ruby, proc_root_index(key.index()), proc)?;
+            named_keys.push((name, key));
         }
         let reply = self.run(
             ruby,
             Request::AttachMany {
                 context_id,
-                entries: named_ids,
+                entries: named_keys,
                 timeout_ms: self.default_timeout_ms,
             },
         )?;
@@ -2977,11 +3271,12 @@ impl Core {
     }
 
     // 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.
+    // realm is gone (reset or disposed), and holding them would keep the embedder's
+    // world alive for the rest of the isolate's life. A V8 function of that realm
+    // may still be reachable (the embedder can hold the old global), but its key
+    // stops answering (`ProcTable::current`), so it never calls a proc again.
+    // Runs on a Ruby thread: it writes nil into the Array. The slots stay: the
+    // keys 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.
@@ -3094,12 +3389,18 @@ impl Core {
         self.reply_value(ruby, reply?)
     }
 
-    fn evaluate_module(&self, ruby: &Ruby, module_id: i32) -> Result<Value, Error> {
+    fn evaluate_module(
+        &self,
+        ruby: &Ruby,
+        module_id: i32,
+        report: Option<String>,
+    ) -> Result<Value, Error> {
         let reply = self.run(
             ruby,
             Request::EvaluateModule {
                 module_id,
                 timeout_ms: self.default_timeout_ms,
+                report,
             },
         )?;
         self.reply_value(ruby, reply)
@@ -3120,11 +3421,6 @@ impl Core {
         self.reply_value(ruby, reply)
     }
 
-    fn dispose_module(&self, ruby: &Ruby, module_id: i32) -> Result<(), Error> {
-        let reply = self.run(ruby, Request::DisposeModule { module_id })?;
-        self.reply_value(ruby, reply).map(|_| ())
-    }
-
     // Classic script: compile, run, dispose.
     #[allow(clippy::too_many_arguments)]
     fn compile_script(
@@ -3170,11 +3466,6 @@ impl Core {
         self.reply_value(ruby, reply)
     }
 
-    fn dispose_script(&self, ruby: &Ruby, script_id: i32) -> Result<(), Error> {
-        let reply = self.run(ruby, Request::DisposeScript { script_id })?;
-        self.reply_value(ruby, reply).map(|_| ())
-    }
-
     // Serialize a fresh bytecode cache from a compiled handle's current state
     // (Script#/Module#create_code_cache). None = V8 couldn't produce one (or the
     // realm is gone).
@@ -3245,6 +3536,7 @@ impl Core {
             st.realms = V8State::default();
             st.modules = ModuleReg::default();
             st.scripts = ScriptReg::default();
+            st.functions = FunctionReg::default();
             st.instantiate_resolve = None;
         }
         // Unregister the near-heap-limit callback before disposal: dropping the box
@@ -3369,6 +3661,11 @@ fn pending_transfer_count() -> usize {
     transfer_registry().lock().unwrap().len()
 }
 
+// A call's Ruby arguments, marshalled for JS.
+fn js_args(args: &[Value]) -> Result<Vec<JsVal>, Error> {
+    args.iter().map(|v| ruby_to_jsval(*v)).collect()
+}
+
 // Thin magnus-method wrappers.
 // Isolate = the VM and its isolate-level operations; it hands out Contexts.
 impl Isolate {
@@ -3443,14 +3740,14 @@ impl Context {
         Ok(())
     }
     // timeout_ms 0 = use the isolate's default; an explicit value overrides it.
-    // |void| discards the completion value instead of marshalling it.
+    // |completion| 0 marshals the completion value, 1 discards it, 2 keeps a primitive alone (`Completion`).
     fn eval(
         ruby: &Ruby,
         rb_self: &Self,
         source: String,
         timeout_ms: u64,
         filename: String,
-        void: bool,
+        completion: u8,
     ) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
         let timeout = if timeout_ms == 0 {
@@ -3458,9 +3755,14 @@ impl Context {
         } else {
             timeout_ms
         };
+        let completion = match completion {
+            1 => Completion::Void,
+            2 => Completion::Primitive,
+            _ => Completion::Value,
+        };
         rb_self
             .core
-            .eval_t(ruby, rb_self.id, source, filename, timeout, void)
+            .eval_t(ruby, rb_self.id, source, filename, timeout, completion)
     }
     fn call(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
@@ -3470,6 +3772,18 @@ impl Context {
         rb_self.check_live(ruby)?;
         rb_self.core.call(ruby, rb_self.id, args, true)
     }
+    // function(path) -> Function: what `call(path, ...)` would call, resolved
+    // now, once — its holder kept as its `this` — so each call skips the path walk.
+    fn function(ruby: &Ruby, rb_self: &Self, path: String) -> Result<JsFunction, Error> {
+        rb_self.check_live(ruby)?;
+        let function_id = rb_self.core.resolve_function(ruby, rb_self.id, path)?;
+        Ok(JsFunction {
+            core: rb_self.core.clone(),
+            context_id: rb_self.id,
+            function_id,
+            disposed: AtomicBool::new(false),
+        })
+    }
     fn attach(ruby: &Ruby, rb_self: &Self, name: String, proc: Proc) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
         rb_self.core.attach(ruby, rb_self.id, name, proc)
@@ -3649,9 +3963,12 @@ impl JsModule {
             .core
             .instantiate_module(ruby, rb_self.module_id, resolver)
     }
-    fn evaluate(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+    // |report|: nil, or the name of the context global that reports the evaluation's rejection (`Request::EvaluateModule`).
+    fn evaluate(ruby: &Ruby, rb_self: &Self, report: Option<String>) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
-        rb_self.core.evaluate_module(ruby, rb_self.module_id)
+        rb_self
+            .core
+            .evaluate_module(ruby, rb_self.module_id, report)
     }
     fn namespace(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
@@ -3695,12 +4012,12 @@ impl JsModule {
         let bytes = rb_self.core.module_code_cache(ruby, rb_self.module_id)?;
         Ok(code_cache_value(ruby, bytes.as_ref()))
     }
-    fn dispose(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
-        if rb_self.disposed.swap(true, Ordering::SeqCst) {
-            return Ok(());
+    // Let go of the module now rather than when this wrapper is collected (see
+    // JsFunction::dispose). Its url still answers while V8 keeps the module.
+    fn dispose(&self) {
+        if !self.disposed.swap(true, Ordering::SeqCst) {
+            self.core.release(Released::Module(self.module_id));
         }
-        let _ = rb_self.core.dispose_module(ruby, rb_self.module_id);
-        Ok(())
     }
     fn disposed(&self) -> bool {
         self.disposed.load(Ordering::SeqCst)
@@ -3746,18 +4063,72 @@ impl Script {
         let bytes = rb_self.core.script_code_cache(ruby, rb_self.script_id)?;
         Ok(code_cache_value(ruby, bytes.as_ref()))
     }
-    fn dispose(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
-        if rb_self.disposed.swap(true, Ordering::SeqCst) {
-            return Ok(());
+    // Let go of the script now rather than when this wrapper is collected (see
+    // JsFunction::dispose).
+    fn dispose(&self) {
+        if !self.disposed.swap(true, Ordering::SeqCst) {
+            self.core.release(Released::Script(self.script_id));
         }
-        let _ = rb_self.core.dispose_script(ruby, rb_self.script_id);
-        Ok(())
     }
     fn disposed(&self) -> bool {
         self.disposed.load(Ordering::SeqCst)
     }
 }
 
+impl JsFunction {
+    fn check_live(&self, ruby: &Ruby) -> Result<(), Error> {
+        // Its realm's reset or dispose is found by the call itself (the handle is
+        // gone from FunctionReg): that is not something this wrapper can see.
+        if self.disposed.load(Ordering::SeqCst) || self.core.is_disposed() {
+            return Err(Error::new(
+                err_class(ruby, "DisposedError"),
+                "disposed function",
+            ));
+        }
+        Ok(())
+    }
+    fn call(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
+        rb_self.check_live(ruby)?;
+        rb_self
+            .core
+            .call_function(ruby, rb_self.context_id, rb_self.function_id, args, false)
+    }
+    fn call_void(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
+        rb_self.check_live(ruby)?;
+        rb_self
+            .core
+            .call_function(ruby, rb_self.context_id, rb_self.function_id, args, true)
+    }
+    // Let go of the function now rather than when this wrapper is collected. Any
+    // thread, any time: the Globals go at the end of the isolate's next op.
+    fn dispose(&self) {
+        if !self.disposed.swap(true, Ordering::SeqCst) {
+            self.core.release(Released::Function(self.function_id));
+        }
+    }
+    fn disposed(&self) -> bool {
+        self.disposed.load(Ordering::SeqCst) || self.core.is_disposed()
+    }
+}
+
+impl Drop for JsFunction {
+    fn drop(&mut self) {
+        self.dispose();
+    }
+}
+
+impl Drop for JsModule {
+    fn drop(&mut self) {
+        self.dispose();
+    }
+}
+
+impl Drop for Script {
+    fn drop(&mut self) {
+        self.dispose();
+    }
+}
+
 // A bytecode cache as a binary (ASCII-8BIT) Ruby String, or nil when there's
 // none — the shared return shape of #cached_data and #create_code_cache.
 fn code_cache_value(ruby: &Ruby, bytes: Option<&Vec<u8>>) -> Value {
@@ -3808,9 +4179,15 @@ fn binary_bytes(
 
 fn vm_err(ruby: &Ruby, e: VmError) -> Error {
     match e {
-        VmError::Parse(m) => Error::new(err_class(ruby, "ParseError"), m),
+        VmError::Parse(m, thrown) => {
+            carrying_thrown(Error::new(err_class(ruby, "ParseError"), m), thrown)
+        }
         VmError::Runtime(m) => Error::new(err_class(ruby, "RuntimeError"), m),
-        VmError::JsError { message, backtrace } => js_runtime_error(ruby, message, backtrace),
+        VmError::JsError {
+            message,
+            backtrace,
+            thrown,
+        } => carrying_thrown(js_runtime_error(ruby, message, backtrace), thrown),
         VmError::Terminated => Error::new(
             err_class(ruby, "ScriptTerminatedError"),
             "JavaScript was terminated (timeout or stop)",
@@ -3819,6 +4196,7 @@ fn vm_err(ruby: &Ruby, e: VmError) -> Error {
             err_class(ruby, "V8OutOfMemoryError"),
             "JavaScript exceeded the isolate memory_limit",
         ),
+        VmError::Disposed(m) => Error::new(err_class(ruby, "DisposedError"), m),
     }
 }
 
@@ -3852,6 +4230,42 @@ fn terminated_error(ruby: &Ruby, js_backtrace: Option<Vec<String>>) -> Error {
     }
 }
 
+// The ivar a Ruby exception carries its thrown value's serial in (`keep_thrown`),
+// beside the message it was raised with.
+const THROWN_IVAR: &str = "@__rusty_racer_thrown";
+
+// |error| as an instance carrying |thrown|'s serial, for a host fn it propagates
+// out of to throw the kept value on (`take_thrown`).
+fn carrying_thrown(error: Error, thrown: Option<u64>) -> Error {
+    let Some(serial) = thrown else {
+        return error;
+    };
+    match error_to_exception(&error) {
+        Some(exc) => {
+            let Ok(message) = exc.funcall::<_, _, Value>("message", ()) else {
+                return Error::from(exc);
+            };
+            let _ = exc
+                .funcall::<_, _, Value>("instance_variable_set", (THROWN_IVAR, (serial, message)));
+            Error::from(exc)
+        }
+        None => error,
+    }
+}
+
+// The serial of the thrown value a host fn's raised |error| carries, if any — not
+// when Ruby re-raised it with a message of its own (`raise e, 'other'` copies
+// the ivar): that error says something the value does not.
+fn thrown_serial_of(error: &Error) -> Option<u64> {
+    let exc = error_to_exception(error)?;
+    let (serial, message): (u64, Value) = exc
+        .funcall::<_, _, Option<(u64, Value)>>("instance_variable_get", (THROWN_IVAR,))
+        .ok()
+        .flatten()?;
+    let now: Value = exc.funcall("message", ()).ok()?;
+    now.eql(message).ok()?.then_some(serial)
+}
+
 // Build a RustyRacer::RuntimeError carrying the JS stack as its Ruby backtrace.
 // Constructs the exception instance so we can set_backtrace before raising;
 // falls back to a plain Error if any of that fails.
@@ -3961,10 +4375,11 @@ pub fn install_classes(ruby: &Ruby) -> Result<(), Error> {
     // A v8::Context (realm): eval/call/attach/compile_module.
     let context = module.define_class("Context", ruby.class_object())?;
     // Backs both keyword-arg wrappers in lib: Context#eval(source, timeout_ms:,
-    // filename:) and #eval_void, which differ only in the 4th arg (the void flag).
+    // filename:), #eval_void and #eval_primitive, which differ only in the 4th arg (what they keep of the completion value).
     context.define_method("_eval", method!(Context::eval, 4))?;
     context.define_method("call", method!(Context::call, -1))?;
     context.define_method("call_void", method!(Context::call_void, -1))?;
+    context.define_method("function", method!(Context::function, 1))?;
     context.define_method("attach", method!(Context::attach, 2))?;
     context.define_method("attach_many", method!(Context::attach_many, 1))?;
     context.define_method("reset", method!(Context::reset, 0))?;
@@ -3985,6 +4400,13 @@ pub fn install_classes(ruby: &Ruby) -> Result<(), Error> {
     script.define_method("dispose", method!(Script::dispose, 0))?;
     script.define_method("disposed?", method!(Script::disposed, 0))?;
 
+    // A resolved function: Context#function -> #call / #call_void.
+    let function = module.define_class("Function", ruby.class_object())?;
+    function.define_method("call", method!(JsFunction::call, -1))?;
+    function.define_method("call_void", method!(JsFunction::call_void, -1))?;
+    function.define_method("dispose", method!(JsFunction::dispose, 0))?;
+    function.define_method("disposed?", method!(JsFunction::disposed, 0))?;
+
     // V8 startup blob: Snapshot.new(code) -> Isolate.new(snapshot:).
     let snapshot = module.define_class("Snapshot", ruby.class_object())?;
     snapshot.define_singleton_method("new", function!(Snapshot::new, -1))?;
@@ -3996,7 +4418,7 @@ pub fn install_classes(ruby: &Ruby) -> Result<(), Error> {
     // Thin ES-module handle: Context#compile_module -> instantiate/evaluate.
     let jsmodule = module.define_class("Module", ruby.class_object())?;
     jsmodule.define_method("_instantiate", method!(JsModule::instantiate, 1))?;
-    jsmodule.define_method("evaluate", method!(JsModule::evaluate, 0))?;
+    jsmodule.define_method("_evaluate", method!(JsModule::evaluate, 1))?;
     jsmodule.define_method("namespace", method!(JsModule::namespace, 0))?;
     jsmodule.define_method("_status", method!(JsModule::status, 0))?;
     jsmodule.define_method("graph_async?", method!(JsModule::graph_async, 0))?;