Complete Exception backtrace: raise-time stack, qualified names, memoization (#896)

CRuby's `Exception#backtrace` reports the full live stack at raise time.
monoruby only recorded the frames the exception actually unwound through
(raise site down to the rescuing frame), so a backtrace for an exception
raised and rescued in the same method was missing that frame's callers.

- Add `Executor::complete_backtrace_for_rescue`, called once at the catch
  point (`handle_error`'s rescue branch, before `take_ex_obj`). It walks
  the still-live caller frames of the rescuing frame via each inner
  frame's saved call-site pc (the same mechanism as `Kernel#caller`) and
  appends the cheap `(loc, sourceinfo, fid)` tuples. No string formatting
  happens here — that stays lazy in `#backtrace`. Control-flow
  pseudo-errors (MethodReturn / BlockBreak / Throw) never reach this path,
  so they pay nothing, keeping raise cheap.

- Render backtrace frame owners with their fully-qualified name in
  `func_description` (`Ns::Cx.foo`, not `Cx.foo`), special-casing Object
  so plain top-level methods still read as `Object#foo`.

- Memoize `#backtrace` into the `/backtrace` hidden ivar so repeated calls
  return the same mutable Array (`e.backtrace.unshift(x)` is visible next
  call; `e.dup.backtrace` is a distinct object). `set_backtrace` writes
  the same ivar, unifying the explicit store with the memo.

- Decouple `#backtrace_locations` from the string backtrace via a new
  `__raise_backtrace` intrinsic (raise-time capture only), so
  `set_backtrace(strings)` on a never-raised exception keeps
  `#backtrace_locations` nil, and an Array of Locations sets both.

Fixes core/exception backtrace_spec, backtrace_locations_spec, and
set_backtrace_spec. Adds tests/backtrace.rs (6 differential tests).


Claude-Session: https://claude.ai/code/session_01XpzdoFu46d2ChJpSzeWsNK

Co-authored-by: Claude <noreply@anthropic.com>

Author: sisshiki1969

monoruby/builtins/startup.rb

@@ -996,11 +996,17 @@ class ThreadError < StandardError; end unless defined?(::ThreadError)
 
 class Exception
   def backtrace_locations
-    bt = backtrace
-    return nil if bt.nil?
-    bt.map do |frame|
-      Thread::Backtrace::Location.new(frame)
-    end
+    # Locations come from the raise-time capture, independent of any
+    # string backtrace installed via #set_backtrace (CRuby: after
+    # `set_backtrace(strings)` on a never-raised exception,
+    # #backtrace_locations stays nil). Memoized so repeated calls
+    # return the same, mutable Array.
+    # A prior #backtrace_locations memo, or locations installed via
+    # set_backtrace(locations), win over re-deriving from the capture.
+    return @backtrace_locations if defined?(@backtrace_locations) && @backtrace_locations
+    frames = __raise_backtrace
+    return nil if frames.nil?
+    @backtrace_locations = frames.map { |f| Thread::Backtrace::Location.new(f) }
   end
 
   # CRuby 3.4+: `set_backtrace` (and thus `$@ =`) also accepts an Array
@@ -1009,8 +1015,13 @@ def backtrace_locations
   # raises the usual TypeError.
   def set_backtrace(bt)
     if bt.is_a?(Array) && !bt.empty? && bt.all? { |e| Thread::Backtrace::Location === e }
+      # CRuby 3.4+: an Array of Locations sets both the string backtrace
+      # and #backtrace_locations.
       __set_backtrace(bt.map(&:to_s))
+      @backtrace_locations = bt
     else
+      # Setting a string backtrace leaves #backtrace_locations as it was
+      # (the raise-time capture, or nil), so don't touch the memo here.
       __set_backtrace(bt)
     end
   end

monoruby/src/builtins/exception.rs

@@ -137,6 +137,7 @@ pub(super) fn init(globals: &mut Globals) {
     globals.define_builtin_func_with(EXCEPTION_CLASS, "initialize", initialize, 0, 2, false);
     globals.define_builtin_func(EXCEPTION_CLASS, "message", message, 0);
     globals.define_builtin_func(EXCEPTION_CLASS, "backtrace", backtrace, 0);
+    globals.define_builtin_func(EXCEPTION_CLASS, "__raise_backtrace", raise_backtrace, 0);
     globals.define_builtin_func(EXCEPTION_CLASS, "set_backtrace", set_backtrace, 1);
     // Internal alias: `startup.rb` redefines `set_backtrace` with a Ruby
     // wrapper that also accepts `Thread::Backtrace::Location` arrays
@@ -485,6 +486,37 @@ fn backtrace(_vm: &mut Executor, globals: &mut Globals, lfp: Lfp, _: BytecodePtr
         // raised, so there is no backtrace to report.
         return Ok(Value::nil());
     }
+    // Memoize the built array so repeated `#backtrace` calls return the
+    // *same* object (CRuby: `e.backtrace.unshift(...)` is visible on the
+    // next `#backtrace`, and `e.dup.backtrace.equal?(e.backtrace)`).
+    let array = Value::array_from_iter(traces.into_iter().map(|s| Value::string(s)));
+    globals
+        .store
+        .set_ivar(self_, IdentId::get_id("/backtrace"), array)?;
+    Ok(array)
+}
+
+///
+/// ### Exception#__raise_backtrace (monoruby intrinsic)
+///
+/// The raise-time captured backtrace strings (nil if the exception was
+/// never raised), *independent* of any string backtrace installed via
+/// `#set_backtrace`. `#backtrace_locations` builds on this so a
+/// `set_backtrace(strings)` on a never-raised exception keeps
+/// `#backtrace_locations` nil, matching CRuby.
+///
+#[monoruby_builtin]
+fn raise_backtrace(
+    _vm: &mut Executor,
+    globals: &mut Globals,
+    lfp: Lfp,
+    _: BytecodePtr,
+) -> Result<Value> {
+    let self_ = lfp.self_val();
+    let traces: Vec<String> = self_.is_exception().unwrap().trace_location(globals);
+    if traces.is_empty() {
+        return Ok(Value::nil());
+    }
     Ok(Value::array_from_iter(
         traces.into_iter().map(|s| Value::string(s)),
     ))

monoruby/src/codegen/jit_module.rs

@@ -249,6 +249,11 @@ pub(super) extern "C" fn handle_error(
                 return ErrorReturn::return_err();
             }
             if let Some((Some(rescue), _, err_reg)) = info.get_exception_dest(pc) {
+                // Fill in the callers of this rescuing frame so the
+                // backtrace matches CRuby's raise-time stack even when
+                // the exception is raised and rescued in the same
+                // method. Cheap tuple walk; formatting stays lazy.
+                vm.complete_backtrace_for_rescue(&globals.store);
                 let err_val = vm.take_ex_obj(globals);
                 vm.set_errinfo(err_val);
                 if let Some(err_reg) = err_reg {

monoruby/src/executor.rs

@@ -1391,6 +1391,75 @@ impl Executor {
             None => unreachable!(),
         };
     }
+
+    ///
+    /// Complete the pending exception's backtrace with the frames that
+    /// are *above* the rescuing frame.
+    ///
+    /// The incremental `push_error_location` path only records the
+    /// frames the exception actually unwinds through — from the raise
+    /// site down to the frame whose `rescue` catches it. CRuby's
+    /// backtrace additionally includes that frame's callers (the rest
+    /// of the live stack at raise time). When an exception is raised and
+    /// rescued within the same method those callers would otherwise be
+    /// missing entirely.
+    ///
+    /// This is called once, at the catch point (`take_ex_obj` in
+    /// `handle_error`'s rescue branch), while the caller frames are
+    /// still live on the stack. It only walks the cheap
+    /// `(loc, sourceinfo, fid)` tuples — no string formatting, which
+    /// stays lazy in `Exception#backtrace`. Control-flow pseudo-errors
+    /// (`MethodReturn` / `BlockBreak` / `Throw`) never reach this path,
+    /// so they pay nothing.
+    ///
+    pub(crate) fn complete_backtrace_for_rescue(&mut self, store: &Store) {
+        if self.exception.is_none() {
+            return;
+        }
+        // Start at the rescuing frame (already recorded); walk its
+        // callers via each inner frame's saved call-site pc, exactly
+        // like `Kernel#caller`.
+        let rescue_cfp = self.cfp();
+        let mut inner_cfp = rescue_cfp;
+        let mut cfp = match rescue_cfp.prev() {
+            Some(prev) => prev,
+            None => return,
+        };
+        loop {
+            let func_id = cfp.lfp().func_id();
+            if let Some(iseq_id) = store[func_id].is_iseq() {
+                let info = &store[iseq_id];
+                // The caller's suspended line: the call-site pc it saved
+                // into its callee's cont-frame slot. Fall back to the
+                // method's definition location when the slot is absent
+                // or out of range (invoker boundary, unaudited path).
+                let loc = {
+                    let slot = inner_cfp.caller_pc_slot();
+                    if slot != 0
+                        && slot % 8 == 0
+                        && let Some(pc) = unsafe { crate::bytecode::BytecodePtr::from_raw(slot as *mut _) }
+                        && info.contains_pc(pc)
+                    {
+                        let idx = info.get_pc_index(Some(pc)).to_usize();
+                        Some(info.sourcemap[idx])
+                    } else {
+                        None
+                    }
+                }
+                .unwrap_or(info.loc);
+                if let Some(err) = &mut self.exception {
+                    err.push_trace(loc, info.sourceinfo.clone(), func_id);
+                }
+            }
+            match cfp.prev() {
+                Some(prev) => {
+                    inner_cfp = cfp;
+                    cfp = prev;
+                }
+                None => break,
+            }
+        }
+    }
 }
 
 //

monoruby/src/globals/store.rs

@@ -427,11 +427,22 @@ impl Store {
                 String::new()
             }
         };
+        // CRuby renders the owner with its *fully-qualified* name
+        // (`ExceptionSpecs::Backtrace.foo`, not `Backtrace.foo`).
+        // `qualified_name` returns "" for Object, where the legacy
+        // display is the bare "Object", so special-case it.
+        let qual = |this: &Self, id: ClassId| {
+            if id == OBJECT_CLASS {
+                "Object".to_string()
+            } else {
+                this.qualified_name(id)
+            }
+        };
         match info.owner_class().get(0) {
             Some(owner) => {
                 if let Some(obj) = self[*owner].get_module().is_singleton() {
                     if let Some(class) = obj.is_class_or_module() {
-                        format!("{}.{name}", class.id().get_name(self))
+                        format!("{}.{name}", qual(self, class.id()))
                     } else {
                         // CRuby names a plain object's singleton
                         // method by the bare method name (only
@@ -440,7 +451,7 @@ impl Store {
                         name
                     }
                 } else {
-                    format!("{}#{name}", owner.get_name(self))
+                    format!("{}#{name}", qual(self, *owner))
                 }
             }
             None => name,

monoruby/tests/backtrace.rs

@@ -0,0 +1,93 @@
+//! Differential coverage for `Exception#backtrace` / `#backtrace_locations`
+//! / `#set_backtrace`: the raise-time stack is captured in full (even when
+//! the exception is raised and rescued within the same method), frame
+//! labels use fully-qualified class names, and the returned array is
+//! memoized. Compared against the reference CRuby.
+
+use monoruby::tests::*;
+
+#[test]
+fn backtrace_includes_callers_when_rescued_in_same_method() {
+    run_test_once(
+        r#"
+        def inner
+          begin
+            raise "x"
+          rescue => e
+            return e.backtrace.map { |l| l.sub(/\A.*:(\d+:in )/, '\1') }
+          end
+        end
+        def outer; inner; end
+        outer
+        "#,
+    );
+}
+
+#[test]
+fn backtrace_propagated_full_chain() {
+    run_test_once(
+        r#"
+        def a; raise "x"; end
+        def b; a; end
+        def c; b; end
+        begin
+          c
+        rescue => e
+          e.backtrace.map { |l| l.sub(/\A.*:(\d+:in )/, '\1') }
+        end
+        "#,
+    );
+}
+
+#[test]
+fn backtrace_uses_qualified_class_name() {
+    run_test_once(
+        r#"
+        module NsX
+          class Cx
+            def self.boom; raise "x"; end
+          end
+        end
+        begin
+          NsX::Cx.boom
+        rescue => e
+          e.backtrace.first.sub(/\A.*:\d+:in /, '')
+        end
+        "#,
+    );
+}
+
+#[test]
+fn backtrace_array_is_memoized_and_mutable() {
+    run_test_once(
+        r#"
+        begin
+          raise "x"
+        rescue => e
+          e.backtrace.unshift("first")
+          [e.backtrace[0], e.backtrace.equal?(e.backtrace), e.dup.backtrace.equal?(e.backtrace)]
+        end
+        "#,
+    );
+}
+
+#[test]
+fn set_backtrace_strings_leaves_locations_nil() {
+    run_test_once(
+        r#"
+        err = RuntimeError.new
+        before = [err.backtrace, err.backtrace_locations]
+        err.set_backtrace(["a.rb:1:in 'x'"])
+        [before, err.backtrace, err.backtrace_locations]
+        "#,
+    );
+}
+
+#[test]
+fn backtrace_of_unraised_exception_is_nil() {
+    run_tests(&[
+        r#"Exception.new.backtrace"#,
+        r#"Exception.new.backtrace_locations"#,
+        r#"RuntimeError.new("x").backtrace"#,
+    ]);
+}