Refine branch hinting: lazy decode and review fixes

- Decode the branch-hint section lazily via per-function readers instead
  of eagerly decoding and heap-allocating every hint
- Discard malformed sections explicitly; keep first of duplicate entries
- take_branch_hint yields BranchHint; init hints in FuncEnvironment::new
- Move the runtime test to misc_testsuite/*.wast; add a malformed-section test
- Add a fuzzing knob; tidy docs and comments

Assisted-by: Claude Code:claude-opus-4-7

Author: gfx

crates/cranelift/src/compiler.rs

@@ -262,7 +262,20 @@ impl wasmtime_environ::Compiler for Compiler {
             context.func.collect_debug_info();
         }
 
-        let mut func_env = FuncEnvironment::new(self, translation, types, wasm_func_ty, key);
+        // Branch hints are keyed by function-body-relative offset, so the body's
+        // module-relative start is needed to convert source locations later.
+        let FunctionBodyData { validator, body } = input;
+        let func_body_offset = body.get_binary_reader().original_position();
+
+        let mut func_env = FuncEnvironment::new(
+            self,
+            translation,
+            types,
+            wasm_func_ty,
+            key,
+            func_index,
+            func_body_offset,
+        );
 
         // The `stack_limit` global value below is the implementation of stack
         // overflow checks in Wasmtime.
@@ -318,19 +331,6 @@ impl wasmtime_environ::Compiler for Compiler {
                 func_env.stack_limit_at_function_entry = Some(stack_limit);
             }
         }
-        let FunctionBodyData { validator, body } = input;
-
-        // Branch hints are keyed by function-body-relative offset, so record the
-        // body's module-relative start to convert source locations later.
-        func_env.set_branch_hints(
-            translation
-                .branch_hints
-                .get(&func_index)
-                .map(|hints| &hints[..])
-                .unwrap_or(&[]),
-            body.get_binary_reader().original_position(),
-        );
-
         let mut validator =
             validator.into_validator(mem::take(&mut compiler.cx.validator_allocations));
         compiler.cx.func_translator.translate_body(

crates/cranelift/src/func_environ.rs

@@ -26,10 +26,12 @@ use cranelift_frontend::Variable;
 use cranelift_frontend::{FuncInstBuilder, FunctionBuilder};
 use smallvec::{SmallVec, smallvec};
 use std::mem;
-use wasmparser::{FuncValidator, Operator, WasmFeatures, WasmModuleResources};
+use wasmparser::{
+    BranchHint, FuncValidator, Operator, SectionLimitedIntoIter, WasmFeatures, WasmModuleResources,
+};
 use wasmtime_core::math::f64_cvt_to_int_bounds;
 use wasmtime_environ::{
-    BranchHint, BuiltinFunctionIndex, ComponentPC, DataIndex, DefinedFuncIndex, ElemIndex,
+    BuiltinFunctionIndex, ComponentPC, DataIndex, DefinedFuncIndex, ElemIndex,
     EngineOrModuleTypeIndex, FrameStateSlotBuilder, FrameValType, FuncIndex, FuncKey,
     GlobalConstValue, GlobalIndex, IndexType, Memory, MemoryIndex, MemoryTunables, Module,
     ModuleInternedTypeIndex, ModuleTranslation, ModuleTypesBuilder, PtrSize, Table, TableIndex,
@@ -233,11 +235,12 @@ pub struct FuncEnvironment<'module_environment> {
     /// to e.g. record the return-address of a callsite for debuginfo.
     pub(crate) next_srcloc: ir::SourceLoc,
 
-    /// Branch hints for the current function, consumed in program-counter order
-    /// by `take_branch_hint`.
-    branch_hints: &'module_environment [BranchHint],
-    /// Forward cursor into `branch_hints`.
-    branch_hint_cursor: usize,
+    /// Lazily-decoded branch hints for the current function, in ascending
+    /// `func_offset` order (as the proposal requires). `None` once exhausted or
+    /// when the function carries no hints.
+    branch_hints: Option<SectionLimitedIntoIter<'module_environment, BranchHint>>,
+    /// One-item lookahead into `branch_hints`, consumed by `take_branch_hint`.
+    peeked_hint: Option<BranchHint>,
     /// Module-relative byte offset of the current function body's start.
     func_body_offset: usize,
 }
@@ -249,10 +252,19 @@ impl<'module_environment> FuncEnvironment<'module_environment> {
         types: &'module_environment ModuleTypesBuilder,
         wasm_func_ty: &'module_environment WasmFuncType,
         key: FuncKey,
+        func_index: FuncIndex,
+        func_body_offset: usize,
     ) -> Self {
         let tunables = compiler.tunables();
         let builtin_functions = BuiltinFunctions::new(compiler);
 
+        // Resolve the lazy branch-hint decoder for this function, if any.
+        // `func_body_offset` lets `take_branch_hint` convert source locations to
+        // the function-body-relative offsets the hints use.
+        let branch_hints = translation
+            .branch_hints(func_index)
+            .map(|reader| reader.into_iter());
+
         // This isn't used during translation, so squash the warning about this
         // being unused from the compiler.
         let _ = BuiltinFunctions::raise;
@@ -303,46 +315,48 @@ impl<'module_environment> FuncEnvironment<'module_environment> {
             next_srcloc: ir::SourceLoc::default(),
             wasm_module_offset: translation.wasm_module_offset,
 
-            branch_hints: &[],
-            branch_hint_cursor: 0,
-            func_body_offset: 0,
+            branch_hints,
+            peeked_hint: None,
+            func_body_offset,
         }
     }
 
-    /// Set the branch hints and the module-relative start offset for the
-    /// function about to be translated. Hints are expected in ascending
-    /// `func_offset` order (as the proposal requires); `take_branch_hint`
-    /// simply skips any that are out of order.
-    pub(crate) fn set_branch_hints(
-        &mut self,
-        hints: &'module_environment [BranchHint],
-        func_body_offset: usize,
-    ) {
-        self.branch_hints = hints;
-        self.branch_hint_cursor = 0;
-        self.func_body_offset = func_body_offset;
-    }
-
     /// Consume the branch hint for the instruction at module-relative `offset`
-    /// (i.e. `builder.srcloc().bits()`), if any; `Some(true)` means likely
-    /// taken. The cursor only advances, making this O(n) over a function body.
-    pub(crate) fn take_branch_hint(&mut self, offset: usize) -> Option<bool> {
-        if self.branch_hints.is_empty() {
+    /// (i.e. `builder.srcloc().bits()`), if any. The lazy decoder only moves
+    /// forward, making this O(n) over a function body.
+    pub(crate) fn take_branch_hint(&mut self, offset: usize) -> Option<BranchHint> {
+        // Fast path for the common case of a function with no hints (always so
+        // when the proposal is disabled): this is called for every `if`/`br_if`.
+        if self.branch_hints.is_none() {
             return None;
         }
         let rel = u32::try_from(offset.checked_sub(self.func_body_offset)?).ok()?;
-        // Skip hints that don't line up with this (or a later) branch.
-        while matches!(
-            self.branch_hints.get(self.branch_hint_cursor),
-            Some(h) if h.func_offset < rel,
-        ) {
-            self.branch_hint_cursor += 1;
+        loop {
+            // Refill the one-item lookahead from the lazy decoder.
+            if self.peeked_hint.is_none() {
+                self.peeked_hint = self.next_branch_hint();
+            }
+            let hint = self.peeked_hint?;
+            if hint.func_offset < rel {
+                // Hint precedes this branch (or never lined up); drop it.
+                self.peeked_hint = None;
+                continue;
+            }
+            if hint.func_offset == rel {
+                self.peeked_hint = None;
+                return Some(hint);
+            }
+            // The next hint is for a later offset; nothing for this branch.
+            return None;
         }
-        let hint = self.branch_hints.get(self.branch_hint_cursor)?;
-        (hint.func_offset == rel).then(|| {
-            self.branch_hint_cursor += 1;
-            hint.taken
-        })
+    }
+
+    /// Decode the next hint for the current function, if any.
+    fn next_branch_hint(&mut self) -> Option<BranchHint> {
+        // These bytes were already validated when the section was decoded into
+        // per-function readers, so this re-decode cannot fail; defensively treat
+        // an unexpected error as the end of the hints.
+        self.branch_hints.as_mut()?.next()?.ok()
     }
 
     pub(crate) fn pointer_type(&self) -> ir::Type {

crates/cranelift/src/translate/code_translator.rs

@@ -335,13 +335,13 @@ pub fn translate_operator(
 
             // Mark the unlikely successor cold per the branch hint. A likely
             // condition makes the else block cold; when it is allocated lazily
-            // (`NoElse`) defer that to `Operator::Else` via `cold_else`.
-            let cold_else = match branch_hint {
-                Some(false) => {
+            // (`NoElse`) defer that to `Operator::Else` via `else_is_cold`.
+            let else_is_cold = match branch_hint {
+                Some(hint) if !hint.taken => {
                     builder.set_cold_block(next_block);
                     false
                 }
-                Some(true) => match &else_data {
+                Some(_) => match &else_data {
                     ElseData::WithElse { else_block } => {
                         builder.set_cold_block(*else_block);
                         false
@@ -366,7 +366,7 @@ pub fn translate_operator(
                 params.len(),
                 results.len(),
                 *blockty,
-                cold_else,
+                else_is_cold,
             );
         }
         Operator::Else => {
@@ -4018,9 +4018,9 @@ fn translate_br_if(
     let (br_destination, inputs) = translate_br_if_args(relative_depth, env);
     let next_block = builder.create_block();
 
-    if let Some(taken) = branch_hint {
+    if let Some(hint) = branch_hint {
         // Likely taken => the fallthrough is cold, else the branch target is.
-        builder.set_cold_block(if taken { next_block } else { br_destination });
+        builder.set_cold_block(if hint.taken { next_block } else { br_destination });
     }
 
     canonicalise_brif(builder, val, br_destination, inputs, next_block, &[]);

crates/environ/src/compile/module_environ.rs

@@ -123,21 +123,19 @@ pub struct ModuleTranslation<'data> {
     /// validation process.
     types: Option<Types>,
 
-    /// Branch hints parsed from the `metadata.code.branch_hint` custom section,
+    /// Per-function readers into the `metadata.code.branch_hint` custom section,
     /// keyed by module-level function index. Only populated when
-    /// [`Tunables::branch_hinting`] is enabled.
-    pub branch_hints: HashMap<FuncIndex, Box<[BranchHint]>>,
+    /// [`Tunables::branch_hinting`] is enabled. The hints are decoded lazily
+    /// during compilation, so this holds the section's per-function sub-readers
+    /// rather than fully-decoded hints; access them via
+    /// [`ModuleTranslation::branch_hints`].
+    branch_hints: HashMap<FuncIndex, BranchHintReader<'data>>,
 }
 
-/// A single branch hint from the `metadata.code.branch_hint` custom section
+/// Lazy decoder over the branch hints attached to a single function in the
+/// `metadata.code.branch_hint` custom section
 /// ([branch-hinting proposal](https://github.com/WebAssembly/branch-hinting)).
-#[derive(Debug, Copy, Clone)]
-pub struct BranchHint {
-    /// Byte offset of the hinted `br_if`/`if` from the start of the function body.
-    pub func_offset: u32,
-    /// Whether the branch's condition is hinted to be true.
-    pub taken: bool,
-}
+pub type BranchHintReader<'a> = wasmparser::SectionLimited<'a, wasmparser::BranchHint>;
 
 impl<'data> ModuleTranslation<'data> {
     /// Create a new translation for the module with the given index.
@@ -164,6 +162,13 @@ impl<'data> ModuleTranslation<'data> {
         }
     }
 
+    /// Returns a lazy decoder over the branch hints for `func`, if the
+    /// `metadata.code.branch_hint` section attached any. Hints are decoded on
+    /// demand during compilation rather than eagerly during parsing.
+    pub fn branch_hints(&self, func: FuncIndex) -> Option<BranchHintReader<'data>> {
+        self.branch_hints.get(&func).cloned()
+    }
+
     /// Returns a reference to the type information of the current module.
     pub fn get_types(&self) -> &Types {
         self.types
@@ -774,30 +779,23 @@ and for re-adding support for interface types you can see this issue:
                 }
             }
             KnownCustom::BranchHints(reader) if self.tunables.branch_hinting => {
-                // Compilation relies on the proposal's guarantee that hints are
-                // in ascending `func_offset` order; we trust it rather than
-                // re-sort (validating malformed sections is not yet done). Hints
-                // are advisory, so skip entries that fail to parse.
-                for func in reader.into_iter().flatten() {
-                    let hints = func
-                        .hints
-                        .into_iter()
-                        .flatten()
-                        .map(|h| BranchHint {
-                            func_offset: h.func_offset,
-                            taken: h.taken,
-                        })
-                        .collect::<Box<[_]>>();
-                    if !hints.is_empty() {
-                        // A well-formed section lists each function at most once;
-                        // if a malformed one repeats a function, keep the first
-                        // entry deterministically rather than silently
-                        // overwriting it.
-                        self.result
-                            .branch_hints
-                            .entry(FuncIndex::from_u32(func.func))
-                            .or_insert(hints);
-                    }
+                // Branch hints are advisory and this section is never validated;
+                // it is decoded lazily during compilation, so record only the
+                // per-function sub-readers here. Discard the whole section if any
+                // entry is malformed rather than applying it partially.
+                let mut hints = HashMap::new();
+                let result: wasmparser::Result<()> = reader.into_iter().try_for_each(|func| {
+                    let func = func?;
+                    // A well-formed section lists each function at most once; keep
+                    // the first entry deterministically if it repeats.
+                    hints
+                        .entry(FuncIndex::from_u32(func.func))
+                        .or_insert(func.hints);
+                    Ok(())
+                });
+                match result {
+                    Ok(()) => self.result.branch_hints = hints,
+                    Err(e) => log::warn!("failed to parse branch-hint section {e:?}"),
                 }
             }
             _ => {

crates/fuzzing/src/generators/config.rs

@@ -138,6 +138,7 @@ impl Config {
             tail_call,
             extended_const,
             wide_arithmetic,
+            branch_hinting,
             component_model_async,
             component_model_more_async_builtins,
             component_model_async_stackful,
@@ -177,6 +178,7 @@ impl Config {
             component_model_fixed_length_lists.unwrap_or(false);
         self.module_config.component_model_implements = component_model_implements.unwrap_or(false);
         self.module_config.stack_switching = stack_switching.unwrap_or(false);
+        self.wasmtime.branch_hinting = branch_hinting.unwrap_or(false);
 
         // Enable/disable proposals that wasm-smith has knobs for which will be
         // read when creating `wasmtime::Config`.
@@ -346,6 +348,7 @@ impl Config {
         cfg.wasm.shared_everything_threads =
             Some(self.module_config.config.shared_everything_threads_enabled);
         cfg.wasm.wide_arithmetic = Some(self.module_config.config.wide_arithmetic_enabled);
+        cfg.wasm.branch_hinting = Some(self.wasmtime.branch_hinting);
         cfg.wasm.exceptions = Some(self.module_config.config.exceptions_enabled);
         cfg.wasm.stack_switching = Some(self.module_config.stack_switching);
         cfg.wasm.shared_memory = Some(self.module_config.shared_memory);
@@ -608,6 +611,10 @@ pub struct WasmtimeConfig {
     table_lazy_init: bool,
     metadata_for_internal_asserts: bool,
     metadata_for_gc_heap_corruption: bool,
+    /// Whether the branch-hinting proposal is enabled. wasm-smith does not emit
+    /// `metadata.code.branch_hint` sections, so for generated modules this only
+    /// toggles the (otherwise no-op) parsing path.
+    branch_hinting: bool,
 
     /// Configuration for whether wasm is invoked in an async fashion and how
     /// it's cooperatively time-sliced.

crates/test-util/src/wasmtime_wast.rs

@@ -39,6 +39,7 @@ pub fn apply_test_config(config: &mut Config, test_config: &wast::TestConfig) {
         tail_call,
         extended_const,
         wide_arithmetic,
+        branch_hinting,
         component_model_async,
         component_model_more_async_builtins,
         component_model_async_stackful,
@@ -72,6 +73,7 @@ pub fn apply_test_config(config: &mut Config, test_config: &wast::TestConfig) {
     let tail_call = tail_call.unwrap_or(false);
     let extended_const = extended_const.unwrap_or(false);
     let wide_arithmetic = wide_arithmetic.unwrap_or(false);
+    let branch_hinting = branch_hinting.unwrap_or(false);
     let component_model_async = component_model_async.unwrap_or(false);
     let component_model_more_async_builtins = component_model_more_async_builtins.unwrap_or(false);
     let component_model_async_stackful = component_model_async_stackful.unwrap_or(false);
@@ -115,6 +117,7 @@ pub fn apply_test_config(config: &mut Config, test_config: &wast::TestConfig) {
         .wasm_custom_page_sizes(custom_page_sizes)
         .wasm_extended_const(extended_const)
         .wasm_wide_arithmetic(wide_arithmetic)
+        .wasm_branch_hinting(branch_hinting)
         .wasm_component_model_async(component_model_async)
         .wasm_component_model_more_async_builtins(component_model_more_async_builtins)
         .wasm_component_model_async_stackful(component_model_async_stackful)

crates/test-util/src/wast.rs

@@ -273,6 +273,7 @@ macro_rules! foreach_config_option {
             tail_call
             extended_const
             wide_arithmetic
+            branch_hinting
             hogs_memory
             nan_canonicalization
             component_model_async

docs/stability-wasm-proposals.md

@@ -74,17 +74,14 @@ The emoji legend is:
 
 |  Proposal                   | Phase 4 | Tests | Finished | Fuzzed | API | C API |
 |-----------------------------|---------|-------|----------|--------|-----|-------|
-| [`branch-hinting`] [^12]    | ❌      | ❌    | 🚧       | ❌     | ✅  | ✅    |
+| [`branch-hinting`] [^12]    | ✅      | ✅    | ✅       | ❌     | ✅  | ✅    |
 | [`stack-switching`] [^11]   | ❌      | 🚧    | 🚧       | ❌     | ❌  | ❌    |
 
 [^11]: The stack-switching proposal is a work-in-progress being tracked
     at [#9465](https://github.com/bytecodealliance/wasmtime/issues/9465).
     Currently the implementation is only for x86\_64 Linux.
-[^12]: Branch hinting parses the `metadata.code.branch_hint` custom section and
-    uses it to mark cold blocks during Cranelift compilation. It is disabled by
-    default (`Config::wasm_branch_hinting`) until it has been fuzzed; spec-test
-    enablement and validation of malformed sections are still pending. Tracked
-    at [#9463](https://github.com/bytecodealliance/wasmtime/issues/9463).
+[^12]: Disabled by default (`Config::wasm_branch_hinting`) pending fuzzing;
+    tracked at [#9463](https://github.com/bytecodealliance/wasmtime/issues/9463).
 
 ## Unimplemented proposals