Introduce Address newtype for bytecode addresses (boa-dev#4862)

Replace raw `u32` with a typed `Address` wrapper for all bytecode
address fields in opcodes, handlers, labels, and the compiler. This
provides type safety to distinguish addresses from other u32 values
(register indices, counts, etc.) and displays addresses as hexadecimal
in bytecode dumps.

---------

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

Author: hansl

core/engine/src/bytecompiler/jump_control.rs

@@ -12,7 +12,7 @@
 use super::Register;
 use crate::{
     bytecompiler::{ByteCompiler, Label},
-    vm::{CallFrame, Handler},
+    vm::{CallFrame, Handler, opcode::Address},
 };
 use bitflags::bitflags;
 use boa_interner::Sym;
@@ -93,7 +93,11 @@ impl JumpRecord {
     }
 
     /// Performs the [`JumpRecordAction`]s.
-    pub(crate) fn perform_actions(mut self, start_address: u32, compiler: &mut ByteCompiler<'_>) {
+    pub(crate) fn perform_actions(
+        mut self,
+        start_address: Address,
+        compiler: &mut ByteCompiler<'_>,
+    ) {
         while let Some(action) = self.actions.pop() {
             match action {
                 JumpRecordAction::Transfer { index } => {
@@ -216,7 +220,7 @@ impl JumpRecord {
 #[derive(Debug)]
 pub(crate) struct JumpControlInfo {
     label: Option<Sym>,
-    start_address: u32,
+    start_address: Address,
     pub(crate) flags: JumpControlInfoFlags,
     pub(crate) jumps: Vec<JumpRecord>,
     current_open_environments_count: u32,
@@ -267,7 +271,7 @@ impl JumpControlInfo {
         self
     }
 
-    pub(crate) const fn with_start_address(mut self, address: u32) -> Self {
+    pub(crate) const fn with_start_address(mut self, address: Address) -> Self {
         self.start_address = address;
         self
     }
@@ -310,7 +314,7 @@ impl JumpControlInfo {
         self.label
     }
 
-    pub(crate) const fn start_address(&self) -> u32 {
+    pub(crate) const fn start_address(&self) -> Address {
         self.start_address
     }
 
@@ -356,7 +360,7 @@ impl JumpControlInfo {
     }
 
     /// Sets the `start_address` field of `JumpControlInfo`.
-    pub(crate) fn set_start_address(&mut self, start_address: u32) {
+    pub(crate) fn set_start_address(&mut self, start_address: Address) {
         self.start_address = start_address;
     }
 }
@@ -439,7 +443,7 @@ impl ByteCompiler<'_> {
     pub(crate) fn push_labelled_control_info(
         &mut self,
         label: Sym,
-        start_address: u32,
+        start_address: Address,
         use_expr: bool,
     ) {
         let new_info = JumpControlInfo::new(self.current_open_environments_count)
@@ -473,7 +477,7 @@ impl ByteCompiler<'_> {
     pub(crate) fn push_loop_control_info(
         &mut self,
         label: Option<Sym>,
-        start_address: u32,
+        start_address: Address,
         use_expr: bool,
     ) {
         let new_info = JumpControlInfo::new(self.current_open_environments_count)
@@ -488,7 +492,7 @@ impl ByteCompiler<'_> {
     pub(crate) fn push_loop_control_info_for_of_in_loop(
         &mut self,
         label: Option<Sym>,
-        start_address: u32,
+        start_address: Address,
         use_expr: bool,
     ) {
         let new_info = JumpControlInfo::new(self.current_open_environments_count)
@@ -503,7 +507,7 @@ impl ByteCompiler<'_> {
     pub(crate) fn push_loop_control_info_for_await_of_loop(
         &mut self,
         label: Option<Sym>,
-        start_address: u32,
+        start_address: Address,
         use_expr: bool,
     ) {
         let new_info = JumpControlInfo::new(self.current_open_environments_count)
@@ -539,7 +543,7 @@ impl ByteCompiler<'_> {
     pub(crate) fn push_switch_control_info(
         &mut self,
         label: Option<Sym>,
-        start_address: u32,
+        start_address: Address,
         use_expr: bool,
     ) {
         let new_info = JumpControlInfo::new(self.current_open_environments_count)
@@ -586,7 +590,7 @@ impl ByteCompiler<'_> {
     ///
     /// # Panic
     ///  - Will panic if popped `JumpControlInfo` is not for a try block.
-    pub(crate) fn pop_try_with_finally_control_info(&mut self, finally_start: u32) {
+    pub(crate) fn pop_try_with_finally_control_info(&mut self, finally_start: Address) {
         assert!(!self.jump_info.is_empty());
         let info = self.jump_info.pop().expect("no jump information found");
 

core/engine/src/bytecompiler/mod.rs

@@ -24,7 +24,7 @@ use crate::{
     js_string,
     vm::{
         CallFrame, CodeBlock, CodeBlockFlags, Constant, GeneratorResumeKind, Handler, InlineCache,
-        opcode::{BindingOpcode, ByteCodeEmitter, VaryingOperand},
+        opcode::{Address, BindingOpcode, ByteCodeEmitter, VaryingOperand},
         source_info::{SourceInfo, SourceMap, SourceMapBuilder, SourcePath},
     },
 };
@@ -366,7 +366,7 @@ enum Literal {
 #[must_use]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct Label {
-    index: u32,
+    index: Address,
 }
 
 #[derive(Debug, Clone, Copy)]
@@ -536,8 +536,10 @@ pub(crate) enum BindingKind {
 
 impl<'ctx> ByteCompiler<'ctx> {
     /// Represents a placeholder address that will be patched later.
-    const DUMMY_ADDRESS: u32 = u32::MAX;
-    const DUMMY_LABEL: Label = Label { index: u32::MAX };
+    const DUMMY_ADDRESS: Address = Address::new(u32::MAX);
+    const DUMMY_LABEL: Label = Label {
+        index: Address::new(u32::MAX),
+    };
 
     /// Creates a new [`ByteCompiler`].
     #[inline]
@@ -802,7 +804,7 @@ impl<'ctx> ByteCompiler<'ctx> {
         }
     }
 
-    fn next_opcode_location(&mut self) -> u32 {
+    fn next_opcode_location(&mut self) -> Address {
         self.bytecode.next_opcode_location()
     }
 
@@ -819,12 +821,13 @@ impl<'ctx> ByteCompiler<'ctx> {
     {
         let start_pc = self.next_opcode_location();
         self.source_map_builder
-            .push_source_position(start_pc, position.into());
+            .push_source_position(start_pc.as_u32(), position.into());
     }
 
     pub(crate) fn pop_source_position(&mut self) {
         let start_pc = self.next_opcode_location();
-        self.source_map_builder.pop_source_position(start_pc);
+        self.source_map_builder
+            .pop_source_position(start_pc.as_u32());
     }
 
     pub(crate) fn emit_get_function(&mut self, dst: &Register, index: u32) {
@@ -1144,7 +1147,7 @@ impl<'ctx> ByteCompiler<'ctx> {
     fn try_fused_comparison_branch(&mut self, op: RelationalOp, binary: &Binary) -> Option<Label> {
         use crate::vm::opcode::ByteCodeEmitter;
 
-        let emit_fn: fn(&mut ByteCodeEmitter, u32, VaryingOperand, VaryingOperand) = match op {
+        let emit_fn: fn(&mut ByteCodeEmitter, Address, VaryingOperand, VaryingOperand) = match op {
             RelationalOp::LessThan => ByteCodeEmitter::emit_jump_if_not_less_than,
             RelationalOp::LessThanOrEqual => ByteCodeEmitter::emit_jump_if_not_less_than_or_equal,
             RelationalOp::GreaterThan => ByteCodeEmitter::emit_jump_if_not_greater_than,
@@ -1153,7 +1156,7 @@ impl<'ctx> ByteCompiler<'ctx> {
             }
             _ => return None,
         };
-        let mut label_index = 0u32;
+        let mut label_index = Address::new(0);
         self.compile_expr_operand(binary.lhs(), |compiler, lhs| {
             compiler.compile_expr_operand(binary.rhs(), |compiler, rhs| {
                 label_index = compiler.next_opcode_location();
@@ -1217,7 +1220,7 @@ impl<'ctx> ByteCompiler<'ctx> {
     }
 
     #[track_caller]
-    pub(crate) fn patch_jump_with_target(&mut self, label: Label, target: u32) {
+    pub(crate) fn patch_jump_with_target(&mut self, label: Label, target: Address) {
         self.bytecode.patch_jump(label.index, target);
     }
 
@@ -2397,7 +2400,7 @@ impl<'ctx> ByteCompiler<'ctx> {
 
         let register_count = self.register_allocator.finish();
 
-        let source_map_entries = self.source_map_builder.build(final_bytecode_len);
+        let source_map_entries = self.source_map_builder.build(final_bytecode_len.as_u32());
 
         CodeBlock {
             length: self.length,

core/engine/src/vm/code_block.rs

@@ -19,7 +19,7 @@ use thin_vec::ThinVec;
 
 use super::{
     InlineCache,
-    opcode::{ByteCode, Instruction, InstructionIterator},
+    opcode::{Address, ByteCode, Instruction, InstructionIterator},
     source_info::{SourceInfo, SourceMap, SourcePath},
 };
 
@@ -79,20 +79,20 @@ unsafe impl Trace for CodeBlockFlags {
 /// [`Handler`] and remove any environments or stack values that where pushed after the handler.
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct Handler {
-    pub(crate) start: u32,
-    pub(crate) end: u32,
+    pub(crate) start: Address,
+    pub(crate) end: Address,
     pub(crate) environment_count: u32,
 }
 
 impl Handler {
     /// Get the handler address.
-    pub(crate) const fn handler(&self) -> u32 {
+    pub(crate) const fn handler(&self) -> Address {
         self.end
     }
 
     /// Check if the provided `pc` is contained in the handler range.
     pub(crate) const fn contains(&self, pc: u32) -> bool {
-        pc < self.end && pc >= self.start
+        pc < self.end.as_u32() && pc >= self.start.as_u32()
     }
 }
 
@@ -944,14 +944,14 @@ impl Display for CodeBlock {
             let pc = iterator.pc();
             let handler = if let Some((i, handler)) = self.find_handler(instruction_start_pc as u32)
             {
-                let border_char = if instruction_start_pc as u32 == handler.start {
+                let border_char = if instruction_start_pc as u32 == u32::from(handler.start) {
                     '>'
-                } else if pc as u32 == handler.end {
+                } else if pc as u32 == u32::from(handler.end) {
                     '<'
                 } else {
                     ' '
                 };
-                format!("{border_char}{i:2}: {:06x}", handler.handler())
+                format!("{border_char}{i:2}: {}", handler.handler())
             } else {
                 "           ".to_string()
             };

core/engine/src/vm/flowgraph/mod.rs

@@ -114,7 +114,7 @@ impl CodeBlock {
                     graph.add_node(previous_pc, NodeShape::Diamond, label.into(), Color::None);
                     graph.add_edge(
                         previous_pc,
-                        address as usize,
+                        address.as_u32() as usize,
                         None,
                         Color::None,
                         EdgeStyle::Line,
@@ -132,7 +132,7 @@ impl CodeBlock {
                     graph.add_node(previous_pc, NodeShape::Diamond, label.into(), Color::None);
                     graph.add_edge(
                         previous_pc,
-                        address as usize,
+                        address.as_u32() as usize,
                         Some("YES".into()),
                         Color::Green,
                         EdgeStyle::Line,
@@ -156,7 +156,7 @@ impl CodeBlock {
                     graph.add_edge(previous_pc, pc, None, Color::None, EdgeStyle::Line);
                     graph.add_edge(
                         previous_pc,
-                        address as usize,
+                        address.as_u32() as usize,
                         Some("SHORT CIRCUIT".into()),
                         Color::Red,
                         EdgeStyle::Line,
@@ -173,7 +173,7 @@ impl CodeBlock {
                     );
                     graph.add_edge(
                         previous_pc,
-                        address as usize,
+                        address.as_u32() as usize,
                         Some("YES".into()),
                         Color::Green,
                         EdgeStyle::Line,
@@ -193,14 +193,14 @@ impl CodeBlock {
                     graph.add_edge(previous_pc, pc, None, Color::None, EdgeStyle::Line);
                     graph.add_edge(
                         previous_pc,
-                        throw_method_undefined as usize,
+                        throw_method_undefined.as_u32() as usize,
                         Some("`throw` undefined".into()),
                         Color::Red,
                         EdgeStyle::Line,
                     );
                     graph.add_edge(
                         previous_pc,
-                        return_method_undefined as usize,
+                        return_method_undefined.as_u32() as usize,
                         Some("`return` undefined".into()),
                         Color::Blue,
                         EdgeStyle::Line,
@@ -216,14 +216,14 @@ impl CodeBlock {
                     graph.add_edge(previous_pc, pc, None, Color::None, EdgeStyle::Line);
                     graph.add_edge(
                         previous_pc,
-                        r#return as usize,
+                        r#return.as_u32() as usize,
                         Some("return".into()),
                         Color::Yellow,
                         EdgeStyle::Line,
                     );
                     graph.add_edge(
                         previous_pc,
-                        exit as usize,
+                        exit.as_u32() as usize,
                         Some("done".into()),
                         Color::Blue,
                         EdgeStyle::Line,
@@ -242,7 +242,7 @@ impl CodeBlock {
                     graph.add_node(previous_pc, NodeShape::Diamond, label.into(), Color::None);
                     graph.add_edge(
                         previous_pc,
-                        address as usize,
+                        address.as_u32() as usize,
                         Some("EXIT".into()),
                         Color::Red,
                         EdgeStyle::Line,
@@ -324,7 +324,7 @@ impl CodeBlock {
                     if let Some((i, handler)) = self.find_handler(previous_pc as u32) {
                         graph.add_edge(
                             previous_pc,
-                            handler.handler() as usize,
+                            handler.handler().as_u32() as usize,
                             Some(format!("Handler {i:2}: CAUGHT").into()),
                             Color::None,
                             EdgeStyle::Line,
@@ -336,7 +336,7 @@ impl CodeBlock {
                         graph.add_node(previous_pc, NodeShape::Record, label.into(), Color::None);
                         graph.add_edge(
                             previous_pc,
-                            handler.handler() as usize,
+                            handler.handler().as_u32() as usize,
                             Some(format!("Handler {i:2}: CAUGHT").into()),
                             Color::None,
                             EdgeStyle::Line,
@@ -366,7 +366,7 @@ impl CodeBlock {
                     for (i, address) in addresses.iter().enumerate() {
                         graph.add_edge(
                             previous_pc,
-                            *address as usize,
+                            address.as_u32() as usize,
                             Some(format!("[{i}]").into()),
                             Color::None,
                             EdgeStyle::Line,

core/engine/src/vm/mod.rs

@@ -552,7 +552,7 @@ impl Vm {
         let environment_sp = frame.env_fp + handler.environment_count;
 
         // Go to handler location.
-        frame.pc = catch_address;
+        frame.pc = u32::from(catch_address);
 
         self.frame.environments.truncate(environment_sp as usize);
 

core/engine/src/vm/opcode/args.rs

@@ -1,6 +1,6 @@
 use thin_vec::ThinVec;
 
-use super::VaryingOperand;
+use super::{Address, VaryingOperand};
 
 /// A trait for types that can be read from a byte slice.
 ///
@@ -149,6 +149,19 @@ impl Argument for VaryingOperand {
     }
 }
 
+impl Argument for Address {
+    #[inline(always)]
+    fn encode(self, bytes: &mut Vec<u8>) {
+        write_u32(bytes, self.value);
+    }
+
+    #[inline(always)]
+    fn decode(bytes: &[u8], pos: usize) -> (Self, usize) {
+        let (value, pos) = read::<u32>(bytes, pos);
+        (Self::new(value), pos)
+    }
+}
+
 macro_rules! impl_argument_for_tuple {
     ($( $i: ident  $t: ident ),*) => {
         impl<$( $t: Argument, )*> Argument for ($( $t, )*) {