rusty_racer 0.1.1 → 0.1.2

data/ext/rusty_racer/src/stack.rs

@@ -0,0 +1,292 @@
+// V8 stack limit + conservative-GC-scan retargeting (in-thread: V8 runs on the
+// calling Ruby thread's stack — a native pthread stack, or a Ruby Fiber's
+// separate mmap'd stack). Self-contained: only raw pointers, std, libc, and the
+// exported V8 symbols below — no IsolateState/JsVal/marshalling. The crate uses
+// discover_scan_start_field (once per isolate), set_v8_stack_limit (per op), and
+// STACK_DEBUG (set at init); everything else is private to this module.
+
+use std::ffi::c_void;
+use std::ptr::null_mut;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+// rusty_v8 doesn't wrap the runtime `v8::Isolate::SetStackLimit(uintptr_t)`, so
+// link the public V8 symbol directly (stable across V8 versions). It sets the
+// lowest address V8's stack may reach before it throws RangeError.
+unsafe extern "C" {
+    #[link_name = "_ZN2v87Isolate13SetStackLimitEm"]
+    fn v8__Isolate__SetStackLimit(isolate: *mut c_void, stack_limit: usize);
+    // V8's own (exported) accessors down to the conservative-GC-scan Stack
+    // object, so we can re-point its stack_start per op when V8 runs on a Ruby
+    // Fiber (see set_fiber_scan_start / discover_scan_start_field). Member fns:
+    // the first arg is `this`. The public v8::Isolate* IS i::Isolate*.
+    #[link_name = "_ZN2v88internal7Isolate4heapEv"]
+    fn v8__internal__Isolate__heap(isolate: *mut c_void) -> *mut c_void;
+    #[link_name = "_ZN2v88internal4Heap5stackEv"]
+    fn v8__internal__Heap__stack(heap: *mut c_void) -> *mut c_void;
+    // Sets the scan stack_start to v8::base::Stack::GetStackStart() (the native
+    // pthread top) — used only to positively identify the field during discovery.
+    #[link_name = "_ZN2v88internal4Heap13SetStackStartEv"]
+    fn v8__internal__Heap__SetStackStart(heap: *mut c_void);
+    #[link_name = "_ZN2v84base5Stack13GetStackStartEv"]
+    fn v8__base__Stack__GetStackStart() -> usize;
+}
+
+// Locate V8's conservative-GC-scan stack_start field
+// (heap::base::Stack::current_segment_.start) so set_fiber_scan_start can
+// re-point it per op. The scanner walks [SP, stack_start); on a Ruby Fiber V8's
+// stack_start is still the NATIVE thread top, a different region, so the walk
+// runs off the fiber's mapped top into the guard page and SEGVs (the residual
+// after the limit fix). We reach the Stack via V8's exported Isolate::heap()/
+// Heap::stack(); the field is the first word of Stack (current_segment_ is its
+// first member, .start the first field), but we VERIFY rather than trust the
+// layout: Heap::SetStackStart() writes that field to base::Stack::GetStackStart(),
+// so if poking a sentinel and re-calling SetStackStart restores the value at
+// offset 0, that word IS the field. Any mismatch returns 0 (override disabled —
+// V8 keeps its native start, i.e. the rare pre-fix crash, NEVER corruption).
+// Must run with the isolate ENTERED. `real_isolate` is the raw v8::Isolate*.
+pub(crate) fn discover_scan_start_field(real_isolate: *mut c_void) -> usize {
+    const SENTINEL: usize = 0xA5A5_A5A5_A5A5_A5A5;
+    unsafe {
+        let heap = v8__internal__Isolate__heap(real_isolate);
+        if heap.is_null() {
+            return 0;
+        }
+        let stack = v8__internal__Heap__stack(heap);
+        if stack.is_null() {
+            return 0;
+        }
+        let nt = v8__base__Stack__GetStackStart();
+        if nt == 0 {
+            return 0;
+        }
+        v8__internal__Heap__SetStackStart(heap); // start := nt
+        let field = stack as *mut usize; // expected &current_segment_.start
+        if field.read() != nt {
+            return 0; // offset 0 isn't the field (layout changed) — disable
+        }
+        field.write(SENTINEL);
+        v8__internal__Heap__SetStackStart(heap); // must rewrite the same word
+        if field.read() != nt {
+            return 0; // SetStackStart doesn't own offset 0 — disable
+        }
+        stack as usize
+    }
+}
+
+// The native thread's stack bounds are stable per NATIVE thread, but querying
+// them (pthread, which reads /proc/self/maps for the main thread on Linux) is
+// far too slow per op. Cache (bottom, top) in a native-thread-local — correct
+// under M:N (each native thread caches its own stack) and ~free after the first
+// op on a thread. (0, 0) if it can't be queried.
+thread_local! {
+    static STACK_BOUNDS: std::cell::Cell<(usize, usize)> =
+        const { std::cell::Cell::new((0, 0)) };
+}
+
+fn native_stack_bounds_cached() -> (usize, usize) {
+    STACK_BOUNDS.with(|c| {
+        let cached = c.get();
+        if cached.0 != 0 {
+            return cached;
+        }
+        let bounds = native_stack_bounds();
+        c.set(bounds);
+        bounds
+    })
+}
+
+// (bottom, top) of the CURRENT native thread's stack via pthread (uncached —
+// callers go through native_stack_bounds_cached). The stack grows DOWN from top
+// toward bottom. (0, 0) if it can't be queried. NB: this is the NATIVE thread's
+// pthread stack; a Ruby Fiber runs on a separate mmap'd stack invisible here.
+#[cfg(target_os = "linux")]
+fn native_stack_bounds() -> (usize, usize) {
+    unsafe {
+        let mut attr: libc::pthread_attr_t = std::mem::zeroed();
+        if libc::pthread_getattr_np(libc::pthread_self(), &mut attr) != 0 {
+            return (0, 0);
+        }
+        let mut addr: *mut c_void = null_mut();
+        let mut size: libc::size_t = 0;
+        let rc = libc::pthread_attr_getstack(&attr, &mut addr, &mut size);
+        libc::pthread_attr_destroy(&mut attr);
+        if rc != 0 {
+            return (0, 0);
+        }
+        (addr as usize, addr as usize + size)
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn native_stack_bounds() -> (usize, usize) {
+    unsafe {
+        let top = libc::pthread_get_stackaddr_np(libc::pthread_self()) as usize;
+        let size = libc::pthread_get_stacksize_np(libc::pthread_self());
+        (top.saturating_sub(size), top)
+    }
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+fn native_stack_bounds() -> (usize, usize) {
+    (0, 0)
+}
+
+// Lower bound (and upper, for caching) of the memory region containing `addr`
+// — i.e. the BOTTOM of the stack `addr` is on. Used for a Ruby Fiber, whose
+// mmap'd stack pthread can't see: V8's limit must sit ABOVE this bottom or a
+// deep fiber recursion overflows the real stack and SEGVs the unmapped guard.
+// Cached per native thread keyed by the region (parsing /proc/self/maps is
+// slow): reused while successive ops stay on the same fiber. (0, 0) if unknown.
+thread_local! {
+    static FIBER_REGION: std::cell::Cell<(usize, usize)> = const { std::cell::Cell::new((0, 0)) };
+}
+
+fn current_region_bounds_cached(addr: usize) -> (usize, usize) {
+    FIBER_REGION.with(|c| {
+        let (lo, hi) = c.get();
+        if lo != 0 && addr >= lo && addr < hi {
+            return (lo, hi);
+        }
+        let bounds = query_region_bounds(addr);
+        if bounds.0 != 0 {
+            c.set(bounds);
+        }
+        bounds
+    })
+}
+
+// The [start, end) of the /proc/self/maps mapping containing `addr`. Linux only;
+// (0, 0) elsewhere (and the caller falls back). Reads the file fresh — slow, so
+// only called on a cache miss (a new fiber).
+#[cfg(target_os = "linux")]
+fn query_region_bounds(addr: usize) -> (usize, usize) {
+    use std::io::Read;
+    let mut buf = String::new();
+    if std::fs::File::open("/proc/self/maps")
+        .and_then(|mut f| f.read_to_string(&mut buf))
+        .is_err()
+    {
+        return (0, 0);
+    }
+    for line in buf.lines() {
+        // e.g. "7f6a...000-7f6a...000 rw-p 00000000 00:00 0 ..."
+        let Some((range, _)) = line.split_once(' ') else {
+            continue;
+        };
+        let Some((lo, hi)) = range.split_once('-') else {
+            continue;
+        };
+        if let (Ok(lo), Ok(hi)) = (
+            usize::from_str_radix(lo, 16),
+            usize::from_str_radix(hi, 16),
+        ) {
+            if addr >= lo && addr < hi {
+                return (lo, hi);
+            }
+        }
+    }
+    (0, 0)
+}
+
+#[cfg(not(target_os = "linux"))]
+fn query_region_bounds(_addr: usize) -> (usize, usize) {
+    (0, 0)
+}
+
+// Set from RUSTY_RACER_STACK_DEBUG at init; gates the per-op stack diagnostics.
+pub(crate) static STACK_DEBUG: AtomicBool = AtomicBool::new(false);
+
+// Re-point V8's stack limit at the CURRENT stack each op. In-thread V8 runs
+// wherever the Ruby code is: usually the native thread's pthread stack, but also
+// a Ruby Fiber's separate mmap'd stack (Capybara::Result is an Enumerator) that
+// pthread can't see. The limit MUST sit between the current SP and the real
+// bottom of whatever stack we're on:
+//   * Too high (above SP) and V8 declares a FALSE overflow on entry.
+//   * Too low (below the real bottom) and a deep recursion grows past the
+//     mapped stack and SEGVs the unmapped guard page below it.
+// So detect the stack by comparing the SP to the cached native bounds: on the
+// native stack, anchor to its pthread bottom; on a fiber, find the bottom of the
+// /proc/self/maps region holding the SP (the fiber's real bottom — anchoring to
+// SP minus a fixed guard punched through the bottom of Avo's small/deep Capybara
+// fibers and SEGV'd). Must be called with the isolate ENTERED. `real_isolate` is
+// the raw v8::Isolate* read out of iso_ptr.
+//
+// On a fiber it ALSO re-points V8's conservative-GC-scan stack_start (via
+// scan_start_field, discovered once per isolate) to `stack_top`: Enter just set
+// it to the native top, but the scanner walks [marker, stack_start), so a native
+// start runs the scan off the fiber's mapped stack into unmapped memory and
+// SEGVs (Avo's Capybara filter chain). scan_start_field is 0 when discovery
+// failed (override disabled).
+//
+// LIMITATION (worker-thread fibers): the GC and a thrown exception ALSO
+// `CHECK(IsOnCentralStack(SP))`, which tests the SP against
+// `base::Stack::GetStackStart()` — the pthread top, cached per native thread,
+// with no API to retarget — NOT the scan start we re-point above. A fiber mmap'd
+// ABOVE that top (the common case on a NON-main native thread, whose stack sits
+// below later fiber mmaps) fails the CHECK, so V8 aborts on the next GC or throw.
+// We can fix the scan (the SEGV) but not that CHECK. On the main thread the
+// process stack is the highest address, so every fiber is below it and both the
+// scan and the CHECK are safe — the Capybara/Avo case. See README.
+pub(crate) fn set_v8_stack_limit(real_isolate: *mut c_void, scan_start_field: usize, stack_top: usize) {
+    let sp_marker = 0u8;
+    let sp = &sp_marker as *const u8 as usize;
+    let (nbottom, ntop) = native_stack_bounds_cached();
+    let on_native = nbottom != 0 && sp > nbottom && sp <= ntop;
+    // Reserve below the limit for V8's own RangeError-throw frames.
+    const NATIVE_GUARD: usize = 128 * 1024;
+    // V8 throws when SP descends to the limit, then needs some real stack BELOW
+    // it to build the RangeError (and V8 itself allows growing a little past the
+    // limit — its overflow slack). On a fiber that reserve must NOT cross the
+    // fiber's real bottom (the mapping below it is an unmapped guard -> SEGV), so
+    // keep it comfortably above V8's slack.
+    const FIBER_RESERVE: usize = 64 * 1024;
+    let mut region = (0usize, 0usize);
+    let limit = if on_native {
+        nbottom + NATIVE_GUARD
+    } else {
+        // Anchor to the FIBER's real bottom (the /proc/self/maps region holding
+        // the SP), not the SP: SP - fixed_guard can punch through the bottom of a
+        // small/deep fiber stack and SEGV (Avo's deep Capybara filter chain).
+        // Reserve FIBER_RESERVE above the bottom for the throw, but keep the
+        // limit below the SP so we don't false-overflow; on a nearly-full fiber
+        // that clamps the headroom down (an early but CLEAN RangeError).
+        region = current_region_bounds_cached(sp);
+        if region.0 != 0 {
+            (region.0 + FIBER_RESERVE).min(sp.saturating_sub(8 * 1024))
+        } else {
+            sp.saturating_sub(64 * 1024) // region unknown (non-linux) — best effort
+        }
+    };
+    if limit == 0 {
+        return; // couldn't determine a sane limit — leave V8's default
+    }
+    unsafe { v8__Isolate__SetStackLimit(real_isolate, limit) };
+    // On a fiber, re-point V8's conservative-GC-scan stack_start to `stack_top`
+    // — a live address captured by the caller ABOVE every V8 frame of this op.
+    // Enter() set the start to the NATIVE top (a different region); the scanner
+    // walks [marker, start), so a native start runs it off the fiber's mapped
+    // top into unmapped memory and SEGVs. Anchoring to stack_top keeps the whole
+    // scan range between two real stack pointers (marker..stack_top), so it's
+    // guaranteed mapped, and every V8 root (all below stack_top) is still found.
+    // (We can't use the /proc/maps region top here: that mapping isn't reliably
+    // contiguous, so the scan could still hit a hole below it.)
+    if !on_native && stack_top != 0 && scan_start_field != 0 {
+        unsafe { (scan_start_field as *mut usize).write(stack_top) };
+    }
+    // Opt-in diagnostics (RUSTY_RACER_STACK_DEBUG): the SP vs the native stack
+    // [nbottom, ntop], the fiber region (if any), the per-op limit, and whether
+    // the SP is above the limit. A crash with sp_above_limit=false means the
+    // limit is wrong for the current stack.
+    if STACK_DEBUG.load(Ordering::Relaxed) {
+        eprintln!(
+            "[rusty stack] sp={sp:#x} nbottom={nbottom:#x} ntop={ntop:#x} \
+             region=[{:#x},{:#x}) limit={limit:#x} fiber={} sp_above_limit={} \
+             fiber_above_native={}",
+            region.0,
+            region.1,
+            !on_native,
+            sp > limit,
+            !on_native && nbottom != 0 && sp > ntop,
+        );
+    }
+}

data/ext/rusty_racer/src/watchdog.rs

@@ -0,0 +1,226 @@
+// The execution watchdog: a persistent per-isolate thread that fires
+// TerminateExecution when an armed deadline passes, plus the request bracket
+// (run_js_bracketed) that arms/disarms it around every JS-running op and maps a
+// fired deadline to VmError::Terminated. Extracted from lib.rs verbatim.
+//
+// Only WatchdogShared is pub(crate) (IsolateState holds the Arc<WatchdogShared>
+// and watchdog_loop takes it); its fields and the whole WatchdogInner/
+// WatchdogFrame state stay PRIVATE — lib.rs touches the watchdog through just
+// two methods, WatchdogShared::new() (initial state) and request_shutdown()
+// (teardown: set the flag + wake the loop). run_js_bracketed, arm_watchdog,
+// disarm_watchdog, watchdog_loop and WATCHDOG_DEBUG are pub(crate) because the
+// op handlers and isolate setup (still in lib.rs) call them;
+// report_watchdog_anomaly is private to this module.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Condvar, Mutex};
+use std::time::{Duration, Instant};
+
+use crate::istate;
+use crate::{IsolateState, JsVal, VmError};
+
+// The watchdog runs on ONE persistent thread per isolate rather than a fresh
+// std::thread per request: spawning + joining a thread on every op cost ~16µs
+// (5.5x) when a timeout was set, dwarfing the actual work. The thread sleeps on
+// a condvar until a deadline is armed, terminates execution once the deadline
+// passes, then goes back to sleep.
+pub(crate) struct WatchdogShared {
+    inner: Mutex<WatchdogInner>,
+    cv: Condvar,
+}
+
+impl WatchdogShared {
+    // The initial (idle) watchdog state, boxed in the Arc IsolateState holds.
+    pub(crate) fn new() -> Arc<Self> {
+        Arc::new(WatchdogShared {
+            inner: Mutex::new(WatchdogInner {
+                frames: Vec::new(),
+                next_generation: 0,
+                fired_generation: None,
+                shutdown: false,
+            }),
+            cv: Condvar::new(),
+        })
+    }
+
+    // Signal the loop to stop and wake it. Called once at isolate teardown,
+    // before the isolate is touched, so the loop can't fire a terminate into an
+    // isolate we're mid-disposing.
+    pub(crate) fn request_shutdown(&self) {
+        self.inner.lock().unwrap().shutdown = true;
+        self.cv.notify_one();
+    }
+}
+
+// One armed request's deadline. `run_js_bracketed` is RE-ENTRANT — a host fn
+// called from JS can issue a nested op that arms again while the outer op is
+// still running — so the armed deadlines form a LIFO stack, not a single slot.
+// (The old per-op design gave each op its own watchdog thread; collapsing onto
+// one thread must not let a nested arm/disarm clobber the outer op's deadline,
+// or the outer op would run unbounded after the nested call returns.)
+#[derive(Clone, Copy)]
+struct WatchdogFrame {
+    generation: u64,
+    deadline: Instant,
+}
+
+struct WatchdogInner {
+    // Every currently-armed op (with timeout_ms > 0), pushed on arm and removed
+    // on disarm. The loop honours the EARLIEST deadline across all frames: the
+    // most urgent timeout fires first, and since TerminateExecution is
+    // isolate-global it tears down whatever is running (escalating outward).
+    frames: Vec<WatchdogFrame>,
+    // Monotonic; each arm takes the next value as its frame's id.
+    next_generation: u64,
+    // The generation whose deadline the loop terminated on — consumed (and
+    // cleared) by that op's disarm so it can map its outcome to Terminated.
+    fired_generation: Option<u64>,
+    // Set at isolate teardown to break the loop.
+    shutdown: bool,
+}
+
+// The persistent watchdog loop. Runs off a Send IsolateHandle so it never
+// borrows the isolate the V8 thread owns.
+pub(crate) fn watchdog_loop(shared: Arc<WatchdogShared>, handle: v8::IsolateHandle) {
+    let mut inner = shared.inner.lock().unwrap();
+    loop {
+        if inner.shutdown {
+            return;
+        }
+        // The earliest deadline among all armed frames is the one to enforce.
+        match inner.frames.iter().min_by_key(|f| f.deadline).copied() {
+            // Idle: sleep until a frame is armed (or shutdown).
+            None => inner = shared.cv.wait(inner).unwrap(),
+            Some(frame) => {
+                let now = Instant::now();
+                if now >= frame.deadline {
+                    handle.terminate_execution();
+                    inner.fired_generation = Some(frame.generation);
+                    // Drop the fired frame so the loop moves on to the next
+                    // deadline instead of re-firing this one every wakeup.
+                    inner.frames.retain(|f| f.generation != frame.generation);
+                } else {
+                    let (next, _) = shared.cv.wait_timeout(inner, frame.deadline - now).unwrap();
+                    inner = next;
+                }
+            }
+        }
+    }
+}
+
+// (The watchdog Arc now lives in IsolateState; arm/disarm reach it via istate!.)
+
+// Arm the watchdog for this request: push a frame with its own deadline and
+// wake the loop. Returns the generation token to hand to `disarm_watchdog`
+// (None when timeout_ms is 0 — no watchdog for this request).
+pub(crate) fn arm_watchdog(scope: &mut v8::PinScope<'_, '_, ()>, timeout_ms: u64) -> Option<u64> {
+    if timeout_ms == 0 {
+        return None;
+    }
+    let shared = &istate!(scope).watchdog;
+    let mut inner = shared.inner.lock().unwrap();
+    inner.next_generation += 1;
+    let generation = inner.next_generation;
+    inner.frames.push(WatchdogFrame {
+        generation,
+        deadline: Instant::now() + Duration::from_millis(timeout_ms),
+    });
+    shared.cv.notify_one();
+    Some(generation)
+}
+
+// Disarm: drop THIS request's frame (leaving any outer frame still armed) and
+// report whether its deadline fired. On fire the caller maps the outcome to
+// Terminated and the outermost frame sweeps the leftover terminate via
+// WATCHDOG_FIRED; removing only this frame keeps a late terminate from
+// poisoning the next request without clobbering a still-running outer op.
+pub(crate) fn disarm_watchdog(scope: &mut v8::PinScope<'_, '_, ()>, generation: Option<u64>) -> bool {
+    let Some(generation) = generation else {
+        return false;
+    };
+    let shared = &istate!(scope).watchdog;
+    let mut inner = shared.inner.lock().unwrap();
+    inner.frames.retain(|f| f.generation != generation);
+    let fired = inner.fired_generation == Some(generation);
+    if fired {
+        inner.fired_generation = None;
+    }
+    shared.cv.notify_one();
+    fired
+}
+
+// Set from RUSTY_RACER_WATCHDOG_DEBUG at init (OFF by default); gates the
+// watchdog-anomaly canary in run_js_bracketed — a diagnostic for the rare
+// next-op-spuriously-terminated leak. Off in production (it would also fire on a
+// legitimate Isolate#terminate); CI turns it on so a recurrence is diagnosable.
+pub(crate) static WATCHDOG_DEBUG: AtomicBool = AtomicBool::new(false);
+
+// The shared bracket every JS-running request (Eval/Call/Attach/RunScript/
+// EvaluateModule) needs: arm the watchdog, run |body|, then on a watchdog
+// timeout flag the leftover terminate for the outermost sweep and — only if
+// |body| actually ran JS (the bool it returns) — override its outcome to
+// Terminated. |body| owns its ContextScope, JS call, and auto_drain, and
+// returns (ran_js, outcome); the realm-disposed/unknown paths return
+// (false, Err(..)) so a raced watchdog can't poison an error for work that ran
+// no JS. Collapsing the five arms onto this keeps the terminate discipline in
+// ONE place.
+pub(crate) fn run_js_bracketed(
+    scope: &mut v8::PinScope<'_, '_, ()>,
+    outermost: bool,
+    timeout_ms: u64,
+    label: &'static str,
+    body: impl FnOnce(&mut v8::PinScope<'_, '_, ()>, bool) -> (bool, Result<JsVal, VmError>),
+) -> Result<JsVal, VmError> {
+    let started = Instant::now();
+    let watchdog = arm_watchdog(scope, timeout_ms);
+    let (ran_js, mut outcome) = body(scope, outermost);
+    let fired = disarm_watchdog(scope, watchdog);
+    // CANARY (RUSTY_RACER_WATCHDOG_DEBUG): the op's JS was terminated but THIS
+    // op's OWN watchdog frame did NOT fire — so a terminate LEAKED in from
+    // elsewhere (a prior op's timeout surviving both the end- and start-sweep
+    // cancels, or a user Isolate#terminate). The rare CI "next op spuriously
+    // terminated" bug lands here; dump the watchdog state + timing so a
+    // recurrence is diagnosable instead of an unreproducible mystery.
+    if WATCHDOG_DEBUG.load(Ordering::Relaxed)
+        && ran_js
+        && !fired
+        && matches!(outcome, Err(VmError::Terminated))
+    {
+        report_watchdog_anomaly(scope, label, watchdog, timeout_ms, started.elapsed());
+    }
+    if fired {
+        istate!(scope).watchdog_fired = true;
+        if ran_js {
+            outcome = Err(VmError::Terminated);
+        }
+    }
+    outcome
+}
+
+// Dump watchdog/terminate state on the leaked-terminate anomaly (see the CANARY
+// in run_js_bracketed). Only reached on that rare path, and only with the debug
+// flag on. elapsed_ms << timeout_ms with a clean inner = a V8-level stale
+// terminate (not the Rust bookkeeping); a non-empty inner.frames /
+// fired_generation would instead point at a frame-lifecycle bug.
+fn report_watchdog_anomaly(
+    scope: &mut v8::PinScope<'_, '_, ()>,
+    label: &str,
+    this_gen: Option<u64>,
+    timeout_ms: u64,
+    elapsed: Duration,
+) {
+    let terminating = scope.is_execution_terminating();
+    let st = istate!(scope);
+    let watchdog_fired_flag = st.watchdog_fired;
+    let inner = st.watchdog.inner.lock().unwrap();
+    let frames: Vec<u64> = inner.frames.iter().map(|f| f.generation).collect();
+    eprintln!(
+        "[rusty watchdog ANOMALY] op={label} terminated but its OWN watchdog frame \
+         did NOT fire (leaked terminate). this_gen={this_gen:?} timeout_ms={timeout_ms} \
+         elapsed_ms={:.2} is_terminating={terminating} watchdog_fired_flag={watchdog_fired_flag} \
+         inner.frames={frames:?} inner.fired_generation={:?} inner.next_generation={}",
+        elapsed.as_secs_f64() * 1000.0,
+        inner.fired_generation,
+        inner.next_generation,
+    );
+}

data/lib/rusty_racer/execjs.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# An ExecJS runtime backed by rusty_racer, so any ExecJS consumer (asset
+# pipelines, CoffeeScript/Babel/Uglify wrappers, …) can run on V8-in-Ruby with
+# no code change: `require "rusty_racer/execjs"` then
+#
+#   ExecJS.runtime = RustyRacer::ExecJSRuntime.new
+#
+# This file is OPTIONAL — rusty_racer never loads it itself, so execjs stays a
+# non-dependency. Requiring it declares you want the integration (and so have
+# execjs installed).
+#
+# Values cross the boundary with ExecJS's JSON semantics, not rusty_racer's
+# richer native marshalling: every result is taken through `JSON.stringify` on
+# the V8 side and parsed back. That is exactly the contract ExecJS's external
+# runtimes (Node, …) provide — functions and `undefined` drop out
+# (`[1, function(){}]` => `[1, nil]`, `{a:1, f(){}}` => `{"a"=>1}`), Dates become
+# ISO strings — so a consumer sees identical results whatever runtime it picked.
+
+require 'json'
+require 'execjs'
+require 'rusty_racer'
+
+module RustyRacer
+  class ExecJSRuntime < ExecJS::Runtime
+    class Context < ExecJS::Runtime::Context
+      # `filename` for every JS run, so a thrown error's stack (which rusty_racer
+      # surfaces as the Ruby backtrace) reads "(execjs):line:col" — ExecJS's test
+      # suite asserts the backtrace mentions "(execjs):".
+      LOCATION = '(execjs)'
+
+      def initialize(_runtime, source = '', _options = {})
+        @isolate = RustyRacer::Isolate.new
+        @context = @isolate.context
+        # ExecJS guarantees a bare global (no browser/Node ambient): V8 installs a
+        # default `console`, so drop it to match the contract (consumers attach
+        # their own if needed), exactly as the mini_racer runtime does.
+        @context.eval('delete globalThis.console')
+        source = encode(source)
+        translate { @context.eval(source, filename: LOCATION) } if /\S/.match?(source)
+      end
+
+      # Run statements in a function body and return what they `return` (nil when
+      # nothing is returned), per ExecJS. The trailing newline before `}` ends any
+      # `//` line comment the source closes with, so it can't eat the wrapper.
+      def exec(source, _options = {})
+        source = encode(source)
+        eval("(function(){#{source}\n})()") if /\S/.match?(source)
+      end
+
+      # Evaluate an expression and return its (JSON-projected) value. Blank source
+      # is nil. The expression is parenthesised so a leading `{` reads as an
+      # object literal (and a trailing `//` comment can't swallow the closing
+      # parens — hence the newline), then routed through JSON.stringify for ExecJS
+      # semantics.
+      def eval(source, _options = {})
+        source = encode(source)
+        return unless /\S/.match?(source)
+
+        json = translate { @context.eval("JSON.stringify((#{source}\n))", filename: LOCATION) }
+        # JSON.stringify yields `undefined` (-> nil here) for a function/undefined
+        # result; otherwise a JSON string to parse back.
+        json.nil? ? nil : JSON.parse(json)
+      end
+
+      # Evaluate `identifier` to a function and call it with the global object as
+      # `this` and the (JSON-marshalled) args. `identifier` is arbitrary JS — a
+      # name path ("a.b.fn"), a member expression, or a function literal — so it
+      # is applied rather than looked up. The newline guards a trailing comment as
+      # in eval/exec.
+      def call(identifier, *args)
+        eval("(#{encode(identifier)}\n).apply(this, #{JSON.generate(args)})")
+      end
+
+      private
+
+      # ExecJS speaks UTF-8. Encoding here both normalises the source and turns a
+      # genuinely binary input into the Encoding::UndefinedConversionError ExecJS
+      # expects, rather than feeding mojibake to V8.
+      def encode(source)
+        source.encode(Encoding::UTF_8)
+      end
+
+      # Map rusty_racer's exception family onto ExecJS's: a compile/syntax failure
+      # is an ExecJS::RuntimeError, a thrown-at-runtime error (or a terminated
+      # script) is an ExecJS::ProgramError. ExecJS asserts the backtrace mentions
+      # "(execjs):". A thrown error already carries the JS stack tagged with our
+      # LOCATION filename; a parse error has only the Ruby call stack, so give it
+      # a synthetic "(execjs):1" frame instead of leaking rusty internals.
+      def translate
+        yield
+      rescue RustyRacer::ParseError => e
+        raise wrap(ExecJS::RuntimeError, e.message, ["#{LOCATION}:1"])
+      rescue RustyRacer::EvalError => e
+        backtrace = Array(e.backtrace)
+        backtrace = ["#{LOCATION}:1"] if backtrace.empty?
+        raise wrap(ExecJS::ProgramError, e.message, backtrace)
+      end
+
+      def wrap(klass, message, backtrace)
+        ex = klass.new(message)
+        ex.set_backtrace(backtrace)
+        ex
+      end
+    end
+
+    def name
+      'RustyRacer (V8)'
+    end
+
+    def available?
+      require 'rusty_racer'
+      true
+    rescue LoadError
+      false
+    end
+  end
+end

data/lib/rusty_racer/version.rb

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